@librechat/agents 3.1.86 → 3.1.88

package/README.md

@@ -46,6 +46,75 @@ const content = await run.processStream(
 );
 ```
 
+## Programmatic Sessions
+
+For scripts, CI, and programmatic integrations, use the session facade. It
+keeps a JSONL session tree by default, so runs can be resumed, cloned, forked,
+branched in place, compacted, and inspected later.
+
+```typescript
+import { Providers, createAgentSession } from '@librechat/agents';
+
+const session = await createAgentSession({
+  checkpointing: true,
+  graphConfig: {
+    type: 'standard',
+    instructions: 'You are a concise coding assistant.',
+    llmConfig: {
+      provider: Providers.OPENAI,
+      model: 'gpt-4o-mini',
+      apiKey: process.env.OPENAI_API_KEY,
+    },
+  },
+});
+
+const result = await session.run('Summarize this repository.');
+console.log(result.text);
+console.log(session.sessionPath); // durable .jsonl session file
+```
+
+When `checkpointing` is enabled, the session injects a shared LangGraph
+checkpointer into `compileOptions`, records checkpoint IDs in JSONL, and uses
+checkpoint state for later turns on the same `thread_id`. When HITL is enabled
+(`humanInTheLoop: { enabled: true }`), sessions also get a `MemorySaver` by
+default so `resumeInterrupt()` can reuse the same saver instead of relying on a
+per-run fallback. JSONL still owns portable replay, clone, fork, and audit
+records.
+
+Sessions expose tree operations inspired by Pi-style workflows:
+
+```typescript
+const store = session.getSessionStore();
+const forkPoint = store?.getForkPoints()[0];
+
+if (forkPoint) {
+  const forked = await session.fork(forkPoint.id, { position: 'before' });
+  await forked.run('Try a different approach from here.');
+}
+
+const cloned = await session.clone();
+await cloned.compact({ instructions: 'Keep only implementation decisions.' });
+```
+
+`session.stream()` projects the SDK's existing graph events, and
+`session.compact()` uses the same summarization node, hooks, and provider
+logic as normal runs. JSONL is the durable journal; the graph remains the
+execution engine.
+
+OpenAI-compatible streaming helpers are available as experimental subpaths:
+
+```typescript
+import { composeEventHandlers } from '@librechat/agents';
+import { createOpenAIHandlers } from '@librechat/agents/openai';
+import { createResponsesEventHandlers } from '@librechat/agents/responses';
+
+const customHandlers = composeEventHandlers(
+  createOpenAIHandlers(openAIConfig),
+  createResponsesEventHandlers(responsesConfig),
+  hostHandlers
+);
+```
+
 ## Development
 
 ```bash

package/dist/cjs/events.cjs

@@ -11,6 +11,28 @@ class HandlerRegistry {
         return this.handlers.get(eventType);
     }
 }
