@iinm/plain-agent 1.9.3 → 1.10.0

package/src/costTracker.mjs

@@ -29,6 +29,8 @@
  * @property {() => Record<string, number>} getAggregatedUsage - Get aggregated usage
  * @property {() => CostSummary} calculateCost - Calculate cost summary
  * @property {() => boolean} hasUsage - Check if any usage recorded
+ * @property {() => ProviderTokenUsage[]} getUsageHistory - Get a snapshot of the raw usage history
+ * @property {(history: ProviderTokenUsage[]) => void} restoreUsageHistory - Replace the usage history (used when resuming a saved session)
  */
 
 /**
@@ -110,11 +112,38 @@ export function createCostTracker(costConfig) {
     return usageHistory.length > 0;
   }
 
+  /**
+   * Get a snapshot copy of the raw usage history.
+   * @returns {ProviderTokenUsage[]}
+   */
+  function getUsageHistory() {
+    return usageHistory.map((u) => u);
+  }
+
+  /**
+   * Replace the usage history. Used when resuming a saved session.
+   * @param {ProviderTokenUsage[]} history
+   */
+  function restoreUsageHistory(history) {
+    if (!Array.isArray(history)) {
+      throw new TypeError("history must be an array");
+    }
+    usageHistory.length = 0;
+    for (const usage of history) {
+      if (typeof usage !== "object" || usage === null) {
+        throw new TypeError("each usage entry must be a non-null object");
+      }
+      usageHistory.push(usage);
+    }
+  }
+
   return Object.freeze({
     recordUsage,
     getAggregatedUsage,
     calculateCost,
     hasUsage,
+    getUsageHistory,
+    restoreUsageHistory,
   });
 }
 

package/src/env.mjs

@@ -30,15 +30,11 @@ export const AGENT_PROJECT_METADATA_DIR = ".plain-agent";
 
 export const AGENT_MEMORY_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "memory");
 export const AGENT_TMP_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "tmp");
+export const SESSIONS_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "sessions");
 
 export const CLAUDE_CODE_PLUGIN_DIR = path.join(
   AGENT_PROJECT_METADATA_DIR,
   "claude-code-plugins",
 );
 
-export const MESSAGES_DUMP_FILE_PATH = path.join(
-  AGENT_PROJECT_METADATA_DIR,
-  "messages.json",
-);
-
 export const USER_NAME = process.env.USER || "unknown";

package/src/main.mjs

@@ -1,7 +1,9 @@
 /**
  * @import { Tool } from "./tool";
+ * @import { SessionState } from "./sessionStore.mjs";
  */
 
+import { randomInt } from "node:crypto";
 import { styleText } from "node:util";
 import { createAgent } from "./agent.mjs";
 import {
@@ -19,8 +21,7 @@ import { AGENT_PROJECT_METADATA_DIR, USER_NAME } from "./env.mjs";
 import { setupMCPServer } from "./mcpIntegration.mjs";
 import { createModelCaller } from "./modelCaller.mjs";
 import { createPrompt } from "./prompt.mjs";
-import { createAskURLTool } from "./tools/askURL.mjs";
-import { createAskWebTool } from "./tools/askWeb.mjs";
+import { listSessions, loadSession } from "./sessionStore.mjs";
 import { createCompactContextTool } from "./tools/compactContext.mjs";
 import { createExecCommandTool } from "./tools/execCommand.mjs";
 import { createPatchFileTool } from "./tools/patchFile.mjs";
@@ -28,6 +29,8 @@ import { readFileTool } from "./tools/readFile.mjs";
 import { createSwitchToMainAgentTool } from "./tools/switchToMainAgent.mjs";
 import { createSwitchToSubagentTool } from "./tools/switchToSubagent.mjs";
 import { createTmuxCommandTool } from "./tools/tmuxCommand.mjs";
+import { createWebFetchTool } from "./tools/webFetch.mjs";
+import { createWebSearchTool } from "./tools/webSearch.mjs";
 import { writeFileTool } from "./tools/writeFile.mjs";
 import { createToolUseApprover } from "./toolUseApprover.mjs";
 
@@ -70,19 +73,74 @@ if (cliArgs.subcommand.type === "cost") {
   }
 }
 
