browserwright 0.6.2__tar.gz

browserwright-0.6.2/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: browserwright
+Version: 0.6.2
+Summary: Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends).
+Requires-Python: >=3.11
+Requires-Dist: cdp-use==1.4.5
+Requires-Dist: websockets==15.0.1
+Requires-Dist: pillow==12.2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: playwright>=1.60.0
+Provides-Extra: ux
+Requires-Dist: rich>=13; extra == "ux"

browserwright-0.6.2/README.md

@@ -0,0 +1,346 @@
+# browserwright
+
+Let an AI/code agent drive a real (or isolated) Chrome from the terminal over CDP — open pages, click, type, fill forms, scrape, screenshot — and author **userscripts** the browser runs on matching sites.
+
+One installable package, two CLIs that work together:
+
+- **`browserwright-daemon`** (Layer 1) — resolves a Chrome CDP WebSocket URL and proxies it. Backends: `env / rdp / extension / cloud`. Also `launch-chrome` to spawn an isolated Chrome.
+- **`browserwright`** (Layer 2) — the agent-facing surface: sessions, heredoc scripting with pre-imported primitives, reusable site tasks, memory, and userscript management.
+
+```
+.
+├── src/browserwright/        the package
+│   ├── …                     Layer 2 — sessions / primitives / site skills / memory / userscripts
+│   └── daemon/               Layer 1 — CDP URL resolver + proxy (env/rdp/extension/cloud backends)
+├── chrome-extension/         unpacked relay extension for the `extension` backend
+├── skill/                    Agent skill bundle (symlinked into Claude Code, Codex, and Pi)
+├── tests/{skill,daemon}/     test suites
+├── docs/                     deeper docs (skill.md, daemon.md, session-model.md, …)
+└── browser-connection.md     why this stack exists (CDP discovery, Chrome 144+ popups)
+```
+
+## Prerequisites
+
+- macOS or Linux
+- Python 3.11 (`brew install python@3.11` / `pyenv install 3.11`)
+- Chrome / Chromium (any flavor)
+- `~/.local/bin` on `$PATH`
+- [`uv`](https://docs.astral.sh/uv/) — manages the venv, lockfile, and Python toolchain (`uv` can fetch Python 3.11 itself)
+
+## Install
+
+### PyPI / global tool install
+
+The distribution target is one PyPI package named `browserwright`. A global tool
+install should expose both CLIs:
+
+```bash
+pipx install browserwright
+# or
+uv tool install browserwright
+```
+
+After that, install the one global daemon service:
+
+```bash
+browserwright-daemon install
+browserwright-daemon status
+browserwright-daemon doctor
+```
+
+On macOS, `browserwright-daemon install` registers the daemon as a LaunchAgent
+at `~/Library/LaunchAgents/com.browserwright-daemon.plist`, starts it on login,
+and keeps the single daemon socket at:
+
+```bash
+${XDG_RUNTIME_DIR:-/tmp}/browserwright-daemon.sock
+```
+
+Linux currently does not auto-install a service; run `browserwright-daemon serve`
+from your own systemd-user unit or process supervisor.
+
+The browser extension is intentionally not part of the PyPI packaging contract.
+The long-term user path is to publish/install it through the Chrome Web Store.
+Until then, local development and release installs can still use the repo's
+`chrome-extension/` directory or the copied local release extension described
+below.
+
+The agent skill bundle remains a thin shell around the installed CLI. For
+local release installs, the release installer symlinks that shell into Claude
+Code, Codex, and Pi. For PyPI installs, the intended stable contract is:
+
+```bash
+browserwright --print-skill
+```
+
+Agents should read the runtime guide generated by the installed package version,
+so the skill instructions stay version-locked to the CLI that actually runs.
+
+The global install is considered healthy when these pass:
+
+```bash
+browserwright version check
+browserwright-daemon version check
+browserwright-daemon doctor
+```
+
+If the daemon was already running when you upgraded the global tool, restart it:
+
+```bash
+browserwright-daemon restart
+```
+
+If it is running in the foreground instead of as the macOS LaunchAgent:
+
+```bash
+browserwright-daemon stop
+browserwright-daemon serve
+```
+
+### PyPI release flow
+
+PyPI releases are driven by git tags. For published artifacts, the git tag is
+the source of truth for the package version; the release workflow rewrites
+`pyproject.toml` to that tag version before building the sdist and wheel.
+
+After a PR has landed on `main`, publish by pushing a version tag:
+
+```bash
+git checkout main
+git pull
+git tag v0.6.3
+git push origin v0.6.3
+```
+
+The GitHub Action only runs for `v*` tags. A tag like `v0.6.3` publishes package
+version `0.6.3`.
+
+### Local immutable release install
+
+From the repo root. If you have [`mise`](https://mise.jdx.dev/), install an immutable local release:
+
+```bash
+mise run install-release
+```
+
+This builds a wheel, installs it into:
+
+```bash
+~/.local/share/browserwright/releases/<version>/
+```
+
+and points global entry points at that release copy:
+
+```bash
+~/.local/bin/browserwright        -> releases/<version>/.venv/bin/browserwright
+~/.local/bin/browserwright-daemon -> releases/<version>/.venv/bin/browserwright-daemon
+~/.claude/skills/browserwright    -> releases/<version>/skill
+~/.codex/skills/browserwright     -> releases/<version>/skill
+~/.pi/agent/skills/browserwright  -> releases/<version>/skill
+```
+
+The global install does not point at the development checkout, so broken in-progress edits do not break agents already using browserwright.
+
+Useful release commands:
+
+```bash
+browserwright release status
+browserwright release list
+browserwright release activate <version>
+mise run version-check
+```
+
+The skill bundle is intentionally a thin shell. The authoritative agent instructions come from `browserwright --print-skill`, so installed agents read docs generated by the installed CLI in the active release.
+
+For development only, `mise run dev-link` links the current checkout into global PATH and skill dirs. That is convenient for debugging but can break global agents if the checkout is broken.
+
+## Update the local global install
+
+Use this flow when you want the global Code Agent install on this machine to pick up the current repo state:
+
+```bash
+# 1. Build a non-editable release and atomically update global symlinks.
+mise run install-release
+
+# 2. Verify the active release, CLI, daemon, generated skill, and extension metadata.
+browserwright release status
+browserwright version check
+browserwright-daemon version check
+
+# 3. Restart the daemon if release status says the running daemon is stale.
+browserwright-daemon restart
+```
+
+If the daemon is running manually instead of as the macOS LaunchAgent, restart it manually:
+
+```bash
+browserwright-daemon stop
+browserwright-daemon serve
+```
+
+The release installer also copies the unpacked Chrome extension into the stable local load path:
+
+```bash
+/Users/metajs/Library/Mobile Documents/com~apple~CloudDocs/etc/chrome-extension/browserwright
+```
+
+If `install-release` reports `reload_chrome_extension: true`, open `chrome://extensions/` and reload the `browserwright` unpacked extension from that stable path. The path does not change across releases; the installer overwrites its contents.
+
+## Local release discipline
+
+For local immutable release installs, `pyproject.toml` is the semver source used
+by the local build. For PyPI releases, the git tag is the source of truth and
+the publish workflow writes that version into `pyproject.toml` before building.
+The Python runtime, daemon runtime, generated skill document, and extension
+checks all read or compare against the built package version.
+
+After installing a release:
+
+```bash
+browserwright version check
+browserwright-daemon version check
+browserwright-daemon restart   # when installed as the macOS LaunchAgent
+```
+
+If `browserwright release install-local` reports that `chrome_extension` changed, reload the unpacked extension in Chrome from the active release's `chrome-extension/` path. Chrome does not allow this repo to refresh the extension automatically.
+
+## Smoke test
+
+```bash
+# Start an isolated Chrome (own profile dir, won't touch your daily Chrome)
+browserwright-daemon launch-chrome --port 9333 --profile bs-smoke --persistent --json
+
+# Drive it
+BD_PORT=9333 BD_BACKEND=rdp browserwright <<'PY'
+page.goto("https://example.com", wait_until="load")
+print(f"URL:   {page.url}")
+print(f"Title: {page.title()}")
+PY
+# expected:
+#   URL:   https://example.com/
+#   Title: Example Domain
+```
+
+Clean up: `kill <pid>` (the `launch-chrome --json` output includes the pid).
+
+## Usage
+
+### Sessions: create once, pass everywhere
+
+A **session** is the isolation key that lets multiple agents drive browsers without colliding. Create one, then every later call carries its id (via `--session` or `BD_SESSION`):
+
+```bash
+sid=$(browserwright session new --backend=extension)
+BD_SESSION=$sid browserwright <<'PY'
+page.goto("https://news.ycombinator.com", wait_until="load")
+print(page.title())
+PY
+browserwright whoami --session=$sid
+browserwright session end --session=$sid
+```
+
+A bare heredoc with no session/`BD_PORT` context exits 2 with guidance — the daemon is never silently shared.
+
+One global daemon serves every session (fixed socket `browserwright-daemon.sock`; no per-instance name). The session's backend is fixed at `session new` and never changes. On `extension` the session's "browser" is a Chrome **tab group** (named after the session) inside the user's real Chrome; `session end` closes the whole group. On `rdp` the daemon launches and owns a dedicated, isolated Chrome (profile `bs-s<id>`) that dies with the session. **Isolation caveat:** rdp sessions get isolated profiles (separate cookies/storage), but extension tab groups isolate only the *tab set* — all extension sessions share the user's one profile, so they share cookies/login/origin storage with each other and with the user.
+
+### Two invocation forms
+
+```bash
+# (a) Inline heredoc — one-off scripts; drive the injected Playwright `page`
+BD_SESSION=$sid browserwright <<'PY'
+page.goto("https://news.ycombinator.com", wait_until="load")
+print(page.title())
+print(snapshot())          # [ref=eN] aria tree → page.locator("aria-ref=eN")
+PY
+
+# (b) Solidified task — reusable, pre-saved flow under ~/.browserwright/site-skills/<host>/tasks/
+browserwright list-tasks
+browserwright list-tasks --query="search the web"
+browserwright task wikipedia.org/lookup --title="Wikipedia"
+```
+
+### Choose a backend
+
+| Scenario | Backend | How |
+|---|---|---|
+| Your daily Chrome (logged-in / personal) *(default for "use my browser")* | `extension` | `browserwright session new --backend=extension …` — load `chrome-extension/` once, connect via the daemon's relay; zero popups |
+| Scripts / iterative work in throwaway profiles | `rdp` + isolated Chrome | `browserwright-daemon launch-chrome --port 9333 --profile bs-dev` + `BD_PORT=9333 BD_BACKEND=rdp` |
+| Fingerprint browser (AdsPower / MultiLogin / 比特浏览器) | `rdp` | point `BD_PORT` at the tool's exposed port |
+| Remote Chrome (Browser Use / Browserless / Hyperbrowser) | `cloud` | `browserwright-daemon serve --provider <name>` + auth env vars |
+
+Interactive wizard: `browserwright install` — walks the decision tree and writes your pick.
+
+### Userscripts
+
+Author Tampermonkey-style scripts the `extension` backend injects on matching sites:
+
+```bash
+browserwright userscript push ./greet.user.js --verify
+browserwright userscript list
+browserwright userscript toggle <id>
+browserwright userscript logs <id>
+browserwright userscript remove <id>
+```
+
+### The heredoc surface
+
+Browser driving is **real synchronous Playwright**. Every heredoc gets three
+names injected, already connected through the daemon's Playwright CDP facade:
+
+- **`page`** — a Playwright `Page` bound to the session's current tab, **reused
+  across heredocs**. Navigate it in place (`page.goto`, `page.locator`,
+  `page.fill`, `page.click`, …); never `page.close()`.
+- **`context`** — the Playwright `BrowserContext`. `context.new_page()` only when
+  you genuinely need a second tab.
+- **`snapshot()`** — a first-party AI aria snapshot; each node carries a
+  `[ref=eN]` you act on via `page.locator("aria-ref=eN")`. Prefer this over
+  screenshots; re-`snapshot()` after each action (observe → act → observe).
+
+The connection is lazy — a heredoc that only uses the helpers below opens no
+browser. **Tab discipline:** reuse the bound tab, navigate in place, never
+close the browser/context (those are the user's real tabs).
+
+Non-browser helpers (also pre-imported):
+
+- **HTTP (no browser, for static pages):** `http_get(url)`
+- **Memory:** `remember`, `remember_global`, `remember_preference`, `memory_read`
+- **Site-skills / tasks:** `list_site_skills`, `load_site_skill`, `run_task`, `run_tasks_concurrent`, `bootstrap_site`
+
+Full catalogue and guidance in `skill/SKILL.md`.
+
+### Diagnostics
+
+```bash
+browserwright-daemon doctor                  # which backends are live, why each is/isn't usable
+browserwright-daemon list-backends
+browserwright doctor                         # skill-side health
+browserwright-daemon stats                   # observability counters when `serve` is running
+```
+
+## Agent integrations
+
+The `skill/` directory is an agent skill bundle. Release install symlinks it into Claude Code, Codex, and Pi skill directories, and each symlink points at the active immutable release copy. The bundle is a stable shell; it tells the agent to run `browserwright --print-skill` for the version-locked runtime guide. Prompts like *"open example.com and screenshot it"*, *"scrape the HN front page"*, or *"write me a userscript that …"* trigger it automatically.
+
+## Uninstall
+
+```bash
+rm ~/.local/bin/browserwright ~/.local/bin/browserwright-daemon
+rm ~/.claude/skills/browserwright
+rm ~/.codex/skills/browserwright
+rm ~/.pi/agent/skills/browserwright
+rm -rf .venv
+rm -rf ~/.cache/browserwright-daemon ~/.browserwright
+```
+
+## Further reading
+
+- `TESTING.md` — map of the test suites and how to run them
+- `browser-connection.md` — *why* this stack exists (CDP discovery paths, Chrome 144+ popup mechanics)
+- `docs/daemon.md` — backend internals, env vars, `config.toml`
+- `docs/skill.md` — full primitive surface and release notes
+- `docs/session-model.md` — the session isolation model
+- `ONBOARDING.md` — contributor-oriented architecture tour
+
+## License
+
+TBD — currently un-licensed source-available. Add a `LICENSE` file before publishing.

browserwright-0.6.2/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "browserwright"
+version = "0.6.2"
+description = "Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends)."
+requires-python = ">=3.11"
+dependencies = [
+    "cdp-use==1.4.5",
+    "websockets==15.0.1",
+    "pillow==12.2.0",
+    "httpx>=0.27",
+    # Phase C: the skill heredoc injects a real Playwright `page`/`context`
+    # bound to the daemon facade, so playwright is a runtime dependency now (it
+    # was previously dev-only). `playwright install chromium` is still needed
+    # for tests that launch a browser; the daemon-facade path drives the
+    # daemon-resolved Chrome and does not need Playwright's bundled browser.
+    "playwright>=1.60.0",
+]
+
+[project.optional-dependencies]
+ux = ["rich>=13"]
+
+[dependency-groups]
+dev = [
+    "coverage>=7",
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+browserwright = "browserwright.cli:main"
+browserwright-daemon = "browserwright.daemon.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+browserwright = [
+    "site_skills_starter/**/*.md",
+    "site_skills_starter/**/*.py",
+    "skill_runtime.md",
+]
+
+[tool.setuptools.exclude-package-data]
+browserwright = ["**/__pycache__/*", "**/*.pyc", "**/*.pyo"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "real_chrome: end-to-end test that launches a real Chrome + extension (skipped unless explicitly selected)",
+]
+
+[tool.coverage.run]
+source = ["src/browserwright"]
+omit = [
+    "src/browserwright/__main__.py",
+    "src/browserwright/site_skills_starter/*",
+]
+
+[tool.coverage.report]
+skip_covered = true
+sort = "Cover"

browserwright-0.6.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

browserwright-0.6.2/src/browserwright/__init__.py

@@ -0,0 +1,33 @@
+"""browserwright — Layer 2 of the browser stack.
+
+Public surface: ``browserwright.cli:main`` is the CLI entry point.
+
+For programmatic use inside REPL/task scripts, import names from the top-level
+``browserwright`` namespace (everything from ``browserwright.api`` is re-exported
+here)::
+
+    from browserwright import http_get, remember, run_task
+
+Browser driving itself is done with real Playwright in inline ``-s/-e`` calls
+via the injected ``page`` / ``context`` (and ``snapshot()``) — see
+``repl/_namespace.build_globals``. Those are NOT importable from this module;
+they are bound per call to the session's current tab.
+"""
+from .version import __version__  # noqa: F401
+
+# Re-export the primitive namespace assembled in api.py so user scripts can
+# `from browserwright import *`. The REPL/inline/task entry points use the same
+# helper to populate their exec globals.
+from .api import EXPORTS  # noqa: F401
+from .api import *  # noqa: F401,F403
+from .errors import (  # noqa: F401
+    AuthWall,
+    BrowserwrightError,
+    Captcha,
+    CDPError,
+    DaemonUnavailable,
+    ElementNotFound,
+    NeedsUserConfirm,
+    NetworkError,
+    PageLoadFailed,
+)

browserwright-0.6.2/src/browserwright/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m browserwright ...`` as an alternate entry point."""
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

browserwright-0.6.2/src/browserwright/_executor/__init__.py

@@ -0,0 +1,47 @@
+"""Phase B: the persistent per-session executor.
+
+A resident, per-session **sync** subprocess (``python -m browserwright._executor
+--session <id>``) that holds live Playwright ``page`` / ``context`` / ``browser``
++ a persistent ``state`` dict + one long-lived facade ``connect_over_cdp``
+connection for its whole lifetime. The ``browserwright -s <id> -e <code>`` CLI
+is a **thin client**: it ships the code body to the session's executor,
+which runs it in a namespace where ``page`` / ``context`` / ``state`` are the
+LIVE persistent objects, and returns the result.
+
+Why a separate subprocess (not a thread in the asyncio daemon):
+  - sync Playwright is thread-affine and can't run on the daemon's event loop;
+  - agent code (infinite loop / segfault) crashing the privileged daemon — which
+    manages the user's real browser — is an unacceptable blast radius.
+A per-session subprocess crashes only itself (D1 of the task).
+
+Transport (Fork 2): the daemon owns the LIFECYCLE (spawn/discover via the
+``ensureExecutor`` verb + an ``_ipc`` discovery file); the executor owns the
+DATA PLANE — its own per-session unix socket speaking a simple length-framed
+request/response of our design (``protocol.py``). The thin client connects
+directly to that socket, keeping arbitrary code + large output OFF the daemon's
+critical path.
+
+Concurrency (Fork 3): a single dedicated worker thread owns the sync-Playwright
+objects (thread-affine); the accept loop enqueues ``{code, timeout}`` requests
+and the worker drains them FIFO (serial queue).
+
+Status: PR1 (process skeleton + data plane), PR2 (daemon-side supervision —
+idle reap / endSession kill / crash reap / orphan sweep), and PR3 (``reset()`` +
+full output protocol: warnings / screenshots / truncation / traceback-bearing
+errors + per-call timeout enforcement) are all in place.
+"""
+from __future__ import annotations
+
+from .protocol import (
+    ExecuteRequest,
+    ExecuteResponse,
+    recv_message,
+    send_message,
+)
+
+__all__ = [
+    "ExecuteRequest",
+    "ExecuteResponse",
+    "recv_message",
+    "send_message",
+]

browserwright-0.6.2/src/browserwright/_executor/__main__.py

@@ -0,0 +1,9 @@
+"""``python -m browserwright._executor --session <id>`` entrypoint."""
+from __future__ import annotations
+
+import sys
+
+from .process import main
+
+if __name__ == "__main__":
+    sys.exit(main())

browserwright-0.6.2/src/browserwright/_executor/client.py

@@ -0,0 +1,127 @@
+"""Thin-client side of the executor data plane.
+
+Used by ``repl/inline.py`` when inline code touches ``page`` / ``context`` /
+``snapshot`` / ``state`` / ``reset``: the whole code body is shipped to the
+session's resident executor and the response is replayed locally.
+
+Control plane (spawn + discover) goes through the daemon's
+``BrowserwrightDaemon.ensureExecutor`` verb over the EXISTING mode_b socket
+(tiny payload). The daemon spawns the executor if absent, waits for it to bind +
+write its ``_ipc`` discovery file, and returns the socket path. The data plane
+(this module) then connects DIRECTLY to that socket — keeping arbitrary code +
+large output off the daemon's event loop (Fork 2).
+"""
+from __future__ import annotations
+
+import socket
+import time
+
+from ..errors import BrowserwrightError
+from .protocol import (
+    DEFAULT_TIMEOUT_MS,
+    ExecuteRequest,
+    ExecuteResponse,
+    recv_message,
+    send_message,
+)
+
+# Generous slack added on TOP of the per-call timeout for the data-plane recv.
+# The FIRST execute on a freshly-spawned executor triggers the lazy cold-start
+# (connect_over_cdp + bind), which can take ~10-35s on a daemon-restart race
+# (the executor's `_COLD_START_CONNECT_ATTEMPTS` backoff is ~10s; the registry's
+# spawn-ready budget is 35s). The control-plane RPC no longer waits on that, so
+# the wait moved HERE — the client's own blocking socket has no keepalive, so a
+# long first call is fine as long as we don't time the recv out prematurely.
+_COLD_START_RECV_SLACK_S = 45.0
+
+
+class ExecutorUnavailable(BrowserwrightError):
+    """The session's executor could not be ensured/reached.
+
+    Surfaced when ``ensureExecutor`` fails or the executor socket can't be
+    connected — actionable: the daemon must be running (it spawns the
+    executor)."""
+
+    default_fix = ("ensure the daemon is running (`browserwright-daemon status "
+                   "--json` should show `alive`); it lazily spawns the "
+                   "per-session executor on first browser use.")
+
+
+def ensure_executor(sess) -> str:
+    """Ask the daemon to ensure the session's executor and return its socket
+    path. Uses the session's mode_b CDP client (``sess.cdp``) to send the
+    control-plane verb."""
+    sid = _session_id(sess)
+    try:
+        # The browserwright session is already bound on the websocket query
+        # (`?session=<id>`). Do not pass it as CDP's top-level `sessionId`;
+        # that field means "attached target session" inside the proxy mux.
+        res = sess.cdp.send(
+            "BrowserwrightDaemon.ensureExecutor", bsSession=sid)
+    except Exception as e:  # noqa: BLE001
+        raise ExecutorUnavailable(
+            f"ensureExecutor failed for session {sid!r}: {e}") from e
+    sock_path = res.get("exec_sock") if isinstance(res, dict) else None
+    if not isinstance(sock_path, str) or not sock_path:
+        raise ExecutorUnavailable(
+            f"ensureExecutor returned no socket for session {sid!r}: {res!r}")
+    return sock_path
+
+
+def run_on_executor(sess, code: str, *,
+                    timeout_ms: int = DEFAULT_TIMEOUT_MS) -> ExecuteResponse:
+    """Ship ``code`` to the session's executor and return its response.
+
+    Ensures the executor (control plane), connects its socket (data plane),
+    sends one :class:`ExecuteRequest`, reads one :class:`ExecuteResponse`.
+
+    The recv socket timeout is the per-call ``timeout_ms`` PLUS a cold-start
+    slack: the first execute on a fresh executor performs the lazy
+    connect_over_cdp + bind (moved off the control plane), which can add up to
+    ~35s. The executor itself bounds the worker per-call timeout; this slack
+    only prevents the CLIENT recv from giving up before the executor replies."""
+    sock_path = ensure_executor(sess)
+    recv_timeout = max(timeout_ms, 1) / 1000.0 + _COLD_START_RECV_SLACK_S
+    conn = _connect(sock_path, timeout=recv_timeout)
+    try:
+        send_message(conn, ExecuteRequest(code=code, timeout_ms=timeout_ms).to_dict())
+        msg = recv_message(conn)
+    except (ConnectionError, OSError, ValueError) as e:
+        raise ExecutorUnavailable(
+            f"executor data-plane error on {sock_path!r}: {e}") from e
+    finally:
+        try:
+            conn.close()
+        except OSError:
+            pass
+    return ExecuteResponse.from_dict(msg)
+
+
+def _connect(sock_path: str, *, timeout: float = 30.0,
+             retry_until: float = 5.0) -> socket.socket:
+    """Connect the executor's unix socket, briefly retrying a not-yet-bound
+    socket (the daemon returns the path the moment it spawns; the bind may race
+    by a few ms)."""
+    deadline = time.monotonic() + retry_until
+    last: OSError | None = None
+    while True:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(timeout)
+        try:
+            s.connect(sock_path)
+            return s
+        except OSError as e:
+            last = e
+            s.close()
+            if time.monotonic() >= deadline:
+                raise ExecutorUnavailable(
+                    f"could not connect executor socket {sock_path!r}: {e}"
+                ) from last
+            time.sleep(0.05)
+
+
+def _session_id(sess) -> str:
+    rec = getattr(sess, "session_record", None)
+    if isinstance(rec, dict) and rec.get("id"):
+        return str(rec["id"])
+    raise ExecutorUnavailable("no session id bound; cannot reach an executor")