@librechat/agents 3.4.4 → 3.4.6

package/dist/cjs/types/hitl.cjs

@@ -0,0 +1,13 @@
+//#region src/types/hitl.ts
+/**
+* Type guard narrowing an arbitrary value to an
+* `AskUserQuestionInterruptPayload`. Same `unknown`-tolerant contract
+* as `isToolApprovalInterrupt`.
+*/
+function isAskUserQuestionInterrupt(payload) {
+	return typeof payload === "object" && payload !== null && payload.type === "ask_user_question";
+}
+//#endregion
+exports.isAskUserQuestionInterrupt = isAskUserQuestionInterrupt;
+
+//# sourceMappingURL=hitl.cjs.map

package/dist/cjs/types/hitl.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.cjs","names":[],"sources":["../../../src/types/hitl.ts"],"sourcesContent":["/**\n * First-class human-in-the-loop (HITL) types for `@librechat/agents`.\n * Surfaces the interrupt payload that `ToolNode` raises when a `PreToolUse`\n * hook returns `decision: 'ask'` and HITL is enabled on the run, plus the\n * resume-decision shape the host returns to continue or reject the tool.\n *\n * Mirrors the LangChain HITL middleware shape (action_requests /\n * review_configs) so hosts and clients can share rendering/UI semantics\n * across the langchain ecosystem.\n */\n\n/** Per-tool approval request emitted inside an interrupt payload. */\nexport interface ToolApprovalRequest {\n  /** Stable id of the tool call (matches LangGraph `ToolCall.id`). */\n  tool_call_id: string;\n  /** Tool name being invoked. */\n  name: string;\n  /**\n   * Arguments the tool is about to be invoked with — already resolved by\n   * any `{{tool<i>turn<n>}}` references and any `updatedInput` returned\n   * by the firing PreToolUse hook.\n   */\n  arguments: Record<string, unknown>;\n  /**\n   * Optional reason the hook supplied for asking (e.g., \"destructive\n   * filesystem write\"). Hosts can render this verbatim.\n   */\n  description?: string;\n}\n\n/** Allowed host-side decisions for a `tool_approval` interrupt. */\nexport type ToolApprovalDecisionType =\n  | 'approve'\n  | 'reject'\n  | 'edit'\n  | 'respond';\n\n/** Per-action review configuration paired with each action_request. */\nexport interface ToolApprovalReviewConfig {\n  /** Tool name (matches the `name` field on the corresponding action_request). */\n  action_name: string;\n  /**\n   * Stable id of the tool call this review_config applies to (matches\n   * the `tool_call_id` of the corresponding action_request). Lets a UI\n   * map review_configs → action_requests directly when a batch\n   * contains the same tool called more than once — by-position\n   * mapping breaks down with duplicates.\n   */\n  tool_call_id: string;\n  /** Decisions the host UI is allowed to surface for this action. */\n  allowed_decisions: ToolApprovalDecisionType[];\n}\n\n/**\n * Resume value the host returns through `Run.resume(decisions)` after a\n * `tool_approval` interrupt. One entry per action_request, in the same\n * order. Hosts may also return a record keyed by `tool_call_id`; the SDK\n * handles either shape.\n *\n * Variants:\n *   - `approve`: run the tool with its original (or hook-rewritten) args.\n *   - `reject`: skip the tool, emit a blocked error `ToolMessage` with\n *     `reason` surfaced to the model.\n *   - `edit`: replace the tool's args with `updatedInput` (re-resolves\n *     any `{{tool<i>turn<n>}}` placeholders) and run the tool.\n *   - `respond`: skip the tool entirely and emit `responseText` as a\n *     successful `ToolMessage`. Mirrors LangChain HITL middleware's\n *     `respond` semantic — the human supplies the result the model sees,\n *     bypassing tool execution. Useful when the user wants to short-circuit\n *     a tool call with a hand-written answer (e.g., \"don't actually run\n *     the search, just tell the model 'no relevant results'\").\n *\n * Note on hook semantics: `respond` does NOT fire the per-tool\n * `PostToolUse` hook (no real tool execution happened, so the\n * \"post-tool\" semantic doesn't apply). It DOES appear in the\n * `PostToolBatch` entry array with `status: 'success'` and the\n * user-supplied text as `toolOutput`, so batch-level audit /\n * convention hooks see the full set of outcomes.\n */\nexport type ToolApprovalDecision =\n  | { type: 'approve' }\n  | { type: 'reject'; reason?: string }\n  | { type: 'edit'; updatedInput: Record<string, unknown> }\n  | { type: 'respond'; responseText: string };\n\n/** Map form of resume decisions, keyed by tool call id. */\nexport type ToolApprovalDecisionMap = Record<string, ToolApprovalDecision>;\n\n/**\n * Categories of human-in-the-loop interrupts the SDK can raise. Hosts\n * narrow on `HumanInterruptPayload.type` to determine which payload\n * shape they're handling and which resume value to send back through\n * `Run.resume()`.\n *\n * Exported as a discrete type so downstream consumers (notably\n * LibreChat's wire types in `librechat-data-provider`) can mirror\n * the discriminator alongside their own host-side `PendingAction`\n * record without re-declaring the union themselves. Internal SDK\n * code narrows directly on the literal strings via the type guards\n * below; this type alias is primarily an integration-layer contract.\n */\nexport type HumanInterruptType = 'tool_approval' | 'ask_user_question';\n\n/** Identifies an interrupt that originated inside a checkpointed subagent. */\nexport interface SubagentInterruptScope {\n  /** Child execution run id used by subagent update and usage events. */\n  run_id: string;\n  /** Child agent id that owns the interrupted tool call. */\n  agent_id: string;\n  /** Configured subagent type selected by the parent tool call. */\n  subagent_type: string;\n  /** Parent `subagent` tool call that launched this child. */\n  parent_tool_call_id?: string;\n}\n\n/**\n * Structured payload the SDK passes to `interrupt()` when one or more\n * pending tool calls require host approval. All `ask`-decision tool calls\n * from a single ToolNode batch are bundled into one interrupt so the host\n * can render and resolve them together.\n *\n * Resume value: `ToolApprovalDecision[]` (in `action_requests` order) or\n * `ToolApprovalDecisionMap` (keyed by `tool_call_id`).\n */\nexport interface ToolApprovalInterruptPayload {\n  type: 'tool_approval';\n  action_requests: ToolApprovalRequest[];\n  review_configs: ToolApprovalReviewConfig[];\n  /** Hook-registry session whose policy raised this interrupt. */\n  hook_session_id?: string;\n  /** Present when the approval request was bridged from a child graph. */\n  subagent?: SubagentInterruptScope;\n}\n\n/**\n * Pre-defined option the user can pick when answering an\n * `ask_user_question` interrupt. The selected option's `value` becomes\n * the resume value's `answer` field.\n */\nexport interface AskUserQuestionOption {\n  /** Human-readable label rendered in the host UI. */\n  label: string;\n  /** Value returned via `AskUserQuestionResolution.answer` if picked. */\n  value: string;\n}\n\n/** Question request emitted inside an `ask_user_question` interrupt. */\nexport interface AskUserQuestionRequest {\n  /** The question to ask the human. */\n  question: string;\n  /** Optional context / description rendered alongside the question. */\n  description?: string;\n  /**\n   * Optional pre-defined response options. When present, hosts can render\n   * a picker; the user may still type a free-form answer when the host\n   * UI allows it. Omit to require a free-form answer.\n   */\n  options?: AskUserQuestionOption[];\n  /**\n   * When `true`, the host UI may let the user pick several options; the\n   * resulting `AskUserQuestionResolution.answer` is the selected option\n   * values joined by `\", \"`. When omitted or `false`, hosts render a\n   * single-select picker. Only meaningful alongside `options`.\n   */\n  multiSelect?: boolean;\n}\n\n/** One independently answerable question in a batched question request. */\nexport interface AskUserQuestionBatchItem extends AskUserQuestionRequest {\n  /** Batch-unique identifier (`[A-Za-z][A-Za-z0-9_-]{0,63}`). */\n  id: string;\n  /** Optional short heading rendered above the question. */\n  header?: string;\n}\n\n/** Input shape for one tool call that asks one to four questions together. */\nexport interface AskUserQuestionsRequest {\n  questions: AskUserQuestionBatchItem[];\n}\n\n/**\n * Structured payload the SDK passes to `interrupt()` when an agent (or\n * a custom node) needs to ask the user a clarifying question. Mirrors\n * Claude Code's `AskUserQuestion` semantic. Resume value is\n * `AskUserQuestionResolution` for a single question, or\n * `AskUserQuestionsResolution` when `questions` is present.\n */\nexport interface AskUserQuestionInterruptPayload {\n  type: 'ask_user_question';\n  /**\n   * Single-question request, or the first question as a compatibility\n   * fallback when `questions` contains a batch. This lets existing hosts show\n   * a useful preview during a staged rollout, but they must support `questions`\n   * and `AskUserQuestionsResolution` before enabling a batched tool schema.\n   */\n  question: AskUserQuestionRequest;\n  /** One to four questions collected by one `ask_user_question` tool call. */\n  questions?: AskUserQuestionsRequest['questions'];\n  /**\n   * The `tool_call_id` of the ask-tool call that raised this interrupt,\n   * when the tool body supplied it (see `askUserQuestion`'s `options`).\n   * Lets hosts attribute the question — and later the answer — to the\n   * exact tool-call content part instead of guessing by position, which\n   * mislabels cards when a model emits several ask calls in one turn.\n   */\n  tool_call_id?: string;\n}\n\n/** Batch-specialized ask payload for hosts that render several questions. */\nexport interface AskUserQuestionsInterruptPayload\n  extends AskUserQuestionInterruptPayload {\n  questions: AskUserQuestionsRequest['questions'];\n}\n\n/**\n * Discriminated union of every interrupt payload the SDK raises. New\n * variants can be added without breaking existing handlers as long as\n * those handlers check `payload.type` before reading variant-specific\n * fields. Use the `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt`\n * type guards for ergonomic narrowing.\n */\nexport type HumanInterruptPayload =\n  | ToolApprovalInterruptPayload\n  | AskUserQuestionInterruptPayload;\n\n/** Resume value the host returns for an `ask_user_question` interrupt. */\nexport interface AskUserQuestionResolution {\n  /**\n   * The human's answer. Free-form text, or — when `options` were\n   * provided — one of the option `value`s (or, when the request set\n   * `multiSelect`, several option `value`s joined by `\", \"`). Hosts may\n   * also send any structured object their custom UI defines; see the\n   * host docs for what your downstream consumer expects.\n   */\n  answer: string;\n}\n\n/** Resume value for a batched `ask_user_question` interrupt. */\nexport interface AskUserQuestionsResolution {\n  /** Human answers keyed by each `AskUserQuestionBatchItem.id`. */\n  answers: Record<string, string>;\n}\n\n/**\n * Type guard narrowing an arbitrary value to a `ToolApprovalInterruptPayload`.\n * Accepts `unknown` (not just `HumanInterruptPayload`) because hosts can\n * raise custom interrupt payloads from custom nodes — `getInterrupt()`\n * surfaces them as-is, and downstream code must validate the shape at\n * runtime before reading variant-specific fields.\n */\nexport function isToolApprovalInterrupt(\n  payload: unknown\n): payload is ToolApprovalInterruptPayload {\n  return (\n    typeof payload === 'object' &&\n    payload !== null &&\n    (payload as { type?: unknown }).type === 'tool_approval'\n  );\n}\n\n/**\n * Type guard narrowing an arbitrary value to an\n * `AskUserQuestionInterruptPayload`. Same `unknown`-tolerant contract\n * as `isToolApprovalInterrupt`.\n */\nexport function isAskUserQuestionInterrupt(\n  payload: unknown\n): payload is AskUserQuestionInterruptPayload {\n  return (\n    typeof payload === 'object' &&\n    payload !== null &&\n    (payload as { type?: unknown }).type === 'ask_user_question'\n  );\n}\n\n/**\n * Run-level configuration controlling HITL semantics. **HITL is OFF by\n * default** for now — the SDK ships the interrupt machinery, but the\n * default stays opt-in until host UIs (notably LibreChat) ship the\n * approval-rendering affordances needed to surface interrupts to end\n * users. Without that UI, an interrupt with no resolver looks like a\n * hung tool-call card. Hosts opt in explicitly with\n * `{ enabled: true }`. The intent is to flip this default to ON in a\n * future minor once the consumer ecosystem is ready to render\n * interrupts end-to-end.\n *\n * When enabled (`{ enabled: true }`):\n *\n *   - `PreToolUse` hooks returning `decision: 'ask'` raise a real\n *     LangGraph `interrupt()` instead of being treated as a synchronous\n *     deny.\n *   - `Run.create` installs a `MemorySaver` checkpointer fallback on the\n *     run's compile options if the host did not provide one, since\n *     LangGraph requires a checkpointer to suspend and resume.\n *\n * When disabled (the default — omitted, or `{ enabled: false }`):\n * `ask` decisions are fail-closed (blocked with an error\n * `ToolMessage`) and no checkpointer is implicitly attached. This\n * matches the pre-HITL behavior so existing hosts upgrading the SDK\n * see no change until they're ready to wire the resume UI.\n *\n * ## Scope: every tool the ToolNode runs\n *\n * The interrupt path is wired into both `dispatchToolEvents` (the\n * event-driven path) and `runDirectToolWithLifecycleHooks` (the\n * direct path used by `directToolNames` entries — graph-managed\n * handoff/subagent tools and every in-process `graphTool` instance).\n * `PreToolUse` hooks fire for every tool the ToolNode invokes, and\n * HITL approval gates every tool whose hook returns `'ask'` —\n * regardless of whether the tool is dispatched as an event or\n * invoked in-process. This convergence happened in two follow-up\n * commits to the original HITL surface (see `Graph.ts` —\n * `hookRegistry`/`humanInTheLoop` are passed in both\n * event-driven and legacy branches; and `ToolNode.runDirectToolWithLifecycleHooks`\n * — direct-path tools build their own single-tool `tool_approval`\n * payload and raise `interrupt()` the same way the event path does).\n *\n * Practical implications:\n *   - Every host gets the full HITL surface across every tool the\n *     model calls — event-dispatched, direct, mixed.\n *   - `createToolPolicyHook` and `createWorkspacePolicyHook` apply\n *     uniformly. A hook can be registered without knowing or caring\n *     which path the tool will take.\n *   - Direct tools that the host opted into via `directToolNames` no\n *     longer bypass policy. If you need a tool to skip the hook\n *     surface entirely, omit it from any registered matcher.\n *\n * ## Resume re-execution: every tool in the interrupted batch\n *\n * LangGraph rolls back to the start of the interrupted node on\n * resume. That means **every tool in the same batch as the one that\n * interrupted re-runs from the top on the resume pass**, not just\n * the interrupting tool, and not just the direct half (this used to\n * be framed as a direct-tool-specific concern; it is not — it\n * applies to event-dispatched siblings too). Practical contract:\n *\n *   - The body of the interrupting tool itself runs **once** total\n *     (the first pass interrupted *before* the body, the resume pass\n *     ran the body after the host's decision was applied).\n *   - The body of any sibling tool that already executed in the\n *     same batch before the interrupting tool runs **twice** — once\n *     on the first pass, once on the resume pass.\n *   - `PreToolUse` hooks fire **once per pass per tool**. A hook\n *     that always returns `'ask'` will loop forever on resume; real\n *     hooks should be deterministic w.r.t. inputs and use the\n *     `'ask' → host approves → resume → hook returns 'allow'`\n *     pattern, where the second-pass `allow` reflects the host\n *     having recorded the approval (e.g., a session-scoped approved-\n *     paths set keyed by `runId`).\n *\n * Consequence: any tool with side effects MUST be idempotent if\n * there's any chance another tool in the same batch could trigger\n * an interrupt. This applies equally to direct tools (handoffs,\n * subagents) and to event tools.\n *\n * ### Guarding non-idempotent siblings via `interruptingToolNames`\n *\n * The \"must be idempotent\" rule above is unavoidable in the general\n * case, but the SDK can protect siblings against the one interrupt\n * shape it can predict: a tool whose *body* raises `interrupt()`\n * mid-execution — the `ask_user_question` shape, where the tool\n * suspends the run to collect a human answer. Declare such tools in\n * `RunConfig.interruptingToolNames`\n * ({@link ToolNodeOptions.interruptingToolNames}) and the ToolNode\n * schedules them, within each batch, **ahead of** their\n * non-interrupting direct siblings. When one interrupts, the batch\n * unwinds before any declared-safe sibling has run, so the sibling\n * executes exactly once (on resume) instead of twice. Empirically:\n *\n *   - A **direct** sibling sharing the interrupter's in-process\n *     `Promise.all` is the only shape that double-executes; declaring\n *     the interrupter closes it.\n *   - An **event-dispatched** sibling is already safe without any\n *     config: the ToolNode awaits the whole direct group (where the\n *     body interrupt unwinds) before it dispatches event tools, so a\n *     dispatched sibling never runs on the first pass.\n *\n * This is a *scheduling* guard, not full resume idempotency: it only\n * covers tools that interrupt from their own body and only protects\n * siblings scheduled after them. It does not retroactively make a\n * `PreToolUse` `'ask'` gate on tool B stop tool A (already executed)\n * from re-running — unless B is itself declared interrupting, so it\n * runs first. Tools with side effects should still be written\n * idempotent as defense in depth.\n *\n * The guard only REORDERS the direct group — declaring a name does not\n * force it onto the direct path. The interrupting tool must already be a\n * real in-process graphTool (the only kind whose body can reach\n * `interrupt()`). A name that resolves to a schema-only event stub (an\n * inherited `toolDefinition` with no executable instance, e.g. in a\n * self-spawned child that scrubs `graphTools`) stays event-dispatched\n * and the ordering is a no-op for it.\n *\n * ## Note on idempotency\n *\n * Same root cause as the resume re-execution above: LangGraph\n * re-runs the interrupted node from the start on resume, which\n * fires `PreToolUse` hooks again. Hooks that produce side effects\n * (logging, external calls) will see at least two invocations per\n * paused turn — exactly two for the interrupting tool, possibly\n * more across siblings.\n */\nexport interface HumanInTheLoopConfig {\n  /**\n   * Master switch. Defaults to `false` — omit the field (or pass\n   * `false`) to keep HITL off, or set `true` to opt in once the host\n   * UI is ready to render and resolve `tool_approval` interrupts.\n   */\n  enabled?: boolean;\n}\n\n/**\n * Snapshot of an in-flight interrupt surfaced from `Run.processStream`\n * via `run.getInterrupt()`. Hosts persist this alongside their job\n * record so they can later call `Run.resume(decisions)` against a Run\n * compiled with the same `thread_id` / checkpointer.\n *\n * The `payload` type defaults to `HumanInterruptPayload` (the SDK's\n * built-in `tool_approval` / `ask_user_question` discriminated union)\n * for ergonomic narrowing in the common case. Hosts that raise custom\n * interrupt payloads from custom graph nodes can pass the type\n * parameter (`run.getInterrupt<MyCustom>()` or\n * `RunInterruptResult<MyCustom>`) — the SDK does not validate the\n * runtime shape, it just transports whatever the node passed to\n * `interrupt()`. Use the `isToolApprovalInterrupt` /\n * `isAskUserQuestionInterrupt` guards (which accept `unknown`) when\n * the source of the interrupt isn't statically known.\n */\nexport interface RunInterruptResult<TPayload = HumanInterruptPayload> {\n  /** Stable id of the LangGraph interrupt (from `Interrupt.id`). */\n  interruptId: string;\n  /** `thread_id` the run was bound to — required to resume. */\n  threadId?: string;\n  /** LangGraph checkpoint id that contains the paused interrupt task. */\n  checkpointId?: string;\n  /** LangGraph checkpoint namespace for the paused interrupt task. */\n  checkpointNs?: string;\n  /** Structured payload describing what needs human input. */\n  payload: TPayload;\n}\n"],"mappings":";;;;;;AAyQA,SAAgB,2BACd,SAC4C;CAC5C,OACE,OAAO,YAAY,YACnB,YAAY,QACX,QAA+B,SAAS;AAE7C"}

