@librechat/agents 3.4.3 → 3.4.5

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/callbacks.mjs

@@ -10,7 +10,14 @@ function findCallback(callbacks, predicate) {
 	if (callbacks == null) return;
 	return (Array.isArray(callbacks) ? callbacks : callbacks.handlers).find(predicate);
 }
+function filterCallbacks(callbacks, predicate) {
+	if (callbacks == null) return [];
+	if (Array.isArray(callbacks)) return callbacks.filter(predicate);
+	const filtered = callbacks.copy();
+	for (const handler of [...filtered.handlers]) if (!predicate(handler)) filtered.removeHandler(handler);
+	return filtered;
+}
 //#endregion
-export { appendCallbacks, findCallback };
+export { appendCallbacks, filterCallbacks, findCallback };
 
 //# sourceMappingURL=callbacks.mjs.map

package/dist/esm/utils/callbacks.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"callbacks.mjs","names":[],"sources":["../../../src/utils/callbacks.ts"],"sourcesContent":["import { ensureHandler } from '@langchain/core/callbacks/manager';\nimport type {\n  BaseCallbackHandler,\n  CallbackHandlerMethods,\n} from '@langchain/core/callbacks/base';\nimport type { Callbacks } from '@langchain/core/callbacks/manager';\n\nexport type CallbackEntry = BaseCallbackHandler | CallbackHandlerMethods;\n\nexport function appendCallbacks(\n  callbacks: Callbacks | undefined,\n  additions: readonly CallbackEntry[]\n): Callbacks {\n  if (additions.length === 0) {\n    return callbacks ?? [];\n  }\n\n  if (callbacks == null) {\n    return [...additions];\n  }\n\n  if (Array.isArray(callbacks)) {\n    return callbacks.concat(additions);\n  }\n\n  return callbacks.copy(additions.map(ensureHandler));\n}\n\nexport function findCallback(\n  callbacks: Callbacks | undefined,\n  predicate: (callback: CallbackEntry) => boolean\n): CallbackEntry | undefined {\n  if (callbacks == null) {\n    return undefined;\n  }\n\n  const handlers = Array.isArray(callbacks) ? callbacks : callbacks.handlers;\n  return handlers.find(predicate);\n}\n"],"mappings":";;AASA,SAAgB,gBACd,WACA,WACW;CACX,IAAI,UAAU,WAAW,GACvB,OAAO,aAAa,CAAC;CAGvB,IAAI,aAAa,MACf,OAAO,CAAC,GAAG,SAAS;CAGtB,IAAI,MAAM,QAAQ,SAAS,GACzB,OAAO,UAAU,OAAO,SAAS;CAGnC,OAAO,UAAU,KAAK,UAAU,IAAI,aAAa,CAAC;AACpD;AAEA,SAAgB,aACd,WACA,WAC2B;CAC3B,IAAI,aAAa,MACf;CAIF,QADiB,MAAM,QAAQ,SAAS,IAAI,YAAY,UAAU,SAAA,CAClD,KAAK,SAAS;AAChC"}
+{"version":3,"file":"callbacks.mjs","names":[],"sources":["../../../src/utils/callbacks.ts"],"sourcesContent":["import { ensureHandler } from '@langchain/core/callbacks/manager';\nimport type {\n  BaseCallbackHandler,\n  CallbackHandlerMethods,\n} from '@langchain/core/callbacks/base';\nimport type { Callbacks } from '@langchain/core/callbacks/manager';\n\nexport type CallbackEntry = BaseCallbackHandler | CallbackHandlerMethods;\n\nexport function appendCallbacks(\n  callbacks: Callbacks | undefined,\n  additions: readonly CallbackEntry[]\n): Callbacks {\n  if (additions.length === 0) {\n    return callbacks ?? [];\n  }\n\n  if (callbacks == null) {\n    return [...additions];\n  }\n\n  if (Array.isArray(callbacks)) {\n    return callbacks.concat(additions);\n  }\n\n  return callbacks.copy(additions.map(ensureHandler));\n}\n\nexport function findCallback(\n  callbacks: Callbacks | undefined,\n  predicate: (callback: CallbackEntry) => boolean\n): CallbackEntry | undefined {\n  if (callbacks == null) {\n    return undefined;\n  }\n\n  const handlers = Array.isArray(callbacks) ? callbacks : callbacks.handlers;\n  return handlers.find(predicate);\n}\n\nexport function filterCallbacks(\n  callbacks: Callbacks | undefined,\n  predicate: (callback: CallbackEntry) => boolean\n): Callbacks {\n  if (callbacks == null) {\n    return [];\n  }\n\n  if (Array.isArray(callbacks)) {\n    return callbacks.filter(predicate);\n  }\n\n  const filtered = callbacks.copy();\n  for (const handler of [...filtered.handlers]) {\n    if (!predicate(handler)) {\n      filtered.removeHandler(handler);\n    }\n  }\n  return filtered;\n}\n"],"mappings":";;AASA,SAAgB,gBACd,WACA,WACW;CACX,IAAI,UAAU,WAAW,GACvB,OAAO,aAAa,CAAC;CAGvB,IAAI,aAAa,MACf,OAAO,CAAC,GAAG,SAAS;CAGtB,IAAI,MAAM,QAAQ,SAAS,GACzB,OAAO,UAAU,OAAO,SAAS;CAGnC,OAAO,UAAU,KAAK,UAAU,IAAI,aAAa,CAAC;AACpD;AAEA,SAAgB,aACd,WACA,WAC2B;CAC3B,IAAI,aAAa,MACf;CAIF,QADiB,MAAM,QAAQ,SAAS,IAAI,YAAY,UAAU,SAAA,CAClD,KAAK,SAAS;AAChC;AAEA,SAAgB,gBACd,WACA,WACW;CACX,IAAI,aAAa,MACf,OAAO,CAAC;CAGV,IAAI,MAAM,QAAQ,SAAS,GACzB,OAAO,UAAU,OAAO,SAAS;CAGnC,MAAM,WAAW,UAAU,KAAK;CAChC,KAAK,MAAM,WAAW,CAAC,GAAG,SAAS,QAAQ,GACzC,IAAI,CAAC,UAAU,OAAO,GACpB,SAAS,cAAc,OAAO;CAGlC,OAAO;AACT"}

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/messages/assistantPhase.d.ts

