@librechat/agents 3.4.2 → 3.4.4

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/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/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.2",
+  "version": "3.4.4",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -217,7 +217,7 @@
     "uuid": "$uuid",
     "ajv": "6.14.0",
     "@opentelemetry/core": "^2.9.0",
-    "js-yaml": "^4.3.0",
+    "js-yaml": "^4.3.1",
     "minimatch": "^10.2.2",
     "test-exclude": "^8.0.0"
   },
@@ -251,7 +251,7 @@
     "dotenv": "^16.4.7",
     "https-proxy-agent": "^7.0.6",
     "mathjs": "^15.2.0",
-    "nanoid": "^3.3.7",
+    "nanoid": "^3.3.18",
     "okapibm25": "^1.4.1",
     "openai": "^6.46.0",
     "reova": "^0.4.1",

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[] = [];

package/src/messages/assistantPhase.test.ts

@@ -0,0 +1,75 @@
+import {
+  getAssistantTextPhase,
+  getMessageCreationContentMetadata,
+  splitAssistantTextContentByPhase,
+} from './assistantPhase';
+import { ContentTypes } from '@/common';
+
+describe('assistant phase metadata', () => {
+  it('reads provider-native Open Responses phase metadata', () => {
+    const part = {
+      type: ContentTypes.TEXT,
+      text: '',
+      phase: 'commentary' as const,
+    };
+
+    expect(getAssistantTextPhase(part)).toBe('commentary');
+    expect(getMessageCreationContentMetadata([part])).toEqual({
+      content_type: ContentTypes.TEXT,
+      phase: 'commentary',
+    });
+  });
+
+  it('reads LangChain standard-content extras', () => {
+    const part = {
+      type: ContentTypes.TEXT,
+      text: '',
+      extras: { phase: 'final_answer' as const },
+    };
+
+    expect(getMessageCreationContentMetadata([part])).toEqual({
+      content_type: ContentTypes.TEXT,
+      phase: 'final_answer',
+    });
+  });
+
+  it('announces reasoning without inventing a text phase', () => {
+    expect(
+      getMessageCreationContentMetadata([
+        { type: ContentTypes.THINK, think: 'checking' },
+      ])
+    ).toEqual({ content_type: ContentTypes.THINK });
+  });
+
+  it('preserves every provider phase in a multi-block text chunk', () => {
+    const commentary = {
+      type: ContentTypes.TEXT,
+      text: 'I will inspect the session path.',
+      phase: 'commentary' as const,
+    };
+    const moreCommentary = {
+      type: ContentTypes.TEXT,
+      text: 'The refresh branch is stale.',
+      phase: 'commentary' as const,
+    };
+    const finalAnswer = {
+      type: ContentTypes.TEXT,
+      text: 'The refresh path is fixed.',
+      phase: 'final_answer' as const,
+    };
+
+    const groups = splitAssistantTextContentByPhase([
+      commentary,
+      moreCommentary,
+      finalAnswer,
+    ]);
+
+    expect(groups).toEqual([[commentary, moreCommentary], [finalAnswer]]);
+    expect(
+      groups.map((group) => getMessageCreationContentMetadata(group))
+    ).toEqual([
+      { content_type: ContentTypes.TEXT, phase: 'commentary' },
+      { content_type: ContentTypes.TEXT, phase: 'final_answer' },
+    ]);
+  });
+});

package/src/messages/assistantPhase.ts

@@ -0,0 +1,91 @@
+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;
+};
+
+function toAssistantTextPhase(value: unknown): AssistantTextPhase | undefined {
+  return value === 'commentary' || value === 'final_answer' ? value : undefined;
+}
+
+/** Reads both provider-native and LangChain standard-content phase fields. */
+export function getAssistantTextPhase(
+  contentPart: MessageContentComplex
+): AssistantTextPhase | undefined {
+  return (
+    toAssistantTextPhase(contentPart.phase) ??
+    toAssistantTextPhase(contentPart.extras?.phase)
+  );
+}
+
+/**
+ * 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 function splitAssistantTextContentByPhase(
+  content: MessageContentComplex[]
+): MessageContentComplex[][] {
+  const groups: MessageContentComplex[][] = [];
+  for (const contentPart of content) {
+    const phase = getAssistantTextPhase(contentPart);
+    const currentGroup = groups.at(-1);
+    if (
+      currentGroup == null ||
+      getAssistantTextPhase(currentGroup[0]) !== phase
+    ) {
+      groups.push([contentPart]);
+      continue;
+    }
+    currentGroup.push(contentPart);
+  }
+  return groups;
+}
+
+function isTextPart(contentPart: MessageContentComplex): boolean {
+  return contentPart.type?.startsWith(ContentTypes.TEXT) ?? false;
+}
+
+function isReasoningPart(contentPart: MessageContentComplex): boolean {
+  return (
+    contentPart.type === ContentTypes.THINK ||
+    (contentPart.type?.startsWith(ContentTypes.THINKING) ?? false) ||
+    (contentPart.type?.startsWith(ContentTypes.REASONING) ?? false) ||
+    (contentPart.type?.startsWith(ContentTypes.REASONING_CONTENT) ?? false) ||
+    contentPart.type === 'redacted_thinking'
+  );
+}
+
+/**
+ * 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 function getMessageCreationContentMetadata(
+  content: string | MessageContentComplex[] | undefined,
+  fallbackContentType?: ContentTypes.TEXT | ContentTypes.THINK
+): MessageCreationContentMetadata {
+  if (!Array.isArray(content)) {
+    return fallbackContentType == null
+      ? {}
+      : { content_type: fallbackContentType };
+  }
+  const textPart = content.find(isTextPart);
+  if (textPart != null) {
+    const phase = getAssistantTextPhase(textPart);
+    return {
+      content_type: ContentTypes.TEXT,
+      ...(phase == null ? {} : { phase }),
+    };
+  }
+  if (content.some(isReasoningPart)) {
+    return { content_type: ContentTypes.THINK };
+  }
+  return fallbackContentType == null
+    ? {}
+    : { content_type: fallbackContentType };
+}

package/src/messages/index.ts

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