---
created: 2026-05-06
gap: G02
order: 3
severity: P0
category: observation
estimate: M
issue: "https://github.com/lidge-jun/agbrowse/issues/59"
depends_on: ['G10']
---

# G02 — observe()-style action candidate API (vs Stagehand, AgentQL)

> Severity **P0** · Category `observation` · Estimate **M** ·
> Tracking issue [#59](https://github.com/lidge-jun/agbrowse/issues/59) · Depends on **G10**

## GPT Pro evidence

Evidence (competitor side): URL: https://docs.stagehand.dev/v3/basics/observe — quote: “discovers actionable elements.” Stagehand says observe() returns structured actions that can be validated before execution. 
Stagehand

Evidence (agbrowse side): README.md:446-463 lists low-level observe/act commands; web-ai/browser-tool-schema.mjs:37-56 exposes browser_snapshot and browser_click_ref, not a candidate-action API. 
GitHub
+1

Why this matters: A planner needs more than a raw snapshot; it needs ranked possible actions with semantics, method, arguments, and risk flags. This is the gap between “browser remote” and “agent-ready observation.”
Proposed scope, respecting forbidden list:

web-ai/observe-actions.mjs — build candidate actions from accessibility snapshot, visible text, forms, and element roles.

web-ai/target-resolver.mjs — expose resolver confidence, matched signals, and failure reasons as structured metadata.

web-ai/action-intent.mjs — map natural-language intents to candidate action verbs and required fields.

skills/browser/browser.mjs — add observe-actions "<instruction>" --json.

structure/commands.md — document ActionCandidate[] schema with refs scoped to latest snapshot.

structure/release_gates.md — add gate:observe-actions-fixtures.
Test surface: test/unit + test/eval.
cli-jaw mirror impact: parity required, because target resolver/action-intent are mirrored surfaces.
Acceptance gate: keep gate:truth-table-fresh; add gate:observe-actions-fixtures.
Estimate: M, 2–3 days.

## Diff-level work breakdown

> Fill in concrete diffs (NEW / MODIFY / DELETE with file:line) once this gap
> reaches the active sprint. Until then, the bullets in **Proposed scope**
> above are the agreed shape; do not implement before the depending gaps
> (G10) ship and `gate:all` stays green.

### NEW files
- _to be filled before implementation_

### MODIFY
- _to be filled before implementation_

### DELETE
- _to be filled before implementation_

## Tests
- `test/unit/...` — _list test files once written_

## Truth-table update
- `structure/CAPABILITY_TRUTH_TABLE.md` — add row or update status when this
  gap reaches `ready` in agbrowse.
- `cli-jaw/structure/CAPABILITY_TRUTH_TABLE.md` — mirror entry per the
  `cli-jaw mirror impact` line above.

## Release gates touched
- Existing: `gate:typecheck`, `gate:tests`, `gate:truth-table-fresh`,
  `gate:mcp-scope-frozen`, `gate:no-experimental-in-readme-ready-section`.
- Added by this gap: see **Acceptance gate** in the GPT Pro evidence block.