@agentforge/core 0.16.9 → 0.16.11

package/dist/index.cjs

@@ -494,10 +494,50 @@ function validateTool(tool) {
 }
 
 // src/tools/builder.ts
-var ToolBuilder = class {
-  metadata = {};
-  _schema;
-  _invoke;
+function cloneRelations(relations) {
+  if (!relations) {
+    return void 0;
+  }
+  return {
+    requires: relations.requires ? [...relations.requires] : void 0,
+    suggests: relations.suggests ? [...relations.suggests] : void 0,
+    conflicts: relations.conflicts ? [...relations.conflicts] : void 0,
+    follows: relations.follows ? [...relations.follows] : void 0,
+    precedes: relations.precedes ? [...relations.precedes] : void 0
+  };
+}
+function cloneExampleValue(value, exampleIndex, field) {
+  try {
+    return structuredClone(value);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new TypeError(
+      `Invalid tool example at index ${exampleIndex}: "${field}" must be a structured-cloneable value. Received a non-cloneable value while building the tool metadata. Original error: ${reason}`
+    );
+  }
+}
+function cloneExamples(examples) {
+  return examples?.map((example, index) => ({
+    ...example,
+    input: cloneExampleValue(example.input, index, "input"),
+    output: example.output === void 0 ? void 0 : cloneExampleValue(example.output, index, "output")
+  }));
+}
+function cloneMetadata(metadata) {
+  return {
+    ...metadata,
+    tags: metadata.tags ? [...metadata.tags] : void 0,
+    examples: cloneExamples(metadata.examples),
+    limitations: metadata.limitations ? [...metadata.limitations] : void 0,
+    relations: cloneRelations(metadata.relations)
+  };
+}
+var ToolBuilder = class _ToolBuilder {
+  constructor(metadata = {}, _schema, _invoke) {
+    this.metadata = metadata;
+    this._schema = _schema;
+    this._invoke = _invoke;
+  }
   /**
    * Set the tool name (required)
    * 
@@ -697,14 +737,13 @@ var ToolBuilder = class {
   }
   /**
    * Set the input schema (required)
-   * 
+   *
    * All fields MUST have .describe() for LLM understanding!
-   * 
+   *
    * @param schema - Zod schema for input validation
    */
   schema(schema) {
-    this._schema = schema;
-    return this;
+    return new _ToolBuilder(cloneMetadata(this.metadata), schema, this._invoke);
   }
   /**
    * Set the implementation function (required)
@@ -712,8 +751,10 @@ var ToolBuilder = class {
    * @param invoke - Async function that implements the tool
    */
   implement(invoke) {
-    this._invoke = invoke;
-    return this;
+    const wrappedInvoke = async function(input) {
+      return invoke.call(this, input);
+    };
+    return new _ToolBuilder(cloneMetadata(this.metadata), this._schema, wrappedInvoke);
   }
   /**
    * Set the implementation function with automatic error handling
@@ -739,9 +780,9 @@ var ToolBuilder = class {
    * ```
    */
   implementSafe(invoke) {
-    const safeInvoke = async (input) => {
+    const safeInvoke = async function(input) {
       try {
-        const data = await invoke(input);
+        const data = await invoke.call(this, input);
         return { success: true, data };
       } catch (error) {
         return {
@@ -750,8 +791,14 @@ var ToolBuilder = class {
         };
       }
     };
-    this._invoke = safeInvoke;
-    return this;
+    const wrappedInvoke = async function(input) {
+      return safeInvoke.call(this, input);
+    };
+    return new _ToolBuilder(
+      cloneMetadata(this.metadata),
+      this._schema,
+      wrappedInvoke
+    );
   }
   /**
    * Build the tool with validation
@@ -780,10 +827,13 @@ var ToolBuilder = class {
     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,
-      this._invoke
+      async function(input) {
+        return invoke.call(this, input);
+      }
     );
   }
 };

package/dist/index.d.cts

@@ -941,6 +941,7 @@ declare function validateTool(tool: Tool): {
  * ```
  */
 
+type ToolInvoke<TOutput> = (this: unknown, input: unknown) => Promise<TOutput>;
 /**
  * Builder for creating tools with a fluent API
  *
@@ -951,6 +952,7 @@ 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)
      *
@@ -4180,6 +4182,7 @@ declare function createErrorReporter(options: ErrorReporterOptions): ErrorReport
  * Types for LangGraph interrupt handling
  * @module langgraph/interrupts/types
  */
+
 /**
  * Priority level for human requests
  */
@@ -4203,7 +4206,7 @@ interface HumanRequest {
     /**
      * Optional context
      */
-    context?: Record<string, any>;
+    context?: JsonObject;
     /**
      * Priority level
      */
@@ -4241,14 +4244,22 @@ interface HumanRequest {
  * Interrupt type - identifies what kind of interrupt occurred
  */
 type InterruptType = 'human_request' | 'approval_required' | 'custom';
+/**
+ * Shared interrupt metadata contract.
+ */
+type InterruptMetadata = JsonObject;
+/**
+ * JSON-safe payload allowed in generic interrupt and resume flows.
+ */
+type InterruptPayload = JsonValue;
 /**
  * Interrupt data stored in the checkpoint
  */
-interface InterruptData {
+interface InterruptData<TType extends InterruptType = InterruptType, TData = unknown, TMetadata extends InterruptMetadata = InterruptMetadata> {
     /**
      * Type of interrupt
      */
-    type: InterruptType;
+    type: TType;
     /**
      * Unique ID for this interrupt
      */
@@ -4260,37 +4271,32 @@ interface InterruptData {
     /**
      * The data associated with this interrupt
      */
-    data: any;
+    data: TData;
     /**
      * Optional metadata
      */
-    metadata?: Record<string, any>;
+    metadata?: TMetadata;
 }
 /**
- * Human request interrupt data
+ * Approval request payload.
  */
-interface HumanRequestInterrupt extends InterruptData {
-    type: 'human_request';
-    data: HumanRequest;
+interface ApprovalRequiredData {
+    action: string;
+    description: string;
+    context?: JsonObject;
 }
+/**
+ * Human request interrupt data
+ */
+type HumanRequestInterrupt = InterruptData<'human_request', HumanRequest>;
 /**
  * Approval required interrupt data
  */
-interface ApprovalRequiredInterrupt extends InterruptData {
-    type: 'approval_required';
-    data: {
-        action: string;
-        description: string;
-        context?: Record<string, any>;
-    };
-}
+type ApprovalRequiredInterrupt = InterruptData<'approval_required', ApprovalRequiredData>;
 /**
  * Custom interrupt data
  */
-interface CustomInterrupt extends InterruptData {
-    type: 'custom';
-    data: any;
-}
+type CustomInterrupt<TData extends InterruptPayload = InterruptPayload, TMetadata extends InterruptMetadata = InterruptMetadata> = InterruptData<'custom', TData, TMetadata>;
 /**
  * Union type of all interrupt types
  */
@@ -4298,15 +4304,15 @@ type AnyInterrupt = HumanRequestInterrupt | ApprovalRequiredInterrupt | CustomIn
 /**
  * Resume command for continuing after an interrupt
  */
-interface ResumeCommand {
+interface ResumeCommand<TResume extends InterruptPayload = InterruptPayload, TMetadata extends InterruptMetadata = InterruptMetadata> {
     /**
      * The response to the interrupt
      */
-    resume: any;
+    resume: TResume;
     /**
      * Optional metadata about the response
      */
-    metadata?: Record<string, any>;
+    metadata?: TMetadata;
 }
 /**
  * Thread status
@@ -4335,7 +4341,7 @@ interface ThreadInfo {
     /**
      * Optional metadata
      */
-    metadata?: Record<string, any>;
+    metadata?: InterruptMetadata;
 }
 /**
  * Options for checking interrupt status
@@ -4365,11 +4371,11 @@ interface ResumeOptions {
     /**
      * The response/value to resume with
      */
-    value: any;
+    value: InterruptPayload;
     /**
      * Optional metadata
      */
-    metadata?: Record<string, any>;
+    metadata?: InterruptMetadata;
 }
 
 /**
@@ -4413,7 +4419,7 @@ declare function createHumanRequestInterrupt(request: HumanRequest): HumanReques
  * );
  * ```
  */
-declare function createApprovalRequiredInterrupt(action: string, description: string, context?: Record<string, any>): ApprovalRequiredInterrupt;
+declare function createApprovalRequiredInterrupt(action: string, description: string, context?: JsonObject): ApprovalRequiredInterrupt;
 /**
  * Create a custom interrupt
  *
@@ -4430,7 +4436,7 @@ declare function createApprovalRequiredInterrupt(action: string, description: st
  * );
  * ```
  */
-declare function createCustomInterrupt(id: string, data: any, metadata?: Record<string, any>): CustomInterrupt;
+declare function createCustomInterrupt<TData extends InterruptPayload, TMetadata extends InterruptMetadata = InterruptMetadata>(id: string, data: TData, metadata?: TMetadata): CustomInterrupt<TData, TMetadata>;
 /**
  * Check if an interrupt is a human request
  *

package/dist/index.d.ts

@@ -941,6 +941,7 @@ declare function validateTool(tool: Tool): {
  * ```
  */
 
+type ToolInvoke<TOutput> = (this: unknown, input: unknown) => Promise<TOutput>;
 /**
  * Builder for creating tools with a fluent API
  *
@@ -951,6 +952,7 @@ 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)
      *
@@ -4180,6 +4182,7 @@ declare function createErrorReporter(options: ErrorReporterOptions): ErrorReport
  * Types for LangGraph interrupt handling
  * @module langgraph/interrupts/types
  */
+
 /**
  * Priority level for human requests
  */
@@ -4203,7 +4206,7 @@ interface HumanRequest {
     /**
      * Optional context
      */
-    context?: Record<string, any>;
+    context?: JsonObject;
     /**
      * Priority level
      */
@@ -4241,14 +4244,22 @@ interface HumanRequest {
  * Interrupt type - identifies what kind of interrupt occurred
  */
 type InterruptType = 'human_request' | 'approval_required' | 'custom';
+/**
+ * Shared interrupt metadata contract.
+ */
+type InterruptMetadata = JsonObject;
+/**
+ * JSON-safe payload allowed in generic interrupt and resume flows.
+ */
+type InterruptPayload = JsonValue;
 /**
  * Interrupt data stored in the checkpoint
  */
-interface InterruptData {
+interface InterruptData<TType extends InterruptType = InterruptType, TData = unknown, TMetadata extends InterruptMetadata = InterruptMetadata> {
     /**
      * Type of interrupt
      */
-    type: InterruptType;
+    type: TType;
     /**
      * Unique ID for this interrupt
      */
@@ -4260,37 +4271,32 @@ interface InterruptData {
     /**
      * The data associated with this interrupt
      */
-    data: any;
+    data: TData;
     /**
      * Optional metadata
      */
-    metadata?: Record<string, any>;
+    metadata?: TMetadata;
 }
 /**
- * Human request interrupt data
+ * Approval request payload.
  */
-interface HumanRequestInterrupt extends InterruptData {
-    type: 'human_request';
-    data: HumanRequest;
+interface ApprovalRequiredData {
+    action: string;
+    description: string;
+    context?: JsonObject;
 }
+/**
+ * Human request interrupt data
+ */
+type HumanRequestInterrupt = InterruptData<'human_request', HumanRequest>;
 /**
  * Approval required interrupt data
  */
-interface ApprovalRequiredInterrupt extends InterruptData {
-    type: 'approval_required';
-    data: {
-        action: string;
-        description: string;
-        context?: Record<string, any>;
-    };
-}
+type ApprovalRequiredInterrupt = InterruptData<'approval_required', ApprovalRequiredData>;
 /**
  * Custom interrupt data
  */
-interface CustomInterrupt extends InterruptData {
-    type: 'custom';
-    data: any;
-}
+type CustomInterrupt<TData extends InterruptPayload = InterruptPayload, TMetadata extends InterruptMetadata = InterruptMetadata> = InterruptData<'custom', TData, TMetadata>;
 /**
  * Union type of all interrupt types
  */
@@ -4298,15 +4304,15 @@ type AnyInterrupt = HumanRequestInterrupt | ApprovalRequiredInterrupt | CustomIn
 /**
  * Resume command for continuing after an interrupt
  */
-interface ResumeCommand {
+interface ResumeCommand<TResume extends InterruptPayload = InterruptPayload, TMetadata extends InterruptMetadata = InterruptMetadata> {
     /**
      * The response to the interrupt
      */
-    resume: any;
+    resume: TResume;
     /**
      * Optional metadata about the response
      */
-    metadata?: Record<string, any>;
+    metadata?: TMetadata;
 }
 /**
  * Thread status
@@ -4335,7 +4341,7 @@ interface ThreadInfo {
     /**
      * Optional metadata
      */
-    metadata?: Record<string, any>;
+    metadata?: InterruptMetadata;
 }
 /**
  * Options for checking interrupt status
@@ -4365,11 +4371,11 @@ interface ResumeOptions {
     /**
      * The response/value to resume with
      */
-    value: any;
+    value: InterruptPayload;
     /**
      * Optional metadata
      */
-    metadata?: Record<string, any>;
+    metadata?: InterruptMetadata;
 }
 
 /**
@@ -4413,7 +4419,7 @@ declare function createHumanRequestInterrupt(request: HumanRequest): HumanReques
  * );
  * ```
  */
-declare function createApprovalRequiredInterrupt(action: string, description: string, context?: Record<string, any>): ApprovalRequiredInterrupt;
+declare function createApprovalRequiredInterrupt(action: string, description: string, context?: JsonObject): ApprovalRequiredInterrupt;
 /**
  * Create a custom interrupt
  *
@@ -4430,7 +4436,7 @@ declare function createApprovalRequiredInterrupt(action: string, description: st
  * );
  * ```
  */
-declare function createCustomInterrupt(id: string, data: any, metadata?: Record<string, any>): CustomInterrupt;
+declare function createCustomInterrupt<TData extends InterruptPayload, TMetadata extends InterruptMetadata = InterruptMetadata>(id: string, data: TData, metadata?: TMetadata): CustomInterrupt<TData, TMetadata>;
 /**
  * Check if an interrupt is a human request
  *

package/dist/index.js

@@ -319,10 +319,50 @@ function validateTool(tool) {
 }
 
 // src/tools/builder.ts
-var ToolBuilder = class {
-  metadata = {};
-  _schema;
-  _invoke;
+function cloneRelations(relations) {
+  if (!relations) {
+    return void 0;
+  }
+  return {
+    requires: relations.requires ? [...relations.requires] : void 0,
+    suggests: relations.suggests ? [...relations.suggests] : void 0,
+    conflicts: relations.conflicts ? [...relations.conflicts] : void 0,
+    follows: relations.follows ? [...relations.follows] : void 0,
+    precedes: relations.precedes ? [...relations.precedes] : void 0
+  };
+}
+function cloneExampleValue(value, exampleIndex, field) {
+  try {
+    return structuredClone(value);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new TypeError(
+      `Invalid tool example at index ${exampleIndex}: "${field}" must be a structured-cloneable value. Received a non-cloneable value while building the tool metadata. Original error: ${reason}`
+    );
+  }
+}
+function cloneExamples(examples) {
+  return examples?.map((example, index) => ({
+    ...example,
+    input: cloneExampleValue(example.input, index, "input"),
+    output: example.output === void 0 ? void 0 : cloneExampleValue(example.output, index, "output")
+  }));
+}
+function cloneMetadata(metadata) {
+  return {
+    ...metadata,
+    tags: metadata.tags ? [...metadata.tags] : void 0,
+    examples: cloneExamples(metadata.examples),
+    limitations: metadata.limitations ? [...metadata.limitations] : void 0,
+    relations: cloneRelations(metadata.relations)
+  };
+}
+var ToolBuilder = class _ToolBuilder {
+  constructor(metadata = {}, _schema, _invoke) {
+    this.metadata = metadata;
+    this._schema = _schema;
+    this._invoke = _invoke;
+  }
   /**
    * Set the tool name (required)
    * 
@@ -522,14 +562,13 @@ var ToolBuilder = class {
   }
   /**
    * Set the input schema (required)
-   * 
+   *
    * All fields MUST have .describe() for LLM understanding!
-   * 
+   *
    * @param schema - Zod schema for input validation
    */
   schema(schema) {
-    this._schema = schema;
-    return this;
+    return new _ToolBuilder(cloneMetadata(this.metadata), schema, this._invoke);
   }
   /**
    * Set the implementation function (required)
@@ -537,8 +576,10 @@ var ToolBuilder = class {
    * @param invoke - Async function that implements the tool
    */
   implement(invoke) {
-    this._invoke = invoke;
-    return this;
+    const wrappedInvoke = async function(input) {
+      return invoke.call(this, input);
+    };
+    return new _ToolBuilder(cloneMetadata(this.metadata), this._schema, wrappedInvoke);
   }
   /**
    * Set the implementation function with automatic error handling
@@ -564,9 +605,9 @@ var ToolBuilder = class {
    * ```
    */
   implementSafe(invoke) {
-    const safeInvoke = async (input) => {
+    const safeInvoke = async function(input) {
       try {
-        const data = await invoke(input);
+        const data = await invoke.call(this, input);
         return { success: true, data };
       } catch (error) {
         return {
@@ -575,8 +616,14 @@ var ToolBuilder = class {
         };
       }
     };
-    this._invoke = safeInvoke;
-    return this;
+    const wrappedInvoke = async function(input) {
+      return safeInvoke.call(this, input);
+    };
+    return new _ToolBuilder(
+      cloneMetadata(this.metadata),
+      this._schema,
+      wrappedInvoke
+    );
   }
   /**
    * Build the tool with validation
@@ -605,10 +652,13 @@ var ToolBuilder = class {
     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,
-      this._invoke
+      async function(input) {
+        return invoke.call(this, input);
+      }
     );
   }
 };

package/package.json

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