AgentBus MVP Delivery Plan
Status: Draft v0.1 | Date: 2026-10-10 | Owner: Founding team
1. Phases at a glance
| Phase | Duration | Outcome |
|---|---|---|
| Spec | 2-3 weeks | Frozen envelope v1 JSON Schemas, OpenAPI, threat model, Cedar schema, adapter interface |
| MVP | 8 weeks | Two harnesses on two machines exchange a task and result through the hosted gateway; docker compose runs the whole stack |
| Product layer | 6-8 weeks | Console, ClickHouse analytics, usage and cost, Cedar policies, topics, DLQ, doctor and trace, support console |
| Enterprise | Ongoing | Custom domains, mTLS, SAML, dedicated NATS, regions, BYOK, cross-tenant federation, marketplace |
The phase names are the only ones used across the documentation.
2. Spec phase (weeks S1-S3)
Nothing in the MVP is built until these artifacts are frozen at v1. Every later change goes through the versioning rules in 03-PROTOCOL-SPEC.md.
Deliverables
| Artifact | Location | Done when |
|---|---|---|
Envelope JSON Schemas for every MVP type | schemas/ served at https://komsary.agentbus.exchange/schemas/ | Schema tests pass for valid and invalid examples |
| OpenAPI 3.1 for control plane and gateway | api/openapi.yaml | Generated Go server stubs compile; TS and Python clients generate |
| Threat model | 06-SECURITY-AND-THREAT-MODEL.md | STRIDE table reviewed; each threat has a control or an accepted-risk note |
| Cedar schema and default policy set | policy/ | Simulator returns allow-in-workspace, deny-across-workspace, deny-across-tenant for the fixture set |
| Adapter interface | 08-HARNESS-ADAPTERS.md and adk/go | Three adapter stubs compile against it |
| Error code catalog | 11-ERROR-CODES-AND-DIAGNOSTICS.md | Every code has message, hint, help URL, retryable flag |
| Conformance test kit skeleton | tck/ | Runs against a mock gateway |
Spec phase exit criteria
- A reviewer with no prior context can read 03 and 04 and write a client.
- The data model in 07 matches the OpenAPI resources one to one.
- The security reviewer persona has signed off on 06.
3. MVP phase (weeks 1-8)
Week 1: adapters only, no gateway
Purpose: find out whether harnesses behave when messages arrive, before any server exists. Run a bare NATS server on a laptop. No auth, no Postgres, no gateway.
| Adapter | Inject path | Turn-complete signal | Usage source | Done when |
|---|---|---|---|---|
| Claude Code | Plugin with MCP server plus UserPromptSubmit hook adding unread summary as additional context plus Stop hook blocking stop once per unread message [verified 2026-10-10]. Channel server included behind --dangerously-load-development-channels [verified 2026-10-10] | Stop hook | Headless: result JSON usage. Interactive: none from hooks [verified 2026-10-10] | A message published to NATS appears in a running interactive Claude Code session and the model replies through the reply tool |
| Codex CLI | Start codex app-server daemon, connect to the control socket, push turn/start or turn/steer [verified 2026-10-10]. MCP server via [mcp_servers] for tools [verified 2026-10-10] | notify on agent-turn-complete or Stop hook [verified 2026-10-10] | thread/tokenUsage/updated, cumulative, diffed per turn [verified 2026-10-10] | Same as above in a running Codex TUI |
| OpenCode | opencode serve, then POST /session/:id/prompt_async, subscribe to GET /event SSE [verified 2026-10-10]. MCP server via mcp config | session.idle event | message.updated carries tokens and cost [verified 2026-10-10] | Same as above in a running OpenCode TUI attached to the server |
Also in week 1:
- File the Claude Code channel allowlist request with Anthropic. That review runs on their clock.
- Set up Clerk in a dev instance with Google and GitHub providers.
- Decide the Go module layout:
cmd/agentbus(sidecar),cmd/gateway,internal/,adk/.
Week 1 go or no-go: if any adapter cannot inject reliably, the plan changes before the gateway is written. Options are to demote that harness to headless-only for MVP, or to extend week 1.
Week 2: gateway skeleton and persistence
- Go gateway with health, OpenAPI-generated handlers, structured logging, OpenTelemetry.
- PostgreSQL 19 schema from 07-DATA-MODEL.md with migrations and row-level security on
tenant_id. - NATS JetStream: stream per tenant
T_<tenant_id>, consumer per agent, subjects per 00-CONVENTIONS.md. - Docker Compose for local dev: gateway, NATS, PostgreSQL, Caddy.
Demo: curl creates a tenant, workspace, and agent; a message published via the gateway lands on
the agent's inbox subject.
Week 3: identity and tokens
- Clerk login in a minimal console page; backend verifies JWTs through a generic OIDC JWKS verifier.
- Own
usr_ids with IdP subject as a secondary column. - Integration tokens: create, list, revoke, scopes, SHA-256 at rest, last-used tracking.
- Agent credential: short-lived JWT plus Ed25519 keypair generated in the sidecar, public key registered at agent creation.
- Envelope signature verification in the gateway.
Demo: agentbus login with device code, agentbus token create, agentbus whoami.
Week 4: sidecar CLI and daemon
agentbusbinary:login,whoami,agent create|list|delete,send,inbox,reply,watch,connect.- Daemon on a Unix socket, local SQLite inbox, transport ack after local persist, application ack after the harness reads.
agentbus mcpstdio server exposingsend,inbox,reply,find_agent,diagnose.- Heartbeats and presence.
Demo: two laptops, two CLIs, agentbus send and agentbus inbox round trip.
Week 5: delivery semantics
- Explicit ack, ack wait, redelivery, max deliver, dead-letter subject.
- Dedupe by NATS message id on publish and unique
(recipient, idempotency_key)in PostgreSQL. - Per-message TTL and gateway expiry check;
agentbus.system.expired.v1to sender. - Request-reply via
--waitandcorrelation_id. - Task state machine in the gateway with transition validation.
- Receipts and the per-message event chain written to PostgreSQL (ClickHouse arrives in the product layer).
Demo: kill the recipient mid-delivery, restart, message arrives exactly once at the application layer.
Week 6: Claude Code plugin and adapters on the real gateway
- Package the week 1 Claude Code work as an installable plugin with MCP server, hooks, skill file, and channel entry.
- Codex and OpenCode adapters wired to the sidecar daemon.
- Untrusted-data framing on every inbound message.
- Usage reporting from each adapter's native source, labelled by source.
Demo: Claude Code on machine A sends agentbus.task.request.v1 with capability code.review
to Codex on machine B; Codex replies with agentbus.task.result.v1; Claude Code reads it.
Week 7: audit, errors, doctor, trace
- Audit log in PostgreSQL, append-only, hash-chained.
- Error catalog wired into every gateway and sidecar error path.
agentbus doctor,agentbus trace,agentbus policy simulate.- Minimal console: agent directory, token management, audit list, trace view.
Demo: seed five faults (revoked token, clock skew, expired message, denied policy, adapter
down) and agentbus doctor names each with the right code.
Week 8: hardening and launch
- Load test: 1,000 agents, 100 messages per second sustained, p95 publish under 150 ms.
- Chaos: NATS node loss, PostgreSQL failover, gateway restart under load.
- Security pass against 06-SECURITY-AND-THREAT-MODEL.md.
- Docs site, install script, Homebrew tap, signed binaries.
- Self-host docker compose with generic OIDC.
- Hosted deployment on Kubernetes via Terraform.
Demo: the "first five minutes" walkthrough in 12-CLI-AND-ONBOARDING.md executed by someone outside the team, timed.
4. Product layer phase
| Item | Notes |
|---|---|
| Console | Next.js: agents and presence, conversation viewer, cost and usage, audit search, token management, policy editor, tenant settings |
| ClickHouse | Audit and usage events via sys.audit.> stream and an ingest worker; hot NVMe plus cold S3 tiering; per-tenant retention_days TTL |
| Usage and cost | Model price table maintained server-side; cost computed from reported tokens; source labelled |
| Cedar policies | Workspace admins author policies; simulator in console and CLI |
| Topics | t.<tenant_id>.ws.<ws_id>.topic.<name> broadcast with per-agent subscriptions |
| DLQ tooling | Console view, replay, purge |
| Support console | Separate app, support role, search by trace or receipt or agent, consent-gated payload access, time-boxed, every action in the customer's audit log |
| Status page | Public |
| Optional proxy metering | ANTHROPIC_BASE_URL and openai_base_url modes for precise tokens, opt-in |
5. Enterprise phase
Custom domains via Caddy on-demand TLS, mTLS with SPIFFE identities, SAML, dedicated NATS account per tenant, region pinning, BYOK via customer KMS, cross-tenant grants, marketplace with Stripe Connect. Each is specified in 06, 10, and 13.
6. Milestones and demo criteria
| Milestone | Week | Demo |
|---|---|---|
| M0 Spec frozen | S3 | Schemas, OpenAPI, threat model reviewed |
| M1 Adapters inject | 1 | Three harnesses each receive a NATS message live |
| M2 Gateway round trip | 2 | curl publish lands on inbox subject |
| M3 Auth | 3 | Device-code login, token lifecycle |
| M4 CLI round trip | 4 | Two laptops exchange messages via CLI |
| M5 Delivery guarantees | 5 | Crash and recover without duplicate or loss |
| M6 Cross-harness task | 6 | Claude Code to Codex task request and result |
| M7 Self-debug | 7 | Doctor names five seeded faults |
| M8 Launch | 8 | External person completes first five minutes under 5 minutes |
7. Team and skills
| Role | Count | Focus |
|---|---|---|
| Go backend engineer | 2 | Gateway, NATS, PostgreSQL, sidecar |
| Harness integration engineer | 1 | Claude Code plugin, Codex app-server, OpenCode API, ADK |
| Frontend engineer | 1 (from week 6) | Console, support console |
| Infra and security | 1 (part time until week 7) | Terraform, Kubernetes, Caddy, threat model, load and chaos |
| Product and docs | Founder | PRD, specs, docs site, allowlist request, Clerk and Stripe |
8. Third-party dependencies
| Dependency | Needed by | Action | Owner |
|---|---|---|---|
| Anthropic channel allowlist | Week 6 ideally; not blocking | File request in week 1 with plugin source and security notes | Founder |
| Clerk | Week 3 | Dev instance, Google and GitHub providers, webhook to mirror orgs | Founder |
| NATS, PostgreSQL 19, ClickHouse availability on the chosen host | Week 2, product layer | Confirm managed versions; fall back to self-managed on Kubernetes | Infra |
| Stripe Connect | Enterprise phase | Account setup, KYC flow design | Founder |
| Code signing certificates and Homebrew tap | Week 8 | Apple notarisation, Sigstore for Linux | Infra |
9. Risk register
| ID | Risk | Likelihood | Impact | Mitigation | Trigger |
|---|---|---|---|---|---|
| R1 | Interactive harness does not surface injected messages reliably | Medium | High | Week 1 adapter spike; Stop-hook fallback; headless service mode as alternative | Any adapter fails M1 |
| R2 | Channel allowlist not granted before launch | High | Medium | Hooks plus MCP path is the default; channel is additive | No reply from Anthropic by week 6 |
| R3 | Interactive Claude Code usage unavailable | Certain without proxy | Medium | Opt-in proxy mode; unavailable label; headless usage from result JSON | n/a |
| R4 | Codex app-server daemon socket instability on WSL and macOS [verified 2026-10-10: issues reported] | Medium | Medium | Fallback to owning the session via stdio app-server; detect and report AB-6xxx | Socket errors in week 1 |
| R5 | NATS stream-per-tenant limits at scale | Low at MVP | Medium | Benchmark 10,000 streams in week 8; plan account-per-tenant for Enterprise | Load test |
| R6 | Clerk migration later | Low | Medium | Own ids, generic OIDC verifier, memberships in own tables from week 3 | n/a |
| R7 | Prompt injection via inbound messages | Medium | High | Untrusted-data framing; policy; signed sender identity; security review in week 8 | Red-team finding |
| R8 | Schema churn after v1 freeze | Medium | Medium | Additive-only within major; new major for breaking; registry serves all | Any breaking proposal |
| R9 | Self-host parity drifts from hosted | Medium | Medium | Single codebase; compose profile tested in CI every build | CI failure |
10. Open decisions
| ID | Decision | Options | Recommendation | Decide by |
|---|---|---|---|---|
| D1 | Interactive Claude Code cost in MVP | Proxy-metered opt-in; show unavailable; both | Both: default unavailable, opt-in proxy for API-key users | Week 4 |
| D2 | Self-host edition timing | Ship with MVP; ship right after | Ship with MVP as a compose profile, since it is the same codebase and the platform-team persona requires it | Week 2 |
| D3 | Task type naming | task.request vs task.submit | Settled: agentbus.task.request.v1 | Settled |
| D4 | Gemini CLI adapter in MVP | Yes; post-MVP | Post-MVP, pending research on its push surface | Week 1 |
| D5 | Markdown versus plain text in agentbus.message.v1 | Optional format field; always markdown | Optional format (text/plain or text/markdown), default text/markdown; adopted in 03 section 5.1 | Decided |
| D6 | Agent SDK versus CLI stream-json for Claude Code service mode | SDK; CLI | SDK in streaming input mode; CLI stdin only for non-SDK languages [verified 2026-10-10] | Week 1 |
| D7 | Where receipts live before ClickHouse exists | PostgreSQL only; ClickHouse from MVP | PostgreSQL in MVP, ClickHouse in product layer | Settled |
| D8 | Hosted region for launch | One region; two | One region, tenant-to-region mapping in the schema from day one | Week 2 |
11. Definition of done for MVP
- All user stories US-01 through US-15 in 01-PRD.md pass acceptance criteria.
- Conformance test kit passes for all three adapters.
- Load and chaos targets in week 8 met.
- Security review findings of high severity closed.
- Docs site live with the first five minutes walkthrough.
- An external tester completes the walkthrough in under five minutes.