High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: audit and update all build paths and architectural references
Luigi Agostib273c213b842
diff --git a/Dockerfile b/Dockerfileindex f955f80b..e8dde9a2 100644--- a/Dockerfile+++ b/Dockerfile@@ -5,7 +5,7 @@ WORKDIR /buildCOPY go.mod go.sum ./RUN go mod downloadCOPY . .-RUN go build -ldflags="-s -w" -o pinchtab .+RUN go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab# Runtime stageFROM alpine:latestdiff --git a/README.md b/README.mdindex 7b0c0a61..e5a3262e 100644--- a/README.md+++ b/README.md@@ -66,7 +66,7 @@ Your agent can clone, build, and configure Pinchtab using the [OpenClaw skill](s```bash# Build-go build -o pinchtab .+go build -o pinchtab ./cmd/pinchtab# Headless mode (default) — no window, pure automation (best for token-efficient API flows)./pinchtab@@ -360,7 +360,7 @@ go install github.com/pinchtab/pinchtab@latest# Or clone and buildgit clone https://github.com/pinchtab/pinchtab.gitcd pinchtab-go build -o pinchtab .+go build -o pinchtab ./cmd/pinchtab```## Development@@ -368,7 +368,7 @@ go build -o pinchtab .```bashgit clone https://github.com/pinchtab/pinchtab.gitcd pinchtab-go build -o pinchtab .+go build -o pinchtab ./cmd/pinchtab./pinchtab# Run tests (38 tests)diff --git a/docs/pinchtab-architecture.md b/docs/pinchtab-architecture.mdindex 47bd779a..59a07fc2 100644--- a/docs/pinchtab-architecture.md+++ b/docs/pinchtab-architecture.md@@ -22,77 +22,60 @@ The accessibility tree (a11y) is the primary interface — not screenshots, not2. **HTTP over WebSocket** — Stateless requests, no connection management for agents3. **Ref stability** — Snapshot refs (e0, e1...) are cached and reused by action endpoints4. **Self-contained** — Launches its own Chrome, manages its own state, zero config needed-5. **Internal tool** — Not a product, not a SaaS, not a platform+5. **Decoupled Architecture** — Interface-driven design for testability and maintainability-## File Structure+## Project Layout++The project follows the standard Go `internal/` pattern to ensure encapsulation and clean boundaries:```pinchtab/-├── main.go # Entry point: Chrome launch, route registration, signal handling-├── config.go # Configuration: env vars, config file, embedded assets-├── bridge.go # Bridge struct: tab management, Chrome lifecycle-├── interfaces.go # BridgeAPI interface (for test mocking)-├── handlers.go # HTTP handlers: navigate, screenshot, tabs, lock, shutdown-├── handler_snapshot.go # Snapshot handler: a11y tree fetch, format, file output-├── handler_actions.go # Action/actions handlers: click, type, press, fill, etc.-├── handler_cookies.go # Cookie get/set handlers-├── handler_stealth.go # Stealth status, fingerprint rotation-├── snapshot.go # A11y tree parsing: CDP response → flat A11yNode list-├── lock.go # Tab locking for multi-agent coordination-├── animations.go # CSS animation disabling (global + per-request)-├── human.go # Human-like interaction: bezier mouse, natural typing-├── cdp.go # Raw CDP helpers: navigate, readyState polling-├── state.go # Session persistence: save/restore tabs to disk-├── middleware.go # HTTP middleware: logging, auth token, CORS-├── stealth.js # Stealth script: light/full modes, injected via CDP-├── readability.js # Readability extraction for /text endpoint-├── welcome.html # Headed mode welcome page (🦀 branding)+├── cmd/pinchtab/ # Application entry points and CLI commands+├── internal/+│ ├── bridge/ # Core CDP logic, tab management, and state logic+│ ├── handlers/ # HTTP API handlers and middleware+│ ├── orchestrator/ # Multi-instance lifecycle and process management+│ ├── profiles/ # Chrome profile management and identity discovery+│ ├── dashboard/ # Backend logic and static assets for the web UI+│ ├── assets/ # Centralized embedded files (stealth scripts, HTML)+│ ├── human/ # Human-like interaction simulation (Bezier mouse, typing)+│ ├── config/ # Centralized configuration management+│ └── web/ # Shared HTTP and JSON utilities├── Dockerfile # Alpine + Chromium container image-└── scripts/- ├── install-autostart.sh # LaunchAgent/systemd installer- ├── launchd/ # macOS plist- └── systemd/ # Linux service unit+└── scripts/ # Deployment and automation scripts```## Core Components-### Bridge (`bridge.go`)--The central state holder. Owns the Chrome browser context, tab registry, and snapshot caches.+### Bridge (`internal/bridge`)-```go-type Bridge struct {- allocCtx context.Context // Chrome allocator context- browserCtx context.Context // Browser-level context- tabs map[string]*TabEntry // tabID → context- snapshots map[string]*refCache // tabID → last snapshot refs- mu sync.RWMutex-}-```+The central state holder. Owns the Chrome browser context, tab registry, and snapshot caches. It implements the `BridgeAPI` interface.Key responsibilities:- **Tab lifecycle** — `CreateTab`, `CloseTab`, `TabContext` (resolve "" to first tab)- **Ref caching** — Each tab's last snapshot is cached. When `/action` receives `ref: "e5"`,- it looks up the cached `backendNodeID` without re-fetching the a11y tree.-- **Thread safety** — `sync.RWMutex` protects tab and cache maps+ it looks up the cached `BackendDOMNodeID` without re-fetching the a11y tree.+- **State Logic** — Diffing snapshots and manage session persistence (`SaveState`/`RestoreState`).-### BridgeAPI Interface (`interfaces.go`)+### Orchestrator (`internal/orchestrator`)-```go-type BridgeAPI interface {- TabContext(tabID string) (ctx context.Context, resolvedID string, err error)- ListTargets() ([]*target.Info, error)- CreateTab(url string) (string, context.Context, context.CancelFunc, error)- CloseTab(tabID string) error- GetRefCache(tabID string) *refCache- SetRefCache(tabID string, cache *refCache)- DeleteRefCache(tabID string)-}-```+Manages multiple isolated browser instances. It uses a `HostRunner` interface to decouple business logic from OS process management.++Key responsibilities:+- **Instance Registry** — Tracking running instances, their ports, and statuses.+- **Process Management** — Spawning, signaling, and stopping instances.+- **Health Monitoring** — Probing instance health via HTTP.-Handlers receive `BridgeAPI`, not `*Bridge`. Tests can mock it without Chrome.+### Profiles (`internal/profiles`)-### Snapshot Pipeline (`snapshot.go`, `handler_snapshot.go`)+Handles Chrome user data directories and metadata.++Key responsibilities:+- **CRUD Operations** — Creating, importing, and resetting profiles.+- **Identity Discovery** — Parsing internal Chrome JSON files to find user identity info.+- **Activity Tracking** — Recording and analyzing agent actions per profile.++### Snapshot Pipeline (`internal/bridge/snapshot.go`)The a11y tree is Pinchtab's core abstraction. Flow:@@ -100,7 +83,7 @@ The a11y tree is Pinchtab's core abstraction. Flow:Chrome a11y tree (CDP)│▼- Raw JSON parse (rawAXNode) ← Manual parsing to avoid cdproto crash+ Raw JSON parse (RawAXNode) ← Manual parsing to avoid cdproto crash│ on "uninteresting" PropertyName values▼Flatten to []A11yNode ← DFS walk, assign refs (e0, e1, e2...)@@ -110,282 +93,29 @@ Chrome a11y tree (CDP)└──▶ YAML ← Alternative structured format```-**A11yNode** is the universal unit:-```go-type A11yNode struct {- Ref string // "e0", "e1" — stable within snapshot- Role string // "button", "link", "textbox"- Name string // Accessible name- Depth int // Tree depth for indentation- Value string // Input values- Disabled bool- Focused bool- NodeID int64 // CDP backendNodeID (internal, for actions)-}-```-**Ref caching**: When `/snapshot` is called, the ref→nodeID mapping is stored per tab.-When `/action` receives `{"ref": "e5", "kind": "click"}`, it looks up `e5` in the cache-to find the backendNodeID. This avoids a second a11y tree fetch (which could drift).+When `/action` receives `{"ref": "e5", "kind": "click"}`, it looks up `e5` in the cache.-**Filters**:-- `?filter=interactive` — Only clickable/typeable elements (~65% token reduction)-- `?depth=3` — Limit tree depth-- `?diff=true` — Return only changes since last snapshot+### Human Interaction (`internal/human`)-### Action System (`handlers.go`)+Two main simulation engines for anti-detection:-Actions are registered in an `actionRegistry` map:--```go-var registry = map[string]actionFunc{- "click": ..., // Standard click- "type": ..., // Type text into focused element- "press": ..., // Key press (Enter, Tab, etc.)- "select": ..., // Select dropdown option- "hover": ..., // Mouse hover- "scroll": ..., // Scroll viewport- "humanClick": ..., // Bezier-curve mouse movement + click- "humanType": ..., // Natural typing with variable delays-}-```--Actions resolve targets in priority order: `ref` → `selector` → `nodeId`.-Ref resolution: look up in snapshot cache → find backendNodeID → execute CDP command.--**Action chaining** (`POST /actions`): Batch multiple actions in one request.-Executes sequentially, returns results array. Saves round-trips for multi-step interactions.--### Human Interaction (`human.go`)--Two main functions for anti-detection:--**`humanMouseMove`** — Cubic bezier curve from A to B:+**`MouseMove`** — Cubic bezier curve from A to B:- Random control points for natural curvature-- Step count scales with distance (5-30 steps, capped to prevent timeout)-- Per-step jitter (±2px) and variable timing (16-24ms)+- Step count scales with distance (5-30 steps)+- Per-step jitter and variable timing-**`humanType`** — Keystroke-level simulation:+**`Type`** — Keystroke-level simulation:- Base delay: 80ms/char (40ms in fast mode)-- 5% chance of long pause ("thinking")-- 3% chance of typo → backspace → correct character-- Faster for repeated characters--### Stealth System (`stealth.js`, `handlers.go`)--Two layers:--**Layer 1: Chrome launch flags** (compile-time)-```---exclude-switches=enable-automation---disable-blink-features=AutomationControlled---disable-infobars-+ 15 more flags-```--**Layer 2: JavaScript injection** (runtime, via `AddScriptToEvaluateOnNewDocument`)-- `navigator.webdriver` → undefined-- `navigator.plugins` → 3 realistic entries-- `navigator.languages` → ['en-US', 'en']-- WebGL vendor → "Intel Inc." / "Intel Iris OpenGL Engine"-- Canvas fingerprint noise → temp canvas with pixel-level noise-- Font metrics noise → Proxy on `measureText` (width only)-- WebRTC → `iceTransportPolicy: 'relay'` (no local IP leak)-- Hardware values → seeded PRNG, consistent within session-- Timezone → configurable via `window.__pinchtab_timezone`--**Stealth status** (`GET /stealth/status`) — live-probes the browser by evaluating JS-to verify features are actually active (not hardcoded booleans).--**Fingerprint rotation** (`POST /fingerprint/rotate`) — injects UA/platform/screen/timezone-overrides via `AddScriptToEvaluateOnNewDocument` (persists across navigations).--### Navigation (`cdp.go`)--Custom `navigatePage` instead of chromedp's built-in `Navigate`:-- Uses raw `Page.navigate` CDP command-- Polls `document.readyState` until "interactive" or "complete"-- 10-second timeout prevents hangs on heavy SPAs-- Doesn't wait for full `load` event (which SPAs may never fire)--### Session Persistence (`state.go`)--On clean shutdown (SIGINT/SIGTERM):-1. Iterate all open tabs, collect URL + title-2. Write to `~/.pinchtab/sessions.json`--On startup:-1. Read `sessions.json` if it exists-2. Re-open tabs with concurrency limiting (max 3 tabs, max 2 navigations)-3. `markCleanExit()` patches Chrome prefs to suppress "didn't shut down correctly" bar--### Configuration (`config.go`)--Priority order (highest wins):-1. Environment variables (`BRIDGE_PORT`, `BRIDGE_TOKEN`, etc.)-2. Config file (`~/.pinchtab/config.json`)-3. Defaults--```go-//go:embed stealth.js-var stealthScript string--//go:embed readability.js-var readabilityJS string-```--Both JS files are compiled into the binary via Go embed.--### Middleware (`middleware.go`)--Request pipeline:-```-Request → Logging → Auth (Bearer token) → CORS → Handler → Response-```--- **Logging**: slog with method, path, status, duration-- **Auth**: Optional `BRIDGE_TOKEN` — if set, all requests need `Authorization: Bearer <token>`-- **CORS**: Permissive (localhost tool, not public)--## Data Flow--### Typical Agent Interaction--```-Agent Pinchtab Chrome- │ │ │- │ POST /navigate │ │- │ {"url": "https://..."} │ │- │ ─────────────────────────────▶│ Page.navigate │- │ │─────────────────────────────▶│- │ │ poll readyState │- │ │◀─────────────────────────────│- │ {"tabId": "AB12..."} │ │- │◀──────────────────────────────│ │- │ │ │- │ GET /snapshot?filter=interactive │- │ ─────────────────────────────▶│ Accessibility.getFullAXTree │- │ │─────────────────────────────▶│- │ │ ◀── raw AX nodes ────────── │- │ │ flatten + assign refs │- │ │ cache ref→nodeID │- │ [{"ref":"e0","role":"button",│ │- │ "name":"Sign In"}, ...] │ │- │◀──────────────────────────────│ │- │ │ │- │ POST /action │ │- │ {"ref":"e0","kind":"click"} │ │- │ ─────────────────────────────▶│ lookup e0 → nodeID 1234 │- │ │ DOM.resolveNode(1234) │- │ │ DOM.getBoxModel │- │ │ Input.dispatchMouseEvent │- │ │─────────────────────────────▶│- │ {"clicked": true} │ │- │◀──────────────────────────────│ │-```--### Typical Agent Interaction in Headed mode--In headed mode, the human sets up and validates profiles first, then the agent runs against those profiles.--```-Human Operator Dashboard (`pinchtab dashboard`) Profile Instance Agent- │ │ │ │- │ create/import profile │ │ │- │───────────────────────────▶│ │ │- │ launch profile on :9868 │ │ │- │───────────────────────────▶│ spawn `pinchtab` │ │- │ │─────────────────────────────▶│ headed Chrome │- │ manual login / 2FA │ │ │- │<──────────────────────────────────── visible browser ────────────────────────-│- │ validate state │ │ │- │ │ profile URL ready │ │- │ │─────────────┬───────────────-│ │- │ │ │ │- │ │ │ POST /navigate │- │ │ │◀──────────────────────────────────-│- │ │ │ GET /snapshot │- │ │ │◀──────────────────────────────────-│- │ │ │ POST /action │- │ │ │◀──────────────────────────────────-│-```--Key point: the dashboard coordinates profiles and lifecycle, but agents call the running profile instance (`http://localhost:<profile-port>`), not the dashboard proxy endpoint.--### Token Efficiency--| Method | ~Tokens | Use Case |-|--------|---------|----------|-| Full snapshot (JSON) | 10,500 | Initial page understanding |-| Interactive filter | 3,600 | Action planning (buttons, links, inputs) |-| `/text` (readability) | 800 | Content extraction |-| `/screenshot` | 2,000 | Visual verification |-| Diff snapshot | varies | Monitoring changes |--## API Reference--### Read Operations--| Endpoint | Method | Description |-|----------|--------|-------------|-| `/health` | GET | Server status + version |-| `/tabs` | GET | List all open tabs |-| `/snapshot` | GET | A11y tree snapshot. Params: `tabId`, `filter`, `depth`, `format`, `diff`, `output` |-| `/screenshot` | GET | JPEG screenshot. Params: `tabId`, `quality`, `output` |-| `/text` | GET | Readability-extracted text. Params: `tabId` |-| `/cookies` | GET | Get cookies for current page. Params: `tabId` |-| `/stealth/status` | GET | Live stealth feature verification |--### Write Operations--| Endpoint | Method | Description |-|----------|--------|-------------|-| `/navigate` | POST | Navigate tab to URL. Body: `{"url", "tabId", "newTab"}` |-| `/action` | POST | Execute single action. Body: `{"kind", "ref", "selector", "text", ...}` |-| `/actions` | POST | Execute action batch. Body: `[{action}, {action}, ...]` |-| `/evaluate` | POST | Run JavaScript. Body: `{"expression", "tabId"}` |-| `/tab` | POST | Tab management. Body: `{"action": "close", "tabId"}` |-| `/cookies` | POST | Set cookies. Body: `{"cookies": [...]}` |-| `/fingerprint/rotate` | POST | Rotate browser fingerprint. Body: `{"os", "browser", "screen", ...}` |--### Action Kinds--| Kind | Required Fields | Description |-|------|----------------|-------------|-| `click` | `ref` or `selector` | Standard click |-| `type` | `ref`/`selector` + `text` | Type into element |-| `press` | `key` | Keyboard press (Enter, Tab, Escape, etc.) |-| `select` | `ref`/`selector` + `values` | Select dropdown option(s) |-| `hover` | `ref` or `selector` | Mouse hover |-| `scroll` | (optional) `scrollX`, `scrollY` | Scroll viewport (default: down 800px) |-| `humanClick` | `ref` or `selector` | Click with bezier mouse movement |-| `humanType` | `ref`/`selector` + `text` | Type with natural timing + typos |--### Snapshot Formats--**JSON** (default): `GET /snapshot`-```json-[- {"ref": "e0", "role": "heading", "name": "Welcome", "depth": 0},- {"ref": "e1", "role": "button", "name": "Sign In", "depth": 1}-]-```--**Text**: `GET /snapshot?format=text`-```-heading "Welcome"- button "Sign In" [e1]- textbox "Email" [e2]-```--**YAML**: `GET /snapshot?format=yaml`+- Random long pauses ("thinking")+- Simulated typos and backspace corrections## Deployment### Binary (recommended)```bash# Build-go build -o pinchtab .+go build -o pinchtab ./cmd/pinchtab# RunBRIDGE_TOKEN=secret ./pinchtab@@ -393,52 +123,6 @@ BRIDGE_TOKEN=secret ./pinchtab### Docker```bash+docker build -t pinchtab .docker run -d -p 9867:9867 -e BRIDGE_TOKEN=secret pinchtab```--### Auto-start-```bash-# macOS-./scripts/install-autostart.sh--# Linux (systemd)-sudo cp scripts/systemd/pinchtab.service /etc/systemd/system/-sudo systemctl enable --now pinchtab-```--### Configuration-```json-// ~/.pinchtab/config.json-{- "port": "9867",- "token": "secret",- "headless": true,- "stateDir": "~/.pinchtab"-}-```--## State & Persistence--```-~/.pinchtab/-├── chrome-profile/ # Chrome user data (cookies, localStorage, etc.)-├── sessions.json # Saved tab state (written on shutdown)-├── screenshots/ # File output from ?output=file-├── snapshots/ # File output from ?output=file-└── config.json # Optional config file-```--## Security Model--Pinchtab has **no authentication by default**. When `BRIDGE_TOKEN` is set:-- All requests must include `Authorization: Bearer <token>`-- `/health` is exempt (for monitoring)--**Pinchtab gives full browser control.** Anyone with HTTP access can:-- Read any page content (cookies, passwords, session tokens)-- Navigate to any URL-- Execute arbitrary JavaScript-- Take screenshots--**Always run behind a firewall.** Bind to localhost unless you explicitly need remote access.-This is a power tool for trusted agents on a trusted machine — not a public service.diff --git a/internal/dashboard/dashboard/profiles.js b/internal/dashboard/dashboard/profiles.jsindex ec66489b..1f279f49 100644--- a/internal/dashboard/dashboard/profiles.js+++ b/internal/dashboard/dashboard/profiles.js@@ -255,7 +255,7 @@ function updateLaunchCommand() {const profilePath = profilePathRaw || '<PROFILE_PATH>';const statePath = profilePath + '/.pinchtab-state';const prefix = profilePathRaw ? '' : '# replace <PROFILE_PATH> first\n';- const cmd = '(test -x ./bin/pinchtab || go build -o ./bin/pinchtab .) && '+ const cmd = '(test -x ./bin/pinchtab || go build -o ./bin/pinchtab ./cmd/pinchtab) && '+ 'BRIDGE_PORT=' + shellQuote(port || '9868') + ' '+ 'BRIDGE_PROFILE=' + shellQuote(profilePath) + ' '+ 'BRIDGE_STATE_DIR=' + shellQuote(statePath) + ' 'diff --git a/scripts/check.sh b/scripts/check.shindex b7046802..ece5a29a 100755--- a/scripts/check.sh+++ b/scripts/check.sh@@ -41,7 +41,7 @@ fisuccess_step "Go Vet"check_step "Build"-if ! go build -o pinchtab .; then+if ! go build -o pinchtab ./cmd/pinchtab; thenerror_step "Build"fisuccess_step "Build"diff --git a/scripts/install-autostart.sh b/scripts/install-autostart.shindex 2ee18c98..5e7ee8ac 100755--- a/scripts/install-autostart.sh+++ b/scripts/install-autostart.sh@@ -11,7 +11,7 @@ if [[ "$OSTYPE" == "darwin"* ]]; thenecho "Detected macOS - using launchd"if [ ! -f "$PINCHTAB_BIN" ]; thenecho "Building pinchtab..."- (cd "$SCRIPT_DIR/.." && go build -o pinchtab .)+ (cd "$SCRIPT_DIR/.." && go build -o pinchtab ./cmd/pinchtab)fiecho "Installing pinchtab to /usr/local/bin..."sudo cp "$PINCHTAB_BIN" /usr/local/bin/pinchtab@@ -36,7 +36,7 @@ elif [[ "$OSTYPE" == "linux-gnu"* ]]; thenecho "Detected Linux - using systemd"if [ ! -f "$PINCHTAB_BIN" ]; thenecho "Building pinchtab..."- (cd "$SCRIPT_DIR/.." && go build -o pinchtab .)+ (cd "$SCRIPT_DIR/.." && go build -o pinchtab ./cmd/pinchtab)fiecho "Installing pinchtab to /usr/local/bin..."sudo cp "$PINCHTAB_BIN" /usr/local/bin/pinchtabdiff --git a/scripts/run_pinchtab.sh b/scripts/run_pinchtab.shindex b8911be7..c00c4dd5 100755--- a/scripts/run_pinchtab.sh+++ b/scripts/run_pinchtab.sh@@ -8,7 +8,7 @@ BIN_PATH="$BIN_DIR/pinchtab"mkdir -p "$BIN_DIR"cd "$ROOT_DIR"-go build -o "$BIN_PATH" .+go build -o "$BIN_PATH" ./cmd/pinchtabif [ "$#" -eq 0 ]; thenset -- dashboard