@librechat/agents 3.2.56 → 3.2.58

package/src/langfuseTraceShaping.ts

@@ -0,0 +1,280 @@
+import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+
+const LANGGRAPH_START_NODE = '__start__';
+const ANONYMOUS_LAMBDA_NAME = 'RunnableLambda';
+const LANGGRAPH_AGENT_NODE_PREFIX = 'agent=';
+const LANGGRAPH_TOOL_NODE_PREFIX = 'tools=';
+const TOOL_BATCH_RUN_NAME = 'tool_batch';
+const AGENT_NODE_SPAN_NAME = 'agent';
+
+type MutableSpan = ReadableSpan & {
+  name: string;
+  attributes: Record<string, unknown>;
+};
+
+type SerializedToolCall = {
+  name: string;
+  args: unknown;
+  id?: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseAttributeValue(value: unknown): unknown {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+    return value;
+  }
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+function getMessageArray(
+  value: unknown
+): Record<string, unknown>[] | undefined {
+  if (Array.isArray(value)) {
+    const records = value.filter(isRecord);
+    return records.length > 0 ? records : undefined;
+  }
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  return (
+    getMessageArray(value.messages) ??
+    getMessageArray(value.input) ??
+    getMessageArray(value.output)
+  );
+}
+
+function getMessageRole(message: Record<string, unknown>): string | undefined {
+  const id = message.id;
+  if (Array.isArray(id)) {
+    const className = id[id.length - 1];
+    if (typeof className === 'string') {
+      if (className.includes('Human')) {
+        return 'user';
+      }
+      if (className.includes('AI')) {
+        return 'assistant';
+      }
+      if (className.includes('System')) {
+        return 'system';
+      }
+      if (className.includes('Tool')) {
+        return 'tool';
+      }
+    }
+  }
+  const rawRole =
+    message.type ?? message._type ?? message.role ?? message.sender;
+  if (typeof rawRole !== 'string') {
+    const kwargs = message.kwargs;
+    return isRecord(kwargs) ? getMessageRole(kwargs) : undefined;
+  }
+  const normalized = rawRole.toLowerCase();
+  if (normalized === 'human') {
+    return 'user';
+  }
+  if (normalized === 'ai') {
+    return 'assistant';
+  }
+  return normalized;
+}
+
+function getMessageText(message: Record<string, unknown>): string | undefined {
+  const content =
+    message.content ??
+    (isRecord(message.kwargs) ? message.kwargs.content : undefined) ??
+    (isRecord(message.data) ? message.data.content : undefined);
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return undefined;
+  }
+  const text = content
+    .filter(isRecord)
+    .map((part) => (typeof part.text === 'string' ? part.text : ''))
+    .join('');
+  return text === '' ? undefined : text;
+}
+
+function findLastMessageText(value: unknown, role: string): string | undefined {
+  const messages = getMessageArray(value);
+  if (messages == null) {
+    return undefined;
+  }
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (getMessageRole(messages[i]) !== role) {
+      continue;
+    }
+    const text = getMessageText(messages[i]);
+    if (text != null && text.trim() !== '') {
+      return text;
+    }
+  }
+  return undefined;
+}
+
+function normalizeToolCall(value: unknown): SerializedToolCall | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const fn = value.function;
+  if (isRecord(fn) && typeof fn.name === 'string') {
+    return {
+      name: fn.name,
+      args: parseAttributeValue(fn.arguments),
+      ...(typeof value.id === 'string' ? { id: value.id } : {}),
+    };
+  }
+  if (typeof value.name !== 'string') {
+    return undefined;
+  }
+  return {
+    name: value.name,
+    args: value.args ?? {},
+    ...(typeof value.id === 'string' ? { id: value.id } : {}),
+  };
+}
+
+function getMessageToolCalls(
+  message: Record<string, unknown>
+): SerializedToolCall[] {
+  const rawCalls =
+    message.tool_calls ??
+    (isRecord(message.kwargs) ? message.kwargs.tool_calls : undefined) ??
+    (isRecord(message.additional_kwargs)
+      ? message.additional_kwargs.tool_calls
+      : undefined) ??
+    (isRecord(message.data) ? message.data.tool_calls : undefined);
+  if (!Array.isArray(rawCalls)) {
+    return [];
+  }
+  const calls: SerializedToolCall[] = [];
+  for (const rawCall of rawCalls) {
+    const call = normalizeToolCall(rawCall);
+    if (call != null) {
+      calls.push(call);
+    }
+  }
+  return calls;
+}
+
+/** Latest assistant turn's tool calls — the calls this tool node is executing. */
+function findPendingToolCalls(value: unknown): SerializedToolCall[] {
+  const messages = getMessageArray(value);
+  if (messages == null) {
+    return [];
+  }
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (getMessageRole(messages[i]) !== 'assistant') {
+      continue;
+    }
+    const calls = getMessageToolCalls(messages[i]);
+    if (calls.length > 0) {
+      return calls;
+    }
+  }
+  return [];
+}
+
+function getRootSpanParentId(span: ReadableSpan): string | undefined {
+  const legacyParent = (span as { parentSpanId?: string }).parentSpanId;
+  if (typeof legacyParent === 'string' && legacyParent !== '') {
+    return legacyParent;
+  }
+  const parentContext = (span as { parentSpanContext?: { spanId?: string } })
+    .parentSpanContext;
+  const spanId = parentContext?.spanId;
+  return typeof spanId === 'string' && spanId !== '' ? spanId : undefined;
+}
+
+function isRootSpan(span: ReadableSpan): boolean {
+  return getRootSpanParentId(span) == null;
+}
+
+/**
+ * LangGraph plumbing observations that add noise without information:
+ * the duplicated `__start__` channel-seed nodes and anonymous
+ * `RunnableLambda` pass-throughs (Langfuse team feedback items 4 & 5).
+ */
+export function shouldDropLangfuseSpan(spanName: string): boolean {
+  return (
+    spanName === LANGGRAPH_START_NODE || spanName === ANONYMOUS_LAMBDA_NAME
+  );
+}
+
+function shapeToolNodeSpan(span: MutableSpan): void {
+  const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  const calls = findPendingToolCalls(
+    parseAttributeValue(span.attributes[inputKey])
+  );
+  if (calls.length === 0) {
+    return;
+  }
+  span.name = [...new Set(calls.map((call) => call.name))].join(', ');
+  span.attributes[inputKey] = JSON.stringify(
+    calls.map(({ name, args }) => ({ name, args }))
+  );
+}
+
+function shapeRootSpan(span: MutableSpan): void {
+  const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  const outputKey = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
+  const question = findLastMessageText(
+    parseAttributeValue(span.attributes[inputKey]),
+    'user'
+  );
+  const answer = findLastMessageText(
+    parseAttributeValue(span.attributes[outputKey]),
+    'assistant'
+  );
+  if (question != null) {
+    span.attributes[inputKey] = question;
+    span.attributes[LangfuseOtelSpanAttributes.TRACE_INPUT] = question;
+  }
+  if (answer != null) {
+    span.attributes[outputKey] = answer;
+    span.attributes[LangfuseOtelSpanAttributes.TRACE_OUTPUT] = answer;
+  }
+}
+
+/**
+ * Reshapes spans per Langfuse-team feedback before export:
+ * - `agent=<id>` / `tools=<id>` node names carry the ephemeral agent id
+ *   (`provider__model`) — strip it so switching models doesn't break
+ *   name-based logic (item 1).
+ * - Tool node spans are renamed to the actual tool name(s) and their
+ *   input scoped to the pending tool-call args instead of the whole
+ *   chat history (items 3 & 4).
+ * - The root span (and trace) input/output become the user question and
+ *   assistant response so the session view reads as a conversation
+ *   (item 2).
+ */
+export function shapeLangfuseSpan(span: ReadableSpan): void {
+  const mutable = span as MutableSpan;
+  if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
+    mutable.name = AGENT_NODE_SPAN_NAME;
+    return;
+  }
+  if (
+    mutable.name.startsWith(LANGGRAPH_TOOL_NODE_PREFIX) ||
+    mutable.name === TOOL_BATCH_RUN_NAME
+  ) {
+    shapeToolNodeSpan(mutable);
+    return;
+  }
+  if (isRootSpan(span)) {
+    shapeRootSpan(mutable);
+  }
+}

