@iinm/plain-agent 1.0.0

package/src/tools/fetchWebPage.mjs

@@ -0,0 +1,96 @@
+/**
+ * @import { Tool } from '../tool'
+ */
+
+import { writeTmpFile } from "../tmpfile.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+const MAX_CONTENT_LENGTH = 1024 * 8;
+
+/** @type {Tool} */
+export const fetchWebPageTool = {
+  def: {
+    name: "fetch_web_page",
+    description:
+      "Fetch and extract web page content from a given URL, returning it as Markdown.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+        },
+      },
+      required: ["url"],
+    },
+  },
+
+  /**
+   * @param {Record<string, unknown>} input
+   * @returns {Record<string, unknown>}
+   */
+  maskApprovalInput: (input) => {
+    try {
+      const url = new URL(String(input.url));
+      return { url: url.hostname };
+    } catch {
+      return input;
+    }
+  },
+
+  /**
+   * @param {{url: string}} input
+   * @returns {Promise<string | Error>}
+   */
+  impl: async (input) =>
+    await noThrow(async () => {
+      const { Readability } = await import("@mozilla/readability");
+      const { JSDOM } = await import("jsdom");
+      const TurndownService = (await import("turndown")).default;
+
+      const response = await fetch(input.url, {
+        signal: AbortSignal.timeout(30 * 1000),
+      });
+      const html = await response.text();
+      const dom = new JSDOM(html, { url: input.url });
+      const reader = new Readability(dom.window.document);
+      const article = reader.parse();
+
+      if (!article?.content) {
+        return "";
+      }
+
+      const turndownService = new TurndownService({
+        headingStyle: "atx",
+        bulletListMarker: "-",
+        codeBlockStyle: "fenced",
+      });
+
+      const markdown = turndownService.turndown(article.content);
+      const trimmedMarkdown = markdown.trim();
+
+      if (trimmedMarkdown.length <= MAX_CONTENT_LENGTH) {
+        return trimmedMarkdown;
+      }
+
+      const filePath = await writeTmpFile(
+        trimmedMarkdown,
+        "read_web_page",
+        "md",
+      );
+
+      const lineCount = trimmedMarkdown.split("\n").length;
+
+      return [
+        `Content is large (${trimmedMarkdown.length} characters, ${lineCount} lines) and saved to ${filePath}`,
+        "- Use rg / awk to read specific parts",
+      ].join("\n");
+    }),
+};
+
+// Playground
+// (async () => {
+//   const input = {
+//     url: "https://devin.ai/agents101",
+//   };
+//   console.log(await fetchWebPageTool.impl(input));
+// })();

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,96 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { PatchFileInput } from './patchFile'
+ */
+
+import fs from "node:fs/promises";
+import { noThrow } from "../utils/noThrow.mjs";
+
+/** @type {Tool} */
+export const patchFileTool = {
+  def: {
+    name: "patch_file",
+    description:
+      "Modify a file by replacing specific content with new content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: {
+          type: "string",
+        },
+        diff: {
+          description: `
+- Content is searched as an exact match including indentation and line breaks.
+- The first match found will be replaced if there are multiple matches.
+- Use multiple SEARCH/REPLACE blocks to replace multiple contents.
+
+Format:
+<<<<<<< SEARCH
+old content
+=======
+new content
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+other old content
+=======
+other new content
+>>>>>>> REPLACE
+          `.trim(),
+          type: "string",
+        },
+      },
+      required: ["filePath", "diff"],
+    },
+  },
+
+  /**
+   * @param {PatchFileInput} input
+   * @returns {Promise<string | Error>}
+   */
+  impl: async (input) =>
+    await noThrow(async () => {
+      const { filePath, diff } = input;
+
+      const content = await fs.readFile(filePath, "utf8");
+      const matches = Array.from(
+        diff.matchAll(
+          /<<<<<<< SEARCH\n(.*?)\n?=======\n(.*?)\n?>>>>>>> REPLACE/gs,
+        ),
+      );
+      if (matches.length === 0) {
+        throw new Error("No matches found in diff.");
+      }
+      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/reportAsSubagent.d.ts

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

package/src/tools/reportAsSubagent.mjs

@@ -0,0 +1,44 @@
+/**
+ * @import { Tool, ToolImplementation } from '../tool'
+ */
+
+export const reportAsSubagentToolName = "report_as_subagent";
+
+/** @returns {Tool} */
+export function createReportAsSubagentTool() {
+  /** @type {ToolImplementation} */
+  let impl = async () => {
+    throw new Error("Not implemented");
+  };
+
+  /** @type {Tool} */
+  const tool = {
+    def: {
+      name: reportAsSubagentToolName,
+      description:
+        "End the subagent role and report the result to the main agent.",
+      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/tavilySearch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @doc https://docs.tavily.com/documentation/api-reference/endpoint/search
+ */
+export type TavilySearchInput = {
+  query: string;
+};

package/src/tools/tavilySearch.mjs

@@ -0,0 +1,57 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { TavilySearchInput } from './tavilySearch'
+ */
+
+import { noThrow } from "../utils/noThrow.mjs";
+
+/**
+ * @param {{apiKey?: string}} config
+ * @returns {Tool}
+ */
+export function createTavilySearchTool(config) {
+  return {
+    def: {
+      name: "search_web",
+      description: "Search the web for information",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+          },
+        },
+        required: ["query"],
+      },
+    },
+
+    /**
+     * @param {TavilySearchInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) =>
+      await noThrow(async () => {
+        const response = await fetch("https://api.tavily.com/search", {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            ...input,
+            max_results: 5,
+          }),
+          signal: AbortSignal.timeout(120 * 1000),
+        });
+
+        if (!response.ok) {
+          return new Error(
+            `Failed to search: status=${response.status}, body=${await response.text()}`,
+          );
+        }
+
+        const body = await response.json();
+        return JSON.stringify(body);
+      }),
+  };
+}

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

package/src/tools/writeFile.mjs

@@ -0,0 +1,56 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { WriteFileInput } from './writeFile'
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { noThrow } from "../utils/noThrow.mjs";
+
+/** @type {Tool} */
+export const writeFileTool = {
+  def: {
+    name: "write_file",
+    description: "Write a file",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: {
+          type: "string",
+        },
+        content: {
+          type: "string",
+        },
+      },
+      required: ["filePath", "content"],
+    },
+  },
+
+  /**
+   * @param {WriteFileInput} input
+   * @returns {Promise<string | Error>}
+   */
+  impl: async (input) =>
+    await noThrow(async () => {
+      const { filePath, content } = input;
+
+      const absFilePath = path.resolve(filePath);
+
+      // Ensure the destination directory exists before writing
+      const dir = path.dirname(absFilePath);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(absFilePath, content, "utf8");
+      return `Wrote to file: ${filePath}`;
+    }),
+
+  /**
+   * @param {Record<string, unknown>} input
+   * @returns {Record<string, unknown>}
+   */
+  maskApprovalInput: (input) => {
+    const writeFileInput = /** @type {WriteFileInput} */ (input);
+    return {
+      filePath: writeFileInput.filePath,
+    };
+  },
+};

package/src/utils/evalJSONConfig.mjs

@@ -0,0 +1,48 @@
+/**
+ * @param {unknown} configItem
+ * @returns {unknown}
+ */
+export function evalJSONConfig(configItem) {
+  if (Array.isArray(configItem)) {
+    return configItem.map((item) => evalJSONConfig(item));
+  }
+
+  if (typeof configItem === "object" && configItem !== null) {
+    if (
+      Object.keys(configItem).length === 1 &&
+      "$regex" in configItem &&
+      typeof configItem.$regex === "string"
+    ) {
+      return new RegExp(configItem.$regex);
+    }
+
+    if (Object.keys(configItem).length === 1 && "$has" in configItem) {
+      const pattern = evalJSONConfig(configItem.$has);
+      /** @param {unknown} value */
+      return (value) => {
+        if (!Array.isArray(value)) return false;
+        return value.some((item) => {
+          if (typeof pattern === "string") {
+            return item === pattern;
+          }
+          if (pattern instanceof RegExp) {
+            return typeof item === "string" && pattern.test(item);
+          }
+          if (typeof pattern === "function") {
+            return pattern(item);
+          }
+          return false;
+        });
+      };
+    }
+
+    /** @type {Record<string,unknown>} */
+    const clone = {};
+    for (const [k, v] of Object.entries(configItem)) {
+      clone[k] = evalJSONConfig(v);
+    }
+    return clone;
+  }
+
+  return configItem;
+}

package/src/utils/matchValue.d.ts

@@ -0,0 +1,6 @@
+export type ValuePattern =
+  | string
+  | RegExp
+  | ((value: unknown) => boolean)
+  | ValuePattern[]
+  | { [key: string]: ValuePattern };

package/src/utils/matchValue.mjs

@@ -0,0 +1,40 @@
+/**
+ * @import { ValuePattern } from "./matchValue"
+ */
+
+/**
+ * @param {unknown} value
+ * @param {ValuePattern} pattern
+ * @returns {boolean}
+ */
+export function matchValue(value, pattern) {
+  if (typeof pattern === "string") {
+    return typeof value === "string" && value === pattern;
+  }
+
+  if (pattern instanceof RegExp) {
+    return typeof value === "string" && pattern.test(value);
+  }
+
+  if (typeof pattern === "function") {
+    return pattern(value);
+  }
+
+  if (Array.isArray(pattern)) {
+    return (
+      Array.isArray(value) && pattern.every((p, i) => matchValue(value[i], p))
+    );
+  }
+
+  if (typeof pattern === "object") {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      Object.entries(pattern).every(([k, p]) =>
+        matchValue(value[/** @type {keyof value} */ (k)], p),
+      )
+    );
+  }
+
+  return false;
+}