@agentforge/patterns 0.8.0 → 0.8.1

package/dist/index.cjs

@@ -604,7 +604,8 @@ function createReActAgent(config, options) {
     return ACTION_NODE;
   };
   const workflow = new import_langgraph.StateGraph(ReActState).addNode(REASONING_NODE, reasoningNode).addNode(ACTION_NODE, actionNode).addNode(OBSERVATION_NODE, observationNode).addEdge("__start__", REASONING_NODE).addConditionalEdges(REASONING_NODE, shouldContinue).addEdge(ACTION_NODE, OBSERVATION_NODE).addEdge(OBSERVATION_NODE, REASONING_NODE);
-  return workflow.compile(checkpointer ? { checkpointer } : void 0);
+  const checkpointerConfig = checkpointer === true ? { checkpointer: true } : checkpointer ? { checkpointer } : void 0;
+  return workflow.compile(checkpointerConfig);
 }
 
 // src/react/builder.ts
@@ -689,6 +690,43 @@ var ReActAgentBuilder = class {
     this.options.nodeNames = nodeNames;
     return this;
   }
+  /**
+   * Set the checkpointer for state persistence (optional)
+   *
+   * Can be:
+   * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+   * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+   *
+   * Required for human-in-the-loop workflows (askHuman tool) and conversation continuity.
+   *
+   * @param checkpointer - Checkpointer instance or `true` for nested graphs
+   *
+   * @example
+   * Standalone agent with its own checkpointer:
+   * ```typescript
+   * import { MemorySaver } from '@langchain/langgraph';
+   *
+   * const agent = new ReActAgentBuilder()
+   *   .withModel(model)
+   *   .withTools(tools)
+   *   .withCheckpointer(new MemorySaver())
+   *   .build();
+   * ```
+   *
+   * @example
+   * Nested agent using parent's checkpointer (for multi-agent systems):
+   * ```typescript
+   * const agent = new ReActAgentBuilder()
+   *   .withModel(model)
+   *   .withTools(tools)
+   *   .withCheckpointer(true)  // Use parent's checkpointer with separate namespace
+   *   .build();
+   * ```
+   */
+  withCheckpointer(checkpointer) {
+    this.config.checkpointer = checkpointer;
+    return this;
+  }
   /**
    * Build the ReAct agent
    *
@@ -708,7 +746,8 @@ var ReActAgentBuilder = class {
       systemPrompt: this.config.systemPrompt || DEFAULT_REACT_SYSTEM_PROMPT,
       maxIterations: this.config.maxIterations ?? 10,
       returnIntermediateSteps: this.config.returnIntermediateSteps ?? false,
-      stopCondition: this.config.stopCondition
+      stopCondition: this.config.stopCondition,
+      checkpointer: this.config.checkpointer
     };
     return createReActAgent(finalConfig, this.options);
   }
@@ -2362,12 +2401,26 @@ function wrapReActAgent(workerId, agent, verbose = false) {
         logger.debug("No active assignment found", { workerId });
         return {};
       }
+      const workerThreadId = config?.configurable?.thread_id ? `${config.configurable.thread_id}:worker:${workerId}` : void 0;
+      const workerConfig = workerThreadId ? {
+        ...config,
+        configurable: {
+          ...config.configurable,
+          thread_id: workerThreadId
+        }
+      } : config;
+      logger.debug("Invoking ReAct agent with worker-specific config", {
+        workerId,
+        parentThreadId: config?.configurable?.thread_id,
+        workerThreadId,
+        hasConfig: !!workerConfig
+      });
       const result = await agent.invoke(
         {
           messages: [{ role: "user", content: task }]
         },
-        config
-        // Pass through the config for checkpointing and interrupt support
+        workerConfig
+        // Worker-specific config with unique thread_id
       );
       const response = result.messages?.[result.messages.length - 1]?.content || "No response";
       logger.debug("Received response from ReAct agent", {

package/dist/index.d.cts

@@ -172,7 +172,12 @@ interface ReActAgentConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
      * @example
+     * Standalone agent with its own checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -183,8 +188,18 @@ interface ReActAgentConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = createReActAgent({
+     *   model,
+     *   tools,
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     * ```
      */