package/src/llm/anthropic/inherited-stream-events.spec.ts

@@ -32,7 +32,6 @@ import { HumanMessage } from '@langchain/core/messages';
 import { ChatModelStream } from '@langchain/core/language_models/stream';
 import type { BaseChatModelCallOptions } from '@langchain/core/language_models/chat_models';
 import type { ChatModelStreamEvent } from '@langchain/core/language_models/event';
-import type { Stream } from '@anthropic-ai/sdk/streaming';
 import type {
   AnthropicMessageStreamEvent,
   AnthropicRequestOptions,
@@ -57,10 +56,14 @@ class MockStreamChatAnthropic extends ChatAnthropic {
     this.mockEvents = mockEvents;
   }
 
+  // Inherit the base method's own Stream identity instead of importing
+  // @anthropic-ai/sdk/streaming here: the SDK ships dual .d.ts/.d.mts types,
+  // and an independent import can resolve to the other format's identity
+  // depending on compile order (flaky TS2416 in sharded CI).
   protected override async createStreamWithRetry(
     request: AnthropicStreamingMessageCreateParams,
     _options?: AnthropicRequestOptions
-  ): Promise<Stream<AnthropicMessageStreamEvent>> {
+  ): ReturnType<ChatAnthropic['createStreamWithRetry']> {
     this.capturedRequest = request;
     const events = this.mockEvents;
     return {
@@ -70,7 +73,7 @@ class MockStreamChatAnthropic extends ChatAnthropic {
           yield event as AnthropicMessageStreamEvent;
         }
       },
-    } as unknown as Stream<AnthropicMessageStreamEvent>;
+    } as unknown as Awaited<ReturnType<ChatAnthropic['createStreamWithRetry']>>;
   }
 }
 

