@agfpd/voice-connect 0.1.11 → 0.2.0

package/README.md

@@ -1,26 +1,44 @@
 # voice-connect
 
-**Text-to-voice for a team of AI agents — the voice component of [iapeer](https://github.com/agfpd/iapeer).**
+**A standalone voice service (STT + TTS) for a team of AI agents.**
 
-An MCP server that gives AI agents a single tool — `voice_create` — to turn text into a ready-to-send `.ogg/opus` voice file.
-
-> **Built for iapeer.** It isn't a standalone TTS service — it runs inside [iapeer](https://github.com/agfpd/iapeer), alongside `iapeer-memory` and `telegram-runtime`. A peer synthesizes a file with one tool call and delivers it over iapeer's own messaging.
+voice-connect gives agents and runtimes one voice layer with two halves — text-to-speech and speech-to-text — over a single multi-provider core. Each request runs a cascade with fallback inside the tool: cloud quality first, a local engine as the floor, so synthesis and transcription still work with no API key and no network. It runs on its own (configured from a file) or inside [iapeer](https://github.com/agfpd/iapeer) (configured from the peer-profile).
 
 ## How it works
 
-Engine routing with fallback happens inside the tool: **Gemini 3.1 Flash TTS** primary (ru+en in one pass) → **gpt-audio** over OpenRouter → **F5-TTS** (live prosody) → **Supertonic 3** local floor (offline). The agent passes text and gets back a path; delivery (e.g. `send_to_peer(personality, attachments=[path])`) stays the caller's job — the tool only produces the file.
+Two facades sit on one core. Agents reach it as an MCP server; runtimes reach it over an OpenAI-compatible HTTP service. Both call the same cascade — no synthesis or routing logic is duplicated between them.
+
+```
+   agents (MCP)                 runtimes (HTTP)
+   tts / stt                    POST /v1/audio/speech
+                                POST /v1/audio/transcriptions
+        \                              /
+         \                            /
+          ▼                          ▼
+   ┌──────────────────────────────────────┐
+   │   core: router + provider cascade     │
+   ├──────────────────────────────────────┤
+   │ TTS:  Gemini → gpt-audio → F5 → Super │
+   │ STT:  speaches → mlx-whisper          │
+   └──────────────────────────────────────┘
+```
+
+The router advances to the next engine only on a known "can't-serve" error (quota, no key, unreachable); any other error propagates, so a real bug surfaces instead of being masked by a fallback. The last rung in each cascade is a local engine — Supertonic 3 for TTS, mlx-whisper for STT — with no fallback of its own: it is the floor, so a result is always produced when an engine is reachable at all.
 
-Short text is synthesized synchronously: the path comes back right away. Long text (over ~2000 chars) is synthesized asynchronously — the tool returns a `job_id` immediately, and a background worker notifies the caller over IAP when the file is ready.
+Delivery is never the service's job. The MCP `tts` tool hands back a file path; you attach it yourself with `send_to_peer(personality, attachments=[path])`. The HTTP facade returns the audio bytes in the response.
+
+Short text is synthesized synchronously — the path comes back at once. Text over ~2000 chars goes async: the `tts` tool returns a `job_id` immediately and a detached worker notifies you over IAP when the file is ready. The HTTP `/v1/audio/speech` route is always synchronous (a runtime holds the connection and wants bytes back).
 
 ## Requirements
 
 - **Node.js ≥ 18**
-- **ffmpeg / ffprobe** on `PATH` (audio encode + probe). On macOS: `brew install ffmpeg`.
-- **python3** — only for the first provision of the local Supertonic fallback (a managed venv is created on demand).
-- **API keys** — read from the environment, or from a shell rc file as a fallback:
-  - `GEMINI_API_KEY` — the primary engine (Google Gemini TTS).
-  - `OPENROUTER_API_KEY` — the gpt-audio fallback rung (OpenRouter).
-  - Neither key is strictly required: with no key, routing falls through to the local F5 / Supertonic engines.
+- **ffmpeg / ffprobe** on `PATH` — audio encode and probe. On macOS: `brew install ffmpeg`.
+- **python3** — only for the first provision of the local Supertonic TTS floor (a managed venv is created on demand).
+- **mlx_whisper** on `PATH` — only for the local STT floor (Apple-silicon Whisper, installed as a `uv` tool). Without it, STT needs a configured speaches endpoint.
+- **API keys** — read from the environment, a shell rc file, or the standalone config file:
+  - `GEMINI_API_KEY` — the primary TTS engine (Google Gemini TTS).
+  - `OPENROUTER_API_KEY` — the gpt-audio TTS fallback rung (OpenRouter).
+  - Neither key is required: with no key, TTS routing falls through to the local F5 / Supertonic engines.
 
 ## Install
 
@@ -37,18 +55,78 @@ Or run the MCP server directly from npm:
 npx -y @agfpd/voice-connect@latest
 ```
 
-## Usage
+The package name is `@agfpd/voice-connect`; the MCP entry point is the `voice-connect-mcp` bin. Wire it into an MCP client by pointing the client at that command, e.g.:
+
+```jsonc
+{
+  "mcpServers": {
+    "voice-connect": {
+      "command": "npx",
+      "args": ["-y", "@agfpd/voice-connect@latest"]
+    }
+  }
+}
+```
+
+### Always-on HTTP service
+
+The HTTP facade is meant to run as a long-lived local service so runtimes can hit it without spawning a process per request. It is self-managed: it owns its own launchd agent (label `com.voice-connect.http`), in the package's own namespace, and writes a discovery slot (`~/.iapeer/voice-provider.json`) consumers read for the endpoint.
+
+```
+node scripts/launchd-http.mjs render      # print the plist (no writes)
+node scripts/launchd-http.mjs install     # write plist + slot, (re)bootstrap
+node scripts/launchd-http.mjs status      # launchctl print + slot
+node scripts/launchd-http.mjs uninstall   # bootout + remove plist + slot
+```
+
+It binds `127.0.0.1:8127` by default (local-only); override with `PEER_VOICE_HTTP_HOST` / `PEER_VOICE_HTTP_PORT`. `GET /health` reports liveness.
+
+## What it does
+
+### MCP tools
+
+| Tool | In → out | Notes |
+|------|----------|-------|
+| `tts` | text → `.ogg/opus` file | Short → `{ path, ... }` sync; long (>~2000 chars) → `{ job_id }` + an IAP "done" message later. |
+| `stt` | audio file path → text | Returns `{ text, engine, fallback_from? }`. |
+| `voice_create` | — | DEPRECATED alias for `tts`, kept one release; use `tts`. |
+
+### HTTP routes (OpenAI-compatible)
 
-The server exposes a single tool:
+| Route | Method | Body | Returns |
+|-------|--------|------|---------|
+| `/v1/audio/speech` | POST | JSON (`input`/`text`, `voice?`, `model?`/`engine?`, `lang?`, `style?`) | Ogg/Opus bytes; engine/fallback in `X-Voice-*` headers. |
+| `/v1/audio/transcriptions` | POST | multipart (`file`, `language?`, `prompt?`, `engine?`, `response_format?`) | `{ text }`, or plain text with `response_format=text`. |
+| `/health` | GET | — | `{ status, service, version }`. |
+
+### Engines
+
+TTS — first applicable engine wins; the cascade advances on a known can't-serve error:
+
+| Engine | Tier | Model | Notes |
+|--------|------|-------|-------|
+| Gemini | cloud primary | `gemini-3.1-flash-tts-preview` | ru+en in one pass; honors `style`; needs `GEMINI_API_KEY`. |
+| gpt-audio | cloud second | `openai/gpt-audio` (OpenRouter) | Multilingual one pass; honors `style`; needs `OPENROUTER_API_KEY`. |
+| F5-TTS | local | `f5-tts` | Live-prosody Russian rung; per-peer voice cloning; applies on the `ru` route only. |
+| Supertonic 3 | local floor | `supertonic-3` | Offline, one pass in the routed language; the floor. |
+
+STT — speaches when an endpoint is configured, otherwise the local floor:
+
+| Engine | Tier | Notes |
+|--------|------|-------|
+| speaches | primary | OpenAI-compatible `/v1/audio/transcriptions`; set `PEER_VOICE_STT_ENDPOINT`. Skipped when unset. |
+| mlx-whisper | local floor | Offline Apple-silicon Whisper via the `mlx_whisper` CLI. |
+
+## `tts` parameters
 
 ```
-voice_create(text, voice?, lang?, style?, note?, engine?, out_path?)
+tts(text, voice?, lang?, style?, note?, engine?, out_path?)
 ```
 
 | Param | Type | Description |
 |-------|------|-------------|
 | `text` | string (required) | Text to speak. Mixed ru+en is fine — read in one pass. |
-| `voice` | string | Gemini prebuilt voice. Default `Aoede`. |
+| `voice` | string | Gemini prebuilt voice for the primary engine. Default `Aoede`. |
 | `lang` | `ru` \| `en` \| `na` | Language hint for the fallback engines (Gemini reads any language itself). Omit to auto-detect by character share. |
 | `style` | string | Delivery directive (tone / emotion / tempo) for the cloud engines; ignored by the local fallbacks. |
 | `note` | string | Reminder echoed back in the async "done" message (e.g. who to deliver to). Ignored for short (sync) text. |
@@ -57,16 +135,38 @@ voice_create(text, voice?, lang?, style?, note?, engine?, out_path?)
 
 **Returns** — short text (sync): `{ path, engine, voice, lang?, probe, fallback_from? }`. Long text (async): `{ job_id, status: "started" }`, followed by an IAP message `voice job <id> done path=<path> note=<note>` when synthesis finishes.
 
-Delivery is never automatic — attach the returned file yourself, e.g. `send_to_peer(personality, attachments=[path])`.
+## `stt` parameters
+
+```
+stt(audio_path, lang?, prompt?, engine?)
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `audio_path` | string (required) | Absolute path to the audio file to transcribe (e.g. a received voice `.ogg`). |
+| `lang` | string | Language hint (ISO-639-1: `en`, `ru`, …). Omit to auto-detect. |
+| `prompt` | string | Decoder-priming prompt — biases spelling/casing of terms (e.g. keep `Claude Code` in Latin). Not part of the output. |
+| `engine` | `auto` \| `speaches` \| `mlx-whisper` | Force an engine. Default `auto`. |
+
+**Returns** `{ text, engine, fallback_from? }`.
+
+## Standalone and iapeer modes
+
+The mode is decided by one signal: whether the caller has an iapeer identity. Both modes share the same core and the same key ladder (env → shell rc → config file).
+
+- **Standalone** — no iapeer identity. Voice and keys come from one config file: `$PEER_VOICE_CONFIG`, else `<PEER_VOICE_HOME>/config.json`:
+
+  ```jsonc
+  {
+    "voice": { "gemini-3.1-flash-tts-preview": "Aoede", "supertonic-3": "F3" },
+    "keys":  { "GEMINI_API_KEY": "...", "OPENROUTER_API_KEY": "..." }
+  }
+  ```
 
-## What makes it different
+  voice-connect only reads this file; it never writes config itself.
 
-- **One tool, four engines.** The cascade routes from cloud quality down to an offline floor inside the tool; the caller never picks an engine unless it wants to.
-- **Mixed ru+en in one pass.** Gemini reads both languages together, so a Russian-dominant line with a few English words comes back natural — no splitting, no per-language calls.
-- **Always a result.** With no API key, routing falls through to the local F5 / Supertonic engines; synthesis works offline.
-- **Long text never blocks.** Over ~2000 chars the tool returns a `job_id` at once and a detached worker notifies the caller over IAP when the file is ready.
-- **Produces, never delivers.** The tool hands back a path; the caller attaches it with `send_to_peer` — one clear boundary between synthesis and delivery.
+- **iapeer** — the caller has an iapeer identity (`PEER_PERSONALITY` or a cwd peer-profile). Voice comes from the peer-profile; keys from the host env/rc. iapeer owns the configuration.
 
 ## License
 
-[Apache-2.0](LICENSE). Platform: macOS. voice-connect is the voice provider for the [iapeer](https://github.com/agfpd/iapeer) ecosystem — a component of iapeer, not a standalone system.
+[Apache-2.0](LICENSE). Platform: macOS.

package/bin/voice-connect.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Unified entry point for @agfpd/voice-connect.
+ *
+ * Arg-dispatched so the SAME bin serves both surfaces without breaking the
+ * live per-peer MCP wiring:
+ *   • no subcommand (or `mcp`) → the MCP stdio server (what the per-peer
+ *     .mcp.json launches via `npx -y @agfpd/voice-connect@latest`, relying on
+ *     this bin being the package-name match — backward compatible).
+ *   • init | update | status | uninstall → the host-provider lifecycle
+ *     (src/provider.mjs), the verbs the iapeer foundation invokes.
+ *
+ * `voice-connect-mcp` remains a direct alias for the MCP server.
+ */
+const cmd = process.argv[2];
+
+const die = (err) => {
+  process.stderr.write(`voice-connect: fatal: ${err && err.stack ? err.stack : err}\n`);
+  process.exit(1);
+};
+
+switch (cmd) {
+  case undefined:
+  case 'mcp': {
+    const { main } = await import('../src/server.mjs');
+    main().catch(die);
+    break;
+  }
+  case 'init': {
+    const { init } = await import('../src/provider.mjs');
+    await init().catch(die);
+    break;
+  }
+  case 'update': {
+    const { update } = await import('../src/provider.mjs');
+    await update().catch(die);
+    break;
+  }
+  case 'status': {
+    const { status } = await import('../src/provider.mjs');
+    try { status(); } catch (e) { die(e); }
+    break;
+  }
+  case 'uninstall': {
+    const { uninstall } = await import('../src/provider.mjs');
+    try { uninstall(); } catch (e) { die(e); }
+    break;
+  }
+  default:
+    process.stderr.write(
+      `voice-connect: unknown command: ${cmd}\n` +
+      `usage: voice-connect [mcp|init|update|status|uninstall]\n` +
+      `  (no subcommand) | mcp   run the MCP stdio server\n` +
+      `  init                    deploy the host backend (launchd HTTP + slot; prompts TTS keys)\n` +
+      `  update                  re-deploy fresh code + restart + bump slot version\n` +
+      `  status                  print slot + launchd state + service health\n` +
+      `  uninstall               remove launchd service + slot + provider home\n`,
+    );
+    process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/voice-connect",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "voice-connect — voice service for agents. MCP tools tts (text → ready-to-send .ogg/opus voice file) and stt (audio → text) over one core, plus an OpenAI-compatible HTTP facade (/v1/audio/speech + /v1/audio/transcriptions) for runtimes. Cascade with fallback inside each tool — TTS: Gemini 3.1 Flash → gpt-audio (OpenRouter) → F5-TTS → Supertonic 3 local floor; STT: speaches → mlx-whisper local floor. Delivery stays the caller's job (send_to_peer attachments).",
   "license": "Apache-2.0",
   "author": {
@@ -32,6 +32,7 @@
   ],
   "type": "module",
   "bin": {
+    "voice-connect": "bin/voice-connect.mjs",
     "voice-connect-mcp": "bin/peer-voice-mcp.mjs"
   },
   "files": [

package/src/http.mjs

@@ -24,9 +24,9 @@
  * not a hand-rolled boundary parser.
  */
 import { createServer as nodeCreateServer } from 'node:http';
-import { readFile, writeFile, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { readFile, writeFile, rm, mkdir, utimes } from 'node:fs/promises';
+import { tmpdir, homedir } from 'node:os';
+import { join, dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { createVoice } from './voice.mjs';
 import { transcribe as transcribeAudio } from './stt.mjs';
@@ -235,6 +235,21 @@ export function createHttpServer({ voice, transcribe, version } = {}) {
   });
 }
 
+/** Liveness file the provider slot points at; the foundation reads its mtime
+ *  for freshness in `iapeer status`. Kept in sync with provider.mjs HEARTBEAT_PATH. */
+const HEARTBEAT_PATH = join(homedir(), '.iapeer', 'state', 'voice-connect', 'http.heartbeat');
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+/** mtime-touch the heartbeat (create on first call). Best-effort — never throws. */
+async function touchHeartbeat() {
+  try {
+    await mkdir(dirname(HEARTBEAT_PATH), { recursive: true });
+    const now = new Date();
+    try { await utimes(HEARTBEAT_PATH, now, now); }
+    catch { await writeFile(HEARTBEAT_PATH, ''); }
+  } catch { /* heartbeat is advisory; a write failure must not kill the service */ }
+}
+
 /** Bootstrap: bind and run the always-on facade. Importable without side effects. */
 export async function main() {
   const server = createHttpServer();
@@ -245,8 +260,11 @@ export async function main() {
     server.listen(port, host, resolve);
   });
   process.stderr.write(`voice-connect http: listening on http://${host}:${port} (version ${readVersion()})\n`);
+  await touchHeartbeat();
+  const heartbeat = setInterval(touchHeartbeat, HEARTBEAT_INTERVAL_MS);
+  heartbeat.unref(); // never keep the event loop alive on the heartbeat alone
   for (const sig of ['SIGINT', 'SIGTERM']) {
-    process.on(sig, () => server.close(() => process.exit(0)));
+    process.on(sig, () => { clearInterval(heartbeat); server.close(() => process.exit(0)); });
   }
   return server;
 }

package/src/provider.mjs

@@ -0,0 +1,344 @@
+/**
+ * Host-level provider lifecycle for voice-connect — the callable verbs the
+ * iapeer foundation invokes (`init`, `update`) plus `status` and `uninstall`.
+ *
+ * Contract (agreed with the iapeer peer, 2026-06-22): voice-connect is a
+ * host-level provider modelled 1:1 on the memory provider. The foundation's
+ * onboarding step runs `voice-connect init` with inherited stdio; its update
+ * cascade leg runs `voice-connect update` via
+ * `npm exec --package=@agfpd/voice-connect@latest`. The core only READS the
+ * slot ~/.iapeer/voice-provider.json — the provider declares it.
+ *
+ * Scope (the PIN): init = HOST BACKEND only — the self-managed launchd HTTP
+ * facade (com.voice-connect.http) + the discovery slot + TTS-key prompts. It
+ * wires NO host-wide MCP. The voice_create/tts MCP surface is per-peer via
+ * `iapeer enable voice-connect <peer>` (cwd-resolved per-peer voice identity,
+ * the 0.1.10 codex-parity mechanism). So the slot carries no provision/
+ * unprovision commands (unlike memory — voice is opt-in, not auto-at-birth).
+ *
+ * Robust-update model: init/update copy the RUNNING package's runtime tree into
+ * a STABLE provider home (~/.iapeer/providers/voice-connect) and point the
+ * launchd plist there — never at the ephemeral npx cache (which is GC'd; a
+ * plist into _npx/<hash> is the exact fragile path to avoid). `update` runs
+ * from the `npm exec …@latest` temp package = fresh code; it re-copies that into
+ * the stable home, restarts the service, and the slot version (read from the
+ * copied package.json) reflects the new release — so the foundation's
+ * before/after version-gate is real.
+ *
+ * This module is the single source of truth for the launchd posture; the dev
+ * tool scripts/launchd-http.mjs delegates here (codeHome = the repo, no copy).
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, rmSync, cpSync,
+  existsSync, accessSync, constants,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { configPath } from './configfile.mjs';
+import { readGeminiKey, readOpenRouterKey } from './apikey.mjs';
+
+const HOME = homedir();
+
+// ── Identity ───────────────────────────────────────────────────────────────
+// SERVICE drives the label, log dir and the slot's `provider` field. ROLE is the
+// stable discovery role — the slot FILE NAME and the operator env-file name,
+// which survive any implementation rename (mirrors ~/.iapeer/memory-provider.json:
+// file name = role, `provider` field = concrete provider).
+const SERVICE = 'voice-connect';
+const ROLE = 'voice-provider';
+const LABEL = `com.${SERVICE}.http`;
+
+const STABLE_HOME = join(HOME, '.iapeer', 'providers', SERVICE);
+const PLIST_PATH = join(HOME, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+const LOG_DIR = join(HOME, '.iapeer', 'logs', `${SERVICE}-http`);
+const SLOT_PATH = join(HOME, '.iapeer', `${ROLE}.json`);
+// Host-local operator STT config (speaches primary endpoint/model) — NOT in the
+// repo, NOT published. Sourced into the plist so the deployed service has a
+// working STT tier and survives a bare reinstall. Absent → mlx-whisper floor.
+const STT_ENV_FILE = join(HOME, '.iapeer', `${ROLE}.env`);
+// Liveness file the HTTP daemon mtime-touches; the foundation reads its mtime
+// for freshness in `iapeer status`. http.mjs computes the same path.
+const HEARTBEAT_PATH = join(HOME, '.iapeer', 'state', SERVICE, 'http.heartbeat');
+const DOMAIN = `gui/${process.getuid()}`;
+
+// The running package's root: src/provider.mjs → repo root. In dev that's the
+// checkout; under `npm exec …@latest` it's the freshly-fetched temp package.
+const SOURCE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// ── small helpers ────────────────────────────────────────────────────────────
+function port() {
+  const p = parseInt(process.env.PEER_VOICE_HTTP_PORT || '', 10);
+  return Number.isInteger(p) && p > 0 ? p : 8127;
+}
+function host() {
+  return (process.env.PEER_VOICE_HTTP_HOST || '127.0.0.1').trim() || '127.0.0.1';
+}
+
+/** Absolute node path for launchd's minimal PATH. Prefer the brew SYMLINK over
+ *  the versioned Cellar path (which breaks on every `brew upgrade node`). */
+function nodeBin() {
+  for (const c of ['/opt/homebrew/bin/node', '/usr/local/bin/node']) {
+    try { accessSync(c, constants.X_OK); return c; } catch { /* try next */ }
+  }
+  return process.execPath;
+}
+
+/** Parse a simple KEY=VALUE / `export KEY=VALUE` env file (optional quotes). */
+function readEnvFile(p) {
+  const out = {};
+  try {
+    for (const line of readFileSync(p, 'utf8').split('\n')) {
+      const m = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*?)\s*$/);
+      if (!m || line.trim().startsWith('#')) continue;
+      let v = m[2];
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+      out[m[1]] = v;
+    }
+  } catch { /* no file → no STT config */ }
+  return out;
+}
+
+/** Resolved STT tier config: the operator env-file is the durable source;
+ *  process.env overrides it. Empty endpoint → speaches tier skipped, floor used. */
+function sttConfig() {
+  const file = readEnvFile(STT_ENV_FILE);
+  const endpoint = (process.env.PEER_VOICE_STT_ENDPOINT ?? file.PEER_VOICE_STT_ENDPOINT ?? '').trim();
+  const model = (process.env.PEER_VOICE_STT_MODEL ?? file.PEER_VOICE_STT_MODEL ?? '').trim();
+  return { endpoint, model };
+}
+
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+function readManifest(codeHome) {
+  return JSON.parse(readFileSync(join(codeHome, 'package.json'), 'utf8'));
+}
+
+// ── render: plist + slot (parameterized by codeHome) ─────────────────────────
+/** Render the launchd plist for a service whose code lives at `codeHome`. */
+export function renderPlist(codeHome) {
+  const node = nodeBin();
+  const entry = join(codeHome, 'bin', 'peer-voice-http.mjs');
+  // ~/.local/bin FIRST: the mlx-whisper STT floor lives there (uv tool); without
+  // it the floor crash-loops ENOENT under launchd's minimal PATH. Then brew + system.
+  const PATH = `${HOME}/.local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin`;
+  const { endpoint: sttEndpoint, model: sttModel } = sttConfig();
+  const sttEnv =
+    (sttEndpoint ? `        <key>PEER_VOICE_STT_ENDPOINT</key>\n        <string>${xml(sttEndpoint)}</string>\n` : '') +
+    (sttModel ? `        <key>PEER_VOICE_STT_MODEL</key>\n        <string>${xml(sttModel)}</string>\n` : '');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>${xml(node)}</string>
+        <string>${xml(entry)}</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>${xml(codeHome)}</string>
+
+    <!-- launchd gives a minimal PATH; bake an absolute node path + a usable PATH
+         so a bare binary name can't crash-loop. -->
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${PATH}</string>
+        <key>PEER_VOICE_HTTP_PORT</key>
+        <string>${port()}</string>
+        <key>PEER_VOICE_HTTP_HOST</key>
+        <string>${xml(host())}</string>
+${sttEnv}    </dict>
+
+    <!-- durable: start at load, restart on crash, throttle the respawn -->
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>${xml(join(LOG_DIR, 'launchd-stdout.log'))}</string>
+    <key>StandardErrorPath</key>
+    <string>${xml(join(LOG_DIR, 'launchd-stderr.log'))}</string>
+</dict>
+</plist>
+`;
+}
+
+/** Declarative discovery slot — the manifest the core READS (never writes).
+ *  Mirrors ~/.iapeer/memory-provider.json: `provider` (role), package, version,
+ *  registeredAt, heartbeat; plus voice-specific endpoint/routes for discovery. */
+export function renderSlot(codeHome) {
+  const pkg = readManifest(codeHome);
+  return JSON.stringify(
+    {
+      provider: SERVICE,
+      package: pkg.name,
+      version: pkg.version,
+      registeredAt: new Date().toISOString(),
+      heartbeat: HEARTBEAT_PATH,
+      managed: 'self',
+      label: LABEL,
+      host: host(),
+      port: port(),
+      endpoint: `http://${host()}:${port()}`,
+      routes: {
+        tts: '/v1/audio/speech',
+        stt: '/v1/audio/transcriptions',
+        health: '/health',
+      },
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+// ── launchd install / uninstall / status (no code copy) ──────────────────────
+/** Write plist+slot for code at `codeHome` and (re)load the agent. Idempotent. */
+export function installLaunchd(codeHome) {
+  mkdirSync(LOG_DIR, { recursive: true });
+  mkdirSync(dirname(SLOT_PATH), { recursive: true });
+  mkdirSync(dirname(PLIST_PATH), { recursive: true });
+  mkdirSync(dirname(HEARTBEAT_PATH), { recursive: true });
+  writeFileSync(PLIST_PATH, renderPlist(codeHome));
+  writeFileSync(SLOT_PATH, renderSlot(codeHome));
+  // Idempotent (re)load: bootout an existing instance, then bootstrap fresh.
+  try { execFileSync('launchctl', ['bootout', DOMAIN, PLIST_PATH], { stdio: 'ignore' }); } catch { /* not loaded */ }
+  execFileSync('launchctl', ['bootstrap', DOMAIN, PLIST_PATH], { stdio: 'inherit' });
+}
+
+export function uninstall() {
+  try { execFileSync('launchctl', ['bootout', DOMAIN, PLIST_PATH], { stdio: 'ignore' }); } catch { /* not loaded */ }
+  rmSync(PLIST_PATH, { force: true });
+  rmSync(SLOT_PATH, { force: true });
+  // Remove our code home; KEEP user data (config.json keys) + logs + STT env.
+  rmSync(STABLE_HOME, { recursive: true, force: true });
+  process.stdout.write(
+    `uninstalled ${LABEL}\n  removed: plist, slot, ${STABLE_HOME}\n  kept:    logs, ${STT_ENV_FILE}, key config\n`,
+  );
+}
+
+export function status() {
+  const slot = existsSync(SLOT_PATH) ? readFileSync(SLOT_PATH, 'utf8') : null;
+  process.stdout.write(
+    `provider: ${SERVICE}\nlabel:    ${LABEL}\nplist:    ${PLIST_PATH} ${existsSync(PLIST_PATH) ? '(present)' : '(absent)'}\n` +
+    `slot:     ${SLOT_PATH} ${slot ? '(present)' : '(absent)'}\nhome:     ${STABLE_HOME} ${existsSync(STABLE_HOME) ? '(present)' : '(absent)'}\n\n`,
+  );
+  if (slot) process.stdout.write(slot + '\n');
+  try {
+    process.stdout.write(execFileSync('launchctl', ['print', `${DOMAIN}/${LABEL}`], { encoding: 'utf8' }));
+  } catch {
+    process.stdout.write(`(${LABEL} not loaded in ${DOMAIN})\n`);
+  }
+}
+
+// ── runtime tree copy → stable home ──────────────────────────────────────────
+/** Copy the running package's runtime files into the stable provider home,
+ *  replacing any prior copy (so files removed in a new release don't linger),
+ *  and MATERIALIZE the runtime dependency. The published tarball ships no
+ *  node_modules (`files` is bin/src/LICENSE/README), so a bare file copy leaves
+ *  the service ERR_MODULE_NOT_FOUND on @modelcontextprotocol/sdk. We prefer
+ *  copying the source's node_modules (offline, the exact tested versions); when
+ *  absent — the `npm exec …@latest` case, where deps hoist to the npx env root,
+ *  not inside the package — we `npm install --omit=dev` from the registry. */
+function copyRuntimeTree(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const item of ['bin', 'src']) {
+    rmSync(join(dest, item), { recursive: true, force: true });
+    cpSync(join(src, item), join(dest, item), { recursive: true });
+  }
+  for (const file of ['package.json', 'LICENSE', 'README.md']) {
+    const from = join(src, file);
+    if (existsSync(from)) cpSync(from, join(dest, file));
+  }
+  const srcModules = join(src, 'node_modules');
+  const destModules = join(dest, 'node_modules');
+  rmSync(destModules, { recursive: true, force: true });
+  if (existsSync(srcModules)) {
+    cpSync(srcModules, destModules, { recursive: true });
+  } else {
+    execFileSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund', '--no-save'],
+      { cwd: dest, stdio: 'inherit' });
+  }
+}
+
+// ── interactive key prompts (init only) ──────────────────────────────────────
+/** Prompt once on a TTY for any unresolved cloud key and persist to the
+ *  autonomous config file's `keys` map. The RUNTIME stays read-only; this write
+ *  is the operator provision action. Skipped without a TTY (update / headless)
+ *  and for keys already resolvable via env/rc/config — local floors need none. */
+async function ensureKeys() {
+  if (!process.stdin.isTTY) return;
+  const wanted = [
+    { name: 'GEMINI_API_KEY', get: readGeminiKey, label: 'Gemini TTS (primary)' },
+    { name: 'OPENROUTER_API_KEY', get: readOpenRouterKey, label: 'gpt-audio via OpenRouter (fallback)' },
+  ];
+  const missing = wanted.filter((k) => !k.get());
+  if (!missing.length) return;
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((res) => rl.question(q, (a) => res(a.trim())));
+  process.stdout.write(
+    '\nvoice-connect: optional TTS cloud keys (blank = skip; the local F5/Supertonic floor needs none):\n',
+  );
+  const collected = {};
+  for (const k of missing) {
+    const v = await ask(`  ${k.label} — ${k.name}: `);
+    if (v) collected[k.name] = v;
+  }
+  rl.close();
+  if (Object.keys(collected).length) persistKeys(collected);
+}
+
+/** Merge `keys` into the autonomous config file (create dirs as needed). */
+function persistKeys(keys) {
+  const p = configPath();
+  let data = {};
+  try { data = JSON.parse(readFileSync(p, 'utf8')) || {}; } catch { /* new file */ }
+  data.keys = { ...(data.keys && typeof data.keys === 'object' ? data.keys : {}), ...keys };
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(data, null, 2) + '\n');
+  process.stdout.write(`  saved ${Object.keys(keys).join(', ')} → ${p}\n`);
+}
+
+// ── the verbs ────────────────────────────────────────────────────────────────
+/** Deploy the host backend: copy code → stable home, (init only) prompt keys,
+ *  install the launchd HTTP service + slot. Idempotent. */
+export async function deploy({ interactive = false } = {}) {
+  const prev = readSlotVersion();
+  copyRuntimeTree(SOURCE_ROOT, STABLE_HOME);
+  if (interactive) await ensureKeys();
+  installLaunchd(STABLE_HOME);
+  const pkg = readManifest(STABLE_HOME);
+  const stt = sttConfig();
+  const verb = prev ? (prev === pkg.version ? `re-deployed (v${pkg.version})` : `updated ${prev} → ${pkg.version}`) : `installed v${pkg.version}`;
+  process.stdout.write(
+    `voice-connect ${verb}\n  label:    ${LABEL}\n  home:     ${STABLE_HOME}\n  slot:     ${SLOT_PATH}\n` +
+    `  endpoint: http://${host()}:${port()}\n  heartbeat:${HEARTBEAT_PATH}\n` +
+    `  STT primary: ${stt.endpoint || '(none — mlx-whisper floor only)'}${stt.model ? ` [${stt.model}]` : ''}\n`,
+  );
+}
+
+/** Read the current slot's version (for update from→to reporting), or null. */
+function readSlotVersion() {
+  try { return JSON.parse(readFileSync(SLOT_PATH, 'utf8')).version || null; } catch { return null; }
+}
+
+/** `init` — onboard install. Inherits the tty for key prompts. */
+export const init = () => deploy({ interactive: true });
+
+/** `update` — cascade leg. Non-interactive; re-copies fresh code + restarts +
+ *  bumps the slot version. MUST be invoked via
+ *  `npm exec --package=@agfpd/voice-connect@latest -- voice-connect update`
+ *  so SOURCE_ROOT is the freshly-fetched package, not a stale on-disk copy. */
+export const update = () => deploy({ interactive: false });
+
+export const paths = { SERVICE, ROLE, LABEL, STABLE_HOME, PLIST_PATH, SLOT_PATH, STT_ENV_FILE, HEARTBEAT_PATH, LOG_DIR };