@agfpd/voicetalk-runtime 0.3.1 → 0.4.0

package/src/selfInstall.ts

@@ -19,13 +19,20 @@
 // (the package now owns this path); a sandbox proof sets IAPEER_BIN_DIR so a test never
 // touches the real ~/.local/bin.
 
-import { spawnSync } from 'child_process'
-import { chmodSync, copyFileSync, existsSync, mkdirSync, renameSync, statSync } from 'fs'
+import { chmodSync, copyFileSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
+import { publishInstallPair } from './installPair.ts'
+import { randomUUID } from 'crypto'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { BIN_NAME, PACKAGE_NAME } from './constants.ts'
 import { scaffoldHostDocs, type HostDocsResult } from './hostDocs.ts'
-import { buildManifest, resolveIapeerRoot, writeManifestAtomic } from './manifest.ts'
+import { buildManifest, resolveIapeerRoot } from './manifest.ts'
+import {
+  ensureExecutableSignature,
+  runInstallCommand,
+  type ExecutableSignatureState,
+  type InstallCommandRunner,
+} from './installSignature.ts'
 
 /** The launcher binary name (`voicetalk-runtime`). Re-exported so callers/tests have a
  *  single import surface for the self-install contract. */
@@ -44,6 +51,11 @@ export interface SelfInstallOptions {
    *  (`<pkg>/src/cli.ts` → `<pkg>/docs`). Missing (e.g. running from a compiled bin with
    *  no source tree) → soft-skip, never fails the install. */
   docsSource?: string
+  /** Test seams: no host-global mocks or environment-based signature bypass. */
+  runner?: InstallCommandRunner
+  platform?: NodeJS.Platform
+  /** Synchronous publication fault seam for tests; no environment bypass. */
+  publishRename?: typeof renameSync
 }
 
 export type SelfInstallBinMode = 'compiled' | 'copied-self'
@@ -54,6 +66,7 @@ export interface SelfInstallResult {
   binMode: SelfInstallBinMode
   root: string
   binDir: string
+  signature: ExecutableSignatureState
   /** On-host docs scaffolding verdict (best-effort; never blocks the install). */
   docs: HostDocsResult
 }
@@ -88,20 +101,12 @@ function isBunInterpreter(execPath: string): boolean {
 
 function cleanup(path: string): void {
   try {
-    if (existsSync(path)) renameSync(path, `${path}.dead`)
+    rmSync(path, { force: true })
   } catch {
     // best-effort
   }
 }
 
-/** Tiny deterministic string hash for a unique-ish tmp suffix (Math.random is avoided
- *  to keep the tmp name reproducible within a run). */
-function hashStr(s: string): number {
-  let h = 0
-  for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) | 0
-  return h
-}
-
 /**
  * Self-install: place the launcher on PATH + write the manifest. IDEMPOTENT — a
  * repeat run produces the same on-disk bin and a byte-identical manifest (atomic
@@ -116,42 +121,51 @@ export function selfInstall(opts: SelfInstallOptions = {}): SelfInstallResult {
   const binDir = resolveBinDir(env)
   const binPath = join(binDir, BIN_NAME)
 
+  // Fail closed BEFORE any write/process: a sandbox must isolate BOTH surfaces, so
+  // both must be EXPLICIT overrides. Comparing against a "host home" cannot work —
+  // Bun's os.userInfo().homedir follows $HOME, which a sandbox points at itself.
+  if ((env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1')
+    && (!env.IAPEER_BIN_DIR?.trim() || !env.IAPEER_ROOT?.trim())) {
+    throw new Error('self-install: refusing real host bin/root under IAPEER_TEST_SANDBOX=1 — set IAPEER_BIN_DIR and IAPEER_ROOT')
+  }
   mkdirSync(binDir, { recursive: true, mode: 0o755 })
 
   // Build to a sibling tmp in the SAME dir (rename is atomic only within one FS), then
-  // chmod +x and rename over the target. A reader of `voicetalk-runtime` never sees a
-  // half-written file, and a legacy symlink at binPath is replaced atomically.
-  const tmp = `${binPath}.tmp.${process.pid}.${Math.abs(hashStr(binPath + execPath))}`
+  // chmod +x, verify/repair its macOS signature, THEN rename over the target. A
+  // reader never sees a half-written file; a legacy symlink is replaced atomically.
+  const tmp = `${binPath}.tmp.${process.pid}.${randomUUID()}`
+  const run = opts.runner ?? runInstallCommand
   let binMode: SelfInstallBinMode
+  let signature: ExecutableSignatureState
+  let manifestPath: string
 
-  if (isCompilableSource(sourceEntry) && isBunInterpreter(execPath)) {
-    // PRIMARY path: running under bun from the package source (npx → bin → bun cli.ts).
-    // Compile a self-contained snapshot so the installed bin does not depend on the npm
-    // cache (GC'd) or the source tree.
-    const r = spawnSync(execPath, ['build', '--compile', '--outfile', tmp, sourceEntry], {
-      encoding: 'utf8',
-      env: env as Record<string, string>,
-    })
-    if (r.error || (r.status ?? 1) !== 0) {
-      cleanup(tmp)
-      throw new Error(
-        `self-install: bun build --compile failed: ${(r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim()}`,
-      )
+  try {
+    if (isCompilableSource(sourceEntry) && isBunInterpreter(execPath)) {
+      // PRIMARY: compile a snapshot decoupled from the npm cache/source tree.
+      const r = run(execPath, ['build', '--compile', '--outfile', tmp, sourceEntry], env)
+      if (r.error || (r.status ?? 1) !== 0) {
+        throw new Error(
+          `self-install: bun build --compile failed: ${(r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim()}`,
+        )
+      }
+      binMode = 'compiled'
+    } else {
+      // FALLBACK: running from a compiled bin; re-assert by copying the executable.
+      copyFileSync(execPath, tmp)
+      binMode = 'copied-self'
     }
-    binMode = 'compiled'
-  } else {
-    // FALLBACK: running from an already-compiled bin (no .ts source / execPath is not
-    // bun). Re-assert the install by copying the running executable into binDir.
-    copyFileSync(execPath, tmp)
-    binMode = 'copied-self'
-  }
-
-  chmodSync(tmp, 0o755)
-  renameSync(tmp, binPath)
 
-  // Manifest pins the ABSOLUTE installed bin into the self-config descriptor.
-  const manifest = buildManifest(binPath)
-  const manifestPath = writeManifestAtomic(manifest, env)
+    chmodSync(tmp, 0o755)
+    signature = ensureExecutableSignature(tmp, { env, runner: run, platform: opts.platform })
+    // Pair publication: the manifest (pinning the ABSOLUTE installed bin into the
+    // self-config descriptor) is staged BEFORE the binary is published; a manifest
+    // rename failure restores the previous binary inode (or removes a first install).
+    manifestPath = publishInstallPair(tmp, binPath, buildManifest(binPath), env, opts.publishRename)
+  } finally {
+    // Includes partial compiler/copy output and chmod/sign/rename failures. Do not
+    // leave .dead binaries; a failed signature gate never reaches the manifest.
+    cleanup(tmp)
+  }
 
   // On-host docs — stage this version's public docs to <root>/docs/voicetalk-runtime/.
   // Best-effort: scaffoldHostDocs already soft-skips missing source / copy errors; the
@@ -168,5 +182,5 @@ export function selfInstall(opts: SelfInstallOptions = {}): SelfInstallResult {
     }
   }
 
-  return { binPath, manifestPath, binMode, root: resolveIapeerRoot(env), binDir, docs }
+  return { binPath, manifestPath, binMode, signature, root: resolveIapeerRoot(env), binDir, docs }
 }

package/src/voiceSession.ts

@@ -43,6 +43,7 @@ import {
   type Segment,
 } from './audio.ts'
 import { synthesize, transcribe } from './voiceConnect.ts'
+import { nativeVoiceTargets, type NativeVoiceControl } from './nativeVoice.ts'
 import {
   buildAddressBook,
   hallucinationReason,
@@ -104,6 +105,11 @@ const PLAYBACK_ENABLED = process.env.VOICETALK_PLAYBACK !== '0'
  *  are mode 0600 under the runtime scratch dir and the oldest pair is evicted. */
 const WAKE_CAPTURE_ENABLED = process.env.VOICETALK_WAKE_CAPTURE !== '0'
 const WAKE_CAPTURE_MAX = Math.min(100, num(process.env.VOICETALK_WAKE_CAPTURE_MAX, 16))
+/** Native voice hand-off: how often the listener asks whether the peer's voice is closed,
+ *  and the hard ceiling after which it asks iapeer to close it. Idle-close itself belongs
+ *  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)
 
 export type DeliverFn = (target: string, text: string) => Promise<{ ok: boolean; detail?: string }>
 export type LogFn = (evt: string, fields: Record<string, unknown>) => void
@@ -116,6 +122,21 @@ export type VoiceSessionOptions = {
   /** Scratch dir for captured WAVs and synthesized OGGs. */
   tmpDir: string
   peers?: FleetPeer[]
+  /** The door to a peer's native voice mode; absent = every target goes through STT. */
+  nativeVoice?: NativeVoiceControl
+  /** Override the hand-off poll / hold ceiling (tests); defaults come from the env. */
+  nativePollMs?: number
+  nativeMaxMs?: number
+}
+
+/** The microphone is lent to a peer's native voice. `releasing` and `reclaiming` are the
+ *  edges where nobody listens (earcons are allowed there); during `opening` and `open`
+ *  the room belongs to the peer and voicetalk stays silent. */
+type NativeHandOff = {
+  target: string
+  phase: 'releasing' | 'opening' | 'open' | 'reclaiming'
+  since: number
+  session?: string | null
 }
 
 type WakeRoutingDecision = {
@@ -153,8 +174,18 @@ export class VoiceSession {
   /** When the current turn was handed to the fleet — the clock for «ответ за N с». */
   private deliveredAt = new Map<string, number>()
   private stopped = false
+  private nativeTargets: Set<string>
+  private native: NativeHandOff | null = null
+  private nativeWaiters: Array<() => void> = []
+
+  constructor(private readonly opts: VoiceSessionOptions) {
+    this.nativeTargets = opts.nativeVoice ? nativeVoiceTargets(opts.binding) : new Set()
+  }
 
-  constructor(private readonly opts: VoiceSessionOptions) {}
+  /** Who currently holds the microphone instead of the wake listener (null = we do). */
+  get nativeHolder(): { target: string; phase: string } | null {
+    return this.native ? { target: this.native.target, phase: this.native.phase } : null
+  }
 
   /** Resolve the input device, prime the address book, open the mic. Throws if the mic
    *  cannot be resolved — the caller decides whether that is fatal (it is not: the
@@ -173,7 +204,10 @@ export class VoiceSession {
       onStart: attempt => this.opts.log('mic.start', { device: device.index, name: device.name, attempt }),
       onError: detail => this.opts.log('mic.error', { detail }),
     })
-    this.mic.start()
+    // A restart must not grab a microphone a peer is still talking on: adopt an open
+    // native voice and wait for its close before listening.
+    const adopted = await this.adoptOpenNativeVoice()
+    if (!adopted) this.mic.start()
     return { deviceIndex: device.index, deviceName: device.name, addresses: this.book.length }
   }
 
@@ -216,6 +250,9 @@ export class VoiceSession {
 
   private async earcon(kind: keyof Earcons): Promise<void> {
     if (!this.earcons || process.env.VOICETALK_EARCONS === '0' || !PLAYBACK_ENABLED) return
+    // The peer's own voice session is listening to the room — a beep from us would be
+    // heard (and possibly answered) by it.
+    if (this.native && (this.native.phase === 'opening' || this.native.phase === 'open')) return
     try {
       this.muteUntil = Math.max(this.muteUntil, Date.now() + 600)
       await playFile(this.earcons[kind], { timeoutMs: 5_000 })
@@ -229,7 +266,7 @@ export class VoiceSession {
   }
 
   private onAudio(chunk: Buffer): void {
-    if (this.stopped) return
+    if (this.stopped || this.native) return
     if (this.muted()) {
       // Our own speech (or an earcon) is in the room — throw the audio away rather than
       // letting the endpointer build an utterance out of it.
@@ -439,10 +476,18 @@ export class VoiceSession {
       // goes out before the new one starts.
       this.opts.log('wake.switch', { from: active, to: match!.target })
       this.flush('switch')
-      this.append(match!.target, match!.body)
+      if (this.nativeTargets.has(match!.target)) this.handOff(match!)
+      else this.append(match!.target, match!.body)
       return { candidate: match!, accepted: true }
     }
 
+    if (match && this.nativeTargets.has(match.target)) {
+      // An accepted, spoken, exact address to a native-voice peer: the conversation moves
+      // to the peer's own realtime voice. Nothing is transcribed onward or sent as text.
+      this.handOff(match)
+      return { candidate: match, accepted: true }
+    }
+
     if (match) {
       if (!match.body) {
         // Addressed with nothing to say yet («Борис?») — acknowledge and hold the mic
@@ -569,6 +614,151 @@ export class VoiceSession {
     this.followTimer = null
   }
 
+  // ── native voice hand-off ─────────────────────────────────────────────────────
+
+  /** One accepted wake → one hand-off. Synchronously marks the microphone as lent (so no
+   *  second wake can be formed from audio already captured), then runs the hand-off. */
+  private handOff(match: WakeMatch): void {
+    if (this.native) {
+      this.opts.log('native.ignored', { target: match.target, holder: this.native.target, phase: this.native.phase })
+      return
+    }
+    this.native = { target: match.target, phase: 'releasing', since: Date.now() }
+    // Audio captured before the wake was handled belongs to no one now: the owner is
+    // about to talk to the peer directly. A thought in flight to someone ELSE still goes.
+    const dropped = this.queue.length
+    this.queue = []
+    if (this.pending) this.flush('native-voice')
+    this.clearWindow()
+    this.followTarget = null
+    this.opts.log('native.wake', { target: match.target, alias: match.alias, body: match.body || null, droppedSegments: dropped })
+    void this.runHandOff(match.target)
+  }
+
+  private async runHandOff(target: string): Promise<void> {
+    const control = this.opts.nativeVoice!
+    const released = this.mic ? await this.mic.pause() : { released: true }
+    this.segmenter.reset()
+    this.opts.log('mic.released', { to: target, confirmed: released.released })
+    if (!released.released) {
+      // Our capture has not provably let go of the device; opening the peer's voice now
+      // could put two listeners on one microphone. Abort this activation instead.
+      this.native!.phase = 'reclaiming'
+      await this.earcon('error')
+      this.reclaim(target, 'release-unconfirmed')
+      return
+    }
+    // "Heard you" — played while NOBODY is listening: our capture is gone and the peer's
+    // voice is not open yet.
+    await this.earcon('end')
+    if (this.stopped) return
+    this.native!.phase = 'opening'
+    this.opts.log('native.open-requested', { target })
+    const started = Date.now()
+    const receipt = await control.open(target)
+    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
+      // at all. The microphone comes back only on a confirmed `closed` (contract with
+      // iapeer, 26.10) — until then we hold exactly as if the voice were open.
+      this.opts.log('native.open-failed', { target, state: receipt.state, error: receipt.error, openMs: Date.now() - started })
+      this.native!.phase = 'open'
+      await this.holdUntilClosed(target, { failedOpen: true })
+      return
+    }
+    this.native!.phase = 'open'
+    this.native!.session = receipt.session ?? null
+    this.opts.log('native.opened', { target, session: receipt.session ?? null, already: !!receipt.already, openMs: Date.now() - started })
+    await this.holdUntilClosed(target)
+  }
+
+  /** Poll the peer's voice state until iapeer confirms it is closed, then give the
+   *  microphone back to the wake listener. */
+  private async holdUntilClosed(target: string, opts: { failedOpen?: boolean } = {}): Promise<void> {
+    const control = this.opts.nativeVoice!
+    const openedAt = Date.now()
+    let closeRequested = false
+    let lastAlarm = Date.now()
+    let lastState = ''
+    while (!this.stopped) {
+      await new Promise(r => setTimeout(r, this.opts.nativePollMs ?? NATIVE_POLL_MS))
+      if (this.stopped) return
+      const st = await control.status(target)
+      if (st.state !== lastState) {
+        this.opts.log('native.status', { target, state: st.state, reason: st.reason ?? null, error: st.error ?? null })
+        lastState = st.state
+      }
+      if (st.state === 'closed') {
+        this.opts.log('native.closed', { target, session: st.session ?? this.native?.session ?? null, reason: st.reason ?? null, heldMs: Date.now() - openedAt })
+        break
+      }
+      if (!closeRequested && Date.now() - openedAt >= (this.opts.nativeMaxMs ?? NATIVE_MAX_MS)) {
+        closeRequested = true
+        this.opts.log('native.close-requested', { target, reason: 'hold ceiling', heldMs: Date.now() - openedAt })
+        const closed = await control.close(target)
+        this.opts.log('native.close-receipt', { target, ok: closed.ok, state: closed.state, error: closed.error ?? null })
+      }
+      if (closeRequested && Date.now() - lastAlarm >= 60_000) {
+        // Past the ceiling and still no confirmed close. Taking the microphone back
+        // unconfirmed would put two listeners on one device; staying deaf is the
+        // recoverable failure, so it is reported loudly instead of resolved by guess.
+        lastAlarm = Date.now()
+        this.opts.log('native.stuck', { target, lastState, heldMs: Date.now() - openedAt })
+        const closed = await control.close(target)
+        this.opts.log('native.close-receipt', { target, ok: closed.ok, state: closed.state, error: closed.error ?? null })
+      }
+    }
+    if (this.stopped) return
+    this.native!.phase = 'reclaiming'
+    if (opts.failedOpen) await this.earcon('error')
+    this.reclaim(target, opts.failedOpen ? 'open-failed' : 'closed')
+    if (!opts.failedOpen) void this.earcon('close')
+  }
+
+  private reclaim(target: string, reason: string): void {
+    this.segmenter.reset()
+    this.native = null
+    // Back to wake mode proper: after a native conversation the next turn needs a name.
+    this.clearWindow()
+    this.followTarget = null
+    this.mic?.resume()
+    this.opts.log('wake.listening', { after: target, reason })
+    const waiters = this.nativeWaiters
+    this.nativeWaiters = []
+    for (const w of waiters) w()
+  }
+
+  /** On start: if a native voice is already open (the runtime restarted mid-conversation),
+   *  stay off the microphone until it closes. */
+  private async adoptOpenNativeVoice(): Promise<boolean> {
+    const control = this.opts.nativeVoice
+    if (!control) return false
+    for (const target of [...this.nativeTargets]) {
+      const st = await control.status(target)
+      if (st.state === 'unknown') {
+        // Preflight: the contract does not answer at all (an iapeer without `voice`, a
+        // broken CLI). Nothing can have been opened by THIS process yet, so the safe
+        // degradation is the STT path for this target — not a listener that goes deaf
+        // forever on the first wake because no `closed` can ever be confirmed.
+        this.nativeTargets.delete(target)
+        this.opts.log('native.unavailable', { target, error: st.error ?? null, fallback: 'stt' })
+        continue
+      }
+      if (st.state === 'open' || st.state === 'opening' || st.state === 'closing') {
+        this.native = { target, phase: 'open', since: Date.now(), session: st.session ?? null }
+        this.opts.log('native.adopted', { target, state: st.state, session: st.session ?? null })
+        void this.holdUntilClosed(target)
+        return true
+      }
+    }
+    return false
+  }
+
+  private waitNativeIdle(): Promise<void> {
+    if (!this.native) return Promise.resolve()
+    return new Promise(resolve => this.nativeWaiters.push(resolve))
+  }
+
   /** Speak an agent's answer on the owner's speaker, then hold the follow-up window
    *  open — the conversational turn passes back to the human. */
   async speak(from: string, message: string): Promise<void> {
@@ -596,6 +786,11 @@ export class VoiceSession {
   }
 
   private async say(text: string, opts: { from?: string } = {}): Promise<void> {
+    if (this.native) {
+      // The room belongs to a peer's native voice; speaking now would be heard by it.
+      this.opts.log('tts.deferred', { from: opts.from ?? null, holder: this.native.target })
+      await this.waitNativeIdle()
+    }
     const out = join(this.opts.tmpDir, `say-${randomUUID()}.ogg`)
     const started = Date.now()
     try {

package/src/wake.ts

@@ -120,6 +120,10 @@ export type VoicetalkBinding = {
   wake_words?: Record<string, string> | string[]
   default_target?: string
   device?: string
+  /** Targets answered in their own NATIVE voice mode (Codex `/voice`) instead of
+   *  STT → envelope → TTS. The wake word still has to be spoken and pass every activation
+   *  check — this only changes what an accepted activation does. */
+  native_voice?: string[]
 }
 
 export type AddressBookOptions = {

package/tsconfig.json

@@ -11,5 +11,5 @@
     "allowImportingTsExtensions": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts"]
 }