+function composeEventHandlers(...handlerSets) {
+    const composed = {};
+    for (const handlerSet of handlerSets) {
+        if (!handlerSet) {
+            continue;
+        }
+        for (const [eventType, handler] of Object.entries(handlerSet)) {
+            const previous = composed[eventType];
+            if (previous === undefined) {
+                composed[eventType] = handler;
+                continue;
+            }
+            composed[eventType] = {
+                handle: async (...args) => {
+                    await previous.handle(...args);
+                    await handler.handle(...args);
+                },
+            };
+        }
+    }
+    return composed;
+}
 class ModelEndHandler {
     collectedUsage;
     constructor(collectedUsage) {
@@ -154,5 +176,6 @@ exports.ModelEndHandler = ModelEndHandler;
 exports.TestChatStreamHandler = TestChatStreamHandler;
 exports.TestLLMStreamHandler = TestLLMStreamHandler;
 exports.ToolEndHandler = ToolEndHandler;
+exports.composeEventHandlers = composeEventHandlers;
 exports.createMetadataAggregator = createMetadataAggregator;
 //# sourceMappingURL=events.cjs.map

package/dist/cjs/events.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.cjs","sources":["../../src/events.ts"],"sourcesContent":["/* eslint-disable no-console */\n// src/events.ts\nimport type {\n  BaseMessageFields,\n  UsageMetadata,\n} from '@langchain/core/messages';\nimport type { MultiAgentGraph, StandardGraph } from '@/graphs';\nimport type { Logger } from 'winston';\nimport type * as t from '@/types';\nimport { Constants } from '@/common';\n\nexport class HandlerRegistry {\n  private handlers: Map<string, t.EventHandler> = new Map();\n\n  register(eventType: string, handler: t.EventHandler): void {\n    this.handlers.set(eventType, handler);\n  }\n\n  getHandler(eventType: string): t.EventHandler | undefined {\n    return this.handlers.get(eventType);\n  }\n}\n\nexport class ModelEndHandler implements t.EventHandler {\n  collectedUsage?: UsageMetadata[];\n  constructor(collectedUsage?: UsageMetadata[]) {\n    if (collectedUsage && !Array.isArray(collectedUsage)) {\n      throw new Error('collectedUsage must be an array');\n    }\n    this.collectedUsage = collectedUsage;\n  }\n\n  async handle(\n    event: string,\n    data: t.ModelEndData,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    if (!graph || !metadata) {\n      console.warn(`Graph or metadata not found in ${event} event`);\n      return;\n    }\n\n    const usage = data?.output?.usage_metadata;\n    if (usage != null && this.collectedUsage != null) {\n      this.collectedUsage.push(usage);\n    }\n  }\n}\n\nexport class ToolEndHandler implements t.EventHandler {\n  private callback?: t.ToolEndCallback;\n  private logger?: Logger;\n  constructor(callback?: t.ToolEndCallback, logger?: Logger) {\n    this.callback = callback;\n    this.logger = logger;\n  }\n\n  /**\n   * Handles on_tool_end events from the for-await stream consumer.\n   *\n   * This handler is now purely a consumer callback — tool completion\n   * (ON_RUN_STEP_COMPLETED dispatch + session context storage) is handled\n   * in graph context by ToolNode directly, eliminating the race between\n   * the stream consumer and graph execution.\n   */\n  async handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    try {\n      if (!graph || !metadata) {\n        if (this.logger) {\n          this.logger.warn(`Graph or metadata not found in ${event} event`);\n        } else {\n          console.warn(`Graph or metadata not found in ${event} event`);\n        }\n        return;\n      }\n\n      const toolEndData = data as t.ToolEndData | undefined;\n      if (!toolEndData?.output) {\n        if (this.logger) {\n          this.logger.warn('No output found in tool_end event');\n        } else {\n          console.warn('No output found in tool_end event');\n        }\n        return;\n      }\n\n      if (\n        metadata[Constants.PROGRAMMATIC_TOOL_CALLING] === true ||\n        metadata[Constants.BASH_PROGRAMMATIC_TOOL_CALLING] === true\n      ) {\n        return;\n      }\n\n      if (this.callback) {\n        await this.callback(toolEndData, metadata);\n      }\n    } catch (error) {\n      if (this.logger) {\n        this.logger.error('Error handling tool_end event:', error);\n      } else {\n        console.error('Error handling tool_end event:', error);\n      }\n    }\n  }\n}\n\nexport class TestLLMStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk ? chunk.message : undefined;\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && typeof msg.content === 'string') {\n      process.stdout.write(msg.content);\n    }\n  }\n}\n\nexport class TestChatStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isContentChunk = !!(chunk && 'content' in chunk);\n    if (!isContentChunk) {\n      return;\n    }\n\n    const content = chunk.content;\n\n    if (chunk.tool_call_chunks && chunk.tool_call_chunks.length > 0) {\n      console.dir(chunk.tool_call_chunks, { depth: null });\n    }\n\n    if (typeof content === 'string') {\n      process.stdout.write(content);\n    } else {\n      console.dir(content, { depth: null });\n    }\n  }\n}\n\nexport class LLMStreamHandler implements t.EventHandler {\n  handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>\n  ): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk ? chunk.message : undefined;\n    if (metadata) {\n      console.log(metadata);\n    }\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && typeof msg.content === 'string') {\n      process.stdout.write(msg.content);\n    }\n  }\n}\n\nexport const createMetadataAggregator = (\n  _collected?: Record<\n    string,\n    NonNullable<BaseMessageFields['response_metadata']>\n  >[]\n): t.MetadataAggregatorResult => {\n  const collected = _collected || [];\n\n  const handleLLMEnd: t.HandleLLMEnd = (output) => {\n    const { generations } = output;\n    const lastMessageOutput = (\n      generations[generations.length - 1] as\n        | (t.StreamGeneration | undefined)[]\n        | undefined\n    )?.[0];\n    if (!lastMessageOutput) {\n      return;\n    }\n    const { message } = lastMessageOutput;\n    if (message?.response_metadata) {\n      collected.push(message.response_metadata);\n    }\n  };\n\n  return { handleLLMEnd, collected };\n};\n"],"names":["Constants"],"mappings":";;;;MAWa,eAAe,CAAA;AAClB,IAAA,QAAQ,GAAgC,IAAI,GAAG,EAAE;IAEzD,QAAQ,CAAC,SAAiB,EAAE,OAAuB,EAAA;QACjD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC;IACvC;AAEA,IAAA,UAAU,CAAC,SAAiB,EAAA;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC;IACrC;AACD;MAEY,eAAe,CAAA;AAC1B,IAAA,cAAc;AACd,IAAA,WAAA,CAAY,cAAgC,EAAA;QAC1C,IAAI,cAAc,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE;AACpD,YAAA,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC;QACpD;AACA,QAAA,IAAI,CAAC,cAAc,GAAG,cAAc;IACtC;IAEA,MAAM,MAAM,CACV,KAAa,EACb,IAAoB,EACpB,QAAkC,EAClC,KAAuC,EAAA;AAEvC,QAAA,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE;AACvB,YAAA,OAAO,CAAC,IAAI,CAAC,kCAAkC,KAAK,CAAA,MAAA,CAAQ,CAAC;YAC7D;QACF;AAEA,QAAA,MAAM,KAAK,GAAG,IAAI,EAAE,MAAM,EAAE,cAAc;QAC1C,IAAI,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,EAAE;AAChD,YAAA,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;QACjC;IACF;AACD;MAEY,cAAc,CAAA;AACjB,IAAA,QAAQ;AACR,IAAA,MAAM;IACd,WAAA,CAAY,QAA4B,EAAE,MAAe,EAAA;AACvD,QAAA,IAAI,CAAC,QAAQ,GAAG,QAAQ;AACxB,QAAA,IAAI,CAAC,MAAM,GAAG,MAAM;IACtB;AAEA;;;;;;;AAOG;IACH,MAAM,MAAM,CACV,KAAa,EACb,IAAmC,EACnC,QAAkC,EAClC,KAAuC,EAAA;AAEvC,QAAA,IAAI;AACF,YAAA,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE;AACvB,gBAAA,IAAI,IAAI,CAAC,MAAM,EAAE;oBACf,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA,+BAAA,EAAkC,KAAK,CAAA,MAAA,CAAQ,CAAC;gBACnE;qBAAO;AACL,oBAAA,OAAO,CAAC,IAAI,CAAC,kCAAkC,KAAK,CAAA,MAAA,CAAQ,CAAC;gBAC/D;gBACA;YACF;YAEA,MAAM,WAAW,GAAG,IAAiC;AACrD,YAAA,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE;AACxB,gBAAA,IAAI,IAAI,CAAC,MAAM,EAAE;AACf,oBAAA,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC;gBACvD;qBAAO;AACL,oBAAA,OAAO,CAAC,IAAI,CAAC,mCAAmC,CAAC;gBACnD;gBACA;YACF;AAEA,YAAA,IACE,QAAQ,CAACA,eAAS,CAAC,yBAAyB,CAAC,KAAK,IAAI;gBACtD,QAAQ,CAACA,eAAS,CAAC,8BAA8B,CAAC,KAAK,IAAI,EAC3D;gBACA;YACF;AAEA,YAAA,IAAI,IAAI,CAAC,QAAQ,EAAE;gBACjB,MAAM,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC;YAC5C;QACF;QAAE,OAAO,KAAK,EAAE;AACd,YAAA,IAAI,IAAI,CAAC,MAAM,EAAE;gBACf,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAK,CAAC;YAC5D;iBAAO;AACL,gBAAA,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAK,CAAC;YACxD;QACF;IACF;AACD;MAEY,oBAAoB,CAAA;IAC/B,MAAM,CAAC,KAAa,EAAE,IAAmC,EAAA;AACvD,QAAA,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK;QACzB,MAAM,cAAc,GAAG,CAAC,EAAE,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC;AACtD,QAAA,MAAM,GAAG,GAAG,cAAc,GAAG,KAAK,CAAC,OAAO,GAAG,SAAS;AACtD,QAAA,IAAI,GAAG,IAAI,GAAG,CAAC,gBAAgB,IAAI,GAAG,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE;AAClE,YAAA,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC;QACnC;aAAO,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE;YACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;QACnC;IACF;AACD;MAEY,qBAAqB,CAAA;IAChC,MAAM,CAAC,KAAa,EAAE,IAAmC,EAAA;AACvD,QAAA,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK;QACzB,MAAM,cAAc,GAAG,CAAC,EAAE,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC;QACtD,IAAI,CAAC,cAAc,EAAE;YACnB;QACF;AAEA,QAAA,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO;AAE7B,QAAA,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE;AAC/D,YAAA,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACtD;AAEA,QAAA,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE;AAC/B,YAAA,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;QAC/B;aAAO;YACL,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACvC;IACF;AACD;MAEY,gBAAgB,CAAA;AAC3B,IAAA,MAAM,CACJ,KAAa,EACb,IAAmC,EACnC,QAAkC,EAAA;AAElC,QAAA,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK;QACzB,MAAM,cAAc,GAAG,CAAC,EAAE,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC;AACtD,QAAA,MAAM,GAAG,GAAG,cAAc,GAAG,KAAK,CAAC,OAAO,GAAG,SAAS;QACtD,IAAI,QAAQ,EAAE;AACZ,YAAA,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;QACvB;AACA,QAAA,IAAI,GAAG,IAAI,GAAG,CAAC,gBAAgB,IAAI,GAAG,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE;AAClE,YAAA,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC;QACnC;aAAO,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE;YACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;QACnC;IACF;AACD;AAEM,MAAM,wBAAwB,GAAG,CACtC,UAGG,KAC2B;AAC9B,IAAA,MAAM,SAAS,GAAG,UAAU,IAAI,EAAE;AAElC,IAAA,MAAM,YAAY,GAAmB,CAAC,MAAM,KAAI;AAC9C,QAAA,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM;AAC9B,QAAA,MAAM,iBAAiB,GACrB,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAGnC,GAAG,CAAC,CAAC;QACN,IAAI,CAAC,iBAAiB,EAAE;YACtB;QACF;AACA,QAAA,MAAM,EAAE,OAAO,EAAE,GAAG,iBAAiB;AACrC,QAAA,IAAI,OAAO,EAAE,iBAAiB,EAAE;AAC9B,YAAA,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAC3C;AACF,IAAA,CAAC;AAED,IAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE;AACpC;;;;;;;;;;"}
+{"version":3,"file":"events.cjs","sources":["../../src/events.ts"],"sourcesContent":["/* eslint-disable no-console */\n// src/events.ts\nimport type {\n  BaseMessageFields,\n  UsageMetadata,\n} from '@langchain/core/messages';\nimport type { MultiAgentGraph, StandardGraph } from '@/graphs';\nimport type { Logger } from 'winston';\nimport type * as t from '@/types';\nimport { Constants } from '@/common';\n\nexport class HandlerRegistry {\n  private handlers: Map<string, t.EventHandler> = new Map();\n\n  register(eventType: string, handler: t.EventHandler): void {\n    this.handlers.set(eventType, handler);\n  }\n\n  getHandler(eventType: string): t.EventHandler | undefined {\n    return this.handlers.get(eventType);\n  }\n}\n\nexport function composeEventHandlers(\n  ...handlerSets: Array<Record<string, t.EventHandler> | undefined>\n): Record<string, t.EventHandler> {\n  const composed: Partial<Record<string, t.EventHandler>> = {};\n\n  for (const handlerSet of handlerSets) {\n    if (!handlerSet) {\n      continue;\n    }\n    for (const [eventType, handler] of Object.entries(handlerSet)) {\n      const previous = composed[eventType];\n      if (previous === undefined) {\n        composed[eventType] = handler;\n        continue;\n      }\n      composed[eventType] = {\n        handle: async (\n          ...args: Parameters<t.EventHandler['handle']>\n        ): Promise<void> => {\n          await previous.handle(...args);\n          await handler.handle(...args);\n        },\n      };\n    }\n  }\n\n  return composed as Record<string, t.EventHandler>;\n}\n\nexport class ModelEndHandler implements t.EventHandler {\n  collectedUsage?: UsageMetadata[];\n  constructor(collectedUsage?: UsageMetadata[]) {\n    if (collectedUsage && !Array.isArray(collectedUsage)) {\n      throw new Error('collectedUsage must be an array');\n    }\n    this.collectedUsage = collectedUsage;\n  }\n\n  async handle(\n    event: string,\n    data: t.ModelEndData,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    if (!graph || !metadata) {\n      console.warn(`Graph or metadata not found in ${event} event`);\n      return;\n    }\n\n    const usage = data?.output?.usage_metadata;\n    if (usage != null && this.collectedUsage != null) {\n      this.collectedUsage.push(usage);\n    }\n  }\n}\n\nexport class ToolEndHandler implements t.EventHandler {\n  private callback?: t.ToolEndCallback;\n  private logger?: Logger;\n  constructor(callback?: t.ToolEndCallback, logger?: Logger) {\n    this.callback = callback;\n    this.logger = logger;\n  }\n\n  /**\n   * Handles on_tool_end events from the for-await stream consumer.\n   *\n   * This handler is now purely a consumer callback — tool completion\n   * (ON_RUN_STEP_COMPLETED dispatch + session context storage) is handled\n   * in graph context by ToolNode directly, eliminating the race between\n   * the stream consumer and graph execution.\n   */\n  async handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    try {\n      if (!graph || !metadata) {\n        if (this.logger) {\n          this.logger.warn(`Graph or metadata not found in ${event} event`);\n        } else {\n          console.warn(`Graph or metadata not found in ${event} event`);\n        }\n        return;\n      }\n\n      const toolEndData = data as t.ToolEndData | undefined;\n      if (!toolEndData?.output) {\n        if (this.logger) {\n          this.logger.warn('No output found in tool_end event');\n        } else {\n          console.warn('No output found in tool_end event');\n        }\n        return;\n      }\n\n      if (\n        metadata[Constants.PROGRAMMATIC_TOOL_CALLING] === true ||\n        metadata[Constants.BASH_PROGRAMMATIC_TOOL_CALLING] === true\n      ) {\n        return;\n      }\n\n      if (this.callback) {\n        await this.callback(toolEndData, metadata);\n      }\n    } catch (error) {\n      if (this.logger) {\n        this.logger.error('Error handling tool_end event:', error);\n      } else {\n        console.error('Error handling tool_end event:', error);\n      }\n    }\n  }\n}\n\nexport class TestLLMStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk ? chunk.message : undefined;\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && typeof msg.content === 'string') {\n      process.stdout.write(msg.content);\n    }\n  }\n}\n\nexport class TestChatStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isContentChunk = !!(chunk && 'content' in chunk);\n    if (!isContentChunk) {\n      return;\n    }\n\n    const content = chunk.content;\n\n    if (chunk.tool_call_chunks && chunk.tool_call_chunks.length > 0) {\n      console.dir(chunk.tool_call_chunks, { depth: null });\n    }\n\n    if (typeof content === 'string') {\n      process.stdout.write(content);\n    } else {\n      console.dir(content, { depth: null });\n    }\n  }\n}\n\nexport class LLMStreamHandler implements t.EventHandler {\n  handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>\n  ): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk ? chunk.message : undefined;\n    if (metadata) {\n      console.log(metadata);\n    }\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && typeof msg.content === 'string') {\n      process.stdout.write(msg.content);\n    }\n  }\n}\n\nexport const createMetadataAggregator = (\n  _collected?: Record<\n    string,\n    NonNullable<BaseMessageFields['response_metadata']>\n  >[]\n): t.MetadataAggregatorResult => {\n  const collected = _collected || [];\n\n  const handleLLMEnd: t.HandleLLMEnd = (output) => {\n    const { generations } = output;\n    const lastMessageOutput = (\n      generations[generations.length - 1] as\n        | (t.StreamGeneration | undefined)[]\n        | undefined\n    )?.[0];\n    if (!lastMessageOutput) {\n      return;\n    }\n    const { message } = lastMessageOutput;\n    if (message?.response_metadata) {\n      collected.push(message.response_metadata);\n    }\n  };\n\n  return { handleLLMEnd, collected };\n};\n"],"names":["Constants"],"mappings":"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"}

package/dist/cjs/graphs/Graph.cjs

@@ -16,7 +16,7 @@ var reducer = require('../messages/reducer.cjs');
 var _enum = require('../common/enum.cjs');
 var graph = require('../utils/graph.cjs');
 var llm = require('../utils/llm.cjs');
-var handlers = require('../tools/handlers.cjs');
+require('../stream.cjs');
 var run = require('../utils/run.cjs');
 require('ai-tokenizer');
 require('zod-to-json-schema');
@@ -31,6 +31,7 @@ var node = require('../summarization/node.cjs');
 var schema = require('../tools/schema.cjs');
 var AgentContext = require('../agents/AgentContext.cjs');
 var fake = require('../llm/fake.cjs');
+var handlers = require('../tools/handlers.cjs');
 require('../tools/local/CompileCheckTool.cjs');
 require('path');
 require('fs/promises');
@@ -53,6 +54,9 @@ var toolCache = require('../llm/openrouter/toolCache.cjs');
 const { AGENT, TOOLS, SUMMARIZE } = _enum.GraphNodeKeys;
 /** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
 const CALIBRATION_VARIANCE_THRESHOLD = 0.15;
+function getHandlerDispatchedEventKey(eventName, stepId) {
+    return `${eventName}:${stepId}`;
+}
 class Graph {
     messageStepHasToolCalls = new Map();
     messageIdsByStepKey = new Map();
@@ -63,11 +67,12 @@ class Graph {
     contentIndexMap = new Map();
     toolCallStepIds = new Map();
     /**
-     * Step IDs that have been dispatched via handler registry directly
-     * (in dispatchRunStep).  Used by the custom event callback to skip
-     * duplicate dispatch through the LangGraph callback chain.
+     * Step IDs dispatched through the handler registry during this run.
+     * Event echo suppression is tracked separately so repeated deltas for
+     * the same step are scoped to the active custom event dispatch.
      */
     handlerDispatchedStepIds = new Set();
+    handlerDispatchedEventCounts = new Map();
     signal;
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds;
@@ -86,6 +91,16 @@ class Graph {
      * graph compiles.
      */
     toolOutputReferences;
+    /**
+     * Run-scoped opt-in for eager event-driven tool execution. The stream
+     * handler may prestart eligible event-driven tools; ToolNode later
+     * consumes the settled promises while preserving final ToolMessage order.
+     */
+    eagerEventToolExecution;
+    eagerEventToolExecutions = new Map();
+    eagerEventToolUsageCount = new Map();
+    eagerEventToolUsageCountsByAgentId = new Map();
+    eagerEventToolCallChunks = new Map();
     /**
      * Run-scoped execution backend for built-in code tools. Defaults to the
      * remote Code API sandbox when unset.
@@ -124,7 +139,12 @@ class Graph {
         this.hookRegistry = undefined;
         this.humanInTheLoop = undefined;
         this.toolOutputReferences = undefined;
+        this.eagerEventToolExecution = undefined;
+        this.eagerEventToolExecutions.clear();
+        this.clearEagerEventToolUsageCounts();
+        this.eagerEventToolCallChunks.clear();
         this.toolExecution = undefined;
+        this.handlerDispatchedEventCounts.clear();
         /**
          * ToolNodes compiled from this graph captured the registry
          * instance at construction time, so simply dropping the Graph's
@@ -154,6 +174,39 @@ class Graph {
         this._compiledToolNodes.clear();
         this.sessions.clear();
     }
+    getEagerEventToolUsageCount(agentId) {
+        if (agentId == null || agentId === '') {
+            return this.eagerEventToolUsageCount;
+        }
+        let usageCount = this.eagerEventToolUsageCountsByAgentId.get(agentId);
+        if (usageCount == null) {
+            usageCount = new Map();
+            this.eagerEventToolUsageCountsByAgentId.set(agentId, usageCount);
+        }
+        return usageCount;
+    }
+    clearEagerEventToolUsageCounts() {
+        this.eagerEventToolUsageCount.clear();
+        for (const usageCount of this.eagerEventToolUsageCountsByAgentId.values()) {
+            usageCount.clear();
+        }
+    }
+    markHandlerDispatchedEvent(eventName, stepId) {
+        const key = getHandlerDispatchedEventKey(eventName, stepId);
+        this.handlerDispatchedEventCounts.set(key, (this.handlerDispatchedEventCounts.get(key) ?? 0) + 1);
+        return () => {
+            const count = this.handlerDispatchedEventCounts.get(key) ?? 0;
+            if (count <= 1) {
+                this.handlerDispatchedEventCounts.delete(key);
+                return;
+            }
+            this.handlerDispatchedEventCounts.set(key, count - 1);
+        };
+    }
+    hasHandlerDispatchedEvent(eventName, stepId) {
+        const key = getHandlerDispatchedEventKey(eventName, stepId);
+        return (this.handlerDispatchedEventCounts.get(key) ?? 0) > 0;
+    }
     /**
      * Subclass hook to register a freshly compiled ToolNode so
      * `clearHeavyState` can flush its per-Run direct-path turn cache
@@ -284,7 +337,11 @@ class StandardGraph extends Graph {
          * a stale reference on 2nd+ processStream calls.
          */
         this.toolCallStepIds.clear();
+        this.eagerEventToolExecutions.clear();
+        this.clearEagerEventToolUsageCounts();
+        this.eagerEventToolCallChunks.clear();
         this.handlerDispatchedStepIds = graph.resetIfNotEmpty(this.handlerDispatchedStepIds, new Set());
+        this.handlerDispatchedEventCounts = graph.resetIfNotEmpty(this.handlerDispatchedEventCounts, new Map());
         this.messageIdsByStepKey = graph.resetIfNotEmpty(this.messageIdsByStepKey, new Map());
         this.messageStepHasToolCalls = graph.resetIfNotEmpty(this.messageStepHasToolCalls, new Map());
         this.prelimMessageIdsByStepKey = graph.resetIfNotEmpty(this.prelimMessageIdsByStepKey, new Map());
@@ -508,6 +565,9 @@ class StandardGraph extends Graph {
                 toolRegistry: agentContext?.toolRegistry,
                 hookRegistry: this.hookRegistry,
                 humanInTheLoop: this.humanInTheLoop,
+                eagerEventToolExecution: this.eagerEventToolExecution,
+                eagerEventToolExecutions: this.eagerEventToolExecutions,
+                eagerEventToolUsageCount: this.getEagerEventToolUsageCount(agentContext?.agentId),
                 toolExecution: this.toolExecution,
                 directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
                 maxContextTokens: agentContext?.maxContextTokens,
@@ -958,7 +1018,7 @@ class StandardGraph extends Graph {
                         if (typeof content === 'string') {
                             await this.dispatchMessageDelta(stepId, {
                                 content: [{ type: _enum.ContentTypes.TEXT, text: content }],
-                            });
+                            }, metadata);
                         }
                         else if (Array.isArray(content) &&
                             content.every((c) => typeof c === 'object' &&
@@ -967,7 +1027,7 @@ class StandardGraph extends Graph {
                                 c.type.startsWith('text'))) {
                             await this.dispatchMessageDelta(stepId, {
                                 content: content,
-                            });
+                            }, metadata);
                         }
                     }
                 }
