@librechat/agents 3.4.4 → 3.4.6

package/dist/esm/types/hitl.mjs

@@ -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
+export { isAskUserQuestionInterrupt };
+
+//# sourceMappingURL=hitl.mjs.map

package/dist/esm/types/hitl.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.mjs","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/esm/utils/handlers.mjs

@@ -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/esm/utils/handlers.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.mjs","names":[],"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,qBAAqB,wBAAwB;CAsEnE,OAAO;EACL;EACA;EACA,UAAA;oBArEwB,IAAI,eAAe;0BACb,IAAI,gBAAgB;6BACjB,IAAI,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.mjs","names":[],"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,qBAAqB,wBAAwB;CA+EnE,OAAO;EACL;EACA;EACA,UAAA;oBA9EwB,IAAI,eAAe;0BACb,IAAI,gBAAgB;6BACjB,IAAI,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/types/common/enum.d.ts

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

package/dist/types/graphs/Graph.d.ts

@@ -45,6 +45,17 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     stepKeyIds: Map<string, string[]>;
     contentIndexMap: Map<string, number>;
     toolCallStepIds: Map<string, string>;
+    /** Step ID -> tool call IDs whose completions have not yet arrived. */
+    pendingToolCallsByStep: Map<string, Set<string>>;
+    /**
+     * 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: Map<string, number>;
+    /** Agent key ('' for single-agent) -> currently open MESSAGE_CREATION step ID. */
+    openMessageStepByAgent: Map<string, string>;
     /**
      * Step IDs dispatched through the handler registry during this run.
      * Event echo suppression is tracked separately so repeated deltas for
@@ -153,6 +164,16 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     clearHeavyState(): void;
     getEagerEventToolUsageCount(agentId?: string): Map<string, number>;
     protected clearEagerEventToolUsageCounts(): void;
+    /**
+     * 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: string, stepId: string): void;
+    /** Lazily creates a step's pending-completions set; callers registering a
+     *  batch hoist this lookup out of their per-call loop. */
+    protected getPendingToolCallSet(stepId: string): Set<string>;
     markHandlerDispatchedEvent(eventName: string, stepId: string): () => void;
     hasHandlerDispatchedEvent(eventName: string, stepId: string): boolean;
     /**
@@ -415,6 +436,72 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     releasePreemptSeal(): void;
     getPreemptStats(): t.PreemptStats;
     getRunStep(stepId: string): t.RunStep | undefined;
+    /**
+     * 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.
+     */
+    protected getStepAgentKey(metadata?: Record<string, unknown>): string;
+    /**
+     * O(1) reverse lookup: both dispatch funnels key the open-message map by
+     * `runStep.agentId ?? ''`, so the entry is addressable without scanning.
+     */
+    private untrackRunStep;
+    /**
+     * 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.
+     */
+    protected trackDispatchedRunStep(runStep: t.RunStep, metadata?: Record<string, unknown>, 
+    /**
+     * Summarization steps are typed MESSAGE_CREATION but own an explicit
+     * completion, and their model call emits `CHAT_MODEL_END` well before the
+     * summary is assembled. Tracking one as the lane's open step would let
+     * model-end publish an authoritative `completed` closure early — the
+     * measured duration would exclude the remaining work and a later
+     * post-model failure could no longer change the status. They close
+     * through `recordStepCompletion` instead.
+     */
+    trackAsOpenMessageStep?: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    closeRunStep(stepId: string, status: Exclude<t.RunStepStatus, 'in_progress'>, options?: t.RunStepCloseOptions): Promise<boolean>;
+    /**
+     * 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.
+     */
+    recordStepCompletion(stepId: string, options?: t.RecordStepCompletionOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    closeOpenMessageStep(metadata?: Record<string, unknown>, 
+    /** Model-end time captured before host handlers ran, so a slow usage sink
+     *  cannot inflate the step's measured duration. */
+    at?: number): Promise<void>;
+    /**
+     * 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.
+     */
+    closeUnfinishedRunSteps(status: Exclude<t.RunStepStatus, 'in_progress'>, at?: number): Promise<void>;
     getAgentContext(metadata: Record<string, unknown> | undefined): AgentContext;
     getStepBaseKey(metadata: Record<string, unknown> | undefined): string;
     getStepKey(metadata: Record<string, unknown> | undefined): string;

package/dist/types/hitl/askUserQuestions.d.ts

@@ -0,0 +1,24 @@
+import type { AskUserQuestionsRequest, AskUserQuestionsResolution } from '@/types/hitl';
+/**
+ * Suspend once to collect answers to several related questions. The first
+ * question is also included in the legacy `question` field so existing hosts
+ * can render a useful fallback during a staged rollout.
+ *
+ * Question ids must be non-empty and unique within the batch. The helper
+ * accepts at most four questions so hosts can render the interaction as one
+ * focused decision surface rather than an unbounded form.
+ *
+ * @example
+ * ```ts
+ * const { answers } = askUserQuestions({
+ *   questions: [
+ *     { id: 'environment', question: 'Which environment?' },
+ *     { id: 'region', question: 'Which region?' },
+ *   ],
+ * });
+ * return `Deploy to ${answers.environment} in ${answers.region}`;
+ * ```
+ */
+export declare function askUserQuestions(request: AskUserQuestionsRequest, options?: {
+    toolCallId?: string;
+}): AskUserQuestionsResolution;

package/dist/types/hitl/askUserQuestionsInterrupt.d.ts

@@ -0,0 +1,11 @@
+import type { AskUserQuestionRequest, AskUserQuestionsInterruptPayload } from '@/types/hitl';
+/** Maximum questions supported by one batched clarification interaction. */
+export declare const MAX_ASK_USER_QUESTIONS = 4;
+/** Safe identifier format for answer-map keys in a batched question. */
+export declare const ASK_USER_QUESTION_ID_PATTERN: RegExp;
+export declare function isAskUserQuestionRequest(value: unknown): value is AskUserQuestionRequest;
+/**
+ * Type guard for the batched form of an `ask_user_question` interrupt. Hosts
+ * use this to select the multi-question UI and `AskUserQuestionsResolution`.
+ */
+export declare function isAskUserQuestionsInterrupt(payload: unknown): payload is AskUserQuestionsInterruptPayload;

package/dist/types/hitl/index.d.ts

@@ -4,3 +4,5 @@
  * `askUserQuestion()`) live here.
  */
 export { askUserQuestion } from './askUserQuestion';
+export { askUserQuestions } from './askUserQuestions';
+export { ASK_USER_QUESTION_ID_PATTERN, isAskUserQuestionsInterrupt, MAX_ASK_USER_QUESTIONS, } from './askUserQuestionsInterrupt';

package/dist/types/langfuseTraceShaping.d.ts

@@ -20,8 +20,9 @@ export declare function shouldDropLangfuseSpan(spanName: string): boolean;
  * - Agent nodes become `agent` observations, while tool-dispatch nodes become
  *   stable `chain` observations whose input is scoped to the pending calls.
  *   Individual child calls remain `tool` observations (items 3 & 4).
- * - Agent trace roots become `agent` observations and title trace roots become
- *   `chain` observations. Root and trace input/output are reduced to the user
- *   question and assistant response when chat messages are available (item 2).
+ * - Agent trace roots become `agent` observations, while title and activity
+ *   summary roots become `chain` observations. Root and trace input/output are
+ *   reduced to the user question and assistant response when chat messages are
+ *   available (item 2).
  */
 export declare function shapeLangfuseSpan(span: ReadableSpan): void;

package/dist/types/run.d.ts

@@ -138,6 +138,14 @@ export declare class Run<_T extends t.BaseGraphState> {
     private createCustomEventCallback;
     private shouldClearHookSession;
     private isAwaitingResume;
+    /**
+     * Terminal status for steps still open at end-of-run: `cancelled` for
+     * intentional stops (caller abort, hook halt), `failed` for unexpected
+     * stream errors, `completed` for a natural finish. Reads `_haltedReason`
+     * behind a method boundary on purpose — it is assigned inside the
+     * `consumeStream` closure, which control-flow narrowing cannot see.
+     */
+    private resolveSweepStatus;
     private getStreamLangfuseConfig;
     private getStreamToolOutputTracingLangfuseConfig;
     processStream(inputs: t.IState | Command, callerConfig: t.RunStreamConfig, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;
@@ -247,7 +255,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     }>;
     /**
      * Generates one parent summary for two or more logical activities. The
-     * summary model is traced as a dedicated activity-phase agent root in the
+     * summary model is traced as a dedicated activity-phase chain root in the
      * conversation session, with the model callback recorded as its generation
      * child. No session id means no phase trace, avoiding orphan observations.
      */

package/dist/types/session/types.d.ts

@@ -150,7 +150,7 @@ export interface AgentSessionRunOptions {
     streamOptions?: t.EventStreamOptions;
 }
 export interface AgentSessionStreamEvent {
-    type: 'run.started' | 'message.delta' | 'reasoning.delta' | 'tool.started' | 'tool.delta' | 'tool.completed' | 'usage.updated' | 'run.completed' | 'run.failed' | 'run.interrupted' | 'run.halted';
+    type: 'run.started' | 'message.delta' | 'reasoning.delta' | 'tool.started' | 'tool.delta' | 'tool.completed' | 'step.finished' | 'usage.updated' | 'run.completed' | 'run.failed' | 'run.interrupted' | 'run.halted';
     sequence: number;
     runId: string;
     threadId: string;

package/dist/types/summarization/node.d.ts

@@ -21,6 +21,12 @@ interface CreateSummarizeNodeParams {
         hookRegistry?: HookRegistry;
         dispatchRunStep: (runStep: t.RunStep, config?: RunnableConfig) => Promise<void>;
         dispatchRunStepCompleted: (stepId: string, result: t.StepCompleted, config?: RunnableConfig) => Promise<void>;
+        /**
+         * Terminal close for a summary step that ends without a completion —
+         * an errored or empty summary would otherwise stay `in_progress` until
+         * the run-end sweep reported it as `completed`.
+         */
+        closeRunStep?: (stepId: string, status: Exclude<t.RunStepStatus, 'in_progress'>, config?: RunnableConfig) => Promise<void>;
         /** The run's shared breaker signal, composed into every summarization
          * model attempt so a sibling branch tripping a stream limit also
          * cancels in-flight summaries. */

package/dist/types/types/graph.d.ts

@@ -5,8 +5,8 @@ import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
+import type { RunStep, RunStepDeltaEvent, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
-import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
@@ -73,7 +73,7 @@ export interface ContextUsageEvent {
     calibrationRatio?: number;
 }
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
+    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -442,7 +442,7 @@ export type ExecutableSubagentConfig = ResolvedSubagentConfig | LazySingleAgentS
 /** Graph-aware config accepted by the executor. Graph configs stay eager. */
 export type ExecutableSubagentConfigEntry = ExecutableSubagentConfig | GraphSubagentConfig;
 /** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
-export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
 export interface SubagentAncestryEntry {
     readonly subagentRunId: string;
     readonly subagentType: string;

package/dist/types/types/hitl.d.ts

@@ -157,15 +157,35 @@ export interface AskUserQuestionRequest {
      */
     multiSelect?: boolean;
 }
+/** One independently answerable question in a batched question request. */
+export interface AskUserQuestionBatchItem extends AskUserQuestionRequest {
+    /** Batch-unique identifier (`[A-Za-z][A-Za-z0-9_-]{0,63}`). */
+    id: string;
+    /** Optional short heading rendered above the question. */
+    header?: string;
+}
+/** Input shape for one tool call that asks one to four questions together. */
+export interface AskUserQuestionsRequest {
+    questions: AskUserQuestionBatchItem[];
+}
 /**
  * Structured payload the SDK passes to `interrupt()` when an agent (or
  * a custom node) needs to ask the user a clarifying question. Mirrors
- * Claude Code's `AskUserQuestion` semantic. Resume value:
- * `AskUserQuestionResolution`.
+ * Claude Code's `AskUserQuestion` semantic. Resume value is
+ * `AskUserQuestionResolution` for a single question, or
+ * `AskUserQuestionsResolution` when `questions` is present.
  */
 export interface AskUserQuestionInterruptPayload {
     type: 'ask_user_question';
+    /**
+     * Single-question request, or the first question as a compatibility
+     * fallback when `questions` contains a batch. This lets existing hosts show
+     * a useful preview during a staged rollout, but they must support `questions`
+     * and `AskUserQuestionsResolution` before enabling a batched tool schema.
+     */
     question: AskUserQuestionRequest;
+    /** One to four questions collected by one `ask_user_question` tool call. */
+    questions?: AskUserQuestionsRequest['questions'];
     /**
      * The `tool_call_id` of the ask-tool call that raised this interrupt,
      * when the tool body supplied it (see `askUserQuestion`'s `options`).
@@ -175,6 +195,10 @@ export interface AskUserQuestionInterruptPayload {
      */
     tool_call_id?: string;
 }
+/** Batch-specialized ask payload for hosts that render several questions. */
+export interface AskUserQuestionsInterruptPayload extends AskUserQuestionInterruptPayload {
+    questions: AskUserQuestionsRequest['questions'];
+}
 /**
  * Discriminated union of every interrupt payload the SDK raises. New
  * variants can be added without breaking existing handlers as long as
@@ -194,6 +218,11 @@ export interface AskUserQuestionResolution {
      */
     answer: string;
 }
+/** Resume value for a batched `ask_user_question` interrupt. */
+export interface AskUserQuestionsResolution {
+    /** Human answers keyed by each `AskUserQuestionBatchItem.id`. */
+    answers: Record<string, string>;
+}
 /**
  * Type guard narrowing an arbitrary value to a `ToolApprovalInterruptPayload`.
  * Accepts `unknown` (not just `HumanInterruptPayload`) because hosts can

package/dist/types/types/stream.d.ts

@@ -2,6 +2,7 @@ import type { MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessa
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { Command } from '@langchain/langgraph';
+import type Anthropic from '@anthropic-ai/sdk';
 import type { AnthropicContentBlock } from '@/llm/anthropic/types';
 import type { AssistantTextPhase } from '@/types/assistantPhase';
 import type { SummarizeCompleteEvent } from '@/types/summarize';
@@ -34,8 +35,25 @@ start, stream and end are associated with slightly different data payload.
 
 Please see the documentation for EventData for more details. */
 export type EventName = string;
+export type RunStepStatus = 'in_progress' | 'completed' | 'cancelled' | 'failed';
 export type RunStep = {
     type: StepTypes;
+    /** Epoch ms when the step was dispatched. */
+    created_at?: number;
+    /**
+     * Lifecycle status; terminal values are stamped when the step closes.
+     * Invariant (enforced by `closeRunStep`, not the type, to stay wire-compatible
+     * with the OpenAI Assistants shape): a terminal status sets exactly one
+     * matching `*_at` field; first close wins and `cancelled`/`failed` are
+     * immutable once stamped.
+     */
+    status?: RunStepStatus;
+    /** Epoch ms when the step closed with status `completed`. */
+    completed_at?: number;
+    /** Epoch ms when the step closed with status `cancelled` (abort/halt). */
+    cancelled_at?: number;
+    /** Epoch ms when the step closed with status `failed`. */
+    failed_at?: number;
     id: string;
     runId?: string;
     agentId?: string;
@@ -71,6 +89,41 @@ export interface RunStepDeltaEvent {
      */
     delta: ToolCallDelta;
 }
+/**
+ * Terminal signal for a run step, emitted exactly once per step when it
+ * finishes (`completed`), is aborted/halted (`cancelled`), or the run errors
+ * (`failed`). The `id` is top-level so callback echoes dedupe like other
+ * step-scoped events.
+ */
+export interface RunStepClosedEvent {
+    id: string;
+    index: number;
+    type: StepTypes;
+    status: Exclude<RunStepStatus, 'in_progress'>;
+    /** Epoch ms when the step was dispatched, when known. */
+    created_at?: number;
+    /** Epoch ms when the step reached its terminal status. */
+    closed_at: number;
+    runId?: string;
+    agentId?: string;
+    groupId?: number;
+    stepIndex?: number;
+}
+export type RecordStepCompletionOptions = {
+    /** The completing tool call, when the step tracks pending completions. */
+    toolCallId?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * Producer-stamped completion time (epoch ms). Carried through so a slow
+     * host completion handler cannot inflate the recorded step duration.
+     */
+    at?: number;
+};
+export type RunStepCloseOptions = {
+    /** Epoch ms for the terminal stamp; defaults to `Date.now()` at close time. */
+    at?: number;
+    metadata?: Record<string, unknown>;
+};
 export type StepDetails = MessageCreationDetails | ToolCallsDetails;
 export type SummaryCompleted = {
     type: 'summary';
@@ -132,6 +185,8 @@ export type ToolCompleteEvent = ToolCallCompleted & {
     /** The content index of the tool call */
     index: number;
     type: 'tool_call';
+    /** Epoch ms when this tool call's completion was dispatched. */
+    completed_at?: number;
 };
 export type ToolCallsDetails = {
     type: StepTypes.TOOL_CALLS;
@@ -224,6 +279,8 @@ export type MessageDeltaUpdate = {
     type: ContentTypes.TEXT;
     text: string;
     tool_call_ids?: string[];
+    /** Provider-supplied source citations, accumulated across deltas. */
+    citations?: Anthropic.TextCitation[];
 };
 export type ReasoningDeltaUpdate = {
     type: ContentTypes.THINK;

package/dist/types/utils/handlers.d.ts

@@ -21,6 +21,7 @@ interface HandlerCallbacks {
     onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;
     onRunStepCompleted?: (event: GraphEvents.ON_RUN_STEP_COMPLETED, data: t.StreamEventData) => void;
     onRunStepDelta?: (event: GraphEvents.ON_RUN_STEP_DELTA, data: t.StreamEventData) => void;
+    onRunStepClosed?: (event: GraphEvents.ON_RUN_STEP_CLOSED, data: t.RunStepClosedEvent) => void;
     onMessageDelta?: (event: GraphEvents.ON_MESSAGE_DELTA, data: t.StreamEventData) => void;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.4.4",
+  "version": "3.4.6",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -199,6 +199,7 @@
     "supervised": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/supervised.ts --provider anthropic --name Jo --location \"New York, NY\"",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "test:live:handoffs": "RUN_HANDOFF_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest src/specs/agent-handoffs.live.test.ts --runInBand",
+    "test:live:ask-user-questions": "RUN_ASK_USER_QUESTIONS_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest src/specs/ask-user-questions.live.test.ts --runInBand",
     "test:memory": "NODE_OPTIONS='--expose-gc' npx jest src/specs/title.memory-leak.test.ts",
     "test:all": "npm test -- --testPathIgnorePatterns=title.memory-leak.test.ts && npm run test:memory",
     "reinstall": "npm run clean && npm ci && rm -rf ./dist && npm run build",