Merge pull request #18 from browser-use/sync/harness-fefca43

sync: harness fefca43

Author: Alezander9

AGENTS.md

@@ -135,12 +135,16 @@ See `UPSTREAM.md` for the canonical version. Short form:
 ### Vendored harness
 
 `packages/bcode-browser/harness/` is vendored from
-`browser-use/browser-harness`. Path-allowlist policy:
-
-- `helpers.py` — editable. Primary BrowserCode extension surface.
-- `daemon.py`, `admin.py` — protected. Pull verbatim. If behavior change
-  is needed, upstream a PR to `browser-use/browser-harness`.
-- `interaction-skills/`, `domain-skills/` — verbatim. Never edit.
+`browser-use/browser-harness`. Path-allowlist policy (post upstream PR #229
+src-layout reorg):
+
+- `agent-workspace/agent_helpers.py` — editable. Primary BrowserCode
+  extension surface.
+- `src/browser_harness/*.py` (`daemon.py`, `admin.py`, `helpers.py`,
+  `run.py`, `_ipc.py`) — protected. Pull verbatim. If behavior change is
+  needed, upstream a PR to `browser-use/browser-harness`.
+- `interaction-skills/`, `agent-workspace/domain-skills/` — verbatim.
+  Never edit.
 
 Sync workflow lives in `harness-sync.md`.
 

UPSTREAM.md

@@ -54,7 +54,7 @@ Future Yellow modifications (per ROADMAP):
 
 Every Yellow modification should be evaluated for conversion to a Green extension point via upstream PR. See decisions.md §1c and ROADMAP F8.
 
-The harness has its own narrower zone policy (see §3 below): `helpers.py` is editable, `daemon.py`/`admin.py` are protected, deliberate divergences are logged per-file.
+The harness has its own narrower zone policy (see §3 below): `agent-workspace/agent_helpers.py` is editable, the `src/browser_harness/` core package is protected, deliberate divergences are logged per-file.
 
 ---
 
@@ -83,19 +83,20 @@ Each upstream has its own append-only table. Add a row every time you pull.
 | Date | From SHA | To SHA | By | Notes |
 |---|---|---|---|---|
 | 2026-04-26 | — (initial) | `216a2c9` | bcode | Initial vendor at A2. Verbatim copy of `browser-use/browser-harness@216a2c9`. No divergences yet. |
