> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modusbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent voice

> WebRTC-first voice agent reference (Mars + Venus personas, optional Twilio adapter). Skillpack-as-reference paradigm — the install-time agent COPIES code into your host agent repo where it becomes user-owned and mutable, NOT a runtime modusbrain dependency.

# Voice Personas: Mars + Venus

A reference voice agent (WebRTC-first; OpenAI Realtime) shipped as **copy-into-your-repo** content rather than runtime modusbrain skills. The install-time agent reads this recipe, copies the bundle into your host agent repo (e.g. `~/git/your-agent-repo/`), wires the resolver, and starts the voice server. From there, the code lives in YOUR repo, on YOUR cadence, with YOUR edits.

## What ships in the bundle

* **Two personas** — Mars (introspective thought partner; voice `Orus`) and Venus (sharp executive assistant; voice `Aoede`).
* **WebRTC browser client** at `/call?test=1` for the production-grade voice loop. Production load installs zero test instrumentation; `?test=1` enables Web Audio API tee → MediaRecorder capture for the E2E.
* **Tool router** with a read-only allow-list by default (search, query, get\_page, list\_pages, find\_experts, get\_recent\_salience, get\_recent\_transcripts, read\_article). Write ops are denylisted; operators opt in to a bounded set via local override.
* **Persona-aware prompt builder** with identity-first composition + Unicode sanitization for Realtime API safety.
* **Optional Twilio adapter** (`/voice` TwiML, WSS bridge) for phone inbound. Skip if you only want browser voice.
* **Three skills** for resolver routing: `voice-persona-mars`, `voice-persona-venus`, `voice-post-call`.
* **Unit + E2E tests** that ride with the copy. PII-shape regex guards every prompt, classifier triages upstream vs plumbing failures.

## The skillpack-as-reference paradigm

Earlier modusbrain skillpacks installed to `~/.modusbrain/skills/<name>/` as managed-block-canonical first-class skills. The user's local edits drifted from the canonical and updates were either "overwrite local" or "skip update" — neither is what an operator wants on code they've extended.

This recipe ships a different shape: modusbrain holds the up-to-date REFERENCE, and `modusbrain integrations install agent-voice --target <host-repo>` COPIES it into the operator's repo. The code now lives in the host repo, on the operator's release cadence, with the operator's edits. Subsequent `--refresh` invocations diff host-side files against modusbrain's reference and propose changes; the operator picks per-file (keep mine / take theirs / merge).

The shipped reference does NOT contain personal names, hardcoded private paths, or upstream-agent codenames. A CI guard (`scripts/check-no-pii-in-agent-voice.sh`) blocks any drift back; a deterministic import script (`scripts/import-from-upstream.sh`) refreshes the modusbrain reference from an upstream voice-agent source.

## Install

```bash theme={null}
# 1. Detect target repo
export TARGET_REPO=$OPENCLAW_WORKSPACE     # or your agent repo path

# 2. Install
modusbrain integrations install agent-voice --target $TARGET_REPO

# 3. Set env vars in $TARGET_REPO/.env (NOT in modusbrain)
echo "OPENAI_API_KEY=sk-..." >> $TARGET_REPO/.env
echo "DEFAULT_PERSONA=venus" >> $TARGET_REPO/.env

# 4. Implement context builder (optional but recommended)
# Replace $TARGET_REPO/services/voice-agent/code/lib/context-builder.example.mjs
# with your operator-specific implementation. See the contract at:
#   $TARGET_REPO/services/voice-agent/code/lib/personas/context-builder.contract.md

# 5. Run host-side tests
cd $TARGET_REPO/services/voice-agent && bun install && bun run test
# OR if your repo uses npm: npm install && npm test

# 6. Start the voice server
cd $TARGET_REPO/services/voice-agent && bun run start
# Voice agent listens on http://localhost:8765
```

Open `http://localhost:8765/call` and click Connect. The browser asks for mic permission; once granted, it does an SDP exchange via `POST /session`, the OpenAI Realtime API returns the SDP answer, and audio flows bidirectionally over WebRTC.

For test-mode roundtrip checks, append `?test=1` to the URL — that enables the `window._modusbrainTest` instrumentation namespace + MediaRecorder capture of the response audio.

## Update (refresh from modusbrain)

