browser-workspace 0.4.2 → 0.4.9

package/README.md

@@ -26,7 +26,7 @@ browser-workspace session stop SESSION_ID
 
 ```text
 browser-workspace
-├── src/browser_harness/     low-level browser/CDP runtime (forked internally)
+├── pyproject.toml           pins the external browser-harness runtime dependency
 ├── agent-workspace/         Browser Workspace helper layer
 ├── extension/               Chrome workspace/tab manager
 ├── session_daemon.py        persistent Python session service
@@ -136,3 +136,17 @@ Each platform manifest records explicit verification status and evidence. `verif
 ## 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.
+
+### Python distribution (PyPI)
+
+Browser Workspace is also packaged as a Python CLI. Once its PyPI trusted publisher is configured and a `pypi-v*` release tag is published, invoke it with:
+
+```bash
+uvx browser-workspace status
+uvx browser-workspace session list
+uvx browser-workspace platform profile wechat-channels
+```
+
+The package entry point is `browser_workspace_app.cli:main`, and Python dependencies are managed by `pyproject.toml`. This uses the same existing Chrome profile and Session Daemon socket as the previous npm CLI; it does **not** start a second browser or daemon when the existing one is healthy.
+
+Before building, run `python tools/sync-pypi-package.py` to copy canonical Python and packaged platform assets to the wheel source. Run `uv build`, then validate with `uvx --from dist/browser_workspace-<version>-py3-none-any.whl browser-workspace status`. The PyPI publishing workflow uses GitHub OIDC trusted publishing; configure `lalalic/browser-workspace` with the `pypi` environment as the publisher on PyPI before the first tag release.

package/SKILL.md

@@ -9,14 +9,14 @@ Browser Workspace is the **only browser skill agents should load**. It includes
 
 ## Agent contract
 
-When installed with `npx skills`, use the CLI from the skill itself; no separate install step is required:
+Install the Skill instructions through your preferred skill manager, but run the published Python CLI through **PyPI/uvx**. The Skill directory is documentation, not the executable source of truth:
 
 ```bash
-BW_CLI="$HOME/.agents/skills/browser-workspace/bin/browser-workspace"
-$BW_CLI status
+bw() { uvx browser-workspace "$@"; }
+bw status
 ```
 
-On first use, Browser Workspace bootstraps its own `.venv` automatically.
+On first use, `uvx` installs Browser Workspace and Python dependencies from PyPI into its managed cache. No local source checkout, `.venv`, `.env`, or `npx` CLI is required. Use `uvx browser-workspace ...` consistently, including in NeoY/Agents Relay workers.
 
 Use one session-owned execution path for orchestrated browser work:
 
@@ -61,7 +61,7 @@ Rules:
 Default workspace is `Harness`:
 
 ```bash
-$BW_CLI session start
+bw 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.
@@ -69,7 +69,7 @@ Normal agents do not choose or manage workspaces. `session start` defaults to `H
 Start directly at a URL when known:
 
 ```bash
-$BW_CLI session start --url https://example.com
+bw session start --url https://example.com
 ```
 
 The result is JSON containing `session_id`, `workspace`, `target_id`, the starting `url`, and `workspace_supported`.
@@ -81,7 +81,7 @@ Browser Workspace self-manages exactly one machine-wide persistent, visible Chro
 `session exec` reads Python from stdin. Helpers are already imported; do not import another browser package.
 
 ```bash
-$BW_CLI session exec <session_id> <<'PY'
+bw session exec <session_id> <<'PY'
 print(page_info())
 print(snapshot())
 PY
@@ -90,7 +90,7 @@ PY
 Python state persists across later calls in the same session:
 
 ```bash
-$BW_CLI session exec <session_id> <<'PY'
+bw session exec <session_id> <<'PY'
 meeting_name = "Demo"
 print(current_tab())
 PY
