fix(session): bound oversized PDF requests

[Astro-Han]

Summary

Keep path-backed PDFs out of provider payloads, bound aggregate media projected into each model request, and recover safely from HTTP 413 by retrying only materially smaller media projections.

There is no related GitHub issue; this PR addresses a directly reported desktop bug where attaching many PDFs could make the model request unresponsive.

Why

Path-backed PDFs were automatically read and promoted into inline base64 media whenever the selected model accepted PDF/image input. Multiple PDFs therefore expanded one user turn into a large provider request without an aggregate count or byte budget. HTTP 413 was also treated as token context overflow, which sent a request-body problem into compaction instead of reducing media.

Related Issue

None. This came from a direct user bug report.

Human Review Status

Pending

Review Focus

Please focus on the request-only projection boundary, the 8-item / 12 MiB aggregate media limits, and the finite HTTP 413 recovery path. In particular, verify that explicit context-overflow evidence still wins over a bare 413 and that no retry is sent when the next media projection would be identical.

Risk Notes

The main behavioral tradeoff is that older media can be represented by omission markers once the aggregate provider-request budget is reached; durable conversation history and original file paths remain unchanged. HTTP 413 recovery is limited to projections with a strictly smaller selected-media set and still passes through the existing side-effect safety gate.

The visible-UI conditional checklist item is left unticked because no UI or copy surface changed. The docs/release/dependency conditional item is left unticked because this PR changes no docs, release metadata, dependencies, permissions, credentials, deletions, generated files, or local-only files.

How To Verify

Message projection + processor regression suites: 152 passed, 0 failed
Prompt user-path checks (normal LLM call and PDF path-only attachment): 2 passed, 0 failed
Compaction + prompt adjacent suites: 121 passed, 0 failed
TypeScript typecheck: passed
Final independent review: no remaining reproducible P0-P3 findings
Git diff whitespace check: passed

Screenshots or Recordings

Not applicable — no visible UI changes.

Checklist

How to use this checklist:

• Tick a box by replacing [ ] with [x]. Do not edit, add, or remove items.
• The bot-applied label items can only be honestly ticked AFTER the PR is opened and the labeler / priority-triage bots have run — return to the PR description and tick them then.
• Most items are required. The few that are conditional are explicitly marked (conditional); for those, leave unticked if they truly do not apply and explain why in Risk Notes. All other items must be ticked before requesting human review.

• Type label — this PR carries exactly one of bug, enhancement, task, documentation. Type labels are author-added; the labeler bot does NOT assign them. Add the label in the GitHub UI, then tick this.
• Routing labels — this PR carries at least one of app, ui, platform, harness, ci. The labeler bot assigns these on PR open based on changed paths. Confirm the bot's choice (or override if wrong), then tick this.
• Priority label — this PR carries exactly one of P0, P1, P2, P3. The priority-triage bot suggests one on PR open. Confirm or override, then tick this.
• Human Review Status above is set to Pending, Approved by @<reviewer>, or Not required: <reason> (default is Pending; "not required" is restricted to bot-authored low-risk PRs).
• I linked the related issue, or stated in Summary why there is no issue.
• I described the review focus and any meaningful risks.
• I replaced the example block in How To Verify with the real verification steps and the key result for each.
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope.
• (conditional) I manually checked visible UI or copy changes when needed, with screenshots or recordings. Leave unticked only if no visible UI or copy changed.
• (conditional) I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes. Leave unticked only if no platform/packaging surface was touched.
• (conditional) I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant. Leave unticked only if none of those surfaces was touched.
• I reviewed the final diff for unrelated changes and suspicious dependency changes.
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English.

Summary by CodeRabbit

• New Features

  • Automatically retries oversized requests by progressively degrading media attachments (preserve → degraded → stripped) until success or exhaustion, including stream and message replay.
  • Added configurable media projection when preparing prompts, with consistent omission/placeholder behavior for both normal and tool outputs.

