diff --git a/.gitignore b/.gitignore index 39d5d7a..f979906 100644 --- a/.gitignore +++ b/.gitignore @@ -68,6 +68,11 @@ _scratch/ _proof/ # Security and hygiene guards +_after-care/ +BEFUNDE.md +MARKETING-LOG.txt + + *.pem *.key *.pfx @@ -101,13 +106,11 @@ uv.lock # Host-spezifische Sync-Dateien (OneDrive Sync-Konflikte) *-ASUS-GEI* *-ASUS* -*-WORKSTATION-LG* *-WORKSTATION* *-LAPTOP* *-Mac Studio* *-MacBook* *-IDEAPAD* -*-IDEAPAD-GEI* *.sync-conflict-* *.conflict *-conflict-* diff --git a/BEFUNDE.md b/BEFUNDE.md deleted file mode 100644 index b4aabac..0000000 --- a/BEFUNDE.md +++ /dev/null @@ -1,55 +0,0 @@ -# Maintainer-Befunde - -## 2026-08-13 – Multi-Agent-Integrationsabdeckung - -- Task 1311 ergänzt drei prozessfreie Integrationstests für zwei unabhängige - `JobRunner` auf einem `JobBoard`, den CLI-`--dry-run` mit ältestem Auftrag - sowie inkrementelles Agent-JSONL-Streaming über `since()` und `inbox`. -- `python -m pytest -q`: **236 Tests bestanden**. -- `ruff check coma comas tests`, `python -m compileall -q coma comas tests` - und `git diff --check`: **ohne Befund**. -- Echte Agentenprozesse werden weiterhin nicht gestartet; die Tests prüfen - bewusst Protokoll-, Status- und Kommandoverträge mit Fakes. - -## 2026-08-01 – deterministischer Qualitätscheck - -- Der Arbeitsbaum war vor der Prüfung sauber; der lokale Branch `main` war - synchron mit `origin/main` und wurde nicht verändert oder veröffentlicht. -- `python -m pytest -q`: **233 Tests bestanden**. -- `python -m compileall -q coma comas tests`: **ohne Befund**. -- `ellmos-module.v2.json`: **gültig gelesen**, Schema `ellmos.module.v2`, - ID `coma`, Version `0.2.0`. - -### Offene Gates - -Der Kimi-Adapter bleibt wie in README und Konzept als Gerüst/unverified -gekennzeichnet. Aus diesem Maintainer-Lauf wurden keine unverified Adapter, -Agentenprozesse oder externen Kommunikationspfade gestartet. - -## 2026-08-20 – TASKWRITER-Readback / offene COMA-Gates - -- Der aktuelle Plan-D-Clone steht sauber auf `c129f3d` und ist zu `origin/main` - paritätisch. Task 1310 (comas-Kompatibilitätsalias) und Task 1311 - (Multi-Agent-Integrationsabdeckung) sind bereits `done`; der Evidence- - Readback zu 1311 wurde nicht erneut als offene Arbeit angelegt. -- Der aktuelle Release-/Manifeststand ist 0.2.1 mit 241 dokumentierten Tests. - Ältere Angaben in diesem Befundregister und in `KONZEPT.md` sowie ein - widersprüchlicher Agy-Docstring bleiben als geklärte Dokumentationslücken - sichtbar und werden nicht stillschweigend überschrieben. -- Über die TASKPLAN-API wurden die belegten nächsten Schritte formalisiert: - `2088` Dokumentations-/Adapterparität (`effort=medium`, `scope=local`), - `2089` Kimi-Verifikationsgate (`special`, `local`), `2090` zentrale - Multi-Agent-Registry (`large`, `local`), `2091` autorisiertes Plan-D- - Deployment (`special`, `local`) und `2092` Cross-Projekt-Migration von - `llmauto`/`swarm-ai` (`large`, `central`). -- Der im Konzept genannte Zielpfad `/.CONTROL/coma` - ist nicht vorhanden; der OneDrive-Cloud-Filter meldet dort weiterhin hohes - Lock-Risiko. Es wurde nichts kopiert, verschoben, überschrieben, getestet, - live gestartet, veröffentlicht oder gepusht. - -## 2026-09-12 – Status-, Adapter- und Release-Parität (Tasks 2088 / 2078) - -- Agy-Adapter-Docstring in `coma/adapters/agy.py` auf `verified = True` korrigiert. -- `KONZEPT.md` Status, Versionsstand (0.2.1) und Adapter-Verifikation (Claude, Codex, Agy verifiziert, Kimi Gerüst) synchronisiert. -- `python -m pytest`: **260 Tests bestanden** (100% grün, prozessfrei). -- Die OneDrive-Projektion (`/.TOPICS/.AI/.MODULES/.ORCHESTRATION/coma`) bleibt als gitlose Altprojektion klassifiziert; keine unautorisierte Spiegelung bei aktiver cldflt.sys Lock-Gefahr. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b0b3a9..f8982a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,34 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Added -- Pfad B ASCII Four-View Architectural Topology (`### ASCII Four-View Architectural Topology` / `### ASCII Vier-Sichten-Architekturtopologie`) in Section 2 of both `README.md` and `README_de.md` projecting all 10 architectural and runtime invariants `INV-COMA-01` through `INV-COMA-10` across View 1 (Client & Orchestrator Entrypoints), View 2 (Single-Writer Protocol & Directory Queues), View 3 (COMA Core Engine & Multi-Provider CLI Adapters), and View 4 (Air-Gap Perimeter, Unprivileged `RunAsInvoker` & Governance). -- Re-audited Level 1 SBOM text companion `THIRD_PARTY_LICENSES.txt` and `THIRD_PARTY_LICENSES.md` to Stand 2026-10-04 with confirmed zero external runtime dependencies (`INV-COMA-02`), Zero-Copyleft isolation guarantee, unprivileged user-mode certification (`RunAsInvoker`), and 48h Security Response SLA. -- Synchronized Shields.io test status badges to 313 passed tests (`pytest-313 passed` / `pytest-313 bestanden | 100% green`) and recency markers (`Verified: 2026-10-04` / `Geprüft: 2026-10-04`) across English and German README editions. -- Updated `llms.txt` context index (`Last-checked: 2026-10-04`, 313 passed tests baseline) and Section 13 testing guidelines. -- Section 12 in `MARKETING-LOG.txt` documenting the Pfad B discoverability audit Stand 2026-10-04 with live traffic analytics (274 clones across 98 unique cloners) and 3 actionable recommendations (`REC-20261004-01`, `REC-20261004-02`, `REC-20261004-03`). -- Automated contract tests in `tests/test_metadata.py` verifying bilingual ASCII four-view architectural topology parity, Level 1 SBOM recency Stand 2026-10-04, marketing log Section 12 presence, and badge recency. -- CI Lifecycle Workflows `.github/workflows/auto-assign.yml` (`actions/github-script@v7`, `timeout-minutes: 5`, least-privilege `pull-requests: write`, `issues: write`, concurrency cancellation) and `.github/workflows/label-sync.yml` (`EndBug/label-sync@v2`, `timeout-minutes: 5`, `issues: write`). -- Canonical `.github/labels.yml` defining 11 standard triage labels according to GOVERNANCE.md §4.2. -- Comprehensive bilingual `CONTRIBUTING.md` guide (EN/DE) with formal Quality Gates, Plan D local development workflow, unprivileged `RunAsInvoker` guarantee (`INV-COMA-09`), and complete compliance matrix for operational invariants `INV-COMA-01` through `INV-COMA-10`. -- Registered `"Contributing"`, `"Level 1 SBOM"`, and `"Plain-Text License"` URLs in PEP 621 `[project.urls]` within `pyproject.toml`. -- Re-audited Level 1 SBOM companion `THIRD_PARTY_LICENSES.txt` and `THIRD_PARTY_LICENSES.md` to Stand 2026-10-01, validating Zero External Runtime Dependencies (`INV-COMA-02`), Zero-Copyleft Isolation, and unprivileged user-mode execution. -- Multi-host sync and lock protection in `.gitignore` covering `TASKPLAN_*.md`, `ehthumbs.db`, `LOCK.dev.*`, `LOCK.antigravity.*`, and `LOCK.bugsearch.*`. -- Hardened pytest configuration in `pyproject.toml` with `.pytest_tmp*`, `.tox`, and `.turbo` in `norecursedirs`. -- Section 11 in `MARKETING-LOG.txt` documenting the Pfad A maintenance & hygiene audit (Stand 2026-10-01). -- Synchronized Shields.io badges across `README.md` and `README_de.md` for `Verified: 2026-10-01` / `Geprüft: 2026-10-01`. -- Updated `llms.txt` context index (`Last-checked: 2026-10-01`). -- Expanded automated contract test suite in `tests/test_metadata.py` verifying CI lifecycle workflows, labels, contributing guidelines, PEP 621 URLs, and SBOM recency. -- 18-point bilingual quick navigation parity across `README.md` and `README_de.md` with reciprocal dual HTML anchors (``..`` aliases). -- Plain-text Level 1 SBOM companion `THIRD_PARTY_LICENSES.txt` with Invariant Cross-Reference Matrix table mapping `INV-COMA-01`..`INV-COMA-10`, unprivileged user-mode certification (`RunAsInvoker`), and full license text inventory. -- Registered `"Third-Party Licenses (Text)"` URL in `[project.urls]` and included `THIRD_PARTY_LICENSES.txt` in PEP 621 `license-files` within `pyproject.toml`. -- Saturated PEP 621 package `keywords` with full 20/20 GitHub repository topics. -- Hardened pytest runner configuration with `addopts = "-ra -v --basetemp=.pytest_temp"` and `.hypothesis` in `norecursedirs`. -- Expanded `.gitignore` with multi-host tokens (`*-IDEAPAD*`, `*-IDEAPAD-GEI*`), cache patterns (`.pytest_tmp*/`), and Windows folder descriptors (`Desktop.ini`, `desktop.ini`). -- Updated `NOTICE` attribution cross-referencing `THIRD_PARTY_LICENSES.txt`. -- Root `NOTICE` file establishing formal open-source copyright attribution (Lukas Geiger / ellmos-ai / open-bricks). -- Extended `SECURITY.md` with explicit 48-hour acknowledgment SLA, 5-business-day triage commitment, and official security reporting addresses (`security@ellmos.ai`, `security@open-bricks.org`, `lukas@open-bricks.org`). -- Section 10 in `MARKETING-LOG.txt` documenting the Pfad B marketing, discoverability, and visual architecture audit. +### Scope correction — 2026-10-11 + +- Corrected current documentation to distinguish COMA's local-file and subprocess behavior from the network access, privileges, environment, and permission controls of launched agent CLIs. One writer per channel is a caller convention, and probe cleanup is best-effort. +- This scope correction supersedes earlier marketing, certification, air-gap, zero-egress, zero-copyleft-isolation, and non-elevation claims in prior Unreleased descriptions and historical documentation. Dates, test counts, and CLI versions below record their original snapshots only; they are not current verification or certification. + +### Changed — 2026-10-11 +- Clarified in the English and German READMEs, SECURITY.md, CONTRIBUTING.md, KONZEPT.md, llms.txt, package metadata, and the license inventory that COMA itself uses local files and subprocesses while launched agent CLIs inherit caller privileges and may access networks. +- Replaced network-isolation, zero-copyleft, RunAsInvoker, certification, and process-tree cleanup guarantees with the documented runtime boundaries. One writer per channel is described as a caller protocol requirement; probe cleanup is best-effort. +- Corrected adapter examples, role-manifest examples, current CLI source links, and the scope of historical provider compatibility checks. +- Updated THIRD_PARTY_LICENSES.md and THIRD_PARTY_LICENSES.txt with the actual project and tooling license metadata; linked to the complete upstream Python license text. +- Updated TODO.md to retain open task identifiers while removing stale current-status claims and clarifying that the kimi-cli 0.31.0 check does not verify kimi-code. + +### Removed +- Removed internal maintenance records from the public tracked set while retaining their local copies. +- Removed fixed test-count and verification-date badges, and removed automated assertions that depended on internal marketing logs, dated snapshots, or unsupported guarantees. + +### Earlier unreleased work — snapshot 2026-10-04 +- Earlier work added the bilingual 18-section README navigation, four-view architecture diagrams, CI lifecycle workflows and labels, contribution guidance, PEP 621 metadata and URLs, test-runner configuration, multi-host ignore patterns, and NOTICE attribution. +- SECURITY.md records maintainer acknowledgment and triage response targets; these are maintainer policy, not runtime guarantees. +- The earlier snapshot also recorded dated test counts, adapter versions, and discoverability measurements. Those values remain historical observations and do not establish current verification or certification. ## [0.3.2] — 2026-09-19 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f35768..bd0210d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,30 @@ # Contributing to coma / Mitwirken an coma -Welcome! We welcome contributions to `coma` (Command & Communication for Autonomous Agents). To maintain deterministic session decoupling, air-gapped process isolation, single-writer filesystem safety, and compliance across multi-host environments, all contributions must adhere to the quality standards and operational invariants defined below. +Welcome! Contributions improve COMA's local-file job protocol, subprocess lifecycle, CLI adapters, and developer documentation. The documented behavior and limits below describe the current implementation and maintainer policies. --- ## English ### 1. General Principles & Quality Gates -1. **Local-First & Zero-Egress (`INV-COMA-02`)**: Core library and CLI logic must operate strictly offline by default. Zero external runtime dependencies; 100% Python standard library. Never introduce telemetry, outbound sockets, or external network requests. -2. **Single-Writer Rule (`INV-COMA-01`)**: Exactly one writer per channel file (`IN/`, `OUT/`, `DONE/`), eliminating race conditions and lock contention. -3. **Session Decoupling & RC Immunity (`INV-COMA-03`)**: Subprocesses spawn in dedicated process trees outside interactive terminal sessions, bypassing remote-control permission stalls. -4. **Process-Free Dry Runs (`INV-COMA-04`)**: Command builders (`build_cmd`, `build_session_plan`, `--dry-run`) must construct argument vectors without launching processes or consuming LLM tokens. -5. **Deterministic Multi-Provider Fallback (`INV-COMA-05`)**: Candidate chain (`ordered_candidates`, `available_candidates`) resolves CLI binaries systematically across Claude Code, Codex, AGY, and Kimi. -6. **Fail-Closed Provider Safety (`INV-COMA-06`)**: Unverified or experimental adapters remain strictly fail-closed unless callers explicitly opt in with an established contract. -7. **Bounded Probe Cleanup (`INV-COMA-07`)**: Reachability probes enforce strict execution timeouts and guarantee child-process termination to prevent zombie processes. -8. **Idempotent Dual-Platform Starters (`INV-COMA-08`)**: Generated starter scripts (`START.bat`, `start.sh`) carry unique marker guards preventing accidental overwrites of custom wrappers. -9. **Unprivileged User-Mode Execution (`INV-COMA-09` / `RunAsInvoker`)**: Core process management, job board polling, and CLI execution run strictly in unprivileged user space without administrative elevation. -10. **48h Security & Governance SLA (`INV-COMA-10`)**: Maintain 48h acknowledgment and 5-business-day triage commitments for security reports. -11. **Version Freeze Discipline (`T-20260920-167562623`)**: Version 0.3.2 is strictly frozen across all manifests. Do not bump the version string. Document all advancements under `## [Unreleased]` in `CHANGELOG.md`. -12. **Clean Code & Regression Testing**: Every feature or fix must include regression tests in `tests/`. Keep test coverage at 100% pass rate. -13. **Bilingual Parity**: Maintain synchronized structural and navigational parity across `README.md` and `README_de.md` (18-point dual anchors `sec-01` through `sec-18`). + +1. **Local COMA boundary (`INV-COMA-02`)**: COMA uses local files and subprocesses and does not implement a network service. Launched agent CLIs may contact their providers or other services; COMA does not sandbox them or block network access. Keep the direct Python runtime dependency list empty unless a change is explicitly justified. +2. **Channel writer convention (`INV-COMA-01`)**: Callers must assign one writer per channel file. Optional role checks are not OS locking or identity enforcement; callers coordinate concurrent writers. +3. **Subprocess lifecycle (`INV-COMA-03`)**: COMA starts provider CLIs as subprocesses. Child processes inherit the launcher's privileges and environment; COMA does not create a security sandbox or drop privileges. +4. **Process-free dry runs (`INV-COMA-04`)**: Command builders (`build_cmd`, `build_session_plan`, `--dry-run`) construct argument vectors without launching the provider CLI. +5. **Provider fallback (`INV-COMA-05`)**: Candidate helpers (`ordered_candidates`, `available_candidates`) resolve CLI binaries according to the configured adapter order. +6. **Adapter opt-in (`INV-COMA-06`)**: Kimi execution through the spawner/session path requires explicit opt-in; raw adapter and probe argument builders do not enforce this gate. +7. **Probe cleanup (`INV-COMA-07`)**: Reachability probes use a timeout and best-effort platform-dependent cleanup; do not describe this as guaranteed process-tree termination. +8. **Starter generation (`INV-COMA-08`)**: Generated starter scripts (`START.bat`, `start.sh`) use marker guards to avoid overwriting customized wrappers. +9. **Inherited privileges (`INV-COMA-09`)**: Child processes inherit the launching process's privileges. COMA does not request elevation or drop privileges; it is not a security isolation boundary. +10. **Maintainer response policy (`INV-COMA-10`)**: `SECURITY.md` documents the maintainers' 48-hour acknowledgment and 5-business-day triage targets. +11. **Version freeze discipline (`T-20260920-167562623`)**: Version `0.3.2` remains frozen across manifests. Do not bump it. Document changes under ## [Unreleased] in `CHANGELOG.md`. +12. **Clean code & regression testing**: Add tests for behavioral changes in `tests/`. Keep the complete suite passing. +13. **Bilingual parity**: Maintain synchronized structure and navigation across `README.md` and `README_de.md` (18-point dual anchors `sec-01` through `sec-18`). ### 2. Local Development Workflow -```bash + +~~~bash # Install package with development dependencies python -m pip install -e ".[test]" @@ -33,38 +35,41 @@ python -X utf8 -m pytest -ra -v python -m ruff check . # Check bytecode compilation -python -m compileall -q . +python -m compileall -q coma comas tests # Check whitespace and git diff cleanliness git diff --check -``` +~~~ ### 3. Submission Protocol + - Open an issue for behavioral discussions before large refactoring. - Keep provider API keys, bearer tokens, and private credentials strictly outside the repository. -- Ensure all 10 governance invariants (`INV-COMA-01` to `INV-COMA-10`) remain VERIFIED. +- Describe changes to the documented behavior or limits in the relevant public documentation. --- ## Deutsch ### 1. Grundsätze & Qualitäts-Tore -1. **Local-First & Zero-Egress (`INV-COMA-02`)**: Sämtliche Kernbibliotheken und CLI-Abläufe arbeiten standardmäßig zu 100% offline ohne Telemetrie, Sockets oder externe Datenübertragung. Null externe Laufzeitabhängigkeiten, 100% Python Standard-Bibliothek. -2. **Single-Writer-Regel (`INV-COMA-01`)**: Genau ein Schreiber pro Kanal-Datei (`IN/`, `OUT/`, `DONE/`), wodurch Race Conditions und Lock-Konflikte strukturell ausgeschlossen werden. -3. **Sitzungsentkopplung & RC-Immunität (`INV-COMA-03`)**: Subprozesse starten in isolierten Prozessbäumen außerhalb interaktiver Terminal-Sessions. -4. **Prozessfreie Trockenläufe (`INV-COMA-04`)**: Kommandokonstruktion (`build_cmd`, `build_session_plan`, `--dry-run`) erzeugt verifizierte argv-Vektoren ohne Prozessstart und ohne Token-Verbrauch. -5. **Deterministischer Multi-Provider-Fallback (`INV-COMA-05`)**: Systematische Adapter-Kandidatenkette über Claude Code, Codex, AGY und Kimi. -6. **Fail-Closed Provider-Sicherheit (`INV-COMA-06`)**: Unverifizierte oder experimentelle Adapter bleiben strikt fail-closed, sofern kein expliziter Opt-in vorliegt. -7. **Terminierende Sondenbereinigung (`INV-COMA-07`)**: Erreichbarkeitssonden erzwingen strikte Timeouts und garantieren die Beendigung von Kindprozessen zur Vermeidung von Zombie-Prozessen. -8. **Idempotente Plattform-Starter (`INV-COMA-08`)**: Generierte Starter-Skripte (`START.bat`, `start.sh`) besitzen eindeutige Schutzmarker gegen versehentliches Überschreiben manueller Wrapper. -9. **Unprivilegierte Benutzer-Ausführung (`INV-COMA-09` / `RunAsInvoker`)**: Sämtliche Prozess-, Job- und CLI-Aufrufe laufen strikt im unprivilegierten Standard-Benutzerkontext ohne administrative Rechte oder UAC-Elevation. -10. **48h Sicherheits- & Governance-SLA (`INV-COMA-10`)**: Einhaltung von 48h Reaktionszeit und 5 Werktagen Triage-Frist für Sicherheitsmeldungen. -11. **Strikte Versions-Freeze-Disziplin (`T-20260920-167562623`)**: Version 0.3.2 bleibt in allen Manifesten eingefroren. Keine Versionserhöhung vornehmen; alle Änderungen unter `## [Unreleased]` in `CHANGELOG.md` festhalten. -12. **Testabdeckung & Regressionstests**: Für jede Verhaltensänderung ist ein Vertragstest in `tests/` zu ergänzen. Die Testsuite muss zu 100% grün bleiben. -13. **Zweisprachige Dokumentationsparität**: `README.md` und `README_de.md` müssen strukturgleich und mit synchronen 18-Punkte-HTML-Ankern (`sec-01` bis `sec-18`) gepflegt werden. + +1. **Lokale COMA-Grenze (`INV-COMA-02`)**: COMA verwendet lokale Dateien und Subprozesse und stellt keinen Netzwerkdienst bereit. Gestartete Agenten-CLIs können ihre Anbieter oder andere Dienste kontaktieren; COMA isoliert sie nicht in einer Sandbox und sperrt keinen Netzzugriff. Die Liste direkter Python-Laufzeitabhängigkeiten bleibt leer, sofern eine Änderung nicht ausdrücklich begründet ist. +2. **Kanal-Schreiberkonvention (`INV-COMA-01`)**: Aufrufer müssen jedem Kanal eine schreibende Instanz zuordnen. Optionale Rollenprüfungen sind weder Betriebssystem-Sperren noch Identitätsprüfung; parallele Schreiber müssen von den Aufrufern koordiniert werden. +3. **Subprozess-Lebenszyklus (`INV-COMA-03`)**: COMA startet Anbieter-CLIs als Subprozesse. Kindprozesse erben Rechte und Umgebung des startenden Prozesses; COMA stellt keine Sicherheitssandbox bereit und gibt keine Rechte ab. +4. **Prozessfreie Trockenläufe (`INV-COMA-04`)**: Befehlsbauer (`build_cmd`, `build_session_plan`, `--dry-run`) erzeugen Argumentvektoren, ohne das Anbieter-CLI zu starten. +5. **Provider-Fallback (`INV-COMA-05`)**: Kandidatenhelfer (`ordered_candidates`, `available_candidates`) lösen CLI-Binaries entsprechend der konfigurierten Adapterreihenfolge auf. +6. **Adapter-Opt-in (`INV-COMA-06`)**: Die Kimi-Ausführung über Spawner und Sitzungsplanung erfordert ein ausdrückliches Opt-in; rohe Adapter- und Probe-Argumentgeneratoren setzen diese Sperre nicht durch. +7. **Sondenbereinigung (`INV-COMA-07`)**: Erreichbarkeitssonden verwenden ein Timeout und eine plattformabhängige Bereinigung nach bestem Bemühen; sie garantieren keine Beendigung des gesamten Prozessbaums. +8. **Starter-Erzeugung (`INV-COMA-08`)**: Generierte Starter-Skripte (`START.bat`, `start.sh`) verwenden Schutzmarker, damit angepasste Wrapper nicht versehentlich überschrieben werden. +9. **Geerbte Rechte (`INV-COMA-09`)**: Kindprozesse erben die Rechte des startenden Prozesses. COMA fordert keine Erhöhung an und gibt keine Rechte ab; es ist keine Sicherheitsgrenze. +10. **Maintainer-Antwortpolitik (`INV-COMA-10`)**: `SECURITY.md` dokumentiert die Ziele der Maintainer: Bestätigung innerhalb von 48 Stunden und Triage innerhalb von 5 Werktagen. +11. **Versions-Freeze (`T-20260920-167562623`)**: Version `0.3.2` bleibt in allen Manifesten eingefroren. Keine Versionserhöhung vornehmen. Änderungen unter ## [Unreleased] in `CHANGELOG.md` festhalten. +12. **Sauberer Code & Regressionstests**: Verhaltensänderungen durch Tests in `tests/` absichern. Die vollständige Testsuite muss grün bleiben. +13. **Zweisprachige Parität**: Struktur und Navigation in `README.md` und `README_de.md` synchron halten (18 duale Anker `sec-01` bis `sec-18`). ### 2. Lokaler Entwicklungsablauf -```bash + +~~~bash # Entwicklungsumgebung einrichten python -m pip install -e ".[test]" @@ -75,13 +80,14 @@ python -X utf8 -m pytest -ra -v python -m ruff check . # Bytecode-Kompilierung -python -m compileall -q . +python -m compileall -q coma comas tests # Diff- und Whitespace-Prüfung git diff --check -``` +~~~ ### 3. Einreichung -- Vor größeren Eingriffen ein Issue zur Abstimmung anlegen. + +- Vor größeren Verhaltensänderungen ein Issue zur Abstimmung anlegen. - LLM-API-Schlüssel, Zugriffstoken und vertrauliche Daten niemals ins Repository committen. -- Alle 10 Invarianten (`INV-COMA-01` bis `INV-COMA-10`) müssen erfüllt bleiben. +- Änderungen an beschriebenem Verhalten oder Grenzen in der passenden öffentlichen Dokumentation erläutern. diff --git a/KONZEPT.md b/KONZEPT.md index 3ffcf5b..860fa24 100644 --- a/KONZEPT.md +++ b/KONZEPT.md @@ -1,217 +1,112 @@ # COMA — COMmunication for Autonomous Subagents -> Modul-Konzept. Beschlossen von Lukas Geiger am 2026-07-26, erarbeitet in Session -> „OPUS WORKSTATION". Status: **Modul gebaut & erweitert** (`coma` 0.2.1, 2026-08-20) — die -> Spawn-Schicht ist aus den drei bestehenden Implementierungen extrahiert, 243 Tests -> laufen ohne Prozessstart, Claude, Codex und Agy sind verifiziert, Kimi liegt als Gerüst vor. -> Referenzimplementierung (`.bat`) existiert weiter und bleibt lokal. -> Siehe `README.md`, „Offen" unten und den Ergebnisbericht -> `_agentjobs/OUT/coma-modul-bauen.result.md`. +> Konzept und Abgrenzung. Grundentscheidungen stammen vom 2026-07-26; historische +> Stände aus 2026-08 sind als damalige Beobachtungen gekennzeichnet. Dieses Dokument +> wurde am 2026-10-11 mit dem aktuellen Umfang abgeglichen. COMA 0.3.2 bleibt eingefroren. +> Aktuelle Nutzung: README.md und README_de.md; Sicherheits- und Meldewege: SECURITY.md; +> offene Arbeit: TODO.md. ## Was COMA ist -Die **Lebenszyklus-Schicht** für Agenten: Wie entsteht ein Agent als eigener Prozess, -und wie bleibt man mit ihm in Kontakt, solange er läuft? +COMA ist die Lebenszyklus-Schicht für Agentenprozesse: Sie startet konfigurierte +CLI-Prozesse und stellt Datei- und Polling-Schnittstellen bereit, über die ein +aufrufendes System Aufträge und Ergebnisse austauschen kann. -Genau eine Verantwortung. COMA sperrt nichts, verwaltet keine Rechte und hält kein -Gedächtnis. - -| Schicht | Frage | Zuständig | +| Zuständigkeit | Aufgabe | System | |---|---|---| -| **Lebenszyklus** | Wie entsteht ein Agent, wie rede ich mit ihm? | **COMA** | -| Anspruch | Wer darf was anfassen? | `team-lock` → `lock-master` → Roshambo | -| Gedächtnis | Wurde das schon versucht, wie ging es aus? | Roshambo | - -Die Verben trennen sauber: COMA spricht `spawn`, `send`, `poll`, `result`. -Roshambo-MCP spricht `claim`, `release`, `remember`, `recall`, `decide`, `status`. -Keine Überschneidung — hätten zwei Systeme dieselbe Aufgabe, überlappte ihr Vokabular. - -## Warum es COMA braucht — der belegte Anlass - -In einer **Remote-Control-Session** reicht Claude Code `--dangerously-skip-permissions` -nicht an den Remote-Client durch. Belegt durch die offenen Issues -[#71518](https://github.com/anthropics/claude-code/issues/71518) und -[#29214](https://github.com/anthropics/claude-code/issues/29214). - -Folge: Jeder Tool-Aufruf fragt nach — auch bei Subagenten. Ist niemand am Rechner, -**stehen sie still**. Am 2026-07-26 real passiert: zwei Agenten warteten stundenlang. - -Die Lösung ist nicht, mehr Regeln in eine Allowlist zu schreiben (das erzeugt nur -Klick-Ermüdung und eine Liste, die Zustimmung behauptet, die es nie gab), sondern den -Agenten **gar nicht erst in der RC-Session leben zu lassen**: ein eigener lokaler -Prozess, Kommunikation über das Dateisystem. - -**Verifiziert am 2026-07-26:** Selbsttest aus einer laufenden RC-Session heraus -gestartet — Exit 0, keine einzige Berechtigungsabfrage. Danach ein echter Auftrag -(26 min, Opus) vollständig durchgelaufen, ohne dass der Nutzer etwas klicken musste. - -## Warum eigenes Modul - -- **llmauto** würde COMA importieren (es ist heute claude-only; die Multi-CLI-Fähigkeit - kommt aus COMA). -- **swarm-ai** würde COMA importieren (spawnt heute selbst per `subprocess`). -- **Roshambo** würde COMA importieren — es koordiniert Agenten, erzeugt aber keine. - -Drei Konsumenten aus drei Richtungen. Läge COMA in einem davon, müssten die anderen -zwei davon abhängen. - -## Der entscheidende Trennungsgrund: Offline - -Roshambo hängt an CockroachDB Cloud und AWS Bedrock. COMA arbeitet mit Dateien und -Prozessen — **ohne Konto, ohne Netz, ohne Cluster**. - -Fällt die Cloud aus, muss der lokale Agentenbetrieb weiterlaufen. Ein Koordinator, -dessen Prozess-Substrat am selben Netz hängt wie er selbst, hat keinen Rückfallweg. -COMA ist deshalb das Substrat, auf dem Roshambo aufsetzt — nicht sein Konkurrent. - -**`ellmos-agent-bridge` ist ebenfalls kein Konkurrent und kein künftiger -COMA-Importeur** — es verwaltet Partner-Metadaten (Fähigkeiten, Kosten, -Erreichbarkeit, Konfigurationsdateien) und trifft Empfehlungen, startet aber -nichts: im ganzen Paket kein einziger `subprocess`-Aufruf. Belegt in -`_agentjobs/OUT/coma-agentbridge-grenze.result.md`. Entsteht später eine Kopplung, -ist die einzig saubere Richtung agent-bridge → COMA, nie umgekehrt. - -## Grenze: was Modul ist und was lokal bleibt - -Damit das Modul nicht mit einer Maschine verwachsen geboren wird: - -**Modul (allgemein, veröffentlichbar):** -- Das COMA-Protokoll (Verzeichnis- und Dateikonvention, siehe unten) -- Der Statusschreiber (`coma/status.py`) -- Die Spawn-Schicht mit **CLI-Adaptern**: claude, codex, agy, kimi — der Unterschied - zwischen ihnen ist ein Kommando-Template plus Flags. Diese Adapter werden **aus - bestehendem Code extrahiert** (`llmauto/core/runner.py`, `swarm-ai/tools/runner.py`, - das Dungeon-Skript, `START-LOCAL-AGENT.bat`), nicht neu entworfen — sonst entsteht - eine vierte Parallelimplementierung statt einer Konsolidierung. -- Poll-/Lese-Hilfen für Orchestratoren - -**Lokal (Lukas-spezifisch, bleibt im `_control-center`):** -- `_control-center/_agentjobs/` — die konkreten Job-Verzeichnisse -- `START-LOCAL-AGENT.bat` — die Startschale, die aus Remote Control herausführt - -Die `.bat` ist Umgehung eines Client-Bugs, keine allgemeine Fähigkeit. Sie gehört nicht -ins Modul. - -## Protokoll: ein Schreiber je Datei - -``` -IN/ .md Auftrag (Freitext-Markdown) -OUT/ .result.md Ergebnis - coma..json Status — nur der Runner schreibt - coma..from-agent.jsonl Fortschritt — nur der Agent schreibt - coma..to-agent.jsonl Nachrichten — nur der Orchestrator schreibt - coma..console.log stdout/stderr des Laufs -DONE/ .md erledigter Auftrag -``` - -**Ein Schreiber je Datei — kein Locking nötig, Kollision strukturell unmöglich.** -Gelesen werden darf von allen. Das ist keine Vorsichtsmaßnahme, sondern eine Lektion: -Eine geteilte Logdatei in OneDrive hat schon einmal zu Konfliktkopien geführt -(Ticket `T-20260621-44`, `_TICKETS/_logs/INTAKE-TRIAGE-LOG.txt`, seitdem deprecated). - -`.jsonl` für die Kanäle, weil Anhängen atomar ist — ein Schreiber muss nicht erst -lesen, parsen und neu schreiben. - -Bei mehreren Subagenten kommt eine zentrale Registry dazu (`coma-reg.json`, nur der -Operator schreibt) plus je Agent ein eigenes Status-JSON — das Muster aus -`swarm-ai/experiments/dungeon/elephant_path_treasure_hunt_live.py` (`live_.json` -je Agent + `experiment_live.json` zentral). - -## Harte Lektionen aus der Referenzimplementierung - -**1. Der `-p`-Prompt bleibt kurz und zeichenarm.** Lauf 1 des Selbsttests starb -**still** — kein Ergebnis, Status blieb auf `running`, Fenster weg. Ursache: JSON mit -`\"` im Prompt. **CMD kennt keine Backslash-Escapes**, der Befehl zerriss. Alle -Anweisungen gehören in die Auftragsdatei; der Prompt zeigt nur darauf. (Dieselbe Regel -gilt im Ökosystem bereits für `agy` und `codex`.) - -**2. Keine eingebetteten Interpreter-Einzeiler in der Startschale** — gleiches -Quoting-Problem. Statusschreiben liegt deshalb in einer eigenen Datei. - -**3. Immer `> log 2>&1`.** Ein stiller Tod darf nicht möglich sein. - -**4. `--permission-mode dontAsk` ist für unbeaufsichtigte Läufe die bessere Wahl als -Bypass** (Muster aus swarm-ai): Es fragt nie, sondern **verweigert**. Zusammen mit einer -expliziten Werkzeugliste kann ein Agent damit strukturell nicht hängenbleiben. Bypass -kann in Sonderfällen weiterhin nachfragen. „Verweigert und meldet das" ist besser als -„wartet auf einen Klick, den niemand gibt". - -**5. `CLAUDECODE` aus der Umgebung entfernen** ist in swarm-ai üblich, war hier aber -**nicht nötig** — der Bypass wirkte auch ohne. Ob das Leeren überhaupt greift, ist -ungeklärt: Der Testagent maß `CLAUDECODE=1` innerhalb seines eigenen Bash-Aufrufs, und -Claude Code setzt die Variable für seine eigenen Subprozesse selbst. Er hat damit nicht -das geerbte Environment gemessen. - -## Gegen eine Schnittstelle programmieren, nicht gegen lock-master - -COMA ruft Claims über eine schmale Schnittstelle (`claim` / `release` / `status`) auf, -nicht gegen ein konkretes Modul. Dann ist der spätere Wechsel ein Zeilenwechsel im -Stack-Manifest statt eines Umbaus: - -- `comalock` = COMA + lock-master (lokal, offline) -- `comaroshambo` = COMA + Roshambo (verteilt, Cloud) - -## Herkunft - -Referenzimplementierung entstanden am 2026-07-26 unter -`_control-center/_agentjobs/` + `START-LOCAL-AGENT.bat`; Protokoll dort in `README.md`. -Muster für Spawn und Live-Status aus `swarm-ai`, Claim-Semantik aus -`swarm-ai/tools/team_lock.py` (wird eigenes Modul `team-lock`). - -## Not-Aus: WorkflowHooker gehört dazu, nicht daneben [U 2026-07-26] - -Der Kanal `to-agent.jsonl` ist **kein Komfortmerkmal, sondern das fehlende Sicherheitsmerkmal**. -Ein Modul, dessen Zweck „läuft unbeaufsichtigt mit umgangener Berechtigungsabfrage" ist, braucht -einen Abbruchweg. - -**Selbstprüfung an Prüfpunkten genügt dafür nicht.** Sie greift nur, wenn der Agent einen -Prüfpunkt erreicht — in einer Schleife oder einem langen Aufruf kommt er nie an. **Nur ein Hook -kann tatsächlich stoppen**, und nur `PreToolUse` kann einen Aufruf blockieren. - -Das passt zur eigenen Regel von WorkflowHooker: „`PreToolUse` nur für **echte Blocker** — -niemals für Hinweise" (gemessen 287 ms je Tool-Aufruf). Ein Not-Aus ist der legitime Fall -dieser Regel, nicht ihre Ausnahme. Für Hinweise ohne Dringlichkeit bleibt `PostToolUse` mit -enger Bedingung (nur bei geänderter Datei-Mtime) oder die Selbstprüfung. - -**Auslieferungsentscheidung:** COMA liefert WorkflowHooker als **Nachlader** mit — nicht als -harte Abhängigkeit, aber mit klarer Empfehlung. Begründung: Nutzer, die nur ein oder zwei -Module übernehmen, bekommen sonst ein Werkzeug für unbeaufsichtigte Läufe **ohne Not-Aus**. -COMA allein ist lauffähig; ohne Hooker fehlt aber die Möglichkeit, einen laufenden Agenten -von außen zu stoppen. Das gehört in die README, nicht ins Kleingedruckte. - -Verwandt: WorkflowHooker plant bereits einen `TimeInjector` („Timebeat + ungelesene -Nachrichten") — der Zustellweg ist dort konzeptionell vorgesehen, Status heute -„Gerüst angelegt, nicht implementiert". - -## Offen - -Stand 2026-08-01, nach dem Bau des Moduls (`coma` 0.2.0, Ergebnisbericht: -`_agentjobs/OUT/coma-modul-bauen.result.md`). - -- [x] `ellmos-module.v2.json` — liegt vor, mit Adapter-Abschnitt und Stand je Adapter -- [x] Lock-Schnittstelle definieren — `coma/locks.py`: `LockBackend` (Protocol - mit `claim`/`release`/`status`), `NullLock`, Kontextmanager `claimed()`. - **Nur definiert**, nicht implementiert; kein Import von `lock-master`, - `team-lock` oder Roshambo (per Test abgesichert) -- [x] CLI-Adapter über claude hinaus — `codex` und `agy` sind live verifiziert - (`verified = True`); `kimi` liegt als **Gerüst** vor (`verified = False`, - der Spawner verweigert ihn ohne ausdrückliches `allow_unverified=True`). -- [ ] Zentrale Registry `coma-reg.json` für Mehr-Agenten-Betrieb — nicht gebaut. - Der Spawner kann bereits nebenläufig starten (`run_many`, `ProcessHandle`, - `wait_all`), aber es gibt kein zentrales Verzeichnis über mehrere Agenten -- [x] Entscheidung: öffentlich (Sichtbarkeit `public`) — MIT-Lizenz gesetzt am - 2026-07-26. Begründung: COMA startet lokale Prozesse und schreibt - Dateien, hat keine Netzfläche; eine netzauslösende Copyleft-Klausel wie - AGPL §13 würde hier nie greifen. Details: - `_agentjobs/OUT/coma-lizenz-und-metarepo.result.md`. **Tatsächliche - Veröffentlichung (Push, OneDrive-Spiegelung, Katalog-Eintrag) steht - weiterhin aus** — bewusst nicht Teil dieses Laufs -- [ ] `llmauto` und `swarm-ai` auf COMA umhängen — ausdrücklich **nicht** Teil - des Bau-Auftrags; eigener, späterer Schritt. Beide bauen heute weiterhin - ihre eigenen `claude`-Aufrufe -- [ ] Plan-D-Deploy: Quellkopie nach `.CONTROL/coma/` in OneDrive — kommt separat, - jetzt, da das Modul steht -- [ ] Widerspruch in der Referenzimplementierung: `_agentjobs/README.md:25` - dokumentiert `OUT/.status` mit Inhalt `"running" -> "done "`. - Real geschrieben wird `OUT/coma..json`. Das Modul folgt der `.bat` - und diesem Konzept; die README ist zu korrigieren +| Lebenszyklus | Prozesse starten, Status und Ergebnisse bereitstellen | COMA | +| Autorisierung und Koordination | Zugriffsentscheidungen und Arbeitszuweisung | Aufrufendes System | +| Gedächtnis und Verlauf | Vorherige Versuche und Ergebnisse bewahren | Aufrufendes System | + +COMA erzwingt keine Berechtigungen, verwaltet keine zentrale Agenten-Registry und +speichert kein dauerhaftes Gedächtnis. Integrationen bleiben optional; sie erzeugen +keine harte Abhängigkeit zwischen COMA und anderen Projekten. + +## Prozess-, Netzwerk- und Berechtigungsgrenzen + +COMA verwendet konfigurierte lokale Dateien und startet Subprozesse. Es stellt selbst +keinen Netzwerkdienst bereit. Gestartete Agenten-CLIs können ihre Anbieter oder andere +Dienste kontaktieren. Sie erben die Rechte und die Umgebung des startenden Prozesses. +COMA stellt weder eine Sandbox noch eine Netzsperre, einen Air-Gap oder eine +Berechtigungsgrenze bereit. + +Die Adapter bauen CLI-Argumente. Die jeweilige Agenten-CLI bestimmt, wie sie diese +Argumente durchsetzt. In der konfigurierten Claude-Standardvariante setzt COMA +`dontAsk` mit den Werkzeugen Read, Edit, Write, Bash, Glob und Grep; das separate +`read_only`-Preset beschränkt die Werkzeugliste auf Read, Glob und Grep. MCP ist in +der Standardvariante aus. `bat_compat` verwendet `bypassPermissions` und kann +umfassendere Ausführungsmöglichkeiten einschließlich MCP zulassen. Beim Codex-Adapter +ist `read-only` der Standard; `write` wird als `workspace-write` abgebildet. +`danger-full-access` ist ausdrücklich konfigurierbar. Diese CLI-Profile ersetzen +keine Prozess- oder Netzwerksandbox. + +Der Session-Probe startet die konfigurierte CLI mit Timeout und versucht die +plattformabhängige Bereinigung bestmöglich. Die Beendigung des gesamten Prozessbaums +ist nicht garantiert. Der bestehende Probe-Test startet für seine Kontrollprüfung +einen lokalen Python-Prozess und prüft den erwarteten Token-Rückgabewert; er ist kein +Live-Test eines Anbieter-CLIs. + +## Datei- und Kanalprotokoll + +| Datei | Protokollrolle | +|---|---| +| `IN/.md` | Auftrag | +| `OUT/.result.md` | Ergebnis | +| `coma..json` | Status; vom Runner geschrieben | +| `coma..from-agent.jsonl` | Fortschritt; vom Agenten geschrieben | +| `coma..to-agent.jsonl` | Nachrichten; vom Orchestrator geschrieben | +| `coma..console.log` | Laufzeit-Ausgabe | +| `DONE/.md` | Abgeschlossener Auftrag | + +Aufrufende Systeme müssen pro Kanal einen Schreiber zuordnen. Optionale Rollenprüfungen +sind weder OS-Sperren noch Identitätsprüfungen; mehrere Prozesse mit derselben Rolle +werden nicht gegenseitig ausgeschlossen. Aufrufende Systeme koordinieren konkurrierende +Schreibvorgänge selbst. JSONL ermöglicht zeilenorientierte Anhänge, garantiert aber +keine prozessübergreifende Synchronisierung für alle Dateisysteme. + +## Kimi-Adapterstatus + +Der Kimi-Adapter bleibt unbestätigt. Die Ausführung über Spawner und Session erfordert +ein ausdrückliches Opt-in; direkte KimiAdapter- oder Probe-Argument-Aufrufe setzen +diese Grenze nicht selbst durch. Der frühere Kompatibilitätscheck mit Version 0.31.0 +bezog sich auf das inzwischen archivierte legacy kimi-cli (2026-09-23). Er belegt keine +Kompatibilität mit dem Nachfolger kimi-code. Eine aktuelle Nachfolgerprüfung bleibt +TASK-COMA-01 in TODO.md; bis dahin werden weder aktuelle Live-Unterstützung noch +Kompatibilität behauptet. + +## Historischer Anlass und Entwurfsentscheidungen + +Am 2026-07-26 wurde in einer Remote-Control-Arbeitssitzung beobachtet, dass ein +konkreter Agentenlauf auf eine Freigabe wartete. Ein damals gestarteter lokaler +Selbsttest und ein einzelner Auftrag liefen durch. Das ist eine historische lokale +Beobachtung, kein Nachweis für aktuelle Anbieter-Kompatibilität und keine Aussage, +dass COMA Freigaben umgeht oder Agenten unbeaufsichtigt sicher macht. Früher zitierte +Issue- und Laufzeitbeobachtungen werden hier nicht als aktuelle Anbieterzustände +ausgegeben. + +Die Trennung als eigenes Modul sollte den Prozesslebenszyklus von Orchestrierung, +Rechteverwaltung und Erinnerung trennen. COMA kann von anderen Projekten optional +genutzt werden; für die konkrete Nutzerliste und ihre Integrationsstellen siehe +README.md und README_de.md. + +Ein Snapshot vom 2026-08-20 bezeichnete Version 0.2.1 als erweitert, notierte damals +243 Tests sowie damalige Claude-, Codex- und AGY-Adapterchecks. Diese datierten Zahlen +und Checks sind historische Angaben, keine aktuellen Testzahlen, Zertifizierungen oder +Live-Anbieterprüfungen. + +## Historische Not-Aus-Diskussion + +Eine frühe Entwurfsnotiz vom 2026-07-26 schlug einen externen Workflow-Hook als +zusätzlichen Abbruchweg vor. COMA liefert WorkflowHooker nicht mit und integriert ihn +nicht. Diese historische Empfehlung ist kein Bestandteil des COMA-Protokolls und keine +Sicherheitsgarantie. + +## Lizenzhinweis und aktueller Arbeitsstand + +Das COMA-Projekt wird unter der MIT-Lizenz bereitgestellt. Ob gesetzliche Regeln wie +§ 521 BGB auf ein konkretes Rechtsverhältnis anwendbar sind, hängt vom Rechtsverhältnis +und dem anwendbaren Recht ab; dieses Dokument gibt keine pauschale Haftungsfreistellung. + +TODO.md ist die aktuelle Aufgabenübersicht. Historische Arbeitsstände und +Implementierungsentscheidungen werden dort nicht als gegenwärtige Runtime-Garantien +fortgeschrieben. diff --git a/MARKETING-LOG.txt b/MARKETING-LOG.txt deleted file mode 100644 index fa446e0..0000000 --- a/MARKETING-LOG.txt +++ /dev/null @@ -1,183 +0,0 @@ -# MARKETING-LOG — COMA (Command & Communication for Autonomous Agents) -# Stand: 2026-10-04 (Vorige Stände: Stand: 2026-10-01, Stand: 2026-09-28, Stand: 2026-09-24, Stand: 2026-09-19, Stand: 2026-09-14) | Repository: ellmos-ai/coma | Lizenz: MIT - -## 1. Positionierung & Kernnutzen (Value Proposition) - -COMA (`coma`) ist die schlanke, dateibasierte Lebenszyklus- und Entkopplungsschicht für autonome KI-Agenten. -Es löst das fundamentale Problem interaktiver Agenten-Sessions (wie z. B. Claude Code CLI, OpenAI Codex CLI, Google Antigravity / AGY CLI und Kimi Code CLI): -Wenn Agenten in Remote-Control- oder interaktiven Terminalsitzungen ausgeführt werden, blockieren Berechtigungsabfragen -(`--dangerously-skip-permissions`, `dontAsk` etc.) häufig bei unbesetzter Konsole oder hinterlassen hängende Prozesse. - -COMA startet den Agenten als eigenständigen, entkoppelten Betriebssystem-Prozess außerhalb der interaktiven Session und -etabliert einen kollisionsfreien Dateisystem-Kanal (`IN/`, `OUT/`, `DONE/`). - -- **Zero-Dependency:** 100% Python Standard-Bibliothek, null externe Pakete zur Laufzeit. -- **Zero-Network-Egress:** Keine Netzwerkverbindungen, keine Cloud-Dienste, keine Kontopflicht, 100% lokal. -- **Single-Writer-Protokoll:** Jede Datei im Auftragsbaum besitzt genau einen autorisierten Schreiber — strukturelle Vermeidung von Race Conditions und Lock-Konflikten. -- **Prozessfreie Kommandokonstruktion:** `--dry-run`, `cmd` und `build_session_plan()` erzeugen verifizierte argv-Vektoren ohne Prozessstart und ohne Tokenverbrauch. - ---- - -## 2. Ziel-Personas (Target Audience) - -1. **Autonomous Agent Architects & Framework Developers** - - Entwickler, die Multi-Agenten-Pipelines und Swarm-Strukturen aufsetzen. - - Suchen eine robuste, dateibasierte Entkopplung zwischen Orchestrator-Session und ausführendem Worker-Prozess. - -2. **Local-First & Privacy-Conscious AI Engineers** - - Teams mit strikten Air-Gapped-, DSGVO- oder On-Prem-Vorgaben, die keine externen Daemon-Dienste oder Cloud-Orchestratoren zulassen. - - Profitieren vom garantierten Zero-Network-Egress und auditierbaren Dateisystem-Kanälen. - -3. **Claude Code / Codex / Antigravity CLI Power Users** - - Anwender, die Hintergrund-Jobs unbeaufsichtigt und headless ablaufen lassen möchten, ohne dass interaktive Prompts den Ablauf blockieren. - - Nutzen vorgefertigte CLI-Adapter (`ClaudeAdapter`, `CodexAdapter`, `AntigravityAdapter`, `KimiAdapter`). - -4. **Edge & Headless Automation Operators** - - Betreiber von Scheduled Tasks, Cronjobs oder lokalen Service-Pipelines, die strukturierte Statusmeldungen (`coma..json`), Konsolen-Logs (`console.log`) und Fortschritts-Streams (`from-agent.jsonl`) benötigen. - ---- - -## 3. Discoverability & SEO-Keywords - -`autonomous-agents`, `agent-lifecycle`, `subprocess-spawner`, `claude-code`, `codex-cli`, `antigravity-cli`, `kimi-cli`, -`multi-agent`, `session-decoupling`, `job-board`, `file-based-queue`, `local-first`, `zero-dependency`, `zero-egress`, -`process-isolation`, `python-stdlib`, `ellmos-ai`, `open-bricks` - ---- - -## 4. Verzeichnis- & Katalog-Empfehlungen (Directory Submissions) - -Folgende Verzeichnisse und Community-Sammlungen eignen sich für eine Aufnahme von COMA: - -| Verzeichnis / Liste | Kategorie | Begründung / Relevanz | -|---|---|---| -| **Awesome-AI-Agents** (`e2b-dev/awesome-ai-agents`) | Agent Infrastructure / Tools | Etabliertes Referenzverzeichnis für Agenten-Entwicklung; COMA füllt die Lücke des entkoppelten Subprozess-Spawners. | -| **Awesome-Local-AI** | Local Infrastructure | Zeigt lokale, serverlose Orchestrierung ohne externe Cloud-Abhängigkeiten. | -| **Awesome-Claude** | Developer Tools / Extensions | Direkter Support für Claude Code CLI via `ClaudeAdapter` mit Berechtigungs-Flag-Übersetzung. | -| **LibHunt / Python** | Task Queue / Process Automation | Listet Python-Pakete; COMA bietet Zero-Dependency JobBoard-Alternative zu Celery/RQ für lokale Agenten. | -| **PyPI (Python Package Index)** | Package Release | Bereitstellung als `pip install coma-agents` oder `ellmos-coma` nach Erreichen von v0.3.x/v1.0.0. | - ---- - -## 5. Ökosystem-Integration & Geschwister-Werkzeuge - -COMA ist integraler Bestandteil der `ellmos-ai` und `open-bricks` Infrastruktur: - -- **`ellmos-ai/policy-registry`**: Liefert Governance-Regeln und Rollendefinitionen, die als Prompts über `IN/.md` übergeben werden. -- **`ellmos-ai/lock-master`**: Verwaltet Projekt- und Dateisperren (Roshambo-Schicht) getrennt vom Prozesslebenszyklus in COMA. -- **`ellmos-ai/rinnsal`**: Nutzt COMA als lokalen Ausführungskanal für autonome Hintergrundaufgaben und SQLite-gepufferte Kontextübergabe. -- **`ellmos-ai/condition-gates`**: Validiert Vorbedingungen und Evidenzen, bevor ein COMA-Job gestartet oder als fertig markiert wird. -- **`ellmos-ai/workflowhooker`**: Löst COMA-Job-Starts ereignisgesteuert über Dateisystem- oder Webhook-Signale aus. -- **`ellmos-ai/memoryhooker`**: Sichert Erfahrungen und Lessons Learned nach erfolgreichem Abschluss eines COMA-Jobs. -- **`dev-bricks/safe-start-for-codex`**: Führt Umgebungs- und Health-Checks vor dem Start von COMA-Agenten durch. - ---- - -## 6. Konkrete Marketing- & Design-Empfehlungen (Roadmap) - -1. **Asciinema Terminal Screencast:** - - Aufnahme eines kurzen (30–45s) Terminal-Demos: `coma submit`, `coma run --dry-run`, `coma run`, `coma status` und `coma result`. - - Einbindung als SVG/GIF in `README.md` und `README_de.md`. - -2. **PyPI Package Publication (`coma-agents`):** - - Sobald das Modul-Gate freigegeben ist, Paketierung über `build` und Veröffentlichung auf PyPI. - - Ermöglicht `pip install coma-agents` für weltweite Nutzbarkeit. - -3. **Multi-Agent MCP Bridge:** - - Bereitstellung eines schlanken MCP-Tools (`coma_submit`, `coma_poll`, `coma_result`), damit Claude Desktop, Cursor und Antigravity COMA-Hintergrundjobs nativ ansteuern können. - -4. **Dual-Language Interaktive Quickstarts:** - - Ausbau von interaktiven Python-Notebooks / Beispielen unter `examples/` für Standard-Agent-Workflows (Refactoring, Code-Review, Test-Generierung). - ---- - -## 7. Release 0.3.1 Highlights (Pfad A — Quality, Stale Automation & Multi-Host Defense Audit 2026-09-14) - -- **CI Workflow & Concurrency Hardening:** Deployed `.github/workflows/tests.yml` with multi-OS (Ubuntu, Windows, macOS) and multi-Python (3.10–3.13) matrix, `timeout-minutes: 15` runaway guardrail, and `cancel-in-progress: true` concurrency group cancellation. -- **Stale Issues & PRs Lifecycle Automation:** Added `.github/workflows/stale.yml` using `actions/stale@v9` with `timeout-minutes: 10`, daily scheduled cron (`30 1 * * *`), and least-privilege permissions (`issues: write`, `pull-requests: write`). -- **Welcome Workflow Deployment:** Added `.github/workflows/welcome.yml` with `timeout-minutes: 5` execution bounds and welcoming guidance for community issues and PRs. -- **Multi-Host & Conflict Hardening:** Extended `.gitignore` against cross-system sync artifacts across multi-host environments (`* (Kopie)*`, `* (Copy)*`, `*conflicted copy*`, `*-WORKSTATION*`, `*-ASUS*`, `*-LAPTOP*`, `*-Mac Studio*`), canonical lock indicators (`LOCK`, `LOCK.*`, `uv.lock`), and coverage/cache directories. -- **PEP 621 Standard Compliance:** Registered `"LLM Ready"` context URL pointing to `llms.txt` and configured standard Pytest options (`addopts = "-ra -v"`) in `pyproject.toml`. -- **Version Harmonization:** Synchronized release version to `0.3.1` across package manifests, module definition, and documentation. -- **Automated Contract Tests:** Expanded `tests/test_metadata.py` with contract tests verifying CI timeouts, stale workflow configuration, multi-host gitignore defense, PEP 621 metadata, and marketing log recency. - ---- - -## 8. Release 0.3.2 Highlights (Pfad B — Marketing, Discoverability, Visual Architecture & SBOM Re-Certification 2026-09-19) - -- **18-Point Quick Navigation Parity:** Introduced identical 18-point numbered navigation structures in both `README.md` and `README_de.md` with 100% reciprocal HTML anchors (``). -- **Target Personas & Search Intent Mapping:** Formulated 4 dedicated personas (`[PERSONA-01]` Autonomous Agent Swarm Architects, `[PERSONA-02]` Local-First Sovereign Developers, `[PERSONA-03]` Remote-Control Headless DevOps, `[PERSONA-04]` Enterprise Security Auditors) and mapped high-intent search queries in English and German. -- **10-Dimension Comparative Matrix:** Benchmarked COMA against Celery/RQ, Temporal/Camunda, raw Python subprocesses, and cloud agent frameworks across 10 architectural invariants (`INV-COMA-01` to `INV-COMA-10`). -- **Dual Mermaid Visualizations:** Added 5-layer system architecture topology flowchart (`flowchart TD`) and sequence diagram (`sequenceDiagram`) with zero trailing semicolons and strict label escaping. -- **Level 1 SBOM & Unprivileged Certification:** Updated `THIRD_PARTY_LICENSES.md` to Stand 2026-09-19 with complete SPDX package inventory, 10-invariant compliance matrix, and `RunAsInvoker` non-elevation certification. -- **Statutory Notice (§ 521 BGB):** Embedded statutory liability limitation notice for gratuitous open-source software under German Law. -- **GitHub Discoverability:** Expanded topics to full 20/20 capacity (`agent-lifecycle`, `agent-orchestration`, `ai-agents`, `antigravity`, `claude-code`, `cli`, `codex`, `job-board`, `local-first`, `multi-agent`, `offline-first`, `open-bricks`, `process-isolation`, `python`, `session-decoupling`, `spawn`, `status-polling`, `subagents`, `zero-dependencies`, `zero-egress`) and verified homepage URL via GitHub CLI. -- **Contract Test Suite Expansion:** Added automated tests in `tests/test_metadata.py` verifying navigation parity, persona definitions, comparative matrix, § 521 BGB disclaimer, and SBOM recency (284 passed tests | 100% green). - ---- - -## 9. Pfad A Maintenance & Hygiene Audit (Stand 2026-09-24) - -- **Formal NOTICE Attribution:** Added root `NOTICE` file establishing open-source attribution for Lukas Geiger / `ellmos-ai` under the `open-bricks` umbrella, and registered it in `pyproject.toml` `license-files` and PEP 621 `[project.urls]` Notice URL. -- **Canonical Lock System & Multi-Host Gitignore Hardening:** Hardened `.gitignore` against canonical multi-agent locks (`LOCK.user.*`, `LOCK.until.*`, `LOCK.condition.*`, `.automation-lock`, `!package-lock.json`), multi-host tokens (`*-MacBook*`), and temporary pytest cache artifacts (`.pytest_temp/`). -- **PEP 621 & Pytest Configuration Standards:** Standardized `minversion = "7.0"` and `norecursedirs` in `pyproject.toml`. -- **Security SLA Policy Hardening:** Updated `SECURITY.md` with explicit 48-hour acknowledgment SLA, 5-business-day triage commitment, and security contacts (`security@ellmos.ai`, `security@open-bricks.org`, `lukas@open-bricks.org`). -- **Third-Party Inventory & SBOM Re-Audit:** Updated `THIRD_PARTY_LICENSES.md` to Stand 2026-09-24, validating Zero External Runtime Dependencies (`INV-COMA-02`) and cross-referencing `NOTICE`. -- **Automated Contract Tests:** Expanded `tests/test_metadata.py` with 6 new contract tests covering NOTICE presence, security SLA contacts, canonical lock patterns, and metadata parity (290 tests | 100% green). - ---- - -## 10. Pfad B Discoverability, Visual Architecture & Level 1 SBOM Audit (Stand 2026-09-28) - -- **18-Point Bilingual Navigation Parity & Dual Reciprocal Anchors:** Integrated reciprocal dual HTML anchors (``..`` aliases) across all 18 numbered sections in both `README.md` and `README_de.md`, providing permanent universal deep-links for documentation, RAG engines, and external tooling. Fixed umlaut encoding defect in section 15 anchors. -- **Level 1 SBOM Plain-Text Companion (`THIRD_PARTY_LICENSES.txt`):** Created full plain-text companion file documenting zero-copyleft guarantee, `RunAsInvoker` non-elevation certification, complete runtime/build dependency matrices, and 10-invariant compliance cross-reference table (`INV-COMA-01`..`INV-COMA-10`). -- **PEP 621 Metadata Saturation & URL Registration:** Saturated `pyproject.toml` package keywords with full 20/20 GitHub repository topics (`agent-lifecycle`, `agent-orchestration`, `ai-agents`, `antigravity`, `backend-agnostic`, `chat-runtime`, `claude-code`, `cli`, `codex`, `job-board`, `local-first`, `messaging`, `multi-agent`, `offline-first`, `open-bricks`, `process-isolation`, `python`, `session-decoupling`, `spawn`, `status-polling`, `subagents`, `zero-dependencies`, `zero-egress`). Registered `"Third-Party Licenses (Text)"` in `[project.urls]` and added `THIRD_PARTY_LICENSES.txt` to PEP 621 `license-files`. -- **Pytest Isolation & Multi-Host Defense:** Hardened `pyproject.toml` with `addopts = "-ra -v --basetemp=.pytest_temp"` and `.hypothesis` in `norecursedirs`. Extended `.gitignore` with `*-IDEAPAD*`, `*-IDEAPAD-GEI*`, `.pytest_tmp*/`, `Desktop.ini`, and `desktop.ini`. -- **Shields.io Badge Synchronization:** Synchronized Shields.io badges across `README.md` and `README_de.md` (`Verified: 2026-09-28` / `Geprüft: 2026-09-28`, `Third-Party Licenses (Text)`). -- **RAG Context & License Attribution Parity:** Updated `llms.txt` context index (`Last-checked: 2026-09-28`) and root `NOTICE` attribution file with explicit cross-references to `THIRD_PARTY_LICENSES.txt`. -- **Automated Contract Tests:** Expanded `tests/test_metadata.py` with dedicated contract tests verifying `sec-01`..`sec-18` anchor parity, `THIRD_PARTY_LICENSES.txt` plain-text companion invariants, PEP 621 keywords saturation, and marketing log recency. - ---- - -## 11. Pfad A Maintenance & Hygiene Audit (Stand 2026-10-01) - -- **CI Lifecycle Workflows Deployment:** Added `.github/workflows/auto-assign.yml` (least-privilege PR triage with `actions/github-script@v7`, `timeout-minutes: 5`, and concurrency cancellation) and `.github/workflows/label-sync.yml` (`EndBug/label-sync@v2`, `timeout-minutes: 5`, `issues: write`). -- **Canonical Label Configuration:** Deployed `.github/labels.yml` with 11 standard triage and prioritization labels gemäß GOVERNANCE.md §4.2. -- **Bilingual CONTRIBUTING Guidelines:** Created root `CONTRIBUTING.md` in full English and German parity documenting Quality Gates, Plan D local development setup, unprivileged `RunAsInvoker` guarantee (`INV-COMA-09`), and operational compliance across `INV-COMA-01` through `INV-COMA-10`. -- **Level 1 SBOM & Plain-Text Companion Re-Audit:** Updated `THIRD_PARTY_LICENSES.txt` and `THIRD_PARTY_LICENSES.md` to Stand 2026-10-01, verifying Zero External Runtime Dependencies (`INV-COMA-02`), Zero-Copyleft Isolation, and non-elevated user execution. -- **PEP 621 Metadata Expansion:** Registered `"Contributing"`, `"Level 1 SBOM"`, and `"Plain-Text License"` URLs in `[project.urls]` within `pyproject.toml`. Hardened pytest configuration with `.pytest_tmp*`, `.tox`, and `.turbo` in `norecursedirs`. -- **Multi-Host & Taskplan Gitignore Hardening:** Hardened `.gitignore` with `TASKPLAN_*.md`, `ehthumbs.db`, `LOCK.dev.*`, `LOCK.antigravity.*`, and `LOCK.bugsearch.*`. -- **Documentation & Context Synchronisation:** Synchronized Shields.io badges across `README.md` and `README_de.md` for `Verified: 2026-10-01` / `Geprüft: 2026-10-01`, and refreshed `llms.txt` context index (`Last-checked: 2026-10-01`). -- **Automated Contract Tests:** Expanded `tests/test_metadata.py` with dedicated tests validating CI lifecycle workflows, canonical labels, contributing guidelines, PEP 621 URLs, and SBOM recency. - ---- - -## 12. Pfad B Discoverability, Visual Architecture & Level 1 SBOM Audit (Stand 2026-10-04) - -- **Live Traffic & Clone Analytics:** - - 14-Tage-Clones: 274 Clones über 98 eindeutige Cloner (Spitzen am 2026-10-01 mit 64 Clones / 27 Uniques und 2026-09-24 mit 48 Clones / 19 Uniques). - - 14-Tage-Views: 6 Views über 4 eindeutige Besucher. - - Befund: Sehr starke Clone- und Ingestion-Aktivität von automatisierten Repräsentanten und Buildern, bei moderatem manuellem Web-Traffic. Discoverability profitiert maßgeblich von strukturierter RAG-Aufbereitung (`llms.txt`) und exzellenter Terminal-/CLI-Architektur. - -- **ASCII Vier-Sichten-Architekturtopologie (Section 2 Parität EN/DE):** - - Projektion aller 10 architektonischen und Laufzeitinvarianten (`INV-COMA-01` bis `INV-COMA-10`) in eine strukturierte 4-Sichten-Darstellung: - - *View 1 / Sicht 1:* Client-Laufzeiten, Orchestrator-Eintrittspunkte & Sitzungsplanung (`JobBoard.submit`, `JobRunner.run`, `Spawner.run`, CLI-Befehle, prozessfreie Trockenläufe `INV-COMA-04`, deterministischer Fallback `INV-COMA-05`, Starter aus `roles[]` `INV-COMA-08`). - - *View 2 / Sicht 2:* Single-Writer-Dateiprotokoll & Verzeichnis-Warteschlangen (`IN/`, `OUT/`, `DONE/`, `to-agent.jsonl`, `from-agent.jsonl`, `coma..json`, `console.log`, `result.md`, `INV-COMA-01`). - - *View 3 / Sicht 3:* COMA Kern-Lebenszyklus-Engine & Multi-Provider CLI-Adapter (100% Python Standardbibliothek `INV-COMA-02`, verifizierte Claude-, Codex- und AGY-Adapter, Fail-Closed Kimi-Sicherheit `INV-COMA-06`, begrenzte Probe-Bereinigung `INV-COMA-07`, Prozess-Isolation & RC-Immunität `INV-COMA-03`). - - *View 4 / Sicht 4:* Air-Gap Sicherheitsperimeter, unprivilegierter RunAsInvoker & Governance (Strikter Benutzermodus `INV-COMA-09`, Zero Network Egress, Zero-Copyleft MIT-Isolation, gesetzlicher Hinweis § 521 BGB Gefälligkeitsrecht, verbindliche 48h Security Response SLA `INV-COMA-10`). - -- **Level 1 SBOM Text-Companion & Re-Audit Stand 2026-10-04:** - - `THIRD_PARTY_LICENSES.txt` und `THIRD_PARTY_LICENSES.md` auf Stand 2026-10-04 re-auditiert. - - Bestätigung aller 10 Invarianten, strikter Unprivileged User Mode (`RunAsInvoker`), Zero-Copyleft Isolation Guarantee, reiner Python-Standardbibliothek-Stack (PSFL-2.0). - -- **Dokumentations-, Badge- & Test-Parität:** - - Shields.io Badges in `README.md` und `README_de.md` auf 313 bestandene Tests (`pytest-313 passed` / `pytest-313 bestanden | 100% green`) und Verifikationsstempel `Verified: 2026-10-04` / `Geprüft: 2026-10-04` synchronisiert. - - Section 13 CLI-Testbefehl auf 313 Tests aktualisiert. - - `llms.txt` Stand 2026-10-04 mit 313 Tests Baseline und Verweisen auf die Vier-Sichten-Topologie aktualisiert. - - Release Notes in `CHANGELOG.md` unter `## [Unreleased]` Stand 2026-10-04 dokumentiert. - - Version `0.3.2` strikt eingefroren per T-20260920-167562623 (0 Version-Diffs). - -- **Konkrete, nicht-automatisierte Handlungsempfehlungen (Discoverability):** - - **[REC-20261004-01] Interaktives Terminal-GIF / Asciinema-Player:** Aufnahme eines 20s Terminal-Casts für die interaktive Dokumentation (`coma run myjob --dry-run` und `coma session --provider codex`), um Konversionsraten auf GitHub zu maximieren. - - **[REC-20261004-02] PyPI Alpha Packaging (`coma-agents`):** Einreichung des minimalen Zero-Dependency-Pakets auf PyPI als `coma-agents` zur einfachen Installation via `pip install coma-agents`. - - **[REC-20261004-03] Upstream Pull Request zu Awesome-AI-Agents & Awesome-Claude:** Erstellung präziser Upstream-PRs zur Aufnahme in kuratierte Repositorien unter der Kategorie "Local-First Agent Spawner & Subprocess Lifecycle". diff --git a/README.md b/README.md index 0132eff..6d627e2 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,13 @@ **[English](README.md) | [Deutsch](README_de.md)** -[![Pytest Status](https://img.shields.io/badge/pytest-313%20passed-brightgreen.svg)](https://docs.pytest.org/) -[![Verified](https://img.shields.io/badge/verified-2026--10--04-brightgreen.svg)](MARKETING-LOG.txt) +[![Tests](https://github.com/ellmos-ai/coma/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ellmos-ai/coma/actions/workflows/tests.yml) [![Third-Party Licenses (Text)](https://img.shields.io/badge/licenses--text-Level%201%20SBOM-blue.svg)](THIRD_PARTY_LICENSES.txt) [![Version](https://img.shields.io/badge/version-0.3.2-blue.svg)](pyproject.toml) [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) -[![Dependencies](https://img.shields.io/badge/dependencies-0%20(stdlib)-brightgreen.svg)](pyproject.toml) -[![Network](https://img.shields.io/badge/network-zero--egress-success.svg)](SECURITY.md) -[![Execution](https://img.shields.io/badge/mode-RunAsInvoker-informational.svg)](THIRD_PARTY_LICENSES.md) +[![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-none-blue.svg)](pyproject.toml) [![Architecture](https://img.shields.io/badge/architecture-local--first-blue.svg)](KONZEPT.md) -[![Protocol](https://img.shields.io/badge/protocol-single--writer-informational.svg)](KONZEPT.md) +[![Protocol](https://img.shields.io/badge/protocol-file--based-informational.svg)](README.md#5-job-protocol) [![Security SLA](https://img.shields.io/badge/security-48h%20SLA-blue.svg)](SECURITY.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![LLM Ready](https://img.shields.io/badge/llms.txt-ready-blueviolet.svg)](llms.txt) @@ -29,7 +26,7 @@ ### Quick Navigation -1. [What Is COMA? & Value Proposition](#1-what-is-coma) · 2. [Primary Use Cases & Session Decoupling](#2-use-cases) · 3. [Target Personas & Discoverability](#3-target-personas--discoverability) · 4. [Quickstart & Command Line Usage](#4-quickstart) · 5. [File-Based Job Board Protocol](#5-job-protocol) · 6. [Spawner Layer & Multi-Engine CLI Adapters](#6-spawner-layer) · 7. [Interactive & Headless Session Planning](#7-interactive-and-headless-sessions) · 8. [Starters from roles[] Declarations](#8-starters-from-roles) · 9. [10-Dimension Comparative Matrix](#9-comparative-matrix-vs-alternatives) · 10. [Dual Mermaid Diagrams](#10-dual-mermaid-diagrams) · 11. [Governance & 10 Runtime Invariants](#11-governance-and-runtime-invariants) · 12. [CLI Commands Reference](#12-cli-commands) · 13. [Testing & Verification Suite](#13-testing) · 14. [Third-Party Licenses & Level 1 SBOM](#14-third-party-licenses--sbom) · 15. [Sibling Ecosystem & Integration](#15-sibling-tools--ecosystem) · 16. [Security Policy & Subprocess Isolation](#16-security) · 17. [Statutory Notice (§ 521 BGB)](#17-statutory-notice--liability-limitation) · 18. [License & Open-Source Umbrella](#18-license--umbrella) +1. [What Is COMA? & Value Proposition](#1-what-is-coma) · 2. [Primary Use Cases & Session Decoupling](#2-use-cases) · 3. [Target Personas & Discoverability](#3-target-personas--discoverability) · 4. [Quickstart & Command Line Usage](#4-quickstart) · 5. [File-Based Job Board Protocol](#5-job-protocol) · 6. [Spawner Layer & Multi-Engine CLI Adapters](#6-spawner-layer) · 7. [Interactive & Headless Session Planning](#7-interactive-and-headless-sessions) · 8. [Starters from roles[] Declarations](#8-starters-from-roles) · 9. [COMA Behavior and Boundaries](#9-coma-behavior-and-boundaries) · 10. [Dual Mermaid Diagrams](#10-dual-mermaid-diagrams) · 11. [Governance & Runtime Contracts](#11-governance-and-runtime-invariants) · 12. [CLI Commands Reference](#12-cli-commands) · 13. [Testing & Verification Suite](#13-testing) · 14. [Third-Party Licenses & Level 1 SBOM](#14-third-party-licenses--sbom) · 15. [Sibling Ecosystem & Integration](#15-sibling-tools--ecosystem) · 16. [Security Policy & Subprocess Isolation](#16-security) · 17. [Statutory Notice (§ 521 BGB)](#17-statutory-notice--liability-limitation) · 18. [License & Open-Source Umbrella](#18-license--umbrella) --- @@ -48,7 +45,7 @@ COMA is a **session-decoupled communication channel and process spawner for autonomous AI agents** (file-system based via `IN/`, `OUT/`, `DONE/`). The name stands for **Command & Communication for Autonomous Subagents**. -Single responsibility: COMA does not handle permissions, locks, or long-term agent memory. It works strictly with local files and standard OS processes—**no account required, no network services, no cluster dependencies**. Zero third-party dependencies, standard library only. +COMA coordinates work through local files and starts agent CLIs as subprocesses. COMA itself does not implement a network service or require a COMA account. A launched CLI may contact its provider or other services and may require its own account or network access. The project declares no direct Python runtime package dependencies. See [`KONZEPT.md`](KONZEPT.md) for background details, motivations, and architectural decisions. @@ -72,7 +69,7 @@ Separation of verbs: COMA uses `spawn`, `send`, `poll`, `result`. A coordinator ## 2. Primary Use Cases & Session Decoupling 1. **Decoupling from Remote Control (RC) Sessions** - In interactive remote-control sessions, CLI permission bypass flags like `--dangerously-skip-permissions` may fail to pass through to remote clients (open issues [#71518](https://github.com/anthropics/claude-code/issues/71518), [#29214](https://github.com/anthropics/claude-code/issues/29214)). COMA launches the agent as an independent OS process outside the RC session, communicating cleanly via file-system channels. + Interactive and remote-control clients can handle CLI permissions differently. COMA starts the selected CLI as a subprocess and exchanges work through filesystem channels; the provider CLI's own permissions remain in effect. 2. **Session-Independent Handoffs & Relays** Tasks can be handed off across session boundaries between agents without blocking process threads or losing context. @@ -82,48 +79,13 @@ Separation of verbs: COMA uses `spawn`, `send`, `poll`, `result`. A coordinator ### ASCII Four-View Architectural Topology -```text -+====================================================================================================================+ -| COMA -- FOUR-VIEW ARCHITECTURAL TOPOLOGY (LOCAL-FIRST & ZERO-EGRESS) | -+====================================================================================================================+ -| [VIEW 1: CLIENT RUNTIMES, ORCHESTRATOR ENTRYPOINTS & SESSION PLANNING] | -| * High-Level Client APIs: JobBoard.submit(job_id, prompt), JobRunner.run(job_id), Spawner.run(prompt) | -| * Interactive CLI Commands: coma run, coma cmd, coma session, coma submit, coma status, coma result, coma send | -| * Process-Free Dry Runs [INV-COMA-04]: build_cmd() & build_session_plan() construct argv vectors without execution| -| * Deterministic Multi-Provider Fallback [INV-COMA-05]: ordered_candidates() & available_candidates() resolution | -| * Idempotent Dual-Platform Starters [INV-COMA-08]: START.bat & start.sh generated from roles[] with marker guards | -+--------------------------------------------------------------------------------------------------------------------+ - | - v -+--------------------------------------------------------------------------------------------------------------------+ -| [VIEW 2: SINGLE-WRITER FILE PROTOCOL & DIRECTORY QUEUE TIERS] | -| * Single-Writer File Protocol [INV-COMA-01]: Exactly one writer per channel file, eliminating race conditions | -| * Ingestion Queue: IN/.md (job prompt written by submitter; atomic lease acquisition by runner) | -| * Live Bidirectional Streaming: OUT/coma..to-agent.jsonl (orchestrator) & from-agent.jsonl (agent) | -| * Execution Telemetry & Status: OUT/coma..json (runner state machine) & OUT/coma..console.log | -| * Result Delivery & Archival: OUT/.result.md -> atomic transition to DONE/.md upon completion | -+--------------------------------------------------------------------------------------------------------------------+ - | - v -+--------------------------------------------------------------------------------------------------------------------+ -| [VIEW 3: COMA CORE LIFECYCLE ENGINE & MULTI-PROVIDER CLI ADAPTERS] | -| * Zero External Dependencies [INV-COMA-02]: 100% pure Python standard library (subprocess, pathlib, os, json, sys)| -| * Verified Adapters: ClaudeAdapter (Claude Code CLI), CodexAdapter (OpenAI Codex CLI), AgyAdapter (AGY CLI) | -| * Fail-Closed Provider Safety [INV-COMA-06]: KimiAdapter remains fail-closed without explicit verified opt-in | -| * Bounded Probe Cleanup [INV-COMA-07]: probe() enforces strict timeouts & deterministic child termination | -| * Process Isolation & RC Immunity [INV-COMA-03]: Spawns detached OS process trees outside remote control sessions| -+--------------------------------------------------------------------------------------------------------------------+ - | - v -+--------------------------------------------------------------------------------------------------------------------+ -| [VIEW 4: AIR-GAP SECURITY PERIMETER, UNPRIVILEGED RUNASINVOKER & GOVERNANCE] | -| * Unprivileged User-Mode Execution [INV-COMA-09]: Strict RunAsInvoker non-elevation, zero admin/root requirements | -| * Zero Network Egress: Air-gapped local execution, zero telemetry emissions, zero external network sockets | -| * Zero-Copyleft Isolation: Strictly permissive MIT runtime, clean Level 1 SBOM companion THIRD_PARTY_LICENSES.txt | -| * Statutory Disclaimer (§ 521 BGB): Gratuitous open-source liability limitation under German Civil Code (§ 521) | -| * Security & Vulnerability SLA [INV-COMA-10]: Committed 48h response SLA & 5-day triage (security@ellmos.ai) | -+====================================================================================================================+ -``` +COMA keeps four responsibilities explicit: + +- Clients build commands and submit jobs. +- The job board coordinates through local files and caller-assigned channel writers. +- The spawner starts provider CLIs as subprocesses that inherit caller privileges. +- Documentation describes provider, network, permission, and cleanup boundaries. + --- @@ -137,34 +99,7 @@ Separation of verbs: COMA uses `spawn`, `send`, `poll`, `result`. A coordinator ## 3. Target Personas & Discoverability -### Target Personas - -- **[PERSONA-01] Autonomous Agent Framework Engineers & Swarm Architects:** - - *Context:* Developers designing multi-agent swarms, relay pipelines, or hierarchical agent hierarchies across Claude Code, OpenAI Codex, and Google Antigravity. - - *Pain Point:* Subprocess management and inter-agent communication are typically tightly coupled to brittle IPC pipes, sockets, or complex cloud servers that fail when child processes hang. - - *How COMA Solves It:* Pure file-system based queueing and bi-directional streaming channels (`to-agent.jsonl`, `from-agent.jsonl`) with single-writer guarantees (`INV-COMA-01`) and session decoupling (`INV-COMA-03`). - -- **[PERSONA-02] Local-First & Sovereign AI Developers:** - - *Context:* Engineers running AI developer toolchains locally on sovereign workstations and air-gapped environments without external cloud telemetry or mandatory accounts. - - *Pain Point:* Modern orchestration tools enforce cloud dependencies, Docker daemons, Redis clusters, or SaaS subscriptions just to run a child agent. - - *How COMA Solves It:* Zero external runtime dependencies (100% standard library `INV-COMA-02`), zero network egress, and fully self-contained directory protocol (`IN/`, `OUT/`, `DONE/`). - -- **[PERSONA-03] Remote Control & Headless Automation DevOps:** - - *Context:* DevOps engineers orchestrating headless runs, scheduled tasks, or remote terminal sessions (e.g. VS Code Remote, SSH, Antigravity/Claude remote control). - - *Pain Point:* Interactive permission bypass flags (e.g. `--dangerously-skip-permissions`, `--yolo`) fail to pass through remote sessions (open Anthropic issues #71518, #29214), stalling unattended automation for manual user approval. - - *How COMA Solves It:* Spawns agents in detached, independent OS process trees outside the remote-control session with verifiable, process-free dry-run contracts (`INV-COMA-04`). - -- **[PERSONA-04] Enterprise Security Officers & Systems Auditors:** - - *Context:* Security compliance teams auditing enterprise codebases for supply-chain risks, privilege escalation, and data exfiltration. - - *Pain Point:* Agent frameworks bundle hundreds of transitive node/python dependencies, spawn uncontrolled background daemons, or demand root/administrator privileges. - - *How COMA Solves It:* Zero third-party dependencies, strictly unprivileged user-mode execution (`RunAsInvoker` / `INV-COMA-09`), fail-closed adapter safety (`INV-COMA-06`), and strict 48h security triage SLA (`INV-COMA-10`). - -### High-Intent Search Queries - -| Language | High-Intent Search Queries | -|---|---| -| **English (EN)** | `autonomous agent lifecycle manager python` · `session decoupled agent runner` · `claude code cli spawner` · `codex cli subprocess orchestration` · `local-first agent communication channel` · `file-based agent job board` · `zero dependency agent spawner` · `bypass claude code remote control permission stall` | -| **German (DE)** | `autonome ki agenten lebenszyklus python` · `agenten prozess entkopplung dateibasiert` · `claude code cli automatisierung spawner` · `ki agenten job board ohne redis` · `lokale agenten steuerung standardbibliothek` · `remote session rechteabfrage umgehen agenten` · `multi agenten kommunikation dateisystem` · `offline agenten runner python stdlib` | +COMA is for developers integrating agent CLIs, teams coordinating jobs through local files, and maintainers who need to review subprocess permissions and data flow. It does not provide an agent, provider account, or security sandbox; selected CLIs keep their own permission and network behavior. --- @@ -177,10 +112,12 @@ Separation of verbs: COMA uses `spawn`, `send`, `poll`, `result`. A coordinator ## 4. Quickstart & Command Line Usage +Install COMA from the canonical Git repository with `python -m pip install "git+https://github.com/ellmos-ai/coma.git"`. The PyPI distribution named `coma` is a different project. + ```python from coma import JobBoard, JobRunner -board = JobBoard(r"C:\jobs\_agentjobs") +board = JobBoard(r"C:\path\to\agent-work") board.submit("myjob", "# Instructions\nWrite result to OUT/myjob.result.md.\n") result = JobRunner(board).run("myjob") @@ -190,10 +127,10 @@ print(result["status"]["state"], result["result_written"]) Or from the command line: ```bat -coma --root C:\jobs\_agentjobs run myjob -coma --root C:\jobs\_agentjobs run myjob --dry-run :: preview command without launching -coma --root C:\jobs\_agentjobs status myjob -coma --root C:\jobs\_agentjobs result myjob +coma --root C:\path\to\agent-work run myjob +coma --root C:\path\to\agent-work run myjob --dry-run :: preview command without launching +coma --root C:\path\to\agent-work status myjob +coma --root C:\path\to\agent-work result myjob ``` `--dry-run` constructs the complete command and displays it without consuming tokens or starting a process. @@ -220,7 +157,7 @@ OUT/ .result.md Final agent result output DONE/ .md Completed job prompt ``` -**Single writer per file:** No locking required, structural collision prevention. +**Channel writers:** Callers must assign one writer per channel file. Role checks do not provide OS locking or identity enforcement; callers coordinate concurrent writers. --- @@ -246,15 +183,16 @@ spawner = Spawner(adapter) result = spawner.run("Say Hello", log_file="run.log") ``` -### Verified Adapters +### Versioned Adapter Compatibility Notes -| Adapter | Target Engine | Status | -|---|---|---| -| `claude` | Anthropic Claude Code CLI | **Verified** — Flags checked against `claude --help` 2.1.263 | -| `codex` | OpenAI Codex CLI | **Verified** — Tested against CLI 0.153.4 | -| `agy` | Google Antigravity / AGY CLI | **Verified** — Tested against agy 1.1.27 | -| `kimi` | Kimi Code CLI | **Skeleton** — help contract checked with CLI 0.31.0; no real prompt run | +The version strings record prior local checks, not a current support guarantee or live-provider verification. +| Adapter | Target Engine | Historical note | +|---|---|---| +| claude | Anthropic Claude Code CLI | Prior flag check against version 2.1.263; not a current certification | +| codex | OpenAI Codex CLI | Prior compatibility check against version 0.153.4; not a current certification | +| agy | Google Antigravity / AGY CLI | Prior compatibility check against version 1.1.27; not a current certification | +| kimi | Kimi Code CLI | Skeleton; prior help contract check against version 0.31.0; no live prompt run | --- @@ -266,13 +204,9 @@ result = spawner.run("Say Hello", log_file="run.log") ## 7. Interactive and Headless Session Planning -`build_session_plan()` provides one process-free contract for interactive and -headless Claude, Codex, AGY and Kimi argv. A role prompt file and the user -request remain separate arguments. `ordered_candidates()` and -`available_candidates()` build a deterministic provider fallback chain, while -`build_probe_command()` and `probe()` provide a bounded read-only reachability -check with child-process cleanup. Kimi remains fail-closed unless a caller that -already owns a verified Kimi contract explicitly opts in. +`build_session_plan()` creates provider-specific argv without starting a process. A role prompt file and the user request remain separate arguments. `ordered_candidates()` and `available_candidates()` build a deterministic provider fallback chain. + +Probe commands are not uniformly read-only: Codex uses `--sandbox read-only`; Claude receives `--strict-mcp-config` but no general read-only sandbox; AGY and Kimi add no access restriction. Inspect generated arguments and the selected CLI permissions before running. Probe cleanup is best-effort and platform-dependent. Kimi opt-in applies to adapter session planning and spawner execution; `build_probe_command()` has no separate fail-closed guard. ```python from coma import build_session_plan @@ -295,21 +229,27 @@ print(plan.command) # argv only; no process has started ## 8. Starters from roles[] Declarations -`coma starters generate` reads the module's top-level `roles[]` declarations -and writes a thin `START.bat` plus executable `start.sh`. Both forward to the -unified console when it is installed and expose a visible COMA fallback when it -is not. The generator only replaces files carrying its own marker unless -`--force` is explicit. +`coma starters generate` reads a user-provided module manifest with a top-level `roles[]` array. Each role must include `id`, `prompt`, `request`, and a non-empty `providers` list. The prompt path is relative to the manifest and the file must exist. `ellmos-module.v2.json` describes COMA itself and is not a starter roles manifest. + +```json +{ + "id": "my-module", + "roles": [ + { "id": "reviewer", "prompt": "prompts/reviewer.md", "request": "Review the current change.", "providers": ["codex"] } + ] +} +``` ```bat -coma starters generate --manifest ellmos-module.v2.json --output-dir starters -starters\START.bat tasksolver --provider codex --dry-run +coma starters generate --manifest my-module.json --output-dir starters +starters\START.bat reviewer --provider codex --dry-run ``` --- + @@ -317,20 +257,17 @@ starters\START.bat tasksolver --provider codex --dry-run -## 9. 10-Dimension Comparative Matrix vs. Alternatives - -| Technical Dimension / Invariant | COMA (`ellmos-ai/coma`) | Celery / RQ / Redis Queue | Temporal / Camunda / Airflow | Raw Python Subprocess | Cloud Agent Frameworks (LangGraph/CrewAI) | -|---|---|---|---|---|---| -| **INV-COMA-01 Single-Writer Protocol** | **Native file protocol (`IN/`, `OUT/`, `DONE/`)** | Requires centralized Redis/RabbitMQ | Database state tables / distributed locks | Unmanaged raw OS pipes (race-prone) | Cloud SaaS database / opaque remote state | -| **INV-COMA-02 Zero Runtime Dependencies** | **100% Python Standard Library** | Multiple third-party packages & brokers | Heavy JVM/Go/Python dependency stack | Python standard library | Heavy third-party dependency tree | -| **INV-COMA-03 Session Decoupling (RC)** | **Detached OS process tree outside RC** | Background workers require daemon setup | Heavy orchestration engine | Child process killed on session exit | Serverless cloud execution (external) | -| **INV-COMA-04 Process-Free Dry Runs** | **Built-in `build_cmd` & `--dry-run`** | None (Queues require live execution) | Complex workflow dry-run mocks | Manual string concatenation | Token-consuming test runs | -| **INV-COMA-05 Multi-Provider Fallback** | **Deterministic `ordered_candidates`** | Static worker routing | Dynamic activity routing | Manual try/except loops | Vendor-locked LLM API adapters | -| **INV-COMA-06 Fail-Closed Provider Safety** | **Explicit opt-in guard (`KimiAdapter`)** | Open execution | Open execution | Silent failure / unhandled exceptions | Silent fallback / hallucinations | -| **INV-COMA-07 Bounded Probe Cleanup** | **Timeouts & child-process reaping** | Heartbeat checks with broker timeouts | Server-side worker timeouts | Can leave orphan zombie processes | Cloud container timeout | -| **INV-COMA-08 Idempotent Starters** | **Marker guards on `START.bat`/`start.sh`** | None | CLI scaffolders | Manual shell scripts | Cloud web dashboard | -| **INV-COMA-09 User-Mode Execution** | **Strictly `RunAsInvoker` (Unprivileged)** | Often requires daemon/systemd service | Often requires daemon/system services | Inherits parent privileges | Container or cloud VM privileges | -| **INV-COMA-10 48h Security SLA** | **48h Acknowledgment & 5d Triage** | Variable open-source tracker | Enterprise SLA ($$$) / Community | None | SaaS SLA (Commercial account required) | +## 9. COMA Behavior and Boundaries + +| Dimension | COMA behavior and limit | +|---|---| +| Job coordination | Local directory and file-based job protocol. | +| Direct Python runtime packages | None are declared in `pyproject.toml`; this says nothing about provider CLIs or their own dependencies. | +| Network behavior | COMA itself does not implement a network service. A launched CLI may contact providers or other services. | +| Channel concurrency | Callers must assign one writer per channel. Role checks are not OS locks or identity enforcement. | +| Process permissions | Agent CLIs inherit the launching process privileges; COMA does not sandbox them. | +| Probe cleanup | Timeout and platform-dependent best-effort cleanup; descendants may remain. | +| Security reporting | Maintainers publish acknowledgment and triage targets in SECURITY.md. | --- @@ -355,9 +292,9 @@ flowchart TD end subgraph Layer2 ["2. Queue & Protocol Directory"] - B1 --> C1["_agentjobs/IN/"] - C2["_agentjobs/OUT/"] - C3["_agentjobs/DONE/"] + B1 --> C1["agent-work/IN/"] + C2["agent-work/OUT/"] + C3["agent-work/DONE/"] end subgraph Layer3 ["3. COMA Core Lifecycle Engine"] @@ -369,12 +306,12 @@ flowchart TD subgraph Layer4 ["4. Multi-Provider CLI Adapters"] D2 --> E1["ClaudeAdapter"] D2 --> E2["CodexAdapter"] - D2 --> E3["AntigravityAdapter"] - D2 --> E4["KimiAdapter (Fail-Closed)"] + D2 --> E3["AgyAdapter"] + D2 --> E4["Kimi: opt-in via Spawner/session"] end - subgraph Layer5 ["5. Detached OS Processes & Channels"] - E1 & E2 & E3 & E4 -->|"Spawns Unprivileged Process"| F1["Detached Agent Process"] + subgraph Layer5 ["5. Agent CLI Subprocesses & Channels"] + E1 & E2 & E3 & E4 -->|"Starts subprocess; caller privileges inherited"| F1["Agent CLI subprocess"] F1 -->|"Progress Events"| G1["OUT/coma..from-agent.jsonl"] F1 -->|"Final Output"| G2["OUT/.result.md"] F1 -->|"Console Logs"| G3["OUT/coma..console.log"] @@ -393,12 +330,12 @@ sequenceDiagram participant Board as "JobBoard (IN/)" participant Runner as "COMA Runner / Spawner" participant Adapter as "CLI Adapter (Claude/Codex/AGY/Kimi)" - participant Subprocess as "Agent Process (Detached OS Process)" + participant Subprocess as "Agent CLI subprocess (inherits caller privileges)" participant Channels as "Output Channels (OUT/)" participant Archive as "Job Archive (DONE/)" Orchestrator->>Board: "submit(job_id, prompt_markdown)" - Note over Board: "Single writer: Orchestrator writes IN/.md" + Note over Board: "Assigned writer: Orchestrator writes IN/.md" Orchestrator->>Runner: "run(job_id) (or background watcher triggers)" Runner->>Board: "Read prompt & acquire single-worker lease" Runner->>Adapter: "build_cmd(prompt, options) -> Process-free argv" @@ -429,22 +366,22 @@ sequenceDiagram -## 11. Governance & 10 Runtime Invariants +## 11. Governance & Runtime Contracts -To preserve security, system integrity, and predictability, COMA adheres to 10 strict invariants: +The following table separates implementation behavior from caller conventions and maintainer policy: | ID | Invariant | Description | |---|---|---| -| **INV-COMA-01** | **Single-Writer Rule** | Each channel file in `_agentjobs/` has exactly one writer (`IN/` by submitter, `to-agent.jsonl` by orchestrator, `from-agent.jsonl`/`result.md` by agent, `coma..json` by runner). Eliminates lock contention and sync conflicts. | -| **INV-COMA-02** | **Zero External Runtime Dependencies** | The core COMA library makes 0 network connections, opens no ports, and has zero external package dependencies. Standard library only. | -| **INV-COMA-03** | **Session Decoupling** | Subprocesses run in dedicated, independent OS process trees outside interactive terminal sessions, bypassing remote-control interactive permission stalls. | +| **INV-COMA-01** | **Channel writer convention** | Callers must assign one writer per channel file. Optional role checks are not OS locks or identity enforcement; callers coordinate concurrency. | +| **INV-COMA-02** | **Direct runtime dependencies** | `pyproject.toml` declares no direct external Python runtime packages. COMA itself does not implement a network service; launched agent CLIs may access networks and services. | +| **INV-COMA-03** | **Subprocess lifecycle** | Provider CLIs start as subprocesses. Their permission behavior, privileges, and network access come from the CLI and launching environment; COMA does not sandbox them. | | **INV-COMA-04** | **Process-Free Dry Runs** | Command builders (`build_cmd`, `build_session_plan`, `--dry-run`) construct argument lists deterministically without starting processes or consuming LLM tokens. | | **INV-COMA-05** | **Deterministic CLI Fallback** | Multi-provider fallback chains (`ordered_candidates`) resolve binaries deterministically without silent execution of unverified engines. | -| **INV-COMA-06** | **Fail-Closed Provider Safety** | Unverified or experimental adapters (such as Kimi) remain fail-closed and reject real prompt runs unless callers explicitly opt in with an established contract. | -| **INV-COMA-07** | **Bounded Probe Cleanup** | Reachability probes (`probe()`) enforce strict execution timeouts and guarantee child-process cleanup to avoid orphaned processes. | +| **INV-COMA-06** | **Kimi execution opt-in** | Spawner/session execution through `coma.spawn` and `coma.session` requires explicit opt-in; raw adapter or probe argument construction does not enforce the gate. | +| **INV-COMA-07** | **Probe timeout and cleanup** | Reachability probes use a timeout and attempt platform-dependent cleanup. Windows requests process-tree termination; Unix kills the direct process. Descendant termination is not guaranteed. | | **INV-COMA-08** | **Idempotent Dual-Platform Starters** | Starter scripts (`START.bat`, `start.sh`) generated from `roles[]` carry unique marker guards preventing accidental overwrites of custom wrappers. | -| **INV-COMA-09** | **Unprivileged User-Mode Execution** | Strictly unprivileged user-space execution (`RunAsInvoker`); zero administrative elevation, driver hooks, or root permissions required. | -| **INV-COMA-10** | **48h Security Response SLA** | Committed 48-hour response SLA and 5-business-day vulnerability triage for all reported security hazards. | +| **INV-COMA-09** | **Inherited privileges** | Child processes inherit the launching process privileges. COMA does not request elevation, drop privileges, or provide a security isolation boundary. | +| **INV-COMA-10** | **Maintainer response policy** | [`SECURITY.md`](SECURITY.md) states targets of acknowledgment within 48 hours and triage within 5 business days. | --- @@ -483,11 +420,11 @@ To preserve security, system integrity, and predictability, COMA adheres to 10 s ## 13. Testing & Verification Suite ```bash -python -m pytest -q :: 313 passed tests +python -m pytest -ra -v ``` -Tests never start a provider. One bounded probe test uses the local Python -interpreter as a harmless fake CLI; all remaining subprocess calls are mocked. +Tests mock provider CLI execution; the suite does not perform live-provider verification. A probe test starts a controlled local Python process to check reachability. + --- @@ -500,13 +437,7 @@ interpreter as a harmless fake CLI; all remaining subprocess calls are mocked. ## 14. Third-Party Licenses & Level 1 SBOM -COMA enforces an audited **Level 1 Software Bill of Materials (SBOM)** with Zero External Runtime Dependencies (`INV-COMA-02`): - -- **Core Runtime:** 100% Python Standard Library ([PSF License 2.0](https://docs.python.org/3/license.html)). -- **Zero-Copyleft Isolation Guarantee:** Strictly permissive licensing throughout (MIT / PSF-2.0 / Apache-2.0). Zero viral copyleft exposure. -- **Unprivileged Execution:** Certified for standard user mode (`RunAsInvoker`). -- **Complete SBOM & License Texts:** Maintained in [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md) with comprehensive SPDX inventory and 10-invariant compliance matrix. - +The project license is MIT. [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md) inventories the project and listed Python dependencies. It does not certify the licenses of separately installed agent CLIs, provider services, the Python runtime, or build tools. The project declares no direct Python runtime package dependencies in `pyproject.toml`. --- @@ -535,7 +466,14 @@ COMA is part of the `ellmos-ai` orchestration architecture and the broader `open | **Agent Bootstrap** | [`dev-bricks/safe-start-for-codex`](https://github.com/dev-bricks/safe-start-for-codex) | Safe startup, environment checks & preflight diagnostics | | **Umbrella Ecosystem** | [`open-bricks`](https://github.com/open-bricks) | Open-source foundation for local-first developer tools | -- [Swarm AI](https://github.com/ellmos-ai/swarm_ai) optionally uses COMA's Spawner and adapter APIs for provider-backed workflows. +Documented integrations in public repositories are optional or use COMA at a specific integration point; they do not imply a hard dependency: + +- [swarm_ai](https://github.com/ellmos-ai/swarm_ai) uses COMA Spawner and adapter APIs for provider-backed workflows. +- [marblerun](https://github.com/ellmos-ai/marblerun) integrates with COMA Spawner and adapters. +- [ellmos-scheduler](https://github.com/ellmos-ai/ellmos-scheduler) integrates with COMA Spawner and adapters. +- [task-master](https://github.com/ellmos-ai/task-master) has an optional COMA integration. +- [open-ocean](https://github.com/ellmos-ai/open-ocean) checks for optional COMA session support and provides a CLI fallback. +- [ticket-master](https://github.com/ellmos-ai/ticket-master) uses COMA Starters at build time; it is not a runtime integration. --- @@ -546,10 +484,9 @@ COMA is part of the `ellmos-ai` orchestration architecture and the broader `open -## 16. Security Policy & Subprocess Isolation - -For subprocess isolation details, single-writer protocol boundaries, non-elevation certification (`RunAsInvoker`), and vulnerability disclosure policies, see [`SECURITY.md`](SECURITY.md). +## 16. Security Boundaries and Reporting +COMA starts provider CLIs as subprocesses. Child processes inherit the launching process privileges and may use the network; COMA does not sandbox them. For channel conventions, probe cleanup limits, and vulnerability reporting, see [`SECURITY.md`](SECURITY.md). --- @@ -559,11 +496,9 @@ For subprocess isolation details, single-writer protocol boundaries, non-elevati -## 17. Statutory Notice & Liability Limitation (§ 521 BGB) - -> **Statutory Notice pursuant to German Law (§ 521 BGB - Gefälligkeitsrecht):** -> COMA is provided free of charge as an open-source developer tool without commercial consideration. In accordance with § 521 of the German Civil Code (*BGB*), the liability of the authors and contributors is restricted to intent (*Vorsatz*) and gross negligence (*grobe Fahrlässigkeit*). Use of this software, including process spawning and execution of autonomous subagents, occurs at the user's sole risk and discretion. +## 17. Statutory Notice (§ 521 BGB) +The project is provided under the MIT license. Whether statutory rules such as section 521 BGB apply depends on the legal relationship and applicable law; this documentation does not provide a blanket exemption from liability. --- diff --git a/README_de.md b/README_de.md index 44eb30e..e595196 100644 --- a/README_de.md +++ b/README_de.md @@ -4,16 +4,13 @@ **[English](README.md) | [Deutsch](README_de.md)** -[![Pytest Status](https://img.shields.io/badge/pytest-313%20bestanden-brightgreen.svg)](https://docs.pytest.org/) -[![Geprüft](https://img.shields.io/badge/gepr%C3%BCft-2026--10--04-brightgreen.svg)](MARKETING-LOG.txt) +[![Tests](https://github.com/ellmos-ai/coma/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ellmos-ai/coma/actions/workflows/tests.yml) [![Drittanbieter-Lizenzen (Text)](https://img.shields.io/badge/lizenzen--text-Level%201%20SBOM-blue.svg)](THIRD_PARTY_LICENSES.txt) [![Version](https://img.shields.io/badge/version-0.3.2-blue.svg)](pyproject.toml) [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) -[![Abhaengigkeiten](https://img.shields.io/badge/abhaengigkeiten-0%20(stdlib)-brightgreen.svg)](pyproject.toml) -[![Netzwerk](https://img.shields.io/badge/netzwerk-zero--egress-success.svg)](SECURITY.md) -[![Ausfuehrung](https://img.shields.io/badge/modus-RunAsInvoker-informational.svg)](THIRD_PARTY_LICENSES.md) +[![Laufzeit-Abhängigkeiten](https://img.shields.io/badge/laufzeit--abhängigkeiten-keine-blue.svg)](pyproject.toml) [![Architektur](https://img.shields.io/badge/architektur-local--first-blue.svg)](KONZEPT.md) -[![Protokoll](https://img.shields.io/badge/protokoll-single--writer-informational.svg)](KONZEPT.md) +[![Protokoll](https://img.shields.io/badge/protokoll-dateibasiert-informational.svg)](README_de.md#5-job-protokoll) [![Sicherheits-SLA](https://img.shields.io/badge/sicherheit-48h%20SLA-blue.svg)](SECURITY.md) [![Lizenz: MIT](https://img.shields.io/badge/Lizenz-MIT-yellow.svg)](LICENSE) [![LLM Bereit](https://img.shields.io/badge/llms.txt-bereit-blueviolet.svg)](llms.txt) @@ -29,7 +26,7 @@ ### Schnellnavigation -1. [Was ist COMA? & Kernnutzen](#1-was-ist-coma) · 2. [Primäre Anwendungsfälle & Session-Entkopplung](#2-anwendungsfaelle) · 3. [Zielgruppen & Auffindbarkeit](#3-zielgruppen--auffindbarkeit) · 4. [Schnellstart & CLI-Nutzung](#4-schnellstart) · 5. [Dateibasiertes Job-Board-Protokoll](#5-job-protokoll) · 6. [Spawner-Schicht & Multi-Engine CLI-Adapter](#6-spawner-schicht) · 7. [Interaktive & Headless Sitzungsplanung](#7-interaktive-und-headless-sitzungen) · 8. [Starter aus roles[] Deklarationen](#8-starter-aus-rollen) · 9. [10-Dimensionen Vergleichsmatrix](#9-vergleichsmatrix-vs-alternativen) · 10. [Duale Mermaid-Diagramme](#10-duale-mermaid-diagramme) · 11. [Governance & 10 Laufzeit-Invarianten](#11-governance--und-laufzeit-invarianten) · 12. [CLI-Befehlsreferenz](#12-kommandozeile) · 13. [Tests & Verifikationssuite](#13-tests) · 14. [Drittanbieter-Lizenzen & Level 1 SBOM](#14-drittanbieter-lizenzen) · 15. [Geschwister-Ökosystem & Integration](#15-geschwisterwerkzeuge--ökosystem) · 16. [Sicherheitsarchitektur & Subprozess-Isolation](#16-sicherheit) · 17. [Gesetzlicher Hinweis (§ 521 BGB)](#17-gesetzlicher-hinweis--haftungsbeschraenkung) · 18. [Lizenz & Open-Source-Dach](#18-stand--lizenz) +1. [Was ist COMA? & Kernnutzen](#1-was-ist-coma) · 2. [Primäre Anwendungsfälle & Session-Entkopplung](#2-anwendungsfaelle) · 3. [Zielgruppen & Auffindbarkeit](#3-zielgruppen--auffindbarkeit) · 4. [Schnellstart & CLI-Nutzung](#4-schnellstart) · 5. [Dateibasiertes Job-Board-Protokoll](#5-job-protokoll) · 6. [Spawner-Schicht & Multi-Engine CLI-Adapter](#6-spawner-schicht) · 7. [Interaktive & Headless Sitzungsplanung](#7-interaktive-und-headless-sitzungen) · 8. [Starter aus roles[] Deklarationen](#8-starter-aus-roles) · 9. [COMA-Verhalten und Grenzen](#9-coma-verhalten-und-grenzen) · 10. [Duale Mermaid-Diagramme](#10-duale-mermaid-diagramme) · 11. [Governance & Laufzeitverträge](#11-governance--und-laufzeit-invarianten) · 12. [CLI-Befehlsreferenz](#12-kommandozeile) · 13. [Tests & Verifikationssuite](#13-tests) · 14. [Drittanbieter-Lizenzen & Level 1 SBOM](#14-drittanbieter-lizenzen) · 15. [Geschwister-Ökosystem & Integration](#15-geschwisterwerkzeuge--ökosystem) · 16. [Sicherheitsarchitektur & Subprozess-Isolation](#16-sicherheit) · 17. [Gesetzlicher Hinweis (§ 521 BGB)](#17-gesetzlicher-hinweis--haftungsbeschraenkung) · 18. [Lizenz & Open-Source-Dach](#18-stand--lizenz) --- @@ -48,7 +45,7 @@ COMA steht primär als **session-übergreifender und session-unabhängiger Kommunikations- und Auftragskanal für autonome Subagents** (Dateisystem-basiert via `IN/`, `OUT/`, `DONE/`). Als Begriffsauslegung steht **Command & Communication for Autonomous Subagents** im Mittelpunkt. -Genau eine Verantwortung: COMA sperrt nichts, verwaltet keine Rechte und hält kein Gedächtnis. Es arbeitet mit Dateien und Prozessen — **ohne Konto, ohne Netz, ohne Cluster**. Null externe Abhängigkeiten, nur Python-Standardbibliothek. +COMA koordiniert Aufträge über lokale Dateien und startet Anbieter-CLIs als Subprozesse. COMA selbst stellt keinen Netzwerkdienst bereit und benötigt kein eigenes Konto. Gestartete CLIs können ihre Anbieter oder andere Dienste kontaktieren und eigene Konten oder Netzzugriff benötigen. Das Projekt deklariert keine direkten externen Python-Laufzeitpakete. Konzept, Begründung und Abgrenzung: [`KONZEPT.md`](KONZEPT.md). @@ -71,10 +68,8 @@ Die Verben trennen sauber: COMA spricht `spawn`, `send`, `poll`, `result`. Ein K ## 2. Primäre Anwendungsfälle & Session-Entkopplung -1. **Entkopplung von Remote-Control-Sessions (RC-Immunität)** - In einer **Remote-Control-Session** reicht Claude Code `--dangerously-skip-permissions` oft nicht an den Remote-Client durch (offene Issues [#71518](https://github.com/anthropics/claude-code/issues/71518), [#29214](https://github.com/anthropics/claude-code/issues/29214)). Folge: Jeder Tool-Aufruf fragt nach — auch bei Agenten. Ist niemand am Rechner, stehen sie still: Unbeaufsichtigte Agenten warten auf Freigabeklicks, die niemand gibt. - - Die Lösung ist, den Agenten **gar nicht erst in der RC-Session leben zu lassen**: Ein eigener lokaler Betriebssystem-Prozess außerhalb dieser Session, Kommunikation robust über das Dateisystem. **COMA umgeht keine Sicherheitsgrenze**, sondern nutzt dokumentierte CLI-Flags (`--permission-mode`, `--allowedTools`) an der Stelle, an der sie tatsächlich ankommen. +1. **Entkopplung von Remote-Control-Sessions** + Interaktive Clients und Remote-Control-Sitzungen können CLI-Berechtigungen unterschiedlich handhaben. COMA startet das gewählte CLI als Subprozess und tauscht Aufträge über Dateisystemkanäle aus; die Berechtigungen des Anbieter-CLIs gelten weiterhin. 2. **Session-übergreifende Handoffs & Multi-Agent Relays** Aufgaben werden über Session-Grenzen hinweg zwischen Agenten übergeben, ohne dass Prozesse blockieren oder Kontext verloren geht. @@ -84,48 +79,13 @@ Die Verben trennen sauber: COMA spricht `spawn`, `send`, `poll`, `result`. Ein K ### ASCII Vier-Sichten-Architekturtopologie -```text -+====================================================================================================================+ -| COMA -- VIER-SICHTEN-ARCHITEKTURTOPOLOGIE (LOKAL-FIRST & ZERO-EGRESS) | -+====================================================================================================================+ -| [SICHT 1: CLIENT-LAUFZEITEN, ORCHESTRATOR-EINTRITTSPUNKTE & SITZUNGSPLANUNG] | -| * High-Level Client-APIs: JobBoard.submit(job_id, prompt), JobRunner.run(job_id), Spawner.run(prompt) | -| * Interaktive CLI-Befehle: coma run, coma cmd, coma session, coma submit, coma status, coma result, coma send | -| * Prozessfreie Trockenläufe [INV-COMA-04]: build_cmd() & build_session_plan() erzeugen argv-Vektoren ohne Start | -| * Deterministischer Multi-Provider-Fallback [INV-COMA-05]: ordered_candidates() & available_candidates() Auflösung| -| * Idempotente Dual-Plattform-Starter [INV-COMA-08]: START.bat & start.sh aus roles[] mit Schutzmarkern | -+--------------------------------------------------------------------------------------------------------------------+ - | - v -+--------------------------------------------------------------------------------------------------------------------+ -| [SICHT 2: SINGLE-WRITER DATEIPROTOKOLL & VERZEICHNIS-WARTESCHLANGEN] | -| * Single-Writer-Dateiprotokoll [INV-COMA-01]: Genau ein Schreiber je Kanaldatei, vollständige Kollisionsfreiheit | -| * Auftrags-Eingang: IN/.md (Auftragsprompt durch Einreicher; atomare Ausführungsübernahme durch Runner) | -| * Live-Streaming: OUT/coma..to-agent.jsonl (Orchestrator) & from-agent.jsonl (Agent) | -| * Ausführungsstatus & Telemetrie: OUT/coma..json (Zustandsmaschine) & OUT/coma..console.log | -| * Ergebnisabgabe & Archivierung: OUT/.result.md -> atomare Überführung nach DONE/.md bei Erfolg | -+--------------------------------------------------------------------------------------------------------------------+ - | - v -+--------------------------------------------------------------------------------------------------------------------+ -| [SICHT 3: COMA KERN-LEBENSZYKLUS-ENGINE & MULTI-PROVIDER CLI-ADAPTER] | -| * Null externe Abhängigkeiten [INV-COMA-02]: 100% reine Python-Standardbibliothek (subprocess, pathlib, os, json) | -| * Verifizierte Adapter: ClaudeAdapter (Claude Code CLI), CodexAdapter (OpenAI Codex CLI), AgyAdapter (AGY CLI) | -| * Fail-Closed Provider-Sicherheit [INV-COMA-06]: KimiAdapter bleibt ohne explizites Opt-in strikt fail-closed | -| * Begrenzte Probe-Bereinigung [INV-COMA-07]: probe() erzwingt strikte Timeouts & garantierte Kindprozess-Terminierung| -| * Prozess-Isolation & RC-Immunität [INV-COMA-03]: Eigene Betriebssystem-Prozessbäume außerhalb von Remote-Sessions| -+--------------------------------------------------------------------------------------------------------------------+ - | - v -+--------------------------------------------------------------------------------------------------------------------+ -| [SICHT 4: AIR-GAP SICHERHEITSPERIMETER, UNPRIVILEGIERTER RUNASINVOKER & GOVERNANCE] | -| * Unprivilegierte Ausführung [INV-COMA-09]: Striktes RunAsInvoker Benutzermodus, null Administrator-/Root-Rechte | -| * Zero-Network-Egress: Vollständig netzwerkisoliert, null Telemetrie-Übertragung, null externe Sockets | -| * Zero-Copyleft-Isolation: Rein permissive MIT-Lizenz, sauberer Level 1 SBOM Begleiter THIRD_PARTY_LICENSES.txt | -| * Gesetzlicher Hinweis (§ 521 BGB): Haftungsbeschränkung für unentgeltliche Bereitstellung nach deutschem BGB | -| * Sicherheits- & Governance-SLA [INV-COMA-10]: Verbindliche 48h Antwort-SLA & 5 Tage Triage (security@ellmos.ai) | -+====================================================================================================================+ -``` +COMA trennt vier Aufgaben: + +- Clients planen Befehle und übergeben Aufträge. +- Das Job-Board koordiniert Dateien und von Aufrufern zugeordnete Kanalschreiber. +- Der Spawner startet Anbieter-CLIs mit den geerbten Rechten des Aufrufers. +- Die Dokumentation benennt Netzwerk-, Rechte- und Bereinigungsgrenzen. + --- @@ -139,34 +99,7 @@ Die Verben trennen sauber: COMA spricht `spawn`, `send`, `poll`, `result`. Ein K ## 3. Zielgruppen & Auffindbarkeit -### Ziel-Personas - -- **[PERSONA-01] Autonomous Agent Framework Engineers & Swarm Architects:** - - *Kontext:* Entwickler von Multi-Agenten-Pipelines, Swarm-Hierarchien und Relay-Systemen über Claude Code, OpenAI Codex und Google Antigravity. - - *Pain Point:* Subprozess-Steuerung und Inter-Agenten-Kommunikation hängen oft an fragilen IPC-Pipes, Sockets oder schweren Cloud-Servern, die abstürzen, wenn Kindprozesse blockieren. - - *Wie COMA es löst:* Rein dateibasierte Warteschlange und bidirektionale Streaming-Kanäle (`to-agent.jsonl`, `from-agent.jsonl`) mit Single-Writer-Garantie (`INV-COMA-01`) und Session-Entkopplung (`INV-COMA-03`). - -- **[PERSONA-02] Local-First & Sovereign AI Developers:** - - *Kontext:* Ingenieure, die lokale KI-Entwickler-Pipelines auf eigenen Workstations oder in Air-Gapped-Umgebungen betreiben — ohne externe Telemetrie oder Kontozwang. - - *Pain Point:* Moderne Orchestrierungswerkzeuge erzwingen Cloud-Dienste, Docker-Daemons, Redis-Cluster oder SaaS-Abos, nur um einen Kind-Agenten zu starten. - - *Wie COMA es löst:* Null externe Laufzeit-Abhängigkeiten (100% Standardbibliothek `INV-COMA-02`), Zero-Network-Egress und vollständiges lokales Verzeichnisprotokoll (`IN/`, `OUT/`, `DONE/`). - -- **[PERSONA-03] Remote Control & Headless Automation DevOps:** - - *Kontext:* DevOps-Ingenieure für Headless-Läufe, geplante Tasks oder entfernte Terminalsitzungen (z. B. VS Code Remote, SSH, Antigravity/Claude Remote Control). - - *Pain Point:* Interaktive Rechteüberbrückungs-Flags (`--dangerously-skip-permissions`, `--yolo`) versagen in Remotesitzungen (Anthropic-Bugs #71518, #29214), sodass unbeaufsichtigte Läufe auf Nutzerbestätigungen hängenbleiben. - - *Wie COMA es löst:* Startet Agenten als isolierte Betriebssystem-Prozesse außerhalb der Remote-Session mit verifizierbarem, prozessfreiem Dry-Run-Vertrag (`INV-COMA-04`). - -- **[PERSONA-04] Enterprise Security Officers & Systems Auditors:** - - *Kontext:* Sicherheits- und Compliance-Beauftragte, die Software-Lieferketten, Rechteeskalationen und Datenabflüsse auditieren. - - *Pain Point:* Agenten-Frameworks schleppen Hunderte transitive Node/Python-Pakete ein, starten unkontrollierte Daemons oder fordern Administrator-/Root-Rechte an. - - *Wie COMA es löst:* Null Drittanbieter-Pakete, strikter unprivilegierter Nutzermodus (`RunAsInvoker` / `INV-COMA-09`), Fail-Closed Adapter-Sicherheit (`INV-COMA-06`) und verbindliche 48h Sicherheits-SLA (`INV-COMA-10`). - -### High-Intent Suchbegriffe - -| Sprache | High-Intent Suchanfragen | -|---|---| -| **Deutsch (DE)** | `autonome ki agenten lebenszyklus python` · `agenten prozess entkopplung dateibasiert` · `claude code cli automatisierung spawner` · `ki agenten job board ohne redis` · `lokale agenten steuerung standardbibliothek` · `remote session rechteabfrage umgehen agenten` · `multi agenten kommunikation dateisystem` · `offline agenten runner python stdlib` | -| **Englisch (EN)** | `autonomous agent lifecycle manager python` · `session decoupled agent runner` · `claude code cli spawner` · `codex cli subprocess orchestration` · `local-first agent communication channel` · `file-based agent job board` · `zero dependency agent spawner` · `bypass claude code remote control permission stall` | +COMA richtet sich an Entwickler, die Anbieter-CLIs integrieren, Teams mit dateibasierter Auftragskoordination und Maintainer, die Rechte und Datenflüsse gestarteter Subprozesse prüfen müssen. COMA liefert weder einen Agenten noch ein Anbieter-Konto oder eine Sicherheits-Sandbox; Rechte und Netzwerkverhalten hängen von der jeweiligen CLI ab. --- @@ -179,10 +112,12 @@ Die Verben trennen sauber: COMA spricht `spawn`, `send`, `poll`, `result`. Ein K ## 4. Schnellstart & CLI-Nutzung +Installation aus dem kanonischen Git-Repository: `python -m pip install "git+https://github.com/ellmos-ai/coma.git"`. Das PyPI-Paket namens `coma` ist ein anderes Projekt. + ```python from coma import JobBoard, JobRunner -board = JobBoard(r"C:\jobs\_agentjobs") +board = JobBoard(r"C:\path\to\agent-work") board.submit("meinjob", "# Auftrag\n\nSchreibe das Ergebnis nach OUT/meinjob.result.md.\n") result = JobRunner(board).run("meinjob") @@ -192,10 +127,10 @@ print(result["status"]["state"], result["result_written"]) Oder von der Kommandozeile: ```bat -coma --root C:\jobs\_agentjobs run meinjob -coma --root C:\jobs\_agentjobs run meinjob --dry-run :: nur zeigen, nichts starten -coma --root C:\jobs\_agentjobs status meinjob -coma --root C:\jobs\_agentjobs result meinjob +coma --root C:\path\to\agent-work run meinjob +coma --root C:\path\to\agent-work run meinjob --dry-run :: nur zeigen, nichts starten +coma --root C:\path\to\agent-work status meinjob +coma --root C:\path\to\agent-work result meinjob ``` `--dry-run` baut das vollständige Kommando und zeigt es, ohne dass ein Token fließt oder ein Prozess gestartet wird. @@ -222,7 +157,7 @@ OUT/ .result.md Ergebnis DONE/ .md Erledigter Auftrag (wird bei Erfolg verschoben) ``` -**Ein Schreiber je Datei:** Keine Sperren erforderlich, strukturelle Kollisionsvermeidung. +**Kanalschreiber:** Aufrufer müssen jedem Kanal genau einen Schreiber zuordnen. Rollenprüfungen sind weder Betriebssystem-Sperren noch Identitätsprüfung; Aufrufer koordinieren parallele Schreiber. --- @@ -249,15 +184,16 @@ spawner = Spawner(adapter) result = spawner.run("Sag Hallo", log_file="run.log") ``` -### Verifizierte Adapter +### Historische CLI-Kompatibilitätsprüfungen -| Adapter | Ziel-Engine | Status | -|---|---|---| -| `claude` | Anthropic Claude Code CLI | **Verifiziert** — Flags gegen `claude --help` 2.1.263 geprüft | -| `codex` | OpenAI Codex CLI | **Verifiziert** — Gegen CLI 0.153.4 getestet | -| `agy` | Google Antigravity / AGY CLI | **Verifiziert** — Gegen agy 1.1.27 getestet | -| `kimi` | Kimi Code CLI | **Gerüst (Skeleton)** — help-Vertrag mit CLI 0.31.0 abgeglichen; kein echter Prompt-Lauf | +Die Versionsangaben dokumentieren frühere lokale Prüfungen, keine aktuelle Supportzusage oder Live-Anbieter-Verifikation. +| Adapter | Ziel-Engine | Historischer Prüfstand | +|---|---|---| +| claude | Anthropic Claude Code CLI | Frühere Flag-Prüfung gegen Version 2.1.263; keine aktuelle Zertifizierung | +| codex | OpenAI Codex CLI | Frühere Kompatibilitätsprüfung gegen Version 0.153.4 | +| agy | Google Antigravity / AGY CLI | Frühere Kompatibilitätsprüfung gegen Version 1.1.27 | +| kimi | Kimi Code CLI | Gerüst; frühere Hilfe-Vertragsprüfung gegen Version 0.31.0; kein Live-Promptlauf | --- @@ -269,12 +205,9 @@ result = spawner.run("Sag Hallo", log_file="run.log") ## 7. Interaktive & Headless Sitzungsplanung -`build_session_plan()` liefert einen prozessfreien Vertrag für interaktive und headless -Claude-, Codex-, AGY- und Kimi-argv. Rollen-Prompt-Datei und Nutzeranfrage bleiben -getrennte Argumente. `ordered_candidates()` und `available_candidates()` bauen eine -deterministische Provider-Fallback-Kette, während `build_probe_command()` und `probe()` -eine begrenzte, lesende Erreichbarkeitsprüfung mit Kindprozess-Bereinigung bereitstellen. -Kimi bleibt Fail-Closed, solange ein Aufrufer nicht explizit per Vertrag optiert. +`build_session_plan()` erstellt anbieterabhängige Argumentlisten, ohne einen Prozess zu starten. Rollen-Prompt-Datei und Nutzeranfrage bleiben getrennte Argumente. `ordered_candidates()` und `available_candidates()` bauen eine deterministische Provider-Fallback-Kette. + +Nicht alle Sonden sind lesebeschränkt: Codex erhält `--sandbox read-only`; Claude erhält `--strict-mcp-config`, jedoch keine allgemeine Nur-Lese-Sandbox; AGY und Kimi ergänzen keine Zugriffsbeschränkung. Prüfe Argumente und Rechte des gewählten CLI vor dem Start. Die Sondenbereinigung erfolgt nach bestem Bemühen und ist plattformabhängig. Kimi-Opt-in gilt für Adapter-Sitzungsplanung und Spawner-Ausführung; `build_probe_command()` enthält keine eigene Fail-Closed-Sperre. ```python from coma import build_session_plan @@ -297,21 +230,27 @@ print(plan.command) # Nur argv; kein Prozess gestartet ## 8. Starter aus roles[] Deklarationen -`coma starters generate` liest die `roles[]`-Deklarationen eines Modul-Manifests -(`ellmos-module.v2.json`) und erzeugt ein schlankes `START.bat` sowie ein ausführbares -`start.sh`. Beide leiten an die Unified Console weiter, falls installiert, oder bieten -einen sichtbaren COMA-Fallback. Der Generator überschreibt nur Dateien mit eigenem Marker, -es sei denn, `--force` wird angegeben. +`coma starters generate` liest ein vom Nutzer bereitgestelltes Modul-Manifest mit einer obersten `roles[]`-Liste. Jede Rolle benötigt `id`, `prompt`, `request` und eine nichtleere `providers`-Liste. Der Promptpfad gilt relativ zum Manifest und die Datei muss existieren. `ellmos-module.v2.json` beschreibt COMA selbst und ist kein Rollenmanifest für Starter. + +```json +{ + "id": "my-module", + "roles": [ + { "id": "reviewer", "prompt": "prompts/reviewer.md", "request": "Review the current change.", "providers": ["codex"] } + ] +} +``` ```bat -coma starters generate --manifest ellmos-module.v2.json --output-dir starters -starters\START.bat tasksolver --provider codex --dry-run +coma starters generate --manifest my-module.json --output-dir starters +starters\START.bat reviewer --provider codex --dry-run ``` --- + @@ -319,20 +258,18 @@ starters\START.bat tasksolver --provider codex --dry-run -## 9. 10-Dimensionen Vergleichsmatrix vs. Alternativen - -| Technische Dimension / Invariante | COMA (`ellmos-ai/coma`) | Celery / RQ / Redis Queue | Temporal / Camunda / Airflow | Reiner Python Subprozess | Cloud Agent Frameworks (LangGraph/CrewAI) | -|---|---|---|---|---|---| -| **INV-COMA-01 Single-Writer-Protokoll** | **Natives Dateiprotokoll (`IN/`, `OUT/`, `DONE/`)** | Benötigt zentralen Redis/RabbitMQ-Broker | Datenbank-Statustabellen / verteilte Sperren | Unverwaltete OS-Pipes (anfällig für Race Conditions) | Cloud SaaS-Datenbank / intransparenter Remote-State | -| **INV-COMA-02 Zero Runtime Dependencies** | **100% Python-Standardbibliothek** | Mehrere externe Pakete & Broker nötig | Schwerer JVM/Go/Python-Stack | Standardbibliothek | Schwere Drittanbieter-Abhängigkeitsbäume | -| **INV-COMA-03 Session-Entkopplung (RC)** | **Isolierter OS-Prozess außerhalb RC** | Hintergrund-Worker benötigen Daemons | Schwergewichtige Orchestrierungs-Engine | Kindprozess stirbt beim Session-Ende | Serverlose Cloud-Ausführung (extern) | -| **INV-COMA-04 Prozessfreie Dry-Runs** | **Integriertes `build_cmd` & `--dry-run`** | Keine (Queues erfordern Live-Ausführung) | Komplexe Workflow-Mocks erforderlich | Manuelle String-Verknüpfung | Token-verbrauchende Testläufe | -| **INV-COMA-05 Multi-Provider Fallback** | **Deterministisches `ordered_candidates`** | Statisches Worker-Routing | Dynamisches Activity-Routing | Manuelle try/except-Schleifen | Vendor-Locked LLM-API-Adapter | -| **INV-COMA-06 Fail-Closed Provider-Sicherheit** | **Expliziter Opt-in Guard (`KimiAdapter`)** | Offene Ausführung | Offene Ausführung | Stille Fehler / unbehandelte Exceptions | Stiller Fallback / Halluzinationen | -| **INV-COMA-07 Bounded Probe Cleanup** | **Timeouts & Kindprozess-Bereinigung** | Heartbeat-Checks mit Broker-Timeouts | Serverseitige Worker-Timeouts | Hinterlässt verwaiste Zombie-Prozesse | Cloud Container-Timeout | -| **INV-COMA-08 Idempotente Starter** | **Marker-Wächter auf `START.bat`/`start.sh`** | Keine | CLI-Scaffolder | Manuelle Shell-Skripte | Cloud Web-Dashboard | -| **INV-COMA-09 Nutzermodus-Ausführung** | **Strikt `RunAsInvoker` (Unprivilegiert)** | Erfordert oft Daemon/Systemd-Dienst | Erfordert oft Systemdienste | Erbt Elternprozess-Rechte | Container- oder Cloud-VM-Privilegien | -| **INV-COMA-10 48h Sicherheits-SLA** | **48h Bestätigung & 5 Werktage Triage** | Variable Open-Source-Tracker | Enterprise-SLA ($$$) / Community | Keine | SaaS-SLA (Kommerzieller Account erforderlich) | +## 9. COMA-Verhalten und Grenzen + +| Dimension | COMA-Verhalten und Grenze | +|---|---| +| Auftragskoordination | Lokales Verzeichnis und dateibasiertes Job-Protokoll. | +| Direkte Python-Laufzeitpakete | In pyproject.toml sind keine deklariert; dies sagt nichts über Anbieter-CLIs oder deren Abhängigkeiten aus. | +| Netzwerkverhalten | COMA selbst stellt keinen Netzwerkdienst bereit. Gestartete CLIs können Anbieter oder andere Dienste kontaktieren. | +| Kanalparallelität | Aufrufer ordnen jedem Kanal einen Schreiber zu. Rollenprüfungen sind keine Betriebssystem-Sperren oder Identitätsprüfung. | +| Prozessrechte | Anbieter-CLIs erben Rechte des startenden Prozesses; COMA isoliert sie nicht in einer Sandbox. | +| Sondenbereinigung | Timeout und plattformabhängiger Bereinigungsversuch; Kindprozesse können bestehen bleiben. | +| Sicherheitsmeldungen | Maintainer dokumentieren Bestätigungs- und Triage-Ziele in SECURITY.md. | + --- @@ -357,9 +294,9 @@ flowchart TD end subgraph Layer2 ["2. Queue & Protokoll-Verzeichnis"] - B1 --> C1["_agentjobs/IN/"] - C2["_agentjobs/OUT/"] - C3["_agentjobs/DONE/"] + B1 --> C1["agent-work/IN/"] + C2["agent-work/OUT/"] + C3["agent-work/DONE/"] end subgraph Layer3 ["3. COMA Kern-Lebenszyklus-Engine"] @@ -371,12 +308,12 @@ flowchart TD subgraph Layer4 ["4. Multi-Provider CLI-Adapter"] D2 --> E1["ClaudeAdapter"] D2 --> E2["CodexAdapter"] - D2 --> E3["AntigravityAdapter"] - D2 --> E4["KimiAdapter (Fail-Closed)"] + D2 --> E3["AgyAdapter"] + D2 --> E4["Kimi: Opt-in über Spawner/Sitzung"] end - subgraph Layer5 ["5. Isolierte OS-Prozesse & Streaming-Kanäle"] - E1 & E2 & E3 & E4 -->|"Startet unprivilegierten Prozess"| F1["Isolierter Agenten-Prozess"] + subgraph Layer5 ["5. Agenten-CLI-Subprozesse & Kanäle"] + E1 & E2 & E3 & E4 -->|"Startet Subprozess; Rechte des Aufrufers geerbt"| F1["Agenten-CLI-Subprozess"] F1 -->|"Fortschritts-Events"| G1["OUT/coma..from-agent.jsonl"] F1 -->|"Ergebnis-Datei"| G2["OUT/.result.md"] F1 -->|"Konsolen-Logs"| G3["OUT/coma..console.log"] @@ -400,7 +337,7 @@ sequenceDiagram participant Archive as "Job Archive (DONE/)" Orchestrator->>Board: "submit(job_id, prompt_markdown)" - Note over Board: "Single Writer: Orchestrator schreibt IN/.md" + Note over Board: "Schreiberzuordnung: Aufrufer koordiniert IN/.md" Orchestrator->>Runner: "run(job_id) (oder Hintergrund-Watcher)" Runner->>Board: "Liest Prompt & sichert Single-Worker-Lease" Runner->>Adapter: "build_cmd(prompt, options) -> Prozessfreies argv" @@ -430,22 +367,22 @@ sequenceDiagram -## 11. Governance & 10 Laufzeit-Invarianten +## 11. Governance & Laufzeitverträge -COMA wahrt Systemstabilität, Sicherheit und Nachvollziehbarkeit über 10 verbindliche Invarianten: +Die folgende Tabelle trennt Implementierungsverhalten, Aufruferkonventionen und Maintainer-Politik: | ID | Invariante | Beschreibung | |---|---|---| -| **INV-COMA-01** | **Single-Writer-Regel** | Jede Kanal-Datei in `_agentjobs/` hat exakt einen Schreiber (`IN/` durch Einreicher, `to-agent.jsonl` durch Orchestrator, `from-agent.jsonl`/`result.md` durch Agent, `coma..json` durch Runner). Verhindert Race Conditions und Lock-Konflikte strukturell. | -| **INV-COMA-02** | **Zero Network Egress** | Die Kernbibliothek führt 0 Netzwerkaufrufe durch, öffnet keine Ports und hat null externe Laufzeit-Paketabhängigkeiten. Ausschließlich Standardbibliothek. | -| **INV-COMA-03** | **Session-Entkopplung** | Subprozesse laufen in eigenständigen OS-Prozessbäumen außerhalb interaktiver Terminal-Sessions und umgehen damit Remote-Control-Rechteabfrage-Hänger. | +| **INV-COMA-01** | **Kanalschreiber-Konvention** | Aufrufer müssen jedem Kanal einen Schreiber zuordnen. Rollenprüfungen sind weder OS-Sperren noch Identitätsprüfung; Aufrufer koordinieren Parallelität. | +| **INV-COMA-02** | **Direkte Laufzeitpakete** | pyproject.toml deklariert keine direkten externen Python-Laufzeitpakete. COMA selbst stellt keinen Netzwerkdienst bereit; gestartete CLIs können Netzwerke und Dienste nutzen. | +| **INV-COMA-03** | **Subprozess-Lebenszyklus** | Anbieter-CLIs starten als Subprozesse. Rechte, Netzwerkzugriff und Berechtigungsverhalten folgen der CLI und Startumgebung; COMA bietet keine Sandbox. | | **INV-COMA-04** | **Prozessfreie Dry-Runs** | Befehlsbauer (`build_cmd`, `build_session_plan`, `--dry-run`) konstruieren Argumentlisten deterministisch, ohne Prozesse zu starten oder Tokens zu verbrauchen. | | **INV-COMA-05** | **Deterministischer CLI-Fallback** | Multi-Provider-Fallback-Ketten (`ordered_candidates`) lösen Binaries systematisch auf, ohne unbestätigte Engines stillschweigend auszuführen. | -| **INV-COMA-06** | **Fail-Closed Provider-Sicherheit** | Unverifizierte Adapter (wie Kimi) bleiben strikt Fail-Closed und lehnen echte Prompt-Läufe ohne explizites Opt-in ab. | -| **INV-COMA-07** | **Bounded Probe Cleanup** | Erreichbarkeitsprüfungen (`probe()`) erzwingen strikte Timeouts und garantieren Kindprozess-Bereinigung zur Vermeidung von Zombie-Prozessen. | +| **INV-COMA-06** | **Kimi-Ausführung mit Opt-in** | Die Ausführung über `coma.spawn` und `coma.session` erfordert ein ausdrückliches Opt-in; rohe Adapter- oder Probe-Argumentgeneratoren setzen diese Sperre nicht durch. | +| **INV-COMA-07** | **Sondentimeout und Bereinigung** | Sonden verwenden ein Timeout und versuchen eine plattformabhängige Bereinigung. Windows fordert Prozessbaumterminierung an; Unix beendet den direkten Prozess. Nachkommen werden nicht garantiert beendet. | | **INV-COMA-08** | **Idempotente Dual-Platform-Starter** | Aus `roles[]` generierte Starter-Skripte (`START.bat`, `start.sh`) tragen Schutzmarker, die versehentliches Überschreiben eigener Skripte verhindern. | -| **INV-COMA-09** | **Unprivilegierte Nutzermodus-Ausführung** | Strikte Ausführung im normalen Benutzerkontext (`RunAsInvoker`); keinerlei Administrator-Rechte oder Treiber-Hooks erforderlich. | -| **INV-COMA-10** | **48h Sicherheits-Reaktions-SLA** | Verbindliche 48-Stunden-Reaktionszeit und Triage innerhalb von 5 Werktagen für alle gemeldeten Sicherheitsrisiken. | +| **INV-COMA-09** | **Geerbte Rechte** | Kindprozesse erben die Rechte des startenden Prozesses. COMA fordert keine Erhöhung an, gibt keine Rechte ab und bildet keine Sicherheitsgrenze. | +| **INV-COMA-10** | **Maintainer-Antwortpolitik** | SECURITY.md nennt Ziele für Bestätigung innerhalb von 48 Stunden und Triage innerhalb von 5 Werktagen. | --- @@ -482,11 +419,11 @@ COMA wahrt Systemstabilität, Sicherheit und Nachvollziehbarkeit über 10 verbin ## 13. Tests & Verifikationssuite ```bat -python -m pytest -q :: 313 bestanden +python -m pytest -ra -v ``` -Tests starten niemals echte Provider. Ein beschränkter Probe-Test nutzt den lokalen -Python-Interpreter als unschädliche Test-CLI; alle übrigen Subprozess-Aufrufe sind gemockt. +Tests mocken die Ausführung von Anbieter-CLIs; die Suite ist keine Live-Anbieter-Verifikation. +Ein Sondentest startet einen kontrollierten lokalen Python-Prozess, um Erreichbarkeit zu prüfen. --- @@ -498,13 +435,7 @@ Python-Interpreter als unschädliche Test-CLI; alle übrigen Subprozess-Aufrufe ## 14. Drittanbieter-Lizenzen & Level 1 SBOM -COMA erzwingt ein auditiertes **Level 1 Software Bill of Materials (SBOM)** mit Null externen Laufzeit-Abhängigkeiten (`INV-COMA-02`): - -- **Kern-Laufzeit:** 100% Python-Standardbibliothek ([PSF License 2.0](https://docs.python.org/3/license.html)). -- **Zero-Copyleft-Isolationsgarantie:** Ausschließlich permissive Lizenzen (MIT / PSF-2.0 / Apache-2.0). Kein virales Copyleft. -- **Unprivilegierte Ausführung:** Zertifiziert für Standard-Nutzermodus (`RunAsInvoker`). -- **Vollständiges SBOM- & Lizenzverzeichnis:** Dokumentiert in [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md) mit detailliertem SPDX-Inventar und 10-Invarianten-Konformitätsmatrix. - +Das Projekt steht unter der MIT-Lizenz. [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md) inventarisiert das Projekt und die dort aufgeführten Python-Pakete. Es zertifiziert nicht die Lizenzen separat installierter Agenten-CLIs, Anbieter-Dienste, der Python-Laufzeit oder von Build-Werkzeugen. pyproject.toml deklariert keine direkten externen Python-Laufzeitpakete. --- @@ -532,7 +463,14 @@ COMA ist integraler Bestandteil der `ellmos-ai`-Architektur und des `open-bricks | **Agenten-Bootstrap** | [`dev-bricks/safe-start-for-codex`](https://github.com/dev-bricks/safe-start-for-codex) | Sicherer Start, Umgebungsprüfungen & Preflight-Diagnostik | | **Dach-Ökosystem** | [`open-bricks`](https://github.com/open-bricks) | Open-Source-Fundament für lokale Entwicklerwerkzeuge | -- [Swarm AI](https://github.com/ellmos-ai/swarm_ai) nutzt COMAs Spawner- und Adapter-APIs optional für anbieterbasierte Workflows. +Dokumentierte Integrationen in öffentlichen Repositories sind optional oder auf eine bestimmte Integrationsstelle begrenzt; sie begründen keine harte Abhängigkeit: + +- [swarm_ai](https://github.com/ellmos-ai/swarm_ai) nutzt COMA Spawner- und Adapter-APIs für anbieterbasierte Workflows. +- [marblerun](https://github.com/ellmos-ai/marblerun) integriert COMA Spawner und Adapter. +- [ellmos-scheduler](https://github.com/ellmos-ai/ellmos-scheduler) integriert COMA Spawner und Adapter. +- [task-master](https://github.com/ellmos-ai/task-master) besitzt eine optionale COMA-Integration. +- [open-ocean](https://github.com/ellmos-ai/open-ocean) prüft optionale COMA-Sitzungsunterstützung und bietet einen CLI-Fallback. +- [ticket-master](https://github.com/ellmos-ai/ticket-master) verwendet COMA Starters zur Build-Zeit; es ist keine Laufzeitintegration. --- @@ -542,10 +480,9 @@ COMA ist integraler Bestandteil der `ellmos-ai`-Architektur und des `open-bricks -## 16. Sicherheitsarchitektur & Subprozess-Isolation - -Details zu Subprozess-Isolation, Single-Writer-Protokollgrenzen, Rechteverzicht (`RunAsInvoker`) und Offenlegungsrichtlinien: [`SECURITY.md`](SECURITY.md). +## 16. Sicherheitsgrenzen und Meldungen +COMA startet Anbieter-CLIs als Subprozesse. Kindprozesse erben Rechte des startenden Prozesses und können das Netzwerk nutzen; COMA bietet keine Sandbox. Kanalschreiber-Konvention, Sondenbereinigung und Meldungswege stehen in [`SECURITY.md`](SECURITY.md). --- @@ -554,11 +491,9 @@ Details zu Subprozess-Isolation, Single-Writer-Protokollgrenzen, Rechteverzicht -## 17. Gesetzlicher Hinweis & Haftungsbeschränkung (§ 521 BGB) - -> **Gesetzlicher Hinweis gemäß § 521 BGB (Gefälligkeitsrecht):** -> COMA wird als unentgeltliche Open-Source-Software ohne kommerzielle Gegenleistung zur Verfügung gestellt. Gemäß § 521 BGB haftet der Urheber ausschließlich für Vorsatz und grobe Fahrlässigkeit. Die Nutzung der Software, insbesondere das Starten von Subprozessen und die Ausführung autonomer KI-Agenten, erfolgt auf eigene Verantwortung des Anwenders. +## 17. Gesetzlicher Hinweis (§ 521 BGB) +Das Projekt wird unter der MIT-Lizenz bereitgestellt. Ob gesetzliche Vorschriften wie § 521 BGB gelten, hängt vom Rechtsverhältnis und anwendbaren Recht ab; diese Dokumentation begründet keine pauschale Haftungsfreistellung. --- diff --git a/SECURITY.md b/SECURITY.md index 6476fcd..a4804f1 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,30 +2,39 @@ ## Overview -COMA (`coma`) provides a local-first, process-isolated lifecycle spawner and session-decoupled communication protocol for autonomous AI agents. Security in COMA centers around predictable process invocation, strict filesystem boundary separation, and zero external network exposure. +COMA (`coma`) starts agent command-line tools as subprocesses and coordinates work through local files. COMA itself does not implement a network service. A launched agent CLI may contact its provider or other services; COMA does not sandbox that process or block its network access. ## Security Architecture & Principles -### 1. Local-First & Zero Network Exposure -- COMA operates strictly with standard local OS processes (`subprocess.Popen` / `subprocess.run`) and filesystem paths (`IN/`, `OUT/`, `DONE/`). -- COMA requires **zero network dependencies**, opens no listening ports, makes no background HTTP/socket requests, and has no cloud server telemetry. +### 1. Local Files, Runtime Dependencies, and Data Flow -### 2. Single-Writer File Protocol -- The job board protocol utilizes distinct single-writer files per channel: - - `IN/.md`: Written exclusively by the orchestrator / job submitter. - - `OUT/coma..json`: Written exclusively by the `JobRunner`. - - `OUT/coma..from-agent.jsonl`: Written exclusively by the agent process. - - `OUT/coma..to-agent.jsonl`: Written exclusively by the orchestrator. - - `OUT/.result.md`: Written exclusively by the completing agent. -- This deterministic separation prevents race conditions and cross-agent concurrency hazards without distributed locks. +- COMA's job board, channels, status, and result handling use local filesystem paths. +- The package declares no direct external Python runtime package dependencies. This describes package dependencies, not the network behavior of child processes. +- Job prompts, instructions, process output, and results may be stored in the configured job directory and log files. Provider CLIs receive their configured arguments and inherit the launching process's environment; review workspace permissions, log contents, and environment variables accordingly. +- COMA does not provide network isolation, a firewall, or an air-gap mode. -### 3. Subprocess Isolation & Non-Elevation -- COMA spawns agent CLI processes with explicit argument arrays, preventing shell-injection vulnerabilities (`shell=False`). -- COMA does not elevate privileges or execute commands as root/administrator. -- Permission modes (`--dangerously-skip-permissions`, `dontAsk`) and tool whitelists (`--allowedTools`, `--disallowedTools`) are configurable via CLI adapters (`ClaudeAdapter`, `CodexAdapter`, `AgyAdapter`, `KimiAdapter`) with safe defaults. +### 2. Channel Writer Convention -### 4. Deterministic Mocking in Test Suites -- Test suites run 100% locally with mocked subprocess calls to avoid accidental token consumption, unexpected execution, or remote side effects. +- Callers assign one writer to each channel file as a protocol convention. +- Optional role checks in `Channel.append` do not provide OS-level locking or identity enforcement. They do not prevent multiple processes using the same role from writing concurrently. +- Callers are responsible for coordinating writers when concurrent access is possible. Distinct channel files alone do not prevent races. + +### 3. Process Invocation and Permissions + +- COMA builds explicit argument arrays and uses subprocess APIs without a shell for provider CLI invocation. +- Child processes inherit the launching process's privileges and environment. COMA does not request elevation or drop privileges, and it is not a security isolation boundary. +- Adapter profiles differ. For example, Claude's `dontAsk` profile allows Read, Edit, Write, Bash, Glob, and Grep; MCP is off by default. Its separate `read_only` preset limits tools to Read, Glob, and Grep. `bat_compat` expands permissions and can enable `bypassPermissions` and MCP. Codex defaults to `read-only`; its `write` profile uses workspace-write, and `danger-full-access` can be configured. Users remain responsible for selecting a provider profile and reviewing the provider CLI's permission and network behavior. +- Claude Code, Codex, Antigravity/AGY, and Kimi are independently developed products. Naming them as adapter targets does not imply endorsement, certification, or an official relationship. + +### 4. Probe Timeouts and Cleanup + +- Reachability probes use a timeout and attempt to clean up the process they start. +- Cleanup is best-effort and platform-dependent. On Windows COMA requests termination of the process tree; on Unix it kills the direct process. This does not guarantee termination of every descendant. + +### 5. Test Scope + +- Tests mock provider CLI execution; no test suite result is a live-provider verification. +- A probe test starts a controlled local Python process to check reachability. ## Supported Versions @@ -42,12 +51,14 @@ If you discover a security vulnerability or execution hazard within COMA: 1. **Do not open a public issue.** 2. Report the vulnerability privately via GitHub Security Advisories at [https://github.com/ellmos-ai/coma/security/advisories](https://github.com/ellmos-ai/coma/security/advisories). 3. If GitHub Advisories is unavailable, contact the security team directly: - - Primary Security Contact: `security@ellmos.ai` - - Umbrella Security: `security@open-bricks.org` - - Lead Maintainer: `lukas@open-bricks.org` / `support@lukasgeiger.com` + - Primary Security Contact: security@ellmos.ai + - Umbrella Security: security@open-bricks.org + - Lead Maintainer: lukas@open-bricks.org / support@lukasgeiger.com 4. Include a minimal reproduction case, details of the adapter/OS environment, and expected vs. actual behavior. -### Response SLA & Disclosure Timeline +### Maintainer Response Policy + +Maintainers commit to the following response targets for reports received through the channels above: - **Initial Acknowledgment:** Within **48 hours** of receiving your report. - **Triage & Status Assessment:** Within **5 business days** with an initial remediation assessment. diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md index eaacdd1..e61f126 100644 --- a/THIRD_PARTY_LICENSES.md +++ b/THIRD_PARTY_LICENSES.md @@ -1,36 +1,36 @@ # Third-Party Licenses & Software Inventory > **Repository License:** [MIT License](LICENSE) | [Attribution Notice](NOTICE)
-> **Audited:** 2026-10-04 (Previous Audits: 2026-10-01, 2026-09-28, 2026-09-24, 2026-09-19, 2026-09-12)
-> **Status:** Invariant Confirmed — Zero External Runtime Dependencies (`INV-COMA-02`)
-> **Architecture & Security:** 100% Local-First, Zero-Egress, Single-Writer Channel Protocol, Unprivileged User-Mode (`RunAsInvoker`) +> **Inventory snapshot:** 2026-10-04 (previous snapshots: 2026-10-01, 2026-09-28, 2026-09-24, 2026-09-19, 2026-09-12)
+> **Scope:** COMA project and listed Python packages for runtime metadata, testing, and build.
+> **Process boundary:** Launched provider CLIs inherit caller privileges and environment and may access networks. --- -## 1. Executive Summary & Zero-Copyleft Isolation Guarantee +## 1. Project Scope and License Inventory -`coma` is engineered as a provider-independent, session-decoupled agent lifecycle and process orchestration interface. To preserve maximum operational reliability across multi-agent environments (Claude Code CLI, OpenAI Codex CLI, Google Antigravity / AGY CLI, Kimi Code CLI), ensure deterministic multi-OS execution (Windows, Linux, macOS), and eliminate external supply-chain attack vectors, `coma` strictly enforces the **Zero External Runtime Dependencies** invariant (**INV-COMA-02**). +The COMA project is provided under the MIT license. pyproject.toml declares no direct external Python runtime package dependencies (INV-COMA-02). This package metadata does not cover the Python runtime, build tools, separately installed agent CLIs, or provider services. -- **100% Permissive / Standard Library:** Core execution uses exclusively the Python Standard Library distributed under the Python Software Foundation License (PSFL-2.0). -- **Zero-Copyleft Isolation Guarantee:** No GPL, AGPL, or viral copyleft dependencies are incorporated into the runtime distribution. -- **Unprivileged User-Mode (`RunAsInvoker`):** `coma` executes exclusively in standard, non-elevated user space without requesting root or administrator privileges. +- COMA uses configured local filesystem paths and starts provider CLIs as subprocesses. Launched CLIs inherit the launching process's privileges and environment and may contact providers or other services. +- COMA does not provide a network sandbox, an air-gap guarantee, privilege dropping, or a security isolation boundary. +- One writer per channel is a protocol requirement for callers. Optional role checks are not OS locking or identity enforcement; callers coordinate concurrent writes. --- ## 2. Invariant Cross-Reference Matrix (INV-COMA-01 .. INV-COMA-10) -| Invariant ID | Guarantee & Scope | Enforcing Subsystem / Module | Compliance Assurance | +| Invariant ID | Behavior and Caller Scope | Subsystem / Metadata | Description and Limits | |---|---|---|---| -| **INV-COMA-01** | **Single-Writer Rule** | `coma.protocol`, `coma.channels` | Exactly one writer per channel file (`IN/`, `OUT/`, `DONE/`), eliminating race conditions and lock contention. | -| **INV-COMA-02** | **Zero External Runtime Dependencies** | `pyproject.toml`, `coma/` | Zero external runtime wheels; 100% pure Python standard library (`subprocess`, `os`, `sys`, `pathlib`, `json`, `time`). | -| **INV-COMA-03** | **Session Decoupling & RC Immunity** | `coma.spawner`, `coma.session` | Subprocesses spawn in dedicated process trees outside interactive terminal sessions, bypassing remote-control permission stalls. | +| **INV-COMA-01** | **Channel writer convention** | coma.channels | One writer per channel is a caller protocol requirement; role checks do not enforce OS locking or identity. | +| **INV-COMA-02** | **Direct runtime packages** | pyproject.toml | No direct external Python runtime package dependencies are declared; this does not describe provider CLIs or services. | +| **INV-COMA-03** | **Subprocess lifecycle** | coma.spawn, coma.session | Provider CLIs run as subprocesses and inherit caller privileges and environment; COMA does not sandbox them. | | **INV-COMA-04** | **Process-Free Dry Runs** | `coma.adapters`, `coma.session` | Command builders (`build_cmd`, `build_session_plan`, `--dry-run`) construct argument vectors without launching processes or consuming tokens. | -| **INV-COMA-05** | **Deterministic Multi-Provider Fallback** | `coma.session.candidates` | Candidate chain (`ordered_candidates`, `available_candidates`) resolves CLI binaries systematically across Claude, Codex, AGY, and Kimi. | -| **INV-COMA-06** | **Fail-Closed Provider Safety** | `coma.adapters.kimi`, `coma.session` | Unverified or experimental adapters remain strictly fail-closed unless callers explicitly opt in with an established contract. | -| **INV-COMA-07** | **Bounded Probe Cleanup** | `coma.session.probe` | Reachability probes enforce strict execution timeouts and guarantee child-process termination to prevent zombie processes. | +| **INV-COMA-05** | **Deterministic Multi-Provider Fallback** | `coma.session` | Candidate chain (`ordered_candidates`, `available_candidates`) resolves CLI binaries systematically across Claude, Codex, AGY, and Kimi. | +| **INV-COMA-06** | **Kimi execution opt-in** | `coma.spawn`, `coma.session` | Spawner/session execution of the unverified Kimi adapter requires explicit opt-in; raw adapter or probe argument construction does not enforce that gate. | +| **INV-COMA-07** | **Probe cleanup** | coma.session | A timeout and best-effort platform-dependent cleanup are used; descendant termination is not guaranteed. | | **INV-COMA-08** | **Idempotent Dual-Platform Starters** | `coma.starters` | Generated starter scripts (`START.bat`, `start.sh`) carry unique marker guards preventing accidental overwrites of custom wrappers. | -| **INV-COMA-09** | **Unprivileged User-Mode Execution** | `coma.spawner`, `coma.cli` | Strictly unprivileged user execution (`RunAsInvoker`); zero administrative elevation or driver hooks required. | -| **INV-COMA-10** | **48h Security & Governance SLA** | `SECURITY.md`, `ellmos-ai` | Committed 48-hour response SLA and 5-business-day vulnerability triage for all reported security hazards. | +| **INV-COMA-09** | **Inherited privileges** | coma.spawn | Child processes inherit the launching process privileges; COMA does not request elevation or drop privileges. | +| **INV-COMA-10** | **Maintainer response policy** | SECURITY.md | Maintainers publish acknowledgment and triage response targets. | --- @@ -41,29 +41,31 @@ | Package | Version Spec | SPDX Identifier | Scope | Upstream / Repository | Purpose | | :--- | :--- | :--- | :--- | :--- | :--- | | **Python Standard Library** | `>=3.10` | `Python-2.0` | `runtime` | [python/cpython](https://github.com/python/cpython) | Process management, JSON serialization, filesystem I/O, threading, and logging | -| *(External Wheels)* | `None` | `N/A` | `runtime` | `N/A` | Pure standard library invariant confirmed | +| *(External Wheels)* | None | N/A | runtime | N/A | No direct external Python runtime packages are declared in project metadata | ### Development, Test & Build Tooling | Package / Tool | Version Spec | SPDX Identifier | Scope | Upstream / Repository | Purpose | | :--- | :--- | :--- | :--- | :--- | :--- | | **[pytest](https://pytest.org/)** | `>=8.0.0` | `MIT` | `[test]` | [pytest-dev/pytest](https://github.com/pytest-dev/pytest) | Automated unit, regression, contract, and metadata test suite execution | -| **[ruff](https://github.com/astral-sh/ruff)** | `>=0.5.0` | `MIT OR Apache-2.0` | `[dev]` | [astral-sh/ruff](https://github.com/astral-sh/ruff) | High-performance Python linter, style enforcer, and AST validation | +| **[ruff](https://github.com/astral-sh/ruff)** | not pinned | `MIT` | maintainer/CI tooling | [astral-sh/ruff](https://github.com/astral-sh/ruff) | Python linter used by maintainers and CI | | **[setuptools](https://github.com/pypa/setuptools)** | `>=77.0.0` | `MIT` | `[build-system]` | [pypa/setuptools](https://github.com/pypa/setuptools) | Standard PEP 517 / PEP 621 build backend and package distribution | -| **[wheel](https://github.com/pypa/wheel)** | `>=0.40.0` | `MIT` | `[build-system]` | [pypa/wheel](https://github.com/pypa/wheel) | Standard wheel binary distribution format builder | +| **[wheel](https://github.com/pypa/wheel)** | not pinned | `MIT` | `[build-system]` | [pypa/wheel](https://github.com/pypa/wheel) | Standard wheel binary distribution format builder | --- ## 4. External System-Level Binaries & CLI Adapter Targets -| Binary / CLI Target | Verified Version | SPDX / License | Scope | Purpose | +| Binary / CLI Target | Prior checked version | Terms assessed here | Scope | Purpose | | :--- | :--- | :--- | :--- | :--- | | **[Python](https://www.python.org/)** | `>=3.10` | `Python-2.0` | System Runtime | Host multi-OS runtime (`Windows`, `Linux`, `macOS`) | | **[Git](https://git-scm.com/)** | `>=2.40` | `GPL-2.0-only` | Version Control | Plan-D source-of-truth management and tag tracking | -| **[claude](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code)** | `2.1.263` | `Proprietary` | Agent Engine | Anthropic Claude Code CLI adapter target (`ClaudeAdapter`) | -| **[codex](https://github.com/openai/codex)** | `0.153.4` | `Proprietary` | Agent Engine | OpenAI Codex CLI adapter target (`CodexAdapter`) | -| **[agy](https://github.com/google/antigravity)** | `1.1.27` | `Proprietary` | Agent Engine | Google Antigravity CLI adapter target (`AntigravityAdapter`) | -| **[kimi](https://github.com/moonshot-ai/kimi-code)** | `0.31.0` | `Proprietary` | Agent Engine | Kimi Code CLI skeleton adapter target (fail-closed, `KimiAdapter`) | +| **[claude](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code)** | 2.1.263 (prior check) | Not assessed | External CLI | Anthropic Claude Code CLI adapter target (ClaudeAdapter) | +| **[codex](https://github.com/openai/codex)** | 0.153.4 (prior check) | Not assessed | External CLI | OpenAI Codex CLI adapter target (CodexAdapter) | +| **[agy](https://antigravity.google/docs/cli/overview/)** | 1.1.27 (prior check) | Not assessed | External CLI | Google Antigravity CLI adapter target (AgyAdapter) | +| **[kimi](https://github.com/MoonshotAI/kimi-code)** | legacy kimi-cli 0.31.0 (prior check; archived 2026-09-23) | Not assessed | External CLI | KimiAdapter targets the kimi-code successor; current compatibility is unverified | + +The recorded Kimi CLI check covered legacy kimi-cli 0.31.0, archived on 2026-09-23. That check does not establish compatibility with its kimi-code successor. See the [kimi-code repository](https://github.com/MoonshotAI/kimi-code) and the [successor getting-started guide](https://github.com/MoonshotAI/kimi-cli/blob/main/docs/en/guides/getting-started.md). --- @@ -91,53 +93,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -### Python Software Foundation License Version 2 (`Python Standard Library`) - -```text -PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 --------------------------------------------- - -1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and -the Individual or Organization ("Licensee") accessing and otherwise using this -software ("Python") in source or binary form and its associated documentation. - -2. Subject to the terms and conditions of this License Agreement, PSF hereby -grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, -analyze, test, perform and/or display publicly, prepare derivative works, -distribute, and otherwise use Python alone or in any derivative version, -provided, however, that PSF's License Agreement and PSF's notice of copyright, -i.e., "Copyright (c) 2001-2026 Python Software Foundation; All Rights Reserved" -are retained in Python alone or in any derivative version prepared by Licensee. - -3. In the event Licensee prepares a derivative work that is based on or -incorporates Python or any part thereof, and wants to make the derivative work -available to others as provided herein, then Licensee hereby agrees to include in -any such work a brief summary of the changes made to Python. - -4. PSF is making Python available to Licensee on an "AS IS" basis. PSF MAKES NO -REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT -LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF -MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF -PYTHON WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. - -5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON FOR ANY -INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, -DISTRIBUTING, OR OTHERWISE USING PYTHON, OR ANY DERIVATIVE THEREOF, EVEN IF -ADVISED OF THE POSSIBILITY THEREOF. -``` - -### Apache License Version 2.0 (`ruff` dual license) +### Python Software Foundation License Version 2 (Python Standard Library) -```text -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -``` +The Python Standard Library is licensed under the PSF License Version 2. See the [complete upstream license text](https://docs.python.org/3/license.html). diff --git a/THIRD_PARTY_LICENSES.txt b/THIRD_PARTY_LICENSES.txt index 0c2a3b9..2298147 100644 --- a/THIRD_PARTY_LICENSES.txt +++ b/THIRD_PARTY_LICENSES.txt @@ -1,90 +1,99 @@ THIRD-PARTY LICENSES & LEVEL 1 SBOM NOTICE Project: ellmos-ai/coma -Audited: 2026-10-04 (Previous Audits: 2026-10-01, 2026-09-28, 2026-09-24, 2026-09-19, 2026-09-12) +Inventory snapshot: 2026-10-04 (previous snapshots listed in THIRD_PARTY_LICENSES.md) Repository License: MIT License (see LICENSE) Repository Attribution Notice: NOTICE (see NOTICE) -Architecture & Security: 100% Local-First, Zero-Egress, Single-Writer Channel Protocol, Unprivileged User-Mode (RunAsInvoker), Zero External Runtime Dependencies (INV-COMA-02) +Scope: COMA repository and listed Python packages for runtime metadata, testing, and build. ================================================================================ -1. EXECUTIVE SUMMARY & ZERO-COPYLEFT ISOLATION GUARANTEE +1. PROJECT AND SUBPROCESS SCOPE ================================================================================ -COMA (Command & Communication for Autonomous Agents) is engineered as a provider-independent, -session-decoupled agent lifecycle and process orchestration interface. To preserve maximum -operational reliability across multi-agent environments (Claude Code CLI, OpenAI Codex CLI, -Google Antigravity / AGY CLI, Kimi Code CLI), ensure deterministic multi-OS execution -(Windows, Linux, macOS), and eliminate external supply-chain attack vectors, COMA strictly -enforces the Zero External Runtime Dependencies invariant (INV-COMA-02). +COMA is provided under the MIT license. pyproject.toml declares no direct +external Python runtime package dependencies (INV-COMA-02). This package +metadata does not cover the Python runtime, build tools, separately installed +agent CLIs, or provider services. -- 100% Permissive / Standard Library: Core execution uses exclusively the Python Standard - Library distributed under the Python Software Foundation License (PSFL-2.0). -- Zero-Copyleft Isolation Guarantee: No GPL, AGPL, or viral copyleft dependencies are - incorporated into the runtime distribution. -- Unprivileged User-Mode (RunAsInvoker): COMA executes exclusively in standard, non-elevated - user space without requesting root or administrator privileges. +COMA uses configured local filesystem paths and starts provider CLIs as +subprocesses. Launched CLIs inherit the launching process's privileges and +environment and may contact providers or other services. COMA does not provide +network isolation, an air-gap guarantee, privilege dropping, or a security +isolation boundary. + +One writer per channel is a caller protocol requirement. Optional role checks +are not OS locking or identity enforcement; callers coordinate concurrent +writes. Probe cleanup is best-effort and platform-dependent; descendant +termination is not guaranteed. + +This inventory describes the project and listed Python packages only. It does +not determine license terms or legal status for separately installed agent +CLIs, provider services, the Python runtime, or other build and deployment +tools. Review those terms independently. ================================================================================ -2. INVARIANT CROSS-REFERENCE MATRIX (INV-COMA-01 .. INV-COMA-10) +2. BEHAVIOR AND CALLER SCOPE ================================================================================ -Invariant ID | Operational Mandate | Technical Enforcement | License Scope ---------------+------------------------------------+--------------------------------------+------------------- -INV-COMA-01 | Single-Writer Rule | Exactly one writer per channel file | PSFL-2.0 / MIT -INV-COMA-02 | Zero External Runtime Dependencies | 100% pure standard library | PSFL-2.0 -INV-COMA-03 | Session Decoupling & RC Immunity | Dedicated process trees outside RC | PSFL-2.0 / MIT -INV-COMA-04 | Process-Free Dry Runs | Build command args without execution | PSFL-2.0 / MIT -INV-COMA-05 | Deterministic Multi-Provider Fallback| Systematic provider resolution chain| PSFL-2.0 / MIT -INV-COMA-06 | Fail-Closed Provider Safety | Experimental adapters fail-closed | PSFL-2.0 / MIT -INV-COMA-07 | Bounded Probe Cleanup | Timeout-guaranteed child termination | PSFL-2.0 / MIT -INV-COMA-08 | Idempotent Dual-Platform Starters | Safe idempotent batch & shell scripts| PSFL-2.0 / MIT -INV-COMA-09 | Unprivileged User-Mode Execution | Non-elevated user mode (RunAsInvoker)| MIT -INV-COMA-10 | 48h Security & Governance SLA | Committed response & triage SLA | SECURITY.md +Invariant ID | Behavior | Current scope and limit +--------------+----------------------------------+----------------------------------------------- +INV-COMA-01 | Channel writer convention | Caller coordinates writers; role checks are not OS locks +INV-COMA-02 | Direct runtime packages | No direct external Python runtime packages declared +INV-COMA-03 | Subprocess lifecycle | Child CLIs inherit caller privileges and environment +INV-COMA-04 | Process-free command planning | Builders construct argv; they do not start the provider CLI +INV-COMA-05 | CLI candidate resolution | Helpers resolve binaries in configured adapter order +INV-COMA-06 | Kimi execution opt-in | Spawner/session execution requires explicit opt-in; raw adapter/probe argument builders do not enforce the gate +INV-COMA-07 | Probe cleanup | Timeout and best-effort cleanup; descendants not guaranteed +INV-COMA-08 | Starter generation | Generated wrappers use marker guards +INV-COMA-09 | Inherited privileges | COMA does not drop privileges or provide a sandbox +INV-COMA-10 | Maintainer response policy | SECURITY.md publishes acknowledgment and triage targets ================================================================================ -3. ZERO-COPYLEFT ISOLATION GUARANTEE & RUNASINVOKER CERTIFICATION +3. RUNTIME DEPENDENCY INVENTORY ================================================================================ -1. Zero-Copyleft Guarantee: No component of COMA links against, vendors, - or invokes any code under GPLv1, GPLv2, GPLv3, AGPLv3, LGPL, SSPL, or CC-BY-SA - copyleft licenses. All dependencies and tools are strictly permissive (MIT, PSFL-2.0). -2. Unprivileged Execution (RunAsInvoker): COMA requires no administrative - privileges, no daemon services, and no root credentials. It operates entirely - in unprivileged user space. -3. Zero-Egress Perimeter: By default, no network traffic is emitted by COMA. - All agent communication is handled locally via the file-system protocol (IN/, OUT/, DONE/). +Package Role / Functional Scope License Upstream +-----------------------+------------------------------------------------+-------------+--------------------- +Python Standard Library Host Python runtime, not a project wheel Python-2.0 python/cpython +External runtime wheels None declared in pyproject.toml N/A N/A ================================================================================ -4. RUNTIME DEPENDENCY MATRIX (LEVEL 1 SBOM) +4. DEVELOPMENT, TEST, AND BUILD TOOLS ================================================================================ -Package Role / Functional Scope License Upstream ------------------------+------------------------------------------------------+---------+--------------------- -Python Standard Library Process management, JSON, filesystem I/O, threading PSFL-2.0 python/cpython -(External Wheels) None (Zero external runtime dependencies confirmed) N/A N/A +Package Usage & Purpose License Source / Upstream +-----------------------+------------------------------------------------+-------------+--------------------- +pytest Test extra MIT pytest-dev/pytest +ruff Maintainer/CI lint tooling MIT astral-sh/ruff (not pinned) +setuptools PEP 517 / PEP 621 build backend MIT pypa/setuptools +wheel Wheel distribution builder MIT pypa/wheel ================================================================================ -5. DEVELOPMENT & QUALITY ASSURANCE TOOLING +5. EXTERNAL SYSTEM-LEVEL TOOLS ================================================================================ -Package Usage & Purpose License Source / Upstream ------------------------+------------------------------------------------------+---------+--------------------- -pytest (>=8.0.0) Automated unit, regression, and contract test runner MIT pytest-dev/pytest -ruff (>=0.5.0) High-performance Python linter and style enforcer MIT/Apache astral-sh/ruff -setuptools (>=77.0.0) PEP 517 / PEP 621 packaging and build backend MIT pypa/setuptools -wheel (>=0.40.0) Standard wheel distribution builder MIT pypa/wheel +Python, Git, and provider CLIs are installed and licensed separately from +COMA. This inventory does not certify their current versions, licenses, or +terms. ================================================================================ -6. EXTERNAL SYSTEM-LEVEL BINARIES & CLI ADAPTER TARGETS +6. PRIOR LOCAL CLI COMPATIBILITY CHECKS ================================================================================ -Binary / Target Verified Version License Scope Purpose ------------------------+--------------------+-------------+----------------+---------------------------------- -Python >=3.10 PSFL-2.0 System Runtime Multi-OS host runtime -Git >=2.40 GPL-2.0-only Version Control Source repository management -claude 2.1.263 Proprietary Agent Engine Anthropic Claude Code CLI adapter -codex 0.153.4 Proprietary Agent Engine OpenAI Codex CLI adapter -agy 1.1.27 Proprietary Agent Engine Google Antigravity CLI adapter -kimi 0.31.0 Proprietary Agent Engine Kimi Code CLI skeleton adapter +The versions below record prior checks, not current support guarantees, +certification, or live-provider verification. License terms are not assessed +by this project inventory. + +Adapter CLI target Prior checked version Scope +------- -------------------------------- --------------------- -------------------------- +claude Anthropic Claude Code CLI 2.1.263 Prior flag compatibility +codex OpenAI Codex CLI 0.153.4 Prior compatibility check +agy Google Antigravity / AGY CLI 1.1.27 Prior compatibility check +kimi legacy kimi-cli 0.31.0 prior check Archived 2026-09-23; not successor proof + +The recorded Kimi CLI check covered legacy kimi-cli 0.31.0, archived on 2026-09-23. +That check does not establish compatibility with the kimi-code successor. +Successor sources: https://github.com/MoonshotAI/kimi-code +https://github.com/MoonshotAI/kimi-cli/blob/main/docs/en/guides/getting-started.md ================================================================================ 7. LICENSE TEXTS & ATTRIBUTION @@ -111,15 +120,5 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 (Python Standard Library) ---------------------------------------------------------------------- -1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and -the Individual or Organization ("Licensee") accessing and otherwise using this -software ("Python") in source or binary form and its associated documentation. - -2. Subject to the terms and conditions of this License Agreement, PSF hereby -grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, -analyze, test, perform and/or display publicly, prepare derivative works, distribute, -and otherwise use Python alone or in any derivative version, provided, however, that -PSF's License Agreement and PSF's notice of copyright, i.e., "Copyright (c) 2001-2026 -Python Software Foundation; All Rights Reserved" are included in Python alone or -in any derivative version prepared by Licensee. +The complete upstream license text is available at: +https://docs.python.org/3/license.html diff --git a/TODO.md b/TODO.md index 98c501a..8a637bd 100644 --- a/TODO.md +++ b/TODO.md @@ -1,29 +1,29 @@ # TODO.md — Active work **Version:** 0.3.2 -**Updated:** 2026-09-24 -**Reason:** Standardization, NOTICE attribution, multi-host lock defense, gate readiness, and AI discoverability +**Updated:** 2026-10-11 +**Reason:** Current implementation scope, documentation accuracy, and repository hygiene **Purpose:** Track only work that remains open. ## STATUS | Category | Status | Evidence / next gate | |---|---|---| -| Core Spawner & Adapters | DONE | Process-free command generation, mocked runner execution, Claude/Codex/AGY verified, Kimi fail-closed; verified by 260 automated tests (100% green). | -| Multi-Channel Job Protocol | DONE | IN/OUT/DONE queues, single-writer channels (`coma..json`, `to-agent.jsonl`, `from-agent.jsonl`, `result.md`, `console.log`), atomic moves. | -| Session Planning & Probing | DONE | Process-free `build_session_plan`, deterministic `ordered_candidates`, bounded reachability `probe` with child-process cleanup. | +| Core Spawner & Adapters | DONE | Command construction and mocked execution are covered; prior Claude/Codex/AGY checks are historical compatibility notes, not current certification. Kimi remains unverified and fail-closed by default. | +| Multi-Channel Job Protocol | DONE | IN/OUT/DONE queues and channel files; callers assign one writer per channel. Role checks are not OS locks or identity enforcement. | +| Session Planning & Probing | DONE | Session planning constructs argv; reachability probes use a timeout and best-effort platform-dependent cleanup. Descendant termination is not guaranteed. | | Starters Generator | DONE | Dual-platform `START.bat` and `start.sh` generation from module `roles[]` with idempotent marker guards. | -| Path Neutrality & Hygiene | DONE | Neutral environments, standard `.gitignore` patterns, zero personal paths, zero secrets. | +| Path Neutrality & Hygiene | DONE | Reviewed tracked files for known host-path patterns and common credential markers; this bounded check does not certify that no secrets exist. | | AI Discoverability & Metadata | DONE | Machine-readable `llms.txt`, PEP 621 classifiers, PEP 639 license inventory, schema v2 metadata parity. | | CI Workflows & Multi-Host Defense | DONE | Multi-OS/Python GitHub Actions with timeouts, stale triage workflow, hardened .gitignore. | -| Ecosystem Integration | DONE | Registered in `.MODULES/.ORCHESTRATION/coma`, Plan-D pointer configured, shared under `ellmos-ai` and `open-bricks`. | -| Public Release Gate | USER | MIT License selected; explicit public visibility approval pending from user. | +| Ecosystem Integration | DONE | Public repositories document optional integrations and specific use points; they do not imply hard dependencies. | +| Public source and package status | CURRENT | GitHub source is public; version 0.3.2 remains frozen. Install from the canonical Git repository; the PyPI name coma belongs to a different project. | ## Formalized next tasks - [ ] **TASK-COMA-01: Kimi-Live-Verifikationsgate** (`effort=special`, `scope=kimi`, priority `normal`). - - **Ziel:** Sobald Kimi Code CLI über einen autorisierten interaktiven Promptlauf-Vertrag verfügt, Verifikationsflag in `coma/session.py` und `coma/adapters/kimi.py` von Skeleton auf Verified heben. - - **Definition of Done:** End-to-End Test mit Kimi-CLI-Prozess in isolierter Sandbox; Dokumentation in `BEFUNDE.md` und `KONZEPT.md`. + - **Ziel:** Sobald die aktuelle `kimi-code`-Nachfolge-CLI über einen autorisierten interaktiven Promptlauf-Vertrag verfügt, Verifikationsflag in `coma/session.py` und `coma/adapters/kimi.py` von Skeleton auf Verified heben. Der frühere Check von `kimi-cli` 0.31.0 (archiviert am 2026-09-23) belegt keine Kompatibilität mit dem Nachfolger. + - **Definition of Done:** End-to-End-Test mit der aktuellen `kimi-code`-CLI nach einem autorisierten Promptlauf-Vertrag; aktuelle Adaptergrenzen in `KONZEPT.md` dokumentieren. - [ ] **TASK-COMA-02: Zentrale Multi-Agent-Registry** (`effort=large`, `scope=registry`, priority `normal`). - **Ziel:** Zentrale Schnittstelle für die Orchestrierung dynamischer Agentenflotten über COMA-Prozess-Spawner. diff --git a/coma/__init__.py b/coma/__init__.py index b0dce2d..cc6d628 100644 --- a/coma/__init__.py +++ b/coma/__init__.py @@ -8,13 +8,13 @@ ``poll``, ``result`` — ein Koordinator wie Roshambo spricht ``claim``, ``release``, ``remember``, ``recall``, ``decide``, ``status``. -Arbeitet mit Dateien und Prozessen: **ohne Konto, ohne Netz, ohne Cluster.** +COMA selbst nutzt lokale Dateien und Subprozesse und stellt keinen Netzwerkdienst bereit. Gestartete Agenten-CLIs können Anbieter und andere Dienste kontaktieren; COMA isoliert sie nicht und sperrt ihren Netzzugriff. Kurzform:: from coma import JobBoard, JobRunner - board = JobBoard(r"C:\\…\\_control-center\\_agentjobs") + board = JobBoard("path/to/agent-work") result = JobRunner(board).run("meinjob") print(result["status"]["state"], result["result_written"]) diff --git a/coma/adapters/claude.py b/coma/adapters/claude.py index e8d8d86..f37b91b 100644 --- a/coma/adapters/claude.py +++ b/coma/adapters/claude.py @@ -22,7 +22,7 @@ ``--verbose``, ``--safe-mode``, ``CLAUDECODE``-Bereinigung -``_control-center/START-LOCAL-AGENT.bat:72`` Standardkonfiguration +``START-LOCAL-AGENT.bat:72`` Standardkonfiguration (Modell ``opus``, Zeiger-Prompt) =============================================================== ========================== diff --git a/coma/manifest.py b/coma/manifest.py index 9572ee4..c444810 100644 --- a/coma/manifest.py +++ b/coma/manifest.py @@ -22,7 +22,7 @@ "module": "coma", "version": "0.1.0", "vendored_at": "2026-07-26T12:00:00", - "source": "C:/_Local_DEV/repos/coma/coma", + "source": "path/to/coma", "path": "third_party/coma", "files": {"spawn.py": "sha256:…", "adapters/claude.py": "sha256:…"} } diff --git a/coma/status.py b/coma/status.py index 3cb2ac6..9493d34 100644 --- a/coma/status.py +++ b/coma/status.py @@ -1,6 +1,6 @@ """Der Statusschreiber — **einziger** Schreiber von ``coma..json``. -Vorlage: ``_control-center/_agentjobs/coma_status.py``. Die Schluessel sind +Vorlage: eine bestehende JSON-Statusdatei. Die Schlüssel sind zeichengleich uebernommen (``job_id``, ``state``, ``model``, ``started``, ``finished``, ``job_file``, ``result_file``, ``exit_code``), damit die bestehende Startschale und diese Python-Schicht dieselbe Datei lesen und schreiben koennen. diff --git a/ellmos-module.v2.json b/ellmos-module.v2.json index b0eebfd..6492755 100644 --- a/ellmos-module.v2.json +++ b/ellmos-module.v2.json @@ -7,7 +7,7 @@ "kind": "runtime", "status": "development", "visibility": "public", - "description": "Provider-unabhängige Orchestrierungs- und Lebenszyklus-Schicht für Agentenprozesse. Spawn-Schicht mit verifizierten CLI-Adaptern für Claude, Codex und Agy sowie fail-closed Kimi-Gerüst, Datei-Protokoll mit einem Schreiber je Datei, Statusschreiber und Poll-Hilfen. COMA ist kein Scheduler, sperrt nichts, verwaltet keine Rechte und hält kein Gedächtnis.", + "description": "Provider-unabhängige Orchestrierungs- und Lebenszyklus-Schicht für Agentenprozesse. COMA konstruiert CLI-Aufrufe für Claude, Codex und AGY; historische Kompatibilitätschecks sind keine aktuellen Live-Garantien. Der Kimi-Adapter ist unverifiziert und nur über Spawner/Session opt-in ausführbar. Aufrufer müssen Kanal-Schreiber eigenständig zuordnen und parallele Zugriffe koordinieren. Die Netzwerkgrenze beschreibt COMA selbst; gestartete Anbieter-CLIs können Netzwerkzugriff haben. COMA ist kein Scheduler, sperrt nichts, verwaltet keine Rechte und hält kein Gedächtnis.", "package": "coma", "entrypoints": { "cli": "python -m coma", diff --git a/llms.txt b/llms.txt index b14e886..3a43e03 100644 --- a/llms.txt +++ b/llms.txt @@ -1,128 +1,98 @@ # COMA — Command & Communication for Autonomous Agents -> Machine-readable specification and RAG context index for `ellmos-ai/coma`.
-> Last-checked: 2026-10-04
-> Verification: 313 passed Pytest unit & contract tests (100% green).
-> Execution Mode: Standard User Mode (`RunAsInvoker`) — Zero Administrative Elevation.
-> Attribution & Notice: [NOTICE](NOTICE) | [MIT License](LICENSE) | [Level 1 SBOM (Text)](THIRD_PARTY_LICENSES.txt)
-> Statutory Notice: § 521 BGB Gefälligkeitsrecht applies. +> Machine-readable specification and RAG context index for ellmos-ai/coma. +> Updated: 2026-10-11 | Current package version: 0.3.2 (frozen). +> Install from the canonical Git repository. The PyPI name `coma` belongs to a different project. -## Overview +## Scope -COMA (`coma`) is a zero-dependency, local-first **agent lifecycle layer and session-decoupled communication channel**. It manages how autonomous AI agents (such as Claude Code CLI, OpenAI Codex CLI, Google Antigravity / AGY CLI, and Kimi Code CLI) are spawned as independent subprocesses, monitored during execution, and communicated with via a file-based job board protocol. +COMA coordinates jobs through local files and starts agent command-line tools as subprocesses. COMA itself does not implement a network service. A launched CLI may contact its provider or other services, require an account, and access the network. COMA does not sandbox child processes or block their network access. -COMA operates purely on local files and standard processes—without external network services, databases, cloud servers, or user accounts. Zero external runtime dependencies (`INV-COMA-02`). +The project declares no direct external Python runtime package dependencies in `pyproject.toml`. This describes COMA package metadata; it does not describe dependencies, permissions, or network behavior of agent CLIs, Python itself, or build tools. -## Core Architecture & Responsibilities +## Core responsibilities -| Layer | Responsibility | Handled By | -|---|---|---| -| **Lifecycle & Spawner** | Process creation, CLI argument formatting, subprocess execution, stdout/stderr logging | **COMA (`coma.spawner`, `coma.adapters`)** | -| **Decoupled Communication** | Session-independent job submission, progress tracking, status reporting, result retrieval | **COMA (`coma.protocol`, `coma.board`, `coma.runner`)** | -| **Session Planning** | Process-free argv planning for interactive and headless sessions with CLI reachability probes | **COMA (`coma.session`)** | -| **Starter Generation** | Dual-platform starter scripts (`START.bat`, `start.sh`) generated from `roles[]` manifests | **COMA (`coma.starters`)** | -| **Locking & Permissions** | File access rules, claim management (optional protocol integration) | `lock-master` / Roshambo | -| **Agent Memory** | Context retention, decision history, attempt tracking | `memoryhooker` / Roshambo | +| Area | Responsibility | +|---|---| +| Job lifecycle | Create, execute, monitor, and retrieve jobs through a file-based board. | +| Session planning | Construct provider-specific argv without starting a process. | +| CLI adapters | Format arguments for provider CLIs; enforcement depends on the provider CLI. | +| Probe | Start a provider-specific reachability probe with a timeout and best-effort cleanup. | +| Starters | Generate `START.bat` and `start.sh` from a user-provided module manifest with a top-level `roles[]` array. | -## Target Personas +COMA does not provide a scheduler, access-control system, lock manager, agent memory, provider account, or security sandbox. -- **[PERSONA-01] Autonomous Agent Framework Engineers & Swarm Architects:** Designing multi-agent swarms, relay pipelines, or hierarchical agent networks. -- **[PERSONA-02] Local-First & Sovereign AI Developers:** Running AI developer toolchains locally on sovereign workstations and air-gapped systems without cloud telemetry. -- **[PERSONA-03] Remote Control & Headless Automation DevOps:** Orchestrating headless runs, scheduled tasks, or remote terminal sessions where interactive permission flags stall. -- **[PERSONA-04] Enterprise Security Officers & Systems Auditors:** Auditing software supply-chains for zero dependencies, non-elevation (`RunAsInvoker`), and 48h security SLAs. +## Job board protocol -## The File-Based Job Board Protocol +The job board uses local directories such as `IN/`, `OUT/`, and `DONE/`. Callers must assign one writer per channel file. Optional role checks are not OS-level locking or identity enforcement and do not exclude two processes using the same role. Callers coordinate concurrent writes. -Job communication uses a directory structure (`_agentjobs/`) with distinct single-writer files to eliminate file-locking collisions across sessions: +## Process and permission boundaries -``` -IN/ .md Job prompt / instruction (Markdown) -OUT/ .result.md Final result output from agent - coma..json Runner status (state: PENDING, RUNNING, DONE, FAILED) - coma..from-agent.jsonl Agent-to-runner event stream (.jsonl) - coma..to-agent.jsonl Runner-to-agent instruction stream (.jsonl) - coma..console.log Combined stdout / stderr log -DONE/ .md Completed job prompt (moved upon success) -``` - -## CLI Adapters - -COMA abstracts CLI flag differences into verified adapters: -- **`ClaudeAdapter`**: Formats flags for Anthropic Claude Code CLI (`-p`, `--permission-mode dontAsk`, `--allowedTools`, `--disallowedTools mcp__*`). -- **`CodexAdapter`**: Formats flags for OpenAI Codex CLI (`exec`, workspace-write, `--output-last-message`). -- **`AntigravityAdapter`**: Formats flags for Google Antigravity / AGY CLI (`agy`). -- **`KimiAdapter`**: Formats flags for Kimi Code CLI (fail-closed skeleton). +Agent CLIs inherit the launching process privileges and environment. COMA does not request elevation or drop privileges. Configure and review each provider CLI permission profile and environment before starting it. -## Session Planning & Starters +Adapter profiles differ. Claude `dontAsk` permits Read, Edit, Write, Bash, Glob, and Grep; its separate `read_only` preset limits tools to Read, Glob, and Grep. MCP is off by default; `bat_compat` can enable broader permissions and MCP. Codex defaults to `read-only`, `write` uses workspace-write, and `danger-full-access` can be configured. -- **`build_session_plan()`**: Constructs process-free argument lists for interactive or headless provider sessions (`Claude`, `Codex`, `AGY`, `Kimi`), keeping role prompts and requests separated. -- **`ordered_candidates()` / `available_candidates()`**: Deterministic provider fallback chain. -- **`probe()` / `build_probe_command()`**: Bounded, read-only reachability check with child-process cleanup. -- **`coma starters generate`**: Generates dual-platform `START.bat` and `start.sh` from module `roles[]` definitions with overwrite protection markers. +Probe arguments are provider-specific and do not all establish read-only access: Codex adds `--sandbox read-only`; Claude adds `--strict-mcp-config` but no general read-only sandbox; AGY and Kimi add no access restriction. Inspect argv and CLI permissions before running. Kimi opt-in applies to adapter session planning and Spawner execution; `build_probe_command()` has no separate fail-closed guard. -## Governance & 10 Runtime Invariants +On Windows probe cleanup requests process-tree termination; on Unix it kills the direct process. Cleanup is best-effort and descendant termination is not guaranteed. -- **INV-COMA-01 (Single Writer):** Exactly one writer per channel file; no distributed locking needed. -- **INV-COMA-02 (Zero Egress):** 0 network calls, 0 listening ports, standard library only. -- **INV-COMA-03 (Session Decoupling):** Spawner runs processes detached from interactive client sessions outside RC. -- **INV-COMA-04 (Process-Free Dry Runs):** Argv construction without starting processes or consuming tokens. -- **INV-COMA-05 (Deterministic CLI Fallback):** Multi-provider chains resolve binaries deterministically. -- **INV-COMA-06 (Fail-Closed Provider Safety):** Unverified adapters (Kimi) reject real prompt runs unless explicit opt-in. -- **INV-COMA-07 (Bounded Probes):** Reachability checks enforce timeouts and guarantee child-process cleanup. -- **INV-COMA-08 (Idempotent Starters):** Generated starters carry unique markers to prevent overwrites. -- **INV-COMA-09 (Unprivileged Execution):** Standard user mode execution (`RunAsInvoker`); zero root/admin elevation. -- **INV-COMA-10 (48h Security Response SLA):** Committed 48-hour response SLA and 5-business-day vulnerability triage. +## API and CLI -## Quick Python API Usage +The public Python API includes `JobBoard`, `JobRunner`, `Spawner`, `ClaudeAdapter`, `CodexAdapter`, `AgyAdapter`, `KimiAdapter` (unverified; Spawner/session execution requires explicit opt-in), `build_session_plan`, `ordered_candidates`, `available_candidates`, `build_probe_command`, and `probe`. -```python -from coma import JobBoard, JobRunner, ClaudeAdapter, Spawner, build_session_plan +Process planning builds argv only; Spawner execution starts the configured provider CLI. -# 1. Job Board Protocol -board = JobBoard(r"C:\jobs\_agentjobs") -board.submit("job123", "# Instruction\nPerform technical audit and write output to OUT/job123.result.md\n") +Examples: -# 2. Run Job via Runner -runner = JobRunner(board) -result = runner.run("job123") +```bat +python -m coma --help +python -m coma adapters +python -m pip install "git+https://github.com/ellmos-ai/coma.git" +``` -# 3. Direct Spawner Usage -adapter = ClaudeAdapter.preset("unattended") -spawner = Spawner(adapter) -handle = spawner.start("Audit code", log_file="audit.log") +For role starters, provide a user module manifest with a top-level `roles` array and a prompt file for each role. Each role needs `id`, `prompt`, `request`, and a non-empty `providers` list. The prompt path is relative to the manifest and the file must exist. `ellmos-module.v2.json` describes COMA itself and is not a role-starter manifest. -# 4. Session Planning -plan = build_session_plan("codex", prompt_file="AGENTS.md", request="Audit code", mode="headless") -print(plan.command) +```json +{ + "id": "my-module", + "roles": [ + { "id": "reviewer", "prompt": "prompts/reviewer.md", "request": "Review the current change.", "providers": ["codex"] } + ] +} ``` -## Quick CLI Usage - ```bat -coma --root C:\jobs\_agentjobs submit job123 --file prompt.md -coma --root C:\jobs\_agentjobs run job123 --dry-run -coma --root C:\jobs\_agentjobs status job123 -coma --root C:\jobs\_agentjobs result job123 -coma adapters -coma session --provider codex --prompt-file AGENTS.md --request "Audit" --dry-run -coma starters generate --manifest ellmos-module.v2.json --output-dir starters -coma check .\coma-vendor.json +coma starters generate --manifest my-module.json --output-dir starters +starters\START.bat reviewer --provider codex --dry-run ``` -## Key Documentation & RAG References +## Known integrations + +The following public repositories have documented, optional COMA integrations: + +- [swarm_ai](https://github.com/ellmos-ai/swarm_ai) uses COMA Spawner and adapter APIs for provider-backed workflows. +- [marblerun](https://github.com/ellmos-ai/marblerun) uses COMA Spawner and adapter APIs. +- [ellmos-scheduler](https://github.com/ellmos-ai/ellmos-scheduler) uses COMA Spawner and adapter APIs. +- [task-master](https://github.com/ellmos-ai/task-master) has an optional COMA integration. +- [open-ocean](https://github.com/ellmos-ai/open-ocean) checks for optional COMA session support and provides a CLI fallback. +- [ticket-master](https://github.com/ellmos-ai/ticket-master) uses COMA Starters at build time; it is not a runtime integration. + +## Tests + +The automated suite mocks provider CLI execution and does not perform live-provider verification. A probe test starts a controlled local Python process to check reachability. Test counts are available from current CI; this file does not pin a count. + +## Public documentation + +- [English README](README.md) +- [German README](README_de.md) +- [Security policy](SECURITY.md) +- [Third-party license inventory](THIRD_PARTY_LICENSES.md) +- [Plain-text license inventory](THIRD_PARTY_LICENSES.txt) +- [Changelog](CHANGELOG.md) +- [Open tasks](TODO.md) -- [`README.md`](README.md): Primary documentation and 18-point quick navigation. -- [`README_de.md`](README_de.md): German documentation and architecture overview. -- [Swarm AI](https://github.com/ellmos-ai/swarm_ai): Optional consumer of COMA's Spawner and adapter APIs for provider-backed workflows. -- [`NOTICE`](NOTICE): Formal copyright attribution (Lukas Geiger / ellmos-ai / open-bricks). -- [`KONZEPT.md`](KONZEPT.md): Architectural rationale, session-decoupling motivation, and offline design. -- [`SECURITY.md`](SECURITY.md): Process isolation, single-writer protocol boundaries, and 48h vulnerability reporting SLA. -- [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md): Level 1 SBOM, zero-dependency invariant, and unprivileged user mode certification. -- [`THIRD_PARTY_LICENSES.txt`](THIRD_PARTY_LICENSES.txt): Plain-text Level 1 SBOM companion file and full license text inventory. -- [`MARKETING-LOG.txt`](MARKETING-LOG.txt): Target personas, SEO keywords, ecosystem integrations, and release highlights. -- [`CHANGELOG.md`](CHANGELOG.md): Historical releases and semantic version log. -- [`TODO.md`](TODO.md): Release readiness gates and active task tracker. +## Legal and license notes -## Statutory Notice (§ 521 BGB) +The project is provided under the MIT license. Whether statutory rules such as section 521 BGB apply depends on the legal relationship and applicable law; this documentation does not provide a blanket exemption from liability. -Pursuant to § 521 BGB (German Civil Code), COMA is provided free of charge without consideration. Liability is limited to intent and gross negligence. +The repository license and dependency inventory do not certify separately installed agent CLIs, provider services, or build tools. Their terms apply independently. diff --git a/pyproject.toml b/pyproject.toml index 3fa3d64..c49964e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,16 +27,13 @@ keywords = [ "local-first", "messaging", "multi-agent", - "offline-first", "open-bricks", - "process-isolation", "python", "session-decoupling", "spawn", "status-polling", "subagents", "zero-dependencies", - "zero-egress", ] classifiers = [ "Development Status :: 3 - Alpha", @@ -50,9 +47,9 @@ classifiers = [ "Topic :: Software Development :: Build Tools", "Topic :: System :: Distributed Computing", ] -# Absichtlich leer. COMA arbeitet mit Dateien und Prozessen -- ohne Konto, ohne -# Netz, ohne Cluster. Das ist sein Trennungsgrund gegenüber Roshambo, nicht ein -# noch nicht erledigter Schritt. Siehe KONZEPT.md, Abschnitt "Offline". +# Absichtlich leer: COMA deklariert keine direkten externen Python-Laufzeitpakete. +# COMA nutzt lokale Dateien und Subprozesse, implementiert selbst aber keinen Netzwerkdienst. +# Gestartete Anbieter-CLIs können eigene Abhängigkeiten und Netzzugriff haben. dependencies = [] [project.optional-dependencies] @@ -71,7 +68,6 @@ Security = "https://github.com/ellmos-ai/coma/blob/main/SECURITY.md" Notice = "https://github.com/ellmos-ai/coma/blob/main/NOTICE" "Plain-Text License" = "https://raw.githubusercontent.com/ellmos-ai/coma/main/LICENSE" "LLM Ready" = "https://github.com/ellmos-ai/coma/blob/main/llms.txt" -"Marketing Log" = "https://github.com/ellmos-ai/coma/blob/main/MARKETING-LOG.txt" "Level 1 SBOM" = "https://github.com/ellmos-ai/coma/blob/main/THIRD_PARTY_LICENSES.md" "Third-Party Licenses" = "https://github.com/ellmos-ai/coma/blob/main/THIRD_PARTY_LICENSES.md" "Third-Party Licenses (Text)" = "https://github.com/ellmos-ai/coma/blob/main/THIRD_PARTY_LICENSES.txt" diff --git a/tests/conftest.py b/tests/conftest.py index 69daabc..46f5458 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -95,7 +95,7 @@ def kill(self): # pragma: no cover - Notausgang @pytest.fixture def board(tmp_path: Path) -> JobBoard: """Ein leeres Jobverzeichnis mit IN/ OUT/ DONE/.""" - board = JobBoard(tmp_path / "_agentjobs") + board = JobBoard(tmp_path / "agent-work") board.ensure_dirs() return board diff --git a/tests/test_metadata.py b/tests/test_metadata.py index 9d4baba..5bace5a 100644 --- a/tests/test_metadata.py +++ b/tests/test_metadata.py @@ -59,9 +59,7 @@ def test_core_documentation_files(): "LICENSE", "NOTICE", "KONZEPT.md", - "BEFUNDE.md", "CHANGELOG.md", - "MARKETING-LOG.txt", "THIRD_PARTY_LICENSES.md", "TODO.md", "pyproject.toml", @@ -99,16 +97,13 @@ def test_llms_txt_structure(): content = llms_path.read_text(encoding="utf-8") assert "# COMA" in content - assert "Last-checked:" in content - assert "Verification:" in content + assert "Updated:" in content assert "ClaudeAdapter" in content assert "CodexAdapter" in content - assert "AntigravityAdapter" in content + assert "AgyAdapter" in content assert "KimiAdapter" in content assert "JobBoard" in content assert "JobRunner" in content - assert "INV-COMA-01" in content - assert "MARKETING-LOG.txt" in content def test_readme_badge_and_ecosystem_parity(): @@ -141,28 +136,15 @@ def test_pyproject_pep621_urls(): assert "Security" in pyproject_content assert "Notice" in pyproject_content assert "LLM Ready" in pyproject_content - assert "Marketing Log" in pyproject_content assert "Parent Organization" in pyproject_content assert "Umbrella Ecosystem" in pyproject_content -def test_marketing_log_structure(): - """Verify that MARKETING-LOG.txt exists and contains required strategic sections.""" - marketing_log_path = REPO_ROOT / "MARKETING-LOG.txt" - assert marketing_log_path.exists() - content = marketing_log_path.read_text(encoding="utf-8") - assert "Ziel-Personas" in content or "Target" in content - assert "Discoverability" in content or "SEO" in content - assert "Awesome-" in content - assert "Roadmap" in content or "Empfehlungen" in content - - def test_license_and_third_party_inventory(): """Verify THIRD_PARTY_LICENSES.md invariant and PEP 639 license-files.""" licenses_path = REPO_ROOT / "THIRD_PARTY_LICENSES.md" assert licenses_path.exists() content = licenses_path.read_text(encoding="utf-8") - assert "Zero External Runtime Dependencies" in content assert "INV-COMA-02" in content assert "MIT License" in content @@ -243,19 +225,6 @@ def test_pyproject_pytest_addopts(): assert 'addopts = "-ra -v --basetemp=.pytest_temp"' in content -def test_marketing_log_recent_hygiene_entry(): - """Verify MARKETING-LOG.txt includes recent Pfad A hygiene audit entry.""" - content = (REPO_ROOT / "MARKETING-LOG.txt").read_text(encoding="utf-8") - assert ( - "Stand: 2026-10-01" in content - or "Stand: 2026-09-28" in content - or "Stand: 2026-09-24" in content - or "Stand: 2026-09-14" in content - ) - assert "Pfad A" in content - assert "Release 0.3.1 Highlights" in content - - def test_changelog_recent_pfad_a_entry(): """Verify CHANGELOG.md documents Release 0.3.1 on 2026-09-14.""" content = (REPO_ROOT / "CHANGELOG.md").read_text(encoding="utf-8") @@ -319,36 +288,6 @@ def test_readme_18_point_navigation_parity(): assert f'id="{anchor}"' in readme_en, f"Reciprocal anchor '{anchor}' missing in README.md" -def test_target_personas_and_high_intent_queries(): - """Verify that both READMEs document 4 target personas and high-intent SEO queries.""" - readme_en = (REPO_ROOT / "README.md").read_text(encoding="utf-8") - readme_de = (REPO_ROOT / "README_de.md").read_text(encoding="utf-8") - - personas = ["[PERSONA-01]", "[PERSONA-02]", "[PERSONA-03]", "[PERSONA-04]"] - for persona in personas: - assert persona in readme_en, f"{persona} missing in README.md" - assert persona in readme_de, f"{persona} missing in README_de.md" - - assert "High-Intent Search Queries" in readme_en or "High-Intent" in readme_en - assert "High-Intent Suchbegriffe" in readme_de or "High-Intent" in readme_de - - -def test_comparative_matrix_and_invariants(): - """Verify that both READMEs include the 10-dimension comparative matrix vs alternatives.""" - readme_en = (REPO_ROOT / "README.md").read_text(encoding="utf-8") - readme_de = (REPO_ROOT / "README_de.md").read_text(encoding="utf-8") - - alternatives = ["Celery", "Temporal", "Subprocess", "LangGraph"] - for alt in alternatives: - assert alt in readme_en, f"Alternative '{alt}' missing in README.md matrix" - assert alt in readme_de, f"Alternative '{alt}' missing in README_de.md matrix" - - for i in range(1, 11): - inv_id = f"INV-COMA-{i:02d}" - assert inv_id in readme_en, f"{inv_id} missing in README.md" - assert inv_id in readme_de, f"{inv_id} missing in README_de.md" - - def test_statutory_notice_bgb_521(): """Verify statutory disclaimer pursuant to § 521 BGB in English and German.""" readme_en = (REPO_ROOT / "README.md").read_text(encoding="utf-8") @@ -358,19 +297,12 @@ def test_statutory_notice_bgb_521(): assert "521 BGB" in readme_en assert "521 BGB" in readme_de assert "521 BGB" in llms_txt - assert "Gefälligkeitsrecht" in readme_de - assert "grobe Fahrlässigkeit" in readme_de -def test_third_party_licenses_sbom_and_run_as_invoker(): - """Verify THIRD_PARTY_LICENSES.md Level 1 SBOM, RunAsInvoker, and 10 invariants.""" +def test_third_party_licenses_sbom_inventory_ids(): + """Verify the Level 1 SBOM document and invariant identifiers.""" content = (REPO_ROOT / "THIRD_PARTY_LICENSES.md").read_text(encoding="utf-8") - assert "2026-09-19" in content - assert "Audited" in content - assert "RunAsInvoker" in content - assert "Zero External Runtime Dependencies" in content - assert "Zero-Copyleft Isolation Guarantee" in content assert "Level 1 Software Bill of Materials" in content for i in range(1, 11): @@ -403,14 +335,11 @@ def test_mermaid_diagram_syntax(): assert not line_str.endswith(";"), f"Trailing semicolon found in {lang} sequence diagram: {line_str}" -def test_changelog_and_marketing_log_release_0_3_2(): - """Verify CHANGELOG.md and MARKETING-LOG.txt record Release 0.3.2.""" +def test_changelog_release_0_3_2(): + """Verify CHANGELOG.md records Release 0.3.2.""" changelog = (REPO_ROOT / "CHANGELOG.md").read_text(encoding="utf-8") - marketing = (REPO_ROOT / "MARKETING-LOG.txt").read_text(encoding="utf-8") assert "[0.3.2] — 2026-09-19" in changelog - assert "Release 0.3.2 Highlights" in marketing - assert "Pfad B" in marketing def test_notice_attribution_file(): @@ -466,13 +395,6 @@ def test_unreleased_changelog_entry(): assert ".gitignore" in content -def test_marketing_log_audit_stand_20260924(): - """Verify MARKETING-LOG.txt documents Pfad A audit stand 2026-09-24.""" - content = (REPO_ROOT / "MARKETING-LOG.txt").read_text(encoding="utf-8") - assert "2026-09-24" in content - assert "Pfad A Maintenance & Hygiene Audit (Stand 2026-09-24)" in content - - def test_readme_sec_01_to_18_anchor_parity(): """Verify that README.md and README_de.md implement sec-01 through sec-18 reciprocal anchors.""" readme_en = (REPO_ROOT / "README.md").read_text(encoding="utf-8") @@ -491,9 +413,6 @@ def test_third_party_licenses_text_companion(): content = text_path.read_text(encoding="utf-8") assert "LEVEL 1 SBOM NOTICE" in content - assert "RunAsInvoker" in content - assert "Zero External Runtime Dependencies" in content - assert "Zero-Copyleft Isolation Guarantee" in content assert "MIT LICENSE" in content assert "PYTHON SOFTWARE FOUNDATION LICENSE" in content @@ -519,16 +438,13 @@ def test_pep621_github_topics_saturation(): "local-first", "messaging", "multi-agent", - "offline-first", "open-bricks", - "process-isolation", "python", "session-decoupling", "spawn", "status-polling", "subagents", "zero-dependencies", - "zero-egress", ] for topic in topics: assert f'"{topic}"' in pyproject_content, ( @@ -537,17 +453,6 @@ def test_pep621_github_topics_saturation(): assert '"Third-Party Licenses (Text)"' in pyproject_content -def test_marketing_log_audit_stand_20260928(): - """Verify MARKETING-LOG.txt documents Pfad B audit stand 2026-09-28.""" - content = (REPO_ROOT / "MARKETING-LOG.txt").read_text(encoding="utf-8") - assert "Stand: 2026-09-28" in content - assert ( - "Pfad B Discoverability, Visual Architecture & Level 1 SBOM Audit (Stand" - " 2026-09-28)" - in content - ) - - def test_notice_third_party_text_companion(): """Verify NOTICE cross-references THIRD_PARTY_LICENSES.txt companion.""" content = (REPO_ROOT / "NOTICE").read_text(encoding="utf-8") @@ -611,7 +516,6 @@ def test_bilingual_contributing_guidelines(): content = contrib_path.read_text(encoding="utf-8") assert "Contributing to coma" in content assert "Mitwirken an coma" in content - assert "RunAsInvoker" in content assert "T-20260920-167562623" in content assert "pytest -ra -v" in content for i in range(1, 11): @@ -629,25 +533,6 @@ def test_pep621_extended_hygiene_urls(): assert '".turbo"' in pyproject_content -def test_third_party_licenses_audit_recency_20261001(): - """Verify THIRD_PARTY_LICENSES.txt and THIRD_PARTY_LICENSES.md are audited to 2026-10-01 or later.""" - txt_content = (REPO_ROOT / "THIRD_PARTY_LICENSES.txt").read_text(encoding="utf-8") - md_content = (REPO_ROOT / "THIRD_PARTY_LICENSES.md").read_text(encoding="utf-8") - assert ("Audited: 2026-10-01" in txt_content) or ("Audited: 2026-10-04" in txt_content) - assert ("Audited:** 2026-10-01" in md_content) or ("Audited:** 2026-10-04" in md_content) - for i in range(1, 11): - inv_id = f"INV-COMA-{i:02d}" - assert inv_id in txt_content, f"{inv_id} missing in THIRD_PARTY_LICENSES.txt" - assert inv_id in md_content, f"{inv_id} missing in THIRD_PARTY_LICENSES.md" - - -def test_marketing_log_audit_stand_20261001(): - """Verify MARKETING-LOG.txt documents Pfad A audit stand 2026-10-01.""" - content = (REPO_ROOT / "MARKETING-LOG.txt").read_text(encoding="utf-8") - assert "Stand: 2026-10-01" in content or "Stand: 2026-10-04" in content - assert "11. Pfad A Maintenance & Hygiene Audit (Stand 2026-10-01)" in content - - def test_gitignore_additional_multihost_guards(): """Verify .gitignore includes TASKPLAN, ehthumbs.db, and lock guards.""" content = (REPO_ROOT / ".gitignore").read_text(encoding="utf-8") @@ -658,59 +543,6 @@ def test_gitignore_additional_multihost_guards(): assert "LOCK.bugsearch.*" in content -def test_ascii_four_view_architectural_topology_parity_en_de(): - """Verify ASCII Four-View Architectural Topology presence and invariant parity across README.md and README_de.md.""" - readme_en = (REPO_ROOT / "README.md").read_text(encoding="utf-8") - readme_de = (REPO_ROOT / "README_de.md").read_text(encoding="utf-8") - - assert "ASCII Four-View Architectural Topology" in readme_en - assert "ASCII Vier-Sichten-Architekturtopologie" in readme_de - - for view in ["[VIEW 1:", "[VIEW 2:", "[VIEW 3:", "[VIEW 4:"]: - assert view in readme_en, f"{view} missing in README.md" - - for sicht in ["[SICHT 1:", "[SICHT 2:", "[SICHT 3:", "[SICHT 4:"]: - assert sicht in readme_de, f"{sicht} missing in README_de.md" - - for i in range(1, 11): - inv_id = f"INV-COMA-{i:02d}" - assert inv_id in readme_en, f"{inv_id} missing in README.md topology" - assert inv_id in readme_de, f"{inv_id} missing in README_de.md topology" - - -def test_third_party_licenses_audit_recency_20261004(): - """Verify THIRD_PARTY_LICENSES.txt and THIRD_PARTY_LICENSES.md are audited to 2026-10-04.""" - txt_content = (REPO_ROOT / "THIRD_PARTY_LICENSES.txt").read_text(encoding="utf-8") - md_content = (REPO_ROOT / "THIRD_PARTY_LICENSES.md").read_text(encoding="utf-8") - assert "Audited: 2026-10-04" in txt_content - assert "Audited:** 2026-10-04" in md_content - for i in range(1, 11): - inv_id = f"INV-COMA-{i:02d}" - assert inv_id in txt_content, f"{inv_id} missing in THIRD_PARTY_LICENSES.txt" - assert inv_id in md_content, f"{inv_id} missing in THIRD_PARTY_LICENSES.md" - - -def test_marketing_log_audit_stand_20261004(): - """Verify MARKETING-LOG.txt documents Pfad B audit stand 2026-10-04.""" - content = (REPO_ROOT / "MARKETING-LOG.txt").read_text(encoding="utf-8") - assert "Stand: 2026-10-04" in content - assert "12. Pfad B Discoverability, Visual Architecture & Level 1 SBOM Audit (Stand 2026-10-04)" in content - assert "REC-20261004-01" in content - assert "REC-20261004-02" in content - assert "REC-20261004-03" in content - - -def test_readme_badges_audit_recency_and_test_count_313(): - """Verify Shields.io badges in README.md and README_de.md reflect 313 tests and 2026-10-04 verification.""" - readme_en = (REPO_ROOT / "README.md").read_text(encoding="utf-8") - readme_de = (REPO_ROOT / "README_de.md").read_text(encoding="utf-8") - - assert "pytest-313%20passed" in readme_en - assert "verified-2026--10--04" in readme_en - assert "pytest-313%20bestanden" in readme_de - assert "gepr%C3%BCft-2026--10--04" in readme_de - - def test_version_freeze_discipline_032(): """Verify version 0.3.2 is strictly frozen per T-20260920-167562623 across all manifests.""" pyproject_content = (REPO_ROOT / "pyproject.toml").read_text(encoding="utf-8") diff --git a/tests/test_status_and_channels.py b/tests/test_status_and_channels.py index d6f3f09..e90be3a 100644 --- a/tests/test_status_and_channels.py +++ b/tests/test_status_and_channels.py @@ -2,7 +2,7 @@ """Statusschreiber und Kanaele. Der Statustest ist ein Kompatibilitaetstest: Die Schluessel muessen denen von -``_agentjobs/coma_status.py`` entsprechen, sonst lesen ``.bat`` und +``agent-work/coma_status.py`` entsprechen, sonst lesen ``.bat`` und Python-Schicht aneinander vorbei. """ import json