-    checkpointer?: BaseCheckpointSaver;
+    checkpointer?: BaseCheckpointSaver | true;
     /**
      * Enable tool call deduplication to prevent calling the same tool with identical parameters multiple times
      * @default true
@@ -287,6 +302,31 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  *   { configurable: { thread_id: 'conversation-123' } }
  * );
  * ```
+ *
+ * @example
+ * As a nested agent in a multi-agent system:
+ * ```typescript
+ * import { createReActAgent, createMultiAgentSystem } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * // Create worker agent with checkpointer: true to use parent's checkpointer
+ * const hrAgent = createReActAgent({
+ *   model: new ChatOpenAI({ model: 'gpt-4' }),
+ *   tools: [createAskHumanTool(), ...hrTools],
+ *   checkpointer: true  // Use parent's checkpointer with separate namespace
+ * });
+ *
+ * // Create multi-agent system with its own checkpointer
+ * const system = createMultiAgentSystem({
+ *   workers: { hr: hrAgent },
+ *   checkpointer: new MemorySaver()  // Parent checkpointer
+ * });
+ *
+ * // When hrAgent calls askHuman, it will use a separate checkpoint namespace
+ * // Format: {parent_thread_id}:worker:hr
+ * ```
  */
 declare function createReActAgent(config: ReActAgentConfig, options?: ReActBuilderOptions): CompiledStateGraph<any, any>;
 
@@ -372,6 +412,40 @@ declare class ReActAgentBuilder {
         action?: string;
         observation?: string;
     }): this;
+    /**
+     * Set the checkpointer for state persistence (optional)
+     *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
+     * Required for human-in-the-loop workflows (askHuman tool) and conversation continuity.
+     *
+     * @param checkpointer - Checkpointer instance or `true` for nested graphs
+     *
+     * @example
+     * Standalone agent with its own checkpointer:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(new MemorySaver())
+     *   .build();
+     * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(true)  // Use parent's checkpointer with separate namespace
+     *   .build();
+     * ```
+     */
+    withCheckpointer(checkpointer: any): this;
     /**
      * Build the ReAct agent
      *
@@ -2593,7 +2667,20 @@ interface MultiAgentSystemConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * **Worker Checkpoint Namespaces:**
+     * When worker agents are configured with `checkpointer: true`, they automatically use
+     * separate checkpoint namespaces to enable proper handling of nested graph interrupts.
+     *
+     * The namespace format is: `{parent_thread_id}:worker:{workerId}`
+     *
+     * For example, if the parent thread ID is `thread_abc123` and the worker ID is `hr`,
+     * the worker's checkpoint namespace will be `thread_abc123:worker:hr`.
+     *
+     * This allows worker agents to use the `askHuman` tool without causing infinite loops,
+     * as each worker's state is saved and resumed independently.
+     *
      * @example
+     * Basic usage with checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -2604,6 +2691,35 @@ interface MultiAgentSystemConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Worker agents with nested graph interrupts:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     * import { createReActAgent } from '@agentforge/patterns';
+     * import { createAskHumanTool } from '@agentforge/tools';
+     *
+     * // Create worker agent with checkpointer: true
+     * const hrAgent = createReActAgent({
+     *   model,
+     *   tools: [createAskHumanTool(), ...hrTools],
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     *
+     * // Create multi-agent system with checkpointer
+     * const system = createMultiAgentSystem({
+     *   supervisor: { strategy: 'skill-based', model },
+     *   workers: [{
+     *     id: 'hr',
+     *     capabilities: { skills: ['hr'], ... },
+     *     agent: hrAgent
+     *   }],
+     *   checkpointer: new MemorySaver()
+     * });
+     *
+     * // When hrAgent calls askHuman, it will use checkpoint namespace:
+     * // thread_abc123:worker:hr
+     * ```
      */
     checkpointer?: BaseCheckpointSaver;
 }

package/dist/index.d.ts

@@ -172,7 +172,12 @@ interface ReActAgentConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
      * @example