+| 2026-04-28 | `216a2c9` | `fefca43` | bcode | 41 upstream commits. **Major restructure** (PR #229): src-layout reorg (`*.py` → `src/browser_harness/*.py`), `domain-skills/` → `agent-workspace/domain-skills/`, agent-editable surface moved from root `helpers.py` to `agent-workspace/agent_helpers.py`, new `_ipc.py` for Windows TCP / POSIX AF_UNIX support, tests moved to `tests/{unit,integration}/`. Also: Expedia/Substack/Loom/Gmail domain skills, screenshot max-dim, helpers.switch_tab dict-accept, websockets pin 15.0.1, BU_CDP_URL, doctor improvements, JS eval refactor. Adapted our integration: `browser-execute.ts` invokes `browser-harness` console-script (not `python run.py`); `harness.ts` `PRESERVED_PATHS` updated to `agent-workspace/agent_helpers.py`; smoke test now imports from `browser_harness` package; `browser-execute.txt` prompt updated to point at new helper paths. Divergences touched: none (still just `.gitignore` + `.venv/`). |
 
 ---
 
 ## 3. Harness divergences
 
 Per-file record of where `packages/bcode-browser/harness/` deliberately differs from upstream. Read this *before* a sync diff so intentional differences aren't mistaken for missing features.
 
-Path-allowlist policy (decisions.md §3.7, §4.5):
+Path-allowlist policy (decisions.md §3.7, §4.5; updated for upstream PR #229 src-layout reorg):
 
-- `helpers.py` — editable; primary BrowserCode extension surface. Divergences expected.
-- `daemon.py`, `admin.py` — protected. Pulled verbatim from upstream. If behavior change is needed, upstream a PR to `browser-use/browser-harness`.
-- `interaction-skills/`, `domain-skills/` — verbatim from upstream. We never edit these.
-- Other files (`run.py`, `pyproject.toml`, `LICENSE`, `README.md`, etc.) — divergence allowed but discouraged.
+- `agent-workspace/agent_helpers.py` — editable; primary BrowserCode extension surface. Divergences expected.
+- `src/browser_harness/*.py` (`daemon.py`, `admin.py`, `helpers.py`, `run.py`, `_ipc.py`) — protected. Pulled verbatim from upstream. If behavior change is needed, upstream a PR to `browser-use/browser-harness`.
+- `interaction-skills/`, `agent-workspace/domain-skills/` — verbatim from upstream. We never edit these.
+- Other files (`pyproject.toml`, `LICENSE`, `README.md`, etc.) — divergence allowed but discouraged.
 
 | File | Section | Direction | Reason |
 |---|---|---|---|

harness-sync.md

@@ -62,23 +62,24 @@ This is where the agent earns its keep. For each file changed in `<recorded-sha>
 
 | File category | Action |
 |---|---|
-| Files not in our divergences table (incl. `daemon.py`, `admin.py`, `domain-skills/`, `interaction-skills/`, `pyproject.toml`, `LICENSE`, etc.) | Take upstream verbatim — `cp temp/browser-harness/<path> packages/bcode-browser/harness/<path>`. |
+| Files not in our divergences table (incl. `src/browser_harness/*.py`, `agent-workspace/domain-skills/`, `interaction-skills/`, `tests/`, `pyproject.toml`, `LICENSE`, etc.) | Take upstream verbatim — `cp temp/browser-harness/<path> packages/bcode-browser/harness/<path>`. |
 | Files in our divergences table | Read each upstream hunk. For each, decide: **take** (apply upstream change to our file), **skip** (our divergence wins, ignore upstream change), or **adapt** (rewrite our divergence to coexist with the upstream change). Update the divergences row if its reason or scope shifts. |
 | New upstream files | Copy in. |
 | Files we have but upstream removed | Decide: keep ours (record in divergences) or delete. |
 
 Path-allowlist policy stays in force during sync resolution as well as normal development:
-- `helpers.py` — editable, agent's primary extension surface.
-- `daemon.py`, `admin.py` — protected. Always take upstream verbatim. If upstream regresses, file an issue at `browser-use/browser-harness` and pin to the prior SHA, do not patch locally.
+- `agent-workspace/agent_helpers.py` — editable, agent's primary extension surface (post PR #229).
+- `src/browser_harness/*.py` (`daemon.py`, `admin.py`, `helpers.py`, `run.py`, `_ipc.py`) — protected. Always take upstream verbatim. If upstream regresses, file an issue at `browser-use/browser-harness` and pin to the prior SHA, do not patch locally.
 
 ### 6. Smoke test
 
 ```sh
 cd packages/bcode-browser/harness
-uv run python -c "import run, helpers, daemon, admin; print('imports ok')"
+uv run python -c "from browser_harness import run, helpers, daemon, admin, _ipc; print('imports ok')"
+uv run browser-harness --version
 ```
 
-Verifies the package builds, deps resolve, and all four modules import. We don't try to start the daemon here — that needs a real Chrome and is covered by integration tests, not the sync workflow.
+The first line verifies the package builds, deps resolve, and the core modules import. The second exercises the console-script entry point we invoke from `browser-execute.ts`. We don't try to start the daemon here — that needs a real Chrome and is covered by integration tests, not the sync workflow.
 
 ### 7. Update UPSTREAM.md
 

packages/bcode-browser/harness/README.md

@@ -4,15 +4,15 @@
 
 The simplest, thinnest, **self-healing** harness that gives LLM **complete freedom** to complete any browser task. Built directly on CDP.
 
-The agent writes what's missing, mid-task. No framework, no recipes, no rails. One websocket to Chrome, nothing between.
+The agent writes what's missing, mid-task, inside `agent-workspace/`. No framework, no recipes, no rails. One websocket to Chrome, nothing between.
 
 ```
   ● agent: wants to upload a file
   │
-  ● helpers.py → upload_file() missing
+  ● agent-workspace/agent_helpers.py → helper missing
   │
-  ● agent edits the harness and writes it    helpers.py   192 → 199 lines
-  │                                                       + upload_file()
+  ● agent writes it                         agent_helpers.py
+  │                                                       + custom helper
   ✓ file uploaded
 ```
 
@@ -25,14 +25,14 @@ Paste into Claude Code or Codex:
 ```text
 Set up https://github.com/browser-use/browser-harness for me.
 
-Read `install.md` first to install and connect this repo to my real browser. Then read `SKILL.md` for normal usage. Always read `helpers.py` because that is where the functions are. When you open a setup or verification tab, activate it so I can see the active browser tab. After it is installed, open this repository in my browser and, if I am logged in to GitHub, ask me whether you should star it for me as a quick demo that the interaction works — only click the star if I say yes. If I am not logged in, just go to browser-use.com.
+Read `install.md` first to install and connect this repo to my real browser. Then read `SKILL.md` for normal usage. Use `agent-workspace/agent_helpers.py` and `agent-workspace/domain-skills/` for task-specific edits. When you open a setup or verification tab, activate it so I can see the active browser tab. After it is installed, open this repository in my browser and, if I am logged in to GitHub, ask me whether you should star it for me as a quick demo that the interaction works — only click the star if I say yes. If I am not logged in, just go to browser-use.com.
 ```
 
 When this page appears, tick the checkbox so the agent can connect to your browser:
 
 <img src="docs/setup-remote-debugging.png" alt="Remote debugging setup" width="520" style="border-radius: 12px;" />
 
-See [domain-skills/](domain-skills/) for example tasks.
+See [agent-workspace/domain-skills/](agent-workspace/domain-skills/) for example tasks.
 
 ## Free remote browsers
 
@@ -46,16 +46,16 @@ Useful for stealth, sub-agents, or deployment.<br>
 
 - `install.md` — first-time install and browser bootstrap
 - `SKILL.md` — day-to-day usage
-- `run.py` (~36 lines) — runs plain Python with helpers preloaded
-- `helpers.py` (~195 lines) — starting tool calls; the agent edits these
-- `admin.py` + `daemon.py` (~361 lines) — daemon bootstrap plus the CDP websocket and socket bridge
+- `src/browser_harness/` — protected core package
+- `agent-workspace/agent_helpers.py` — helper code the agent edits
+- `agent-workspace/domain-skills/` — reusable site-specific skills the agent edits
 
 ## Contributing
 
-PRs and improvements welcome. The best way to help: **contribute a new domain skill** under [domain-skills/](domain-skills/) for a site or task you use often (LinkedIn outreach, ordering on Amazon, filing expenses, etc.). Each skill teaches the agent the selectors, flows, and edge cases it would otherwise have to rediscover.
+PRs and improvements welcome. The best way to help: **contribute a new domain skill** under [agent-workspace/domain-skills/](agent-workspace/domain-skills/) for a site or task you use often (LinkedIn outreach, ordering on Amazon, filing expenses, etc.). Each skill teaches the agent the selectors, flows, and edge cases it would otherwise have to rediscover.
 
 - **Skills are written by the harness, not by you.** Just run your task with the agent — when it figures something non-obvious out, it files the skill itself (see [SKILL.md](SKILL.md)). Please don't hand-author skill files; agent-generated ones reflect what actually works in the browser.
-- Open a PR with the generated `domain-skills/<site>/` folder — small and focused is great.
+- Open a PR with the generated `agent-workspace/domain-skills/<site>/` folder — small and focused is great.
 - Bug fixes, docs tweaks, and helper improvements are equally welcome.
 - Browse existing skills (`github/`, `linkedin/`, `amazon/`, ...) to see the shape.
 

packages/bcode-browser/harness/SKILL.md

@@ -5,16 +5,16 @@ description: Direct browser control via CDP. Use when the user wants to automate
 
 # browser-harness
 
-Direct browser control via CDP. Read helpers.py — that's where the functions live. For setup, install, or connection problems, read install.md.
+Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py` and `agent-workspace/domain-skills/`. For setup, install, or connection problems, read install.md.
 
 ## Usage
 
 ```bash
-browser-harness <<'PY'
+browser-harness -c '
 new_tab("https://docs.browser-use.com")
 wait_for_load()
 print(page_info())
-PY
+'
 ```
 
 - Invoke as browser-harness — it's on $PATH. No cd, no uv run.
@@ -30,9 +30,9 @@ Available domain skills:
 ## Tool call shape
 
 ```bash
-browser-harness <<'PY'
+browser-harness -c '
 # any python. helpers pre-imported. daemon auto-starts.
-PY
+'
 ```
 
 run.py calls ensure_daemon() before exec — you never start/stop manually unless you want to.
@@ -42,18 +42,18 @@ run.py calls ensure_daemon() before exec — you never start/stop manually unles
 Use remote for parallel sub-agents (each gets its own isolated browser via a distinct BU_NAME) or on a headless server. BROWSER_USE_API_KEY must be set. start_remote_daemon, list_cloud_profiles, list_local_profiles, sync_local_profile are pre-imported.
 
 ```bash
-browser-harness <<'PY'
+browser-harness -c '
 start_remote_daemon("work")                               # default — clean browser, no profile
 # start_remote_daemon("work", profileName="my-work")      # reuse a cloud profile (already logged in)
 # start_remote_daemon("work", profileId="<uuid>")         # same, but by UUID
 # start_remote_daemon("work", proxyCountryCode="de", timeout=120)   # DE proxy, 2-hour timeout
 # start_remote_daemon("work", proxyCountryCode=None)      # disable the Browser Use proxy
-PY
+'
 
-BU_NAME=work browser-harness <<'PY'
+BU_NAME=work browser-harness -c '
 new_tab("https://example.com")
 print(page_info())
-PY
+'
 ```
 
 start_remote_daemon prints liveUrl and auto-opens it in the local browser (if a GUI is detected) so the user can watch along. Headless servers print only — share the URL with the user. The daemon PATCHes the cloud browser to stop on shutdown, which persists profile state. Running remote daemons bill until timeout.
@@ -62,7 +62,7 @@ Profiles (cookies-only login state) live in interaction-skills/profile-sync.md 
 
 ## Search first
 
-Search domain-skills/ first for the domain you are working on before inventing a new approach.
+Search `agent-workspace/domain-skills/` first for the domain you are working on before inventing a new approach.
 
 Only if you start struggling with a specific mechanic while navigating, look in interaction-skills/ for helpers. The available interaction skills are:
 - cookies.md
@@ -85,13 +85,13 @@ Only if you start struggling with a specific mechanic while navigating, look in
 Useful commands:
 
 ```bash
-rg --files domain-skills
-rg -n "tiktok|upload" domain-skills
+rg --files agent-workspace/domain-skills
+rg -n "tiktok|upload" agent-workspace/domain-skills
 ```
 
 ## Always contribute back
 
-If you learned anything non-obvious about how a site works, open a PR to domain-skills/<site>/ before you finish. Default to contributing. The harness gets better only because agents file what they learn. If figuring something out cost you a few steps, the next run should not pay the same tax.
+If you learned anything non-obvious about how a site works, open a PR to `agent-workspace/domain-skills/<site>/` before you finish. Default to contributing. The harness gets better only because agents file what they learn. If figuring something out cost you a few steps, the next run should not pay the same tax.
 
 Examples of what's worth a PR:
 
@@ -118,7 +118,7 @@ The *durable* shape of the site — the map, not the diary. Focus on what the ne
 
 - Raw pixel coordinates. They break on viewport, zoom, and layout changes. Describe how to *locate* the target (selector, scrollIntoView, aria-label, visible text) — never where it happened to be on your screen.
 - Run narration or step-by-step of the specific task you just did.
-- Secrets, cookies, session tokens, user-specific state. domain-skills/ is shared and public.
+- Secrets, cookies, session tokens, user-specific state. `agent-workspace/domain-skills/` is shared and public.
 
 ## What actually works
 
@@ -139,7 +139,7 @@ The *durable* shape of the site — the map, not the diary. Focus on what the ne
 - Connect to the user's running Chrome. Don't launch your own browser.
 - cdp-use is only for CDPClient.send_raw. Prefer raw CDP strings over typed wrappers.
 - run.py stays tiny. No argparse, subcommands, or extra control layer.
-- Helpers stay short. Browser primitives in helpers.py; daemon/bootstrap and remote session admin live in admin.py.
+- Core helpers stay short. Put task-specific helper additions in `agent-workspace/agent_helpers.py`; daemon/bootstrap and remote session admin live in the core package.
 - Don't add a manager layer. No retries framework, session manager, daemon supervisor, config system, or logging framework.
 
 ## Gotchas (field-tested)
@@ -158,4 +158,4 @@ The *durable* shape of the site — the map, not the diary. Focus on what the ne
 ## Interaction notes
 
 - interaction-skills/ holds reusable UI mechanics such as dialogs, tabs, dropdowns, iframes, and uploads.
-- domain-skills/ holds site-specific workflows and should be updated when you discover reusable patterns for a website.
+- `agent-workspace/domain-skills/` holds site-specific workflows and should be updated when you discover reusable patterns for a website.

packages/bcode-browser/harness/agent-workspace/agent_helpers.py

@@ -0,0 +1,7 @@
+"""Agent-editable browser helpers.
+
+Add task-specific browser primitives here. Core helpers from browser_harness.helpers
+load this file when BH_AGENT_WORKSPACE points at this directory, or when this
+repo's default agent-workspace exists.
+"""
+