@agfpd/voicetalk-runtime 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-26
+
+### Changed
+
+- `iapeer voice open` now carries `--mic-released` as the LAST argv token — the
+  hand-off token iapeer ≥0.4.151 requires while a voicetalk runtime is alive (no second
+  listener can be opened next to ours). Sent only after the capture exit is confirmed;
+  harmless on older cores.
+- A cold peer (`status.live === false`) is woken by open itself (up to ~2 min); open
+  then gets a 150 s budget (`VOICETALK_NATIVE_OPEN_COLD_MS`) instead of 20 s.
+
+## [0.4.1] - 2026-10-26
+
+### Added
+
+- `native.ready {target, state}` on start when the `iapeer voice status` preflight
+  answers and the target stays in native mode — a positive receipt, so a healthy start
+  is distinguishable from one that never ran the preflight.
+
 ## [0.4.0] - 2026-10-26
 
 ### Added

package/docs/README.md

@@ -60,7 +60,8 @@ live session, which iapeer opens and closes:
    what an accepted activation does, never what counts as one.
 2. voicetalk kills its capture process and waits until it has actually exited (no
    CoreAudio client left), plays the short "heard you" earcon while nobody is
-   listening, then runs `iapeer voice open <peer> --json`.
+   listening, then runs `iapeer voice open <peer> --json --mic-released` (150 s budget when the
+   peer has no live session — open wakes it first).
 3. While the peer holds the room voicetalk stays silent: no earcons, and any agent
    answer that arrives is spoken only after the hand-off ends.
 4. voicetalk polls `iapeer voice status <peer> --json` (1 s) and takes the microphone

package/docs/ru/README.md

@@ -60,7 +60,8 @@ prompt: такой контекст способен сам породить и
    принятая активация, но не то, что ею считается.
 2. voicetalk гасит процесс захвата и ждёт его фактического выхода (CoreAudio-клиента
    нет), играет короткий earcon «услышал», пока никто не слушает, и вызывает
-   `iapeer voice open <peer> --json`.
+   `iapeer voice open <peer> --json --mic-released` (для пира без живой сессии бюджет
+   150 с — open сначала будит его).
 3. Пока комната у пира, voicetalk молчит: ни earcon'ов, а пришедший ответ агента
    озвучивается только после возврата микрофона.
 4. voicetalk опрашивает `iapeer voice status <peer> --json` (1 с) и забирает микрофон

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/voicetalk-runtime",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Voice runtime-router for IAP peers.",
   "repository": {
     "type": "git",

package/src/nativeVoice.ts

@@ -5,8 +5,8 @@
 // session belongs to iapeer (the pty supervisor), so voicetalk only REQUESTS and OBSERVES
 // over a small CLI contract agreed with the iapeer Implementer (topic codex-voice-wake):
 //
-//   iapeer voice open   <peer> --json → {"ok":true,"state":"open","session":"…","already":bool}
-//   iapeer voice status <peer> --json → {"state":"open|opening|closing|closed","session":…,"reason"?:…}
+//   iapeer voice open   <peer> --json --mic-released → {"ok":true,"state":"open","session":"…","already":bool}
+//   iapeer voice status <peer> --json → {"state":"open|opening|closing|closed","session":…,"reason"?:…,"live"?:bool}
 //   iapeer voice close  <peer> --json → {"ok":true,"state":"closed"}
 //
 // open returns only once the realtime session is confirmed started, close once it is
@@ -24,13 +24,16 @@ export type NativeVoiceReceipt = {
   session?: string | null
   already?: boolean
   reason?: string
+  /** status only: is the peer's session alive? A cold peer is woken by open first. */
+  live?: boolean
   error?: string
   /** Raw stdout/stderr tail for the log when the answer did not parse. */
   raw?: string
 }
 
 export type NativeVoiceControl = {
-  open(peer: string): Promise<NativeVoiceReceipt>
+  /** Called ONLY after our capture process has provably exited. */
+  open(peer: string, opts?: { timeoutMs?: number }): Promise<NativeVoiceReceipt>
   status(peer: string): Promise<NativeVoiceReceipt>
   close(peer: string): Promise<NativeVoiceReceipt>
 }
@@ -52,6 +55,7 @@ export function parseVoiceReceipt(stdout: string, stderr: string, exitCode: numb
         session: typeof obj.session === 'string' ? obj.session : null,
         already: obj.already === true,
         reason: typeof obj.reason === 'string' ? obj.reason : undefined,
+        ...(typeof obj.live === 'boolean' ? { live: obj.live } : {}),
         error: exitCode === 0 && obj.ok !== false ? undefined : (errorText ?? `exit ${exitCode}`),
       }
     } catch {}
