browser-workspace 0.4.0

package/PRIVACY.md

@@ -0,0 +1,21 @@
+# Browser Workspace Privacy Policy
+
+Browser Workspace is a Chrome extension that manages named tab-group workspaces and reusable tab pools inside the user's browser.
+
+## Data handling
+
+Browser Workspace does not send, sell, share, or transfer user data to the developer or to third parties.
+
+The extension uses Chrome's local extension storage only to keep workspace configuration and local lease metadata needed to restore and manage workspaces. This information stays in the user's browser profile.
+
+The extension may read tab identifiers, URLs, tab-group membership, navigation-target relationships, and related browser state only as needed to create, group, navigate, reuse, release, or reclaim workspace tabs. This information is processed locally and is not transmitted to an external service.
+
+Browser Workspace does not collect personally identifiable information, authentication information, financial information, health information, personal communications, location data, website content, or user activity for external storage or analytics.
+
+## Remote code
+
+Browser Workspace does not execute remote JavaScript or WebAssembly. All extension code is packaged with the extension.
+
+## Contact
+
+Questions about this privacy policy may be submitted through the Browser Workspace GitHub repository.

package/README.md

@@ -0,0 +1,138 @@
+# Browser Workspace
+
+Browser Workspace is a single browser automation skill and CLI built around persistent Python sessions, workspace-owned Chrome tabs, compact snapshot refs, and built-in platform workflows.
+
+## Public interface
+
+The CLI has two public execution paths:
+
+```bash
+# Known platform action: runner owns start/stop.
+browser-workspace platform run PLATFORM ACTION [--config FILE] [--url URL]
+
+# Custom browser workflow: caller owns lifecycle.
+browser-workspace session start [--url URL]
+browser-workspace session exec SESSION_ID <<'PY'
+print(snapshot())
+PY
+browser-workspace session stop SESSION_ID
+```
+
+`--workspace` is hidden from normal CLI help. Normal sessions use `Harness`; product integrations may set an explicit workspace internally when they require isolation.
+
+`session stop` closes all tabs created/owned by that session while leaving unrelated browser tabs untouched.
+
+## Included layers
+
+```text
+browser-workspace
+├── src/browser_harness/     low-level browser/CDP runtime (forked internally)
+├── agent-workspace/         Browser Workspace helper layer
+├── extension/               Chrome workspace/tab manager
+├── session_daemon.py        persistent Python session service
+├── platforms/               site/domain actions + verification metadata
+├── interaction-skills/      browser interaction references
+└── SKILL.md                 single agent-facing skill contract
+```
+
+Agents should load only the Browser Workspace skill. `browser-harness` and `browser-platforms` are no longer separate runtime/skill dependencies.
+
+## Install
+
+```bash
+./scripts/install.sh
+```
+
+The installer creates the skill-owned `.venv` and links `browser-workspace` to `~/.local/bin` by default.
+
+By default Browser Workspace owns exactly one machine-wide persistent, visible Chrome instance. Every session and runtime reuses that same Browser Workspace Chrome; config/runtime overrides never create another Chrome. It uses a Browser Workspace-managed user-data directory, prefers CDP port 9222, and selects the next available candidate only when starting the singleton for the first time. Users do not manage Chrome profiles or remote-debugging settings. Chrome Stable no longer permits silent `--load-extension` for local unpacked extensions, so the extension is treated as an optional workspace-grouping enhancement rather than a prerequisite for browser sessions.
+
+`BU_CDP_URL` / `BU_CDP_WS` remain advanced overrides for callers that intentionally provide their own browser endpoint. `BROWSER_WORKSPACE_CDP_PORT` changes the preferred managed port.
+
+The Web Store build remains available for ordinary interactive Chrome installs, but the managed runtime does not depend on it: `https://chromewebstore.google.com/detail/kgbghhigmbpefppgkocgjgnnnbhjchic`.
+
+## Snapshot model
+
+`snapshot()` uses Chrome's accessibility tree to identify useful controls/content, annotates the corresponding live DOM elements with `data-ref="eN"`, and emits a compact representation. Interact using normal CSS selectors:
+
+```python
+print(snapshot())
+click('[data-ref="e2"]')
+fill_input('[data-ref="e3"]', 'hello')
+```
+
+There is no separate ref registry.
+
+## Upstream
+
+The internal browser-control core is forked from `browser-use/browser-harness`. Its license is retained in `licenses/browser-harness-MIT.txt`.
+
+
+
+## Product-owned workspaces
+
+Normal browser automation uses the default `Harness` workspace. Ordinary agents manage browser sessions only; they do not create, resize, or delete workspaces. Workspace lifecycle belongs to product runtimes such as Agents Relay or NeoY.
+
+Products discover the installed Browser Workspace instance with:
+
+```bash
+browser-workspace status
+```
+
+The command returns machine-readable JSON including the resolved installation `root`, absolute `admin_helper` path, and daemon status. Calling `status` also ensures the existing Browser Workspace session daemon is ready; it does not create a separate service.
+
+A Node.js product can then load the product-only helper without depending on the `browser-workspace` npm package or hardcoding an install path:
+
+```js
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+const status = JSON.parse(
+  execFileSync("browser-workspace", ["status"], { encoding: "utf8" })
+);
+const { ensureWorkspace, deleteWorkspace } =
+  await import(pathToFileURL(status.admin_helper).href);
+
+await ensureWorkspace("Relay", 6);
+// later, if the product owns and no longer needs it:
+await deleteWorkspace("Relay", { force: true });
+```
+
+`ensureWorkspace(name, size)` is idempotent: it creates a missing workspace, keeps one with the same capacity, and reconfigures an existing workspace when the requested size changes. The physical tab pool still grows lazily up to that capacity. `deleteWorkspace(name, { force })` removes the workspace through the existing daemon/extension RPC path.
+
+There is intentionally no `browser-workspace workspace create/delete` CLI. Workspace lifecycle is a product API, not an agent command.
+
+### Start a session in a product-owned workspace
+
+`--workspace` remains an internal integration option for product code:
+
+```bash
+browser-workspace session start --workspace "Relay" --url https://example.com
+```
+
+It is hidden from normal CLI help. Product code owns the workspace choice; platform actions remain unaware of workspace/session policy.
+
+Recommended product lifecycle:
+
+```text
+product startup
+  -> browser-workspace status
+  -> import status.admin_helper
+  -> ensureWorkspace("Relay", 6)
+
+browser task
+  -> browser-workspace session start --workspace "Relay"
+  -> browser-workspace session exec <session_id>
+  -> browser-workspace session stop <session_id>
+```
+
+## Platform boundary
+
+Platform action code is infrastructure-agnostic. It may use browser helpers, but it must not create/stop Browser Workspace sessions, choose workspaces, or import session/workspace infrastructure. The generic platform runner wraps actions in a default Harness session and always cleans up. Product code may execute the same action in a product-owned browser context when longer-lived isolation is required.
+
+Each platform manifest records explicit verification status and evidence. `verified` means live-site verification; migrated code is labeled `migrated_unverified` until exercised in the current integration.
+
+
+## npx skills installation
+
+After `npx skills add ...`, invoke `~/.agents/skills/browser-workspace/bin/browser-workspace` directly. The first session start bootstraps the skill-owned Python virtual environment automatically; running `scripts/install.sh` is optional.

