@iinm/plain-agent 1.0.0

package/src/toolInputValidator.mjs

@@ -0,0 +1,183 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  AGENT_MEMORY_DIR,
+  AGENT_TMP_DIR,
+  CLAUDE_CODE_PLUGIN_DIR,
+} from "./env.mjs";
+import { noThrowSync } from "./utils/noThrow.mjs";
+
+/**
+ * @param {unknown} input
+ * @returns {boolean}
+ */
+export function isSafeToolInput(input) {
+  if (["number", "boolean", "undefined"].includes(typeof input)) {
+    return true;
+  }
+
+  if (typeof input === "string") {
+    return isSafeToolInputItem(input);
+  }
+
+  if (Array.isArray(input)) {
+    return input.every((item) => isSafeToolInput(item));
+  }
+
+  if (typeof input === "object") {
+    if (input === null) {
+      return true;
+    }
+    return Object.values(input).every((value) => isSafeToolInput(value));
+  }
+
+  return false;
+}
+
+/**
+ * @param {string} arg
+ * @returns {boolean}
+ */
+export function isSafeToolInputItem(arg) {
+  const workingDir = process.cwd();
+
+  // Note: An argument can be a command option (e.g., '-l').
+  // It will then create an absolute path like `/path/to/project/-l`.
+  const absPath = path.resolve(arg);
+
+  const realPath = resolveRealPath(absPath, workingDir);
+  if (!realPath) {
+    return false;
+  }
+
+  // Disallow paths outside the working directory (WITHOUT EXCEPTION)
+  if (!isInsideWorkingDirectory(realPath, workingDir)) {
+    return false;
+  }
+
+  // Disallow any input that contains ".." as a path segment (directory traversal)
+  // Example:
+  // - When write_file is allowed for ^safe-dir/.+
+  // - "safe-dir/../unsafe-path" should be disallowed
+  if (arg.split(path.sep).includes("..")) {
+    return false;
+  }
+
+  // Allow safe path even if git-ignored.
+  if (isSafePath(realPath)) {
+    return true;
+  }
+
+  // Deny git ignored files (which may contain sensitive information or should not be accessed)
+  return !isGitIgnored(realPath);
+}
+
+/**
+ * @param {string} absPath
+ * @param {string} workingDir
+ * @returns {string | null}
+ */
+function resolveRealPath(absPath, workingDir) {
+  const realPathResult = noThrowSync(() => fs.realpathSync(absPath));
+  if (!(realPathResult instanceof Error)) {
+    return realPathResult;
+  }
+
+  // realpathSync can fail if the path (or its target) doesn't exist.
+  // Manually follow symlink chain for broken links to ensure they don't point outside.
+  let currentPath = absPath;
+  const seen = new Set();
+  const MAX_SYMLINK_DEPTH = 10;
+
+  for (let depth = 0; depth < MAX_SYMLINK_DEPTH; depth++) {
+    if (seen.has(currentPath)) {
+      return null; // Circular link
+    }
+    seen.add(currentPath);
+
+    // Check if the current path is a symbolic link.
+    const lstats = noThrowSync(() => fs.lstatSync(currentPath));
+    if (lstats instanceof Error || !lstats.isSymbolicLink()) {
+      break; // Not a symlink or doesn't exist; stop traversal.
+    }
+
+    // Read the target path the symlink points to.
+    const target = noThrowSync(() => fs.readlinkSync(currentPath));
+    if (typeof target !== "string") {
+      break; // Failed to read the link; stop traversal.
+    }
+
+    currentPath = path.resolve(path.dirname(currentPath), target);
+
+    // If at any point it goes outside, we stop and use this path for the check.
+    if (!isInsideWorkingDirectory(currentPath, workingDir)) {
+      return currentPath;
+    }
+  }
+
+  if (seen.size >= MAX_SYMLINK_DEPTH) {
+    return null; // Too deep
+  }
+
+  return currentPath;
+}
+
+/**
+ * @param {string} targetPath
+ * @param {string} workingDir
+ * @returns {boolean}
+ */
+function isInsideWorkingDirectory(targetPath, workingDir) {
+  return (
+    targetPath === workingDir ||
+    targetPath.startsWith(`${workingDir}${path.sep}`)
+  );
+}
+
+/**
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+function isSafePath(targetPath) {
+  const safePaths = [AGENT_MEMORY_DIR, AGENT_TMP_DIR, CLAUDE_CODE_PLUGIN_DIR];
+
+  for (const safePath of safePaths) {
+    const safeAbsPath = path.resolve(safePath);
+    if (
+      targetPath === safeAbsPath ||
+      targetPath.startsWith(`${safeAbsPath}${path.sep}`)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * @param {string} absPath
+ * @returns {boolean}
+ */
+function isGitIgnored(absPath) {
+  try {
+    execFileSync("git", ["check-ignore", "--no-index", "-q", absPath], {
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    // The path is ignored (exit code 0)
+    return true;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "status" in error &&
+      typeof error.status === "number" &&
+      error.status === 1
+    ) {
+      // Path is not ignored
+      return false;
+    }
+    // Other errors (e.g., status 128 if not a git repo or other git error)
+    // We treat this as "effectively ignored" to be safe.
+    return true;
+  }
+}

package/src/toolUseApprover.mjs

@@ -0,0 +1,98 @@
+/**
+ * @import { ToolUseApprover, ToolUseApproverConfig, ToolUseDecision, ToolUsePattern } from './tool'
+ * @import { MessageContentToolUse } from './model'
+ */
+
+import { isSafeToolInput } from "./toolInputValidator.mjs";
+import { matchValue } from "./utils/matchValue.mjs";
+
+/**
+ * @param {ToolUseApproverConfig} config
+ * @returns {ToolUseApprover}
+ */
+export function createToolUseApprover({
+  patterns,
+  maxApprovals: max,
+  defaultAction,
+  maskApprovalInput,
+}) {
+  const state = {
+    approvalCount: 0,
+    /** @type {ToolUsePattern[]} */
+    allowedToolUseInSession: [],
+  };
+
+  /** @returns {void} */
+  function resetApprovalCount() {
+    state.approvalCount = 0;
+  }
+
+  /**
+   * @param {MessageContentToolUse} toolUse
+   * @returns {ToolUseDecision}
+   */
+  function isAllowedToolUse(toolUse) {
+    const toolUseToMatch = {
+      toolName: toolUse.toolName,
+      input: toolUse.input,
+    };
+
+    for (const pattern of [...patterns, ...state.allowedToolUseInSession]) {
+      const patternToMatch = {
+        toolName: pattern.toolName,
+        ...(pattern.input !== undefined && { input: pattern.input }),
+      };
+
+      if (!matchValue(toolUseToMatch, patternToMatch)) {
+        continue;
+      }
+
+      const action = pattern.action ?? defaultAction;
+
+      if (!["allow", "deny", "ask"].includes(action)) {
+        return {
+          action: "ask",
+        };
+      }
+
+      if (action === "deny") {
+        return {
+          action: "deny",
+          reason: pattern.reason,
+        };
+      }
+
+      if (action === "allow") {
+        const maskedInput = maskApprovalInput(toolUse.toolName, toolUse.input);
+        if (isSafeToolInput(maskedInput)) {
+          state.approvalCount += 1;
+          return state.approvalCount <= max
+            ? { action: "allow" }
+            : { action: "ask" };
+        }
+      }
+
+      return { action };
+    }
+
+    return { action: defaultAction };
+  }
+
+  /**
+   * @param {MessageContentToolUse} toolUse
+   * @returns {void}
+   */
+  function allowToolUse(toolUse) {
+    state.allowedToolUseInSession.push({
+      toolName: toolUse.toolName,
+      input: maskApprovalInput(toolUse.toolName, toolUse.input),
+      action: "allow",
+    });
+  }
+
+  return {
+    isAllowedToolUse,
+    allowToolUse,
+    resetApprovalCount,
+  };
+}

package/src/tools/askGoogle.mjs

@@ -0,0 +1,135 @@
+/**
+ * @import { Tool } from '../tool'
+ */
+
+import { styleText } from "node:util";
+import { getGoogleCloudAccessToken } from "../providers/platform/googleCloud.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+/**
+ * @typedef {Object} AskGoogleToolOptions
+ * @property {"vertex-ai"=} platform
+ * @property {string=} baseURL
+ * @property {string=} apiKey - API key for Google AI Studio
+ * @property {string=} account - The Google Cloud account to use for Vertex AI
+ * @property {string=} model
+ */
+
+/**
+ * @typedef {Object} AskGoogleInput
+ * @property {string} question
+ */
+
+/**
+ * @param {AskGoogleToolOptions} config
+ * @returns {Tool}
+ */
+export function createAskGoogleTool(config) {
+  /**
+   * @param {AskGoogleInput} input
+   * @param {number} retryCount
+   * @returns {Promise<string | Error>}
+   */
+  async function askGoogle(input, retryCount = 0) {
+    const model = config.model ?? "gemini-3-flash-preview";
+    const url =
+      config.platform === "vertex-ai" && config.baseURL
+        ? `${config.baseURL}/publishers/google/models/${model}:generateContent`
+        : config.baseURL
+          ? `${config.baseURL}/models/${model}:generateContent`
+          : `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+
+    /** @type {Record<string,string>} */
+    const authHeader =
+      config.platform === "vertex-ai"
+        ? {
+            Authorization: `Bearer ${await getGoogleCloudAccessToken(config.account)}`,
+          }
+        : {
+            "x-goog-api-key": config.apiKey ?? "",
+          };
+
+    const data = {
+      contents: [
+        {
+          role: "user",
+          parts: [
+            {
+              text: `I need a comprehensive answer to this question. Please note that I don't have access to external URLs, so include all relevant facts, data, or explanations directly in your response. Avoid referencing links I can't open.
+
+Question: ${input.question}`,
+            },
+          ],
+        },
+      ],
+      tools: [
+        {
+          google_search: {},
+        },
+      ],
+    };
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        ...authHeader,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(data),
+      signal: AbortSignal.timeout(120 * 1000),
+    });
+
+    if (response.status === 429 || response.status >= 500) {
+      const interval = Math.min(2 * 2 ** retryCount, 16);
+      console.error(
+        styleText(
+          "yellow",
+          `Google API returned ${response.status}. Retrying in ${interval} seconds...`,
+        ),
+      );
+      await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+      return askGoogle(input, retryCount + 1);
+    }
+
+    if (!response.ok) {
+      return new Error(
+        `Failed to ask Google: status=${response.status}, body=${await response.text()}`,
+      );
+    }
+
+    const body = await response.json();
+
+    const answer = body.candidates?.[0]?.content?.parts?.[0]?.text;
+
+    if (typeof answer !== "string") {
+      return new Error(
+        `Unexpected response format from Google: ${JSON.stringify(body)}`,
+      );
+    }
+
+    return answer;
+  }
+
+  return {
+    def: {
+      name: "ask_google",
+      description: "Ask Google a question using natural language",
+      inputSchema: {
+        type: "object",
+        properties: {
+          question: {
+            type: "string",
+            description: "The question to ask Google",
+          },
+        },
+        required: ["question"],
+      },
+    },
+
+    /**
+     * @param {AskGoogleInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) => await noThrow(async () => askGoogle(input, 0)),
+  };
+}

package/src/tools/delegateToSubagent.d.ts

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

package/src/tools/delegateToSubagent.mjs

@@ -0,0 +1,48 @@
+/**
+ * @import { Tool, ToolImplementation } from '../tool'
+ */
+
+export const delegateToSubagentToolName = "delegate_to_subagent";
+
+/** @returns {Tool} */
+export function createDelegateToSubagentTool() {
+  /** @type {ToolImplementation} */
+  let impl = async () => {
+    throw new Error("Not implemented");
+  };
+
+  /** @type {Tool} */
+  const tool = {
+    def: {
+      name: delegateToSubagentToolName,
+      description:
+        "Delegate a subtask to a subagent. You inherit the current context and work on the delegated goal.",
+      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;
+    },
+  };
+
+  return tool;
+}

package/src/tools/execCommand.d.ts

@@ -0,0 +1,22 @@
+export type ExecCommandInput = {
+  command: string;
+  args?: string[];
+};
+
+export type ExecCommandConfig = {
+  sandbox?: ExecCommandSanboxConfig;
+};
+
+export type ExecCommandSanboxConfig = {
+  command: string;
+  args?: string[];
+  separator?: string;
+  rules?: {
+    pattern: {
+      command: string;
+      args?: string[];
+    };
+    mode: "sandbox" | "unsandboxed";
+    additionalArgs?: string[];
+  }[];
+};

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