browser-oracle

> STOP. READ THIS ENTIRE SKILL.MD BEFORE CALLING ANY ENDPOINT. # browser-oracle Small skill for **where** browser oracles point — not for running reviews. Use **`$ask webgpt`** (or `$surf`) for the actual submit after resolve. ## Two stores | Store | Path | In git? | |-------|------|---------| | Tab id + URL | `~/.pi/webgpt-projects/<name>.json` | No | | Directory → project name | `.ask/browser-oracles.yaml` | Yes | ## Agent workflow ```bash cd skills/browser-oracle # 1. Resolve from cwd or a named directory (walk-up like python-dotenv) ./run.sh resolve --from /path/to/work --json # 2. If binding missing, human binds once ./run.sh bind oc-subagent-personas --tab-id <ID> --url <URL> --manual # 3. Register directory mapping (committed yaml) ./run.sh register --at agents --default oc-subagent-personas ./run.sh register --at agents --relative-path mathematics oc-subagent-personas # 4. Preflight ./run.sh doctor --from /path/to/work --json # 5. Ask uses project only cd ../ask ./run.sh ask webgpt "Review …" --webgpt-project oc-subagent-personas --once ``` **Do not** pass `--webgpt-tab-id` on every round when a project binding exists. ## Required lookup behavior when `$browser-oracle` is mentioned When a human mentions `$browser-oracle`, `browser-oracle`, WebGPT binding, reviewer tab, tab id, desktop, or "where should WebGPT look", the agent must first resolve from the relevant project or skill directory before asking the human for tab/url/desktop again. Use this order: 1. If the task is inside a project repo, resolve from that repo root: `./run.sh resolve --from /path/to/project --backend webgpt --json`. 2. If the task is about a skill or subagent, resolve from that skill/subagent directory first: `./run.sh resolve --from /path/to/skill-or-agent --backend webgpt --json`. 3. If the nearest `.ask/browser-oracles.yaml` resolves a project, use the machine-local binding under `~/.pi/<backend>-projects/<project>.json`. 4. Only ask the human for tab id, URL, or desktop when resolve/doctor reports `no_registry`, `no_project_resolved`, `missing_live_tab`, or `url_mismatch`. Project repositories and skills should therefore commit a nearest registry file: ```text <project-or-skill>/.ask/browser-oracles.yaml ``` with at least: ```yaml version: 1 webgpt: default: <project-name> ``` It is acceptable to keep human-readable tab id, URL, and desktop notes as YAML comments in that registry when the human explicitly asks for them, but the executable binding remains `~/.pi/webgpt-projects/<project-name>.json`. ## Skill integration contract Every reviewable skill should connect to WebGPT through this two-part binding: 1. Commit a directory registry inside the skill: ```text <skill>/.ask/browser-oracles.yaml ``` ```yaml version: 1 webgpt: default: <skill-project-name> ``` 2. Bind the project name once to the live WebGPT tab and URL: ```bash skills/browser-oracle/run.sh bind <skill-project-name> \ --backend webgpt \ --tab-id <tab-id> \ --url '<chatgpt-project-conversation-url>' \ --manual \ --json ``` Then preflight from the skill directory: ```bash skills/browser-oracle/run.sh resolve --from skills/<skill-name> --backend webgpt --json skills/browser-oracle/run.sh doctor --from skills/<skill-name> --backend webgpt --json ``` This is what lets `$webgpt-review`, `$ask webgpt`, and `$surf webgpt.submit` connect a skill to its browser reviewer without hardcoded tab ids in prompts, README files, or project-agent memory. ## Walk-up rule From `--from` (default `.`), walk **child → parent** for `.ask/browser-oracles.yaml`. **Nearest file wins.** See `references/browser-oracles.schema.yml`. Within a registry root, `by_relative_path` keys are relative to that root (e.g. `mathematics` under `agents/`). ## Full CLI reference ### `resolve` ```bash ./run.sh resolve [--from PATH] [--backend webgpt|webgemini|webkimi|webclaude|cursor-browser] [--project NAME] [--lane LANE] [--json] ``` Walk up from `--from` (default `.`), map directory → project, load `~/.pi/*-projects/<project>.json`. ### `bind` ```bash ./run.sh bind NAME [--backend webgpt] --tab-id ID [--url URL] [--view-id ID] [--manual|--auto] [--json] ``` Persist tab/view id + URL under `~/.pi/<backend>-projects/`. Use `--manual` for long-lived reviewer tabs. ### `verify` ```bash ./run.sh verify NAME [--backend webgpt] [--json] ``` Check binding file exists and tab is still open (Chrome backends via `surf tab.list`). ### `list` ```bash ./run.sh list [--backend webgpt] [--verify] [--json] ``` ### `reconcile` ```bash ./run.sh reconcile [--backend webgpt] [--project NAME] [--prune-missing] [--json] ``` Scan stored bindings against live `surf tab.list --json --with-kde` inventory. Reports `ready`, `missing_live_tab`, `url_mismatch`, `live_scan_incomplete`, or `scan_failed` per binding. `--prune-missing` deletes only binding files whose stored Chrome tab id no longer exists after a complete live scan; it does not close browser tabs. On KDE Plasma, missing OS/window workspace metadata is a transport ambiguity, so stale bindings are preserved fail-closed. Successful verification refreshes stored Chrome window/KDE observation fields so callers can remember `chrome_window_id`, `kde_desktop_index`, `kde_x11_window_id`, and the observation source/confidence. ### `open-bind` ```bash ./run.sh open-bind NAME [--backend webgpt] --url URL [--window] [--manual|--auto] [--json] ``` Open a fresh reviewer surface and persist the new tab id as the project binding. For **webgpt**, the default is an isolated Chrome **window** on KDE Desktop 2 (`--window`, overridable with `BROWSER_ORACLE_OPEN_BIND_WINDOW=0`). That keeps one project = one single-tab reviewer window instead of polluting the main Chrome window on Desktop 1. The window opens unfocused by default (`BROWSER_ORACLE_OPEN_BIND_UNFOCUSED=1`) and the tab title is labeled `<project> · WebGPT reviewer` for humans. `open-bind` must leave the bound tab on the requested reviewer URL, not on a Surf placeholder page. If `window.new` returns an "Agent Window" placeholder, browser-oracle owns the immediate `surf go <url> --tab-id <id>` recovery before saving the binding. Project agents should not hand-navigate reviewer windows after `open-bind`. Use plain `tab.new` only when you explicitly pass `--no-window` semantics via `BROWSER_ORACLE_OPEN_BIND_WINDOW=0` for webgpt, or for non-webgpt backends. ### `register` ```bash ./run.sh register PROJECT [--at DIR] [--backend webgpt] [--default] [--relative-path SUB] [--json] ``` Write `.ask/browser-oracles.yaml` at registry root (`--at`). `--default` sets fallback project; `--relative-path` maps a subpath. ### `show-registry` / `walk-up` ```bash ./run.sh show-registry [--from PATH] [--json] ./run.sh walk-up [--from PATH] [--json] ``` ### `doctor` ```bash ./run.sh doctor [--from PATH] [--backend webgpt] [--project NAME] [--json] ``` Resolve + verify + readiness (`ready` | `needs_attention`). ### `unbind` ```bash ./run.sh unbind NAME [--backend webgpt] ``` ## Flag parity with `/ask` and `/surf` | Intent | `$browser-oracle` | `$ask webgpt` | `$surf webgpt.submit` | |--------|-------------------|---------------|------------------------| | Walk-up root | `--from PATH` | `--browser-oracle-from PATH` | `--browser-oracle-from PATH` | | Explicit project | `--project NAME` (resolve only) | `--webgpt-project NAME` | `--project NAME` | | Tab id | via `bind` → binding file | `--webgpt-tab-id ID` | `--tab-id ID` | | Conversation URL | `--url` on `bind`; resolve returns it | `--webgpt-url URL` | `--url URL` (+ `--expect-url`) | | Fresh reviewer window/tab | `open-bind NAME --url URL` (webgpt defaults to `--window`) | `--webgpt-create-tab` / auto-provision on first `--webgpt-project` | `--create-tab` (project-aware: open-bind `--window`) | | Stored tab scan | `reconcile --project NAME` | compose before review | automatic before walked-up submit | | Delete stale id | `reconcile --prune-missing` | compose before review | `SURF_BROWSER_ORACLE_PRUNE_MISSING=1` | | Single round | — | `--once` | — | ## Commands (quick) ```bash ./run.sh resolve [--from PATH] [--backend webgpt] [--project NAME] [--lane LANE] [--json] ./run.sh bind NAME [--backend webgpt] --tab-id ID [--url URL] [--view-id ID] [--manual] ./run.sh verify NAME [--backend webgpt] [--json] ./run.sh list [--backend webgpt] [--verify] [--json] ./run.sh reconcile [--backend webgpt] [--project NAME] [--prune-missing] [--json] ./run.sh open-bind NAME [--backend webgpt] --url URL [--manual] [--json] ./run.sh register [--at DIR] [--backend webgpt] [--default] [--relative-path SUB] PROJECT ./run.sh show-registry [--from PATH] [--json] ./run.sh walk-up [--from PATH] [--json] ./run.sh doctor [--from PATH] [--backend webgpt] [--project NAME] [--json] ./run.sh unbind NAME [--backend webgpt] ``` ## Human prompts | Intent | Say | |--------|-----| | Bind tab once | `$browser-oracle bind <project> tab <id> url <url> manual` | | Map a directory | `$browser-oracle register agents default <project>` | | Map subpath | `$browser-oracle register … relative-path mathematics <project>` | | Use from here | `$ask webgpt …` or `$surf webgpt.submit …` from that directory — walk-up fills project/tab/url automatically | | Override project | `$ask webgpt … --webgpt-project <name>` or `--browser-oracle-from <dir>` | | Inspect binding | `$browser-oracle doctor --from <dir>` or `resolve --json` | ## Backends | Backend | Binding field | Store | |---------|---------------|-------| | `webgpt` | `tab_id` | `~/.pi/webgpt-projects/` | | `webgemini` | `tab_id` | `~/.pi/webgemini-projects/` | | `webkimi` | `tab_id` | `~/.pi/webkimi-projects/` | | `webclaude` | `tab_id` | `~/.pi/webclaude-projects/` |