@agentforge/core 0.16.35 → 0.16.37

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { z, ZodTypeAny, output, ZodType, ZodTypeDef } from 'zod';
+import * as _langchain_core_tools from '@langchain/core/tools';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 import * as _langchain_langgraph from '@langchain/langgraph';
 import { AnnotationRoot, BaseChannel, StateDefinition, UpdateType, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
@@ -919,233 +920,44 @@ declare function validateTool(tool: Tool): {
     errors: string[];
 };
 
-/**
- * Tool Builder API
- *
- * Fluent interface for creating tools with automatic validation.
- *
- * @example
- * ```ts
- * const tool = createToolBuilder()
- *   .name('read-file')
- *   .description('Read a file from the file system')
- *   .category(ToolCategory.FILE_SYSTEM)
- *   .tags(['file', 'read', 'io'])
- *   .schema(z.object({
- *     path: z.string().describe('Path to the file')
- *   }))
- *   .implement(async ({ path }) => {
- *     // Implementation
- *   })
- *   .build();
- * ```
- */
-
 type ToolInvoke<TOutput> = (this: unknown, input: unknown) => Promise<TOutput>;
-/**
- * Builder for creating tools with a fluent API
- *
- * This provides a more ergonomic way to create tools compared to
- * manually constructing the metadata object.
- */
+type SafeToolResult<T> = {
+    success: boolean;
+    data?: T;
+    error?: string;
+};
+
 declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
     private metadata;
     private _schema?;
     private _invoke?;
     constructor(metadata?: Partial<ToolMetadata>, _schema?: z.ZodSchema<TInput> | undefined, _invoke?: ToolInvoke<TOutput> | undefined);
-    /**
-     * Set the tool name (required)
-     *
-     * @param name - Tool name in kebab-case (e.g., 'read-file')
-     */
     name(name: string): this;
-    /**
-     * Set the tool description (required)
-     *
-     * @param description - Clear description of what the tool does
-     */
     description(description: string): this;
-    /**
-     * Set the tool category (required)
-     *
-     * @param category - Tool category for organization
-     */
     category(category: ToolCategory): this;
-    /**
-     * Set the display name (optional)
-     *
-     * @param displayName - Human-friendly name for UI display
-     */
     displayName(displayName: string): this;
-    /**
-     * Set tags for searchability (optional)
-     *
-     * @param tags - Array of tags for categorization and search
-     */
     tags(tags: string[]): this;
-    /**
-     * Add a single tag (optional)
-     *
-     * @param tag - Tag to add
-     */
     tag(tag: string): this;
-    /**
-     * Add an example (optional)
-     *
-     * @param example - Usage example for the tool
-     */
     example(example: ToolExample): this;
-    /**
-     * Set usage notes (optional)
-     *
-     * @param notes - Important usage information
-     */
     usageNotes(notes: string): this;
-    /**
-     * Set limitations (optional)
-     *
-     * @param limitations - Array of known limitations
-     */
     limitations(limitations: string[]): this;
-    /**
-     * Add a single limitation (optional)
-     *
-     * @param limitation - Limitation to add
-     */
     limitation(limitation: string): this;
-    /**
-     * Set version (optional)
-     *
-     * @param version - Semantic version string
-     */
     version(version: string): this;
-    /**
-     * Set author (optional)
-     *
-     * @param author - Tool author name
-     */
     author(author: string): this;
-    /**
-     * Set tools that must be called before this tool (optional)
-     *
-     * @param tools - Array of tool names that are required
-     * @example
-     * ```ts
-     * .requires(['view-file', 'search-codebase'])
-     * ```
-     */
     requires(tools: string[]): this;
-    /**
-     * Set tools that work well with this tool (optional)
-     *
-     * @param tools - Array of tool names that are suggested
-     * @example
-     * ```ts
-     * .suggests(['run-tests', 'format-code'])
-     * ```
-     */
     suggests(tools: string[]): this;
-    /**
-     * Set tools that conflict with this tool (optional)
-     *
-     * @param tools - Array of tool names that conflict
-     * @example
-     * ```ts
-     * .conflicts(['delete-file'])
-     * ```
-     */
     conflicts(tools: string[]): this;
-    /**
-     * Set tools this typically follows in a workflow (optional)
-     *
-     * @param tools - Array of tool names this follows
-     * @example
-     * ```ts
-     * .follows(['search-codebase', 'view-file'])
-     * ```
-     */
     follows(tools: string[]): this;
-    /**
-     * Set tools this typically precedes in a workflow (optional)
-     *
-     * @param tools - Array of tool names this precedes
-     * @example
-     * ```ts
-     * .precedes(['run-tests'])
-     * ```
-     */
     precedes(tools: string[]): this;
-    /**
-     * Set the input schema (required)
-     *
-     * All fields MUST have .describe() for LLM understanding!
-     *
-     * @param schema - Zod schema for input validation
-     */
     schema<T>(schema: z.ZodSchema<T>): ToolBuilder<T, TOutput>;
-    /**
-     * Set the implementation function (required)
-     *
-     * @param invoke - Async function that implements the tool
-     */
     implement<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
-    /**
-     * Set the implementation function with automatic error handling
-     *
-     * Wraps the implementation in a try-catch block and returns a standardized
-     * result object with success/error information.
-     *
-     * @param invoke - Async function that implements the tool
-     * @returns ToolBuilder with safe result type { success: boolean; data?: T; error?: string }
-     *
-     * @example
-     * ```ts
-     * const tool = toolBuilder()
-     *   .name('read-file')
-     *   .schema(z.object({ path: z.string() }))
-     *   .implementSafe(async ({ path }) => {
-     *     return await fs.readFile(path, 'utf-8');
-     *   })
-     *   .build();
-     *
-     * // Result will be: { success: true, data: "file content" }
-     * // Or on error: { success: false, error: "ENOENT: no such file..." }
-     * ```
-     */
-    implementSafe<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, {
-        success: boolean;
-        data?: T;
-        error?: string;
-    }>;
-    /**
-     * Build the tool with validation
-     *
-     * Validates:
-     * - All required fields are present
-     * - Metadata is valid
-     * - Schema has descriptions on all fields
-     *
-     * @returns The validated tool
-     * @throws {Error} If validation fails
-     */
+    implementSafe<T>(invoke: (input: TInput) => Promise<T>): ToolBuilder<TInput, SafeToolResult<T>>;
     build(): Tool<TInput, TOutput>;
 }
