@modelrelay/sdk 1.25.0 → 1.27.0

package/dist/node.d.cts

@@ -0,0 +1,149 @@
+import { k as Tool, u as ToolRegistry } from './tools-Db-F5rIL.cjs';
+
+/**
+ * Local filesystem tool pack for client-side tool execution.
+ *
+ * Implements tools.v0 contract:
+ * - fs.read_file - Read workspace-relative files
+ * - fs.list_files - List files recursively
+ * - fs.search - Regex search (ripgrep or JS fallback)
+ *
+ * Safety features:
+ * - Root sandbox with symlink resolution
+ * - Path traversal prevention
+ * - Size limits with hard caps
+ * - Ignore patterns for common large directories
+ * - UTF-8 validation
+ *
+ * @module
+ */
+
+/** Reserved tool names from tools.v0 specification. */
+declare const ToolNames: {
+    readonly FS_READ_FILE: "fs.read_file";
+    readonly FS_LIST_FILES: "fs.list_files";
+    readonly FS_SEARCH: "fs.search";
+};
+/** Default size limits and caps from wire contract. */
+declare const FSDefaults: {
+    readonly MAX_READ_BYTES: 64000;
+    readonly HARD_MAX_READ_BYTES: 1000000;
+    readonly MAX_LIST_ENTRIES: 2000;
+    readonly HARD_MAX_LIST_ENTRIES: 20000;
+    readonly MAX_SEARCH_MATCHES: 100;
+    readonly HARD_MAX_SEARCH_MATCHES: 2000;
+    readonly SEARCH_TIMEOUT_MS: 5000;
+    readonly MAX_SEARCH_BYTES_PER_FILE: 1000000;
+};
+/** Default directories to skip during list/search operations. */
+declare const DEFAULT_IGNORE_DIRS: Set<string>;
+/** Configuration options for LocalFSToolPack. */
+interface LocalFSToolPackOptions {
+    /** Root directory for sandboxing (required). All paths are relative to this. */
+    root: string;
+    /** Directory names to skip during list/search. Defaults to DEFAULT_IGNORE_DIRS. */
+    ignoreDirs?: Set<string>;
+    /** Default max_bytes for fs.read_file. Defaults to 64KB. */
+    maxReadBytes?: number;
+    /** Hard cap for fs.read_file max_bytes. Defaults to 1MB. */
+    hardMaxReadBytes?: number;
+    /** Default max_entries for fs.list_files. Defaults to 2000. */
+    maxListEntries?: number;
+    /** Hard cap for fs.list_files max_entries. Defaults to 20000. */
+    hardMaxListEntries?: number;
+    /** Default max_matches for fs.search. Defaults to 100. */
+    maxSearchMatches?: number;
+    /** Hard cap for fs.search max_matches. Defaults to 2000. */
+    hardMaxSearchMatches?: number;
+    /** Timeout for fs.search in milliseconds. Defaults to 5000. */
+    searchTimeoutMs?: number;
+    /** Max bytes to read per file during JS fallback search. Defaults to 1MB. */
+    maxSearchBytesPerFile?: number;
+}
+/**
+ * Tool pack providing safe filesystem access for LLM workflows.
+ *
+ * @example
+ * ```typescript
+ * const pack = new LocalFSToolPack({ root: process.cwd() });
+ * const registry = pack.toRegistry();
+ *
+ * // Use tools in a workflow
+ * const response = await client.responses.create({
+ *   model: "anthropic/claude-sonnet-4-20250514",
+ *   input: [{ type: "message", role: "user", content: [{ type: "text", text: "List all TypeScript files" }] }],
+ *   tools: pack.getToolDefinitions(),
+ * });
+ *
+ * // Execute tool calls
+ * const results = await registry.executeAll(response.output.filter(o => o.type === "tool_use"));
+ * ```
+ */
+declare class LocalFSToolPack {
+    private readonly rootAbs;
+    private readonly cfg;
+    private rgPath;
+    private rgChecked;
+    constructor(options: LocalFSToolPackOptions);
+    /**
+     * Returns the tool definitions for LLM requests.
+     * Use these when constructing the tools array for /responses requests.
+     */
+    getToolDefinitions(): Tool[];
+    /**
+     * Registers handlers into an existing ToolRegistry.
+     * @param registry - The registry to register into
+     * @returns The registry for chaining
+     */
+    registerInto(registry: ToolRegistry): ToolRegistry;
+    /**
+     * Creates a new ToolRegistry with fs.* tools pre-registered.
+     */
+    toRegistry(): ToolRegistry;
+    private readFile;
+    private listFiles;
+    private search;
+    /**
+     * 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
+     */
+    private resolveAndValidatePath;
+    private detectRipgrep;
+    private searchWithRipgrep;
+    private normalizeRipgrepLine;
+    private searchWithJS;
+    private parseArgs;
+    private toolArgumentError;
+    private requireString;
+    private optionalString;
+    private optionalPositiveInt;
+    private isValidUtf8;
+    /**
+     * Recursively walks a directory, calling visitor for each entry.
+     * Visitor returns true to continue, false to skip (for dirs) or stop.
+     */
+    private walkDir;
+}
+/**
+ * Creates a LocalFSToolPack with the given options.
+ *
+ * @example
+ * ```typescript
+ * const pack = createLocalFSToolPack({ root: process.cwd() });
+ * ```
+ */
+declare function createLocalFSToolPack(options: LocalFSToolPackOptions): LocalFSToolPack;
+/**
+ * Creates a ToolRegistry with fs.* tools pre-registered.
+ * Shorthand for createLocalFSToolPack(options).toRegistry().
+ *
+ * @example
+ * ```typescript
+ * const registry = createLocalFSTools({ root: process.cwd() });
+ * const result = await registry.execute(toolCall);
+ * ```
+ */
+declare function createLocalFSTools(options: LocalFSToolPackOptions): ToolRegistry;
+
+export { DEFAULT_IGNORE_DIRS, FSDefaults, ToolNames as FSToolNames, LocalFSToolPack, type LocalFSToolPackOptions, createLocalFSToolPack, createLocalFSTools };