@@ -0,0 +1,22 @@
+import type { AssistantTextPhase } from '@/types/assistantPhase';
+import type { MessageContentComplex } from '@/types/stream';
+import { ContentTypes } from '@/common';
+export type MessageCreationContentMetadata = {
+    content_type?: ContentTypes.TEXT | ContentTypes.THINK;
+    phase?: AssistantTextPhase;
+};
+/** Reads both provider-native and LangChain standard-content phase fields. */
+export declare function getAssistantTextPhase(contentPart: MessageContentComplex): AssistantTextPhase | undefined;
+/**
+ * Keeps provider-authored text phases in distinct message-creation steps.
+ * Open Responses may return commentary and final-answer blocks in one chunk;
+ * collapsing the array into one step would assign the first block's phase to
+ * every block and hide the boundary that closes an activity phase.
+ */
+export declare function splitAssistantTextContentByPhase(content: MessageContentComplex[]): MessageContentComplex[][];
+/**
+ * Derives additive message-creation metadata before a content delta is
+ * dispatched. The fallback covers string-only providers whose semantic lane
+ * is tracked by the stream handler rather than represented on a block.
+ */
+export declare function getMessageCreationContentMetadata(content: string | MessageContentComplex[] | undefined, fallbackContentType?: ContentTypes.TEXT | ContentTypes.THINK): MessageCreationContentMetadata;

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

@@ -14,3 +14,4 @@ export * from './contextPruning';
 export * from './contextPruningSettings';
 export * from './reducer';
 export * from './recency';
+export * from './assistantPhase';

package/dist/types/prompts/activityLabel.d.ts

@@ -1,5 +1,5 @@
+import type { ActivityLabelToolEntry, ActivityPhaseEntry } from '@/types/activityLabel';
 import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
