@securecoms/agent-bridge 0.11.3 → 0.15.0

package/README.md

@@ -404,6 +404,81 @@ attachments: the cryptography lives in the daemon, not the agent.
 
 ---
 
+## Voice fast path
+
+On a live voice call, the daemon can send an instant, persona-voiced
+one-sentence acknowledgement while your full agent harness is still thinking —
+so the human hears *something* immediately instead of dead air.
+
+**The credential file's `voice` block is now a fallback, not the primary
+source.** As of `@securecoms/agent-bridge` 0.13.0, the daemon fetches this
+agent's voice settings from the backend (`GET /api/v1/agents/{identity_id}/voice-settings`)
+on start and again whenever it receives a `voice_settings_changed` ping, and
+prefers that backend row whenever its `version` is ≥ 1 — an owner has saved
+settings from the web app's "Voice settings" page (`/app/agents/:identityId/voice`).
+A `version: 0` response (nothing saved yet) keeps the file's persona/voice/pace
+as a default, but **the fast-path LLM call goes through the SecureComs
+backend proxy** (`POST /api/v1/voice/fast-complete`) whenever the settings
+fetch itself succeeds — `voice_settings_source` is `"backend"`, or `"file"`
+with `version: 0` — and in that case the file's own
+`fast_path.api_key`/`base_url`/`model` are ignored; only the file's `persona`
+and `enabled` flag still matter, as the fallback source for those fields. The
+daemon needs no API key of its own for the proxied path — the backend proxy
+holds `OPENROUTER_API_KEY` and does the call. **If the settings fetch itself
+fails at boot** (network error, backend down), the daemon has no proxy config
+to fall back to and instead falls back to the file's own `fast_path` block
+in full, including its `api_key`/`api_key_env`/`base_url`/`model` — the
+daemon then calls your own model provider directly with that key until a
+later fetch succeeds.
+
+Check which source is active via the daemon's health endpoint:
+```bash
+curl -H "Authorization: Bearer $(cat <credential-dir>/bridge-token)" \
+  http://127.0.0.1:7077/healthz | jq '.voice_settings_version, .voice_settings_source'
+```
+`voice_settings_source` is `"backend"` (a saved row won), `"file"` (fell back
+to the credential file's `voice` block), or `"none"` (neither is configured).
+
+Add a `voice` block to `agent.json` (used only as the fallback described above):
+
+```json
+"voice": {
+  "persona": { "display_name": "Cortina",
+               "persona": "You are Cortina, a crisp, warm operations lead who co-owns AgentVault with Eric and Chris.",
+               "quirks": ["opens with 'Right —' when sure", "asks one clarifying question instead of guessing"] },
+  "fast_path": { "enabled": true, "base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini",
+                 "api_key_env": "SECURECOMS_VOICE_LLM_KEY", "timeout_ms": 2500, "max_tokens": 80 }
+}
+```
+
+- `persona` describes how the fast-path model should speak; it is folded into
+  a compiled-in system prompt shared with the daemon's other voice guidance.
+- `fast_path.api_key_env` names an environment variable holding your LLM
+  provider's API key (e.g. `SECURECOMS_VOICE_LLM_KEY`); `api_key` accepts one
+  inline instead, but the env-var form is preferred so the key never lives in
+  the credential file. Without a resolvable key, the fast path stays disabled
+  even if `enabled: true`.
+- `fast_path.base_url` must be `https://` or a loopback (`127.0.0.1` /
+  `localhost` / `::1`) `http://` URL — the daemon refuses any other
+  non-loopback plaintext endpoint, the same rule it applies to itself.
+- Only a genuine live voice turn from a human (or unknown) sender fires the
+  fast path; it never fires for the agent's own relayed turns, and a fast-path
+  failure (timeout, network, bad response) is fail-soft — it never blocks or
+  delays your full agent's reply.
+
+**The fast-path call runs through the SecureComs backend proxy — your own
+model key never pays for it — whenever the settings fetch succeeds** (the
+`fast_path.api_key`/`api_key_env`/`base_url`/`model` fields above are
+ignored whenever `voice_settings_source` is `"backend"`, or `"file"` with
+`version: 0`; they only take effect again if the settings fetch fails at
+boot, in which case the daemon falls back to the file's own `fast_path`
+including its key). Each proxied call is metered server-side
+(`voice_fast_completions` table; `usage_daily` metrics `fast_voice_calls`,
+`fast_voice_tokens_in`, `fast_voice_tokens_out`), capped at
+`VOICE_FAST_CALLS_PER_MINUTE` (default 60) per agent.
+
+---
+
 ## Flags and environment
 
 | Flag | Env var | Default | Description |