@iinm/plain-agent 1.8.4 → 1.8.6

package/src/cliArgs.mjs

@@ -0,0 +1,175 @@
+/**
+ * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand} Subcommand
+ */
+
+/**
+ * @typedef {{ type: 'help' }} HelpSubcommand
+ */
+
+/**
+ * @typedef {{ type: 'interactive', config: string[], model: string | null }} InteractiveSubcommand
+ */
+
+/**
+ * @typedef {{ type: 'batch', task: string, config: string[], model: string | null }} BatchSubcommand
+ */
+
+/**
+ * @typedef {{ type: 'list-models' }} ListModelsSubcommand
+ */
+
+/**
+ * @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
+ */
+
+/**
+ * Parse command-line arguments.
+ * @param {string[]} argv - process.argv or similar
+ * @returns {CliArgs}
+ */
+export function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  const subcommandName = args[0];
+
+  if (["-h", "--help", "help"].includes(subcommandName)) {
+    return {
+      subcommand: { type: "help" },
+    };
+  }
+
+  if (!subcommandName || subcommandName.startsWith("-")) {
+    // Interactive mode (default)
+    const config = [];
+    let model = null;
+
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === "-m" || args[i] === "--model") {
+        if (args[i + 1]) {
+          model = args[i + 1];
+          i++;
+        }
+      } else if (args[i] === "-c" || args[i] === "--config") {
+        if (args[i + 1]) {
+          config.push(args[i + 1]);
+          i++;
+        }
+      }
+    }
+
+    return {
+      subcommand: { type: "interactive", config, model },
+    };
+  }
+
+  if (subcommandName === "batch") {
+    const batchArgs = args.slice(1);
+
+    let task = null;
+    let model = null;
+    const config = [];
+
+    for (let i = 0; i < batchArgs.length; i++) {
+      if (batchArgs[i] === "-m" || batchArgs[i] === "--model") {
+        if (batchArgs[i + 1]) {
+          model = batchArgs[i + 1];
+          i++;
+        }
+      } else if (batchArgs[i] === "-c" || batchArgs[i] === "--config") {
+        if (batchArgs[i + 1]) {
+          config.push(batchArgs[i + 1]);
+          i++;
+        }
+      } else if (!batchArgs[i].startsWith("-") && !task) {
+        task = batchArgs[i];
+      }
+    }
+
+    return {
+      subcommand: { type: "batch", task: task || "", config, model },
+    };
+  }
+
+  if (subcommandName === "list-models") {
+    return {
+      subcommand: { type: "list-models" },
+    };
+  }
+
+  if (subcommandName === "install-claude-code-plugins") {
+    return {
+      subcommand: { type: "install-claude-code-plugins" },
+    };
+  }
+
+  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" },
+  };
+}
+
+/**
+ * Print help message and exit.
+ * @param {number} [exitCode] - Exit code (default: 0)
+ */
+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
+
+Options:
+  -m, --model <model+variant>  Model to use
+  -h, --help                   Show this help message
+  -c, --config <file>          Config file to load (repeatable)
+
+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
+
+Examples:
+  plain -m gpt-5.4+thinking-medium
+  plain batch \\
+        -c ~/.config/plain-agent/config.local.json \\
+        -c .plain-agent/config.json \\
+        "Add tests for ..."
+`);
+  process.exit(exitCode);
+}

package/src/cliBatch.mjs

@@ -0,0 +1,147 @@
+/**
+ * @import { UserEventEmitter, AgentEventEmitter, AgentCommands } from "./agent"
+ */
+
+import { formatCostForBatch } from "./cliFormatter.mjs";
+import { appendUsageRecord, buildUsageRecord } from "./usageStore.mjs";
+
+/**
+ * @typedef {object} BatchSessionOptions
+ * @property {UserEventEmitter} userEventEmitter
+ * @property {AgentEventEmitter} agentEventEmitter
+ * @property {AgentCommands} agentCommands
+ * @property {string} task - Task instruction to execute
+ * @property {string} sessionId
+ * @property {string} modelName
+ * @property {boolean} sandbox
+ * @property {Date} startTime
+ * @property {() => Promise<void>} onStop
+ */
+
+/**
+ * Start a batch session and execute the task.
+ * Events are output as JSON Lines (1 line = 1 JSON object).
+ *
+ * @param {BatchSessionOptions} options
+ * @returns {Promise<void>}
+ */
+export async function startBatchSession({
+  userEventEmitter,
+  agentEventEmitter,
+  agentCommands,
+  task,
+  sessionId,
+  modelName,
+  sandbox,
+  startTime,
+  onStop,
+}) {
+  setupEventHandlers(agentEventEmitter, { sessionId, modelName, sandbox });
+
+  userEventEmitter.emit("userInput", [{ type: "text", text: task }]);
+
+  await new Promise((/** @type {(value?: void) => void} */ resolve) => {
+    agentEventEmitter.on("turnEnd", async () => {
+      const costSummary = agentCommands.getCostSummary();
+
+      outputEvent({
+        type: "session_end",
+        timestamp: new Date().toISOString(),
+        cost: formatCostForBatch(costSummary),
+      });
+
+      try {
+        const record = buildUsageRecord({
+          sessionId,
+          mode: "batch",
+          modelName,
+          workingDir: process.cwd(),
+          costSummary,
+          now: startTime,
+        });
+        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();
+    });
+  });
+
+  process.exit(0);
+}
+
+/**
+ * Setup event handlers for batch mode.
+ * Output events as JSON Lines.
+ *
+ * @param {AgentEventEmitter} agentEventEmitter
+ * @param {{ sessionId: string, modelName: string, sandbox: boolean }} meta
+ */
+function setupEventHandlers(
+  agentEventEmitter,
+  { sessionId, modelName, sandbox },
+) {
+  outputEvent({
+    type: "session_start",
+    sessionId,
+    modelName,
+    sandbox,
+    timestamp: new Date().toISOString(),
+  });
+
+  agentEventEmitter.on("message", (message) => {
+    outputEvent({
+      type: "message",
+      message,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  agentEventEmitter.on("error", (error) => {
+    outputEvent({
+      type: "error",
+      error: {
+        message: error.message,
+        stack: error.stack,
+      },
+      timestamp: new Date().toISOString(),
+    });
+
+    process.exit(1);
+  });
+
+  agentEventEmitter.on("subagentSwitched", (subagent) => {
+    outputEvent({
+      type: "subagent_switched",
+      subagent,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  agentEventEmitter.on("providerTokenUsage", (usage) => {
+    outputEvent({
+      type: "token_usage",
+      usage,
+      timestamp: new Date().toISOString(),
+    });
+  });
+}
+
+/**
+ * Output an event as JSON Lines format.
+ * Each event is a single line of JSON.
+ *
+ * @param {object} event
+ */
+function outputEvent(event) {
+  console.log(JSON.stringify(event));
+}

package/src/cliCommands.mjs

@@ -0,0 +1,283 @@
+/**
+ * @import { UserEventEmitter, AgentCommands } from "./agent"
+ * @import { ClaudeCodePlugin } from "./claudeCodePlugin.mjs"
+ */
+
+import { execFileSync } from "node:child_process";
+import { styleText } from "node:util";
+import { formatCostSummary } from "./cliFormatter.mjs";
+import { loadAgentRoles } from "./context/loadAgentRoles.mjs";
+import { loadPrompts } from "./context/loadPrompts.mjs";
+import { loadUserMessageContext } from "./context/loadUserMessageContext.mjs";
+import { CLAUDE_CODE_COMPATIBILITY_NOTES } from "./prompt.mjs";
+import { parseFileRange } from "./utils/parseFileRange.mjs";
+import { readFileRange } from "./utils/readFileRange.mjs";
+
+/**
+ * @typedef {"prompt" | "continue"} CommandResult
+ * - "prompt": return control to prompt (state.turn = true; cli.prompt())
+ * - "continue": agent is now running, do nothing
+ */
+
+/**
+ * @typedef {object} CommandHandlerDeps
+ * @property {AgentCommands} agentCommands
+ * @property {UserEventEmitter} userEventEmitter
+ * @property {ClaudeCodePlugin[] | undefined} claudeCodePlugins
+ * @property {string} helpMessage
+ */
+
+/**
+ * Create command handler function for processing slash commands.
+ *
+ * @param {CommandHandlerDeps} deps
+ * @returns {(input: string) => Promise<CommandResult>}
+ */
+export function createCommandHandler({
+  agentCommands,
+  userEventEmitter,
+  claudeCodePlugins,
+  helpMessage,
+}) {
+  /**
+   * Invoke an agent with the given id and goal.
+   * @param {string} id
+   * @param {string} goal
+   * @returns {Promise<CommandResult>}
+   */
+  async function invokeAgent(id, goal) {
+    const agentRoles = await loadAgentRoles(claudeCodePlugins);
+    const agent = agentRoles.get(id);
+    const name = agent ? id : `custom:${id}`;
+
+    const [goalTextContent, ...goalImages] = await loadUserMessageContext(goal);
+    const goalText =
+      goalTextContent?.type === "text" ? goalTextContent.text : goal;
+
+    const messageText = `Switch to "${name}" subagent with goal: ${goalText}`;
+    userEventEmitter.emit("userInput", [
+      { type: "text", text: messageText },
+      ...goalImages,
+    ]);
+    return "continue";
+  }
+
+  /**
+   * Invoke a prompt with the given id, args, and display invocation.
+   * @param {string} id
+   * @param {string} args
+   * @param {string} displayInvocation
+   * @returns {Promise<CommandResult>}
+   */
+  async function invokePrompt(id, args, displayInvocation) {
+    const prompts = await loadPrompts(claudeCodePlugins);
+    const prompt = prompts.get(id);
+
+    if (!prompt) {
+      console.log(styleText("red", `\nPrompt not found: ${id}`));
+      return "prompt";
+    }
+
+    const [argsTextContent, ...argsImages] = args
+      ? await loadUserMessageContext(args)
+      : [];
+    const argsText =
+      argsTextContent?.type === "text" ? argsTextContent.text : args;
+
+    const invocation = `${displayInvocation}${argsText ? ` ${argsText}` : ""}`;
+    const promptContent = prompt.claudeOriginated
+      ? `${prompt.content}\n\n---\n\n${CLAUDE_CODE_COMPATIBILITY_NOTES}`
+      : prompt.content;
+    const message = prompt.isSkill
+      ? `System: This prompt was invoked as "${invocation}".\nPrompt path: ${prompt.filePath}\n\n${promptContent}`
+      : `System: This prompt was invoked as "${invocation}".\n\n${promptContent}`;
+
+    userEventEmitter.emit("userInput", [
+      { type: "text", text: message },
+      ...argsImages,
+    ]);
+    return "continue";
+  }
+
+  /**
+   * Handle a complete user input string and return a CommandResult.
+   * @param {string} inputTrimmed
+   * @returns {Promise<CommandResult>}
+   */
+  return async function handleCommand(inputTrimmed) {
+    // /help or help
+    if (["/help", "help"].includes(inputTrimmed.toLowerCase())) {
+      console.log(`\n${helpMessage}`);
+      return "prompt";
+    }
+
+    // !path — read file content and emit as user input
+    if (inputTrimmed.startsWith("!")) {
+      const fileRange = parseFileRange(inputTrimmed.slice(1));
+      if (fileRange instanceof Error) {
+        console.log(styleText("red", `\n${fileRange.message}`));
+        return "prompt";
+      }
+
+      const fileContent = await readFileRange(fileRange);
+      if (fileContent instanceof Error) {
+        console.log(styleText("red", `\n${fileContent.message}`));
+        return "prompt";
+      }
+
+      const messageWithContext = await loadUserMessageContext(fileContent);
+      userEventEmitter.emit("userInput", messageWithContext);
+      return "continue";
+    }
+
+    // /dump
+    if (inputTrimmed.toLowerCase() === "/dump") {
+      await agentCommands.dumpMessages();
+      return "prompt";
+    }
+
+    // /load
+    if (inputTrimmed.toLowerCase() === "/load") {
+      await agentCommands.loadMessages();
+      return "prompt";
+    }
+
+    // /cost
+    if (inputTrimmed.toLowerCase() === "/cost") {
+      const summary = agentCommands.getCostSummary();
+      console.log(formatCostSummary(summary));
+      return "prompt";
+    }
+
+    // /compact
+    if (inputTrimmed.toLowerCase() === "/compact") {
+      const message = [
+        'System: This prompt was invoked as "/compact".',
+        "",
+        "Compact the conversation context:",
+        "1. Update the memory file for the current task so it fully captures the task overview, progress, decisions, and next steps in a self-contained way.",
+        '2. Then call the "compact_context" tool alone with that memory file path and a brief reason.',
+      ].join("\n");
+      userEventEmitter.emit("userInput", [{ type: "text", text: message }]);
+      return "continue";
+    }
+
+    // /agents or /agents:id
+    if (inputTrimmed === "/agents") {
+      const agentRoles = await loadAgentRoles(claudeCodePlugins);
+
+      console.log(styleText("bold", "\nAvailable Agent Roles:"));
+      if (agentRoles.size === 0) {
+        console.log("  No agent roles found.");
+      } else {
+        for (const role of agentRoles.values()) {
+          const maxLength = process.stdout.columns ?? 100;
+          const line = `  ${styleText("cyan", role.id.padEnd(20))} - ${role.description}`;
+          console.log(
+            line.length > maxLength ? `${line.slice(0, maxLength)}...` : line,
+          );
+        }
+      }
+      return "prompt";
+    }
+
+    if (inputTrimmed.startsWith("/agents:")) {
+      const match = inputTrimmed.match(/^\/agents:([^ ]+)(?:\s+(.*))?$/s);
+      if (!match) {
+        console.log(styleText("red", "\nInvalid agent invocation format."));
+        return "prompt";
+      }
+      return await invokeAgent(match[1], match[2] || "");
+    }
+
+    // /prompts or /prompts:id
+    if (inputTrimmed.startsWith("/prompts")) {
+      const prompts = await loadPrompts(claudeCodePlugins);
+
+      if (inputTrimmed === "/prompts") {
+        console.log(styleText("bold", "\nAvailable Prompts:"));
+        if (prompts.size === 0) {
+          console.log("  No prompts found.");
+        } else {
+          for (const prompt of prompts.values()) {
+            const maxLength = process.stdout.columns ?? 100;
+            const line = `  ${styleText("cyan", prompt.id.padEnd(20))} - ${prompt.description}`;
+            console.log(
+              line.length > maxLength ? `${line.slice(0, maxLength)}...` : line,
+            );
+          }
+        }
+        return "prompt";
+      }
+
+      if (inputTrimmed.startsWith("/prompts:")) {
+        const match = inputTrimmed.match(/^\/prompts:([^ ]+)(?:\s+(.*))?$/s);
+        if (!match) {
+          console.log(styleText("red", "\nInvalid prompt invocation format."));
+          return "prompt";
+        }
+        return await invokePrompt(
+          match[1],
+          match[2] || "",
+          `/prompts:${match[1]}`,
+        );
+      }
+    }
+
+    // /paste — read clipboard and emit as user input
+    if (inputTrimmed.startsWith("/paste")) {
+      const prompt = inputTrimmed.slice("/paste".length).trim();
+      let clipboard;
+      try {
+        if (process.platform === "darwin") {
+          clipboard = execFileSync("pbpaste", { encoding: "utf8" });
+        } else if (process.platform === "linux") {
+          clipboard = execFileSync("xsel", ["--clipboard", "--output"], {
+            encoding: "utf8",
+          });
+        } else {
+          console.log(
+            styleText(
+              "red",
+              `\nUnsupported platform for /paste: ${process.platform}`,
+            ),
+          );
+          return "prompt";
+        }
+      } catch (e) {
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        console.log(
+          styleText(
+            "red",
+            `\nFailed to get clipboard content: ${errorMessage}`,
+          ),
+        );
+        return "prompt";
+      }
+
+      const combinedInput = prompt ? `${prompt}\n\n${clipboard}` : clipboard;
+      const messageWithContext = await loadUserMessageContext(combinedInput);
+      userEventEmitter.emit("userInput", messageWithContext);
+      return "continue";
+    }
+
+    // /<id> — shortcut for prompts in shortcuts/ directory
+    if (inputTrimmed.startsWith("/")) {
+      const match = inputTrimmed.match(/^\/([^ ]+)(?:\s+(.*))?$/);
+      if (match) {
+        const id = match[1];
+        const prompts = await loadPrompts(claudeCodePlugins);
+        const prompt = prompts.get(id);
+
+        if (prompt?.isShortcut) {
+          return await invokePrompt(id, match[2] || "", `/${id}`);
+        }
+      }
+    }
+
+    // Default: emit as plain user input
+    const messageWithContext = await loadUserMessageContext(inputTrimmed);
+    userEventEmitter.emit("userInput", messageWithContext);
+    return "continue";
+  };
+}