Voicebox documentation

Voicebox Documentation Guide

Welcome to the Voicebox technical documentation. This index organizes the architectural overview, runtime operations, security boundaries, capability guides, and roadmap epics across the repository.

1. Core Architecture & Operations

Start here to understand how Voicebox is structured, how the local server and browser interface run, and how turns execute end-to-end:

Document Topic Summary
00-architectural-overview.md Architectural Overview High-level system architecture, Mermaid component and sequence diagrams, browser/host layers, multi-harness concurrency, and module ownership map.
07-architecture.md Runtime Reference & Generated Tables Detailed component map, live voice and text turn paths, UI pop-over bubbles, workspace roots (core/root.ts), and auto-generated runtime tables.
08-how-it-runs.md Operating Model & Dev Workflow How server.mjs and Vite (vite.config.js) run on loopback (127.0.0.1), runtime invariants, and how documentation stays synchronized with code.
09-agent-loop.md The Agent Loop End-to-end walkthrough of how a voice or text turn starts, resolves into an action, executes inside the active root, and records to the audit log.
12-pre-push-gate.md Testing Lanes & Pre-Push Gate How tests are partitioned into concurrent unit and isolated live lanes, stage timeout budgets, and cross-worktree gate locking.
21-voice-system-commands.md Voice System Commands & Catalogue Deterministic, zero-latency voice commands (lib/system-commands.mjs) for clipboard, theme switching, panel navigation, and audio/session control.
23-pluggable-live-models.md Pluggable Live Models Public harness API, Gemini 3.8 Thinking, OpenAI Realtime, SVG/ASCII layers, audio negotiation and bounded tools.
23-gemini-live-config-and-video.md Gemini Live Config & Camera / Screen Video Full BidiGenerateContentSetup configuration matrix (lib/live-video-stream.mjs), Camera (getUserMedia) and Desktop (getDisplayMedia) live video streaming (public/live-video-experiment.mjs), and the Live Vision Studio Mini-App (public/apps/live-vision-studio.html).
24-gemini-multimodal-platform-plan.md Gemini Multi-Model Capabilities Unified integration for Image Generation (gemini-2.5-flash-image), Veo Video Generation (veo-2.0-generate-001), and Workspace Semantic Search (text-embedding-004) via lib/gemini-models.mjs.
22-roadmap-epics.md Roadmap & Platform Epics Architectural summary of the 6 platform epics (shared rooms, branch landing inspector, local STT/TTS, multi-harness diff comparison, OS hotkey bridge, and Wasm concurrency).

2. Security, Sandboxing & Credential Custody

Voicebox enforces capability boundaries through host-held credentials, explicit extension admission, and OS-level sandboxing:

Document Topic Summary
07-extension-admission.md Extension Admission & Capability Gate How extension proposals are staged, inspected via capability disclosure plans, and admitted using the host token or one-time console approval codes.
08-wire-protocol.md Wire Protocol & Channel Contract Call and observation envelopes (core/wire.ts), lib/channel.mjs RPC semantics, and WebSocket /channel authentication.
09-proxied-custody.md Proxied Custody & Pairing How the local host manages 0600 credentials in HOST_DIR, pairs with remote environments (POST /api/pair), revokes pairings (DELETE /api/pair), and proxies calls.
13-local-browser-authentication-options.md Loopback Authentication Analysis Security evaluation of local browser authentication models (Origin validation, bootstrap tickets, and WebCrypto pairing).
14-s3-l2-bridge-decision.md Sandbox Network Architecture Decision Architectural rationale for keeping interactive voice servers at L1.5 (shared network for cloud model WebSockets) while reserving --unshare-net for offline batch tasks.
15-sandbox.md Environment Sandboxing & Probes How L1 (tools/fence.sh) and L1.5 (tools/fence-unit.sh) sandboxes bound filesystems and processes, how GET /api/probe measures boundaries, and how /exec runs.
18-loopback-session-auth.md Loopback Session Gate (VOICEBOX_LOOPBACK_AUTH=1) Opt-in single-use bootstrap ticket (?bootstrap=) and HttpOnly session cookie protection for local HTTP and WebSocket endpoints.

3. Capabilities, Coding Harnesses & Mini-Apps

Guides covering task delegation to external coding agents, interactive Web MCP Mini-Apps, and WebAssembly tools:

Document Topic Summary
10-delegate-task-d1.md Task Delegation & Durable Handles Authenticated task admission (delegate_task), sealed root-bound task addresses, private audit persistence, and outcome classification.
11-acp-adapter.md Agent Client Protocol (ACP) Adapters Integrating external coding agents (lib/pi-acp.mjs and lib/claude-acp.mjs) over stdio JSON-RPC with bounded timeouts and cancellation.
12-harness-inventory.md Installed Harness Inventory Discovering installed coding agent CLIs (GET /api/harnesses, tools/list-harnesses.mjs) and operator-declared tool catalogues.
16-zero-server-delegation.md Zero-Server Browser Delegation Running task delegation across browser, machine, and remote placements with portable opfs, handle, and machine roots (lib/task-placement.mjs).
17-mini-apps-architecture.md Interactive Mini-Apps (Web MCP) Double-iframe sandbox architecture (/mini-app-bridge.html), private MessagePort RPC, and live voice tool registration via window.webMcp.
20-webassembly-tools.md WebAssembly Tool Shelf Authoring, compiling (tools/build-wasm.mjs), digest-pinning, and executing isolated .wasm modules (buffer-abi/1 and buffer-abi/diff).
25-factory-agent-proposal.md Factory Agent Fleet & Defect Taxonomy Defect mining taxonomy across closed beads, audit yield decision (0% yield -> retire background sweep), and .github/factory-agents.json lane specifications.
27-factory-findings-triage.md Factory Findings Triage The private --sink file report to public-issue pipeline: severity and identity routing, credential sanitisation, the deliberate embargo bypass declared on each issue, fingerprint dedupe, and the reviewed --promote path that is the only way a bead is created.
26-harness-project-live-loop.md Harness & Project Live Integration Loop Bidirectional context & workspace diff loop (lib/harness-project-loop.mjs) connecting coding harnesses (lib/pi-acp.mjs, lib/claude-acp.mjs, lib/cli-harness-executor.mjs) with the active project workspace.
28-factory-review-adapter.md Local Software Factory Review Adapter Bounded local review-trigger adapter (base..tip -> diff-relevant station via fleet-heavy), inbound issue poller with loop guard, and publisher integration.

4. Historical Design Archive & Empirical Evidence

Early pre-implementation spike notes (archived under docs/archive/) and empirical test receipts (under docs/evidence/):

5. How Documentation Stays Verified

scripts/docs-check.mjs automatically verifies the documentation against the live codebase on every test run (tests/docs-drift.test.mjs):

  1. Generated Runtime Blocks: Capabilities, routes, turn resolvers, live voice models, and environment variables between <!-- BEGIN GENERATED: ... --> and <!-- END GENERATED: ... --> markers in README.md, docs/07-architecture.md, and docs/08-how-it-runs.md are derived directly from a live scratch server and source modules. Run npm run docs:write to update them.
  2. File Path Existence: Every backticked repository file path in README.md, PRODUCT.md, docs/*.md, and designs/README.md is checked to ensure the referenced file exists on disk.
  3. Policy Claims (docs/claims.json): Enforces required architectural invariants and blocks retired terminology from reappearing in hand-written prose.