@librechat/agents 3.2.41 → 3.2.43

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

@@ -2,6 +2,7 @@ import type * as t from '@/types';
 import {
   createCloudflareWorkspaceFS,
   createCloudflareLocalExecutionConfig,
+  execWithClientTimeout,
   executeCloudflareBash,
   executeCloudflareCode,
 } from '../cloudflare/CloudflareSandboxExecutionEngine';
@@ -9,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';
@@ -257,6 +259,327 @@ describe('Cloudflare sandbox execution backend', () => {
     expect(result.timedOut).toBe(true);
   });
 
+  it('rejects with a client-side timeout when sandbox exec stalls (no native cancellation)', async () => {
+    // The native Cloudflare Sandbox DO exec() is uncancellable (ExecOptions has no
+    // signal) and its own `timeout` is not enforced when the container/RPC stalls,
+    // while the in-sandbox `timeout(1)` wrapper only bounds a *running* command.
+    // Without a client-side race a stalled exec hangs until the host's run-level
+    // abort, burning the whole budget on one tool call (issue #251).
+    jest.useFakeTimers();
+    try {
+      let mainExecCalls = 0;
+      const sandbox = createRuntime({
+        exec: (command) => {
+          // Cleanup (`rm -rf`) resolves immediately; the real command stalls,
+          // simulating an unresponsive / cold container exec that never returns.
+          if (command.startsWith('rm -rf')) {
+            return Promise.resolve({ exitCode: 0, stdout: '', stderr: '' });
+          }
+          mainExecCalls += 1;
+          return new Promise<t.CloudflareSandboxExecResult>(() => undefined);
+        },
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("slow")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+
+      // Client backstop = outerTimeoutMs(1000) + 5000 = 11000ms; advance past it.
+      await jest.advanceTimersByTimeAsync(11500);
+      await assertion;
+      expect(mainExecCalls).toBe(1);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('aborts signal-aware execs when the client timeout fires', async () => {
+    // For signal-aware transports (e.g. the HTTP bridge), a client timeout should
+    // actually cancel the underlying exec, not just abandon it.
+    jest.useFakeTimers();
+    try {
+      let mainSignal: AbortSignal | undefined;
+      const sandbox = createRuntime({
+        supportsExecSignal: true,
+        exec: (command, options) => {
+          if (command.startsWith('rm -rf')) {
+            return Promise.resolve({ exitCode: 0, stdout: '', stderr: '' });
+          }
+          mainSignal = options?.signal;
+          return new Promise<t.CloudflareSandboxExecResult>(() => undefined);
+        },
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("slow")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+      await jest.advanceTimersByTimeAsync(11500);
+      await assertion;
+
+      expect(mainSignal).toBeDefined();
+      expect(mainSignal?.aborted).toBe(true);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('composes a caller abort signal with the timeout instead of clobbering it', async () => {
+    let received: AbortSignal | undefined;
+    const sandbox = createRuntime({
+      supportsExecSignal: true,
+      exec: (_command, options) => {
+        received = options?.signal;
+        return new Promise<t.CloudflareSandboxExecResult>(
+          (_resolve, reject) => {
+            options?.signal?.addEventListener(
+              'abort',
+              () => reject(new Error('aborted')),
+              { once: true }
+            );
+          }
+        );
+      },
+    });
+
+    const caller = new AbortController();
+    const settled = execWithClientTimeout(
+      sandbox,
+      'echo hi',
+      { signal: caller.signal },
+      60000,
+      'test'
+    ).catch((e) => e as Error);
+
+    await Promise.resolve();
+    expect(received).toBeDefined();
+    // The exec gets a composed signal, not the caller's directly.
+    expect(received).not.toBe(caller.signal);
+    expect(received?.aborted).toBe(false);
+
+    // A caller cancellation must reach the exec (not wait for the client timeout).
+    caller.abort();
+    await settled;
+    expect(received?.aborted).toBe(true);
+  });
+
+  it('strips a caller signal for native runtimes that cannot consume it', async () => {
+    let received: t.CloudflareSandboxExecOptions | undefined;
+    const sandbox = createRuntime({
+      // no supportsExecSignal -> native DO, which cannot clone/consume a signal
+      exec: async (_command, options) => {
+        received = options;
+        return { exitCode: 0, stdout: 'ok', stderr: '' };
+      },
+    });
+    const caller = new AbortController();
+
+    await execWithClientTimeout(
+      sandbox,
+      'echo hi',
+      { cwd: '/workspace', signal: caller.signal },
+      60000,
+      'test'
+    );
+
+    expect(received).toBeDefined();
+    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;