+     * Standalone agent with its own checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -183,8 +188,18 @@ interface ReActAgentConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = createReActAgent({
+     *   model,
+     *   tools,
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     * ```
      */
-    checkpointer?: BaseCheckpointSaver;
+    checkpointer?: BaseCheckpointSaver | true;
     /**
      * Enable tool call deduplication to prevent calling the same tool with identical parameters multiple times
      * @default true
@@ -287,6 +302,31 @@ declare const DEFAULT_REACT_SYSTEM_PROMPT = "You are a helpful assistant that us
  *   { configurable: { thread_id: 'conversation-123' } }
  * );
  * ```
+ *
+ * @example
+ * As a nested agent in a multi-agent system:
+ * ```typescript
+ * import { createReActAgent, createMultiAgentSystem } from '@agentforge/patterns';
+ * import { createAskHumanTool } from '@agentforge/tools';
+ * import { MemorySaver } from '@langchain/langgraph';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * // Create worker agent with checkpointer: true to use parent's checkpointer
+ * const hrAgent = createReActAgent({
+ *   model: new ChatOpenAI({ model: 'gpt-4' }),
+ *   tools: [createAskHumanTool(), ...hrTools],
+ *   checkpointer: true  // Use parent's checkpointer with separate namespace
+ * });
+ *
+ * // Create multi-agent system with its own checkpointer
+ * const system = createMultiAgentSystem({
+ *   workers: { hr: hrAgent },
+ *   checkpointer: new MemorySaver()  // Parent checkpointer
+ * });
+ *
+ * // When hrAgent calls askHuman, it will use a separate checkpoint namespace
+ * // Format: {parent_thread_id}:worker:hr
+ * ```
  */
 declare function createReActAgent(config: ReActAgentConfig, options?: ReActBuilderOptions): CompiledStateGraph<any, any>;
 
@@ -372,6 +412,40 @@ declare class ReActAgentBuilder {
         action?: string;
         observation?: string;
     }): this;
+    /**
+     * Set the checkpointer for state persistence (optional)
+     *
+     * Can be:
+     * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+     * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+     *
+     * Required for human-in-the-loop workflows (askHuman tool) and conversation continuity.
+     *
+     * @param checkpointer - Checkpointer instance or `true` for nested graphs
+     *
+     * @example
+     * Standalone agent with its own checkpointer:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     *
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(new MemorySaver())
+     *   .build();
+     * ```
+     *
+     * @example
+     * Nested agent using parent's checkpointer (for multi-agent systems):
+     * ```typescript
+     * const agent = new ReActAgentBuilder()
+     *   .withModel(model)
+     *   .withTools(tools)
+     *   .withCheckpointer(true)  // Use parent's checkpointer with separate namespace
+     *   .build();
+     * ```
+     */
+    withCheckpointer(checkpointer: any): this;
     /**
      * Build the ReAct agent
      *
@@ -2593,7 +2667,20 @@ interface MultiAgentSystemConfig {
      * Optional checkpointer for state persistence
      * Required for human-in-the-loop workflows (askHuman tool), interrupts, and conversation continuity
      *
+     * **Worker Checkpoint Namespaces:**
+     * When worker agents are configured with `checkpointer: true`, they automatically use
+     * separate checkpoint namespaces to enable proper handling of nested graph interrupts.
+     *
+     * The namespace format is: `{parent_thread_id}:worker:{workerId}`
+     *
+     * For example, if the parent thread ID is `thread_abc123` and the worker ID is `hr`,
+     * the worker's checkpoint namespace will be `thread_abc123:worker:hr`.
+     *
+     * This allows worker agents to use the `askHuman` tool without causing infinite loops,
+     * as each worker's state is saved and resumed independently.
+     *
      * @example
+     * Basic usage with checkpointer:
      * ```typescript
      * import { MemorySaver } from '@langchain/langgraph';
      *
@@ -2604,6 +2691,35 @@ interface MultiAgentSystemConfig {
      *   checkpointer
      * });
      * ```
+     *
+     * @example
+     * Worker agents with nested graph interrupts:
+     * ```typescript
+     * import { MemorySaver } from '@langchain/langgraph';
+     * import { createReActAgent } from '@agentforge/patterns';
+     * import { createAskHumanTool } from '@agentforge/tools';
+     *
+     * // Create worker agent with checkpointer: true
+     * const hrAgent = createReActAgent({
+     *   model,
+     *   tools: [createAskHumanTool(), ...hrTools],
+     *   checkpointer: true  // Use parent's checkpointer with separate namespace
+     * });
+     *
+     * // Create multi-agent system with checkpointer
+     * const system = createMultiAgentSystem({
+     *   supervisor: { strategy: 'skill-based', model },
+     *   workers: [{
+     *     id: 'hr',
+     *     capabilities: { skills: ['hr'], ... },
+     *     agent: hrAgent
+     *   }],
+     *   checkpointer: new MemorySaver()
+     * });
+     *
+     * // When hrAgent calls askHuman, it will use checkpoint namespace:
+     * // thread_abc123:worker:hr
+     * ```
      */
     checkpointer?: BaseCheckpointSaver;
 }

