@securecoms/agent-bridge 0.11.3 → 0.16.0

package/README.md

@@ -359,6 +359,7 @@ pm2 start "npx @agentvault/connect-agent-bridge --credential ./agent.json" \
 - Install **verifies the daemon actually came up** and fails loudly with the log path if it didn't — no silent crash-loops.
 - Install echoes the credential's `device_id`, `issued_at`, and a redacted api-key fingerprint so you can confirm you installed the newest download. **Re-running install is the only way to update a live (e.g. rotated) credential** — replacing the downloaded file alone does nothing.
 - Optional `--harness openclaw|hermes|custom` prints a paste-ready config snippet with the chosen port and the token-file path (the token itself never appears in output).
+- **One harness gateway serves one agent.** The connector registers a single platform and resolves a single bound identity for the life of the gateway process, so a connector directory (`~/.hermes/plugins/securecoms`, `~/.openclaw/local-plugins/securecoms`) holds exactly one agent. Install and `wire` therefore **refuse** to overwrite a binding that names a different agent — doing so would take the harness away from that agent, not add one alongside it. To run two agents on one host, give each its own harness profile with its own connector directory and binding. To deliberately move a harness to a different agent, pass `--rebind`.
 
 ---
 
@@ -404,6 +405,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 |

package/connectors/hermes/adapter.py

@@ -132,7 +132,17 @@ class SecureComsAdapter(BasePlatformAdapter):
 
     # ── Connection lifecycle ──────────────────────────────────────────────
 
-    async def connect(self) -> bool:
+    async def connect(self, *, is_reconnect: bool = False) -> bool:
+        """Connect to the local daemon.
+
+        ``is_reconnect`` mirrors BasePlatformAdapter.connect's signature —
+        gateway/run.py passes it as a keyword on EVERY call, cold boot
+        included, so an adapter that omits it raises TypeError and the
+        platform never attaches. SecureComs holds no server-side update
+        queue to preserve across an outage (the daemon is a local WS the
+        supervisor re-opens), so the flag carries no behaviour here.
+        """
+        del is_reconnect  # accepted for contract parity; nothing to preserve
         self._stopped = False
 
         # BINDING-STABILITY fold: resolve bound_identity here, ONCE, for the

package/connectors/hermes/tests/test_adapter_wiring.py

@@ -539,3 +539,36 @@ class TestCheckRequirementsWiring:
         monkeypatch.setenv("SECURECOMS_CONNECTION_FILE", str(tmp_path / "does-not-exist.json"))
 
         assert adapter.check_requirements() is False
+
+
+# ---------------------------------------------------------------------------
+# (6) connect() signature contract with BasePlatformAdapter
+# ---------------------------------------------------------------------------
+
+
+class TestConnectSignatureContract:
+    """gateway/run.py ALWAYS calls `adapter.connect(is_reconnect=...)` — on the
+    cold first boot as well as on every reconnect. An adapter whose connect()
+    does not accept that keyword raises TypeError inside the gateway's
+    connect helper, which the reconnect watcher reports as a platform error
+    and retries forever: the daemon looks connected to the SecureComs server
+    while the harness side never attaches and the agent never answers.
+    """
+
+    def test_connect_accepts_is_reconnect_keyword(self):
+        import inspect
+
+        sig = inspect.signature(adapter.SecureComsAdapter.connect)
+        param = sig.parameters.get("is_reconnect")
+        assert param is not None, "connect() must accept the is_reconnect keyword"
+        assert param.kind is inspect.Parameter.KEYWORD_ONLY
+        assert param.default is False
+
+    @pytest.mark.asyncio
+    async def test_connect_is_reconnect_true_reaches_the_unwired_path(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch, files={})  # no binding file -> unwired
+        ok = await a.connect(is_reconnect=True)
+        assert ok is False
+        code, _message, retryable = a.fatal_errors[-1]
+        assert code == "unwired"
+        assert retryable is False