Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: give batch and macro a single per-item writer that carries the paused-tab code and hint (PIN-179)

Luigi Agostif8d7ed43268c
diff --git a/docs/endpoints.md b/docs/endpoints.md
index b8b291e4..c4987bc5 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -117,11 +117,11 @@ Notes:
- a paused-handoff tab blocks the action-execution routes, but the two envelopes differ.
`POST /action` returns `409` with code `tab_paused_handoff` and a `details.hint` naming
`/resume`. `POST /actions` and `POST /macro` return **200** — they answer with a result
- list — and refuse per item: the entry for each step against the paused tab has
- `success: false` and a message naming the pause, with no code of its own yet. With
- `stopOnError` false (the default) the remaining steps still run, so each step aimed at the
- paused tab is refused the same way while steps naming another tab execute normally.
- `/resume` clears the state for all of them.
+ list — and carry the same refusal per item: the entry for each step against the paused tab
+ has `success: false`, `code: "tab_paused_handoff"` and the same `details`. Match on the
+ code, not on the message. With `stopOnError` false (the default) the remaining steps still
+ run, so each step aimed at the paused tab is refused the same way while steps naming another
+ tab execute normally. `/resume` clears the state for all of them.
- treat the handoff record as coordination state, not as a security boundary — non-action endpoints (snapshots, screenshots, network logs, evals subject to their own gates) remain reachable
- CLI wrappers exist: `pinchtab handoff`, `pinchtab resume`, `pinchtab handoff-status`, plus the `pinchtab tab handoff|resume|handoff-status` aliases
diff --git a/internal/handlers/action_types.go b/internal/handlers/action_types.go
index ab81ac2d..557e1073 100644
--- a/internal/handlers/action_types.go
+++ b/internal/handlers/action_types.go
@@ -14,6 +14,8 @@ type actionResult struct {
Success bool `json:"success"`
Result map[string]any `json:"result,omitempty"`
Error string `json:"error,omitempty"`
+ Code string `json:"code,omitempty"`
+ Details map[string]any `json:"details,omitempty"`
}
func countSuccessful(results []actionResult) int {
diff --git a/internal/handlers/actions.go b/internal/handlers/actions.go
index f8e9cb7f..5f7be67e 100644
--- a/internal/handlers/actions.go
+++ b/internal/handlers/actions.go
@@ -839,7 +839,7 @@ func (h *Handlers) handleActionsBatch(w http.ResponseWriter, r *http.Request, re
return
}
if err := h.enforceTabNotPausedForHandoff(resolvedTabID); err != nil {
- results = append(results, actionResult{Index: i, Success: false, Error: err.Error()})
+ results = append(results, h.handoffPausedActionResult(i, resolvedTabID, err))
if req.StopOnError {
break
}
@@ -1059,7 +1059,7 @@ func (h *Handlers) HandleMacro(w http.ResponseWriter, r *http.Request) {
return
}
if err := h.enforceTabNotPausedForHandoff(resolvedTabID); err != nil {
- results = append(results, actionResult{Index: i, Success: false, Error: err.Error()})
+ results = append(results, h.handoffPausedActionResult(i, resolvedTabID, err))
if req.StopOnError {
break
}
diff --git a/internal/handlers/handoff.go b/internal/handlers/handoff.go
index c9e0eadc..550e835d 100644
--- a/internal/handlers/handoff.go
+++ b/internal/handlers/handoff.go
@@ -30,6 +30,8 @@ func (h *Handlers) handoffController() (tabHandoffController, bool) {
// the agent must yield control to a human operator.
const handoffHintMessage = "return control to the user and ask them to manually solve the challenge in the browser window, then call POST /tabs/{id}/resume to continue"
+const handoffPausedCode = "tab_paused_handoff"
+
// 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.
@@ -68,23 +70,29 @@ func (h *Handlers) enforceTabNotPausedForHandoff(tabID string) error {
// enforceTabNotPausedForHandoffOrRespond is the single writer of the RESPONSE-LEVEL
// paused-tab refusal: an endpoint that answers with one status calls it, so a client
-// sees the same 409, code and remedy hint whichever it hit. Reports ok=false once the
-// 409 has been written.
-//
-// It is NOT every page-mutating endpoint. POST /actions and POST /macro answer 200 with
-// a result list, so a status written from inside their loop would describe the wrong
-// thing; they call the raw predicate above and carry the condition as a per-item result,
-// which today is a bare message with no code and no hint. Giving that shape its own
-// writer beside this one is PIN-179.
+// sees the same 409, code and remedy hint whichever it hit. POST /actions and POST /macro
+// answer 200 with a result list instead, so they carry the same condition per item through
+// handoffPausedActionResult — the two writers are siblings, same code and hint, different
+// envelope. Reports ok=false once the 409 has been written.
func (h *Handlers) enforceTabNotPausedForHandoffOrRespond(w http.ResponseWriter, tabID string) bool {
err := h.enforceTabNotPausedForHandoff(tabID)
if err == nil {
return true
}
- httpx.ErrorCode(w, http.StatusConflict, "tab_paused_handoff", err.Error(), false, h.handoffErrorDetails(tabID))
+ httpx.ErrorCode(w, http.StatusConflict, handoffPausedCode, err.Error(), false, h.handoffErrorDetails(tabID))
return false
}
+func (h *Handlers) handoffPausedActionResult(index int, tabID string, err error) actionResult {
+ return actionResult{
+ Index: index,
+ Success: false,
+ Error: err.Error(),
+ Code: handoffPausedCode,
+ Details: h.handoffErrorDetails(tabID),
+ }
+}
+
// pauseTabForHandoff marks a tab as paused for human handoff and broadcasts
// a dashboard event. source identifies what triggered the handoff
// (e.g. "autosolver", "manual"). Returns the applied reason.
diff --git a/internal/handlers/handoff_batch_refusal_test.go b/internal/handlers/handoff_batch_refusal_test.go
new file mode 100644
index 00000000..1acf2c1c
--- /dev/null
+++ b/internal/handlers/handoff_batch_refusal_test.go
@@ -0,0 +1,131 @@
+package handlers
+
+import (
+ "bytes"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+func pausedHandoffActionHandlers(t *testing.T) *Handlers {
+ t.Helper()
+
+ b := &handoffRecordingBridge{
+ state: bridge.TabHandoffState{
+ Status: "paused_handoff",
+ Reason: "captcha_manual",
+ PausedAt: time.Now().UTC(),
+ LastUpdatedAt: time.Now().UTC(),
+ },
+ has: true,
+ }
+ return New(b, &config.RuntimeConfig{AllowMacro: true}, nil, nil, nil)
+}
+
+type batchEnvelope struct {
+ Results []struct {
+ Index int `json:"index"`
+ Success bool `json:"success"`
+ Error string `json:"error"`
+ Code string `json:"code"`
+ Details map[string]any `json:"details"`
+ } `json:"results"`
+}
+
+func TestBatchAndMacroCarryThePausedTabRefusalPerItem(t *testing.T) {
+ for _, tc := range []struct{ name, path, body string }{
+ {
+ name: "batch",
+ path: "/actions",
+ body: `{"tabId":"tab1","actions":[{"kind":"click","selector":"button"}]}`,
+ },
+ {
+ name: "macro",
+ path: "/macro",
+ body: `{"tabId":"tab1","steps":[{"kind":"click","selector":"button"}]}`,
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ h := pausedHandoffActionHandlers(t)
+ req := httptest.NewRequest(http.MethodPost, tc.path, bytes.NewReader([]byte(tc.body)))
+ req.Header.Set("Content-Type", "application/json")
+ rec := httptest.NewRecorder()
+
+ if tc.path == "/macro" {
+ h.HandleMacro(rec, req)
+ } else {
+ h.HandleActions(rec, req)
+ }
+
+ if rec.Code != http.StatusOK {
+ t.Fatalf("%s answered %d, want the 200 result-list envelope: %s", tc.path, rec.Code, rec.Body.String())
+ }
+
+ var envelope batchEnvelope
+ if err := json.Unmarshal(rec.Body.Bytes(), &envelope); err != nil {
+ t.Fatalf("%s response is not the result envelope: %v: %s", tc.path, err, rec.Body.String())
+ }
+ if len(envelope.Results) != 1 {
+ t.Fatalf("%s returned %d results, want one per step: %s", tc.path, len(envelope.Results), rec.Body.String())
+ }
+
+ entry := envelope.Results[0]
+ if entry.Success {
+ t.Errorf("%s reported the step as successful against a paused tab", tc.path)
+ }
+ if entry.Code != "tab_paused_handoff" {
+ t.Errorf("%s per-item code = %q, want %q — a client must detect this by code, not by matching the message", tc.path, entry.Code, "tab_paused_handoff")
+ }
+ hint, _ := entry.Details["hint"].(string)
+ if !strings.Contains(hint, "/tabs/{id}/resume") {
+ t.Errorf("%s per-item details.hint = %q, want the remedy naming the resume route", tc.path, hint)
+ }
+ if entry.Error == "" {
+ t.Errorf("%s dropped the human-readable reason; the code is added beside it, not instead of it", tc.path)
+ }
+ })
+ }
+}
+
+func TestThePerItemRefusalMatchesTheResponseLevelOne(t *testing.T) {
+ h := pausedHandoffActionHandlers(t)
+
+ single := httptest.NewRecorder()
+ singleReq := httptest.NewRequest(http.MethodPost, "/action", bytes.NewReader([]byte(`{"tabId":"tab1","kind":"click","selector":"button"}`)))
+ singleReq.Header.Set("Content-Type", "application/json")
+ h.HandleAction(single, singleReq)
+
+ if single.Code != http.StatusConflict {
+ t.Fatalf("POST /action answered %d, want the response-level 409: %s", single.Code, single.Body.String())
+ }
+ var refusal struct {
+ Code string `json:"code"`
+ Details map[string]any `json:"details"`
+ }
+ if err := json.Unmarshal(single.Body.Bytes(), &refusal); err != nil {
+ t.Fatalf("409 body is not JSON: %v: %s", err, single.Body.String())
+ }
+
+ batch := httptest.NewRecorder()
+ batchReq := httptest.NewRequest(http.MethodPost, "/actions", bytes.NewReader([]byte(`{"tabId":"tab1","actions":[{"kind":"click","selector":"button"}]}`)))
+ batchReq.Header.Set("Content-Type", "application/json")
+ h.HandleActions(batch, batchReq)
+
+ var envelope batchEnvelope
+ if err := json.Unmarshal(batch.Body.Bytes(), &envelope); err != nil || len(envelope.Results) != 1 {
+ t.Fatalf("batch response unusable: %v: %s", err, batch.Body.String())
+ }
+
+ if envelope.Results[0].Code != refusal.Code {
+ t.Errorf("per-item code %q and response-level code %q have drifted apart; they are the same condition", envelope.Results[0].Code, refusal.Code)
+ }
+ if got, want := envelope.Results[0].Details["hint"], refusal.Details["hint"]; got != want {
+ t.Errorf("per-item hint %v and response-level hint %v differ; a client following one is misled by the other", got, want)
+ }
+}