Agent Bridge

The Agent Bridge is the external execution path for the AI Agent. Instead of running the agentic loop in-process, it spawns a real Claude Code CLI subprocess that connects back to Opbox via MCP. The bridge claims tasks from AgentTask queue, hands them to Claude Code, and writes the result back when complete.

Key design point: from Opbox's perspective, the bridge is just an MCP client. It authenticates with a cp_live_* API key, calls tools, and reports completion via the bridge API. The Opbox server doesn't care that there's a Claude Code subprocess on the other end.

Why Two Paths?

Path	Strengths	Trade-offs
In-process worker	Simple, no extra deploy. Resolves BYOK locally. Fast for short tasks.	Bound by the host's CPU/memory budget. No native Claude Code features (skills, plan mode, sub-agents).
Agent Bridge	Full Claude Code feature set. Can run on a separate, beefier machine. Native skills + sub-agents.	Extra infra. Extra auth boundary.

For most workspaces, the in-process worker is sufficient. The bridge shines for document-generation workloads where Claude Code's structured-output skills + extended context window matter.

Connection Lifecycle

1. Bridge process starts. Reads cp_live_* key from env.
2. Bridge polls /api/agent-tasks?status=PENDING (via MCP `agent_queue_list`).
3. Task appears. Bridge calls /api/agent-tasks/[taskId]/claim (atomic, returns claimToken).
4. Bridge spawns `claude-code` subprocess.
   - stdio: stdin/stdout NDJSON.
   - --mcp-server flag pointing at https://opbox.app/api/mcp
   - --api-key from env (the cp_live_* key)
5. Bridge writes the task prompt + briefing to Claude Code's stdin.
6. Claude Code runs its agentic loop:
   a. Reads tools/list from MCP.
   b. Calls tools (matters, docs, agent-queue, doc-gen, ...).
   c. Each tool call is auth'd via the bearer token.
   d. autonomyLevel on the key controls what's allowed.
7. Bridge reads progress events from Claude Code's stdout, calls
   /api/agent-tasks/[taskId]/progress with text snippets.
8. Claude Code emits `done`. Bridge calls
   /api/agent-tasks/[taskId]/complete with result + cost + duration.
9. Bridge releases lease (or it auto-expires if Claude Code crashed).
10. Loop back to step 2.

Bridge API (MCP API Key Auth)

These endpoints are auth'd via Authorization: Bearer cp_live_... + X-MCP-Client header (same as MCP routes). No session cookies.

Endpoint	Method	Purpose
`/api/agent-tasks/[taskId]/claim`	POST	Atomic claim. Returns plaintext `claimToken` + task details + autonomy level.
`/api/agent-tasks/[taskId]/progress`	PATCH	Update `progressText`. Requires `claimToken`. Idempotent.
`/api/agent-tasks/[taskId]/complete`	PATCH	Transition to DONE/FAILED. Accepts `result`, `costUsd`, `durationMs`, `toolCallCount`. Triggers post-completion side effects (matter comment, audit log).

claimToken is the bridge's proof it owns the lease. Progress and complete calls are rejected if the token doesn't match the active claim - protects against split-brain when a stale process tries to update a task that another process has since reclaimed.

Authentication Model

The bridge uses the same cp_live_* API key as a Claude Code user with MCP integration. There's no separate "bridge key" type. This means:

Issuing a key for the bridge is identical to issuing one for a developer's local Claude Code.
The autonomy level on the key controls what the bridge can do.
Revoking the key kills the bridge's access immediately.
Audit trail attribution is the same: tool calls log under the agent member's userId.

Self-Reference: Bridge Calls MCP

The bridge is, in a sense, an MCP client of itself. The Claude Code subprocess connects via MCP just like an external Claude Code on a developer's laptop would. This means:

The autonomy enforcement is the same code path.
The cross-tenant _targetWorkspaceId mechanism works the same way.
Cost ledger writes the same row shape.
Injection scanning runs on the same tool results.

The "agent ran via the bridge" vs "developer ran from Claude Code" distinction is purely operational - the security and cost model are identical.

Cross-Workspace Operation

If the bridge's API key is in an overseer workspace, it can use _targetWorkspaceId to act on subordinate workspaces just like any other MCP key. Useful for the CSP citadel model: one bridge fleet, many client workspaces.

The cross-tenant authority check runs at the MCP executor level - the bridge's key proves the home workspace, and oversight relationships gate the swap. The bridge cannot forge a _targetWorkspaceId because the key itself anchors the home workspace.

Resilience

Failure mode	Recovery
Bridge process crashes mid-task	30-min lease expires, task returns to PENDING for re-claim.
Claude Code subprocess hangs	Bridge enforces an outer timeout (configurable, e.g. 15 min). Calls `/complete` with `FAILED`.
MCP token revoked	Next tool call returns `401`. Bridge reports `FAILED` and exits.
Network partition	Bridge can resume polling once reachable. The 30-min lease covers most partitions.
Two bridges running on the same key	Atomic claims serialise. Only one wins per task.

Operational Setup

The bridge is shipped as a separate Node.js binary. Configure via env vars:

Var	Purpose
`OPBOX_MCP_URL`	`https://opbox.app/api/mcp`
`OPBOX_API_KEY`	The `cp_live_*` key. Provision in `Settings > Integrations > Addons > AI Agent`.
`OPBOX_WORKSPACE_ID`	(optional) target workspace if the key is overseer-class and you want a default `_targetWorkspaceId`.
`CLAUDE_CODE_BIN`	Path to the `claude-code` binary.
`BRIDGE_POLL_INTERVAL_MS`	How often to poll for pending tasks (default 5000).
`BRIDGE_TASK_TIMEOUT_MS`	Outer timeout per task (default 600000 = 10 min). The queue lease is separate and defaults to 30 min.

Run the bridge under a process supervisor (systemd, pm2, or your platform's equivalent). On exit, leases auto-expire so a restart is non-disruptive.

Operational Setup (Cloud-Fire)

Some installations prefer the bridge to be cloud-hosted and fire-on-demand rather than continuously polling. This is the path the v1.1 Doc Generation Agent uses. Opbox POSTs to a fire URL when a step needs work; the hosted Claude Code Routine wakes up, claims the task, runs, and shuts down.

See Document Generation for the cloud-fire dispatch path.