fix(browser): update Gemini web protocol and fallback handling

[mpeter]

Update Gemini web request framing and current model headers, return clear errors for upstream failures/empty responses, and add --no-gemini-fallback while retaining fallback by default and through restarted sessions.

Maintainer repair preserves the model/thinking selectors and client UUID in the header as well as the new payload fields. It also keeps raw gg-dl image recovery reachable through the success guard. Oversized Google response headers now produce actionable Node startup guidance; the process's configured fetch/proxy/TLS transport is preserved.

Validation on a25365a160db8952dde6a94aed2c87d191528520:

• Typecheck, lint, build, docs/help checks, and full suite: 2,000 passed, 43 skipped.
• Real built CLI: text reply, PNG attachment interpretation, image generation, and image editing all succeeded with --no-gemini-fallback and the requested gemini-3.1-pro route.
• The host needed the documented NODE_OPTIONS=--max-http-header-size=65536 for Google's session headers. No private dispatcher or new runtime dependency was introduced.
• Generated and edited images decode as 1024×1024 JPEGs; bytes/hash changed and the requested red triangle appears in the edit. These are synthetic test assets, inspected and stripped of metadata before upload.
• Final branch autoreview through P2 is scoped-clean. CI: https://github.com/steipete/oracle/actions/runs/34111459874.

Generated source (left), edited result (right):

The live runs establish the requested route and pipeline behavior; they do not independently attest Google's backend model identity. Changelog credit is collected in the final notes PR.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 7, 2026, 6:33 AM ET / 10:33 UTC.

ClawSweeper review

What this changes

Updates Oracle’s cookie-based Gemini requests and model headers, rejects failed or empty responses, adds a persisted fallback opt-out, and explains oversized response-header failures.

Merge readiness

✅ Ready for maintainer review

The PR remains useful: main and v0.18.0 retain the older request framing and error handling. No blocking introduced defect was found, and the updated validation addresses the previous attachment/image coverage concern. Repository policy also excludes automatic closure.

Likely related people: steipete and Michal Kubenka are routing candidates from relevant main-branch history; exact source-line attribution remains unverified.

Priority: P2
Reviewed head: a25365a160db8952dde6a94aed2c87d191528520

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, compatibility-preserving repair with reported real-path coverage and no blocking finding.
Proof confidence	🐚 platinum hermit (4/6) ✨ media proof bonus	Sufficient (linked_artifact): The captured head-specific report exercises the built CLI through the Gemini executor and HTTP client for text, attachments, generation and editing, with fallback disabled and observed output checks. It resolves the previous coverage concern; the unavailable image preview is a reviewer limitation, and Google’s backend model identity remains outside the claim.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (linked_artifact): The captured head-specific report exercises the built CLI through the Gemini executor and HTTP client for text, attachments, generation and editing, with fallback disabled and observed output checks. It resolves the previous coverage concern; the unavailable image preview is a reviewer limitation, and Google’s backend model identity remains outside the claim.
Evidence reviewed	8 items	Repository policy and identity: The origin identifies steipete/oracle. Root AGENTS.md was read fully; no nested AGENTS.md was found under the changed directories, and .agents/maintainer-notes was absent. Changelog guidance was considered alongside the owner-authored release-notes PR. Introduced change verified: The local base-to-head diff matches the host’s introduced file set: 13 files, 350 additions and 52 deletions. The supplied verified test merge has the pinned main and head parents. All introduced hunks were inspected locally, including patches truncated in the prompt. Compatibility-preserving fallback: Fallback is disabled only by an explicit false value. New sessions persist the choice, and restart passes it back into the executor; older records without the optional field retain fallback. The success guard preserves raw gg-dl image recovery.
Findings	None	None.
Security	None	None.

How this fits together

Oracle’s Gemini web executor takes prompts, attachments, model choices, and signed-in browser cookies, then calls Google’s web endpoints. It returns answers and saves generated or edited images through the browser-engine session workflow.

flowchart TD
  A[CLI options and saved sessions] --> B[Gemini web executor]
  C[Browser cookies and attachments] --> B
  B --> D[Build model headers and request]
  D --> E[Google web endpoints]
  E --> F[Validate response and fallback policy]
  F --> G[Answer and saved images]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +138/-36; tests +200/-14	Production growth supports protocol framing, response validation and fallback control, with focused regression coverage.
Reported real CLI coverage	4 scenarios on the reviewed head	Text, attachment interpretation, image generation and image editing cover the shared request path.

Technical review

Best possible solution:

Keep the refreshed protocol with default fallback, explicit strict selection, restart compatibility, and clear upstream errors.

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

Yes for the error-handling defect: main returns upstream error outputs without rejecting them, and the executor can turn those into an empty answer. Live protocol failure on main was not independently reproduced.

Is this the best way to solve the issue?

