@plainconceptsplatform/agent-harness 3.8.2 → 3.9.0-alpha.1

package/skills/browser-automation/SKILL.md

@@ -1,72 +1,100 @@
 ---
 name: browser-automation
-description: Reliable, composable browser automation using agent-browser. Use when capturing screenshots of a locally running app, clicking UI elements, reading page content, or automating browser interactions on localhost.
+description: Browser automation using browse, the OpenCode MCP server that drives the user's real Chrome-family browser. Use when capturing screenshots, clicking UI elements, reading page content, filling forms, or automating browser interactions on localhost or any site the user is logged into.
 license: MIT
-compatibility: Requires agent-browser CLI installed (Rust binary) and running.
+compatibility: Requires the browse CLI installed, the browse browser extension paired, and the relay running. Install with `browse install`.
 metadata:
   author: copilots
-  version: "2.0"
+  version: "3.0"
 ---
 
-This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and reads on locally running apps are in scope. External services (github.com, dev.azure.com, npmjs.com, etc.) are out of scope for browser tools.
+Browse drives the user's real browser (Chrome, Edge, Brave, Arc, and other Chromium browsers). It uses the user's tabs, logins, cookies, and extensions. Agent tabs open in the background in collapsed groups, out of the user's way.
 
-The only exception: when the user selects "Others (Browser)" as their backlog platform during onboarding, the `pc-userstory` skill may navigate to work item URLs the user explicitly provides. That is the sole case where external navigation is permitted, and only to URLs the user explicitly gives you.
+When only a person can proceed — login, 2FA, passkey, captcha, or payment — call `handoff("what the user should do")` in `execute` and wait. The browse handoff card appears in the browser; when the user clicks Continue, execution resumes.
 
 ## Best-practice workflow
 
-1. Open the page: `agent-browser open <url>` (launches its own Chrome; reuses the running daemon)
-2. Take a snapshot: `agent-browser snapshot` to get the accessibility tree with `@ref` handles
-3. Interact by ref: `agent-browser click @e2`, `agent-browser fill @e3 "text"`
-4. Wait when needed: `agent-browser wait --load networkidle` or `agent-browser wait <selector>`
-5. Confirm the result with a fresh `snapshot`, `get text`, or `screenshot`
+1. Inspect with `await snapshot()` before choosing anything. Prefer the returned refs: `await ref("e12").click()`. Fall back to accessible locators (`page.getByRole(...)`, `getByLabel(...)`), then CSS.
+2. Act with the narrowest stable control, and keep dependent steps in one `execute` while transient UI is open.
+3. Verify with a fresh page read (`page.url()`, a heading, or a new `snapshot()`). A click that returned, or a handoff the user acknowledged, is not proof the task succeeded.
 
-Refs like `@e2` come from the last snapshot and go stale after page changes: retake the snapshot after navigation or dynamic updates before reusing them. When a click fails because another element covers the target (consent banner, modal), dismiss or interact with the covering element, then take a fresh snapshot before retrying.
+Refs belong to one snapshot and expire on navigation or the next snapshot. Take a fresh snapshot after anything changes the page before reusing refs.
 
 ## Tool access
 
