@librechat/agents 3.2.65 → 3.2.67

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/ToolSearch.ts

@@ -359,18 +359,48 @@ function simplifyParametersForSearch(
   return { type: parameters.type };
 }
 
+/**
+ * Splits one alphanumeric identifier segment on case boundaries without
+ * emitting artificial one-character acronym fragments.
+ */
+function splitCaseSegment(segment: string): string[] {
+  const splitTokens = segment
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+
+  if (splitTokens.length < 2) return splitTokens;
+
+  const mergedTokens: string[] = [];
+  let prefix = '';
+  for (const token of splitTokens) {
+    if (token.length === 1) {
+      prefix += token;
+      continue;
+    }
+    mergedTokens.push(`${prefix}${token}`);
+    prefix = '';
+  }
+
+  if (prefix && mergedTokens.length > 0) {
+    mergedTokens[mergedTokens.length - 1] += prefix;
+  }
+  return mergedTokens.length > 0 ? mergedTokens : [prefix];
+}
+
 /**
  * Tokenizes a string into lowercase words for BM25.
- * Splits on underscores and non-alphanumeric characters for consistent matching.
+ * Splits camelCase, underscores, and non-alphanumeric characters for consistent matching.
  * @param text - The text to tokenize
  * @returns Array of lowercase tokens
  */
 function tokenize(text: string): string[] {
   return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]/g, ' ')
-    .split(/\s+/)
-    .filter((token) => token.length > 0);
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .flatMap(splitCaseSegment);
 }
 
 /**
@@ -396,7 +426,7 @@ function createToolDocument(tool: t.ToolMetadata, fields: string[]): string {
     parts.push(paramNames);
   }
 
-  return parts.join(' ');
+  return tokenize(parts.join(' ')).join(' ');
 }
 
 /**
@@ -498,35 +528,63 @@ function performLocalSearch(
 
   const maxScore = Math.max(...scores.filter((s) => s > 0), 1);
   const queryLower = query.toLowerCase().trim();
+  const queryIdentifier = queryTokens.join('');
+  const matchesIdentifiers = fields.includes('name');
 
-  const results: t.ToolSearchResult[] = [];
+  const results: Array<{
+    result: t.ToolSearchResult;
+    identifierPriority: number;
+  }> = [];
   for (let i = 0; i < tools.length; i++) {
-    if (scores[i] > 0) {
-      const { field, snippet } = findMatchedField(
-        tools[i],
-        queryTokens,
-        fields
-      );
-      let normalizedScore = Math.min(scores[i] / maxScore, 1.0);
-
-      const baseName = getBaseToolName(tools[i].name).toLowerCase();
-      if (baseName === queryLower) {
+    const score = scores[i];
+    const hasSearchScore = Number.isFinite(score) && score > 0;
+    let identifierPriority = 0;
+    let normalizedScore = hasSearchScore ? Math.min(score / maxScore, 1.0) : 0;
+
+    if (matchesIdentifiers) {
+      const rawBaseName = getBaseToolName(tools[i].name).toLowerCase();
+      const rawFullName = tools[i].name.toLowerCase();
+      const baseIdentifier = tokenize(rawBaseName).join('');
+      const fullIdentifier = tokenize(rawFullName).join('');
+
+      if (rawFullName === queryLower) {
+        identifierPriority = 4;
+        normalizedScore = 1.0;
+      } else if (rawBaseName === queryLower) {
+        identifierPriority = 3;
+        normalizedScore = 1.0;
+      } else if (
+        baseIdentifier === queryIdentifier ||
+        fullIdentifier === queryIdentifier
+      ) {
+        identifierPriority = 2;
         normalizedScore = 1.0;
-      } else if (baseName.startsWith(queryLower)) {
+      } else if (baseIdentifier.startsWith(queryIdentifier)) {
+        identifierPriority = 1;
         normalizedScore = Math.max(normalizedScore, 0.95);
       }
+    }
+
+    if (!hasSearchScore && identifierPriority === 0) continue;
 
-      results.push({
+    const { field, snippet } = findMatchedField(tools[i], queryTokens, fields);
+    results.push({
+      result: {
         tool_name: tools[i].name,
         match_score: normalizedScore,
         matched_field: field,
         snippet,
-      });
-    }
+      },
+      identifierPriority,
+    });
   }
 
-  results.sort((a, b) => b.match_score - a.match_score);
-  const topResults = results.slice(0, maxResults);
+  results.sort(
+    (a, b) =>
+      b.identifierPriority - a.identifierPriority ||
+      b.result.match_score - a.result.match_score
+  );
+  const topResults = results.slice(0, maxResults).map(({ result }) => result);
 
   return {
     tool_references: topResults,

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');
   });
 });