@modelrelay/sdk 1.25.0 → 1.27.0

package/dist/node.js

@@ -0,0 +1,611 @@
+import {
+  PathEscapeError,
+  ToolArgumentError,
+  ToolRegistry
+} from "./chunk-BL7GWXRZ.js";
+
+// src/tools_local_fs.ts
+import { promises as fs } from "fs";
+import * as path from "path";
+import { spawn } from "child_process";
+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 fs.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 fs.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 fs.realpath(this.rootAbs);
+    } catch {
+      rootReal = this.rootAbs;
+    }
+    const stat = await fs.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 fs.realpath(this.rootAbs);
+    } catch {
+      rootReal = this.rootAbs;
+    }
+    let resolved;
+    try {
+      resolved = await fs.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 = 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 = 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 fs.stat(filePath);
+        if (stat.size > this.cfg.maxSearchBytesPerFile) {
+          return true;
+        }
+      } catch {
+        return true;
+      }
+      try {
+        const content = await fs.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 fs.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();
+}
+export {
+  DEFAULT_IGNORE_DIRS,
+  FSDefaults,
+  ToolNames as FSToolNames,
+  LocalFSToolPack,
+  createLocalFSToolPack,
+  createLocalFSTools
+};