browser-oracle

name	browser-oracle
description	Persistent browser-oracle tab bindings and directory walk-up registry for WebGPT, Cursor Browser, Gemini, Kimi, and Claude. Binds tab id / viewId + URL once under ~/.pi; maps directories to project names via .ask/browser-oracles.yaml discovered like python-dotenv parent walk-up.
triggers	["browser oracle","browser-oracle","bind webgpt tab","remember webgpt tab","webgpt project binding","which webgpt tab","resolve browser oracle","register browser oracle for this directory","webgpt tab for this directory","browser oracle doctor"]
provides	["browser-oracle-binding","browser-oracle-registry"]
composes	["surf"]
complies	["best-practices-skills","best-practices-python"]
taxonomy	["orchestration","validation"]

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

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:

<project-or-skill>/.ask/browser-oracles.yaml

with at least:

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:

   <skill>/.ask/browser-oracles.yaml
   

   version: 1
   webgpt:
     default: <skill-project-name>
   

2. Bind the project name once to the live WebGPT tab and URL:

   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:

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

./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

./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

./run.sh verify NAME [--backend webgpt] [--json]

Check binding file exists and tab is still open (Chrome backends via surf tab.list).

list

./run.sh list [--backend webgpt] [--verify] [--json]

reconcile

./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

./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

./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

./run.sh show-registry [--from PATH] [--json]
./run.sh walk-up [--from PATH] [--json]

doctor

./run.sh doctor [--from PATH] [--backend webgpt] [--project NAME] [--json]

Resolve + verify + readiness (ready | needs_attention).

unbind

./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)

./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/
cursor-browser	view_id	~/.pi/cursor-browser-projects/

Boundaries

• browser-oracle: bind, verify, walk-up registry, doctor.
• /ask: oracle orchestration, artifacts, review loops.
• /surf: transport + sentinel proof only.

Legacy ./run.sh webgpt-project … in /ask remains; prefer browser-oracle for new work.

Proof

• Resolve/doctor JSON with project, registry_path, tab_id, readiness.
• Reconcile JSON includes KDE workspace metadata when available: live_window_id, live_kde_desktop_index, and live_scan_context.
• Binding JSON persists last observed desktop/window metadata after verify.
• Ask artifacts for actual WebGPT rounds (not chat paraphrase).

Details: README.md, docs/PROJECT_KNOWLEDGE.md, references/browser-oracles.schema.yml.

Composition with /ask and /surf

$browser-oracle is the binding + registry layer. Callers compose it; they do not reimplement walk-up or ~/.pi/*-projects/ IO.

Skill	Role	How it composes
/ask	Orchestration	Before call_webgpt, resolves project/tab/url from cwd (or --browser-oracle-from) via browser_oracle_client.py → ./run.sh resolve --json. Records browser_oracle_resolved in run events.
/surf	Transport	webgpt.submit accepts --project and --browser-oracle-from; shells to the same resolve --json and fills --tab-id / --url / --expect-url.

Zero-flag workflow (from a registered directory):

cd agents/mathematics
$ask webgpt "review this bundle" --once          # walk-up → oc-subagent-personas + tab 837352004
$surf webgpt.submit --input REQ.md --output RESP.md --no-activate  # same walk-up from cwd

Explicit overrides still win: --webgpt-tab-id, --webgpt-url, --webgpt-project, --webgpt-create-tab.