-/**
- * Create a new tool builder
- *
- * @example
- * ```ts
- * const tool = toolBuilder()
- *   .name('my-tool')
- *   .description('Does something useful')
- *   .category(ToolCategory.UTILITY)
- *   .schema(z.object({ input: z.string().describe('Input') }))
- *   .implement(async ({ input }) => input)
- *   .build();
- * ```
- */
 declare function toolBuilder(): ToolBuilder;
 
+type RegistryTool = Tool<unknown, unknown>;
+
 type RegistryEventHandler<TData = unknown> = (data: TData) => void;
 
 interface RegistryPromptOptions {
@@ -1159,355 +971,41 @@ interface RegistryPromptOptions {
     minimal?: boolean;
 }
 
-/**
- * Tool Registry
- *
- * Central registry for managing and querying tools.
- * Provides CRUD operations, querying, and event notifications.
- *
- * @example
- * ```ts
- * const registry = new ToolRegistry();
- *
- * registry.register(readFileTool);
- * registry.register(writeFileTool);
- *
- * const fileTool = registry.get('read-file');
- * const fileTools = registry.getByCategory(ToolCategory.FILE_SYSTEM);
- * ```
- */
-
-/**
- * Registry events
- */
 declare enum RegistryEvent {
     TOOL_REGISTERED = "tool:registered",
     TOOL_REMOVED = "tool:removed",
     TOOL_UPDATED = "tool:updated",
     REGISTRY_CLEARED = "registry:cleared"
 }
-/**
- * Event handler type
- */
 type EventHandler = RegistryEventHandler;
-type RegisterManyTool = Tool<never, unknown>;
-type RegistryTool = Tool<unknown, unknown>;
-/**
- * Options for generating tool prompts
- */
 interface PromptOptions extends RegistryPromptOptions {
-    /** Include usage examples in the prompt */
-    includeExamples?: boolean;
-    /** Include usage notes in the prompt */
-    includeNotes?: boolean;
-    /** Include limitations in the prompt */
-    includeLimitations?: boolean;
-    /** Include tool relations in the prompt */
-    includeRelations?: boolean;
-    /** Group tools by category */
-    groupByCategory?: boolean;
-    /** Filter by specific categories */
-    categories?: ToolCategory[];
-    /** Maximum number of examples to include per tool */
-    maxExamplesPerTool?: number;
-    /**
-     * Minimal mode - only supplementary context, not full definitions
-     *
-     * Use this when tool definitions are sent via API (OpenAI, Anthropic, etc.)
-     *
-     * When true:
-     * - Excludes basic tool name/description/parameters
-     * - Includes only relations, examples, notes, limitations
-     * - Tool names are used as headers for matching
-     *
-     * When false (default):
-     * - Includes full tool definitions (current behavior)
-     * - Backward compatible
-     */
-    minimal?: boolean;
 }
-/**
- * Tool Registry - Central registry for managing tools
- *
- * Features:
- * - CRUD operations (register, get, remove, update)
- * - Query operations (by category, tag, search)
- * - Bulk operations (registerMany, clear)
- * - Event system for observability
- *
- * @example
- * ```ts
- * const registry = new ToolRegistry();
- *
- * // Register tools
- * registry.register(myTool);
- * registry.registerMany([tool1, tool2, tool3]);
- *
- * // Query tools
- * const tool = registry.get('my-tool');
- * const fileTools = registry.getByCategory(ToolCategory.FILE_SYSTEM);
- * const searchResults = registry.search('file');
- *
- * // Listen to events
- * registry.on(RegistryEvent.TOOL_REGISTERED, (tool) => {
- *   console.log('Tool registered:', tool.metadata.name);
- * });
- * ```
- */
+
 declare class ToolRegistry {
     private tools;
     private eventHandlers;
     private readonly mutationEvents;
     private readonly emitMutation;
-    /**
-     * Register a tool in the registry
-     *
-     * @param tool - The tool to register
-     * @throws Error if a tool with the same name already exists
-     *
-    * @example
-    * ```ts
-    * registry.register(readFileTool);
-     * ```
-     */
+    private readonly mutations;
+    private readonly queries;
+    constructor();
     register<TInput, TOutput>(tool: Tool<TInput, TOutput>): void;
-    /**
-     * Get a tool by name
-     *
-     * @param name - The tool name
-     * @returns The tool, or undefined if not found
-     *
-     * @example
-     * ```ts
-     * const tool = registry.get('read-file');
-     * if (tool) {
-     *   const result = await tool.execute({ path: './file.txt' });
-     * }
-     * ```
-     */
     get(name: string): RegistryTool | undefined;
-    /**
-     * Check if a tool exists in the registry
-     *
-     * @param name - The tool name
-     * @returns True if the tool exists
-     *
-     * @example
-     * ```ts
-     * if (registry.has('read-file')) {
-     *   console.log('Tool exists!');
-     * }
-     * ```
-     */
     has(name: string): boolean;
-    /**
-     * Remove a tool from the registry
-     *
-     * @param name - The tool name
-     * @returns True if the tool was removed, false if it didn't exist
-     *
-    * @example
-    * ```ts
-    * const removed = registry.remove('read-file');
-    * console.log(removed ? 'Removed' : 'Not found');
-     * ```
-     */
     remove(name: string): boolean;
-    /**
-     * Update an existing tool
-     *
-     * @param name - The tool name
-     * @param tool - The new tool definition
-     * @returns True if updated, false if the tool didn't exist
-     * @throws Error if the tool's metadata.name doesn't match the name parameter
-     *
-    * @example
-    * ```ts
-    * const updated = registry.update('read-file', newReadFileTool);
-     * ```
-     */
     update<TInput, TOutput>(name: string, tool: Tool<TInput, TOutput>): boolean;
-    /**
-     * Get all registered tools
-     *
-     * @returns Array of all tools
-     *
-     * @example
-     * ```ts
-     * const allTools = registry.getAll();
-     * console.log(`Total tools: ${allTools.length}`);
-     * ```
-     */
     getAll(): RegistryTool[];
-    /**
-     * Get tools by category
-     *
-     * @param category - The tool category
-     * @returns Array of tools in the category
-     *
-     * @example
-     * ```ts
-     * const fileTools = registry.getByCategory(ToolCategory.FILE_SYSTEM);
-     * ```
-     */
     getByCategory(category: ToolCategory): RegistryTool[];
-    /**
-     * Get tools by tag
-     *
-     * @param tag - The tag to search for
-     * @returns Array of tools with the tag
-     *
-     * @example
-     * ```ts
-     * const fileTools = registry.getByTag('file');
-     * ```
-     */
     getByTag(tag: string): RegistryTool[];
-    /**
-     * Search tools by name or description
-     *
-     * Case-insensitive search across tool names, display names, and descriptions.
-     *
-     * @param query - The search query
-     * @returns Array of matching tools
-     *
-     * @example
-     * ```ts
-     * const results = registry.search('file');
-     * // Returns tools with 'file' in name or description
-     * ```
-     */
     search(query: string): RegistryTool[];
-    /**
-     * Register multiple tools at once
-     *
-     * @param tools - Iterable of tools to register
-     * @throws Error if any tool name conflicts with existing tools
-     *
-    * @example
-    * ```ts
-    * registry.registerMany([tool1, tool2, tool3]);
-     * ```
-     */
-    registerMany(tools: Iterable<RegisterManyTool>): void;
-    /**
-     * Clear all tools from the registry
-     *
-    * @example
-    * ```ts
-    * registry.clear();
-    * console.log(registry.size()); // 0
-     * ```
-     */
+    registerMany(tools: Iterable<Tool<never, unknown>>): void;
     clear(): void;
-    /**
-     * Get the number of registered tools
-     *
-     * @returns Number of tools in the registry
-     *
-     * @example
-     * ```ts
-     * console.log(`Registry has ${registry.size()} tools`);
-     * ```
-     */
     size(): number;
-    /**
-     * Get all tool names
-     *
-     * @returns Array of tool names
-     *
-     * @example
-     * ```ts
-     * const names = registry.getNames();
-     * console.log('Available tools:', names.join(', '));
-     * ```
-     */
     getNames(): string[];
-    /**
-     * Register an event handler
-     *
-     * @param event - The event to listen for
-     * @param handler - The handler function
-     *
-     * @example
-     * ```ts
-     * registry.on(RegistryEvent.TOOL_REGISTERED, (tool) => {
-     *   console.log('New tool:', tool.metadata.name);
-     * });
-     * ```
-     */
     on(event: RegistryEvent, handler: EventHandler): void;
-    /**
-     * Unregister an event handler
-     *
-     * @param event - The event to stop listening for
-     * @param handler - The handler function to remove
-     *
-     * @example
-     * ```ts
-     * const handler = (tool) => console.log(tool);
-     * registry.on(RegistryEvent.TOOL_REGISTERED, handler);
-     * registry.off(RegistryEvent.TOOL_REGISTERED, handler);
-     * ```
-     */
     off(event: RegistryEvent, handler: EventHandler): void;
-    /**
-     * Emit an event to all registered handlers
-     *
-     * @param event - The event to emit
-     * @param data - The event data
-     * @private
-     */
     private emit;
-    /**
-     * Convert all registered tools to LangChain format
-     *
-     * This allows the entire registry to be used with LangChain agents.
-     *
-     * @returns Array of LangChain DynamicStructuredTools
-     *
-     * @example
-     * ```ts
-     * const registry = new ToolRegistry();
-     * registry.registerMany([tool1, tool2, tool3]);
-     *
-     * const langchainTools = registry.toLangChainTools();
-     *
-     * const agent = createAgent({
-     *   model: new ChatOpenAI(),
-     *   tools: langchainTools,
-     * });
-     * ```
-     */
-    toLangChainTools(): DynamicStructuredTool[];
-    /**
-     * Generate a formatted prompt describing all tools
-     *
-     * Creates a human-readable description of all tools in the registry,
-     * suitable for inclusion in LLM prompts.
-     *
-     * @param options - Options for customizing the prompt
-     * @returns Formatted prompt string
-     *
-     * @example
-     * ```ts
-     * const prompt = registry.generatePrompt({
-     *   includeExamples: true,
-     *   groupByCategory: true,
-     *   maxExamplesPerTool: 2,
-     * });
-     *
-     * console.log(prompt);
-     * // Available Tools:
-     * //
-     * // FILE SYSTEM TOOLS:
-     * // - read-file: Read a file from the file system
-     * //   Parameters: path (string)
-     * //   Example: Read a text file
-     * //     Input: { "path": "./README.md" }
-     * // ...
-     * ```
-     */
+    toLangChainTools(): _langchain_core_tools.DynamicStructuredTool<_langchain_core_tools.ToolSchemaBase, any, any, any, string>[];
     generatePrompt(options?: PromptOptions): string;
 }