package/dist/index.js

@@ -501,7 +501,8 @@ function createReActAgent(config, options) {
     return ACTION_NODE;
   };
   const workflow = new StateGraph(ReActState).addNode(REASONING_NODE, reasoningNode).addNode(ACTION_NODE, actionNode).addNode(OBSERVATION_NODE, observationNode).addEdge("__start__", REASONING_NODE).addConditionalEdges(REASONING_NODE, shouldContinue).addEdge(ACTION_NODE, OBSERVATION_NODE).addEdge(OBSERVATION_NODE, REASONING_NODE);
-  return workflow.compile(checkpointer ? { checkpointer } : void 0);
+  const checkpointerConfig = checkpointer === true ? { checkpointer: true } : checkpointer ? { checkpointer } : void 0;
+  return workflow.compile(checkpointerConfig);
 }
 
 // src/react/builder.ts
@@ -586,6 +587,43 @@ var ReActAgentBuilder = class {
     this.options.nodeNames = nodeNames;
     return this;
   }
+  /**
+   * Set the checkpointer for state persistence (optional)
+   *
+   * Can be:
+   * - A BaseCheckpointSaver instance (e.g., MemorySaver) for standalone agents
+   * - `true` to use the parent graph's checkpointer with a separate namespace (for nested graphs)
+   *
+   * Required for human-in-the-loop workflows (askHuman tool) and conversation continuity.
+   *
+   * @param checkpointer - Checkpointer instance or `true` for nested graphs
+   *
+   * @example
+   * Standalone agent with its own checkpointer:
+   * ```typescript
+   * import { MemorySaver } from '@langchain/langgraph';
+   *
+   * const agent = new ReActAgentBuilder()
+   *   .withModel(model)
+   *   .withTools(tools)
+   *   .withCheckpointer(new MemorySaver())
+   *   .build();
+   * ```
+   *
+   * @example
+   * Nested agent using parent's checkpointer (for multi-agent systems):
+   * ```typescript
+   * const agent = new ReActAgentBuilder()
+   *   .withModel(model)
+   *   .withTools(tools)
+   *   .withCheckpointer(true)  // Use parent's checkpointer with separate namespace
+   *   .build();
+   * ```
+   */
+  withCheckpointer(checkpointer) {
+    this.config.checkpointer = checkpointer;
+    return this;
+  }
   /**
    * Build the ReAct agent
    *
@@ -605,7 +643,8 @@ var ReActAgentBuilder = class {
       systemPrompt: this.config.systemPrompt || DEFAULT_REACT_SYSTEM_PROMPT,
       maxIterations: this.config.maxIterations ?? 10,
       returnIntermediateSteps: this.config.returnIntermediateSteps ?? false,
-      stopCondition: this.config.stopCondition
+      stopCondition: this.config.stopCondition,
+      checkpointer: this.config.checkpointer
     };
     return createReActAgent(finalConfig, this.options);
   }
@@ -2259,12 +2298,26 @@ function wrapReActAgent(workerId, agent, verbose = false) {
         logger.debug("No active assignment found", { workerId });
         return {};
       }
+      const workerThreadId = config?.configurable?.thread_id ? `${config.configurable.thread_id}:worker:${workerId}` : void 0;
+      const workerConfig = workerThreadId ? {
+        ...config,
+        configurable: {
+          ...config.configurable,
+          thread_id: workerThreadId
+        }
+      } : config;
+      logger.debug("Invoking ReAct agent with worker-specific config", {
+        workerId,
+        parentThreadId: config?.configurable?.thread_id,
+        workerThreadId,
+        hasConfig: !!workerConfig
+      });
       const result = await agent.invoke(
         {
           messages: [{ role: "user", content: task }]
         },
-        config
-        // Pass through the config for checkpointing and interrupt support
+        workerConfig
+        // Worker-specific config with unique thread_id
       );
       const response = result.messages?.[result.messages.length - 1]?.content || "No response";
       logger.debug("Received response from ReAct agent", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/patterns",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Agent patterns (ReAct, Planner-Executor) for AgentForge framework",
   "type": "module",
   "main": "./dist/index.cjs",