package/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: browser-workspace
+description: Control the real browser through one Browser Workspace skill and CLI, with leased tab workspaces, persistent Python sessions, compact snapshots, and built-in platform workflows.
+---
+
+# Browser Workspace
+
+Browser Workspace is the **only browser skill agents should load**. It includes the browser-control runtime, workspace/tab leasing, persistent Python sessions, snapshot refs, and site-specific platform workflows. Do not load or invoke a separate `browser-harness` or `browser-platforms` skill.
+
+## Agent contract
+
+When installed with `npx skills`, use the CLI from the skill itself; no separate install step is required:
+
+```bash
+BW_CLI="$HOME/.agents/skills/browser-workspace/bin/browser-workspace"
+$BW_CLI status
+```
+
+On first use, Browser Workspace bootstraps its own `.venv` automatically.
+
+Use one of two execution paths:
+
+```text
+known platform flow
+  -> $BW_CLI platform run <platform> <action> [--config FILE]
+  -> runner creates the browser session
+  -> runner executes the platform action
+  -> runner always stops and cleans up
+
+custom browser workflow
+  -> $BW_CLI session start
+  -> $BW_CLI session exec <session_id>
+  -> $BW_CLI session stop <session_id>
+```
+
+Do not manually create a session around a platform action unless product code intentionally owns a longer-lived browser context. There are no separate top-level `open`, `tabs`, `status`, or `screenshot` commands.
+
+Every logical browser workflow must follow:
+
+```text
+start
+  -> exec
+  -> exec
+  -> ...
+finally
+  -> stop
+```
+
+Rules:
+
+- Start one session per logical browser workflow and retain its `session_id`.
+- Reuse that same session for every action/observation turn.
+- Always stop the session in cleanup/finally, including on failure or cancellation.
+- A session owns one leased browser tab and a persistent Python namespace.
+- Multiple independent workflows may use different sessions concurrently.
+
+## Start
+
+Default workspace is `Harness`:
+
+```bash
+$BW_CLI session start
+```
+
+Normal agents do not choose or manage workspaces. `session start` defaults to `Harness`; the `--workspace` implementation option is hidden from normal CLI help. Workspace lifecycle is not exposed through the agent CLI. Product runtimes that need persistent isolation discover the product-only Node admin helper with `browser-workspace status`, then call `ensureWorkspace` / `deleteWorkspace` through that helper.
+
+Start directly at a URL when known:
+
+```bash
+$BW_CLI session start --url https://example.com
+```
+
+The result is JSON containing `session_id`, `workspace`, `target_id`, the starting `url`, and `workspace_supported`.
+
+Browser Workspace self-manages exactly one machine-wide persistent, visible Chrome instance. Every session and runtime must reuse that singleton. Runtime/config overrides must never create another Chrome. Browser Workspace owns the user-data directory and local CDP endpoint, prefers port 9222, and selects another candidate only when starting the singleton for the first time. Agents do not choose a Chrome profile or enable remote debugging. The Chrome workspace extension remains optional: Chrome Stable blocks silent local unpacked-extension loading, so sessions continue in plain-browser mode when the extension is absent; grouping/lease isolation becomes available when the extension is installed.
+
+## Exec
+
+`session exec` reads Python from stdin. Helpers are already imported; do not import another browser package.
+
+```bash
+$BW_CLI session exec <session_id> <<'PY'
+print(page_info())
+print(snapshot())
+PY
+```
+
+Python state persists across later calls in the same session:
+
+```bash
+$BW_CLI session exec <session_id> <<'PY'
+meeting_name = "Demo"
+print(current_tab())
+PY
+```
+
+Then later:
+
+```bash
+$BW_CLI session exec <session_id> <<'PY'
+print(meeting_name)
+PY
+```
+
+A Python file may also be used with `--code-file`.
+
+## Stop
+
+```bash
+$BW_CLI session stop <session_id>
+```
+
+Stopping closes every tab owned or opened by that session—including tabs created with `new_tab()`, `bh.new_tab()`, direct `Target.createTarget`, and detected child/popup tabs—then destroys the session's Python namespace. It does not close unrelated browser tabs. Do not reuse the ID afterward.
+
+A safe shell structure is:
+
+```bash
+SESSION_JSON=$($BW_CLI session start)
+SESSION_ID=$(python3 -c 'import json,sys; print(json.loads(sys.argv[1])["session_id"])' "$SESSION_JSON")
+trap '$BW_CLI session stop "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
+
+$BW_CLI session exec "$SESSION_ID" <<'PY'
+print(snapshot())
+PY
+```
+
+## Browser helpers
+
+The session exposes the browser primitives directly, including:
+
+```python
+page_info()
+goto_url(url)
+current_tab()
+new_tab(url)
+close_tab(...)
+js(expression, target_id=None)
+cdp(method, ...)
+wait_for_load()
+wait_for_element(...)
+fill_input(selector, text)
+click(selector)
+capture_screenshot(...)
+```
+
+Use the higher-level helpers first. Use raw `js(...)`/`cdp(...)` only when needed.
+
+Interaction-specific reference material is bundled under `interaction-skills/` inside this skill.
+
+## Snapshot refs
+
+`snapshot()` returns a compact accessibility-oriented view and writes each returned ref directly onto the corresponding live DOM element as `data-ref="eN"`.
+
+Example:
+
+```text
+- button "Calendar" [ref=e1]
+- button "Meet now" [ref=e2]
+- textbox "Meeting name" [ref=e3]
+```
+
+The live DOM then contains equivalent annotations such as:
+
+```html
+<button data-ref="e2">Meet now</button>
+```
+
+Refs are ordinary CSS selectors. Use normal helpers:
+
+```python
+print(snapshot())
+click('[data-ref="e2"]')
+fill_input('[data-ref="e3"]', 'Demo meeting')
+```
+
+Do **not** invent `click("e2")`, `click_ref("e2")`, or an `@e2` API. After navigation or a substantial DOM update, call `snapshot()` again and use the new refs.
+
+`snapshot(interactive_only=False)` may include named content roles in addition to interactive elements. `target_id=` may be used for target-specific inspection.
+
+## Workspaces
+
+Default configuration:
+
+```text
+BH_WORKSPACE_NAME=Harness
+BH_WORKSPACE_POOL_SIZE=5
+```
+
+When the Browser Workspace Chrome extension is installed, the pool size is the maximum concurrent capacity; tabs are created lazily. The extension owns grouping, lease/release, idle reclaim, and workspace isolation.
+
+Without the extension, browser sessions still work using the built-in browser core. Workspace names, grouping, pool capacity, lease isolation, and idle reclaim are unavailable; tab/navigation/input/snapshot/platform helpers continue to work. `workspace_status()` reports `supported: false` instead of failing.
+
+Available workspace helpers include:
+
+```python
+workspace_create("Research", 5)
+workspace_status()
+workspace_list()
+workspace_resize("Research", 6)
+workspace_delete("Research")
+```
+
+Never use URL as tab identity. Workspace ownership and leased target identity are authoritative.
+
+## Platform contract
+
+Known-site knowledge is bundled under `platforms/`. A platform contains **site/domain behavior only**.
+
+```text
+platforms/<name>/
+├── README.md       site behavior and rules
+├── manifest.yaml   actions + verification metadata
+├── actions/        reusable browser action code
+└── flows/          optional flow documentation
+```
+
+Platform rules:
+
+- Platform actions may use browser helpers such as `new_tab()`, `current_tab()`, `snapshot()`, `js()`, `cdp()`, uploads, downloads, and screenshots.
+- Platform actions must **not** create/stop Browser Workspace sessions, choose a workspace, call workspace-management APIs, invoke the Browser Workspace CLI, or import session/workspace infrastructure.
+- Platform `README.md` and flow docs should describe site behavior, preconditions, side effects, and verification evidence—not Browser Workspace lifecycle mechanics.
+- Platform actions must remain usable in either a generic runner-owned session or a product-owned browser context.
+- The generic runner owns the normal lifecycle: start a default Harness session, inject browser helpers/config, execute the action, then always stop the session and close its owned tabs.
+- Products that require a dedicated or persistent browser context (for example Family Tutor or Agents Relay) may execute the same platform action inside product-owned infrastructure. The platform code itself stays unchanged.
+- Do not rediscover a known site's mechanics when a verified platform flow/action already exists.
+
+Run a platform action through the generic runner:
+
+```bash
+$BW_CLI platform run microsoft-teams meeting --config /path/to/config.json
+```
+
+The runner output hides the raw session ID. It returns the platform/action result, optional workspace-extension warning, and cleanup evidence.
+
+### Platform verification contract
+
+Every `platforms/<name>/manifest.yaml` must declare:
+
+Platform-owned publishing facts belong in the same manifest, not in caller-specific tables. When applicable, declare `media`, `fields`, `capabilities`, `content_mapping`, and platform notes there. Callers inspect them with `browser-workspace platform profile <name>` and must not maintain a second authoritative limits/capabilities registry.
+
+```text
+platform:
+status:
+last_verified:
+actions:
+verification:
+  status:
+  last_verified:
+  evidence:
+```
+
+Verification rules:
+
+- `verified`: exercised against the live site and supported by concrete evidence.
+- `partially_verified`: some declared flows are live-verified while others remain implemented but unverified.
+- `migrated_unverified`: code was migrated from a previously working adapter but has not yet been live-verified in the current Browser Workspace integration.
+- Never upgrade a status merely because code compiles or contract tests pass.
+- Flow-level verification in `manifest.yaml` should be more specific than the platform-wide status.
+- When live behavior changes, update `last_verified`, evidence, and affected flow status in the same change.
+
+Current bundled platforms:
+
+```text
+platforms/chatgpt/
+platforms/chrome-web-store/
+platforms/microsoft-teams/
+platforms/tiktok/
+platforms/wechat-channels/
+platforms/xhs/
+platforms/youtube/
+```
+
+Read the matching platform `README.md` and `manifest.yaml` before invoking or modifying a known flow. The platform README is documentation owned by this root Browser Workspace skill; it is not a separately loadable skill.
+
+## Installation
+
+Run the bundled installer from the skill directory:
+
+```bash
+./scripts/install.sh
+```
+
+It creates a Browser Workspace-owned `.venv`, installs the vendored browser runtime and dependencies, writes Browser Workspace environment configuration to `agent-workspace/.env`, and links `browser-workspace` into `~/.local/bin` by default.
+
+There is no required separate Browser Harness installation.
+
+The Chrome extension is recommended but not required. Without it Browser Workspace runs in plain-browser mode and `session start` provides the installation link. The public Web Store URL is:
+
+```text
+https://chromewebstore.google.com/detail/kgbghhigmbpefppgkocgjgnnnbhjchic
+```
+
+The extension is also bundled at `extension/` for unpacked/development installs. Default extension ID:
+
+```text
+kgbghhigmbpefppgkocgjgnnnbhjchic
+```
+
+## Internal provenance
+
+The low-level browser runtime is forked from `browser-use/browser-harness` and kept internally under `src/browser_harness/`. Browser Workspace is the public product/skill/CLI surface. Upstream licensing is preserved under `licenses/`.