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.mdindex 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` aliasesdiff --git a/internal/handlers/action_types.go b/internal/handlers/action_types.goindex 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.goindex 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, rereturn}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.goindex 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.gonew file mode 100644index 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)+ }+}