package/src/run.ts

@@ -127,6 +127,7 @@ export class Run<_T extends t.BaseGraphState> {
   private langfuse?: t.LangfuseConfig;
   private toolOutputReferences?: t.ToolOutputReferencesConfig;
   private eagerEventToolExecution?: t.EagerEventToolExecutionConfig;
+  private codeSessionToolNames?: string[];
   private toolExecution?: t.ToolExecutionConfig;
   private subagentUsageSink?: t.SubagentUsageSink;
   private indexTokenCountMap?: Record<string, number>;
@@ -182,6 +183,7 @@ export class Run<_T extends t.BaseGraphState> {
     this.langfuse = config.langfuse;
     this.toolOutputReferences = config.toolOutputReferences;
     this.eagerEventToolExecution = config.eagerEventToolExecution;
+    this.codeSessionToolNames = config.codeSessionToolNames;
     this.toolExecution = config.toolExecution;
     this.subagentUsageSink = config.subagentUsageSink;
 
@@ -268,6 +270,7 @@ export class Run<_T extends t.BaseGraphState> {
     standardGraph.humanInTheLoop = this.humanInTheLoop;
     standardGraph.toolOutputReferences = this.toolOutputReferences;
     standardGraph.eagerEventToolExecution = this.eagerEventToolExecution;
+    standardGraph.codeSessionToolNames = this.codeSessionToolNames;
     standardGraph.toolExecution = this.toolExecution;
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
@@ -297,6 +300,7 @@ export class Run<_T extends t.BaseGraphState> {
     multiAgentGraph.humanInTheLoop = this.humanInTheLoop;
     multiAgentGraph.toolOutputReferences = this.toolOutputReferences;
     multiAgentGraph.eagerEventToolExecution = this.eagerEventToolExecution;
+    multiAgentGraph.codeSessionToolNames = this.codeSessionToolNames;
     multiAgentGraph.toolExecution = this.toolExecution;
     this.Graph = multiAgentGraph;
     return multiAgentGraph.createWorkflow();
@@ -1399,7 +1403,7 @@ export class Run<_T extends t.BaseGraphState> {
         inputText,
         skipLanguage,
       }),
-    }).withConfig({ runName: 'ConvoTransform' });
+    }).withConfig({ runName: 'PrepareTitleInput' });
 
     const titleChain =
       titleMethod === TitleMethod.COMPLETION
