@iinm/plain-agent 1.8.4 → 1.8.6

package/src/tools/writeFile.mjs

@@ -0,0 +1,56 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { WriteFileInput } from './writeFile'
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { noThrow } from "../utils/noThrow.mjs";
+
+/** @type {Tool} */
+export const writeFileTool = {
+  def: {
+    name: "write_file",
+    description: "Write a file",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: {
+          type: "string",
+        },
+        content: {
+          type: "string",
+        },
+      },
+      required: ["filePath", "content"],
+    },
+  },
+
+  /**
+   * @param {WriteFileInput} input
+   * @returns {Promise<string | Error>}
+   */
+  impl: async (input) =>
+    await noThrow(async () => {
+      const { filePath, content } = input;
+
+      const absFilePath = path.resolve(filePath);
+
+      // Ensure the destination directory exists before writing
+      const dir = path.dirname(absFilePath);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(absFilePath, content, "utf8");
+      return `Wrote to file: ${filePath}`;
+    }),
+
+  /**
+   * @param {Record<string, unknown>} input
+   * @returns {Record<string, unknown>}
+   */
+  maskApprovalInput: (input) => {
+    const writeFileInput = /** @type {WriteFileInput} */ (input);
+    return {
+      filePath: writeFileInput.filePath,
+    };
+  },
+};

package/src/usageStore.mjs

