feat: Environment browser on the web, with an agent-browser session per thread

[immakermatty]

Status: in progress — awaiting DEV-6646 integration review

Why

Root decision 0191 (plan DEV-6646): on a Lazurio Remote Environment the agents of every thread work in the Environment browser, one shared headed Chromium on the Environment. Each thread drives a window of its own through the agent-browser CLI, and a person watches and takes over through a view (the agent-browser dashboard) behind the Environment's gateway.

T3 Code's web client has no browser: the right panel's Browser is disabled ("Only available in the desktop app") wherever Electron's desktopBridge.preview is missing. Nothing told an agent which agent-browser session belongs to its thread either.

What

Two overlays, each with a small seam in upstream code.

A. Server: an agent-browser session per thread. Lives in apps/server/src/lazurio/agentBrowserSession.ts, plus one call in ProviderService.ts.

• Every provider process T3 starts for a thread gets AGENT_BROWSER_SESSION=<name>.
  • Ordinary threads. An id that already fits agent-browser's grammar ([A-Za-z0-9_-]) within its dashboard's 64 characters gets exactly t3-<thread id>. Every ordinary thread id is a UUID, so this is the normal case.
  • Any other id. Characters outside the grammar become - and the name is cut. It then ends in 32 hex digits (128 bits) of the SHA-256 of the exact id, so two threads never share a session (a 32-bit FNV-1a suffix in an earlier head could be made to collide; see the review). Long imported ids (import:<instance>:<session>, where an instance id may take 64 characters) are the case this covers.
• ProviderService.prepareMcpSession records the name with the thread's provider session (withAgentBrowserSession). Every adapter already spreads that session's environment into the processes it starts for the thread (withAgentDeviceEnvironment, the path the agent-device CLI takes). So Codex's per-thread app-server, Claude Code, Cursor, Grok, OpenCode and Antigravity all get it without adapter changes.
• The thread's own name wins over one inherited from T3's environment. It only names a session and grants nothing.

B. Web: the right panel's Browser shows the Environment browser. Lives in apps/web/src/lazurio/, with seams in rightPanelStore.ts, RightPanelTabs.tsx and ChatView.tsx.

• When it asks. Only without the desktop preview, and only for threads of the environment that serves the page. When the right panel opens, it asks this origin for GET /.lazurio/browser.json?session=<name> with credentials: "same-origin", redirect: "error", cache: "no-store" and a 10 s timeout.
• What enables Browser. Only a 200 {"available": true, "view": "<https URL>", "session": "<name>" | null}.
• What keeps it disabled. Everything else keeps today's disabled state and text: available: false, any other status (a 404 from an older Platform, 400, 202, and so on), a network error, an answer that is not JSON (including T3's own index.html fallback), a view that is not https: or sits on this page's origin, or a different session.
• The surface. Opening Browser adds a new surface kind, environment-browser. It cannot be preview, because reconcileBrowserSurfaces drops preview surfaces that have no live server tab.
• The view URL is never stored. It carries a short-lived token in its fragment, so the surface asks for it again on every open and on Reload. The URL lives only in component state; the persisted surface is just {id, kind}.
• The frame. An <iframe allow="clipboard-read; clipboard-write; fullscreen" sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-downloads allow-modals"> fills the panel.
  • A slim header holds "Environment browser", Reload, and "Open in new tab" (target=_blank rel=noopener, same URL). The new tab is there because the gateway's sign-in page cannot render inside a frame.
  • With allow-same-origin the frame keeps its own origin, so a view on T3's own origin is refused.
• No profile chooser on the web. The desktop browser-profile chooser only shows where the desktop preview exists; the web has no profiles to pick.
• Two copies of the name function. The session name lives in apps/server/src/lazurio/agentBrowserSession.ts and apps/web/src/lazurio/agentBrowserSession.ts. Sharing it through packages/shared would need an entry in that package's export map, and upstream has changed that package.json in 31 commits since August. The release contract test asserts the two copies are the same function.

