@iinm/plain-agent 1.7.19 → 1.7.20

package/README.md

@@ -1,10 +1,6 @@
-<p align="center">
-  <img src="https://pub-0bb49aa929f242d49c89ed8c297932b5.r2.dev/plain-agent/plain-agent-logo.png" alt="plain-agent logo" width="320">
-</p>
-
 # Plain Agent
 
-A lightweight CLI-based coding agent with zero framework dependencies.
+A lightweight CLI-based coding agent.
 
 ## Why Plain Agent?
 
@@ -23,6 +19,7 @@ A lightweight CLI-based coding agent with zero framework dependencies.
 
 ## Limitations
 
+- **CLI only** — Plain Agent does not provide a terminal UI.
 - **Sequential subagent execution** — Subagents run one at a time rather than
   in parallel. The trade-off is full visibility: every step is streamed to
   your terminal so you can follow exactly what each subagent is doing.
@@ -31,7 +28,7 @@ A lightweight CLI-based coding agent with zero framework dependencies.
 
 - Node.js 22 or later
 - LLM provider credentials
-- bash / docker for sandboxed execution
+- Bash / Docker for sandboxed execution
 - [ripgrep](https://github.com/burntsushi/ripgrep)
 - [fd](https://github.com/sharkdp/fd)
 
@@ -52,8 +49,8 @@ Create the configuration.
 ```js
 // ~/.config/plain-agent/config.local.json
 {
-  "model": "gpt-5.4+thinking-high",
-  // "model": "claude-sonnet-4-6+thinking-high",
+  "model": "claude-sonnet-4-6+thinking-high",
+  // "model": "gpt-5.5+thinking-high",
 
   // Configure the providers you want to use
   "platforms": [
@@ -83,15 +80,11 @@ Create the configuration.
       "provider": "gemini",
       "apiKey": "<GEMINI_API_KEY>",
       "model": "gemini-3-flash-preview"
-      // Optional
-      // "baseURL": "<proxy_url>"
 
       // Or use Vertex AI (Requires gcloud CLI to get authentication token)
       // "provider": "gemini-vertex-ai",
       // "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project_id>/locations/<location>",
       // "model": "gemini-3-flash-preview"
-      // Optional:
-      // "account": "<service_account_email>"
     },
 
     // askURL: Answers questions based on provided URL content.
@@ -100,15 +93,8 @@ Create the configuration.
       "provider": "gemini",
       "apiKey": "<GEMINI_API_KEY>"
       "model": "gemini-3-flash-preview"
-      // Optional
-      // "baseURL": "<proxy_url>"
 
       // Or use Vertex AI (Requires gcloud CLI to get authentication token)
-      // "provider": "gemini-vertex-ai",
-      // "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project_id>/locations/<location>",
-      // "model": "gemini-3-flash-preview"
-      // Optional:
-      // "account": "<service_account_email>"
     }
   },
 
@@ -166,6 +152,7 @@ Create the configuration.
 ```
 
 ```js
+// OpenAI-compatible provider (Ollama) example with a custom model
 {
   "platforms": [
     {
@@ -279,6 +266,9 @@ plain
 plain -m <model+variant>
 ```
 
+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.
+
 (Optional) Set up a sandbox for your project with the `sandbox-configurator` agent.
 
 ```
@@ -292,7 +282,7 @@ After the agent finishes, run the generated setup script once to build the sandb
 ```
 
 Run in batch mode (non-interactive).
-In batch mode, config files are not loaded automatically. Only the files specified with `--config` are loaded.
+In batch mode, config files are not loaded automatically. Only the files specified with `-c` are loaded.
 
 ```sh
 plain batch \
@@ -307,21 +297,15 @@ 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.
+Show daily token costs across sessions. `plain cost` reads
+`~/.local/share/plain-agent/usage.jsonl`; use `--from` / `--to` to set the
+period. Currencies are shown 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.
-
 ## Available Tools
 
 The agent can use the following tools to assist with tasks:
@@ -338,29 +322,24 @@ The agent can use the following tools to assist with tasks:
 
 ## Configuration
 
+Files are loaded in the following order. Settings in later files override earlier ones.
+
 ```
 ~/.config/plain-agent/
-  \__ config.json        # User configuration
-  \__ config.local.json  # User local configuration (including secrets)
-  \__ prompts/           # Global/User-defined prompts
-  \__ agents/            # Global/User-defined agent roles
+  ├── (1) config.json        # User configuration
+  ├── (2) config.local.json  # User local configuration (including secrets)
+  ├── prompts/               # Global/User-defined prompts
+  └── agents/                # Global/User-defined agent roles
 
 <project-root>
-  \__ .plain-agent/
-        \__ config.json            # Project-specific configuration
-        \__ config.local.json      # Project-specific local configuration (including secrets)
-        \__ memory/                # Task-specific memory files
-        \__ prompts/               # Project-specific prompts
-        \__ agents/                # Project-specific agent roles
+  └── .plain-agent/
+        ├── (3) config.json        # Project-specific configuration
+        ├── (4) config.local.json  # Project-specific local configuration (including secrets)
+        ├── memory/                  # Task-specific memory files
+        ├── prompts/                 # Project-specific prompts
+        └── agents/                  # Project-specific agent roles
 ```
 
-The agent loads configuration files in the following order. Settings in later files will override those in earlier files.
-
-- `~/.config/plain-agent/config.json`
-- `~/.config/plain-agent/config.local.json`
-- `.plain-agent/config.json`
-- `.plain-agent/config.local.json`
-
 ### Example
 
 <details>
@@ -423,19 +402,19 @@ The agent loads configuration files in the following order. Settings in later fi
     "patterns": [
       {
         "toolName": { "$regex": "^(write_file|patch_file)$" },
-        "input": { "filePath": { "$regex": "^(\\./)?\\.plain-agent/memory/.+\\.md$" } },
+        "input": { "filePath": { "$regex": "^\\.plain-agent/memory/.+\\.md$" } },
         "action": "allow"
       },
       {
         "toolName": { "$regex": "^(write_file|patch_file)$" },
-        "input": { "filePath": { "$regex": "^(\\./)?src/" } },
+        "input": { "filePath": { "$regex": "^src/" } },
         "action": "allow"
       },
 
       // ⚠️ Arbitrary code execution can access unauthorized files and networks. Always use a sandbox.
       {
         "toolName": "exec_command",
-        "input": { "command": "npm", "args": ["run", { "$regex": "^(check|test|lint|fix)$" }] },
+        "input": { "command": "npm", "args": ["run", { "$regex": "^(lint|test)$" }] },
         "action": "allow"
       },
 
@@ -511,8 +490,8 @@ The agent loads configuration files in the following order. Settings in later fi
     }
   },
 
-  // Override default notification command
-  // "notifyCmd": "/path/to/notification-command"
+  // Override default notification command (falls back to terminal bell)
+  // "notifyCmd": { "command": "plain-notify-desktop", "args": [] }
 
   // (Optional) Voice input. See "Voice Input" below.
   // "voiceInput": {
@@ -527,6 +506,17 @@ The agent loads configuration files in the following order. Settings in later fi
 
 You can define reusable prompts in Markdown files.
 
+### Locations
+
+The agent searches for prompts in the following directories:
+
+- `~/.config/plain-agent/prompts/`
+- `.plain-agent/prompts/`
+- `.claude/commands/`
+- `.claude/skills/`
+
+The prompt ID is the relative path of the file without the `.md` extension. For example, `.plain-agent/prompts/commit.md` becomes `/prompts:commit`.
+
 ### Prompt File Format
 
 ```md
@@ -548,30 +538,8 @@ import: https://raw.githubusercontent.com/anthropics/claude-code/5cff78741f54a0d
 - Parallel execution of subagents is not supported. Delegate to subagents sequentially.
 ```
 
-```md
----
-import: https://raw.githubusercontent.com/anthropics/claude-code/db8834ba1d72e9a26fba30ac85f3bc4316bb0689/plugins/code-review/commands/code-review.md
----
-
-- Parallel execution of subagents is not supported. Delegate to subagents sequentially.
-- If CLAUDE.md is not found, refer to AGENTS.md instead for project rules and conventions.
-- If the PR branch is already checked out, review changes from local files instead of fetching from GitHub.
-- After explaining the review results to the user, ask whether to post the comments to GitHub as well.
-```
-
 Remote prompts are fetched and cached locally. The local content will be appended to the imported content.
 
-### Locations
-
-The agent searches for prompts in the following directories:
-
-- `~/.config/plain-agent/prompts/`
-- `.plain-agent/prompts/`
-- `.claude/commands/`
-- `.claude/skills/`
-
-The prompt ID is the relative path of the file without the `.md` extension. For example, `.plain-agent/prompts/commit.md` becomes `/prompts:commit`.
-
 ### Shortcuts
 
 Prompts located in a `shortcuts/` subdirectory (e.g., `.plain-agent/prompts/shortcuts/commit.md`) can be invoked directly as a top-level command (e.g., `/commit`).
@@ -580,6 +548,14 @@ Prompts located in a `shortcuts/` subdirectory (e.g., `.plain-agent/prompts/shor
 
 Subagents are specialized agents designed for specific tasks.
 
+### Locations
+
+The agent searches for subagent definitions in the following directories:
+
+- `~/.config/plain-agent/agents/`
+- `.plain-agent/agents/`
+- `.claude/agents/`
+
 ### Subagent File Format
 
 ```md
@@ -602,14 +578,6 @@ Use AGENTS.md instead of CLAUDE.md in this project.
 
 Remote subagents are fetched and cached locally. The local content will be appended to the imported content.
 
-### Locations
-
-The agent searches for subagent definitions in the following directories:
-
-- `~/.config/plain-agent/agents/`
-- `.plain-agent/agents/`
-- `.claude/agents/`
-
 ## Claude Code Plugin Support
 
 Example:
@@ -653,7 +621,7 @@ and send them like regular text.
 
 ### Providers
 
-**OpenAI Realtime** (default, recommended):
+**OpenAI Realtime**
 
 ```js
 {
@@ -666,7 +634,7 @@ and send them like regular text.
 }
 ```
 
-**Gemini Live** (preview API; model names and pricing may change):
+**Gemini Live**
 
 ```js
 {
@@ -683,8 +651,7 @@ and send them like regular text.
 
 - `toggleKey` — Rebind the toggle. Accepts `"ctrl-<char>"` where `<char>`
   is a letter (a-z) or one of `[ \ ] ^ _`. Defaults to `"ctrl-o"`.
-- `recorder` — Override recorder auto-detection. Must write raw 16-bit
-  little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
+- `recorder` — Override recorder auto-detection, e.g. `{ "command": "sox", "args": ["-q", "-d", "-b", "16", "-c", "1", "-r", "24000", "-e", "signed-integer", "-t", "raw", "-"] }`. Must write raw 16-bit little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
 
 ## Development
 
@@ -705,13 +672,9 @@ npx npm-check-updates -t minor -c 3 -u
 ## Release
 
 ```sh
-npm run check
-
-git commit -m "<message>"
-
 npm version <major|minor|patch>
-git push --follow-tags
 
+git push --follow-tags
 gh release create $(git describe --tags) --generate-notes
 
 npm publish --access public

package/config/config.predefined.json

@@ -813,7 +813,7 @@
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-medium",
       "platform": {
         "name": "openai",
@@ -823,7 +823,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "medium", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -833,14 +833,14 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-high",
       "platform": {
         "name": "openai",
@@ -850,7 +850,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "high", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -860,14 +860,14 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-xhigh",
       "platform": {
         "name": "openai",
@@ -877,7 +877,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "xhigh", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -887,9 +887,9 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.19",
+  "version": "1.7.20",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",
@@ -10,9 +10,7 @@
   },
   "bin": {
     "plain": "./bin/plain",
-    "plain-interrupt": "./bin/plain-interrupt",
     "plain-notify-desktop": "./bin/plain-notify-desktop",
-    "plain-notify-terminal-bell": "./bin/plain-notify-terminal-bell",
     "plain-sandbox": "./sandbox/bin/plain-sandbox"
   },
   "files": [

package/src/agentLoop.mjs

@@ -128,7 +128,9 @@ export function createAgentLoop({
 
       const { message: assistantMessage, providerTokenUsage } = modelOutput;
       stateManager.appendMessages([assistantMessage]);
-      agentEventEmitter.emit("providerTokenUsage", providerTokenUsage);
+      if (providerTokenUsage) {
+        agentEventEmitter.emit("providerTokenUsage", providerTokenUsage);
+      }
 
       // Gemini may stop with "thinking" -> continue
       const lastContent = assistantMessage.content.at(-1);

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 ?? []),