@iinm/plain-agent 1.7.18 → 1.7.20

package/src/cliCost.mjs

@@ -0,0 +1,309 @@
+/**
+ * @import { UsageRecord } from "./usageStore.mjs"
+ */
+
+import { styleText } from "node:util";
+import * as usageStore from "./usageStore.mjs";
+
+/**
+ * @typedef {Object} CostPeriod
+ * @property {string} from - YYYY-MM-DD (inclusive, local date)
+ * @property {string} to - YYYY-MM-DD (inclusive, local date)
+ */
+
+/**
+ * @typedef {Object} DailyEntry
+ * @property {string} date - YYYY-MM-DD
+ * @property {number} totalCost
+ * @property {number} sessionCount
+ */
+
+/**
+ * @typedef {Object} CurrencyAggregation
+ * @property {string} currency
+ * @property {DailyEntry[]} daily - sorted by date ascending
+ * @property {number} totalCost
+ * @property {number} sessionCount
+ */
+
+/**
+ * @typedef {Object} CostReport
+ * @property {CostPeriod} period
+ * @property {CurrencyAggregation[]} byCurrency - sorted by currency
+ * @property {number} noPricingSessionCount - sessions without cost data
+ * @property {number} excludedOutOfRange - records dropped (out of period)
+ * @property {number} totalRecords - records considered (before filtering)
+ */
+
+/**
+ * Compute the default period: first day of current month (local) through today (local).
+ * @param {Date} [now]
+ * @returns {CostPeriod}
+ */
+export function defaultPeriod(now = new Date()) {
+  const y = now.getFullYear();
+  const m = now.getMonth();
+  const firstOfMonth = new Date(y, m, 1);
+  return {
+    from: formatLocalDate(firstOfMonth),
+    to: formatLocalDate(now),
+  };
+}
+
+/**
+ * Format a Date as YYYY-MM-DD in local time.
+ * @param {Date} date
+ * @returns {string}
+ */
+export function formatLocalDate(date) {
+  const y = date.getFullYear();
+  const m = `${date.getMonth() + 1}`.padStart(2, "0");
+  const d = `${date.getDate()}`.padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+/**
+ * Parse and validate a YYYY-MM-DD string, returning a Date at local midnight.
+ * @param {string} value
+ * @returns {Date}
+ */
+export function parseDateOnly(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) {
+    throw new Error(`Invalid date: "${value}" (expected YYYY-MM-DD)`);
+  }
+  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() !== y ||
+    date.getMonth() !== m - 1 ||
+    date.getDate() !== d
+  ) {
+    throw new Error(`Invalid date: "${value}"`);
+  }
+  return date;
+}
+
+/**
+ * Aggregate usage records into a cost report.
+ *
+ * @param {UsageRecord[]} records
+ * @param {CostPeriod} period
+ * @returns {CostReport}
+ */
+export function aggregateUsage(records, period) {
+  const fromDate = parseDateOnly(period.from);
+  const toDate = parseDateOnly(period.to);
+  if (fromDate.getTime() > toDate.getTime()) {
+    throw new Error(
+      `"from" (${period.from}) must be on or before "to" (${period.to}).`,
+    );
+  }
+
+  /** @type {Map<string, Map<string, DailyEntry>>} */
+  const byCurrency = new Map();
+  let noPricingSessionCount = 0;
+  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++;
+      continue;
+    }
+    const localDate = formatLocalDate(recordedAt);
+    if (localDate < period.from || localDate > period.to) {
+      excludedOutOfRange++;
+      continue;
+    }
+    if (record.totalCost === null) {
+      noPricingSessionCount++;
+      continue;
+    }
+    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;
+      existing.sessionCount += 1;
+    } else {
+      perDate.set(localDate, {
+        date: localDate,
+        totalCost: record.totalCost,
+        sessionCount: 1,
+      });
+    }
+  }
+
+  /** @type {CurrencyAggregation[]} */
+  const aggregations = [];
+  for (const [currency, perDate] of byCurrency) {
+    const daily = Array.from(perDate.values()).sort((a, b) =>
+      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));
+
+  return {
+    period,
+    byCurrency: aggregations,
+    noPricingSessionCount,
+    excludedOutOfRange,
+    totalRecords: records.length,
+  };
+}
+
+/**
+ * @param {number} count
+ * @returns {string}
+ */
+function formatSessions(count) {
+  return `${count} session${count === 1 ? "" : "s"}`;
+}
+
+/**
+ * Render a cost report as a human-readable string.
+ *
+ * @param {CostReport} report
+ * @param {{ color?: boolean }} [options]
+ * @returns {string}
+ */
+export function formatCostReport(report, options = {}) {
+  const color = options.color ?? true;
+  /** @param {string | string[]} _modifiers @param {string} text @returns {string} */
+  const plainStyle = (_modifiers, text) => text;
+  const style = color ? styleText : plainStyle;
+
+  const lines = [];
+  lines.push(
+    style("bold", `Period: ${report.period.from} to ${report.period.to}`),
+  );
+
+  if (report.byCurrency.length === 0) {
+    lines.push("");
+    lines.push(style("gray", "No usage recorded in this period."));
+    if (report.noPricingSessionCount > 0) {
+      lines.push(
+        style(
+          "gray",
+          `(${report.noPricingSessionCount} session(s) had no pricing configuration)`,
+        ),
+      );
+    }
+    return lines.join("\n");
+  }
+
+  for (const agg of report.byCurrency) {
+    lines.push("");
+    lines.push(style("bold", `Daily cost (${agg.currency}):`));
+    for (const entry of agg.daily) {
+      lines.push(
+        `  ${entry.date}   ${formatCost(entry.totalCost)} ${agg.currency}   (${formatSessions(entry.sessionCount)})`,
+      );
+    }
+    lines.push("");
+    lines.push(
+      style(
+        "bold",
+        `Total: ${formatCost(agg.totalCost)} ${agg.currency} (${formatSessions(agg.sessionCount)})`,
+      ),
+    );
+  }
+
+  if (report.noPricingSessionCount > 0) {
+    lines.push("");
+    lines.push(
+      style(
+        "gray",
+        `Note: ${report.noPricingSessionCount} session(s) had no pricing configuration and are excluded from totals.`,
+      ),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format a cost value with 4 decimals.
+ * @param {number} value
+ * @returns {string}
+ */
+function formatCost(value) {
+  return value.toFixed(4);
+}
+
+/**
+ * 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, 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 (
+    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 (${details}${ellipsis}).`,
+    );
+  }
+
+  const report = aggregateUsage(records, { from, to });
+  console.log(formatCostReport(report));
+  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}
+ */
+export function resolvePeriod(args) {
+  const fallback = defaultPeriod();
+  const from = args.from ?? fallback.from;
+  const to = args.to ?? fallback.to;
+  // Validate format (throws on invalid input).
+  parseDateOnly(from);
+  parseDateOnly(to);
+  return { from, 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

@@ -16,6 +16,7 @@ import {
 import { createInterruptTransform } from "./cliInterruptTransform.mjs";
 import { createMuteTransform } from "./cliMuteTransform.mjs";
 import { createPasteHandler } from "./cliPasteTransform.mjs";
+import { appendUsageRecord, buildUsageRecord } from "./usageStore.mjs";
 import { notify } from "./utils/notify.mjs";
 import { parseVoiceToggleKey, startVoiceSession } from "./voiceInput.mjs";
 
@@ -56,13 +57,39 @@ 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]
  * @property {VoiceInputConfig} [voiceInput]
  */
 
+/**
+ * Persist the session's cost summary to the usage log.
+ * Failures are logged but never thrown so exit is not blocked.
+ *
+ * @param {import("./costTracker.mjs").CostSummary} summary
+ * @param {{ sessionId: string, modelName: string }} meta
+ */
+async function persistUsage(summary, { sessionId, modelName }) {
+  try {
+    const record = buildUsageRecord({
+      sessionId,
+      mode: "interactive",
+      modelName,
+      workingDir: process.cwd(),
+      costSummary: summary,
+    });
+    if (!record) return;
+    await appendUsageRecord(record);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(
+      styleText("yellow", `Warning: failed to record usage: ${message}`),
+    );
+  }
+}
+
 /**
  * @param {CliOptions} options
  */
@@ -126,6 +153,7 @@ export function startInteractiveSession({
     const summary = agentCommands.getCostSummary();
     console.log();
     console.log(formatCostSummary(summary));
+    await persistUsage(summary, { sessionId, modelName });
     await onStop();
     process.exit(0);
   };

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

@@ -12,6 +12,15 @@ export const AGENT_USER_CONFIG_DIR = path.join(
 );
 export const AGENT_CACHE_DIR = path.join(os.homedir(), ".cache", "plain-agent");
 
+export const AGENT_DATA_DIR = path.join(
+  os.homedir(),
+  ".local",
+  "share",
+  "plain-agent",
+);
+
+export const USAGE_LOG_PATH = path.join(AGENT_DATA_DIR, "usage.jsonl");
+
 export const TRUSTED_CONFIG_HASHES_DIR = path.join(
   AGENT_CACHE_DIR,
   "trusted-config-hashes",
@@ -32,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

@@ -10,15 +10,12 @@ import {
 } from "./claudeCodePlugin.mjs";
 import { parseCliArgs, printHelp } from "./cliArgs.mjs";
 import { startBatchSession } from "./cliBatch.mjs";
+import { runCostCommand } from "./cliCost.mjs";
 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";
@@ -58,6 +55,20 @@ if (cliArgs.subcommand.type === "install-claude-code-plugins") {
   process.exit(0);
 }
 
+if (cliArgs.subcommand.type === "cost") {
+  try {
+    const exitCode = await runCostCommand({
+      from: cliArgs.subcommand.from,
+      to: cliArgs.subcommand.to,
+    });
+    process.exit(exitCode);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exit(1);
+  }
+}
+
 (async () => {
   const startTime = new Date();
   const sessionId = [
@@ -255,7 +266,7 @@ if (cliArgs.subcommand.type === "install-claude-code-plugins") {
   } 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;