@@ -0,0 +1,167 @@
+/**
+ * @import { CostSummary } from "./costTracker.mjs"
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { USAGE_LOG_PATH } from "./env.mjs";
+
+/**
+ * @typedef {Object} UsageRecord
+ * @property {string} timestamp - ISO 8601 timestamp
+ * @property {string} sessionId
+ * @property {"interactive" | "batch"} mode
+ * @property {string} modelName - e.g. "claude-sonnet-4-6+thinking-high"
+ * @property {string} workingDir
+ * @property {string} currency - e.g. "USD"
+ * @property {string} unit - e.g. "1M"
+ * @property {number | null} totalCost - null when no pricing configured
+ * @property {Record<string, number>} tokens - aggregated token counts by path
+ */
+
+/**
+ * Maximum size (in bytes) of a single JSONL line.
+ * Linux guarantees atomicity of O_APPEND writes up to PIPE_BUF (4096 bytes),
+ * so we enforce a smaller limit to stay safely under that threshold even
+ * with multi-byte UTF-8 characters in model/session names.
+ */
+const MAX_RECORD_BYTES = 3072;
+
+/**
+ * Append a usage record to the persistent usage log.
+ *
+ * On POSIX systems, `fs.appendFile` opens the file with `O_APPEND`, which
+ * guarantees that each write lands at end-of-file and is atomic when the
+ * payload is <= PIPE_BUF (4096 bytes on Linux). We write the record as a
+ * single call to preserve this guarantee even if multiple plain-agent
+ * sessions finish simultaneously.
+ *
+ * @param {UsageRecord} record
+ * @param {{ path?: string }} [options]
+ * @returns {Promise<void>}
+ */
+export async function appendUsageRecord(record, options = {}) {
+  const filePath = options.path ?? USAGE_LOG_PATH;
+  const line = `${JSON.stringify(record)}\n`;
+  const bytes = Buffer.byteLength(line, "utf8");
+  if (bytes > MAX_RECORD_BYTES) {
+    throw new Error(
+      `Usage record exceeds ${MAX_RECORD_BYTES} bytes (${bytes}); refusing to write to keep appends atomic.`,
+    );
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.appendFile(filePath, line, { encoding: "utf8" });
+}
+
+/**
+ * Read all usage records from the log file.
+ * Malformed lines are skipped and collected in `skipped`.
+ *
+ * @param {{ path?: string }} [options]
+ * @returns {Promise<{ records: UsageRecord[], skipped: { line: number, reason: string }[] }>}
+ */
+export async function readUsageRecords(options = {}) {
+  const filePath = options.path ?? USAGE_LOG_PATH;
+  /** @type {string} */
+  let content;
+  try {
+    content = await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+    ) {
+      return { records: [], skipped: [] };
+    }
+    throw err;
+  }
+
+  /** @type {UsageRecord[]} */
+  const records = [];
+  /** @type {{ line: number, reason: string }[]} */
+  const skipped = [];
+
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (raw.length === 0) continue;
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isUsageRecord(parsed)) {
+        skipped.push({ line: i + 1, reason: "invalid shape" });
+        continue;
+      }
+      records.push(parsed);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      skipped.push({ line: i + 1, reason });
+    }
+  }
+
+  return { records, skipped };
+}
+
+/**
+ * Build a usage record from a finished session's cost summary.
+ * Returns null when there's nothing worth recording (no tokens).
+ *
+ * @param {Object} args
+ * @param {string} args.sessionId
+ * @param {"interactive" | "batch"} args.mode
+ * @param {string} args.modelName
+ * @param {string} args.workingDir
+ * @param {CostSummary} args.costSummary
+ * @param {Date} [args.now]
+ * @returns {UsageRecord | null}
+ */
+export function buildUsageRecord({
+  sessionId,
+  mode,
+  modelName,
+  workingDir,
+  costSummary,
+  now,
+}) {
+  /** @type {Record<string, number>} */
+  const tokens = {};
+  for (const [key, entry] of Object.entries(costSummary.breakdown)) {
+    tokens[key] = entry.tokens;
+  }
+  if (Object.keys(tokens).length === 0) {
+    return null;
+  }
+  const timestamp = (now ?? new Date()).toISOString();
+  return {
+    timestamp,
+    sessionId,
+    mode,
+    modelName,
+    workingDir,
+    currency: costSummary.currency,
+    unit: costSummary.unit,
+    totalCost:
+      costSummary.totalCost === undefined ? null : costSummary.totalCost,
+    tokens,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is UsageRecord}
+ */
+function isUsageRecord(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const r = /** @type {Record<string, unknown>} */ (value);
+  return (
+    typeof r.timestamp === "string" &&
+    typeof r.sessionId === "string" &&
+    (r.mode === "interactive" || r.mode === "batch") &&
+    typeof r.modelName === "string" &&
+    typeof r.workingDir === "string" &&
+    typeof r.currency === "string" &&
+    typeof r.unit === "string" &&
+    (r.totalCost === null || typeof r.totalCost === "number") &&
+    typeof r.tokens === "object" &&
+    r.tokens !== null
+  );
+}

package/src/utils/evalJSONConfig.mjs

@@ -0,0 +1,72 @@
+/**
+ * @param {unknown} configItem
+ * @returns {unknown}
+ */
+export function evalJSONConfig(configItem) {
+  if (Array.isArray(configItem)) {
+    return configItem.map((item) => evalJSONConfig(item));
+  }
+
+  if (typeof configItem === "object" && configItem !== null) {
+    if (
+      Object.keys(configItem).length === 1 &&
+      "$regex" in configItem &&
+      typeof configItem.$regex === "string"
+    ) {
+      return new RegExp(configItem.$regex);
+    }
+
+    if (
+      Object.keys(configItem).length === 1 &&
+      "$env" in configItem &&
+      typeof configItem.$env === "string"
+    ) {
+      const value = process.env[configItem.$env];
+      if (value === undefined) {
+        throw new Error(
+          `Environment variable '${configItem.$env}' is not defined`,
+        );
+      }
+      return value;
+    }
+
+    if (
+      Object.keys(configItem).length === 1 &&
+      "$env" in configItem &&
+      typeof configItem.$env !== "string"
+    ) {
+      throw new Error(
+        `The value of '$env' must be a string, got: ${typeof configItem.$env}`,
+      );
+    }
+
+    if (Object.keys(configItem).length === 1 && "$has" in configItem) {
+      const pattern = evalJSONConfig(configItem.$has);
+      /** @param {unknown} value */
+      return (value) => {
+        if (!Array.isArray(value)) return false;
+        return value.some((item) => {
+          if (typeof pattern === "string") {
+            return item === pattern;
+          }
+          if (pattern instanceof RegExp) {
+            return typeof item === "string" && pattern.test(item);
+          }
+          if (typeof pattern === "function") {
+            return pattern(item);
+          }
+          return false;
+        });
+      };
+    }
+
+    /** @type {Record<string,unknown>} */
+    const clone = {};
+    for (const [k, v] of Object.entries(configItem)) {
+      clone[k] = evalJSONConfig(v);
+    }
+    return clone;
+  }
+
+  return configItem;
+}

package/src/utils/matchValue.d.ts

@@ -0,0 +1,6 @@
+export type ValuePattern =
+  | string
+  | RegExp
+  | ((value: unknown) => boolean)
+  | ValuePattern[]
+  | { [key: string]: ValuePattern };

package/src/utils/matchValue.mjs

@@ -0,0 +1,40 @@
+/**
+ * @import { ValuePattern } from "./matchValue"
+ */
+
+/**
+ * @param {unknown} value
+ * @param {ValuePattern} pattern
+ * @returns {boolean}
+ */
+export function matchValue(value, pattern) {
+  if (typeof pattern === "string") {
+    return typeof value === "string" && value === pattern;
+  }
+
+  if (pattern instanceof RegExp) {
+    return typeof value === "string" && pattern.test(value);
+  }
+
+  if (typeof pattern === "function") {
+    return pattern(value);
+  }
+
+  if (Array.isArray(pattern)) {
+    return (
+      Array.isArray(value) && pattern.every((p, i) => matchValue(value[i], p))
+    );
+  }
+
+  if (typeof pattern === "object") {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      Object.entries(pattern).every(([k, p]) =>
+        matchValue(value[/** @type {keyof value} */ (k)], p),
+      )
+    );
+  }
+
+  return false;
+}