@@ -1408,10 +1412,10 @@ export class Run<_T extends t.BaseGraphState> {
 
     /** Pipes `convoTemplate` -> `transformer` -> `titleChain` */
     const fullChain = convoTemplate
-      .withConfig({ runName: 'ConvoTemplate' })
+      .withConfig({ runName: 'FormatConversation' })
       .pipe(convoToTitleInput)
       .pipe(titleChain)
-      .withConfig({ runName: 'TitleChain' });
+      .withConfig({ runName: 'GenerateConversationTitle' });
 
     const invokeConfig = Object.assign({}, chainOptions, {
       run_id: this.id,

package/src/specs/langfuse-routing.integration.test.ts

@@ -469,7 +469,7 @@ describe('Langfuse per-run routing integration', () => {
       expectNamedSpansUseTraceId({
         starts,
         traceId: titleTraceId,
-        names: [`LibreChat Title: Parent ${tenantId}`, 'CompletionTitleChain'],
+        names: [`LibreChat Title: Parent ${tenantId}`, 'GenerateTitle'],
       });
       expectNoCrossTenantTrace({
         tenantId,

package/src/specs/langfuse-trace-shaping.test.ts

@@ -0,0 +1,194 @@
+import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import {
+  shapeLangfuseSpan,
+  shouldDropLangfuseSpan,
+} from '@/langfuseTraceShaping';
+
+type TestSpan = ReadableSpan & {
+  name: string;
+  attributes: Record<string, unknown>;
+};
+
+function createSpan(
+  name: string,
+  attributes: Record<string, unknown> = {},
+  parentSpanId?: string
+): TestSpan {
+  return {
+    name,
+    attributes,
+    ...(parentSpanId != null ? { parentSpanId } : {}),
+  } as unknown as TestSpan;
+}
+
+const INPUT = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+const OUTPUT = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
+const TRACE_INPUT = LangfuseOtelSpanAttributes.TRACE_INPUT;
+const TRACE_OUTPUT = LangfuseOtelSpanAttributes.TRACE_OUTPUT;
+
+describe('shouldDropLangfuseSpan', () => {
+  it('drops langgraph __start__ seed spans', () => {
+    expect(shouldDropLangfuseSpan('__start__')).toBe(true);
+  });
+
+  it('drops anonymous RunnableLambda pass-throughs', () => {
+    expect(shouldDropLangfuseSpan('RunnableLambda')).toBe(true);
+  });
+
+  it('keeps named observations', () => {
+    expect(shouldDropLangfuseSpan('GenerateTitle')).toBe(false);
+    expect(shouldDropLangfuseSpan('agent=openAI__gpt-5.4')).toBe(false);
+    expect(shouldDropLangfuseSpan('ChatOpenAI')).toBe(false);
+  });
+});
+
+describe('shapeLangfuseSpan', () => {
+  it('strips the ephemeral agent id (provider__model) from agent node names', () => {
+    const span = createSpan('agent=openAI__gpt-5.4', {}, 'parent-1');
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('agent');
+  });
+
+  it('renames tool node spans to the pending tool names and scopes input to args', () => {
+    const messages = [
+      { type: 'human', content: 'hello' },
+      {
+        type: 'ai',
+        content: '',
+        tool_calls: [
+          {
+            name: 'get_service_details',
+            args: { path: 'organizations/1' },
+            id: 'call_1',
+          },
+        ],
+      },
+    ];
+    const span = createSpan(
+      'tools=openAI__gpt-5.4',
+      { [INPUT]: JSON.stringify({ messages }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('get_service_details');
+    expect(JSON.parse(span.attributes[INPUT] as string)).toEqual([
+      { name: 'get_service_details', args: { path: 'organizations/1' } },
+    ]);
+  });
+
+  it('joins multiple pending tool names and dedupes repeats', () => {
+    const messages = [
+      {
+        type: 'ai',
+        tool_calls: [
+          { name: 'web_search', args: { q: 'a' }, id: '1' },
+          { name: 'web_search', args: { q: 'b' }, id: '2' },
+          { name: 'execute_code', args: { code: '1+1' }, id: '3' },
+        ],
+      },
+    ];
+    const span = createSpan(
+      'tool_batch',
+      { [INPUT]: JSON.stringify({ messages }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('web_search, execute_code');
+  });
+
+  it('reads tool calls from serialized langchain message kwargs', () => {
+    const messages = [
+      {
+        lc: 1,
+        type: 'constructor',
+        id: ['langchain_core', 'messages', 'AIMessage'],
+        kwargs: {
+          content: '',
+          tool_calls: [{ name: 'lookup', args: { id: 7 }, id: 'call_7' }],
+        },
+      },
+    ];
+    const span = createSpan(
+      'tools=agent_abc',
+      { [INPUT]: JSON.stringify({ messages }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('lookup');
+  });
+
+  it('leaves tool node spans untouched when no tool calls are found', () => {
+    const original = JSON.stringify({
+      messages: [{ type: 'human', content: 'hi' }],
+    });
+    const span = createSpan(
+      'tools=agent_abc',
+      { [INPUT]: original },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('tools=agent_abc');
+    expect(span.attributes[INPUT]).toBe(original);
+  });
+
+  it('sets root span and trace input/output to the question and answer', () => {
+    const span = createSpan('LibreChat Agent', {
+      [INPUT]: JSON.stringify({
+        messages: [
+          { type: 'system', content: 'You are helpful.' },
+          { type: 'human', content: 'What is ClickHouse?' },
+        ],
+      }),
+      [OUTPUT]: JSON.stringify({
+        messages: [
+          { type: 'human', content: 'What is ClickHouse?' },
+          { type: 'ai', content: 'A columnar OLAP database.' },
+        ],
+      }),
+    });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe('What is ClickHouse?');
+    expect(span.attributes[TRACE_INPUT]).toBe('What is ClickHouse?');
+    expect(span.attributes[OUTPUT]).toBe('A columnar OLAP database.');
+    expect(span.attributes[TRACE_OUTPUT]).toBe('A columnar OLAP database.');
+  });
+
+  it('extracts answer text from content part arrays', () => {
+    const span = createSpan('LibreChat Agent', {
+      [INPUT]: JSON.stringify([{ type: 'human', content: 'hi' }]),
+      [OUTPUT]: JSON.stringify({
+        messages: [
+          {
+            id: ['langchain_core', 'messages', 'AIMessage'],
+            kwargs: {
+              content: [
+                { type: 'text', text: 'Hello ' },
+                { type: 'text', text: 'there.' },
+              ],
+            },
+          },
+        ],
+      }),
+    });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe('hi');
+    expect(span.attributes[OUTPUT]).toBe('Hello there.');
+  });
+
+  it('does not rewrite non-root spans with message payloads', () => {
+    const original = JSON.stringify({
+      messages: [{ type: 'human', content: 'hi' }],
+    });
+    const span = createSpan('ChatOpenAI', { [INPUT]: original }, 'parent-1');
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe(original);
+  });
+
+  it('preserves root attributes when extraction finds nothing', () => {
+    const span = createSpan('LibreChat Agent', { [INPUT]: 'plain text' });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe('plain text');
+    expect(span.attributes[TRACE_INPUT]).toBeUndefined();
+  });
+});

package/src/stream.ts

@@ -135,7 +135,14 @@ function isEagerExecutionExcludedTool(
     return false;
   }
   const excluded = graph.eagerEventToolExecution?.excludeToolNames;
-  return excluded != null && excluded.includes(name);
+  if (excluded != null && excluded.includes(name)) {
+    return true;
+  }
+  // A code-session participant writes to the shared sandbox, so it is
+  // side-effecting: never prestart it speculatively (a revised/superseded turn
+  // would leave the write applied). Implies exclusion without the host having
+  // to also list the name in excludeToolNames.
+  return graph.codeSessionToolNames?.includes(name) === true;
 }
 
 function isDirectGraphTool(
@@ -195,7 +202,8 @@ function getCodeSessionContext(
   if (
     !CODE_EXECUTION_TOOLS.has(name) &&
     name !== Constants.SKILL_TOOL &&
-    name !== Constants.READ_FILE
+    name !== Constants.READ_FILE &&
+    graph.codeSessionToolNames?.includes(name) !== true
   ) {
     return undefined;
   }

package/src/tools/ToolNode.ts

@@ -439,6 +439,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private eventDrivenMode: boolean = false;
   /** Opt-in stream-layer prestart config for event-driven tools. */
   private eagerEventToolExecution?: t.EagerEventToolExecutionConfig;
+  /** Host tools that write to the code sandbox and share its exec session. */
+  private codeSessionToolNames?: ReadonlySet<string>;
   /** Shared per-run prestarted tool registry populated by ChatModelStreamHandler. */
   private eagerEventToolExecutions?: Map<string, t.EagerEventToolExecution>;
   /** Shared per-run per-tool turn counter used by eager and normal event dispatch. */
@@ -515,6 +517,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     agentId,
     executingAgentId,
     directToolNames,
+    codeSessionToolNames,
     maxContextTokens,
     maxToolResultChars,
     hookRegistry,
@@ -552,6 +555,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     // existing agentId option) still get attribution without knowing the new option.
     this.executingAgentId = executingAgentId ?? agentId;
     this.directToolNames = directToolNames;
+    this.codeSessionToolNames =
+      codeSessionToolNames != null && codeSessionToolNames.length > 0
+        ? new Set(codeSessionToolNames)
+        : undefined;
     this.maxToolResultChars =
       maxToolResultChars ?? calculateMaxToolResultChars(maxContextTokens);
     this.hookRegistry = hookRegistry;
@@ -973,7 +980,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        * still need to travel through `_injected_files`; the legacy
        * `/files/<session_id>` fallback was removed from the executors.
        */
-      if (CODE_EXECUTION_TOOLS.has(call.name)) {
+      if (this.participatesInCodeSession(call.name)) {
         const codeSession = this.sessions?.get(Constants.EXECUTE_CODE) as
           | t.CodeSessionContext
           | undefined;
@@ -1759,6 +1766,23 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * Extracts code execution session context from tool results and stores in Graph.sessions.
    * Mirrors the session storage logic in handleRunToolCompletions for direct execution.
    */
+  /**
+   * True when a tool's successful result should fold its returned exec
+   * `session_id` into the shared code session: built-in `CODE_EXECUTION_TOOLS`,
+   * plus host-declared sandbox-writing tools (`codeSessionToolNames`, e.g.
+   * create_file/edit_file). Kept name-scoped rather than a blanket artifact
+   * opt-in so only host-declared tools can influence the shared session.
+   */
+  private participatesInCodeSession(name: string): boolean {
+    if (name === '') {
+      return false;
+    }
+    return (
+      CODE_EXECUTION_TOOLS.has(name) ||
+      this.codeSessionToolNames?.has(name) === true
+    );
+  }
+
   private storeCodeSessionFromResults(
     results: t.ToolExecuteResult[],
     requestMap: Map<string, t.ToolCallRequest>
@@ -1777,7 +1801,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       if (
         request?.name == null ||
         request.name === '' ||
-        (!CODE_EXECUTION_TOOLS.has(request.name) &&
+        (!this.participatesInCodeSession(request.name) &&
           request.name !== Constants.SKILL_TOOL)
       ) {
         continue;
@@ -1830,7 +1854,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         continue;
       }
 
-      if (this.sessions && CODE_EXECUTION_TOOLS.has(call.name)) {
+      if (this.sessions && this.participatesInCodeSession(call.name)) {
         const artifact = toolMessage.artifact as
           | t.CodeExecutionArtifact
           | undefined;
@@ -2463,7 +2487,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       const plan = buildToolExecutionRequestPlan({
         toolCalls: approvedEntries.map((entry) => {
           const codeSessionContext =
-            CODE_EXECUTION_TOOLS.has(entry.call.name) ||
+            this.participatesInCodeSession(entry.call.name) ||
             entry.call.name === Constants.SKILL_TOOL ||
             entry.call.name === Constants.READ_FILE
               ? this.getCodeSessionContext()