feat(browser): integrate Chrome companion runtime and production setup

[TerminallyLazy]

Summary

Adds the Chrome extension bridge through the bundled _browser and _a0_connector plugins: protected pairing and default selection, signed restricted transport, exact runtime admission, site/action policy, chat and artifact relay, and owned-tab finalization. The native companion runs on the Chrome host, never inside Agent Zero's Docker container.

Coordinated changes: extension setup PR #11, native companion and CLI PR #26.

Production-only scope and cleanup

• Removed 43 development-only files, including 16 DOX sidecars, development API/WebSocket handlers, limited runtime, WebUI stores and their dedicated tests/fixtures. Removed two obsolete foundation guides. No generated binaries or caches are included.
• Production transport only. Old development credentials/grants are neither promoted nor deleted; stale selectors reject without CLI/CDP/internal-browser fallback. Production users explicitly pair/select the production identity.
• Consolidated duplicate setup, approval, artifact and lifecycle tests into their owning suites; new test modules fell from 52 to 44 while retaining the 73 affected behavioral test functions. Shared synthetic fixtures replace duplicated setup. Subsequent review removed five tests for two unused discovery-only models; actual runtime/security tests remain. The latest regressions extend existing suites and shared fixtures, not new test modules.
• Full PR: 43,684 additions / 84 deletions across 196 files, down from 52,828 additions (9,144 fewer). Production Python/JS/HTML/CSS source: 25,800 additions / 84 deletions / 25,716 net across 93 files. Source figures exclude tests, DOX, prompts and configuration; comments and blank lines are included.
• One feature commit against ready: 9d23a49d75fd524316020e681b9436be59b2aa73. Scoped backup refs retain earlier versions; no upstream history was rewritten. No Actions run requested.

Why shared Core changes remain

Feature implementations remain plugin-owned. Shared changes total 439 added / 48 removed / 391 net lines across seven source files, excluding tests and DOX.

Shared file	Added / removed	Necessity
helpers/ws.py	153 / 12	Authenticates restricted companion principals after Origin validation and before handler activation, preventing ambient-cookie/API-key rescue and cross-handler dispatch. A plugin handler cannot secure the shared pre-dispatch path from inside itself.
helpers/ws_manager.py	208 / 31	Excludes restricted sockets from ordinary broadcasts, replay buffers and diagnostics; revalidates exact connection generation and credentials before queued delivery. Plugin checks cannot intercept shared fan-out after returning.
helpers/ws_principal.py	45 / 0	Shared immutable scope/handler/event identity and safe correlation IDs for both framework transport and plugin authorization.
helpers/tool.py	7 / 2	Default-compatible get_display_args() hook allows typed-input redaction before base-tool terminal logging. The existing browser log-object override protects a different output path.
helpers/persist_chat.py	3 / 1	Two extensibility decorators plus import let plugin hooks quarantine exact legacy state before serialization/deserialization, without embedding migration logic in Core.
helpers/ui_server.py	13 / 2	Existing @extensible construction hook plus a fresh local AsyncExitStack and webui_server_start dispatch inside each ASGI lifespan. Uvicorn retries reinstall services after prior cleanup; hook failure and shutdown await exact-owner retirement. No browser-specific imports remain in the shared server.
extensions/python/_functions/helpers/ui_server/UiServerRuntime/create/end/_05_legacy_browser_guard.py	10 / 0	Mandatory Core hook delegates the existing legacy HTTP retirement guard, even if the connector is disabled. It must not be an optional plugin hook that could revive retired routes. No retirement or runtime activation is initiated.

No changes to agent.py, initialize.py or models.py. Matching helper DOX and owning contracts document the boundaries. Exact legacy fixture bytes remain because retirement tests verify their digests; they are inert fixtures, not an active development runtime.

frdel review and simplification

Aligned in the reviewed boundaries, inferred from actual local diffs rather than a claim of maintainer approval: 89d4b891 consolidates helpers while preserving compatibility; 7eb6d5b1 preserves activated WebSocket handler identity; b94d4b79 owns server construction/lifespan; b6be345a moves feature behavior into plugin hooks; 93d1131c standardizes browser UI components.

