@pellux/goodvibes-tui 1.26.0 → 1.27.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "1.26.0",
+  "version": "1.27.1",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -107,13 +107,14 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "1.19.2",
-    "@pellux/goodvibes-terminal-shell": "1.19.2",
+    "@pellux/goodvibes-sdk": "1.21.0",
+    "@pellux/goodvibes-terminal-shell": "1.21.0",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",
     "jszip": "^3.10.1",
     "node-edge-tts": "^1.2.10",
+    "onnxruntime-web": "^1.27.0",
     "openai": "^6.29.0",
     "pyright": "^1.1.408",
     "simple-git": "^3.33.0",
@@ -134,10 +135,10 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@pellux/goodvibes-tui-linux-x64": "1.26.0",
-    "@pellux/goodvibes-tui-linux-arm64": "1.26.0",
-    "@pellux/goodvibes-tui-darwin-x64": "1.26.0",
-    "@pellux/goodvibes-tui-darwin-arm64": "1.26.0"
+    "@pellux/goodvibes-tui-linux-x64": "1.27.1",
+    "@pellux/goodvibes-tui-linux-arm64": "1.27.1",
+    "@pellux/goodvibes-tui-darwin-x64": "1.27.1",
+    "@pellux/goodvibes-tui-darwin-arm64": "1.27.1"
   },
   "trustedDependencies": [],
   "overrides": {

package/scripts/postinstall.js

@@ -230,9 +230,65 @@ function deployBundledFiles() {
   }
 }
 
+/**
+ * Put the wake-word model on the machine as part of installing.
+ *
+ * Everything needed to detect "hey goodvibes" already shipped, and provisioning
+ * was reachable only by typing `/voice wake setup` — so the ordinary outcome of
+ * installing was a wake word that could not start. The pins (URLs, byte counts,
+ * checksums) live in the SDK's wake-word manifest and stay there; this calls the
+ * SDK's install policy, which:
+ *
+ *   - never throws (an absent network, DNS, a proxy serving HTML, an unwritable
+ *     home directory and a provisioner that itself threw all come back as an
+ *     outcome), so a failed download CANNOT fail this install;
+ *   - reaps a torn artifact before retrying, so a killed attempt converges;
+ *   - reports one plain line, printed below either way.
+ *
+ * A failure degrades to exactly the previous behaviour: the feature reports
+ * not-provisioned by content, `/voice wake setup` fetches it, and a running
+ * daemon retries at every boot.
+ *
+ * It honours the same skip switches as the binary install (`--no-download`,
+ * GOODVIBES_SKIP_BINARY_DOWNLOAD) plus its own
+ * GOODVIBES_SKIP_WAKE_MODEL_DOWNLOAD, and it stays out of a source checkout for
+ * the same reason the binary install does — a repo clone is a development tree,
+ * not an installation.
+ */
+async function installWakeWordModel() {
+  if (noDownload) {
+    console.log('postinstall: skipping the wake-word model (--no-download)');
+    return;
+  }
+  if (isSourceCheckout()) {
+    console.log('postinstall: source checkout detected; skipping the wake-word model install');
+    return;
+  }
+  try {
+    const { provisionWakeWordModelsAtInstall, resolveManagedVoiceRoot } =
+      await import('@pellux/goodvibes-sdk/platform/voice');
+    const outcome = await provisionWakeWordModelsAtInstall({
+      managedRoot: resolveManagedVoiceRoot(home),
+      recoveryHint: '/voice wake setup',
+    });
+    console.log(`postinstall: ${outcome.message}`);
+  } catch (error) {
+    // The policy is contracted not to throw, so reaching here means the import
+    // itself failed (a partially installed dependency tree, most likely). Even
+    // that is not a reason to fail the install of everything else.
+    console.log(
+      'postinstall: the wake-word model could not be installed '
+      + `(${error instanceof Error ? error.message : String(error)}); everything else installed normally. `
+      + 'Run /voice wake setup to fetch it, or leave it and the next daemon start tries again.',
+    );
+  }
+}
+
 async function main() {
   await installPlatformBinaries();
   deployBundledFiles();
+  // Last, and never fatal: a wake-word model is not worth failing an install over.
+  await installWakeWordModel();
 }
 
 // Guarded so this module can be imported by tests (to exercise
