@modelrelay/sdk 1.25.0 → 1.28.0

package/dist/node.cjs

@@ -0,0 +1,878 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/node.ts
+var node_exports = {};
+__export(node_exports, {
+  DEFAULT_IGNORE_DIRS: () => DEFAULT_IGNORE_DIRS,
+  FSDefaults: () => FSDefaults,
+  FSToolNames: () => ToolNames,
+  LocalFSToolPack: () => LocalFSToolPack,
+  createLocalFSToolPack: () => createLocalFSToolPack,
+  createLocalFSTools: () => createLocalFSTools
+});
+module.exports = __toCommonJS(node_exports);
+
+// src/tools_local_fs.ts
+var import_fs = require("fs");
+var path = __toESM(require("path"), 1);
+var import_child_process = require("child_process");
+
+// package.json
+var package_default = {
+  name: "@modelrelay/sdk",
+  version: "1.28.0",
+  description: "TypeScript SDK for the ModelRelay API",
+  type: "module",
+  main: "dist/index.cjs",
+  module: "dist/index.js",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      require: "./dist/index.cjs"
+    },
+    "./node": {
+      types: "./dist/node.d.ts",
+      import: "./dist/node.js",
+      require: "./dist/node.cjs"
+    }
+  },
+  publishConfig: {
+    access: "public"
+  },
+  files: [
+    "dist"
+  ],
+  scripts: {
+    build: "tsup src/index.ts src/node.ts --format esm,cjs --dts --external playwright",
+    dev: "tsup src/index.ts src/node.ts --format esm,cjs --dts --watch",
+    lint: "tsc --noEmit --project tsconfig.lint.json",
+    test: "vitest run",
+    "generate:types": "openapi-typescript ../../api/openapi/api.json -o src/generated/api.ts"
+  },
+  keywords: [
+    "modelrelay",
+    "llm",
+    "sdk",
+    "typescript"
+  ],
+  author: "Shane Vitarana",
+  license: "Apache-2.0",
+  dependencies: {
+    "fast-json-patch": "^3.1.1",
+    zod: "^3.23.0"
+  },
+  peerDependencies: {
+    playwright: ">=1.40.0"
+  },
+  peerDependenciesMeta: {
+    playwright: {
+      optional: true
+    }
+  },
+  devDependencies: {
+    "@types/node": "^25.0.3",
+    "openapi-typescript": "^7.4.4",
+    playwright: "^1.49.0",
+    tsup: "^8.2.4",
+    typescript: "^5.6.3",
+    vitest: "^2.1.4"
+  }
+};
+
+// src/types.ts
+var SDK_VERSION = package_default.version || "0.0.0";
+var DEFAULT_CLIENT_HEADER = `modelrelay-ts/${SDK_VERSION}`;
+
+// src/errors.ts
+var ModelRelayError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    this.name = this.constructor.name;
+    this.category = opts.category;
+    this.status = opts.status;
+    this.code = opts.code;
+    this.requestId = opts.requestId;
+    this.fields = opts.fields;
+    this.data = opts.data;
+    this.retries = opts.retries;
+    this.cause = opts.cause;
+  }
+};
+var ToolArgumentError = class extends ModelRelayError {
+  constructor(opts) {
+    super(opts.message, {
+      category: "config",
+      status: 400,
+      cause: opts.cause
+    });
+    this.toolCallId = opts.toolCallId;
+    this.toolName = opts.toolName;
+    this.rawArguments = opts.rawArguments;
+  }
+};
+var PathEscapeError = class extends ModelRelayError {
+  constructor(opts) {
+    super(`path escapes sandbox: ${opts.requestedPath}`, {
+      category: "config",
+      status: 403
+    });
+    this.requestedPath = opts.requestedPath;
+    this.resolvedPath = opts.resolvedPath;
+  }
+};
+
+// src/tools.ts
+function toolResultMessage(toolCallId, result) {
+  const content = typeof result === "string" ? result : JSON.stringify(result);
+  return {
+    type: "message",
+    role: "tool",
+    toolCallId,
+    content: [{ type: "text", text: content }]
+  };
+}
+var ToolArgsError = class extends Error {
+  constructor(message, toolCallId, toolName, rawArguments) {
+    super(message);
+    this.name = "ToolArgsError";
+    this.toolCallId = toolCallId;
+    this.toolName = toolName;
+    this.rawArguments = rawArguments;
+  }
+};
+var ToolRegistry = class {
+  constructor() {
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Registers a handler function for a tool name.
+   * @param name - The tool name (must match the function name in the tool definition)
+   * @param handler - Function to execute when this tool is called
+   * @returns this for chaining
+   */
+  register(name, handler) {
+    this.handlers.set(name, handler);
+    return this;
+  }
+  /**
+   * Unregisters a tool handler.
+   * @param name - The tool name to unregister
+   * @returns true if the handler was removed, false if it didn't exist
+   */
+  unregister(name) {
+    return this.handlers.delete(name);
+  }
+  /**
+   * Checks if a handler is registered for the given tool name.
+   */
+  has(name) {
+    return this.handlers.has(name);
+  }
+  /**
+   * Returns the list of registered tool names.
+   */
+  getRegisteredTools() {
+    return Array.from(this.handlers.keys());
+  }
+  /**
+   * Executes a single tool call.
+   * @param call - The tool call to execute
+   * @returns The execution result
+   */
+  async execute(call) {
+    const toolName = call.function?.name ?? "";
+    const handler = this.handlers.get(toolName);
+    if (!handler) {
+      return {
+        toolCallId: call.id,
+        toolName,
+        result: null,
+        error: `Unknown tool: '${toolName}'. Available tools: ${this.getRegisteredTools().join(", ") || "none"}`
+      };
+    }
+    let args;
+    try {
+      args = call.function?.arguments ? JSON.parse(call.function.arguments) : {};
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        toolCallId: call.id,
+        toolName,
+        result: null,
+        error: `Invalid JSON in arguments: ${errorMessage}`,
+        isRetryable: true
+      };
+    }
+    try {
+      const result = await handler(args, call);
+      return {
+        toolCallId: call.id,
+        toolName,
+        result
+      };
+    } catch (err) {
+      const isRetryable = err instanceof ToolArgsError || err instanceof ToolArgumentError;
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        toolCallId: call.id,
+        toolName,
+        result: null,
+        error: errorMessage,
+        isRetryable
+      };
+    }
+  }
+  /**
+   * Executes multiple tool calls in parallel.
+   * @param calls - Array of tool calls to execute
+   * @returns Array of execution results in the same order as input
+   */
+  async executeAll(calls) {
+    return Promise.all(calls.map((call) => this.execute(call)));
+  }
+  /**
+   * Converts execution results to tool result messages.
+   * Useful for appending to the conversation history.
+   * @param results - Array of execution results
+   * @returns Array of tool result input items (role "tool")
+   */
+  resultsToMessages(results) {
+    return results.map((r) => {
+      const content = r.error ? `Error: ${r.error}` : typeof r.result === "string" ? r.result : JSON.stringify(r.result);
+      return toolResultMessage(r.toolCallId, content);
+    });
+  }
+};
+
+// src/tools_local_fs.ts
+var ToolNames = {
+  FS_READ_FILE: "fs.read_file",
+  FS_LIST_FILES: "fs.list_files",
+  FS_SEARCH: "fs.search"
+};
+var FSDefaults = {
+  MAX_READ_BYTES: 64e3,
+  HARD_MAX_READ_BYTES: 1e6,
+  MAX_LIST_ENTRIES: 2e3,
+  HARD_MAX_LIST_ENTRIES: 2e4,
+  MAX_SEARCH_MATCHES: 100,
+  HARD_MAX_SEARCH_MATCHES: 2e3,
+  SEARCH_TIMEOUT_MS: 5e3,
+  MAX_SEARCH_BYTES_PER_FILE: 1e6
+};
+var DEFAULT_IGNORE_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  ".next",
+  "target",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".pytest_cache",
+  "coverage"
+]);
+var LocalFSToolPack = class {
+  constructor(options) {
+    this.rgPath = null;
+    this.rgChecked = false;
+    const root = options.root?.trim();
+    if (!root) {
+      throw new Error("LocalFSToolPack: root directory required");
+    }
+    this.rootAbs = path.resolve(root);
+    this.cfg = {
+      ignoreDirs: options.ignoreDirs ?? new Set(DEFAULT_IGNORE_DIRS),
+      maxReadBytes: options.maxReadBytes ?? FSDefaults.MAX_READ_BYTES,
+      hardMaxReadBytes: options.hardMaxReadBytes ?? FSDefaults.HARD_MAX_READ_BYTES,
+      maxListEntries: options.maxListEntries ?? FSDefaults.MAX_LIST_ENTRIES,
+      hardMaxListEntries: options.hardMaxListEntries ?? FSDefaults.HARD_MAX_LIST_ENTRIES,
+      maxSearchMatches: options.maxSearchMatches ?? FSDefaults.MAX_SEARCH_MATCHES,
+      hardMaxSearchMatches: options.hardMaxSearchMatches ?? FSDefaults.HARD_MAX_SEARCH_MATCHES,
+      searchTimeoutMs: options.searchTimeoutMs ?? FSDefaults.SEARCH_TIMEOUT_MS,
+      maxSearchBytesPerFile: options.maxSearchBytesPerFile ?? FSDefaults.MAX_SEARCH_BYTES_PER_FILE
+    };
+  }
+  /**
+   * Returns the tool definitions for LLM requests.
+   * Use these when constructing the tools array for /responses requests.
+   */
+  getToolDefinitions() {
+    return [
+      {
+        type: "function",
+        function: {
+          name: ToolNames.FS_READ_FILE,
+          description: "Read the contents of a file. Returns the file contents as UTF-8 text.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: {
+                type: "string",
+                description: "Workspace-relative path to the file (e.g., 'src/index.ts')"
+              },
+              max_bytes: {
+                type: "integer",
+                description: `Maximum bytes to read. Default: ${this.cfg.maxReadBytes}, max: ${this.cfg.hardMaxReadBytes}`
+              }
+            },
+            required: ["path"]
+          }
+        }
+      },
+      {
+        type: "function",
+        function: {
+          name: ToolNames.FS_LIST_FILES,
+          description: "List files recursively in a directory. Returns newline-separated workspace-relative paths.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: {
+                type: "string",
+                description: "Workspace-relative directory path. Default: '.' (workspace root)"
+              },
+              max_entries: {
+                type: "integer",
+                description: `Maximum files to list. Default: ${this.cfg.maxListEntries}, max: ${this.cfg.hardMaxListEntries}`
+              }
+            }
+          }
+        }
+      },
+      {
+        type: "function",
+        function: {
+          name: ToolNames.FS_SEARCH,
+          description: "Search for text matching a regex pattern. Returns matches as 'path:line:content' format.",
+          parameters: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Regex pattern to search for"
+              },
+              path: {
+                type: "string",
+                description: "Workspace-relative directory to search. Default: '.' (workspace root)"
+              },
+              max_matches: {
+                type: "integer",
+                description: `Maximum matches to return. Default: ${this.cfg.maxSearchMatches}, max: ${this.cfg.hardMaxSearchMatches}`
+              }
+            },
+            required: ["query"]
+          }
+        }
+      }
+    ];
+  }
+  /**
+   * Registers handlers into an existing ToolRegistry.
+   * @param registry - The registry to register into
+   * @returns The registry for chaining
+   */
+  registerInto(registry) {
+    registry.register(ToolNames.FS_READ_FILE, this.readFile.bind(this));
+    registry.register(ToolNames.FS_LIST_FILES, this.listFiles.bind(this));
+    registry.register(ToolNames.FS_SEARCH, this.search.bind(this));
+    return registry;
+  }
+  /**
+   * Creates a new ToolRegistry with fs.* tools pre-registered.
+   */
+  toRegistry() {
+    return this.registerInto(new ToolRegistry());
+  }
+  // ========================================================================
+  // Tool Handlers
+  // ========================================================================
+  async readFile(_args, call) {
+    const args = this.parseArgs(call, ["path"]);
+    const func = call.function;
+    const relPath = this.requireString(args, "path", call);
+    const requestedMax = this.optionalPositiveInt(args, "max_bytes", call);
+    let maxBytes = this.cfg.maxReadBytes;
+    if (requestedMax !== void 0) {
+      if (requestedMax > this.cfg.hardMaxReadBytes) {
+        throw new ToolArgumentError({
+          message: `max_bytes exceeds hard cap (${this.cfg.hardMaxReadBytes})`,
+          toolCallId: call.id,
+          toolName: func.name,
+          rawArguments: func.arguments
+        });
+      }
+      maxBytes = requestedMax;
+    }
+    const absPath = await this.resolveAndValidatePath(relPath, call);
+    const stat = await import_fs.promises.stat(absPath);
+    if (stat.isDirectory()) {
+      throw new Error(`fs.read_file: path is a directory: ${relPath}`);
+    }
+    if (stat.size > maxBytes) {
+      throw new Error(`fs.read_file: file exceeds max_bytes (${maxBytes})`);
+    }
+    const data = await import_fs.promises.readFile(absPath);
+    if (!this.isValidUtf8(data)) {
+      throw new Error(`fs.read_file: file is not valid UTF-8: ${relPath}`);
+    }
+    return data.toString("utf-8");
+  }
+  async listFiles(_args, call) {
+    const args = this.parseArgs(call, []);
+    const func = call.function;
+    const startPath = this.optionalString(args, "path", call)?.trim() || ".";
+    let maxEntries = this.cfg.maxListEntries;
+    const requestedMax = this.optionalPositiveInt(args, "max_entries", call);
+    if (requestedMax !== void 0) {
+      if (requestedMax > this.cfg.hardMaxListEntries) {
+        throw new ToolArgumentError({
+          message: `max_entries exceeds hard cap (${this.cfg.hardMaxListEntries})`,
+          toolCallId: call.id,
+          toolName: func.name,
+          rawArguments: func.arguments
+        });
+      }
+      maxEntries = requestedMax;
+    }
+    const absPath = await this.resolveAndValidatePath(startPath, call);
+    let rootReal;
+    try {
+      rootReal = await import_fs.promises.realpath(this.rootAbs);
+    } catch {
+      rootReal = this.rootAbs;
+    }
+    const stat = await import_fs.promises.stat(absPath);
+    if (!stat.isDirectory()) {
+      throw new Error(`fs.list_files: path is not a directory: ${startPath}`);
+    }
+    const files = [];
+    await this.walkDir(absPath, async (filePath, dirent) => {
+      if (files.length >= maxEntries) {
+        return false;
+      }
+      if (dirent.isDirectory()) {
+        if (this.cfg.ignoreDirs.has(dirent.name)) {
+          return false;
+        }
+        return true;
+      }
+      if (dirent.isFile()) {
+        const relPath = path.relative(rootReal, filePath);
+        files.push(relPath.split(path.sep).join("/"));
+      }
+      return true;
+    });
+    return files.join("\n");
+  }
+  async search(_args, call) {
+    const args = this.parseArgs(call, ["query"]);
+    const func = call.function;
+    const query = this.requireString(args, "query", call);
+    const startPath = this.optionalString(args, "path", call)?.trim() || ".";
+    let maxMatches = this.cfg.maxSearchMatches;
+    const requestedMax = this.optionalPositiveInt(args, "max_matches", call);
+    if (requestedMax !== void 0) {
+      if (requestedMax > this.cfg.hardMaxSearchMatches) {
+        throw new ToolArgumentError({
+          message: `max_matches exceeds hard cap (${this.cfg.hardMaxSearchMatches})`,
+          toolCallId: call.id,
+          toolName: func.name,
+          rawArguments: func.arguments
+        });
+      }
+      maxMatches = requestedMax;
+    }
+    const absPath = await this.resolveAndValidatePath(startPath, call);
+    const rgPath = await this.detectRipgrep();
+    if (rgPath) {
+      return this.searchWithRipgrep(
+        rgPath,
+        query,
+        absPath,
+        maxMatches
+      );
+    }
+    return this.searchWithJS(query, absPath, maxMatches, call);
+  }
+  // ========================================================================
+  // Path Safety
+  // ========================================================================
+  /**
+   * Resolves a workspace-relative path and validates it stays within the sandbox.
+   * @throws {ToolArgumentError} if path is invalid
+   * @throws {PathEscapeError} if resolved path escapes root
+   */
+  async resolveAndValidatePath(relPath, call) {
+    const func = call.function;
+    const cleanRel = relPath.trim();
+    if (!cleanRel) {
+      throw new ToolArgumentError({
+        message: "path cannot be empty",
+        toolCallId: call.id,
+        toolName: func.name,
+        rawArguments: func.arguments
+      });
+    }
+    if (path.isAbsolute(cleanRel)) {
+      throw new ToolArgumentError({
+        message: "path must be workspace-relative (not absolute)",
+        toolCallId: call.id,
+        toolName: func.name,
+        rawArguments: func.arguments
+      });
+    }
+    const normalized = path.normalize(cleanRel);
+    if (normalized.startsWith("..") || normalized.startsWith(`.${path.sep}..`)) {
+      throw new ToolArgumentError({
+        message: "path must not escape the workspace root",
+        toolCallId: call.id,
+        toolName: func.name,
+        rawArguments: func.arguments
+      });
+    }
+    const target = path.join(this.rootAbs, normalized);
+    let rootReal;
+    try {
+      rootReal = await import_fs.promises.realpath(this.rootAbs);
+    } catch {
+      rootReal = this.rootAbs;
+    }
+    let resolved;
+    try {
+      resolved = await import_fs.promises.realpath(target);
+    } catch (err) {
+      resolved = path.join(rootReal, normalized);
+    }
+    const relFromRoot = path.relative(rootReal, resolved);
+    if (relFromRoot.startsWith("..") || relFromRoot.startsWith(`.${path.sep}..`) || path.isAbsolute(relFromRoot)) {
+      throw new PathEscapeError({
+        requestedPath: relPath,
+        resolvedPath: resolved
+      });
+    }
+    return resolved;
+  }
+  // ========================================================================
+  // Ripgrep Search
+  // ========================================================================
+  async detectRipgrep() {
+    if (this.rgChecked) {
+      return this.rgPath;
+    }
+    this.rgChecked = true;
+    return new Promise((resolve2) => {
+      const proc = (0, import_child_process.spawn)("rg", ["--version"], { stdio: "ignore" });
+      proc.on("error", () => {
+        this.rgPath = null;
+        resolve2(null);
+      });
+      proc.on("close", (code) => {
+        if (code === 0) {
+          this.rgPath = "rg";
+          resolve2("rg");
+        } else {
+          this.rgPath = null;
+          resolve2(null);
+        }
+      });
+    });
+  }
+  async searchWithRipgrep(rgPath, query, dirAbs, maxMatches) {
+    return new Promise((resolve2, reject) => {
+      const args = ["--line-number", "--no-heading", "--color=never"];
+      for (const name of this.cfg.ignoreDirs) {
+        args.push("--glob", `!**/${name}/**`);
+      }
+      args.push(query, dirAbs);
+      const proc = (0, import_child_process.spawn)(rgPath, args, {
+        timeout: this.cfg.searchTimeoutMs
+      });
+      const lines = [];
+      let stderr = "";
+      let killed = false;
+      proc.stdout.on("data", (chunk) => {
+        if (killed) return;
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+        const newLines = text.split("\n").filter((l) => l.trim());
+        for (const line of newLines) {
+          lines.push(this.normalizeRipgrepLine(line));
+          if (lines.length >= maxMatches) {
+            killed = true;
+            proc.kill();
+            break;
+          }
+        }
+      });
+      proc.stderr.on("data", (chunk) => {
+        stderr += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+      });
+      proc.on("error", (err) => {
+        reject(new Error(`fs.search: ripgrep error: ${err.message}`));
+      });
+      proc.on("close", (code) => {
+        if (killed) {
+          resolve2(lines.join("\n"));
+          return;
+        }
+        if (code === 0 || code === 1) {
+          resolve2(lines.join("\n"));
+        } else if (code === 2 && stderr.toLowerCase().includes("regex")) {
+          reject(
+            new ToolArgumentError({
+              message: `invalid query regex: ${stderr.trim()}`,
+              toolCallId: "",
+              toolName: ToolNames.FS_SEARCH,
+              rawArguments: ""
+            })
+          );
+        } else if (stderr) {
+          reject(new Error(`fs.search: ripgrep failed: ${stderr.trim()}`));
+        } else {
+          resolve2(lines.join("\n"));
+        }
+      });
+    });
+  }
+  normalizeRipgrepLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes(":")) {
+      return trimmed;
+    }
+    const colonIdx = trimmed.indexOf(":");
+    const filePath = trimmed.slice(0, colonIdx);
+    const rest = trimmed.slice(colonIdx + 1);
+    if (path.isAbsolute(filePath)) {
+      const rel = path.relative(this.rootAbs, filePath);
+      if (!rel.startsWith("..")) {
+        return rel.split(path.sep).join("/") + ":" + rest;
+      }
+    }
+    return filePath.split(path.sep).join("/") + ":" + rest;
+  }
+  // ========================================================================
+  // JavaScript Fallback Search
+  // ========================================================================
+  async searchWithJS(query, dirAbs, maxMatches, call) {
+    const func = call.function;
+    let regex;
+    try {
+      regex = new RegExp(query);
+    } catch (err) {
+      throw new ToolArgumentError({
+        message: `invalid query regex: ${err.message}`,
+        toolCallId: call.id,
+        toolName: func.name,
+        rawArguments: func.arguments
+      });
+    }
+    const matches = [];
+    const deadline = Date.now() + this.cfg.searchTimeoutMs;
+    await this.walkDir(dirAbs, async (filePath, dirent) => {
+      if (Date.now() > deadline) {
+        return false;
+      }
+      if (matches.length >= maxMatches) {
+        return false;
+      }
+      if (dirent.isDirectory()) {
+        if (this.cfg.ignoreDirs.has(dirent.name)) {
+          return false;
+        }
+        return true;
+      }
+      if (!dirent.isFile()) {
+        return true;
+      }
+      try {
+        const stat = await import_fs.promises.stat(filePath);
+        if (stat.size > this.cfg.maxSearchBytesPerFile) {
+          return true;
+        }
+      } catch {
+        return true;
+      }
+      try {
+        const content = await import_fs.promises.readFile(filePath, "utf-8");
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length && matches.length < maxMatches; i++) {
+          if (regex.test(lines[i])) {
+            const relPath = path.relative(this.rootAbs, filePath);
+            const normalizedPath = relPath.split(path.sep).join("/");
+            matches.push(`${normalizedPath}:${i + 1}:${lines[i]}`);
+          }
+        }
+      } catch {
+      }
+      return true;
+    });
+    return matches.join("\n");
+  }
+  // ========================================================================
+  // Helpers
+  // ========================================================================
+  parseArgs(call, required) {
+    const func = call.function;
+    if (!func) {
+      throw new ToolArgumentError({
+        message: "tool call missing function",
+        toolCallId: call.id,
+        toolName: "",
+        rawArguments: ""
+      });
+    }
+    const rawArgs = func.arguments || "{}";
+    let parsed;
+    try {
+      parsed = JSON.parse(rawArgs);
+    } catch (err) {
+      throw new ToolArgumentError({
+        message: `invalid JSON arguments: ${err.message}`,
+        toolCallId: call.id,
+        toolName: func.name,
+        rawArguments: rawArgs
+      });
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new ToolArgumentError({
+        message: "arguments must be an object",
+        toolCallId: call.id,
+        toolName: func.name,
+        rawArguments: rawArgs
+      });
+    }
+    const args = parsed;
+    for (const key of required) {
+      const value = args[key];
+      if (value === void 0 || value === null || value === "") {
+        throw new ToolArgumentError({
+          message: `${key} is required`,
+          toolCallId: call.id,
+          toolName: func.name,
+          rawArguments: rawArgs
+        });
+      }
+    }
+    return args;
+  }
+  toolArgumentError(call, message) {
+    const func = call.function;
+    throw new ToolArgumentError({
+      message,
+      toolCallId: call.id,
+      toolName: func?.name ?? "",
+      rawArguments: func?.arguments ?? ""
+    });
+  }
+  requireString(args, key, call) {
+    const value = args[key];
+    if (typeof value !== "string") {
+      this.toolArgumentError(call, `${key} must be a string`);
+    }
+    if (value.trim() === "") {
+      this.toolArgumentError(call, `${key} is required`);
+    }
+    return value;
+  }
+  optionalString(args, key, call) {
+    const value = args[key];
+    if (value === void 0 || value === null) {
+      return void 0;
+    }
+    if (typeof value !== "string") {
+      this.toolArgumentError(call, `${key} must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+      return void 0;
+    }
+    return value;
+  }
+  optionalPositiveInt(args, key, call) {
+    const value = args[key];
+    if (value === void 0 || value === null) {
+      return void 0;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+      this.toolArgumentError(call, `${key} must be an integer`);
+    }
+    if (value <= 0) {
+      this.toolArgumentError(call, `${key} must be > 0`);
+    }
+    return value;
+  }
+  isValidUtf8(buffer) {
+    try {
+      const text = buffer.toString("utf-8");
+      return !text.includes("\uFFFD");
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Recursively walks a directory, calling visitor for each entry.
+   * Visitor returns true to continue, false to skip (for dirs) or stop.
+   */
+  async walkDir(dir, visitor) {
+    const entries = await import_fs.promises.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const shouldContinue = await visitor(fullPath, entry);
+      if (!shouldContinue) {
+        if (entry.isDirectory()) {
+          continue;
+        }
+        return;
+      }
+      if (entry.isDirectory()) {
+        await this.walkDir(fullPath, visitor);
+      }
+    }
+  }
+};
+function createLocalFSToolPack(options) {
+  return new LocalFSToolPack(options);
+}
+function createLocalFSTools(options) {
+  return createLocalFSToolPack(options).toRegistry();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_IGNORE_DIRS,
+  FSDefaults,
+  FSToolNames,
+  LocalFSToolPack,
+  createLocalFSToolPack,
+  createLocalFSTools
+});