Fork policy.

• Every touched upstream client file is in allowed_upstream_changes with a reason. ChatView.tsx was already listed.
• CI now also runs vp test run src/lazurio in apps/server.
• The runbook gets two "retain" rows and a section called "Prohlížeč Environmentu".

Review. Greptile raised four findings. Two were real and are fixed in follow-up commits:

• Cut or rewritten ids could share a session: fixed in 1bb1015.
• Only a 200 answer should enable Browser: fixed in ab3a24b.

The other two are answered in their threads and left as designed:

• Browser keeps the cached answer while the check runs on reopen.
• Reopening during the panel's exit animation keeps the live frame.

What does not change

• Desktop app with desktopBridge.preview: no request is made, Browser is the desktop preview, and profiles work as before.
• Unchanged areas: the mobile app, wire contracts and packages/.
• No Environment browser: where the Environment offers none, or on any non-Lazurio deployment, Browser stays disabled with the upstream text.
• Desktop-only paths: the preview.toggle keybinding and "open in preview" links still open URLs in a desktop preview tab only.
• Other environments: threads on non-primary environments keep upstream behaviour.

Verified

• Lazurio Fork CI on ab3a24b, all green (run 37375471330):
  • Server and web compatibility: allowlist guard, vp fmt --check, typecheck of server and web, the hosted-server tests, the new Test the Lazurio server overlay, Test the Lazurio web overlay, the release contract test and the release image build.
  • CLI archives / Build darwin-arm64, CLI archives / Build linux-x64 and CLI archives / Launcher install linux-x64.
  • The run on the first head (fb2c560) lost its Linux jobs to the GitHub Actions incident of 2026-10-05. Its darwin archive job passed.
• Run locally on Node 24.16.0 with pnpm 11.10.0:
  • pnpm exec vp fmt --check: clean.
  • pnpm exec vp run --filter t3 typecheck and pnpm exec vp run --filter @t3tools/web typecheck: pass.
  • pnpm exec vp lint --report-unused-disable-directives on every changed file: exit 0 and no new warnings. ChatView.tsx (69) and RightPanelTabs.tsx (1) have the same warnings as the upstream baseline.
  • cd apps/server && pnpm exec vp test run src/lazurio: 6/6. This covers the name rule (exact for clean ids; distinct, readable and in the grammar for rewritten, long and imported ids), the merge into the provider-session environment, ProviderService recording the name before the adapter starts, and the environment the Codex app-server and Claude Code start with.
    • Mutation check: without the seam in ProviderService.ts, the ProviderService test fails.
  • cd apps/web && pnpm exec vp test run src/lazurio: 19/19 (this includes the prompt-draft tests). This covers the name, every browser.json case (available, unscoped, not offered, 404, 400, 202, network or redirect, HTML, not JSON, http, relative, javascript:, this page's origin, missing or mistyped fields, another session, other response origin, array, timeout) and the surface store (singleton, survives preview reconciliation, toggle, close, persisted as {id, kind}).
  • node --test scripts/lazurio-release-contract.test.mjs: 17/17.
  • Upstream suites of the touched modules:
    • web src/rightPanelStore.test.ts src/components/RightPanelTabs.test.tsx src/components/ChatView.logic.test.ts: 228/228.
    • server src/provider/Layers/ProviderService.test.ts src/mcp/McpProviderSession.test.ts: 94/94.
    • src/server.test.ts: 212/212.
    • adapter suites (Claude, Codex, Cursor, Grok, OpenCode, Antigravity): 415/416. The one failure, AntigravityAdapter > serves client file reads and writes only inside the session roots, fails the same way on the unchanged base. It is a macOS /var vs /private/var temp-path issue that does not affect Linux CI.
  • pnpm exec vp run --filter @t3tools/web build and pnpm exec vp run --filter t3 build: both pass. The bundles carry AGENT_BROWSER_SESSION and /.lazurio/browser.json.
• Not run: a browser pass. No live Environment browser was available, so it belongs to the integration review.

Risks

• Framing. The view's origin must allow being framed by the T3 origin (frame-ancestors / X-Frame-Options on the gateway's browser. origin). The Platform and gateway own this; it is to be confirmed in the integration review.
• The sandbox. allow-scripts together with allow-same-origin only confines the frame because the view is on another origin, so a same-origin view is refused. The lint rule is suppressed on that line with the reason.
• Delay before Browser enables. Browser stays disabled until the Environment answers, which is up to 10 s if the view has to start cold. On reopen, the last answer for the thread shows while it is checked again.
• Dependence on the MCP credential. The variable rides the thread's provider session, which is recorded whenever the MCP credential is issued. That happens for every session a server starts, because the MCP session registry is part of every server layer. A server without the registry (tests only) starts providers without the variable.
• Computing the name elsewhere. Anything outside T3 that derives a session name from a T3 thread id must use the same rule: plain t3-<id> for clean UUIDs, otherwise the cut name plus 32 hex digits of the id's SHA-256. Today nothing outside T3 derives it; the Platform reads AGENT_BROWSER_SESSION as given.

