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.goindex 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.goindex 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.CallToolRequif _, 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.CallToolRequif 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"] = modediff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex 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).")),