Skip to content

fix(pdf): reject fractional page selections#99399

Merged
steipete merged 6 commits into
openclaw:mainfrom
qingminglong:codex/99393-pdf-fractional-pages
Jul 6, 2026
Merged

fix(pdf): reject fractional page selections#99399
steipete merged 6 commits into
openclaw:mainfrom
qingminglong:codex/99393-pdf-fractional-pages

Conversation

@qingminglong

@qingminglong qingminglong commented Jul 3, 2026 •
edited by steipete
Loading

Copy link
Copy Markdown
Contributor

Closes #99393

What Problem This Solves

Fixes an issue where users who pass fractional PDF pages values, such as 1.5, could have the PDF tool accept the input even though downstream extraction only keeps integer page numbers. In fallback extraction mode that can leave the request with no selected PDF page content instead of a clear input error.

Why This Change Was Made

The PDF tool parser is the source-of-truth boundary for converting user pages text into page numbers. This change makes single-page tokens match the same positive-integer contract already used by range tokens, so fractional values fail fast as invalid page numbers before any provider or extractor path sees them.

User Impact

Users now get an actionable Invalid page number error for fractional PDF page selections. Valid integer pages, ranges, sorting, deduping, max-page clamping, and the existing empty-selection error remain unchanged.

Evidence

Current prepared head: f3233b1c22b95fe4901ef2419e614cf108060549 (rebased onto 89f911f322c90c3e7e3ec51120686256de19b4b1).

  • Claim proved: fractional PDF page selections now reject at the shared PDF tool parser boundary before fallback extraction or model analysis can run.
  • Before-fix source behavior on main: parsePageRange("1.5", 20) accepted the fractional token as [1.5], and parsePageRange("1,1.5", 20) accepted [1,1.5].
  • After-fix helper behavior: parsePageRange("1.5", 20) and parsePageRange("1,2.5", 20) reject with Invalid page number.
  • Real tool-boundary behavior: createPdfTool().execute(...) rejects pages: "1.5" and pages: "1,2.5" before media loading, extraction, or model completion. A separate exact-head runtime smoke uses a nonexistent PDF and no configured model yet still returns Invalid page number: "1.5", proving parser validation runs before file/network I/O and model resolution.
  • Focused validation:
    • Sanitized direct AWS Crabbox cbx_864980d2079c on reviewed pre-rebase head 6ef2bbecb1e64800de50851f28a60cfd56feafda, public networking/no Tailscale/no instance profile. The later native sync only rebased the same four-file patch.
    • pnpm test src/agents/tools/pdf-tool.helpers.test.ts src/agents/tools/pdf-tool.test.ts: passed, 2 files / 51 tests (run).
    • Exact-head runtime smoke: passed (run).
    • Fresh AutoReview on final prepared head: clean, no accepted/actionable findings; correctness 0.86.
    • Targeted oxfmt --check and git diff --check: passed.
  • Final prepared-head hosted CI: every relevant check passed (run). Native OPENCLAW_TESTBOX=1 scripts/pr prepare-run 99399 recorded gates_mode=hosted_exact_head for f3233b1c22b95fe4901ef2419e614cf108060549.
  • Competing PR note: fix: reject fractional PDF page selections #99403 is an open proof-positive candidate for the same issue. This PR now includes equivalent real tool-boundary proof; maintainers should choose exactly one landing candidate and should not merge both independently.
  • Not tested / proof gaps:
    • No live provider API call was made because the invalid pages input is rejected before fallback extraction or model completion.

@openclaw-barnacle openclaw-barnacle Bot added agents Agent runtime and tooling size: XS labels Jul 3, 2026
@clawsweeper

clawsweeper Bot commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 6, 2026, 1:37 AM ET / 05:37 UTC.

Summary
The branch rejects fractional PDF pages tokens at the parser boundary, validates page selections before PDF loading/model work, and adds helper plus tool-boundary regression tests.