Related

• Root decision 0191: Decision 0191: the Environment browser and desktop in the right panel HumanAndMachines/Lazurio#497
• Part of Web right panel: Browser embeds the Environment browser view (Desktop later) #40 (the web Browser; the Desktop entry is a later wave)
• Collaborative browser: není dostupný preview automation host, nelze použít přihlášený tab #28 (on a Remote Environment, this is the browser agents can use)

🤖 Generated with Claude Code

[agentrozjedemeai]

P1 — Imported threads can still share one browser session (apps/server/src/lazurio/agentBrowserSession.ts:28-33, mirrored in web). The 8-hex-digit FNV-1a suffix is not unique. I ran the exact function on this head: for prefix = "import:codex-" + "w".repeat(58) + ":", agentBrowserSessionName(prefix + "f64cccd6-59c8-42a7-aa0e-319969aeccc9") equals agentBrowserSessionName(prefix + "3c4a8834-35dc-418d-a6dd-d8d1934ab83f"); both yield t3-import-codex-wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww-dc7d7bc4. These are distinct, valid imported thread IDs of the shape generated by AgentSessionImporter.ts:168-170. Their providers therefore receive the same AGENT_BROWSER_SESSION and can drive the same window, violating the per-thread isolation this change promises. Please address the collision (e.g. a sufficiently long collision-resistant digest plus this regression pair, or collision-checked persistent allocation if strict uniqueness is required) and synchronize the server/web implementations. The 17/17 release-contract tests pass locally, but do not cover this case. No merge/release action taken.

[immakermatty]

@agentrozjedemeai Fixed in 1a43117: the suffix of a cut or rewritten id is now the first 32 hex digits (128 bits) of the exact id's SHA-256 (node:crypto on the server, @noble/hashes in the web, one function text compared by the release contract test). Your colliding pair is a regression case on both sides and in the contract test. Locally on Node 24.16: format check, server and web typecheck, server overlay 6/6, web overlay 19/19, contract 17/17.

[agentrozjedemeai]

@immakermatty Approved at exact head 1a43117. The prior P1 collision pair now maps to distinct 64-character, grammar-valid session names with the 128-bit SHA-256 suffix on both server and web; ordinary UUIDs retain t3-. I inspected the one-commit repair and the server/web parity and release contract, and ran the isolated server overlay tests (6/6), web overlay tests (19/19), release contract (17/17), format check, and server/web typechecks (all passed; local Node 26 versus required Node 24). Fork CI has four successful jobs on this head; review threads are resolved. No browser integration smoke was available. This approval is review-only, not merge or release authorization.