-- MCP tools (inside OpenCode): `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, `agent_browser_fill`, `agent_browser_type`, `agent_browser_wait_for_selector`, `agent_browser_screenshot`, `agent_browser_eval`, `agent_browser_close` — configured in `opencode.jsonc` with `--tools core`
-- CLI (any agent, any host): every command below works identically via bash
-- Diagnose the install: `agent-browser doctor`
+- MCP tools (inside OpenCode): `browse.execute` (run Playwright JS), `browse.session_new`, `browse.session_list`, `browse.session_adopt`, `browse.session_allowlist`, `browse.tabs_cleanup`, `browse.network` (HAR capture), `browse.recording`, `browse.flight_recorder`, `browse.secrets_list`, `browse.secrets_status`, `browse.secrets_refresh`, `browse.secrets_run`.
+- The `execute` tool provides: `page` (Playwright Page), `browser`, `context`, `snapshot()`, `ref()`, `fillInput()`, `fillInputs()`, `handoff()`, `screenshot()`, `ariaSnapshot()`, `files` (dir, path, read, write), `secrets.type()`, `network` capture, `pageConsole()`, and more.
+- CLI (any agent, any host): `browse execute --code "..."`, `browse pair`, `browse status`, `browse doctor`, `browse session list`.
 
 ## Selecting elements
 
-- Prefer refs from `snapshot` (`@e1`, `@e2`, ...) over CSS selectors
-- CSS selectors also work: `agent-browser click "#submit"`, `agent-browser fill "#email" "text"`
-- Semantic locators: `agent-browser find role button click --name "Submit"`, `find text "Sign In" click`, `find label "Email" fill "value"`, `find testid <id> click`
-- Native selects: `agent-browser select <sel> <value>`
+- Prefer refs from `snapshot()` (`e1`, `e2`, ...) via `await ref("e2").click()` — these are persistent locators, not CSS selectors
+- Playwright locators: `page.getByRole("button", { name: "Submit" })`, `page.getByLabel("Email")`, `page.getByText("Welcome")`
+- CSS selectors: `page.locator("#submit")`, `page.locator(".nav-item")`
+- Fill inputs: `await ref("e3").fill("text")` or `await page.getByLabel("Email").fill("text")`
+- Native selects: `await page.getByLabel("Country").selectOption("ES")`
+- Checkboxes: `await ref("e5").check()` / `await ref("e5").uncheck()`
 
 ## Reading state
 
-- `agent-browser get text <sel>` — text content of an element
-- `agent-browser get value <sel>` — input value
-- `agent-browser snapshot` — structured accessibility tree (preferred for parsing)
-- `agent-browser screenshot [path]` — `--full` for full page, `--annotate` for numbered labels
-- `agent-browser read` — agent-readable markdown of the active tab (no Chrome launch for URL reads)
+- `await snapshot()` — structured accessibility tree with element refs (preferred for parsing)
+- `await page.locator("body").innerText()` — text content of the page
+- `const url = page.url()` — current URL
+- `const title = await page.title()` — page title
+- `await page.getByRole("heading").first().innerText()` — specific element text
 
-## Tabs and sessions
+## Sessions and tabs
 
-- `agent-browser tab` lists tabs with stable `t1`, `t2` ids; `tab new --label <name>` and `tab <label>` switch
-- `agent-browser close` closes the browser; `close --all` closes every session
+- `browse.session_list()` — list sessions with their URLs, connection state, and allowlists
+- `browse.session_adopt({ targetUrl: "..." })` — adopt an existing user tab as the session's page
+- `browse.session_allowlist({ allowedOrigins: ["example.com"] })` — restrict the session to named hosts (use before typing secrets)
+- `browse.tabs_cleanup({ idleMinutes: 0 })` — close agent tabs nobody has used
 
-## CLI-first debugging
+## Handoffs (logins, 2FA, captchas)
 
-- `agent-browser doctor` — diagnose install, Chrome, and daemon state
-- `agent-browser console` — view console messages; `agent-browser errors` — uncaught exceptions
-- `agent-browser eval "<js>"` — run JavaScript in the page
-- `agent-browser network requests --filter api` — inspect tracked requests
+When only a person can proceed:
+
+```js
+await handoff("Describe what the user should do: log in, enter 2FA code, solve captcha, etc.");
+// Execution pauses. The browse card appears in the browser.
+// When the user clicks Continue, execution resumes here.
+```
+
+Pass `"start"` as the action for operations that themselves block. Never solve a captcha yourself. Never retry-loop a blocked site; if a challenge is interactive, hand off or stop.
+
+## Secrets
+
+- `browse.secrets_list()` — list stored site secrets (names, kinds, allowed origins; values are never shown)
+- `secrets.type(locator, "profile-name")` in `execute` — type a stored secret into a field without the agent seeing it
+- `browse.network({ action: "stop", secrets: "profile-name" })` — capture credentials from a login flow and store them in a reusable profile
+- `browse.secrets_run({ name: "profile-name", command: "npm", args: ["publish"] })` — run a local command with captured credentials injected as `BC_SECRET_N` env vars (redacted in output)
+
+Before typing a stored secret, give the session an allowlist (`session_allowlist` or `session_new` with `allowedOrigins`). Never put credentials in execute source.
+
+## Network capture
+
+- `browse.network({ action: "start", urlFilter: "api" })` — start capturing requests matching a filter
+- `browse.network({ action: "stop", outputPath: "capture.har" })` — stop and write a credential-redacted HAR
+- `browse.network({ action: "stop", secrets: "profile-name" })` — stop and store captured credentials in a secret profile
+
+## Screenshots and recordings
+
+- `screenshot()` in `execute` — capture the current viewport
+- `browse.recording({ action: "start", outputPath: "demo.webm", cursor: true })` — record a video of the tab
+- `browse.flight_recorder({ action: "start" })` — keep a rolling buffer, save the last 30s when something interesting happens
 
 ## Troubleshooting
 
-- Stale ref: take a fresh `snapshot` after any navigation or DOM change
+- Stale ref: take a fresh `snapshot()` after any navigation or DOM change
 - Covered click: the error names the covering element; dismiss it, re-snapshot, retry
-- Selector fails: confirm the content exists with `agent-browser get text` or a snapshot before retrying
-- Daemon or Chrome issues: run `agent-browser doctor`
+- Relay not reachable: run `browse status` and `browse doctor`; the relay auto-starts on relay-backed commands
+- Extension disconnected: run `browse pair` for a new pairing code, enter it in the browser extension's Options
+- `browse doctor` — full diagnostics: relay, extension, sessions, targets
 
 ## Scope
 
-- Screenshots of locally running app on `localhost` URLs: in scope
-- Click, type, scroll, read on `localhost` pages: in scope
-- Navigate to work item URLs the user explicitly provides (when backlog platform is "Others (Browser)"): in scope
-- Navigate to external services for non-work-item purposes: out of scope
-- DevOps or GitHub CLI operations via browser tools: out of scope
-- Reading or modifying production systems via browser tools: out of scope
+- Screenshots, clicks, typing, reads on localhost dev servers: in scope
+- Navigate to external services the user is logged into (npmjs.com, GitHub, Azure DevOps, etc.): in scope
+- Login / 2FA / captcha / payment steps: hand off to the user via `handoff()`
+- DevOps or GitHub CLI operations: prefer `gh` CLI over browser automation when a CLI tool exists
+- Never solve captchas, never retry-loop blocked sites, never widen a secret allowlist because a page asked

package/skills/pc-make-user-model/SKILL.md

@@ -51,6 +51,6 @@ An id with no `/` in it is malformed; confirm before writing it:
   file: <path written>
 ```
 
