/** * AI SDK Tools Registry - Core Registry Implementation * * Singleton-safe registry for managing built-in and custom tools. * Supports lazy loading, middleware, and multi-agent safety. */ import type { ToolMetadata, ToolFactory, PraisonTool, ToolHooks, ToolMiddleware, ToolInstallStatus } from './types'; /** * Thrown when a tool id is not present in the factory registry. * * Distinct from {@link ToolConstructionError} on purpose: "you asked for a * tool nobody registered" and "the registered tool failed to build" need * different fixes, and collapsing both into a `null` hid the second one. */ export declare class ToolNotRegisteredError extends Error { readonly toolId: string; constructor(id: string, available: string[]); } /** Thrown when a registered tool's factory throws while building an instance. */ export declare class ToolConstructionError extends Error { readonly toolId: string; constructor(id: string, cause: unknown); } /** * Tools Registry - Manages tool registration, lookup, and instantiation */ export declare class ToolsRegistry { private tools; private middleware; private hooks; private installCache; /** * Register a tool with the registry */ register(metadata: ToolMetadata, factory: ToolFactory): this; /** * Unregister a tool */ unregister(id: string): boolean; /** * Check if a tool is registered */ has(id: string): boolean; /** * Get tool metadata */ getMetadata(id: string): ToolMetadata | undefined; /** * List all registered tools */ list(): ToolMetadata[]; /** * List tools by tag */ listByTag(tag: string): ToolMetadata[]; /** * List tools by capability */ listByCapability(capability: keyof ToolMetadata['capabilities']): ToolMetadata[]; /** * Create a tool instance (lazy loads the dependency) */ create(id: string, config?: TConfig): PraisonTool; /** * Like {@link create}, but returns `null` when the tool is simply not * registered. A registered tool whose factory throws still raises * {@link ToolConstructionError} — a broken tool must never look identical * to a missing one. */ tryCreate(id: string, config?: TConfig): PraisonTool | null; /** * Add middleware to the pipeline */ use(middleware: ToolMiddleware): this; /** * Set hooks */ setHooks(hooks: ToolHooks): this; /** * Check if a tool's optional dependency is installed */ checkInstalled(id: string): Promise; /** * Check environment variables for a tool */ checkEnvVars(id: string): string[]; /** * Get installation status for a tool */ getInstallStatus(id: string): Promise; /** * Get installation status for all tools */ getAllInstallStatus(): Promise; /** * Clear the registry */ clear(): void; /** * Get the number of registered tools */ get size(): number; } /** * Get the global tools registry (singleton) */ export declare function getToolsRegistry(): ToolsRegistry; /** * Create a new isolated registry (for testing or multi-agent scenarios) */ export declare function createToolsRegistry(): ToolsRegistry; /** * Reset the global registry (mainly for testing) */ export declare function resetToolsRegistry(): void; /** * Register a tool FACTORY with the global factory registry. * * Not `register_tool`: Python's takes the callable you already have, this one * takes install metadata plus a builder. */ export declare function registerToolFactory(metadata: ToolMetadata, factory: ToolFactory): void; /** * Build an instance of a registered tool, throwing * {@link ToolNotRegisteredError} for an unknown id and * {@link ToolConstructionError} when the factory fails. */ export declare function createToolInstance(id: string, config?: TConfig): PraisonTool; /** * Build an instance of a registered tool, or `null` if no tool is registered * under `id`. * * A registered tool whose factory throws still raises * {@link ToolConstructionError}: "not registered" and "failed to build" are * different failures and must not share a return value. */ export declare function tryCreateToolInstance(id: string, config?: TConfig): PraisonTool | null; /** * @deprecated Ambiguous with `getTool` from `tools/decorator` (which looks a * tool up by name). Use {@link tryCreateToolInstance}, which says that it * BUILDS the tool. */ export declare const getTool: typeof tryCreateToolInstance; /** * Report whether a registered tool's npm dependency and required environment * variables are in place. * * Not `validate_tool`: Python's `validate_tool(tool)` takes the tool object * and raises `ToolValidationError` on a malformed tool — that one is exported * as `validateTool` / `validate_tool` from `tools/base.ts`. */ export declare function validateToolInstall(id: string): Promise<{ valid: boolean; installed: boolean; missingEnvVars: string[]; errors: string[]; }>;