```bash theme={null}
# Pull latest modusbrain → re-run the install with --refresh
git -C $(which modusbrain | xargs -I{} dirname {})/.. pull   # or your modusbrain update path
modusbrain integrations install agent-voice --target $TARGET_REPO --refresh
```

`--refresh` reads the `.modusbrain-source.json` manifest written by the original install, re-computes per-file SHA-256 against modusbrain's current reference, and classifies each file:

* **unchanged-identical** — host file matches modusbrain reference; skip.
* **unchanged-stale** — host file matches the recorded SHA but reference moved; offer to update.
* **locally-modified** — host file diverges from the recorded SHA; show diff, offer three options (keep mine / take theirs / merge).
* **source-deleted** — modusbrain reference removed a file; offer cleanup.
* **source-renamed** — detected via path-mapping; offer to follow.

A transaction journal at `<target>/services/voice-agent/.modusbrain-source.refresh.log` allows partial-apply recovery if the refresh is interrupted.

## Architecture

```
                Browser (call.html)
                       │
                       │  WebRTC (mic + remote audio + data channel)
                       ▼
              ┌─────────────────────┐
              │   server.mjs (8765) │
              │   ─────────────     │
   ┌──────────┤  GET  /call         │      POST /session
   │ static   │  GET  /health        ├──────────────────▶  api.openai.com/v1/realtime/calls
   │ files    │  POST /session       │       (SDP exchange via FormData)
   └──────────┤  POST /tool          │
              │  POST /voice  (Twi.) │
              │  WSS  /ws     (Twi.) │
              └──────────┬───────────┘
                         │  /tool dispatches through tools.mjs allow-list
                         ▼
              ┌─────────────────────┐
              │  tools.mjs router    │
              │  ─────────────       │   denylist: put_page, submit_job, file_upload, ...
              │  READ_ONLY_OPS only  │   allow-list: 8 read ops; operator extends optional ops via override
              └──────────┬───────────┘
                         │
                         ▼  stdio JSON-RPC
              ┌─────────────────────┐
              │  modusbrain serve (MCP)  │
              └─────────────────────┘
```

## Production checklist

Reference code ships intentionally minimal. Before public deployment:

* **Twilio signature validation** on `/voice` — currently absent; add `X-Twilio-Signature` header validation.
* **Rate limiting** on `/session` and `/tool` — currently absent.
* **CORS allowlist** — currently `*`; restrict to your deployed origins.
* **Auth on /tool** — voice-side tool calls currently trust the in-process connection; if you expose `/tool` publicly, gate it behind a session token.
* **HTTPS** — required for browser mic access in production. Use ngrok / Caddy / Cloudflare Tunnel.
* **Twilio fallback URL** — `/fallback` is a TwiML stub; wire to your operator's cell for crash recovery.
* **PII scrub at context-builder** — the shipped `context-builder.example.mjs` includes phone/email regex scrubs, but operators should extend per their brain's PII pattern set.

## Tests

```bash theme={null}
cd $TARGET_REPO/services/voice-agent
bun run test                   # host-side unit tests (5 suites, ~100 cases)
AGENT_VOICE_E2E=1 bun run test:e2e             # WebRTC roundtrip (~$0.10/run)
AGENT_VOICE_FULL_E2E=1 bun run test:full-flow  # openclaw-driven install + roundtrip (~$1-2/run)
```

The full-flow E2E is **friction-discovery**, not a ship-gate. Pre-ship gates on host-side unit tests and the PII guard; flakes in the live OpenAI Realtime path soft-fail with `STATUS: skipped_upstream_degraded` and log to the friction channel.

## What's deferred

* DIY STT+LLM+TTS pipeline (`pipeline.mjs`, `pipeline-v3.mjs` for Gemini Live) — recipe Option A (WebRTC direct to OpenAI Realtime) ships now; Option B (Deepgram + Claude + Cartesia) is a follow-up wave.
* Multilingual Mars — the persona drops the multilingual claim until a multilingual eval lands; restoring it is gated on the eval.
* Live cross-call memory between sessions — the persona is session-scoped today.
* Pre-computed engagement-bid system (the "Bid System" pattern from production deployments) — would belong in `prompt.mjs`.
* Smart VAD presets (quiet/normal/noisy/very\_noisy) — uses Realtime API's default VAD today.
* WebRTC `/session` does not yet ship MediaRecorder fallback for environments where the WebAudio-tee fails.

Each of the deferred items is filed as a TODO in the modusbrain repo's `TODOS.md`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.