High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
refactor(skill): progressive disclosure — split SKILL.md into references (#15)
luigiagentfa052e2905c5
diff --git a/.gitignore b/.gitignoreindex 191346fe..5dedf81f 100644--- a/.gitignore+++ b/.gitignore@@ -1,6 +1,6 @@node_modules/browser-bridge-pinchtab+/pinchtabcoverage.out# OpenClaw workspace files (should never be committed)diff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.mdindex a3f2c389..d674f67d 100644--- a/skill/pinchtab/SKILL.md+++ b/skill/pinchtab/SKILL.md@@ -1,6 +1,5 @@---name: pinchtab-version: 0.6.2description: >Control a headless or headed Chrome browser via Pinchtab's HTTP API. Use for web automation,scraping, form filling, navigation, and multi-tab workflows. Pinchtab exposes the accessibility@@ -19,81 +18,12 @@ metadata:secret: trueoptional: truedescription: "Bearer auth token for Pinchtab API"- - name: BRIDGE_BIND- optional: true- description: "Bind address (default: 127.0.0.1, set 0.0.0.0 for network access)"- name: BRIDGE_PORToptional: truedescription: "HTTP port (default: 9867)"- name: BRIDGE_HEADLESSoptional: truedescription: "Run Chrome headless (true/false)"- - name: BRIDGE_PROFILE- optional: true- description: "Chrome profile directory (default: ~/.pinchtab/chrome-profile)"- - name: BRIDGE_STATE_DIR- optional: true- description: "State/session storage directory (default: ~/.pinchtab)"- - name: BRIDGE_NO_RESTORE- optional: true- description: "Skip restoring tabs from previous session (true/false)"- - name: BRIDGE_STEALTH- optional: true- description: "Stealth level: light (default, basic) or full (canvas/WebGL/font spoofing)"- - name: BRIDGE_MAX_TABS- optional: true- description: "Maximum number of open tabs (default: 20, 0 = unlimited)"- - name: BRIDGE_BLOCK_IMAGES- optional: true- description: "Block image loading for faster, lower-bandwidth browsing (true/false)"- - name: BRIDGE_BLOCK_MEDIA- optional: true- description: "Block all media: images + fonts + CSS + video (true/false)"- - name: BRIDGE_NO_ANIMATIONS- optional: true- description: "Disable CSS animations/transitions globally (true/false)"- - name: BRIDGE_TIMEZONE- optional: true- description: "Force browser timezone (IANA tz, e.g. Europe/Rome)"- - name: BRIDGE_CHROME_VERSION- optional: true- description: "Chrome version string used by fingerprint rotation profiles"- - name: CHROME_BINARY- optional: true- description: "Path to Chrome/Chromium binary (auto-detected if not set)"- - name: CHROME_FLAGS- optional: true- description: "Extra Chrome flags, space-separated"- - name: BRIDGE_CONFIG- optional: true- description: "Path to config JSON file (default: ~/.pinchtab/config.json)"- - name: BRIDGE_TIMEOUT- optional: true- description: "Action timeout in seconds (default: 15)"- - name: BRIDGE_NAV_TIMEOUT- optional: true- description: "Navigation timeout in seconds (default: 30)"- - name: CDP_URL- optional: true- description: "Connect to existing Chrome DevTools instead of launching"- - name: BRIDGE_NO_DASHBOARD- optional: true- description: "Disable dashboard/orchestrator endpoints on instance processes"- - name: PINCHTAB_AUTO_LAUNCH- optional: true- description: "Dashboard mode: auto-launch default profile instance on startup"- - name: PINCHTAB_DEFAULT_PROFILE- optional: true- description: "Dashboard mode: default profile name for auto-launch"- - name: PINCHTAB_DEFAULT_PORT- optional: true- description: "Dashboard mode: default port for auto-launched profile"- - name: PINCHTAB_HEADED- optional: true- description: "Dashboard mode: when set, auto-launched profile runs headed"- - name: PINCHTAB_DASHBOARD_URL- optional: true- description: "Base dashboard URL used by `pinchtab connect` helper"---# Pinchtab@@ -102,136 +32,21 @@ Fast, lightweight browser control for AI agents via HTTP + accessibility tree.## Setup-Start Pinchtab in one of these modes:-```bash-# Headless (default) — no UI, pure automation (lowest token cost when using /text and filtered snapshots)+# Headless (default)pinchtab &# Headed — visible Chrome for human + agent workflowsBRIDGE_HEADLESS=false pinchtab &-# Dashboard/orchestrator — profile manager + launcher, no browser in dashboard process+# Dashboard/orchestrator — profile manager + launcherpinchtab dashboard &```-Default port: `9867`. Override with `BRIDGE_PORT=9868`.-Auth: set `BRIDGE_TOKEN=<secret>` and pass `Authorization: Bearer <secret>`.--Base URL for all examples: `http://localhost:9867`--Token savings come from the API shape (`/text`, `/snapshot?filter=interactive&format=compact`), not from headless vs headed alone.+Default port: `9867`. Auth: set `BRIDGE_TOKEN=<secret>` and pass `Authorization: Bearer <secret>`.-### Headed mode definition--Headed mode means a real visible Chrome window managed by Pinchtab.--- Human can open profile(s), log in, pass 2FA/captcha, and validate page state-- Agent then calls Pinchtab HTTP APIs against that same running profile instance-- Session state persists in the profile directory, so follow-up runs reuse cookies/storage--In dashboard workflows, the dashboard process itself does not launch Chrome; it launches profile instances that run Chrome (headed or headless).--To resolve a running profile endpoint from dashboard state:--```bash-pinchtab connect <profile-name>-```--Recommended human + agent flow:--```bash-# human-pinchtab dashboard-# setup profile + launch profile instance--# agent-PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"-curl "$PINCHTAB_BASE_URL/health"-```--## Profile Management (Dashboard Mode)--When running `pinchtab dashboard`, profiles are managed via the dashboard API on port 9867.--### List profiles--```bash-curl http://localhost:9867/profiles-```--Returns array of profiles with `id`, `name`, `accountEmail`, `useWhen`, etc.--### Start a profile by ID--```bash-# Auto-allocate port (recommended)-curl -X POST http://localhost:9867/profiles/278be873adeb/start--# With specific port and headless mode-curl -X POST http://localhost:9867/profiles/278be873adeb/start \- -H 'Content-Type: application/json' \- -d '{"port": "9868", "headless": true}'--# Short alias (same behavior)-curl -X POST http://localhost:9867/start/278be873adeb-```--Returns the instance info including the allocated `port`. Use that port for all subsequent API calls (navigate, snapshot, action, etc.).--### Stop a profile by ID--```bash-curl -X POST http://localhost:9867/profiles/278be873adeb/stop--# Short alias-curl -X POST http://localhost:9867/stop/278be873adeb-```--### Check profile instance status--```bash-# By profile ID (recommended)-curl http://localhost:9867/profiles/278be873adeb/instance--# By profile name (also works)-curl http://localhost:9867/profiles/Pinchtab%20org/instance-```--### Launch by name (dashboard style)--```bash-curl -X POST http://localhost:9867/instances/launch \- -H 'Content-Type: application/json' \- -d '{"name": "work", "port": "9868"}'-```--### Typical agent flow with profiles--```bash-# 1. List profiles to find the right one-PROFILES=$(curl -s http://localhost:9867/profiles)-# Pick the profile ID you need (12-char hex, e.g. "278be873adeb")--# 2. Start the profile (auto-allocates port)-INSTANCE=$(curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/start)-PORT=$(echo $INSTANCE | jq -r .port)--# 3. Use the instance (all API calls go to the instance port)-curl -X POST http://localhost:$PORT/navigate -H 'Content-Type: application/json' \- -d '{"url": "https://mail.google.com"}'-curl http://localhost:$PORT/snapshot?maxTokens=4000--# 4. Check instance status-curl http://localhost:9867/profiles/$PROFILE_ID/instance--# 5. Stop when done-curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/stop-```--### Profile IDs--Each profile gets a stable 12-char hex ID (SHA-256 of name, truncated) stored in `profile.json`. The ID is generated at creation time and never changes. Use IDs instead of names in automation — they're URL-safe and stable.+For dashboard/profile workflows, see [references/profiles.md](references/profiles.md).+For all environment variables, see [references/env.md](references/env.md).## Core Workflow@@ -244,268 +59,32 @@ The typical agent loop:Refs (e.g. `e0`, `e5`, `e12`) are cached per tab after each snapshot — no need to re-snapshot before every action unless the page changed significantly.-## API Reference--### Navigate+### Quick examples```bash+# Navigatecurl -X POST http://localhost:9867/navigate \-H 'Content-Type: application/json' \-d '{"url": "https://example.com"}'-# With options: custom timeout, block images, open in new tab-curl -X POST http://localhost:9867/navigate \- -H 'Content-Type: application/json' \- -d '{"url": "https://example.com", "timeout": 60, "blockImages": true, "newTab": true}'-```--### Snapshot (accessibility tree)--```bash-# Full tree-curl http://localhost:9867/snapshot--# Interactive elements only (buttons, links, inputs) — much smaller-curl "http://localhost:9867/snapshot?filter=interactive"--# Limit depth-curl "http://localhost:9867/snapshot?depth=5"--# Smart diff — only changes since last snapshot (massive token savings)-curl "http://localhost:9867/snapshot?diff=true"--# Text format — indented tree, ~40-60% fewer tokens than JSON-curl "http://localhost:9867/snapshot?format=text"+# Snapshot (interactive only, compact format — best token efficiency)+curl "http://localhost:9867/snapshot?filter=interactive&format=compact"-# Compact format — one-line-per-node, 56-64% fewer tokens than JSON (recommended)-curl "http://localhost:9867/snapshot?format=compact"--# YAML format-curl "http://localhost:9867/snapshot?format=yaml"--# Scope to CSS selector (e.g. main content only)-curl "http://localhost:9867/snapshot?selector=main"--# Truncate to ~N tokens-curl "http://localhost:9867/snapshot?maxTokens=2000"--# Combine for maximum efficiency-curl "http://localhost:9867/snapshot?format=compact&selector=main&maxTokens=2000&filter=interactive"--# Disable animations before capture-curl "http://localhost:9867/snapshot?noAnimations=true"--# Write to file-curl "http://localhost:9867/snapshot?output=file&path=/tmp/snapshot.json"-```--Returns flat JSON array of nodes with `ref`, `role`, `name`, `depth`, `value`, `nodeId`.--**Token optimization**: Use `?format=compact` for best token efficiency. Add `?filter=interactive` for action-oriented tasks (~75% fewer nodes). Use `?selector=main` to scope to relevant content. Use `?maxTokens=2000` to cap output. Use `?diff=true` on multi-step workflows to see only changes. Combine all params freely.--### Act on elements--```bash-# Click by ref+# Clickcurl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "click", "ref": "e5"}'-# Type into focused element (click first, then type)-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "click", "ref": "e12"}'+# Typecurl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "type", "ref": "e12", "text": "hello world"}'-# Press a key-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "press", "key": "Enter"}'--# Focus an element-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "focus", "ref": "e3"}'--# Fill (set value directly, no keystrokes)-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "fill", "selector": "#email", "text": "[email protected]"}'--# Hover (trigger dropdowns/tooltips)-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "hover", "ref": "e8"}'--# Select dropdown option (by value or visible text)-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "select", "ref": "e10", "value": "option2"}'--# Scroll to element-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "scroll", "ref": "e20"}'--# Scroll by pixels (infinite scroll pages)-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "scroll", "scrollY": 800}'--# Click and wait for navigation (link clicks)-curl -X POST http://localhost:9867/action \- -H 'Content-Type: application/json' \- -d '{"kind": "click", "ref": "e5", "waitNav": true}'-```--### Extract text--```bash-# Readability mode (default) — strips nav/footer/ads, keeps article/main content+# Extract readable text (cheapest — ~1K tokens)curl http://localhost:9867/text--# Raw innerText (old behavior)-curl "http://localhost:9867/text?mode=raw"```-Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).--### Download files--```bash-# Download using browser session (preserves cookies, auth, stealth)-# Returns base64 JSON by default-curl "http://localhost:9867/download?url=https://site.com/report.pdf"--# Raw bytes (pipe to file)-curl "http://localhost:9867/download?url=https://site.com/image.jpg&raw=true" -o image.jpg--# Save directly to disk-curl "http://localhost:9867/download?url=https://site.com/export.csv&output=file&path=/tmp/export.csv"-```--Key use case: downloading files from authenticated sites — the browser's cookies and stealth settings are used automatically. No need to extract cookies and use curl separately.--### Upload files--```bash-# Upload a local file to a file input-curl -X POST "http://localhost:9867/upload?tabId=TAB_ID" \- -H "Content-Type: application/json" \- -d '{"selector": "input[type=file]", "paths": ["/tmp/photo.jpg"]}'--# Upload base64-encoded data-curl -X POST "http://localhost:9867/upload" \- -H "Content-Type: application/json" \- -d '{"selector": "#avatar-input", "files": ["data:image/png;base64,iVBOR..."]}'--# Combine both — local files + base64-curl -X POST "http://localhost:9867/upload" \- -H "Content-Type: application/json" \- -d '{"selector": "input[type=file]", "paths": ["/tmp/doc.pdf"], "files": ["data:image/png;base64,..."]}'-```--Sets files on `<input type=file>` elements via CDP. The browser fires `change` events as if the user picked files. Selector defaults to `input[type=file]` if omitted. Supports base64 data URLs, raw base64 strings, and local file paths.--### Screenshot--```bash-# Raw JPEG bytes-curl "http://localhost:9867/screenshot?raw=true" -o screenshot.jpg--# With quality setting (default 80)-curl "http://localhost:9867/screenshot?raw=true&quality=50" -o screenshot.jpg-```--### Evaluate JavaScript--```bash-curl -X POST http://localhost:9867/evaluate \- -H 'Content-Type: application/json' \- -d '{"expression": "document.title"}'-```--### Tab management--```bash-# List tabs-curl http://localhost:9867/tabs--# Open new tab-curl -X POST http://localhost:9867/tab \- -H 'Content-Type: application/json' \- -d '{"action": "new", "url": "https://example.com"}'--# Close tab-curl -X POST http://localhost:9867/tab \- -H 'Content-Type: application/json' \- -d '{"action": "close", "tabId": "TARGET_ID"}'-```--Multi-tab: pass `?tabId=TARGET_ID` to snapshot/screenshot/text, or `"tabId"` in POST body.--### Tab locking (multi-agent)--```bash-# Lock a tab (default 30s timeout, max 5min)-curl -X POST http://localhost:9867/tab/lock \- -H 'Content-Type: application/json' \- -d '{"tabId": "TARGET_ID", "owner": "agent-1", "timeoutSec": 60}'--# Unlock-curl -X POST http://localhost:9867/tab/unlock \- -H 'Content-Type: application/json' \- -d '{"tabId": "TARGET_ID", "owner": "agent-1"}'-```--Locked tabs show `owner` and `lockedUntil` in `/tabs`. Returns 409 on conflict.--### Batch actions--```bash-# Execute multiple actions in sequence-curl -X POST http://localhost:9867/actions \- -H 'Content-Type: application/json' \- -d '{"actions":[{"kind":"click","ref":"e3"},{"kind":"type","ref":"e3","text":"hello"},{"kind":"press","key":"Enter"}]}'--# Stop on first error (default: false, continues through all)-curl -X POST http://localhost:9867/actions \- -H 'Content-Type: application/json' \- -d '{"tabId":"TARGET_ID","actions":[...],"stopOnError":true}'-```--### Cookies--```bash-# Get cookies for current page-curl http://localhost:9867/cookies--# Set cookies-curl -X POST http://localhost:9867/cookies \- -H 'Content-Type: application/json' \- -d '{"url":"https://example.com","cookies":[{"name":"session","value":"abc123"}]}'-```--### Stealth--```bash-# Check stealth status and score-curl http://localhost:9867/stealth/status--# Rotate browser fingerprint-curl -X POST http://localhost:9867/fingerprint/rotate \- -H 'Content-Type: application/json' \- -d '{"os":"windows"}'-# os: "windows", "mac", or omit for random-```--### Health check--```bash-curl http://localhost:9867/health-```+For the full API (download, upload, screenshot, evaluate, tabs, cookies, stealth, batch actions), see [references/api.md](references/api.md).## Token Cost Guide@@ -514,58 +93,17 @@ curl http://localhost:9867/health| `/text` | ~800 | Reading page content || `/snapshot?filter=interactive` | ~3,600 | Finding buttons/links to click || `/snapshot?diff=true` | varies | Multi-step workflows (only changes) |-| `/snapshot?format=compact` | ~56-64% less | One-line-per-node, best token efficiency |-| `/snapshot?format=text` | ~40-60% less | Indented tree, cheaper than JSON |+| `/snapshot?format=compact` | ~56-64% less | One-line-per-node, best efficiency || `/snapshot` | ~10,500 | Full page understanding || `/screenshot` | ~2K (vision) | Visual verification |-**Strategy**: Start with `/snapshot?filter=interactive`. Use `?diff=true` on subsequent snapshots in multi-step tasks. Use `/text` when you only need the readable content. Use `?format=text` to cut token costs further. Use full `/snapshot` only for complete page understanding.--## Environment Variables--### Core runtime--| Var | Default | Description |-|---|---|---|-| `BRIDGE_BIND` | `127.0.0.1` | Bind address — localhost only by default. Set `0.0.0.0` for network access |-| `BRIDGE_PORT` | `9867` | HTTP port |-| `BRIDGE_HEADLESS` | `true` | Run Chrome headless |-| `BRIDGE_TOKEN` | (none) | Bearer auth token (recommended when using `BRIDGE_BIND=0.0.0.0`) |-| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile dir |-| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |-| `BRIDGE_NO_RESTORE` | `false` | Skip tab restore on startup |-| `BRIDGE_STEALTH` | `light` | Stealth level: `light` or `full` |-| `BRIDGE_MAX_TABS` | `20` | Max open tabs (0 = unlimited) |-| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |-| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |-| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions |-| `BRIDGE_TIMEZONE` | (none) | Force browser timezone (IANA tz) |-| `BRIDGE_CHROME_VERSION` | `144.0.7559.133` | Chrome version string used by fingerprint rotation |-| `CHROME_BINARY` | (auto) | Path to Chrome/Chromium binary |-| `CHROME_FLAGS` | (none) | Extra Chrome flags (space-separated) |-| `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |-| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |-| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |-| `CDP_URL` | (none) | Connect to existing Chrome DevTools |-| `BRIDGE_NO_DASHBOARD` | `false` | Disable dashboard/orchestrator endpoints on instance processes |--### Dashboard mode (`pinchtab dashboard`)--| Var | Default | Description |-|---|---|---|-| `PINCHTAB_AUTO_LAUNCH` | `false` | Auto-launch a default profile at dashboard startup |-| `PINCHTAB_DEFAULT_PROFILE` | `default` | Profile name for auto-launch |-| `PINCHTAB_DEFAULT_PORT` | `9867` | Port for auto-launched profile |-| `PINCHTAB_HEADED` | (unset) | If set, auto-launched profile is headed; unset means headless |-| `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | CLI helper base URL for `pinchtab connect` |+**Strategy**: Start with `?filter=interactive&format=compact`. Use `?diff=true` on subsequent snapshots. Use `/text` when you only need readable content. Full `/snapshot` only when needed.## Tips-- **Always pass `tabId` explicitly** when working with multiple tabs — active tab tracking can be unreliable+- **Always pass `tabId` explicitly** when working with multiple tabs- Refs are stable between snapshot and actions — no need to re-snapshot before clicking-- After navigation or major page changes, take a new snapshot to get fresh refs-- Use `filter=interactive` by default, fall back to full snapshot when needed+- After navigation or major page changes, take a new snapshot for fresh refs- Pinchtab persists sessions — tabs survive restarts (disable with `BRIDGE_NO_RESTORE=true`)- Chrome profile is persistent — cookies/logins carry over between runs-- Chrome uses its native User-Agent by default — `BRIDGE_CHROME_VERSION` only affects fingerprint rotation-- Use `BRIDGE_BLOCK_IMAGES=true` or `"blockImages": true` on navigate for read-heavy tasks — reduces bandwidth and memory+- Use `BRIDGE_BLOCK_IMAGES=true` or `"blockImages": true` on navigate for read-heavy tasksdiff --git a/skill/pinchtab/references/api.md b/skill/pinchtab/references/api.mdnew file mode 100644index 00000000..42e3b23b--- /dev/null+++ b/skill/pinchtab/references/api.md@@ -0,0 +1,231 @@+# Pinchtab API Reference++Base URL for all examples: `http://localhost:9867`++## Navigate++```bash+curl -X POST /navigate \+ -H 'Content-Type: application/json' \+ -d '{"url": "https://example.com"}'++# With options: custom timeout, block images, open in new tab+curl -X POST /navigate \+ -H 'Content-Type: application/json' \+ -d '{"url": "https://example.com", "timeout": 60, "blockImages": true, "newTab": true}'+```++## Snapshot (accessibility tree)++```bash+# Full tree+curl /snapshot++# Interactive elements only (buttons, links, inputs) — much smaller+curl "/snapshot?filter=interactive"++# Limit depth+curl "/snapshot?depth=5"++# Smart diff — only changes since last snapshot (massive token savings)+curl "/snapshot?diff=true"++# Text format — indented tree, ~40-60% fewer tokens than JSON+curl "/snapshot?format=text"++# Compact format — one-line-per-node, 56-64% fewer tokens than JSON (recommended)+curl "/snapshot?format=compact"++# YAML format+curl "/snapshot?format=yaml"++# Scope to CSS selector (e.g. main content only)+curl "/snapshot?selector=main"++# Truncate to ~N tokens+curl "/snapshot?maxTokens=2000"++# Combine for maximum efficiency+curl "/snapshot?format=compact&selector=main&maxTokens=2000&filter=interactive"++# Disable animations before capture+curl "/snapshot?noAnimations=true"++# Write to file+curl "/snapshot?output=file&path=/tmp/snapshot.json"+```++Returns flat JSON array of nodes with `ref`, `role`, `name`, `depth`, `value`, `nodeId`.++**Token optimization**: Use `?format=compact` for best token efficiency. Add `?filter=interactive` for action-oriented tasks (~75% fewer nodes). Use `?selector=main` to scope to relevant content. Use `?maxTokens=2000` to cap output. Use `?diff=true` on multi-step workflows to see only changes. Combine all params freely.++## Act on elements++```bash+# Click by ref+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "click", "ref": "e5"}'++# Type into focused element (click first, then type)+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "click", "ref": "e12"}'+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "type", "ref": "e12", "text": "hello world"}'++# Press a key+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "press", "key": "Enter"}'++# Focus an element+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "focus", "ref": "e3"}'++# Fill (set value directly, no keystrokes)+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "fill", "selector": "#email", "text": "[email protected]"}'++# Hover (trigger dropdowns/tooltips)+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "hover", "ref": "e8"}'++# Select dropdown option (by value or visible text)+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "select", "ref": "e10", "value": "option2"}'++# Scroll to element+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "scroll", "ref": "e20"}'++# Scroll by pixels (infinite scroll pages)+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "scroll", "scrollY": 800}'++# Click and wait for navigation (link clicks)+curl -X POST /action -H 'Content-Type: application/json' \+ -d '{"kind": "click", "ref": "e5", "waitNav": true}'+```++## Batch actions++```bash+# Execute multiple actions in sequence+curl -X POST /actions -H 'Content-Type: application/json' \+ -d '{"actions":[{"kind":"click","ref":"e3"},{"kind":"type","ref":"e3","text":"hello"},{"kind":"press","key":"Enter"}]}'++# Stop on first error (default: false)+curl -X POST /actions -H 'Content-Type: application/json' \+ -d '{"tabId":"TARGET_ID","actions":[...],"stopOnError":true}'+```++## Extract text++```bash+# Readability mode (default) — strips nav/footer/ads+curl /text++# Raw innerText+curl "/text?mode=raw"+```++Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).++## Download files++```bash+# Returns base64 JSON by default (uses browser session/cookies/stealth)+curl "/download?url=https://site.com/report.pdf"++# Raw bytes (pipe to file)+curl "/download?url=https://site.com/image.jpg&raw=true" -o image.jpg++# Save directly to disk+curl "/download?url=https://site.com/export.csv&output=file&path=/tmp/export.csv"+```++## Upload files++```bash+# Upload a local file to a file input+curl -X POST "/upload?tabId=TAB_ID" -H "Content-Type: application/json" \+ -d '{"selector": "input[type=file]", "paths": ["/tmp/photo.jpg"]}'++# Upload base64-encoded data+curl -X POST /upload -H "Content-Type: application/json" \+ -d '{"selector": "#avatar-input", "files": ["data:image/png;base64,iVBOR..."]}'+```++Sets files on `<input type=file>` elements via CDP. Fires `change` events. Selector defaults to `input[type=file]` if omitted.++## Screenshot++```bash+curl "/screenshot?raw=true" -o screenshot.jpg+curl "/screenshot?raw=true&quality=50" -o screenshot.jpg+```++## Evaluate JavaScript++```bash+curl -X POST /evaluate -H 'Content-Type: application/json' \+ -d '{"expression": "document.title"}'+```++## Tab management++```bash+# List tabs+curl /tabs++# Open new tab+curl -X POST /tab -H 'Content-Type: application/json' \+ -d '{"action": "new", "url": "https://example.com"}'++# Close tab+curl -X POST /tab -H 'Content-Type: application/json' \+ -d '{"action": "close", "tabId": "TARGET_ID"}'+```++Multi-tab: pass `?tabId=TARGET_ID` to snapshot/screenshot/text, or `"tabId"` in POST body.++## Tab locking (multi-agent)++```bash+# Lock a tab (default 30s timeout, max 5min)+curl -X POST /tab/lock -H 'Content-Type: application/json' \+ -d '{"tabId": "TARGET_ID", "owner": "agent-1", "timeoutSec": 60}'++# Unlock+curl -X POST /tab/unlock -H 'Content-Type: application/json' \+ -d '{"tabId": "TARGET_ID", "owner": "agent-1"}'+```++Locked tabs show `owner` and `lockedUntil` in `/tabs`. Returns 409 on conflict.++## Cookies++```bash+# Get cookies for current page+curl /cookies++# Set cookies+curl -X POST /cookies -H 'Content-Type: application/json' \+ -d '{"url":"https://example.com","cookies":[{"name":"session","value":"abc123"}]}'+```++## Stealth++```bash+# Check stealth status and score+curl /stealth/status++# Rotate browser fingerprint+curl -X POST /fingerprint/rotate -H 'Content-Type: application/json' \+ -d '{"os":"windows"}'+# os: "windows", "mac", or omit for random+```++## Health check++```bash+curl /health+```diff --git a/skill/pinchtab/references/env.md b/skill/pinchtab/references/env.mdnew file mode 100644index 00000000..18425ed7--- /dev/null+++ b/skill/pinchtab/references/env.md@@ -0,0 +1,37 @@+# Pinchtab Environment Variables++## Core runtime++| Var | Default | Description |+|---|---|---|+| `BRIDGE_BIND` | `127.0.0.1` | Bind address. Set `0.0.0.0` for network access |+| `BRIDGE_PORT` | `9867` | HTTP port |+| `BRIDGE_HEADLESS` | `true` | Run Chrome headless |+| `BRIDGE_TOKEN` | (none) | Bearer auth token (recommended with `0.0.0.0`) |+| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile dir |+| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |+| `BRIDGE_NO_RESTORE` | `false` | Skip tab restore on startup |+| `BRIDGE_STEALTH` | `light` | Stealth level: `light` or `full` |+| `BRIDGE_MAX_TABS` | `20` | Max open tabs (0 = unlimited) |+| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |+| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |+| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions |+| `BRIDGE_TIMEZONE` | (none) | Force browser timezone (IANA tz) |+| `BRIDGE_CHROME_VERSION` | `144.0.7559.133` | Chrome version for fingerprint rotation |+| `CHROME_BINARY` | (auto) | Path to Chrome/Chromium binary |+| `CHROME_FLAGS` | (none) | Extra Chrome flags (space-separated) |+| `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |+| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |+| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |+| `CDP_URL` | (none) | Connect to existing Chrome DevTools |+| `BRIDGE_NO_DASHBOARD` | `false` | Disable dashboard endpoints on instance processes |++## Dashboard mode (`pinchtab dashboard`)++| Var | Default | Description |+|---|---|---|+| `PINCHTAB_AUTO_LAUNCH` | `false` | Auto-launch default profile at startup |+| `PINCHTAB_DEFAULT_PROFILE` | `default` | Profile name for auto-launch |+| `PINCHTAB_DEFAULT_PORT` | `9867` | Port for auto-launched profile |+| `PINCHTAB_HEADED` | (unset) | If set, auto-launched profile is headed |+| `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | Base URL for `pinchtab connect` |diff --git a/skill/pinchtab/references/profiles.md b/skill/pinchtab/references/profiles.mdnew file mode 100644index 00000000..86167df6--- /dev/null+++ b/skill/pinchtab/references/profiles.md@@ -0,0 +1,97 @@+# Profile Management (Dashboard Mode)++When running `pinchtab dashboard`, profiles are managed via the dashboard API on port 9867.++## List profiles++```bash+curl http://localhost:9867/profiles+```++Returns array of profiles with `id`, `name`, `accountEmail`, `useWhen`, etc.++## Start a profile++```bash+# Auto-allocate port (recommended)+curl -X POST http://localhost:9867/profiles/<ID>/start++# With specific port and headless mode+curl -X POST http://localhost:9867/profiles/<ID>/start \+ -H 'Content-Type: application/json' \+ -d '{"port": "9868", "headless": true}'++# Short alias+curl -X POST http://localhost:9867/start/<ID>+```++Returns instance info including allocated `port`. Use that port for all subsequent API calls.++## Stop a profile++```bash+curl -X POST http://localhost:9867/profiles/<ID>/stop++# Short alias+curl -X POST http://localhost:9867/stop/<ID>+```++## Check instance status++```bash+# By profile ID (recommended)+curl http://localhost:9867/profiles/<ID>/instance++# By profile name+curl http://localhost:9867/profiles/My%20Profile/instance+```++## Launch by name++```bash+curl -X POST http://localhost:9867/instances/launch \+ -H 'Content-Type: application/json' \+ -d '{"name": "work", "port": "9868"}'+```++## Typical agent flow++```bash+# 1. List profiles+PROFILES=$(curl -s http://localhost:9867/profiles)++# 2. Start profile (auto-allocates port)+INSTANCE=$(curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/start)+PORT=$(echo $INSTANCE | jq -r .port)++# 3. Use the instance+curl -X POST http://localhost:$PORT/navigate -H 'Content-Type: application/json' \+ -d '{"url": "https://mail.google.com"}'+curl http://localhost:$PORT/snapshot?maxTokens=4000++# 4. Stop when done+curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/stop+```++## Profile IDs++Each profile gets a stable 12-char hex ID (SHA-256 of name, truncated) stored in `profile.json`. IDs are URL-safe and never change — use them instead of names in automation.++## Headed mode++Headed mode = real visible Chrome window managed by Pinchtab.++- Human can log in, pass 2FA/captcha, validate state+- Agent calls HTTP APIs against the same running instance+- Session state persists in profile directory (cookies/storage carry over)++Recommended human + agent flow:++```bash+# Human starts dashboard and sets up profile+pinchtab dashboard++# Agent resolves the profile endpoint+PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"+curl "$PINCHTAB_BASE_URL/health"+```