@@ -99,7 +99,7 @@ PY
 Then later:
 
 ```bash
-$BW_CLI session exec <session_id> <<'PY'
+bw session exec <session_id> <<'PY'
 print(meeting_name)
 PY
 ```
@@ -109,7 +109,7 @@ A Python file may also be used with `--code-file`.
 ## Stop
 
 ```bash
-$BW_CLI session stop <session_id>
+bw session stop <session_id>
 ```
 
 Stopping closes every tab owned or opened by that session—including tabs created with `new_tab()`, `bh.new_tab()`, and detected child/popup tabs—then destroys the session's Python namespace. Raw `cdp("Target.createTarget", ...)` is rejected; use `new_tab()` so Browser Workspace can own and group the tab. It does not close unrelated browser tabs. Do not reuse the ID afterward.
@@ -117,11 +117,11 @@ Stopping closes every tab owned or opened by that session—including tabs creat
 A safe shell structure is:
 
 ```bash
-SESSION_JSON=$($BW_CLI session start)
+SESSION_JSON=$(bw 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
+trap 'bw session stop "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
 
-$BW_CLI session exec "$SESSION_ID" <<'PY'
+bw session exec "$SESSION_ID" <<'PY'
 print(snapshot())
 PY
 ```
@@ -231,23 +231,23 @@ Platform rules:
 Normal orchestrator workflow:
 
 ```bash
-SESSION_JSON=$($BW_CLI session start --url https://example.com)
+SESSION_JSON=$(bw session start --url https://example.com)
 SESSION_ID=$(python3 -c 'import json,sys; print(json.loads(sys.argv[1])["session_id"])' "$SESSION_JSON")
 
-$BW_CLI platform run microsoft-teams meeting \
+bw platform run microsoft-teams meeting \
   --session-id "$SESSION_ID" \
   --config /path/to/config.json
 
 # If it fails: inspect/self-heal using the same SESSION_ID, write the repair
 # back to the platform implementation, then resume safely.
 
-$BW_CLI session stop "$SESSION_ID"
+bw session stop "$SESSION_ID"
 ```
 
 One-shot mode is explicit and is not self-healing:
 
 ```bash
-$BW_CLI platform run microsoft-teams meeting \
+bw platform run microsoft-teams meeting \
   --auto-session \
   --config /path/to/config.json
 ```
@@ -296,13 +296,14 @@ Read the matching platform `README.md` and `manifest.yaml` before invoking or mo
 
 ## Installation
 
-Run the bundled installer from the skill directory:
+Use the published PyPI command (requires `uv`/`uvx`):
 
 ```bash
-./scripts/install.sh
+uvx browser-workspace status
+uvx browser-workspace session list
 ```
 
-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.
+`uvx` resolves the published Python wheel and installs the dependencies declared in `pyproject.toml`. Do not run the legacy bundled installer or point agents at a checked-out `bin/browser-workspace` script. The installed CLI reuses the same Browser Workspace Chrome profile and Session Daemon socket.
 
 There is no required separate Browser Harness installation.
 
