@librechat/agents 3.2.42 → 3.2.43

package/src/graphs/Graph.ts

@@ -28,6 +28,7 @@ import {
   syncBudgetDerivedFields,
   addTailCacheControl,
   resolvePromptCacheTtl,
+  resolveBedrockPromptCacheTtl,
   supportsBedrockToolCache,
   getMessageId,
   makeIsDeferred,
@@ -1880,9 +1881,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         const bedrockOptions = agentContext.clientOptions as
           | t.BedrockAnthropicClientOptions
           | undefined;
+        // Non-Claude models (Nova) reject the extended 1h TTL, so resolve it
+        // against the model — message/system caching stays on, clamped to 5m.
         finalMessages = addBedrockTailCacheControl<BaseMessage>(
           finalMessages,
-          resolvePromptCacheTtl(bedrockOptions?.promptCacheTtl)
+          resolveBedrockPromptCacheTtl(
+            bedrockOptions?.promptCacheTtl,
+            (bedrockOptions as { model?: string } | undefined)?.model
+          )
         );
       }
 

package/src/llm/bedrock/index.ts

@@ -40,7 +40,7 @@ import {
   handleConverseStreamMetadata,
 } from './utils';
 import {
-  resolvePromptCacheTtl,
+  resolveBedrockPromptCacheTtl,
   supportsBedrockToolCache,
   type PromptCacheTtl,
 } from '@/messages/cache';
@@ -184,7 +184,7 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
         ? insertBedrockToolCachePoint(
           baseParams.toolConfig,
           true,
-          resolvePromptCacheTtl(this.promptCacheTtl)
+          resolveBedrockPromptCacheTtl(this.promptCacheTtl, this.cacheModelId)
         )
         : baseParams.toolConfig;
 

package/src/messages/cache.test.ts

@@ -19,6 +19,7 @@ import {
   buildAnthropicCacheControl,
   buildBedrockCachePoint,
   resolvePromptCacheTtl,
+  resolveBedrockPromptCacheTtl,
   supportsBedrockToolCache,
   DEFAULT_PROMPT_CACHE_TTL,
 } from './cache';
@@ -926,6 +927,37 @@ describe('supportsBedrockToolCache', () => {
   });
 });
 
