Skip to content

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.go
index 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, wrongKey
return "", 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 string
param 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.RawMessage
if err := json.Unmarshal(body, &top); err != nil {