unique-sdk 2026.28.0.dev15__tar.gz → 2026.28.0.dev16__tar.gz

{unique_sdk-2026.28.0.dev15 → unique_sdk-2026.28.0.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.28.0.dev15
+Version: 2026.28.0.dev16
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.28.0.dev15 → unique_sdk-2026.28.0.dev16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.28.0.dev15"
+version = "2026.28.0.dev16"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.28.0.dev15 → unique_sdk-2026.28.0.dev16}/unique_sdk/cli/cli.py

@@ -2,12 +2,22 @@
 
 from __future__ import annotations
 
+import json
 from collections.abc import Callable
 from typing import Any
 
 import click
 
 from unique_sdk.cli import __version__
+from unique_sdk.cli.commands.browser import (
+    cmd_browser_action,
+    cmd_browser_control,
+    cmd_browser_download,
+    cmd_browser_status,
+)
+from unique_sdk.cli.commands.browser import (
+    is_error_output as _is_browser_error_output,
+)
 from unique_sdk.cli.commands.cite_file import cmd_cite_file
 from unique_sdk.cli.commands.cite_file import (
     is_error_output as _is_cite_error_output,
@@ -129,6 +139,7 @@ Examples:
   unique-cli web-search search "x"  Search the web via the public API
   unique-cli web-search crawl URL   Crawl a URL via the public API
   unique-cli dynamic-frontend list  List manageable Dynamic Frontend spaces
+  unique-cli browser get-dom        Read the user's live Chrome tab (a11y tree)
 """
 
 
@@ -1550,6 +1561,398 @@ def elicit_respond(
     )
 
 
+# -- Browser Steering ------------------------------------------------------
+
+
+_BROWSER_HELP = """\
+Steer the user's live, signed-in Chrome tab via the Unique browser extension.
+
+\b
+Commands talk to the browser-bridge relay, which forwards each action to the
+extension over the user's outbound WebSocket. You never see the page directly —
+work from the DOM snapshot `get-dom` returns.
+
+\b
+Core loop:
+  1. read   unique-cli browser get-dom          (pruned a11y tree + `ref`s)
+  2. act    unique-cli browser click --ref e42   (use a ref from the latest DOM)
+  3. re-read after anything that changes the page; refs are per-snapshot only.
+
+\b
+Every subcommand prints a JSON envelope: {"ok": true, "result": ...} or
+{"ok": false, "error": "<code>", ...}. On `browser_not_connected`, relay the
+remediation to the user and stop until the extension is installed and signed in.
+
+\b
+Examples:
+  unique-cli browser status
+  unique-cli browser get-dom
+  unique-cli browser navigate --url https://example.com
+  unique-cli browser click --ref e42
+  unique-cli browser fill --ref e10 --text "hello@unique.ch"
+  unique-cli browser download "https://portal/report.pdf" ./output/report.pdf
+"""
+
+
+def _browser_target_args(ref: str | None, selector: str | None) -> dict[str, Any]:
+    """Build the {ref|selector} arg map, preferring an explicit ref.
+
+    Empty strings are treated as absent so ``--ref ""`` / ``--selector ""``
+    cannot bypass the missing-target guard and reach the bridge.
+    """
+    args: dict[str, Any] = {}
+    if ref:
+        args["ref"] = ref
+    if selector:
+        args["selector"] = selector
+    return args
+
+
+def _browser_missing_target(verb: str) -> str:
+    """JSON error envelope for a verb invoked without --ref or --selector."""
+    return json.dumps(
+        {
+            "ok": False,
+            "error": "browser_missing_target",
+            "message": f"{verb} requires --ref (from the latest get-dom) or --selector.",
+        },
+        indent=2,
+    )
+
+
+def _browser_missing_condition(verb: str, required: str) -> str:
+    """JSON error envelope for a verb invoked without a required condition."""
+    return json.dumps(
+        {
+            "ok": False,
+            "error": "browser_missing_target",
+            "message": f"{verb} requires {required}.",
+        },
+        indent=2,
+    )
+
+
+@main.group(help=_BROWSER_HELP)
+def browser() -> None:
+    pass
+
+
+@browser.command(name="status")
+@click.pass_context
+def browser_status(ctx: click.Context) -> None:
+    """Check whether a browser extension is connected for this user."""
+    emit(cmd_browser_status(LazyState.get(ctx)), is_error=_is_browser_error_output)
+
+
+@browser.command(name="get-dom")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_get_dom(ctx: click.Context, tab_id: int | None) -> None:
+    """Return a pruned accessibility tree with `ref` handles for the active tab."""
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "get-dom", {}, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="screenshot")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_screenshot(ctx: click.Context, tab_id: int | None) -> None:
+    """Capture a PNG of the visible tab (returned as a data URL). Costs tokens."""
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "screenshot", {}, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="navigate")
+@click.option("--url", required=True, help="URL to load in the active tab.")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_navigate(ctx: click.Context, url: str, tab_id: int | None) -> None:
+    """Load a URL in the active tab and wait for load."""
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "navigate", {"url": url}, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="click")
+@click.option("--ref", default=None, help="Element ref from the latest get-dom.")
+@click.option("--selector", default=None, help="CSS selector (fallback when no ref).")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_click(
+    ctx: click.Context, ref: str | None, selector: str | None, tab_id: int | None
+) -> None:
+    """Click an element by `--ref` (preferred) or `--selector`."""
+    if not ref and not selector:
+        emit(
+            _browser_missing_target("click"),
+            is_error=_is_browser_error_output,
+        )
+        return
+    args = _browser_target_args(ref, selector)
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "click", args, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="type")
+@click.option("--text", required=True, help="Text to append into the field.")
+@click.option("--ref", default=None, help="Element ref from the latest get-dom.")
+@click.option("--selector", default=None, help="CSS selector (fallback when no ref).")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_type(
+    ctx: click.Context,
+    text: str,
+    ref: str | None,
+    selector: str | None,
+    tab_id: int | None,
+) -> None:
+    """Append text into a field (does not clear existing value; see `fill`)."""
+    if not ref and not selector:
+        emit(_browser_missing_target("type"), is_error=_is_browser_error_output)
+        return
+    args = _browser_target_args(ref, selector)
+    args["text"] = text
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "type", args, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="fill")
+@click.option("--text", required=True, help="Replacement value for the field.")
+@click.option("--ref", default=None, help="Element ref from the latest get-dom.")
+@click.option("--selector", default=None, help="CSS selector (fallback when no ref).")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_fill(
+    ctx: click.Context,
+    text: str,
+    ref: str | None,
+    selector: str | None,
+    tab_id: int | None,
+) -> None:
+    """Replace a field's entire value."""
+    if not ref and not selector:
+        emit(_browser_missing_target("fill"), is_error=_is_browser_error_output)
+        return
+    args = _browser_target_args(ref, selector)
+    args["text"] = text
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "fill", args, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="select")
+@click.option("--value", required=True, help="Option value to select.")
+@click.option("--ref", default=None, help="Element ref from the latest get-dom.")
+@click.option("--selector", default=None, help="CSS selector (fallback when no ref).")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_select(
+    ctx: click.Context,
+    value: str,
+    ref: str | None,
+    selector: str | None,
+    tab_id: int | None,
+) -> None:
+    """Choose a `<select>` option by value."""
+    if not ref and not selector:
+        emit(_browser_missing_target("select"), is_error=_is_browser_error_output)
+        return
+    args = _browser_target_args(ref, selector)
+    args["value"] = value
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "select", args, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="press")
+@click.option("--key", required=True, help="Key to send, e.g. Enter, Tab, Escape.")
+@click.option("--ref", default=None, help="Focus this element first (optional).")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_press(
+    ctx: click.Context, key: str, ref: str | None, tab_id: int | None
+) -> None:
+    """Send a key event (optionally after focusing `--ref`)."""
+    args: dict[str, Any] = {"key": key}
+    if ref:
+        args["ref"] = ref
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "press", args, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="scroll")
+@click.option("--ref", default=None, help="Scroll this element into view (optional).")
+@click.option(
+    "--y", type=int, default=None, help="Absolute vertical scroll position (px)."
+)
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_scroll(
+    ctx: click.Context, ref: str | None, y: int | None, tab_id: int | None
+) -> None:
+    """Scroll the page, or to a specific element / y offset."""
+    args: dict[str, Any] = {}
+    if ref:
+        args["ref"] = ref
+    if y is not None:
+        args["y"] = y
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "scroll", args, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="wait-for")
+@click.option(
+    "--selector", default=None, help="Wait until this CSS selector is present."
+)
+@click.option("--text", default=None, help="Wait until this text appears on the page.")
+@click.option("--timeout-ms", type=int, default=None, help="Max wait in milliseconds.")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_wait_for(
+    ctx: click.Context,
+    selector: str | None,
+    text: str | None,
+    timeout_ms: int | None,
+    tab_id: int | None,
+) -> None:
+    """Wait for a selector or text to appear before continuing."""
+    if not selector and not text:
+        emit(
+            _browser_missing_condition("wait-for", "--selector or --text"),
+            is_error=_is_browser_error_output,
+        )
+        return
+    args: dict[str, Any] = {}
+    if selector:
+        args["selector"] = selector
+    if text:
+        args["text"] = text
+    if timeout_ms is not None:
+        args["timeoutMs"] = timeout_ms
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "wait-for", args, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="list-tabs")
+@click.pass_context
+def browser_list_tabs(ctx: click.Context) -> None:
+    """List open tabs (tabId, title, url)."""
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "list-tabs", {}),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="open-tab")
+@click.option("--url", required=True, help="URL to open in a new tab.")
+@click.pass_context
+def browser_open_tab(ctx: click.Context, url: str) -> None:
+    """Open a new tab at the given URL."""
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "open-tab", {"url": url}),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="extract-links")
+@click.option(
+    "--tab-id", type=int, default=None, help="Target tab id (default: active tab)."
+)
+@click.pass_context
+def browser_extract_links(ctx: click.Context, tab_id: int | None) -> None:
+    """Return all visible links on the active tab."""
+    emit(
+        cmd_browser_action(LazyState.get(ctx), "extract-links", {}, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="download")
+@click.argument("url")
+@click.argument("dest")
+@click.option("--tab-id", type=int, default=None, help="Tab whose session to use.")
+@click.pass_context
+def browser_download(
+    ctx: click.Context, url: str, dest: str, tab_id: int | None
+) -> None:
+    """Download URL using the page session and save it to workspace path DEST.
+
+    \b
+    Fetches the resource with the tab's existing login/session (essential for
+    files behind a sign-in) and writes the bytes to DEST. It does NOT upload to
+    the knowledge base or attach to the chat — do that as a separate follow-up
+    (e.g. `unique-cli upload <file> <folder>`).
+
+    \b
+    Examples:
+      unique-cli browser download "https://portal/report.pdf" ./output/report.pdf
+    """
+    emit(
+        cmd_browser_download(LazyState.get(ctx), url, dest, tab_id=tab_id),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="open-panel")
+@click.pass_context
+def browser_open_panel(ctx: click.Context) -> None:
+    """Open the Unique side panel in the user's browser (extension shell)."""
+    emit(
+        cmd_browser_control(LazyState.get(ctx), "open-panel", {}),
+        is_error=_is_browser_error_output,
+    )
+
+
+@browser.command(name="focus-tab")
+@click.option(
+    "--tab-id", type=int, required=True, help="Tab id to bring to the foreground."
+)
+@click.pass_context
+def browser_focus_tab(ctx: click.Context, tab_id: int) -> None:
+    """Bring a specific tab to the foreground (extension shell control)."""
+    emit(
+        cmd_browser_control(LazyState.get(ctx), "focus-tab", {"tabId": tab_id}),
+        is_error=_is_browser_error_output,
+    )
+
+
 # -- Web Search ------------------------------------------------------------
 
 

unique_sdk-2026.28.0.dev16/unique_sdk/cli/commands/browser.py

@@ -0,0 +1,354 @@
+"""Browser steering command: drive the user's signed-in Chrome tab.
+
+``unique-cli browser <verb>`` talks to the **browser-bridge** relay service,
+which forwards each action to the Unique Chrome extension over the user's
+outbound WebSocket. The agent never sees the page directly — it works from the
+DOM snapshot / result JSON the extension returns.
+
+Unlike the knowledge-base commands (which hit the platform ``api_base`` via
+:mod:`unique_sdk` resources), the bridge lives at its own base URL supplied by
+the Swappable Intelligence runner in ``.unique-browser.json``:
+
+    {"bridgeUrl": "https://gateway.<cluster>/browser-bridge",
+     "installUrl": "https://..."}
+
+The command therefore issues plain HTTP requests to
+``{bridgeUrl}/public/browser/{status,action,control,download}`` with the same
+identity headers the SDK sends (``Authorization`` / ``x-user-id`` /
+``x-company-id`` / ``x-app-id``). The gateway authenticates the request and the
+bridge enforces the host allowlist / kill-switch itself; the CLI only needs the
+HTTP base.
+
+Every subcommand prints a JSON envelope to stdout:
+
+    success  -> {"ok": true, "result": <verb-specific payload>}
+    failure  -> {"ok": false, "error": "<code>", "message": "...", ...}
+
+so the agent can ``json.loads`` the output and branch on ``ok``. Error
+envelopes cause a non-zero exit so Bash ``&&`` chains stop cleanly. The bridge's
+``browser_not_connected`` body (installUrl + remediation) is passed through
+verbatim under ``ok: false``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+
+import requests
+
+from unique_sdk.cli.state import ShellState
+
+BROWSER_ERROR_PREFIX = "browser:"
+BROWSER_CONFIG_FILENAME = ".unique-browser.json"
+ENV_CONFIG_PATH = "UNIQUE_BROWSER_CONFIG"
+
+# Bridge controller base (`@Controller('public/browser')`), appended to the
+# configured bridge base URL. Keep in sync with the browser-bridge service.
+_BRIDGE_API_PREFIX = "public/browser"
+
+# Generous defaults: page loads / waits can legitimately take a while, and the
+# bridge already caps its own per-action timeout. Downloads stream large files.
+_ACTION_TIMEOUT_SECONDS = 120
+_DOWNLOAD_TIMEOUT_SECONDS = 600
+_DOWNLOAD_CHUNK_BYTES = 64 * 1024
+
+
+class BrowserConfigError(Exception):
+    """Raised when ``.unique-browser.json`` is missing or has no ``bridgeUrl``."""
+
+
+def resolve_config_path(config_path: str | None = None) -> Path:
+    """Locate ``.unique-browser.json`` (explicit arg → env → cwd)."""
+    if config_path:
+        return Path(config_path).expanduser()
+    env_path = os.environ.get(ENV_CONFIG_PATH)
+    if env_path:
+        return Path(env_path).expanduser()
+    return Path.cwd() / BROWSER_CONFIG_FILENAME
+
+
+def load_browser_config(config_path: str | None = None) -> dict[str, Any]:
+    """Read and validate the browser bridge config.
+
+    Returns a dict with at least ``bridgeUrl`` (str) and an optional
+    ``installUrl`` (str | None). Raises :class:`BrowserConfigError` with an
+    agent-actionable message when browser control is not wired up for this
+    turn, so the caller can relay it instead of dialing an empty URL.
+    """
+    path = resolve_config_path(config_path)
+    if not path.is_file():
+        raise BrowserConfigError(
+            f"browser steering is not enabled for this task ({BROWSER_CONFIG_FILENAME} "
+            "not found). Ask the operator to enable Browser Control on the assistant."
+        )
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise BrowserConfigError(f"could not read {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise BrowserConfigError(f"{path} is not a JSON object")
+    bridge_url = data.get("bridgeUrl")
+    if not isinstance(bridge_url, str) or not bridge_url.strip():
+        raise BrowserConfigError(
+            f"{path} has no 'bridgeUrl'; browser steering cannot reach the bridge."
+        )
+    return data
+
+
+def _bridge_endpoint(bridge_url: str, endpoint: str) -> str:
+    return f"{bridge_url.rstrip('/')}/{_BRIDGE_API_PREFIX}/{endpoint}"
+
+
+def _auth_headers(state: ShellState, *, json_body: bool) -> dict[str, str]:
+    """Identity headers mirroring ``unique_sdk`` request headers.
+
+    On a secured cluster / localhost the gateway injects identity from the
+    request context and ``api_key`` / ``app_id`` may be empty; we still send
+    ``x-user-id`` / ``x-company-id`` so the bridge can key the connection.
+    """
+    headers: dict[str, str] = {"Accept": "application/json"}
+    config = state.config
+    if config.api_key:
+        headers["Authorization"] = f"Bearer {config.api_key}"
+    if config.user_id:
+        headers["x-user-id"] = config.user_id
+    if config.company_id:
+        headers["x-company-id"] = config.company_id
+    if config.app_id:
+        headers["x-app-id"] = config.app_id
+    if json_body:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def _ok(result: Any) -> str:
+    return json.dumps({"ok": True, "result": result}, indent=2, ensure_ascii=False)
+
+
+def _err(code: str, message: str, **extra: Any) -> str:
+    body: dict[str, Any] = {"ok": False, "error": code, "message": message}
+    body.update(extra)
+    return json.dumps(body, indent=2, ensure_ascii=False)
+
+
+def _error_from_response(resp: requests.Response) -> str:
+    """Translate a non-2xx bridge response into an ``ok: false`` envelope.
+
+    The bridge returns structured JSON bodies — ``browser_not_connected``
+    (424, with ``installUrl`` + ``remediation``) and ``{error, message}`` for
+    action failures. Pass those through verbatim so the agent sees the exact
+    remediation the skill documents; fall back to a generic envelope when the
+    body is not JSON.
+    """
+    try:
+        body = resp.json()
+    except ValueError:
+        return _err(
+            "browser_bridge_error",
+            (resp.text or f"bridge returned HTTP {resp.status_code}").strip(),
+            status=resp.status_code,
+        )
+    if isinstance(body, dict):
+        passthrough = dict(body)
+        passthrough.setdefault("error", "browser_bridge_error")
+        passthrough.setdefault("message", f"bridge returned HTTP {resp.status_code}")
+        passthrough["ok"] = False
+        return json.dumps(passthrough, indent=2, ensure_ascii=False)
+    return _err(
+        "browser_bridge_error",
+        f"bridge returned HTTP {resp.status_code}",
+        status=resp.status_code,
+    )
+
+
+# ── Verb dispatch ─────────────────────────────────────────────────────────────
+
+
+def cmd_browser_status(state: ShellState, *, config_path: str | None = None) -> str:
+    """Probe bridge connectivity for the current user."""
+    try:
+        config = load_browser_config(config_path)
+    except BrowserConfigError as exc:
+        return _err("browser_not_configured", str(exc))
+
+    url = _bridge_endpoint(config["bridgeUrl"], "status")
+    try:
+        resp = requests.get(
+            url,
+            headers=_auth_headers(state, json_body=False),
+            timeout=_ACTION_TIMEOUT_SECONDS,
+        )
+    except requests.RequestException as exc:
+        return _err(
+            "browser_bridge_unreachable", f"could not reach the browser bridge: {exc}"
+        )
+    if not resp.ok:
+        return _error_from_response(resp)
+    try:
+        return _ok(resp.json())
+    except ValueError:
+        return _err("browser_bridge_error", "bridge returned a non-JSON status body")
+
+
+def _post_verb(
+    state: ShellState,
+    endpoint: str,
+    payload: dict[str, Any],
+    *,
+    config_path: str | None,
+) -> str:
+    """Shared POST for the ``action`` and ``control`` endpoints."""
+    try:
+        config = load_browser_config(config_path)
+    except BrowserConfigError as exc:
+        return _err("browser_not_configured", str(exc))
+
+    url = _bridge_endpoint(config["bridgeUrl"], endpoint)
+    try:
+        resp = requests.post(
+            url,
+            headers=_auth_headers(state, json_body=True),
+            data=json.dumps(payload),
+            timeout=_ACTION_TIMEOUT_SECONDS,
+        )
+    except requests.RequestException as exc:
+        return _err(
+            "browser_bridge_unreachable", f"could not reach the browser bridge: {exc}"
+        )
+    if not resp.ok:
+        return _error_from_response(resp)
+    try:
+        body = resp.json()
+    except ValueError:
+        return _err("browser_bridge_error", "bridge returned a non-JSON body")
+    # Controller responds with {ok: true, result}. Surface the result directly
+    # under our own envelope so the shape is identical across every verb.
+    if isinstance(body, dict) and "result" in body:
+        return _ok(body["result"])
+    return _ok(body)
+
+
+def cmd_browser_action(
+    state: ShellState,
+    verb: str,
+    args: dict[str, Any],
+    *,
+    tab_id: int | None = None,
+    config_path: str | None = None,
+) -> str:
+    """Run a DOM / interaction verb against the active (or given) tab."""
+    payload: dict[str, Any] = {"verb": verb, "args": args}
+    if tab_id is not None:
+        payload["tabId"] = tab_id
+    return _post_verb(state, "action", payload, config_path=config_path)
+
+
+def cmd_browser_control(
+    state: ShellState,
+    verb: str,
+    args: dict[str, Any],
+    *,
+    config_path: str | None = None,
+) -> str:
+    """Run a control verb that steers the extension shell (panel/tab focus)."""
+    payload: dict[str, Any] = {"verb": verb, "args": args}
+    return _post_verb(state, "control", payload, config_path=config_path)
+
+
+def cmd_browser_download(
+    state: ShellState,
+    url: str,
+    dest: str,
+    *,
+    tab_id: int | None = None,
+    config_path: str | None = None,
+) -> str:
+    """Download *url* using the page's session and stream it to *dest*.
+
+    Writes bytes to the workspace path ``dest`` (creating parent directories).
+    Does not upload to the knowledge base or attach to the chat — that is a
+    separate follow-up command. Returns an envelope describing the saved file.
+    """
+    try:
+        config = load_browser_config(config_path)
+    except BrowserConfigError as exc:
+        return _err("browser_not_configured", str(exc))
+
+    payload: dict[str, Any] = {"url": url}
+    if tab_id is not None:
+        payload["tabId"] = tab_id
+
+    endpoint = _bridge_endpoint(config["bridgeUrl"], "download")
+    try:
+        resp = requests.post(
+            endpoint,
+            headers=_auth_headers(state, json_body=True),
+            data=json.dumps(payload),
+            timeout=_DOWNLOAD_TIMEOUT_SECONDS,
+            stream=True,
+        )
+    except requests.RequestException as exc:
+        return _err(
+            "browser_bridge_unreachable", f"could not reach the browser bridge: {exc}"
+        )
+
+    if not resp.ok:
+        # Error bodies are small JSON — read fully (not streamed) before mapping.
+        return _error_from_response(resp)
+
+    dest_path = Path(dest).expanduser()
+
+    total = 0
+    try:
+        # Parent creation lives inside the try so a permission / filesystem
+        # failure surfaces as an ok:false envelope instead of a traceback.
+        if dest_path.parent and not dest_path.parent.exists():
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+        with dest_path.open("wb") as handle:
+            for chunk in resp.iter_content(chunk_size=_DOWNLOAD_CHUNK_BYTES):
+                if chunk:
+                    handle.write(chunk)
+                    total += len(chunk)
+    except requests.RequestException as exc:
+        # Network failures during streaming (timeout, dropped connection,
+        # chunked-encoding error) — drop any truncated bytes so a later step
+        # can't mistake the partial file for a complete download.
+        dest_path.unlink(missing_ok=True)
+        return _err(
+            "browser_bridge_unreachable",
+            f"download stream from the browser bridge failed: {exc}",
+        )
+    except OSError as exc:
+        dest_path.unlink(missing_ok=True)
+        return _err(
+            "browser_download_write_failed",
+            f"could not prepare or write {dest_path}: {exc}",
+        )
+
+    file_name_header = resp.headers.get("X-Browser-File-Name")
+    file_name = unquote(file_name_header) if file_name_header else dest_path.name
+    result = {
+        "path": str(dest_path),
+        "bytes": total,
+        "mimeType": resp.headers.get("Content-Type"),
+        "fileName": file_name,
+    }
+    return _ok(result)
+
+
+def is_error_output(output: str) -> bool:
+    """Return ``True`` when a JSON envelope reports ``ok: false``.
+
+    Lets the Click layer translate a failure envelope into a non-zero exit
+    without special-casing each error code. Non-JSON or non-``ok`` payloads
+    (e.g. the ``status`` body) are treated as success.
+    """
+    try:
+        data = json.loads(output)
+    except (json.JSONDecodeError, TypeError):
+        return False
+    return isinstance(data, dict) and data.get("ok") is False