@iinm/plain-agent 1.7.16 → 1.7.17

package/README.md

@@ -60,19 +60,19 @@ Create the configuration.
     {
       "name": "anthropic",
       "variant": "default",
-      "apiKey": "FIXME"
+      "apiKey": "<ANTHROPIC_API_KEY>"
       // Or
       // "apiKey": { "$env": "ANTHROPIC_API_KEY" }
     },
     {
       "name": "gemini",
       "variant": "default",
-      "apiKey": "FIXME"
+      "apiKey": "<GEMINI_API_KEY>"
     },
     {
       "name": "openai",
       "variant": "default",
-      "apiKey": "FIXME"
+      "apiKey": "<OPENAI_API_KEY>"
     },
   ],
 
@@ -81,7 +81,7 @@ Create the configuration.
     // askWeb: Searches the web to answer questions requiring up-to-date information or external sources.
     "askWeb": {
       "provider": "gemini",
-      "apiKey": "FIXME",
+      "apiKey": "<GEMINI_API_KEY>",
       "model": "gemini-3-flash-preview"
       // Optional
       // "baseURL": "<proxy_url>"
@@ -98,7 +98,7 @@ Create the configuration.
     //         Directly injecting URL content into context is not supported to prevent prompt injection.
     "askURL": {
       "provider": "gemini",
-      "apiKey": "FIXME"
+      "apiKey": "<GEMINI_API_KEY>"
       "model": "gemini-3-flash-preview"
       // Optional
       // "baseURL": "<proxy_url>"
@@ -134,7 +134,7 @@ Create the configuration.
       "name": "bedrock",
       "variant": "default",
       "baseURL": "https://bedrock-runtime.<region>.amazonaws.com",
-      "awsProfile": "FIXME"
+      "awsProfile": "<AWS_PROFILE>"
     },
     {
       // Requires gcloud CLI to get authentication token
@@ -159,19 +159,19 @@ Create the configuration.
       "name": "openai-compatible",
       "variant": "ollama",
       "baseURL": "https://ollama.com",
-      "apiKey": "FIXME"
+      "apiKey": "<API_KEY>"
     },
     {
       "name": "openai-compatible",
       "variant": "huggingface",
       "baseURL": "https://router.huggingface.co",
-      "apiKey": "FIXME"
+      "apiKey": "<HUGGINGFACE_API_KEY>"
     },
     {
       "name": "openai-compatible",
       "variant": "fireworks",
       "baseURL": "https://api.fireworks.ai/inference",
-      "apiKey": "FIXME"
+      "apiKey": "<FIREWORKS_API_KEY>"
     }
   ]
 }
@@ -243,7 +243,7 @@ Create the configuration.
       "name": "bedrock",
       "variant": "jp",
       "baseURL": "https://bedrock-runtime.ap-northeast-1.amazonaws.com",
-      "awsProfile": "FIXME"
+      "awsProfile": "<AWS_PROFILE>"
     }
   ]
 }
@@ -463,7 +463,7 @@ The agent loads configuration files in the following order. Settings in later fi
     // ⚠️ Add this to config.local.json to avoid committing secrets to Git
     "slack": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://mcp.slack.com/mcp", "--header", "Authorization:Bearer FIXME"],
+      "args": ["-y", "mcp-remote", "https://mcp.slack.com/mcp", "--header", "Authorization:Bearer <SLACK_TOKEN>"],
     },
     "notion": {
       "command": "npx",
@@ -480,12 +480,18 @@ The agent loads configuration files in the following order. Settings in later fi
     // ⚠️ Add this to config.local.json to avoid committing secrets to Git
     "google_developer-knowledge": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://developerknowledge.googleapis.com/mcp", "--header", "X-Goog-Api-Key:FIXME"]
+      "args": ["-y", "mcp-remote", "https://developerknowledge.googleapis.com/mcp", "--header", "X-Goog-Api-Key:<GOOGLE_API_KEY>"]
     }
   },
 
   // Override default notification command
   // "notifyCmd": "/path/to/notification-command"
+
+  // (Optional) Voice input. See "Voice Input" below.
+  // "voiceInput": {
+  //   "provider": "openai",
+  //   "apiKey": "<OPENAI_API_KEY>"
+  // }
 }
 ```
 </details>
@@ -606,6 +612,53 @@ Example:
 plain install-claude-code-plugins
 ```
 
