change-browser-runtime

Change the Browser Runtime

Trace the Shared Contract

1. Read Browser runtime, packages/product-runtime/AGENTS.md, apps/web/AGENTS.md, and apps/desktop/AGENTS.md.
2. Identify the owner key and whether the behavior is canonical runtime state, a BrowserControl command/result, a read-only event, presentation selection, host signaling, or Web UI state.
3. Trace the change across Browser schemas/runtime, control and route handlers, persistence and reaping, Browser tools, Desktop host/view handlers, remote host/WebRTC data channel, generated SDK where applicable, and the Web Browser store/surface.
4. Load change-server-api for route/schema changes, develop-frontend for product UI, change-persistence for saved Browser state, and change-execution-boundaries for navigation or evaluation policy.

Preserve Ownership and Presentation

1. Keep one Browser session per owner and at most one canonical page per Browser session. Do not introduce a tab adapter or merge host-only pages into canonical state.
2. Keep page creation lazy. State reads, event subscriptions, signaling, and host attachment may ensure the owner session exists but must not create a page; ordinary first navigation owns page creation.
3. Keep POST /browser/control command/response behavior separate from the read-only /browser/events stream. Return explicit page-missing, host-pending, retryable, and terminal errors.
4. Preserve Desktop-native WebContentsView and remote WebRTC/data-channel presentation as peer modes over the same owner/page/control contract. Do not add iframe, screenshot-stream, pseudo-tab, or hidden fallback pages.
5. Treat managed-local Desktop native presentation as strict. Bootstrap may passively read the owner key without a ticket, but events and controls require fresh owner-bound tickets after host.registered; ticket, attach, renderer, and navigation failures remain in native recovery and never fall back to WebRTC. Web and remote Desktop select WebRTC explicitly.
6. Keep pointer, keyboard, text, IME/paste, and viewport coordinates normalized across native and remote presentation. Preserve CSS width/height semantics and coalesced pending viewport behavior.
7. Keep Chromium responsible for webpage network security. The gateway owns loopback binding, owner authentication, connection limits, CONNECT-establishment timeout, forwarding, and revoke cleanup; do not add IP-range classification, Fake-IP exceptions, localhost port lists, or DNS policy. Preserve protocol checks, workspace file containment, hidden/project metadata exclusions, download filtering, and sensitive-header redaction.
8. Treat the server-provided session-state ownerKey as canonical. Route directories select a route; they never derive native tickets, profiles, broker pages, or view attachment identity.
9. Keep a native owner/page handle stable while replacing its WebContentsView, control, and diagnostics generation. Preserve page/profile/proxy/URL/bounds/visibility/focus identity and page-scoped recovery status. Treat resume as the idempotent recovery entry: a healthy page returns state without replacing its generation, an in-flight recovery is awaited, and failed recovery starts a new bounded flight with only the transient budget reset. Rate-limit resume-driven recovery (15s cooldown) so the Agent path cannot loop a failing page; the native Retry control bypasses the cooldown. During restarting or failed, reject side-effect commands with browser_native_restarting or browser_native_recovery_failed while allowing resume, close, stop, and safe observations; emit ready only after the recovery guard clears, and never replay an action whose execution outcome is unknown.
10. Dispose live Browser state on session archive/delete and global shutdown; preserve profile, storage-state, download, annotation, and restored page-ID ownership.
11. Keep Browser implementations out of the Agent worker runner's static dependency graph. Only serializable Browser tool definitions cross into the worker; callbacks, canonical sessions, Playwright/Chromium state, host signaling, native views, and WebRTC state remain Control Plane/tool-runtime owned.
12. Attribute resource state by owner and page backend without exposing owner IDs. Retire the remote Host only after the broker reports no active canonical page; Performance aggregation must never close a page or stop the Host.
13. Keep Browser viewer Origin authorization on explicit server CORS origins. Do not promote auto-detected LAN CORS origins or reverse-proxy forwarding headers into the viewer trust boundary. Origin checks supplement one-shot owner/page/role-bound tickets and never replace them.