• Bug Fixes

  • More precise error classification for request/payload-too-large vs context overflow, with correct handling of HTTP 413 and improved retry/non-retry decisions.
  • Treats PDFs as documents for path-only attachment rendering; recognizes audio/video as media.

• Tests

  • Expanded coverage for progressive 413 recovery, media projection selection/budgeting, and PDF/path-only behavior.

[github-actions]

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: abd55613-da93-49db-bdfb-9d6456f0b508

📥 Commits

Reviewing files that changed from the base of the PR and between 4b17df2 and dbf7ee3.

📒 Files selected for processing (7)

• packages/opencode/src/provider/error.ts
• packages/opencode/src/session/message-v2.ts
• packages/opencode/src/session/processor.ts
• packages/opencode/src/session/prompt.ts
• packages/opencode/src/util/media.ts
• packages/opencode/test/session/message-v2.test.ts
• packages/opencode/test/session/processor-effect.test.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• packages/opencode/src/session/prompt.ts
• packages/opencode/test/session/message-v2.test.ts
• packages/opencode/src/session/message-v2.ts
• packages/opencode/src/provider/error.ts
• packages/opencode/src/session/processor.ts

---

📝 Walkthrough

Walkthrough

The change separates request-size failures from context overflow, adds budgeted media projections, and retries oversized model requests with degraded and stripped media. PDFs use path-only handling, while compaction and tests adopt the new projection behavior.

Changes

Request-size media recovery

Layer / File(s)	Summary
Request-size error classification packages/opencode/src/provider/error.ts, packages/opencode/src/session/message-v2.ts, packages/opencode/test/session/message-v2.test.ts	Stream and API errors now expose request_too_large, classify HTTP 413 separately from context overflow, and map the result to a non-retryable invalid-request API error.
Media projection and serialization packages/opencode/src/session/message-v2.ts, packages/opencode/src/session/compaction.ts, packages/opencode/src/session/prompt.ts, packages/opencode/src/util/media.ts, packages/opencode/test/session/message-v2.test.ts, packages/opencode/test/session/prompt-effect.test.ts	Model messages select media by projection and aggregate budgets, replace omitted attachments with placeholders, apply the stripped projection during compaction, recognize audio and video media, and keep PDFs path-only.
Progressive media retry recovery packages/opencode/src/session/processor.ts, packages/opencode/src/session/prompt.ts, packages/opencode/test/session/processor-effect.test.ts	Session processing detects oversized requests, obtains reduced media messages, and replays attempts through degraded and stripped projections before stopping or succeeding.
Before-progress retry policy packages/opencode/src/session/run-incident/policy.ts	Initial auto-retry eligibility no longer requires a terminal cause categorized as occurring before provider progress.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SessionProcessor
  participant nextMediaMessages
  participant MessageV2
  participant LLM
  SessionProcessor->>LLM: submit normal media messages
  LLM-->>SessionProcessor: request_too_large
  SessionProcessor->>nextMediaMessages: request reduced projection
  nextMediaMessages->>MessageV2: nextMediaMessages(current)
  MessageV2-->>nextMediaMessages: degraded or stripped projection
  nextMediaMessages->>MessageV2: render projected model messages
  MessageV2-->>nextMediaMessages: reduced messages
  nextMediaMessages-->>SessionProcessor: projection and messages
  SessionProcessor->>LLM: replay with reduced media

Loading

Possibly related PRs

• Astro-Han/pawwork#155: Both changes modify shared media MIME classification in util/media.ts.
• Astro-Han/pawwork#863: Both changes modify session retry decision flow in processor.ts.
• Astro-Han/pawwork#1466: Both changes modify provider error classification in provider/error.ts.

Suggested labels: desktop

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: limiting oversized PDF/session requests and retry behavior.
Description check	✅ Passed	All required sections are present, and the checklist/risk/verification details are complete with reasons for conditional unticks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/pdf-request-projection

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}