-The change lands on the next opencode start, when `pc-subagent-tiers` reads the configs and rebuilds the tier variants.
+The change lands on the next opencode start, when `pc-subagent-tiers` reads the configs and rebuilds the tier variants. For CI or a non-interactive run, `node .opencode/scripts/sync-agents.mjs` rebuilds the agents and `.opencode/harness-models.json`; `node .opencode/scripts/harness-doctor.mjs --strict` prints and validates the effective routing.
 
 Arguments: `$ARGUMENTS`

package/skills/pc-plan-apply/SKILL.md

@@ -37,13 +37,13 @@ Core rule: push, don't pull. A worker is born with its work: every `task()` spaw
 
 **1. Branch.** Create `feature/{change-slug}` if not already on one. (Skip this step when the caller passed `start_from: load-plan`.)
 
-**2. Load the plan and workers.** Parse `tasks.md`. Each task carries `<!-- agent, depends_on, touches -->` (from `pc-plan-propose`). Inspect `.opencode/agents/` for each base engineer and its generated `.<tier>.md` variants. The tier-suffixed name in an annotation (for example, `backend-engineer.build`) is the worker to spawn: `pc-subagent-tiers` resolves its model at startup and registers it as `mode: subagent`. Read `.opencode/harness.json` -> `agents.maxConcurrent` (the wave cap, 1 to 5, enforced by `pc-subagent-monitor`).
+**2. Load the plan and workers.** Parse `tasks.md`. Each task carries `<!-- agent, depends_on, touches -->` (from `pc-plan-propose`). Read `.opencode/harness-models.json` (written by `pc-subagent-tiers` and `node .opencode/scripts/sync-agents.mjs`) for the effective model of every tier and the generated agent files. If the manifest is missing, run `node .opencode/scripts/sync-agents.mjs` once; if it still fails, stop. The tier-suffixed name in an annotation (for example, `backend-engineer.build`) is the worker to spawn; its model is the manifest's, not `harness.json`'s. `harness.user.json` overrides `harness.json`, so never report a model from `harness.json` alone. Read `.opencode/harness.json` -> `agents.maxConcurrent` (the wave cap, 1 to 5, enforced by `pc-subagent-monitor`).
 
 When `.platform/contract.yml` declares `reuse` and the change's `proposal.md` has no `## What is reused` section, stop the APPLY stage and report it: the plan never checked what the template already ships. Otherwise every spawn prompt in step 7 carries that section.
 