+describe('resolveBedrockPromptCacheTtl', () => {
+  test('Claude: defaults to 1h and honors an explicit ttl', () => {
+    const claude = 'us.anthropic.claude-sonnet-4-5-20250929-v1:0';
+    expect(resolveBedrockPromptCacheTtl(undefined, claude)).toBe('1h');
+    expect(resolveBedrockPromptCacheTtl('1h', claude)).toBe('1h');
+    expect(resolveBedrockPromptCacheTtl('5m', claude)).toBe('5m');
+  });
+
+  test('Nova: clamps to 5m even when 1h is configured (extended TTL Anthropic-only)', () => {
+    const nova = 'us.amazon.nova-lite-v1:0';
+    expect(resolveBedrockPromptCacheTtl(undefined, nova)).toBe('5m');
+    expect(resolveBedrockPromptCacheTtl('1h', nova)).toBe('5m');
+    expect(resolveBedrockPromptCacheTtl('5m', nova)).toBe('5m');
+  });
+
+  test('other non-Claude families clamp to 5m', () => {
+    expect(
+      resolveBedrockPromptCacheTtl('1h', 'meta.llama3-1-70b-instruct-v1:0')
+    ).toBe('5m');
+    expect(
+      resolveBedrockPromptCacheTtl('1h', 'mistral.mistral-large-2407-v1:0')
+    ).toBe('5m');
+  });
+
+  test('omitted model defaults to Claude behavior (1h)', () => {
+    expect(resolveBedrockPromptCacheTtl(undefined, undefined)).toBe('1h');
+    expect(resolveBedrockPromptCacheTtl(undefined, null)).toBe('1h');
+    expect(resolveBedrockPromptCacheTtl('1h', undefined)).toBe('1h');
+  });
+});
+
 describe('stripAnthropicCacheControl', () => {
   it('removes cache_control fields from content blocks', () => {
     const messages: TestMsg[] = [

package/src/messages/cache.ts

@@ -79,6 +79,16 @@ export function buildBedrockCachePoint(
   return ttl === '1h' ? { type: 'default', ttl: '1h' } : { type: 'default' };
 }
 
+/**
+ * Whether a Bedrock model id is an Anthropic Claude model. Claude is the only
+ * Bedrock family that accepts the explicit cache features below; Amazon Nova and
+ * others reject them. Matches both the `anthropic.` and cross-region
+ * (`us.anthropic.`) / bare `claude` forms.
+ */
+function isBedrockAnthropicModel(model: string | undefined | null): boolean {
+  return typeof model === 'string' && /claude|anthropic/i.test(model);
+}
+
 /**
  * A `cachePoint` under `toolConfig.tools` is only accepted on Anthropic Claude
  * models. Amazon Nova rejects it outright — `Malformed input request:
@@ -89,8 +99,7 @@ export function buildBedrockCachePoint(
  *
  * Gate ONLY the tool checkpoint on this, so a `promptCache: true` config on Nova
  * keeps its valid message/system caching instead of either 400-ing (tool point)
- * or losing caching entirely. This is a capability gate (the key is rejected
- * outright), distinct from the TTL value which Bedrock downgrades gracefully.
+ * or losing caching entirely.
  *
  * @see https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
  * @see https://github.com/danny-avila/LibreChat/issues/13838
@@ -98,10 +107,27 @@ export function buildBedrockCachePoint(
 export function supportsBedrockToolCache(
   model: string | undefined | null
 ): boolean {
-  if (typeof model !== 'string') {
-    return false;
+  return isBedrockAnthropicModel(model);
+}
+
+/**
+ * Resolve the Bedrock `cachePoint` TTL for a model. The extended `1h` TTL is
+ * Anthropic-only: non-Claude models (e.g. Nova) hard-reject it with
+ * `Extended TTL prompt caching is only supported for Anthropic models`, so they
+ * are clamped to `5m` even when `1h` is configured (verified live). An omitted
+ * model defaults to a Claude model, and Claude downgrades an unsupported `1h` to
+ * `5m` server-side, so the `1h` default is safe for the Claude/undefined paths.
+ *
+ * @see https://github.com/danny-avila/LibreChat/issues/13838
+ */
+export function resolveBedrockPromptCacheTtl(
+  ttl: PromptCacheTtl | undefined,
+  model: string | undefined | null
+): PromptCacheTtl {
+  if (model != null && !isBedrockAnthropicModel(model)) {
+    return '5m';
   }
-  return /claude|anthropic/i.test(model);
+  return resolvePromptCacheTtl(ttl);
 }
 
 /**

package/src/specs/vllm-reasoning-toolcalls.test.ts

@@ -0,0 +1,340 @@
+/**
+ * Regression coverage for a generic `custom` OpenAI-compatible endpoint
+ * (provider `openai`, non-OpenAI `baseURL`, default `reasoningKey`,
+ * non-standard model name) that streams reasoning in the modern vLLM
+ * `reasoning` field — `reasoning_content` is `null` throughout — and streams
+ * `tool_calls` with fragmented arguments (vLLM `--reasoning-parser qwen3` +
+ * `--tool-call-parser qwen3_coder`).
+ *
+ * A non-OpenAI `baseURL` is required so the model stays on the custom-endpoint
+ * (final-signal) path rather than the official-OpenAI sequential-seal path.
+ *
+ * The wire shapes mirror the captures in LibreChat discussion #13849:
+ *   - reasoning must surface as `think` content (the Thoughts block), and
+ *   - the fragmented streamed tool call must be assembled by the graph into a
+ *     structured call and executed.
+ */
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import type { UsageMetadata } from '@langchain/core/messages';
+import type { OpenAIClient } from '@langchain/openai';
+import type * as t from '@/types';
+import { ContentTypes, GraphEvents, Providers, StepTypes } from '@/common';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { createContentAggregator } from '@/stream';
+import { ChatOpenAI } from '@/llm/openai';
+import { Run } from '@/run';
+
+type CompletionChunk = OpenAIClient.Chat.Completions.ChatCompletionChunk;
+type CompletionChoice =
+  OpenAIClient.Chat.Completions.ChatCompletionChunk.Choice;
+type CompletionDelta = CompletionChoice['delta'] & {
+  reasoning?: string | null;
+  reasoning_content?: string | null;
+};
+type StreamingCompletions = {
+  completionWithRetry: () => Promise<AsyncIterable<CompletionChunk>>;
+};
+
+const MODEL = 'custom_llm_thinking';
+const BASE_URL = 'http://vllm.internal:8000/v1';
+
+function completionChunk(
+  delta: CompletionDelta,
+  finishReason: CompletionChoice['finish_reason'] = null
+): CompletionChunk {
+  return {
+    id: 'chatcmpl-vllm',
+    object: 'chat.completion.chunk',
+    created: 0,
+    model: MODEL,
+    choices: [{ index: 0, delta, finish_reason: finishReason }],
+  };
+}
+
+function customEndpointModel(): ChatOpenAI {
+  return new ChatOpenAI({
+    model: MODEL,
+    apiKey: 'test-key',
+    streaming: true,
+    configuration: { baseURL: BASE_URL },
+  });
+}
+
+function setCompletionStream(
+  model: ChatOpenAI,
+  stream: () => AsyncIterable<CompletionChunk>
+): void {
+  (
+    model as unknown as { completions: StreamingCompletions }
+  ).completions.completionWithRetry = async () => stream();
+}
+
+describe('custom OpenAI-compatible endpoint (vLLM reasoning + qwen3_coder tool calls)', () => {
+  const config = {
+    configurable: { thread_id: 'vllm-reasoning-toolcalls' },
+    streamMode: 'values' as const,
+    version: 'v2' as const,
+  };
+
+  it('renders reasoning from delta.reasoning when reasoning_content is null', async () => {
+    const reasoningTokens = [
+      'Here',
+      '\'s a thinking',
+      ' process: 17*23',
+      ' = 391',
+    ];
+    const contentTokens = ['\n\nUm ', '17 ×', ' 23 = **391', '**.'];
+
+    const reasoningDeltas: t.ReasoningDeltaEvent[] = [];
+    const messageDeltas: t.MessageDeltaEvent[] = [];
+    const { contentParts, aggregateContent } = createContentAggregator();
+
+    const run = await Run.create<t.IState>({
+      runId: 'vllm-reasoning',
+      graphConfig: {
+        type: 'standard',
+        llmConfig: { provider: Providers.OPENAI, streamUsage: false },
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers: {
+        [GraphEvents.ON_RUN_STEP]: {
+          handle: (
+            event: GraphEvents.ON_RUN_STEP,
+            data: t.StreamEventData
+          ): void => aggregateContent({ event, data: data as t.RunStep }),
+        },
+        [GraphEvents.ON_MESSAGE_DELTA]: {
+          handle: (
+            event: GraphEvents.ON_MESSAGE_DELTA,
+            data: t.StreamEventData
+          ): void => {
+            messageDeltas.push(data as t.MessageDeltaEvent);
+            aggregateContent({ event, data: data as t.MessageDeltaEvent });
+          },
+        },
+        [GraphEvents.ON_REASONING_DELTA]: {
+          handle: (
+            event: GraphEvents.ON_REASONING_DELTA,
+            data: t.StreamEventData
+          ): void => {
+            reasoningDeltas.push(data as t.ReasoningDeltaEvent);
+            aggregateContent({ event, data: data as t.ReasoningDeltaEvent });
+          },
+        },
+      },
+    });
+    if (!run.Graph) {
+      throw new Error('Expected graph to be initialized');
+    }
+
+    const model = customEndpointModel();
+    setCompletionStream(
+      model,
+      async function* streamChunks(): AsyncGenerator<CompletionChunk> {
+        yield completionChunk({ role: 'assistant', content: '' });
+        for (const reasoning of reasoningTokens) {
+          yield completionChunk({
+            reasoning,
+            reasoning_content: null,
+            content: null,
+          });
+        }
+        for (let i = 0; i < contentTokens.length; i++) {
+          yield completionChunk(
+            {
+              reasoning: null,
+              reasoning_content: null,
+              content: contentTokens[i],
+            },
+            i === contentTokens.length - 1 ? 'stop' : null
+          );
+        }
+      }
+    );
+    run.Graph.overrideModel = model as t.ChatModel;
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage('Was ist 17*23? Denk Schritt für Schritt.'),
+        ],
+      },
+      config
+    );
+
+    const thoughts = reasoningDeltas
+      .flatMap((delta) => delta.delta.content ?? [])
+      .map((part) => (part as { think?: string }).think ?? '')
+      .join('');
+    const answer = messageDeltas
+      .flatMap((delta) => delta.delta.content ?? [])
+      .map((part) => (part as { text?: string }).text ?? '')
+      .join('');
+
+    expect(reasoningDeltas).toHaveLength(reasoningTokens.length);
+    expect(thoughts).toBe(reasoningTokens.join(''));
+    expect(answer).toBe(contentTokens.join(''));
+    expect(contentParts.map((part) => part?.type)).toEqual([
+      ContentTypes.THINK,
+      ContentTypes.TEXT,
+    ]);
+  });
+
+  it('assembles fragmented streamed tool_calls and executes the tool through the graph', async () => {
+    let weatherArgs: unknown;
+    const getWeather = new DynamicStructuredTool({
+      name: 'get_weather',
+      description: 'Get the current weather for a location',
+      schema: {
+        type: 'object',
+        properties: { location: { type: 'string' } },
+        required: ['location'],
+      },
+      func: async (input: unknown): Promise<string> => {
+        weatherArgs = input;
+        return JSON.stringify({
+          location: 'Berlin',
+          summary: 'sunny',
+          temp_c: 18,
+        });
+      },
+    });
+
+    const { aggregateContent } = createContentAggregator();
+    const collectedUsage: UsageMetadata[] = [];
+    const runSteps: t.RunStep[] = [];
+    const streamedToolArgs: string[] = [];
+
+    const run = await Run.create<t.IState>({
+      runId: 'vllm-tool-calls',
+      graphConfig: {
+        type: 'standard',
+        llmConfig: { provider: Providers.OPENAI, streamUsage: false },
+        tools: [getWeather],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers: {
+        [GraphEvents.TOOL_END]: new ToolEndHandler(),
+        [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(collectedUsage),
+        [GraphEvents.ON_RUN_STEP]: {
+          handle: (
+            event: GraphEvents.ON_RUN_STEP,
+            data: t.StreamEventData
+          ): void => {
+            runSteps.push(data as t.RunStep);
+            aggregateContent({ event, data: data as t.RunStep });
+          },
+        },
+        [GraphEvents.ON_RUN_STEP_DELTA]: {
+          handle: (
+            _event: GraphEvents.ON_RUN_STEP_DELTA,
+            data: t.StreamEventData
+          ): void => {
+            const { delta } = data as t.RunStepDeltaEvent;
+            if (
+              delta.type !== StepTypes.TOOL_CALLS ||
+              delta.tool_calls == null
+            ) {
+              return;
+            }
+            for (const toolCallDelta of delta.tool_calls) {
+              if (typeof toolCallDelta.args === 'string') {
+                streamedToolArgs.push(toolCallDelta.args);
+              }
+            }
+          },
+        },
+        [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+          handle: (
+            event: GraphEvents.ON_RUN_STEP_COMPLETED,
+            data: t.StreamEventData
+          ): void =>
+            aggregateContent({
+              event,
+              data: data as unknown as { result: t.ToolEndEvent },
+            }),
+        },
+        [GraphEvents.ON_MESSAGE_DELTA]: {
+          handle: (
+            event: GraphEvents.ON_MESSAGE_DELTA,
+            data: t.StreamEventData
+          ): void =>
+            aggregateContent({ event, data: data as t.MessageDeltaEvent }),
+        },
+      },
+    });
+    if (!run.Graph) {
+      throw new Error('Expected graph to be initialized');
+    }
+
+    const model = customEndpointModel();
+    async function* toolCallStream(): AsyncGenerator<CompletionChunk> {
+      yield completionChunk({ role: 'assistant', content: '\n\n' });
+      yield completionChunk({
+        tool_calls: [
+          {
+            id: 'call_0065144d618f4f33be1491af',
+            type: 'function',
+            index: 0,
+            function: { name: 'get_weather', arguments: '' },
+          },
+        ],
+      });
+      yield completionChunk({
+        tool_calls: [{ index: 0, function: { arguments: '{' } }],
+      });
+      yield completionChunk({
+        tool_calls: [
+          { index: 0, function: { arguments: '"location": "Berlin"' } },
+        ],
+      });
+      yield completionChunk(
+        { tool_calls: [{ index: 0, function: { arguments: '}' } }] },
+        'tool_calls'
+      );
+    }
+    async function* finalAnswerStream(): AsyncGenerator<CompletionChunk> {
+      yield completionChunk({
+        role: 'assistant',
+        content: 'Das Wetter in Berlin ist sonnig.',
+      });
+      yield completionChunk({ content: '' }, 'stop');
+    }
+    let modelCall = 0;
+    setCompletionStream(model, () => {
+      modelCall += 1;
+      return modelCall === 1 ? toolCallStream() : finalAnswerStream();
+    });
+    run.Graph.overrideModel = model as t.ChatModel;
+
+    await run.processStream(
+      { messages: [new HumanMessage('Wie ist das Wetter in Berlin?')] },
+      config
+    );
+
+    const toolCallStepNames = runSteps
+      .filter((step) => step.stepDetails.type === StepTypes.TOOL_CALLS)
+      .flatMap(
+        (step) => (step.stepDetails as t.ToolCallsDetails).tool_calls ?? []
+      )
+      .map((call) => ('function' in call ? call.function.name : call.name));
+
+    const messages = run.getRunMessages() ?? [];
+    const finalAnswer = messages
+      .filter((message): message is AIMessage => message.getType() === 'ai')
+      .map((message) =>
+        typeof message.content === 'string' ? message.content : ''
+      )
+      .join('');
+
+    expect(modelCall).toBe(2);
+    expect(toolCallStepNames).toContain('get_weather');
+    expect(streamedToolArgs.join('')).toBe('{"location": "Berlin"}');
+    expect(weatherArgs).toEqual({ location: 'Berlin' });
+    expect(messages.some((message) => message.getType() === 'tool')).toBe(true);
+    expect(finalAnswer).toContain('Das Wetter in Berlin ist sonnig.');
+  });
+});

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

@@ -10,6 +10,7 @@ import {
   createCloudflareBashProgrammaticToolCallingTool,
   createCloudflareProgrammaticToolCallingTool,
 } from '../cloudflare/CloudflareProgrammaticToolCalling';
+import { isWorkspaceClientTimeoutError } from '../local/workspaceFS';
 import { createCloudflareBridgeRuntime } from '../cloudflare/CloudflareBridgeRuntime';
 import { resolveLocalToolsForBinding } from '../local/resolveLocalExecutionTools';
 import { spawnLocalProcess } from '../local/LocalExecutionEngine';
@@ -388,6 +389,197 @@ describe('Cloudflare sandbox execution backend', () => {
     expect(received).not.toHaveProperty('signal');
   });
 
+  it('rejects with a client-side timeout when sandbox readFile stalls', async () => {
+    // The native-DO file-IO RPCs (readFile/writeFile/listFiles/...) have the same
+    // stall hazard exec() does: no signal, no enforced timeout. A cold/unresponsive
+    // container otherwise hangs the host await until the run-level abort, burning
+    // the whole budget on one read (observed live: a `read_file` stalled ~552s).
+    jest.useFakeTimers();
+    try {
+      let readCalls = 0;
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          readFile: () => {
+            readCalls += 1;
+            return new Promise<string>(() => undefined);
+          },
+        }),
+      });
+
+      const error = (fs.readFile as (p: string) => Promise<unknown>)(
+        '/workspace/a.txt'
+      ).catch((e: unknown) => e);
+      // Client backstop = clientFsTimeoutMs(1000) = 6000ms; advance past it.
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await error;
+      // Must be the DISTINGUISHABLE timeout error so ENOENT-only callers rethrow
+      // it instead of mistaking a stalled read for a missing file.
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+      expect((settled as Error).message).toMatch(/client-side timeout/);
+      expect(readCalls).toBe(1);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('keeps the backstop active while draining a streamed file read', async () => {
+    // sandbox.readFile resolves to { content: ReadableStream } whose stream never
+    // ends. The race must cover the drain (normalizeReadFileContent), not just the
+    // initial RPC, or read_file/open/stat still hang to the run-level abort.
+    jest.useFakeTimers();
+    try {
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          readFile: async () => ({
+            content: new ReadableStream<Uint8Array>({
+              // start() never enqueues or closes -> the drain stalls forever.
+              start() {},
+            }),
+          }),
+        }),
+      });
+
+      const error = (fs.readFile as (p: string) => Promise<unknown>)(
+        '/workspace/a.txt'
+      ).catch((e: unknown) => e);
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await error;
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('rethrows a stat directory-probe timeout instead of falling through to readFile', async () => {
+    // findChildInfo returns nothing -> the directory probe (listFiles) runs; if it
+    // STALLS it must surface, not fall through to the readFile branch (which would
+    // burn a SECOND full backstop, ~2x the timeout, before the caller sees it).
+    jest.useFakeTimers();
+    try {
+      let readFileCalls = 0;
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          listFiles: (dir) =>
+            dir === '/workspace/probe-me'
+              ? new Promise(() => undefined) // the probe stalls
+              : Promise.resolve([]), // findChildInfo's parent listing returns fast
+          readFile: () => {
+            readFileCalls += 1;
+            return Promise.resolve('');
+          },
+        }),
+      });
+
+      const error = fs.stat('/workspace/probe-me').catch((e: unknown) => e);
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await error;
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+      // Must NOT have fallen through to the readFile probe.
+      expect(readFileCalls).toBe(0);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('bounds execute_code temp-dir setup RPCs (mkdir/writeFile) that stall', async () => {
+    jest.useFakeTimers();
+    try {
+      const sandbox = createRuntime({
+        // exec would resolve fine; the stall is in the pre-exec mkdir setup.
+        mkdir: () => new Promise<{ ok: true }>(() => undefined),
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("hi")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+      await jest.advanceTimersByTimeAsync(6500);
+      await assertion;
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('still cleans up the temp dir when execute_code setup (writeFile) times out', async () => {
+    // The setup RPCs are inside the try, so a stalled writeFile still triggers
+    // the finally cleanup — otherwise the late (uncancellable) write leaves an
+    // orphaned .lc-exec/<uuid> dir behind on every cold-container failure.
+    jest.useFakeTimers();
+    try {
+      const execCommands: string[] = [];
+      const sandbox = createRuntime({
+        mkdir: async () => ({ ok: true }),
+        writeFile: () => new Promise<{ ok: true }>(() => undefined), // stalls
+        exec: async (command) => {
+          execCommands.push(command);
+          return { exitCode: 0, stdout: '', stderr: '' };
+        },
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("hi")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      ).catch((e: unknown) => e);
+      await jest.advanceTimersByTimeAsync(6500);
+      const settled = await promise;
+      expect(isWorkspaceClientTimeoutError(settled)).toBe(true);
+      // Cleanup must have been issued despite the setup failure.
+      expect(execCommands.some((c) => c.startsWith('rm -rf'))).toBe(true);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('rejects with a client-side timeout when sandbox listFiles stalls', async () => {
+    jest.useFakeTimers();
+    try {
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({
+          listFiles: () =>
+            new Promise<t.CloudflareSandboxFileInfo[]>(() => undefined),
+        }),
+      });
+
+      const promise = (fs.readdir as (p: string) => Promise<unknown>)(
+        '/workspace/sub'
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+      await jest.advanceTimersByTimeAsync(6500);
+      await assertion;
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('does not time out a native FS RPC that returns in time', async () => {
+    jest.useFakeTimers();
+    try {
+      const fs = createCloudflareWorkspaceFS({
+        workspaceRoot: '/workspace',
+        timeoutMs: 1000,
+        sandbox: createRuntime({ readFile: async () => 'contents' }),
+      });
+
+      const result = await (
+        fs.readFile as (p: string, e: 'utf8') => Promise<string>
+      )('/workspace/a.txt', 'utf8');
+      expect(result).toBe('contents');
+      // The backstop timer must have been cleared, not left dangling.
+      expect(jest.getTimerCount()).toBe(0);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
   it('passes call-specific timeouts to the Cloudflare spawn wrapper', async () => {
     let execCommand = '';
     let execTimeout: number | undefined;