+if (cliArgs.subcommand.type === "resume" && cliArgs.subcommand.list) {
+  const sessions = await listSessions();
+  if (sessions.length === 0) {
+    console.log("No resumable sessions in .plain-agent/sessions/.");
+    process.exit(0);
+  }
+  console.log("Resumable sessions (most recently updated first):\n");
+  for (const s of sessions) {
+    console.log(
+      `  ${s.sessionId}  ${s.modelName}  (updated ${formatLocalDateTime(s.lastUpdatedAt)}, ${s.messageCount} messages)`,
+    );
+    if (s.workingDir !== process.cwd()) {
+      console.log(`    workingDir: ${s.workingDir}`);
+    }
+  }
+  process.exit(0);
+}
+
 (async () => {
-  const startTime = new Date();
-  const sessionId = [
-    `${startTime.getFullYear()}-${`0${startTime.getMonth() + 1}`.slice(-2)}-${`0${startTime.getDate()}`.slice(-2)}`,
-    `0${startTime.getHours()}`.slice(-2) +
-      `0${startTime.getMinutes()}`.slice(-2),
-  ].join("-");
+  /** @type {SessionState | null} */
+  let resumedState = null;
+
+  if (cliArgs.subcommand.type === "resume") {
+    const requestedId = cliArgs.subcommand.sessionId;
+    if (requestedId) {
+      resumedState = await loadSession(requestedId);
+      if (!resumedState) {
+        console.error(
+          styleText("red", `No saved session found for id: ${requestedId}`),
+        );
+        process.exit(1);
+      }
+    } else {
+      const sessions = await listSessions();
+      if (sessions.length === 0) {
+        console.error(
+          styleText(
+            "red",
+            "No resumable sessions found in .plain-agent/sessions/.",
+          ),
+        );
+        process.exit(1);
+      }
+      resumedState = await loadSession(sessions[0].sessionId);
+      if (!resumedState) {
+        console.error(
+          styleText(
+            "red",
+            `Failed to load latest session: ${sessions[0].sessionId}`,
+          ),
+        );
+        process.exit(1);
+      }
+    }
+  }
+
+  const startTime = resumedState
+    ? new Date(resumedState.startTime)
+    : new Date();
+  const sessionId = resumedState ? resumedState.sessionId : generateSessionId();
   const tmuxSessionId = `agent-${sessionId}`;
 
   const isBatchMode = cliArgs.subcommand.type === "batch";
+  /** @type {string[]} */
   const configFiles =
     cliArgs.subcommand.type === "batch" ||
-    cliArgs.subcommand.type === "interactive"
+    cliArgs.subcommand.type === "interactive" ||
+    cliArgs.subcommand.type === "resume"
       ? cliArgs.subcommand.config
       : [];
 
@@ -109,6 +167,23 @@ if (cliArgs.subcommand.type === "cost") {
     } else {
       console.log(styleText("yellow", "\n📦 Sandbox: off"));
     }
+
+    if (resumedState) {
+      console.log(
+        styleText("green", `\n⏯  Resuming session: ${resumedState.sessionId}`),
+      );
+      console.log(
+        `  ⤷ ${resumedState.messages.length} messages, last updated ${formatLocalDateTime(resumedState.lastUpdatedAt)}`,
+      );
+      if (resumedState.workingDir !== process.cwd()) {
+        console.log(
+          styleText(
+            "yellow",
+            `  ⚠️ workingDir differs (saved: ${resumedState.workingDir}, current: ${process.cwd()})`,
+          ),
+        );
+      }
+    }
   }
 
   /** @type {(() => Promise<void>)[]} */
@@ -156,7 +231,30 @@ if (cliArgs.subcommand.type === "cost") {
     cliArgs.subcommand.type === "interactive"
       ? cliArgs.subcommand.model
       : null;
-  const modelNameWithVariant = modelFromArgs || modelFromConfig;
+  let modelNameWithVariant = modelFromArgs || modelFromConfig;
+
+  if (resumedState) {
+    // Switching models on resume is not supported. The model from the saved
+    // session always wins. If config disagrees, fail loudly.
+    if (
+      modelNameWithVariant &&
+      modelNameWithVariant !== resumedState.modelName
+    ) {
+      console.error(
+        styleText(
+          "red",
+          [
+            `Cannot resume session ${resumedState.sessionId}: model mismatch.`,
+            `  saved model:   ${resumedState.modelName}`,
+            `  current model: ${modelNameWithVariant}`,
+            "Resume must use the same model the session was started with.",
+          ].join("\n"),
+        ),
+      );
+      process.exit(1);
+    }
+    modelNameWithVariant = resumedState.modelName;
+  }
 
   const pluginPaths = resolvePluginPaths(appConfig.claudeCodePlugins ?? []);
   const [prompts, agentRoles] = await Promise.all([
@@ -187,28 +285,6 @@ if (cliArgs.subcommand.type === "cost") {
     createSwitchToMainAgentTool(),
   ];
 
-  if (appConfig.tools?.askWeb) {
-    builtinTools.push(createAskWebTool(appConfig.tools.askWeb));
-  }
-
-  if (appConfig.tools?.askURL) {
-    builtinTools.push(createAskURLTool(appConfig.tools.askURL));
-  }
-
-  const toolUseApprover = createToolUseApprover({
-    maxApprovals: appConfig.autoApproval?.maxApprovals || 50,
-    defaultAction: appConfig.autoApproval?.defaultAction || "ask",
-    patterns: appConfig.autoApproval?.patterns || [],
-    maskApprovalInput: (toolName, input) => {
-      for (const tool of builtinTools) {
-        if (tool.def.name === toolName && tool.maskApprovalInput) {
-          return tool.maskApprovalInput(input);
-        }
-      }
-      return input;
-    },
-  });
-
   const [modelName, modelVariant] = modelNameWithVariant.split("+");
   const modelDef = (appConfig.models ?? []).find(
     (entry) => entry.name === modelName && entry.variant === modelVariant,
@@ -230,19 +306,95 @@ if (cliArgs.subcommand.type === "cost") {
     );
   }
 
+  if (appConfig.tools?.webSearch) {
+    const webSearchConfig = appConfig.tools.webSearch;
+    if (webSearchConfig.provider === "command") {
+      const webSearchCallModel = createModelCaller({
+        ...modelDef,
+        platform: {
+          ...modelDef.platform,
+          ...platform,
+        },
+      });
+      builtinTools.push(
+        createWebSearchTool({
+          provider: "command",
+          command: webSearchConfig.command,
+          args: webSearchConfig.args,
+          timeoutMs: webSearchConfig.timeoutMs,
+          env: webSearchConfig.env,
+          modelCaller: webSearchCallModel,
+          maxLengthPerSearch: webSearchConfig.maxLengthPerSearch,
+          maxTotalLength: webSearchConfig.maxTotalLength,
+        }),
+      );
+    } else {
+      builtinTools.push(createWebSearchTool(webSearchConfig));
+    }
+  }
+
+  if (appConfig.tools?.webFetch) {
+    const webFetchConfig = appConfig.tools.webFetch;
+    if (webFetchConfig.provider === "command") {
+      const webFetchCallModel = createModelCaller({
+        ...modelDef,
+        platform: {
+          ...modelDef.platform,
+          ...platform,
+        },
+      });
+      builtinTools.push(
+        createWebFetchTool({
+          provider: "command",
+          command: webFetchConfig.command,
+          args: webFetchConfig.args,
+          timeoutMs: webFetchConfig.timeoutMs,
+          env: webFetchConfig.env,
+          modelCaller: webFetchCallModel,
+          maxLength: webFetchConfig.maxLength,
+        }),
+      );
+    } else {
+      builtinTools.push(createWebFetchTool(webFetchConfig));
+    }
+  }
+
+  const toolUseApprover = createToolUseApprover({
+    maxApprovals: appConfig.autoApproval?.maxApprovals || 50,
+    defaultAction: appConfig.autoApproval?.defaultAction || "ask",
+    patterns: appConfig.autoApproval?.patterns || [],
+    maskApprovalInput: (toolName, input) => {
+      for (const tool of builtinTools) {
+        if (tool.def.name === toolName && tool.maskApprovalInput) {
+          return tool.maskApprovalInput(input);
+        }
+      }
+      return input;
+    },
+  });
+
+  const agentCallModel = createModelCaller({
+    ...modelDef,
+    platform: {
+      ...modelDef.platform,
+      ...platform,
+    },
+  });
+
   const { userEventEmitter, agentEventEmitter, agentCommands } = createAgent({
-    callModel: createModelCaller({
-      ...modelDef,
-      platform: {
-        ...modelDef.platform,
-        ...platform,
-      },
-    }),
+    callModel: agentCallModel,
     prompt,
     tools: [...builtinTools, ...mcpTools],
     toolUseApprover,
     agentRoles,
     modelCostConfig: modelDef.cost,
+    sessionMetadata: {
+      sessionId,
+      modelName: modelNameWithVariant,
+      workingDir: process.cwd(),
+      startTime,
+    },
+    initialState: resumedState,
   });
 
   const sessionOptions = {
@@ -281,3 +433,41 @@ if (cliArgs.subcommand.type === "cost") {
   console.error(err);
   process.exit(1);
 });
+
+/**
+ * Generate a session id of the form `YYYY-MM-DD-HHMM-<3 random base36 chars>`.
+ * The random suffix avoids collisions when multiple `plain` processes start
+ * within the same minute. `randomInt` is uniform over `[0, 36 ** 3)`, so
+ * each suffix character is unbiased.
+ *
+ * @param {Date} [now]
+ * @returns {string}
+ */
+function generateSessionId(now = new Date()) {
+  const date = [
+    `${now.getFullYear()}-${`0${now.getMonth() + 1}`.slice(-2)}-${`0${now.getDate()}`.slice(-2)}`,
+    `0${now.getHours()}`.slice(-2) + `0${now.getMinutes()}`.slice(-2),
+  ].join("-");
+  const suffix = randomInt(36 ** 3)
+    .toString(36)
+    .padStart(3, "0");
+  return `${date}-${suffix}`;
+}
+
+/**
+ * Format an ISO 8601 timestamp as `YYYY-MM-DD HH:MM:SS` in the local timezone.
+ *
+ * @param {string} iso
+ * @returns {string}
+ */
+function formatLocalDateTime(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  const y = d.getFullYear();
+  const mo = `${d.getMonth() + 1}`.padStart(2, "0");
+  const da = `${d.getDate()}`.padStart(2, "0");
+  const h = `${d.getHours()}`.padStart(2, "0");
+  const mi = `${d.getMinutes()}`.padStart(2, "0");
+  const s = `${d.getSeconds()}`.padStart(2, "0");
+  return `${y}-${mo}-${da} ${h}:${mi}:${s}`;
+}

package/src/sessionStore.mjs

@@ -0,0 +1,164 @@
+/**
+ * @import { Message, ProviderTokenUsage } from "./model"
+ * @import { ToolUsePattern } from "./tool"
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SESSIONS_DIR } from "./env.mjs";
+
+/** Current on-disk format version. Bump on breaking changes. */
+export const SESSION_FILE_VERSION = 1;
+
+/**
+ * @typedef {Object} SubagentSerializedState
+ * @property {{name: string, goal: string, switchMessageIndex: number}[]} subagents
+ * @property {number} subagentCount
+ */
+
+/**
+ * @typedef {Object} SessionState
+ * @property {number} version
+ * @property {string} sessionId
+ * @property {string} modelName
+ * @property {string} workingDir
+ * @property {string} startTime - ISO 8601
+ * @property {string} lastUpdatedAt - ISO 8601
+ * @property {Message[]} messages
+ * @property {SubagentSerializedState} subagentState
+ * @property {ToolUsePattern[]} allowedToolUseInSession
+ * @property {ProviderTokenUsage[]} tokenUsageHistory
+ */
+
+/**
+ * @typedef {Object} SessionSummary
+ * @property {string} sessionId
+ * @property {string} modelName
+ * @property {string} workingDir
+ * @property {string} startTime
+ * @property {string} lastUpdatedAt
+ * @property {number} messageCount
+ */
+
+/**
+ * Resolve the path to a session file.
+ * @param {string} sessionId
+ * @param {{ dir?: string }} [options]
+ */
+export function sessionFilePath(sessionId, options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  return path.join(dir, `${sessionId}.json`);
+}
+
+/**
+ * Persist a session state atomically.
+ *
+ * Writes to a process-unique temp file in the same directory, then renames
+ * it over the target path. Same-directory rename is atomic on POSIX, so a
+ * crash during write leaves either the previous file or the new one — never
+ * a half-written file.
+ *
+ * @param {SessionState} state
+ * @param {{ dir?: string }} [options]
+ * @returns {Promise<void>}
+ */
+export async function saveSession(state, options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  await fs.mkdir(dir, { recursive: true });
+  const target = path.join(dir, `${state.sessionId}.json`);
+  const tmp = `${target}.tmp.${process.pid}`;
+  const json = JSON.stringify(state, null, 2);
+  await fs.writeFile(tmp, json, "utf8");
+  await fs.rename(tmp, target);
+}
+
+/**
+ * Load a session by id. Returns null when the file does not exist.
+ * Throws on parse errors or unsupported versions.
+ *
+ * @param {string} sessionId
+ * @param {{ dir?: string }} [options]
+ * @returns {Promise<SessionState | null>}
+ */
+export async function loadSession(sessionId, options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  const target = path.join(dir, `${sessionId}.json`);
+  /** @type {string} */
+  let raw;
+  try {
+    raw = await fs.readFile(target, "utf8");
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+    ) {
+      return null;
+    }
+    throw err;
+  }
+
+  const parsed = JSON.parse(raw);
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    typeof parsed.version !== "number"
+  ) {
+    throw new Error(`Invalid session file: ${target}`);
+  }
+  if (parsed.version !== SESSION_FILE_VERSION) {
+    throw new Error(
+      `Unsupported session file version ${parsed.version} at ${target} (expected ${SESSION_FILE_VERSION})`,
+    );
+  }
+  return /** @type {SessionState} */ (parsed);
+}
+
+/**
+ * List sessions in the sessions directory, sorted by lastUpdatedAt descending.
+ * Malformed files are silently skipped.
+ *
+ * @param {{ dir?: string }} [options]
+ * @returns {Promise<SessionSummary[]>}
+ */
+export async function listSessions(options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = await fs.readdir(dir);
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+    ) {
+      return [];
+    }
+    throw err;
+  }
+
+  /** @type {SessionSummary[]} */
+  const summaries = [];
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    if (name.includes(".tmp.")) continue;
+    const sessionId = name.slice(0, -".json".length);
+    try {
+      const state = await loadSession(sessionId, { dir });
+      if (!state) continue;
+      summaries.push({
+        sessionId: state.sessionId,
+        modelName: state.modelName,
+        workingDir: state.workingDir,
+        startTime: state.startTime,
+        lastUpdatedAt: state.lastUpdatedAt,
+        messageCount: state.messages.length,
+      });
+    } catch {
+      // Skip malformed or version-mismatched files so a single bad file
+      // doesn't break listing.
+    }
+  }
+
+  summaries.sort((a, b) => b.lastUpdatedAt.localeCompare(a.lastUpdatedAt));
+  return summaries;
+}