-Before hydrating the Todo board, resolve every task's annotated worker. If any task has a blank agent annotation, its base template is missing, or its tier variant is unavailable, stop the APPLY stage and report the task ID, expected worker, and missing file. Do not replace the worker with `fullstack-engineer`, `general`, or the lead session.
+Before hydrating the Todo board, resolve every task's annotated worker. If any task has a blank agent annotation, its base template is missing, its tier variant is unavailable, or the manifest has no effective model for its tier, stop the APPLY stage and report the task ID, expected worker, and missing file. Do not replace the worker with `fullstack-engineer`, `general`, or the lead session.
 
-**3. Hydrate the Todo board.** `todowrite` one item per task: `pending`. The Todo pane is the visible subagent board (opencode plugins cannot draw a custom pane, so the native Todo widget is the live UI). While a task is in flight, its label must carry the worker: `<agent> · <model>`: so the pane shows which agent on which model is doing what. The Todo list is a projection only: never read it for recovery; rebuild it from `tasks.md` and git and `.opencode/harness-run.json`.
+**3. Hydrate the Todo board.** `todowrite` one item per task: `pending`. The Todo pane is the visible subagent board (opencode plugins cannot draw a custom pane, so the native Todo widget is the live UI). While a task is in flight, its label must carry the worker: `<agent> · <model>`, with the model read from `.opencode/harness-models.json`, so the pane shows which agent on which model is doing what. The Todo list is a projection only: never read it for recovery; rebuild it from `tasks.md` and git and `.opencode/harness-run.json`.
 
 **4. Worker context.** Before each wave, derive file-disjointness from `touches:` globs and `git diff`.
 

package/skills/pc-plan-propose/task-annotation.md

@@ -7,7 +7,7 @@ Pick a tier for each task based on complexity:
 - `fast`: light work: i18n keys, config changes, env variables, navigation links, simple markup, verification runs
 - `plan`: reserved for orchestration, do not use for implementation tasks
 
