fix(mcp): allow text-only preview snapshots

[juliusmarminge]

Closes #10187.

Repeated preview_snapshot calls add a PNG to each MCP result. Providers or gateways with image-count limits may reject the accumulated conversation.

Add optional includeImage. {"includeImage":false} returns fresh page metadata and JSON text without an image content part. Omitted or true preserves the existing PNG response. The flag stays inside the MCP server. Browser capture and the shared snapshot contract are unchanged.

The user selected this opt-in mitigation with current defaults preserved. It cannot remove images already in provider-owned history, does not stop host capture, and does not guarantee that a gateway accepts an existing conversation. The reporter's original gateway rejection was not replayed.

Verification on integrated main 585ce2c2:

• The registered MCP tool and real preview broker use a synthetic host. Exact-main before controls fail twice and pass 12 tests. The candidate passes all 14, including the existing HTTP session lifecycle test.
• Six text-only calls return fresh metadata with no image. A following default call returns PNG again. Repeated default and explicit-image calls preserve the PNG bytes and metadata. Tab targeting, bounded host errors and invalid inputs are covered.
• The orchestrator independently reviewed all four changed files, ran both sides, and passed scoped typecheck and changed-file lint. Two unchanged Effect suggestions remain in the server environment machine.

The subsequent f12d3935 main update does not change the MCP implementation or preview contracts. No client UI changed, so screenshots are not applicable. This is protocol/output evidence, not a browser, native or real-provider claim.

Ready for human review; unmerged. Current-head CI finished with 16 successful and four skipped checks. The orchestrator read all check outputs, annotations, comments and reviews; no unresolved finding remains. The configured Cursor review is paused by its spending limit, so its successful dispatch is not claimed as a code review.

Implemented with GPT 6 Astra via Codex in T3 Code.

Note

Allow text-only preview snapshots in McpHttpServer

• Adds test coverage for includeImage=false and omitted includeImage in preview_snapshot, verifying failure responses stay bounded and omit image content
• Adds a parameterized integration test confirming repeated preview_snapshot calls return fresh metadata with distinct titles, include a PNG by default or when explicitly enabled, and omit it when disabled
• Adds rejection tests for non-boolean includeImage values (string, numeric, null), asserting they fail with an AiError summary before browser-host selection
• Risk: no behavioral change beyond test coverage; all modifications are in McpHttpServer.test.ts

^{Macroscope summarized 3d458d3.}

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[macroscopeapp]

Approvability

Verdict: Approved at 3d458d3

Macroscope's review found this PR approvable — This preserves existing PNG responses by default while adding a small, explicitly selected includeImage=false MCP option that returns the same metadata without the image content part. Browser capture and shared contracts remain unchanged, and the new behavior is covered by focused integration tests.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.6 KiB	13.5 KiB	−56 B (−0.4%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.0 KiB	−7 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.6 KiB	6.5 KiB	−49 B (−0.7%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.1 KiB	57.0 KiB	−88 B (−0.2%)	66.4 KiB	✅
Codex	Live turn messages	10	8	−2 (−20.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.6 KiB	+39 B (+0.3%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.0 KiB	7.0 KiB	+9 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+30 B (+0.5%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.8 KiB	57.8 KiB	+44 B (+0.1%)	66.4 KiB	✅
Claude	Live turn messages	8	9	+1 (+12.5%)	21	✅

Baseline: f12d393 · PR result: 3d458d3 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.