@iinm/plain-agent 1.8.4 → 1.8.6

package/src/toolExecutor.mjs

@@ -0,0 +1,236 @@
+/**
+ * @import { MessageContentToolResult, MessageContentToolUse } from "./model"
+ * @import { Tool } from "./tool"
+ */
+
+/**
+ * @typedef {ReturnType<typeof createToolExecutor>} ToolExecutor
+ */
+
+/**
+ * @typedef {Object} ToolExecutorOptions
+ * @property {string[]} [exclusiveToolNames] - Tool names that must be called exclusively
+ */
+
+/**
+ * Create a tool executor that handles tool validation, execution, and error handling
+ * @param {Map<string, Tool>} toolByName - Map of tool names to tool implementations
+ * @param {ToolExecutorOptions} [options] - Configuration options
+ */
+export function createToolExecutor(toolByName, options = {}) {
+  const { exclusiveToolNames = [] } = options;
+
+  /**
+   * @typedef {ValidationSuccess | ValidationFailure} ValidationResult
+   */
+
+  /**
+   * @typedef {Object} ValidationSuccess
+   * @property {true} isValid
+   */
+
+  /**
+   * @typedef {Object} ValidationFailure
+   * @property {false} isValid
+   * @property {string} errorMessage
+   * @property {MessageContentToolResult[]} toolResults
+   */
+
+  /**
+   * Validate all tool uses (tool existence, input validation, exclusive tool check)
+   * @param {MessageContentToolUse[]} toolUseParts - Tool uses to validate
+   * @returns {ValidationResult}
+   */
+  function validateBatch(toolUseParts) {
+    // Tool existence + Input validation
+    /** @type {{index: number, message: string}[]} */
+    const errors = [];
+
+    for (let i = 0; i < toolUseParts.length; i++) {
+      const toolUse = toolUseParts[i];
+      const tool = toolByName.get(toolUse.toolName);
+      if (!tool) {
+        errors.push({
+          index: i,
+          message: `Tool not found: ${toolUse.toolName}`,
+        });
+        continue;
+      }
+
+      if (tool.validateInput) {
+        const result = tool.validateInput(toolUse.input);
+        if (result instanceof Error) {
+          errors.push({ index: i, message: result.message });
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      return {
+        isValid: false,
+        errorMessage: errors.map((e) => e.message).join("; "),
+        toolResults: toolUseParts.map((toolUse, index) => {
+          const error = errors.find((e) => e.index === index);
+          return {
+            type: "tool_result",
+            toolUseId: toolUse.toolUseId,
+            toolName: toolUse.toolName,
+            content: [
+              {
+                type: "text",
+                text: error
+                  ? error.message
+                  : "Tool call rejected due to other tool validation error",
+              },
+            ],
+            isError: true,
+          };
+        }),
+      };
+    }
+
+    // Exclusive tool validation
+    const exclusiveResult = validateExclusiveTools(toolUseParts);
+    if (!exclusiveResult.isValid) {
+      return {
+        isValid: false,
+        errorMessage: exclusiveResult.errorMessage,
+        toolResults: toolUseParts.map((t) => ({
+          type: "tool_result",
+          toolUseId: t.toolUseId,
+          toolName: t.toolName,
+          content: [{ type: "text", text: exclusiveResult.errorMessage }],
+          isError: true,
+        })),
+      };
+    }
+
+    return { isValid: true };
+  }
+
+  /**
+   * @typedef {ExecuteBatchSuccess | ExecuteBatchFailure} ExecuteBatchResult
+   */
+
+  /**
+   * @typedef {Object} ExecuteBatchSuccess
+   * @property {true} success - Execution succeeded
+   * @property {MessageContentToolResult[]} results - Tool results on success
+   */
+
+  /**
+   * @typedef {Object} ExecuteBatchFailure
+   * @property {false} success - Execution failed
+   * @property {MessageContentToolResult[]} errors - Error tool results on validation failure
+   * @property {string} errorMessage - Error message on validation failure
+   */
+
+  /**
+   * Validate and execute multiple tools
+   * @param {MessageContentToolUse[]} toolUseParts
+   * @returns {Promise<ExecuteBatchResult>}
+   */
+  async function executeBatch(toolUseParts) {
+    const validation = validateBatch(toolUseParts);
+
+    if (!validation.isValid) {
+      return {
+        success: false,
+        errors: /** @type {MessageContentToolResult[]} */ (
+          validation.toolResults
+        ),
+        errorMessage: /** @type {string} */ (validation.errorMessage),
+      };
+    }
+
+    const results = [];
+    for (const toolUse of toolUseParts) {
+      results.push(await execute(toolUse));
+    }
+
+    return {
+      success: true,
+      results,
+    };
+  }
+
+  /**
+   * Validate exclusive tool constraints
+   * @param {MessageContentToolUse[]} toolUseParts
+   * @returns {{isValid: true} | {isValid: false, errorMessage: string}}
+   */
+  function validateExclusiveTools(toolUseParts) {
+    const exclusiveTools = toolUseParts.filter((t) =>
+      exclusiveToolNames.includes(t.toolName),
+    );
+
+    if (exclusiveTools.length > 1) {
+      const toolNames = exclusiveTools.map((t) => t.toolName).join(", ");
+      return {
+        isValid: false,
+        errorMessage: `System: ${toolNames} cannot be called together. Only one of these tools can be called at a time.`,
+      };
+    }
+
+    if (exclusiveTools.length === 1 && toolUseParts.length > 1) {
+      return {
+        isValid: false,
+        errorMessage: `System: ${exclusiveTools[0].toolName} cannot be called with other tools. It must be called alone.`,
+      };
+    }
+
+    return { isValid: true };
+  }
+
+  /**
+   * Execute a tool use and return the result
+   * @param {MessageContentToolUse} toolUse
+   * @returns {Promise<MessageContentToolResult>}
+   */
+  async function execute(toolUse) {
+    const tool = toolByName.get(toolUse.toolName);
+    if (!tool) {
+      return {
+        type: "tool_result",
+        toolUseId: toolUse.toolUseId,
+        toolName: toolUse.toolName,
+        content: [
+          { type: "text", text: `Tool not found: ${toolUse.toolName}` },
+        ],
+        isError: true,
+      };
+    }
+
+    const result = await tool.impl(toolUse.input);
+    if (result instanceof Error) {
+      return {
+        type: "tool_result",
+        toolUseId: toolUse.toolUseId,
+        toolName: toolUse.toolName,
+        content: [{ type: "text", text: result.message }],
+        isError: true,
+      };
+    }
+
+    if (typeof result === "string") {
+      return {
+        type: "tool_result",
+        toolUseId: toolUse.toolUseId,
+        toolName: toolUse.toolName,
+        content: [{ type: "text", text: result }],
+      };
+    }
+
+    return {
+      type: "tool_result",
+      toolUseId: toolUse.toolUseId,
+      toolName: toolUse.toolName,
+      content: result,
+    };
+  }
+
+  return {
+    executeBatch,
+    validateBatch,
+  };
+}

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,99 @@
+/**
+ * @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: defaultAction };
+      }
+
+      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,
+  };
+}