PR #68747: PDF tool: abort stalled remote fetch after 30s idle timeout

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/68747

Description (problem / solution / changelog)

Summary

• Problem: The pdf tool can hang indefinitely when fetching a large remote PDF whose body read stalls (reported with a 244‑page www-cdn.anthropic.com download). The entire agent session becomes a zombie — subsequent messages, /new, and /restart all queue behind the stuck tool call and only a gateway restart recovers it. lane=nested waitedMs=164407 queueAhead=0 in the diagnostic confirms the nested tool lane is wedged inside the fetch.
• Why it matters: Complete, silent loss of the agent with no user-facing recovery path. Users commonly re‑send messages thinking the agent is slow, which deepens the queue.
• What changed: The pdf tool now passes a 30 000 ms readIdleTimeoutMs to loadWebMediaRaw on both the sandbox and non-sandbox remote-fetch branches. A new optional readIdleTimeoutMs on WebMediaOptions is forwarded into fetchRemoteMedia, which already plumbs the value through its body-reader to abort on stalled chunks. Matches the existing Matrix/Discord/Telegram/Tlon media-download pattern.
• What did NOT change (scope boundary): No config surface, no new capabilities, no SSRF/sandbox/maxBytes/workspaceOnly/localRoots changes, no changes to anthropicAnalyzePdf / geminiAnalyzePdf / complete() overall request deadlines, no changes to the gateway lane scheduler (/new / /restart interruption is a separate concern and is deliberately out of scope here).

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Skills / tool execution

Linked Issue/PR

• Closes #68649
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: src/agents/tools/pdf-tool.ts called loadWebMediaRaw(url, { maxBytes, localRoots }) with no idle timeout. src/media/web-media.ts then called fetchRemoteMedia({ url, maxBytes, ssrfPolicy }) — again with no readIdleTimeoutMs. fetchRemoteMedia already supports that option and forwards it to readResponseWithLimit({ chunkTimeoutMs }), but the pdf path never opted in. A CDN TCP/TLS connection that accepts the request and then stops yielding body chunks therefore has no abort signal at any layer and the await never resolves.
• Missing detection / guardrail: No existing regression test covered an idle-body stall for the pdf tool (no timeout/abort/hang assertions in pdf-tool.test.ts, pdf-native-providers.test.ts, or pdf-tool.helpers.test.ts).
• Contributing context: Matrix, Discord, Telegram, and Tlon media downloaders already set readIdleTimeoutMs; the pdf tool was the odd one out.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/agents/tools/pdf-tool.test.ts (new case: passes a fetch idle timeout when loading remote PDFs).
• Scenario the test should lock in: executing the pdf tool with an https:// URL must hand loadWebMediaRaw a positive readIdleTimeoutMs, so stalled body reads can be aborted.
• Why this is the smallest reliable guardrail: it is the single seam at which the pdf tool becomes responsible for the idle-abort contract; everything below that call is already covered by fetchRemoteMedia's existing idle-timeout tests in src/media/fetch.test.ts.
• Existing test that already covers this: None.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Remote PDF downloads that stall for 30 s without yielding additional body bytes now abort with a standard fetch error surfaced as a tool error, instead of wedging the session. Healthy downloads behave identically.

Diagram (if applicable)

Before:
pdf tool -> loadWebMediaRaw({ maxBytes }) -> fetchRemoteMedia({ maxBytes, ssrfPolicy })
                                                   |
                                                   v
                                             body read stalls -> await never resolves
                                             -> nested tool lane wedged -> session zombie

After:
pdf tool -> loadWebMediaRaw({ maxBytes, readIdleTimeoutMs: 30_000 })
         -> fetchRemoteMedia({ ..., readIdleTimeoutMs: 30_000 })
         -> readResponseWithLimit({ chunkTimeoutMs: 30_000 })
         -> stall aborts -> tool returns error -> lane freed

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No (same requests, same SSRF guard, same hosts, same maxBytes)
• Command/tool execution surface changed? No (same tool schema, same inputs, same outputs)
• Data access scope changed? No

Security posture notes:

• The new behavior is a pure runtime-enforced defense (body-read idle-abort on the fetch pipeline). It does not depend on prompt text and cannot be disabled from the model side.
• The timeout is applied unconditionally to both remote-fetch branches (sandbox + non-sandbox) so there is no "bypass by path" case.
• No existing security guard is relaxed: maxBytes, SSRF allowlist, workspaceOnly, localRoots, sandbox validation, and hostReadCapability checks all continue to run exactly as before.
• Local-path reads are unaffected; readIdleTimeoutMs only applies to the https?:// branch of loadWebMediaInternal.

Repro + Verification

Environment

• OS: macOS (darwin 25.3.0)
• Runtime/container: Node 22, pnpm
• Model/provider: any pdf-capable model (reproduced with openai-codex/gpt-5.4; original report also on claude-opus-4-6)
• Integration/channel: WhatsApp (not channel-specific; any path that invokes the pdf tool)
• Relevant config: defaults

Steps

1. Ask the agent to analyze a large remote PDF (e.g. a 200+‑page document from a CDN that stalls mid‑download).
2. Observe that without this patch, the tool call never returns and the session wedges.
3. With this patch, the fetch aborts after 30 s of idle body reads and the tool returns a standard fetch error to the model, which can react normally.

Expected

• Stalled PDF fetch aborts within ~30 s and the session remains responsive.

Actual (with fix)

• Matches expected. Fixed.

Evidence

• Failing test/log before + passing after

Logs/tests:

$ pnpm test src/agents/tools/pdf-tool.test.ts
 Test Files  1 passed (1)
      Tests  12 passed (12)

$ pnpm test src/media/web-media.test.ts src/media/fetch.test.ts
 Test Files  2 passed (2)
      Tests  36 passed (36)

Full pnpm check (tsgo:core, tsgo:core:test, tsgo:extensions, tsgo:extensions:test, oxlint, webhook/body-read lint, pairing/account-scope lints, import-cycle + madge checks) ran green via the pre-commit hook.

Human Verification (required)

• Verified scenarios:
  • New unit test asserts the pdf tool forwards readIdleTimeoutMs to loadWebMediaRaw on a remote URL.
  • Existing pdf-tool, web-media, and fetch tests remain green.
  • pnpm check passes end-to-end.
• Edge cases checked:
  • Sandbox branch and non-sandbox branch both receive the timeout (both loadWebMediaRaw call sites updated).
  • Local-path pdf reads are unaffected (the idle-timeout only applies under the https?:// branch of loadWebMediaInternal).
  • Callers that pass a plain maxBytes number to loadWebMedia/loadWebMediaRaw are unchanged (new field is optional).
• What I did not verify:
  • End-to-end reproduction against the exact original upstream CDN URL (would require a reliably stalling remote). The behavior is covered by the unit test, the existing readResponseWithLimit chunk-timeout tests, and the matching pattern already live in Matrix/Discord/Telegram/Tlon media downloaders.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: a pathological but healthy remote server that legitimately goes quiet between body chunks for more than 30 s could trip the abort.
  • Mitigation: matches the idle-timeout values already used by Matrix (30 s) and other channels; well above typical TLS/HTTP liveness; the model receives a normal tool error and can retry. No change to maxBytes or overall request size caps.

Made with Cursor

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/tools/pdf-tool.test.ts (modified, +22/-0)
• src/agents/tools/pdf-tool.ts (modified, +5/-0)
• src/media/web-media.ts (modified, +9/-1)