@iinm/plain-agent 1.7.19 → 1.7.21

package/src/cliCost.mjs

@@ -3,7 +3,7 @@
  */
 
 import { styleText } from "node:util";
-import { readUsageRecords } from "./usageStore.mjs";
+import * as usageStore from "./usageStore.mjs";
 
 /**
  * @typedef {Object} CostPeriod
@@ -72,15 +72,15 @@ export function parseDateOnly(value) {
   if (!match) {
     throw new Error(`Invalid date: "${value}" (expected YYYY-MM-DD)`);
   }
-  const [, y, m, d] = match;
-  const year = Number(y);
-  const month = Number(m);
-  const day = Number(d);
-  const date = new Date(year, month - 1, day);
+  const [, year, month, day] = match;
+  const y = Number(year);
+  const m = Number(month);
+  const d = Number(day);
+  const date = new Date(y, m - 1, d);
   if (
-    date.getFullYear() !== year ||
-    date.getMonth() !== month - 1 ||
-    date.getDate() !== day
+    date.getFullYear() !== y ||
+    date.getMonth() !== m - 1 ||
+    date.getDate() !== d
   ) {
     throw new Error(`Invalid date: "${value}"`);
   }
@@ -109,6 +109,10 @@ export function aggregateUsage(records, period) {
   let excludedOutOfRange = 0;
 
   for (const record of records) {
+    if (record.timestamp == null) {
+      excludedOutOfRange++;
+      continue;
+    }
     const recordedAt = new Date(record.timestamp);
     if (Number.isNaN(recordedAt.getTime())) {
       excludedOutOfRange++;
@@ -123,12 +127,13 @@ export function aggregateUsage(records, period) {
       noPricingSessionCount++;
       continue;
     }
-
-    let perDate = byCurrency.get(record.currency);
-    if (!perDate) {
-      perDate = new Map();
-      byCurrency.set(record.currency, perDate);
+    if (!record.currency || typeof record.currency !== "string") {
+      excludedOutOfRange++;
+      continue;
     }
+
+    const perDate = byCurrency.get(record.currency) ?? new Map();
+    byCurrency.set(record.currency, perDate);
     const existing = perDate.get(localDate);
     if (existing) {
       existing.totalCost += record.totalCost;
@@ -146,13 +151,14 @@ export function aggregateUsage(records, period) {
   const aggregations = [];
   for (const [currency, perDate] of byCurrency) {
     const daily = Array.from(perDate.values()).sort((a, b) =>
-      a.date < b.date ? -1 : a.date > b.date ? 1 : 0,
-    );
-    const totalCost = daily.reduce((sum, entry) => sum + entry.totalCost, 0);
-    const sessionCount = daily.reduce(
-      (sum, entry) => sum + entry.sessionCount,
-      0,
+      a.date.localeCompare(b.date),
     );
+    let totalCost = 0;
+    let sessionCount = 0;
+    for (const entry of daily) {
+      totalCost += entry.totalCost;
+      sessionCount += entry.sessionCount;
+    }
     aggregations.push({ currency, daily, totalCost, sessionCount });
   }
   aggregations.sort((a, b) => a.currency.localeCompare(b.currency));
@@ -166,6 +172,14 @@ export function aggregateUsage(records, period) {
   };
 }
 
+/**
+ * @param {number} count
+ * @returns {string}
+ */
+function formatSessions(count) {
+  return `${count} session${count === 1 ? "" : "s"}`;
+}
+
 /**
  * Render a cost report as a human-readable string.
  *
@@ -175,10 +189,9 @@ export function aggregateUsage(records, period) {
  */
 export function formatCostReport(report, options = {}) {
   const color = options.color ?? true;
-  const style = color
-    ? styleText
-    : /** @param {any} _modifiers @param {string} text */ (_modifiers, text) =>
-        text;
+  /** @param {string | string[]} _modifiers @param {string} text @returns {string} */
+  const plainStyle = (_modifiers, text) => text;
+  const style = color ? styleText : plainStyle;
 
   const lines = [];
   lines.push(
@@ -204,14 +217,14 @@ export function formatCostReport(report, options = {}) {
     lines.push(style("bold", `Daily cost (${agg.currency}):`));
     for (const entry of agg.daily) {
       lines.push(
-        `  ${entry.date}   ${formatCost(entry.totalCost)} ${agg.currency}   (${entry.sessionCount} session${entry.sessionCount === 1 ? "" : "s"})`,
+        `  ${entry.date}   ${formatCost(entry.totalCost)} ${agg.currency}   (${formatSessions(entry.sessionCount)})`,
       );
     }
     lines.push("");
     lines.push(
       style(
         "bold",
-        `Total: ${formatCost(agg.totalCost)} ${agg.currency} (${agg.sessionCount} session${agg.sessionCount === 1 ? "" : "s"})`,
+        `Total: ${formatCost(agg.totalCost)} ${agg.currency} (${formatSessions(agg.sessionCount)})`,
       ),
     );
   }
@@ -242,28 +255,50 @@ function formatCost(value) {
  * Run the `plain cost` subcommand.
  *
  * @param {{ from: string | null, to: string | null }} args
+ * @param {{ readUsageRecords?: typeof import("./usageStore.mjs").readUsageRecords }} [deps]
  * @returns {Promise<number>} exit code
  */
-export async function runCostCommand(args) {
-  const { from, to } = resolvePeriod(args);
+export async function runCostCommand(args, deps = {}) {
+  let from;
+  let to;
+  try {
+    ({ from, to } = resolvePeriod(args));
+  } catch (err) {
+    if (err instanceof Error) {
+      console.error(`Error: ${err.message}`);
+    } else {
+      console.error("Error: invalid period arguments");
+    }
+    return 1;
+  }
 
-  const { records, skipped } = await readUsageRecords();
+  const { records, skipped } = await (
+    deps.readUsageRecords ?? usageStore.readUsageRecords
+  )();
   if (skipped.length > 0) {
+    const details = skipped
+      .slice(0, 3)
+      .map((s) => `line ${s.line}: ${s.reason}`)
+      .join(", ");
+    const ellipsis =
+      skipped.length > 3 ? `, and ${skipped.length - 3} more` : "";
     console.error(
-      `Warning: skipped ${skipped.length} malformed line(s) in usage log.`,
+      `Warning: skipped ${skipped.length} malformed line(s) in usage log (${details}${ellipsis}).`,
     );
   }
 
   const report = aggregateUsage(records, { from, to });
   console.log(formatCostReport(report));
-  return 0;
+  return skipped.length > 0 ? 1 : 0;
 }
 
 /**
+ * Resolve a period from CLI arguments, falling back to the current month.
+ *
  * @param {{ from: string | null, to: string | null }} args
  * @returns {CostPeriod}
  */
-function resolvePeriod(args) {
+export function resolvePeriod(args) {
   const fallback = defaultPeriod();
   const from = args.from ?? fallback.from;
   const to = args.to ?? fallback.to;

package/src/cliFormatter.mjs

@@ -91,7 +91,7 @@ export function formatToolUse(toolUse) {
     const diffs = [];
     const matches = Array.from(
       diff.matchAll(
-        /<<<<<<< SEARCH [0-9a-z]{3}\n(.*?)\n======= [0-9a-z]{3}\n(.*?)\n?>>>>>>> REPLACE [0-9a-z]{3}/gs,
+        /<<< [0-9a-z]{3} <<< SEARCH\n(.*?)\n=== [0-9a-z]{3} ===\n(.*?)\n?>>> [0-9a-z]{3} >>> REPLACE/gs,
       ),
     );
     for (const match of matches) {

package/src/cliInteractive.mjs

@@ -57,7 +57,7 @@ const HELP_MESSAGE = [
  * @property {AgentCommands} agentCommands
  * @property {string} sessionId
  * @property {string} modelName
- * @property {string} notifyCmd
+ * @property {{ command: string; args?: string[] } | undefined} notifyCmd
  * @property {boolean} sandbox
  * @property {() => Promise<void>} onStop
  * @property {ClaudeCodePlugin[]} [claudeCodePlugins]

package/src/config.d.ts

@@ -21,14 +21,14 @@ export type AppConfig = {
     askURL?: AskURLToolOptions;
   };
   mcpServers?: Record<string, MCPServerConfig>;
-  notifyCmd?: string;
+  notifyCmd?: { command: string; args?: string[] };
   voiceInput?: VoiceInputConfig;
   claudeCodePlugins?: ClaudeCodePluginRepo[];
 };
 
 export type MCPServerConfig = {
   command: string;
-  args: string[];
+  args?: string[];
   env?: Record<string, string>;
   options?: {
     enabledTools?: string[];

package/src/config.mjs

@@ -93,7 +93,7 @@ export async function loadAppConfig(options = {}) {
         ...(merged.mcpServers ?? {}),
         ...(config.mcpServers ?? {}),
       },
-      notifyCmd: config.notifyCmd || merged.notifyCmd,
+      notifyCmd: config.notifyCmd ?? merged.notifyCmd,
       claudeCodePlugins: [
         ...(merged.claudeCodePlugins ?? []),
         ...(config.claudeCodePlugins ?? []),

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: {