+## Voice Input
+
+Press **Ctrl-O** to start recording, press it again to stop. Partial
+transcripts are inserted into the prompt as you speak so you can edit
+and send them like regular text.
+
+### Requirements
+
+- A recording command on `PATH`: `arecord`, `sox`, or `ffmpeg`.
+- An API key for the chosen provider.
+- Your host must have microphone access. The sandbox does not need to.
+
+### Providers
+
+**OpenAI Realtime** (default, recommended):
+
+```js
+{
+  "voiceInput": {
+    "provider": "openai",
+    "apiKey": "<OPENAI_API_KEY>"
+    // "model": "gpt-4o-transcribe",  // or "gpt-4o-mini-transcribe", "whisper-1"
+    // "language": "ja"               // ISO-639-1 code. Improves accuracy and latency.
+  }
+}
+```
+
+**Gemini Live** (preview API; model names and pricing may change):
+
+```js
+{
+  "voiceInput": {
+    "provider": "gemini",
+    "apiKey": "<GEMINI_API_KEY>"
+    // "model": "gemini-3.1-flash-live-preview",
+    // "language": "ja"
+  }
+}
+```
+
+### Options
+
+- `toggleKey` — Rebind the toggle. Accepts `"ctrl-<char>"` where `<char>`
+  is a letter (a-z) or one of `[ \ ] ^ _`. Defaults to `"ctrl-o"`.
+- `recorder` — Override recorder auto-detection. Must write raw 16-bit
+  little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
+
 ## Development
 
 ```sh
@@ -644,9 +697,9 @@ npm publish --access public
 
 ```sh
 # IAM Identity Center 
