High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: nodeId is read for all nine action tools but declared on three, so six lose discovery and validation (PIN-144)
Luigi Agostibe0f68c4b604
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.mdindex 864d58c0..7f4fd0d7 100644--- a/docs/reference/mcp-tools.md+++ b/docs/reference/mcp-tools.md@@ -32,19 +32,19 @@ Structured semantic locators are matched by the semantic engine; CSS, XPath, ref## Interaction-All element-action tools accept the unified `selector` and the legacy aliases `ref` (deprecated) and `query` (semantic shorthand).+All element-action tools accept the unified `selector` and the legacy aliases `ref` (deprecated) and `query` (semantic shorthand). Every one of them also accepts `nodeId` (a backend node ID from a snapshot) as an alternative target. Coordinates (`x`/`y`) are accepted only by `pinchtab_click`, `pinchtab_hover` and `pinchtab_scroll` — the other kinds have no coordinate behaviour.| Tool | Key Parameters | Notes || --- | --- | --- || `pinchtab_click` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId`, `dialogAction`, `dialogText`, `waitNav`, `mode`, `snap` | Click element by selector or coordinate; `mode` accepts `dom` or `dispatch` as a broad low-level escape hatch for click delivery; `mode` and `humanize` are mutually exclusive; `dialogAction` handles a dialog opened by the click; `waitNav=true` waits for navigation; `snap=true` returns a snapshot |-| `pinchtab_type` | `selector`, `ref`, `query`, `text` required, `tabId` | Sends key events at the targeted input |-| `pinchtab_press` | `key` required, `tabId` | Press a key such as `Enter` |+| `pinchtab_type` | `selector`, `ref`, `query`, `nodeId`, `text` required, `tabId` | Sends key events at the targeted input; target with `selector` or `nodeId` |+| `pinchtab_press` | `key` required, `nodeId`, `tabId` | Press a key such as `Enter`; `nodeId` focuses that node first, otherwise the key goes to the focused element || `pinchtab_hover` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId` | Hover an element or coordinate || `pinchtab_focus` | `selector`, `ref`, `query`, `tabId`, `nodeId` | Focus element |-| `pinchtab_select` | `selector`, `ref`, `query`, `value` required, `tabId`, `snap` | Select `<option>` by value or visible text |-| `pinchtab_scroll` | `selector`, `ref`, `query`, `pixels`, `deltaX`, `deltaY`, `direction`, `steps`, `x`, `y`, `tabId` | Omit `selector` to scroll the page; element + `pixels` uses wheel semantics; `direction` accepts `up`/`down` |-| `pinchtab_scroll_into_view` | `selector`, `ref`, `query`, `tabId` | Scrolls the target into view and returns geometry for stable follow-up actions |-| `pinchtab_fill` | `selector`, `ref`, `query`, `value` required, `tabId`, `snap` | Direct fill via JS dispatch instead of keystrokes |+| `pinchtab_select` | `selector`, `ref`, `query`, `nodeId`, `value` required, `tabId`, `snap` | Select `<option>` by value or visible text; target with `selector` or `nodeId` |+| `pinchtab_scroll` | `selector`, `ref`, `query`, `nodeId`, `pixels`, `deltaX`, `deltaY`, `direction`, `steps`, `x`, `y`, `tabId` | Omit every target to scroll the page; element + `pixels` uses wheel semantics; `direction` accepts `up`/`down` |+| `pinchtab_scroll_into_view` | `selector`, `ref`, `query`, `nodeId`, `tabId` | Scrolls the target into view and returns geometry for stable follow-up actions; target with `selector` or `nodeId` |+| `pinchtab_fill` | `selector`, `ref`, `query`, `nodeId`, `value` required, `tabId`, `snap` | Direct fill via JS dispatch instead of keystrokes; target with `selector` or `nodeId` |## Keyboarddiff --git a/internal/mcp/argcheck_test.go b/internal/mcp/argcheck_test.goindex 02b0ea1b..4a4a729c 100644--- a/internal/mcp/argcheck_test.go+++ b/internal/mcp/argcheck_test.go@@ -224,10 +224,13 @@ func TestEveryHandlerHasASchemaAndEverySchemaAHandler(t *testing.T) {// see it either — it derives from the schemas, so an undeclared argument keeps the// silent-coercion-drop this package otherwise rejects.//-// Name-level, not per-tool, and deliberately so: a per-tool assertion needs a-// tool-to-handler-source mapping that is declared nowhere and would be brittle-// enough to invite deletion. Name-level needs no mapping and still catches the-// class.+// NAME-LEVEL, not per-tool: an argument passes as soon as ONE tool declares it,+// so this census cannot see an argument read for a kind whose own tool omits it —+// which is how nodeId and x/y were each read for all nine action tools while+// three declared them. TestNoActionToolIsSentATypedArgumentItDoesNotDeclare covers+// that per-tool half behaviourally, for the action family. The two are not one+// check: this one spans every handler in the package and catches a name declared+// nowhere at all; that one is narrower in scope and stricter within it.//// optString is deliberately NOT scanned. A string argument read without a// declaration is undiscoverable but not a correctness hazard: there is no@@ -378,3 +381,92 @@ func TestOnlyPointerToolsDeclareHumanize(t *testing.T) {}}}++// The per-tool half the name-level census above cannot see. A typed argument read+// for a kind whose tool does not declare it is undiscoverable AND unvalidated,+// because validateTypedArgs keys its type map per tool — the name being declared+// somewhere else does not help the tool being called. handleAction reads its+// arguments before switching on kind, so this is where that goes wrong.+//+// Behavioural rather than structural: reachability is observed as an effect on the+// wire (the argument, or anything derived from it, in the outbound body) or as an+// extra upstream request. That needs no tool-to-handler-source mapping and cannot+// go stale as the handler moves code around. Its blind spot is an undeclared read+// with no observable effect at all, which by construction changes nothing.+func TestNoActionToolIsSentATypedArgumentItDoesNotDeclare(t *testing.T) {+ // Arguments the handler only reads as a set; sending one alone proves nothing.+ groups := [][]string{{"x", "y"}}+ grouped := map[string]bool{}+ for _, group := range groups {+ for _, name := range group {+ grouped[name] = true+ }+ }+ for _, tc := range actionToolTargets {+ for name := range schemaArgTypesOnce()[tc.tool] {+ if !grouped[name] {+ groups = append(groups, []string{name})+ grouped[name] = true+ }+ }+ }++ // The declared type of each name, taken from whichever action tool declares it,+ // so the probe value is one the accessor would actually read.+ typeOf := map[string]string{}+ for _, tc := range actionToolTargets {+ for name, kind := range schemaArgTypesOnce()[tc.tool] {+ typeOf[name] = kind+ }+ }++ const sentinel = 424242.0+ checked := 0+ for _, tc := range actionToolTargets {+ declared := schemaArgTypesOnce()[tc.tool]+ for _, group := range groups {+ kinds := map[string]int{}+ for _, name := range group {+ kinds[declared[name]]+++ }+ if len(kinds) != 1 {+ t.Errorf("%s declares %v inconsistently (%v); the group must be all-or-nothing", tc.tool, group, kinds)+ continue+ }+ if _, isDeclared := declared[group[0]]; isDeclared {+ continue+ }++ args := actionArgs(tc.tool, map[string]any{"selector": "#a"})+ for _, name := range group {+ if typeOf[name] == "boolean" {+ args[name] = true+ continue+ }+ args[name] = sentinel+ }+ checked++++ srv, paths := upstreamRecorder(t)+ result := callTool(t, tc.tool, args, srv)+ if result.IsError {+ t.Fatalf("%s rejected undeclared %v outright (%s); this guard expects it to be ignored", tc.tool, group, resultText(t, result))+ }+ body, _ := resultJSON(t, result)["body"].(map[string]any)+ for field, value := range body {+ if value == sentinel || value == true || field == "hasXY" {+ t.Errorf("pinchtab_%s: %v is reachable for kind %q but the tool does not declare it — outbound body carries %s=%v, so it is undiscoverable and validateTypedArgs cannot type-check it",+ strings.TrimPrefix(tc.tool, "pinchtab_"), group, tc.tool, field, value)+ break+ }+ }+ if len(*paths) != 1 {+ t.Errorf("%s made %v upstream requests with undeclared %v; the argument changed behaviour it cannot be validated for", tc.tool, *paths, group)+ }+ }+ }+ if checked == 0 {+ t.Fatal("no undeclared (tool, argument) pair exercised — this guard is checking nothing")+ }+ t.Logf("checked %d undeclared (tool, typed argument) pairs across %d action tools", checked, len(actionToolTargets))+}diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.goindex 32c4d7e3..aa40594b 100644--- a/internal/mcp/handlers_interaction.go+++ b/internal/mcp/handlers_interaction.go@@ -15,6 +15,12 @@ import (// also has mode, so only click can hit the mutual-exclusion rule.var humanizeAction = map[string]bool{"click": true, "hover": true}+// xyAction is the set of kinds that can be targeted by coordinate, mirroring the+// tools that declare x/y. The bridge honours x/y only for these kinds — the text+// and form actions target by nodeId or selector — so reading it for every kind+// forwarded an inert, undiscoverable and unvalidated pair, hasXY included.+var xyAction = map[string]bool{"click": true, "hover": true, "scroll": true}+func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {payload := map[string]any{"kind": kind}@@ -23,7 +29,10 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequpayload["tabId"] = tabID}- x, y, hasXY := resolveXY(r)+ x, y, hasXY := 0.0, 0.0, false+ if xyAction[kind] {+ x, y, hasXY = resolveXY(r)+ }if hasXY {payload["x"] = xpayload["y"] = y@@ -94,7 +103,7 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ}case "type":- if _, err := resolveSelector(true); err != nil {+ if _, err := resolveSelector(!hasNodeID); err != nil {return mcp.NewToolResultError(err.Error()), nil}text := firstNonEmptyString(r, "text", "value")@@ -111,7 +120,7 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequpayload["key"] = keycase "select":- if _, err := resolveSelector(true); err != nil {+ if _, err := resolveSelector(!hasNodeID); err != nil {return mcp.NewToolResultError(err.Error()), nil}value := firstNonEmptyString(r, "value", "option")@@ -171,12 +180,12 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ}case "scrollintoview":- if _, err := resolveSelector(true); err != nil {+ if _, err := resolveSelector(!hasNodeID); err != nil {return mcp.NewToolResultError(err.Error()), nil}case "fill":- if _, err := resolveSelector(true); err != nil {+ if _, err := resolveSelector(!hasNodeID); err != nil {return mcp.NewToolResultError(err.Error()), nil}value := firstNonEmptyString(r, "value", "text")diff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.goindex 14052b61..84f550df 100644--- a/internal/mcp/handlers_interaction_test.go+++ b/internal/mcp/handlers_interaction_test.go@@ -341,3 +341,128 @@ func TestHandleFocus(t *testing.T) {t.Errorf("expected focus, got %s", text)}}++// actionToolTargets is the per-tool matrix this card decided: every action tool+// declares nodeId, because the bridge honours req.NodeID for every one of the nine+// kinds. requiredArgs are the tool's own non-target requirements, and+// selectorOptionalWithNodeID marks the tools whose MCP layer used to demand a+// selector even though the bridge does not.+var actionToolTargets = []struct {+ tool string+ requiredArgs map[string]any+ selectorOptionalWithNodeID bool+}{+ {tool: "pinchtab_click", selectorOptionalWithNodeID: true},+ {tool: "pinchtab_hover", selectorOptionalWithNodeID: true},+ {tool: "pinchtab_focus", selectorOptionalWithNodeID: true},+ {tool: "pinchtab_type", requiredArgs: map[string]any{"text": "hi"}, selectorOptionalWithNodeID: true},+ {tool: "pinchtab_fill", requiredArgs: map[string]any{"value": "v"}, selectorOptionalWithNodeID: true},+ {tool: "pinchtab_select", requiredArgs: map[string]any{"value": "v"}, selectorOptionalWithNodeID: true},+ {tool: "pinchtab_scroll_into_view", selectorOptionalWithNodeID: true},+ {tool: "pinchtab_scroll"},+ {tool: "pinchtab_press", requiredArgs: map[string]any{"key": "Enter"}},+}++func actionArgs(tool string, extra map[string]any) map[string]any {+ args := map[string]any{}+ for _, entry := range actionToolTargets {+ if entry.tool != tool {+ continue+ }+ for name, value := range entry.requiredArgs {+ args[name] = value+ }+ }+ for name, value := range extra {+ args[name] = value+ }+ return args+}++// nodeId was read before the switch on kind, so all nine tools forwarded it, but+// only click, hover and focus declared it. On the other six that meant no+// discovery and — because validateTypedArgs keys its type map per tool — no+// validation either, so a malformed value was dropped in silence.+func TestEveryActionToolAcceptsAndValidatesNodeID(t *testing.T) {+ for _, tc := range actionToolTargets {+ t.Run(tc.tool, func(t *testing.T) {+ srv, _ := upstreamRecorder(t)+ result := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"selector": "#a", "nodeId": float64(42)}), srv)+ if result.IsError {+ t.Fatalf("a valid nodeId was rejected: %s", resultText(t, result))+ }+ body, _ := resultJSON(t, result)["body"].(map[string]any)+ if got, ok := body["nodeId"]; !ok || got != float64(42) {+ t.Errorf("outbound nodeId = %v (present: %v), want 42 — the bridge honours it for this kind", got, ok)+ }++ srv2, paths := upstreamRecorder(t)+ malformed := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"selector": "#a", "nodeId": "abc"}), srv2)+ if !malformed.IsError {+ t.Fatalf("nodeId \"abc\" was accepted and silently dropped; upstream saw %v", *paths)+ }+ if text := resultText(t, malformed); !strings.Contains(text, "nodeId") {+ t.Errorf("rejection %q does not name nodeId, so the caller cannot correct it", text)+ }+ if len(*paths) != 0 {+ t.Errorf("upstream was called %v despite the malformed argument", *paths)+ }+ })+ }+}++// The MCP layer required a selector on type, fill, select and scroll_into_view+// even though the bridge resolves those kinds from NodeID alone. Declaring nodeId+// there without relaxing this would advertise an argument that cannot be used.+func TestNodeIDAloneSatisfiesTheTargetRequirement(t *testing.T) {+ for _, tc := range actionToolTargets {+ if !tc.selectorOptionalWithNodeID {+ continue+ }+ t.Run(tc.tool, func(t *testing.T) {+ srv, _ := upstreamRecorder(t)+ result := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"nodeId": float64(42)}), srv)+ if result.IsError {+ t.Fatalf("nodeId alone was rejected: %s", resultText(t, result))+ }+ body, _ := resultJSON(t, result)["body"].(map[string]any)+ if _, ok := body["selector"]; ok {+ t.Errorf("outbound body carries a selector the caller never sent: %v", body)+ }+ if got := body["nodeId"]; got != float64(42) {+ t.Errorf("outbound nodeId = %v, want 42", got)+ }++ srv2, paths := upstreamRecorder(t)+ neither := callTool(t, tc.tool, actionArgs(tc.tool, nil), srv2)+ if !neither.IsError {+ t.Fatalf("a call with no target at all was accepted; upstream saw %v", *paths)+ }+ if text := resultText(t, neither); !strings.Contains(text, "selector") {+ t.Errorf("the no-target rejection %q should still name selector", text)+ }+ })+ }+}++// x/y had the same shape as nodeId — read before the switch, so forwarded for all+// nine kinds with hasXY set — but the opposite correct answer: the bridge honours+// coordinates only for the pointer kinds, so the fix is to stop reading it+// elsewhere rather than to declare it everywhere.+func TestCoordinatesReachTheWireOnlyForTheToolsThatDeclareThem(t *testing.T) {+ for _, tc := range actionToolTargets {+ t.Run(tc.tool, func(t *testing.T) {+ _, declared := schemaArgTypesOnce()[tc.tool]["x"]+ srv, _ := upstreamRecorder(t)+ result := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"selector": "#a", "x": float64(11), "y": float64(22)}), srv)+ if result.IsError {+ t.Fatalf("coordinates were rejected: %s", resultText(t, result))+ }+ body, _ := resultJSON(t, result)["body"].(map[string]any)+ _, forwarded := body["hasXY"]+ if declared != forwarded {+ t.Errorf("%s declares x/y = %v but forwards them = %v (body %v)", tc.tool, declared, forwarded, body)+ }+ })+ }+}diff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex 12dc55a2..2210c93e 100644--- a/internal/mcp/tools.go+++ b/internal/mcp/tools.go@@ -118,6 +118,7 @@ func allTools() []mcp.Tool {mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),mcp.WithString("text", mcp.Required(), mcp.Description("Text to type")),+ mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),mcp.WithString("tabId", mcp.Description("Target tab ID")),mcp.WithString("browser",mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),@@ -125,6 +126,7 @@ func allTools() []mcp.Tool {mcp.NewTool("pinchtab_press",mcp.WithDescription("Press a keyboard key (Enter, Tab, Escape, etc.)"),mcp.WithString("key", mcp.Required(), mcp.Description("Key to press (e.g., 'Enter', 'Tab', 'Escape')")),+ mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),mcp.WithString("tabId", mcp.Description("Target tab ID")),mcp.WithString("browser",mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),@@ -158,6 +160,7 @@ func allTools() []mcp.Tool {mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),mcp.WithString("value", mcp.Required(), mcp.Description("Option value or visible text to select")),+ mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),mcp.WithString("tabId", mcp.Description("Target tab ID")),mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after select (saves a round-trip)")),mcp.WithString("browser",@@ -175,6 +178,7 @@ func allTools() []mcp.Tool {mcp.WithNumber("steps", mcp.Description("Multiplier for direction-based scrolling (default 1)")),mcp.WithNumber("x", mcp.Description("Optional X coordinate for wheel target")),mcp.WithNumber("y", mcp.Description("Optional Y coordinate for wheel target")),+ mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),mcp.WithString("tabId", mcp.Description("Target tab ID")),mcp.WithString("browser",mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),@@ -184,6 +188,7 @@ func allTools() []mcp.Tool {mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref — use 'selector' instead")),mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),+ mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),mcp.WithString("tabId", mcp.Description("Target tab ID")),mcp.WithString("browser",mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),@@ -194,6 +199,7 @@ func allTools() []mcp.Tool {mcp.WithString("ref", mcp.Description("(deprecated) Element ref — use 'selector' instead")),mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),mcp.WithString("value", mcp.Required(), mcp.Description("Value to fill")),+ mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),mcp.WithString("tabId", mcp.Description("Target tab ID")),mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after fill (saves a round-trip)")),mcp.WithString("browser",