@iinm/plain-agent 1.7.18 → 1.7.19

package/README.md

@@ -307,6 +307,17 @@ Display the help message.
 /help
 ```
 
+Show aggregated token cost per day across sessions.
+Each finished session appends a record to `~/.local/share/plain-agent/usage.jsonl`,
+and `plain cost` reads that log. The period defaults to the first day of the
+current month through today; override it with `--from` / `--to`. Multiple
+currencies (e.g., USD and JPY) are aggregated separately.
+
+```sh
+plain cost
+plain cost --from 2026-04-01 --to 2026-04-30
+```
+
 Interrupt the agent while it's running:
 
 Press **Ctrl-C** to pause auto-approve. The agent will finish the current tool call, then return to the prompt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.18",
+  "version": "1.7.19",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",

package/src/cliArgs.mjs

@@ -1,5 +1,5 @@
 /**
- * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand} Subcommand
+ * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand} Subcommand
  */
 
 /**
@@ -22,6 +22,10 @@
  * @typedef {{ type: 'install-claude-code-plugins' }} InstallClaudeCodePluginsSubcommand
  */
 
+/**
+ * @typedef {{ type: 'cost', from: string | null, to: string | null }} CostSubcommand
+ */
+
 /**
  * @typedef {Object} CliArgs
  * @property {Subcommand} subcommand - The subcommand to execute
@@ -106,6 +110,28 @@ export function parseCliArgs(argv) {
     };
   }
 
+  if (subcommandName === "cost") {
+    const costArgs = args.slice(1);
+    let from = null;
+    let to = null;
+    for (let i = 0; i < costArgs.length; i++) {
+      if (costArgs[i] === "--from") {
+        if (costArgs[i + 1]) {
+          from = costArgs[i + 1];
+          i++;
+        }
+      } else if (costArgs[i] === "--to") {
+        if (costArgs[i + 1]) {
+          to = costArgs[i + 1];
+          i++;
+        }
+      }
+    }
+    return {
+      subcommand: { type: "cost", from, to },
+    };
+  }
+
   return {
     subcommand: { type: "help" },
   };
@@ -119,6 +145,7 @@ export function printHelp(exitCode = 0) {
   console.log(`
 Usage: plain [options]
        plain batch [options] <task>
+       plain cost [--from YYYY-MM-DD] [--to YYYY-MM-DD]
        plain list-models
        plain install-claude-code-plugins
 
@@ -131,6 +158,9 @@ Subcommands:
   batch <task>                 Run in batch mode with the given task instruction.
                                Config files are NOT auto-loaded in batch mode;
                                use -c to specify config files explicitly.
+  cost                         Show aggregated token cost per day for a period.
+                               Defaults to the first day of the current month
+                               through today.
   list-models                  List available models
   install-claude-code-plugins  Install Claude Code plugins
 

package/src/cliBatch.mjs

@@ -3,6 +3,7 @@
  */
 
 import { formatCostForBatch } from "./cliFormatter.mjs";
+import { appendUsageRecord, buildUsageRecord } from "./usageStore.mjs";
 
 /**
  * @typedef {object} BatchSessionOptions
@@ -46,6 +47,27 @@ export async function startBatchSession({
         timestamp: new Date().toISOString(),
         cost: formatCostForBatch(costSummary),
       });
+
+      try {
+        const record = buildUsageRecord({
+          sessionId,
+          mode: "batch",
+          modelName,
+          workingDir: process.cwd(),
+          costSummary,
+        });
+        if (record) {
+          await appendUsageRecord(record);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        outputEvent({
+          type: "error",
+          error: { message: `failed to record usage: ${message}` },
+          timestamp: new Date().toISOString(),
+        });
+      }
+
       await onStop();
       resolve();
     });

package/src/cliCost.mjs

@@ -0,0 +1,274 @@
+/**
+ * @import { UsageRecord } from "./usageStore.mjs"
+ */
+
+import { styleText } from "node:util";
+import { readUsageRecords } 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 [, y, m, d] = match;
+  const year = Number(y);
+  const month = Number(m);
+  const day = Number(d);
+  const date = new Date(year, month - 1, day);
+  if (
+    date.getFullYear() !== year ||
+    date.getMonth() !== month - 1 ||
+    date.getDate() !== day
+  ) {
+    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) {
+    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;
+    }
+
+    let perDate = byCurrency.get(record.currency);
+    if (!perDate) {
+      perDate = 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 < 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,
+    );
+    aggregations.push({ currency, daily, totalCost, sessionCount });
+  }
+  aggregations.sort((a, b) => a.currency.localeCompare(b.currency));
+
+  return {
+    period,
+    byCurrency: aggregations,
+    noPricingSessionCount,
+    excludedOutOfRange,
+    totalRecords: records.length,
+  };
+}
+
+/**
+ * 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;
+  const style = color
+    ? styleText
+    : /** @param {any} _modifiers @param {string} text */ (_modifiers, text) =>
+        text;
+
+  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}   (${entry.sessionCount} session${entry.sessionCount === 1 ? "" : "s"})`,
+      );
+    }
+    lines.push("");
+    lines.push(
+      style(
+        "bold",
+        `Total: ${formatCost(agg.totalCost)} ${agg.currency} (${agg.sessionCount} session${agg.sessionCount === 1 ? "" : "s"})`,
+      ),
+    );
+  }
+
+  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
+ * @returns {Promise<number>} exit code
+ */
+export async function runCostCommand(args) {
+  const { from, to } = resolvePeriod(args);
+
+  const { records, skipped } = await readUsageRecords();
+  if (skipped.length > 0) {
+    console.error(
+      `Warning: skipped ${skipped.length} malformed line(s) in usage log.`,
+    );
+  }
+
+  const report = aggregateUsage(records, { from, to });
+  console.log(formatCostReport(report));
+  return 0;
+}
+
+/**
+ * @param {{ from: string | null, to: string | null }} args
+ * @returns {CostPeriod}
+ */
+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/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";
 
@@ -63,6 +64,32 @@ const HELP_MESSAGE = [
  * @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/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",

package/src/main.mjs

@@ -10,6 +10,7 @@ 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";
@@ -58,6 +59,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 = [

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
+  );
+}