package/src/subagent.mjs

@@ -256,10 +256,66 @@ export function createSubagentManager(agentRoles, handlers) {
     return subagents.length > 0;
   }
 
+  /**
+   * Get the most recently activated subagent, or null if none is active.
+   * @returns {{name: string} | null}
+   */
+  function getActiveSubagent() {
+    const top = subagents.at(-1);
+    return top ? { name: top.name } : null;
+  }
+
+  /**
+   * @typedef {Object} SubagentSerializedState
+   * @property {{name: string, goal: string, switchMessageIndex: number}[]} subagents
+   * @property {number} subagentCount
+   */
+
+  /**
+   * Snapshot the subagent stack for persistence.
+   * @returns {SubagentSerializedState}
+   */
+  function getState() {
+    return {
+      subagents: subagents.map((s) => ({ ...s })),
+      subagentCount,
+    };
+  }
+
+  /**
+   * Restore the subagent stack from a previously saved snapshot.
+   * Does NOT fire onSubagentSwitched; the caller is responsible for
+   * syncing any UI state (since listeners may not be attached yet).
+   * @param {SubagentSerializedState} state
+   */
+  function restoreState(state) {
+    if (typeof state !== "object" || state === null) {
+      throw new TypeError("state must be a non-null object");
+    }
+    if (!Array.isArray(state.subagents)) {
+      throw new TypeError("state.subagents must be an array");
+    }
+    if (typeof state.subagentCount !== "number") {
+      throw new TypeError("state.subagentCount must be a number");
+    }
+    subagents.length = 0;
+    for (const s of state.subagents) {
+      subagents.push({
+        name: s.name,
+        goal: s.goal,
+        switchMessageIndex: s.switchMessageIndex,
+      });
+    }
+    subagentCount = state.subagentCount;
+  }
+
   return {
     switchToSubagent,
     switchToMainAgent,
     processToolResults,
     isSubagentActive,
+    getActiveSubagent,
+    getState,
+    restoreState,
   };
 }