@@ -69,7 +73,7 @@ export function cliNativeVoice(opts: {
   statusTimeoutMs?: number
   closeTimeoutMs?: number
 }): NativeVoiceControl {
-  const run = (verb: string, peer: string, timeoutMs: number) =>
+  const run = (verb: string, peer: string, timeoutMs: number, extra: string[] = []) =>
     new Promise<NativeVoiceReceipt>(resolve => {
       let stdout = ''
       let stderr = ''
@@ -82,7 +86,7 @@ export function cliNativeVoice(opts: {
       }
       let child: ReturnType<typeof spawn>
       try {
-        child = spawn(opts.bin, ['voice', verb, peer, '--json'], {
+        child = spawn(opts.bin, ['voice', verb, peer, '--json', ...extra], {
           cwd: opts.cwd,
           env: opts.env ?? process.env,
           stdio: ['ignore', 'pipe', 'pipe'],
@@ -103,7 +107,11 @@ export function cliNativeVoice(opts: {
       child.on('close', code => finish(parseVoiceReceipt(stdout, stderr, code)))
     })
   return {
-    open: peer => run('open', peer, opts.openTimeoutMs ?? 20_000),
+    // `--mic-released` is the hand-off token (iapeer ≥0.4.151): while a voicetalk runtime
+    // is alive, iapeer accepts open ONLY with it, so nobody can open a second listener
+    // next to ours. It goes LAST in argv — an older parser that does not know the flag
+    // would otherwise swallow the next token as its value.
+    open: (peer, o) => run('open', peer, o?.timeoutMs ?? opts.openTimeoutMs ?? 20_000, ['--mic-released']),
     status: peer => run('status', peer, opts.statusTimeoutMs ?? 5_000),
     close: peer => run('close', peer, opts.closeTimeoutMs ?? 15_000),
   }

package/src/voiceSession.ts

@@ -110,6 +110,9 @@ const WAKE_CAPTURE_MAX = Math.min(100, num(process.env.VOICETALK_WAKE_CAPTURE_MA
  *  to iapeer; the ceiling only bounds a hand-off whose closing was never confirmed. */
 const NATIVE_POLL_MS = num(process.env.VOICETALK_NATIVE_POLL_MS, 1_000)
 const NATIVE_MAX_MS = num(process.env.VOICETALK_NATIVE_MAX_MS, 30 * 60_000)
+/** open on a peer with no live session first wakes it (one short turn, up to ~2 min per
+ *  iapeer); killing that open at the warm 20 s budget would only guarantee a failure. */
+const NATIVE_OPEN_COLD_MS = num(process.env.VOICETALK_NATIVE_OPEN_COLD_MS, 150_000)
 
 export type DeliverFn = (target: string, text: string) => Promise<{ ok: boolean; detail?: string }>
 export type LogFn = (evt: string, fields: Record<string, unknown>) => void
@@ -653,9 +656,12 @@ export class VoiceSession {
     await this.earcon('end')
     if (this.stopped) return
     this.native!.phase = 'opening'
-    this.opts.log('native.open-requested', { target })
+    // A cold peer (no live session) is woken by open itself: give it the long budget.
+    const pre = await control.status(target)
+    const cold = pre.live === false
+    this.opts.log('native.open-requested', { target, cold })
     const started = Date.now()
-    const receipt = await control.open(target)
+    const receipt = await control.open(target, cold ? { timeoutMs: NATIVE_OPEN_COLD_MS } : undefined)
     if (!receipt.ok || receipt.state !== 'open') {
       // A failed open is NOT evidence that the peer is off the microphone: the realtime
       // session may still start late, and a timeout or an unreadable answer says nothing
@@ -750,6 +756,10 @@ export class VoiceSession {
         void this.holdUntilClosed(target)
         return true
       }
+      // Positive preflight receipt: the contract answered and the target is live in
+      // native mode. Without this line a healthy start is indistinguishable from one that
+      // never ran the preflight.
+      this.opts.log('native.ready', { target, state: st.state })
     }
     return false
   }