# AUN / agent-com Reboot Architecture ## 0. Purpose This issue restarts the architecture/design track for `watchout/agent-comms-mcp` so that agent-com / AUN is no longer treated as a Discord bridge, queue helper, MCP wrapper, tmux manager, or Claude Code-only plugin. The target product category is: ```text Durable Agent Control Plane / Agent Operations Mesh ``` The implementation process must follow the Shirube / `watchout/ai-dev-framework` model: ```text retrofit → SSOT → plan → vertical slices → audit → PR conveyor ``` This issue is intentionally architecture-first, but not abstract. It defines the target design, SSOT structure, protected surfaces, phase gates, and first implementable PR slices. --- ## 1. Context Current `agent-comms-mcp` already contains several advanced pieces: - MCP server - CLI entrypoints: `agent-com`, `aun` - Discord adapter / Discord client handling - inbound receiver - outbound consumer - DB-backed message queue - runtime heartbeat - state-daemon readiness - queue-work runner/finalizer - GitHub writeback mediation - PR conveyor / protected gate work - AUN normalization docs - enterprise control-plane direction docs However, the current code and docs still carry too much coupled legacy surface: ```text Discord operation + state-daemon queue-work canaries + tmux/TUI wake fallback + per-bot checkout/env drift + endpoint lease drift + Discord projection concerns + residue cleanup policy + GitHub-backed handoff writeback ``` This makes failures hard to attribute and makes the product look smaller than it is. The target is to preserve current internal operation while progressively replacing implicit operational folklore with deterministic DB-backed evidence. --- ## 2. North Star AUN is a durable control plane for LLM agents. Discord, Slack, Teams, web UI, MCP transports, local CLIs, Codex, Claude Code, remote workers, tmux, local paths, provider tokens, and GitHub comments are surfaces, runtimes, connectors, or projections. They are not the product identity. AUN should be able to answer, from durable evidence: ```text What happened? Who owned it? Which runtime claimed it? Was the claim still valid? What input caused it? What output closed it? Which connector projected it? Why was the state transition allowed? How can it be recovered safely? ``` --- ## 3. Product Positioning ### 3.1 Public category ```text Durable Agent Control Plane Agent Operations Mesh Evidence-Native Agent Runtime Coordination Layer ``` ### 3.2 Do not position AUN as - Discord bot collection - chat sync tool - queue helper - MCP wrapper - tmux session manager - Claude Code-only plugin - Codex-only runner - GitHub comment bot ### 3.3 Enterprise-grade differentiators AUN should preserve the following differentiators: 1. Evidence-native agent communication 2. Runtime-independent identity 3. Connector-neutral routing 4. DB-backed claim / lease / recovery semantics 5. Typed operational mutations 6. Provider output as projection 7. Protected-surface fail-closed governance 8. Standards-aligned public surface 9. Deterministic operator diagnostics 10. Shirube-compatible high-speed implementation loop --- ## 4. Design Principles ## P1. `agent_id` is canonical `agent_id` is the logical identity. The following are not identity: - Discord user id - Discord bot token - Claude Code session - Codex session - tmux pane - local path - MCP transport - HTTP port - provider token - GitHub username - runtime process id These are evidence or bindings attached to the logical agent. --- ## P2. Runtime and connector are separate Runtime = executes work. Connector = sends/receives external events. Example: ```text agent_id: kodama runtime: - codex-cli instance - claude-code session - remote worker - future container runner connector: - discord bot token - slack bot token - teams app - MCP Streamable HTTP endpoint - GitHub writeback adapter ``` Runtime replacement must not change identity. Connector replacement must not change identity. --- ## P3. DB is the coordination source Agent messages, queue rows, claims, runtime heartbeats, connector readiness, channel policy, delivery-owner resolution, writeback evidence, and audit events must be machine-readable and DB-backed. The database should not require the same fact to be manually entered in multiple locations. Editable source should be minimal; derived evidence should be generated or reconciled by deterministic code. --- ## P4. Every mutation is typed Every operational mutation must go through one of: - CLI command - daemon action - migration - typed runner - audited reconcile command LLMs can inspect, propose, summarize, and prepare commands. They must not be the untyped authority for routing, credentials, queue completion, runtime cleanup, or protected state transitions. --- ## P5. Provider output is projection Discord messages, Slack messages, GitHub comments, Teams posts, and future web UI updates are projection evidence. They may prove delivery, but they are not the authority for: - identity - authorization - queue ownership - task completion - recovery state Completion authority must be queue terminal state plus terminal evidence. --- ## P6. Protected surfaces fail closed The following are protected surfaces: - queue lifecycle - claim / lease / fencing - runtime activation - connector credential handling - routing policy - MCP transport behavior - GitHub writeback - state-daemon behavior - auto-merge / approval gate - audit evidence - destructive cleanup / restart Protected work must progress in this order unless explicitly approved otherwise: ```text read-only diagnostic → dry-run planner → exact-fenced executable command → synthetic canary → one-agent live canary → policy allowlist expansion → default enable ``` --- ## 5. Target Architecture ```text AUN Control Plane ├── Identity Layer │ ├── agents │ ├── agent_profiles │ ├── agent_uri │ └── role bindings │ ├── Runtime Layer │ ├── runtime_instances │ ├── runtime_capabilities │ ├── runtime_heartbeats │ ├── endpoint_leases │ └── supervisor_evidence │ ├── Connector Layer │ ├── connector_instances │ ├── connector_credentials │ ├── provider_identities │ ├── provider_channel_access │ └── agent_ui_bindings │ ├── Queue Layer │ ├── agent_messages │ ├── message_queue │ ├── outbound_queue │ ├── claims │ ├── leases │ └── terminal evidence │ ├── Routing Layer │ ├── channels │ ├── channel_members │ ├── channel_routing_policy │ ├── effective_delivery_owner │ └── outbound ACL │ ├── Execution Layer │ ├── runtime-v2 │ ├── queue-work runner │ ├── mediated GitHub writeback │ ├── task finalizer │ └── recovery planner │ ├── Governance Layer │ ├── PR conveyor │ ├── route classifier │ ├── approval policy │ ├── protected gate │ └── audit signal │ └── Projection Layer ├── Discord projection ├── GitHub projection ├── operator CLI reports ├── future web UI └── external observability export ``` --- ## 6. Runtime-v2 Boundary Runtime-v2 should become the canonical execution boundary. ### 6.1 Runtime-v2 responsibility ```text pending queue row → exact fenced selection → claim with runtime_instance_id → process by selected runtime adapter → produce structured result → validate result contract → write terminal evidence → optional projection/writeback ``` ### 6.2 Runtime-v2 must not - treat Discord as authority - treat tmux pane as identity - treat local path as agent identity - broadly clean stale queues - treat LLM prose as done evidence - post GitHub comments without mediated writeback validation - execute protected mutation without read-only or dry-run evidence first ### 6.3 Proposed runtime-v2 CLI contract ```bash aun runtime-v2 plan \ --agent-id \ --queue-id \ --message-id \ --created-after \ --json aun runtime-v2 claim \ --agent-id \ --queue-id \ --message-id \ --created-after \ --dry-run \ --json aun runtime-v2 execute \ --agent-id \ --queue-id \ --message-id \ --created-after \ --json aun runtime-v2 finalize \ --queue-id \ --message-id \ --result-file \ --json ``` ### 6.4 Runtime-v2 acceptance criteria - DB access is rejected before read/mutation unless exact fences are present when required. - Default live target is allowlist-only. - Dry-run never mutates DB. - Claim is atomic. - Claim owner is recorded. - Claim has lease/fencing-compatible evidence. - Stale claim is recoverable by deterministic planner. - Result contract mismatch does not terminal-close work. - GitHub-backed handoff cannot close without mediated writeback evidence. --- ## 7. Shirube / SSOT Reorganization This repo should be retrofitted into a Shirube-compatible SSOT structure. ### 7.1 Target docs structure ```text docs/ ├── ssot/ │ ├── 00_PRODUCT_PRD.md │ ├── 01_AGENT_IDENTITY.md │ ├── 02_RUNTIME_CONTRACT.md │ ├── 03_CONNECTOR_CONTRACT.md │ ├── 04_QUEUE_CONTRACT.md │ ├── 05_ROUTING_CONTRACT.md │ ├── 06_EXECUTION_CONTRACT.md │ ├── 07_GOVERNANCE_CONTRACT.md │ ├── 08_OBSERVABILITY_AUDIT.md │ └── 09_SECURITY_MODEL.md │ ├── design/ │ ├── REBOOT_ARCHITECTURE.md │ ├── AUN_CONTROL_PLANE_TARGET.md │ ├── RUNTIME_V2_TARGET.md │ ├── CONNECTOR_REGISTRY_TARGET.md │ ├── QUEUE_LEASE_TARGET.md │ └── MIGRATION_PLAN.md │ ├── adr/ │ ├── ADR-001-agent-id-is-canonical.md │ ├── ADR-002-provider-output-is-projection.md │ ├── ADR-003-runtime-v2-is-canonical-execution.md │ ├── ADR-004-db-is-coordination-source.md │ └── ADR-005-protected-surfaces-fail-closed.md │ ├── specs/ │ ├── runtime-v2/ │ ├── connector-registry/ │ ├── queue-lease/ │ ├── governance/ │ └── projections/ │ └── decision-backlog.md ``` ### 7.2 SSOT layer policy Each SSOT must be split into: ```text CORE CONTRACT DETAIL ``` #### CORE Stable product meaning. Examples: - `agent_id` is logical identity. - Provider output is projection. - Queue terminal evidence is completion authority. - Protected mutations fail closed. #### CONTRACT Implementation I/O, DB, CLI, state transitions. Examples: - runtime-v2 claim input/output - message_queue state transition - connector credential secret-reference contract - `aun doctor --strict` JSON schema and exit code #### DETAIL Implementation defaults that can change. Examples: - polling interval - log wording - local file path - diagnostic display order - default timeout DETAIL-level uncertainty may go to Decision Backlog. CORE / CONTRACT uncertainty blocks implementation. --- ## 8. Development Flow ### 8.1 Repo-level flow ```text Phase 0: Repository inventory Phase 1: SSOT retrofit Phase 2: Contract freeze Phase 3: Runtime-v2 narrow slice Phase 4: Connector/credential normalization Phase 5: Queue lease/fencing normalization Phase 6: Doctor/audit/projection Phase 7: Public enterprise-ready packaging ``` ### 8.2 Shirube flow ```bash cd /path/to/agent-comms-mcp shirube retrofit --scan-only shirube retrofit shirube plan shirube audit ssot shirube run shirube audit all shirube status --json ``` Important: retrofit output is current-state evidence, not target-state authority. The target state is this reboot architecture plus the resulting SSOT contracts. --- ## 9. Phase 0: Repository Inventory ### Goal Create a complete map of the existing repository before code mutation. ### Deliverables ```text docs/reports/repo-inventory.md docs/reports/current-architecture-map.md docs/reports/protected-surface-map.md docs/reports/test-coverage-map.md docs/reports/ssot-gap-analysis.md docs/reports/drift-report.md ``` ### Tasks #### INV-001: File inventory Classify: ```text package.json bin/ cli/ core/ adapters/ db/ scripts/ tests/ docs/ config/ hooks/ entrypoints/ ``` Classification labels: ```text core identity runtime connector queue routing governance projection test migration legacy compatibility unknown ``` #### INV-002: Protected surface map List files touching: ```text queue lifecycle runtime activation state-daemon Discord connector GitHub writeback PR conveyor approval gate migration credential/token handling cleanup/restart ``` #### INV-003: Existing SSOT map Classify existing docs as: ```text authoritative directional implementation spec historical superseded working notes ``` #### INV-004: Drift report Find mismatches among: - README - docs/SSOT.md - docs/design/* - docs/spec/* - implementation - tests - recent PR bodies - open issues --- ## 10. Phase 1: SSOT Retrofit ### Goal Reorganize current design docs into Shirube-compatible SSOT. ### Deliverables ```text docs/ssot/00_PRODUCT_PRD.md docs/ssot/01_AGENT_IDENTITY.md docs/ssot/02_RUNTIME_CONTRACT.md docs/ssot/03_CONNECTOR_CONTRACT.md docs/ssot/04_QUEUE_CONTRACT.md docs/ssot/05_ROUTING_CONTRACT.md docs/ssot/06_EXECUTION_CONTRACT.md docs/ssot/07_GOVERNANCE_CONTRACT.md docs/ssot/08_OBSERVABILITY_AUDIT.md docs/ssot/09_SECURITY_MODEL.md docs/decision-backlog.md ``` ### PR slicing #### PR-SSOT-001: Product / positioning - AUN is durable control plane. - Discord is first local surface. - MCP is one transport, not identity. - Target users: internal AI dev fleet first, enterprise later. #### PR-SSOT-002: Identity / runtime - `agent_id` - `agent_uri` - `agent_profile` - `runtime_instance` - heartbeat - endpoint lease #### PR-SSOT-003: Connector / credential - connector instance - provider identity - secret reference - token fingerprint - provider channel access #### PR-SSOT-004: Queue / execution - message_queue - outbound_queue - claim - lease - fencing - terminal evidence #### PR-SSOT-005: Governance / audit - protected surface - route classifier - approval gate - audit signal - GitHub writeback evidence --- ## 11. Phase 2: Runtime-v2 Stabilization ### Goal Create the smallest canonical runtime-v2 path that does not depend on legacy state-daemon / wake / tmux authority. ### PR slicing #### PR-RV2-001: read-only runtime-v2 plan - Reads DB state. - Evaluates target queue row. - Emits JSON execution plan. - No mutation. #### PR-RV2-002: exact-fenced claim dry-run - Generates claim SQL / operation packet. - Emits dry-run evidence. - No mutation. #### PR-RV2-003: synthetic claim - Uses isolated test DB fixture. - Proves atomic claim. - No production DB mutation. #### PR-RV2-004: kodama-only live canary - Allowlist: `kodama` only. - Requires exact `queue_id`, `message_id`, and `created_after`. - Requires manual approval. #### PR-RV2-005: mediated finalization - Defines structured result schema. - Validates terminal evidence. - Enforces mediated GitHub writeback when required. --- ## 12. Phase 3: Connector Registry ### Goal Separate provider identity, connector credential, channel access, and core agent identity. ### Target tables / models ```text connector_credentials connector_instances provider_identities provider_channel_access agent_ui_bindings ``` ### Rules - Raw tokens must not be printed in diagnostics. - Raw tokens should not be ordinary readable DB row content. - DB stores secret reference and non-secret fingerprint. - Provider identity is verified evidence. - Channel access is startup/reconcile evidence. - Hot path reads DB evidence, not provider APIs. ### PR slicing #### PR-CONN-001: credential evidence read-only diagnostic ```bash aun connector credential-diagnostic --json ``` #### PR-CONN-002: provider identity verifier ```bash aun connector verify-discord-identity --agent-id --dry-run --json ``` #### PR-CONN-003: channel access discovery ```bash aun connector discover-channel-access --agent-id --dry-run --json ``` #### PR-CONN-004: agent_ui_bindings materializer ```bash aun connector materialize-ui-bindings --dry-run --json ``` #### PR-CONN-005: effective delivery owner resolver ```bash aun routing resolve-delivery-owner --channel-id --agent-id --json ``` --- ## 13. Phase 4: Queue Lease / Fencing ### Goal Move beyond queue status alone and introduce enterprise-grade recovery semantics. ### Target state transition ```text pending → claimed → in_progress → done | failed | skipped | expired ``` ### Claim evidence ```text claim_id queue_id message_id owner_runtime_instance_id claimed_at lease_expires_at fencing_token heartbeat_at terminal_evidence_id ``` ### Rules - Stale holder is invalidated by fencing token. - Terminal close is allowed only by claim owner or authorized reconciler. - Progress reply is not completion. - ACK is not terminal close. - Retry is bounded. - Orphan recovery creates audit evidence. ### PR slicing #### PR-LEASE-001: additive lease schema Add schema only. No behavior change. #### PR-LEASE-002: read-only lease diagnostic ```bash aun queue lease-diagnostic --json ``` #### PR-LEASE-003: runtime-v2 claim writes lease evidence Runtime-v2 claim records lease-compatible evidence. #### PR-LEASE-004: finalize requires valid lease Finalize checks fencing token / claim owner. #### PR-LEASE-005: stale recovery planner ```bash aun queue stale-recovery-plan --json ``` Read-only first. Executable recovery is separate. --- ## 14. Phase 5: Doctor / Audit / Operator Projection ### Goal AUN health must be mechanically decidable without reading Discord, tmux panes, local path folklore, or LLM prose. ### Commands ```bash aun doctor --strict --json aun fleet readiness --json aun agent status --agent-id --json aun queue stuck-report --json aun audit evidence --queue-id --json ``` ### Strict doctor checks - Active agent has `agents` row. - Active agent has editable profile. - Active runtime has heartbeat. - Active runtime has endpoint lease evidence. - Active connector has credential evidence. - Active connector has provider identity evidence. - Operational channel has routing policy. - Delivery owner is resolvable. - No duplicate active token fingerprint. - No stale queue outside approved policy. - No active process without DB runtime evidence. - Protected mutation policy is enabled. - GitHub writeback role markers are enforced. ### PR slicing #### PR-DOC-001: strict doctor JSON schema Schema only. No behavior change. #### PR-DOC-002: runtime checks - heartbeat - endpoint lease - supervisor evidence #### PR-DOC-003: connector checks - credential fingerprint - provider identity - channel access #### PR-DOC-004: queue checks - stale pending - stale claimed - missing terminal evidence - duplicate enqueue #### PR-DOC-005: governance checks - route classifier - approval gate - audit signal - writeback proof --- ## 15. Phase 6: Governance Conveyor ### Goal AI agents can develop quickly, but dangerous changes must automatically route through protected review. ### Route classes ```text route:fast-merge route:l2-audit route:cto-approval route:ceo-approval route:blocked ``` ### Protected detector paths Changes under these paths should generally be protected: ```text bin/aun/** core/queue/** core/runtime/** core/connector/** core/routing/** core/state-daemon/** db/migrate* scripts/*recovery* scripts/*activation* .github/workflows/** ``` ### Required evidence - Tests pass. - Audit passes. - Exact-head check is present where labels/mutations are involved. - No broad cleanup. - Tests never mutate production DB. - Protected mutation has read-only or dry-run planner first. - PR body contains validation evidence. - PR body states non-scope. --- ## 16. Phase 7: Public / Enterprise Packaging ### Goal Make AUN understandable and credible for large technology organizations. ### Public positioning ```text AUN is an evidence-native control plane for LLM agents. It coordinates agent identity, runtime ownership, queue claims, connector delivery, and audit evidence across local and remote AI coding agents. ``` ### Public docs ```text docs/public/WHAT_IS_AUN.md docs/public/ARCHITECTURE.md docs/public/SECURITY_MODEL.md docs/public/OPERATIONS_MODEL.md docs/public/MCP_TRANSPORT.md docs/public/A2A_COMPATIBILITY_DIRECTION.md docs/public/OBSERVABILITY.md docs/public/ENTERPRISE_EVALUATION_GUIDE.md ``` ### Enterprise evaluation checklist - Can agent identity survive runtime replacement? - Can runtime claim be audited? - Can failed work be recovered deterministically? - Are secrets excluded from diagnostics? - Is provider output only projection? - Is every mutation typed? - Is every protected action fail-closed? - Can the system explain who owned what and why? - Can logs/metrics/traces be exported? - Can OAuth/OIDC/zero-trust be added without identity rewrite? - Can non-Discord connectors be added without core rewrite? --- ## 17. Immediate First 10 PRs ### PR-001: Reboot architecture document Files: ```text docs/design/REBOOT_ARCHITECTURE.md docs/decision-backlog.md ``` No code change. ### PR-002: SSOT index Files: ```text docs/ssot/README.md docs/ssot/00_PRODUCT_PRD.md docs/ssot/01_AGENT_IDENTITY.md ``` No code change. ### PR-003: Protected surface classifier spec Files: ```text docs/ssot/07_GOVERNANCE_CONTRACT.md docs/spec/protected-surface-classifier.md tests/protected-surface-classifier.test.ts ``` Code allowed only for classifier test fixture. ### PR-004: Runtime-v2 command contract Files: ```text docs/ssot/02_RUNTIME_CONTRACT.md docs/spec/runtime-v2-command-contract.md tests/aun-runtime-v2-contract.test.ts ``` No live DB. ### PR-005: Runtime-v2 read-only planner Files: ```text bin/aun/runtime-v2.ts core/aun-runtime-v2-plan.ts tests/aun-runtime-v2-plan.test.ts ``` Mutation prohibited. ### PR-006: Queue lease target SSOT Files: ```text docs/ssot/04_QUEUE_CONTRACT.md docs/spec/queue-lease-target.md ``` No code change. ### PR-007: Connector registry target SSOT Files: ```text docs/ssot/03_CONNECTOR_CONTRACT.md docs/spec/connector-registry-target.md ``` No code change. ### PR-008: Doctor strict schema Files: ```text docs/ssot/08_OBSERVABILITY_AUDIT.md schemas/aun-doctor-strict.schema.json tests/aun-doctor-schema.test.ts ``` No production behavior change. ### PR-009: Runtime-v2 exact-fence dry-run Files: ```text core/aun-runtime-v2-claim-plan.ts bin/aun/runtime-v2.ts tests/aun-runtime-v2-claim-plan.test.ts ``` Dry-run only. ### PR-010: Synthetic runtime-v2 claim Files: ```text core/aun-runtime-v2-claim.ts tests/aun-runtime-v2-claim.test.ts ``` Test DB only. Production DB mutation prohibited. --- ## 18. Non-goals for this reboot MVP Do not implement these in the first reboot phase: - hosted SaaS - multi-tenant RBAC - full OAuth/OIDC enforcement - complete Discord removal - complete tmux removal - all agents runtime-v2 migration - public web UI - remote worker federation - Vault migration - Kubernetes deployment - multi-region HA - arbitrary A2A protocol implementation - automatic production DB cleanup These belong to v1 / v2 / enterprise phases. --- ## 19. Definition of Done The reboot MVP is complete when: ```bash aun doctor --strict --json ``` can mechanically determine internal fleet health without relying on Discord transcript reading, tmux observation, local path folklore, or LLM claims. Required success conditions: - Active agent identity is DB-backed. - Runtime liveness is DB-backed. - Connector readiness is DB-backed. - Token identity is unambiguous. - Routing policy is explicit. - Queue claim and terminal evidence are auditable. - Stale work is recoverable by deterministic planner. - Protected mutations fail closed. - Operator can understand health and ownership from typed reports. --- ## 20. Suggested first action Start with PR-001 only: ```text docs/design/REBOOT_ARCHITECTURE.md docs/decision-backlog.md ``` No code change. The first PR should establish the target architecture and decision backlog so subsequent Codex/Claude work can proceed in narrow, auditable, Shirube-compatible vertical slices.

nanookclaw analysis page

nanookclaw