This document catalogues the six major architectural epics designed in the foundational Voicebox briefs and interface studies (docs/archive/00-brief.md, docs/archive/02-environment.md, and docs/archive/interface.md) and describes their implementation across the Voicebox runtime.
Each epic is tracked in Beads (bd) as an epic issue with clear module boundaries and verification criteria.
| Epic | Bead | Title | Origin / Design Reference | Implementation Modules | Priority |
|---|---|---|---|---|---|
| Epic 1 | voicebox-beads-jagv |
Multi-Participant Shared Voice Rooms & Live Presence (“Here, Together”) | docs/archive/00-brief.md, docs/archive/interface.md |
lib/room-presence.mjs, server.mjs, core/shared-log.ts, lib/channel.mjs, public/fused.js |
P2 |
| Epic 2 | voicebox-beads-2pfb |
Visual Branch & Worktree Landing Inspector (“Waiting to Land”) | docs/archive/00-brief.md, docs/archive/interface.md |
lib/branch-landing.mjs, public/apps/landing-inspector.html, server.mjs, lib/git-env.mjs |
P1 |
| Epic 3 | voicebox-beads-1r99 |
Local Offline Speech-to-Text & TTS Fallback (Whisper / Piper) | docs/archive/00-brief.md, docs/07-architecture.md |
lib/offline-speech.mjs, public/offline-speech-client.mjs, lib/live-session.mjs, public/live-voice.js |
P2 |
| Epic 4 | voicebox-beads-80bd |
Multi-Harness Result Comparison & Automated Diff Synthesis | Multi-harness architecture (lib/tasks.mjs) |
lib/harness-comparison.mjs, public/apps/agent-monitor.html, lib/tasks.mjs |
P1 |
| Epic 5 | voicebox-beads-kpp6 |
Native OS Companion / Global Hotkey & System Tray Bridge | docs/archive/00-brief.md (“stay in the conversation while doing something else”) |
lib/os-companion.mjs, scripts/voicebox-companion.mjs, public/pip-mic.mjs |
P3 |
| Epic 6 | voicebox-beads-3l0w |
Wasm Execution Cell Concurrency Semaphore & WASI Preview2 Capability Grants | docs/20-webassembly-tools.md, docs/archive/02-environment.md |
lib/wasm-shelf.mjs, lib/wasm-worker.mjs, core/extensions.ts |
P2 |
voicebox-beads-jagv)In docs/archive/00-brief.md and docs/archive/interface.md, Voicebox specifies a “Here, together” presence model built on shared log + per-root work that still merges. Alongside core/shared-log.ts (appendEntry, markSeen, peerPresence), lib/room-presence.mjs provides createRoomPresenceCoordinator and DEFAULT_PRESENCE_TTL_MS (45000 ms) to coordinate live multi-participant room state, floor control, and shared captions across connected browser tabs, paired environments, and coding harnesses.
lib/room-presence.mjs, server.mjs, tests/room-presence.test.mjs)lib/room-presence.mjs):
joinParticipant, heartbeatParticipant, leaveParticipant) with automatic TTL expiry pruning (DEFAULT_PRESENCE_TTL_MS).requestFloor / releaseFloor) with floor-busy refusals when another active participant holds the microphone and automatic floor release on participant leave or TTL expiry.recordSharedCaption, sharedCaptions).server.mjs):
GET /api/presence returns the live pruned room snapshot (count, floorHolderId, activeSpeaker, participants, sharedCaptions).POST /api/presence dispatches join, heartbeat, leave, requestFloor, releaseFloor, and recordSharedCaption actions, broadcasts { type: "presence", ...snapshot } over /channel, and returns HTTP 409 on floor contention (floor-busy).voicebox-beads-2pfb)docs/archive/interface.md specifies a first-class “Waiting to land” workflow where changes produced in an isolated git branch or worktree by a delegated coding harness appear as an explicit, refusable landing proposal (source root → destination root, changed files, conflict pre-check, and recovery boundary) with “Review merge”, “Merge these changes”, and “Keep separate” actions.
server.mjs, lib/git-env.mjs)server.mjs):
"keep separate" dismissal.voicebox-beads-1r99)When cloud voice provider credentials (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY) are unconfigured or the machine is offline, /live enters standby mode and falls back to local on-device speech recognition and synthesis so the room remains conversational without cloud connectivity.
lib/live-session.mjs, public/live-voice.js)whisper-cli / whisper-cpp) and Piper (piper) or OS TTS (say / espeak-ng) binaries, transcribes 16 kHz PCM audio locally, and synthesizes spoken responses with zero cloud dependencies.public/live-voice.js):
voicebox-beads-80bd)Voicebox supports delegating the same prompt simultaneously across multiple coding harnesses (POST /api/tasks/delegate with agents: ["pi", "claude", "antigravity"]). Once parallel harnesses finish, the operator can compare their generated diffs, modified files, and execution metrics side-by-side.
public/apps/agent-monitor.html, lib/tasks.mjs)public/apps/agent-monitor.html):
voicebox-beads-kpp6)In docs/archive/00-brief.md, a core operator goal is “an agent that stays in the conversation while I do something else.” Alongside the Document Picture-in-Picture microphone (public/pip-mic.mjs), the Native OS Companion bridge lets external global hotkeys and system tray helpers drive push-to-talk, mute, and desktop notifications over loopback.
public/pip-mic.mjs)push-to-talk, toggle-mute, stop-speaking, quick-note), and desktop notification queuing.server.mjs, forwards global shortcut events into the active room, and surfaces native OS notifications when background tasks complete.voicebox-beads-3l0w)As documented in docs/20-webassembly-tools.md, lib/wasm-shelf.mjs spawns isolated worker_threads Workers (lib/wasm-worker.mjs) per callWasmTool invocation with memory ceilings and hard timeouts. To protect host resources under parallel tool fan-out and support capability-scoped virtual preopens, the Wasm shelf enforces a bounded concurrency semaphore and WASI Preview2 capability grants.
lib/wasm-shelf.mjs, lib/wasm-worker.mjs, core/extensions.ts)lib/wasm-shelf.mjs):
VOICEBOX_WASM_MAX_CONCURRENCY, default 4) and bounded wait queue so bursts of concurrent Wasm tool calls never exhaust host threads or memory.lib/wasm-shelf.mjs, lib/wasm-worker.mjs, core/extensions.ts):