• Removed singleton transport-registry searches, one-lifecycle fan-out, two unused discovery-only lease/finalization models and their private validators. Exact ownership and actual runtime binding tests remain. Static discovery keeps its IDs/keys but no longer claims live lease validation.
• Malformed non-string action/choice values in four protected APIs return no-store HTTP 400 before state access. Successful action notices expire after three seconds; uncertain decisions retain the no-retry warning.
• Resolved the lifetime 2,048-message/queue-receipt ceiling using one plugin-owned journal backed by existing atomic KVP storage. New hash-only receipts are individually indexed; original receipts remain a read-only fallback. Accepted replays, payload conflicts, uncertain reservations and the separate 32-live-item queue bound are preserved. Queue projection logic is shared and read failure after an effect reports unknown.
• Before the first indexed write, atomically mark the original journal schema v2 without changing its records. Older builds reject it, preventing downgrade from overlooking newer receipts and repeating work. Do not erase the marker or receipts to force rollback. Migration occurs on authorized writes, not startup. Disk usage grows with distinct IDs; this is not bounded disk retention or new cross-process transaction support.
• Browser installation and awaited cleanup now share each ASGI lifespan through the enabled connector's webui_server_start hook. Removed the stored server-lifetime shutdown stack: startup retries on the same server object install afresh after retirement. A later startup-hook failure also awaits cleanup. Plugin disablement does not suppress registered cleanup; exact manager checks and the mandatory legacy HTTP guard remain.
• Removed the alternate whole-document writer used only for injected journals. Tests now inject KVP-shaped reads/writes and execute the exact production indexed-storage and migration path. All tracked callbacks were updated; disk formats and browser wire contracts are unchanged.
• Replaced stale unwired/development-stage DOX with current unbound-versus-composed ownership. Construction, pairing and policy never substitute for production admission/reconciliation.

Across the initial review and approved follow-ups: 45 fewer total lines and 220 fewer production-source lines. The lifetime-capacity fix deliberately retains replay receipts instead of deleting safety state to reduce size. Latest backup: backup/core-before-frdel-second-review-20260906.

Verification

• 26 focused backend assertion scenarios passed in an isolated framework source overlay: transport identity, 20 malformed raw-HTTP enum values, strict bodies, lifecycle ownership/turn cleanup, durable message replay/uncertainty, full original-journal migration, corruption/failing writes, queue limits, startup retry/failed-hook cleanup, disabled-plugin/exact-manager retirement, three application-composition cases and four context-controller cases.
• Changed Python syntax and scoped whitespace checks passed. Earlier review passed three Node UI and four MV3 discovery scenarios; unchanged UI/discovery code was not rerun for this backend follow-up.
• Pytest is unavailable in the framework environment. These were explicit assertion harnesses invoking test functions, not a full pytest run. No dependencies installed, live browser actions, credential changes or deployment performed. Whole-PR whitespace checking retains pre-existing EOF-blank warnings in digest-pinned legacy fixtures; those bytes were not rewritten.

Release and deployment limits

• Public extension repository; documentation PR #12 is merged. Guided unpacked 0.1.1 ZIP and separate dashboard ZIP are public. Pair once and choose the default across chats; update in the same folder/profile without resetting pairing.
• Production extension ID remains nhliclifilepdkoolioacpjpijomfplj. Published macOS 13+ Intel/Apple Silicon companion is signed/notarized 2.12.3. Core separately requires publisher-signed exact-version policy for 0.1.1 + 2.12.3; that operator policy is not committed here. This follow-up changes no wire protocol, native binary or extension package.
• Native/CLI PR IDEAS: OpenWebUI Pipeline Integration and Workflow Optimization #26 stays at b0dd656a7888e27dd67ca2d091b6cb7955073daa. Linux production packaging/catalog/provenance and desktop acceptance remain incomplete. Windows candidate verification/HKCU installation, genuine signing and native platform acceptance remain incomplete. Extension portability is not end-to-end OS support.
• Web Store publication, source licensing/icon provenance, live deployment and maintainer merge remain separate. This account has READ permission on upstream Core/CLI repositories; no maintainer approval, upstream merge, all-OS production completion or exhaustive security certification is claimed.

