@iinm/plain-agent 1.8.4 → 1.8.6

package/src/tools/execCommand.mjs

@@ -0,0 +1,200 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { ExecCommandConfig, ExecCommandInput, ExecCommandSanboxConfig } from './execCommand'
+ */
+
+import { execFile } from "node:child_process";
+import { writeTmpFile } from "../tmpfile.mjs";
+import { matchValue } from "../utils/matchValue.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+const OUTPUT_MAX_LENGTH = 1024 * 8;
+const OUTPUT_TRUNCATED_LENGTH = 1024 * 2;
+
+/**
+ * @param {ExecCommandConfig=} config
+ * @returns {Tool}
+ */
+export function createExecCommandTool(config) {
+  /** @type {Tool} */
+  return {
+    def: {
+      name: "exec_command",
+      description: "Run a command without shell interpretation.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          command: {
+            description: "The executable name or path. e.g., rg",
+            type: "string",
+          },
+          args: {
+            // Gemini 3 flashが command: rg, args: [rg, ...] のようにargsにコマンドを含めることがある
+            description:
+              "Array of arguments to pass to the command. Do not include the command name itself in this array.",
+            type: "array",
+            items: {
+              type: "string",
+            },
+          },
+        },
+        required: ["command"],
+      },
+    },
+
+    validateInput: (input) => {
+      if (typeof input.command !== "string") {
+        return new Error("command must be a string");
+      }
+
+      // Example: fd<arg_key>args</arg_key><arg_value>[... (GLM-5)
+      if (input.command.match(/[<>]/)) {
+        return new Error(
+          `invalid tool use format: command=${JSON.stringify(input.command)}`,
+        );
+      }
+
+      if (input.command.startsWith("-")) {
+        return new Error("command must not start with '-'");
+      }
+
+      if (input.args && !Array.isArray(input.args)) {
+        return new Error("args must be an array of strings");
+      }
+
+      return;
+    },
+
+    /**
+     * @param {ExecCommandInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) =>
+      await noThrow(async () => {
+        const { command, args } = config?.sandbox
+          ? rewriteInputForSandbox(input, config.sandbox)
+          : input;
+        return new Promise((resolve, _reject) => {
+          const child = execFile(
+            command,
+            args,
+            {
+              shell: false,
+              env: {
+                PWD: process.env.PWD,
+                PATH: process.env.PATH,
+                HOME: process.env.HOME,
+              },
+              timeout: 5 * 60 * 1000,
+            },
+            async (err, stdout, stderr) => {
+              /**
+               * @param {string} content
+               * @param {string} type
+               * @returns {Promise<string>}
+               */
+              const formatOutput = async (content, type) => {
+                if (content.length <= OUTPUT_MAX_LENGTH) {
+                  return content;
+                }
+
+                let fileExtension = "txt";
+                try {
+                  JSON.parse(content);
+                  fileExtension = "json";
+                } catch {
+                  // not JSON
+                }
+
+                const prefix = `exec_command-${type}`;
+                const filePath = await writeTmpFile(
+                  content,
+                  prefix,
+                  fileExtension,
+                );
+                const lineCount = content.split("\n").length;
+
+                const head = content.slice(0, OUTPUT_TRUNCATED_LENGTH);
+                const tail = content.slice(
+                  Math.max(content.length - OUTPUT_TRUNCATED_LENGTH, 0),
+                );
+
+                return [
+                  `Content is too large (${content.length} characters, ${lineCount} lines). Saved to ${filePath}.`,
+                  `<truncated_output part="start" length="${OUTPUT_TRUNCATED_LENGTH}" total_length="${content.length}">\n${head}\n</truncated_output>`,
+                  `<truncated_output part="end" length="${OUTPUT_TRUNCATED_LENGTH}" total_length="${content.length}">\n${tail}</truncated_output>\n`,
+                ].join("\n\n");
+              };
+
+              const stdoutOrMessage = await formatOutput(stdout, "stdout");
+              const stderrOrMessage = await formatOutput(stderr, "stderr");
+
+              const result = [
+                stdoutOrMessage
+                  ? `<stdout>\n${stdoutOrMessage}</stdout>`
+                  : "<stdout></stdout>",
+                "",
+                stderrOrMessage
+                  ? `<stderr>\n${stderrOrMessage}</stderr>`
+                  : "<stderr></stderr>",
+              ];
+
+              if (err) {
+                // rg: 何もマッチしない場合は exit status != 0 になるので無視
+                const ignoreError = [command, ...(args || [])].includes("rg");
+                if (!ignoreError) {
+                  // err.message が長過ぎる場合は先頭を表示
+                  const errMessageTruncated = err.message.slice(
+                    0,
+                    OUTPUT_TRUNCATED_LENGTH,
+                  );
+                  const isErrMessageTruncated =
+                    err.message.length > OUTPUT_MAX_LENGTH;
+                  result.push(
+                    `\n<error>\n${err.name}: ${errMessageTruncated}${isErrMessageTruncated ? "... (Message truncated)" : ""}</error>`,
+                  );
+                }
+              }
+              return resolve(result.join("\n"));
+            },
+          );
+          child.stdin?.end();
+        });
+      }),
+  };
+}
+
+/**
+ * @param {ExecCommandInput} input
+ * @param {ExecCommandSanboxConfig} sandbox
+ * @returns {ExecCommandInput}
+ */
+function rewriteInputForSandbox(input, sandbox) {
+  const matchedRule = (sandbox.rules || []).find((rule) =>
+    matchValue(input, rule.pattern),
+  );
+
+  if (matchedRule?.mode === "unsandboxed") {
+    return input;
+  }
+
+  const args = [
+    ...(sandbox.args || []),
+    ...(matchedRule?.additionalArgs || []),
+  ];
+
+  if (sandbox.separator) {
+    args.push(sandbox.separator);
+  }
+
+  args.push(input.command);
+
+  if (input.args) {
+    args.push(...input.args);
+  }
+
+  return {
+    command: sandbox.command,
+    args,
+  };
+}

