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:

{
  "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:

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.

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:

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 Formulierungen, Validierungsfaelle und Execution-Pfade absichern.

Projektstruktur

.
|-- README.md
|-- CONTRIBUTING.md
|-- bootstrap_runtime.py
|-- main.py
|-- cli.py
|-- start_marc_a1.bat
|-- requirements.txt
|-- requirements-runtime.txt
|-- agent
|   |-- core.py
|   |-- diagnostics.py
|   |-- executor.py
|   |-- memory.py
|   |-- models.py
|   |-- planner.py
|   |-- prompts.py
|   |-- reporting.py
|   |-- router.py
|   |-- session.py
|   `-- verification.py
|-- config
|   |-- agent.json.example
|   `-- settings.py
|-- llm
|   |-- provider.py
|   |-- ollama_client.py
|   `-- schemas.py
|-- runtime
|   |-- logger.py
|   |-- tool_dispatcher.py
|   `-- workspace.py
|-- server
|   |-- app.py
|   |-- schemas.py
|   `-- task_manager.py
|-- tools
|   |-- difftools.py
|   |-- filesystem.py
|   |-- gittools.py
|   |-- registry.py
|   |-- safety.py
|   |-- search.py
|   `-- shell.py
|-- tests
|   |-- test_access_modes.py
|   |-- test_bootstrap.py
|   |-- test_diagnostics.py
|   |-- test_dispatcher.py
|   |-- test_filesystem.py
|   |-- test_planner.py
|   |-- test_repo_inspection.py
|   |-- test_reporting.py
|   |-- test_router.py
|   |-- test_safety.py
|   |-- test_shell.py
|   |-- test_validation_planner.py
|   |-- test_web_api.py
|   `-- test_workspace.py
`-- webui
    |-- app.js
    |-- index.html
    `-- styles.css

Schnellstart

Minimal:

python main.py

Beim Serverstart prueft M.A.R.C A1 jetzt immer zuerst die komplette Runtime-Anforderungsliste aus requirements-runtime.txt. Fehlende oder unpassende Python-Pakete werden automatisch installiert, danach startet die Web-App direkt weiter.

Beim ersten Aufruf der Weboberflaeche fuehrt jetzt ein integrierter Setup-Assistent durch die Ersteinrichtung. Er legt die .env an, erzeugt den ersten Admin-Zugang, speichert Runtime-Defaults wie Ollama-Host und Modelle und verbindet auf Wunsch direkt das erste Projekt, ohne dass diese Schritte manuell per Hand vorbereitet werden muessen.

Auf Windows prueft der Startpfad jetzt zusaetzlich, ob Ollama vorhanden ist. Wenn ollama fehlt, versucht M.A.R.C A1 die offizielle Windows-Installation automatisch anzustossen und wartet danach auf die lokale API unter OLLAMA_HOST. Sobald der Server steht, werden die empfohlenen Modelle serverseitig angestossen und ihr Download-Status ist in der Web-GUI sichtbar.

Wenn das System-Python extern verwaltet ist, zum Beispiel bei Homebrew-Python auf macOS oder aehnlichen PEP-668-Setups, weicht M.A.R.C A1 automatisch auf ein repo-lokales Runtime-Venv unter .marc_a1/runtime-venv aus. Folge-Starts verwenden dieses Runtime-Venv direkt weiter.

Unter Windows:

start_marc_a1.bat

Mit eigener virtueller Umgebung:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py

Nützliche Optionen:

python main.py --host 0.0.0.0 --port 8080
python main.py --access-mode safe
python main.py --access-mode approval
python main.py --access-mode full
python main.py --dry-run

CLI

Die CLI ist vorhanden, aber bewusst nicht der Hauptfokus.

python cli.py task "Fuege JWT Login hinzu"
python cli.py inspect --focus auth
python cli.py diff
python cli.py config show

Ollama Setup

Standardmodell:

• qwen3-coder:30b

Lokaler Ollama-Start:

ollama serve
ollama pull qwen3-coder:30b

Wichtige Defaults:

• OLLAMA_HOST=http://127.0.0.1:11434
• MODEL_NAME=qwen3-coder:30b
• WORKSPACE_ROOT=.
• ACCESS_MODE=approval

API

Wichtige Endpunkte:

• GET /api/health
• GET /api/config
• GET /api/workspace/inspect
• GET /api/sessions
• GET /api/sessions/{session_id}
• GET /api/sessions/{session_id}/logs
• GET /api/sessions/{session_id}/events
• POST /api/tasks

Session-Antworten enthalten unter anderem:

• workflow_stage
• validation_plan
• validation_runs
• diagnostics
• report

/api/sessions/{session_id}/events streamt Live-Updates per SSE.

Session-State Und Artefakte

Interner Zustand liegt standardmaessig in:

.marc_a1/

Darin befinden sich unter anderem:

• sessions/
• logs/
• memory/
• helpers/
• reports/

Der Report-Bereich speichert fuer jede Session einen strukturierten Abschlussbericht mit Status, Stop-Grund, Commands, Validation-Runs, Diagnosen, Blockern und geaenderten Dateien.

Sicherheit

Die Runtime bleibt lokal, aber defensiv:

• safe und approval bleiben auf den Workspace begrenzt
• full hebt die Pfadbegrenzung auf
• harte Shell-Blocker fuer destruktive Kommandos bleiben aktiv
• Netzwerkzugriff ist standardmaessig deaktiviert
• alle Tool-Calls und Entscheidungen werden geloggt
• Diffs und Session-Aenderungen bleiben sichtbar

Bootstrap-Verhalten:

• main.py und cli.py installieren fehlende Runtime-Abhaengigkeiten automatisch
• ausserhalb eines venv wird zuerst ein normaler lokaler Pip-Installationsversuch unternommen
• falls das Host-Python extern verwaltet ist oder der direkte Installationsversuch scheitert, erstellt M.A.R.C A1 automatisch ein repo-lokales Runtime-Venv unter .marc_a1/runtime-venv
• dieses Runtime-Venv wird danach fuer weitere Starts wiederverwendet
• das Verhalten kann ueber MARC_A1_PIP_SCOPE=user|global|auto gesteuert werden
• zusaetzliche Pip-Argumente koennen ueber MARC_A1_PIP_EXTRA_ARGS gesetzt werden

Tests

Mit aktiver virtueller Umgebung oder installiertem pytest:

python -m pytest -q

Abgedeckt sind aktuell unter anderem:

• Workspace-Sicherheit
• Tool-Argumentvalidierung
• File-Patching und Diffs
• Shell-Schutz und Timeout-Verhalten
• Access-Mode-Logik
• Repo-Inspektion
• Fehlerdiagnostik
• Validation-Planung
• Web-API und Session-Metadaten

Git Workflow

Das Repo ist auf einen professionelleren Branching-Flow ausgelegt:

• main fuer stabile, releasbare Staende
• develop fuer laufende Integration
• feature/<topic> fuer neue Arbeit
• fix/<topic> fuer Fehlerbehebungen
• hotfix/<topic> fuer dringende Korrekturen auf main

Details stehen in CONTRIBUTING.md.

Grenzen

M.A.R.C A1 ist jetzt deutlich naeher an einem starken lokalen Coding-Agenten, aber noch nicht fertig in jedem Punkt.

Aktuelle reale Grenzen:

• die eigentliche Codequalitaet haengt weiterhin stark vom lokalen Modell ab
• approval blockiert riskante Schritte derzeit, statt einen echten Freigabe-Dialog anzubieten
• die Repo-Inspektion ist heuristisch, nicht symbolisch indexiert
• es gibt noch keine Multi-Agent-Orchestrierung

Erweiterbarkeit

Sinnvolle naechste Ausbaustufen:

• Approval-UI fuer medium/high-risk Aktionen
• Repo-Index mit Symbol-Layer
• Multi-Agent-Orchestrierung fuer Explore/Edit/Verify
• persistente Hintergrund-Queue
• weitere projektbewusste Exec-Tools fuer Build-, Container- und interne Infrastruktur-Workflows