package/src/utils/noThrow.mjs

@@ -0,0 +1,31 @@
+/**
+ * @template T
+ * @param {() => Promise<T>} task
+ * @returns {Promise<T | Error>}
+ */
+export async function noThrow(task) {
+  try {
+    return await task();
+  } catch (error) {
+    if (error instanceof Error) {
+      return error;
+    }
+    return new Error(`Non-Error thrown: ${error}`);
+  }
+}
+
+/**
+ * @template T
+ * @param {() => T} task
+ * @returns {T | Error}
+ */
+export function noThrowSync(task) {
+  try {
+    return task();
+  } catch (error) {
+    if (error instanceof Error) {
+      return error;
+    }
+    return new Error(`Non-Error thrown: ${error}`);
+  }
+}

package/src/utils/notify.mjs

@@ -0,0 +1,29 @@
+import { execFileSync } from "node:child_process";
+import { noThrowSync } from "./noThrow.mjs";
+
+/**
+ * @param {{ command: string; args?: string[] } | undefined} notifyCmd
+ * @returns {void | Error}
+ */
+export function notify(notifyCmd) {
+  if (!notifyCmd) {
+    process.stdout.write("\x07");
+    return;
+  }
+
+  return noThrowSync(() => {
+    execFileSync(notifyCmd.command, notifyCmd.args ?? [], {
+      shell: false,
+      stdio: ["ignore", "inherit", "pipe"],
+      env: {
+        PWD: process.env.PWD,
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        // for Linux
+        DISPLAY: process.env.DISPLAY,
+        DBUS_SESSION_BUS_ADDRESS: process.env.DBUS_SESSION_BUS_ADDRESS,
+      },
+      timeout: 10 * 1000,
+    });
+  });
+}

package/src/utils/parseFileRange.mjs

@@ -0,0 +1,18 @@
+/**
+ * @param {string} fileRange
+ * @returns {{filePath: string, startLine?: number, endLine?: number} | Error}
+ */
+export function parseFileRange(fileRange) {
+  const match = fileRange.match(/^([^:]+)(?::(\d+)(?:-(\d+))?)?$/);
+  if (!match) {
+    return new Error(
+      "Invalid format. Use: path/to/file[:line] or path/to/file[:start-end]",
+    );
+  }
+  const [, filePath, startLine, endLine] = match;
+  return {
+    filePath,
+    startLine: startLine ? Number.parseInt(startLine, 10) : undefined,
+    endLine: endLine ? Number.parseInt(endLine, 10) : undefined,
+  };
+}

package/src/utils/parseFrontmatter.mjs

@@ -0,0 +1,19 @@
+/**
+ * Parse simple key-value frontmatter using regex.
+ * Only supports `key: value` format. No multiline strings.
+ * @param {string} frontmatter - The YAML frontmatter content (without --- delimiters)
+ * @returns {Record<string, string>} Parsed key-value pairs
+ */
+export function parseFrontmatter(frontmatter) {
+  /** @type {Record<string, string>} */
+  const result = {};
+
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const match = line.match(/^(\w[\w-]*):\s?(.*)$/);
+    if (match) {
+      result[match[1]] = match[2].trimEnd();
+    }
+  }
+
+  return result;
+}