@@ -242,4 +298,4 @@ if (import.meta.main) {
   await main();
 }
 
-export { verifyChecksum, parseChecksumFile, sha256, resolveArtifactNames, CHECKSUM_MANIFEST_NAME };
+export { verifyChecksum, parseChecksumFile, sha256, resolveArtifactNames, CHECKSUM_MANIFEST_NAME, installWakeWordModel };

package/src/audio/activation-sound.ts

@@ -0,0 +1,117 @@
+/**
+ * activation-sound.ts — the sound a confirmed wake makes.
+ *
+ * A wake takes the microphone from "scoring frames nobody hears" to "recording
+ * what you say next", and the user needs to know the moment that happened —
+ * otherwise the only feedback is a transcript arriving seconds later, and a
+ * false accept is indistinguishable from nothing having happened at all. So the
+ * sound is played AT the wake, before transcription, per
+ * `voice.wake.activationSound`:
+ *
+ *  - `chime`  — a short two-tone WAV synthesised here. No asset file to ship,
+ *               install, provision or lose, and nothing to fetch at runtime.
+ *  - `custom` — the file named by `voice.wake.activationSoundPath`.
+ *  - `none`   — silent.
+ *
+ * Playback reuses the streaming player the spoken-turn path already owns
+ * (player.ts), so a host with mpv or ffplay needs nothing extra and a host with
+ * neither degrades to silence with a reported reason rather than an exception in
+ * the middle of a capture.
+ */
+
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+import { encodeWavPcm16 } from '@pellux/goodvibes-sdk/platform/voice';
+import type { WakeActivationSound } from '@pellux/goodvibes-sdk/platform/voice';
+import type { VoiceAudioChunk } from '@pellux/goodvibes-sdk/platform/voice';
+import type { StreamingAudioPlayer } from './player.ts';
+
+/** Sample rate of the synthesised chime. 16 kHz is plenty for two short tones. */
+const CHIME_SAMPLE_RATE = 16000;
+/** The two tones, in Hz: a rising pair reads as "listening", not as an error. */
+const CHIME_TONES_HZ = [880, 1320] as const;
+/** Milliseconds per tone. Short enough not to overlap the start of an utterance. */
+const CHIME_TONE_MS = 70;
+/** Peak amplitude on the int16 magnitude scale — audible without being startling. */
+const CHIME_PEAK = 6000;
+/**
+ * Fade applied to each end of each tone, in samples. Without it the abrupt start
+ * and stop of a sine burst is a click, which on small laptop speakers is louder
+ * than the tone itself.
+ */
+const CHIME_FADE_SAMPLES = 96;
+
+/**
+ * Synthesise the built-in chime as a complete WAV file.
+ *
+ * Written as samples rather than shipped as an asset for the same reason the
+ * wake front end is computed in code: a binary blob is one more thing that can
+ * be missing, and this one is 40 milliseconds of two sine waves.
+ */
+export function buildActivationChimeWav(): Uint8Array {
+  const perTone = Math.round((CHIME_TONE_MS / 1000) * CHIME_SAMPLE_RATE);
+  const samples = new Float32Array(perTone * CHIME_TONES_HZ.length);
+  let offset = 0;
+  for (const frequency of CHIME_TONES_HZ) {
+    for (let i = 0; i < perTone; i++) {
+      const fadeIn = Math.min(1, i / CHIME_FADE_SAMPLES);
+      const fadeOut = Math.min(1, (perTone - 1 - i) / CHIME_FADE_SAMPLES);
+      const envelope = Math.min(fadeIn, fadeOut);
+      samples[offset + i] = Math.sin((2 * Math.PI * frequency * i) / CHIME_SAMPLE_RATE) * CHIME_PEAK * envelope;
+    }
+    offset += perTone;
+  }
+  return encodeWavPcm16(samples, CHIME_SAMPLE_RATE);
+}
+
+/** One-chunk stream, matching what the streaming player consumes. */
+async function* singleChunk(data: Uint8Array, format: string): AsyncIterable<VoiceAudioChunk> {
+  yield { data, sequence: 1, format };
+}
+
+export interface ActivationSoundPlayerDeps {
+  readonly player: StreamingAudioPlayer;
+  /** Where a sound that could not be played is reported, in the user's words. */
+  readonly notify: (message: string) => void;
+  /** Injected in tests; defaults to reading the custom file off disk. */
+  readonly readFile?: (path: string) => Uint8Array;
+}
+
+/**
+ * Play the resolved activation sound. Never throws and never blocks the caller
+ * on the audio finishing: a wake's next step is recording the utterance, and a
+ * sound that fails to play must not delay or cancel that.
+ *
+ * `settings.activationSound` arrives already resolved against surface capability
+ * — the SDK downgrades `custom` to `chime` on a surface that cannot read a local
+ * file, and this surface can, so `custom` here means a real path.
+ */
+export function playActivationSound(sound: WakeActivationSound, deps: ActivationSoundPlayerDeps): void {
+  if (sound.kind === 'none') return;
+  if (!deps.player.available) {
+    deps.notify(`[Voice] Wake heard, but no audio player is installed to play the ${sound.kind} activation sound (${deps.player.label}).`);
+    return;
+  }
+  let data: Uint8Array;
+  let format: string;
+  if (sound.kind === 'custom') {
+    const path = sound.path.trim();
+    if (path.length === 0) {
+      deps.notify('[Voice] voice.wake.activationSound is "custom" but voice.wake.activationSoundPath is empty, so no sound was played.');
+      return;
+    }
+    try {
+      data = (deps.readFile ?? ((target: string) => new Uint8Array(readFileSync(target))))(path);
+    } catch (error) {
+      deps.notify(`[Voice] Could not read the activation sound at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    format = extname(path).replace('.', '').toLowerCase() || 'wav';
+  } else {
+    data = buildActivationChimeWav();
+    format = 'wav';
+  }
+  void deps.player.play(singleChunk(data, format), { format }).catch((error: unknown) => {
+    deps.notify(`[Voice] The activation sound could not be played: ${error instanceof Error ? error.message : String(error)}`);
+  });
+}

package/src/audio/capture.ts

@@ -0,0 +1,112 @@
+/**
+ * capture.ts — the ONE place this terminal opens a microphone.
+ *
+ * Two consumers sit on it and they share this single device path: push-to-talk
+ * voice input (src/audio/voice-input-session.ts) and wake-word detection
+ * (src/audio/wake-runtime.ts). A wake does not END a capture session, it starts
+ * one — the SDK listener keeps the same stream open and switches it to recording
+ * the utterance that follows — so a second opener would drop the beginning of a
+ * sentence and race the operating system for a device that is already held.
+ *
+ * The framing arithmetic, the recorder argv and the utterance policy all live in
+ * the SDK (`@pellux/goodvibes-sdk/platform/voice/capture`), because getting any
+ * of them subtly wrong is SILENT: a container header out of byte alignment, or a
+ * short frame, still "works" and simply never detects. What is local is the one
+ * thing that cannot be shared — actually starting a process. That mirrors
+ * playback exactly (see player.ts): resolve a command off PATH, spawn it, and
+ * treat "no tool installed" as a reported state rather than an exception.
+ */
+
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import {
+  createRecorderCaptureOpener,
+  type AudioCaptureOpener,
+  type AudioCaptureWarn,
+  type CaptureChildProcess,
+  type CaptureSpawn,
+} from '@pellux/goodvibes-sdk/platform/voice/capture';
+
+/**
+ * Whether a command is runnable from PATH. Same scan `player.ts` uses for
+ * mpv/ffplay (`resolveStreamingAudioPlayerCommand` -> `findExecutable`): every
+ * PATH entry, X_OK access, Windows extensions included — kept identical so a
+ * host where playback finds its tool and capture does not is a real difference
+ * in what is installed, never a difference in how the two looked.
+ */
+export function isExecutableOnPath(
+  name: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: string = process.platform,
+): boolean {
+  const pathValue = env.PATH ?? '';
+  const extensions = platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : [''];
+  for (const dir of pathValue.split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of extensions) {
+      try {
+        accessSync(join(dir, `${name}${ext}`), constants.X_OK);
+        return true;
+      } catch {
+        // Keep scanning PATH.
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Spawn a recorder with its stdout piped and stdin closed.
+ *
+ * `stdio: ['ignore', 'pipe', 'pipe']` is deliberate on all three: a recorder
+ * with an inherited stdin would compete with the TUI for the terminal's raw-mode
+ * keystrokes, stdout carries the raw PCM, and stderr is the ONLY place the
+ * reason a device did not open is written, so it is kept for the error message
+ * rather than discarded.
+ */
+export const spawnRecorderProcess: CaptureSpawn = (command, args): CaptureChildProcess => {
+  const child = spawn(command, [...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+  // Adapted rather than returned directly: the SDK's port declares the signal as
+  // a plain `string` (it is shared with a browser bundle that has no
+  // NodeJS.Signals) and node's narrower union is not assignable to it. The two
+  // event listeners are branched explicitly for the same reason — node's `on` is
+  // overloaded per event name and takes no union.
+  return {
+    stdout: child.stdout,
+    stderr: child.stderr,
+    on(event: 'error' | 'close', listener: (...args: never[]) => void): unknown {
+      if (event === 'error') return child.on('error', listener as (error: Error) => void);
+      return child.on('close', listener as (code: number | null, signal: NodeJS.Signals | null) => void);
+    },
+    kill: (signal?: string) => child.kill(signal as NodeJS.Signals | undefined),
+  };
+};
+
+export interface TuiCaptureOpenerOptions {
+  /** Injected in tests so no real recorder is ever started. */
+  readonly spawn?: CaptureSpawn;
+  /** Injected in tests; defaults to the PATH + X_OK scan above. */
+  readonly isInstalled?: (command: string) => boolean;
+  readonly platform?: string;
+  readonly warn?: AudioCaptureWarn;
+}
+
+/**
+ * Build the terminal's capture opener. Called once during startup wiring; both
+ * voice consumers receive the SAME opener.
+ */
+export function createTuiCaptureOpener(options: TuiCaptureOpenerOptions = {}): AudioCaptureOpener {
+  return createRecorderCaptureOpener({
+    spawn: options.spawn ?? spawnRecorderProcess,
+    isInstalled: options.isInstalled ?? ((command: string) => isExecutableOnPath(command)),
+    platform: options.platform ?? process.platform,
+    // FALSE here, and correct: a recorder subprocess captures raw PCM and filters
+    // nothing. The suppression stage is applied by the SDK's own wrapper inside
+    // WakeListener and PushToTalkSession, which ask this opener for raw frames —
+    // so `speex` arriving at the RECORDER directly, unwrapped by either, is still
+    // refused rather than passed through unfiltered.
+    speexAvailable: false,
+    ...(options.warn !== undefined ? { warn: options.warn } : {}),
+  });
+}

package/src/audio/onnxruntime-assets.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The two onnxruntime-web assets the wake engine needs on disk.
+ *
+ * Both are imported with `with { type: 'file' }`, which resolves to a PATH
+ * string rather than module contents — a real filesystem path when the shell
+ * runs from source, and a `/$bunfs/root/...` path inside a compiled binary,
+ * where the bytes are embedded. Declared here because these are asset
+ * specifiers, not typed modules: onnxruntime-web publishes them for exactly
+ * this purpose (its `exports` map lists both by name) but ships no types for
+ * them, and without the `file` attribute the `.mjs` would be pulled in as
+ * untyped JavaScript.
+ *
+ * They are extracted and pointed at by wake-inference.ts, which is the only
+ * importer.
+ */
+declare module 'onnxruntime-web/ort-wasm-simd-threaded.mjs' {
+  const assetPath: string;
+  export default assetPath;
+}
+
+declare module 'onnxruntime-web/ort-wasm-simd-threaded.wasm' {
+  const assetPath: string;
+  export default assetPath;
+}

package/src/audio/voice-capture-wiring.ts

@@ -0,0 +1,119 @@
+/**
+ * voice-capture-wiring.ts — composes the terminal's two voice consumers over ONE
+ * capture path.
+ *
+ * Push-to-talk and wake detection are not two audio stacks. They share the
+ * opener built here (capture.ts), the transcription gateway (core/voice-stt-gateway.ts)
+ * and the same `voice.wake.*` capture rows — device, recorder, noise
+ * suppression, ceiling — so a device that works for one works for the other and
+ * a change in /settings applies to both.
+ *
+ * This is the composition root the shell calls once. It owns nothing the shell
+ * does not hand it: the composer draft, the turn submission, the message router
+ * and the render request all arrive as callbacks, which is what keeps this file
+ * out of the shell-UI layers the architecture check bars src/audio from importing.
+ */
+
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { ConfigKey, ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { VoiceCaptureIndicatorState } from '../core/voice-capture-status.ts';
+import { createTuiCaptureOpener } from './capture.ts';
+import { playActivationSound } from './activation-sound.ts';
+import { LocalStreamingAudioPlayer } from './player.ts';
+import type { StreamingAudioPlayer } from './player.ts';
+import { createVoiceSttGateway } from '../core/voice-stt-gateway.ts';
+import { wireVoiceInputRuntime } from './voice-input-session.ts';
+import { startWakeRuntime, wireWakeRuntime } from './wake-runtime.ts';
+import { terminalWakeCapabilities } from '../core/wake-provision-status.ts';
+import { resolveWakeRuntimeSettings } from '@pellux/goodvibes-sdk/platform/voice/wake/runtime';
+import { wakeProvisionStatus } from '@pellux/goodvibes-sdk/platform/voice';
+
+export interface VoiceCaptureWiringDeps {
+  readonly configManager: ConfigManager;
+  /** `<root>/voice` — the managed root the wake tree hangs off (same root /voice setup uses). */
+  readonly managedVoiceRoot: string;
+  /** A directory this surface owns for the extracted onnxruntime assets. */
+  readonly assetDirectory: string;
+  readonly homeDirectory: string | (() => string);
+  /** Names retained clips so the SDK's sweeper can reap them when the session ends. */
+  readonly sessionId: string;
+  /** Writes recognised text into the composer draft. */
+  readonly writeDraft: (text: string) => void;
+  /** Submits recognised text as a turn (`voice.wake.autoSubmit` on). */
+  readonly submitTurn: (text: string) => void;
+  readonly notify: (message: string) => void;
+  readonly render: () => void;
+  /** Injected in tests; defaults to a real streaming player for the activation sound. */
+  readonly player?: StreamingAudioPlayer;
+}
+
+export interface VoiceCaptureWiring {
+  /** The Alt+V action: start recording, or stop and transcribe. */
+  readonly toggleVoiceInput: () => void;
+  /**
+   * The live footer row. A push-to-talk recording OUTRANKS the wake row: the user
+   * pressed a key and is waiting on that one, while the detector's row describes a
+   * standing condition they already know about.
+   */
+  readonly status: () => VoiceCaptureIndicatorState | null;
+  /** Teardown, for the shell's `unsubs` registry — releases any open device. */
+  readonly unsubs: readonly (() => void)[];
+}
+
+/** Compose voice input and wake detection. Opens no device by itself. */
+export function wireVoiceCapture(deps: VoiceCaptureWiringDeps): VoiceCaptureWiring {
+  const readConfig = (key: string): unknown => deps.configManager.get(key as ConfigKey);
+  const warn = (message: string, meta?: Readonly<Record<string, unknown>>): void => {
+    logger.debug(`voice capture: ${message}`, meta ?? {});
+  };
+  // ONE opener, both consumers. The suppression stage is inside it, so `speex`
+  // is applied rather than refused (see capture.ts).
+  const openCapture = createTuiCaptureOpener({ warn });
+  const resolveTranscriber = () => {
+    const resolution = createVoiceSttGateway({ configManager: deps.configManager, homeDirectory: deps.homeDirectory });
+    return resolution.available
+      ? { available: true as const, gateway: resolution.gateway }
+      : { available: false as const, reason: resolution.reason };
+  };
+  // Capabilities are re-read per resolve rather than captured once: provisioning
+  // the speech gate is something a user does WHILE the session is running, and a
+  // capability snapshot taken at startup would keep reporting it unavailable.
+  const readSettings = () => resolveWakeRuntimeSettings(
+    readConfig,
+    'tui',
+    terminalWakeCapabilities(wakeProvisionStatus({ managedRoot: deps.managedVoiceRoot })),
+  );
+  const subscribeConfig = (key: string, listener: () => void): (() => void) => deps.configManager.subscribe(key as ConfigKey, listener);
+  const player = deps.player ?? new LocalStreamingAudioPlayer();
+
+  const voiceInput = wireVoiceInputRuntime({
+    openCapture,
+    readSettings,
+    resolveTranscriber,
+    writeDraft: deps.writeDraft,
+    notify: deps.notify,
+    render: deps.render,
+  });
+
+  const wake = wireWakeRuntime({
+    readConfig,
+    subscribeConfig,
+    openCapture,
+    managedRoot: deps.managedVoiceRoot,
+    assetDirectory: deps.assetDirectory,
+    resolveTranscriber,
+    playActivationSound: (sound) => playActivationSound(sound, { player, notify: deps.notify }),
+    submitTurn: deps.submitTurn,
+    writeDraft: deps.writeDraft,
+    notify: deps.notify,
+    render: deps.render,
+    sessionId: deps.sessionId,
+    warn,
+  });
+
+  return {
+    toggleVoiceInput: voiceInput.toggle,
+    status: () => voiceInput.status() ?? wake.status(),
+    unsubs: [...startWakeRuntime(wake, { subscribeConfig }), () => { void voiceInput.release(); }],
+  };
+}

package/src/audio/voice-input-session.ts

@@ -0,0 +1,181 @@
+/**
+ * voice-input-session.ts — push-to-talk voice input for the terminal.
+ *
+ * PRESS TO START, PRESS AGAIN TO STOP — not press-and-hold. A terminal receives
+ * discrete key EVENTS, not held-key state: there is no key-release event to
+ * observe, so a genuine hold would have to be faked with a timer that guesses
+ * when the user let go. The binding's description says "press to start, press
+ * again to stop" for that reason, and the SDK's `captureMaxSeconds` ceiling still
+ * applies as the backstop for a second press that never arrives (a lost focus, a
+ * closed terminal) so the microphone cannot be left open indefinitely.
+ *
+ * The transcript is written into the COMPOSER DRAFT and never submitted. Speech
+ * recognition is wrong often enough that submitting it unseen would send the
+ * wrong prompt, and the composer is where the user already fixes things. The
+ * wake path is where auto-submit is a choice (`voice.wake.autoSubmit`), because
+ * there the user spoke a whole command on purpose.
+ */
+
+import {
+  PushToTalkSession,
+  utteranceToAudioArtifact,
+  AudioCaptureError,
+  type AudioCaptureOpener,
+  type CapturedUtterance,
+  type PushToTalkPhase,
+  type WakeRuntimeSettings,
+} from '@pellux/goodvibes-sdk/platform/voice';
+import type { VoiceCaptureIndicatorState } from '../core/voice-capture-status.ts';
+import type { VoiceSttGateway } from '../core/voice-stt-gateway.ts';
+import { describeTranscriptionFailure } from '../core/voice-stt-gateway.ts';
+
+export interface VoiceInputRuntimeDeps {
+  readonly openCapture: AudioCaptureOpener;
+  /**
+   * Resolved `voice.wake.*` capture rows, read at each press so a device or
+   * recorder change in /settings applies without a restart.
+   */
+  readonly readSettings: () => Pick<WakeRuntimeSettings, 'capture' | 'captureMaxSeconds' | 'indicator'>;
+  /** Resolved per press, so a daemon that comes up mid-session starts working. */
+  readonly resolveTranscriber: () => { readonly available: true; readonly gateway: VoiceSttGateway } | { readonly available: false; readonly reason: string };
+  /** Writes the recognised text into the composer draft. */
+  readonly writeDraft: (text: string) => void;
+  readonly notify: (message: string) => void;
+  readonly render: () => void;
+}
+
+export interface VoiceInputRuntime {
+  /** The keybinding action: start capturing, or stop and transcribe. */
+  toggle(): void;
+  /** Current indicator row, or null when no microphone is open. */
+  status(): VoiceCaptureIndicatorState | null;
+  /** Release the device without transcribing. Used by the exit path. */
+  release(): Promise<void>;
+}
+
+/** Indicator kinds for the phases worth showing; `idle`/`error` render nothing. */
+const PHASE_INDICATOR: Partial<Record<PushToTalkPhase, VoiceCaptureIndicatorState['kind']>> = {
+  requesting: 'requesting',
+  recording: 'recording',
+  stopping: 'transcribing',
+};
+
+/**
+ * Wire push-to-talk. One session object is reused across presses (the SDK session
+ * is restartable after both a stop and a failure), so a device is opened per
+ * press and released on every path out of it — including the failing ones.
+ */
+export function wireVoiceInputRuntime(deps: VoiceInputRuntimeDeps): VoiceInputRuntime {
+  let session: PushToTalkSession | null = null;
+  let phase: PushToTalkPhase = 'idle';
+  let transcribing = false;
+
+  const status = (): VoiceCaptureIndicatorState | null => {
+    const indicator = deps.readSettings().indicator;
+    if (transcribing) {
+      return { kind: 'transcribing', deviceLabel: session?.deviceLabel ?? null, indicator };
+    }
+    const kind = PHASE_INDICATOR[phase];
+    if (kind === undefined) return null;
+    const seconds = Math.floor((session?.durationMs ?? 0) / 1000);
+    return {
+      kind,
+      deviceLabel: session?.deviceLabel ?? null,
+      indicator,
+      ...(kind === 'recording' ? { detail: `${seconds}s` } : {}),
+    };
+  };
+
+  const transcribe = async (utterance: CapturedUtterance): Promise<void> => {
+    if (utterance.silent) {
+      deps.notify('[Voice] Nothing above the silence floor was captured, so nothing was transcribed.');
+      deps.render();
+      return;
+    }
+    const resolution = deps.resolveTranscriber();
+    if (!resolution.available) {
+      deps.notify(`[Voice] Captured ${Math.round(utterance.durationMs)} ms of audio but could not transcribe it: ${resolution.reason}`);
+      deps.render();
+      return;
+    }
+    transcribing = true;
+    deps.render();
+    try {
+      const text = (await resolution.gateway.transcribe(utteranceToAudioArtifact(utterance))).trim();
+      if (text.length === 0) {
+        deps.notify('[Voice] Speech-to-text returned no words for that recording.');
+      } else {
+        deps.writeDraft(text);
+      }
+    } catch (error) {
+      deps.notify(`[Voice] Transcription failed: ${describeTranscriptionFailure(error)}`);
+    } finally {
+      // The device is already released by the session's stop(); this only clears
+      // the indicator so a failed transcription cannot leave a "recording" row up.
+      transcribing = false;
+      deps.render();
+    }
+  };
+
+  const start = (): void => {
+    const settings = deps.readSettings();
+    const active = new PushToTalkSession({
+      openCapture: deps.openCapture,
+      capture: settings.capture,
+      captureMaxSeconds: settings.captureMaxSeconds,
+      // 0 disables silence-stop: someone who pressed the key and paused has not
+      // finished talking, so the second press is what ends the recording.
+      silenceStopMs: 0,
+      onPhaseChange: (next) => { phase = next; deps.render(); },
+      onAutoStop: (utterance) => {
+        // The ceiling fired instead of a second keypress. The audio is still what
+        // the user said, so it is transcribed rather than discarded.
+        session = null;
+        deps.notify(`[Voice] Recording reached the ${settings.captureMaxSeconds}s ceiling (voice.wake.captureMaxSeconds) and stopped on its own.`);
+        void transcribe(utterance);
+      },
+      onError: (error) => { deps.notify(`[Voice] Capture stopped: ${error.message}`); deps.render(); },
+    });
+    session = active;
+    void active.start().catch((error: unknown) => {
+      session = null;
+      phase = 'idle';
+      const message = error instanceof AudioCaptureError
+        ? `${error.message} (${error.reason})`
+        : error instanceof Error ? error.message : String(error);
+      deps.notify(`[Voice] Could not start recording: ${message}`);
+      deps.render();
+    });
+  };
+
+  const stop = (): void => {
+    const active = session;
+    if (active === null) return;
+    session = null;
+    void active.stop().then(
+      (utterance) => { if (utterance !== null) void transcribe(utterance); else deps.render(); },
+      (error: unknown) => {
+        deps.notify(`[Voice] Recording could not be stopped cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        deps.render();
+      },
+    );
+  };
+
+  return {
+    toggle: () => {
+      if (transcribing) {
+        deps.notify('[Voice] Still transcribing the previous recording.');
+        return;
+      }
+      if (session === null) start();
+      else stop();
+    },
+    status,
+    release: async () => {
+      const active = session;
+      session = null;
+      phase = 'idle';
+      if (active !== null) await active.cancel();
+    },
+  };
+}