package/src/tool.d.ts

@@ -59,6 +59,8 @@ export type ToolUseApprover = {
   isAllowedToolUse: (toolUse: MessageContentToolUse) => ToolUseDecision;
   allowToolUse: (toolUse: MessageContentToolUse) => void;
   resetApprovalCount: () => void;
+  getAllowedToolUseInSession: () => ToolUsePattern[];
+  restoreAllowedToolUseInSession: (patterns: ToolUsePattern[]) => void;
 };
 
 export type ToolUsePattern = {

package/src/toolUseApprover.mjs

@@ -91,9 +91,34 @@ export function createToolUseApprover({
     });
   }
 
+  /**
+   * Snapshot the tool-use patterns the user explicitly allowed during this
+   * session. Used to persist resumable session state.
+   * @returns {ToolUsePattern[]}
+   */
+  function getAllowedToolUseInSession() {
+    return state.allowedToolUseInSession.map((p) => ({ ...p }));
+  }
+
+  /**
+   * Replace the in-session allow-list with a previously saved snapshot.
+   * @param {ToolUsePattern[]} patterns
+   */
+  function restoreAllowedToolUseInSession(patterns) {
+    if (!Array.isArray(patterns)) {
+      throw new TypeError("patterns must be an array");
+    }
+    state.allowedToolUseInSession.length = 0;
+    for (const p of patterns) {
+      state.allowedToolUseInSession.push({ ...p });
+    }
+  }
+
   return {
     isAllowedToolUse,
     allowToolUse,
     resetApprovalCount,
+    getAllowedToolUseInSession,
+    restoreAllowedToolUseInSession,
   };
 }

package/src/tools/execCommand.mjs

@@ -84,6 +84,7 @@ export function createExecCommandTool(config) {
                 PWD: process.env.PWD,
                 PATH: process.env.PATH,
                 HOME: process.env.HOME,
+                LANG: process.env.LANG,
               },
               timeout: 5 * 60 * 1000,
             },