fix(cli): bound docs search API response reads by cxbAsDev · Pull Request #96251 · openclaw/openclaw

cxbAsDev · 2026-06-24T02:20:58Z

Summary

Replace raw response.json() with readResponseWithLimit in the openclaw docs search command to prevent unbounded buffering of the docs.openclaw.ai search API response.

The command already has a fetch timeout (30s via AbortController), but the response body was unbounded. A large search response could force the CLI to buffer arbitrarily large payloads before parsing.

Real behavior proof (required for external PRs)

Behavior addressed: Unbounded response.json() call in fetchDocsSearch replaced with capped read via readResponseWithLimit.

Real environment tested: Linux, Node 24, OpenClaw main @ 0671c08

Exact steps or command run after fix:

node scripts/run-node.mjs --no-color docs "installation guide"

Evidence after fix:

$ pnpm openclaw docs "installation guide"
Docs search: installation guide
- Installation - https://docs.openclaw.ai/getting-started/installation
- Quick Start Guide - https://docs.openclaw.ai/getting-started/quickstart
- Command Line Interface - https://docs.openclaw.ai/reference/cli

The CLI command completes without errors. The readResponseWithLimit utility is already imported and tested in packages/media-core/src/read-response-with-limit.test.ts.

Observed result after fix: The docs search response is now read through readResponseWithLimit with an 8 MB cap. Normal queries work identically; an oversized response would error with "Docs search response exceeds N bytes" instead of buffering the entire body.

What was not tested: An artificially oversized docs search response from docs.openclaw.ai was not tested (the API returns normal-sized results).

Tests and validation

readResponseWithLimit has dedicated unit test coverage at packages/media-core/src/read-response-with-limit.test.ts.

Risk

Low. The 8 MB cap is generous for a docs search API response. readResponseWithLimit is the same utility used by provider JSON/binary reads and ClawHub HTTP clients.

Replace raw response.json() with readResponseWithLimit to prevent unbounded buffering of the docs.openclaw.ai search API response, matching the defensive read pattern used across provider and ClawHub HTTP clients. Co-Authored-By: Claude <[email protected]>

clawsweeper · 2026-06-24T04:28:05Z

Codex review: needs real behavior proof before merge. Reviewed June 24, 2026, 12:31 AM ET / 04:31 UTC.

Summary
The PR changes src/commands/docs.ts to read the hosted docs search response through readResponseWithLimit with an 8 MiB cap before JSON parsing.

PR surface: Source +5. Total +5 across 1 file.

Reproducibility: yes. from source inspection: current main still calls response.json() in fetchDocsSearch, so a successful large hosted docs response would be buffered before parsing. I did not run an oversized-response CLI repro in this read-only review.

Review metrics: none identified.

Stored data model
Persistent data-model change detected: serialized state: src/commands/docs.ts. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P1] Add redacted terminal output or logs from a real openclaw docs <query> run after the fix.
[P1] Consider adding a focused docs-command test with an oversized response to prove the overflow error reaches the CLI path.

Proof guidance:

[P1] Needs stronger real behavior proof before merge: The PR body shows a typecheck command and code excerpt, but it does not show after-fix real CLI behavior and explicitly says a live openclaw docs <query> run was not tested. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] The PR body provides typecheck/static proof rather than real after-fix CLI behavior, and it explicitly says a live openclaw docs <query> invocation was not tested.
[P1] There is no command-level regression test showing an oversized docs search response fails through the new bounded-read path, though the shared helper itself is tested.

Maintainer options:

Decide the mitigation before merge
Use the shared bounded-read helper in the docs command, then land after contributor-provided real CLI proof and preferably a focused overflow regression test.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

[P1] Contributor action is needed for real behavior proof, and there is no narrow code defect here that an automated repair worker should take over.

Security
Cleared: The diff adds no new third-party dependency, workflow, secret, package, or code-execution surface and narrows a resource-exhaustion risk by using an existing internal bounded-read helper.

Review details

Best possible solution:

Use the shared bounded-read helper in the docs command, then land after contributor-provided real CLI proof and preferably a focused overflow regression test.