package/dist/cjs/utils/handlers.cjs

@@ -36,6 +36,9 @@ function createHandlers(callbacks) {
 				});
 				callbacks?.onRunStepDelta?.(event, data);
 			} },
+			["on_run_step_closed"]: { handle: (event, data) => {
+				callbacks?.onRunStepClosed?.(event, data);
+			} },
 			["on_message_delta"]: { handle: (event, data) => {
 				aggregateContent({
 					event,

package/dist/cjs/utils/handlers.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.cjs","names":["createContentAggregator","ToolEndHandler","ModelEndHandler","ChatModelStreamHandler"],"sources":["../../../src/utils/handlers.ts"],"sourcesContent":["/**\n * Multi-Agent Handler Utilities\n *\n * Provides a simple helper to create handlers with content aggregation for multi-agent scripts.\n *\n * Usage:\n * ```typescript\n * const { contentParts, aggregateContent, handlers } = createHandlers();\n *\n * // With callbacks\n * const { contentParts, aggregateContent, handlers } = createHandlers({\n *   onRunStep: (event, data) => console.log('Step:', data),\n *   onRunStepCompleted: (event, data) => console.log('Completed:', data)\n * });\n * ```\n */\n\nimport type * as t from '@/types';\nimport { ChatModelStreamHandler, createContentAggregator } from '@/stream';\nimport { ToolEndHandler, ModelEndHandler } from '@/events';\nimport { GraphEvents } from '@/common';\n\ninterface HandlerCallbacks {\n  onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;\n  onRunStepCompleted?: (\n    event: GraphEvents.ON_RUN_STEP_COMPLETED,\n    data: t.StreamEventData\n  ) => void;\n  onRunStepDelta?: (\n    event: GraphEvents.ON_RUN_STEP_DELTA,\n    data: t.StreamEventData\n  ) => void;\n  onMessageDelta?: (\n    event: GraphEvents.ON_MESSAGE_DELTA,\n    data: t.StreamEventData\n  ) => void;\n}\n\n/**\n * Creates handlers with content aggregation for multi-agent scripts\n */\nexport function createHandlers(callbacks?: HandlerCallbacks): {\n  contentParts: Array<t.MessageContentComplex | undefined>;\n  aggregateContent: ReturnType<\n    typeof createContentAggregator\n  >['aggregateContent'];\n  handlers: Record<string, t.EventHandler>;\n} {\n  // Set up content aggregator\n  const { contentParts, aggregateContent } = createContentAggregator();\n\n  // Create the handlers object\n  const handlers = {\n    [GraphEvents.TOOL_END]: new ToolEndHandler(),\n    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),\n    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),\n\n    [GraphEvents.ON_RUN_STEP]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStep });\n        callbacks?.onRunStep?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_COMPLETED]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_COMPLETED,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({\n          event,\n          data: data as unknown as { result: t.ToolEndEvent },\n        });\n        callbacks?.onRunStepCompleted?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStepDeltaEvent });\n        callbacks?.onRunStepDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_MESSAGE_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_MESSAGE_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.MessageDeltaEvent });\n        callbacks?.onMessageDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_DELTA]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeDeltaData,\n        });\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_COMPLETE]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeCompleteEvent,\n        });\n      },\n    },\n  };\n\n  return {\n    contentParts,\n    aggregateContent,\n    handlers,\n  };\n}\n"],"mappings":";;;;;;;;AAyCA,SAAgB,eAAe,WAM7B;CAEA,MAAM,EAAE,cAAc,qBAAqBA,eAAAA,wBAAwB;CAsEnE,OAAO;EACL;EACA;EACA,UAAA;oBArEwB,IAAIC,eAAAA,eAAe;0BACb,IAAIC,eAAAA,gBAAgB;6BACjB,IAAIC,eAAAA,uBAAuB;oBAEjC,EACzB,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAAkB,CAAC;IACnD,WAAW,YAAY,OAAO,IAAI;GACpC,EACF;8BAEqC,EACnC,SACE,OACA,SACS;IACT,iBAAiB;KACf;KACM;IACR,CAAC;IACD,WAAW,qBAAqB,OAAO,IAAI;GAC7C,EACF;0BAEiC,EAC/B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;yBAEgC,EAC9B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;2BAEkC,EAChC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;8BAEqC,EACnC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;EAMO;CACT;AACF"}
+{"version":3,"file":"handlers.cjs","names":["createContentAggregator","ToolEndHandler","ModelEndHandler","ChatModelStreamHandler"],"sources":["../../../src/utils/handlers.ts"],"sourcesContent":["/**\n * Multi-Agent Handler Utilities\n *\n * Provides a simple helper to create handlers with content aggregation for multi-agent scripts.\n *\n * Usage:\n * ```typescript\n * const { contentParts, aggregateContent, handlers } = createHandlers();\n *\n * // With callbacks\n * const { contentParts, aggregateContent, handlers } = createHandlers({\n *   onRunStep: (event, data) => console.log('Step:', data),\n *   onRunStepCompleted: (event, data) => console.log('Completed:', data)\n * });\n * ```\n */\n\nimport type * as t from '@/types';\nimport { ChatModelStreamHandler, createContentAggregator } from '@/stream';\nimport { ToolEndHandler, ModelEndHandler } from '@/events';\nimport { GraphEvents } from '@/common';\n\ninterface HandlerCallbacks {\n  onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;\n  onRunStepCompleted?: (\n    event: GraphEvents.ON_RUN_STEP_COMPLETED,\n    data: t.StreamEventData\n  ) => void;\n  onRunStepDelta?: (\n    event: GraphEvents.ON_RUN_STEP_DELTA,\n    data: t.StreamEventData\n  ) => void;\n  onRunStepClosed?: (\n    event: GraphEvents.ON_RUN_STEP_CLOSED,\n    data: t.RunStepClosedEvent\n  ) => void;\n  onMessageDelta?: (\n    event: GraphEvents.ON_MESSAGE_DELTA,\n    data: t.StreamEventData\n  ) => void;\n}\n\n/**\n * Creates handlers with content aggregation for multi-agent scripts\n */\nexport function createHandlers(callbacks?: HandlerCallbacks): {\n  contentParts: Array<t.MessageContentComplex | undefined>;\n  aggregateContent: ReturnType<\n    typeof createContentAggregator\n  >['aggregateContent'];\n  handlers: Record<string, t.EventHandler>;\n} {\n  // Set up content aggregator\n  const { contentParts, aggregateContent } = createContentAggregator();\n\n  // Create the handlers object\n  const handlers = {\n    [GraphEvents.TOOL_END]: new ToolEndHandler(),\n    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),\n    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),\n\n    [GraphEvents.ON_RUN_STEP]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStep });\n        callbacks?.onRunStep?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_COMPLETED]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_COMPLETED,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({\n          event,\n          data: data as unknown as { result: t.ToolEndEvent },\n        });\n        callbacks?.onRunStepCompleted?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.RunStepDeltaEvent });\n        callbacks?.onRunStepDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_RUN_STEP_CLOSED]: {\n      handle: (\n        event: GraphEvents.ON_RUN_STEP_CLOSED,\n        data: t.StreamEventData\n      ): void => {\n        callbacks?.onRunStepClosed?.(event, data as t.RunStepClosedEvent);\n      },\n    },\n\n    [GraphEvents.ON_MESSAGE_DELTA]: {\n      handle: (\n        event: GraphEvents.ON_MESSAGE_DELTA,\n        data: t.StreamEventData\n      ): void => {\n        aggregateContent({ event, data: data as t.MessageDeltaEvent });\n        callbacks?.onMessageDelta?.(event, data);\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_DELTA]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeDeltaData,\n        });\n      },\n    },\n\n    [GraphEvents.ON_SUMMARIZE_COMPLETE]: {\n      handle: (event: string, data: t.StreamEventData): void => {\n        aggregateContent({\n          event: event as GraphEvents,\n          data: data as t.SummarizeCompleteEvent,\n        });\n      },\n    },\n  };\n\n  return {\n    contentParts,\n    aggregateContent,\n    handlers,\n  };\n}\n"],"mappings":";;;;;;;;AA6CA,SAAgB,eAAe,WAM7B;CAEA,MAAM,EAAE,cAAc,qBAAqBA,eAAAA,wBAAwB;CA+EnE,OAAO;EACL;EACA;EACA,UAAA;oBA9EwB,IAAIC,eAAAA,eAAe;0BACb,IAAIC,eAAAA,gBAAgB;6BACjB,IAAIC,eAAAA,uBAAuB;oBAEjC,EACzB,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAAkB,CAAC;IACnD,WAAW,YAAY,OAAO,IAAI;GACpC,EACF;8BAEqC,EACnC,SACE,OACA,SACS;IACT,iBAAiB;KACf;KACM;IACR,CAAC;IACD,WAAW,qBAAqB,OAAO,IAAI;GAC7C,EACF;0BAEiC,EAC/B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;2BAEkC,EAChC,SACE,OACA,SACS;IACT,WAAW,kBAAkB,OAAO,IAA4B;GAClE,EACF;yBAEgC,EAC9B,SACE,OACA,SACS;IACT,iBAAiB;KAAE;KAAa;IAA4B,CAAC;IAC7D,WAAW,iBAAiB,OAAO,IAAI;GACzC,EACF;2BAEkC,EAChC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;8BAEqC,EACnC,SAAS,OAAe,SAAkC;IACxD,iBAAiB;KACR;KACD;IACR,CAAC;GACH,EACF;EAMO;CACT;AACF"}

package/dist/esm/common/enum.mjs

@@ -14,6 +14,8 @@ let GraphEvents = /* @__PURE__ */ function(GraphEvents) {
 	GraphEvents["ON_RUN_STEP_DELTA"] = "on_run_step_delta";
 	/** [Custom] Completed event for run steps (tool calls) */
 	GraphEvents["ON_RUN_STEP_COMPLETED"] = "on_run_step_completed";
+	/** [Custom] Terminal signal for a run step: closed with status + timestamps */
+	GraphEvents["ON_RUN_STEP_CLOSED"] = "on_run_step_closed";
 	/** [Custom] Delta events for messages */
 	GraphEvents["ON_MESSAGE_DELTA"] = "on_message_delta";
 	/** [Custom] Reasoning Delta events for messages */

package/dist/esm/common/enum.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"enum.mjs","names":[],"sources":["../../../src/common/enum.ts"],"sourcesContent":["/**\n * Enum representing the various event types emitted during the execution of runnables.\n * These events provide real-time information about the progress and state of different components.\n *\n * @enum {string}\n */\nexport enum GraphEvents {\n  /* Custom Events */\n\n  /** [Custom] Agent update event in multi-agent graph/workflow */\n  ON_AGENT_UPDATE = 'on_agent_update',\n  /** [Custom] Delta event for run steps (message creation and tool calls) */\n  ON_RUN_STEP = 'on_run_step',\n  /** [Custom] Delta event for run steps (tool calls) */\n  ON_RUN_STEP_DELTA = 'on_run_step_delta',\n  /** [Custom] Completed event for run steps (tool calls) */\n  ON_RUN_STEP_COMPLETED = 'on_run_step_completed',\n  /** [Custom] Delta events for messages */\n  ON_MESSAGE_DELTA = 'on_message_delta',\n  /** [Custom] Reasoning Delta events for messages */\n  ON_REASONING_DELTA = 'on_reasoning_delta',\n  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */\n  ON_TOOL_EXECUTE = 'on_tool_execute',\n  /** [Custom] Emitted when the summarize node begins generating a summary */\n  ON_SUMMARIZE_START = 'on_summarize_start',\n  /** [Custom] Delta event carrying the completed summary content */\n  ON_SUMMARIZE_DELTA = 'on_summarize_delta',\n  /** [Custom] Emitted when the summarize node completes with the final summary */\n  ON_SUMMARIZE_COMPLETE = 'on_summarize_complete',\n  /** [Custom] Progress update from a running subagent (wraps child-graph events so hosts can display activity separately from parent). */\n  ON_SUBAGENT_UPDATE = 'on_subagent_update',\n  /** [Custom] Diagnostic logging event for context management observability */\n  ON_AGENT_LOG = 'on_agent_log',\n  /** [Custom] Per-model-call context window usage snapshot (post-prune token budget) */\n  ON_CONTEXT_USAGE = 'on_context_usage',\n\n  /* Official Events */\n\n  /** Custom event, emitted by system */\n  ON_CUSTOM_EVENT = 'on_custom_event',\n  /** Emitted when a chat model starts processing. */\n  CHAT_MODEL_START = 'on_chat_model_start',\n\n  /** Emitted when a chat model streams a chunk of its response. */\n  CHAT_MODEL_STREAM = 'on_chat_model_stream',\n\n  /** Emitted when a chat model completes its processing. */\n  CHAT_MODEL_END = 'on_chat_model_end',\n\n  /** Emitted when a language model starts processing. */\n  LLM_START = 'on_llm_start',\n\n  /** Emitted when a language model streams a chunk of its response. */\n  LLM_STREAM = 'on_llm_stream',\n\n  /** Emitted when a language model completes its processing. */\n  LLM_END = 'on_llm_end',\n\n  /** Emitted when a chain starts processing. */\n  CHAIN_START = 'on_chain_start',\n\n  /** Emitted when a chain streams a chunk of its output. */\n  CHAIN_STREAM = 'on_chain_stream',\n\n  /** Emitted when a chain completes its processing. */\n  CHAIN_END = 'on_chain_end',\n\n  /** Emitted when a tool starts its operation. */\n  TOOL_START = 'on_tool_start',\n\n  /** Emitted when a tool completes its operation. */\n  TOOL_END = 'on_tool_end',\n\n  /** Emitted when a retriever starts its operation. */\n  RETRIEVER_START = 'on_retriever_start',\n\n  /** Emitted when a retriever completes its operation. */\n  RETRIEVER_END = 'on_retriever_end',\n\n  /** Emitted when a prompt starts processing. */\n  PROMPT_START = 'on_prompt_start',\n\n  /** Emitted when a prompt completes its processing. */\n  PROMPT_END = 'on_prompt_end',\n}\n\nexport enum Providers {\n  OPENAI = 'openAI',\n  VERTEXAI = 'vertexai',\n  BEDROCK = 'bedrock',\n  ANTHROPIC = 'anthropic',\n  MISTRALAI = 'mistralai',\n  MISTRAL = 'mistral',\n  GOOGLE = 'google',\n  AZURE = 'azureOpenAI',\n  DEEPSEEK = 'deepseek',\n  OPENROUTER = 'openrouter',\n  XAI = 'xai',\n  MOONSHOT = 'moonshot',\n}\n\nexport enum GraphNodeKeys {\n  TOOLS = 'tools=',\n  AGENT = 'agent=',\n  SUMMARIZE = 'summarize=',\n  ROUTER = 'router',\n  PRE_TOOLS = 'pre_tools',\n  POST_TOOLS = 'post_tools',\n}\n\nexport enum GraphNodeActions {\n  TOOL_NODE = 'tool_node',\n  CALL_MODEL = 'call_model',\n  ROUTE_MESSAGE = 'route_message',\n}\n\nexport enum CommonEvents {\n  LANGGRAPH = 'LangGraph',\n}\n\nexport enum StepTypes {\n  TOOL_CALLS = 'tool_calls',\n  MESSAGE_CREATION = 'message_creation',\n}\n\nexport enum ContentTypes {\n  TEXT = 'text',\n  ERROR = 'error',\n  THINK = 'think',\n  TOOL_CALL = 'tool_call',\n  IMAGE_URL = 'image_url',\n  IMAGE_FILE = 'image_file',\n  /** Anthropic */\n  THINKING = 'thinking',\n  /** Vertex AI / Google Common */\n  REASONING = 'reasoning',\n  /** Multi-Agent Switch */\n  AGENT_UPDATE = 'agent_update',\n  /** Framework-level conversation summary block */\n  SUMMARY = 'summary',\n  /** Bedrock */\n  REASONING_CONTENT = 'reasoning_content',\n  /** Mid-run user steer persisted inline in an assistant message; replayed as a user turn */\n  STEER = 'steer',\n  /** Fast-model activity label for a tool/reasoning block; UI-only, never model input */\n  ACTIVITY_LABEL = 'activity_label',\n}\n\nexport enum ToolCallTypes {\n  FUNCTION = 'function',\n  RETRIEVAL = 'retrieval',\n  FILE_SEARCH = 'file_search',\n  CODE_INTERPRETER = 'code_interpreter',\n  /* Agents Tool Call */\n  TOOL_CALL = 'tool_call',\n}\n\nexport enum Callback {\n  TOOL_ERROR = 'handleToolError',\n  TOOL_START = 'handleToolStart',\n  TOOL_END = 'handleToolEnd',\n  CUSTOM_EVENT = 'handleCustomEvent',\n  /*\n  LLM_START = 'handleLLMStart',\n  LLM_NEW_TOKEN = 'handleLLMNewToken',\n  LLM_ERROR = 'handleLLMError',\n  LLM_END = 'handleLLMEnd',\n  CHAT_MODEL_START = 'handleChatModelStart',\n  CHAIN_START = 'handleChainStart',\n  CHAIN_ERROR = 'handleChainError',\n  CHAIN_END = 'handleChainEnd',\n  TEXT = 'handleText',\n  AGENT_ACTION = 'handleAgentAction',\n  AGENT_END = 'handleAgentEnd',\n  RETRIEVER_START = 'handleRetrieverStart',\n  RETRIEVER_END = 'handleRetrieverEnd',\n  RETRIEVER_ERROR = 'handleRetrieverError',\n  */\n}\n\nexport enum Constants {\n  OFFICIAL_CODE_BASEURL = 'https://api.librechat.ai/v1',\n  EXECUTE_CODE = 'execute_code',\n  TOOL_SEARCH = 'tool_search',\n  PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',\n  WEB_SEARCH = 'web_search',\n  CONTENT_AND_ARTIFACT = 'content_and_artifact',\n  LC_TRANSFER_TO_ = 'lc_transfer_to_',\n  HANDOFF_PARALLEL_BATCH = '__handoff_parallel_batch',\n  HANDOFF_GROUP_ID = '__handoff_group_id',\n  /** Delimiter for MCP tools: toolName_mcp_serverName */\n  MCP_DELIMITER = '_mcp_',\n  /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */\n  ANTHROPIC_SERVER_TOOL_PREFIX = 'srvtoolu_',\n  SKILL_TOOL = 'skill',\n  /**\n   * Callback-metadata keys stamped by `attemptInvoke` /\n   * `tryFallbackProviders` carrying the provider (SDK `Providers` enum\n   * value) and configured model that actually served a model invocation.\n   * Unlike `ls_provider` — which derived providers inherit from their base\n   * class (e.g. DeepSeek/OpenRouter report `'openai'`) — these reflect the\n   * SDK's own routing, including fallback-provider calls. Consumed by the\n   * subagent usage-capture handler to tag billing events.\n   */\n  INVOKED_PROVIDER = '__invoked_provider',\n  INVOKED_MODEL = '__invoked_model',\n  READ_FILE = 'read_file',\n  BASH_TOOL = 'bash_tool',\n  BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',\n  SUBAGENT = 'subagent',\n  /**\n   * Local-engine coding tool names. Promoted to `Constants.*` (rather\n   * than left as per-file `*ToolName` consts) so consumer UIs — most\n   * importantly LibreChat's `getToolIconType` map — can match against\n   * canonical strings instead of guessing. Existing matched names:\n   * `bash_tool`, `read_file`, `execute_code`, `run_tools_with_code`.\n   * The rest below are new and currently fall through to the generic\n   * tool icon; once LibreChat adds icons keyed on the same names, the\n   * wiring will work without an SDK change.\n   */\n  WRITE_FILE = 'write_file',\n  EDIT_FILE = 'edit_file',\n  GREP_SEARCH = 'grep_search',\n  GLOB_SEARCH = 'glob_search',\n  LIST_DIRECTORY = 'list_directory',\n  COMPILE_CHECK = 'compile_check',\n}\n\n/** Tool names that use the code execution environment (shared session, file tracking). */\nexport const CODE_EXECUTION_TOOLS: ReadonlySet<string> = new Set([\n  Constants.EXECUTE_CODE,\n  Constants.BASH_TOOL,\n  Constants.PROGRAMMATIC_TOOL_CALLING,\n  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,\n]);\n\n/**\n * Canonical names of the local-engine-specific coding tools — the\n * file/edit/search/typecheck surface that doesn't exist in the\n * remote (sandbox-API) engine. Single source of truth; the per-tool\n * factories, registry definitions, and `createWorkspacePolicyHook`\n * default extractors all key off these.\n *\n * `read_file` is on this list (the existing ReadFile tool is\n * remote-specific; the local engine's `read_file` is a parallel\n * implementation that shares the canonical name so consumer UIs\n * — most importantly LibreChat's `getToolIconType` — render both\n * with the same icon).\n */\nexport const LOCAL_CODING_TOOL_NAMES: readonly string[] = [\n  Constants.READ_FILE,\n  Constants.WRITE_FILE,\n  Constants.EDIT_FILE,\n  Constants.GREP_SEARCH,\n  Constants.GLOB_SEARCH,\n  Constants.LIST_DIRECTORY,\n  Constants.COMPILE_CHECK,\n];\n\n/**\n * Every tool name the local coding bundle (`createLocalCodingTools`)\n * exposes — the local-specific tools above plus the bash/code/PTC\n * pair that the local engine wraps around the existing factories.\n * Tests pin against this so any addition/removal in the bundle is\n * accompanied by a deliberate canonical-name update here.\n */\nexport const LOCAL_CODING_BUNDLE_NAMES: readonly string[] = [\n  ...LOCAL_CODING_TOOL_NAMES,\n  Constants.BASH_TOOL,\n  Constants.EXECUTE_CODE,\n  Constants.PROGRAMMATIC_TOOL_CALLING,\n  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,\n];\n\nexport enum TitleMethod {\n  STRUCTURED = 'structured',\n  FUNCTIONS = 'functions',\n  COMPLETION = 'completion',\n}\n\nexport enum EnvVar {\n  CODE_BASEURL = 'LIBRECHAT_CODE_BASEURL',\n  CODE_API_RUN_TIMEOUT_MS = 'CODE_API_RUN_TIMEOUT_MS',\n}\n"],"mappings":"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"}
+{"version":3,"file":"enum.mjs","names":[],"sources":["../../../src/common/enum.ts"],"sourcesContent":["/**\n * Enum representing the various event types emitted during the execution of runnables.\n * These events provide real-time information about the progress and state of different components.\n *\n * @enum {string}\n */\nexport enum GraphEvents {\n  /* Custom Events */\n\n  /** [Custom] Agent update event in multi-agent graph/workflow */\n  ON_AGENT_UPDATE = 'on_agent_update',\n  /** [Custom] Delta event for run steps (message creation and tool calls) */\n  ON_RUN_STEP = 'on_run_step',\n  /** [Custom] Delta event for run steps (tool calls) */\n  ON_RUN_STEP_DELTA = 'on_run_step_delta',\n  /** [Custom] Completed event for run steps (tool calls) */\n  ON_RUN_STEP_COMPLETED = 'on_run_step_completed',\n  /** [Custom] Terminal signal for a run step: closed with status + timestamps */\n  ON_RUN_STEP_CLOSED = 'on_run_step_closed',\n  /** [Custom] Delta events for messages */\n  ON_MESSAGE_DELTA = 'on_message_delta',\n  /** [Custom] Reasoning Delta events for messages */\n  ON_REASONING_DELTA = 'on_reasoning_delta',\n  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */\n  ON_TOOL_EXECUTE = 'on_tool_execute',\n  /** [Custom] Emitted when the summarize node begins generating a summary */\n  ON_SUMMARIZE_START = 'on_summarize_start',\n  /** [Custom] Delta event carrying the completed summary content */\n  ON_SUMMARIZE_DELTA = 'on_summarize_delta',\n  /** [Custom] Emitted when the summarize node completes with the final summary */\n  ON_SUMMARIZE_COMPLETE = 'on_summarize_complete',\n  /** [Custom] Progress update from a running subagent (wraps child-graph events so hosts can display activity separately from parent). */\n  ON_SUBAGENT_UPDATE = 'on_subagent_update',\n  /** [Custom] Diagnostic logging event for context management observability */\n  ON_AGENT_LOG = 'on_agent_log',\n  /** [Custom] Per-model-call context window usage snapshot (post-prune token budget) */\n  ON_CONTEXT_USAGE = 'on_context_usage',\n\n  /* Official Events */\n\n  /** Custom event, emitted by system */\n  ON_CUSTOM_EVENT = 'on_custom_event',\n  /** Emitted when a chat model starts processing. */\n  CHAT_MODEL_START = 'on_chat_model_start',\n\n  /** Emitted when a chat model streams a chunk of its response. */\n  CHAT_MODEL_STREAM = 'on_chat_model_stream',\n\n  /** Emitted when a chat model completes its processing. */\n  CHAT_MODEL_END = 'on_chat_model_end',\n\n  /** Emitted when a language model starts processing. */\n  LLM_START = 'on_llm_start',\n\n  /** Emitted when a language model streams a chunk of its response. */\n  LLM_STREAM = 'on_llm_stream',\n\n  /** Emitted when a language model completes its processing. */\n  LLM_END = 'on_llm_end',\n\n  /** Emitted when a chain starts processing. */\n  CHAIN_START = 'on_chain_start',\n\n  /** Emitted when a chain streams a chunk of its output. */\n  CHAIN_STREAM = 'on_chain_stream',\n\n  /** Emitted when a chain completes its processing. */\n  CHAIN_END = 'on_chain_end',\n\n  /** Emitted when a tool starts its operation. */\n  TOOL_START = 'on_tool_start',\n\n  /** Emitted when a tool completes its operation. */\n  TOOL_END = 'on_tool_end',\n\n  /** Emitted when a retriever starts its operation. */\n  RETRIEVER_START = 'on_retriever_start',\n\n  /** Emitted when a retriever completes its operation. */\n  RETRIEVER_END = 'on_retriever_end',\n\n  /** Emitted when a prompt starts processing. */\n  PROMPT_START = 'on_prompt_start',\n\n  /** Emitted when a prompt completes its processing. */\n  PROMPT_END = 'on_prompt_end',\n}\n\nexport enum Providers {\n  OPENAI = 'openAI',\n  VERTEXAI = 'vertexai',\n  BEDROCK = 'bedrock',\n  ANTHROPIC = 'anthropic',\n  MISTRALAI = 'mistralai',\n  MISTRAL = 'mistral',\n  GOOGLE = 'google',\n  AZURE = 'azureOpenAI',\n  DEEPSEEK = 'deepseek',\n  OPENROUTER = 'openrouter',\n  XAI = 'xai',\n  MOONSHOT = 'moonshot',\n}\n\nexport enum GraphNodeKeys {\n  TOOLS = 'tools=',\n  AGENT = 'agent=',\n  SUMMARIZE = 'summarize=',\n  ROUTER = 'router',\n  PRE_TOOLS = 'pre_tools',\n  POST_TOOLS = 'post_tools',\n}\n\nexport enum GraphNodeActions {\n  TOOL_NODE = 'tool_node',\n  CALL_MODEL = 'call_model',\n  ROUTE_MESSAGE = 'route_message',\n}\n\nexport enum CommonEvents {\n  LANGGRAPH = 'LangGraph',\n}\n\nexport enum StepTypes {\n  TOOL_CALLS = 'tool_calls',\n  MESSAGE_CREATION = 'message_creation',\n}\n\nexport enum ContentTypes {\n  TEXT = 'text',\n  ERROR = 'error',\n  THINK = 'think',\n  TOOL_CALL = 'tool_call',\n  IMAGE_URL = 'image_url',\n  IMAGE_FILE = 'image_file',\n  /** Anthropic */\n  THINKING = 'thinking',\n  /** Vertex AI / Google Common */\n  REASONING = 'reasoning',\n  /** Multi-Agent Switch */\n  AGENT_UPDATE = 'agent_update',\n  /** Framework-level conversation summary block */\n  SUMMARY = 'summary',\n  /** Bedrock */\n  REASONING_CONTENT = 'reasoning_content',\n  /** Mid-run user steer persisted inline in an assistant message; replayed as a user turn */\n  STEER = 'steer',\n  /** Fast-model activity label for a tool/reasoning block; UI-only, never model input */\n  ACTIVITY_LABEL = 'activity_label',\n}\n\nexport enum ToolCallTypes {\n  FUNCTION = 'function',\n  RETRIEVAL = 'retrieval',\n  FILE_SEARCH = 'file_search',\n  CODE_INTERPRETER = 'code_interpreter',\n  /* Agents Tool Call */\n  TOOL_CALL = 'tool_call',\n}\n\nexport enum Callback {\n  TOOL_ERROR = 'handleToolError',\n  TOOL_START = 'handleToolStart',\n  TOOL_END = 'handleToolEnd',\n  CUSTOM_EVENT = 'handleCustomEvent',\n  /*\n  LLM_START = 'handleLLMStart',\n  LLM_NEW_TOKEN = 'handleLLMNewToken',\n  LLM_ERROR = 'handleLLMError',\n  LLM_END = 'handleLLMEnd',\n  CHAT_MODEL_START = 'handleChatModelStart',\n  CHAIN_START = 'handleChainStart',\n  CHAIN_ERROR = 'handleChainError',\n  CHAIN_END = 'handleChainEnd',\n  TEXT = 'handleText',\n  AGENT_ACTION = 'handleAgentAction',\n  AGENT_END = 'handleAgentEnd',\n  RETRIEVER_START = 'handleRetrieverStart',\n  RETRIEVER_END = 'handleRetrieverEnd',\n  RETRIEVER_ERROR = 'handleRetrieverError',\n  */\n}\n\nexport enum Constants {\n  OFFICIAL_CODE_BASEURL = 'https://api.librechat.ai/v1',\n  EXECUTE_CODE = 'execute_code',\n  TOOL_SEARCH = 'tool_search',\n  PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',\n  WEB_SEARCH = 'web_search',\n  CONTENT_AND_ARTIFACT = 'content_and_artifact',\n  LC_TRANSFER_TO_ = 'lc_transfer_to_',\n  HANDOFF_PARALLEL_BATCH = '__handoff_parallel_batch',\n  HANDOFF_GROUP_ID = '__handoff_group_id',\n  /** Delimiter for MCP tools: toolName_mcp_serverName */\n  MCP_DELIMITER = '_mcp_',\n  /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */\n  ANTHROPIC_SERVER_TOOL_PREFIX = 'srvtoolu_',\n  SKILL_TOOL = 'skill',\n  /**\n   * Callback-metadata keys stamped by `attemptInvoke` /\n   * `tryFallbackProviders` carrying the provider (SDK `Providers` enum\n   * value) and configured model that actually served a model invocation.\n   * Unlike `ls_provider` — which derived providers inherit from their base\n   * class (e.g. DeepSeek/OpenRouter report `'openai'`) — these reflect the\n   * SDK's own routing, including fallback-provider calls. Consumed by the\n   * subagent usage-capture handler to tag billing events.\n   */\n  INVOKED_PROVIDER = '__invoked_provider',\n  INVOKED_MODEL = '__invoked_model',\n  READ_FILE = 'read_file',\n  BASH_TOOL = 'bash_tool',\n  BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',\n  SUBAGENT = 'subagent',\n  /**\n   * Local-engine coding tool names. Promoted to `Constants.*` (rather\n   * than left as per-file `*ToolName` consts) so consumer UIs — most\n   * importantly LibreChat's `getToolIconType` map — can match against\n   * canonical strings instead of guessing. Existing matched names:\n   * `bash_tool`, `read_file`, `execute_code`, `run_tools_with_code`.\n   * The rest below are new and currently fall through to the generic\n   * tool icon; once LibreChat adds icons keyed on the same names, the\n   * wiring will work without an SDK change.\n   */\n  WRITE_FILE = 'write_file',\n  EDIT_FILE = 'edit_file',\n  GREP_SEARCH = 'grep_search',\n  GLOB_SEARCH = 'glob_search',\n  LIST_DIRECTORY = 'list_directory',\n  COMPILE_CHECK = 'compile_check',\n}\n\n/** Tool names that use the code execution environment (shared session, file tracking). */\nexport const CODE_EXECUTION_TOOLS: ReadonlySet<string> = new Set([\n  Constants.EXECUTE_CODE,\n  Constants.BASH_TOOL,\n  Constants.PROGRAMMATIC_TOOL_CALLING,\n  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,\n]);\n\n/**\n * Canonical names of the local-engine-specific coding tools — the\n * file/edit/search/typecheck surface that doesn't exist in the\n * remote (sandbox-API) engine. Single source of truth; the per-tool\n * factories, registry definitions, and `createWorkspacePolicyHook`\n * default extractors all key off these.\n *\n * `read_file` is on this list (the existing ReadFile tool is\n * remote-specific; the local engine's `read_file` is a parallel\n * implementation that shares the canonical name so consumer UIs\n * — most importantly LibreChat's `getToolIconType` — render both\n * with the same icon).\n */\nexport const LOCAL_CODING_TOOL_NAMES: readonly string[] = [\n  Constants.READ_FILE,\n  Constants.WRITE_FILE,\n  Constants.EDIT_FILE,\n  Constants.GREP_SEARCH,\n  Constants.GLOB_SEARCH,\n  Constants.LIST_DIRECTORY,\n  Constants.COMPILE_CHECK,\n];\n\n/**\n * Every tool name the local coding bundle (`createLocalCodingTools`)\n * exposes — the local-specific tools above plus the bash/code/PTC\n * pair that the local engine wraps around the existing factories.\n * Tests pin against this so any addition/removal in the bundle is\n * accompanied by a deliberate canonical-name update here.\n */\nexport const LOCAL_CODING_BUNDLE_NAMES: readonly string[] = [\n  ...LOCAL_CODING_TOOL_NAMES,\n  Constants.BASH_TOOL,\n  Constants.EXECUTE_CODE,\n  Constants.PROGRAMMATIC_TOOL_CALLING,\n  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,\n];\n\nexport enum TitleMethod {\n  STRUCTURED = 'structured',\n  FUNCTIONS = 'functions',\n  COMPLETION = 'completion',\n}\n\nexport enum EnvVar {\n  CODE_BASEURL = 'LIBRECHAT_CODE_BASEURL',\n  CODE_API_RUN_TIMEOUT_MS = 'CODE_API_RUN_TIMEOUT_MS',\n}\n"],"mappings":"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"}

package/dist/esm/graphs/Graph.mjs

@@ -294,6 +294,17 @@ var Graph = class {
 	stepKeyIds = /* @__PURE__ */ new Map();
 	contentIndexMap = /* @__PURE__ */ new Map();
 	toolCallStepIds = /* @__PURE__ */ new Map();
+	/** Step ID -> tool call IDs whose completions have not yet arrived. */
+	pendingToolCallsByStep = /* @__PURE__ */ new Map();
+	/**
+	* Step ID -> latest producer completion time seen for that step. Parallel
+	* calls sharing a step can settle out of producer order when their host
+	* handlers differ in latency, so the call that happens to drain the set is
+	* not necessarily the one that finished last.
+	*/
+	latestCompletionByStep = /* @__PURE__ */ new Map();
+	/** Agent key ('' for single-agent) -> currently open MESSAGE_CREATION step ID. */
+	openMessageStepByAgent = /* @__PURE__ */ new Map();
 	/**
 	* Step IDs dispatched through the handler registry during this run.
 	* Event echo suppression is tracked separately so repeated deltas for
@@ -407,6 +418,9 @@ var Graph = class {
 		this.contentIndexMap = /* @__PURE__ */ new Map();
 		this.stepKeyIds = /* @__PURE__ */ new Map();
 		this.toolCallStepIds.clear();
+		this.pendingToolCallsByStep.clear();
+		this.latestCompletionByStep.clear();
+		this.openMessageStepByAgent.clear();
 		this.messageIdsByStepKey = /* @__PURE__ */ new Map();
 		this.messageStepHasTextDeltas = /* @__PURE__ */ new Set();
 		this.reasoningStepHasDeltas = /* @__PURE__ */ new Set();
@@ -454,6 +468,26 @@ var Graph = class {
 		this.eagerEventToolUsageCount.clear();
 		for (const usageCount of this.eagerEventToolUsageCountsByAgentId.values()) usageCount.clear();
 	}
+	/**
+	* Tracks a tool call whose completion must arrive before its step can be
+	* considered finished. Registered wherever `toolCallStepIds` gains entries,
+	* except cross-process subagent resume restoration, where pending state
+	* cannot be faithfully rebuilt and closes fall back to completions/sweep.
+	*/
+	registerPendingToolCall(toolCallId, stepId) {
+		if (!toolCallId || !stepId) return;
+		this.getPendingToolCallSet(stepId).add(toolCallId);
+	}
+	/** Lazily creates a step's pending-completions set; callers registering a
+	*  batch hoist this lookup out of their per-call loop. */
+	getPendingToolCallSet(stepId) {
+		let pending = this.pendingToolCallsByStep.get(stepId);
+		if (!pending) {
+			pending = /* @__PURE__ */ new Set();
+			this.pendingToolCallsByStep.set(stepId, pending);
+		}
+		return pending;
+	}
 	markHandlerDispatchedEvent(eventName, stepId) {
 		const key = getHandlerDispatchedEventKey(eventName, stepId);
 		this.handlerDispatchedEventCounts.set(key, (this.handlerDispatchedEventCounts.get(key) ?? 0) + 1);
@@ -803,6 +837,9 @@ var StandardGraph = class StandardGraph extends Graph {
 		* a stale reference on 2nd+ processStream calls.
 		*/
 		this.toolCallStepIds.clear();
+		this.pendingToolCallsByStep.clear();
+		this.latestCompletionByStep.clear();
+		this.openMessageStepByAgent.clear();
 		this.runProducedAiMessageIds.clear();
 		this.eagerEventToolExecutions.clear();
 		this.clearEagerEventToolUsageCounts();
@@ -971,6 +1008,196 @@ var StandardGraph = class StandardGraph extends Graph {
 		const index = this.contentIndexMap.get(stepId);
 		if (index !== void 0) return this.contentData[index];
 	}
+	/**
+	* Derives the same lane key `dispatchRunStep` stamps as `runStep.agentId`.
+	* The multi-agent check gates the lookup because `getAgentContext` signals
+	* a miss by throwing: single-agent graphs key every step under `''`, so
+	* resolving the context could only ever produce a thrown-and-discarded
+	* Error on a per-model-call path.
+	*/
+	getStepAgentKey(metadata) {
+		if (!metadata || !this.isMultiAgentGraph()) return "";
+		try {
+			const agentContext = this.getAgentContext(metadata);
+			if (agentContext.agentId) return agentContext.agentId;
+		} catch (_e) {}
+		return "";
+	}
+	/**
+	* O(1) reverse lookup: both dispatch funnels key the open-message map by
+	* `runStep.agentId ?? ''`, so the entry is addressable without scanning.
+	*/
+	untrackRunStep(runStep) {
+		this.pendingToolCallsByStep.delete(runStep.id);
+		this.latestCompletionByStep.delete(runStep.id);
+		const agentKey = runStep.agentId ?? "";
+		if (this.openMessageStepByAgent.get(agentKey) === runStep.id) this.openMessageStepByAgent.delete(agentKey);
+	}
+	/**
+	* Shared step accounting for both dispatch funnels: a successor step in
+	* the same agent lane marks the previous message step as finished — its
+	* CLOSED event must precede the successor's ON_RUN_STEP so hosts observe
+	* a consistent open-step timeline — then the step is registered in the
+	* content maps and tracked as the lane's open message step when
+	* applicable.
+	*/
+	async trackDispatchedRunStep(runStep, metadata, trackAsOpenMessageStep = true) {
+		const agentKey = runStep.agentId ?? "";
+		const openMessageStepId = this.openMessageStepByAgent.get(agentKey);
+		/**
+		* Reserve the content index and register the step SYNCHRONOUSLY, before
+		* awaiting the predecessor's closure. Parallel agent lanes dispatch
+		* successors concurrently: if both yielded here first, they would push
+		* with the same `contentData.length` and `contentIndexMap` would resolve
+		* one step id to the other lane's entry, so later deltas and completions
+		* would mutate the wrong agent's step. Assigning the index at push time
+		* also supersedes whatever the caller computed before this await point.
+		*/
+		runStep.index = this.contentData.length;
+		this.contentData.push(runStep);
+		this.contentIndexMap.set(runStep.id, runStep.index);
+		if (trackAsOpenMessageStep && runStep.type === "message_creation") this.openMessageStepByAgent.set(agentKey, runStep.id);
+		else this.openMessageStepByAgent.delete(agentKey);
+		/**
+		* Awaited after registration but before the caller dispatches this step's
+		* ON_RUN_STEP, so the predecessor's CLOSED event still precedes the
+		* successor's start event.
+		*/
+		if (openMessageStepId != null && openMessageStepId !== runStep.id)
+ /**
+		* Isolated: this step is already registered in `contentData`, so a
+		* predecessor delivery failure rejecting here would abort the caller
+		* before it publishes this step's ON_RUN_STEP — leaving the sweep to
+		* emit a terminal event for a step that never announced a start.
+		*/
+		try {
+			await this.closeRunStep(openMessageStepId, "completed", { metadata });
+		} catch (_e) {}
+		/**
+		* Stamped last, after the predecessor's closure has been delivered and
+		* immediately before the caller publishes this step's ON_RUN_STEP.
+		* `created_at` documents when the step was dispatched, so it must not
+		* absorb the latency of an arbitrarily slow predecessor handler.
+		*/
+		runStep.created_at = Date.now();
+	}
+	/**
+	* Closes a run step: stamps its terminal status + timestamp on the stored
+	* `RunStep` and emits `ON_RUN_STEP_CLOSED`. First close wins — later calls
+	* are no-ops — except a `restamp` close, which lets a `completed`
+	* TOOL_CALLS step refresh `completed_at` when a late-registered parallel
+	* tool call finishes after the step already closed (the eager-execution
+	* race). `cancelled`/`failed` are immutable once stamped.
+	*/
+	async closeRunStep(stepId, status, options) {
+		if (!stepId) return false;
+		const runStep = this.getRunStep(stepId);
+		if (!runStep) return false;
+		if (runStep.status != null && runStep.status !== "in_progress") {
+			this.untrackRunStep(runStep);
+			return false;
+		}
+		const closedAt = options?.at ?? Date.now();
+		runStep.status = status;
+		if (status === "completed") runStep.completed_at = closedAt;
+		else if (status === "cancelled") runStep.cancelled_at = closedAt;
+		else runStep.failed_at = closedAt;
+		const closedEvent = {
+			id: stepId,
+			index: runStep.index,
+			type: runStep.type,
+			status,
+			closed_at: closedAt
+		};
+		if (runStep.created_at != null) closedEvent.created_at = runStep.created_at;
+		if (runStep.runId != null) closedEvent.runId = runStep.runId;
+		if (runStep.agentId != null) closedEvent.agentId = runStep.agentId;
+		if (runStep.groupId != null) closedEvent.groupId = runStep.groupId;
+		if (runStep.stepIndex != null) closedEvent.stepIndex = runStep.stepIndex;
+		this.untrackRunStep(runStep);
+		const handler = this.handlerRegistry?.getHandler("on_run_step_closed");
+		if (handler) {
+			await handler.handle("on_run_step_closed", closedEvent, options?.metadata, this);
+			this.handlerDispatchedStepIds.add(stepId);
+		}
+		const unmarkHandlerDispatchedEvent = handler ? this.markHandlerDispatchedEvent("on_run_step_closed", stepId) : void 0;
+		try {
+			if (this.config) await safeDispatchCustomEvent("on_run_step_closed", closedEvent, this.config);
+		} finally {
+			unmarkHandlerDispatchedEvent?.();
+		}
+		return true;
+	}
+	/**
+	* Observes one `ON_RUN_STEP_COMPLETED` for a step and closes the step when
+	* no registered tool calls remain pending. Steps without pending tracking
+	* (summaries, cross-process resume) close on their first completion; the
+	* terminal-status guard in `closeRunStep` absorbs duplicate echoes.
+	*/
+	async recordStepCompletion(stepId, options) {
+		if (!stepId) return;
+		const { toolCallId, metadata, at } = options ?? {};
+		if (at != null) {
+			const latest = this.latestCompletionByStep.get(stepId);
+			if (latest == null || at > latest) this.latestCompletionByStep.set(stepId, at);
+		}
+		const closeAt = this.latestCompletionByStep.get(stepId) ?? at;
+		const pending = this.pendingToolCallsByStep.get(stepId);
+		if (pending == null) {
+			await this.closeRunStep(stepId, "completed", {
+				metadata,
+				at: closeAt
+			});
+			return;
+		}
+		if (toolCallId != null && toolCallId !== "") pending.delete(toolCallId);
+		if (pending.size > 0) return;
+		await this.closeRunStep(stepId, "completed", {
+			metadata,
+			at: closeAt
+		});
+	}
+	/**
+	* Closes the tracked open MESSAGE_CREATION step for the event's agent lane.
+	* Fires on every model end, so the empty-map check short-circuits ahead of
+	* resolving the lane key — a turn whose message step already closed through
+	* successor-close does no work here.
+	*/
+	async closeOpenMessageStep(metadata, at) {
+		if (this.openMessageStepByAgent.size === 0) return;
+		const agentKey = this.getStepAgentKey(metadata);
+		const openStepId = this.openMessageStepByAgent.get(agentKey);
+		if (openStepId == null) return;
+		await this.closeRunStep(openStepId, "completed", {
+			metadata,
+			at
+		});
+	}
+	/**
+	* End-of-run sweep: closes every step that never reached a terminal
+	* status. Dual-dispatches like any other close — the custom-event channel
+	* is usually already torn down here and `safeDispatchCustomEvent` reports
+	* that quietly, but callback-only subscribers still receive the terminal
+	* signal whenever it is alive.
+	*/
+	async closeUnfinishedRunSteps(status, at) {
+		const closedAt = at ?? Date.now();
+		for (const runStep of this.contentData) {
+			if (runStep.status != null && runStep.status !== "in_progress") continue;
+			/**
+			* Isolated per step: one host handler throwing must not strand the
+			* remaining steps `in_progress` with no terminal event. The step is
+			* stamped before dispatch either way, so a thrown handler still leaves
+			* consistent state behind.
+			*/
+			try {
+				await this.closeRunStep(runStep.id, status, { at: closedAt });
+			} catch (_e) {}
+		}
+		this.pendingToolCallsByStep.clear();
+		this.latestCompletionByStep.clear();
+		this.openMessageStepByAgent.clear();
+	}
 	getAgentContext(metadata) {
 		if (!metadata) throw new Error("No metadata provided to retrieve agent context");
 		const currentNode = metadata.langgraph_node;
@@ -2644,8 +2871,8 @@ var StandardGraph = class StandardGraph extends Graph {
 						const groupId = this.resolveParallelGroupId(runStep.agentId, resolvedConfig?.metadata);
 						if (groupId != null) runStep.groupId = groupId;
 					}
-					this.contentData.push(runStep);
-					this.contentIndexMap.set(runStep.id, runStep.index);
+					runStep.status ??= "in_progress";
+					await this.trackDispatchedRunStep(runStep, resolvedConfig?.metadata, false);
 					const handler = this.handlerRegistry?.getHandler("on_run_step");
 					if (handler) {
 						await handler.handle("on_run_step", runStep, resolvedConfig?.configurable, this);
@@ -2658,15 +2885,24 @@ var StandardGraph = class StandardGraph extends Graph {
 						unmarkHandlerDispatchedEvent?.();
 					}
 				},
+				closeRunStep: async (stepId, status, nodeConfig) => {
+					await this.closeRunStep(stepId, status, { metadata: (nodeConfig ?? this.config)?.metadata });
+				},
 				dispatchRunStepCompleted: async (stepId, result, nodeConfig) => {
 					const resolvedConfig = nodeConfig ?? this.config;
-					const runStep = this.contentData.find((s) => s.id === stepId);
+					const completedAt = Date.now();
+					const runStep = this.getRunStep(stepId);
 					const handler = this.handlerRegistry?.getHandler("on_run_step_completed");
 					if (handler) await handler.handle("on_run_step_completed", { result: {
 						...result,
 						id: stepId,
-						index: runStep?.index ?? 0
+						index: runStep?.index ?? 0,
+						completed_at: completedAt
 					} }, resolvedConfig?.configurable, this);
+					await this.recordStepCompletion(stepId, {
+						metadata: resolvedConfig?.metadata,
+						at: completedAt
+					});
 				}
 			},
 			generateStepId: (stepKey) => this.generateStepId(stepKey)
@@ -2714,10 +2950,15 @@ var StandardGraph = class StandardGraph extends Graph {
 	async dispatchRunStep(stepKey, stepDetails, metadata) {
 		if (!this.config) throw new Error("No config provided");
 		const [stepId, stepIndex] = this.generateStepId(stepKey);
-		if (stepDetails.type === "tool_calls" && stepDetails.tool_calls) for (const tool_call of stepDetails.tool_calls) {
-			const toolCallId = tool_call.id ?? "";
-			if (!toolCallId || this.toolCallStepIds.has(toolCallId)) continue;
-			this.toolCallStepIds.set(toolCallId, stepId);
+		if (stepDetails.type === "tool_calls" && stepDetails.tool_calls) {
+			let pendingToolCalls;
+			for (const tool_call of stepDetails.tool_calls) {
+				const toolCallId = tool_call.id ?? "";
+				if (!toolCallId || this.toolCallStepIds.has(toolCallId)) continue;
+				this.toolCallStepIds.set(toolCallId, stepId);
+				pendingToolCalls ??= this.getPendingToolCallSet(stepId);
+				pendingToolCalls.add(toolCallId);
+			}
 		}
 		const runStep = {
 			stepIndex,
@@ -2725,20 +2966,26 @@ var StandardGraph = class StandardGraph extends Graph {
 			type: stepDetails.type,
 			index: this.contentData.length,
 			stepDetails,
-			usage: null
+			usage: null,
+			status: "in_progress"
 		};
 		const runId = this.runId ?? "";
 		if (runId) runStep.runId = runId;
-		if (metadata) try {
+		/**
+		* `agentId`/`groupId` are multi-agent-only, and `getAgentContext` signals a
+		* miss by throwing — so for a single-agent graph the lookup could only ever
+		* build and discard an Error while producing the same undefined fields.
+		* The constant-time check gates it out of the per-step dispatch path.
+		*/
+		if (metadata && this.isMultiAgentGraph()) try {
 			const agentContext = this.getAgentContext(metadata);
-			if (this.isMultiAgentGraph() && agentContext.agentId) {
+			if (agentContext.agentId) {
 				runStep.agentId = agentContext.agentId;
 				const groupId = this.resolveParallelGroupId(agentContext.agentId, metadata);
 				if (groupId != null) runStep.groupId = groupId;
 			}
 		} catch (_e) {}
-		this.contentData.push(runStep);
-		this.contentIndexMap.set(stepId, runStep.index);
+		await this.trackDispatchedRunStep(runStep, metadata);
 		const handler = this.handlerRegistry?.getHandler("on_run_step");
 		if (handler) {
 			await handler.handle("on_run_step", runStep, metadata, this);
@@ -2779,6 +3026,7 @@ var StandardGraph = class StandardGraph extends Graph {
 		const errorDetail = error?.message != null ? `: ${serializeToolContentBounded(error.message, Math.max(0, eventValueLimit - 21 - 2))}` : "";
 		const runStep = graph.getRunStep(stepId);
 		if (!runStep) return false;
+		const completedAt = Date.now();
 		const tool_call = {
 			id: data.id,
 			name: name || "",
@@ -2792,8 +3040,14 @@ var StandardGraph = class StandardGraph extends Graph {
 			id: stepId,
 			index: runStep.index,
 			type: "tool_call",
-			tool_call
+			tool_call,
+			completed_at: completedAt
 		} }, metadata, graph);
+		await graph.recordStepCompletion(stepId, {
+			toolCallId: data.id,
+			metadata,
+			at: completedAt
+		});
 		return true;
 	}
 	/**