@@ -320,4 +321,4 @@ 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/`.
+The low-level browser runtime is the separately maintained `browser-harness` Python dependency. Browser Workspace owns the session/workspace/platform product layer and pins the exact Harness runtime revision it was tested with; Harness source is not vendored into this repository. Upstream licensing remains documented under `licenses/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-workspace",
-  "version": "0.4.2",
+  "version": "0.4.9",
   "description": "Agent browser workspace with persistent sessions, tab leasing, snapshots, and platform workflows.",
   "bin": {
     "browser-workspace": "bin/browser-workspace"

package/platform_runner.py

@@ -135,7 +135,11 @@ def action_path(platform: str, action: str) -> Path:
 
 def prepare_action(path: Path, config_path: Path | None = None) -> str:
     source = path.read_text()
-    source = "import sys\nsys.path.insert(0, " + repr(str(path.parent.resolve())) + ")\n" + source
+    # The daemon is long-lived: importing a previous installed platform module
+    # must never shadow the current action source in sys.modules.
+    siblings = [p.stem for p in path.parent.glob("_*.py")]
+    prelude = "import sys\n" + "\n".join(f"sys.modules.pop({name!r}, None)" for name in siblings)
+    source = prelude + "\nsys.path.insert(0, " + repr(str(path.parent.resolve())) + ")\n" + source
     if "__CFG_PATH__" in source:
         if config_path is None:
             raise ValueError(f"{path.parent.parent.name}/{path.stem}: --config is required")
@@ -173,7 +177,12 @@ def run_platform_action(
 
     owned_session = bool(auto_session)
     started = request({"op": "start", "workspace": None, "url": url}) if owned_session else {"session_id": session_id, "workspace_supported": None}
-    sid = started["session_id"]
+    sid = started.get("session_id")
+    if not sid:
+        return {"platform": platform, "action": action, "workspace_supported": started.get("workspace_supported"),
+                "session_mode": "auto_session_no_self_heal" if owned_session else "caller_owned_self_heal_capable",
+                "self_heal_capable": not owned_session,
+                "result": {"ok": False, "error": started.get("error", "session start returned no session_id")}}
     result = None
     cleanup = None
     try:

package/platforms/chatgpt/actions/_lifecycle_common.py

@@ -1,6 +1,12 @@
 import json
 import time
-from _readiness import wait_until_stable, submission_receipt, prompt_text_matches
+from _readiness import (
+    SubmissionVerificationError,
+    submission_failure_diagnostic,
+    submission_receipt,
+    prompt_text_matches,
+    wait_until_stable,
+)
 
 
 def composer_selector():
@@ -12,6 +18,24 @@ def composer_selector():
         const r=e.getBoundingClientRect();
         if (r.width>0 && r.height>0) return selector;
       }
+      const generic=[...document.querySelectorAll('[contenteditable="true"]')].filter(e=>{
+        if (e.id==='pending-home-input' || e.disabled) return false;
+        const r=e.getBoundingClientRect();
+        return r.width>0 && r.height>0;
+      });
+      return generic.length===1 ? '[contenteditable="true"]:not(#pending-home-input)' : null;
+    })()""")
+
+
+def primary_composer_selector():
+    return js("""(() => {
+      const selectors=['#prompt-textarea','[contenteditable="true"][data-composer-markdown]','[contenteditable="true"][data-lexical-editor="true"]'];
+      for (const selector of selectors) {
+        const e=document.querySelector(selector);
+        if (!e || e.disabled) continue;
+        const r=e.getBoundingClientRect();
+        if (r.width>0 && r.height>0) return selector;
+      }
       return null;
     })()""")
 
@@ -33,6 +57,16 @@ def send_enabled():
     })()"""))
 
 
