@librechat/agents 3.6.7 → 3.6.8

package/dist/esm/stream.mjs

@@ -1,6 +1,6 @@
-import { composeAbortSignals } from "./utils/misc.mjs";
 import { CODE_EXECUTION_TOOLS, LOCAL_CODING_BUNDLE_NAMES } from "./common/enum.mjs";
 import "./common/index.mjs";
+import { composeAbortSignals } from "./utils/misc.mjs";
 import { calculateMaxToolResultChars, truncateToolResultContent } from "./utils/truncation.mjs";
 import { serializeStructuredValueBounded, serializeToolContentBounded } from "./utils/toolContent.mjs";
 import { getMessageId } from "./messages/ids.mjs";

package/dist/esm/tools/ToolNode.mjs

@@ -1,8 +1,8 @@
+import { CODE_EXECUTION_TOOLS } from "../common/enum.mjs";
+import "../common/index.mjs";
 import { attachRunStepResumeState } from "./runStepResume.mjs";
 import { SUBAGENT_PARENT_BATCH_CONFIG_KEY, SUBAGENT_REPLAY_CONTROLLER, attachSubagentResumeManifest } from "./subagent/SubagentReplay.mjs";
 import { composeAbortSignals } from "../utils/misc.mjs";
-import { CODE_EXECUTION_TOOLS } from "../common/enum.mjs";
-import "../common/index.mjs";
 import { resolveLangfuseRuntimeScope, withLangfuseRuntimeScope } from "../langfuseRuntimeScope.mjs";
 import { calculateMaxToolResultChars, truncateToolResultContent } from "../utils/truncation.mjs";
 import { cloneToolMessageWithContent, compactToolContent, hasComputerCallOutputMarker, isComputerCallOutputContent, isComputerCallOutputMessage, serializeStructuredValueBounded, serializeToolContentBounded } from "../utils/toolContent.mjs";

package/dist/esm/tools/subagent/SubagentExecutor.mjs

@@ -1,8 +1,8 @@
+import "../../common/enum.mjs";
+import "../../common/index.mjs";
 import { stripRunStepResumeState } from "../runStepResume.mjs";
 import { SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY, SUBAGENT_RESUME_MANIFEST_CONFIG_KEY, attachSubagentResumeManifest, getSubagentResumeManifest } from "./SubagentReplay.mjs";
 import { composeAbortSignals } from "../../utils/misc.mjs";
-import "../../common/enum.mjs";
-import "../../common/index.mjs";
 import { seedAgentInitialSessions } from "../../utils/toolSessions.mjs";
 import { convertInjectedMessages } from "../../messages/injected.mjs";
 import { StreamLimitExceededError } from "../../llm/streamLimits.mjs";

package/dist/types/common/constants.d.ts

@@ -29,3 +29,11 @@ export declare const PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS = 120000;
  * the stream config; a preemption-enabled run adds its seal budget on top.
  */
 export declare const DEFAULT_RECURSION_LIMIT = 50;
+/** Stable runtime names used for agent workflow observations. */
+export declare const STANDARD_GRAPH_RUN_NAME = "AgentGraph";
+export declare const MULTI_AGENT_GRAPH_RUN_NAME = "MultiAgentGraph";
+export declare const AGENT_MODEL_CALL_RUN_NAME = "AgentModelCall";
+export declare const ACTIVITY_LABEL_RUN_NAME = "StepLabel";
+export declare const REASONING_LABEL_RUN_NAME = "ReasoningLabel";
+export declare const ACTIVITY_PHASE_RUN_NAME = "MultiStepLabel";
+export declare const ACTIVITY_PHASE_LABEL_RUN_NAME = "MultiStepLabelGeneration";

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

@@ -234,6 +234,7 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     getOrCreateFileCheckpointer(): t.LocalFileCheckpointer | undefined;
 }
 export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
+    readonly runName: string;
     overrideModel?: t.ChatModel;
     private subagentModelOverride?;
     private readonly graphFactory;
@@ -260,10 +261,12 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * component: public run ids are unrestricted and may repeat across
      * concurrently executing runs (retries, duplicate submissions,
      * tenant-local message ids), and equal stamps would let those runs adopt
