@agfpd/iapeer 0.4.18 → 0.4.19

package/CHANGELOG.md

@@ -10,6 +10,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.19] - 2026-06-22
+
+### Added
+
+- **Voice provider slot** (`@agfpd/voice-connect`) — a second declarative provider slot
+  alongside memory, integrated into the host lifecycle:
+  - `iapeer onboard` now offers an optional **DEFAULT-YES** voice step (after memory) in
+    both the linear path (`--no-voice` / `--voice <pkg>`) and the interactive wizard. It
+    installs the voice provider's **HOST BACKEND only** (a self-managed launchd HTTP
+    TTS/STT service) via the provider's own `init` (inherited stdio) — per-peer voice
+    tooling stays the separate explicit `iapeer enable voice-connect <peer>`. Report-only
+    for the exit code (an empty slot is a valid state).
+  - `iapeer update` cascades to the voice provider (best-effort, version-gated) via its
+    own `npm exec --package=@agfpd/voice-connect@latest -- voice-connect update` verb —
+    after foundation + runtimes + memory.
+  - `iapeer status` shows a `voice:` line (`<provider> <version> @ <endpoint>` + heartbeat
+    freshness, or `none`). The voice slot is read-only to the core, fail-open; unlike
+    memory it carries no provision/unprovision (voice is opt-in per-peer, not at birth)
+    and adds an `endpoint` for HTTP-facade discovery (telegram-STT / voicetalk).
+
 ## [0.4.18] - 2026-06-22
 
 ### Changed
@@ -274,7 +294,8 @@ Initial public release — the foundation core of the iapeer multi-agent ecosyst
 - **Heterogeneous peers** — AI agents (Claude, Codex), humans (Telegram), and services
   (timer = cron, watcher = event) are all first-class and addressed the same way.
 