-import type { ActivityLabelToolEntry } from '@/types/activityLabel';
 /**
  * Default system prompt for fast-model activity labeling.
  *
@@ -9,8 +9,13 @@ import type { ActivityLabelToolEntry } from '@/types/activityLabel';
  * "Synthesized version data and curated comparative framework").
  */
 export declare const ACTIVITY_LABEL_PROMPT = "Write a short label describing what this block of agent activity accomplished. It appears as the header of a collapsed activity group in a chat UI.\n\nRules:\n- 5 to 9 words, past-tense verb first\n- Name the most distinctive subject (file, API, topic); drop articles and filler\n- Describe outcomes, not mechanics; if something failed, say so plainly\n- Output only the label \u2014 no quotes, no punctuation at the end, no preamble\n\nExamples:\n- Searched Node.js release notes and changelogs\n- Compared runtime versions across official sources\n- Fixed failing auth middleware tests\n- Read project config and dependency manifests\n- Attempted database migration, hit permission errors";
+/** Default system prompt for a run-wide parent activity phase. */
+export declare const ACTIVITY_PHASE_LABEL_PROMPT = "Summarize what this phase of an agent run accomplished. The result appears as the header of one collapsed parent group containing several activities.\n\nRules:\n- One line, 8 to 18 words, past tense\n- Lead with the concrete outcome and name the most distinctive subject\n- Synthesize the phase; do not enumerate, count, or restate individual activities\n- Describe failures plainly when they are the phase's material outcome\n- Never mention tool names, calls, arguments, reasoning, commentary, or activity counts\n- Output only the summary \u2014 no quotes, no trailing punctuation, no preamble\n\nExamples:\n- Reconciled authentication behavior and fixed the failing session refresh path\n- Compared deployment options and documented the safest production rollout\n- Investigated database latency but could not confirm the suspected index regression\n\nBad examples:\n- Used three tools to inspect files and run tests\n- Searched code, read configuration, and updated middleware";
+/** Hard ceiling across every activity/context section in one phase request. */
+export declare const ACTIVITY_PHASE_PROMPT_MAX_LENGTH = 12000;
 /** Truncates a serialized value for the label prompt. */
 export declare function truncateForLabel(value: string, maxLength: number): string;
