feat(mcp): list and close preview tabs

[juliusmarminge]

Agents could open and control collaborative browser tabs through MCP, but they could not discover every tab owned by the current thread or close one exact tab without using a client UI.

This adds bounded preview_list and explicit-tab preview_close tools. Listing reads only the server preview manager with a thread-bound keyset cursor. Closing uses the manager's existing close event, preserves foreign tabs, and clears the provider session's implicit broker tab behind a sequence barrier so an older automation response cannot restore the closed target.

Behavior:

• browser access remains gated by the credential's existing preview capability;
• list never selects a host, opens a browser, or navigates;
• close requires tabId, returns the exact closed ID, and reports missing, foreign, or repeated closes as PreviewSessionLookupError;
• connected clients receive the normal server-owned closed event and release the matching desktop webview;
• read-only Claude sessions can use the preview tools whose annotations are read-only.

Focused validation:

• 123 focused server/shared tests, including production HTTP tools/list, manager events, broker lease clearing, stable pagination, authority denial, and repeated close;
• contracts, shared, and server typechecks;
• targeted lint and formatting checks.

Dependency: standalone sibling based on agents/mcp-controls/base-490318a at 490318afa505d3d033295eca12d7e62b4b922725. It does not depend on the project or queue/input stacks.

Implemented by GPT-5.6-Sol via Codex in T3 Code.

---

Note

Medium Risk
Touches concurrent preview automation broker tab-leasing and close races; incorrect barriers could mis-route automation or leave stale tab targets, though behavior is heavily test-covered.

Overview
Agents can discover and tear down collaborative preview tabs for the current thread via new MCP tools preview_list and preview_close, without opening or attaching a browser host for listing.

preview_list reads server-tracked sessions only: thread-scoped keyset pagination (cursor / limit), stable cursors (hashed thread binding, size-capped), truncated load-failure diagnostics, and rejection of foreign-thread cursors. Access still requires the credential preview capability.

preview_close requires an exact tabId, closes through PreviewManager.closeExact (normal closed events for desktop clients), and calls PreviewAutomationBroker.forgetClosedTab so the provider session’s implicit “current tab” lease is cleared. The broker now commits tab assignments only after successful responses and uses close sequence barriers so in-flight or late host responses cannot resurrect a closed tab or steal routing from another tab; barriers retire on timeout, failure, or interrupt.

Wiring includes PreviewMcpService, contract schemas/errors, toolkit handlers and registration, Claude read-only allowlist updates for annotated read-only preview tools, UI presentation strings, and user/docs notes on agent browser controls.

^{Reviewed by Cursor Bugbot for commit 66853ce. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add Orchestration V2 system with MCP toolkits for preview, orchestrator, and worktree operations

• Introduces a full Orchestration V2 backend: event store, projection store, provider adapters (Claude, Codex, Cursor, OpenCode, Grok, ACP Registry), checkpoint capture/rollback services, effect outbox, thread launch/lifecycle management, scheduled tasks, and legacy V1 importer. Backed by migrations 044–052 creating the V2 persistence schema.
• Adds three MCP service toolkits registered on the HTTP server: PreviewMcpService (list/close preview tabs with cursor pagination), OrchestratorMcpService (thread/task lifecycle, delegation, scheduling), and WorktreeMcpService (git worktree handoff and status). Each enforces capability-scoped access via McpInvocationContext.
• Migrates web and mobile clients to V2 types: shell/thread projections, bounded snapshot loading with progressive history paging, queue workflow controls, thread relationships panel, scheduled tasks settings, legacy migration toast, and composer UI refactors using ComposerBanner primitives.
• Includes extensive provider replay testkit infrastructure with deterministic runtime fixtures across all built-in providers and scenarios (interrupts, forks, subagents, rollbacks, web search, queued turns, steering).
• Behavioral Change: OrchestrationCommandReceipt schema now requires a commandType string field; ProviderInstance.adapter renamed to orchestrationAdapter with type ProviderAdapterV2Shape; LatestTurnTiming/SessionActivityState renamed to LatestRunTiming/RuntimeActivityState with turnId→runId and activeTurnId→activeRunId; WebSocket RPC methods switched from ORCHESTRATION_WS_METHODS to ORCHESTRATION_V2_WS_METHODS; requireMcpCapability signature narrowed to only accept 'preview'; cache schema version bumped to 3 and old V1 entries are auto-discarded on decode failure; ModelSelection encoding now emits instance-based canonical form instead of legacy provider-based form.

^{Macroscope summarized fe4579d.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: af2e649c-fb40-40e4-b286-86d16fb45f85

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

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

[github-actions]

Thread transfer impact

⚠️ The latest CI run did not produce a thread transfer result for fe4579d.

This comment will update automatically after the next completed run.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds two production MCP operations, including destructive tab closure, and changes broker lease and response-ordering behavior used by existing preview automation. Capability gating and focused tests reduce risk, but the cross-component runtime changes and concurrency logic exceed a bounded additive change.

No code changes detected at fe4579d. Prior analysis still applies.

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit 319a8eb. Configure here.}

[juliusmarminge]

Superseded as the active MCP proposal by #10559 in the rebuilt MCP stack, following the maintainer request to review thin service wrappers separately from service hardening.

This is not a full feature-parity replacement. The existing preview capability and browser-access setting are required. Close uses the existing server/host lifecycle and does not claim renderer cleanup has finished. Broker race hardening is separate.

Closing this mixed proposal without merging. The remote branch agents/mcp-preview-controls/list-close and exact head fe4579dfa694932d79da94dacefaf372d0deeee9 are retained so the service changes can be extracted for separate review later.