@agentforge/core 0.16.36 → 0.16.38

package/dist/index.cjs

@@ -493,7 +493,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;
@@ -532,309 +579,115 @@ 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() {

package/dist/index.d.cts

@@ -920,231 +920,40 @@ 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>;

package/dist/index.d.ts

@@ -920,231 +920,40 @@ 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>;

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,309 +404,115 @@ 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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/core",
-  "version": "0.16.36",
+  "version": "0.16.38",
   "description": "Production-ready TypeScript agent framework built on LangGraph with orchestration, middleware, and typed abstractions.",
   "type": "module",
   "main": "./dist/index.cjs",