Skip to content

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.go
new file mode 100644
index 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.json
index 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.md
index 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.md
index 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.md
index 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.md
index 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.