@iinm/plain-agent 1.11.9 → 1.12.0

package/README.md

@@ -3,7 +3,7 @@
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/iinm/plain-agent)
 [![npm version](https://img.shields.io/npm/v/@iinm/plain-agent)](https://www.npmjs.com/package/@iinm/plain-agent)
 [![install size](https://packagephobia.com/badge?p=@iinm/plain-agent)](https://packagephobia.com/result?p=@iinm/plain-agent)
-[![Socket Badge](https://badge.socket.dev/npm/package/@iinm/plain-agent/1.11.9)](https://socket.dev/npm/package/@iinm/plain-agent)
+[![Socket Badge](https://badge.socket.dev/npm/package/@iinm/plain-agent/1.12.0)](https://socket.dev/npm/package/@iinm/plain-agent)
 [![CodeQL](https://github.com/iinm/plain-agent/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/iinm/plain-agent/actions/workflows/github-code-scanning/codeql)
 
 A lightweight terminal-based coding agent focused on safety and low token cost
@@ -25,7 +25,6 @@ A lightweight terminal-based coding agent focused on safety and low token cost
 - [Prompts](#prompts)
 - [Subagents](#subagents)
 - [Claude Code Plugin Support](#claude-code-plugin-support)
-- [Voice Input](#voice-input)
 - [Appendix: Creating Least-Privilege Users for Cloud Providers](#appendix-creating-least-privilege-users-for-cloud-providers)
 - [Developer Notes](#developer-notes)
 
@@ -848,52 +847,6 @@ Example:
 plain install-claude-code-plugins
 ```
 
-## Voice Input
-
-Press **Ctrl-O** to start recording, then 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.
-
-### Providers
-
-**OpenAI Realtime**
-
-```js
-// ~/.config/plain-agent/config.local.json
-{
-  "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**
-
-```js
-// ~/.config/plain-agent/config.local.json
-{
-  "voiceInput": {
-    "provider": "gemini",
-    "apiKey": "<GEMINI_API_KEY>"
-    // "model": "gemini-3.1-flash-live-preview",
-    // "language": "ja"
-  }
-}
-```
-
-### Options
-
-- `toggleKey` — Rebind the toggle key. Accepts `"ctrl-<char>"` where `<char>`
-  is a letter (a-z) or one of `[ \ ] ^ _`. Defaults to `"ctrl-o"`.
-- `recorder` — Override automatic recorder detection, e.g. `{ "command": "sox", "args": ["-q", "-d", "-b", "16", "-c", "1", "-r", "24000", "-e", "signed-integer", "-t", "raw", "-"] }`. It must write raw 16-bit little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
-
 ## Appendix: Creating Least-Privilege Users for Cloud Providers
 
 <details>

package/config/config.predefined.json

@@ -5,9 +5,15 @@
     "patterns": [
       {
         "toolName": "exec_command",
-        "input": { "command": { "$regex": "^(find|grep)$" } },
+        "input": { "command": "find" },
         "action": "deny",
-        "reason": "Use rg or fd instead"
+        "reason": "Use fd instead; fd respects .gitignore by default"
+      },
+      {
+        "toolName": "exec_command",
+        "input": { "command": "grep" },
+        "action": "deny",
+        "reason": "Use rg instead; rg respects .gitignore by default"
       },
       {
         "toolName": "exec_command",
@@ -146,6 +152,16 @@
       }
     ],
     "tests": [
+      {
+        "desc": "find should be denied",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "find" } },
+        "expectedAction": "deny"
+      },
+      {
+        "desc": "grep should be denied",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "grep" } },
+        "expectedAction": "deny"
+      },
       {
         "desc": "ls should be allowed",
         "toolUse": { "toolName": "exec_command", "input": { "command": "ls" } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.11.9",
+  "version": "1.12.0",
   "description": "A lightweight terminal-based coding agent focused on safety and low token cost",
   "license": "MIT",
   "type": "module",

package/src/cli/interactive.mjs

@@ -2,8 +2,6 @@
  * @import { UserEventEmitter, AgentEventEmitter, AgentCommands } from "../agent"
  * @import { ClaudeCodePlugin } from "../claudeCodePlugin.mjs"
  * @import { Tool, SandboxModeProvider } from "../tool"
- * @import { VoiceInputConfig } from "../voice/input.mjs"
- * @import { VoiceSession } from "../voice/session.mjs"
  */
 
 import readline from "node:readline";
@@ -11,8 +9,6 @@ import { styleText } from "node:util";
 import { appendUsageRecord, buildUsageRecord } from "../usageStore.mjs";
 import { createSequentialExecutor } from "../utils/createSequentialExecutor.mjs";
 import { notify } from "../utils/notify.mjs";
-import { startVoiceSession } from "../voice/input.mjs";
-import { parseVoiceToggleKey } from "../voice/toggleKey.mjs";
 import { createCommandHandler } from "./commands.mjs";
 import { createCompleter, SLASH_COMMANDS } from "./completer.mjs";
 import {
@@ -21,7 +17,6 @@ import {
   printMessage,
 } from "./formatter.mjs";
 import { createInterruptTransform } from "./interruptTransform.mjs";
-import { createMuteTransform } from "./muteTransform.mjs";
 import { createPasteHandler } from "./pasteTransform.mjs";
 import { createStreamFormatter } from "./streamFormatter.mjs";
 
@@ -67,7 +62,6 @@ const HELP_MESSAGE = [
  * @property {boolean} sandbox
  * @property {() => Promise<void>} onStop
  * @property {ClaudeCodePlugin[]} [claudeCodePlugins]
- * @property {VoiceInputConfig} [voiceInput]
  * @property {Tool & SandboxModeProvider} [execCommandTool]
  */
 
@@ -112,7 +106,6 @@ export function startInteractiveSession({
   sandbox,
   onStop,
   claudeCodePlugins,
-  voiceInput,
   execCommandTool,
 }) {
   /** @type {{ turn: boolean, multiLineBuffer: string[] | null, subagentName: string, toolSpinnerIndex: number, toolSpinnerLastTime: number }} */
@@ -127,19 +120,9 @@ export function startInteractiveSession({
   const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
   const SPINNER_INTERVAL_MS = 80;
 
-  /**
-   * Active voice input session, or null when not recording.
-   * @type {{ session: VoiceSession, startCursor: number, transcriptLength: number } | null}
-   */
-  let voice = null;
-
   // Create the stream buffer instance for this session
   const streamBuffer = createStreamBuffer();
 
-  // 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 = "") =>
     [
       "",
@@ -198,100 +181,7 @@ 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();
@@ -347,20 +237,14 @@ export function startInteractiveSession({
   };
 
   // Pre-readline pipeline:
-  //   stdin -> interrupt (Ctrl-C / Ctrl-D) -> mute (voice recording) -> paste (bracketed paste) -> readline
+  //   stdin -> interrupt (Ctrl-C / Ctrl-D) -> 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(mute).pipe(paste.transform);
+  process.stdin.pipe(interrupt).pipe(paste.transform);
 
   // Enable bracketed paste mode
   if (process.stdout.isTTY) {

package/src/cli/interruptTransform.mjs

@@ -1,31 +1,21 @@
 import { Transform } from "node:stream";
 
 /**
- * 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.
+ * Create a Transform that intercepts Ctrl-C (0x03) and Ctrl-D (0x04).
+ * 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.
  *
  * Priority when multiple handled bytes appear in the same chunk:
- * Ctrl-C > Ctrl-D > voice toggle.
+ * Ctrl-C > Ctrl-D.
  *
  * @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,
-  onVoiceToggle,
-  voiceToggleByte = 0x0f,
-}) {
-  const voiceToggleChar = String.fromCharCode(voiceToggleByte);
+export function createInterruptTransform({ onCtrlC, onCtrlD }) {
   return new Transform({
     transform(chunk, _encoding, callback) {
       const data = chunk.toString("utf8");
@@ -39,11 +29,6 @@ export function createInterruptTransform({
         callback();
         return;
       }
-      if (onVoiceToggle && data.includes(voiceToggleChar)) {
-        onVoiceToggle();
-        callback();
-        return;
-      }
       this.push(chunk);
       callback();
     },

package/src/config.d.ts

@@ -10,7 +10,6 @@ import {
   WebSearchToolGeminiOptions,
   WebSearchToolGeminiVertexAIOptions,
 } from "./tools/webSearch.mjs";
-import { VoiceInputConfig } from "./voice/input.mjs";
 
 /**
  * JSON-serializable webFetch configuration.
@@ -88,7 +87,6 @@ export type AppConfig = {
   };
   mcpServers?: Record<string, MCPServerConfig>;
   notifyCmd?: { command: string; args?: string[] };
-  voiceInput?: VoiceInputConfig;
   claudeCodePlugins?: ClaudeCodePluginRepo[];
 };
 

package/src/config.mjs

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

package/src/main.mjs

@@ -447,7 +447,6 @@ export async function main(argv = process.argv) {
       execCommandTool,
       notifyCmd: appConfig.notifyCmd,
       claudeCodePlugins: resolvePluginPaths(appConfig.claudeCodePlugins ?? []),
-      voiceInput: appConfig.voiceInput,
     });
   }
 }

package/src/cli/muteTransform.mjs

@@ -1,26 +0,0 @@
-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/voice/gemini.mjs

@@ -1,102 +0,0 @@
-import { isObjectLike, startWebSocketVoiceSession } from "./session.mjs";
-
-/**
- * @import { VoiceProviderHooks, VoiceRecorderConfig, VoiceSession, VoiceSessionCallbacks } from "./session.mjs"
- */
-
-/**
- * @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]
- */
-
-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;
-const GEMINI_LABEL = "Gemini Live";
-
-/**
- * Start a voice input session backed by the Gemini Live BidiGenerateContent
- * WebSocket. Spawns a recorder, streams PCM as base64 JSON messages, and
- * forwards transcript deltas via `onTranscript`.
- *
- * Gemini Live was designed for voice agents, not pure STT, so the setup
- * message forces `maxOutputTokens: 1` and disables thinking on 2.5 models
- * to minimise wasted audio output.
- *
- * @param {object} options
- * @param {VoiceInputGeminiConfig} options.config
- * @param {VoiceSessionCallbacks} options.callbacks
- * @returns {VoiceSession}
- */
-export function startGeminiVoiceSession({ config, callbacks }) {
-  /** @type {VoiceProviderHooks<VoiceInputGeminiConfig>} */
-  const hooks = {
-    label: GEMINI_LABEL,
-    sampleRate: GEMINI_SAMPLE_RATE,
-    buildWsUrl(config) {
-      const base = config.baseURL ?? GEMINI_DEFAULT_WS;
-      return `${base}?key=${encodeURIComponent(config.apiKey)}`;
-    },
-    buildSetupMessage(config) {
-      const model = config.model ?? GEMINI_DEFAULT_MODEL;
-      /** @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 };
-    },
-    isReadyMessage(message) {
-      return isObjectLike(message) && "setupComplete" in message;
-    },
-    extractTranscript(message) {
-      if (!isObjectLike(message)) return undefined;
-      const serverContent = message.serverContent;
-      if (!isObjectLike(serverContent)) return undefined;
-      const transcription = serverContent.inputTranscription;
-      if (
-        isObjectLike(transcription) &&
-        typeof transcription.text === "string" &&
-        transcription.text.length > 0
-      ) {
-        return transcription.text;
-      }
-      return undefined;
-    },
-    buildAudioPayload(chunk, sampleRate) {
-      return {
-        realtimeInput: {
-          audio: {
-            data: chunk.toString("base64"),
-            mimeType: `audio/pcm;rate=${sampleRate}`,
-          },
-        },
-      };
-    },
-  };
-
-  return startWebSocketVoiceSession({ hooks, config, callbacks });
-}

package/src/voice/input.mjs

@@ -1,29 +0,0 @@
-import { startGeminiVoiceSession } from "./gemini.mjs";
-import { startOpenAIVoiceSession } from "./openai.mjs";
-import { failVoiceSessionAsync } from "./session.mjs";
-
-/**
- * @typedef {import("./openai.mjs").VoiceInputOpenAIConfig | import("./gemini.mjs").VoiceInputGeminiConfig} VoiceInputConfig
- */
-/**
- * Start a voice input session. Dispatches to the provider-specific
- * implementation based on `config.provider`.
- *
- * @param {object} options
- * @param {VoiceInputConfig} options.config
- * @param {import("./session.mjs").VoiceSessionCallbacks} options.callbacks
- * @returns {import("./session.mjs").VoiceSession}
- */
-export function startVoiceSession({ config, callbacks }) {
-  if (config.provider === "openai") {
-    return startOpenAIVoiceSession({ config, callbacks });
-  }
-  if (config.provider === "gemini") {
-    return startGeminiVoiceSession({ config, callbacks });
-  }
-  const provider = /** @type {{ provider: string }} */ (config).provider;
-  return failVoiceSessionAsync(
-    callbacks,
-    new Error(`Unsupported voiceInput.provider: ${provider}`),
-  );
-}

package/src/voice/openai.mjs

@@ -1,102 +0,0 @@
-import { isObjectLike, startWebSocketVoiceSession } from "./session.mjs";
-
-/**
- * @import { VoiceProviderHooks, VoiceRecorderConfig, VoiceSession, VoiceSessionCallbacks } from "./session.mjs"
- */
-
-/**
- * @typedef {Object} VoiceInputOpenAIConfig
- * @property {"openai"} provider
- * @property {string} apiKey
- * @property {string} [model] - Transcription model. Defaults to "gpt-realtime-whisper".
- * @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".
- */
-
-const OPENAI_DEFAULT_TRANSCRIPTION_MODEL = "gpt-realtime-whisper";
-const OPENAI_DEFAULT_WS = "wss://api.openai.com/v1/realtime";
-const OPENAI_SAMPLE_RATE = 24000;
-const OPENAI_LABEL = "OpenAI Realtime";
-
-/**
- * Start a voice input session backed by the OpenAI Realtime transcription
- * WebSocket. Spawns a recorder, streams PCM as base64 JSON messages, and
- * forwards transcript deltas via `onTranscript`.
- *
- * @param {object} options
- * @param {VoiceInputOpenAIConfig} options.config
- * @param {VoiceSessionCallbacks} options.callbacks
- * @returns {VoiceSession}
- */
-export function startOpenAIVoiceSession({ config, callbacks }) {
-  /** @type {VoiceProviderHooks<VoiceInputOpenAIConfig>} */
-  const hooks = {
-    label: OPENAI_LABEL,
-    sampleRate: OPENAI_SAMPLE_RATE,
-    buildWsUrl(config) {
-      const base = config.baseURL ?? OPENAI_DEFAULT_WS;
-      return `${base}?intent=transcription`;
-    },
-    buildWsOptions(config) {
-      return {
-        headers: {
-          Authorization: `Bearer ${config.apiKey}`,
-        },
-      };
-    },
-    buildSetupMessage(config) {
-      const model = config.model ?? OPENAI_DEFAULT_TRANSCRIPTION_MODEL;
-      /** @type {{ model: string, language?: string }} */
-      const transcription = { model };
-      if (config.language) transcription.language = config.language;
-      return {
-        type: "session.update",
-        session: {
-          type: "transcription",
-          audio: {
-            input: {
-              format: { type: "audio/pcm", rate: OPENAI_SAMPLE_RATE },
-              transcription,
-            },
-          },
-        },
-      };
-    },
-    isReadyMessage(message) {
-      return (
-        isObjectLike(message) &&
-        (message.type === "session.created" ||
-          message.type === "session.updated")
-      );
-    },
-    extractError(message) {
-      if (!isObjectLike(message) || message.type !== "error") return undefined;
-      const error = message.error;
-      if (!isObjectLike(error)) return undefined;
-      return typeof error.message === "string"
-        ? error.message
-        : JSON.stringify(error);
-    },
-    extractTranscript(message) {
-      if (
-        isObjectLike(message) &&
-        message.type === "conversation.item.input_audio_transcription.delta" &&
-        typeof message.delta === "string" &&
-        message.delta.length > 0
-      ) {
-        return message.delta;
-      }
-      return undefined;
-    },
-    buildAudioPayload(chunk, _sampleRate) {
-      return {
-        type: "input_audio_buffer.append",
-        audio: chunk.toString("base64"),
-      };
-    },
-  };
-
-  return startWebSocketVoiceSession({ hooks, config, callbacks });
-}

package/src/voice/session.mjs

@@ -1,543 +0,0 @@
-import { spawn, spawnSync } from "node:child_process";
-
-/**
- * @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
- */
-
-/**
- * @typedef {Object} RecorderHandle
- * @property {() => void} stop
- */
-
-export const VOICE_DEBUG = process.env.PLAIN_VOICE_DEBUG === "1";
-
-/**
- * @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
- */
-export 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;
-}
-
-/**
- * Spawn a recorder subprocess that emits raw PCM on stdout, and wire its
- * lifecycle events to the provided callbacks. This is purely transport
- * plumbing — it knows nothing about any specific STT provider.
- *
- * @param {object} options
- * @param {VoiceRecorderConfig} options.recorder
- * @param {(chunk: Buffer) => void} options.onAudio
- * @param {(error: Error) => void} options.onError
- * @param {() => void} options.onExit - Called after the recorder subprocess exits (for any reason).
- * @returns {RecorderHandle}
- */
-export function startRecorder({ recorder, onAudio, onError, onExit }) {
-  const child = spawn(recorder.command, recorder.args, {
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
-  /** @type {string[]} */
-  const stderrChunks = [];
-  child.stderr.on("data", (chunk) => {
-    stderrChunks.push(chunk.toString("utf8"));
-  });
-
-  child.on("error", (err) => {
-    const suffix =
-      /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
-        ? ` (command "${recorder.command}" not found)`
-        : "";
-    onError(new Error(`Recorder failed to start${suffix}: ${err.message}`));
-  });
-
-  child.on("exit", (code, signal) => {
-    if (code !== 0 && signal === null) {
-      const stderrText = stderrChunks.join("").trim();
-      onError(
-        new Error(
-          `Recorder "${recorder.command}" exited with code ${code}${
-            stderrText ? `: ${stderrText}` : ""
-          }`,
-        ),
-      );
-    }
-    onExit();
-  });
-
-  child.stdout.on("data", onAudio);
-
-  return {
-    stop() {
-      try {
-        child.kill("SIGTERM");
-      } catch {
-        // ignore
-      }
-    },
-  };
-}
-
-/**
- * Report an error asynchronously and return an already-terminated session.
- *
- * Calls `onError` followed by `onClose` in a microtask, ensuring the caller
- * receives a valid {@link VoiceSession} synchronously while still notifying
- * the consumer of the failure.
- *
- * @param {VoiceSessionCallbacks} callbacks
- * @param {Error} error
- * @returns {VoiceSession}
- */
-export function failVoiceSessionAsync(callbacks, error) {
-  queueMicrotask(() => {
-    callbacks.onError(error);
-    callbacks.onClose?.();
-  });
-  return { stop: async () => {} };
-}
-
-/**
- * Provider-specific hook contract for {@link startWebSocketVoiceSession}.
- *
- * Each hook is called at a specific point in the session lifecycle:
- *
- * 1. **Construction** – `buildWsUrl` (and optionally `buildWsOptions`) are
- *    invoked immediately to create the WebSocket.
- * 2. **Open** – `buildSetupMessage` is sent as the first JSON message once the
- *    WebSocket opens.
- * 3. **Ready** – `isReadyMessage` is tested on every incoming message until it
- *    returns `true`. At that point the session transitions to *ready* and any
- *    buffered audio chunks are flushed.
- * 4. **Streaming** – `buildAudioPayload` is called for every recorder chunk
- *    while the WebSocket is open and ready.
- * 5. **Error extraction** – `extractError` is checked on every message before
- *    transcript extraction. If it returns a string, the session reports an
- *    error and drops the message.
- * 6. **Transcription** – `extractTranscript` is called on every message after
- *    the session is ready. Non-empty results are pushed through the CJK
- *    space normalizer and then forwarded to `onTranscript`.
- *
- * @template TConfig
- * @typedef {Object} VoiceProviderHooks
- * @property {string} label - Human-readable provider name (used in logs and
- *   error messages).
- * @property {number} sampleRate - PCM sample rate expected by the provider
- *   (e.g. 16000 for Gemini, 24000 for OpenAI). Passed to the recorder and
- *   `buildAudioPayload`.
- * @property {(config: TConfig) => string} buildWsUrl - Returns the full
- *   WebSocket URL, including any query parameters.
- * @property {(config: TConfig) => { headers?: Record<string, string> }} [buildWsOptions]
- *   - Returns optional per-provider WebSocket constructor options. Node's
- *   global WebSocket (undici) accepts a non-standard `headers` option that
- *   is not declared in the standard typings.
- * @property {(config: TConfig) => object} buildSetupMessage - Returns the
- *   first JSON message sent immediately after the WebSocket opens.
- * @property {(message: unknown) => boolean} isReadyMessage - Returns `true`
- *   when the given server message signals that the provider is ready to
- *   receive audio.
- * @property {(message: unknown) => string | undefined} extractTranscript -
- *   Extracts a transcript delta from a server message. Return `undefined`
- *   when the message carries no transcript.
- * @property {(message: unknown) => string | undefined} [extractError] -
- *   Extracts an error description from a server message. Return `undefined`
- *   when the message carries no error.
- * @property {(chunk: Buffer, sampleRate: number) => object} buildAudioPayload -
- *   Wraps a raw PCM chunk into the provider-specific JSON payload. The
- *   `sampleRate` argument is the same value as `hooks.sampleRate`.
- */
-
-/**
- * Shared WebSocket voice session implementation used by both Gemini and
- * OpenAI drivers.
- *
- * Responsibilities of this function:
- * - Detect and start a suitable system audio recorder.
- * - Establish the provider WebSocket connection.
- * - Manage the lifecycle (setup → ready → streaming → close).
- * - Buffer audio chunks while the connection is not yet ready.
- * - Apply CJK space normalization to transcript text.
- *
- * Responsibilities of the caller (the driver):
- * - Provide a {@link VoiceProviderHooks} object that knows the provider's
- *   wire protocol (URLs, headers, message schemas).
- * - Supply `config` and `callbacks` from the user's call site.
- *
- * @template TConfig
- * @param {object} options
- * @param {VoiceProviderHooks<TConfig>} options.hooks
- * @param {TConfig & { recorder?: VoiceRecorderConfig }} options.config
- * @param {VoiceSessionCallbacks} options.callbacks
- * @returns {VoiceSession}
- */
-export function startWebSocketVoiceSession({ hooks, config, callbacks }) {
-  const recorder =
-    config.recorder ?? detectRecorder(getRecorderCandidates(hooks.sampleRate));
-  if (!recorder) {
-    return failVoiceSessionAsync(
-      callbacks,
-      new Error(
-        "No voice recorder found. Install arecord, sox, or ffmpeg (or set `voiceInput.recorder`).",
-      ),
-    );
-  }
-
-  if (!isCommandAvailable(recorder.command)) {
-    return failVoiceSessionAsync(
-      callbacks,
-      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();
-
-  function emitClose() {
-    if (closeEmitted) return;
-    closeEmitted = true;
-    callbacks.onClose?.();
-  }
-
-  const wsUrl = hooks.buildWsUrl(config);
-  const wsOptions = hooks.buildWsOptions?.(config);
-
-  // 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)
-  );
-  const ws = new Ctor(wsUrl, wsOptions);
-  ws.binaryType = "arraybuffer";
-
-  const rec = startRecorder({
-    recorder,
-    onAudio(chunk) {
-      if (stopped) return;
-      if (ready && ws.readyState === WebSocket.OPEN) {
-        sendAudio(chunk);
-      } else {
-        pendingAudio.push(chunk);
-      }
-    },
-    onError(err) {
-      if (!stopped) callbacks.onError(err);
-      stop();
-    },
-    onExit() {
-      stop();
-    },
-  });
-
-  /**
-   * @param {Buffer} chunk
-   */
-  function sendAudio(chunk) {
-    const payload = hooks.buildAudioPayload(chunk, hooks.sampleRate);
-    try {
-      ws.send(JSON.stringify(payload));
-    } catch (err) {
-      if (VOICE_DEBUG) {
-        process.stderr.write(
-          `[voiceInput] sendAudio dropped: ${formatError(err)}\n`,
-        );
-      }
-    }
-  }
-
-  ws.addEventListener("open", () => {
-    const setup = hooks.buildSetupMessage(config);
-    try {
-      ws.send(JSON.stringify(setup));
-    } catch (err) {
-      callbacks.onError(
-        new Error(`Failed to send setup message: ${formatError(err)}`),
-      );
-      stop();
-    }
-  });
-
-  ws.addEventListener("message", (event) => {
-    if (stopped) return;
-    let raw = "";
-    let message;
-    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: ${formatError(err)}`),
-      );
-      return;
-    }
-    if (!isObjectLike(message)) return;
-    if (VOICE_DEBUG) {
-      process.stderr.write(`[voiceInput] <- ${raw.slice(0, 800)}\n`);
-    }
-
-    const errorText = hooks.extractError?.(message);
-    if (errorText) {
-      callbacks.onError(new Error(`${hooks.label} error: ${errorText}`));
-      return;
-    }
-
-    if (!ready && hooks.isReadyMessage(message)) {
-      ready = true;
-      for (const chunk of pendingAudio.splice(0)) {
-        if (ws.readyState === WebSocket.OPEN) sendAudio(chunk);
-      }
-      return;
-    }
-
-    const transcript = hooks.extractTranscript(message);
-    if (transcript && transcript.length > 0) {
-      const normalized = normalizer.push(transcript);
-      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(`${hooks.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(
-          `${hooks.label} WebSocket closed (code ${event.code}${reason})`,
-        ),
-      );
-    }
-    stopped = true;
-    rec.stop();
-    emitClose();
-  });
-
-  if (VOICE_DEBUG) {
-    process.stderr.write(
-      `[voiceInput] driver=${hooks.label} recorder=${recorder.command} ${recorder.args.join(" ")}\n`,
-    );
-  }
-
-  /**
-   * Stops the recorder and closes the WebSocket.
-   *
-   * **Note on asynchronicity:** This function is `async` only to satisfy the
-   * {@link VoiceSession} interface. It is called without `await` from event
-   * listeners (recorder exit, WebSocket error/close). Callers must not rely
-   * on the returned promise because unhandled rejections would crash the
-   * process. If the function is ever changed to perform real async work,
-   * every call site must wrap it with `.catch(() => {})`.
-   */
-  async function stop() {
-    if (stopped) return;
-    stopped = true;
-    rec.stop();
-    pendingAudio.length = 0;
-    if (
-      ws.readyState === WebSocket.OPEN ||
-      ws.readyState === WebSocket.CONNECTING
-    ) {
-      try {
-        ws.close(1000, "client stop");
-      } catch (err) {
-        if (VOICE_DEBUG) {
-          process.stderr.write(
-            `[voiceInput] ws.close failed: ${formatError(err)}\n`,
-          );
-        }
-      }
-    }
-    emitClose();
-  }
-
-  return { stop };
-}
-
-/**
- * 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 = "";
-
-  /**
-   * @param {string} c
-   * @returns {boolean}
-   */
-  function isSpace(c) {
-    return 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>}
- */
-export function isObjectLike(value) {
-  return typeof value === "object" && value !== null;
-}
-
-/**
- * @param {unknown} err
- * @returns {string}
- */
-function formatError(err) {
-  return err instanceof Error ? err.message : String(err);
-}

package/src/voice/toggleKey.mjs

@@ -1,62 +0,0 @@
-/**
- * @typedef {Object} VoiceToggleKey
- * @property {number} byte
- * @property {string} label
- */
-
-// 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,
-]);
-
-/**
- * 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()}` };
-}