@lleverage-ai/agent-sdk 0.0.1

package/dist/tools/filesystem.js

@@ -0,0 +1,311 @@
+/**
+ * Filesystem tools for agent file operations.
+ *
+ * These tools wrap the BackendProtocol interface to provide file operations
+ * to agents. Each tool is a factory function that takes a backend and returns
+ * an AI SDK compatible tool.
+ *
+ * @packageDocumentation
+ */
+import { tool } from "ai";
+import { z } from "zod";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Default number of lines to read from a file */
+const DEFAULT_READ_LIMIT = 2000;
+/** Character count threshold for warning (approximate tokens = chars / 4) */
+const LARGE_CONTENT_WARNING_CHARS = 80_000; // ~20k tokens
+// =============================================================================
+// Read Tool
+// =============================================================================
+/**
+ * Creates a tool for reading file contents.
+ *
+ * Reads files with line numbers and supports offset/limit for large files.
+ * By default reads the first 2000 lines.
+ *
+ * @param backend - The backend to use for file operations
+ * @returns An AI SDK compatible tool for reading files
+ *
+ * @example
+ * ```typescript
+ * import { createReadTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const read = createReadTool(backend);
+ * const agent = createAgent({
+ *   model,
+ *   tools: { read },
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function createReadTool(backend) {
+    return tool({
+        description: `Read a file with line numbers. Default reads first ${DEFAULT_READ_LIMIT} lines. Use offset/limit for large files.`,
+        inputSchema: z.object({
+            file_path: z.string().describe("Absolute path to the file to read"),
+            offset: z.number().optional().describe("Line number to start from (0-indexed)"),
+            limit: z
+                .number()
+                .optional()
+                .describe(`Maximum lines to read (default: ${DEFAULT_READ_LIMIT})`),
+        }),
+        execute: async ({ file_path, offset, limit, }) => {
+            const effectiveLimit = limit ?? DEFAULT_READ_LIMIT;
+            const content = await backend.read(file_path, offset, effectiveLimit);
+            // Add warning for large content
+            if (content.length > LARGE_CONTENT_WARNING_CHARS) {
+                const estimatedTokens = Math.round(content.length / 4);
+                return `[Warning: Large file content (~${estimatedTokens} tokens). Consider using offset/limit to read specific sections.]\n\n${content}`;
+            }
+            return content;
+        },
+    });
+}
+// =============================================================================
+// Write Tool
+// =============================================================================
+/**
+ * Creates a tool for writing/creating files.
+ *
+ * Creates new files or overwrites existing ones. Parent directories are
+ * created automatically if they don't exist.
+ *
+ * @param backend - The backend to use for file operations
+ * @returns An AI SDK compatible tool for writing files
+ *
+ * @example
+ * ```typescript
+ * import { createWriteTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const write = createWriteTool(backend);
+ * const agent = createAgent({
+ *   model,
+ *   tools: { write },
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function createWriteTool(backend) {
+    return tool({
+        description: "Create or overwrite a file with the given content. Parent directories are created automatically.",
+        inputSchema: z.object({
+            file_path: z.string().describe("Absolute path for the file to write"),
+            content: z.string().describe("Content to write to the file"),
+        }),
+        execute: async ({ file_path, content }) => {
+            const result = await backend.write(file_path, content);
+            if (!result.success) {
+                return `Error: ${result.error}`;
+            }
+            const lines = content.split("\n").length;
+            return `Successfully wrote ${lines} lines to ${file_path}`;
+        },
+    });
+}
+// =============================================================================
+// Edit Tool
+// =============================================================================
+/**
+ * Creates a tool for editing files via string replacement.
+ *
+ * Replaces text in a file. By default, the `old_string` must be unique
+ * in the file to prevent accidental replacements. Use `replace_all: true`
+ * to replace all occurrences.
+ *
+ * @param backend - The backend to use for file operations
+ * @returns An AI SDK compatible tool for editing files
+ *
+ * @example
+ * ```typescript
+ * import { createEditTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const edit = createEditTool(backend);
+ * const agent = createAgent({
+ *   model,
+ *   tools: { edit },
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function createEditTool(backend) {
+    return tool({
+        description: "Edit a file by replacing text. The old_string must be unique unless replace_all is true.",
+        inputSchema: z.object({
+            file_path: z.string().describe("Absolute path to the file to edit"),
+            old_string: z.string().describe("Text to find and replace (must be unique in file)"),
+            new_string: z.string().describe("Replacement text"),
+            replace_all: z
+                .boolean()
+                .optional()
+                .describe("If true, replace all occurrences. Default: false (unique match required)"),
+        }),
+        execute: async ({ file_path, old_string, new_string, replace_all, }) => {
+            const result = await backend.edit(file_path, old_string, new_string, replace_all);
+            if (!result.success) {
+                return `Error: ${result.error}`;
+            }
+            if (result.occurrences !== undefined && result.occurrences > 1) {
+                return `Successfully replaced ${result.occurrences} occurrences in ${file_path}`;
+            }
+            return `Successfully edited ${file_path}`;
+        },
+    });
+}
+// =============================================================================
+// Glob Tool
+// =============================================================================
+/**
+ * Creates a tool for finding files matching glob patterns.
+ *
+ * Supports glob patterns like `**\/*.ts`, `src/**\/*.test.ts`, etc.
+ *
+ * @param backend - The backend to use for file operations
+ * @returns An AI SDK compatible tool for glob searching
+ *
+ * @example
+ * ```typescript
+ * import { createGlobTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const glob = createGlobTool(backend);
+ * const agent = createAgent({
+ *   model,
+ *   tools: { glob },
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function createGlobTool(backend) {
+    return tool({
+        description: 'Find files matching a glob pattern. Supports patterns like "**/*.ts", "src/**/*.test.ts".',
+        inputSchema: z.object({
+            pattern: z.string().describe('Glob pattern to match files (e.g., "**/*.ts")'),
+            path: z.string().optional().describe("Base directory to search from (default: root)"),
+        }),
+        execute: async ({ pattern, path }) => {
+            const files = await backend.globInfo(pattern, path);
+            return formatGlobOutput(files);
+        },
+    });
+}
+/**
+ * Format glob output for display.
+ * @internal
+ */
+function formatGlobOutput(files) {
+    if (files.length === 0) {
+        return "No files found matching the pattern.";
+    }
+    const paths = files.map((f) => f.path);
+    const header = `Found ${files.length} file(s):`;
+    return `${header}\n${paths.join("\n")}`;
+}
+// =============================================================================
+// Grep Tool
+// =============================================================================
+/**
+ * Creates a tool for searching file contents with regex.
+ *
+ * Searches for pattern matches across files, with optional glob filtering.
+ *
+ * @param backend - The backend to use for file operations
+ * @returns An AI SDK compatible tool for grep searching
+ *
+ * @example
+ * ```typescript
+ * import { createGrepTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const grep = createGrepTool(backend);
+ * const agent = createAgent({
+ *   model,
+ *   tools: { grep },
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function createGrepTool(backend) {
+    return tool({
+        description: "Search for pattern matches in files using regex. Returns matching lines with file paths and line numbers.",
+        inputSchema: z.object({
+            pattern: z.string().describe("Regular expression pattern to search for"),
+            path: z.string().optional().describe("Directory to search in (default: root)"),
+            glob: z.string().optional().describe('Glob pattern to filter files (e.g., "*.ts")'),
+        }),
+        execute: async ({ pattern, path, glob }) => {
+            const result = await backend.grepRaw(pattern, path, glob);
+            // Handle string result (some backends may return formatted string)
+            if (typeof result === "string") {
+                return result;
+            }
+            return formatGrepOutput(result);
+        },
+    });
+}
+/**
+ * Format grep output for display.
+ * @internal
+ */
+function formatGrepOutput(matches) {
+    if (matches.length === 0) {
+        return "No matches found.";
+    }
+    const lines = matches.map((m) => `${m.path}:${m.line}: ${m.text}`);
+    const header = `Found ${matches.length} match(es):`;
+    return `${header}\n${lines.join("\n")}`;
+}
+/**
+ * Creates all filesystem tools from a backend.
+ *
+ * This is a convenience factory that creates all filesystem tools at once.
+ * For read-only access, set `includeWrite` and `includeEdit` to false.
+ *
+ * @param options - Configuration options
+ * @returns Object containing all filesystem tools
+ *
+ * @example
+ * ```typescript
+ * import { createFilesystemTools, FilesystemBackend } from "@lleverage-ai/agent-sdk";
+ *
+ * const backend = new FilesystemBackend({ rootDir: process.cwd() });
+ * const fsTools = createFilesystemTools({ backend });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: fsTools,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Read-only mode
+ * const fsTools = createFilesystemTools({
+ *   backend,
+ *   includeWrite: false,
+ *   includeEdit: false,
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function createFilesystemTools(options) {
+    const { backend, includeWrite = true, includeEdit = true } = options;
+    const tools = {
+        read: createReadTool(backend),
+        glob: createGlobTool(backend),
+        grep: createGrepTool(backend),
+    };
+    if (includeWrite) {
+        tools.write = createWriteTool(backend);
+    }
+    if (includeEdit) {
+        tools.edit = createEditTool(backend);
+    }
+    return tools;
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/tools/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../src/tools/filesystem.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Core tools for agent operations.
+ *
+ * This module provides factory functions for creating the minimal tool set:
+ * - `read`, `write`, `edit`, `glob`, `grep` - filesystem operations
+ * - `bash` - shell command execution
+ * - `todo_write` - task tracking
+ * - `task` - subagent delegation
+ * - `skill` - progressive capability loading
+ *
+ * @packageDocumentation
+ */
+export type { BashResult, BashToolOptions } from "./execute.js";
+export { createBashTool } from "./execute.js";
+export type { CoreTools, CoreToolsOptions } from "./factory.js";
+export { coreToolsToToolSet, createCoreTools, createFilesystemToolsOnly, } from "./factory.js";
+export type { FilesystemTools, FilesystemToolsOptions } from "./filesystem.js";
+export { createEditTool, createFilesystemTools, createGlobTool, createGrepTool, createReadTool, createWriteTool, } from "./filesystem.js";
+export type { SearchToolsOptions } from "./search.js";
+export { createSearchToolsTool } from "./search.js";
+export type { LoadableSkillDefinition, SkillLoadResult, SkillRegistryOptions, SkillToolOptions, } from "./skills.js";
+export { createSkillRegistry, createSkillTool, defineLoadableSkill, SkillRegistry, } from "./skills.js";
+export type { TaskStatus, TaskToolOptions, } from "./task.js";
+export { cleanupStaleTasks, clearCompletedTasks, createTaskTool, getBackgroundTask, listBackgroundTasks, recoverFailedTasks, recoverRunningTasks, } from "./task.js";
+export type { OnTodosChanged, TodoChangeType, TodoInput, TodosChangedData, TodoWriteToolOptions, } from "./todos.js";
+export { createTodoWriteTool } from "./todos.js";
+export type { ToolLoadResult, ToolMetadata, ToolRegistryOptions, ToolSearchOptions, UseToolsToolOptions, } from "./tool-registry.js";
+export { createToolRegistry, createUseToolsTool, ToolRegistry, } from "./tool-registry.js";
+export type { AskUserCallback, QuestionOption, } from "./user-interaction.js";
+export { createAskUserQuestionTool } from "./user-interaction.js";
+export type { ToolReference } from "./utils.js";
+export { mcpTools, mcpToolsFor, toolsFrom, toolsFromPlugin } from "./utils.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,YAAY,EACV,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,cAAc,EACd,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,eAAe,EACf,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,33 @@
+/**
+ * Core tools for agent operations.
+ *
+ * This module provides factory functions for creating the minimal tool set:
+ * - `read`, `write`, `edit`, `glob`, `grep` - filesystem operations
+ * - `bash` - shell command execution
+ * - `todo_write` - task tracking
+ * - `task` - subagent delegation
+ * - `skill` - progressive capability loading
+ *
+ * @packageDocumentation
+ */
+// Bash tool
+export { createBashTool } from "./execute.js";
+// Tool factory (unified tool creation)
+export { coreToolsToToolSet, createCoreTools, createFilesystemToolsOnly, } from "./factory.js";
+// Filesystem tools
+export { createEditTool, createFilesystemTools, createGlobTool, createGrepTool, createReadTool, createWriteTool, } from "./filesystem.js";
+// Search tools (MCP integration)
+export { createSearchToolsTool } from "./search.js";
+// Skill tool (progressive disclosure)
+export { createSkillRegistry, createSkillTool, defineLoadableSkill, SkillRegistry, } from "./skills.js";
+// Task tool (subagent delegation)
+export { cleanupStaleTasks, clearCompletedTasks, createTaskTool, getBackgroundTask, listBackgroundTasks, recoverFailedTasks, recoverRunningTasks, } from "./task.js";
+// Todo tool
+export { createTodoWriteTool } from "./todos.js";
+// Tool registry (deferred tool loading)
+export { createToolRegistry, createUseToolsTool, ToolRegistry, } from "./tool-registry.js";
+// User interaction tools
+export { createAskUserQuestionTool } from "./user-interaction.js";
+// Tool utilities (DX helpers)
+export { mcpTools, mcpToolsFor, toolsFrom, toolsFromPlugin } from "./utils.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,uCAAuC;AACvC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AAEtB,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,iCAAiC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAOpD,sCAAsC;AACtC,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAKrB,kCAAkC;AAClC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAQnB,YAAY;AACZ,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAQjD,wCAAwC;AACxC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAK5B,yBAAyB;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,8BAA8B;AAC9B,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools/search.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool search meta-tool for progressive disclosure.
+ *
+ * @packageDocumentation
+ */
+import type { Tool } from "ai";
+import type { MCPManager } from "../mcp/manager.js";
+/**
+ * Options for creating the search_tools tool.
+ *
+ * @category Tools
+ */
+export interface SearchToolsOptions {
+    /** MCP manager to search */
+    manager: MCPManager;
+    /**
+     * Maximum results to return.
+     * @defaultValue 10
+     */
+    maxResults?: number;
+    /**
+     * Whether to enable loading tools after search.
+     * When true, the tool accepts an optional 'load' parameter.
+     * @defaultValue false
+     */
+    enableLoad?: boolean;
+    /**
+     * Callback when tools are loaded.
+     * Used to notify the agent that tools have changed.
+     */
+    onToolsLoaded?: (toolNames: string[]) => void;
+}
+/**
+ * Creates the search_tools meta-tool for discovering MCP tools.
+ *
+ * This tool allows agents to search for available tools by query,
+ * enabling progressive disclosure of capabilities.
+ *
+ * @param options - Configuration options
+ * @returns AI SDK tool definition
+ *
+ * @example
+ * ```typescript
+ * const searchTool = createSearchToolsTool({
+ *   manager: mcpManager,
+ *   maxResults: 5,
+ * });
+ *
+ * // Agent can then use:
+ * // search_tools({ query: "github issues" })
+ *
+ * // With loading enabled:
+ * // search_tools({ query: "github issues", load: true })
+ * ```
+ *
+ * @category Tools
+ */
+export declare function createSearchToolsTool(options: SearchToolsOptions): Tool;
+//# sourceMappingURL=search.d.ts.map

