@iinm/plain-agent 1.7.19 → 1.7.20

package/src/costTracker.mjs

@@ -31,23 +31,58 @@
  * @property {() => boolean} hasUsage - Check if any usage recorded
  */
 
+/**
+ * Validate a cost configuration object at runtime.
+ * @param {unknown} config
+ */
+function validateCostConfig(config) {
+  if (config === undefined) return;
+  if (typeof config !== "object" || config === null) {
+    throw new TypeError("CostConfig must be an object");
+  }
+  const c = /** @type {Record<string, unknown>} */ (config);
+  if (typeof c.currency !== "string") {
+    throw new TypeError("CostConfig.currency must be a string");
+  }
+  if (typeof c.unit !== "string") {
+    throw new TypeError("CostConfig.unit must be a string");
+  }
+  if (typeof c.costs !== "object" || c.costs === null) {
+    throw new TypeError("CostConfig.costs must be an object");
+  }
+  for (const [key, value] of Object.entries(
+    /** @type {Record<string, unknown>} */ (c.costs),
+  )) {
+    if (typeof value !== "number") {
+      throw new TypeError(
+        `CostConfig.costs["${key}"] must be a number, got ${typeof value}`,
+      );
+    }
+  }
+}
+
 /**
  * Create a cost tracker for session token usage
  * @param {CostConfig} [costConfig] - Optional cost configuration
  * @returns {CostTracker}
  */
 export function createCostTracker(costConfig) {
+  validateCostConfig(costConfig);
+
   /** @type {ProviderTokenUsage[]} */
   const usageHistory = [];
 
   /**
-   * Record token usage from a provider
+   * Record token usage from a provider.
+   * Throws when usage is not a non-null object.
    * @param {ProviderTokenUsage} usage
+   * @throws {TypeError} when usage is null, undefined, or not an object
    */
   function recordUsage(usage) {
-    if (typeof usage === "object" && usage !== null) {
-      usageHistory.push(usage);
+    if (typeof usage !== "object" || usage === null) {
+      throw new TypeError("usage must be a non-null object");
     }
+    usageHistory.push(usage);
   }
 
   /**
@@ -75,12 +110,12 @@ export function createCostTracker(costConfig) {
     return usageHistory.length > 0;
   }
 
-  return {
+  return Object.freeze({
     recordUsage,
     getAggregatedUsage,
     calculateCost,
     hasUsage,
-  };
+  });
 }
 
 /**
@@ -132,40 +167,44 @@ function calculateCostFromConfig(aggregated, config) {
   /** @type {Record<string, TokenBreakdown>} */
   const breakdown = {};
   let totalCost = 0;
-  const hasPricing = config?.costs;
 
   for (const [key, tokens] of Object.entries(aggregated)) {
-    breakdown[key] = { tokens, cost: undefined };
+    breakdown[key] = Object.freeze({ tokens, cost: undefined });
 
-    if (!hasPricing || !config.costs[key]) {
+    if (!config?.costs?.[key]) {
       continue;
     }
 
     const costValue = config.costs[key];
     const unitSize = parseUnit(config.unit);
 
-    if (typeof costValue === "number") {
-      const cost = (tokens * costValue) / unitSize;
-      breakdown[key].cost = cost;
-      totalCost += cost;
+    if (typeof costValue !== "number") {
+      throw new TypeError(
+        `config.costs["${key}"] must be a number, got ${typeof costValue}`,
+      );
     }
+
+    const cost = (tokens * costValue) / unitSize;
+    breakdown[key] = Object.freeze({ tokens, cost });
+    totalCost += cost;
   }
 
-  return {
-    currency: config?.currency || "USD",
-    unit: config?.unit || "1M",
+  return Object.freeze({
+    currency: config?.currency ?? "USD",
+    unit: config?.unit ?? "1M",
     breakdown,
-    totalCost: hasPricing ? totalCost : undefined,
-  };
+    totalCost: config?.costs ? totalCost : undefined,
+  });
 }
 
 /**
- * Parse unit string to number
+ * Parse unit string to number.
  * @param {string} unit
  * @returns {number}
+ * @throws {Error} when the unit is not recognized
  */
 function parseUnit(unit) {
   if (unit === "1M") return 1_000_000;
   if (unit === "1K") return 1_000;
-  return 1;
+  throw new Error(`Unknown cost unit: "${unit}"`);
 }

package/src/env.mjs

@@ -41,10 +41,4 @@ export const MESSAGES_DUMP_FILE_PATH = path.join(
   "messages.json",
 );
 
-export const AGENT_NOTIFY_CMD_DEFAULT = path.join(
-  AGENT_ROOT,
-  "bin",
-  "plain-notify-terminal-bell",
-);
-
 export const USER_NAME = process.env.USER || "unknown";

package/src/main.mjs

@@ -15,11 +15,7 @@ import { startInteractiveSession } from "./cliInteractive.mjs";
 import { loadAppConfig } from "./config.mjs";
 import { loadAgentRoles } from "./context/loadAgentRoles.mjs";
 import { loadPrompts } from "./context/loadPrompts.mjs";
-import {
-  AGENT_NOTIFY_CMD_DEFAULT,
-  AGENT_PROJECT_METADATA_DIR,
-  USER_NAME,
-} from "./env.mjs";
+import { AGENT_PROJECT_METADATA_DIR, USER_NAME } from "./env.mjs";
 import { setupMCPServer } from "./mcp.mjs";
 import { createModelCaller } from "./modelCaller.mjs";
 import { createPrompt } from "./prompt.mjs";
@@ -270,7 +266,7 @@ if (cliArgs.subcommand.type === "cost") {
   } else {
     startInteractiveSession({
       ...sessionOptions,
-      notifyCmd: appConfig.notifyCmd || AGENT_NOTIFY_CMD_DEFAULT,
+      notifyCmd: appConfig.notifyCmd,
       claudeCodePlugins: resolvePluginPaths(appConfig.claudeCodePlugins ?? []),
       voiceInput: appConfig.voiceInput,
     });

package/src/model.d.ts

@@ -10,7 +10,7 @@ export type ModelInput = {
 
 export type ModelOutput = {
   message: Message;
-  providerTokenUsage: ProviderTokenUsage;
+  providerTokenUsage?: ProviderTokenUsage;
 };
 
 export type ProviderTokenUsage = Record<

package/src/tools/patchFile.mjs

@@ -26,22 +26,21 @@ export function createPatchFileTool(
           },
           diff: {
             description: `
-- Content is searched as an exact match including indentation and line breaks.
-- The first match found will be replaced if there are multiple matches.
-- Use multiple SEARCH/REPLACE blocks with session-scoped nonce (${nonce}) to replace multiple contents.
-
 Format:
-<<<<<<< SEARCH ${nonce}
+<<< ${nonce} <<< SEARCH
 old content
-======= ${nonce}
+=== ${nonce} ===
 new content
->>>>>>> REPLACE ${nonce}
+>>> ${nonce} >>> REPLACE
 
-<<<<<<< SEARCH ${nonce}
+<<< ${nonce} <<< SEARCH
 other old content
-======= ${nonce}
+=== ${nonce} ===
 other new content
->>>>>>> REPLACE ${nonce}
+>>> ${nonce} >>> REPLACE
+
+- Content is searched as an exact match including indentation and line breaks.
+- The first match found will be replaced if there are multiple matches.
           `.trim(),
             type: "string",
           },
@@ -62,14 +61,14 @@ other new content
         const matches = Array.from(
           diff.matchAll(
             new RegExp(
-              `<<<<<<< SEARCH ${nonce}\\n(.*?)\\n======= ${nonce}\\n(.*?)\\n?>>>>>>> REPLACE ${nonce}`,
+              `<<< ${nonce} <<< SEARCH\\n(.*?)\\n=== ${nonce} ===\\n(.*?)\\n?>>> ${nonce} >>> REPLACE`,
               "gs",
             ),
           ),
         );
         if (matches.length === 0) {
           throw new Error(
-            `Invalid diff format. All markers must include the nonce, e.g., <<<<<<< SEARCH ${nonce} / ======= ${nonce} / >>>>>>> REPLACE ${nonce}`,
+            `Invalid diff format. Each markers must include the nonce: <<< ${nonce} <<< SEARCH, === ${nonce} ===, >>> ${nonce} >>> REPLACE`,
           );
         }
         let newContent = content;

package/src/utils/notify.mjs

@@ -2,16 +2,17 @@ import { execFileSync } from "node:child_process";
 import { noThrowSync } from "./noThrow.mjs";
 
 /**
- * @param {string=} notifyCmd
+ * @param {{ command: string; args?: string[] } | undefined} notifyCmd
  * @returns {void | Error}
  */
 export function notify(notifyCmd) {
   if (!notifyCmd) {
+    process.stdout.write("\x07");
     return;
   }
 
   return noThrowSync(() => {
-    execFileSync(/** @type {string} */ (notifyCmd), [], {
+    execFileSync(notifyCmd.command, notifyCmd.args ?? [], {
       shell: false,
       stdio: ["ignore", "inherit", "pipe"],
       env: {

package/src/voiceInputGemini.mjs

@@ -1,16 +1,10 @@
 import {
-  createCJKSpaceNormalizer,
-  detectRecorder,
-  failVoiceSessionAsync,
-  getRecorderCandidates,
-  isCommandAvailable,
   isObjectLike,
-  startRecorder,
-  VOICE_DEBUG,
+  startWebSocketVoiceSession,
 } from "./voiceInputSession.mjs";
 
 /**
- * @import { VoiceRecorderConfig, VoiceSession, VoiceSessionCallbacks } from "./voiceInputSession.mjs"
+ * @import { VoiceProviderHooks, VoiceRecorderConfig, VoiceSession, VoiceSessionCallbacks } from "./voiceInputSession.mjs"
  */
 
 /**
@@ -45,213 +39,67 @@ const GEMINI_LABEL = "Gemini Live";
  * @returns {VoiceSession}
  */
 export function startGeminiVoiceSession({ config, callbacks }) {
-  const recorder =
-    config.recorder ??
-    detectRecorder(getRecorderCandidates(GEMINI_SAMPLE_RATE));
-  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.`,
-      ),
-    );
-  }
-
-  const model = config.model ?? GEMINI_DEFAULT_MODEL;
-  const base = config.baseURL ?? GEMINI_DEFAULT_WS;
-
-  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 = new WebSocket(`${base}?key=${encodeURIComponent(config.apiKey)}`);
-  ws.binaryType = "arraybuffer";
-
-  const rec = startRecorder({
-    recorder,
-    onAudio(chunk) {
-      if (stopped) return;
-      if (ready && ws.readyState === WebSocket.OPEN) {
-        sendAudio(chunk);
-      } else {
-        pendingAudio.push(chunk);
+  /** @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 };
     },
-    onError(err) {
-      if (!stopped) callbacks.onError(err);
-      stop();
+    isReadyMessage(message) {
+      return isObjectLike(message) && "setupComplete" in message;
     },
-    onExit() {
-      stop();
+    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;
     },
-  });
-
-  /**
-   * @param {Buffer} chunk
-   */
-  function sendAudio(chunk) {
-    const payload = {
-      realtimeInput: {
-        audio: {
-          data: chunk.toString("base64"),
-          mimeType: `audio/pcm;rate=${GEMINI_SAMPLE_RATE}`,
+    buildAudioPayload(chunk, sampleRate) {
+      return {
+        realtimeInput: {
+          audio: {
+            data: chunk.toString("base64"),
+            mimeType: `audio/pcm;rate=${sampleRate}`,
+          },
         },
-      },
-    };
-    try {
-      ws.send(JSON.stringify(payload));
-    } catch {
-      // connection may have just closed
-    }
-  }
-
-  ws.addEventListener("open", () => {
-    /** @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}.` }],
       };
-    }
-    try {
-      ws.send(JSON.stringify({ setup }));
-    } 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 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: ${err instanceof Error ? err.message : String(err)}`,
-        ),
-      );
-      return;
-    }
-    if (!isObjectLike(message)) return;
-    if (VOICE_DEBUG) {
-      process.stderr.write(`[voiceInput] <- ${raw.slice(0, 800)}\n`);
-    }
-
-    if (!ready && "setupComplete" in message) {
-      ready = true;
-      for (const chunk of pendingAudio.splice(0)) {
-        if (ws.readyState === WebSocket.OPEN) sendAudio(chunk);
-      }
-      return;
-    }
-
-    const serverContent = message.serverContent;
-    if (!isObjectLike(serverContent)) return;
-    const transcription = serverContent.inputTranscription;
-    if (
-      isObjectLike(transcription) &&
-      typeof transcription.text === "string" &&
-      transcription.text.length > 0
-    ) {
-      const normalized = normalizer.push(transcription.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(`${GEMINI_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(
-          `${GEMINI_LABEL} WebSocket closed (code ${event.code}${reason})`,
-        ),
-      );
-    }
-    stopped = true;
-    rec.stop();
-    emitClose();
-  });
-
-  if (VOICE_DEBUG) {
-    process.stderr.write(
-      `[voiceInput] driver=${GEMINI_LABEL} recorder=${recorder.command} ${recorder.args.join(" ")}\n`,
-    );
-  }
-
-  /**
-   * @returns {Promise<void>}
-   */
-  async function stop() {
-    if (stopped) return;
-    stopped = true;
-    rec.stop();
-    if (
-      ws.readyState === WebSocket.OPEN ||
-      ws.readyState === WebSocket.CONNECTING
-    ) {
-      try {
-        ws.close(1000, "client stop");
-      } catch {
-        // ignore
-      }
-    }
-    emitClose();
-  }
+    },
+  };
 
-  return { stop };
+  return startWebSocketVoiceSession({ hooks, config, callbacks });
 }