@omercnet/paseo-shared-browser 0.3.1-next.72.1

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## [0.3.1](https://github.com/omercnet/paseo-plugins/compare/shared-browser-v0.3.0...shared-browser-v0.3.1) (2026-09-15)
+
+
+### Bug Fixes
+
+* **shared-browser:** support system Chromium on Linux ARM64 ([#58](https://github.com/omercnet/paseo-plugins/issues/58)) ([f9c3dcb](https://github.com/omercnet/paseo-plugins/commit/f9c3dcb1031840c7cd0aed4a70f984d9d9bd24c1))
+
+## [0.3.0](https://github.com/omercnet/paseo-plugins/compare/shared-browser-v0.2.2...shared-browser-v0.3.0) (2026-09-12)
+
+
+### Features
+
+* **shared-browser:** adopt agent-browser runtime ([#18](https://github.com/omercnet/paseo-plugins/issues/18)) ([09623f3](https://github.com/omercnet/paseo-plugins/commit/09623f34f2b93943c19f809a865813fa37f467bd))
+
+
+### Bug Fixes
+
+* **shared-browser:** skip MCP injection for OMP ([#21](https://github.com/omercnet/paseo-plugins/issues/21)) ([ee2db08](https://github.com/omercnet/paseo-plugins/commit/ee2db08243640600c5592debe72f680446fa26d0))
+
+## [1.0.0](https://github.com/omercnet/paseo-plugins/compare/shared-browser-v0.2.2...shared-browser-v1.0.0) (2026-09-12)
+
+### ⚠ BREAKING CHANGES
+
+* replace the browser runtime in place with plugin-owned `agent-browser` 0.37.1 and a detached daemon-host supervisor; deployments must provide the packaged runtime and a compatible Chromium executable, with Linux ARM64 deployments supplying native Chromium through `PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE`
+
+### Bug Fixes
+
+* leave OMP agent creation unchanged because the provider rejects external MCP servers
+
+### Features
+
+* preserve workspace browser processes across client disconnects and plugin reloads during a 120-second orphan grace, while retaining per-workspace profiles and tearing down active runtimes when workspace archive events are received
+* add daemon-local runtime overrides through `PASEO_SHARED_BROWSER_AGENT_BROWSER_BINARY` and `PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE`
+
+## [0.2.2](https://github.com/omercnet/paseo-plugins/compare/shared-browser-v0.2.1...shared-browser-v0.2.2) (2026-09-10)
+
+
+### Bug Fixes
+
+* upgrade plugins to Paseo 0.8.0 ([c6b4e40](https://github.com/omercnet/paseo-plugins/commit/c6b4e4081fc9527de0ca6183a3903ff5ec4f93c4))
+* upgrade plugins to Paseo 0.8.0 ([d7ad454](https://github.com/omercnet/paseo-plugins/commit/d7ad4540d2e1875bdf4a4d21f76ded25cac2f3dc))
+
+## [0.2.1](https://github.com/omercnet/paseo-shared-browser/compare/v0.2.0...v0.2.1) (2026-09-08)
+
+
+### Bug Fixes
+
+* address Paseo 0.8 migration review feedback ([#10](https://github.com/omercnet/paseo-shared-browser/issues/10)) ([15d2515](https://github.com/omercnet/paseo-shared-browser/commit/15d25157503b7fb70d02c5e420522764250cab62))
+
+## [0.2.0](https://github.com/omercnet/paseo-shared-browser/compare/v0.1.1...v0.2.0) (2026-09-08)
+
+### Features
+
+* migrate shared browser to Paseo 0.8 ([#8](https://github.com/omercnet/paseo-shared-browser/issues/8)) ([36f27ab](https://github.com/omercnet/paseo-shared-browser/commit/36f27abc5dab4a16c9770d6296916631965af333))
+## [0.1.1](https://github.com/omercnet/paseo-shared-browser/compare/v0.1.0...v0.1.1) (2026-09-07)
+
+### Bug Fixes
+
+* include README screenshots in release archives ([#6](https://github.com/omercnet/paseo-shared-browser/issues/6)) ([a231db4](https://github.com/omercnet/paseo-shared-browser/commit/a231db4b20e9c52ebe8624ad69e34e907037ac0a))
+
+## 0.1.0 (2026-09-07)
+
+### Features
+
+* share one live Chromium session per Paseo workspace ([b1e9fac](https://github.com/omercnet/paseo-shared-browser/commit/b1e9fac5021746cf2dc09f7bfb9ccf0cb3b82e5d))
+
+### Bug Fixes
+
+* keep format check off the generated changelog ([#4](https://github.com/omercnet/paseo-shared-browser/issues/4)) ([2219adf](https://github.com/omercnet/paseo-shared-browser/commit/2219adf3c11591a88dc54b899dece76003f313c4))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omer Cohen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# Shared Browser
+
+A Paseo plugin that runs one real Chromium browser per workspace on the daemon host and shares that
+exact live session with every connected Paseo client. Version 1.0 replaces the previous browser
+runtime in place with a plugin-owned, pinned `agent-browser` runtime; existing installations keep
+the `shared-browser` plugin ID and upgrade without installing a second plugin.
+
+This is not URL synchronization and not a second browser with copied cookies. Every viewer and
+eligible workspace agent acts on the same running page, DOM, navigation state, and login state.
+Many viewers can watch; human control remains server-authoritative and takes priority over agent
+input.
+
+## Screenshots
+
+### Wide desktop
+
+![Shared Browser showing the same live Paseo page to two viewers on desktop](docs/images/shared-browser-wide.png)
+
+### Compact client
+
+![Shared Browser controls and the same canonical browser viewport on a compact client](docs/images/shared-browser-compact.png)
+
+## Runtime model
+
+- The plugin server runs beside the Paseo daemon and starts one `agent-browser` session and Chromium
+  process per open browser workspace. Browser execution, profiles, IPC, and network access are on the
+  daemon host, not on the viewing phone, browser, or desktop app.
+- The plugin owns `agent-browser` version `0.37.1`, its IPC directory, and the Chromium executable.
+  It strips inherited `AGENT_BROWSER_*` variables and sets `AGENT_BROWSER_SOCKET_DIR`,
+  `AGENT_BROWSER_IDLE_TIMEOUT_MS=0`, `AGENT_BROWSER_STREAM_PORT=0`, and
+  `AGENT_BROWSER_NO_AUTO_DIALOG=1` itself.
+- Frames stream from Chromium through CDP `Page.startScreencast`, with a bounded screenshot fallback.
+  Remote input supports tap, double-tap, right-click, drag, swipe scrolling, text, and special keys.
+- Device presets for Desktop Chrome, iPhone 15 Pro, Pixel 7, and iPad Pro 11 change Chromium's
+  viewport, device pixel ratio, touch behavior, platform, and user agent. A phone can view and
+  control the shared browser, but the rendered browser remains Chromium. An iPhone preset is mobile
+  emulation, not WebKit, iOS, or real Safari.
+
+## Lifetime and persistence
+
+The browser runtime is held by a detached supervisor rather than by a particular Paseo client or
+plugin subprocess. Closing a panel, disconnecting a client, or losing the plugin bridge invalidates
+that client's viewer/control tokens but does not immediately close Chromium. A replacement plugin
+bridge can reclaim the existing workspace runtime. If no bridge reconnects, the supervisor closes
+all orphaned runtimes after a 120-second grace period. A missed heartbeat fences the old bridge after
+30 seconds; the bridge sends heartbeats every 10 seconds.
+
+Each workspace gets a private profile under
+`$PASEO_HOME/plugin-data/shared-browser/profiles/<workspace-id-sha256>`. Cookies and site login state
+therefore survive viewer disconnects, plugin reloads, and Chromium process restarts while that
+directory remains intact. Profiles are local to one daemon host: they are not synchronized between
+hosts or Paseo clients, do not use a personal Chrome or Safari profile, and are not portable across
+arbitrary Chromium versions.
+
+When Paseo emits `workspace.archived` while the plugin server is active, the plugin fences that
+workspace, expires its viewers and controller, and closes its browser runtime, including a runtime
+whose creation raced the archive. The profile directory is retained. Archive events missed while
+the plugin bridge is disconnected are not replayed or reconciled by the plugin; the orphan grace
+still closes the runtime, but retained profile data must be removed manually if it is no longer
+wanted.
+
+## Install
+
+Enable trusted plugins on the target Paseo daemon, then install from npm:
+
+```bash
+paseo plugin install npm:@omercnet/paseo-shared-browser
+paseo plugin ls
+```
+
+Or install from Git:
+
+```bash
+paseo plugin add omercnet/paseo-plugins:paseo-shared-browser
+paseo plugin ls
+```
+
+Installation runs `npm ci --include=dev` and `npm run prepare:runtime` on the daemon host. The
+preparation step installs the pinned browser runtime and builds both `supervisor.cjs` and
+`shared-browser-mcp.cjs` under
+`$PASEO_HOME/plugin-data/shared-browser/runtime`. For a local monorepo checkout:
+
+```bash
+cd paseo-plugins/paseo-shared-browser
+npm ci --include=dev
+npm run prepare:runtime
+paseo plugin install "$PWD"
+```
+
+The build requires Node.js 24 or newer and npm on the daemon host. The runtime also needs a
+Chromium-compatible executable. On Linux ARM64, where the bundled download is unavailable, the
+installer automatically uses native Chromium from `/usr/bin/chromium`. Install a non-Snap Chromium
+build with the system package manager before adding the plugin. Set
+`PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE` to an absolute path when Chromium is installed elsewhere.
+The plugin does not emulate x64 Chromium.
+
+Open a workspace, search the Command Center for **Open Shared Browser**, or tap the **Shared
+Browser** composer pill while a workspace session is open.
+
+## Agent MCP access
+
+The plugin automatically injects its stdio MCP adapter only when a new, non-internal agent is
+created with a provider that accepts external MCP servers. Agents that already exist, resumed
+sessions, imported sessions, and Paseo's internal agents are not modified. Paseo's OMP provider
+uses native host-tool injection and rejects external MCP servers, so OMP agents are left unchanged.
+Pi agents continue to receive the adapter, but they require Pi's optional MCP support to launch it.
+
+The injected MCP server exposes exactly these tools: `shared_browser_status`,
+`shared_browser_capture`, `shared_browser_acquire_control`, `shared_browser_release_control`,
+`shared_browser_navigate`, `shared_browser_input`, and `shared_browser_viewport`. It does not
+expose arbitrary CDP commands, JavaScript or page evaluation, browser profile access, or filesystem
+access.
+
+Each adapter launch receives an opaque credential bound to its workspace. It cannot use that
+credential to operate another workspace's browser. Agent input follows human-priority control: an
+agent cannot force a takeover while a human viewer holds control. The human must release control or
+the lease must expire before agent input can proceed.
+
+The provider launches the stdio adapter on the Paseo daemon host, beside the daemon-owned browser
+runtime. Web, desktop, and mobile clients never own or host the adapter or Chromium, and a client
+disconnect does not close or reset either process.
+
+## Runtime environment overrides
+
+The plugin recognizes only these deployment overrides:
+
+| Variable                                    | Meaning                                                                                                                                                                                                                                     |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PASEO_HOME`                                | Paseo data root. Defaults to `~/.paseo`; browser runtime, supervisor IPC, and profiles live below `plugin-data/shared-browser`.                                                                                                             |
+| `PASEO_SHARED_BROWSER_AGENT_BROWSER_BINARY` | Absolute path to the pinned `agent-browser` executable. Defaults to `$PASEO_HOME/plugin-data/shared-browser/runtime/node_modules/.bin/agent-browser`.                                                                                       |
+| `PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE`  | Absolute path to Chromium. Defaults to `$PASEO_HOME/plugin-data/shared-browser/runtime/chromium/chrome`. On Linux ARM64, installation automatically links `/usr/bin/chromium`; use this override for another compatible, non-Snap location. |
+
+User-supplied `AGENT_BROWSER_*` variables are deliberately ignored.
+
+## Controls
+
+- Toolbar: back, forward, reload, address bar, and device emulation.
+- Status row: session state, viewer count, controller, and lease expiry.
+- Human control: **Take control**, **Release**, and **Take over** for explicit handoff. Agent MCP
+  calls have no forced-takeover operation.
+- Mobile: swipe scrolls by default; pointer and keyboard options open as bottom sheets.
+
+## Security boundary
+
+- Paseo plugins are trusted, unsandboxed code. The plugin server, detached supervisor,
+  `agent-browser`, and Chromium execute as the daemon OS user and can reach that user's files,
+  processes, credentials, and network.
+- Supervisor IPC uses a user-private Unix socket and token files with owner-only permissions.
+  `agent-browser` IPC metadata and workspace profile directories are also owner-only. The plugin
+  rejects a non-loopback CDP endpoint and disables the `agent-browser` stream port.
+- Viewer and control tokens coordinate clients already paired to the same Paseo daemon. Paseo v0.8
+  plugin RPC callbacks expose no authenticated caller identity, so these human-viewer tokens are a
+  workflow safeguard, not an authorization boundary. The stdio MCP adapter separately uses an
+  opaque, workspace-bound credential.
+- Downloads, uploads, clipboard synchronization, media permissions, extensions, native passkeys,
+  and platform authenticators are not exposed by this plugin.
+- Browser navigation uses the daemon OS user's network access, including local development servers.
+  It is therefore a trusted-agent capability; this plugin deliberately does not apply a blanket
+  loopback or RFC1918 navigation ban.
+
+## Develop
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm run format:check
+npm run test:unit
+npm run prepare:runtime
+paseo plugin install "$PWD"
+paseo plugin reload shared-browser
+```
+
+`npm run test:smoke` launches the configured real Chromium runtime and exercises two viewers,
+control handoff, reconnect, stale-frame rejection, viewport changes, device emulation, profile
+persistence, and archive teardown.
+
+Release Please maintains the version, changelog, component tag, and GitHub release from
+Conventional Commits in the monorepo.
+
+Both the Paseo daemon and app must satisfy `^0.8.0`, including Paseo 0.8 prereleases. The client
+surface uses React Native primitives and works in desktop, web, iOS, and Android Paseo clients.