-identity_center_instance_arn="FIXME" # e.g., arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxxx"
-identity_store_id=FIXME
-aws_account_id=FIXME
+identity_center_instance_arn="<IDENTITY_CENTER_INSTANCE_ARN>" # e.g., arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxxx"
+identity_store_id=<IDENTITY_STORE_ID>
+aws_account_id=<AWS_ACCOUNT_ID>
 
 # Create a permission set
 permission_set_arn=$(aws sso-admin create-permission-set \
@@ -681,10 +734,10 @@ aws sso-admin put-inline-policy-to-permission-set \
   --inline-policy "$policy"
 
 # Create an SSO user
-sso_user_name=FIXME
-sso_user_email=FIXME
-sso_user_family_name=FIXME
-sso_user_given_name=FIXME
+sso_user_name=<SSO_USER_NAME>
+sso_user_email=<SSO_USER_EMAIL>
+sso_user_family_name=<SSO_USER_FAMILY_NAME>
+sso_user_given_name=<SSO_USER_GIVEN_NAME>
 
 user_id=$(aws identitystore create-user \
   --identity-store-id "$identity_store_id" \
@@ -725,8 +778,8 @@ aws bedrock-runtime invoke-model \
 <summary><b>Azure - Microsoft Foundry</b></summary>
 
 ```sh
-resource_group=FIXME
-account_name=FIXME # resource name
+resource_group=<RESOURCE_GROUP>
+account_name=<ACCOUNT_NAME> # resource name
 
 # Create a service principal
 service_principal=$(az ad sp create-for-rbac --name "CodingAgentServicePrincipal" --skip-assignment)
@@ -758,10 +811,10 @@ az login --service-principal -u "$app_id" -p "$app_secret" --tenant "$tenant_id"
 <summary><b>Google Cloud Vertex AI</b></summary>
 
 ```sh
-project_id=FIXME
-service_account_name=FIXME
+project_id=<PROJECT_ID>
+service_account_name=<SERVICE_ACCOUNT_NAME>
 service_account_email="${service_account_name}@${project_id}.iam.gserviceaccount.com"
-your_account_email=FIXME
+your_account_email=<YOUR_ACCOUNT_EMAIL>
 
 # Create a service account
 gcloud iam service-accounts create "$service_account_name" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.16",
+  "version": "1.7.17",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",

package/src/cliInteractive.mjs

@@ -1,6 +1,7 @@
 /**
  * @import { UserEventEmitter, AgentEventEmitter, AgentCommands } from "./agent"
  * @import { ClaudeCodePlugin } from "./claudeCodePlugin.mjs"
+ * @import { VoiceInputConfig, VoiceSession } from "./voiceInput.mjs"
  */
 
 import readline from "node:readline";
@@ -13,8 +14,10 @@ import {
   printMessage,
 } from "./cliFormatter.mjs";
 import { createInterruptTransform } from "./cliInterruptTransform.mjs";
+import { createMuteTransform } from "./cliMuteTransform.mjs";
 import { createPasteHandler } from "./cliPasteTransform.mjs";
 import { notify } from "./utils/notify.mjs";
+import { parseVoiceToggleKey, startVoiceSession } from "./voiceInput.mjs";
 
 const HELP_MESSAGE = [
   "Commands:",
@@ -57,6 +60,7 @@ const HELP_MESSAGE = [
  * @property {boolean} sandbox
  * @property {() => Promise<void>} onStop
  * @property {ClaudeCodePlugin[]} [claudeCodePlugins]
+ * @property {VoiceInputConfig} [voiceInput]
  */
 
 /**
@@ -72,6 +76,7 @@ export function startInteractiveSession({
   sandbox,
   onStop,
   claudeCodePlugins,
+  voiceInput,
 }) {
   /** @type {{ turn: boolean, multiLineBuffer: string[] | null, subagentName: string }} */
   const state = {
@@ -80,6 +85,16 @@ export function startInteractiveSession({
     subagentName: "",
   };
 
+  /**
+   * Active voice input session, or null when not recording.
+   * @type {{ session: VoiceSession, startCursor: number, transcriptLength: number } | null}
+   */
+  let voice = null;
+
+  // Parse the voice toggle key once at startup so misconfiguration fails
+  // loudly instead of silently falling back.
+  const voiceToggle = parseVoiceToggleKey(voiceInput?.toggleKey);
+
   const getCliPrompt = (subagentName = "", flashMessage = "") =>
     [
       "",
@@ -136,7 +151,100 @@ export function startInteractiveSession({
     cli.prompt();
   };
 
+  const stopVoiceSession = async () => {
+    if (!voice) return;
+    const current = voice;
+    voice = null;
+    await current.session.stop();
+    cli.setPrompt(currentCliPrompt);
+    // @ts-expect-error - internal property
+    cli._refreshLine?.();
+  };
+
+  const handleVoiceToggle = () => {
+    // Ignore while the agent is working.
+    if (!state.turn) return;
+
+    if (voice) {
+      stopVoiceSession();
+      return;
+    }
+
+    if (!voiceInput) {
+      cli.setPrompt(
+        getCliPrompt(
+          state.subagentName,
+          styleText(
+            "yellow",
+            `Voice input not configured. Set \`voiceInput\` in your config to enable ${voiceToggle.label}.`,
+          ),
+        ),
+      );
+      cli.prompt(true);
+      return;
+    }
+
+    const startCursor = cli.cursor;
+    const session = startVoiceSession({
+      config: voiceInput,
+      callbacks: {
+        onTranscript: (delta) => {
+          if (!voice) return;
+          const insertAt = voice.startCursor + voice.transcriptLength;
+          // Insert delta at the recording's insertion point. User input is
+          // swallowed while recording, so the buffer around `insertAt` is
+          // stable.
+          const before = cli.line.slice(0, insertAt);
+          const after = cli.line.slice(insertAt);
+          // `line` and `cursor` are declared readonly in the Node typings but
+          // are writable at runtime — the existing code already patches
+          // `_refreshLine` in the same way.
+          const mutableCli = /** @type {{ line: string, cursor: number }} */ (
+            /** @type {unknown} */ (cli)
+          );
+          mutableCli.line = before + delta + after;
+          mutableCli.cursor = insertAt + delta.length;
+          voice.transcriptLength += delta.length;
+          // @ts-expect-error - internal property
+          cli._refreshLine?.();
+        },
+        onError: (err) => {
+          voice = null;
+          cli.setPrompt(
+            getCliPrompt(
+              state.subagentName,
+              styleText("red", `Voice input error: ${err.message}`),
+            ),
+          );
+          cli.prompt(true);
+        },
+        onClose: () => {
+          if (!voice) return;
+          voice = null;
+          cli.setPrompt(currentCliPrompt);
+          // @ts-expect-error - internal property
+          cli._refreshLine?.();
+        },
+      },
+    });
+    voice = { session, startCursor, transcriptLength: 0 };
+    cli.setPrompt(
+      getCliPrompt(
+        state.subagentName,
+        styleText(["red", "bold"], `● REC  (${voiceToggle.label} to stop)`),
+      ),
+    );
+    // @ts-expect-error - internal property
+    cli._refreshLine?.();
+  };
+
   const handleCtrlC = () => {
+    // Stop voice recording first if active.
+    if (voice) {
+      stopVoiceSession();
+      return;
+    }
+
     // Agent turn: pause auto-approve; do not clear input.
     if (!state.turn) {
       agentCommands.pauseAutoApprove();
@@ -192,14 +300,20 @@ export function startInteractiveSession({
   };
 
   // Pre-readline pipeline:
-  //   stdin -> interrupt (Ctrl-C / Ctrl-D) -> paste (bracketed paste) -> readline
+  //   stdin -> interrupt (Ctrl-C / Ctrl-D) -> mute (voice recording) -> paste (bracketed paste) -> readline
   const interrupt = createInterruptTransform({
     onCtrlC: handleCtrlC,
     onCtrlD: handleCtrlD,
+    onVoiceToggle: handleVoiceToggle,
+    voiceToggleByte: voiceToggle.byte,
   });
+  // While a voice session is recording, swallow all stdin bytes other than
+  // Ctrl-C / Ctrl-D / the voice toggle key so transcript insertion stays
+  // consistent.
+  const mute = createMuteTransform({ isMuted: () => voice !== null });
   const paste = createPasteHandler();
 
-  process.stdin.pipe(interrupt).pipe(paste.transform);
+  process.stdin.pipe(interrupt).pipe(mute).pipe(paste.transform);
 
   // Enable bracketed paste mode
   if (process.stdout.isTTY) {

package/src/cliInterruptTransform.mjs

@@ -1,19 +1,31 @@
 import { Transform } from "node:stream";
 
 /**
- * Create a Transform that intercepts Ctrl-C (0x03) and Ctrl-D (0x04). When
- * either byte is seen anywhere in a chunk, the corresponding callback is
- * invoked and the entire chunk is dropped so that downstream consumers (e.g.
+ * Create a Transform that intercepts Ctrl-C (0x03), Ctrl-D (0x04), and an
+ * optional "voice toggle" byte (default Ctrl-O, 0x0f). When one of those
+ * bytes is seen anywhere in a chunk, the corresponding callback is invoked
+ * and the entire chunk is dropped so that downstream consumers (e.g.
  * readline) never observe it. All other input flows through unchanged.
  *
- * If both bytes appear in the same chunk, Ctrl-C is handled first.
+ * Priority when multiple handled bytes appear in the same chunk:
+ * Ctrl-C > Ctrl-D > voice toggle.
  *
  * @param {object} handlers
  * @param {() => void} handlers.onCtrlC - Called when Ctrl-C is detected
  * @param {() => void} handlers.onCtrlD - Called when Ctrl-D is detected
+ * @param {() => void} [handlers.onVoiceToggle]
+ *   Called when the voice toggle byte is detected.
+ * @param {number} [handlers.voiceToggleByte]
+ *   Byte value for the voice toggle key. Defaults to 0x0f (Ctrl-O).
  * @returns {Transform}
  */
-export function createInterruptTransform({ onCtrlC, onCtrlD }) {
+export function createInterruptTransform({
+  onCtrlC,
+  onCtrlD,
+  onVoiceToggle,
+  voiceToggleByte = 0x0f,
+}) {
+  const voiceToggleChar = String.fromCharCode(voiceToggleByte);
   return new Transform({
     transform(chunk, _encoding, callback) {
       const data = chunk.toString("utf8");
@@ -27,6 +39,11 @@ export function createInterruptTransform({ onCtrlC, onCtrlD }) {
         callback();
         return;
       }
+      if (onVoiceToggle && data.includes(voiceToggleChar)) {
+        onVoiceToggle();
+        callback();
+        return;
+      }
       this.push(chunk);
       callback();
     },

package/src/cliMuteTransform.mjs

@@ -0,0 +1,26 @@
+import { Transform } from "node:stream";
+
+/**
+ * Create a Transform that swallows all chunks while `isMuted()` returns true,
+ * and passes them through unchanged while it returns false.
+ *
+ * Intended to sit between `createInterruptTransform` and the paste handler so
+ * that callers can fully silence regular stdin input during special modes
+ * (e.g. while a voice input session is recording) without coupling that
+ * concern to the interrupt-detection logic.
+ *
+ * @param {object} options
+ * @param {() => boolean} options.isMuted
+ *   Called for each incoming chunk; when true the chunk is dropped.
+ * @returns {Transform}
+ */
+export function createMuteTransform({ isMuted }) {
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      if (!isMuted()) {
+        this.push(chunk);
+      }
+      callback();
+    },
+  });
+}

package/src/config.d.ts

@@ -4,6 +4,7 @@ import { AskURLToolOptions } from "./tools/askURL.mjs";
 import { AskWebToolOptions } from "./tools/askWeb.mjs";
 import { ExecCommandSanboxConfig } from "./tools/execCommand";
 import { ClaudeCodePluginRepo } from "./claudeCodePlugin.mjs";
+import { VoiceInputConfig } from "./voiceInput.mjs";
 
 export type AppConfig = {
   model?: string;
@@ -21,6 +22,7 @@ export type AppConfig = {
   };
   mcpServers?: Record<string, MCPServerConfig>;
   notifyCmd?: string;
+  voiceInput?: VoiceInputConfig;
   claudeCodePlugins?: ClaudeCodePluginRepo[];
 };
 

package/src/config.mjs

@@ -98,6 +98,9 @@ export async function loadAppConfig(options = {}) {
         ...(merged.claudeCodePlugins ?? []),
         ...(config.claudeCodePlugins ?? []),
       ],
+      voiceInput: config.voiceInput
+        ? { ...(merged.voiceInput ?? {}), ...config.voiceInput }
+        : merged.voiceInput,
     };
   }
 

package/src/main.mjs

@@ -257,6 +257,7 @@ if (cliArgs.subcommand.type === "install-claude-code-plugins") {
       ...sessionOptions,
       notifyCmd: appConfig.notifyCmd || AGENT_NOTIFY_CMD_DEFAULT,
       claudeCodePlugins: resolvePluginPaths(appConfig.claudeCodePlugins ?? []),
+      voiceInput: appConfig.voiceInput,
     });
   }
 })().catch((err) => {

package/src/voiceInput.mjs

@@ -0,0 +1,671 @@
+import { spawn, spawnSync } from "node:child_process";
+
+/**
+ * @typedef {VoiceInputOpenAIConfig | VoiceInputGeminiConfig} VoiceInputConfig
+ */
+
+/**
+ * @typedef {Object} VoiceInputOpenAIConfig
+ * @property {"openai"} provider
+ * @property {string} apiKey
+ * @property {string} [model] - Defaults to "gpt-4o-transcribe".
+ * @property {string} [language] - ISO-639-1 code (e.g. "ja", "en"). Improves accuracy and latency when set.
+ * @property {string} [baseURL]
+ * @property {VoiceRecorderConfig} [recorder]
+ * @property {string} [toggleKey] - "ctrl-<char>". Defaults to "ctrl-o".
+ */
+
+/**
+ * @typedef {Object} VoiceInputGeminiConfig
+ * @property {"gemini"} provider
+ * @property {string} apiKey
+ * @property {string} [model] - Defaults to "gemini-3.1-flash-live-preview".
+ * @property {string} [language] - ISO-639-1 code (e.g. "ja", "en"). Passed to the model as a system instruction since Gemini Live has no native language hint for input transcription.
+ * @property {string} [baseURL]
+ * @property {VoiceRecorderConfig} [recorder]
+ * @property {string} [toggleKey]
+ */
+
+/**
+ * @typedef {Object} VoiceRecorderConfig
+ * @property {string} command
+ * @property {string[]} args
+ *   Must write raw 16-bit little-endian mono PCM to stdout at the sample
+ *   rate required by the chosen provider (24 kHz for OpenAI, 16 kHz for
+ *   Gemini).
+ */
+
+/**
+ * @typedef {Object} VoiceSessionCallbacks
+ * @property {(text: string) => void} onTranscript
+ * @property {(error: Error) => void} onError
+ * @property {() => void} [onClose]
+ */
+
+/**
+ * @typedef {Object} VoiceSession
+ * @property {() => Promise<void>} stop
+ */
+
+const DEBUG = process.env.PLAIN_VOICE_DEBUG === "1";
+
+// Bytes reserved for other terminal/readline uses — cannot be used as a voice toggle.
+//   0x03 = Ctrl-C (SIGINT)
+//   0x04 = Ctrl-D (EOF / readline exit)
+//   0x09 = Ctrl-I (Tab)
+//   0x0a = Ctrl-J (LF / Enter)
+//   0x0d = Ctrl-M (CR / Enter)
+//   0x11 = Ctrl-Q (XON: resume terminal output)
+//   0x13 = Ctrl-S (XOFF: suspend terminal output)
+const RESERVED_TERMINAL_BYTES = new Set([
+  0x03, 0x04, 0x09, 0x0a, 0x0d, 0x11, 0x13,
+]);
+
+/**
+ * @typedef {Object} VoiceToggleKey
+ * @property {number} byte
+ * @property {string} label
+ */
+
+/**
+ * Parse a "ctrl-<char>" binding into the raw byte the terminal sends in
+ * raw mode. Only Ctrl-<char> is supported because it is the only family
+ * the pre-readline pipeline can recognize without a full key decoder.
+ *
+ * @param {string | undefined} spec
+ * @returns {VoiceToggleKey}
+ */
+export function parseVoiceToggleKey(spec) {
+  const raw = (spec ?? "ctrl-o").trim().toLowerCase();
+
+  const match = /^ctrl-(.)$/.exec(raw);
+  if (!match) {
+    throw new Error(
+      `Invalid voiceInput.toggleKey "${spec}". Expected "ctrl-<char>".`,
+    );
+  }
+
+  const ch = match[1];
+  const code = ch.charCodeAt(0);
+
+  // Subtracting a fixed offset from the character's ASCII code yields the
+  // control byte (0x01–0x1f) the terminal sends for that Ctrl combination.
+  let byte;
+  if (code >= 0x61 && code <= 0x7a) {
+    // a–z (0x61–0x7a): subtract 0x60 → 0x01 (Ctrl-A) – 0x1a (Ctrl-Z)
+    byte = code - 0x60;
+  } else if (code >= 0x5b && code <= 0x5f) {
+    // [ \ ] ^ _ (0x5b–0x5f): subtract 0x40 → 0x1b (Ctrl-[) – 0x1f (Ctrl-_)
+    byte = code - 0x40;
+  } else {
+    throw new Error(
+      `Unsupported voiceInput.toggleKey "${spec}". Use ctrl-<letter> or ctrl-<[ \\ ] ^ _>.`,
+    );
+  }
+
+  if (RESERVED_TERMINAL_BYTES.has(byte)) {
+    throw new Error(
+      `voiceInput.toggleKey "${spec}" conflicts with a reserved terminal/readline key.`,
+    );
+  }
+
+  return { byte, label: `Ctrl-${ch.toUpperCase()}` };
+}
+
+/**
+ * @param {number} sampleRate
+ * @returns {VoiceRecorderConfig[]}
+ */
+export function getRecorderCandidates(sampleRate) {
+  const rate = String(sampleRate);
+  const isMac = process.platform === "darwin";
+  /** @type {VoiceRecorderConfig[]} */
+  const candidates = [];
+
+  if (!isMac) {
+    candidates.push({
+      command: "arecord",
+      args: ["-q", "-f", "S16_LE", "-c", "1", "-r", rate, "-t", "raw"],
+    });
+  }
+
+  candidates.push({
+    command: "sox",
+    args: [
+      "-q",
+      "-d",
+      "-b",
+      "16",
+      "-c",
+      "1",
+      "-r",
+      rate,
+      "-e",
+      "signed-integer",
+      "-t",
+      "raw",
+      "-",
+    ],
+  });
+
+  const ffmpegInput = isMac
+    ? ["-f", "avfoundation", "-i", ":0"]
+    : ["-f", "alsa", "-i", "default"];
+  candidates.push({
+    command: "ffmpeg",
+    args: [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      ...ffmpegInput,
+      "-ac",
+      "1",
+      "-ar",
+      rate,
+      "-f",
+      "s16le",
+      "-",
+    ],
+  });
+
+  return candidates;
+}
+
+/**
+ * @param {VoiceRecorderConfig[]} candidates
+ * @returns {VoiceRecorderConfig | null}
+ */
+export function detectRecorder(candidates) {
+  return candidates.find((c) => isCommandAvailable(c.command)) ?? null;
+}
+
+/**
+ * @param {string} command
+ */
+function isCommandAvailable(command) {
+  if (process.platform === "win32") {
+    const result = spawnSync("where", [command], { stdio: "ignore" });
+    return result.status === 0;
+  }
+  const result = spawnSync("sh", ["-c", `command -v ${command}`], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+/**
+ * Start a voice input session. Spawns a recorder, opens a WebSocket to the
+ * configured provider, and streams transcript deltas via `onTranscript`.
+ *
+ * @param {object} options
+ * @param {VoiceInputConfig} options.config
+ * @param {VoiceSessionCallbacks} options.callbacks
+ * @returns {VoiceSession}
+ */
+export function startVoiceSession({ config, callbacks }) {
+  /**
+   * Report an error asynchronously and return an already-terminated session.
+   * @param {Error} error
+   * @returns {VoiceSession}
+   */
+  function failAsync(error) {
+    queueMicrotask(() => {
+      callbacks.onError(error);
+      callbacks.onClose?.();
+    });
+    return { stop: async () => {} };
+  }
+
+  /** @type {VoiceDriver} */
+  let driver;
+  try {
+    driver = createDriver(config);
+  } catch (err) {
+    return failAsync(err instanceof Error ? err : new Error(String(err)));
+  }
+
+  const recorder =
+    config.recorder ?? detectRecorder(getRecorderCandidates(driver.sampleRate));
+  if (!recorder) {
+    return failAsync(
+      new Error(
+        "No voice recorder found. Install arecord, sox, or ffmpeg (or set `voiceInput.recorder`).",
+      ),
+    );
+  }
+
+  if (!isCommandAvailable(recorder.command)) {
+    return failAsync(
+      new Error(
+        `Voice recorder command "${recorder.command}" not found on PATH.`,
+      ),
+    );
+  }
+
+  let stopped = false;
+  let closeEmitted = false;
+  let ready = false;
+  /** @type {Buffer[]} */
+  const pendingAudio = [];
+  const normalizer = createCJKSpaceNormalizer();
+
+  const emitClose = () => {
+    if (closeEmitted) return;
+    closeEmitted = true;
+    callbacks.onClose?.();
+  };
+
+  const ws = driver.connect();
+  ws.binaryType = "arraybuffer";
+
+  const child = spawn(recorder.command, recorder.args, {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  /** @type {string[]} */
+  const recorderStderr = [];
+  child.stderr.on("data", (chunk) => {
+    recorderStderr.push(chunk.toString("utf8"));
+  });
+
+  child.on("error", (err) => {
+    if (stopped) return;
+    const suffix =
+      /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+        ? ` (command "${recorder.command}" not found)`
+        : "";
+    callbacks.onError(
+      new Error(`Recorder failed to start${suffix}: ${err.message}`),
+    );
+    stop();
+  });
+
+  child.on("exit", (code, signal) => {
+    if (stopped) return;
+    if (code !== 0 && signal === null) {
+      const stderrText = recorderStderr.join("").trim();
+      callbacks.onError(
+        new Error(
+          `Recorder "${recorder.command}" exited with code ${code}${
+            stderrText ? `: ${stderrText}` : ""
+          }`,
+        ),
+      );
+    }
+    stop();
+  });
+
+  child.stdout.on("data", (chunk) => {
+    if (stopped) return;
+    if (ready && ws.readyState === WebSocket.OPEN) {
+      sendAudio(chunk);
+    } else {
+      pendingAudio.push(chunk);
+    }
+  });
+
+  ws.addEventListener("open", () => {
+    try {
+      ws.send(JSON.stringify(driver.buildSetup()));
+    } catch (err) {
+      callbacks.onError(
+        new Error(
+          `Failed to send setup message: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      );
+      stop();
+    }
+  });
+
+  ws.addEventListener("message", (event) => {
+    if (stopped) return;
+    let message;
+    let raw = "";
+    try {
+      raw =
+        typeof event.data === "string"
+          ? event.data
+          : Buffer.from(/** @type {ArrayBuffer} */ (event.data)).toString(
+              "utf8",
+            );
+      message = JSON.parse(raw);
+    } catch (err) {
+      callbacks.onError(
+        new Error(
+          `Failed to parse server message: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      );
+      return;
+    }
+    if (!isObject(message)) return;
+    if (DEBUG) {
+      process.stderr.write(`[voiceInput] <- ${raw.slice(0, 800)}\n`);
+    }
+
+    if (message.type === "error" && isObject(message.error)) {
+      const detail =
+        typeof message.error.message === "string"
+          ? message.error.message
+          : JSON.stringify(message.error);
+      callbacks.onError(new Error(`${driver.label} error: ${detail}`));
+      return;
+    }
+
+    if (!ready && driver.isReady(message)) {
+      ready = true;
+      for (const chunk of pendingAudio.splice(0)) {
+        if (ws.readyState === WebSocket.OPEN) sendAudio(chunk);
+      }
+      return;
+    }
+
+    const text = driver.parseTranscript(message);
+    if (text !== null) {
+      const normalized = normalizer.push(text);
+      if (normalized.length > 0) {
+        callbacks.onTranscript(normalized);
+      }
+    }
+  });
+
+  ws.addEventListener("error", (event) => {
+    if (stopped) return;
+    const message =
+      /** @type {{ message?: string }} */ (event).message ?? "WebSocket error";
+    callbacks.onError(new Error(`${driver.label} WebSocket error: ${message}`));
+    stop();
+  });
+
+  ws.addEventListener("close", (event) => {
+    if (!stopped && event.code !== 1000 && event.code !== 1005) {
+      const reason = event.reason ? `: ${event.reason}` : "";
+      callbacks.onError(
+        new Error(
+          `${driver.label} WebSocket closed (code ${event.code}${reason})`,
+        ),
+      );
+    }
+    stopped = true;
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // ignore
+    }
+    emitClose();
+  });
+
+  /**
+   * @param {Buffer} chunk
+   */
+  function sendAudio(chunk) {
+    const payload = driver.buildAudioMessage(chunk.toString("base64"));
+    try {
+      ws.send(JSON.stringify(payload));
+    } catch {
+      // connection may have just closed
+    }
+  }
+
+  if (DEBUG) {
+    process.stderr.write(
+      `[voiceInput] driver=${driver.label} recorder=${recorder.command} ${recorder.args.join(" ")}\n`,
+    );
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async function stop() {
+    if (stopped) return;
+    stopped = true;
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // ignore
+    }
+    if (
+      ws.readyState === WebSocket.OPEN ||
+      ws.readyState === WebSocket.CONNECTING
+    ) {
+      try {
+        ws.close(1000, "client stop");
+      } catch {
+        // ignore
+      }
+    }
+    emitClose();
+  }
+
+  return { stop };
+}
+
+/**
+ * @typedef {Object} VoiceDriver
+ * @property {string} label
+ * @property {number} sampleRate
+ * @property {() => WebSocket} connect
+ * @property {() => object} buildSetup
+ * @property {(message: Record<string, unknown>) => boolean} isReady
+ * @property {(base64: string) => object} buildAudioMessage
+ * @property {(message: Record<string, unknown>) => string | null} parseTranscript
+ */
+
+/**
+ * @param {VoiceInputConfig} config
+ * @returns {VoiceDriver}
+ */
+function createDriver(config) {
+  if (config.provider === "openai") {
+    return createOpenAIDriver(config);
+  }
+  if (config.provider === "gemini") {
+    return createGeminiDriver(config);
+  }
+  throw new Error(
+    `Unsupported voiceInput.provider: ${/** @type {{provider: string}} */ (config).provider}`,
+  );
+}
+
+const OPENAI_DEFAULT_MODEL = "gpt-4o-transcribe";
+const OPENAI_DEFAULT_WS = "wss://api.openai.com/v1/realtime";
+const OPENAI_SAMPLE_RATE = 24000;
+
+/**
+ * @param {VoiceInputOpenAIConfig} config
+ * @returns {VoiceDriver}
+ */
+function createOpenAIDriver(config) {
+  const model = config.model ?? OPENAI_DEFAULT_MODEL;
+  const base = config.baseURL ?? OPENAI_DEFAULT_WS;
+  return {
+    label: "OpenAI Realtime",
+    sampleRate: OPENAI_SAMPLE_RATE,
+    connect() {
+      // Node's global WebSocket (undici) accepts a non-standard `headers`
+      // option. The built-in typings only declare the standards-compliant
+      // constructor, so cast through `WebSocket`-as-constructor.
+      const Ctor =
+        /** @type {new (url: string, opts?: unknown) => WebSocket} */ (
+          /** @type {unknown} */ (WebSocket)
+        );
+      return new Ctor(`${base}?intent=transcription`, {
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`,
+          "OpenAI-Beta": "realtime=v1",
+        },
+      });
+    },
+    buildSetup() {
+      /** @type {{ model: string, language?: string }} */
+      const transcription = { model };
+      if (config.language) transcription.language = config.language;
+      // The `?intent=transcription` endpoint uses the flat transcription-session
+      // schema, not the nested `session.audio.input.*` realtime schema.
+      return {
+        type: "transcription_session.update",
+        session: {
+          input_audio_format: "pcm16",
+          input_audio_transcription: transcription,
+          turn_detection: { type: "server_vad" },
+        },
+      };
+    },
+    isReady(message) {
+      return (
+        message.type === "transcription_session.created" ||
+        message.type === "transcription_session.updated"
+      );
+    },
+    buildAudioMessage(base64) {
+      return { type: "input_audio_buffer.append", audio: base64 };
+    },
+    parseTranscript(message) {
+      if (
+        message.type === "conversation.item.input_audio_transcription.delta" &&
+        typeof message.delta === "string" &&
+        message.delta.length > 0
+      ) {
+        return message.delta;
+      }
+      return null;
+    },
+  };
+}
+
+const GEMINI_DEFAULT_MODEL = "gemini-3.1-flash-live-preview";
+const GEMINI_DEFAULT_WS =
+  "wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent";
+const GEMINI_SAMPLE_RATE = 16000;
+
+/**
+ * @param {VoiceInputGeminiConfig} config
+ * @returns {VoiceDriver}
+ */
+function createGeminiDriver(config) {
+  const model = config.model ?? GEMINI_DEFAULT_MODEL;
+  const base = config.baseURL ?? GEMINI_DEFAULT_WS;
+  return {
+    label: "Gemini Live",
+    sampleRate: GEMINI_SAMPLE_RATE,
+    connect() {
+      return new WebSocket(`${base}?key=${encodeURIComponent(config.apiKey)}`);
+    },
+    buildSetup() {
+      // Gemini Live was designed for voice agents, not pure STT.
+      // Force maxOutputTokens: 1 and disable thinking on 2.5 models
+      // to minimise wasted audio output.
+
+      /** @type {Record<string, unknown>} */
+      const generationConfig = {
+        // https://ai.google.dev/gemini-api/docs/live-api/capabilities#response-modalities
+        // > The native audio models only support `AUDIO response modality.
+        responseModalities: ["AUDIO"],
+        maxOutputTokens: 1,
+      };
+      if (model.includes("2.5")) {
+        generationConfig.thinkingConfig = { thinkingBudget: 0 };
+      }
+      /** @type {Record<string, unknown>} */
+      const setup = {
+        model: `models/${model}`,
+        generationConfig,
+        inputAudioTranscription: {},
+      };
+      if (config.language) {
+        setup.systemInstruction = {
+          parts: [{ text: `The user is speaking in ${config.language}.` }],
+        };
+      }
+      return { setup };
+    },
+    isReady(message) {
+      return "setupComplete" in message;
+    },
+    buildAudioMessage(base64) {
+      return {
+        realtimeInput: {
+          audio: {
+            data: base64,
+            mimeType: `audio/pcm;rate=${GEMINI_SAMPLE_RATE}`,
+          },
+        },
+      };
+    },
+    parseTranscript(message) {
+      const serverContent = message.serverContent;
+      if (!isObject(serverContent)) return null;
+      const t = serverContent.inputTranscription;
+      if (isObject(t) && typeof t.text === "string" && t.text.length > 0) {
+        return t.text;
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * Drop whitespace sitting between two CJK characters. Some providers return
+ * Japanese transcripts with morpheme-separating spaces ("そう 、 声 で");
+ * mixed strings like "Windows を使う" keep their inter-script spaces.
+ *
+ * @returns {{ push: (text: string) => string, flush: () => string }}
+ */
+export function createCJKSpaceNormalizer() {
+  let prevChar = "";
+  let pendingSpaces = "";
+  const isSpace = (/** @type {string} */ c) =>
+    c === " " || c === "\t" || c === "\u3000";
+
+  return {
+    push(text) {
+      let out = "";
+      for (const ch of text) {
+        if (isSpace(ch)) {
+          pendingSpaces += ch;
+          continue;
+        }
+        if (pendingSpaces.length > 0) {
+          if (!(isCJKChar(prevChar) && isCJKChar(ch))) {
+            out += pendingSpaces;
+          }
+          pendingSpaces = "";
+        }
+        out += ch;
+        prevChar = ch;
+      }
+      return out;
+    },
+    flush() {
+      const out = pendingSpaces;
+      pendingSpaces = "";
+      prevChar = "";
+      return out;
+    },
+  };
+}
+
+/**
+ * @param {string} ch
+ * @returns {boolean}
+ */
+function isCJKChar(ch) {
+  const code = ch.codePointAt(0);
+  if (code === undefined) return false;
+  return (
+    (code >= 0x3000 && code <= 0x33ff) ||
+    (code >= 0x3400 && code <= 0x4dbf) ||
+    (code >= 0x4e00 && code <= 0x9fff) ||
+    (code >= 0xac00 && code <= 0xd7af) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xff00 && code <= 0xffef) ||
+    (code >= 0x20000 && code <= 0x2ffff)
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}