@librechat/agents 3.2.64 → 3.2.66

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

@@ -25,6 +25,8 @@ type SpanStartRecord = {
   name: string;
   params: ProcessorParams;
   traceId: string;
+  spanId: string;
+  parentSpanId?: string;
 };
 
 const spanStarts: SpanStartRecord[] = [];
@@ -140,11 +142,15 @@ jest.mock('@langfuse/otel', () => ({
   LangfuseSpanProcessor: jest.fn().mockImplementation((params) => ({
     forceFlush: jest.fn(),
     onEnd: jest.fn(),
-    onStart: jest.fn((span) => {
+    onStart: jest.fn((span, parentContext) => {
+      const spanContext = span.spanContext();
+      const parentSpanId = otelTrace.getSpanContext(parentContext)?.spanId;
       spanStarts.push({
         name: span.name,
         params,
-        traceId: span.spanContext().traceId,
+        traceId: spanContext.traceId,
+        spanId: spanContext.spanId,
+        ...(parentSpanId != null ? { parentSpanId } : {}),
       });
     }),
     shutdown: jest.fn(),
@@ -190,7 +196,6 @@ function tenantLangfuse(tenantId: string): t.LangfuseConfig {
     deterministicTraceId: true,
     metadata: { tenantId },
     tags: [`tenant:${tenantId}`],
-    toolNodeTracing: { enabled: true },
     toolOutputTracing: { enabled: true },
   };
 }
@@ -239,6 +244,23 @@ function expectNamedSpansUseTraceId({
   }
 }
 
+function expectChildSpanParentName({
+  starts,
+  childName,
+  parentNamePrefix,
+}: {
+  starts: SpanStartRecord[];
+  childName: string;
+  parentNamePrefix: string;
+}): void {
+  const children = starts.filter((record) => record.name === childName);
+  expect(children).not.toHaveLength(0);
+  for (const child of children) {
+    const parent = starts.find((record) => record.spanId === child.parentSpanId);
+    expect(parent?.name.startsWith(parentNamePrefix)).toBe(true);
+  }
+}
+
 function expectOnlyTraceIds(
   starts: SpanStartRecord[],
   allowedTraceIds: string[]
@@ -446,6 +468,23 @@ describe('Langfuse per-run routing integration', () => {
     getChatModelClassSpy.mockRestore();
   });
 
+  it('keeps tool observations attached to the exported dispatch parent', async () => {
+    await runTenantFlow('tenant-hierarchy');
+
+    const starts = startsForTenant('tenant-hierarchy');
+    expect(starts.some((record) => record.name === 'tool_batch')).toBe(false);
+    expectChildSpanParentName({
+      starts,
+      childName: 'echo',
+      parentNamePrefix: 'tools=',
+    });
+    expectChildSpanParentName({
+      starts,
+      childName: 'subagent',
+      parentNamePrefix: 'tools=',
+    });
+  });
+
   it('routes parallel root, model, tool, subagent, and title spans to each run config', async () => {
     await Promise.all([runTenantFlow('tenant-a'), runTenantFlow('tenant-b')]);
 
@@ -462,10 +501,16 @@ describe('Langfuse per-run routing integration', () => {
         names: [
           `LibreChat Agent: Parent ${tenantId}`,
           'FakeChatModel',
-          'tool_batch',
+          'echo',
           'subagent',
         ],
       });
+      expect(starts.some((record) => record.name === 'tool_batch')).toBe(false);
+      expectChildSpanParentName({
+        starts,
+        childName: 'echo',
+        parentNamePrefix: 'tools=',
+      });
       expectNamedSpansUseTraceId({
         starts,
         traceId: titleTraceId,

package/src/specs/langfuse-tool-output-tracing.test.ts

@@ -118,7 +118,7 @@ describe('Langfuse tool output tracing redaction', () => {
     process.env = originalEnv;
   });
 
-  it('enables ToolNode tracing only when Langfuse is active by default', () => {
+  it('keeps internal ToolNode batch tracing opt-in', () => {
     delete process.env.LANGFUSE_SECRET_KEY;
     delete process.env.LANGFUSE_PUBLIC_KEY;
     delete process.env.LANGFUSE_BASE_URL;
@@ -132,7 +132,7 @@ describe('Langfuse tool output tracing redaction', () => {
           secretKey: 'sk-run',
         },
       })
-    ).toBe(true);
+    ).toBe(false);
     expect(
       shouldTraceToolNodeForLangfuse({
         agentLangfuse: {
@@ -149,7 +149,7 @@ describe('Langfuse tool output tracing redaction', () => {
     process.env.LANGFUSE_PUBLIC_KEY = 'pk-test';
     process.env.LANGFUSE_BASE_URL = 'https://langfuse.test';
 
-    expect(shouldTraceToolNodeForLangfuse({})).toBe(true);
+    expect(shouldTraceToolNodeForLangfuse({})).toBe(false);
     expect(
       shouldTraceToolNodeForLangfuse({
         runLangfuse: { toolNodeTracing: { enabled: true } },
@@ -162,7 +162,7 @@ describe('Langfuse tool output tracing redaction', () => {
     ).toBe(false);
   });
 
-  it('lets agent Langfuse enablement override disabled run defaults for ToolNode tracing', () => {
+  it('lets an agent explicitly opt into ToolNode batch tracing', () => {
     delete process.env.LANGFUSE_SECRET_KEY;
     delete process.env.LANGFUSE_PUBLIC_KEY;
     delete process.env.LANGFUSE_BASE_URL;
@@ -177,6 +177,7 @@ describe('Langfuse tool output tracing redaction', () => {
           publicKey: 'pk-agent',
           secretKey: 'sk-agent',
           baseUrl: 'https://langfuse.test',
+          toolNodeTracing: { enabled: true },
         },
       })
     ).toBe(true);

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

@@ -26,6 +26,8 @@ const INPUT = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
 const OUTPUT = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
 const TRACE_INPUT = LangfuseOtelSpanAttributes.TRACE_INPUT;
 const TRACE_OUTPUT = LangfuseOtelSpanAttributes.TRACE_OUTPUT;
+const OBSERVATION_TYPE = LangfuseOtelSpanAttributes.OBSERVATION_TYPE;
+const TRACE_TAGS = LangfuseOtelSpanAttributes.TRACE_TAGS;
 
 describe('shouldDropLangfuseSpan', () => {
   it('drops langgraph __start__ seed spans', () => {
@@ -40,6 +42,7 @@ describe('shouldDropLangfuseSpan', () => {
     expect(shouldDropLangfuseSpan('GenerateTitle')).toBe(false);
     expect(shouldDropLangfuseSpan('agent=openAI__gpt-5.4')).toBe(false);
     expect(shouldDropLangfuseSpan('ChatOpenAI')).toBe(false);
+    expect(shouldDropLangfuseSpan('tool_batch')).toBe(false);
   });
 });
 
@@ -48,9 +51,10 @@ describe('shapeLangfuseSpan', () => {
     const span = createSpan('agent=openAI__gpt-5.4', {}, 'parent-1');
     shapeLangfuseSpan(span);
     expect(span.name).toBe('agent');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('agent');
   });
 
-  it('renames tool node spans to the pending tool names and scopes input to args', () => {
+  it('shapes tool nodes as stable dispatch chains with scoped call inputs', () => {
     const messages = [
       { type: 'human', content: 'hello' },
       {
@@ -71,13 +75,14 @@ describe('shapeLangfuseSpan', () => {
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('get_service_details');
+    expect(span.name).toBe('tool-dispatch');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('chain');
     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', () => {
+  it('preserves every pending call in a multi-tool dispatch input', () => {
     const messages = [
       {
         type: 'ai',
@@ -89,12 +94,16 @@ describe('shapeLangfuseSpan', () => {
       },
     ];
     const span = createSpan(
-      'tool_batch',
+      'tools=openAI__gpt-5.4',
       { [INPUT]: JSON.stringify({ messages }) },
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('web_search, execute_code');
+    expect(JSON.parse(span.attributes[INPUT] as string)).toEqual([
+      { name: 'web_search', args: { q: 'a' } },
+      { name: 'web_search', args: { q: 'b' } },
+      { name: 'execute_code', args: { code: '1+1' } },
+    ]);
   });
 
   it('reads tool calls from serialized langchain message kwargs', () => {
@@ -115,10 +124,10 @@ describe('shapeLangfuseSpan', () => {
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('lookup');
+    expect(span.name).toBe('tool-dispatch');
   });
 
-  it('leaves tool node spans untouched when no tool calls are found', () => {
+  it('keeps a stable tool-dispatch shape when no tool calls are found', () => {
     const original = JSON.stringify({
       messages: [{ type: 'human', content: 'hi' }],
     });
@@ -128,12 +137,14 @@ describe('shapeLangfuseSpan', () => {
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('tools=agent_abc');
+    expect(span.name).toBe('tool-dispatch');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('chain');
     expect(span.attributes[INPUT]).toBe(original);
   });
 
   it('sets root span and trace input/output to the question and answer', () => {
     const span = createSpan('LibreChat Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
       [INPUT]: JSON.stringify({
         messages: [
           { type: 'system', content: 'You are helpful.' },
@@ -156,6 +167,7 @@ describe('shapeLangfuseSpan', () => {
 
   it('extracts answer text from content part arrays', () => {
     const span = createSpan('LibreChat Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
       [INPUT]: JSON.stringify([{ type: 'human', content: 'hi' }]),
       [OUTPUT]: JSON.stringify({
         messages: [
@@ -189,6 +201,65 @@ describe('shapeLangfuseSpan', () => {
     const span = createSpan('LibreChat Agent', { [INPUT]: 'plain text' });
     shapeLangfuseSpan(span);
     expect(span.attributes[INPUT]).toBe('plain text');
-    expect(span.attributes[TRACE_INPUT]).toBeUndefined();
+    expect(span.attributes[TRACE_INPUT]).toBe('plain text');
+  });
+
+  it('renames generation spans to a provider-agnostic name', () => {
+    const span = createSpan(
+      'ChatOpenAI',
+      { [OBSERVATION_TYPE]: 'generation' },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('llm');
+  });
+
+  it('marks only agent-tagged root spans as agent observations', () => {
+    const span = createSpan('LibreChat Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
+      [INPUT]: JSON.stringify({
+        messages: [{ type: 'human', content: 'hi' }],
+      }),
+    });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('agent');
+  });
+
+  it('marks title-tagged root spans as chain observations', () => {
+    const span = createSpan('LibreChat Title', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'title']),
+      [INPUT]: 'Conversation text',
+      [OUTPUT]: 'Conversation title',
+    });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('chain');
+    expect(span.attributes[TRACE_INPUT]).toBe('Conversation text');
+    expect(span.attributes[TRACE_OUTPUT]).toBe('Conversation title');
+  });
+
+  it('does not classify untagged root spans as agents', () => {
+    const span = createSpan('Custom root', { [INPUT]: 'input' });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.attributes[OBSERVATION_TYPE]).toBeUndefined();
+  });
+
+  it('shapes standalone generation roots without replacing their type', () => {
+    const span = createSpan('ChatOpenAI', {
+      [OBSERVATION_TYPE]: 'generation',
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'title']),
+      [INPUT]: 'Generate a title',
+      [OUTPUT]: 'A useful title',
+    });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.name).toBe('llm');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('generation');
+    expect(span.attributes[TRACE_INPUT]).toBe('Generate a title');
+    expect(span.attributes[TRACE_OUTPUT]).toBe('A useful title');
   });
 });

package/src/specs/subagent.test.ts

@@ -312,6 +312,186 @@ describe('Subagent Integration', () => {
     createWorkflowSpy.mockRestore();
   });
 
+  it('forwards event-driven tools through nested child graphs', async () => {
+    const originalCreateWorkflow = StandardGraph.prototype.createWorkflow;
+    const parentToolHandler = jest.fn(
+      (_event: string, rawData: unknown): void => {
+        const request = rawData as t.ToolExecuteBatchRequest;
+        request.resolve(
+          request.toolCalls.map((call) => ({
+            toolCallId: call.id,
+            status: 'success' as const,
+            content: `ran ${call.name}`,
+          }))
+        );
+      }
+    );
+    const parentUpdateHandler = jest.fn();
+    let specialistToolDefinitions: t.LCTool[] | undefined;
+    let forwardedToolResults: t.ToolExecuteResult[] | undefined;
+
+    const createWorkflowSpy = jest
+      .spyOn(StandardGraph.prototype, 'createWorkflow')
+      .mockImplementation(function (this: StandardGraph) {
+        const workflow = originalCreateWorkflow.call(this);
+        if (this.defaultAgentId === 'router') {
+          return {
+            invoke: jest.fn(async () => {
+              const routerContext = this.agentContexts.get('router');
+              const nestedTool = (
+                routerContext?.graphTools as t.GenericTool[] | undefined
+              )?.find(
+                (tool) => 'name' in tool && tool.name === Constants.SUBAGENT
+              );
+              if (nestedTool == null) {
+                throw new Error('Nested subagent tool was not created');
+              }
+              await nestedTool.invoke(
+                {
+                  description: 'Use the event-driven lookup tool.',
+                  subagent_type: 'specialist',
+                },
+                callerConfig
+              );
+              return { messages: [new AIMessage('router done')] };
+            }),
+          } as unknown as ReturnType<StandardGraph['createWorkflow']>;
+        }
+        if (this.defaultAgentId === 'specialist') {
+          specialistToolDefinitions =
+            this.agentContexts.get('specialist')?.toolDefinitions;
+          return {
+            invoke: jest.fn(async (_state, options) => {
+              const invokeOptions = options as
+                | { callbacks?: unknown[] }
+                | undefined;
+              const forwarder = (invokeOptions?.callbacks ?? [])[0] as
+                | {
+                    handleCustomEvent?: (
+                      eventName: string,
+                      data: unknown,
+                      runId: string
+                    ) => Promise<void> | void;
+                  }
+                | undefined;
+              if (forwarder?.handleCustomEvent != null) {
+                forwardedToolResults = await new Promise<t.ToolExecuteResult[]>(
+                  (resolve, reject) => {
+                    const request: t.ToolExecuteBatchRequest = {
+                      toolCalls: [
+                        { id: 'nested-call', name: 'mcp_lookup', args: {} },
+                      ],
+                      agentId: 'specialist',
+                      resolve,
+                      reject,
+                    };
+                    void forwarder.handleCustomEvent?.(
+                      GraphEvents.ON_TOOL_EXECUTE,
+                      request,
+                      'specialist-run'
+                    );
+                  }
+                );
+                await forwarder.handleCustomEvent(
+                  GraphEvents.ON_RUN_STEP,
+                  { id: 'specialist-step', type: 'tool_calls' },
+                  'specialist-run'
+                );
+              }
+              return { messages: [new AIMessage('specialist done')] };
+            }),
+          } as unknown as ReturnType<StandardGraph['createWorkflow']>;
+        }
+        return workflow;
+      });
+
+    const rootAgent: t.AgentInputs = {
+      agentId: 'root',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Delegate through the router.',
+      maxContextTokens: 8000,
+      maxSubagentDepth: 2,
+      subagentConfigs: [
+        {
+          type: 'router',
+          name: 'Router',
+          description: 'Routes work to specialists.',
+          allowNested: true,
+          agentInputs: {
+            agentId: 'router',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'Delegate to the specialist.',
+            maxContextTokens: 8000,
+            subagentConfigs: [
+              {
+                type: 'specialist',
+                name: 'Specialist',
+                description: 'Uses an event-driven tool.',
+                agentInputs: {
+                  agentId: 'specialist',
+                  provider: Providers.OPENAI,
+                  clientOptions: {
+                    modelName: 'gpt-4o-mini',
+                    apiKey: 'test-key',
+                  },
+                  instructions: 'Use the lookup tool.',
+                  maxContextTokens: 8000,
+                  toolDefinitions: [{ name: 'mcp_lookup' }],
+                },
+              },
+            ],
+          },
+        },
+      ],
+    };
+
+    try {
+      const run = await Run.create<t.IState>({
+        runId: `nested-event-tools-${Date.now()}`,
+        graphConfig: { type: 'standard', agents: [rootAgent] },
+        customHandlers: {
+          [GraphEvents.ON_TOOL_EXECUTE]: { handle: parentToolHandler },
+          [GraphEvents.ON_SUBAGENT_UPDATE]: {
+            handle: parentUpdateHandler,
+          },
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+      const rootContext = (run.Graph as StandardGraph).agentContexts.get(
+        'root'
+      );
+      const rootSubagentTool = (
+        rootContext?.graphTools as t.GenericTool[] | undefined
+      )?.find((tool) => 'name' in tool && tool.name === Constants.SUBAGENT);
+      expect(rootSubagentTool).toBeDefined();
+
+      await rootSubagentTool!.invoke(
+        { description: 'Route this task.', subagent_type: 'router' },
+        callerConfig
+      );
+
+      expect(specialistToolDefinitions).toEqual([{ name: 'mcp_lookup' }]);
+      expect(parentToolHandler).toHaveBeenCalledTimes(1);
+      expect(forwardedToolResults).toEqual([
+        {
+          toolCallId: 'nested-call',
+          status: 'success',
+          content: 'ran mcp_lookup',
+        },
+      ]);
+      const forwardedSubagentTypes = parentUpdateHandler.mock.calls.map(
+        ([, data]) => (data as t.SubagentUpdateEvent).subagentType
+      );
+      expect(forwardedSubagentTypes).toContain('router');
+      expect(forwardedSubagentTypes).not.toContain('specialist');
+    } finally {
+      createWorkflowSpy.mockRestore();
+    }
+  });
+
   it('should not create subagent tool when maxSubagentDepth is 0', async () => {
     const agentWithZeroDepth: t.AgentInputs = {
       ...createParentAgent(),

package/src/tools/BashExecutor.ts

@@ -58,17 +58,18 @@ Usage:
 `.trim();
 
 /**
- * Bash statefulness is filesystem-tier: on a warm session the machine (files
- * including /tmp, installed packages, background processes) persists between
- * calls, but each call may start a fresh shell — so shell variables and cwd
- * are NOT reliable, and the machine can be reset at any time. Only /mnt/data
- * is durable.
+ * Bash statefulness is filesystem-tier and scoped to `/mnt/data`. The machine
+ * is warm across calls, but each call runs in a fresh sandbox (new process
+ * tree + private /tmp), so background processes are reaped when the call ends
+ * and anything written outside /mnt/data is discarded. The note must not
+ * promise otherwise: a model told background processes survive will start a
+ * server in one call and assume it is listening in the next.
  */
 export const STATEFUL_BASH_NOTE =
-  'Session state (best-effort): commands in this conversation usually run on the same machine, so files (including /tmp), installed packages, and running background processes from earlier calls typically persist. Each call may still start a fresh shell — do not rely on shell variables or the working directory carrying over — and the machine may be reset at any time. Only /mnt/data is durable.';
+  'Session state: commands in this conversation run on the same warm machine, so files written to /mnt/data persist between calls. Each call runs in a fresh, isolated sandbox: shell variables, the working directory, /tmp, and background processes do NOT survive after the call returns — a process started in one call is terminated when that call ends. Only /mnt/data is durable (the machine itself may also be reset at any time).';
 
 export const StatefulBashExecutionToolDescription = `
-Runs bash commands and returns stdout/stderr output from a session-based execution environment, similar to a long-running machine.
+Runs bash commands and returns stdout/stderr output. Commands in this conversation share one warm machine with a persistent /mnt/data, but each command runs in its own isolated sandbox (not a persistent shell session).
 
 ${STATEFUL_BASH_NOTE}
 
@@ -125,7 +126,7 @@ export function buildBashExecutionToolDescription(options?: {
 const STATELESS_BASH_PARAM_NOTE =
   'The environment is stateless; variables and state don\'t persist between executions.';
 const STATEFUL_BASH_PARAM_NOTE =
-  'Files, installed packages, and background processes usually persist between calls, but each call may start a fresh shell (do not rely on shell variables or cwd) and the machine may reset. Only /mnt/data is durable.';
+  'Files written to /mnt/data persist between calls on the same warm machine. Each call runs in a fresh sandbox: shell variables, cwd, /tmp, and background processes do NOT survive the call. Only /mnt/data is durable.';
 
 export function buildBashExecutionToolSchema(opts?: {
   statefulSessions?: boolean;

package/src/tools/CodeExecutor.ts

@@ -150,16 +150,18 @@ Usage:
 `.trim();
 
 /**
- * Best-effort statefulness note. Deliberately hedged: warm reuse is an
- * optimization, not a guarantee (the runtime may be reset on idle timeout,
- * eviction, or the 8h VM lifetime), so the model must never depend on carried
- * state for correctness and must persist anything durable to /mnt/data.
+ * Statefulness here is FILESYSTEM-tier, not runtime-tier. Executions in a
+ * session reuse one warm machine, so `/mnt/data` carries across calls — but
+ * every execution is a brand-new interpreter process in a fresh sandbox, so
+ * variables and imports never survive. The note must not imply otherwise: a
+ * model told its in-memory state persists writes `df = ...` in one call and
+ * `df.head()` in the next, then hits a NameError it was told to treat as rare.
  */
 export const STATEFUL_ENV_NOTE =
-  'Session state (best-effort): consecutive executions in this conversation usually share one runtime, so variables, imports, and in-memory data from earlier successful calls are typically still available. The runtime may be reset at any time, so treat carried-over state as an optimization, never a guarantee. Anything that must survive MUST be written to /mnt/data. If a NameError/ImportError signals lost state, re-run the needed setup and continue.';
+  'Session state: executions in this conversation run on the same warm machine, so files persist between calls — but each execution is a NEW process. Variables, imports, and in-memory data NEVER carry over: every call must re-import and rebuild the state it needs. Only /mnt/data is durable (the machine itself may also be reset at any time), so write anything that must survive there and read it back next call.';
 
 export const StatefulCodeExecutionToolDescription = `
-Runs code and returns stdout/stderr output from a session-based execution environment, similar to a long-running command-line session.
+Runs code and returns stdout/stderr output. Executions in this conversation share one warm machine with a persistent /mnt/data, but each execution runs as a separate process (not a notebook-style kernel).
 
 ${STATEFUL_ENV_NOTE}
 
@@ -181,7 +183,7 @@ export function buildCodeExecutionToolDescription(opts?: {
 const STATELESS_CODE_PARAM_NOTE =
   'The environment is stateless; variables and imports don\'t persist between executions.';
 const STATEFUL_CODE_PARAM_NOTE =
-  'Executions in this conversation usually share one runtime: variables and imports from prior successful calls are typically still defined, but the runtime may reset between calls. Rebuild state on NameError/ImportError; persist anything important to /mnt/data.';
+  'Executions in this conversation share one warm machine, so files written to /mnt/data persist between calls. Each execution is a new process: variables and imports do NOT carry over — re-import and reload from /mnt/data every call.';
 
 export function buildCodeExecutionToolSchema(opts?: {
   statefulSessions?: boolean;

package/src/tools/__tests__/BashExecutor.test.ts

@@ -65,13 +65,24 @@ describe('buildBashExecutionToolDescription', () => {
       ).toBe(StatefulBashExecutionToolDescription);
     });
 
-    it('hedges: usually-persists but may-reset, and only /mnt/data is durable', () => {
+    /* Filesystem-tier only: each call runs in a fresh sandbox (new process
+     * tree + private /tmp), so background processes are reaped and non-
+     * /mnt/data writes are discarded. The description must not promise
+     * otherwise. */
+    it('promises /mnt/data persistence WITHOUT promising surviving processes or /tmp', () => {
       const d = StatefulBashExecutionToolDescription;
-      expect(d).toContain('usually');
-      expect(d).toContain('may be reset');
+      expect(d).toContain('same warm machine');
       expect(d).toContain('Only /mnt/data is durable');
-      /* filesystem-tier, not shell-variable-tier */
-      expect(d).toContain('do not rely on shell variables');
+      expect(d).toContain('background processes do NOT survive');
+      expect(d).toContain('/tmp');
+    });
+
+    it('never claims /tmp or background processes persist between calls', () => {
+      const d = StatefulBashExecutionToolDescription;
+      expect(d).not.toContain('files (including /tmp)');
+      expect(d).not.toContain(
+        'background processes from earlier calls typically persist'
+      );
     });
 
     it('keeps the artifact-path guidance in both variants', () => {

package/src/tools/__tests__/CodeExecutor.stateful.test.ts

@@ -41,22 +41,33 @@ describe('CodeExecutor stateful description', () => {
     );
   });
 
-  it('hedges the stateful wording and keeps /mnt/data as the durable store', () => {
+  /* Statefulness is filesystem-tier only: the machine is warm across calls,
+   * but every execution is a new interpreter process, so in-memory state never
+   * carries over. The description must not imply a notebook-style kernel. */
+  it('promises filesystem persistence WITHOUT promising a shared runtime', () => {
     const d = StatefulCodeExecutionToolDescription;
-    expect(d).toContain('usually share one runtime');
-    expect(d).toContain('may be reset at any time');
-    expect(d).toContain('MUST be written to /mnt/data');
+    expect(d).toContain('same warm machine');
+    expect(d).toContain('/mnt/data');
+    expect(d).toContain('NEW process');
+    expect(d).toContain('NEVER carry over');
     expect(d).toContain(CODE_ARTIFACT_PATH_GUIDANCE);
   });
 
+  it('never claims variables/imports survive between executions', () => {
+    const d = StatefulCodeExecutionToolDescription;
+    expect(d).not.toContain('share one runtime');
+    expect(d).not.toContain('typically still available');
+  });
+
   it('adjusts the code-param note per mode', () => {
     const stateless =
       buildCodeExecutionToolSchema().properties.code.description;
     const stateful = buildCodeExecutionToolSchema({ statefulSessions: true })
       .properties.code.description;
     expect(stateless).toContain('variables and imports don\'t persist');
-    expect(stateful).toContain('typically still defined');
-    expect(stateful).toContain('may reset between calls');
+    expect(stateful).toContain('do NOT carry over');
+    expect(stateful).toContain('/mnt/data');
+    expect(stateful).not.toContain('typically still defined');
   });
 });