@lleverage-ai/agent-sdk 0.0.6 → 0.0.7

package/dist/tools/tool-registry.d.ts

@@ -1,424 +0,0 @@
-/**
- * Tool Registry for progressive tool disclosure.
- *
- * The ToolRegistry enables deferred tool loading to keep initial context small.
- * Instead of loading all tool schemas upfront, tools are registered with lightweight
- * metadata and loaded on-demand when the agent needs them.
- *
- * This mirrors the MCP Tool Search pattern used in Claude Code, where hundreds
- * of tools can be available without consuming context window until needed.
- *
- * @packageDocumentation
- */
-import type { Tool, ToolSet } from "ai";
-/**
- * Lightweight metadata for a registered tool.
- *
- * This is what the agent sees before loading - just enough information
- * to decide whether to load the full tool definition.
- *
- * @category Tools
- */
-export interface ToolMetadata {
-    /** Tool name (unique identifier) */
-    name: string;
-    /** Brief description for search/discovery */
-    description: string;
-    /** Plugin that provides this tool (if any) */
-    plugin?: string;
-    /** Category for grouping related tools */
-    category?: string;
-    /** Tags for semantic search */
-    tags?: string[];
-}
-/**
- * Result from loading tools.
- *
- * @category Tools
- */
-export interface ToolLoadResult {
-    /** Whether loading was successful */
-    success: boolean;
-    /** Names of tools that were loaded */
-    loaded: string[];
-    /** Names of tools that were already loaded (skipped) */
-    skipped: string[];
-    /** Names of tools that weren't found */
-    notFound: string[];
-    /** The loaded tools as a ToolSet */
-    tools: ToolSet;
-    /** Error message if something went wrong */
-    error?: string;
-}
-/**
- * Options for creating a tool registry.
- *
- * @category Tools
- */
-export interface ToolRegistryOptions {
-    /**
-     * Callback when tools are loaded.
-     */
-    onToolsLoaded?: (result: ToolLoadResult) => void;
-    /**
-     * Callback when the registry is updated.
-     */
-    onRegistryUpdated?: () => void;
-    /**
-     * Callback when a tool is registered.
-     */
-    onToolRegistered?: (input: {
-        tool_name: string;
-        description: string;
-        source?: string;
-    }) => void | Promise<void>;
-    /**
-     * Callback when a tool fails to load.
-     */
-    onToolLoadError?: (input: {
-        tool_name: string;
-        error: Error;
-        source?: string;
-    }) => void | Promise<void>;
-}
-/**
- * Options for searching tools.
- *
- * @category Tools
- */
-export interface ToolSearchOptions {
-    /** Search query (matches name, description, tags) */
-    query?: string;
-    /** Filter by plugin name */
-    plugin?: string;
-    /** Filter by category */
-    category?: string;
-    /** Filter by tags (any match) */
-    tags?: string[];
-    /** Include already-loaded tools in results */
-    includeLoaded?: boolean;
-    /** Maximum results to return */
-    limit?: number;
-}
-/**
- * Registry for managing tools with deferred loading.
- *
- * The ToolRegistry stores tools with lightweight metadata and loads full
- * definitions on-demand. This enables agents to have access to hundreds of
- * tools without consuming context window until needed.
- *
- * @example
- * ```typescript
- * const registry = new ToolRegistry();
- *
- * // Register tools (does not load them)
- * registry.register({
- *   name: "stripe_create_payment",
- *   description: "Create a payment intent in Stripe",
- *   plugin: "stripe",
- *   tool: stripeCreatePaymentTool,
- * });
- *
- * // Agent searches for tools
- * const matches = registry.search({ query: "payment" });
- * // Returns: [{ name: "stripe_create_payment", description: "..." }]
- *
- * // Agent loads tools when needed
- * const result = registry.load(["stripe_create_payment"]);
- * // Tools are now available for use
- * ```
- *
- * @category Tools
- */
-export declare class ToolRegistry {
-    /** All registered tools */
-    private entries;
-    /** Callbacks */
-    private onToolsLoaded?;
-    private onRegistryUpdated?;
-    private onToolRegistered?;
-    private onToolLoadError?;
-    /**
-     * Creates a new tool registry.
-     *
-     * @param options - Configuration options
-     */
-    constructor(options?: ToolRegistryOptions);
-    /**
-     * Register a tool with the registry.
-     *
-     * The tool is stored but not loaded - only metadata is exposed until
-     * the tool is explicitly loaded.
-     *
-     * @param metadata - Tool metadata
-     * @param toolDef - The full tool definition
-     * @throws Error if a tool with the same name is already registered
-     *
-     * @example
-     * ```typescript
-     * registry.register(
-     *   {
-     *     name: "send_email",
-     *     description: "Send an email via SMTP",
-     *     plugin: "email",
-     *     category: "communication",
-     *     tags: ["email", "notification"],
-     *   },
-     *   sendEmailTool
-     * );
-     * ```
-     */
-    register(metadata: ToolMetadata, toolDef: Tool): void;
-    /**
-     * Register multiple tools at once.
-     *
-     * @param tools - Array of [metadata, tool] tuples
-     *
-     * @example
-     * ```typescript
-     * registry.registerMany([
-     *   [{ name: "tool1", description: "..." }, tool1],
-     *   [{ name: "tool2", description: "..." }, tool2],
-     * ]);
-     * ```
-     */
-    registerMany(tools: Array<[ToolMetadata, Tool]>): void;
-    /**
-     * Register all tools from a plugin.
-     *
-     * Convenience method that extracts tool metadata and registers each tool
-     * with the plugin name attached.
-     *
-     * @param pluginName - Name of the plugin
-     * @param tools - ToolSet from the plugin
-     * @param options - Optional metadata overrides
-     *
-     * @example
-     * ```typescript
-     * registry.registerPlugin("stripe", stripePlugin.tools, {
-     *   category: "payments",
-     * });
-     * ```
-     */
-    registerPlugin(pluginName: string, tools: ToolSet, options?: {
-        category?: string;
-        tags?: string[];
-    }): void;
-    /**
-     * Unregister a tool from the registry.
-     *
-     * @param name - The tool name to unregister
-     * @returns True if the tool was found and removed
-     */
-    unregister(name: string): boolean;
-    /**
-     * Check if a tool is registered.
-     *
-     * @param name - The tool name to check
-     */
-    has(name: string): boolean;
-    /**
-     * Check if a tool is currently loaded.
-     *
-     * @param name - The tool name to check
-     */
-    isLoaded(name: string): boolean;
-    /**
-     * Get metadata for a registered tool.
-     *
-     * @param name - The tool name
-     * @returns Tool metadata or undefined if not found
-     */
-    getMetadata(name: string): ToolMetadata | undefined;
-    /**
-     * Search for tools matching criteria.
-     *
-     * Searches tool metadata (name, description, tags) without loading
-     * the full tool definitions.
-     *
-     * @param options - Search options
-     * @returns Array of matching tool metadata
-     *
-     * @example
-     * ```typescript
-     * // Search by query
-     * const paymentTools = registry.search({ query: "payment" });
-     *
-     * // Filter by plugin
-     * const stripeTools = registry.search({ plugin: "stripe" });
-     *
-     * // Combined search
-     * const results = registry.search({
-     *   query: "create",
-     *   plugin: "stripe",
-     *   limit: 5,
-     * });
-     * ```
-     */
-    search(options?: ToolSearchOptions): ToolMetadata[];
-    /**
-     * Load tools, making them available for use.
-     *
-     * @param names - Tool names to load
-     * @returns Result containing loaded tools and status
-     *
-     * @example
-     * ```typescript
-     * const result = registry.load(["stripe_create_payment", "stripe_refund"]);
-     * if (result.success) {
-     *   // result.tools contains the loaded ToolSet
-     *   // Inject into agent's active tools
-     * }
-     * ```
-     */
-    load(names: string[]): ToolLoadResult;
-    /**
-     * Load tools matching a search query.
-     *
-     * Convenience method combining search and load.
-     *
-     * @param options - Search options (same as search())
-     * @returns Result containing loaded tools
-     *
-     * @example
-     * ```typescript
-     * const result = registry.loadMatching({ query: "stripe", limit: 5 });
-     * ```
-     */
-    loadMatching(options: ToolSearchOptions): ToolLoadResult;
-    /**
-     * Get all currently loaded tools as a ToolSet.
-     *
-     * @returns ToolSet containing all loaded tools
-     */
-    getLoadedTools(): ToolSet;
-    /**
-     * List all available (not yet loaded) tools.
-     *
-     * @returns Array of tool metadata
-     */
-    listAvailable(): ToolMetadata[];
-    /**
-     * List all loaded tools.
-     *
-     * @returns Array of tool names
-     */
-    listLoaded(): string[];
-    /**
-     * List all registered tools with their load status.
-     *
-     * @returns Array of tool metadata with loaded flag
-     */
-    listAll(): Array<ToolMetadata & {
-        loaded: boolean;
-    }>;
-    /**
-     * Get all plugins that have registered tools.
-     *
-     * @returns Array of unique plugin names
-     */
-    listPlugins(): string[];
-    /**
-     * Reset all tools to unloaded state.
-     *
-     * Does not unregister tools, only marks them as unloaded.
-     */
-    reset(): void;
-    /**
-     * Clear all registered tools.
-     */
-    clear(): void;
-    /**
-     * Get the number of registered tools.
-     */
-    get size(): number;
-    /**
-     * Get the number of loaded tools.
-     */
-    get loadedCount(): number;
-    /**
-     * Build the tool index string for the use_tools description.
-     *
-     * This creates a compact representation of available tools that fits
-     * in the meta-tool description.
-     *
-     * @param options - Formatting options
-     * @returns Formatted tool index string
-     */
-    buildToolIndex(options?: {
-        includePlugins?: boolean;
-    }): string;
-}
-/**
- * Options for creating the use_tools meta-tool.
- *
- * @category Tools
- */
-export interface UseToolsToolOptions {
-    /** The tool registry to use */
-    registry: ToolRegistry;
-    /**
-     * Custom name for the tool.
-     * @defaultValue "use_tools"
-     */
-    name?: string;
-    /**
-     * Custom description prefix.
-     */
-    descriptionPrefix?: string;
-    /**
-     * Whether to include plugin groupings in tool index.
-     * @defaultValue true
-     */
-    groupByPlugin?: boolean;
-}
-/**
- * Creates the use_tools meta-tool for discovering and loading tools.
- *
- * This tool allows agents to search available tools and load them on-demand.
- * Tools loaded through this tool become available in subsequent agent steps.
- *
- * @param options - Configuration options
- * @returns An AI SDK compatible tool
- *
- * @example
- * ```typescript
- * const registry = new ToolRegistry();
- * registry.registerPlugin("stripe", stripePlugin.tools);
- *
- * const useToolsTool = createUseToolsTool({ registry });
- *
- * const agent = createAgent({
- *   model,
- *   tools: {
- *     ...coreTools,
- *     use_tools: useToolsTool,
- *   },
- *   toolRegistry: registry,
- * });
- * ```
- *
- * @category Tools
- */
-export declare function createUseToolsTool(options: UseToolsToolOptions): Tool<{
-    query?: string | undefined;
-    tools?: string[] | undefined;
-    plugin?: string | undefined;
-}, Record<string, unknown>>;
-/**
- * Creates a new tool registry.
- *
- * @param options - Configuration options
- * @returns A new ToolRegistry instance
- *
- * @example
- * ```typescript
- * const registry = createToolRegistry({
- *   onToolsLoaded: (result) => console.log("Loaded:", result.loaded),
- * });
- * ```
- *
- * @category Tools
- */
-export declare function createToolRegistry(options?: ToolRegistryOptions): ToolRegistry;
-//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tools/tool-registry.d.ts.map

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