[TerminallyLazy]

Added 8b7579d: production WebSocket decoder now strips only manager-owned correlation metadata; strict payload and auth checks remain. Browser setup now supports one protected global Chrome default without requiring an open chat, preserves project/profile overrides, and refreshes readiness automatically. Consolidated three empty approval error rows into one recovery control; known pending approvals remain visible but disabled on failed refreshes. Focused checks: 3 transport, 6 default-selection, 11 WebUI tests passed, plus narrow/wide synthetic previews. Scoped source deployed to the local Docker instance; default selection saved through protected UI, companion status/doctor INSTALL_VERIFIED. Live control is still waiting for Chrome and is NOT claimed accepted. No store submission or cross-platform release claim.

[TerminallyLazy]

Live acceptance update: the existing production pairing has now reconnected after the deployed transport/default-selection fix. In actual host Chrome, opening Browser plugin settings with no chat active reports: Chrome is connected. This browser is the default for your chats. This is the strict default-selection runtime-readiness projection, not inferred from pairing or installation. No new pairing code, manual extension reconnection, or site grant was used. Browser operation acceptance and broader platform releases remain separate.

[TerminallyLazy]

Connection follow-up: 1d25de0 composes production reconciliation and keeps transport admission provisional until exact snapshot settlement; first repeated authenticated hello starts reconciliation after native consumed its initial ACK. This also prevents initial finalization controls racing the ACK. Browser readiness now reflects reconciliation, not just transport registration. Removed the composer recovery button entirely; automatic polling remains and outages use one quiet notification-center entry. Focused regression: 8 tests passed (production reconciliation and composer inbox); earlier targeted runtime/default-selection checks also passed. Scoped files are deployed to the local Docker instance with backups and pairing/site permissions unchanged. Live fixed-symbol diagnostics confirm initial hello, renewal and a settled negative reconciliation reply: UNSUPPORTED_CAPABILITY. Extension startup separately has an impossible wrong-direction artifact-method readiness requirement; that fix is in progress in the extension PR. End-to-end READY is not yet verified. No merge, store publication or Actions dispatch.

[TerminallyLazy]

Current source-integration status: the production extension is now user-confirmed loading conversation content, and Core independently recorded RECONCILIATION_SUCCEEDED after the paired/selected native handshake and renewal. The user has explicitly requested commit, push and merge of the coordinated changes. Browser-operation acceptance, Chrome Web Store publication, Linux release availability and Windows implementation/distribution remain separate incomplete release gates; source integration must not be represented as full cross-platform production completion. Latest Core head is 1d25de0. Matching extension PR #1 includes ongoing chat continuity, inert Markdown and explicit title/link-only tab references; those do not grant tab control. This account has pull access but no push/maintain/admin permission to agent0ai/agent-zero, so a maintainer may be required to merge into ready.

[TerminallyLazy]

Merge attempt outcome: PR marked ready for review; exact-head merge of 1d25de0 was refused by GitHub because TerminallyLazy lacks MergePullRequest permission. No admin bypass or force operation was attempted. A repository maintainer needs to merge this PR into ready. Companion CLI PR #26 has the same permission boundary.

[TerminallyLazy]

Follow-up c9fac7e fixes the real first-open ORIGIN_BLOCKED gap: a bounded production-only server-owned WebUI consent request now precedes Chrome open dispatch. Allow once binds subsequent access to the exact successful resulting lease; allow turn stays exact route/context/session/turn/origin scoped. No native challenge/receipt fabrication or saved policy changes. Deny/expiry guidance explicitly forbids alternate-tool workarounds. 19 focused authority/runtime/UI tests plus 5 tool/prompt regressions passed in an offline disposable framework container. Deployed nine exact source files to the named local Docker instance with recoverable backups; source compilation and HTTP 200 verified. Live consent-to-Chrome effects remain unverified. Extension blue-group and transient-activity changes are separately merged as agent-zero-browser-extension PRs #2/#3. Base remains ready; maintainer merge is still required. No GitHub Actions requested.