@agentforge/core 0.16.35 → 0.16.37

package/dist/index.js

@@ -318,7 +318,54 @@ function validateTool(tool) {
   };
 }
 
-// src/tools/builder.ts
+// src/tools/builder-finalize.ts
+function assertBuildable(metadata, schema, invoke) {
+  if (!metadata.name) {
+    throw new Error("Tool name is required. Use .name() to set it.");
+  }
+  if (!metadata.description) {
+    throw new Error("Tool description is required. Use .description() to set it.");
+  }
+  if (!metadata.category) {
+    throw new Error("Tool category is required. Use .category() to set it.");
+  }
+  if (!schema) {
+    throw new Error("Tool schema is required. Use .schema() to set it.");
+  }
+  if (!invoke) {
+    throw new Error("Tool implementation is required. Use .implement() to set it.");
+  }
+}
+function buildTool(metadata, schema, invoke) {
+  assertBuildable(metadata, schema, invoke);
+  const finalSchema = schema;
+  const finalInvoke = invoke;
+  return createTool(metadata, finalSchema, async function(input) {
+    return finalInvoke.call(this, input);
+  });
+}
+
+// src/tools/builder-implementation.ts
+function wrapInvoke(invoke) {
+  return async function(input) {
+    return invoke.call(this, input);
+  };
+}
+function wrapSafeInvoke(invoke) {
+  return wrapInvoke(async function(input) {
+    try {
+      const data = await invoke.call(this, input);
+      return { success: true, data };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  });
+}
+
+// src/tools/builder-metadata.ts
 function cloneRelations(relations) {
   if (!relations) {
     return void 0;
@@ -357,338 +404,121 @@ function cloneMetadata(metadata) {
     relations: cloneRelations(metadata.relations)
   };
 }
+function appendMetadataList(metadata, key, value) {
+  if (!metadata[key]) {
+    metadata[key] = [];
+  }
+  metadata[key].push(value);
+}
+function appendExample(metadata, example) {
+  if (!metadata.examples) {
+    metadata.examples = [];
+  }
+  metadata.examples.push(example);
+}
+function setRelation(metadata, relation, tools) {
+  metadata.relations = {
+    ...metadata.relations ?? {},
+    [relation]: tools
+  };
+}
+
+// src/tools/builder.ts
 var ToolBuilder = class _ToolBuilder {
   constructor(metadata = {}, _schema, _invoke) {
     this.metadata = metadata;
     this._schema = _schema;
     this._invoke = _invoke;
   }
-  /**
-   * Set the tool name (required)
-   * 
-   * @param name - Tool name in kebab-case (e.g., 'read-file')
-   */
   name(name) {
     this.metadata.name = name;
     return this;
   }
-  /**
-   * Set the tool description (required)
-   * 
-   * @param description - Clear description of what the tool does
-   */
   description(description) {
     this.metadata.description = description;
     return this;
   }
-  /**
-   * Set the tool category (required)
-   * 
-   * @param category - Tool category for organization
-   */
   category(category) {
     this.metadata.category = category;
     return this;
   }
-  /**
-   * Set the display name (optional)
-   * 
-   * @param displayName - Human-friendly name for UI display
-   */
   displayName(displayName) {
     this.metadata.displayName = displayName;
     return this;
   }
-  /**
-   * Set tags for searchability (optional)
-   * 
-   * @param tags - Array of tags for categorization and search
-   */
   tags(tags) {
     this.metadata.tags = tags;
     return this;
   }
-  /**
-   * Add a single tag (optional)
-   * 
-   * @param tag - Tag to add
-   */
   tag(tag) {
-    if (!this.metadata.tags) {
-      this.metadata.tags = [];
-    }
-    this.metadata.tags.push(tag);
+    appendMetadataList(this.metadata, "tags", tag);
     return this;
   }
-  /**
-   * Add an example (optional)
-   * 
-   * @param example - Usage example for the tool
-   */
   example(example) {
-    if (!this.metadata.examples) {
-      this.metadata.examples = [];
-    }
-    this.metadata.examples.push(example);
+    appendExample(this.metadata, example);
     return this;
   }
-  /**
-   * Set usage notes (optional)
-   * 
-   * @param notes - Important usage information
-   */
   usageNotes(notes) {
     this.metadata.usageNotes = notes;
     return this;
   }
-  /**
-   * Set limitations (optional)
-   * 
-   * @param limitations - Array of known limitations
-   */
   limitations(limitations) {
     this.metadata.limitations = limitations;
     return this;
   }
-  /**
-   * Add a single limitation (optional)
-   * 
-   * @param limitation - Limitation to add
-   */
   limitation(limitation) {
-    if (!this.metadata.limitations) {
-      this.metadata.limitations = [];
-    }
-    this.metadata.limitations.push(limitation);
+    appendMetadataList(this.metadata, "limitations", limitation);
     return this;
   }
-  /**
-   * Set version (optional)
-   * 
-   * @param version - Semantic version string
-   */
   version(version) {
     this.metadata.version = version;
     return this;
   }
-  /**
-   * Set author (optional)
-   *
-   * @param author - Tool author name
-   */
   author(author) {
     this.metadata.author = author;
     return 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) {
-    if (!this.metadata.relations) {
-      this.metadata.relations = {};
-    }
-    this.metadata.relations.requires = tools;
+    setRelation(this.metadata, "requires", tools);
     return 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) {
-    if (!this.metadata.relations) {
-      this.metadata.relations = {};
-    }
-    this.metadata.relations.suggests = tools;
+    setRelation(this.metadata, "suggests", tools);
     return this;
   }
-  /**
-   * Set tools that conflict with this tool (optional)
-   *
-   * @param tools - Array of tool names that conflict
-   * @example
-   * ```ts
-   * .conflicts(['delete-file'])
-   * ```
-   */
   conflicts(tools) {
-    if (!this.metadata.relations) {
-      this.metadata.relations = {};
-    }
-    this.metadata.relations.conflicts = tools;
+    setRelation(this.metadata, "conflicts", tools);
     return 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) {
-    if (!this.metadata.relations) {
-      this.metadata.relations = {};
-    }
-    this.metadata.relations.follows = tools;
+    setRelation(this.metadata, "follows", tools);
     return 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) {
-    if (!this.metadata.relations) {
-      this.metadata.relations = {};
-    }
-    this.metadata.relations.precedes = tools;
+    setRelation(this.metadata, "precedes", tools);
     return this;
   }
-  /**
-   * Set the input schema (required)
-   *
-   * All fields MUST have .describe() for LLM understanding!
-   *
-   * @param schema - Zod schema for input validation
-   */
   schema(schema) {
     return new _ToolBuilder(cloneMetadata(this.metadata), schema, this._invoke);
   }
-  /**
-   * Set the implementation function (required)
-   *
-   * @param invoke - Async function that implements the tool
-   */
   implement(invoke) {
-    const wrappedInvoke = async function(input) {
-      return invoke.call(this, input);
-    };
-    return new _ToolBuilder(cloneMetadata(this.metadata), this._schema, wrappedInvoke);
+    return new _ToolBuilder(cloneMetadata(this.metadata), this._schema, wrapInvoke(invoke));
   }
-  /**
-   * 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(invoke) {
-    const safeInvoke = async function(input) {
-      try {
-        const data = await invoke.call(this, input);
-        return { success: true, data };
-      } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : String(error)
-        };
-      }
-    };
-    const wrappedInvoke = async function(input) {
-      return safeInvoke.call(this, input);
-    };
     return new _ToolBuilder(
       cloneMetadata(this.metadata),
       this._schema,
-      wrappedInvoke
+      wrapSafeInvoke(invoke)
     );
   }
-  /**
-   * 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
-   */
   build() {
-    if (!this.metadata.name) {
-      throw new Error("Tool name is required. Use .name() to set it.");
-    }
-    if (!this.metadata.description) {
-      throw new Error("Tool description is required. Use .description() to set it.");
-    }
-    if (!this.metadata.category) {
-      throw new Error("Tool category is required. Use .category() to set it.");
-    }
-    if (!this._schema) {
-      throw new Error("Tool schema is required. Use .schema() to set it.");
-    }
-    if (!this._invoke) {
-      throw new Error("Tool implementation is required. Use .implement() to set it.");
-    }
-    const invoke = this._invoke;
-    return createTool(
-      this.metadata,
-      this._schema,
-      async function(input) {
-        return invoke.call(this, input);
-      }
-    );
+    return buildTool(this.metadata, this._schema, this._invoke);
   }
 };
 function toolBuilder() {
   return new ToolBuilder();
 }
 
-// src/tools/registry-collection.ts
-function getAllRegistryTools(tools) {
-  return Array.from(tools.values());
-}
-function getRegistryToolNames(tools) {
-  return Array.from(tools.keys());
-}
-function getRegistryToolsByCategory(tools, category) {
-  return getAllRegistryTools(tools).filter((tool) => tool.metadata.category === category);
-}
-function getRegistryToolsByTag(tools, tag) {
-  return getAllRegistryTools(tools).filter((tool) => tool.metadata.tags?.includes(tag));
-}
-function searchRegistryTools(tools, query) {
-  const lowerQuery = query.toLowerCase();
-  return getAllRegistryTools(tools).filter((tool) => {
-    const name = tool.metadata.name.toLowerCase();
-    const displayName = tool.metadata.displayName?.toLowerCase() ?? "";
-    const description = tool.metadata.description.toLowerCase();
-    return name.includes(lowerQuery) || displayName.includes(lowerQuery) || description.includes(lowerQuery);
-  });
-}
-
 // src/langgraph/observability/logger.ts
 var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
   LogLevel2["DEBUG"] = "debug";
@@ -889,6 +719,40 @@ function clearRegistryTools(tools, emit, events) {
   emit(events.cleared, null);
 }
 
+// src/tools/registry-mutation-api.ts
+function createRegistryMutationApi(tools, emit, events) {
+  return {
+    register: (tool) => registerRegistryTool(tools, tool, emit, events),
+    remove: (name) => removeRegistryTool(tools, name, emit, events),
+    update: (name, tool) => updateRegistryTool(tools, name, tool, emit, events),
+    registerMany: (toolsToRegister) => registerManyRegistryTools(tools, toolsToRegister, emit, events),
+    clear: () => clearRegistryTools(tools, emit, events)
+  };
+}
+
+// src/tools/registry-collection.ts
+function getAllRegistryTools(tools) {
+  return Array.from(tools.values());
+}
+function getRegistryToolNames(tools) {
+  return Array.from(tools.keys());
+}
+function getRegistryToolsByCategory(tools, category) {
+  return getAllRegistryTools(tools).filter((tool) => tool.metadata.category === category);
+}
+function getRegistryToolsByTag(tools, tag) {
+  return getAllRegistryTools(tools).filter((tool) => tool.metadata.tags?.includes(tag));
+}
+function searchRegistryTools(tools, query) {
+  const lowerQuery = query.toLowerCase();
+  return getAllRegistryTools(tools).filter((tool) => {
+    const name = tool.metadata.name.toLowerCase();
+    const displayName = tool.metadata.displayName?.toLowerCase() ?? "";
+    const description = tool.metadata.description.toLowerCase();
+    return name.includes(lowerQuery) || displayName.includes(lowerQuery) || description.includes(lowerQuery);
+  });
+}
+
 // src/tools/registry-prompt.ts
 import { z as z3 } from "zod";
 
@@ -1151,7 +1015,23 @@ function getSchemaShape(schema) {
   return void 0;
 }
 
-// src/tools/registry.ts
+// src/tools/registry-query-api.ts
+function createRegistryQueryApi(tools) {
+  return {
+    get: (name) => tools.get(name),
+    has: (name) => tools.has(name),
+    getAll: () => getAllRegistryTools(tools),
+    getByCategory: (category) => getRegistryToolsByCategory(tools, category),
+    getByTag: (tag) => getRegistryToolsByTag(tools, tag),
+    search: (query) => searchRegistryTools(tools, query),
+    size: () => tools.size,
+    getNames: () => getRegistryToolNames(tools),
+    toLangChainTools: () => convertRegistryToolsToLangChain(getAllRegistryTools(tools)),
+    generatePrompt: (options = {}) => generateRegistryPrompt(getAllRegistryTools(tools), options)
+  };
+}
+
+// src/tools/registry-types.ts
 var RegistryEvent = /* @__PURE__ */ ((RegistryEvent2) => {
   RegistryEvent2["TOOL_REGISTERED"] = "tool:registered";
   RegistryEvent2["TOOL_REMOVED"] = "tool:removed";
@@ -1159,6 +1039,8 @@ var RegistryEvent = /* @__PURE__ */ ((RegistryEvent2) => {
   RegistryEvent2["REGISTRY_CLEARED"] = "registry:cleared";
   return RegistryEvent2;
 })(RegistryEvent || {});
+
+// src/tools/registry.ts
 var ToolRegistry = class {
   tools = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
@@ -1171,291 +1053,65 @@ var ToolRegistry = class {
   emitMutation = (event, data) => {
     this.emit(event, data);
   };
-  /**
-   * 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);
-   * ```
-   */
+  mutations;
+  queries;
+  constructor() {
+    this.mutations = createRegistryMutationApi(this.tools, this.emitMutation, this.mutationEvents);
+    this.queries = createRegistryQueryApi(this.tools);
+  }
   register(tool) {
-    registerRegistryTool(this.tools, tool, this.emitMutation, this.mutationEvents);
+    this.mutations.register(tool);
   }
-  /**
-   * 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) {
-    return this.tools.get(name);
+    return this.queries.get(name);
   }
-  /**
-   * 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) {
-    return this.tools.has(name);
+    return this.queries.has(name);
   }
-  /**
-   * 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) {
-    return removeRegistryTool(this.tools, name, this.emitMutation, this.mutationEvents);
+    return this.mutations.remove(name);
   }
-  /**
-   * 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(name, tool) {
-    return updateRegistryTool(this.tools, name, tool, this.emitMutation, this.mutationEvents);
+    return this.mutations.update(name, tool);
   }
-  /**
-   * Get all registered tools
-   *
-   * @returns Array of all tools
-   *
-   * @example
-   * ```ts
-   * const allTools = registry.getAll();
-   * console.log(`Total tools: ${allTools.length}`);
-   * ```
-   */
   getAll() {
-    return getAllRegistryTools(this.tools);
+    return this.queries.getAll();
   }
-  /**
-   * 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) {
-    return getRegistryToolsByCategory(this.tools, category);
+    return this.queries.getByCategory(category);
   }
-  /**
-   * 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) {
-    return getRegistryToolsByTag(this.tools, tag);
+    return this.queries.getByTag(tag);
   }
-  /**
-   * 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) {
-    return searchRegistryTools(this.tools, query);
+    return this.queries.search(query);
   }
-  /**
-   * 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) {
-    registerManyRegistryTools(this.tools, tools, this.emitMutation, this.mutationEvents);
+    this.mutations.registerMany(tools);
   }
-  /**
-   * Clear all tools from the registry
-   *
-  * @example
-  * ```ts
-  * registry.clear();
-  * console.log(registry.size()); // 0
-   * ```
-   */
   clear() {
-    clearRegistryTools(this.tools, this.emitMutation, this.mutationEvents);
+    this.mutations.clear();
   }
-  /**
-   * Get the number of registered tools
-   *
-   * @returns Number of tools in the registry
-   *
-   * @example
-   * ```ts
-   * console.log(`Registry has ${registry.size()} tools`);
-   * ```
-   */
   size() {
-    return this.tools.size;
+    return this.queries.size();
   }
-  /**
-   * Get all tool names
-   *
-   * @returns Array of tool names
-   *
-   * @example
-   * ```ts
-   * const names = registry.getNames();
-   * console.log('Available tools:', names.join(', '));
-   * ```
-   */
   getNames() {
-    return getRegistryToolNames(this.tools);
+    return this.queries.getNames();
   }
-  /**
-   * 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, handler) {
     addRegistryEventHandler(this.eventHandlers, event, handler);
   }
-  /**
-   * 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, handler) {
     removeRegistryEventHandler(this.eventHandlers, event, handler);
   }
-  /**
-   * Emit an event to all registered handlers
-   *
-   * @param event - The event to emit
-   * @param data - The event data
-   * @private
-   */
   emit(event, data) {
     emitRegistryEvent(this.eventHandlers, event, data);
   }
-  /**
-   * 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() {
-    return convertRegistryToolsToLangChain(this.getAll());
+    return this.queries.toLangChainTools();
   }
-  /**
-   * 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" }
-   * // ...
-   * ```
-   */
   generatePrompt(options = {}) {
-    return generateRegistryPrompt(this.getAll(), options);
+    return this.queries.generatePrompt(options);
   }
 };