High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: the shipped agent skills still describe the pre-fix navigating-click contract (PIN-283)
Luigi Agosti77dcd5eb8ba2
diff --git a/internal/mcp/skill_click_contract_test.go b/internal/mcp/skill_click_contract_test.gonew file mode 100644index 00000000..d3066688--- /dev/null+++ b/internal/mcp/skill_click_contract_test.go@@ -0,0 +1,140 @@+package mcp++import (+ "encoding/json"+ "os"+ "path/filepath"+ "regexp"+ "strings"+ "testing"+)++const clickDocPath = "docs/reference/click.md"++// clickContractSkills are the two shipped skills that describe the click contract.+// They are the surface agents actually read, and they drifted from the docs for a+// release because only the docs were ever listed in a contract-changing card's+// footprint. This guard is the answer to that: the skills are checked AGAINST the+// docs, so the next contract change reds here instead of shipping stale guidance.+var clickContractSkills = []string{"skills/pinchtab/SKILL.md", "skills/pinchtab-mcp/SKILL.md"}++// clickContractBanned are statements the contract no longer produces. An agent+// taught to handle a 409 from a click is taught a branch that can never be taken.+var clickContractBanned = []string{"409", "navigation_changed", "unexpected page navigation"}++func readRepoFile(t *testing.T, rel string) string {+ t.Helper()+ body, err := os.ReadFile(filepath.Join("..", "..", rel))+ if err != nil {+ t.Fatalf("read %s: %v", rel, err)+ }+ return string(body)+}++// navigationSignalKeys reads the wire names of the navigation outcome from their+// DECLARATION SITE in internal/bridge — the one place that decides what a navigating+// action reports. Reading them rather than listing them here is what makes this a+// drift guard with no list to remember: a signal added to the contract must reach the+// docs and both skills or this reds, and one renamed cannot silently stop being+// checked.+func navigationSignalKeys(t *testing.T) []string {+ t.Helper()++ src := readRepoFile(t, "internal/bridge/action_request.go")+ pattern := regexp.MustCompile(`(?m)^\s*Result[A-Za-z]+\s*=\s*"([^"]+)"`)+ matches := pattern.FindAllStringSubmatch(src, -1)++ var keys []string+ for _, m := range matches {+ keys = append(keys, m[1])+ }+ if len(keys) < 4 {+ t.Fatalf("found %d navigation signal constants (%v) in internal/bridge/action_request.go; the contract publishes at least navigated, url, previousUrl and refsStale, so this guard is reading the wrong place and would pass vacuously", len(keys), keys)+ }+ return keys+}++// documentedClickResult parses the JSON example in docs/reference/click.md. A+// documented example is the one artefact no other test covers, so it is driven+// through a parser here rather than trusted to look right.+func documentedClickResult(t *testing.T, doc string) map[string]any {+ t.Helper()++ const fence = "```json"+ start := strings.Index(doc, fence)+ if start < 0 {+ t.Fatalf("%s has no json example of a navigating click; this guard reads the contract from that block and would pass vacuously without it", clickDocPath)+ }+ block := doc[start+len(fence):]+ end := strings.Index(block, "```")+ if end < 0 {+ t.Fatalf("%s has an unterminated json block", clickDocPath)+ }++ var payload struct {+ Result map[string]any `json:"result"`+ }+ if err := json.Unmarshal([]byte(block[:end]), &payload); err != nil {+ t.Fatalf("the json example in %s does not parse, so the contract cannot be read from it: %v", clickDocPath, err)+ }+ return payload.Result+}++// The skills must name every signal the documented response carries. An agent that+// cannot learn from the skill that the answer is already in the response either+// re-snapshots blindly or keeps using dead refs after a click it did not know+// navigated.+func TestTheSkillsNameEverySignalTheDocumentedClickResultCarries(t *testing.T) {+ keys := navigationSignalKeys(t)++ // The docs first: they are the description this guard measures the skills+ // against, so a signal missing from them would let the skills omit it too.+ documented := documentedClickResult(t, readRepoFile(t, clickDocPath))+ for _, key := range keys {+ if _, ok := documented[key]; !ok {+ t.Errorf("%s does not show %q in its navigating-click example, which internal/bridge reports", clickDocPath, key)+ }+ }++ for _, skill := range clickContractSkills {+ body := readRepoFile(t, skill)+ for _, key := range keys {+ if !strings.Contains(body, key) {+ t.Errorf("%s never mentions %q, which a navigating click returns — the skill is the surface an agent reads, so a signal missing here is a signal it will not use",+ skill, key)+ }+ }+ }+}++// The status the contract no longer produces, and the framing the docs explicitly+// correct. Both are checked against the docs rather than against a remembered rule:+// the banned strings must be absent from the docs too, so this cannot outlive the+// contract it guards.+func TestTheSkillsDoNotTeachTheContractThatWasReplaced(t *testing.T) {+ doc := readRepoFile(t, clickDocPath)++ for _, banned := range clickContractBanned {+ if strings.Contains(doc, banned) {+ t.Fatalf("%s itself contains %q, so this ban no longer describes the contract — re-derive it before trusting the skill assertions below", clickDocPath, banned)+ }+ }++ const correction = "not permission to navigate"+ if !strings.Contains(doc, correction) {+ t.Fatalf("%s no longer states that the wait flag is %q; this guard mirrors the docs, so it cannot pin a correction the docs have dropped", clickDocPath, correction)+ }++ for _, skill := range clickContractSkills {+ body := readRepoFile(t, skill)+ for _, banned := range clickContractBanned {+ if strings.Contains(body, banned) {+ t.Errorf("%s still mentions %q; the contract no longer produces it, so this teaches a branch that can never be taken", skill, banned)+ }+ }+ if !strings.Contains(body, correction) {+ t.Errorf("%s does not say the wait flag is %q — without it the skill reads as 'add the flag because the click navigates', which is the inverted framing %s exists to correct",+ skill, correction, clickDocPath)+ }+ }+}diff --git a/internal/mcp/testdata/preamble_budget.json b/internal/mcp/testdata/preamble_budget.jsonindex f852a1ca..f97974f1 100644--- a/internal/mcp/testdata/preamble_budget.json+++ b/internal/mcp/testdata/preamble_budget.json@@ -9,15 +9,15 @@{"surface": "skills/pinchtab-mcp/SKILL.md","minBytes": 6789,- "maxBytes": 13579,- "takenOn": "2026-08-22",- "commit": "15af50c1"+ "maxBytes": 14109,+ "takenOn": "2026-09-03",+ "commit": "a0884888"},{"surface": "skills/pinchtab/SKILL.md","minBytes": 10176,- "maxBytes": 20356,- "takenOn": "2026-08-22",- "commit": "22eb3209"+ "maxBytes": 20688,+ "takenOn": "2026-09-03",+ "commit": "a0884888"}]diff --git a/plugins/grok/skills/pinchtab-mcp/SKILL.md b/plugins/grok/skills/pinchtab-mcp/SKILL.mdindex f50c07fb..4af81551 100644--- a/plugins/grok/skills/pinchtab-mcp/SKILL.md+++ b/plugins/grok/skills/pinchtab-mcp/SKILL.md@@ -146,7 +146,8 @@ pinchtab_click(selector="e5")```- Use refs from snapshot (e.g., `e5`).-- For links/buttons that navigate: add `waitNav=true`.+- A click that navigates **succeeds** (no error to handle): the result adds `navigated`, `url` (landed), `previousUrl`, `refsStale` — never guess whether your refs survived. A `#fragment` jump is not a navigation; refs survive.+- `waitNav=true` is not permission to navigate — it *waits* for the navigation to settle, for when the next step needs the new page loaded. Fields above are reported whichever form you use.- To save a round-trip: add `snap=true` to get a snapshot after the click.### Fill input@@ -345,7 +346,7 @@ For these, use the pinchtab CLI or HTTP API directly.## Element Ref Best Practices-1. **Re-snapshot after navigation; a ref survives a change of filter, selector or depth.** Always re-snapshot after `pinchtab_navigate` or `pinchtab_click(waitNav=true)` — a new document expires every ref. But within one page a ref denotes a node, so carrying `e5` from a full snapshot into an `interactive`/`selector`/`depth` read is safe and returns the same node (filtered views are sparse — `e0, e1, e6`). The tools track each snapshot's vocabulary token, so a truly stale ref surfaces as a `vocab_superseded` refusal instead of a wrong-element click.+1. **Re-snapshot when the result says your refs are dead; a ref survives a change of filter, selector or depth.** Re-snapshot after `pinchtab_navigate` and after any result carrying `refsStale` — a new document expires every ref. Key on `refsStale`, never on whether you passed `waitNav`: the page decides whether a click navigates, and the result says which happened. But within one page a ref denotes a node, so carrying `e5` from a full snapshot into an `interactive`/`selector`/`depth` read is safe and returns the same node (filtered views are sparse — `e0, e1, e6`). The tools track each snapshot's vocabulary token, so a truly stale ref surfaces as a `vocab_superseded` refusal instead of a wrong-element click.2. **Use `diff=true` after interactions.** Shows only changed elements, saving tokens.3. **Prefer refs over CSS selectors.** Refs resolve by backend node IDs, more reliable than CSS.4. **Refs work across iframes.** Same-origin iframe content is flattened into the main tree — refs are clickable without frame hops.diff --git a/plugins/grok/skills/pinchtab/SKILL.md b/plugins/grok/skills/pinchtab/SKILL.mdindex e2002da6..a230d46a 100644--- a/plugins/grok/skills/pinchtab/SKILL.md+++ b/plugins/grok/skills/pinchtab/SKILL.md@@ -216,7 +216,8 @@ Rules:- Click behavior: omit `--mode` for the normal click path, use `click --mode dom` for `element.click()`, or `click --mode dispatch` for synthetic click events.- Treat `click --mode dom` and `click --mode dispatch` as broad low-level escape hatches; bypassing occlusion is the common case.- `click --mode ...` and `click --humanize` are mutually exclusive.-- `click --wait-nav` when a click navigates. May return `{"success":true}` or `Error 409: unexpected page navigation` — treat 409 as success and verify with fresh `snap`/`text`.+- A click that navigates **succeeds** (no error to handle): prints `OK navigated <url>`; JSON adds `navigated`, `url` (landed), `previousUrl`, `refsStale`. `refsStale` means every ref from your last snapshot is dead — re-snapshot first (`click <ref> --snap` does both). A `#fragment` jump is not a navigation; refs survive.+- `--wait-nav` is not permission to navigate — it *waits* for the navigation to settle, for when the next step needs the new page loaded. Fields above are reported whichever form you use.- `--dismiss-banners` on `nav`/`back`/`forward`/`reload` (and on `click --wait-nav`) runs a best-effort pass that clicks a visible Accept all / Got it / OK / Close / Dismiss button, or removes obvious cookie/consent/dialog/overlay containers. Use when a fresh page-load shows a modal that blocks interaction (typical symptom: `Error 500: action click: element is occluded`). Heuristic — can misfire on pages that label legitimate UI as `overlay` or `modal`; not a substitute for an explicit selector when one is known.- Use low-level `mouse` only for drag handles, canvas widgets, or exact pointer sequences.- JS dialogs: `--dialog-action accept|dismiss`, `--dialog-text` for `prompt()` responses.diff --git a/skills/pinchtab-mcp/SKILL.md b/skills/pinchtab-mcp/SKILL.mdindex f50c07fb..4af81551 100644--- a/skills/pinchtab-mcp/SKILL.md+++ b/skills/pinchtab-mcp/SKILL.md@@ -146,7 +146,8 @@ pinchtab_click(selector="e5")```- Use refs from snapshot (e.g., `e5`).-- For links/buttons that navigate: add `waitNav=true`.+- A click that navigates **succeeds** (no error to handle): the result adds `navigated`, `url` (landed), `previousUrl`, `refsStale` — never guess whether your refs survived. A `#fragment` jump is not a navigation; refs survive.+- `waitNav=true` is not permission to navigate — it *waits* for the navigation to settle, for when the next step needs the new page loaded. Fields above are reported whichever form you use.- To save a round-trip: add `snap=true` to get a snapshot after the click.### Fill input@@ -345,7 +346,7 @@ For these, use the pinchtab CLI or HTTP API directly.## Element Ref Best Practices-1. **Re-snapshot after navigation; a ref survives a change of filter, selector or depth.** Always re-snapshot after `pinchtab_navigate` or `pinchtab_click(waitNav=true)` — a new document expires every ref. But within one page a ref denotes a node, so carrying `e5` from a full snapshot into an `interactive`/`selector`/`depth` read is safe and returns the same node (filtered views are sparse — `e0, e1, e6`). The tools track each snapshot's vocabulary token, so a truly stale ref surfaces as a `vocab_superseded` refusal instead of a wrong-element click.+1. **Re-snapshot when the result says your refs are dead; a ref survives a change of filter, selector or depth.** Re-snapshot after `pinchtab_navigate` and after any result carrying `refsStale` — a new document expires every ref. Key on `refsStale`, never on whether you passed `waitNav`: the page decides whether a click navigates, and the result says which happened. But within one page a ref denotes a node, so carrying `e5` from a full snapshot into an `interactive`/`selector`/`depth` read is safe and returns the same node (filtered views are sparse — `e0, e1, e6`). The tools track each snapshot's vocabulary token, so a truly stale ref surfaces as a `vocab_superseded` refusal instead of a wrong-element click.2. **Use `diff=true` after interactions.** Shows only changed elements, saving tokens.3. **Prefer refs over CSS selectors.** Refs resolve by backend node IDs, more reliable than CSS.4. **Refs work across iframes.** Same-origin iframe content is flattened into the main tree — refs are clickable without frame hops.diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex e2002da6..a230d46a 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -216,7 +216,8 @@ Rules:- Click behavior: omit `--mode` for the normal click path, use `click --mode dom` for `element.click()`, or `click --mode dispatch` for synthetic click events.- Treat `click --mode dom` and `click --mode dispatch` as broad low-level escape hatches; bypassing occlusion is the common case.- `click --mode ...` and `click --humanize` are mutually exclusive.-- `click --wait-nav` when a click navigates. May return `{"success":true}` or `Error 409: unexpected page navigation` — treat 409 as success and verify with fresh `snap`/`text`.+- A click that navigates **succeeds** (no error to handle): prints `OK navigated <url>`; JSON adds `navigated`, `url` (landed), `previousUrl`, `refsStale`. `refsStale` means every ref from your last snapshot is dead — re-snapshot first (`click <ref> --snap` does both). A `#fragment` jump is not a navigation; refs survive.+- `--wait-nav` is not permission to navigate — it *waits* for the navigation to settle, for when the next step needs the new page loaded. Fields above are reported whichever form you use.- `--dismiss-banners` on `nav`/`back`/`forward`/`reload` (and on `click --wait-nav`) runs a best-effort pass that clicks a visible Accept all / Got it / OK / Close / Dismiss button, or removes obvious cookie/consent/dialog/overlay containers. Use when a fresh page-load shows a modal that blocks interaction (typical symptom: `Error 500: action click: element is occluded`). Heuristic — can misfire on pages that label legitimate UI as `overlay` or `modal`; not a substitute for an explicit selector when one is known.- Use low-level `mouse` only for drag handles, canvas widgets, or exact pointer sequences.- JS dialogs: `--dialog-action accept|dismiss`, `--dialog-text` for `prompt()` responses.