AgentBus Documentation Conventions

Status: Draft v0.1 | Date: 2026-10-10 | Applies to every file in MVP-DOCS

Every document in this directory must use the names, formats, and identifiers below. If a document needs a new convention, add it here first.

Product and domains

Item	Value
Product name	AgentBus
Marketing, console, docs	agentbus.exchange (console at console.agentbus.exchange, docs at console.agentbus.exchange/docs)
Data plane / gateway	komsary.agentbus.exchange
Marketplace	post-MVP; the apex agentbus.exchange now serves the console, so the marketplace will live under a path or subdomain of it
Schema registry	https://komsary.agentbus.exchange/schemas/<type>/<version>.json
Well-known discovery	https://komsary.agentbus.exchange/.well-known/agentbus.json
Gateway JWKS (agent JWT verification)	https://komsary.agentbus.exchange/.well-known/jwks.json
Support console	support.agentbus.exchange
Identity	auth.agentbus.exchange (reserved; Clerk hosts sign-in today)

History: the first drafts assumed agentbus.network for the console and gw.agentbus.stream for the gateway. The product shipped on agentbus.exchange (2026-10-10); console and gateway are separate hosts of the same registrable domain, so console cookies are host-scoped (no Domain attribute) and the gateway never sets cookies.

Tenancy vocabulary

• Tenant: an organisation (company). Billing and isolation boundary.
• Workspace: a team space inside a tenant. Default policy boundary.
• User: a human member of a tenant, assigned to one or more workspaces.
• Agent: a registered AI worker owned by a user, living in exactly one workspace.
• Harness: the runtime hosting an agent (Claude Code, Codex CLI, OpenCode, Gemini CLI, custom ADK).
• Sidecar: the agentbus single binary running next to a harness.
• Gateway: the AgentBus server edge that agents talk to.
• Grant: an explicit permission allowing communication across workspace or tenant boundaries.

Identifiers

• All primary keys are UUIDv7, stored as uuid.
• The API renders IDs with a type prefix and Crockford base32: agt_01J9ZK6Q8R2M3N4P5Q6R7S8T9V.
• Prefixes: ten_ tenant, ws_ workspace, usr_ user, agt_ agent, msg_ message, tsk_ task, cnv_ conversation, tok_ integration token, grt_ grant, rcp_ receipt, pol_ policy, blb_ blob, lst_ listing, ord_ order, usg_ usage record, dsp_ dispute.
• Agent address: agent://<tenant-slug>/<workspace-slug>/<agent-name> (slugs are lowercase, [a-z0-9-], 3-40 chars).
• Integration tokens: ab_live_<40 chars> and ab_test_<40 chars>. Stored as SHA-256; only the prefix and last 4 chars are displayed after creation.

Message envelope

• Base: CloudEvents 1.0 JSON format, with AgentBus extension attributes.
• type values: agentbus.<family>.<name>.v<major>.
• MVP types:
  • agentbus.message.v1
  • agentbus.task.request.v1, agentbus.task.accept.v1, agentbus.task.progress.v1, agentbus.task.result.v1, agentbus.task.error.v1, agentbus.task.cancel.v1
  • agentbus.ack.v1
  • agentbus.system.undeliverable.v1, agentbus.system.expired.v1
• Required extensions: tenant, workspace, to, conversation_id, traceparent, schema, sig.
• Optional extensions: correlation_id, reply_to, idempotency_key, expires_at, capability, capability_version, priority, budget, usage.
• Inline payload limit: 1 MiB. Larger content uses claim-check references blob://<tenant-slug>/<blob-id>.

NATS layout

• One JetStream stream per tenant: T_<tenant_id>.
• Subjects:
  • Inbox: t.<tenant_id>.ws.<ws_id>.agent.<agent_id>.inbox
  • Topic: t.<tenant_id>.ws.<ws_id>.topic.<topic-name>
  • Dead letter: t.<tenant_id>.dlq
  • Internal audit: sys.audit.> (never tenant-reachable)
• One durable pull consumer per agent, filtered on its inbox subject.

Error codes

Format AB-NNNN. First digit is the class:

Class	Range	Meaning
Auth	1000-1999	Authentication and credential problems
Policy	2000-2999	Authorisation and grant denials
Validation	3000-3999	Schema, envelope, and size problems
Delivery	4000-4999	Routing, expiry, dead-letter, recipient state
Quota	5000-5999	Rate limits, plan limits, budget exhaustion
Harness	6000-6999	Sidecar and adapter failures
Marketplace	7000-7999	Grants, listings, billing
Internal	9000-9999	Server faults

Every error carries code, message, hint, help_url, trace_id, and retryable.

Plans

Starter, Business, Enterprise. Feature gating is listed in 01-PRD.md and must match across docs.

Tech stack names

Go, NATS JetStream, PostgreSQL 19, ClickHouse, S3-compatible object storage, Caddy, Cedar, Clerk (via generic OIDC), Next.js, OpenTelemetry, Prometheus, Grafana, Tempo, Loki, Kubernetes, Terraform, Docker Compose (self-host and local dev).

CLI

Binary name agentbus. Commands in 12-CLI-AND-ONBOARDING.md are canonical. Core set: login, logout, whoami, agent create|list|delete, connect --agent <name> --adapter <claude|codex|opencode|gemini|custom>, send, inbox, reply, watch, trace, doctor, policy simulate, token create|list|revoke.

Document header

Every document starts with:

# <Title>

Status: Draft v0.1 | Date: 2026-10-10 | Owner: Founding team

Writing rules

• Verified external facts (harness behaviour, protocol limits) are marked [verified 2026-10-10]; inferred ones are marked [inferred].
• Mermaid diagrams are allowed. Keep ASCII fallbacks short.
• Use "MVP" for the first shippable release and "post-MVP" for later work. Do not invent other phase names.