Capsule Bus (Experimental)

Capsule Bus v0.4 is an experimental, SQLite-backed, in-process event-to-command routing capability built into Opstage CE. It is single-node, disabled by default, and intended for controlled trials.

It is not a standalone Bus Server, external broker (NATS / RabbitMQ / Redis Streams / Kafka), workflow engine, service mesh, or message broker replacement.

Minimal flow

1. A service publishes an event envelope such as demo.item.created.
2. CE stores the event in SQLite and writes audit records.
3. CE matches enabled or dry-run route rules in-process.
4. An enabled route creates an ACTION_EXECUTE command for the target service/action.
5. Existing Agent SDK or OpHub command polling executes the action.

OpHub thin-forwarding

OpHub may thin-forward local adapter events into CE's built-in Bus:

GET /capsule/bus/events -> OpHub -> POST /api/agents/:agentId/bus/events -> CE

OpHub does not own routing, persistence, or command creation — CE does.

Safety posture

• Routes are disabled by default.
• DRY_RUN routes should be used before enabling command creation.
• Event and route APIs are marked v0.4-experimental.
• Per-agent rate limit — default 60 events/min, configurable via OPSTAGE_CAPSULE_BUS_INGEST_PER_MIN. Excess returns 429 (BUS_RATE_LIMITED).
• Max-depth guard — router-caused re-entry is rejected with BUS_DEPTH_EXCEEDED. Max depth = 1.
• Feature flag: OPSTAGE_CAPSULE_BUS_ENABLED=false by default.

Non-goals in v0.4

• No standalone Bus Server.
• No external broker provider (NATS / RabbitMQ / Redis Streams / Kafka).
• No fan-out / maxCommandsPerEvent — one matched route produces at most one command.
• No HA / clustering / distributed bus.
• No stable API guarantee before v1.0.

Enabling the experiment

In CE, Capsule Bus is disabled by default. Enable it only in controlled environments:

OPSTAGE_CAPSULE_BUS_ENABLED=true

Current CE endpoints follow the existing admin/agent API conventions:

• GET /api/admin/bus/routes
• POST /api/admin/bus/routes
• GET /api/admin/bus/routes/:routeId
• PUT /api/admin/bus/routes/:routeId
• DELETE /api/admin/bus/routes/:routeId
• GET /api/admin/bus/events
• POST /api/agents/:agentId/bus/events