High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat(mcp): register pinchtab_handoff, pinchtab_resume and pinchtab_handoff_status (PIN-345)
Luigi Agosti173a53517dd4
diff --git a/docs/mcp.md b/docs/mcp.mdindex 905f91d4..174a18cf 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -114,7 +114,7 @@ PINCHTAB_TOKEN=<that-host-token> pinchtab --server http://remote:9867 mcp## Available Tools-PinchTab currently exposes 39 tools:+PinchTab currently exposes 42 tools:- Navigation: 9- Interaction: 8@@ -123,6 +123,7 @@ PinchTab currently exposes 39 tools:- Recording: 1- Site: 1- Tab management: 5+- Human handoff: 3- Wait utilities: 1- Network: 5- Diagnostics: 2@@ -178,6 +179,12 @@ PinchTab currently exposes 39 tools:- `pinchtab_cookies_set` (requires `security.allowCookies`)- `pinchtab_connect_profile`+### Human Handoff++- `pinchtab_handoff` — pause a tab (`tabId` required; `reason`, `timeoutMs` optional) so a human can finish a CAPTCHA, login or consent step; every action tool on that tab is refused with `tab_paused_handoff` until it resumes+- `pinchtab_resume` — resume the tab (`tabId` required; `status` optional). Call it only after the user confirms they finished+- `pinchtab_handoff_status` — report `paused_handoff` (with `reason`, `pausedAt`, `expiresAt`) or `active`, so an agent can watch a `timeoutMs` auto-resume without resuming itself+### Wait Utilities- `pinchtab_wait` — `for` is `ms`, `selector`, `text`, `url`, `load` or `function`, and `value` carries the condition@@ -219,7 +226,7 @@ The normal MCP browser loop is:1. Call `pinchtab_navigate` with a `url`2. Call `pinchtab_snapshot` to inspect page structure and collect refs3. Call `pinchtab_click`, `pinchtab_type`, or other action tools with structured arguments-4. Call `pinchtab_wait_*` or `pinchtab_network` when needed+4. Call `pinchtab_wait` or `pinchtab_network` when needed5. Call `pinchtab_back` to leave a dead end, or `pinchtab_reload` to retry the page`pinchtab_back`, `pinchtab_forward` and `pinchtab_reload` take an optional `tabId`diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.mdindex c3577e01..5a64b068 100644--- a/docs/reference/mcp-tools.md+++ b/docs/reference/mcp-tools.md@@ -78,6 +78,14 @@ All element-action tools accept the unified `selector` and the legacy aliases `r| `pinchtab_cookies_set` | `name`, `value` required; `url`, `domain`, `path`, `sameSite`, `secure`, `httpOnly`, `expires`, `tabId` optional | Sets one cookie for session reuse; `url` defaults to the tab's current page and an empty `value` blanks the cookie; requires `security.allowCookies` || `pinchtab_connect_profile` | `profile` required | Returns the connect URL and instance status for a profile |+## Human Handoff++| Tool | Key Parameters | Notes |+| --- | --- | --- |+| `pinchtab_handoff` | `tabId` required; `reason`, `timeoutMs` optional | Pauses the tab for a human (CAPTCHA, login, consent); action tools on it answer `409 tab_paused_handoff` until resumed; `timeoutMs` auto-resumes |+| `pinchtab_resume` | `tabId` required; `status` optional | Resumes the tab; call only after the user confirms they finished the manual step |+| `pinchtab_handoff_status` | `tabId` required | Reports `paused_handoff` with `reason`, `pausedAt` and `expiresAt`, or `active` |+## Wait Utilities| Tool | Key Parameters | Notes |diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.goindex 84819106..b78857e9 100644--- a/internal/mcp/handlers.go+++ b/internal/mcp/handlers.go@@ -54,6 +54,9 @@ func rawHandlerMap(c *Client) map[string]func(context.Context, mcp.CallToolReque"pinchtab_cookies": handleCookies(c),"pinchtab_cookies_set": handleCookiesSet(c),"pinchtab_connect_profile": handleConnectProfile(c),+ "pinchtab_handoff": handleHandoff(c),+ "pinchtab_resume": handleResume(c),+ "pinchtab_handoff_status": handleHandoffStatus(c),"pinchtab_wait": handleWait(c),diff --git a/internal/mcp/handlers_tabs.go b/internal/mcp/handlers_tabs.goindex 04572701..33707578 100644--- a/internal/mcp/handlers_tabs.go+++ b/internal/mcp/handlers_tabs.go@@ -34,6 +34,63 @@ func handleCloseTab(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.}}+func tabRoutePath(tabID, verb string) string {+ return "/tabs/" + url.PathEscape(tabID) + "/" + verb+}++func handleHandoff(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ tabID, err := r.RequireString("tabId")+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ payload := map[string]any{}+ if reason := optTrimmedString(r, "reason"); reason != "" {+ payload["reason"] = reason+ }+ if timeoutMs, ok := optInt(r, "timeoutMs"); ok {+ payload["timeoutMs"] = timeoutMs+ }+ body, code, err := c.Post(ctx, tabRoutePath(tabID, "handoff"), payload)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ return resultFromBytes(body, code)+ }+}++func handleResume(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ tabID, err := r.RequireString("tabId")+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ payload := map[string]any{}+ if status := optTrimmedString(r, "status"); status != "" {+ payload["status"] = status+ }+ body, code, err := c.Post(ctx, tabRoutePath(tabID, "resume"), payload)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ return resultFromBytes(body, code)+ }+}++func handleHandoffStatus(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ tabID, err := r.RequireString("tabId")+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ body, code, err := c.Get(ctx, tabRoutePath(tabID, "handoff"), nil)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ return resultFromBytes(body, code)+ }+}+func handleHealth(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {return func(ctx context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) {body, code, err := c.Get(ctx, "/health", nil)diff --git a/internal/mcp/handoff_tools_test.go b/internal/mcp/handoff_tools_test.gonew file mode 100644index 00000000..0677f5b3--- /dev/null+++ b/internal/mcp/handoff_tools_test.go@@ -0,0 +1,192 @@+package mcp++import (+ "context"+ "encoding/json"+ "net/http"+ "net/http/httptest"+ "os"+ "path/filepath"+ "regexp"+ "strings"+ "testing"+ "time"++ "github.com/chromedp/chromedp"+ "github.com/pinchtab/pinchtab/internal/bridge"+ "github.com/pinchtab/pinchtab/internal/config"+ "github.com/pinchtab/pinchtab/internal/handlers"+ "github.com/pinchtab/pinchtab/internal/testbrowser"+)++func decodeToolJSON(t *testing.T, name string, args map[string]any, api *httptest.Server) (map[string]any, bool) {+ t.Helper()+ result := callTool(t, name, args, api)+ text := resultText(t, result)+ if start := strings.Index(text, "{"); start > 0 {+ text = text[start:]+ }+ var body map[string]any+ if err := json.Unmarshal([]byte(text), &body); err != nil {+ t.Fatalf("%s answered non-JSON %q", name, text)+ }+ return body, result.IsError+}++func TestAnAgentRecoversFromAHandoffRefusalThroughTheMCPToolsAlone(t *testing.T) {+ page := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(`<button id="go" onclick="this.textContent='clicked'">go</button>`))+ }))+ defer page.Close()++ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(+ chromedp.DefaultExecAllocatorOptions[:],+ chromedp.ExecPath(testbrowser.Path(t)),+ chromedp.UserDataDir(testbrowser.ProfileDir(t)),+ chromedp.Flag("headless", true),+ chromedp.Flag("no-sandbox", true),+ )...)+ browserCtx, cancelBrowser := chromedp.NewContext(alloc)+ browserCtx, cancelTimeout := context.WithTimeout(browserCtx, 30*time.Second)+ defer cancelTimeout()+ defer cancelBrowser()+ defer cancelAlloc()+ if err := chromedp.Run(browserCtx); err != nil {+ t.Fatalf("start test browser: %v", err)+ }+ cfg := &config.RuntimeConfig{ActionTimeout: 10 * time.Second, DefaultBrowser: config.BrowserChrome, StateDir: t.TempDir()}+ b := bridge.New(context.Background(), browserCtx, cfg)+ tabID, _, _, err := b.CreateTab(page.URL)+ if err != nil {+ t.Fatalf("create tab: %v", err)+ }+ mux := http.NewServeMux()+ handlers.New(b, cfg, nil, nil, nil).RegisterRoutes(mux, func() {})+ api := httptest.NewServer(mux)+ defer api.Close()+ click := map[string]any{"tabId": tabID, "selector": "#go"}++ paused, isErr := decodeToolJSON(t, "pinchtab_handoff", map[string]any{"tabId": tabID, "reason": "captcha_manual"}, api)+ if isErr || paused["status"] != "paused_handoff" || paused["reason"] != "captcha_manual" {+ t.Fatalf("pinchtab_handoff = %v (error=%v), want paused_handoff with the reason", paused, isErr)+ }++ refused, isErr := decodeToolJSON(t, "pinchtab_click", click, api)+ if !isErr || refused["code"] != "tab_paused_handoff" {+ t.Fatalf("click on a paused tab = %v (error=%v), want the tab_paused_handoff refusal", refused, isErr)+ }++ status, isErr := decodeToolJSON(t, "pinchtab_handoff_status", map[string]any{"tabId": tabID}, api)+ if isErr || status["status"] != "paused_handoff" || status["reason"] != "captcha_manual" {+ t.Fatalf("pinchtab_handoff_status while paused = %v (error=%v), want paused_handoff", status, isErr)+ }++ resumed, isErr := decodeToolJSON(t, "pinchtab_resume", map[string]any{"tabId": tabID, "status": "completed"}, api)+ if isErr || resumed["status"] != "active" || resumed["resumeStatus"] != "completed" {+ t.Fatalf("pinchtab_resume = %v (error=%v), want active carrying the status note", resumed, isErr)+ }++ status, isErr = decodeToolJSON(t, "pinchtab_handoff_status", map[string]any{"tabId": tabID}, api)+ if isErr || status["status"] != "active" {+ t.Fatalf("pinchtab_handoff_status after resume = %v (error=%v), want active", status, isErr)+ }++ clicked, isErr := decodeToolJSON(t, "pinchtab_click", click, api)+ if isErr {+ t.Fatalf("click after resume refused: %v", clicked)+ }+ text := resultText(t, callTool(t, "pinchtab_get_text", map[string]any{"tabId": tabID}, api))+ if !strings.Contains(text, "clicked") {+ t.Fatalf("page text after the resumed click = %q, want the button relabelled by the click", text)+ }+}++func TestHandoffToolsRequireATabAndForwardTheirParameters(t *testing.T) {+ type seen struct {+ method, path string+ body map[string]any+ }+ var last seen+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ last = seen{method: r.Method, path: r.URL.EscapedPath(), body: map[string]any{}}+ _ = json.NewDecoder(r.Body).Decode(&last.body)+ w.Header().Set("Content-Type", "application/json")+ _, _ = w.Write([]byte(`{"tabId":"t1","status":"active"}`))+ }))+ defer srv.Close()++ for _, tc := range []struct {+ tool string+ args map[string]any+ method string+ path string+ body map[string]any+ }{+ {"pinchtab_handoff", map[string]any{"tabId": "t/1", "reason": " login_required ", "timeoutMs": float64(1500)}, http.MethodPost, "/tabs/t%2F1/handoff", map[string]any{"reason": "login_required", "timeoutMs": float64(1500)}},+ {"pinchtab_handoff", map[string]any{"tabId": "t1"}, http.MethodPost, "/tabs/t1/handoff", map[string]any{}},+ {"pinchtab_resume", map[string]any{"tabId": "t1", "status": "completed"}, http.MethodPost, "/tabs/t1/resume", map[string]any{"status": "completed"}},+ {"pinchtab_handoff_status", map[string]any{"tabId": "t1"}, http.MethodGet, "/tabs/t1/handoff", map[string]any{}},+ } {+ t.Run(tc.tool, func(t *testing.T) {+ last = seen{}+ if result := callTool(t, tc.tool, tc.args, srv); result.IsError {+ t.Fatalf("%s errored: %s", tc.tool, resultText(t, result))+ }+ if last.method != tc.method || last.path != tc.path {+ t.Fatalf("%s sent %s %s, want %s %s", tc.tool, last.method, last.path, tc.method, tc.path)+ }+ for k, want := range tc.body {+ if last.body[k] != want {+ t.Errorf("%s body[%s] = %v, want %v", tc.tool, k, last.body[k], want)+ }+ }+ for k := range last.body {+ if _, declared := tc.body[k]; !declared {+ t.Errorf("%s sent undeclared body field %s=%v", tc.tool, k, last.body[k])+ }+ }+ without := callTool(t, tc.tool, map[string]any{}, srv)+ if !without.IsError || last.method != tc.method {+ t.Fatalf("%s without a tabId did not refuse before forwarding", tc.tool)+ }+ })+ }+}++func TestEveryToolNameInTheAgentFacingDocsResolves(t *testing.T) {+ registered := map[string]bool{}+ for _, tool := range allTools() {+ registered[tool.Name] = true+ }+ name := regexp.MustCompile(`pinchtab_[a-z][a-z0-9_]*`)+ root := filepath.Join("..", "..")+ for _, doc := range []string{+ "docs/mcp.md",+ "docs/reference/mcp-tools.md",+ "skills/pinchtab/references/mcp.md",+ "skills/pinchtab-mcp/SKILL.md",+ } {+ data, err := os.ReadFile(filepath.Join(root, doc))+ if err != nil {+ t.Fatal(err)+ }+ found := map[string]bool{}+ for _, hit := range name.FindAllString(string(data), -1) {+ found[strings.TrimRight(hit, "_")] = true+ }+ if len(found) == 0 {+ t.Fatalf("%s names no tool; the census is checking nothing", doc)+ }+ for _, tool := range []string{"pinchtab_handoff", "pinchtab_resume", "pinchtab_handoff_status"} {+ if !found[tool] {+ t.Errorf("%s does not document %s", doc, tool)+ }+ }+ for hit := range found {+ if !registered[hit] {+ t.Errorf("%s names %s, which is not a registered tool", doc, hit)+ }+ }+ }+}diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.goindex 74ece2ec..73ea0f61 100644--- a/internal/mcp/server_test.go+++ b/internal/mcp/server_test.go@@ -18,8 +18,8 @@ func TestNewServerRegistersAllTools(t *testing.T) {// The server should have registered all tools.// We verify by checking that NewServer doesn't panic — the panic// in NewServer fires if any tool lacks a handler.- if len(tools) != 39 {- t.Errorf("expected 39 tools, got %d — if a tool was added or removed, update this count and the totals in docs/mcp.md", len(tools))+ if len(tools) != 42 {+ t.Errorf("expected 42 tools, got %d — if a tool was added or removed, update this count and the totals in docs/mcp.md", len(tools))}}diff --git a/internal/mcp/testdata/preamble_budget.json b/internal/mcp/testdata/preamble_budget.jsonindex 4cb2c7f3..967183f7 100644--- a/internal/mcp/testdata/preamble_budget.json+++ b/internal/mcp/testdata/preamble_budget.json@@ -2,16 +2,16 @@{"surface": "mcp:allTools","minBytes": 18092,- "maxBytes": 38200,+ "maxBytes": 40000,"takenOn": "2026-09-11",- "commit": "d866267e"+ "commit": "1e7b8132"},{"surface": "skills/pinchtab-mcp/SKILL.md","minBytes": 6789,- "maxBytes": 14581,- "takenOn": "2026-09-03",- "commit": "8a12cd4a"+ "maxBytes": 15200,+ "takenOn": "2026-09-11",+ "commit": "1e7b8132"},{"surface": "skills/pinchtab/SKILL.md",diff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex e2cb5b31..1b2f7b17 100644--- a/internal/mcp/tools.go+++ b/internal/mcp/tools.go@@ -237,6 +237,21 @@ func allTools() []mcp.Tool {mcp.NewTool("pinchtab_health",mcp.WithDescription("Check PinchTab server health status"),),+ mcp.NewTool("pinchtab_handoff",+ mcp.WithDescription("Pause a tab for human handoff (a CAPTCHA, a login, a consent wall the agent must not solve). While paused every action tool on that tab is refused with tab_paused_handoff. Return control to the user, ask them to finish in the browser, then call pinchtab_resume. Other tabs are unaffected."),+ requiredTabIDParam(),+ mcp.WithString("reason", mcp.Description("Why the tab is handed off, e.g. captcha_manual or login_required (default manual_handoff)")),+ mcp.WithNumber("timeoutMs", mcp.Description("Optional auto-resume after this many milliseconds; 0 or omitted means the tab stays paused until pinchtab_resume")),+ ),+ mcp.NewTool("pinchtab_resume",+ mcp.WithDescription("Resume a tab paused for human handoff so action tools work again. Call it only after the user has confirmed they finished the manual step; check with pinchtab_handoff_status first when unsure."),+ requiredTabIDParam(),+ mcp.WithString("status", mcp.Description("Optional note recorded with the resume, e.g. completed or failed")),+ ),+ mcp.NewTool("pinchtab_handoff_status",+ mcp.WithDescription("Report a tab's handoff state: status paused_handoff with reason, pausedAt and any expiresAt while a human holds it, or status active once resumed or auto-resumed by its timeout."),+ requiredTabIDParam(),+ ),mcp.NewTool("pinchtab_cookies",mcp.WithDescription("Get cookies for the current page"),tabIDParam(),diff --git a/plugins/grok/skills/pinchtab-mcp/SKILL.md b/plugins/grok/skills/pinchtab-mcp/SKILL.mdindex 364050af..fc8d7588 100644--- a/plugins/grok/skills/pinchtab-mcp/SKILL.md+++ b/plugins/grok/skills/pinchtab-mcp/SKILL.md@@ -289,6 +289,19 @@ pinchtab_close_tab(tabId="...") # Close a specific tab---+## Human Handoff++```+pinchtab_handoff(tabId="...", reason="captcha_manual") # Pause the tab; action tools answer tab_paused_handoff+pinchtab_handoff_status(tabId="...") # paused_handoff (reason, pausedAt, expiresAt) or active+pinchtab_resume(tabId="...") # Only after the user confirms they finished+```++- When an action is refused with `tab_paused_handoff`, hand control to the user and ask them to finish in the browser.+- Resume only once the user says they are done; a `timeoutMs` handoff resumes on its own, which `pinchtab_handoff_status` shows.++---+## WaitingUse for async content (spinners, XHR, lazy-loaded elements):diff --git a/plugins/grok/skills/pinchtab/references/mcp.md b/plugins/grok/skills/pinchtab/references/mcp.mdindex 42f69cf1..fb35acca 100644--- a/plugins/grok/skills/pinchtab/references/mcp.md+++ b/plugins/grok/skills/pinchtab/references/mcp.md@@ -63,7 +63,6 @@ All tool names are prefixed with `pinchtab_`.| `pinchtab_click` | Click element by selector. Required: `selector` or legacy `ref`. Optional: `waitNav`, `mode` (`dom` or `dispatch` as a broad low-level escape hatch), `tabId`. `mode` and `humanize` are mutually exclusive. || `pinchtab_type` | Type text keystroke-by-keystroke. Required: `selector` or legacy `ref`, plus `text`. Optional: `tabId`. || `pinchtab_fill` | Fill input via JS dispatch. Required: `selector` or legacy `ref`, plus `value` — send `value=""` to clear the field (omitting it is refused). Optional: `tabId`. |-| `pinchtab_press` | Press a named key (`Enter`, `Tab`, `Escape`, etc.). Required: `key`. Optional: `tabId`. || `pinchtab_hover` | Hover over element. Required: `selector` or legacy `ref`. Optional: `tabId`. || `pinchtab_focus` | Focus an element. Required: `selector` or legacy `ref`. Optional: `tabId`. || `pinchtab_select` | Select dropdown option. Required: `selector` or legacy `ref`, plus `value`. Optional: `tabId`. |@@ -72,10 +71,7 @@ All tool names are prefixed with `pinchtab_`.### Keyboard| Tool | Description ||------|-------------|-| `pinchtab_keyboard_type` | Type text into the focused element with keystroke events. Required: `text`. Optional: `tabId`. |-| `pinchtab_keyboard_inserttext` | Insert text into the focused element without key events. Required: `text`. Optional: `tabId`. |-| `pinchtab_keydown` | Hold a key down. Required: `key`. Optional: `tabId`. |-| `pinchtab_keyup` | Release a key. Required: `key`. Optional: `tabId`. |+| `pinchtab_key` | Send keyboard input. Required: `action` (`press`, `down`, `up` need `key`; `type`, `insert` need `text`). Optional: `nodeId`, `tabId`. |### Content| Tool | Description |@@ -94,15 +90,17 @@ All tool names are prefixed with `pinchtab_`.| `pinchtab_cookies_set` | Set one cookie on the current page (session reuse). Required: `name`, `value`. Optional: `url` (defaults to the tab's current page), `domain`, `path`, `sameSite`, `secure`, `httpOnly`, `expires`, `tabId`. An empty `value` blanks the cookie. Requires `security.allowCookies: true`. || `pinchtab_connect_profile` | Return connect status for a profile. Required: `profile`. |+### Human Handoff+| Tool | Description |+|------|-------------|+| `pinchtab_handoff` | Pause a tab so the user can finish a CAPTCHA, login or consent step; action tools on it are refused with `tab_paused_handoff` until resumed. Required: `tabId`. Optional: `reason`, `timeoutMs` (auto-resume). |+| `pinchtab_resume` | Resume a paused tab. Call only after the user confirms they finished. Required: `tabId`. Optional: `status`. |+| `pinchtab_handoff_status` | Report `paused_handoff` (with `reason`, `pausedAt`, `expiresAt`) or `active`. Required: `tabId`. |+### Utility| Tool | Description ||------|-------------|-| `pinchtab_wait` | Wait N milliseconds. Required: `ms` (max 30000). |-| `pinchtab_wait_for_selector` | Wait for selector to appear or disappear. Required: `selector`. Optional: `timeout`, `state`, `tabId`. |-| `pinchtab_wait_for_text` | Wait for text to appear. Required: `text`. Optional: `timeout`, `tabId`. |-| `pinchtab_wait_for_url` | Wait for a URL glob match. Required: `url`. Optional: `timeout`, `tabId`. |-| `pinchtab_wait_for_load` | Wait for a load state. Required: `load`. Optional: `timeout`, `tabId`. |-| `pinchtab_wait_for_function` | Wait for a JavaScript expression to become truthy. Required: `fn`. Optional: `timeout`, `tabId`. |+| `pinchtab_wait` | Wait for a condition. Required: `for` (`ms`, `selector`, `text`, `url`, `load` or `function`) and `value` carrying it. Optional: `timeout`, `state`, `tabId`. |### Network| Tool | Description |@@ -110,7 +108,6 @@ All tool names are prefixed with `pinchtab_`.| `pinchtab_network` | List recent captured network requests. Optional: `tabId`, `filter`, `method`, `status`, `type`, `limit`, `bufferSize`. || `pinchtab_network_detail` | Get one request's details. Required: `requestId`. Optional: `tabId`, `body`; inspect bodies only with explicit user approval. || `pinchtab_network_clear` | Clear captured network data. Optional: `tabId`. |-| `pinchtab_network_export` | Export captured data as HAR or NDJSON file. Optional: `tabId`, `format` (har/ndjson), `body`, `filter`, `method`, `status`, `type`, `limit`. Obtain explicit approval, preserve redaction, and delete the artifact after use. Returns `{path, entries, format}`. |### Dialog| Tool | Description |diff --git a/skills/pinchtab-mcp/SKILL.md b/skills/pinchtab-mcp/SKILL.mdindex 364050af..fc8d7588 100644--- a/skills/pinchtab-mcp/SKILL.md+++ b/skills/pinchtab-mcp/SKILL.md@@ -289,6 +289,19 @@ pinchtab_close_tab(tabId="...") # Close a specific tab---+## Human Handoff++```+pinchtab_handoff(tabId="...", reason="captcha_manual") # Pause the tab; action tools answer tab_paused_handoff+pinchtab_handoff_status(tabId="...") # paused_handoff (reason, pausedAt, expiresAt) or active+pinchtab_resume(tabId="...") # Only after the user confirms they finished+```++- When an action is refused with `tab_paused_handoff`, hand control to the user and ask them to finish in the browser.+- Resume only once the user says they are done; a `timeoutMs` handoff resumes on its own, which `pinchtab_handoff_status` shows.++---+## WaitingUse for async content (spinners, XHR, lazy-loaded elements):diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.mdindex 42f69cf1..fb35acca 100644--- a/skills/pinchtab/references/mcp.md+++ b/skills/pinchtab/references/mcp.md@@ -63,7 +63,6 @@ All tool names are prefixed with `pinchtab_`.| `pinchtab_click` | Click element by selector. Required: `selector` or legacy `ref`. Optional: `waitNav`, `mode` (`dom` or `dispatch` as a broad low-level escape hatch), `tabId`. `mode` and `humanize` are mutually exclusive. || `pinchtab_type` | Type text keystroke-by-keystroke. Required: `selector` or legacy `ref`, plus `text`. Optional: `tabId`. || `pinchtab_fill` | Fill input via JS dispatch. Required: `selector` or legacy `ref`, plus `value` — send `value=""` to clear the field (omitting it is refused). Optional: `tabId`. |-| `pinchtab_press` | Press a named key (`Enter`, `Tab`, `Escape`, etc.). Required: `key`. Optional: `tabId`. || `pinchtab_hover` | Hover over element. Required: `selector` or legacy `ref`. Optional: `tabId`. || `pinchtab_focus` | Focus an element. Required: `selector` or legacy `ref`. Optional: `tabId`. || `pinchtab_select` | Select dropdown option. Required: `selector` or legacy `ref`, plus `value`. Optional: `tabId`. |@@ -72,10 +71,7 @@ All tool names are prefixed with `pinchtab_`.### Keyboard| Tool | Description ||------|-------------|-| `pinchtab_keyboard_type` | Type text into the focused element with keystroke events. Required: `text`. Optional: `tabId`. |-| `pinchtab_keyboard_inserttext` | Insert text into the focused element without key events. Required: `text`. Optional: `tabId`. |-| `pinchtab_keydown` | Hold a key down. Required: `key`. Optional: `tabId`. |-| `pinchtab_keyup` | Release a key. Required: `key`. Optional: `tabId`. |+| `pinchtab_key` | Send keyboard input. Required: `action` (`press`, `down`, `up` need `key`; `type`, `insert` need `text`). Optional: `nodeId`, `tabId`. |### Content| Tool | Description |@@ -94,15 +90,17 @@ All tool names are prefixed with `pinchtab_`.| `pinchtab_cookies_set` | Set one cookie on the current page (session reuse). Required: `name`, `value`. Optional: `url` (defaults to the tab's current page), `domain`, `path`, `sameSite`, `secure`, `httpOnly`, `expires`, `tabId`. An empty `value` blanks the cookie. Requires `security.allowCookies: true`. || `pinchtab_connect_profile` | Return connect status for a profile. Required: `profile`. |+### Human Handoff+| Tool | Description |+|------|-------------|+| `pinchtab_handoff` | Pause a tab so the user can finish a CAPTCHA, login or consent step; action tools on it are refused with `tab_paused_handoff` until resumed. Required: `tabId`. Optional: `reason`, `timeoutMs` (auto-resume). |+| `pinchtab_resume` | Resume a paused tab. Call only after the user confirms they finished. Required: `tabId`. Optional: `status`. |+| `pinchtab_handoff_status` | Report `paused_handoff` (with `reason`, `pausedAt`, `expiresAt`) or `active`. Required: `tabId`. |+### Utility| Tool | Description ||------|-------------|-| `pinchtab_wait` | Wait N milliseconds. Required: `ms` (max 30000). |-| `pinchtab_wait_for_selector` | Wait for selector to appear or disappear. Required: `selector`. Optional: `timeout`, `state`, `tabId`. |-| `pinchtab_wait_for_text` | Wait for text to appear. Required: `text`. Optional: `timeout`, `tabId`. |-| `pinchtab_wait_for_url` | Wait for a URL glob match. Required: `url`. Optional: `timeout`, `tabId`. |-| `pinchtab_wait_for_load` | Wait for a load state. Required: `load`. Optional: `timeout`, `tabId`. |-| `pinchtab_wait_for_function` | Wait for a JavaScript expression to become truthy. Required: `fn`. Optional: `timeout`, `tabId`. |+| `pinchtab_wait` | Wait for a condition. Required: `for` (`ms`, `selector`, `text`, `url`, `load` or `function`) and `value` carrying it. Optional: `timeout`, `state`, `tabId`. |### Network| Tool | Description |@@ -110,7 +108,6 @@ All tool names are prefixed with `pinchtab_`.| `pinchtab_network` | List recent captured network requests. Optional: `tabId`, `filter`, `method`, `status`, `type`, `limit`, `bufferSize`. || `pinchtab_network_detail` | Get one request's details. Required: `requestId`. Optional: `tabId`, `body`; inspect bodies only with explicit user approval. || `pinchtab_network_clear` | Clear captured network data. Optional: `tabId`. |-| `pinchtab_network_export` | Export captured data as HAR or NDJSON file. Optional: `tabId`, `format` (har/ndjson), `body`, `filter`, `method`, `status`, `type`, `limit`. Obtain explicit approval, preserve redaction, and delete the artifact after use. Returns `{path, entries, format}`. |### Dialog| Tool | Description |