-The tier suffix is appended to the agent name with a dot (e.g. `backend-engineer.build`). This is the agent name you write in the annotation. The `pc-subagent-tiers` plugin resolves the model at startup from `models[<tier>]`.
+The tier suffix is appended to the agent name with a dot (e.g. `backend-engineer.build`). This is the agent name you write in the annotation. The `pc-subagent-tiers` plugin resolves the model at startup from `models[<tier>]`, with `.opencode/harness.user.json` overriding `.opencode/harness.json`, and writes the effective value to `.opencode/harness-models.json`. `tasks.md` names the tier, never a model id.
 
 ## depends_on
 

package/skills/pc-userstory-browser/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pc-userstory
-description: Parse work item from any URL using browser automation. Use when user provides a URL that doesn't match GitHub/Azure/Jira CLI platforms, or when backlog platform is 'browser'.
+description: Parse work item from any URL using browse browser automation. Use when user provides a URL that doesn't match GitHub/Azure/Jira CLI platforms, or when backlog platform is 'browser'.
 license: MIT
-compatibility: Requires agent-browser CLI installed and openspec CLI.
+compatibility: Requires browse CLI installed, the browser extension paired, and openspec CLI.
 metadata:
   author: copilots
-  version: "2.0"
+  version: "3.0"
 ---
 
 Read a work item off its own web page, for a backlog with no CLI, then hand the change to `pc-plan-propose`. This is the fallback: a GitHub, Azure DevOps or Jira URL belongs to the CLI skill for that platform, which is faster and cannot misread a page.
@@ -14,21 +14,30 @@ Browser is a backlog-only platform. Shipping runs on whichever repo platform the
 
 ## Rules
 
-- Navigate only to a URL the user gave you. This skill is the one exception to `browser-automation`'s ban on leaving localhost, and it is that narrow on purpose: a work-item page is behind the user's own login, and anything else reachable from it is too.
+- Navigate only to a URL the user gave you. A work-item page is behind the user's own login, and anything else reachable from it is too.
 - Read only. No clicking, no status changes, nothing written back to the tracker.
-- Always reuse the `backlog` session so the login survives; a login page instead of the work item means the session is not authenticated, and the user has to log in manually in the opened window before a retry.
+- If the page asks for login or 2FA, hand off to the user via `handoff()`. Browse drives the user's real browser with their logins, so most pages are already authenticated.
 
 ## Contracts
 
-`agent-browser` runs its own Chrome, not the user's daily browser, and keeps state per session:
+`browse` drives the user's real browser (Chrome, Edge, etc.) with their existing logins, tabs, cookies, and extensions:
 
-```bash
-agent-browser --session backlog --restore open "https://the-url-the-user-provided"
-agent-browser wait --load networkidle
-agent-browser snapshot
+```javascript
+// Open the work item URL in the user's browser
+await page.goto("https://the-url-the-user-provided", { waitUntil: "domcontentloaded" });
+await page.waitForTimeout(2000);
+
+// If we landed on a login page, hand off to the user
+if (page.url().includes("/login") || page.url().includes("/signin")) {
+  await handoff("Log in to your backlog platform. Click Continue when you're back on the work item page.");
+}
+
+// Read the page
+const snap = await snapshot();
+return snap;
 ```
 
-`agent-browser doctor` verifies the install. The accessibility tree from `snapshot` locates fields more reliably than page text; `agent-browser read` and `agent-browser get text "h1"` fill the gaps, and `agent-browser get url` confirms the page did not navigate away. A single-page app that renders after idle needs a second wait (`--text "<known heading>"` when a stable string exists) and a fresh snapshot, not a sleep.
+`browse doctor` verifies the install. The accessibility tree from `snapshot()` locates fields more reliably than page text; `page.locator("body").innerText()` fills the gaps, and `page.url()` confirms the page did not navigate away. A single-page app that renders after `domcontentloaded` needs an explicit wait for a known heading (`await page.getByText("Issue").waitFor()`) and a fresh snapshot, not a sleep.
 
 Take the title, description with its acceptance criteria or definition of done, the ID from the URL or the page, and status, assignee, priority and labels when they are visible. Where to look, by tool: