agent-chat
Übersicht
Peer-Agent-Sitzungen koordinieren sich durch den Austausch von Markdown-Dateien in gemeinsamen Kanalordnern – kein Supervisor, kein Nachrichtenbroker, kein gemeinsamer RAM. Jeder Kanal ist ein "Gruppenchat". Der gesamte Thread ist reines Markdown: git-committierbar, menschenlesbar, wiederholbar. Eine abgestürzte Sitzung verliert nichts – die Dateien sind der Zustand.
Die reine Stdlib-CLI (chat.py plus das zugehörige Paket agent_chat/) läuft unter Windows, WSL und Linux. wait schläft zwischen Dateisystemprüfungen und tätigt keine Modellaufrufe.
Kernprinzip: Sprich durch Dateien, nicht durch einander. Zusammenfassungen als Artefakte, keine vollständigen Transkripte, die hin und her gereicht werden.
Dies ist eine lokale Koordinations-Datenschicht, kein MCP-Server oder Agent-Ausführer. Nachrichten, Aufgaben, Leases, Pfadsperren, Fähigkeits-/Statusereignisse und abgeleitete Zustände tätigen keine Completion-, Embedding-, Rerank-, Graphdienst- oder Relay-/Provider-Aufrufe.
Wann verwenden
- Mehrere OMP- oder andere kompatible Agent-Sitzungen, die gleichberechtigt am selben Problem arbeiten.
- Eine Sitzung benötigt eine andere, um etwas zu tun, und wartet dann auf das Ergebnis.
- Sie möchten eine prüfbare Aufzeichnung einer Agentenverhandlung.
- Sie benötigen mehrere unabhängige Gruppenchats (einen pro Thema/Team) – erstellen Sie einen Kanal pro Gruppe.
Wann NICHT verwenden: Ein einzelner Agent mit kostengünstigen Unteragenten ist günstiger und einfacher – dieses Muster tauscht Tokens gegen Parallelität, Fehlertoleranz und Prüfbarkeit. Wenn das Token-Budget knapp ist, verwenden Sie nur den asynchronen/Übergabepfad (posten Sie am Ende der Sitzung eine Zusammenfassung; die nächste Sitzung liest sie) – dieser Modus kostet fast nichts.
Kurzreferenz
Verwenden Sie agent-chat <cmd> nach pipx install agent-chat-plugin, oder
uvx --from agent-chat-plugin agent-chat <cmd> für jeden einmaligen Aufruf.
uvx installiert keinen dauerhaften Befehl. Verwenden Sie bei einem eigenständigen Skill SKILL.md, chat.py und das gesamte Verzeichnis agent_chat/ zusammen und führen Sie python "/path/to/skill/chat.py" <cmd> aus. Die Beispiele kürzen dies als chat.py ab.
Das Claude Code Plugin verwendet python "${CLAUDE_PLUGIN_ROOT}/chat.py" <cmd>.
Andere Hosts verwenden einen tatsächlichen Auscheckpfad, keine angenommene Plugin-Variable.
Root-Priorität ist --root > $AGENT_CHAT_ROOT > ~/agent-chat; setzen Sie --root vor den Unterbefehl. Standard-Roots verschiedener Maschinen sind nicht synchronisiert.
PyPI installiert nur die CLI-/Laufzeitmodule. Optionale hooks/*.py stammen aus dem Checkout/Plugin und benötigen ein explizites Host-Lifecycle-Wiring. Ihre Python-Einstiegspunkte sind portabel; ihre Registrierung und ihr Ausgabevertrag sind nicht automatisch eine OMP-Integration. Sitzungs-/Eingabeaufforderungsnotizen sind Text; Stop emittiert Claude-kompatibles systemMessage JSON. Hooks schauen, ohne Cursor zu bewegen, und beenden immer mit 0; unaufgelöste CLAUDE_PLUGIN_ROOT oder skriptrelative Plugin-Roots werden mit einer einzeiligen stderr-Diagnose übersprungen.
| Führen Sie dies aus | Befehl |
|---|---|
| Erstellen eines Gruppenchats | chat.py init review --members alice,bob --topic "..." |
| Alle Gruppenchats auflisten | chat.py channels |
| Eine Nachricht posten | chat.py post review --from alice --to bob --title "Schema v0.2" --body-file msg.md |
| An die Gruppe senden | chat.py post review --from alice --to all --title "..." (oder --to weglassen) |
| Lesen, was für mich neu ist | chat.py read review --as bob |
| Auf eine Antwort warten (0 Tokens) | chat.py wait review --as alice --timeout 900 |
| Kurz reinsehen, Cursor behalten | chat.py peek review -n 3 |
| Aufgabenmarkierung beanspruchen | chat.py claim work task-12.md --as bob |
| Arbeitsbereichspfade sperren | chat.py lock review src/main.py --as alice --lease-seconds 300 |
| Pfadkonflikte prüfen | chat.py check review src/main.py |
| Pfadsperre aufheben | chat.py unlock review <lock-id-or-path> --as alice |
| Veraltete Sperre wiederherstellen | chat.py recover review <lock-id-or-path> --as bob --reason "stale" |
| Ausstehende Pfadtransaktion wiederherstellen | chat.py recover-pending review --as alice |
| Kanalzustand darstellen | chat.py state review |
| Kanalzustand komprimieren | chat.py compact review --as alice |
| Fähigkeits-/Statusereignis posten | chat.py event post review --from alice --type capability --harness omp |
| Adapterereignisse lesen | chat.py event read review --type capability |
Adapterneutrale Ereignisse verwenden die Schema-Version 1 und werden als JSON-Inhalte in gewöhnlichen Kanalnachrichten übertragen. Fähigkeitsereignisse werben nur für die portablen Grundelemente messages, cursors, wait, tasks, dependencies, leases, path_locks und state_summary. Statusereignisse verwenden ready, busy, idle, blocked oder stopped, mit optionalen Details. Unbekannte Felder, Grundelemente, Versionen, Zeitstempel, Identitäten und Status schlagen mit stabilen EVENT_*-Fehlern fehl. Dieses Protokoll erhebt keinen Anspruch auf MCP, ACP, Wake Bridge oder Agentenausführung. Strukturierte Aufgaben verwenden dieselbe Kanalwurzel und schreiben maßgebliche JSON-Datensätze unter <root>/<channel>/tasks/; aktive Lease-Datensätze leben unter <root>/<channel>/claims/<task-id>.<owner>.json. Jede erfolgreiche Aufgaben- oder Lease-Mutation postet auch ein Prüfereignis über das vorhandene Nachrichtenprotokoll:
chat.py task create <channel> <task-id> --from <agent> --title <title>
chat.py task list <channel>
chat.py task show <channel> <task-id>
chat.py task update <channel> <task-id> --as <agent> [fields...]
chat.py task claim <channel> <task-id> --as <agent> --lease-seconds 300
chat.py task renew <channel> <task-id> --as <agent> --lease-seconds 300
chat.py task done <channel> <task-id> --as <agent>
chat.py task block <channel> <task-id> --as <agent>
chat.py task release <channel> <task-id> --as <agent>
chat.py task recover <channel> <task-id> --as <agent> \
--reason "stale session" --lease-seconds 300
chat.py task recover-pending <channel> --as <agent> \
[--resolve-publication rollback|published]
claim, renew und erfolgloses recover akzeptieren --lease-seconds, --lease oder --ttl; der Wert muss eine positive endliche Dauer sein. claim verschiebt eine bereite Aufgabe zu in_progress, weist den Besitzer zu und schreibt sein Ablaufdatum atomar mit dem Anspruchsdatensatz. Nur der Besitzer kann einen nicht abgelaufenen Anspruch erneuern, freigeben oder abschließen. task done löscht einen aktiven Anspruch atomar; wenn kein Anspruch existiert, bewahrt es den direkten Task 3-Übergang. task release bewahrt ebenfalls den nicht geleasten Task 3-Übergang. Ein abgelaufener Anspruch wird niemals stillschweigend gestohlen: erfolgloses task recover erfordert einen neuen Besitzer und einen nicht leeren Grund und zeichnet previous_owner, previous_lease_expires_at und recovery_reason auf. Nach einem Absturz schließt task recover-pending <channel> --as <agent> explizit die Bereinigung/Rückgängigmachung des dauerhaften Transaktionsmarkers ab; es stiehlt oder weist niemals stillschweigend eine veraltete Aufgabe neu zu. Legacy v1 applied-Marker, deren Prüfpublikation nicht nachgewiesen werden kann, schlagen mit LEASE_TRANSACTION_PUBLICATION_UNKNOWN fehl; führen Sie den Befehl nach einer Betreiberüberprüfung mit --resolve-publication rollback oder published erneut aus.
create akzeptiert --owner, --depends-on, --files-hint, --acceptance und --branch. Wiederholen Sie Listenoptionen, um mehrere Werte hinzuzufügen. update akzeptiert --title, --owner, --depends-on, --files-hint, --acceptance, --branch und --status; verwenden Sie --clear-owner oder --clear-branch, um nullable Felder auf null zurückzusetzen. Generische Aktualisierungen können kein aktives Lease mutieren; verwenden Sie stattdessen die Lease-Befehle. Listenwerte können auch kommagetrennt sein.
Aufgabenstatus sind open, in_progress, blocked, done und cancelled.
done und cancelled sind terminiert. Übergänge erlauben open -> in_progress | blocked | cancelled, in_progress -> open | blocked | done | cancelled und blocked -> open | in_progress | cancelled. Gleiche-Zustand-Schreibvorgänge sind absichtlich idempotent. task done verschiebt in_progress (oder idempotent done) zu done; task block verschiebt open, in_progress oder blocked zu blocked; und task release verschiebt blocked, in_progress oder open zu open. Eine Aufgabe kann nur zu in_progress oder done wechseln, wenn jede ID in depends_on einen Aufgabendatensatz mit dem Status done hat. Die Bereitschaft wird aus Aufgaben-JSON-Datensätzen berechnet, niemals aus Nachrichtentext.
Aufgaben- und Lease-Fehlschläge sind ungleich Null (Exit-Status 2) und enthalten einen stabilen Code. Aufgaben-Codes umfassen TASK_INVALID_COMMAND, TASK_INVALID_ARGUMENT, TASK_INVALID_CHANNEL, TASK_CHANNEL_NOT_FOUND, TASK_NOT_FOUND, TASK_ALREADY_EXISTS, TASK_INVALID_STATUS, TASK_INVALID_UPDATE, TASK_INVALID_TRANSITION, TASK_DEPENDENCY_NOT_READY, TASK_UNKNOWN_DEPENDENCY, TASK_DEPENDENCY_CYCLE, TASK_PATH_OUTSIDE_WORKSPACE, TASK_LOCK_TIMEOUT, TASK_IO_ERROR und TASK_AUDIT_FAILED. Lease-Codes umfassen LEASE_CONFLICT, LEASE_RECOVERY_REQUIRED, LEASE_OWNER_MISMATCH, LEASE_NOT_EXPIRED, LEASE_NOT_FOUND, LEASE_INCONSISTENT, LEASE_MUTATION_REQUIRED, LEASE_INVALID_OWNER, LEASE_INVALID_TASK_ID, LEASE_INVALID_CHANNEL, LEASE_INVALID_REASON, LEASE_INVALID_DURATION, LEASE_INVALID_TIMESTAMP, LEASE_INVALID_RECORD, LEASE_REQUIRED_FIELD_MISSING, LEASE_UNKNOWN_FIELD, LEASE_RECORD_ID_MISMATCH, LEASE_STORAGE_INVALID, LEASE_PATH_OUTSIDE_WORKSPACE, LEASE_TRANSACTION_PENDING, LEASE_TRANSACTION_CLEANUP_FAILED, LEASE_TRANSACTION_PUBLICATION_UNKNOWN, LEASE_TRANSACTION_INVALID, LEASE_TRANSACTION_NOT_FOUND, LEASE_TRANSACTION_RECOVERY_FAILED, LEASE_AUDIT_FAILED und LEASE_AUDIT_ROLLBACK_FAILED. Lease-Schreibvorgänge verwenden einen dauerhaften Transaktionsmarker mit Phasen vorbereitet/angewendet/veröffentlicht; nach einem Absturz oder Bereinigungsfehler schlagen Zugriffe fehl, bis task recover-pending/LeaseStore.recover_pending() explizit rückgängig macht oder die veröffentlichte Transaktion abschließt.
Pfadsperren koordinieren den exklusiven Zugriff auf arbeitsbereichsrelative Dateien und Verzeichnisse:
chat.py lock <channel> <paths...> --as <agent> [--lease-seconds 300]
chat.py check <channel> <paths...> [--as <agent>]
chat.py unlock <channel> <lock-id-or-path> --as <agent>
chat.py recover <channel> <lock-id-or-path> --as <agent> \
--reason "stale session" [--lease-seconds 300]
chat.py recover-pending <channel> --as <agent> \
[--resolve-publication rollback|published]
lock und recover akzeptieren --lease-seconds, --lease oder --ttl. Ziel kann die Sperr-ID oder der exakte normalisierte Pfad sein. Die Normalisierung löst arbeitsbereichsrelative Pfade auf, verhindert Traversal- und Root-/Kanal-/Symlink-Escapes, wendet plattformspezifische Groß-/Kleinschreibungsregeln an (Groß-/Kleinschreibung nicht unterscheidend unter Windows) und lehnt reservierte Windows-Namen, nachgestellte Punkte/Leerzeichen, Steuerzeichen und einzelne Surrogate ab. Datei/Datei-Kollisionen und Verzeichnis/Datei-Überlappungen stehen in Konflikt. Nur der Besitzer kann eine aktive Sperre entsperren; abgelaufene Sperren erfordern explizites recover, das previous_owner, previous_expires_at und recovery_reason aufzeichnet. Mutationen verwenden inhaltsatomares Datei-Publishing, beratende Dateisperren und absturzsicheres Transaktions-Journaling. Pfadsperrfehler beenden mit einem Exit-Status ungleich Null und stabilen Codes wie PATH_LOCK_INVALID_PATH, PATH_LOCK_PATH_OUTSIDE_WORKSPACE, PATH_LOCK_CONFLICT, PATH_LOCK_RECOVERY_REQUIRED, PATH_LOCK_OWNER_MISMATCH, PATH_LOCK_NOT_FOUND, PATH_LOCK_NOT_STALE, PATH_LOCK_INVALID_OWNER, PATH_LOCK_INVALID_LOCK_ID, PATH_LOCK_INVALID_CHANNEL, PATH_LOCK_INVALID_REASON, PATH_LOCK_INVALID_DURATION, PATH_LOCK_INVALID_TIMESTAMP, PATH_LOCK_INVALID_RECORD, PATH_LOCK_STORAGE_INVALID, PATH_LOCK_STORAGE_ERROR, PATH_LOCK_TIMEOUT, PATH_LOCK_TRANSACTION_PENDING, PATH_LOCK_TRANSACTION_CLEANUP_FAILED, PATH_LOCK_TRANSACTION_INVALID, PATH_LOCK_AUDIT_FAILED und PATH_LOCK_AUDIT_ROLLBACK_FAILED.
Kanalzustandszusammenfassung und -komprimierung leiten ein deterministisches state.md-Artefakt ab:
chat.py state <channel> [--write] [--json] [--strict]
chat.py compact <channel> [--as <agent>] [--no-audit] [--json] [--strict]
state rendert oder gibt die abgeleitete Kanalzusammenfassung aus, die Folgendes enthält:
- Ziel / Thema (aus
_meta.json) - Entscheidungen (extrahiert aus Nachrichten und strukturierten Datensätzen)
- Offene Aufgaben (aus
tasks/*.json, einschließlich Status, Besitzer, Lease, Abhängigkeiten) - Blocker (Aufgabenabhängigkeitsblocker, blockierte Aufgabenstatus und Blockernachrichten)
- Besitzer & Leases (aktive Ansprüche, Aufgabenbesitzer und Pfadsperren)
- Pfadsperren (aktive Pfadsperren aus
locks/*.json) - Letzte Überprüfungsnachweise (Abnahmekriterien und Überprüfungsnachrichten)
compact schreibt die abgeleitete Zusammenfassung unter Verwendung atomaren temporären Geschwisterersatzes (.state.md.tmp.*) in <root>/<channel>/state.md und postet standardmäßig ein prüfbares state.compacted-Nachrichtenereignis im Kanal.
state.md ist strikt ein abgeleitetes Artefakt und niemals maßgeblich. Die Komprimierung ist nicht destruktiv: Sie löscht, mutiert oder kürzt niemals eine Nachrichtendatei, Aufgabendatensatz, aktiven Anspruch, Pfadsperre oder Lesecursor. Alle Quelldatensätze bleiben die unveränderliche Grundwahrheit. Zustandsfehler beenden mit einem Exit-Status ungleich Null und stabilen Codes wie STATE_INVALID_CHANNEL, STATE_CHANNEL_NOT_FOUND, STATE_INVALID_RECORD, STATE_MALFORMED_SOURCE, STATE_RECORD_NOT_FOUND, STATE_IO_ERROR und STATE_AUDIT_FAILED. --reply <seq> verwebt eine Nachricht mit einer früheren. python chat.py <cmd> --help für alle Flags.
Adapterneutrale Ereignisbefehle:
chat.py event post <channel> --from <agent> --type capability --harness <harness>
chat.py event post <channel> --from <agent> --type status --harness <harness> --status ready
chat.py event read <channel> [--type capability|status]
Der Ereignisinhalt ist versioniertes JSON, validiert gegen schemas/agent-chat-event.schema.json. Gewöhnliche Markdown-Nachrichten bleiben unverändert und werden von event read ignoriert.
Ordnerstruktur
<root>/
review/ # ein Kanal = ein Gruppenchat
_meta.json # Mitglieder, Thema, erstellt
state.md # abgeleitete Zustandszusammenfassung (nicht maßgeblich)
0001-alice-schema-draft.md # NNNN-<from>-<slug>.md, Frontmatter + Inhalt
0002-bob-schema-review.md
tasks/ # strukturierte Aufgabendatensätze
claims/ # aktive Lease-Datensätze
locks/ # aktive Arbeitsbereichspfadsperren
.cursors/bob.txt # pro Agent "zuletzt gelesene Seq"
deploy/ # ein ZWEITER Gruppenchat, separater Seq-Bereich
...