package/src/tools/patchFile.d.ts

@@ -0,0 +1,4 @@
+export type PatchFileInput = {
+  filePath: string;
+  diff: string;
+};

package/src/tools/patchFile.mjs

@@ -0,0 +1,133 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { PatchFileInput } from './patchFile'
+ */
+
+import fs from "node:fs/promises";
+import { noThrow } from "../utils/noThrow.mjs";
+
+/**
+ * @param {string} [nonce]
+ * @returns {Tool}
+ */
+export function createPatchFileTool(
+  nonce = Math.random().toString(36).substring(2, 5),
+) {
+  return {
+    def: {
+      name: "patch_file",
+      description:
+        "Modify a file by replacing specific content with new content.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filePath: {
+            type: "string",
+          },
+          diff: {
+            description: `
+Format:
+<<< ${nonce} <<< SEARCH
+old content
+=== ${nonce} ===
+new content
+>>> ${nonce} >>> REPLACE
+
+<<< ${nonce} <<< SEARCH
+other old content
+=== ${nonce} ===
+other new content
+>>> ${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",
+          },
+        },
+        required: ["filePath", "diff"],
+      },
+    },
+
+    /**
+     * @param {PatchFileInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) =>
+      await noThrow(async () => {
+        const { filePath, diff } = input;
+
+        // Validate marker counts: each block needs exactly one of each marker.
+        // Since nonce is random, duplicate markers mean the user accidentally
+        // included a marker line in their search/replace content (copy-paste error).
+        const searchMarker = `<<< ${nonce} <<< SEARCH`;
+        const sepMarker = `=== ${nonce} ===`;
+        const replaceMarker = `>>> ${nonce} >>> REPLACE`;
+        /** @type {(s: string, sub: string) => number} */
+        const count = (s, sub) => s.split(sub).length - 1;
+        const nSearch = count(diff, searchMarker);
+        const nSep = count(diff, sepMarker);
+        const nReplace = count(diff, replaceMarker);
+
+        if (nSearch !== nReplace) {
+          throw new Error(
+            `Mismatched block markers: found ${nSearch} "${searchMarker}" but ${nReplace} "${replaceMarker}". ` +
+              "Did you accidentally include a marker in your search/replace content?",
+          );
+        }
+        if (nSep !== nSearch) {
+          throw new Error(
+            `Each diff block needs exactly one "${sepMarker}" separator, ` +
+              `but found ${nSep} separators for ${nSearch} block(s). ` +
+              "Did you accidentally include the separator marker in your search/replace content?",
+          );
+        }
+
+        const content = await fs.readFile(filePath, "utf8");
+        const matches = Array.from(
+          diff.matchAll(
+            new RegExp(
+              `<<< ${nonce} <<< SEARCH\\n(.*?)\\n=== ${nonce} ===\\n(.*?)\\n?>>> ${nonce} >>> REPLACE`,
+              "gs",
+            ),
+          ),
+        );
+        if (matches.length === 0) {
+          throw new Error(
+            `Invalid diff format. Each markers must include the nonce: <<< ${nonce} <<< SEARCH, === ${nonce} ===, >>> ${nonce} >>> REPLACE`,
+          );
+        }
+        let newContent = content;
+        for (const match of matches) {
+          const [_, search, replace] = match;
+          if (!newContent.includes(search)) {
+            throw new Error(
+              JSON.stringify(`Search content not found: ${search}`),
+            );
+          }
+          // Escape $ characters in replacement string to prevent interpretation of $& $1 $$ patterns
+          const escapedReplace = replace.replace(/\$/g, "$$$$");
+          if (replace === "" && newContent.includes(`${search}\n`)) {
+            newContent = newContent.replace(`${search}\n`, "");
+          } else if (replace === "" && newContent.includes(`\n${search}`)) {
+            newContent = newContent.replace(`\n${search}`, "");
+          } else {
+            newContent = newContent.replace(search, escapedReplace);
+          }
+        }
+        await fs.writeFile(filePath, newContent);
+        return `Patched file: ${filePath}`;
+      }),
+
+    /**
+     * @param {Record<string, unknown>} input
+     * @returns {Record<string, unknown>}
+     */
+    maskApprovalInput: (input) => {
+      const patchFileInput = /** @type {PatchFileInput} */ (input);
+      return {
+        filePath: patchFileInput.filePath,
+      };
+    },
+  };
+}

package/src/tools/switchToMainAgent.d.ts

@@ -0,0 +1,3 @@
+export type SwitchToMainAgentInput = {
+  memoryPath: string;
+};

package/src/tools/switchToMainAgent.mjs

@@ -0,0 +1,43 @@
+/**
+ * @import { Tool, ToolImplementation } from '../tool'
+ */
+
+export const switchToMainAgentToolName = "switch_to_main_agent";
+
+/** @returns {Tool} */
+export function createSwitchToMainAgentTool() {
+  /** @type {ToolImplementation} */
+  let impl = async () => {
+    throw new Error("Not implemented");
+  };
+
+  /** @type {Tool} */
+  const tool = {
+    def: {
+      name: switchToMainAgentToolName,
+      description: "Switch back to the main agent role and report the result.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          memoryPath: {
+            type: "string",
+            description:
+              "Path to the memory file containing the result of the subagent's task.",
+          },
+        },
+        required: ["memoryPath"],
+      },
+    },
+
+    // Implementation will be injected by the agent to access its state
+    get impl() {
+      return impl;
+    },
+
+    injectImpl(fn) {
+      impl = fn;
+    },
+  };
+
+  return tool;
+}

package/src/tools/switchToSubagent.d.ts

@@ -0,0 +1,4 @@
+export type SwitchToSubagentInput = {
+  name: string;
+  goal: string;
+};

package/src/tools/switchToSubagent.mjs

@@ -0,0 +1,59 @@
+/**
+ * @import { Tool, ToolImplementation } from '../tool'
+ */
+
+export const switchToSubagentToolName = "switch_to_subagent";
+
+/** @returns {Tool} */
+export function createSwitchToSubagentTool() {
+  /** @type {ToolImplementation} */
+  let impl = async () => {
+    throw new Error("Not implemented");
+  };
+
+  /** @type {Tool} */
+  const tool = {
+    def: {
+      name: switchToSubagentToolName,
+      description:
+        "Switch to a subagent role within the same conversation, focusing on the specified goal. You inherit the current context.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description:
+              "Role or name of the subagent. Use 'custom:' prefix for ad-hoc roles.",
+          },
+          goal: {
+            type: "string",
+            description: "The goal or task for the subagent to achieve.",
+          },
+        },
+        required: ["name", "goal"],
+      },
+    },
+
+    // Implementation will be injected by the agent to access its state
+    get impl() {
+      return impl;
+    },
+
+    injectImpl(fn) {
+      impl = fn;
+    },
+
+    /**
+     * @param {Record<string, unknown>} input
+     * @returns {Record<string, unknown>}
+     */
+    maskApprovalInput: (input) => {
+      const { name } = /** @type {{name: string}} */ (input);
+      return {
+        name,
+      };
+    },
+  };
+
+  return tool;
+}

package/src/tools/tmuxCommand.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from "../tool";
+import type { ExecCommandSanboxConfig } from "./execCommand";
+
+export type TmuxCommandInput = {
+  command: string;
+  args?: string[];
+};
+
+export type TmuxCommandConfig = {
+  sandbox?: ExecCommandSanboxConfig;
+};
+
+export function createTmuxCommandTool(config?: TmuxCommandConfig): Tool;
+export const tmuxCommandTool: Tool;

package/src/tools/tmuxCommand.mjs

@@ -0,0 +1,194 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { TmuxCommandConfig, TmuxCommandInput } from './tmuxCommand'
+ */
+
+import { execFile } from "node:child_process";
+import { noThrow } from "../utils/noThrow.mjs";
+
+const OUTPUT_MAX_LENGTH = 1024 * 8;
+
+/**
++ * Sandbox-aware tmux command tool
++ * @param {TmuxCommandConfig=} config
++ * @returns {Tool}
++ */
+export function createTmuxCommandTool(config) {
+  /** @type {Tool} */
+  return {
+    def: {
+      name: "tmux_command",
+      description: "Run a tmux command",
+      inputSchema: {
+        type: "object",
+        properties: {
+          command: {
+            description: "The tmux command to run",
+            type: "string",
+          },
+          args: {
+            description: "Arguments to pass to the tmux command",
+            type: "array",
+            items: {
+              type: "string",
+            },
+          },
+        },
+        required: ["command"],
+      },
+    },
+
+    /**
+     * @param {TmuxCommandInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) =>
+      await noThrow(async () => {
+        const { command } = input;
+        const args = input.args || [];
+
+        // tmuxはセミコロンを複数コマンドの区切りとして扱うためエスケープが必要
+        // LLMがこのルールを無視するのでここでエスケープする
+        if (command === "send-keys") {
+          for (let i = 1; i < args.length; i++) {
+            const arg = args[i];
+            if (arg.endsWith(";") && !arg.endsWith("\\;")) {
+              args[i] = `${arg.slice(0, -1)}\\;`;
+            }
+          }
+        }
+
+        const execFileOptions = {
+          shell: false,
+          env: {
+            PWD: process.env.PWD,
+            PATH: process.env.PATH,
+            HOME: process.env.HOME,
+          },
+        };
+
+        /**
+         * @param {{command: string, args: string[]}} input
+         * @returns {{command: string, args: string[]}}
+         */
+        const useSandbox = ({ command, args }) => {
+          if (config?.sandbox) {
+            return {
+              command: config.sandbox.command,
+              args: [...(config.sandbox.args || []), command, ...args],
+            };
+          }
+          return { command, args };
+        };
+
+        const execFileTmuxCommandInput = useSandbox({
+          command: "tmux",
+          args: [command, ...args],
+        });
+
+        return new Promise((resolve, _reject) => {
+          execFile(
+            execFileTmuxCommandInput.command,
+            execFileTmuxCommandInput.args,
+            execFileOptions,
+            async (err, stdout, stderr) => {
+              // capture-pane の結果に空白の行が含まれることがあるためtrim する
+              const stdoutTruncated = stdout.trim().slice(-OUTPUT_MAX_LENGTH);
+              const isStdoutTruncated =
+                stdout.trim().length > OUTPUT_MAX_LENGTH;
+              const stderrTruncated = stderr.trim().slice(-OUTPUT_MAX_LENGTH);
+              const isStderrTruncated =
+                stderr.trim().length > OUTPUT_MAX_LENGTH;
+              const result = [
+                stdoutTruncated
+                  ? `<stdout>\n${isStdoutTruncated ? "(Output truncated) ..." : ""}${stdoutTruncated}\n</stdout>`
+                  : "<stdout></stdout>",
+                "",
+                stderrTruncated
+                  ? `<stderr>\n${isStderrTruncated ? "(Output truncated) ..." : ""}${stderrTruncated}\n</stderr>`
+                  : "<stderr></stderr>",
+              ];
+              if (err) {
+                const errMessageTruncated = err.message.slice(
+                  0,
+                  OUTPUT_MAX_LENGTH,
+                );
+                const isErrMessageTruncated =
+                  err.message.length > OUTPUT_MAX_LENGTH;
+                result.push(
+                  `\n<error>\n${err.name}: ${errMessageTruncated}${isErrMessageTruncated ? "... (Message truncated)" : ""}</error>`,
+                );
+              }
+
+              if (["new-session", "new", "new-window"].includes(command)) {
+                // show window list after creating a new session or window
+                const targetPosition = command.includes("window")
+                  ? args.indexOf("-t") + 1
+                  : args.indexOf("-s") + 1;
+                const target = args[targetPosition];
+
+                const execFileTmuxListWindowInput = useSandbox({
+                  command: "tmux",
+                  args: ["list-windows", "-t", target],
+                });
+                const listWindowResult = await new Promise(
+                  (resolve, _reject) => {
+                    execFile(
+                      execFileTmuxListWindowInput.command,
+                      execFileTmuxListWindowInput.args,
+                      execFileOptions,
+                      (err, stdout, _stderr) => {
+                        if (err) {
+                          console.error(
+                            `Failed to list tmux windows: ${err.message}, stack=${err.stack}`,
+                          );
+                        }
+                        return resolve(stdout);
+                      },
+                    );
+                  },
+                );
+                result.push(
+                  `\n<tmux:list-windows>\n${listWindowResult}</tmux:list-windows>`,
+                );
+              }
+
+              if (command === "send-keys") {
+                // capture the pane after sending keys
+                // wait for the command to be executed
+                await new Promise((resolve) => setTimeout(resolve, 2000));
+                const targetPosition = args.indexOf("-t") + 1;
+                const target = args[targetPosition];
+                const execFileTmuxCapturePaneInput = useSandbox({
+                  command: "tmux",
+                  args: ["capture-pane", "-p", "-t", target],
+                });
+                const captured = await new Promise((resolve, _reject) => {
+                  execFile(
+                    execFileTmuxCapturePaneInput.command,
+                    execFileTmuxCapturePaneInput.args,
+                    execFileOptions,
+                    (err, stdout, _stderr) => {
+                      if (err) {
+                        console.error(
+                          `Failed to capture tmux pane: ${err.message}, stack=${err.stack}`,
+                        );
+                      }
+                      return resolve(stdout.trim());
+                    },
+                  );
+                });
+                const capturedTruncated = captured.slice(-OUTPUT_MAX_LENGTH);
+                const isCapturedTruncated = captured.length > OUTPUT_MAX_LENGTH;
+                result.push(
+                  `\n<tmux:capture-pane target="${target}"">\n${isCapturedTruncated ? "(Output truncated) ..." : ""}${capturedTruncated}\n</tmux:capture-pane>`,
+                );
+              }
+
+              return resolve(result.join("\n"));
+            },
+          );
+        });
+      }),
+  };
+}

package/src/tools/writeFile.d.ts

@@ -0,0 +1,4 @@
+export type WriteFileInput = {
+  filePath: string;
+  content: string;
+};