-     * each other's scopes. One graph instance = one execution's stamp, shared
-     * by the stream handler and every graph-level scope of that execution.
+     * each other's scopes. Fresh stream executions rotate this stamp; resumes
+     * retain it so the continuation stays in the interrupted execution.
      */
-    readonly langfuseScopeRunId: string;
+    langfuseScopeRunId: string;
+    /** Opaque key for parenting post-processing observations to this run. */
+    langfuseTraceAnchor: object;
     /**
      * Boundary between historical messages (loaded from conversation state)
      * and messages produced during the current run.  Set once in the state
@@ -388,6 +391,8 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      */
     pendingPreemptReturn: Set<string>;
     constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentTasks, subagentScope, subagentExecutionContext, preemption, streamLimits, }: t.StandardGraphInput, dependencies?: GraphFactoryDependencies);
+    /** Rotates the Langfuse identities that must never cross fresh executions. */
+    startFreshLangfuseExecution(): void;
     resetValues(keepContent?: boolean, checkpointScope?: string): void;
     /** Seeds the sidecar message view that checkpoint restoration bypasses. */
     restoreCheckpointMessages(messages: BaseMessage[], pendingMessages?: BaseMessage[]): void;

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

@@ -16,6 +16,7 @@ import { StandardGraph } from './Graph';
  * OR continues its workflow (direct edges), but not both simultaneously.
  */
 export declare class MultiAgentGraph extends StandardGraph {
+    readonly runName = "MultiAgentGraph";
     private edges;
     private startingNodes;
     private directEdges;

package/dist/types/langfuse.d.ts

@@ -1,4 +1,5 @@
 import { CallbackHandler } from '@langfuse/langchain';
+import type { SpanContext } from '@opentelemetry/api';
 import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
 import type * as t from '@/types';
 import { hasLangfuseConfigCredentials, hasLangfuseEnvCredentials, hasLangfuseEnvConfig } from '@/langfuseConfig';
@@ -12,6 +13,14 @@ type LangfuseHandlerParams = {
     traceMetadata?: LangfuseTraceMetadata;
     tags?: string[];
     traceIdSeed?: string;
+    /** Opaque key used by the span processor to capture this run's parents. */
+    traceAnchor?: object;
+    /** Agent lane this handler owns when ambient callback scope is unavailable. */
+    agentId?: string;
+    /** Exported observation that auxiliary work should be nested beneath. */
+    parentSpanContext?: SpanContext;
+    /** Keep an existing parent trace's user, session, name, and metadata. */
+    inheritTraceIdentity?: boolean;
     /** Identity of the run this handler traces; ambient runtime scopes are
      *  only adopted when stamped with the same run (see
      *  `LangfuseRuntimeContext.runId`). */
@@ -42,7 +51,7 @@ export declare function createLangfuseTraceMetadata({ messageId, parentMessageId
 export declare function getLangfuseTraceName(traceMetadata?: LangfuseTraceMetadata, fallback?: string): string;
 export declare function shouldCreateLangfuseHandler(langfuse?: t.LangfuseConfig): boolean;
 export declare function createLegacyLangfuseHandler(params: LangfuseHandlerParams): CallbackHandler;
-export declare function createLangfuseHandler({ langfuse, userId, sessionId, traceMetadata, tags, traceIdSeed, runId, toolOutputTracing, traceName, }: AgentLangfuseHandlerParams): CallbackHandler | undefined;
+export declare function createLangfuseHandler({ langfuse, userId, sessionId, traceMetadata, tags, traceIdSeed, traceAnchor, agentId, parentSpanContext, inheritTraceIdentity, runId, toolOutputTracing, traceName, }: AgentLangfuseHandlerParams): CallbackHandler | undefined;
 export declare function withLangfuseAttributes<T>(params: LangfuseAttributeParams, action: () => T): T;
 export declare function hasExplicitLangfuseConfig(contexts: Iterable<{
     langfuse?: t.LangfuseConfig;

package/dist/types/langfuseOperation.d.ts

@@ -0,0 +1,2 @@
+/** Internal observation metadata key used to distinguish SDK operations from public tags. */
+export declare const LANGFUSE_OPERATION_METADATA_KEY = "librechat.sdk.operation";

package/dist/types/langfuseRuntimeContext.d.ts

@@ -8,6 +8,8 @@ export type ResolvedLangfuseToolOutputTracingConfig = {
 export type LangfuseRuntimeContext = {
     langfuse?: t.LangfuseConfig;
     traceIdSeed?: string;
+    /** Opaque run-owned key used to recover the exported trace parent. */
+    traceAnchor?: object;
     toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
     /**
      * Identity of the run this scope belongs to. LangChain executes

package/dist/types/langfuseRuntimeScope.d.ts

@@ -6,6 +6,7 @@ export type ResolveLangfuseRuntimeScopeParams = {
     runLangfuse?: t.LangfuseConfig;
     langfuseOverlay?: t.LangfuseConfig;
     traceIdSeed?: string;
+    traceAnchor?: object;
     runId?: string;
     agentId?: string;
 };
@@ -18,6 +19,7 @@ export type LangfuseRuntimeScopeOptions = {
 };
 export declare function getOtelLangfuseConfig(activeContext: Context): t.LangfuseConfig | undefined;
 export declare function getOtelTraceIdSeed(activeContext: Context): string | undefined;
+export declare function resolveLangfuseTraceAnchor(activeContext: Context): object | undefined;
 export declare function getOtelToolOutputTracingConfig(activeContext: Context): ResolvedLangfuseToolOutputTracingConfig | undefined;
 export declare function resolveLangfuseConfigForSpan(activeContext: Context): t.LangfuseConfig | undefined;
 export declare function resolveTraceIdSeedForSpan(activeContext: Context): string | undefined;
@@ -29,4 +31,4 @@ export declare function resolveLangfuseScopeRunId(activeContext: Context): strin
 export declare function resolveLangfuseScopeAgentId(activeContext: Context): string | undefined;
 export declare function resolveToolOutputTracingConfigForSpan(activeContext: Context): ResolvedLangfuseToolOutputTracingConfig | undefined;
 export declare function withLangfuseRuntimeScope<T>(scope: LangfuseRuntimeScope, action: () => T, options?: LangfuseRuntimeScopeOptions): T;
-export declare function resolveLangfuseRuntimeScope({ runLangfuse, langfuseOverlay, traceIdSeed, runId, agentId, }: ResolveLangfuseRuntimeScopeParams): LangfuseRuntimeScope;
+export declare function resolveLangfuseRuntimeScope({ runLangfuse, langfuseOverlay, traceIdSeed, traceAnchor, runId, agentId, }: ResolveLangfuseRuntimeScopeParams): LangfuseRuntimeScope;

package/dist/types/langfuseSpanRegistry.d.ts

@@ -1,8 +1,18 @@
 import type { LangfuseSpanProcessorParams } from '@langfuse/otel';
-import type { Span } from '@opentelemetry/api';
+import type { Span, SpanContext } from '@opentelemetry/api';
 import type * as t from '@/types';
 export declare function registerLangfuseManagedSpan(span: Span, destinationKey: string): void;
 export declare function getLangfuseManagedSpanDestination(span: Span): string | undefined;
+/** Captures the first exported observation for a run and for each agent lane. */
+export declare function registerLangfuseTraceAnchorSpan(anchor: object, span: Span, destinationKey: string, agentId?: string): void;
+/**
+ * Resolves the most specific safe parent available for auxiliary work. An
+ * active observation wins so labels emitted inside a tool or reasoning step
+ * stay beside their source; otherwise the run root anchors the label in the
+ * same trace. An agent lane is the fallback when its overlay exports to a
+ * different destination. Cross-destination parents are never returned.
+ */
+export declare function resolveLangfuseTraceAnchorParent(anchor: object | undefined, destinationKey: string | undefined, agentId?: string): SpanContext | undefined;
 export declare function getLangfuseSpanProcessorParams(langfuse?: t.LangfuseConfig): LangfuseSpanProcessorParams | undefined;
 /**
  * Identity of an export destination (project credentials + endpoint +

package/dist/types/langfuseTraceShaping.d.ts

@@ -13,16 +13,18 @@ export declare function shouldDropLangfuseSpan(spanName: string): boolean;
  *   (`provider__model`) — strip it so switching models doesn't break
  *   name-based logic (item 1). The outer workflow node is named with the
  *   bare agent id; ephemeral ids reduce to their stable sender name.
+ * - Graph and prompt-to-model framework names become stable SDK operations:
+ *   `AgentGraph` / `MultiAgentGraph` and `AgentModelCall`.
  * - LLM generation spans keep the provider client class name (`ChatOpenAI`,
- *   `AzureChatOpenAI`, …); rename them to a provider-agnostic `llm` so the
- *   name reflects the operation, not the model (the model stays on the
- *   generation's model attribute).
+ *   `AzureChatOpenAI`, …); rename ordinary calls to a provider-agnostic `llm`
+ *   and label calls by their activity/reasoning role. The model stays on the
+ *   generation's model attribute.
  * - 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, 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).
+ *   summary operations become `chain` observations. Root-observation
+ *   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

@@ -264,9 +264,10 @@ export declare class Run<_T extends t.BaseGraphState> {
     generateReasoningLabel({ provider, clientOptions, visibleReasoning, reasoningStepId, revision, status, previousLabel, agentId, prompt, charLimit, chainOptions, traceSeed, sourceRunId, sourceTraceId, responseId, }: t.RunReasoningLabelOptions): Promise<t.ReasoningLabelResult>;
     /**
      * Generates one parent summary for two or more logical activities. 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.
+     * summary model is traced as an activity-phase chain beneath the source
+     * agent run, with the model callback recorded as its generation child. It
+     * falls back to a dedicated trace when no source observation is available.
+     * 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

@@ -60,8 +60,9 @@ export type RunActivityLabelOptions = {
     };
     /**
      * Seed for deterministic Langfuse trace ids (e.g. `${runId}-${slotIndex}`)
-     * so each batch's label gets a distinct, reproducible trace. When omitted,
-     * a per-run sequence keeps batches from collapsing into one trace.
+     * for a distinct, reproducible fallback trace when the source agent
+     * observation is unavailable. Normally the label is parented into the
+     * source agent trace instead.
      */
     traceSeed?: string;
 };
@@ -108,7 +109,7 @@ export type RunActivityPhaseLabelOptions = {
     traceSeed?: string;
     /** Stable source run identifier recorded on the phase observation. */
     sourceRunId?: string;
-    /** Source Langfuse trace id for linking this detached summary trace. */
+    /** Source Langfuse trace id retained as correlation metadata. */
     sourceTraceId?: string;
     /** Host response/message identifier recorded on the phase observation. */
     responseId?: string;

package/dist/types/types/reasoningLabel.d.ts

@@ -49,7 +49,7 @@ export type RunReasoningLabelOptions = {
     traceSeed?: string;
     /** Stable source run identifier recorded on the observation. */
     sourceRunId?: string;
-    /** Source Langfuse trace id for linking this detached label trace. */
+    /** Source Langfuse trace id retained as correlation metadata. */
     sourceTraceId?: string;
     /** Host response/message identifier recorded on the observation. */
     responseId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.6.7",
+  "version": "3.6.8",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -245,10 +245,10 @@
     "@langchain/openai": "1.5.8",
     "@langchain/textsplitters": "^1.0.1",
     "@langchain/xai": "^1.4.3",
-    "@langfuse/core": "^5.4.1",
-    "@langfuse/langchain": "^5.4.1",
-    "@langfuse/otel": "^5.4.1",
-    "@langfuse/tracing": "^5.4.1",
+    "@langfuse/core": "^5.10.1",
+    "@langfuse/langchain": "^5.10.1",
+    "@langfuse/otel": "^5.10.1",
+    "@langfuse/tracing": "^5.10.1",
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-node": "^0.220.0",
     "@types/diff": "^7.0.2",

package/src/common/constants.ts

@@ -33,3 +33,12 @@ export const PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS = 120_000;
  * the stream config; a preemption-enabled run adds its seal budget on top.
  */
 export const DEFAULT_RECURSION_LIMIT = 50;
+
+/** Stable runtime names used for agent workflow observations. */
+export const STANDARD_GRAPH_RUN_NAME = 'AgentGraph';
+export const MULTI_AGENT_GRAPH_RUN_NAME = 'MultiAgentGraph';
+export const AGENT_MODEL_CALL_RUN_NAME = 'AgentModelCall';
+export const ACTIVITY_LABEL_RUN_NAME = 'StepLabel';
+export const REASONING_LABEL_RUN_NAME = 'ReasoningLabel';
+export const ACTIVITY_PHASE_RUN_NAME = 'MultiStepLabel';
+export const ACTIVITY_PHASE_LABEL_RUN_NAME = 'MultiStepLabelGeneration';

package/src/graphs/Graph.ts

@@ -74,6 +74,17 @@ import {
   appendPredecessorHandoffCue,
   removePredecessorHandoffCue,
 } from '@/messages';
+import {
+  Constants,
+  GraphNodeKeys,
+  ContentTypes,
+  GraphEvents,
+  Providers,
+  StepTypes,
+  STANDARD_GRAPH_RUN_NAME,
+  AGENT_MODEL_CALL_RUN_NAME,
+  PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS,
+} from '@/common';
 import {
   resetIfNotEmpty,
   isAnthropicLike,
@@ -106,15 +117,6 @@ import {
   isGraphSubagentConfig,
   normalizeSubagentConfigEntries,
 } from '@/tools/subagent';
-import {
-  Constants,
-  GraphNodeKeys,
-  ContentTypes,
-  GraphEvents,
-  Providers,
-  StepTypes,
-  PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS,
-} from '@/common';
 import {
   createLangfuseHandler,
   createLangfuseTraceMetadata,
@@ -1260,6 +1262,7 @@ export abstract class Graph<
 }
 
 export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
+  readonly runName: string = STANDARD_GRAPH_RUN_NAME;
   overrideModel?: t.ChatModel;
   private subagentModelOverride?: t.ChatModel;
   private readonly graphFactory: GraphFactory;
@@ -1286,10 +1289,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * component: public run ids are unrestricted and may repeat across
    * concurrently executing runs (retries, duplicate submissions,
    * tenant-local message ids), and equal stamps would let those runs adopt
-   * each other's scopes. One graph instance = one execution's stamp, shared
-   * by the stream handler and every graph-level scope of that execution.
+   * each other's scopes. Fresh stream executions rotate this stamp; resumes
+   * retain it so the continuation stays in the interrupted execution.
    */
-  readonly langfuseScopeRunId: string;
+  langfuseScopeRunId: string;
+  /** Opaque key for parenting post-processing observations to this run. */
+  langfuseTraceAnchor: object = {};
   /**
    * Boundary between historical messages (loaded from conversation state)
    * and messages produced during the current run.  Set once in the state
@@ -1498,6 +1503,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.defaultAgentId = agents[0].agentId;
   }
 
+  /** Rotates the Langfuse identities that must never cross fresh executions. */
+  startFreshLangfuseExecution(): void {
+    this.langfuseTraceAnchor = {};
+    this.langfuseScopeRunId = `${this.runId ?? 'graph'}:${nanoid()}`;
+  }
+
   /* Init */
 
   resetValues(keepContent?: boolean, checkpointScope?: string): void {
@@ -2913,7 +2924,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         });
 
       if (agentContext.systemRunnable) {
-        model = agentContext.systemRunnable.pipe(model as Runnable);
+        model = agentContext.systemRunnable
+          .pipe(model as Runnable)
+          .withConfig({ runName: AGENT_MODEL_CALL_RUN_NAME });
       }
 
       if (agentContext.tokenCalculationPromise) {
@@ -4010,6 +4023,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           tags: ['librechat', 'agent'],
           traceIdSeed:
             langfuse?.deterministicTraceId === true ? this.runId : undefined,
+          traceAnchor: this.langfuseTraceAnchor,
+          agentId,
           runId: this.langfuseScopeRunId,
           toolOutputTracing: hasToolOutputTracingConfig(
             this.langfuse,
@@ -4052,6 +4067,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           resolveLangfuseRuntimeScope({
             runLangfuse: this.langfuse,
             langfuseOverlay: agentContext.langfuse,
+            traceAnchor: this.langfuseTraceAnchor,
             runId: this.langfuseScopeRunId,
             agentId,
           }),
@@ -4845,94 +4861,98 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           createChildGraphByKind: createConfiguredChildGraph,
           createDetachedChildGraphFactory: (
             parentHandlerRegistry
-          ): GraphFactory =>
-            snapshotChildGraphFactory(parentHandlerRegistry),
+          ): GraphFactory => snapshotChildGraphFactory(parentHandlerRegistry),
         });
         this.registerSubagentExecutor(executor);
 
-        const subagentTool = tool(async (rawInput, config) => {
-          const input = rawInput as {
-            description?: string;
-            subagent_type?: string;
-            subagent_thread_id?: string;
-            run_in_background?: boolean;
-          };
-          const description =
-            typeof input.description === 'string' &&
-            input.description.trim().length > 0
-              ? input.description
-              : DEFAULT_SUBAGENT_DESCRIPTION;
-          const subagentType =
-            typeof input.subagent_type === 'string' ? input.subagent_type : '';
-          const subagentThreadId =
-            typeof input.subagent_thread_id === 'string' &&
-            input.subagent_thread_id.trim() !== ''
-              ? input.subagent_thread_id.trim()
-              : undefined;
-          const threadId = config.configurable?.thread_id as string | undefined;
-          /** Surface the parent call id so child checkpoints, interrupts, and
-           * update events remain correlated across replay and resume. */
-          const toolRuntime = config as {
-            toolCallId?: string;
-            toolCall?: { id?: string };
-          };
-          const toolCall = toolRuntime.toolCall;
-          let parentToolCallId: string | undefined;
-          if (
-            typeof toolRuntime.toolCallId === 'string' &&
-            toolRuntime.toolCallId !== ''
-          ) {
-            parentToolCallId = toolRuntime.toolCallId;
-          } else if (typeof toolCall?.id === 'string' && toolCall.id !== '') {
-            parentToolCallId = toolCall.id;
-          }
-          /** The parent tool batch's entry-captured scope (stamped by
-           * ToolNode before PreToolUse hooks) — binds this child to the
-           * run that dispatched it, not to whatever controller a reset
-           * installed while the hooks were awaited. */
-          const batchScope = config.configurable?.[
-            RUN_BREAKER_SCOPE_CONFIG_KEY
-          ] as RunBreakerScope | undefined;
-          const executeParams = {
-            description,
-            subagentType,
-            threadId,
-            signal: config.signal,
-            parentToolCallId,
-            breaker: batchScope?.controller,
-            /**
-             * Forward the parent's `configurable` so host-set fields
-             * (`requestBody`, `user`, etc.) propagate into the child
-             * workflow. The executor scrubs run-identity fields before
-             * forwarding — see `SubagentExecuteParams.parentConfigurable`.
-             */
-            parentConfigurable: config.configurable as
-              | Record<string, unknown>
-              | undefined,
-          };
-          if (input.run_in_background === true) {
-            return executor.executeInBackground({
-              ...executeParams,
-              ...(subagentThreadId == null
-                ? {}
-                : { subagentThreadId }),
-            });
-          }
-          if (subagentThreadId != null) {
-            return JSON.stringify({
-              status: 'rejected',
-              tool: Constants.SUBAGENT,
-              message:
-                'Child-thread continuation requires run_in_background.',
-            });
-          }
-          const result = await executor.execute(executeParams);
-          return result.content;
-        }, buildSubagentToolParams(executableConfigs, {
-          background: this.subagentTasks != null,
-          threadContinuation:
-            this.subagentTasks?.store.supportsThreadContinuation === true,
-        }));
+        const subagentTool = tool(
+          async (rawInput, config) => {
+            const input = rawInput as {
+              description?: string;
+              subagent_type?: string;
+              subagent_thread_id?: string;
+              run_in_background?: boolean;
+            };
+            const description =
+              typeof input.description === 'string' &&
+              input.description.trim().length > 0
+                ? input.description
+                : DEFAULT_SUBAGENT_DESCRIPTION;
+            const subagentType =
+              typeof input.subagent_type === 'string'
+                ? input.subagent_type
+                : '';
+            const subagentThreadId =
+              typeof input.subagent_thread_id === 'string' &&
+              input.subagent_thread_id.trim() !== ''
+                ? input.subagent_thread_id.trim()
+                : undefined;
+            const threadId = config.configurable?.thread_id as
+              | string
+              | undefined;
+            /** Surface the parent call id so child checkpoints, interrupts, and
+             * update events remain correlated across replay and resume. */
+            const toolRuntime = config as {
+              toolCallId?: string;
+              toolCall?: { id?: string };
+            };
+            const toolCall = toolRuntime.toolCall;
+            let parentToolCallId: string | undefined;
+            if (
+              typeof toolRuntime.toolCallId === 'string' &&
+              toolRuntime.toolCallId !== ''
+            ) {
+              parentToolCallId = toolRuntime.toolCallId;
+            } else if (typeof toolCall?.id === 'string' && toolCall.id !== '') {
+              parentToolCallId = toolCall.id;
+            }
+            /** The parent tool batch's entry-captured scope (stamped by
+             * ToolNode before PreToolUse hooks) — binds this child to the
+             * run that dispatched it, not to whatever controller a reset
+             * installed while the hooks were awaited. */
+            const batchScope = config.configurable?.[
+              RUN_BREAKER_SCOPE_CONFIG_KEY
+            ] as RunBreakerScope | undefined;
+            const executeParams = {
+              description,
+              subagentType,
+              threadId,
+              signal: config.signal,
+              parentToolCallId,
+              breaker: batchScope?.controller,
+              /**
+               * Forward the parent's `configurable` so host-set fields
+               * (`requestBody`, `user`, etc.) propagate into the child
+               * workflow. The executor scrubs run-identity fields before
+               * forwarding — see `SubagentExecuteParams.parentConfigurable`.
+               */
+              parentConfigurable: config.configurable as
+                | Record<string, unknown>
+                | undefined,
+            };
+            if (input.run_in_background === true) {
+              return executor.executeInBackground({
+                ...executeParams,
+                ...(subagentThreadId == null ? {} : { subagentThreadId }),
+              });
+            }
+            if (subagentThreadId != null) {
+              return JSON.stringify({
+                status: 'rejected',
+                tool: Constants.SUBAGENT,
+                message:
+                  'Child-thread continuation requires run_in_background.',
+              });
+            }
+            const result = await executor.execute(executeParams);
+            return result.content;
+          },
+          buildSubagentToolParams(executableConfigs, {
+            background: this.subagentTasks != null,
+            threadContinuation:
+              this.subagentTasks?.store.supportsThreadContinuation === true,
+          })
+        );
         const replayableSubagentTool = subagentTool as typeof subagentTool &
           ReplayableSubagentTool;
         replayableSubagentTool[SUBAGENT_REPLAY_CONTROLLER] = {
@@ -5218,7 +5238,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       .addEdge(summarizeNode, agentNode)
       .addEdge(toolNode, agentContext.toolEnd ? END : agentNode);
 
-    return workflow.compile();
+    return workflow.compile({ name: STANDARD_GRAPH_RUN_NAME });
   }
 
   createWorkflow(): t.CompiledStateWorkflow {
@@ -5247,11 +5267,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         >,
         { ends: [END] }
       )
-      .addEdge(START, this.defaultAgentId)
-      // LangGraph compile() types are overly strict for opt-in options
-      .compile(this.compileOptions as unknown as never);
+      .addEdge(START, this.defaultAgentId);
 
-    return workflow;
+    // LangGraph compile() types are overly strict for opt-in options
+    return workflow.compile({
+      ...this.compileOptions,
+      name: STANDARD_GRAPH_RUN_NAME,
+    } as unknown as never);
   }
 
   /**

package/src/graphs/MultiAgentGraph.ts

@@ -20,9 +20,9 @@ import type { ToolRuntime } from '@langchain/core/tools';
 import type { GraphFactoryDependencies } from '@/graphs/graphFactory';
 import type * as t from '@/types';
 import { serializeToolContentBounded } from '@/utils/toolContent';
+import { Constants, MULTI_AGENT_GRAPH_RUN_NAME } from '@/common';
 import { HARD_MAX_TOOL_RESULT_CHARS } from '@/utils/truncation';
 import { StandardGraph } from './Graph';
-import { Constants } from '@/common';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -177,6 +177,7 @@ function withHandoffGroupMetadata(
  * OR continues its workflow (direct edges), but not both simultaneously.
  */
 export class MultiAgentGraph extends StandardGraph {
+  override readonly runName = MULTI_AGENT_GRAPH_RUN_NAME;
   private edges: t.GraphEdge[];
   private startingNodes: Set<string> = new Set();
   private directEdges: t.GraphEdge[] = [];
@@ -1438,6 +1439,9 @@ export class MultiAgentGraph extends StandardGraph {
       }
     }
 
-    return builder.compile(this.compileOptions as unknown as never);
+    return builder.compile({
+      ...this.compileOptions,
+      name: MULTI_AGENT_GRAPH_RUN_NAME,
+    } as unknown as never);
   }
 }