+def verification_ui_state(selector):
+    return {
+        "composer_selector": selector,
+        "composer_text_length": len((composer_text(selector) or "").strip()),
+        "send_enabled": send_enabled(),
+        "generating": is_generating(),
+        "user_turn_count": len(user_turns()),
+    }
+
+
 def is_generating():
     return bool(js("""(() => !![...document.querySelectorAll('button')].find(b => {
       const a=(b.getAttribute('aria-label')||'').toLowerCase();
@@ -66,12 +100,21 @@ def wait_for_idle(timeout=300):
 
 
 def fill_prompt(prompt):
-    selector=wait_until_stable(
-        lambda: composer_selector(),
-        lambda value: bool(value),
-        timeout=30,
-        phase="ChatGPT composer readiness",
-    )
+    try:
+        selector=wait_until_stable(
+            lambda: primary_composer_selector(),
+            lambda value: bool(value),
+            timeout=20,
+            phase="ChatGPT canonical composer readiness",
+        )
+    except RuntimeError:
+        # The preferred selector timed out; still try the generic composer.
+        selector=wait_until_stable(
+            lambda: composer_selector(),
+            lambda value: bool(value),
+            timeout=5,
+            phase="ChatGPT composer readiness",
+        )
     editable=bool(js(f"""(() => document.querySelector({json.dumps(selector)})?.getAttribute('contenteditable')==='true')()"""))
     if editable:
         chunks=[prompt[i:i+256] for i in range(0, len(prompt), 256)]
@@ -93,27 +136,37 @@ def fill_prompt(prompt):
         if not ok: raise RuntimeError("ChatGPT composer rejected lifecycle continuation")
     else:
         fill_input(selector,prompt,clear_first=True)
-    wait_until_stable(
-        lambda: {"text":composer_text(selector),"send":send_enabled()},
-        lambda state: prompt_text_matches(state["text"],prompt) and state["send"],
-        timeout=20,
-        phase="ChatGPT lifecycle continuation readiness",
-    )
+    try:
+        wait_until_stable(
+            lambda: {"text":composer_text(selector),"send":send_enabled()},
+            lambda state: prompt_text_matches(state["text"],prompt) and state["send"],
+            timeout=20,
+            phase="ChatGPT lifecycle continuation readiness",
+        )
+    except RuntimeError as exc:
+        raise RuntimeError(f"{exc}; diagnostic={json.dumps(verification_ui_state(selector), ensure_ascii=False)}") from exc
     return selector
 
 
 def submit(prompt):
-    before=len(user_turns())
     selector=fill_prompt(prompt)
+    ui_before=verification_ui_state(selector)
     clicked=js("""(() => {
       const b=document.querySelector('button[data-testid="send-button"],button[aria-label="Send prompt"],button[aria-label="Send"],form button[type="submit"]');
       if(!b||b.disabled||b.getAttribute('aria-disabled')==='true')return false;
       b.click(); return true;
     })()""")
     if not clicked: raise RuntimeError("ChatGPT send button changed before lifecycle submit")
-    deadline=time.time()+30
-    while time.time()<deadline:
-        receipt=submission_receipt(user_turns(),before,prompt,composer_text(selector))
-        if receipt: return receipt
-        time.sleep(.2)
-    raise RuntimeError("ChatGPT lifecycle submission was not observed")
+    try:
+        wait_until_stable(
+            lambda: {"composer_empty": not bool(composer_text(selector).strip()), "send_disabled": not send_enabled()},
+            lambda state: state["composer_empty"] and state["send_disabled"],
+            timeout=30, interval=.2, stable_samples=3,
+            phase="post-submit composer reset",
+        )
+    except RuntimeError as exc:
+        raise SubmissionVerificationError(
+            "ChatGPT submission did not reach a stable cleared composer and disabled Send button",
+            {"ui_before":ui_before,"ui_after":verification_ui_state(selector),"reason":"post_submit_ui_unverified"},
+        ) from exc
+    return {"verified_by":"composer-cleared", "turn": {"id":""}}

package/platforms/chatgpt/actions/_new_turn.py

@@ -28,6 +28,7 @@ print(json.dumps({
   "mode":"new-turn",
   "project_id":project_id,
   "thread_id":thread_id,
+  "thread_url":thread_url,
   "verified_by":receipt["verified_by"],
   "user_message_id":receipt["turn"].get("id") or None,
 },ensure_ascii=False),flush=True)

package/platforms/chatgpt/actions/_readiness.py

@@ -1,13 +1,22 @@
 """Bounded polling helpers for ChatGPT submit readiness."""
 from __future__ import annotations
 
+import json
 import re
 import time
 
+
+class SubmissionVerificationError(RuntimeError):
+    def __init__(self, message, diagnostic):
+        serialized = json.dumps(diagnostic, ensure_ascii=False, sort_keys=True)
+        super().__init__(f"{message}: {serialized}")
+        self.diagnostic = diagnostic
+
 def wait_until_stable(read_state, ready, *, timeout, interval=0.25, stable_samples=2, phase):
     deadline = time.monotonic() + timeout
     stable = 0
     last_state = {}
+    stable_state = None
     while time.monotonic() < deadline:
         try:
             last_state = read_state()
@@ -16,7 +25,11 @@ def wait_until_stable(read_state, ready, *, timeout, interval=0.25, stable_sampl
             time.sleep(interval)
             continue
         if ready(last_state):
-            stable += 1
+            if stable_state == last_state:
+                stable += 1
+            else:
+                stable_state = last_state
+                stable = 1
             if stable >= stable_samples:
                 return last_state
         else:
@@ -47,6 +60,19 @@ def submission_receipt(turns, before_count, prompt, composer_text):
     for turn in turns[before_count:]:
         if prompt_text_matches(turn.get("text"), prompt):
             return {"verified_by": "user-turn", "turn": turn}
-    if not (composer_text or "").strip():
-        return {"verified_by": "composer-cleared", "turn": {"id": None, "text": prompt}}
     return None
+
+
+def submission_failure_diagnostic(turns, before_count, prompt, composer_text, ui_before=None, ui_after=None):
+    return {
+        "accepted": False,
+        "reason": "no_accepted_user_turn",
+        "user_turn_matched": False,
+        "before_user_turn_count": len(turns[:before_count]),
+        "user_turn_count": len(turns),
+        "composer_populated": bool((composer_text or "").strip()),
+        "composer_text_length": len((composer_text or "").strip()),
+        "ui_changed": None if ui_before is None or ui_after is None else bool(ui_before != ui_after),
+        "ui_before": ui_before,
+        "ui_after": ui_after,
+    }

package/platforms/chatgpt/actions/_submit_thread.py

@@ -2,7 +2,13 @@ import json
 import os
 import time
 from urllib.parse import quote
-from _readiness import wait_until_stable, submission_receipt, prompt_text_matches
+from _readiness import (
+    SubmissionVerificationError,
+    submission_failure_diagnostic,
+    submission_receipt,
+    prompt_text_matches,
+    wait_until_stable,
+)
 
 CFG=json.load(open("__CFG_PATH__",encoding="utf-8"))
 project_id=str(CFG.get("project_id") or "").strip()
@@ -117,6 +123,8 @@ wait_until_stable(
     timeout=45 if attachments else 20,
     phase="send readiness",
 )
+state_before=composer_state()
+ui_before={"composer_present":state_before["present"],"composer_text_length":len(state_before["text"]),"send_enabled":state_before["sendEnabled"]}
 if not click_visible_send(): raise RuntimeError("ChatGPT send button changed before click")
 deadline=time.time()+15
 receipt=None
@@ -124,6 +132,15 @@ while time.time()<deadline:
     receipt=submission_receipt(user_turns(),before_users,prompt,visible_composer_text())
     if receipt: break
     time.sleep(.1)
-if not receipt: raise RuntimeError("ChatGPT submission verification did not observe an accepted submission")
+if not receipt:
+    state_after=composer_state()
+    raise SubmissionVerificationError(
+        "ChatGPT submission verification did not observe an accepted submission",
+        submission_failure_diagnostic(
+            user_turns(), before_users, prompt, visible_composer_text(),
+            ui_before,
+            {"composer_present":state_after["present"],"composer_text_length":len(state_after["text"]),"send_enabled":state_after["sendEnabled"]},
+        ),
+    )
 
-print(json.dumps({"status":"submitted","project_id":project_id,"thread_id":thread_id,"verified_by":receipt["verified_by"],"user_message_id":receipt["turn"].get("id") or None,"app":app_name or None},ensure_ascii=False),flush=True)
+print(json.dumps({"status":"submitted","project_id":project_id,"thread_id":thread_id,"thread_url":thread_url,"verified_by":receipt["verified_by"],"user_message_id":receipt["turn"].get("id") or None,"app":app_name or None},ensure_ascii=False),flush=True)

package/platforms/chatgpt/actions/_temporary_submit.py

@@ -439,7 +439,14 @@ def _fill_prompt_if_needed(prompt, mode_label, timeout=30):
     deadline = time.time() + timeout
     last_error = None
     while time.time() < deadline:
-        selector = _wait_for_composer(timeout=min(5, max(1, deadline - time.time())))
+        try:
+            selector = _wait_for_composer(timeout=min(5, max(1, deadline - time.time())))
+        except RuntimeError as exc:
+            # Hydration and navigation can temporarily remove the composer.
+            # Continue the outer readiness window rather than aborting on the first poll.
+            last_error = exc
+            time.sleep(.25)
+            continue
         if prompt_text_matches(_composer_text(selector), prompt):
             return selector
 
@@ -567,5 +574,18 @@ while time.time() < deadline:
 else:
     raise RuntimeError("Temporary Chat activation was not observed")
 
-result = _submit_current_page(prompt, temporary=True, mode_label="Temporary Chat")
+try:
+    result = _submit_current_page(prompt, temporary=True, mode_label="Temporary Chat")
+except RuntimeError as exc:
+    # A URL-prefilled Temporary Chat can retain the pre-hydration home input
+    # without ever mounting the active composer. No send occurred, so retry
+    # once on a clean Temporary Chat page without URL prompt prefill.
+    if "composer readiness was not observed ready" not in str(exc):
+        raise
+    goto_url(temporary_chat_entry_url())
+    wait_for_load()
+    _click_temporary_chat_toggle()
+    if not _temporary_chat_enabled():
+        raise RuntimeError("Temporary Chat mode lost during composer recovery") from exc
+    result = _submit_current_page(prompt, temporary=True, mode_label="Temporary Chat")
 print(json.dumps(result, ensure_ascii=False), flush=True)

package/platforms/chatgpt/actions/_thread_turn.py

@@ -3,7 +3,13 @@ import os
 import re
 import time
 from urllib.parse import urlsplit
-from _readiness import wait_until_stable, submission_receipt, prompt_text_matches
+from _readiness import (
+    SubmissionVerificationError,
+    submission_failure_diagnostic,
+    submission_receipt,
+    prompt_text_matches,
+    wait_until_stable,
+)
 
 
 CFG = json.load(open("__CFG_PATH__", encoding="utf-8"))
@@ -260,6 +266,14 @@ def _submit(prompt, files, target_id):
         phase="send readiness",
     )
     selector=state["selector"]
+    ui_before={
+        "composer_present": bool(_composer()),
+        "composer_text_length": len((_composer_text(selector) or "").strip()),
+        "send_present": bool(_send_state().get("present")),
+        "send_enabled": bool(_send_state().get("enabled")),
+        "generating": _is_generating(),
+        "user_turn_count": len(_user_turns()),
+    }
     clicked=js("""(() => {
       const b=document.querySelector('button[data-testid="send-button"],button[aria-label="Send prompt"],button[aria-label="Send"]');
       if (!b || b.disabled || b.getAttribute('aria-disabled') === 'true') return false;
@@ -272,7 +286,22 @@ def _submit(prompt, files, target_id):
         receipt=submission_receipt(_user_turns(), before_users, prompt, _composer_text(selector))
         if receipt: break
         time.sleep(.25)
-    if not receipt: raise RuntimeError("ChatGPT submission verification did not observe an accepted submission")
+    if not receipt:
+        raise SubmissionVerificationError(
+            "ChatGPT submission verification did not observe an accepted submission",
+            submission_failure_diagnostic(
+                _user_turns(), before_users, prompt, _composer_text(selector),
+                ui_before,
+                {
+                    "composer_present": bool(_composer()),
+                    "composer_text_length": len((_composer_text(selector) or "").strip()),
+                    "send_present": bool(_send_state().get("present")),
+                    "send_enabled": bool(_send_state().get("enabled")),
+                    "generating": _is_generating(),
+                    "user_turn_count": len(_user_turns()),
+                },
+            ),
+        )
     return before_assistants, attachments, receipt
 
 def _result(before_assistants, timeout):