-[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.18...HEAD
+[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.19...HEAD
+[0.4.19]: https://github.com/agfpd/iapeer/compare/v0.4.18...v0.4.19
 [0.4.18]: https://github.com/agfpd/iapeer/compare/v0.4.17...v0.4.18
 [0.4.17]: https://github.com/agfpd/iapeer/compare/v0.4.16...v0.4.17
 [0.4.16]: https://github.com/agfpd/iapeer/compare/v0.4.15...v0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -1088,10 +1088,10 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
   { sig: 'help | --help | -h', desc: 'print this usage (works appended to any verb; executes nothing)' },
   { sig: 'daemon [--install-plist]', desc: 'run the host-wide HTTP-MCP router (launchd-held)' },
   {
-    sig: 'onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--infra <csv>]',
-    desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
+    sig: 'onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--no-voice] [--voice <pkg>] [--infra <csv>]',
+    desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory → voice (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
   },
-  { sig: 'status', desc: 'host snapshot: version, daemon health, memory slot (<provider> | none)' },
+  { sig: 'status', desc: 'host snapshot: version, daemon health, memory + voice slots (<provider> | none)' },
   { sig: 'install-runtime <runtime> [--package pkg] [--npx]', desc: 'npx-install a runtime package + deploy its declared peer-set' },
   { sig: 'update-runtime <runtime> | --all [--force]', desc: "version-gate → re-install + re-provision declared set → restart the runtime's peers" },
   { sig: 'init [cwd] [--runtime r] [--description d]', desc: 'onboard the CURRENT folder as a peer (name = folder name; identity + MCP + doctrine)' },
@@ -1231,7 +1231,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Interactive TUI wizard (Фаза TUI-редизайн) — the DEFAULT for an
         // interactive `iapeer onboard`. Routed ONLY in a real interactive terminal
         // and never for an automation path (--accept-risk / --dry-run / --no-memory
-        // / --infra), which stay on the deterministic linear flow below. Escape
+        // / --no-voice / --infra), which stay on the deterministic linear flow below. Escape
         // hatch: IAPEER_ONBOARD_WIZARD=0 forces the linear path (recovery / scripts
         // that want the old flow). The wizard owns its own gate screen, so we route
         // BEFORE the readline gate. It fails closed: no real TTY →
@@ -1241,6 +1241,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           flags['accept-risk'] === true ||
           flags['dry-run'] === true ||
           flags['no-memory'] === true ||
+          flags['no-voice'] === true ||
           typeof flags.infra === 'string'
         if (!wizardOptOut && !automationFlag && process.stdin.isTTY === true && process.stdout.isTTY === true) {
           const { runOnboardWizard, WIZARD_NOT_INTERACTIVE } = await import('../tui/onboard/run.tsx')
@@ -1342,6 +1343,19 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         })
         const memLabel = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
         out(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${memLabel})\n`)
+        // Voice slot (host backend only — per-peer voice tooling is the separate
+        // `iapeer enable voice-connect <peer>`): optional DEFAULT-YES install of the
+        // voice provider; its own init runs with INHERITED stdio (it owns the TTS-key
+        // prompts). REPORT-ONLY for the exit code — an empty slot is a valid state.
+        const { onboardVoiceProvider } = await import('../onboard/voice.ts')
+        const voice = await onboardVoiceProvider({
+          skip: flags['no-voice'] === true,
+          package: typeof flags.voice === 'string' ? flags.voice : undefined,
+          dryRun: flags['dry-run'] === true,
+          env,
+        })
+        const voiceLabel = voice.provider ? `${voice.provider.provider} ${voice.provider.version}` : 'none'
+        out(`voice: ${voice.state}${voice.detail ? ` — ${voice.detail}` : ''} (slot: ${voiceLabel})\n`)
         // Runtime auth readiness (clean-host prerequisite): a peer runs the runtime's
         // interactive TUI; the launcher auto-clears first-run modals (theme/trust) but
         // CANNOT complete a login OAuth flow. Warn for every INSTALLED runtime (marketplace
@@ -1945,9 +1959,11 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // ── Cascade tail: runtimes + memory provider (best-effort) ──
         const { updateAllRuntimes } = await import('../runtime/update.ts')
         const { updateMemoryProvider } = await import('../onboard/memory.ts')
+        const { updateVoiceProvider } = await import('../onboard/voice.ts')
         const tail = await cascadeTail({
           runtimes: () => updateAllRuntimes({ force: flags.force === true, env, warn: m => errOut(`warn: ${m}\n`) }),
           memory: () => updateMemoryProvider({ env }),
+          voice: () => updateVoiceProvider({ env }),
           out,
         })
         return foundationExit === 0 && !tail.failed ? 0 : 1

package/src/onboard/voice.ts

@@ -0,0 +1,204 @@
+// Voice-slot onboard step (the voice provider = @agfpd/voice-connect).
+// Host-phase, optional, DEFAULT-YES: install the voice provider package and run ITS
+// OWN init-verb — the provider deploys its HOST BACKEND (a self-managed launchd HTTP
+// service), writes the slot declaration, and prompts for any TTS keys over our
+// inherited tty. The core never writes the slot itself.
+//
+// SCOPE — host backend ONLY (the PIN, confirmed with voice-connect): init wires NO
+// host MCP server. Per-peer voice tooling (the voice_create / tts MCP surface) is the
+// SEPARATE explicit `iapeer enable voice-connect <peer>` (a marketplace capability
+// plugin whose per-peer identity resolves from the MCP stdio child's cwd — a single
+// host-wide server cannot resolve per-peer voices). So onboard ≠ per-peer wiring; the
+// backend it installs is independently valuable (telegram-STT / voicetalk consume the
+// HTTP facade with no MCP at all). Unlike memory there is therefore NO per-peer birth
+// hook and the slot carries NO provision/unprovision.
+//
+// Outcome semantics: this step NEVER fails the onboard exit code — an empty slot is a
+// fully valid state regardless of why (skipped / not yet published / non-tty refusal).
+// Outcomes are reported, not enforced. Mirrors onboard/memory.ts deliberately (same
+// vocabulary), minus memory's --human/--runtime init args (voice init takes none).
+
+import { spawnSync } from 'child_process'
+import { readVoiceProvider, type VoiceProvider } from '../status/index.ts'
+
+/** The distribution default voice provider. */
+export const DEFAULT_VOICE_PACKAGE = '@agfpd/voice-connect'
+
+export interface VoiceOnboardOptions {
+  /** --no-voice: skip the step entirely. */
+  skip?: boolean
+  /** --voice <pkg>: override the provider package (default @agfpd/voice-connect). */
+  package?: string
+  dryRun?: boolean
+  env?: NodeJS.ProcessEnv
+  /** Wall-clock backstop (ms) for the provider-init subprocess — a hung provider must
+   *  NEVER wedge onboard (voice is optional). The interactive wizard passes a generous
+   *  value; the linear path leaves it unset (no timeout). */
+  timeoutMs?: number
+  /** Injectable runner (tests). Default: availability probe + `npx -y <pkg> init`
+   *  with inherited stdio. */
+  runInit?: (
+    pkg: string,
+    args: string[],
+    env: NodeJS.ProcessEnv,
+    timeoutMs?: number,
+  ) => { status: number | null; unavailable: boolean }
+}
+
+export interface VoiceOnboardResult {
+  state:
+    | 'installed' // provider init succeeded and declared the slot
+    | 'already' // slot already occupied by the SAME package — idempotent no-op
+    | 'skipped-flag' // --no-voice
+    | 'skipped-unavailable' // package not published / no network — soft skip (contract)
+    | 'refused-foreign' // slot occupied by ANOTHER provider — explicit refusal
+    | 'provider-init-failed' // provider init ran and exited non-zero / declared nothing
+    | 'dry-run'
+  provider: VoiceProvider | null
+  detail?: string
+}
+
+function defaultRunInit(
+  pkg: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+  timeoutMs?: number,
+): { status: number | null; unavailable: boolean } {
+  // Availability probe FIRST (cheap, side-effect-free, bounded): an unpublished package
+  // / no network → soft-skip per the contract (the provider's release order must never
+  // block the core's onboard).
+  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env, timeout: 60_000 })
+  if (probe.status !== 0) return { status: probe.status, unavailable: true }
+  // INHERITED stdio — the provider owns its install questions (TTS-key prompts happen
+  // here, once). The provider bin (`voice-connect`) is an ARG-DISPATCHER: a subcommand
+  // (`init`) routes to its lifecycle path, NOT the backward-compatible MCP-stdio path
+  // (no-subcommand) — so `npx -y <pkg> init` correctly hits init.
+  const r = spawnSync('npx', ['-y', pkg, ...args], {
+    stdio: 'inherit',
+    env,
+    ...(timeoutMs ? { timeout: timeoutMs } : {}),
+  })
+  return { status: r.status, unavailable: false }
+}
+
+export async function onboardVoiceProvider(opts: VoiceOnboardOptions = {}): Promise<VoiceOnboardResult> {
+  const env = opts.env ?? process.env
+  const pkg = opts.package?.trim() || DEFAULT_VOICE_PACKAGE
+  const existing = readVoiceProvider(env)
+  if (opts.skip) return { state: 'skipped-flag', provider: existing }
+  if (existing) {
+    if (existing.package === pkg) return { state: 'already', provider: existing }
+    // Never silently install over an occupied slot (contract: FORBIDDEN).
+    return {
+      state: 'refused-foreign',
+      provider: existing,
+      detail: `slot is occupied by "${existing.provider}" (${existing.package}) — uninstall it first`,
+    }
+  }
+  // voice init takes NO core-known facts (no --human/--runtime — the host backend is
+  // peer-agnostic; per-peer voice is a separate `iapeer enable`).
+  const args = ['init']
+  if (opts.dryRun) {
+    return { state: 'dry-run', provider: null, detail: `would run: npx -y ${pkg} ${args.join(' ')}` }
+  }
+  const run = opts.runInit ?? defaultRunInit
+  const r = run(pkg, args, env, opts.timeoutMs)
+  if (r.unavailable) {
+    return {
+      state: 'skipped-unavailable',
+      provider: null,
+      detail: `${pkg} is not available (not published yet / no network) — install later: npx ${pkg} init`,
+    }
+  }
+  if (r.status !== 0) {
+    return {
+      state: 'provider-init-failed',
+      provider: readVoiceProvider(env),
+      detail: `provider init exited ${r.status ?? 'null'}`,
+    }
+  }
+  // The PROVIDER declares the slot; verify it actually did (its contract duty).
+  const after = readVoiceProvider(env)
+  if (!after) {
+    return {
+      state: 'provider-init-failed',
+      provider: null,
+      detail: 'provider init succeeded but did not declare the slot (voice-provider.json missing)',
+    }
+  }
+  return { state: 'installed', provider: after }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// updateVoiceProvider — the voice leg of the cascade `iapeer update` (FU12)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface VoiceUpdateResult {
+  state:
+    | 'updated' // provider update ran and the slot version advanced
+    | 'already-latest' // ran but the slot version is unchanged
+    | 'no-slot' // no provider claimed — nothing to update
+    | 'skipped-unavailable' // package not published / no network — soft skip
+    | 'failed' // provider update exited non-zero
+  package?: string
+  from?: string
+  to?: string
+  detail?: string
+}
+
+/** The provider's CLI bin name = the unscoped package name (`@agfpd/voice-connect` →
+ *  `voice-connect`). That bin is the arg-dispatcher; `<bin> update` routes to its
+ *  lifecycle update path. */
+function voiceBinName(pkg: string): string {
+  return pkg.replace(/^@[^/]+\//, '')
+}
+
+function defaultRunVoiceUpdate(pkg: string, env: NodeJS.ProcessEnv): { status: number | null; unavailable: boolean } {
+  // Availability probe FIRST (cheap, bounded): unpublished / no network → soft-skip.
+  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env, timeout: 60_000 })
+  if (probe.status !== 0) return { status: probe.status, unavailable: true }
+  // `npm exec --package=<pkg>@latest -- <bin> update` fetches the latest published
+  // package into a fresh temp and runs ITS update verb from there — bypassing any
+  // PATH name-shadow (the 0.2.9 pitfall: a bare `npx <bin>` could re-run a stale
+  // installed binary). voice-connect's update then re-copies its runtime tree into the
+  // STABLE provider home (~/.iapeer/providers/voice-connect/, never the GC'd npx cache),
+  // bootout→bootstraps its HTTP service, and bumps slot.version — so the before/after
+  // version-gate this leg reads is real. The provider OWNS update + slot-write + its own
+  // service restart.
+  const r = spawnSync(
+    'npm',
+    ['exec', '--yes', `--package=${pkg}@latest`, '--', voiceBinName(pkg), 'update'],
+    { stdio: 'inherit', env },
+  )
+  return { status: r.status, unavailable: false }
+}
+
+/**
+ * Update the CLAIMED voice provider via ITS OWN update verb (slot contract: the
+ * provider owns install/update + slot-write + service restart; the core only invokes +
+ * reads the slot). No slot → nothing to update. Reports from→to by reading the slot
+ * version before/after. BEST-EFFORT by the caller (the cascade never aborts on it).
+ */
+export function updateVoiceProvider(opts: {
+  env?: NodeJS.ProcessEnv
+  dryRun?: boolean
+  runUpdate?: (pkg: string, env: NodeJS.ProcessEnv) => { status: number | null; unavailable: boolean }
+} = {}): VoiceUpdateResult {
+  const env = opts.env ?? process.env
+  const slot = readVoiceProvider(env)
+  if (!slot) return { state: 'no-slot', detail: 'no voice provider claimed — nothing to update' }
+  const pkg = slot.package
+  const from = slot.version
+  if (opts.dryRun) {
+    return { state: 'updated', package: pkg, from, detail: `would run: npm exec --package=${pkg}@latest -- ${voiceBinName(pkg)} update` }
+  }
+  const run = opts.runUpdate ?? defaultRunVoiceUpdate
+  const r = run(pkg, env)
+  if (r.unavailable) {
+    return { state: 'skipped-unavailable', package: pkg, from, detail: `${pkg}@latest not reachable (no network / unpublished)` }
+  }
+  if (r.status !== 0) return { state: 'failed', package: pkg, from, detail: `provider update exited ${r.status ?? 'null'}` }
+  const to = readVoiceProvider(env)?.version
+  if (from && to && from === to) return { state: 'already-latest', package: pkg, from, to }
+  return { state: 'updated', package: pkg, from, to }
+}

package/src/status/index.ts

@@ -1,10 +1,14 @@
 // Status — the host-snapshot verb: installed-binary version, daemon health, and
-// the MEMORY SLOT line (docs/Слот памяти — контракт memory provider.md). The slot
-// is DECLARATIVE: a root file `~/.iapeer/memory-provider.json` written (atomically)
-// by the PROVIDER's own init/uninstall — the core only ever READS it. An absent or
-// unreadable file is the EMPTY slot — a fully valid state (bare core), never an
-// error (fail-open). The core never acts on heartbeat staleness — it only REPORTS
-// it (healing the provider's daemon is the provider's job).
+// the provider-SLOT lines (docs/Слот памяти — контракт memory provider.md). A slot
+// is DECLARATIVE: a root file (`~/.iapeer/memory-provider.json`, `voice-provider.json`)
+// written (atomically) by the PROVIDER's own init/uninstall — the core only ever
+// READS it. An absent or unreadable file is the EMPTY slot — a fully valid state
+// (bare core), never an error (fail-open). The core never acts on heartbeat
+// staleness — it only REPORTS it (healing the provider's daemon is the provider's
+// job). Two slots share the same declarative contract: MEMORY (auto-at-birth, carries
+// provision/unprovision) and VOICE (host-level backend only; per-peer voice tooling is
+// the separate `iapeer enable voice-connect <peer>` — the voice slot carries NO
+// provision/unprovision, and adds an `endpoint` for HTTP-facade discovery).
 
 import { closeSync, openSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
@@ -97,8 +101,9 @@ export function readMemoryProvider(env: NodeJS.ProcessEnv = process.env): Memory
   }
 }
 
-/** Age (s) of the provider's heartbeat file, or null (none declared / unreadable). */
-export function heartbeatAgeSecs(provider: MemoryProvider, nowMs: number = Date.now()): number | null {
+/** Age (s) of a provider's heartbeat file, or null (none declared / unreadable).
+ *  Generic over any slot carrying an optional `heartbeat` path (memory + voice). */
+export function heartbeatAgeSecs(provider: { heartbeat?: string }, nowMs: number = Date.now()): number | null {
   if (!provider.heartbeat) return null
   try {
     return Math.max(0, Math.floor((nowMs - statSync(provider.heartbeat).mtimeMs) / 1000))
@@ -107,6 +112,63 @@ export function heartbeatAgeSecs(provider: MemoryProvider, nowMs: number = Date.
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// VOICE slot — the voice-connect provider declaration (the same declarative
+// contract as memory, two differences by design: NO provision/unprovision (voice
+// is opt-in PER-PEER via `iapeer enable`, not auto-at-birth), and an `endpoint`
+// (+ a named `routes` object the core does NOT parse) for the HTTP-facade that
+// telegram-STT / voicetalk consume with no MCP at all). The core only READS it.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The voice-slot declaration filename in the storage root. */
+export const VOICE_PROVIDER_FILE = 'voice-provider.json'
+
+export interface VoiceProvider {
+  /** Provider name occupying the slot (e.g. "voice-connect"). */
+  provider: string
+  /** npm package of the provider (e.g. "@agfpd/voice-connect"). */
+  package: string
+  version: string
+  registeredAt: string
+  /** Optional liveness proxy: an absolute path whose mtime the provider's HTTP
+   *  daemon refreshes. status reports its age; the core takes NO action on staleness. */
+  heartbeat?: string
+  /** Base URL of the provider's HTTP facade (e.g. "http://127.0.0.1:PORT") — shown
+   *  in status for discovery. Opaque to the core. */
+  endpoint?: string
+}
+
+export function voiceProviderPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveGlobalRoot(env), VOICE_PROVIDER_FILE)
+}
+
+/**
+ * Read the voice-slot declaration. null = EMPTY slot (absent / unreadable /
+ * schema-invalid file) — a valid state, so this NEVER throws (fail-open to bare).
+ * Self-management extras the provider may add (label/managed/host/port/routes) are
+ * ignored — the core reads only the contract fields it acts/reports on.
+ */
+export function readVoiceProvider(env: NodeJS.ProcessEnv = process.env): VoiceProvider | null {
+  try {
+    const raw = JSON.parse(readFileSync(voiceProviderPath(env), 'utf8')) as unknown
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+    const o = raw as Record<string, unknown>
+    if (typeof o.provider !== 'string' || !o.provider.trim()) return null
+    if (typeof o.package !== 'string' || !o.package.trim()) return null
+    if (typeof o.version !== 'string' || !o.version.trim()) return null
+    return {
+      provider: o.provider.trim(),
+      package: o.package.trim(),
+      version: o.version.trim(),
+      registeredAt: typeof o.registeredAt === 'string' ? o.registeredAt : '',
+      ...(typeof o.heartbeat === 'string' && o.heartbeat.trim() ? { heartbeat: o.heartbeat.trim() } : {}),
+      ...(typeof o.endpoint === 'string' && o.endpoint.trim() ? { endpoint: o.endpoint.trim() } : {}),
+    }
+  } catch {
+    return null // empty slot — bare core is valid
+  }
+}
+
 /**
  * Probe whether the iapeer binary holds Full Disk Access (macOS TCC). Reads the
  * user TCC.db — a canonical FDA-gated resource that is NEVER promptable (silent
@@ -137,6 +199,7 @@ export interface HostStatus {
   version: string
   daemon: { healthy: boolean; url: string | null; sock: string | null }
   memory: { provider: MemoryProvider | null; heartbeatAgeSecs: number | null }
+  voice: { provider: VoiceProvider | null; heartbeatAgeSecs: number | null }
   /** Full Disk Access of the iapeer binary: true granted / false not-granted /
    *  null undeterminable (non-macOS or TCC.db unreadable for a non-TCC reason). */
   fda: boolean | null
@@ -165,11 +228,13 @@ export async function hostStatus(opts: HostStatusOptions = {}): Promise<HostStat
   }
   const health = await waitForDaemonHealthy({ env, timeoutMs: 2500, needConsecutive: 1, probe: opts.probe })
   const provider = readMemoryProvider(env)
+  const voice = readVoiceProvider(env)
   const fda = (opts.fdaProbe ?? (() => probeFullDiskAccess(env)))()
   return {
     version: IAPEER_VERSION,
     daemon: { healthy: health.healthy, url, sock },
     memory: { provider, heartbeatAgeSecs: provider ? heartbeatAgeSecs(provider) : null },
+    voice: { provider: voice, heartbeatAgeSecs: voice ? heartbeatAgeSecs(voice) : null },
     fda,
   }
 }
@@ -190,6 +255,17 @@ export function formatHostStatus(s: HostStatus): string {
       : ' (daemon not running — no heartbeat file)'
   }
   const memory = s.memory.provider ? `${s.memory.provider.provider} ${s.memory.provider.version}${hb}` : 'none'
+  // Voice slot — same heartbeat semantics as memory; also show the HTTP endpoint
+  // (discovery target for telegram-STT / voicetalk). 'none' when the slot is empty.
+  let vhb = ''
+  if (s.voice.provider?.heartbeat) {
+    vhb = s.voice.heartbeatAgeSecs !== null
+      ? ` (heartbeat ${s.voice.heartbeatAgeSecs}s ago)`
+      : ' (daemon not running — no heartbeat file)'
+  }
+  const voice = s.voice.provider
+    ? `${s.voice.provider.provider} ${s.voice.provider.version}${s.voice.provider.endpoint ? ` @ ${s.voice.provider.endpoint}` : ''}${vhb}`
+    : 'none'
   // FDA line: granted → terse OK; NOT granted → the actionable hint (a fresh host
   // without FDA silently meets TCC prompts on every new protected class — peers
   // read protected folders + foreign app containers, attributed to this binary;
@@ -204,5 +280,5 @@ export function formatHostStatus(s: HostStatus): string {
   } else {
     fda = 'fda: unknown (not macOS / undeterminable)'
   }
-  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\n${fda}\n`
+  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\nvoice: ${voice}\n${fda}\n`
 }

package/src/tui/onboard/app.tsx

@@ -18,6 +18,7 @@ import { iapeerBinPath } from '../../install/index.ts'
 export interface WizardResult {
   code: number
   memoryConsent: boolean
+  voiceConsent: boolean
   advisories: string[]
   summary: string[]
   telegramConsent: boolean
@@ -27,7 +28,7 @@ export interface WizardResult {
   hostRuntime?: OnboardRuntime
 }
 
-type Phase = 'gate' | 'running' | 'telegram' | 'memory' | 'declined' | 'finishing'
+type Phase = 'gate' | 'running' | 'telegram' | 'memory' | 'voice' | 'declined' | 'finishing'
 type StepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'fail'
 interface Step {
   key: string
@@ -96,16 +97,17 @@ export function OnboardApp({
   const [advisories, setAdvisories] = useState<string[]>([])
   const [hostRuntime, setHostRuntime] = useState<OnboardRuntime | undefined>(undefined)
   const [telegramConsent, setTelegramConsent] = useState(false)
+  const [memoryConsent, setMemoryConsent] = useState(false)
   const spin = useSpinnerFrame(phase === 'running')
 
-  const finish = (memoryConsent: boolean): void => {
+  const finish = (voiceConsent: boolean): void => {
     const failed = steps.some(s => s.status === 'fail')
     const summary = steps.map(s => {
       const mark = s.status === 'ok' ? '✓' : s.status === 'warn' ? '!' : s.status === 'fail' ? '✗' : '·'
       return `  ${mark} ${s.label}${s.detail ? ` — ${s.detail}` : ''}`
     })
     summary.unshift(failed ? 'Onboard finished with errors:' : 'Onboard complete:')
-    onResult({ code: failed ? 1 : 0, memoryConsent, telegramConsent, advisories, summary, hostRuntime })
+    onResult({ code: failed ? 1 : 0, memoryConsent, voiceConsent, telegramConsent, advisories, summary, hostRuntime })
     setPhase('finishing')
     setTimeout(() => exit(), 30)
   }
@@ -135,19 +137,34 @@ export function OnboardApp({
     { isActive: phase === 'telegram' },
   )
 
-  // Memory consent — DEFAULT-YES ([Y/n]: Enter or y → install).
+  // Memory consent — DEFAULT-YES ([Y/n]: Enter or y → install). Records the decision
+  // and advances to the voice consent (the install itself runs post-Ink). Then → voice.
+  useInput(
+    (input, key) => {
+      if (input === 'n' || input === 'N') {
+        setMemoryConsent(false)
+        setPhase('voice')
+      } else if (input === 'y' || input === 'Y' || key.return) {
+        setMemoryConsent(true)
+        setPhase('voice')
+      }
+    },
+    { isActive: phase === 'memory' },
+  )
+
+  // Voice consent — DEFAULT-YES ([Y/n]: Enter or y → install). The LAST consent → finish.
   useInput(
     (input, key) => {
       if (input === 'n' || input === 'N') finish(false)
       else if (input === 'y' || input === 'Y' || key.return) finish(true)
     },
-    { isActive: phase === 'memory' },
+    { isActive: phase === 'voice' },
   )
 
   // Declined → exit 1 (no host mutation).
   useEffect(() => {
     if (phase !== 'declined') return
-    onResult({ code: 1, memoryConsent: false, telegramConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
+    onResult({ code: 1, memoryConsent: false, voiceConsent: false, telegramConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
     const t = setTimeout(() => exit(), 30)
     return () => clearTimeout(t)
   }, [phase, onResult, exit])
@@ -305,7 +322,7 @@ export function OnboardApp({
     return <Text color="red">onboard aborted — risk not accepted.</Text>
   }
 
-  // running | telegram | memory | finishing
+  // running | telegram | memory | voice | finishing
   return (
     <Box flexDirection="column">
       <Box marginBottom={1}>
@@ -352,6 +369,14 @@ export function OnboardApp({
           <Text dimColor> Gives your agents a shared knowledge vault. [Y/n]</Text>
         </Box>
       ) : null}
+      {phase === 'voice' ? (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold color="cyan">
+            ? Install the voice provider backend (@agfpd/voice-connect)?
+          </Text>
+          <Text dimColor> A local text-to-speech / speech-to-text HTTP service. Per-agent voice tools are a separate `iapeer enable`. [Y/n]</Text>
+        </Box>
+      ) : null}
     </Box>
   )
 }

package/src/tui/onboard/run.tsx

@@ -71,7 +71,7 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
   // wizard only runs on one), off under NO_COLOR.
   const a = makeAnsi(colorEnabled(env, process.stdout))
 
-  let result: WizardResult = { code: 0, memoryConsent: false, telegramConsent: false, advisories: [], summary: [] }
+  let result: WizardResult = { code: 0, memoryConsent: false, voiceConsent: false, telegramConsent: false, advisories: [], summary: [] }
   try {
     const app = render(<OnboardApp env={env} onResult={r => (result = r)} />)
     await app.waitUntilExit()
@@ -79,9 +79,10 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
     return WIZARD_NOT_INTERACTIVE
   }
 
-  // Post-Ink interactive provisioning — telegram THEN memory (the canonical order:
-  // telegram creates the human peer that memory's --human resolves from). These own
-  // the terminal (inherited stdio / readline), so they run AFTER Ink unmounts (no
+  // Post-Ink interactive provisioning — telegram THEN memory THEN voice (the canonical
+  // order: telegram creates the human peer that memory's --human resolves from; voice is
+  // an independent host backend). These own the terminal (inherited stdio / readline),
+  // so they run AFTER Ink unmounts (no
   // contention). NON-WEDGE: ignore SIGINT in the parent so Ctrl-C kills only the
   // CURRENT step's child/readline and onboard continues to the summary, instead of
   // the whole flow dying. The no-op handler is queued past the blocking spawnSync.
@@ -136,6 +137,33 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
         '\n' + paintResult('memory', 'skipped', ' — set it up later with `npx @agfpd/iapeer-memory init`', a) + '\n',
       )
     }
+
+    if (result.voiceConsent) {
+      const { onboardVoiceProvider } = await import('../../onboard/voice.ts')
+      process.stdout.write(
+        '\n' +
+          a.bold('Installing the voice provider backend (@agfpd/voice-connect)…') +
+          '\n' +
+          a.dim(
+            'A local TTS/STT HTTP service. Voice is OPTIONAL: press Ctrl-C to skip it\n' +
+              '(set it up later with `npx @agfpd/voice-connect init`).',
+          ) +
+          '\n\n',
+      )
+      try {
+        const v = await onboardVoiceProvider({ env, timeoutMs: 12 * 60_000 })
+        const label = v.provider ? `${v.provider.provider} ${v.provider.version}` : 'none'
+        const rest = `${v.detail ? ` — ${v.detail}` : ''} ${a.dim(`(slot: ${label})`)}`
+        process.stdout.write('\n' + paintResult('voice', v.state, rest, a) + '\n')
+      } catch (e) {
+        const rest = ` — ${e instanceof Error ? e.message : String(e)} ${a.dim('(set up later: `npx @agfpd/voice-connect init`)')}`
+        process.stdout.write('\n' + paintResult('voice', 'step skipped', rest, a) + '\n')
+      }
+    } else {
+      process.stdout.write(
+        '\n' + paintResult('voice', 'skipped', ' — set it up later with `npx @agfpd/voice-connect init`', a) + '\n',
+      )
+    }
   } finally {
     process.removeListener('SIGINT', ignore)
     for (const h of prevInt) process.on('SIGINT', h as NodeJS.SignalsListener)

package/src/update/index.ts

@@ -51,6 +51,7 @@ import { defaultDaemonSocketPath } from '../daemon/index.ts'
 // shapes but receives the component-updaters as injected deps.
 import type { UpdateRuntimeResult } from '../runtime/update.ts'
 import type { MemoryUpdateResult } from '../onboard/memory.ts'
+import type { VoiceUpdateResult } from '../onboard/voice.ts'
 
 /** The npm package the foundation publishes / updates from. */
 export const IAPEER_PACKAGE = '@agfpd/iapeer'
@@ -320,10 +321,10 @@ export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
 // ─────────────────────────────────────────────────────────────────────────────
 // cascadeTail — the runtimes + memory legs of the cascade `iapeer update` (FU12).
 // Runs AFTER a healthy foundation update (the CLI owns that, abort-on-hard-fail);
-// here we update every installed runtime then the memory provider, BEST-EFFORT — a
-// component failure is reported, never aborts the rest. Pure orchestration over
-// injected component-updaters (no value-import of runtime/onboard → no cycle), so it
-// is hermetically testable. Returns whether anything failed (→ exit≠0).
+// here we update every installed runtime, then the memory provider, then the voice
+// provider, BEST-EFFORT — a component failure is reported, never aborts the rest. Pure
+// orchestration over injected component-updaters (no value-import of runtime/onboard →
+// no cycle), so it is hermetically testable. Returns whether anything failed (→ exit≠0).
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface CascadeTailDeps {
@@ -331,6 +332,8 @@ export interface CascadeTailDeps {
   runtimes: () => Promise<UpdateRuntimeResult[]>
   /** = updateMemoryProvider (onboard/memory.ts). */
   memory: () => MemoryUpdateResult | Promise<MemoryUpdateResult>
+  /** = updateVoiceProvider (onboard/voice.ts). */
+  voice: () => VoiceUpdateResult | Promise<VoiceUpdateResult>
   out: (s: string) => void
 }
 
@@ -353,5 +356,10 @@ export async function cascadeTail(deps: CascadeTailDeps): Promise<{ failed: bool
   deps.out(`memory: ${m.state}${m.package ? ` (${m.package}${mver})` : ''}${m.detail ? ` — ${m.detail}` : ''}\n`)
   if (m.state === 'failed') failed = true
 
+  const v = await deps.voice()
+  const vver = v.from || v.to ? ` ${v.from ?? '?'} → ${v.to ?? '?'}` : ''
+  deps.out(`voice: ${v.state}${v.package ? ` (${v.package}${vver})` : ''}${v.detail ? ` — ${v.detail}` : ''}\n`)
+  if (v.state === 'failed') failed = true
+
   return { failed }
 }