@agentforge/core 0.16.47 → 0.16.49

package/dist/index.d.cts

@@ -6,349 +6,68 @@ import { AnnotationRoot, BaseChannel, StateDefinition, UpdateType, StateGraph, E
 import { RunnableConfig } from '@langchain/core/runnables';
 
 /**
- * Tool System Types
- *
- * Core type definitions for the AgentForge tool system.
- * These types define the structure and metadata for tools.
- */
-
-/**
- * ToolCategory - Categories for organizing tools
- *
- * Why use an enum?
- * - Type safety: Can't use invalid categories
- * - Autocomplete: IDE suggests valid options
- * - Consistency: Everyone uses the same category names
- *
- * Example:
- * ```ts
- * const tool = { category: ToolCategory.FILE_SYSTEM };
- * ```
+ * Categories for organizing tools.
  */
 declare enum ToolCategory {
-    /**
-     * Tools for file system operations
-     * Examples: read-file, write-file, list-directory
-     */
     FILE_SYSTEM = "file-system",
-    /**
-     * Tools for web/HTTP operations
-     * Examples: http-request, web-scrape, download-file
-     */
     WEB = "web",
-    /**
-     * Tools for code operations
-     * Examples: execute-code, analyze-syntax, format-code
-     */
     CODE = "code",
-    /**
-     * Tools for database operations
-     * Examples: query-database, insert-record, update-record
-     */
     DATABASE = "database",
-    /**
-     * Tools for API integrations
-     * Examples: github-api, slack-api, stripe-api
-     */
     API = "api",
-    /**
-     * General utility tools
-     * Examples: calculate, format-date, generate-uuid
-     */
     UTILITY = "utility",
-    /**
-     * Custom/user-defined tools
-     * Use this for tools that don't fit other categories
-     */
     CUSTOM = "custom",
-    /**
-     * Tools for Agent Skills activation and resource loading
-     * Examples: activate-skill, read-skill-resource
-     */
     SKILLS = "skills"
 }
+
 /**
- * ToolExample - Example usage of a tool
- *
- * Why examples?
- * - Help LLMs understand how to use the tool
- * - Provide documentation for developers
- * - Enable few-shot learning in prompts
- *
- * Example:
- * ```ts
- * const example: ToolExample = {
- *   description: 'Read a text file',
- *   input: { path: './README.md' },
- *   output: '# My Project\n\nWelcome...',
- *   explanation: 'Reads the file and returns its contents as a string'
- * };
- * ```
+ * Example usage of a tool to aid documentation and prompt construction.
  */
 interface ToolExample {
-    /**
-     * What this example demonstrates
-     * Should be concise and clear
-     */
     description: string;
-    /**
-     * Example input parameters
-     * Must match the tool's schema
-     */
     input: Record<string, unknown>;
-    /**
-     * Expected output (optional)
-     * Helps users understand what to expect
-     */
     output?: unknown;
-    /**
-     * Additional explanation (optional)
-     * Why this example works, edge cases, etc.
-     */
     explanation?: string;
 }
+
 /**
- * ToolRelations - Defines relationships between tools
- *
- * Helps LLMs understand tool workflows and dependencies.
- *
- * Why tool relations?
- * - Express dependencies: "Must call tool X before tool Y"
- * - Suggest workflows: "After X, consider calling Y"
- * - Prevent conflicts: "Don't use X and Y together"
- * - Guide LLM decisions: Better tool selection and ordering
- *
- * Example:
- * ```ts
- * const relations: ToolRelations = {
- *   requires: ['view-file'],      // Must call this first
- *   suggests: ['run-tests'],       // Often used together
- *   conflicts: ['delete-file'],    // Don't use together
- *   follows: ['search-codebase'],  // Typically called after
- *   precedes: ['edit-file']        // Typically called before
- * };
- * ```
+ * Relationships between tools to guide ordering and compatibility.
  */
 interface ToolRelations {
-    /**
-     * Tools that should be called before this tool
-     *
-     * Example: 'edit-file' requires 'view-file' to be called first
-     * to ensure you know the file contents before editing.
-     */
     requires?: string[];
-    /**
-     * Tools that work well with this tool
-     *
-     * Example: 'edit-file' suggests 'run-tests' to verify changes.
-     */
     suggests?: string[];
-    /**
-     * Tools that conflict with this tool
-     *
-     * Example: 'create-file' conflicts with 'delete-file' on the same path.
-     */
     conflicts?: string[];
-    /**
-     * Tools this typically follows in a workflow
-     *
-     * Example: 'edit-file' typically follows 'view-file' or 'search-codebase'.
-     */
     follows?: string[];
-    /**
-     * Tools this typically precedes in a workflow
-     *
-     * Example: 'view-file' typically precedes 'edit-file'.
-     */
     precedes?: string[];
 }
+
 /**
- * ToolMetadata - Rich metadata for a tool
- *
- * Why so much metadata?
- * - Better LLM understanding: More context = better tool selection
- * - Better developer experience: Clear documentation
- * - Better discoverability: Search by tags, categories
- * - Better maintenance: Version tracking, deprecation warnings
- *
- * Example:
- * ```ts
- * const metadata: ToolMetadata = {
- *   name: 'read-file',
- *   displayName: 'Read File',
- *   description: 'Read contents of a file from the file system',
- *   category: ToolCategory.FILE_SYSTEM,
- *   tags: ['file', 'read', 'io'],
- *   examples: [{ description: 'Read README', input: { path: './README.md' } }],
- *   usageNotes: 'Paths are relative to current working directory',
- *   limitations: ['Cannot read files larger than 10MB'],
- *   version: '1.0.0',
- *   author: 'AgentForge'
- * };
- * ```
+ * Rich metadata describing a tool, its examples, and its lifecycle state.
  */
 interface ToolMetadata {
-    /**
-     * Unique identifier for the tool
-     * Must be kebab-case (lowercase with hyphens)
-     * Examples: 'read-file', 'http-request', 'query-database'
-     */
     name: string;
-    /**
-     * Clear description of what the tool does
-     * Should be 1-2 sentences, written for LLMs to understand
-     * Example: 'Read the contents of a file from the file system'
-     */
     description: string;
-    /**
-     * Primary category for this tool
-     * Used for grouping and filtering
-     */
     category: ToolCategory;
-    /**
-     * Human-readable display name (optional)
-     * Example: 'Read File' instead of 'read-file'
-     */
     displayName?: string;
-    /**
-     * Tags for search and filtering (optional)
-     * Example: ['file', 'read', 'io', 'filesystem']
-     */
     tags?: string[];
-    /**
-     * Usage examples (optional but highly recommended)
-     * Helps LLMs understand how to use the tool
-     */
     examples?: ToolExample[];
-    /**
-     * Additional usage notes (optional)
-     * Important details about how to use the tool
-     * Example: 'Paths are relative to the current working directory'
-     */
     usageNotes?: string;
-    /**
-     * Known limitations (optional)
-     * What the tool cannot do
-     * Example: ['Cannot read files larger than 10MB', 'Requires read permissions']
-     */
     limitations?: string[];
-    /**
-     * Tool version (optional)
-     * Semantic versioning recommended
-     * Example: '1.0.0'
-     */
     version?: string;
-    /**
-     * Tool author (optional)
-     * Who created/maintains this tool
-     * Example: 'AgentForge Team'
-     */
     author?: string;
-    /**
-     * Deprecation flag (optional)
-     * Set to true if this tool should no longer be used
-     */
     deprecated?: boolean;
-    /**
-     * Replacement tool name (optional)
-     * If deprecated, what tool should be used instead?
-     * Example: 'read-file-v2'
-     */
     replacedBy?: string;
-    /**
-     * Tool relations (optional)
-     * Defines relationships with other tools
-     *
-     * Helps LLMs understand:
-     * - Which tools should be called before/after this tool
-     * - Which tools work well together
-     * - Which tools conflict with this tool
-     *
-     * Example:
-     * ```ts
-     * relations: {
-     *   requires: ['view-file'],
-     *   suggests: ['run-tests'],
-     *   follows: ['search-codebase']
-     * }
-     * ```
-     */
     relations?: ToolRelations;
 }
+
 /**
- * Tool - Complete tool definition
- *
- * This is the main interface that combines:
- * - Metadata: What the tool is and how to use it
- * - Schema: What inputs it accepts (validated with Zod)
- * - Execute: The actual implementation
- *
- * Why generic types?
- * - TInput: Type of the input parameters (inferred from schema)
- * - TOutput: Type of the return value
- * - This gives us full type safety!
- *
- * Example:
- * ```ts
- * const readFileTool: Tool<{ path: string }, string> = {
- *   metadata: { name: 'read-file', ... },
- *   schema: z.object({ path: z.string() }),
- *   execute: async ({ path }) => {
- *     // Implementation here
- *     return fileContents;
- *   }
- * };
- * ```
+ * Complete tool contract combining metadata, input schema, and invocation API.
  */
 interface Tool<TInput = unknown, TOutput = unknown> {
-    /**
-     * Rich metadata about the tool
-     */
     metadata: ToolMetadata;
-    /**
-     * Zod schema for input validation
-     *
-     * Why Zod?
-     * - Runtime validation: Catch errors before execution
-     * - Type inference: TypeScript types from schema
-     * - Great error messages: Clear validation errors
-     * - JSON Schema conversion: For LangChain integration
-     */
     schema: z.ZodSchema<TInput>;
-    /**
-     * Tool implementation (primary method)
-     *
-     * Why async?
-     * - Most tools do I/O (files, network, database)
-     * - Async is more flexible (can handle both sync and async)
-     *
-     * The input is automatically validated against the schema
-     * before this function is called.
-     *
-     * This is the industry standard method name used by LangChain.
-     *
-     * @example
-     * ```ts
-     * const result = await tool.invoke({ input: 'hello' });
-     * ```
-     */
     invoke: (input: TInput) => Promise<TOutput>;
     /**
-     * Deprecated alias for invoke()
-     *
-     * @deprecated Use invoke() instead. This method will be removed in v1.0.0.
-     *
-     * Both methods do exactly the same thing, but invoke() is the industry
-     * standard used by LangChain and should be preferred.
-     *
-     * @example
-     * ```ts
-     * // ❌ Deprecated (still works, but will be removed in v1.0.0):
-     * const result1 = await tool.execute({ input: 'hello' });
-     *
-     * // ✅ Preferred (industry standard):
-     * const result2 = await tool.invoke({ input: 'hello' });
-     * ```
+     * @deprecated Use `invoke` instead.
      */
     execute?: (input: TInput) => Promise<TOutput>;
 }
@@ -1009,10 +728,6 @@ declare class ToolRegistry {
     generatePrompt(options?: PromptOptions): string;
 }
 
-/**
- * Tool Executor - Async tool execution with resource management
- * @module tools/executor
- */
 type Priority$1 = 'low' | 'normal' | 'high' | 'critical';
 type BackoffStrategy$1 = 'linear' | 'exponential' | 'fixed';
 interface RetryPolicy {
@@ -1022,6 +737,14 @@ interface RetryPolicy {
     maxDelay?: number;
     retryableErrors?: string[];
 }
+interface ExecutableTool<TInput = unknown, TOutput = unknown> {
+    name?: string;
+    metadata?: {
+        name?: string;
+    };
+    invoke?: (input: TInput) => Promise<TOutput>;
+    execute?: (input: TInput) => Promise<TOutput>;
+}
 interface ToolExecutorConfig {
     maxConcurrent?: number;
     timeout?: number;
@@ -1044,13 +767,12 @@ interface ExecutionMetrics {
     averageDuration: number;
     byPriority: Record<Priority$1, number>;
 }
-interface ExecutableTool<TInput = unknown, TOutput = unknown> {
-    metadata?: {
-        name?: string;
-    };
-    invoke?: (input: TInput) => Promise<TOutput>;
-    execute?: (input: TInput) => Promise<TOutput>;
-}
+
+/**
+ * Tool Executor - Async tool execution with resource management
+ * @module tools/executor
+ */
+
 /**
  * Create a tool executor with resource management
  */