PR surface: Source +2, Tests +38. Total +40 across 4 files.

Reproducibility: yes. Source-level reproduction is high confidence: current main parses fractional single-page tokens with Number(part), then fallback extraction filters non-integer pages.

Review metrics: 2 noteworthy metrics.

  • Competing Fix Candidates: 2 open PRs for 1 linked issue. Both open branches target the same fractional PDF page parser bug, so maintainers should avoid landing both independently.
  • Tool Argument Validation: 1 public tool argument tightened. The PDF tool pages argument changes from permissive numeric parsing to integer-syntax validation, which matters for compatibility review.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #99393
Summary: The canonical issue is the fractional PDF page-token parser bug; this PR and one sibling open PR are competing candidate fixes for that same root cause.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Risk before merge

  • [P1] Merging this PR intentionally turns previously accepted numeric-looking pages strings such as 1.5 or 1e2 into validation errors; that matches the documented integer contract but is still a compatibility-relevant public tool tightening.
  • [P1] A sibling proof-positive PR targets the same linked issue and parser boundary, so maintainers should land exactly one candidate and close the other as superseded.

Maintainer options:

  1. Land One Integer-Only Parser Fix (recommended)
    Accept the compatibility tightening as the intended bug fix, land either this PR or the sibling candidate, and close the other duplicate branch.
  2. Pause For Compatibility Policy
    Pause both candidates if maintainers decide existing permissive numeric parsing should remain supported or needs a migration/deprecation story.

Next step before merge

  • No automated repair is queued because the remaining blocker is maintainer selection of the canonical duplicate PR and acceptance of the validation tightening.

Maintainer decision needed

  • Question: Should maintainers land this PR as the canonical fractional-PDF-page fix, land fix: reject fractional PDF page selections #99403 instead, or pause both because rejecting previously accepted fractional page strings is not desired?
  • Rationale: Both open PRs solve the same bug at the same parser boundary, and the change deliberately tightens a public tool argument, so automation should not choose the canonical landing path alone.
  • Likely owner: steipete — steipete is assigned on the live PR and authored the latest maintainer fixup commit on this branch.
  • Options:
    • Land This PR As Canonical (recommended): Accept the integer-only pages contract here, let final required checks settle, and close the sibling fix candidate as superseded after this lands.
    • Land The Sibling PR Instead: Use fix: reject fractional PDF page selections #99403 as the canonical fix if maintainers prefer that branch's proof trail or patch shape.
    • Pause Both For Compatibility Policy: Pause both candidates only if maintainers want fractional or numeric-expression page strings to remain accepted and need to define a documented mapping for them.

Security
Cleared: The diff tightens PDF parser validation and adds tests; it does not touch dependencies, workflows, secrets, package metadata, lockfiles, or supply-chain execution paths.

Review details

Best possible solution:

Land exactly one parser-boundary integer-validation fix with helper and tool-boundary coverage, then close the linked issue and duplicate unmerged PRs.

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

Yes. Source-level reproduction is high confidence: current main parses fractional single-page tokens with Number(part), then fallback extraction filters non-integer pages.

Is this the best way to solve the issue?

Yes. The parser boundary is the best fix layer because it is the shared conversion point for the public pages string before native-provider checks and extraction fallback; the remaining question is which duplicate PR should be canonical.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 89f911f322c9.

Label changes

Label changes:

  • add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
  • remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

  • P2: This is a normal-priority PDF tool input bug with misleading-output risk but a narrow blast radius and clear fix path.
  • merge-risk: 🚨 compatibility: The PR deliberately turns previously accepted fractional or numeric-expression pages input into hard validation errors.
  • rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (linked_artifact): The PR body and maintainer comment include linked Crabbox test and runtime-smoke artifacts showing fractional pages values reject before media loading, extraction, or model completion; the current head carries the same final patch after rebase.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body and maintainer comment include linked Crabbox test and runtime-smoke artifacts showing fractional pages values reject before media loading, extraction, or model completion; the current head carries the same final patch after rebase.