package/src/utils/readFileRange.mjs

@@ -0,0 +1,33 @@
+import fs from "node:fs/promises";
+
+/**
+ * @param {{filePath: string, startLine?: number, endLine?: number}} fileRange
+ * @returns {Promise<string | Error>}
+ */
+export async function readFileRange({ filePath, startLine, endLine }) {
+  /** @type {string} */
+  let fileContent;
+  try {
+    fileContent = await fs.readFile(filePath, { encoding: "utf-8" });
+  } catch (error) {
+    return new Error(
+      `Error reading file: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const lines = fileContent.split("\n");
+
+  if (startLine) {
+    const start = startLine;
+    const end = endLine ? endLine : start;
+
+    if (!(1 <= start && start <= end && end <= lines.length)) {
+      return new Error(
+        `Invalid line range. File ${filePath} has ${lines.length} lines.`,
+      );
+    }
+
+    return lines.slice(start - 1, end).join("\n");
+  }
+  return fileContent;
+}

package/src/utils/retryOnError.mjs

@@ -0,0 +1,41 @@
+/**
+ * @typedef {Object} RetryOnErrorConfig
+ * @property {(err: unknown) => boolean} shouldRetry
+ * @property {(err: unknown, interval: number) => Promise<void>} [beforeRetry]
+ * @property {number} initialInterval
+ * @property {number} maxInterval
+ * @property {number} multiplier
+ * @property {number} maxAttempt
+ */
+
+/**
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {RetryOnErrorConfig} config
+ * @returns {Promise<T>}
+ */
+export async function retryOnError(fn, config) {
+  let attempt = 0;
+
+  while (true) {
+    try {
+      attempt++;
+      return await fn();
+    } catch (err) {
+      if (attempt >= config.maxAttempt || !config.shouldRetry(err)) {
+        throw err;
+      }
+
+      const interval = Math.min(
+        config.initialInterval * config.multiplier ** (attempt - 1),
+        config.maxInterval,
+      );
+
+      if (config.beforeRetry) {
+        await config.beforeRetry(err, interval);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+}

package/src/voiceInput.mjs

@@ -0,0 +1,61 @@
+import { startGeminiVoiceSession } from "./voiceInputGemini.mjs";
+import { startOpenAIVoiceSession } from "./voiceInputOpenAI.mjs";
+import { failVoiceSessionAsync } from "./voiceInputSession.mjs";
+
+export {
+  createCJKSpaceNormalizer,
+  detectRecorder,
+  getRecorderCandidates,
+} from "./voiceInputSession.mjs";
+export { parseVoiceToggleKey } from "./voiceToggleKey.mjs";
+
+/**
+ * @typedef {import("./voiceInputSession.mjs").VoiceRecorderConfig} VoiceRecorderConfig
+ */
+
+/**
+ * @typedef {import("./voiceInputSession.mjs").VoiceSessionCallbacks} VoiceSessionCallbacks
+ */
+
+/**
+ * @typedef {import("./voiceInputSession.mjs").VoiceSession} VoiceSession
+ */
+
+/**
+ * @typedef {import("./voiceToggleKey.mjs").VoiceToggleKey} VoiceToggleKey
+ */
+
+/**
+ * @typedef {import("./voiceInputOpenAI.mjs").VoiceInputOpenAIConfig} VoiceInputOpenAIConfig
+ */
+
+/**
+ * @typedef {import("./voiceInputGemini.mjs").VoiceInputGeminiConfig} VoiceInputGeminiConfig
+ */
+
+/**
+ * @typedef {VoiceInputOpenAIConfig | 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 {VoiceSessionCallbacks} options.callbacks
+ * @returns {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/voiceInputGemini.mjs

@@ -0,0 +1,105 @@
+import {
+  isObjectLike,
+  startWebSocketVoiceSession,
+} from "./voiceInputSession.mjs";
+
+/**
+ * @import { VoiceProviderHooks, VoiceRecorderConfig, VoiceSession, VoiceSessionCallbacks } from "./voiceInputSession.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 });
+}