Yes. The patch updates the existing Gemini client, retains fallback for existing users, and adds strict selection without replacing the configured transport.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 1c5ac1b38d64.

Labels

Label changes:

• add P2: This is a bounded Gemini web reliability improvement with preserved default behavior and supplied real-run validation.
• remove P1: Current review triage priority is P2, so this older priority label is no longer current.
• remove merge-risk: 🚨 availability: Current PR review selected no merge-risk labels.

Label justifications:

• P2: This is a bounded Gemini web reliability improvement with preserved default behavior and supplied real-run validation.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (linked_artifact): The captured head-specific report exercises the built CLI through the Gemini executor and HTTP client for text, attachments, generation and editing, with fallback disabled and observed output checks. It resolves the previous coverage concern; the unavailable image preview is a reviewer limitation, and Google’s backend model identity remains outside the claim.
• proof: sufficient: Contributor real behavior proof is sufficient. The captured head-specific report exercises the built CLI through the Gemini executor and HTTP client for text, attachments, generation and editing, with fallback disabled and observed output checks. It resolves the previous coverage concern; the unavailable image preview is a reviewer limitation, and Google’s backend model identity remains outside the claim.

Evidence

What I checked:

• Repository policy and identity: The origin identifies steipete/oracle. Root AGENTS.md was read fully; no nested AGENTS.md was found under the changed directories, and .agents/maintainer-notes was absent. Changelog guidance was considered alongside the owner-authored release-notes PR. (AGENTS.md:1, a25365a160db)
• Introduced change verified: The local base-to-head diff matches the host’s introduced file set: 13 files, 350 additions and 52 deletions. The supplied verified test merge has the pinned main and head parents. All introduced hunks were inspected locally, including patches truncated in the prompt. (src/gemini-web/client.ts:238, a25365a160db)
• Compatibility-preserving fallback: Fallback is disabled only by an explicit false value. New sessions persist the choice, and restart passes it back into the executor; older records without the optional field retain fallback. The success guard preserves raw gg-dl image recovery. (src/gemini-web/client.ts:466, a25365a160db)
• Main and release still need the change: Inspected main and v0.18.0 client source: both retain the compact request payload and return upstream error outputs without the new success guard. The local v0.18.0 tag resolves to the supplied release commit; no local tag contains the PR head. (src/gemini-web/client.ts:234, 1c5ac1b38d64)
• Updated real behavior evidence: The captured body at sourceRevision dc883fb1d1eca10a50ac9cc3ca8758c51363a4aa13857d2c2b1cc1723183a815 reports built-CLI text, PNG interpretation, image generation and image editing on the exact head, using gemini-3.1-pro with fallback disabled. It records decoded 1024×1024 JPEG outputs and the requested red-triangle edit. This addresses the previous optional rank-up. The linked image could not be fetched by the reviewer; it was not independently visually verified. Reported live results, rather than CI or the image alone, support the proof assessment. (a25365a160db)
• Transport and dependency review: The new HTTP helper delegates directly to configured global fetch and only annotates header-overflow errors. The lockfile adds integrity-pinned undici 7.29.1 as an already-declared optional OpenAI peer; the Gemini implementation does not import it. No new lifecycle script, credential destination, permission, or private dispatcher is introduced. (src/gemini-web/http.ts:6, a25365a160db)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Michal Kubenka: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (5 earlier review cycles)

• reviewed 2026-08-18T05:24:37.454Z sha 0be49e5 :: needs maintainer review before merge. :: none
• reviewed 2026-08-24T07:13:17.379Z sha 0be49e5 :: needs maintainer review before merge. :: none
• reviewed 2026-08-30T08:06:44.409Z sha 0be49e5 :: needs maintainer review before merge. :: none
• reviewed 2026-08-31T14:52:06.505Z sha 79b4668 :: needs maintainer review before merge. :: none
• reviewed 2026-08-31T19:08:57.987Z sha 79b4668 :: needs maintainer review before merge. :: none

[steipete]

Final maintainer proof on a25365a160db8952dde6a94aed2c87d191528520 is complete. All four CI jobs passed: https://github.com/steipete/oracle/actions/runs/34111459874.

The built CLI completed real Gemini text, PNG attachment interpretation, image generation, and image editing with --no-gemini-fallback, requesting gemini-3.1-pro. The documented NODE_OPTIONS=--max-http-header-size=65536 accommodated Google's response headers without replacing the process's configured fetch/proxy/TLS transport. Both output images decoded as 1024×1024 JPEGs, their hashes differed, and the edit visibly added the requested red triangle. The inspected synthetic comparison is in the PR body.

Typecheck, lint, build, docs/help checks, and the full suite passed (2,000 tests; 43 skipped). Final branch autoreview through P2 is scoped-clean. The requested route and pipeline are proved; Google's actual backend model identity is not independently attested. Contributor credit is retained, and the changelog entry is collected in #462.