Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: pinchtab_click reads humanize but never declares or forwards it (PIN-118)

Luigi Agosti88c0b388beff
diff --git a/internal/mcp/argcheck_test.go b/internal/mcp/argcheck_test.go
index 2d85276e..02b0ea1b 100644
--- a/internal/mcp/argcheck_test.go
+++ b/internal/mcp/argcheck_test.go
@@ -5,6 +5,9 @@ import (
"io"
"net/http"
"net/http/httptest"
+ "os"
+ "reflect"
+ "regexp"
"strings"
"testing"
)
@@ -214,3 +217,164 @@ func TestEveryHandlerHasASchemaAndEverySchemaAHandler(t *testing.T) {
}
}
}
+
+// Every argument the package reads with a TYPED accessor must be declared as
+// number/integer/boolean in some tool's schema. Two things follow from a missing
+// declaration: a model cannot discover the argument, and validateTypedArgs cannot
+// 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.
+//
+// optString is deliberately NOT scanned. A string argument read without a
+// declaration is undiscoverable but not a correctness hazard: there is no
+// coercion, so nothing is silently dropped. Widening this census to optString
+// would produce false positives on the many string aliases the handlers accept.
+func TestEveryTypedAccessorArgumentIsDeclaredInASchema(t *testing.T) {
+ declared := map[string]string{}
+ for _, tool := range allTools() {
+ for name, kind := range typedArgsOf(tool) {
+ declared[name] = kind
+ }
+ }
+ if len(declared) == 0 {
+ t.Fatal("no typed arguments found in any schema — this census is checking nothing")
+ }
+
+ entries, err := os.ReadDir(".")
+ if err != nil {
+ t.Fatal(err)
+ }
+ accessor := regexp.MustCompile(`opt(?:Int|Float|Bool)\(r, "([^"]+)"\)`)
+
+ scanned, found := 0, 0
+ for _, entry := range entries {
+ name := entry.Name()
+ if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
+ continue
+ }
+ raw, err := os.ReadFile(name)
+ if err != nil {
+ t.Fatal(err)
+ }
+ scanned++
+ for _, match := range accessor.FindAllStringSubmatch(string(raw), -1) {
+ found++
+ arg := match[1]
+ if _, ok := declared[arg]; !ok {
+ t.Errorf("%s reads %q with a typed accessor but no tool schema declares it as number/integer/boolean — "+
+ "a model cannot discover it and validateTypedArgs cannot validate it, so a malformed value is silently dropped", name, arg)
+ }
+ }
+ }
+ if scanned == 0 {
+ t.Fatal("no Go source scanned — this census is checking nothing")
+ }
+ if found == 0 {
+ t.Fatal("no typed accessor call found — the pattern no longer matches how arguments are read")
+ }
+ t.Logf("checked %d typed-accessor call sites against %d declared typed arguments", found, len(declared))
+}
+
+// Declaring humanize is only half the fix: it was previously read solely to raise
+// the mutual-exclusion error and never forwarded, so humanized input was
+// unreachable from MCP even for a caller who guessed the name.
+func TestPointerToolsForwardHumanizeToUpstream(t *testing.T) {
+ for _, tool := range []string{"pinchtab_click", "pinchtab_hover"} {
+ t.Run(tool, func(t *testing.T) {
+ srv, _ := upstreamRecorder(t)
+
+ result := callTool(t, tool, map[string]any{"selector": "#b", "humanize": true}, srv)
+ if result.IsError {
+ t.Fatalf("humanize=true was rejected: %s", resultText(t, result))
+ }
+ body, _ := resultJSON(t, result)["body"].(map[string]any)
+ if got, ok := body["humanize"]; !ok || got != true {
+ t.Errorf("outbound body humanize = %v (present: %v), want true — the argument must be usable, not just accepted", got, ok)
+ }
+ })
+ }
+}
+
+// An explicit false is an opt-OUT and must travel, because the wire field is a
+// per-request override of the instance default rather than a flag.
+func TestPointerToolsForwardAnExplicitHumanizeFalse(t *testing.T) {
+ srv, _ := upstreamRecorder(t)
+
+ result := callTool(t, "pinchtab_click", map[string]any{"selector": "#b", "humanize": false}, srv)
+ body, _ := resultJSON(t, result)["body"].(map[string]any)
+ if got, ok := body["humanize"]; !ok || got != false {
+ t.Errorf("outbound body humanize = %v (present: %v), want false to travel as an opt-out", got, ok)
+ }
+}
+
+// Forwarding must not become an unconditional default: a call that omits humanize
+// has to leave the instance config in charge.
+func TestOmittedHumanizeIsNotForwarded(t *testing.T) {
+ for _, tool := range []string{"pinchtab_click", "pinchtab_hover"} {
+ t.Run(tool, func(t *testing.T) {
+ srv, _ := upstreamRecorder(t)
+
+ result := callTool(t, tool, map[string]any{"selector": "#b"}, srv)
+ body, _ := resultJSON(t, result)["body"].(map[string]any)
+ if got, ok := body["humanize"]; ok {
+ t.Errorf("outbound body carries humanize = %v with none requested; the instance default must stay in charge", got)
+ }
+ })
+ }
+}
+
+// The third defect: before humanize was declared, the schema-derived validator
+// could not see it, so "yes" was silently dropped and the mutual-exclusion guard
+// it feeds was bypassed — the guard fired for true and "true" but not "yes".
+// argcheck.go is untouched; the declaration alone brings this under validation.
+func TestMalformedHumanizeIsRejectedFromTheDeclarationAlone(t *testing.T) {
+ srv, paths := upstreamRecorder(t)
+
+ result := callTool(t, "pinchtab_click", map[string]any{"selector": "#b", "mode": "dom", "humanize": "yes"}, srv)
+ if !result.IsError {
+ t.Fatalf(`humanize="yes" was accepted: %s`, resultText(t, result))
+ }
+ message := resultText(t, result)
+ if !strings.Contains(message, "humanize") {
+ t.Errorf("error %q does not name the argument", message)
+ }
+ if len(*paths) != 0 {
+ t.Errorf("rejected call still reached upstream: %v", *paths)
+ }
+}
+
+// The mutual-exclusion rule the CLI enforces stays enforced, for the parsed string
+// form too, and only on the tool that has both arguments.
+func TestModeAndHumanizeRemainMutuallyExclusiveOnClick(t *testing.T) {
+ for _, humanize := range []any{true, "true"} {
+ srv, _ := upstreamRecorder(t)
+ result := callTool(t, "pinchtab_click", map[string]any{"selector": "#b", "mode": "dom", "humanize": humanize}, srv)
+ if !result.IsError {
+ t.Errorf("mode+humanize=%v was accepted: %s", humanize, resultText(t, result))
+ }
+ }
+}
+
+// Only the pointer tools declare it. A tool without a pointer path must not, or
+// the schema would advertise an argument its handler ignores.
+func TestOnlyPointerToolsDeclareHumanize(t *testing.T) {
+ declaring := map[string]bool{}
+ for _, tool := range allTools() {
+ if _, ok := typedArgsOf(tool)["humanize"]; ok {
+ declaring[tool.Name] = true
+ }
+ }
+ want := map[string]bool{"pinchtab_click": true, "pinchtab_hover": true}
+ if !reflect.DeepEqual(declaring, want) {
+ t.Errorf("tools declaring humanize = %v, want %v (the MCP members of the CLI addPointerActionFlags set)", declaring, want)
+ }
+ for kind := range humanizeAction {
+ if !declaring["pinchtab_"+kind] {
+ t.Errorf("handler forwards humanize for %q but pinchtab_%s does not declare it", kind, kind)
+ }
+ }
+}
diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index 2bdaee11..32c4d7e3 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -9,6 +9,12 @@ import (
"github.com/mark3labs/mcp-go/mcp"
)
+// humanizeAction is the set of pointer actions that accept a per-request humanize
+// override, mirroring the CLI's addPointerActionFlags set. Only these tools
+// declare humanize in their schema; focus is not a pointer action, and only click
+// also has mode, so only click can hit the mutual-exclusion rule.
+var humanizeAction = map[string]bool{"click": true, "hover": 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}
@@ -51,6 +57,17 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
if _, err := resolveSelector(requiresSelector); err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
+ // Forwarded only when the caller actually sent it, so an omitted
+ // humanize inherits the instance default instead of overriding it for
+ // every request. An explicit false is a real opt-out and travels: the
+ // wire field is a per-request override, not a flag.
+ humanize, humanizeSet := false, false
+ if humanizeAction[kind] {
+ humanize, humanizeSet = optBool(r, "humanize")
+ if humanizeSet {
+ payload["humanize"] = humanize
+ }
+ }
if kind == "click" {
if waitNav, ok := optBool(r, "waitNav"); ok && waitNav {
payload["waitNav"] = true
@@ -59,7 +76,7 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
if mode != "dom" && mode != "dispatch" {
return mcp.NewToolResultError("mode must be 'dom' or 'dispatch'"), nil
}
- if humanize, ok := optBool(r, "humanize"); ok && humanize {
+ if humanizeSet && humanize {
return mcp.NewToolResultError("mode and humanize are mutually exclusive"), nil
}
payload["mode"] = mode
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index afc58179..48e261f9 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -85,6 +85,7 @@ func allTools() []mcp.Tool {
mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
mcp.WithBoolean("waitNav", mcp.Description("Wait for navigation after the click when the element triggers a page change")),
mcp.WithString("mode", mcp.Description("Optional click delivery override: 'dom' for element.click() or 'dispatch' for synthetic click events on the target")),
+ mcp.WithBoolean("humanize", mcp.Description("Use the humanized input path for this request — bezier pointer path, per-step jitter, pre-press delays. Overrides the instance default; omit to inherit it.")),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after click (saves a round-trip)")),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
mcp.WithString("browser",
@@ -115,6 +116,7 @@ func allTools() []mcp.Tool {
mcp.WithNumber("x", mcp.Description("Optional X coordinate for coordinate hover")),
mcp.WithNumber("y", mcp.Description("Optional Y coordinate for coordinate hover")),
mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
+ mcp.WithBoolean("humanize", mcp.Description("Use the humanized input path for this request — bezier pointer path, per-step jitter, pre-press delays. Overrides the instance default; omit to inherit it.")),
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).")),