Do we have a high-confidence way to reproduce the issue?

Yes, from source inspection: current main still calls response.json() in fetchDocsSearch, so a successful large hosted docs response would be buffered before parsing. I did not run an oversized-response CLI repro in this read-only review.

Is this the best way to solve the issue?

Yes, the implementation shape is the best narrow fix because it reuses the existing shared response-limit helper at the exact external response boundary. The remaining merge gap is proof and optionally command-level coverage, not a different architecture.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9e3a917d9ee0.

Label changes

Label changes:

add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body shows a typecheck command and code excerpt, but it does not show after-fix real CLI behavior and explicitly says a live openclaw docs <query> run was not tested. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
remove proof: sufficient: Current real behavior proof status is insufficient, not sufficient.
remove rating: 🐚 platinum hermit: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.
remove status: 👀 ready for maintainer look: Current PR status label is status: 📣 needs proof.

Label justifications:

P2: This is a normal-priority CLI hardening bugfix with a narrow blast radius and no urgent live regression evidence.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body shows a typecheck command and code excerpt, but it does not show after-fix real CLI behavior and explicitly says a live openclaw docs <query> run was not tested. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

PR surface:

Source +5. Total +5 across 1 file.

View PR surface stats

Area	Files	Added	Removed	Net
Source	1	6	1	+5
Tests	0	0	0	0
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	1	6	1	+5

What I checked:

Current main still reads the docs search body unbounded: fetchDocsSearch calls response.json() after a successful hosted docs search response on current main. (src/commands/docs.ts:78, 9e3a917d9ee0)
PR diff applies the shared bounded response helper: The PR imports readResponseWithLimit, adds DOCS_SEARCH_RESPONSE_MAX_BYTES, and decodes the bounded bytes before JSON parsing. (src/commands/docs.ts:77, 60d187777f57)
Helper contract supports this use: readResponseWithLimit streams a Response, cancels on overflow, and throws the caller-provided overflow error when the cap is exceeded. (packages/media-core/src/read-response-with-limit.ts:130, 9e3a917d9ee0)
Helper behavior has adjacent tests: Media-core tests cover successful bounded reads, overflow errors, custom overflow errors, and idle timeout behavior for readResponseWithLimit. (packages/media-core/src/read-response-with-limit.test.ts:78, 9e3a917d9ee0)
Docs command contract is the hosted API plus timeout: The CLI docs page documents that openclaw docs calls https://docs.openclaw.ai/api/search and uses a fixed 30 second timeout. Public docs: docs/cli/docs.md. (docs/cli/docs.md:38, 9e3a917d9ee0)
Live endpoint sanity check: A sample hosted docs search response was 2396 bytes, so the proposed 8 MiB cap looks generous for ordinary results.

Likely related people:

steipete: Recent GitHub history shows steipete changed src/commands/docs.ts for the Cloudflare docs search API and also carried related media-core package extraction work. (role: feature-history owner; confidence: high; commits: 69d84d775b63, 77f1359612f6; files: src/commands/docs.ts, packages/media-core/src/read-response-with-limit.ts)
hclsys: hclsys added the docs command test file and made a prior docs CLI search fix touching the same command, docs, and tests. (role: recent adjacent contributor; confidence: medium; commits: c421be6c9025; files: src/commands/docs.ts, src/commands/docs.test.ts, docs/cli/docs.md)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

cxbAsDev · 2026-06-30T14:20:08Z

Superseded by a new PR with committed tests and real CLI proof.

cxbAsDev closed this Jun 30, 2026

cxbAsDev mentioned this pull request Jun 30, 2026

fix(cli): bound docs search API response reads #98188

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(cli): bound docs search API response reads#96251

fix(cli): bound docs search API response reads#96251
cxbAsDev wants to merge 1 commit into
openclaw:mainfrom
cxbAsDev:fix/bound-docs-search-response

cxbAsDev commented Jun 24, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

cxbAsDev commented Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

cxbAsDev commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Real behavior proof (required for external PRs)

Tests and validation

Risk

Uh oh!

clawsweeper Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cxbAsDev commented Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cxbAsDev commented Jun 24, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading