Skip to content

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.go
index 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.go
index 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 manually
const 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.go
index 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.go
index 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.go
index 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)
+ }
+}