@@ -997,7 +1057,7 @@ class StandardGraph extends Graph {
                     if (typeof content === 'string') {
                         await this.dispatchMessageDelta(stepId, {
                             content: [{ type: _enum.ContentTypes.TEXT, text: content }],
-                        });
+                        }, metadata);
                     }
                     else if (Array.isArray(content) &&
                         content.every((c) => typeof c === 'object' &&
@@ -1006,7 +1066,7 @@ class StandardGraph extends Graph {
                             c.type.startsWith('text'))) {
                         await this.dispatchMessageDelta(stepId, {
                             content: content,
-                        });
+                        }, metadata);
                     }
                 }
             }
@@ -1176,8 +1236,16 @@ class StandardGraph extends Graph {
                         await handler.handle(_enum.GraphEvents.ON_RUN_STEP, runStep, resolvedConfig?.configurable, this);
                         this.handlerDispatchedStepIds.add(runStep.id);
                     }
-                    if (resolvedConfig) {
-                        await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP, runStep, resolvedConfig);
+                    const unmarkHandlerDispatchedEvent = handler
+                        ? this.markHandlerDispatchedEvent(_enum.GraphEvents.ON_RUN_STEP, runStep.id)
+                        : undefined;
+                    try {
+                        if (resolvedConfig) {
+                            await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP, runStep, resolvedConfig);
+                        }
+                    }
+                    finally {
+                        unmarkHandlerDispatchedEvent?.();
                     }
                 },
                 dispatchRunStepCompleted: async (stepId, result, nodeConfig) => {
@@ -1208,7 +1276,7 @@ class StandardGraph extends Graph {
         const StateAnnotation = langgraph.Annotation.Root({
             messages: langgraph.Annotation({
                 reducer: (a, b) => {
-                    if (!a.length) {
+                    if (!this.messages.length) {
                         this.startIndex = a.length + b.length;
                     }
                     const result = reducer.messagesStateReducer(a, b);
@@ -1305,7 +1373,15 @@ class StandardGraph extends Graph {
         // but the primary dispatch above guarantees the event reaches the handler.
         // The customEventCallback in run.ts skips events already dispatched above
         // to prevent double handling.
-        await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP, runStep, this.config);
+        const unmarkHandlerDispatchedEvent = handler
+            ? this.markHandlerDispatchedEvent(_enum.GraphEvents.ON_RUN_STEP, stepId)
+            : undefined;
+        try {
+            await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP, runStep, this.config);
+        }
+        finally {
+            unmarkHandlerDispatchedEvent?.();
+        }
         return stepId;
     }
     /**
@@ -1354,7 +1430,7 @@ class StandardGraph extends Graph {
     async handleToolCallError(data, metadata) {
         await StandardGraph.handleToolCallErrorStatic(this, data, metadata);
     }
-    async dispatchRunStepDelta(id, delta) {
+    async dispatchRunStepDelta(id, delta, metadata) {
         if (!this.config) {
             throw new Error('No config provided');
         }
@@ -1365,9 +1441,22 @@ class StandardGraph extends Graph {
             id,
             delta,
         };
-        await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP_DELTA, runStepDelta, this.config);
+        const handler = this.handlerRegistry?.getHandler(_enum.GraphEvents.ON_RUN_STEP_DELTA);
+        if (handler) {
+            await handler.handle(_enum.GraphEvents.ON_RUN_STEP_DELTA, runStepDelta, metadata, this);
+            this.handlerDispatchedStepIds.add(id);
+        }
+        const unmarkHandlerDispatchedEvent = handler
+            ? this.markHandlerDispatchedEvent(_enum.GraphEvents.ON_RUN_STEP_DELTA, id)
+            : undefined;
+        try {
+            await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP_DELTA, runStepDelta, this.config);
+        }
+        finally {
+            unmarkHandlerDispatchedEvent?.();
+        }
     }
-    async dispatchMessageDelta(id, delta) {
+    async dispatchMessageDelta(id, delta, metadata) {
         if (!this.config) {
             throw new Error('No config provided');
         }
@@ -1375,9 +1464,22 @@ class StandardGraph extends Graph {
             id,
             delta,
         };
-        await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_MESSAGE_DELTA, messageDelta, this.config);
+        const handler = this.handlerRegistry?.getHandler(_enum.GraphEvents.ON_MESSAGE_DELTA);
+        if (handler) {
+            await handler.handle(_enum.GraphEvents.ON_MESSAGE_DELTA, messageDelta, metadata, this);
+            this.handlerDispatchedStepIds.add(id);
+        }
+        const unmarkHandlerDispatchedEvent = handler
+            ? this.markHandlerDispatchedEvent(_enum.GraphEvents.ON_MESSAGE_DELTA, id)
+            : undefined;
+        try {
+            await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_MESSAGE_DELTA, messageDelta, this.config);
+        }
+        finally {
+            unmarkHandlerDispatchedEvent?.();
+        }
     }
-    dispatchReasoningDelta = async (stepId, delta) => {
+    dispatchReasoningDelta = async (stepId, delta, metadata) => {
         if (!this.config) {
             throw new Error('No config provided');
         }
@@ -1385,7 +1487,20 @@ class StandardGraph extends Graph {
             id: stepId,
             delta,
         };
-        await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_REASONING_DELTA, reasoningDelta, this.config);
+        const handler = this.handlerRegistry?.getHandler(_enum.GraphEvents.ON_REASONING_DELTA);
+        if (handler) {
+            await handler.handle(_enum.GraphEvents.ON_REASONING_DELTA, reasoningDelta, metadata, this);
+            this.handlerDispatchedStepIds.add(stepId);
+        }
+        const unmarkHandlerDispatchedEvent = handler
+            ? this.markHandlerDispatchedEvent(_enum.GraphEvents.ON_REASONING_DELTA, stepId)
+            : undefined;
+        try {
+            await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_REASONING_DELTA, reasoningDelta, this.config);
+        }
+        finally {
+            unmarkHandlerDispatchedEvent?.();
+        }
     };
 }