High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
chore(mcp): trim the helper rationale essays to one-line intent comments
Luigi Agosti6d87e57de5e9
diff --git a/internal/mcp/handlers_helpers.go b/internal/mcp/handlers_helpers.goindex ffd1002d..c046c413 100644--- a/internal/mcp/handlers_helpers.go+++ b/internal/mcp/handlers_helpers.go@@ -21,9 +21,7 @@ func optTrimmedString(r mcp.CallToolRequest, key string) string {return strings.TrimSpace(optString(r, key))}-// Tool calls are written by language models, and a stringified number is one of-// the commonest shapes they emit. Every numeric argument accepts both, so a-// future one cannot pick a strict accessor by accident — there is none.+// Models commonly send numbers as strings; there is no strict numeric accessor.func optFloat(r mcp.CallToolRequest, key string) (float64, bool) {if v, ok := r.GetArguments()[key].(float64); ok {return v, true@@ -41,10 +39,7 @@ func optInt(r mcp.CallToolRequest, key string) (int, bool) {return int(v), ok}-// Booleans get the same tolerance as numbers, and for the same reason. The one-// opt-out argument makes it matter more than the opt-in flags: dropping-// withBounds="false" leaves bounds switched on, so the response looks like the-// default rather than like the request.+// A stringified boolean is accepted so withBounds="false" is not silently read as the default.func optBool(r mcp.CallToolRequest, key string) (bool, bool) {if v, ok := r.GetArguments()[key].(bool); ok {return v, true@@ -80,24 +75,9 @@ func firstNonEmptyString(r mcp.CallToolRequest, keys ...string) string {return ""}-// firstSuppliedString answers "was this argument sent", the question firstNonEmptyString-// cannot answer because collapsing empty and absent is its entire job. It is the same-// question the bridge asks — ActionRequest.HasText is inferred from key presence over the-// same text/value pair that fill and select both read.-//-// The value travels verbatim rather than trimmed, so MCP and POST /action agree on every-// input and not merely on the cases where emptiness is the point.-//-// The dialog arguments keep the collapsing helper deliberately: an empty dialogAction means-// not-specified, so a value this helper would report as supplied-but-unusable is instead a-// skipped one-shot handler. That is a silent SKIP rather than a misleading refusal — a-// different shape, and it wants its own decision rather than being swept in here.-//-// wrongType names the JSON type of a value that WAS supplied under one of the keys but is-// not a string. The library does not enforce the declared type before calling a handler, so-// a model answering a numeric-looking field with 2024 rather than "2024" arrives here — and-// collapsing that into "not supplied" reproduces the very complaint this helper was written-// for: telling a caller an argument it sent is missing.+// firstSuppliedString reports presence, untrimmed, so MCP and POST /action agree on every+// input; wrongType names a value that was sent under a non-string type instead of+// collapsing it into "not supplied".func firstSuppliedString(r mcp.CallToolRequest, keys ...string) (value string, supplied bool, wrongType string) {args := r.GetArguments()for _, key := range keys {@@ -184,12 +164,7 @@ func hasASCIIAlpha(v string) bool {return false}-// firstSelectorString is firstNonEmptyString for the selector aliases, except that a key-// which was SENT under a non-string type is reported by name instead of being collapsed-// into not-given. A later alias that yields a usable string still wins — the caller's-// intent is unambiguous there — so wrongKey only survives when NO key produced a selector.-// A supplied empty string keeps collapsing deliberately: empty carries no selector meaning-// on any verb, so it falls through exactly as before.+// A later alias with a usable string wins; wrongKey survives only when no key produced a selector.func firstSelectorString(r mcp.CallToolRequest, keys ...string) (value, wrongKey, wrongType string) {args := r.GetArguments()for _, key := range keys {@@ -210,14 +185,7 @@ func firstSelectorString(r mcp.CallToolRequest, keys ...string) (value, wrongKeyreturn "", wrongKey, wrongType}-// actionSelectorArg resolves common selector aliases used by MCP clients.-// If only "query" is provided, natural language input is normalized to-// semantic selector form (find:...).-//-// A wrong-typed alias REFUSES rather than falling through — the fall-through would act on-// a different argument (query) or a different target (nodeId) while the caller's mistyped-// selector is silently ignored, which is worse than refusing. The caller of this function-// turns wrongKey/wrongType into the refusal, naming the key that was actually sent.+// A wrong-typed selector alias refuses rather than falling through to a different argument.func actionSelectorArg(r mcp.CallToolRequest) (sel, wrongKey, wrongType string) {sel, wrongKey, wrongType = firstSelectorString(r, "selector", "ref", "element", "target")if sel != "" || wrongType != "" {@@ -268,19 +236,14 @@ func resultFromBytes(body []byte, code int) (*mcp.CallToolResult, error) {return mcp.NewToolResultText(string(body)), nil}-// remedyTool is the MCP tool that performs a pinchtab CLI verb, and the tool parameter-// its single positional value fills.type remedyTool struct {name stringparam string}-// remedyVerbTools maps a pinchtab CLI verb to its MCP tool EXPLICITLY, because neither the-// name nor the argument follows from the verb: nav's tool is pinchtab_navigate, snap's is-// pinchtab_snapshot, and dialog's positional is its action, not a tab id. A verb absent here-// has no MCP counterpart. RemedyToolForVerb and the whole-binary remedy census pin that-// every declared remedy verb is either in this table — naming a registered tool and a real-// parameter — or recorded as counterpart-free, so a new remedy cannot ship untranslated.+// Neither tool name nor parameter follows from the CLI verb (nav is pinchtab_navigate,+// dialog's positional is its action), so the table is explicit and the whole-binary remedy+// census pins it complete.var remedyVerbTools = map[string]remedyTool{"resume": {"pinchtab_resume", "tabId"},"dialog": {"pinchtab_dialog", "action"},@@ -289,10 +252,7 @@ var remedyVerbTools = map[string]remedyTool{"snap": {"pinchtab_snapshot", ""},}-// mcpRemedyGuidance turns a refusal's details.remedy — one pinchtab CLI line the CLI renders-// verbatim — into guidance an MCP agent can act on, which runs tools rather than a shell.-// A verb without an MCP counterpart, or a multi-command remedy, yields nothing and the raw-// body stands alone.+// A verb without an MCP counterpart, or a multi-command remedy, yields no guidance.func mcpRemedyGuidance(body []byte) string {segments := remedy.Segments(remedyLine(body))if len(segments) != 1 {@@ -314,16 +274,13 @@ func mcpRemedyGuidance(body []byte) string {return "call " + tool.name}-// RemedyToolForVerb reports the MCP tool a pinchtab CLI verb maps to, and the tool parameter-// its positional value fills (empty when the tool takes none). It is the seam the whole-binary-// remedy census reads to prove the mapping stays complete and correct.+// RemedyToolForVerb is the seam the whole-binary remedy census reads.func RemedyToolForVerb(verb string) (name, param string, ok bool) {tool, ok := remedyVerbTools[verb]return tool.name, tool.param, ok}-// ToolInputHasParam reports whether name is a registered tool and, when param is non-empty,-// whether that tool declares param in its input schema.+// ToolInputHasParam reports whether name is a registered tool declaring param (any tool when param is empty).func ToolInputHasParam(name, param string) bool {for _, tool := range allTools() {if tool.Name != name {@@ -359,29 +316,10 @@ func firstPositional(words []string) string {return ""}-// reportsNoSuccess is the funnel's body-level failure rule: an endpoint that answers 200-// while reporting it achieved nothing must reach the agent as an error, or the agent-// confirms work the browser never did — the cookie-set path shipped exactly that.-//-// The rule keys on the COUNTING SHAPE, not on failure-flavoured key names: a top-level-// numeric "failed" above zero marks a response that counts the work it was asked to do.-// That is what keeps the exclusions structural rather than a list — the observability-// snapshot, /health/tabs and the console endpoint report failures AS their payload but-// carry no top-level failed count, and /network's per-request "failed" is a nested bool,-// so none of them can match. A key-name rule would break exactly those.-//-// Partial success stays a SUCCESS carrying detail: the succeeded items' effects already-// happened, and the body's own counts and failures list are what the agent needs to retry-// only what missed. Zero success is an error, with the body riding along as the reason.-// Fail closed within the shape: a failed count with no readable success count beside it-// confirms nothing and is refused. A body that does not parse as an object cannot carry-// the shape and keeps the status rule — most funnel responses are not counting anything.-//-// The cookie tool keeps unsetCookieReport ON TOP of this rule deliberately: it confirms a-// single named write with a stricter fail-closed contract (an unreadable body, or one-// missing its counts, refuses) than a funnel serving every tool can impose without-// breaking non-counting responses. Its check runs first, so its more specific message-// wins; this rule is the class-wide net behind it.+// A 200 whose top-level counts report zero successes reaches the agent as an error. The+// rule keys on the counting shape, not on key names, so payloads that describe failures+// without a top-level failed count cannot match. Partial success stays a success; a failed+// count with no success count beside it refuses.func reportsNoSuccess(body []byte) string {var top map[string]json.RawMessageif err := json.Unmarshal(body, &top); err != nil {