High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: the handoff refusal remedy names pinchtab resume for CLI and pinchtab_resume for MCP (PIN-388)
Luigi Agosti4eccf435e27d
diff --git a/internal/cli/apiclient/apierror_test.go b/internal/cli/apiclient/apierror_test.goindex 1220fe4f..e148f145 100644--- a/internal/cli/apiclient/apierror_test.go+++ b/internal/cli/apiclient/apierror_test.go@@ -113,6 +113,21 @@ func TestRenderAPIErrorBodyShowsHintAndRemedy(t *testing.T) {}}+// A tab_paused_handoff refusal must name the CLI resume command, not the HTTP route the+// hint prose carries: the CLI user runs `pinchtab resume`, not a POST. The server ships+// the command as details.remedy; renderGuidance prints it in the Remedy slot.+func TestHandoffRefusalRendersTheCLIResumeCommand(t *testing.T) {+ body := `{"code":"tab_paused_handoff",` ++ `"error":"tab tab1 is paused for human handoff (manual_handoff)",` ++ `"details":{"hint":"...then call POST /tabs/{id}/resume to continue","remedy":"pinchtab resume tab1"}}`++ out := renderAPIErrorBody(http.StatusConflict, []byte(body))++ if !strings.Contains(out, "Remedy: pinchtab resume tab1") {+ t.Errorf("rendered refusal does not name the CLI resume command:\n%s", out)+ }+}+// cachedTabFile installs a cached-tab context pointing at a real file, so a render// that still performed the old os.Remove would be visible as a missing file rather// than as an assertion about a string.diff --git a/internal/handlers/handoff.go b/internal/handlers/handoff.goindex a48bbdc8..bc3fb003 100644--- a/internal/handlers/handoff.go+++ b/internal/handlers/handoff.go@@ -10,6 +10,7 @@ import ("github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/dashboard""github.com/pinchtab/pinchtab/internal/httpx"+ "github.com/pinchtab/pinchtab/internal/remedy")type tabHandoffController interface {@@ -29,11 +30,14 @@ const handoffHintMessage = "return control to the user and ask them to manuallyconst handoffPausedCode = "tab_paused_handoff"+var resumeRemedy = remedy.Declare("pinchtab resume <tab-id>")+// handoffErrorDetails builds the details payload attached to 409 responses// when an action hits a tab that is paused for handoff. Always includes the-// agent hint; when known, also includes the current reason and pausedAt.+// agent hint and the resume remedy; when known, also includes the current+// reason and pausedAt.func (h *Handlers) handoffErrorDetails(tabID string) map[string]any {- details := map[string]any{"hint": handoffHintMessage}+ details := remedy.Details(handoffHintMessage, resumeRemedy.Fill(tabID))if ctrl, ok := h.handoffController(); ok {if state, exists := ctrl.TabHandoffState(tabID); exists {if state.Reason != "" {@@ -176,6 +180,9 @@ func (h *Handlers) HandleTabHandoff(w http.ResponseWriter, r *http.Request) {"timeoutMs": req.TimeoutMs,"hint": handoffHintMessage,}+ if line := resumeRemedy.Fill(resolvedTabID); !line.Empty() {+ resp["remedy"] = line.String()+ }if timeout > 0 {resp["expiresAt"] = time.Now().UTC().Add(timeout).Format(time.RFC3339)}diff --git a/internal/handlers/handoff_guard_test.go b/internal/handlers/handoff_guard_test.goindex 7198c067..81eff291 100644--- a/internal/handlers/handoff_guard_test.go+++ b/internal/handlers/handoff_guard_test.go@@ -104,6 +104,12 @@ func assertHandoffRefusal(t *testing.T, w *httptest.ResponseRecorder) {if resp.Details["hint"] != handoffHintMessage {t.Fatalf("details hint = %v, want the shared handoff hint", resp.Details["hint"])}+ if !strings.Contains(handoffHintMessage, "/tabs/{id}/resume") {+ t.Fatalf("the HTTP hint no longer names the resume route: %q", handoffHintMessage)+ }+ if resp.Details["remedy"] != "pinchtab resume tab1" {+ t.Fatalf("details remedy = %v, want the CLI resume line", resp.Details["remedy"])+ }if resp.Details["reason"] != "manual_handoff" {t.Fatalf("details reason = %v, want manual_handoff", resp.Details["reason"])}diff --git a/internal/mcp/handlers_helpers.go b/internal/mcp/handlers_helpers.goindex 3fd1df61..7cac095e 100644--- a/internal/mcp/handlers_helpers.go+++ b/internal/mcp/handlers_helpers.go@@ -8,6 +8,7 @@ import ("strings""github.com/mark3labs/mcp-go/mcp"+ "github.com/pinchtab/pinchtab/internal/remedy""github.com/pinchtab/pinchtab/internal/selector")@@ -255,7 +256,11 @@ func toolResult(body []byte, code int, err error) (*mcp.CallToolResult, error) {func resultFromBytes(body []byte, code int) (*mcp.CallToolResult, error) {if code >= 400 {- return mcp.NewToolResultError(fmt.Sprintf("HTTP %d: %s", code, string(body))), nil+ message := fmt.Sprintf("HTTP %d: %s", code, string(body))+ if guidance := mcpRemedyGuidance(body); guidance != "" {+ message = guidance + "\n" + message+ }+ return mcp.NewToolResultError(message), nil}if reason := reportsNoSuccess(body); reason != "" {return mcp.NewToolResultError(reason), nil@@ -263,6 +268,60 @@ func resultFromBytes(body []byte, code int) (*mcp.CallToolResult, error) {return mcp.NewToolResultText(string(body)), nil}+// 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. It fires for any remedy whose verb has a matching tool (resume → pinchtab_resume),+// so every future single-command remedy is served, not just handoff; a verb with no matching+// tool, or a multi-command remedy, yields nothing and the raw body stands alone.+func mcpRemedyGuidance(body []byte) string {+ segments := remedy.Segments(remedyLine(body))+ if len(segments) != 1 {+ return ""+ }+ words := segments[0]+ if len(words) < 2 {+ return ""+ }+ tool := "pinchtab_" + words[1]+ if !isRegisteredTool(tool) {+ return ""+ }+ if arg := firstPositional(words[2:]); arg != "" {+ return fmt.Sprintf("call %s with tabId %s", tool, arg)+ }+ return "call " + tool+}++func remedyLine(body []byte) string {+ var envelope struct {+ Details struct {+ Remedy string `json:"remedy"`+ } `json:"details"`+ }+ if json.Unmarshal(body, &envelope) != nil {+ return ""+ }+ return envelope.Details.Remedy+}++func firstPositional(words []string) string {+ for _, word := range words {+ if !strings.HasPrefix(word, "-") {+ return word+ }+ }+ return ""+}++func isRegisteredTool(name string) bool {+ for _, tool := range allTools() {+ if tool.Name == name {+ return true+ }+ }+ return false+}+// 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.diff --git a/internal/mcp/handlers_helpers_test.go b/internal/mcp/handlers_helpers_test.goindex db8507e3..0f8c05c0 100644--- a/internal/mcp/handlers_helpers_test.go+++ b/internal/mcp/handlers_helpers_test.go@@ -213,3 +213,36 @@ func TestEveryFailedKeyProducerHasARecordedFunnelDecision(t *testing.T) {t.Fatal("found no \"failed\" key producer at all; if the spelling moved, re-point this census rather than deleting it")}}++// A refusal's details.remedy is one pinchtab CLI line the CLI renders verbatim, but an+// MCP agent runs tools, not a shell. The funnel must translate the remedy's verb into the+// matching tool so the agent can recover; the handoff refusal is the case that shipped the+// unrunnable "POST /tabs/{id}/resume" instruction to MCP.+func TestMCPRefusalTranslatesTheRemedyIntoAToolCall(t *testing.T) {+ body := []byte(`{"error":"tab tab1 is paused for human handoff (manual_handoff)",` ++ `"code":"tab_paused_handoff",` ++ `"details":{"hint":"...then call POST /tabs/{id}/resume to continue","remedy":"pinchtab resume tab1"}}`)++ result, err := resultFromBytes(body, http.StatusConflict)+ if err != nil {+ t.Fatalf("resultFromBytes: %v", err)+ }+ if !result.IsError {+ t.Fatal("a 409 refusal must reach the agent as an error")+ }+ text := resultText(t, result)+ if !strings.Contains(text, "call pinchtab_resume with tabId tab1") {+ t.Fatalf("MCP refusal does not name the resume tool: %q", text)+ }++ // The mapping is real, not a bare "pinchtab_"+verb: a remedy whose verb has no+ // matching tool (nav → pinchtab_navigate, not pinchtab_nav) adds no guidance.+ noTool := []byte(`{"code":"x","details":{"remedy":"pinchtab nav https://example.test"}}`)+ noToolResult, err := resultFromBytes(noTool, http.StatusConflict)+ if err != nil {+ t.Fatalf("resultFromBytes: %v", err)+ }+ if quiet := resultText(t, noToolResult); strings.Contains(quiet, "call pinchtab_") {+ t.Fatalf("a verb with no matching tool produced tool guidance: %q", quiet)+ }+}