Browser automation and embedded web
The browser system gives each workspace a managed web session for people, agents, extensions, and remote runtimes. It keeps browser state, page authority, network egress, input, files, prompts, and rendered output within clear ownership boundaries. This page is a companion to desktop app platform, with related context in desktop renderer experience, relay protocol and transport, desktop persistence and lifecycle, and command-line and headless runtime.
The main model has five parts: a session owns browser state, a guest shows a page, bridges carry control, a route selects network egress, and a host lease carries remote work. A page identity connects these parts so a page can be automated, streamed, moved, or closed without losing its policy boundary.
This diagram shows how a workspace page connects storage, policy, control, network routing, and remote execution.
flowchart LR
Profile[Browser profile] --> Session[Managed browser session]
Session --> Guest[Embedded page guest]
Session --> Extensions[Profile extensions]
Guest --> Person[Desktop user]
Guest --> CDP[CDP bridge]
CDP --> Agent[Agent-browser helper]
Guest --> Files[Download and upload channels]
Session --> Route[Network route]
Route --> Remote[Remote browser workspace]
Remote --> Stream[Screencast and input bridge]
Remote --> CLI[Remote CLI host lease]
Managed browser sessions
Managed browser sessions give each browser profile its own state and policy. Startup prepares that state before a page can load, while route sessions add a separate network owner when a page runs on another host.
Session profiles
A session profile is the durable identity for one browser storage area. The default profile follows the active desktop profile. Isolated and imported profiles give workspaces separate cookie jars without allowing a renderer or CLI caller to choose arbitrary storage paths.
Profile state includes cookies, site decisions, browser identity, and extension state. Session cookies that Chromium does not persist are saved in protected snapshots and restored before a restored tab loads. Cookie import uses the destination route or local profile that will own the page, so a server cookie jar is not confused with the desktop jar.
Profile deletion removes the profile from admission and retires its browser state. The same retirement also ends page prompts, WebAuthn requests, route data, and extension data that belong to the profile.
References: src/…/browser-session-registry.ts• L1-237 src/…/browser-session-startup.ts• L22-77 src/…/browser-session-cookie-restore.ts• L48-99 src/…/browser-session-cookie-snapshot-file.ts• L39-92 src/…/browser-client-route-cookie-import.ts• L36-123
Session policy
Each session has one policy boundary for permissions, downloads, proxy settings, certificates, user-agent identity, file access, clipboard access, and WebAuthn. Site permissions stay tied to the profile and site origin. Safe browser functions can receive automatic grants. Sensitive requests use a prompt or a stored profile decision.
The policy changes with page ownership. A page that another machine drives can lose file access, clipboard reads, and other local capabilities even when a local browsing page in the same named profile can use them. A preview session is stricter still: it has no ordinary browsing, download, or device authority.
Request policy and extension observation share the session request path. Orca owns the session hooks and forwards allowed request events to extensions, which keeps browser policy and extension behavior from replacing each other.
References: src/…/browser-session-partition-policies.ts• L58-132 src/…/browser-session-request-decisions.ts• L7-35 src/…/browser-session-web-request-observer.ts• L1-93 src/…/browser-extension-web-request-observer.ts• L30-137
Profile extensions
Profile extensions are optional browser features that run inside local browser profiles. Their permissions, content scripts, request observers, menus, side panels, notifications, and worker state follow the profile that activated them.
An extension profile can stop when its last page closes while its saved data remains. Reinstall and uninstall flows separate old data from a new install, and profile deletion removes extension data even when the extension was disabled. Extension surfaces and notifications remain owned by their extension and profile rather than becoming ordinary tabs or desktop-wide actions.
References: src/…/browser-extension-session-loader.test.ts• L258-341 src/…/browser-extension-data-removal.ts• L70-145 src/…/browser-extension-profile-state-store.ts• L31-60 src/…/notifications.ts• L40-67 src/…/notifications.ts• L111-156
Session startup
Session startup is an admission gate for browser partitions. It configures profile storage, route bindings, cookie snapshots, extension data, request policy, and proxy readiness before restored tabs can use a partition.
The startup order prevents a page from opening with an old cookie jar, missing request hooks, or a direct network path. Restored tabs wait for proxy setup and cookie restore within a bounded launch window. A slow restore does not prevent the browser from opening; it leaves the affected page signed out or otherwise reports the failure instead of using unprepared state.
References: src/…/browser-session-startup.ts• L34-77 src/…/browser-session-registry.test.ts• L121-157 src/…/browser-session-partition-policies.ts• L60-114 src/…/browser-session-cookie-restore.ts• L101-169
Embedded page guests
An embedded page guest is the browser content shown inside a desktop workspace. The browser manager gives the guest an owner, navigation rules, popup rules, prompt handling, page state, and teardown behavior. A document preview is also a guest, but it has grant-bound file authority instead of normal browsing authority.
Guest navigation
Normal guests accept supported web navigation and block attempts to reach local files or unsupported schemes. The page identity follows the document that commits, not a failed or provisional target. This keeps the address bar, load errors, certificate actions, prompts, and retry controls attached to the correct page.
Navigation keeps the requested target separate from the last committed URL. This lets the UI and automation report a stalled or failed request without treating an error page or an old document as the new page. A load stall notice can identify whether a request is waiting for policy, headers, or a response. It also gives context about hidden pages using the same host.
Browser identity follows the committed page. Mobile emulation changes the user-agent identity and client hints together. Sign-in pages can use the identity expected by the sign-in service without changing unrelated pages.
References: src/…/browser-manager-guest-navigation-policy.ts• L1-175 src/…/browser-navigation-stall-watchdog.ts• L89-153 src/…/browser-session-ua.ts• L29-88 src/…/browser-url.ts• L272-336
Guest policy profiles
Browsing guests and workspace-document guests have different authority. Browsing guests can navigate, open controlled popups, use automation, and request page capabilities. Document guests stay inside a grant-bound preview and can report approved web links to their host without becoming general browsing pages.
The document preview session reads only files covered by a live workspace grant. It blocks network access, downloads, and unsafe device access. Its content policy prevents preview content from sending file data to the network. Ranged reads support large media without loading the whole file at once, and each chunk must still match the same file version. Revoking the grant removes the guest's ability to read the file.
References: src/…/browser-manager-guest-policy.ts• L24-54 src/…/browser-manager-guest-policy.ts• L207-274 src/…/doc-preview-protocol.ts• L34-59 src/…/doc-preview-protocol.ts• L79-161 src/…/doc-preview-file-reader.ts• L157-192 src/…/doc-preview-file-reader.ts• L228-320
Guest registration
Guest registration binds a native guest to a logical page, its renderer, workspace, worktree, and profile. Policy attaches before registration, so early navigation, prompts, popups, downloads, and load failures cannot run without an owner.
Registration also replays events that arrived before the page record existed. A replaced guest must match the expected page identity and renderer generation. If it does not, the browser refuses the mount rather than leaving an old or privileged guest visible.
References: src/…/browser-manager-registration.ts• L16-117 src/…/browser-manager-registration.ts• L119-188 src/…/browser-manager-event-forwarding.ts• L16-109
Guest lifecycle
Guest lifetime follows page identity and authority. When a page closes, crashes, is replaced, or loses its renderer, the system revokes page authority, cancels page-owned work, releases prompts, and removes the old guest from its indexes.
Hidden pages can remain mounted when automation, remote viewing, capture, mobile driving, or a download still needs them. Memory Saver can later retire an idle hidden guest while keeping its navigation history and page identity for a cold restore. The policy uses page visibility rather than only native window visibility, so a background tab does not become active because the window was restored.
References: src/…/browser-manager-guest-cleanup.ts• L5-65 src/…/browser-page-memory.ts• L169-225 src/…/browser-page-memory.ts• L228-305 src/…/browser-page-idle-discard.ts• L44-95 src/…/browser-guest-page-visibility.ts• L1-77 src/…/browser-guest-page-visibility-report.ts• L1-18
Page interaction state
Navigation, load errors, certificate failures, viewport changes, active-page state, and prompt state update the page record shown by the renderer. The same page identity tells local and remote flows which runtime owns the page.
Automation can move Chromium focus into a guest. The browser protects the user's prior focus, refuses input while an input method is composing text, and releases held input when an owner is revoked. An agent action can mark its page as active for a short handoff window, so a person's new tab waits instead of interrupting an in-flight agent action.
Visibility and activity are separate from tab selection. A page can remain usable for an agent or remote viewer without becoming the user's visible tab. Pointer activity is shown only while an agent command is executing and only when the page surface can display it.
References: src/…/browser-agent-activity.ts• L71-131 src/…/browser-agent-activity.ts• L155-194 src/…/person-pick-hold.ts• L4-47 src/…/browser-manager-guest-policy.ts• L66-101
Page prompts
Page prompts give the desktop one place to handle permission requests, external application opens, WebAuthn choices, HTTP authentication, certificates, and JavaScript dialogs. A prompt is tied to the requesting page and closes when that page navigates, crashes, or is destroyed.
JavaScript dialogs pause page work until a person, an agent, or a phone answers them. Each page has one active dialog. A second frame's dialog is dismissed instead of replacing the prompt that the owner can see. Passkey requests use the same page-owned answer path, but automation can only dismiss them.
References: src/…/browser-javascript-dialogs.ts• L27-139 src/…/browser-webauthn-profile-delete.test.ts• L123-167 src/…/browser-certificate-request-guard.ts• L38-122
Browser interaction bridges
Browser interaction has two local control paths. CDP (Chrome DevTools Protocol) exposes a browser command surface for compatible clients. The agent-browser bridge uses a page-scoped helper for higher-level actions. Both paths resolve a page before each operation and stop when that page or its owner is no longer valid.
CDP bridge
The CDP bridge gives one local client a loopback WebSocket endpoint for one guest. It forwards browser commands while adapting navigation, DOM focus, input, screenshots, printing, and frame targets to embedded guests.
Synthetic sessions make embedded-page targets look like the sessions expected by Playwright and agent-browser. The bridge keeps client, focus, and capture state tied to the selected page. A client replacement clears that state so a new client cannot inherit an old target.
The bridge serializes input and protects user focus. It maps root-page input to the correct embedded frame and uses desktop-owned paths for captures and PDF when raw guest CDP behavior is unreliable.
References: src/…/cdp-ws-proxy.ts• L23-159 src/…/cdp-ws-proxy.ts• L198-321 src/…/cdp-debugger-channel.ts• L30-115
Agent-browser sessions
An agent-browser session is a named helper process pinned to one page's CDP endpoint. The bridge queues commands in page order and bounds process, wait, and result time. It retires the helper after repeated timeouts, page replacement, renderer replacement, or revocation.
The helper is isolated from user agent-browser settings, sockets, config files, profiles, and tabs. It uses the packaged native helper when available and a development or system binary only as a fallback. This keeps a user's independent agent-browser setup from changing Orca's page model.
The bridge supports snapshots, navigation, element actions, keyboard and pointer input, dialogs, evaluation, cookies, viewport and geolocation changes, network routes, request logs, screenshots, PDF output, downloads, and uploads. Raw commands remain page-scoped and cannot replace the selected browser, session, profile, window, or tab.
References: src/…/agent-browser-binary.ts• L7-34 src/…/agent-browser-process-environment.ts• L7-60 src/…/agent-browser-bridge-core-commands.ts• L25-223 src/…/agent-browser-bridge-interaction-commands.ts• L33-271 src/…/agent-browser-bridge-page-commands.ts• L35-207
Agent navigation and element actions
Agent actions resolve a fresh element or page target at the time of the action. Element actions run in the frame that owns the element, while page actions re-check the guest after navigation or a process swap.
Navigation waits for the committed main document rather than trusting an early native completion. It reports a clear failure for an unsupported URL, a failed load, or a page that disappears. Text entry uses the page's edit model and protects focus, so rich editors and input-method composition do not receive a stale or partial write.
Uploads intercept the page file chooser and release it when the page receives its files. Downloads claim the next page-owned download and can return while a long transfer continues. Cookie deletion targets the named cookie through the selected page rather than clearing the whole profile.
References: src/…/agent-browser-bridge-core-commands.ts• L87-199 src/…/agent-browser-bridge-element-calls.ts• L19-135 src/…/agent-browser-bridge-interaction-commands.ts• L65-147 src/…/agent-browser-bridge-page-commands.ts• L157-207 src/…/agent-browser-bridge-navigation.test.ts• L89-211
Action effects
Page actions return an effects record in addition to the action result. The bridge observes the selected page and workspace tabs, waits for navigation and a short period of DOM quiet, then reports bounded changes such as page updates, new tabs, popups, downloads, load errors, passkey requests, blocked print dialogs, and console errors.
The effects record normally contains only the snapshot delta since the agent's last reading. A page can withhold text when an action opens a secret. If the page guest changes or text is withheld, the bridge does not create a new reading baseline, so the next action must read the page again.
References: src/…/agent-browser-action-effects.ts• L25-200 src/…/agent-browser-withheld-page-text.ts• L1-13 src/…/agent-browser-bridge-action-effects.ts• L10-74 src/…/browser-format.ts• L165-232
Input and capture protection
Automation input can change Chromium focus, so the hosting pane records the user's prior focus and restores it after the operation. A focus guard refuses input when the pane cannot protect focus or when the user is composing text with an input method.
Screencast turns a page into an ordered frame stream. It applies the requested viewport to the guest, adapts to the size allowed by the embedder, acknowledges frames, keeps only the newest frame under backpressure, and uses a bounded snapshot when a live frame does not arrive. A stale layout cannot produce a frame that receives current input coordinates.
Capture and input hold the guest active long enough to produce a usable frame, then release the hold on success, cancellation, timeout, and revocation. A debugger, active capture, dialog, or other protected state also prevents memory discard.
References: src/…/browser-screencast-stream.ts• L35-181 src/…/browser-screencast-stream.ts• L198-267 src/…/browser-screencast-frame-pacer.ts• L29-149 src/…/browser-screencast-guest-view-limit.test.ts• L76-114 src/…/browser-page-memory.ts• L57-84
Remote browser workspaces
A remote browser workspace keeps the page on an execution runtime and shows it in the desktop as a screencast. The runtime owns the page process and network access. The desktop owns the page record, toolbar, displayed frame, input mapping, file handoff, and recovery controls.
Remote page lifecycle
The runtime can place a page on a paired desktop or keep it on its own browser. A client-hosted page has a workspace, browser profile, execution host, paired device, and host placement. Those identities are persisted so a restart can reconnect to the same logical page instead of creating an unrelated tab.
The desktop adopts an existing page or asks the runtime to create one. Creation prepares route policy and storage before the page mounts, then binds ownership before navigation so early downloads and popups have a safe owner. A host lease checks authority, runtime identity, protocol support, and page generation during attach and reconnect.
Client-page commands refuse stale placement, renderer, or generation data. A failed or revoked lease retires page work instead of leaving a page with unclear ownership. Persisted pages are restored only for known workspaces and valid page rows.
References: src/…/browser-client-page-opening.ts• L64-161 src/…/runtime-browser-page-registry.ts• L60-123 src/…/runtime-browser-page-registry.ts• L217-315 src/…/client-hosted-browser-page-persistence.test.ts• L18-51 src/…/client-page-recovery-actions.test.ts• L37-117
Remote page streams
The stream turns runtime frames into a desktop page surface. It starts or reuses one page, requests frames for the current viewport, and retries a dropped stream with bounded backoff. The pane keeps the last frame during an ordinary restart and clears it when the page or stream is known to be gone.
Stream failure, page failure, and certificate failure are separate states. The user can reconnect a stream, retry the page URL, approve a supported certificate challenge, or open a safe URL outside the remote page. The pane does not offer local DOM find because it displays pixels rather than a live page tree.
References: src/…/remote-browser-page-pane.tsx• L122-292 src/…/remote-browser-stream-lifecycle.ts• L33-115 src/…/browser-screencast-stream.ts• L159-267 src/…/browser-certificate-request-guard.ts• L89-187
Remote page input
The desktop maps pointer coordinates from the displayed frame, not from the full pane. It queues pointer, keyboard, touch, wheel, and clipboard operations in order and tags them with the current remote page operation. A stale operation is ignored, so input for an old page cannot change a replacement page.
Remote clipboard actions run inside the remote page and then write approved text to the desktop clipboard. They do not forward the host clipboard into the remote page by default. Uploads are converted to workspace-relative paths before the host reads them, and downloads use a negotiated file channel rather than the desktop's local Downloads folder.
References: src/…/use-remote-browser-page-input.ts• L20-235 src/…/use-remote-browser-page-keyboard.ts• L1-190 src/…/runtime-browser-client-automation.ts• L99-186 src/…/browser-client-page-refusal-copy.ts• L3-26
Browser tab targeting
Browser tab commands can target a page ID or a workspace. Page IDs are global enough for an explicit target, while a workspace selector limits discovery and active-page resolution. A page-less command from a remote or chat agent is rejected when it would otherwise drive the tab the person is viewing.
The CLI lists engine tabs and client-hosted pages as one logical tab list. It reports profile, opener, loading, and empty-worktree scope so a user can tell whether there are no tabs in one worktree or no tabs anywhere. --expect-url is sent only when the runtime advertises support; an older runtime is rejected before it can drop the safety check.
References: src/…/browser-command-target.ts• L22-114 src/…/browser-environment-scope.test.ts• L45-129 src/…/browser-tab.ts• L22-114 src/…/browser-tab-list-empty.test.ts• L34-51 src/…/browser-client-page-queries.ts• L44-131 src/…/browser-tab-queries.ts• L53-170
Remote CLI workspaces
Remote CLI-driven workspaces let an allowed managed host drive pages that the desktop displays for that host's workspace. The desktop treats the host as a scoped page controller, not as a general desktop automation client.
The remote command path accepts a fixed browser method set. It checks host authority, page ownership, route identity, operation generation, cancellation, and runtime capabilities before dispatch. It does not forward arbitrary helper commands or grant desktop file access, broad clipboard access, profile changes, cookie-jar changes, identity changes, or certificate bypass.
Small results use one response. Larger screenshots, PDFs, snapshots, and evaluation values use ordered chunks only when both peers support staged results. Delivery failure is reported separately from command failure because the page action may already have completed.
References: src/…/runtime-browser-client-automation.ts• L38-133 src/…/browser-core.ts• L42-151 src/…/browser-extras.ts• L30-207 src/…/browser-host-command-result-staging.test.ts• L57-70 src/…/browser-client-page-command-execution.ts• L20-115
Proxy routing
Proxy routing keeps page identity, cookies, and network egress together. Local sessions use the application proxy. A routed page uses a dedicated session partition and a fixed route endpoint so its traffic cannot silently switch to the desktop network.
Route identity
A route binds a page to a browser profile, authority identity, execution host, storage scope, and proxy endpoint. The route admits a partition only after its network path and session policy are ready. A durable binding lets a reconnect or re-pair adopt the right cookie jar instead of creating a new one.
Route bindings have bounded capacity and retain live or preparing partitions. Retired storage is cleared through Chromium before its backing directory is removed. Cold orphan cleanup can remove unused folders without opening a session, while live cleanup queues deletion until Chromium releases its locks.
References: src/…/browser-route-session-registry.ts• L44-181 src/…/browser-route-session-registry.ts• L232-324 src/…/browser-route-partition-storage-dependencies.ts• L19-73 src/…/browser-route-partition-binding-capacity.test.ts• L29-67
Local and paired routes
Local SSH and paired runtimes use the same route idea with different network owners. Local preparation checks forwarding before it exposes the partition. Paired runtimes attach a browser network tunnel through the runtime connection and reject data from the wrong runtime or tunnel generation.
Traffic leaves through the execution host's own proxy when that host has one. Direct, HTTP CONNECT, and supported unauthenticated SOCKS routes are handled explicitly. Unsupported proxy forms fail closed instead of falling back to direct traffic. Route policy does not let the application-wide proxy overwrite a route-owned endpoint.
References: src/…/browser-session-route-policies.ts• L14-41 src/…/browser-route-egress-electron-launch.ts• L12-65 src/…/local-ssh-browser-profile-retirement.test.ts• L164-209 src/…/browser-route-partition-storage-dependencies.ts• L23-50
Download and upload handling
File ownership follows the page owner, not only the browser session. Local pages save to a desktop destination. Client-hosted pages stage bytes in a desktop-owned temporary file and send them through a negotiated file channel to a workspace-relative destination on the owning runtime.
Download ownership
The download router first resolves client-hosted and popup ownership. A remote owner receives a relay. An extension download has its own owner. An unresolved client-hosted page or an unavailable file channel is blocked, so remote bytes cannot land in the wrong desktop's Downloads folder.
Downloads report start, progress, and one terminal result. If the page closes before its download is attached to a tab, the download is canceled rather than left without an owner. The renderer keeps the page active until all downloads for that page finish. Document previews use a separate deny policy and never enter this browsing download flow.
References: src/…/browser-manager-state.ts• L57-140 src/…/browser-session-partition-policies.ts• L86-114 src/…/agent-browser-bridge-page-commands.ts• L157-207 src/…/doc-preview-protocol.ts• L138-161
File channels
The remote file channel streams bounded chunks and commits the final path on the owning workspace. The desktop checks cancellation during the transfer and removes its staging area after success or failure. Uploads use the reverse direction: remote file names become safe workspace-relative paths before Chromium reads them.
Agent uploads intercept the page file chooser instead of opening an operating-system dialog. A client-hosted page accepts only files inside the owning workspace, so an absolute path from another machine cannot become a local file read.
References: src/…/browser-client-download-relay.ts• L79-183 src/…/browser-client-upload-staging.ts• L61-163 src/…/runtime-browser-client-automation.ts• L151-186 src/…/guest-file-chooser.ts• L1-90
Popup handling
Popup policy converts a page's window request into an Orca tab, a controlled child window, an external application open, or a denial. The choice depends on the destination, opener ownership, user gesture, request shape, and whether the request carries a form body.
Browser popups
Recognized new-tab requests open in Orca. Other web child windows use bounded options and a desktop-controlled origin bar. Scripted tab opens consume a shared budget across the opener's popup tree. A fresh user gesture can fund an open, but a page cannot replay one gesture to create an unlimited popup chain.
Tab-shaped OAuth links without an opener become Orca tabs. A popup with an opener stays a child window so opener state and the login flow remain intact. POST requests are not replayed as a URL when doing so would lose the request body. Agent-opened links are validated before they become tabs and do not activate the desktop user's current view.
References: src/…/browser-manager-guest-popup-policy.ts• L23-180 src/…/browser-page-initiated-tab-budget.ts• L1-100 src/…/browser-manager-event-forwarding.ts• L68-109 src/…/server-agent-tab-placement.ts• L9-66
Popup origin surfaces
The origin bar keeps the destination in a desktop-controlled surface separate from page content. It updates from the last committed origin and marks insecure or opaque documents as unknown or not secure. If policy preparation fails, the content is discarded before its first request can reach a site.
References: src/…/popup-origin-bar-window.ts• L1-230 src/…/popup-committed-origin.ts• L1-40 src/…/browser-popup-native-window.ts• L1-220
Routed popups
A popup from a routed page stays in the opener's partition and inherits its network path and authority. It needs a live route registration and a user gesture. The route limits descendants, registers ownership before the first navigation, and closes them when the opener retires.
Background routed popups use the same checks as visible popups. If route preparation or authority fails, the native child closes before its first request. Revoking the route fences and closes its existing children.
References: src/…/browser-route-guest-popups.ts• L30-142 src/…/browser-route-guest-popups.ts• L173-250 src/…/browser-popup-background-compatibility.electron.test.ts• L107-185
Change checklist
When these files or sections are changed, remember to consider these:
- Keep profile admission, cookie restore, extension attachment, route binding, guest ownership, and download routing aligned. A page can render while automation, extension APIs, or saving correctly fails closed if these identities differ.
- Keep session startup ordering aligned with staged cookie imports, proxy readiness, extension loading, and policy installation. Opening a partition too early can skip a pending state change or request hook.
- Keep route identity, storage scope, execution host, proxy endpoint, capacity, and cleanup mode aligned. A changed identity must adopt the right jar without deleting retained storage.
- Keep guest registration ahead of popup navigation, prompt creation, download creation, and automation. A child can start work before its first page load event.
- Keep committed URL, in-flight URL, load-stall phase, load errors, certificate state, and user-agent mode aligned. A failed target must not become the page's current identity.
- Keep CDP target replacement, helper-session retirement, page generations, viewport state, and queued command admission aligned. A stale command must not reach a replacement guest.
- Keep raw command validation, page-scoped element references, snapshot baselines, and action effects aligned. Caller values must not override the selected page or make secret text the next diff baseline.
- Keep first-paint holds, focus guards, visibility reports, screencast generations, frame acknowledgements, and held-input release balanced across success, cancellation, timeout, and revocation.
- Keep remote frame geometry and pointer mapping based on the same displayed frame. A letterboxed or stale frame must not receive pane coordinates.
- Keep client-host placement, renderer attachment, page metadata revisions, persistence, recovery, and retirement exact to the same page generation.
- Keep CLI target resolution separate from the safety capability check. A missing or unsupported expected-URL check must stop the command before it reaches an older runtime.
- Keep file-channel negotiation, workspace-relative path checks, staging limits, cancellation, and terminal download state aligned on both sides of the runtime connection.
- Keep popup origin surfaces, external-app prompts, opener ownership, committed origins, popup budgets, and route teardown tied to the requesting frame.
- Keep host lease authority, paired-device identity, route identity, page generation, renderer identity, and negotiated capabilities aligned during attach, reconnect, and reconciliation.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A page requests an unknown session partition | It could read another profile's cookies or storage | Session admission accepts only known profiles and route bindings |
| A partition opens before cookie, proxy, or policy preparation finishes | The first page can use stale identity or direct network access | Startup and route admission wait for preparation within bounded limits |
| A route is reused with a different execution host or proxy endpoint | Page traffic could leave through the wrong network | Route identity and endpoint checks reject the reuse |
| An extension or request hook arrives after first navigation | Early policy, content scripts, or request events can be missing | Profile extension and session request ownership start before page use |
| A hidden guest is freed during capture, automation, or download | The active operation stops or its download is canceled | Activity, capture, prompt, and download retention veto discard |
| A guest is replaced during an automation command | The command could act on a different page | Page, guest, renderer, and generation checks run before dispatch and after waits |
| A helper reuses stale user settings or a named session | Commands could reach an unrelated browser or tab | Helper environment isolation and stale-session cleanup pin one page |
| A remote or chat CLI command omits page and workspace scope | It could drive the tab the person is viewing | Unscoped agent commands are refused before transport |
| An older runtime drops an expected-URL option | A safety check can be skipped and the command can run on the wrong page | The caller checks the runtime capability before sending the option |
| A raw helper command changes its target or includes a global option | It could leave the selected embedded page | Passthrough validation refuses retargeting and global controls |
| A page action opens a secret or replaces its guest during settling | Effects could return text the agent must not read | Withheld text and original-guest checks suppress the page delta |
| A remote frame is letterboxed but input uses pane coordinates | Clicks land at the wrong page point | Input uses the displayed frame rectangle and current viewport |
| A client-hosted download loses its owner or file channel | Remote bytes could land in the desktop Downloads folder | Unresolved remote routes block the download |
| A remote upload names a path outside its workspace | The desktop could read an unrelated local file | Absolute paths are converted to and checked as workspace-relative paths |
| A host is revoked while holding input | A mouse button, key, or touch contact can remain stuck | Admission records held input and releases it during revocation |
| A routed popup outlives its opener or route grant | A child could keep using a retired network authority | Popup ownership is registered before navigation and fenced on retirement |
| A document preview reads a revoked or changed file | It could show unauthorized bytes or a mixed file | Grant checks and per-chunk file version checks stop the read |
| A remote result exceeds one frame or the staged result limit | The page action completes but its result cannot reach the host | Negotiated ordered chunks and explicit size failures bound delivery |
Key files
| File | Why to read it |
|---|---|
| src/…/browser-session-startup.ts | Session startup order for profiles, routes, cookies, proxies, and visibility |
| src/…/browser-session-registry.ts | Profile identity, partition admission, persistence, and cleanup |
| src/…/browser-session-partition-policies.ts | Shared policy boundary for browser sessions |
| src/…/browser-session-cookie-restore.ts | Protected session-cookie restore and save behavior |
| src/…/browser-manager-registration.ts | Logical page ownership and guest replacement rules |
| src/…/browser-manager-guest-policy.ts | Browsing and document-preview policy attachment |
| src/…/browser-manager-guest-cleanup.ts | Authority revocation and page-owned cleanup |
| src/…/browser-page-memory.ts | Guest retention, discard, cold restore, and page generations |
| src/…/browser-page-idle-discard.ts | Visibility-based Memory Saver policy |
| src/…/browser-navigation-stall-watchdog.ts | Load stall states and hidden same-origin context |
| src/…/cdp-ws-proxy.ts | Loopback CDP endpoint and command routing |
| src/…/browser-screencast-stream.ts | Remote frame stream, viewport changes, and cleanup |
| src/…/agent-browser-bridge-core-commands.ts | Page-scoped agent navigation and snapshot actions |
| src/…/agent-browser-bridge-page-commands.ts | Dialogs, downloads, storage, and page utility actions |
| src/…/agent-browser-process-environment.ts | Helper isolation from user browser settings and sockets |
| src/…/browser-commands.ts | Runtime browser command surface and page admission |
| src/…/runtime-browser-client-automation.ts | Client-hosted page command routing and workspace file scope |
| src/…/runtime-browser-page-registry.ts | Remote page identity, selection, metadata, and generations |
| src/…/browser-client-page-opening.ts | Paired desktop page placement and creation |
| src/…/browser-command-target.ts | CLI page, workspace, and expected-URL target rules |
| src/…/browser-format.ts | Agent-facing snapshots, screenshots, tab lists, and action effects |
| src/…/browser-route-session-registry.ts | Route partition admission, capacity, and page authority |
| src/…/browser-session-route-policies.ts | Route policy and cookie preparation before navigation |
| src/…/doc-preview-protocol.ts | Secure preview session, network block, and ranged media responses |
| src/…/browser-manager-event-forwarding.ts | Load, popup, permission, and stall event ownership |