`@beevibe/api`

The control plane. Three surfaces — agents speak MCP, the dashboard speaks REST + SSE, your daemon speaks HTTP + WebSocket.

The API is where everything else converges. It enforces auth, exposes tools to agents, serves views to humans, and dispatches sessions to runtimes. It runs server-side and listens on port 3000.

Run it

pnpm --filter @beevibe/api build
pnpm --filter @beevibe/api start    # production: node dist/main.js
pnpm --filter @beevibe/api dev      # watch mode

bash

Required env: DATABASE_URL, BEEVIBE_MCP_SERVER_URL, OPENAI_API_KEY, ANTHROPIC_API_KEY. Override the port with BEEVIBE_API_PORT or PORT. Liveness probe at GET /health.

Three surfaces

The API serves three audiences with different protocols. Auth resolves the same way for all three — every request carries a bearer token.

MCP, for agents

Agents call into the API via the Model Context Protocol. Twelve base tools are available to every agent — task lifecycle, memory reads, room messages, work products. Team and org agents unlock eleven more — escalations, peer asks, negotiations, fact promotion.

REST + SSE, for the dashboard

The web app reads through REST and listens through server-sent events. Tasks, escalations, chat, rooms, identity, runtimes — all REST. Live updates fan out from a single SSE channel.

Runtime control plane, for the daemon

Your daemon registers itself, claims sessions, streams events, and reports completion. The hot path is a WebSocket; the slow path is HTTP polling.

POST /runtime/registerRegister a (daemon, CLI) pair

POST /runtime/claimPull the next session for me

POST /runtime/eventsStream session steps back

POST /runtime/doneMark a session complete

WS /runtime/wsLive push for new work

Auth

Three bearer token types, distinguishable by prefix:

bv_a_… — agent. Used by the CLI when calling MCP tools.
bv_u_… — user. Used by the dashboard and once by the daemon during setup.
bv_d_… — daemon. Used by your daemon for every request after setup.

Under the hood

Every request hits lookupApiKey() from @beevibe/core/auth, which resolves the token to a caller of source agent, human, or daemon. The returned record carries the agent's hierarchy level (ic / team / org), which the MCP tool filter uses to gate access.

Mesh broker

The API hosts an in-process broker that routes agent-to-agent ask and negotiate calls to the right resolver. When the target agent's daemon is offline, the request falls back to the scheduler.

Per-agent caps prevent runaway loops — by default an agent can have at most three in-flight mesh requests at once. Over capacity, requests fail fast with a clear error.

See Mesh in Concepts for the product-level view.

Live updates

Postgres notifies the API and the API pushes events to your browser. Twelve event types fan into React Query invalidations on the dashboard side.

Under the hood

The API runs LISTEN bv_event on a dedicated Postgres connection. Triggers on the major tables emit NOTIFYs. The API serializes those into SSE frames the dashboard can consume.

Source layout

The package source is grouped by concern: auth/ for token lookup, tools/ for MCP tools, routes/ for REST, runtime/ for the daemon control plane, mesh/ for the broker, sse/ for live updates, views/ for read models.

For the wire-level reference, including the full MCP tool list and exact event payloads, see packages/api/README.md on GitHub.

Architecture

Core package