Evidence reviewed

PR surface:

Source +2, Tests +38. Total +40 across 4 files.

View PR surface stats
Area Files Added Removed Net
Source 2 4 2 +2
Tests 2 38 0 +38
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 4 42 2 +40

Acceptance criteria:

  • [P1] pnpm test src/agents/tools/pdf-tool.helpers.test.ts src/agents/tools/pdf-tool.test.ts.
  • [P1] Final exact-head required CI or native prepare before merge.

What I checked:

  • Repository policy read: Root and scoped agent/tool AGENTS.md files were read; the applicable policy requires full path review, dependency contract inspection, and compatibility-risk surfacing for stricter validation changes. (AGENTS.md:11, 89f911f322c9)
  • Current main accepts fractional single-page tokens: Current main documents 1-based pages but parses a single token with Number(part), so a value like 1.5 reaches the downstream pageNumbers contract. (src/agents/tools/pdf-tool.helpers.ts:68, 89f911f322c9)
  • Current main parses pages after loading PDFs: The current tool path loads PDFs before calling parsePageRange, so invalid pages input is not rejected before file/network media work on main. (src/agents/tools/pdf-tool.ts:498, 89f911f322c9)
  • Fallback extractor requires integer pages: The document-extract plugin filters requested pages with Number.isInteger, which explains why a fractional parser result can be dropped instead of becoming a clear input error. (extensions/document-extract/document-extractor.ts:68, 89f911f322c9)
  • Documented pages contract is integer-style: The PDF docs describe pages as a filter like 1-5 or 1,3,7-9 and say the value is parsed as 1-based page numbers. Public docs: docs/tools/pdf.md. (docs/tools/pdf.md:37, 89f911f322c9)
  • PR head parser fix: At the current PR head, the single-page branch rejects tokens that do not match decimal integer syntax before numeric conversion. (src/agents/tools/pdf-tool.helpers.ts:68, f3233b1c22b9)

Likely related people:

  • tyler6204: The original PDF analysis tool commit introduced parsePageRange, the public pages argument, and the PDF tool implementation. (role: introduced behavior; confidence: high; commits: d0ac1b019517; files: src/agents/tools/pdf-tool.helpers.ts, src/agents/tools/pdf-tool.ts, src/agents/tools/pdf-tool.test.ts)
  • steipete: Recent history shows repeated PDF tool validation/test work, and the live PR is assigned to steipete with the latest maintainer fixup commit on the branch. (role: recent area contributor and current reviewer; confidence: high; commits: 7240830ca42f, 998cc02af40c, f3233b1c22b9; files: src/agents/tools/pdf-tool.helpers.ts, src/agents/tools/pdf-tool.ts, src/agents/tools/pdf-tool.test.ts)
  • zhangguiping-xydt: The merged neighboring fix for empty parsed PDF page ranges changed the same parser/helper test surface. (role: recent adjacent repair author; confidence: high; commits: a5165d6a8486, aadd57c31cc8; files: src/agents/tools/pdf-tool.helpers.ts, src/agents/tools/pdf-tool.helpers.test.ts, src/agents/tools/pdf-tool.test.ts)
  • vincentkoc: History ties vincentkoc to the document-extract/PDF fallback surface that filters selected pages downstream. (role: adjacent document-extract contributor; confidence: medium; commits: e3cba98f3904, 83753535eba4; files: extensions/document-extract/document-extractor.ts, src/agents/tools/pdf-tool.helpers.ts)
  • ZengWen-DT: Recent history includes a document-extract PDF image fallback fix, and a sibling open PR from this author targets the same fractional-page parser bug. (role: adjacent contributor and sibling candidate author; confidence: medium; commits: d7dff3cbf405, 80d5d6af344d; files: extensions/document-extract/document-extractor.ts, src/agents/tools/pdf-tool.helpers.ts)
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.
Review history (3 earlier review cycles)
  • reviewed 2026-07-03T11:21:55.253Z sha 451ef04 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-06T05:03:25.442Z sha 6ef2bbe :: needs maintainer review before merge. :: none
  • reviewed 2026-07-06T05:10:10.206Z sha 6ef2bbe :: needs maintainer review before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. labels Jul 3, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jul 3, 2026
