marc_agent

# M.A.R.C A1

Modular Autonomous Runtime Core - Agent 1

M.A.R.C A1 ist ein lokaler, selbstgehosteter Coding- und Entwicklungsagent. Er ist bewusst nicht als allgemeiner Assistent gedacht, sondern fuer echte Entwicklungsarbeit: Repository verstehen, relevante Dateien finden, Code aendern, Tests und Checks ausfuehren, Fehler diagnostizieren, gezielt nachbessern und das Ergebnis sauber dokumentieren.

Die Hauptoberflaeche ist die Web-GUI. Die CLI bleibt fuer Debugging und Automatisierung erhalten, ist aber bewusst sekundar.

## Zielbild

M.A.R.C A1 ist auf diesen Ablauf optimiert:

1. Aufgabe verstehen
2. Projektstruktur und bestehende Architektur analysieren
3. relevante Dateien und Muster priorisieren
4. gezielte Aenderungen an der richtigen Stelle vornehmen
5. passende Tests, Linter, Typechecks oder Builds auswaehlen
6. Fehlerausgaben und Logs diagnostizieren
7. nachbessern und erneut pruefen
8. Diffs, Logs, Diagnosen, Stop-Grund und Abschlussbericht liefern

Wenn die direkte Loesung blockiert ist, darf M.A.R.C A1 kleine Hilfsskripte, Parser oder Test-Harnesses im Workspace erzeugen, solange sie die eigentliche Entwicklungsaufgabe voranbringen und sauber nachvollziehbar bleiben.

## Was Im Vergleich Zum Frueheren Stand Staerker Ist

Das Projekt hatte bereits gute Grundbausteine:

- Python-Backend mit FastAPI
- lokale Weboberflaeche
- Tool-Dispatcher fuer Filesystem, Search, Shell und Git
- Workspace-Sicherheitsgrenzen
- Session-Store und Logdateien
- erste Basistests

Die groessten Schwaechen lagen im agentischen Verhalten:

- zu lineare Agent-Schleife
- zu duenne Repo-Inspektion
- zu schwache Dateiauswahl
- zu wenig projektbezogene Validation
- kaum strukturierte Fehlerdiagnose
- zu wenig Repair-Iteration
- zu wenig sichtbarer Session- und Abschlusszustand

M.A.R.C A1 hebt diese Punkte an, ohne das Repo blind neu zu schreiben.

## Kernverhalten

Die Runtime arbeitet entlang dieser Workflow-Stufen:

1. `discover`
2. `plan`
3. `act`
4. `verify`
5. `repair`
6. `report`

Intern werden diese Stufen ueber konkrete Laufphasen wie `planning`, `exploring`, `editing`, `verifying`, `repairing` und `reporting` abgebildet.

Wichtige Regeln:

- keine verfruehte Finalisierung nach Codeaenderungen, solange noch sinnvolle Validierung offen ist
- Validation-Runs werden pro Edit-Generation verfolgt
- fehlgeschlagene Checks werden als Diagnosen mit Datei- und Aktionshinweisen gespeichert
- Repair-Versuche werden gezaehlt
- jede Session erzeugt einen strukturierten Abschlussbericht
- Tool-Calls, Shell-Kommandos, Diffs und Logs bleiben nachvollziehbar

## Repo- und Kontextverstaendnis

M.A.R.C A1 baut vor relevanten Aenderungen gezielt Kontext auf, statt nur Dateien stumpf zu lesen.

Der Agent extrahiert unter anderem:

- priorisierte Dateien
- Fokus-Dateien passend zur Aufgabe
- File-Insights mit Kategorien und Gruenden
- Repo-Map und wichtige Top-Level-Bereiche
- Manifeste, Configs, Tests, Build- und Deploy-Dateien
- projektbezogene Validation- und Workflow-Kommandos

Damit wird das Verhalten deutlich naeher an einem starken Coding-Agenten als an einem einfachen Tool-Loop.

## Access Modes

Die Runtime kennt drei klare Zugriffsmodi:

- `safe`
  Nur lesende Exploration und low-risk Verifikation. Schreibende Tools und mutierende Shell-Kommandos werden blockiert.
- `approval`
  Normale Coding-Edits ueber File-Tools sind erlaubt. Medium- und High-Risk-Shell- oder Git-Mutationen werden blockiert.
- `full`
  Voller lokaler Modus. Dateien und Shell-Kommandos duerfen auch ausserhalb von `workspace_root` verwendet werden, solange keine Hard-Block-Sicherheitsregel greift.

Die zentrale Konfiguration ist:

```json
{
  "access_mode": "safe | approval | full"
}
```

Legacy-Flags wie `--read-only` und `--approval-mode` werden weiter akzeptiert, intern aber auf `access_mode` normalisiert.

Wichtig:

- `approval` hat aktuell noch keinen interaktiven Freigabe-Dialog in der GUI
- riskante Schritte werden dort derzeit sauber blockiert und im Session-State dokumentiert
- `full` ist der Modus fuer moeglichst autonome lokale Entwicklungsarbeit