+export declare const ACTIVITY_PHASE_LABEL_MAX_LENGTH = 160;
 export type BuildActivityLabelPromptParams = {
     entries: ActivityLabelToolEntry[];
     charLimit: number;
@@ -36,3 +41,18 @@ export type BuildActivityLabelPromptParams = {
  * for direct testing of redaction and truncation behavior.
  */
 export declare function buildActivityLabelPrompt({ entries, charLimit, thinkingExcerpts, lastAssistantText, previousLabels, redaction, }: BuildActivityLabelPromptParams): string;
+export type BuildActivityPhaseLabelPromptParams = {
+    activities: ActivityPhaseEntry[];
+    totalActivityCount?: number;
+    charLimit: number;
+    assistantContext?: string[];
+    redaction?: ResolvedLangfuseToolOutputTracingConfig;
+};
+/**
+ * Builds bounded, redaction-aware evidence for a parent activity phase.
+ * Committed child labels are preferred; raw tool/reasoning evidence is only
+ * used when no child label exists.
+ */
+export declare function buildActivityPhaseLabelPrompt({ activities, totalActivityCount, charLimit, assistantContext, redaction, }: BuildActivityPhaseLabelPromptParams): string;
+/** Normalizes a model result for safe single-row persistence and display. */
+export declare function normalizeActivityPhaseLabel(label: string): string;

package/dist/types/run.d.ts

@@ -1,5 +1,5 @@
-import { BaseMessage } from '@langchain/core/messages';
 import { Command } from '@langchain/langgraph';
+import { BaseMessage } from '@langchain/core/messages';
 import type { MessageContentComplex } from '@langchain/core/messages';
 import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -44,6 +44,10 @@ export declare class Run<_T extends t.BaseGraphState> {
     private _interrupt;
     /** Per-run sequence for batch-unique activity-label trace-seed fallbacks. */
     private activityLabelSeq;
+    /** Per-run sequence for parent activity-phase trace and invocation ids. */
+    private activityPhaseLabelSeq;
+    /** Latest user turn used to keep detached phase roots conversation-shaped. */
+    private activityPhaseTraceInput?;
     /** Distinguishes sibling forks started from the same explicit checkpoint. */
     private checkpointForkSeq;
     private _haltedReason;
@@ -238,7 +242,16 @@ export declare class Run<_T extends t.BaseGraphState> {
      * comes from `lastAssistantText`, content from reasoning excerpts and
      * tool entries.
      */
-    generateActivityLabel({ provider, clientOptions, entries, thinkingExcerpts, lastAssistantText, previousLabels, prompt, charLimit, chainOptions, traceSeed, agentId, }: t.RunActivityLabelOptions): Promise<{
+    generateActivityLabel({ provider, clientOptions, entries, thinkingExcerpts, lastAssistantText, lastAssistantPhase, previousLabels, prompt, charLimit, chainOptions, traceSeed, agentId, }: t.RunActivityLabelOptions): Promise<{
+        label?: string;
+    }>;
+    /**
+     * Generates one parent summary for two or more logical activities. The
+     * summary model is traced as a dedicated activity-phase agent root in the
+     * conversation session, with the model callback recorded as its generation
+     * child. No session id means no phase trace, avoiding orphan observations.
+     */
+    generateActivityPhaseLabel({ provider, clientOptions, activities, totalActivityCount, assistantContext, closingTextPhase, prompt, charLimit, chainOptions, traceSeed, sourceRunId, sourceTraceId, responseId, phaseIndex, status, agentIds, }: t.RunActivityPhaseLabelOptions): Promise<{
         label?: string;
     }>;
 }

package/dist/types/types/activityLabel.d.ts

@@ -1,4 +1,5 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { AssistantTextPhase } from '@/types/assistantPhase';
 import type { ClientOptions } from '@/types/llm';
 import type { Providers } from '@/common';
 /** One tool call's contribution to the label payload (host-assembled). */
@@ -36,6 +37,11 @@ export type RunActivityLabelOptions = {
     thinkingExcerpts?: string[];
     /** Assistant's last text before the block (~200 chars), as intent context. */
     lastAssistantText?: string;
+    /**
+     * Provider-authored semantic phase for `lastAssistantText`. Hosts can use
+     * this to pass commentary as intent while excluding final-answer text.
+     */
+    lastAssistantPhase?: AssistantTextPhase;
     /**
      * Headers already committed for earlier batches in this run (run order,
      * most recent last). Continuity context: the prompt shows them so the new
@@ -59,3 +65,60 @@ export type RunActivityLabelOptions = {
      */
     traceSeed?: string;
 };
+/** One logical activity contributing to a run-wide phase summary. */
+export type ActivityPhaseEntry = {
+    /** Already committed child activity label, preferred over raw evidence. */
+    label?: string;
+    /** Raw fallback for a child label that was disabled, pending, or dropped. */
+    entries?: ActivityLabelToolEntry[];
+    /** Standalone or tool-attached reasoning excerpts for this activity. */
+    thinkingExcerpts?: string[];
+    /** Agent lane that produced the activity. */
+    agentId?: string;
+    /** Failed activities remain useful evidence and still count. */
+    status?: 'success' | 'partial' | 'error';
+};
+/** Options for `Run.generateActivityPhaseLabel`. */
+export type RunActivityPhaseLabelOptions = {
+    provider: Providers;
+    clientOptions?: ClientOptions;
+    /**
+     * Logical activities in run order. The SDK requires at least two so hosts
+     * cannot accidentally spend a model call summarizing a single activity.
+     */
+    activities: ActivityPhaseEntry[];
+    /** Full count when the host retained only bounded prompt evidence. */
+    totalActivityCount?: number;
+    /**
+     * Bounded assistant commentary emitted inside the phase. Human messages
+     * must not be supplied through this low-scrutiny summarization path.
+     */
+    assistantContext?: string[];
+    /** Semantic phase of the text boundary that closed the activity phase. */
+    closingTextPhase?: AssistantTextPhase;
+    /** Override for the dedicated phase-label system prompt. */
+    prompt?: string;
+    /** Per-evidence serialization cap for the prompt. Default 600. */
+    charLimit?: number;
+    /** LangChain runnable config carrier (signal, callbacks, thread/user ids). */
+    chainOptions?: Partial<RunnableConfig> & {
+        configurable?: Record<string, unknown>;
+    };
+    /** Deterministic seed for this phase label trace. */
+    traceSeed?: string;
+    /** Stable source run identifier recorded on the phase observation. */
+    sourceRunId?: string;
+    /** Source Langfuse trace id for linking this detached summary trace. */
+    sourceTraceId?: string;
+    /** Host response/message identifier recorded on the phase observation. */
+    responseId?: string;
+    /** Zero-based index of the phase within the source run. */
+    phaseIndex?: number;
+    /** Completion state recorded on the phase observation. */
+    status?: 'completed' | 'partial' | 'failed';
+    /**
+     * Contributing agents. Their Langfuse redaction policies are combined into
+     * the strictest union before any phase evidence enters the model or trace.
+     */
+    agentIds?: string[];
+};

package/dist/types/types/assistantPhase.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Semantic phase attached to assistant text by Open Responses-compatible
+ * providers. Commentary is intermediate agent narration; final_answer marks
+ * the user-facing answer that closes the preceding activity phase.
+ */
+export type AssistantTextPhase = 'commentary' | 'final_answer';

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

@@ -5,7 +5,7 @@ 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 { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
+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';
@@ -680,6 +680,13 @@ export interface AgentInputs {
     subagentConfigs?: SubagentConfigEntry[];
     /** Maximum subagent nesting depth. Default 1 means top-level agents can spawn subagents but subagents cannot nest further. */
     maxSubagentDepth?: number;
+    /**
+     * Initial tool-session state owned by this agent when it runs as a
+     * subagent. The executor copies these sessions into the isolated child
+     * graph before its first invocation. Top-level runs continue to use
+     * `RunConfig.initialSessions`.
+     */
+    initialSessions?: ToolSessionMap;
     /**
      * Host-supplied tool instances that must execute IN-PROCESS inside the graph's
      * ToolNode even when the run is event-driven (`toolDefinitions` non-empty). Each

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/index.d.ts

@@ -8,3 +8,4 @@ export * from './stream';
 export * from './tools';
 export * from './summarize';
 export * from './activityLabel';
+export * from './assistantPhase';

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

@@ -3,6 +3,7 @@ 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 { AnthropicContentBlock } from '@/llm/anthropic/types';
+import type { AssistantTextPhase } from '@/types/assistantPhase';
 import type { SummarizeCompleteEvent } from '@/types/summarize';
 import type { ToolEndEvent } from '@/types/tools';
 import { StepTypes, ContentTypes, GraphEvents } from '@/common/enum';
@@ -80,6 +81,10 @@ export type MessageCreationDetails = {
     type: StepTypes.MESSAGE_CREATION;
     message_creation: {
         message_id: string;
+        /** Content lane announced before its first delta. */
+        content_type?: ContentTypes.TEXT | ContentTypes.THINK;
+        /** Provider-authored assistant text phase, when available. */
+        phase?: AssistantTextPhase;
     };
 };
 export type ToolEndData = {
@@ -323,6 +328,12 @@ export type MessageContentComplex = (ToolResultContent | ThinkingContentText | S
 }) | (Record<string, any> & {
     type?: never;
 })) & {
+    /** Open Responses-compatible semantic phase for assistant text. */
+    phase?: AssistantTextPhase;
+    /** LangChain standard-content form of provider-specific block fields. */
+    extras?: {
+        phase?: AssistantTextPhase;
+    } & Record<string, unknown>;
     tool_call_ids?: string[];
     agentId?: string;
     groupId?: number;

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

@@ -3,3 +3,4 @@ import type { Callbacks } from '@langchain/core/callbacks/manager';
 export type CallbackEntry = BaseCallbackHandler | CallbackHandlerMethods;
 export declare function appendCallbacks(callbacks: Callbacks | undefined, additions: readonly CallbackEntry[]): Callbacks;
 export declare function findCallback(callbacks: Callbacks | undefined, predicate: (callback: CallbackEntry) => boolean): CallbackEntry | undefined;
+export declare function filterCallbacks(callbacks: Callbacks | undefined, predicate: (callback: CallbackEntry) => boolean): Callbacks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.4.3",
+  "version": "3.4.5",
   "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",

package/src/graphs/Graph.ts

@@ -61,6 +61,8 @@ import {
   supportsBedrockToolCache,
   isSyntheticProviderContextMessage,
   getMessageId,
+  getMessageCreationContentMetadata,
+  splitAssistantTextContentByPhase,
   makeIsDeferred,
   partitionAndMarkAnthropicToolCache,
   DEFAULT_RETAIN_RECENT_TURNS,
@@ -507,18 +509,25 @@ async function dispatchMessageCreationStep({
   graph,
   stepKey,
   messageId,
+  content,
+  contentType,
   metadata,
 }: {
   graph: Graph<t.BaseGraphState>;
   stepKey: string;
   messageId: string;
+  content?: string | t.MessageContentComplex[];
+  contentType?: ContentTypes.TEXT | ContentTypes.THINK;
   metadata: Record<string, unknown>;
 }): Promise<string> {
   await graph.dispatchRunStep(
     stepKey,
     {
       type: StepTypes.MESSAGE_CREATION,
-      message_creation: { message_id: messageId },
+      message_creation: {
+        message_id: messageId,
+        ...getMessageCreationContentMetadata(content, contentType),
+      },
     },
     metadata
   );
@@ -548,6 +557,7 @@ async function dispatchTextMessageContent({
         graph,
         stepKey,
         messageId,
+        content: [contentPart],
         metadata,
       });
       await graph.dispatchMessageDelta(
@@ -558,13 +568,24 @@ async function dispatchTextMessageContent({
     }
     return true;
   }
-  const stepId = await dispatchMessageCreationStep({
-    graph,
-    stepKey,
-    messageId,
-    metadata,
-  });
-  await graph.dispatchMessageDelta(stepId, { content }, metadata);
+  const contentGroups = Array.isArray(content)
+    ? splitAssistantTextContentByPhase(content)
+    : [content];
+  for (const contentGroup of contentGroups) {
+    const stepId = await dispatchMessageCreationStep({
+      graph,
+      stepKey,
+      messageId,
+      content: contentGroup,
+      contentType: ContentTypes.TEXT,
+      metadata,
+    });
+    await graph.dispatchMessageDelta(
+      stepId,
+      { content: contentGroup },
+      metadata
+    );
+  }
   return true;
 }
 
@@ -599,7 +620,10 @@ async function dispatchReasoningContent({
     stepKey,
     {
       type: StepTypes.MESSAGE_CREATION,
-      message_creation: { message_id: messageId },
+      message_creation: {
+        message_id: messageId,
+        content_type: ContentTypes.THINK,
+      },
     },
     metadata
   );

package/src/graphs/__tests__/Graph.reasoning.test.ts

@@ -275,6 +275,63 @@ describe('StandardGraph final response reasoning fallback', () => {
     streamUsage: false,
   };
 
+  it('starts a new message step when streamed assistant phases change', async () => {
+    const reasoningDeltas: t.ReasoningDeltaEvent[] = [];
+    const messageDeltas: t.MessageDeltaEvent[] = [];
+    const { contentParts, aggregateContent } = createContentAggregator();
+    const run = await Run.create<t.IState>({
+      runId: 'separate-streamed-assistant-phases',
+      graphConfig: {
+        type: 'standard',
+        llmConfig,
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers: createReasoningHandlers(
+        aggregateContent,
+        reasoningDeltas,
+        messageDeltas
+      ),
+    });
+
+    if (!run.Graph) {
+      throw new Error('Expected graph to be initialized');
+    }
+
+    run.Graph.overrideModel = new StreamingReasoningModel([
+      new AIMessageChunk({
+        content: [
+          { type: 'text', text: 'Checking the session.', phase: 'commentary' },
+        ] as never,
+      }),
+      new AIMessageChunk({
+        content: [
+          { type: 'text', text: 'The session is fixed.', phase: 'final_answer' },
+        ] as never,
+      }),
+    ]);
+
+    await run.processStream(
+      { messages: [new HumanMessage('fix the session')] },
+      config
+    );
+
+    expect(new Set(messageDeltas.map((delta) => delta.id)).size).toBe(2);
+    expect(contentParts).toEqual([
+      { type: 'text', text: 'Checking the session.' },
+      { type: 'text', text: 'The session is fixed.' },
+    ]);
+    expect(
+      run.Graph.getRunSteps()
+        .filter((step) => step.stepDetails.type === StepTypes.MESSAGE_CREATION)
+        .map((step) =>
+          step.stepDetails.type === StepTypes.MESSAGE_CREATION
+            ? step.stepDetails.message_creation.phase
+            : undefined
+        )
+    ).toEqual(['commentary', 'final_answer']);
+  });
+
   it('emits reasoning_content from invoke-only final responses', async () => {
     const reasoningText = 'Need to inspect the Home Assistant tool state.';
     const reasoningDeltas: t.ReasoningDeltaEvent[] = [];