Closed
@qingminglong

qingminglong commented Jul 3, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 3, 2026
@qingminglong

qingminglong commented Jul 3, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels Jul 3, 2026
@qingminglong

qingminglong commented Jul 3, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 3, 2026
@qingminglong

qingminglong commented Jul 3, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

This was referenced Jul 3, 2026
Closed
Closed
@steipete steipete self-assigned this Jul 6, 2026
@steipete
steipete force-pushed the codex/99393-pdf-fractional-pages branch from 45c2b60 to 6ef2bbe Compare July 6, 2026 04:49
@steipete

steipete commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Maintainer review and fixup are complete on 6ef2bbecb1e64800de50851f28a60cfd56feafda.

What changed:

  • Kept the contributor's parser-boundary repair, using the same decimal-integer grammar as page ranges and the documented examples.
  • Moved page parsing ahead of model discovery and PDF file/network loading.
  • Strengthened the real tool test so standalone and mixed fractional selections prove that media loading, extraction, and completion are never called.

Contract review:

Exact-head proof:

Broad CI run https://github.com/openclaw/openclaw/actions/runs/28768542718 has no PDF-related failure. Its failures are outside this diff: missing UI sidebar exports on the base (subsequently restored on main by 55a0012c44) and the pre-existing workboard typed-hook allowlist mismatch. Native prepare remains to rebase current main and enforce the final exact-head hosted gate.

Proof gap: no provider API call was made because invalid page input must terminate before provider selection. The exact runtime smoke proves that contract.

@steipete
steipete force-pushed the codex/99393-pdf-fractional-pages branch from 6ef2bbe to a19643b Compare July 6, 2026 05:21
@steipete
steipete force-pushed the codex/99393-pdf-fractional-pages branch from a19643b to f3233b1 Compare July 6, 2026 05:33
@clawsweeper clawsweeper Bot added rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. labels Jul 6, 2026
@steipete
steipete merged commit ae4a1e2 into openclaw:main Jul 6, 2026
112 of 114 checks passed
@steipete

steipete commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Merged via squash.

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 6, 2026
@qingminglong @steipete
fix(pdf): reject fractional page selections (openclaw#99399)
41ac80d 
* fix(pdf): reject fractional page selections

* chore: refresh pdf fractional page checks

* chore: refresh failed checkout checks

* test(pdf): prove fractional pages fail at tool boundary

* test(pdf): cover mixed fractional page ranges

* fix(pdf): validate page selections before loading

---------

Co-authored-by: Peter Steinberger <[email protected]>
@steipete steipete mentioned this pull request Jul 6, 2026
Merged
giodl73-repo pushed a commit to giodl73-repo/openclaw that referenced this pull request Jul 8, 2026
@qingminglong @steipete @giodl73-repo
fix(pdf): reject fractional page selections (openclaw#99399)
58da44a 
* fix(pdf): reject fractional page selections

* chore: refresh pdf fractional page checks

* chore: refresh failed checkout checks

* test(pdf): prove fractional pages fail at tool boundary

* test(pdf): cover mixed fractional page ranges

* fix(pdf): validate page selections before loading

---------

Co-authored-by: Peter Steinberger <[email protected]>
@clawsweeper clawsweeper Bot mentioned this pull request Jul 12, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@steipete steipete

Labels

agents Agent runtime and tooling merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: PDF tool accepts fractional page numbers that select no extracted pages

2 participants

@qingminglong @steipete