package/dist/node.d.ts

@@ -0,0 +1,149 @@
+import { k as Tool, u as ToolRegistry } from './tools-Db-F5rIL.js';
+
+/**
+ * Local filesystem tool pack for client-side tool execution.
+ *
+ * Implements tools.v0 contract:
+ * - fs.read_file - Read workspace-relative files
+ * - fs.list_files - List files recursively
+ * - fs.search - Regex search (ripgrep or JS fallback)
+ *
+ * Safety features:
+ * - Root sandbox with symlink resolution
+ * - Path traversal prevention
+ * - Size limits with hard caps
+ * - Ignore patterns for common large directories
+ * - UTF-8 validation
+ *
+ * @module
+ */
+
+/** Reserved tool names from tools.v0 specification. */
+declare const ToolNames: {
+    readonly FS_READ_FILE: "fs.read_file";
+    readonly FS_LIST_FILES: "fs.list_files";
+    readonly FS_SEARCH: "fs.search";
+};
+/** Default size limits and caps from wire contract. */
+declare const FSDefaults: {
+    readonly MAX_READ_BYTES: 64000;
+    readonly HARD_MAX_READ_BYTES: 1000000;
+    readonly MAX_LIST_ENTRIES: 2000;
+    readonly HARD_MAX_LIST_ENTRIES: 20000;
+    readonly MAX_SEARCH_MATCHES: 100;
+    readonly HARD_MAX_SEARCH_MATCHES: 2000;
+    readonly SEARCH_TIMEOUT_MS: 5000;
+    readonly MAX_SEARCH_BYTES_PER_FILE: 1000000;
+};
+/** Default directories to skip during list/search operations. */
+declare const DEFAULT_IGNORE_DIRS: Set<string>;
+/** Configuration options for LocalFSToolPack. */
+interface LocalFSToolPackOptions {
+    /** Root directory for sandboxing (required). All paths are relative to this. */
+    root: string;
+    /** Directory names to skip during list/search. Defaults to DEFAULT_IGNORE_DIRS. */
+    ignoreDirs?: Set<string>;
+    /** Default max_bytes for fs.read_file. Defaults to 64KB. */
+    maxReadBytes?: number;
+    /** Hard cap for fs.read_file max_bytes. Defaults to 1MB. */
+    hardMaxReadBytes?: number;
+    /** Default max_entries for fs.list_files. Defaults to 2000. */
+    maxListEntries?: number;
+    /** Hard cap for fs.list_files max_entries. Defaults to 20000. */
+    hardMaxListEntries?: number;
+    /** Default max_matches for fs.search. Defaults to 100. */
+    maxSearchMatches?: number;
+    /** Hard cap for fs.search max_matches. Defaults to 2000. */
+    hardMaxSearchMatches?: number;
+    /** Timeout for fs.search in milliseconds. Defaults to 5000. */
+    searchTimeoutMs?: number;
+    /** Max bytes to read per file during JS fallback search. Defaults to 1MB. */
+    maxSearchBytesPerFile?: number;
+}
+/**
+ * Tool pack providing safe filesystem access for LLM workflows.
+ *
+ * @example
+ * ```typescript
+ * const pack = new LocalFSToolPack({ root: process.cwd() });
+ * const registry = pack.toRegistry();
+ *
+ * // Use tools in a workflow
+ * const response = await client.responses.create({
+ *   model: "anthropic/claude-sonnet-4-20250514",
+ *   input: [{ type: "message", role: "user", content: [{ type: "text", text: "List all TypeScript files" }] }],
+ *   tools: pack.getToolDefinitions(),
+ * });
+ *
+ * // Execute tool calls
+ * const results = await registry.executeAll(response.output.filter(o => o.type === "tool_use"));
+ * ```
+ */
+declare class LocalFSToolPack {
+    private readonly rootAbs;
+    private readonly cfg;
+    private rgPath;
+    private rgChecked;
+    constructor(options: LocalFSToolPackOptions);
+    /**
+     * Returns the tool definitions for LLM requests.
+     * Use these when constructing the tools array for /responses requests.
+     */
+    getToolDefinitions(): Tool[];
+    /**
+     * Registers handlers into an existing ToolRegistry.
+     * @param registry - The registry to register into
+     * @returns The registry for chaining
+     */
+    registerInto(registry: ToolRegistry): ToolRegistry;
+    /**
+     * Creates a new ToolRegistry with fs.* tools pre-registered.
+     */
+    toRegistry(): ToolRegistry;
+    private readFile;
+    private listFiles;
+    private search;
+    /**
+     * 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
+     */
+    private resolveAndValidatePath;
+    private detectRipgrep;
+    private searchWithRipgrep;
+    private normalizeRipgrepLine;
+    private searchWithJS;
+    private parseArgs;
+    private toolArgumentError;
+    private requireString;
+    private optionalString;
+    private optionalPositiveInt;
+    private isValidUtf8;
+    /**
+     * Recursively walks a directory, calling visitor for each entry.
+     * Visitor returns true to continue, false to skip (for dirs) or stop.
+     */
+    private walkDir;
+}
+/**
+ * Creates a LocalFSToolPack with the given options.
+ *
+ * @example
+ * ```typescript
+ * const pack = createLocalFSToolPack({ root: process.cwd() });
+ * ```
+ */
+declare function createLocalFSToolPack(options: LocalFSToolPackOptions): LocalFSToolPack;
+/**
+ * Creates a ToolRegistry with fs.* tools pre-registered.
+ * Shorthand for createLocalFSToolPack(options).toRegistry().
+ *
+ * @example
+ * ```typescript
+ * const registry = createLocalFSTools({ root: process.cwd() });
+ * const result = await registry.execute(toolCall);
+ * ```
+ */
+declare function createLocalFSTools(options: LocalFSToolPackOptions): ToolRegistry;
+
+export { DEFAULT_IGNORE_DIRS, FSDefaults, ToolNames as FSToolNames, LocalFSToolPack, type LocalFSToolPackOptions, createLocalFSToolPack, createLocalFSTools };