## Web-GUI

Die Web-GUI ist die Hauptoberflaeche fuer echte Agentenarbeit.

Sie zeigt unter anderem:

- neue Tasks starten und Sessions fortsetzen
- Access Mode und Dry Run
- Live-Status und aktuelle Workflow-Stufe
- Tool-Calls und Log-Ereignisse
- geaenderte Dateien und gespeicherte Diffs
- Validation-Runs
- Diagnostik aus fehlgeschlagenen Checks
- Workspace-Analyse mit Repo-Map und Validation-Plan
- strukturierten Abschlussbericht

Standardadresse nach dem Start:

```text
http://127.0.0.1:8000
```

## Login Und Security

Die Web-GUI ist jetzt durch eine serverseitige Login-Schicht geschuetzt:

- Argon2id fuer Passwort-Hashes
- serverseitige Sessions mit HttpOnly-Cookies
- CSRF-Schutz fuer mutierende Requests
- Rate-Limits gegen Brute Force und Credential Stuffing
- optionale TOTP-2FA ueber `AUTH_INITIAL_ADMIN_TOTP_SECRET`

Die konkrete Architektur, das Threat Model, die Security-Entscheidungen und die Pruefanleitung stehen in [docs/auth-security.md](docs/auth-security.md).

## Architektur

Die Architektur ist modular, aber klar auf agentische Entwicklungsarbeit ausgerichtet.

Die Intent- und Tool-Logik ist jetzt sauber in zwei Phasen getrennt:

1. Intent- und Goal-Interpretation
   `agent/router.py` ruft den LLM-basierten Router auf und erzwingt ueber `llm/schemas.py` ein strikt validiertes `RouterOutput`-JSON. Diese Phase extrahiert Nutzerziel, Intent, Entitaeten, Rueckfragen, Safety-Signal und einen Action-Plan.
2. Execution und Tool-Ausfuehrung
   `agent/planner.py` arbeitet danach nur noch mit dem validierten Router-Output. Die Tool-Auswahl kommt nicht mehr direkt aus dem Rohprompt, sondern aus `router_result -> validator -> executor`.

Der Produktionspfad ist damit:

```text
user text -> IntentRouter -> RouterOutput validation/repair -> Planner.execute_action_from_plan -> ToolDispatcher
```

Die restliche Architektur bleibt bewusst modular:

1. Web-GUI
   `webui/` ist die Hauptoberflaeche fuer Tasks, Sessions, Live-Status, Diffs, Logs und Reports.
2. Web-Backend
   `server/` kapselt API, Session-Lifecycle und Live-Streams.
3. Agent-Core
   `agent/core.py`, `router.py`, `planner.py`, `memory.py`, `verification.py`, `diagnostics.py` und `reporting.py` steuern Routing, Planung, Repo-Verstaendnis, Validation, Diagnose, Repair-Loop und Abschlussbericht.
4. Runtime
   `runtime/` erzwingt Workspace-Grenzen, Tool-Dispatching und Logging.
5. Tools
   `tools/` enthaelt Filesystem-, Search-, Shell-, Git- und Safety-Logik.
6. LLM-Schicht
   `llm/provider.py` definiert die austauschbare Provider-Schnittstelle, `llm/ollama_client.py` spricht mit Ollama, `llm/schemas.py` erzwingt strukturierte Router- und Tool-Entscheidungen.
7. Optionale CLI
   `cli.py` ist fuer Debugging, Automatisierung und schnelle lokale Nutzung da.

## Router-Contract

Der Router arbeitet mit einem strikt validierten Contract aus `llm/schemas.py`:

- `intent`: `inspect | create | update | delete | search | explain | plan | unknown`
- `entities`: Zieltyp, Zielname, konkrete Zielpfade, Attribute und Constraints
- `action_plan`: nur erlaubte, ausfuehrbare Action-Namen aus einem festen Catalog
- `needs_clarification`: gezielte Rueckfragen statt Blindflug
- `safe_to_execute`: explizite Safety-Entscheidung
- `confidence`: Float zwischen `0.0` und `1.0`

Wenn der LLM-Output das Schema verletzt, folgt ein Repair-Schritt. Erst danach darf die Execution-Phase starten.

## Neue Intents Erweitern

Neue Intents oder Actions werden an genau diesen Stellen ergaenzt:

1. `llm/schemas.py`
   Neues Enum-Mitglied im Intent- oder Action-Catalog plus Modellregeln.
2. `agent/prompts.py`
   Router-Prompt und Action-Catalog erweitern, damit der LLM die neue Kategorie sauber ausgeben kann.
3. `agent/planner.py`
   Execution-Zweig fuer die neue Action implementieren. Diese Schicht arbeitet nur mit dem validierten Router-Output.
4. `tests/test_router.py` und `tests/test_planner.py`
   Neue freie Formulierunge

[truncated…]