API Reference
The shape of the engine.
Five planes, one port discipline. Volatile surfaces (engines, sandboxes, sync backends, LLM providers, deploy targets, integrations) live behind ports; the stable parts compose them. Swapping any one of them is a one-package change, never surgery.
1. Multi-plane architecture
| Plane | Owns | Canonical source |
|---|---|---|
| Experience | Shared thread, live preview, mission timeline, operator cockpit (mission board, loops, approvals, trace). |
|
| Collaboration | Event-sourced authoritative room log for the conversation; CRDT co-composition for the spec, canvas, and prompts; presence; resumable realtime stream fan-out. |
|
| Control | Identity/SSO, orgs, RBAC, billing, metering, audit, secrets vault, policy engine, promotion gates, licensing. The proprietary spine. |
|
| Agent Runtime | Per-tenant sandboxed Hermes (E2B microVM with snapshot/resume + persistent volume). Multiple engines behind one port: Hermes, OpenCode, Claude Code, Codex. Browser mission runner with scoped short-lived credentials. |
|
| Observability & Health | OpenTelemetry GenAI traces, per-tenant cost metering, session replay, anomaly detection, fleet health, SLO gates, auto-triage agents. |
|
2. Contract surface — packages/contracts/src/
The shared vocabulary. Every plane imports the same shapes; introducing a new event kind means a contracts PR + a reducer test before the wire.
| Module | What ships in it |
|---|---|
| events.ts | Authoritative room event kinds — message, steer, interrupt, tool-call, artifact, approval, gate, promotion, retention. |
| spec.ts | Spec sheet shape used by the spec → review → test promotion gate. |
| browser-mission.ts | Browser-mission envelopes and capability broker contracts (scoped, short-lived credentials, never raw keys). |
| repository-descriptor.ts | GitHub repository descriptor + clone URL resolver for repo-connected workspaces. |
| auth-clock.ts | Identity clock primitives for token rotation and expiry. |
| credential-vault.ts | Control-plane secret shape, scopes, expiry, and revoke semantics. |
| billing.ts | Subscription tier, credit pack, and metering records; double-entry ledger invariants. |
| workspace-ux.ts | Workspace tier flags, presence shape, and surface affordances. |
3. Port surface — packages/ports/src/
Adapters behind every volatile contract. Swapping a port is a one-package change; the planes upstream never know.
port/agent-engine
Hermes (default, identity-bearing), OpenCode, Claude Code, Codex. Dispatched by task profile.
port/sandbox-execution
E2B Firecracker-class microVMs (managed, by-policy region), local Docker for development.
port/browser-runner
Browser-mission driver — isolated Chromium, scoped credentials, default-deny egress.
port/credential-vault
Per-tenant control-plane vault; brokered short-lived capabilities only.
port/billing
Subscription + metered billable boundary. Spend caps enforced in the control plane, not in agent prompts.
port/product-kit
Outcome → blueprint → starter → configuration → integration → evaluation → commercialization.
port/loops
Durable scheduled + continuous work with budgets, independent checkers, out-of-loop kills.
4. HTTP API — /api/*
The HTTP surface is intentionally narrow. Anything stateful lives behind the realtime stream; the endpoints below are the public contract.
| Path | Method | Auth | Purpose |
|---|---|---|---|
| /api/healthz | GET | public | Service-level health probe. |
| /api/session/refresh | POST | session | Refresh the session token with the rotation window. |
| /api/track/request-event | POST | public | Anon-hashed telemetry event ingest (IP is SHA-256 hashed in middleware). |
| /api/contact | POST | public | Public contact form ingest. |
| /api/github/connect/start | GET | user | Begin the GitHub App install flow. |
| /api/github/connect/callback | GET | user | Complete the GitHub App install flow. |
| /api/auth/* | * | session | Workspace-admission routes; URL cannot mint a room credential. |
| /api/internal/* | POST | service | Service-to-service routes used by internal automation. |
5. Realtime — CRDT sync + presence + turn arbitration
- Authoritative room log: server-ordered, append-only, replayable from any point in the workspace lifetime.
- CRDT co-composition: spec, canvas, prompt buffer — Yjs + y-sweet in production; Loro under periodic review.
- Presence: typing, thinking, cursor, viewing; first-class events on the same stream as content.
- Turn arbitration: concurrent human messages within a window batch into one attributed multi-author turn; any participant can steer or interrupt.
- Stream resume: a reconnecting client gets every event it missed plus the current snapshot, with no manual refresh.
6. Webhooks
Every webhook verifies provider signature + delivery ID before the matching capability is dispatched. The capability is scoped (workspace, mission, actions, resources, expiry), never a long-lived raw token.
| Provider | Surface contract |
|---|---|
| Stripe | Signed events (v1) bound to the workspace vault. Armalo checks the signature header, then routes to the matching mission via metadata. |
| GitHub | App-installed events (push, pull_request, check_run, installation). Delivery ID + signature verified against the webhook secret. |
| Cloud API webhooks verified via app secret + verify_token; conversation state stored alongside the room event log. | |
| Meta ads | Conversions API server-side events with dedup keys; Pixel CAPI events mirrored for parity testing. |
| Email (SendGrid or Mailgun) | Inbound webhook + outbound event stream; provider-region pinned by tenant policy. |
Need the source?
The contracts and ports directories are the canonical source of truth. Architectural decisions are recorded as ADRs in docs/adr/.