package/dist/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAG/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,OAAO,EAAE,UAAU,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CA6EvE"}

package/dist/tools/search.js

@@ -0,0 +1,94 @@
+/**
+ * Tool search meta-tool for progressive disclosure.
+ *
+ * @packageDocumentation
+ */
+import { tool } from "ai";
+import { z } from "zod";
+/**
+ * Creates the search_tools meta-tool for discovering MCP tools.
+ *
+ * This tool allows agents to search for available tools by query,
+ * enabling progressive disclosure of capabilities.
+ *
+ * @param options - Configuration options
+ * @returns AI SDK tool definition
+ *
+ * @example
+ * ```typescript
+ * const searchTool = createSearchToolsTool({
+ *   manager: mcpManager,
+ *   maxResults: 5,
+ * });
+ *
+ * // Agent can then use:
+ * // search_tools({ query: "github issues" })
+ *
+ * // With loading enabled:
+ * // search_tools({ query: "github issues", load: true })
+ * ```
+ *
+ * @category Tools
+ */
+export function createSearchToolsTool(options) {
+    const { manager, maxResults = 10, enableLoad = false, onToolsLoaded } = options;
+    const baseDescription = "Search for available tools by query. Returns tool names and descriptions. " +
+        "Use this to discover tools that can help with your task.";
+    const loadDescription = enableLoad
+        ? " Set 'load: true' to load discovered tools for immediate use."
+        : "";
+    const inputSchema = enableLoad
+        ? z.object({
+            query: z
+                .string()
+                .describe("Search query to find relevant tools. Can match tool names or descriptions."),
+            load: z
+                .boolean()
+                .optional()
+                .describe("If true, load the discovered tools for immediate use. Default is false (search only)."),
+        })
+        : z.object({
+            query: z
+                .string()
+                .describe("Search query to find relevant tools. Can match tool names or descriptions."),
+        });
+    return tool({
+        description: baseDescription + loadDescription,
+        inputSchema,
+        execute: async (input) => {
+            const { query, load = false } = input;
+            const results = manager.searchTools(query, maxResults);
+            if (results.length === 0) {
+                return `No tools found matching "${query}". Try a different search term.`;
+            }
+            // If load is requested, load the discovered tools
+            if (load && enableLoad) {
+                const toolNames = results.map((t) => t.name);
+                const loadResult = manager.loadTools(toolNames);
+                // Notify callback if provided
+                if (onToolsLoaded && loadResult.loaded.length > 0) {
+                    onToolsLoaded(loadResult.loaded);
+                }
+                if (loadResult.loaded.length === 0) {
+                    const formatted = results.map((t) => `- **${t.name}**: ${t.description}`).join("\n");
+                    return `Found ${results.length} tool(s) (all already loaded):\n\n${formatted}`;
+                }
+                const loadedFormatted = loadResult.loaded
+                    .map((name) => {
+                    const meta = results.find((t) => t.name === name);
+                    return `- **${name}**: ${meta?.description ?? ""}`;
+                })
+                    .join("\n");
+                let response = `Loaded ${loadResult.loaded.length} tool(s):\n\n${loadedFormatted}`;
+                if (loadResult.alreadyLoaded.length > 0) {
+                    response += `\n\n(${loadResult.alreadyLoaded.length} tool(s) were already loaded)`;
+                }
+                return response;
+            }
+            // Search only - return results without loading
+            const formatted = results.map((t) => `- **${t.name}**: ${t.description}`).join("\n");
+            return `Found ${results.length} tool(s):\n\n${formatted}`;
+        },
+    });
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA2B;IAC/D,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,EAAE,EAAE,UAAU,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAEhF,MAAM,eAAe,GACnB,4EAA4E;QAC5E,0DAA0D,CAAC;IAE7D,MAAM,eAAe,GAAG,UAAU;QAChC,CAAC,CAAC,+DAA+D;QACjE,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,WAAW,GAAG,UAAU;QAC5B,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACP,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,CAAC,4EAA4E,CAAC;YACzF,IAAI,EAAE,CAAC;iBACJ,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CACP,uFAAuF,CACxF;SACJ,CAAC;QACJ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACP,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,CAAC,4EAA4E,CAAC;SAC1F,CAAC,CAAC;IAEP,OAAO,IAAI,CAAC;QACV,WAAW,EAAE,eAAe,GAAG,eAAe;QAC9C,WAAW;QACX,OAAO,EAAE,KAAK,EAAE,KAAwC,EAAE,EAAE;YAC1D,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC;YACtC,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YAEvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,4BAA4B,KAAK,iCAAiC,CAAC;YAC5E,CAAC;YAED,kDAAkD;YAClD,IAAI,IAAI,IAAI,UAAU,EAAE,CAAC;gBACvB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;gBAEhD,8BAA8B;gBAC9B,IAAI,aAAa,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAClD,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;gBACnC,CAAC;gBAED,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACnC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACrF,OAAO,SAAS,OAAO,CAAC,MAAM,qCAAqC,SAAS,EAAE,CAAC;gBACjF,CAAC;gBAED,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM;qBACtC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;oBACZ,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;oBAClD,OAAO,OAAO,IAAI,OAAO,IAAI,EAAE,WAAW,IAAI,EAAE,EAAE,CAAC;gBACrD,CAAC,CAAC;qBACD,IAAI,CAAC,IAAI,CAAC,CAAC;gBAEd,IAAI,QAAQ,GAAG,UAAU,UAAU,CAAC,MAAM,CAAC,MAAM,gBAAgB,eAAe,EAAE,CAAC;gBAEnF,IAAI,UAAU,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxC,QAAQ,IAAI,QAAQ,UAAU,CAAC,aAAa,CAAC,MAAM,+BAA+B,CAAC;gBACrF,CAAC;gBAED,OAAO,QAAQ,CAAC;YAClB,CAAC;YAED,+CAA+C;YAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAErF,OAAO,SAAS,OAAO,CAAC,MAAM,gBAAgB,SAAS,EAAE,CAAC;QAC5D,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}