High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: general update of docs and organization for the site
Luigi Agostib5ccaaa92649
diff --git a/docs/architecture/chrome-lifecycle-and-orchestration.md b/docs/architecture/chrome-lifecycle-and-orchestration.mddeleted file mode 100644index bc84985d..00000000--- a/docs/architecture/chrome-lifecycle-and-orchestration.md+++ /dev/null@@ -1,49 +0,0 @@-# Orchestration--Pinchtab is a Go-based server and bridge system for Chrome. It doesn't just "run" a browser; it manages a fleet of isolated instances, hardened against detection and optimized for automation.--## 1. Allocator Strategy--The foundation of every managed Chrome instance is the chromedp allocator. Pinchtab primarily uses local launch:--- **Managed Launch:** the server spawns a dedicated `pinchtab bridge` child process, which uses `NewExecAllocator` to launch Chrome with a dedicated profile and port.-- **Attach:** separately, the server can register an externally managed Chrome instance through the attach API when attach policy allows it.--## 2. Hardening & Launch Flags--When launching locally, Pinchtab applies a comprehensive set of command-line flags to strip away automation markers and optimize the environment:--- **Anti-Detection:** Flags like `--exclude-switches=enable-automation` and `--disable-infobars` are used to hide the standard "automated software" banner.-- **Isolation:** Each instance is assigned its own `UserDataDir` (Profile), ensuring that cookies, local storage, and sessions are completely isolated between different "agents" or profiles.-- **Stability:** Background throttling and renderer backgrounding are disabled to prevent Chrome from "sleeping" during long-running automation tasks.--## 3. Instance Orchestration--The orchestrator handles the lifecycle of multiple independent Chrome processes:--- **Process Isolation:** Each instance runs as a separate OS process with its own PID.-- **Health Monitoring:** After launching a process, the Orchestrator polls the instance's `/health` endpoint until it is ready to accept commands.-- **Port Management:** It ensures each instance is assigned a unique port and verifies availability before launching.--## 4. Pre-Flight Stealth Injection--The most critical part of the "wrap" happens before any website is even loaded. Pinchtab performs a Pre-Flight Injection:--- **`AddScriptToEvaluateOnNewDocument`:** The `stealth.js` script is registered to execute *before* any other script on a page. This masks `navigator.webdriver` and spoofs hardware identifiers (CPU cores, memory) before a website can fingerprint the browser.-- **Environment Spoofing:** Timezone overrides and locale settings are applied immediately after startup to ensure the browser's "identity" is consistent.--## 5. Resilience & Self-Healing--Pinchtab includes logic to handle common browser startup failures:--- **Lock File Cleanup:** If Chrome previously crashed, it might leave `SingletonLock` or `SingletonSocket` files that prevent it from restarting. Pinchtab automatically detects an "unclean exit" and deletes these locks.-- **Retry Logic:** If Chrome fails to start within the `chromeStartTimeout` (15s), Pinchtab will clear the session data and attempt one retry to ensure service availability.--## 6. Tab Management--Once the browser is running, the `TabManager` (`tab_manager.go`) tracks all open targets (tabs). It provides:--- **Context Lifecycle:** Manages the creation and cancellation of Go `context.Context` objects for each tab.-- **Setup Hooks:** Automatically reapplies stealth and optimization scripts to every new tab opened by the user or by automation scripts.-- **Tab Limits:** Enforces the configured max-tab policy to prevent runaway agents from consuming all memory.-- **Stale Tab Cleanup:** Periodically removes tabs that no longer exist in Chrome.diff --git a/docs/architecture/cli-design.md b/docs/architecture/cli-design.mddeleted file mode 100644index 10002188..00000000--- a/docs/architecture/cli-design.md+++ /dev/null@@ -1,263 +0,0 @@-# CLI Design Guide--This page describes the CLI that exists today in `cmd/pinchtab/cmd_cli.go` and `cmd/pinchtab/main.go`.--## Process Modes--Pinchtab has three startup modes:--```bash-pinchtab # Start full server (default)-pinchtab server # Start full server explicitly-pinchtab bridge # Start bridge-only runtime-```--The CLI commands below are client commands. They expect a running full server unless noted otherwise.--## Core Rule--The current CLI is split into three layers:--1. startup and utility commands-2. top-level browser control commands-3. explicit instance and tab management commands--The important constraint is that the CLI does **not** support a global `--instance` flag today.--If you need to target a specific instance:-- create or inspect it with `pinchtab instance ...`-- open a tab inside it with `pinchtab instance navigate <instance-id> <url>` or the HTTP API-- then operate on the returned tab ID with `pinchtab tab ...`--## Startup And Utility Commands--These commands are handled outside the main HTTP CLI dispatcher:--```bash-pinchtab --version-pinchtab help--pinchtab config init-pinchtab config show-pinchtab config path-pinchtab config validate--pinchtab connect <profile>-pinchtab connect <profile> --json-pinchtab connect <profile> --dashboard http://localhost:9867-```--Notes:-- `connect` resolves a running profile to its bridge URL via `/profiles/{id}/instance`-- there is no CLI command for `attach` yet; attach is API-only for now--## Top-Level Browser Control--These commands talk to the server shorthand endpoints:--```bash-pinchtab nav <url>-pinchtab snap-pinchtab click <ref>-pinchtab type <ref> <text>-pinchtab fill <ref|selector> <text>-pinchtab press <key>-pinchtab hover <ref>-pinchtab scroll <ref|pixels>-pinchtab select <ref> <value>-pinchtab focus <ref>-pinchtab text-pinchtab ss-pinchtab eval <expression>-pinchtab pdf --tab <tabId>-pinchtab health-pinchtab quick <url>-```--These commands operate against the default routed tab context on the server.--Supported flags:--```bash-pinchtab nav <url> [--new-tab] [--block-images] [--block-ads]--pinchtab snap [-i|--interactive] [-c|--compact] [-d|--diff]- [-s|--selector <css>] [--max-tokens N] [--depth N] [--tab <tabId>]--pinchtab text [--raw] [--tab <tabId>]--pinchtab ss [-o|--output <file>] [-q|--quality N] [--tab <tabId>]--pinchtab pdf --tab <tabId> [-o|--output <file>] [--landscape] [--scale N]- [--paper-width N] [--paper-height N]- [--margin-top N] [--margin-bottom N]- [--margin-left N] [--margin-right N]- [--page-ranges RANGE]- [--prefer-css-page-size]- [--display-header-footer]- [--header-template HTML]- [--footer-template HTML]- [--generate-tagged-pdf]- [--generate-document-outline]- [--file-output]- [--path PATH]-```--## Instance Commands--The current instance CLI shape is:--```bash-pinchtab instances--pinchtab instance start [--profileId <id>] [--mode headed|headless] [--port <port>]-pinchtab instance launch [--profileId <id>] [--mode headed|headless] [--port <port>]--pinchtab instance navigate <instance-id> <url>--pinchtab instance logs <instance-id>-pinchtab instance logs --id <instance-id>--pinchtab instance stop <instance-id>-pinchtab instance stop --id <instance-id>-```--Important details:-- `launch` is a CLI alias for `start`-- both `start` and `launch` call `POST /instances/start` today-- there is no `pinchtab instance <id> logs` grammar-- there is no CLI subcommand for `attach`--HTTP mapping:--| CLI | HTTP |-|---|---|-| `pinchtab instances` | `GET /instances` |-| `pinchtab instance start ...` | `POST /instances/start` |-| `pinchtab instance launch ...` | `POST /instances/start` |-| `pinchtab instance navigate <id> <url>` | `POST /instances/{id}/tabs/open` then `POST /tabs/{tabId}/navigate` |-| `pinchtab instance logs <id>` | `GET /instances/{id}/logs` |-| `pinchtab instance stop <id>` | `POST /instances/{id}/stop` |--## Tab Commands--The current tab CLI has two shapes:--1. list or legacy lifecycle shortcuts-2. explicit tab operations--### List And Legacy Shortcuts--```bash-pinchtab tabs-pinchtab tab--pinchtab tabs new [url]-pinchtab tab new [url]--pinchtab tabs close <tabId>-pinchtab tab close <tabId>-```--Notes:-- `tabs` and `tab` are both accepted-- `new` and `close` use the legacy `/tab` endpoint-- `tab new` will auto-launch a default instance if none is running--### Explicit Tab Operations--The implemented grammar is:--```bash-pinchtab tab navigate <tabId> <url>-pinchtab tab snapshot <tabId> [-i] [-c] [-d]-pinchtab tab screenshot <tabId> [-o file] [-q N]-pinchtab tab click <tabId> <ref>-pinchtab tab type <tabId> <ref> <text>-pinchtab tab fill <tabId> <ref> <text>-pinchtab tab press <tabId> <key>-pinchtab tab hover <tabId> <ref>-pinchtab tab scroll <tabId> <direction|pixels>-pinchtab tab select <tabId> <ref> <value>-pinchtab tab focus <tabId> <ref>-pinchtab tab text <tabId> [--raw]-pinchtab tab eval <tabId> <expression>-pinchtab tab pdf <tabId> [-o file] [--landscape] [--scale N]-pinchtab tab cookies <tabId>-pinchtab tab lock <tabId> [--owner name] [--ttl seconds]-pinchtab tab unlock <tabId> [--owner name]-pinchtab tab locks <tabId>-pinchtab tab info <tabId>-```--Important detail:-- the operation comes before the tab ID-- the implemented syntax is `pinchtab tab screenshot <tabId>`-- it is **not** `pinchtab tab <tabId> screenshot`--## Profiles Command--The implemented profile command is:--```bash-pinchtab profiles-```--Current behavior:-- calls `GET /profiles`-- prints a simple human-friendly list of names-- does not currently expose create/update/delete operations through the CLI--## Environment--The CLI uses these environment variables:--```bash-PINCHTAB_URL # server base URL, default http://127.0.0.1:9867-PINCHTAB_TOKEN # bearer token for API requests-PINCHTAB_PORT # startup/server port-CHROME_BIN # startup Chrome binary path-```--Use `PINCHTAB_TOKEN`, not `BRIDGE_TOKEN`.--## Recommended Workflows--### Basic Top-Level Flow--```bash-pinchtab--pinchtab nav https://pinchtab.com-pinchtab snap -i -c-pinchtab click e5-pinchtab text-```--### Explicit Instance Flow--```bash-INST=$(pinchtab instance start --mode headed | jq -r '.id')--pinchtab instance navigate "$INST" https://pinchtab.com-pinchtab tabs-```--### Tab-Targeted Flow--```bash-TAB=$(pinchtab tabs | jq -r '.[0].id')--pinchtab tab snapshot "$TAB" -i -c-pinchtab tab click "$TAB" e5-pinchtab tab text "$TAB" --raw-pinchtab tab pdf "$TAB" -o page.pdf-```--## Non-Goals For This Doc--This page intentionally does not document commands that are not implemented yet, including:-- a global `--instance` flag-- `pinchtab instance attach`-- full profile CRUD through the CLI-- `pinchtab tab <tabId> <action>` grammardiff --git a/docs/architecture/cli-quick-reference.md b/docs/architecture/cli-quick-reference.mddeleted file mode 100644index 7474454e..00000000--- a/docs/architecture/cli-quick-reference.md+++ /dev/null@@ -1,198 +0,0 @@-# CLI Quick Reference--This quick reference matches the current CLI implementation on this branch.--## Startup--```bash-pinchtab-pinchtab server-pinchtab bridge-```--## Utility Commands--```bash-pinchtab --version-pinchtab help--pinchtab config init-pinchtab config show-pinchtab config path-pinchtab config validate--pinchtab connect <profile>-pinchtab connect <profile> --json-pinchtab connect <profile> --dashboard http://localhost:9867-```--## Environment--```bash-export PINCHTAB_URL=http://127.0.0.1:9867-export PINCHTAB_TOKEN=secret_token-```--Startup-related envs:--```bash-PINCHTAB_PORT=9868 pinchtab-PINCHTAB_BIND=0.0.0.0 pinchtab-CHROME_BIN=/usr/bin/google-chrome pinchtab-```--## Top-Level Browser Control--```bash-pinchtab nav https://pinchtab.com-pinchtab nav https://pinchtab.com --new-tab-pinchtab nav https://pinchtab.com --block-images --block-ads--pinchtab snap-pinchtab snap -i-pinchtab snap -i -c-pinchtab snap -d-pinchtab snap --selector 'main'-pinchtab snap --tab <tabId>--pinchtab click e5-pinchtab type e12 "hello world"-pinchtab fill e12 "value"-pinchtab fill 'input[name=email]' "[email protected]"-pinchtab press Enter-pinchtab hover e5-pinchtab scroll e5-pinchtab scroll 500-pinchtab select e7 option2-pinchtab focus e7--pinchtab text-pinchtab text --raw-pinchtab text --tab <tabId>--pinchtab ss -o out.jpg-pinchtab ss -q 85 -o out.jpg-pinchtab ss --tab <tabId> -o out.jpg--pinchtab eval "document.title"--pinchtab pdf --tab <tabId> -o page.pdf-pinchtab pdf --tab <tabId> -o page.pdf --landscape-pinchtab pdf --tab <tabId> --scale 0.9 -o page.pdf--pinchtab health-pinchtab quick https://pinchtab.com-```--## Instance Commands--```bash-pinchtab instances--pinchtab instance start-pinchtab instance start --mode headed-pinchtab instance start --profileId prof_123-pinchtab instance start --port 9999--pinchtab instance launch-pinchtab instance launch --mode headed--pinchtab instance navigate inst_abc123 https://pinchtab.com--pinchtab instance logs inst_abc123-pinchtab instance logs --id inst_abc123--pinchtab instance stop inst_abc123-pinchtab instance stop --id inst_abc123-```--Notes:-- `launch` is a CLI alias for `start`-- there is no CLI `attach` command yet-- there is no `pinchtab instance <id> logs` grammar--## Tabs--### List And Legacy Lifecycle--```bash-pinchtab tabs-pinchtab tab--pinchtab tabs new https://pinchtab.com-pinchtab tab new https://pinchtab.com--pinchtab tabs close tab_xyz789-pinchtab tab close tab_xyz789-```--### Explicit Tab Operations--```bash-pinchtab tab navigate tab_xyz789 https://google.com-pinchtab tab snapshot tab_xyz789 -i -c-pinchtab tab screenshot tab_xyz789 -o out.png-pinchtab tab click tab_xyz789 e5-pinchtab tab type tab_xyz789 e12 "hello world"-pinchtab tab fill tab_xyz789 e12 "value"-pinchtab tab press tab_xyz789 Enter-pinchtab tab hover tab_xyz789 e5-pinchtab tab scroll tab_xyz789 down-pinchtab tab scroll tab_xyz789 500-pinchtab tab select tab_xyz789 e7 option2-pinchtab tab focus tab_xyz789 e7-pinchtab tab text tab_xyz789 --raw-pinchtab tab eval tab_xyz789 "document.title"-pinchtab tab pdf tab_xyz789 -o page.pdf-pinchtab tab cookies tab_xyz789-pinchtab tab lock tab_xyz789 --owner my-agent --ttl 60-pinchtab tab unlock tab_xyz789 --owner my-agent-pinchtab tab locks tab_xyz789-pinchtab tab info tab_xyz789-```--Important:-- the implemented order is `pinchtab tab <operation> <tabId> ...`-- not `pinchtab tab <tabId> <operation>`--## Profiles--```bash-pinchtab profiles-```--Current behavior:-- lists profile names from the server-- prints human-friendly output, not a structured JSON array--## Common Flows--### Start And Drive A Page--```bash-pinchtab--pinchtab nav https://github.com/pinchtab/pinchtab-pinchtab snap -i -c-pinchtab click e5-pinchtab text --raw-```--### Launch An Instance Then Navigate It--```bash-INST=$(pinchtab instance start --mode headed | jq -r '.id')-pinchtab instance navigate "$INST" https://pinchtab.com-pinchtab tabs-```--### Work Directly With A Known Tab--```bash-TAB=tab_xyz789--pinchtab tab snapshot "$TAB" -i -c-pinchtab tab click "$TAB" e5-pinchtab tab text "$TAB" --raw-pinchtab tab pdf "$TAB" -o page.pdf-```diff --git a/docs/architecture/endpoints.md b/docs/architecture/endpoints.mddeleted file mode 100644index 1e564f25..00000000--- a/docs/architecture/endpoints.md+++ /dev/null@@ -1,827 +0,0 @@-# API Reference--Complete HTTP API reference for instances, tabs, and browser operations.--## Overview--Pinchtab uses a **server-first** API model:-- the **Pinchtab server** listens on port `9867` and manages profiles and instances-- each managed **instance** is backed by a single `pinchtab bridge` runtime-- tab operations are tab-first under `/tabs/{id}/...`-- instance lifecycle operations live under `/instances/...`-- attach is the advanced path for registering externally managed Chrome--```text-HTTP Client- │- │ All requests: http://localhost:9867- │- ↓-┌──────────────────────────────────────────┐-│ PinchTab Server (HTTP, port 9867) │-│ ┌────────────────────────────────────┐ │-│ │ - Dashboard │ │-│ │ - Instance management │ │-│ │ - Profile management │ │-│ │ - Routing to bridge runtimes │ │-│ └────────────────────────────────────┘ │-└─────┬──────────────────────────────────────┘- │- │ HTTP proxying to managed instances- │- ├─────────────────────────────────────┐- │ │- ↓ ↓-┌──────────────────┐ ┌──────────────────┐-│ Bridge Runtime 1 │ │ Bridge Runtime 2 │-│ + Chrome │ │ + Chrome │-│ profile: work │ │ profile: scraping│-├──────────────────┤ ├──────────────────┤-│ Tab 1: LinkedIn │ │ Tab 1: API │-│ Tab 2: GitHub │ │ Tab 2: Data │-│ Tab 3: Email │ └──────────────────┘-└──────────────────┘-```--## API Summary--| Category | Operations | Purpose |-|---|---|---|-| **Instance Management** | `POST /instances/start` `POST /instances/launch` `POST /instances/attach` `GET /instances` `GET /instances/{id}` `POST /instances/{id}/stop` | Create, attach, list, inspect, and stop instances |-| **Navigation** | `POST /tabs/{id}/navigate` | Navigate an existing tab by tab ID |-| **Tab Operations** | `POST /instances/{id}/tabs/open` `GET /instances/{id}/tabs` `POST /tabs/{tabId}/navigate` | Open/list tabs and navigate existing tab |-| **Page Inspection** | `GET /tabs/{id}/snapshot` `GET /tabs/{id}/text` | Get accessibility tree, extract text |-| **User Actions** | `POST /tabs/{id}/action` `POST /tabs/{id}/actions` | Click, type, fill, press, hover, focus, scroll, select |-| **JavaScript** | `POST /tabs/{id}/evaluate` | Execute JavaScript in the page |-| **Visual** | `GET /tabs/{id}/screenshot` `GET /tabs/{id}/pdf` | Take screenshot, export PDF |-| **Profiles** | `GET /profiles` `POST /profiles` | List and create browser profiles |-| **Aggregate** | `GET /tabs` | Get all tabs across all instances |-------## Base URL--```-http://127.0.0.1:9867 # PinchTab Server (all endpoints)-```--All requests go to port 9867. Instance-scoped proxy operations use `/instances/{id}/...`, while tab-first operations use `/tabs/{tabId}/...` (for example `POST /tabs/{tabId}/navigate` and `GET /tabs/{tabId}/screenshot`).-------## Instance Management API--### Launch or Start Instance--**Endpoint:**-```-POST /instances/start-POST /instances/launch-```--**Request Body:**-```json-{- "profileId": "work",- "mode": "headed"-}-```--**Parameters:**-- `profileId` (string, optional) - profile ID or name-- `name` (string, optional on `/instances/launch`) - instance/profile name when launching by name-- `mode` (string, optional) - `headless` or `headed`-- `port` (string, optional) - explicit port if you do not want auto-allocation--**Behavior:**-- Creates a managed instance record on the server-- Spawns a `pinchtab bridge` child process for managed instances-- Chrome may initialize lazily on the first browser request-- Returns instance metadata used for later tab operations--**Response (201 Created):**-```json-{- "id": "inst_0a89a5bb",- "profileId": "prof_278be873",- "profileName": "work",- "headless": false,- "status": "starting",- "port": "9868",- "startTime": "2026-02-28T18:35:18Z"-}-```--**Example (curl):**-```bash-curl -X POST http://localhost:9867/instances/launch \- -H "Content-Type: application/json" \- -d '{"name":"work","mode":"headed"}'-```--### Attach Instance--**Endpoint:**-```-POST /instances/attach-```--**Request Body:**-```json-{- "name": "shared-chrome",- "cdpUrl": "ws://127.0.0.1:9222/devtools/browser/..."-}-```--Attach is only available when enabled in config under `attach.enabled`, and the target must pass `allowHosts` and `allowSchemes` policy checks.-------### List All Instances--**Endpoint:**-```-GET /instances-```--**Response:**-```json-[- {- "id": "work-9868",- "profile": "work",- "headless": false,- "status": "running",- "port": "9868",- "startTime": "2026-02-28T18:35:18Z",- "tabs": [- {"id": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},- {"id": "tab-2", "url": "https://github.com", "title": "GitHub"}- ]- },- {- "id": "scraping-9869",- "profile": "scraping",- "headless": true,- "status": "running",- "port": "9869",- "startTime": "2026-02-28T18:35:20Z",- "tabs": [- {"id": "tab-3", "url": "https://api.pinchtab.com", "title": "API"}- ]- }-]-```--**Example (curl):**-```bash-curl http://localhost:9867/instances-```-------### Get Instance Details--**Endpoint:**-```-GET /instances/{id}-```--**Response:**-```json-{- "id": "work-9868",- "profile": "work",- "headless": false,- "status": "running",- "port": "9868",- "startTime": "2026-02-28T18:35:18Z",- "tabs": [- {"id": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},- {"id": "tab-2", "url": "https://github.com", "title": "GitHub"}- ]-}-```--**Example (curl):**-```bash-curl http://localhost:9867/instances/work-9868-```-------### Stop Instance--**Endpoint:**-```-POST /instances/{id}/stop-```--**Response:**-```json-{- "id": "inst_0a89a5bb",- "status": "stopped"-}-```--**Example (curl):**-```bash-curl -X POST http://localhost:9867/instances/inst_0a89a5bb/stop-```-------## Instance Operations--All operations target a specific instance via its ID or port.--### Open Tab (Create Tab)--**Endpoint:**-```-POST /instances/{id}/tabs/open-```--**Request Body:**-- `url` (optional) — URL to open immediately in the new tab--**Response:**-```json-{- "tabId": "tab-1",- "url": "https://pinchtab.com",- "title": "Example Domain"-}-```--**Notes:**-- **Creates a NEW tab** every time-- If `url` is provided, the new tab opens that URL-- Use `POST /tabs/{tabId}/navigate` to navigate an existing tab later--**Example (curl):**-```bash-curl -X POST http://localhost:9867/instances/work-9868/tabs/open \- -H "Content-Type: application/json" \- -d '{"url":"https://linkedin.com"}'-```--**Example (bash):**-```bash-TAB_JSON=$(curl -s -X POST http://localhost:9867/instances/work-9868/tabs/open \- -H "Content-Type: application/json" \- -d '{"url":"https://pinchtab.com"}')-TAB_ID=$(echo $TAB_JSON | jq -r '.tabId')-echo "Opened tab: $TAB_ID"-```-------### Get Instance Tabs--**Endpoint:**-```-GET /instances/{id}/tabs-```--**Response:**-```json-[- {"id": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},- {"id": "tab-2", "url": "https://github.com", "title": "GitHub"}-]-```--**Example (curl):**-```bash-curl http://localhost:9867/instances/work-9868/tabs-```-------### Navigate Existing Tab--**Endpoint:**-```-POST /tabs/{tabId}/navigate?url=<url>-```--**Query Parameters:**-- `url` (required) — URL to navigate to--**Response:**-```json-{- "tabId": "tab-1",- "url": "https://linkedin.com/login",- "title": "LinkedIn Sign In"-}-```--**Notes:**-- Navigates the **existing tab** (reuses cookies, history, etc.)-- Better for workflows that need session continuity--**Example (curl):**-```bash-curl -X POST "http://localhost:9867/tabs/tab-1/navigate?url=https://linkedin.com/login"-```-------### Get Snapshot--**Endpoint:**-```-GET /tabs/{tabId}/snapshot-```--**Query Parameters:**-- `filter` (optional) — `interactive` for buttons/links/inputs only-- `format` (optional) — `compact` or `text`-- `maxTokens` (optional) — Truncate to ~N tokens-- `depth` (optional) — Max tree depth--**Response:**-```json-{- "elements": [- {"ref": "e0", "role": "heading", "name": "LinkedIn Sign In"},- {"ref": "e1", "role": "textbox", "name": "Email or phone"},- {"ref": "e2", "role": "textbox", "name": "Password"},- {"ref": "e3", "role": "button", "name": "Sign in"}- ]-}-```--**Example (curl):**-```bash-curl "http://localhost:9867/tabs/tab-1/snapshot?filter=interactive&format=compact"-```-------### Click Element--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body:**-```json-{- "kind": "click",- "ref": "e3"-}-```--**Response:**-```json-{"success": true}-```--**Example (curl):**-```bash-curl -X POST http://localhost:9867/tabs/tab-1/action \- -H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e3"}'-```-------### Type Text--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body:**-```json-{- "kind": "type",- "ref": "e1",- "text": "[email protected]"-}-```--**Example (curl):**-```bash-curl -X POST http://localhost:9867/tabs/tab-1/action \- -H "Content-Type: application/json" \- -d '{"kind":"type","ref":"e1","text":"[email protected]"}'-```-------### Fill Input (Direct)--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body:**-```json-{- "kind": "fill",- "ref": "e1",- "text": "value"-}-```--Sets input value directly without triggering key events.-------### Press Key--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body:**-```json-{- "kind": "press",- "key": "Enter"-}-```--**Keys:** `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, etc.-------### Hover Element--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body:**-```json-{- "kind": "hover",- "ref": "e5"-}-```-------### Focus Element--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body:**-```json-{- "kind": "focus",- "ref": "e5"-}-```-------### Scroll--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body (scroll to element):**-```json-{- "kind": "scroll",- "ref": "e5"-}-```--**Request Body (scroll by pixels):**-```json-{- "kind": "scroll",- "pixels": 500-}-```-------### Select Dropdown--**Endpoint:**-```-POST /tabs/{id}/action-```--**Request Body:**-```json-{- "kind": "select",- "ref": "e7",- "value": "Option 2"-}-```-------### Extract Text--**Endpoint:**-```-GET /tabs/{id}/text-```--**Query Parameters:**-- `mode` (optional) — `raw` for raw innerText, default for readability extraction--**Response:**-```json-{- "text": "Example Domain\nThis domain is for use in examples...",- "length": 234-}-```--**Example (curl):**-```bash-curl "http://localhost:9867/tabs/tab-1/text?mode=raw"-```-------### Execute JavaScript--**Endpoint:**-```-POST /tabs/{id}/evaluate-```--**Request Body:**-```json-{- "expression": "document.title"-}-```--**Response:**-```json-{- "result": "Example Domain"-}-```--**Example (curl):**-```bash-curl -X POST http://localhost:9867/tabs/tab-1/evaluate \- -H "Content-Type: application/json" \- -d '{"expression":"document.title"}'-```-------### Take Screenshot--**Endpoint:**-```-GET /tabs/{id}/screenshot-```--**Query Parameters:**-- `quality` (optional) — JPEG quality 0-100 (default: 90)--**Response (image/jpeg):**-```-[Binary JPEG data]-```--**Example (curl):**-```bash-curl "http://localhost:9867/tabs/tab-1/screenshot?quality=85" \- -o screenshot.jpg-```-------### Export PDF--**Endpoint:**-```-GET /tabs/{id}/pdf-```--**Query Parameters:**-- `landscape` (optional) — `true` for landscape-- `paperWidth`, `paperHeight` (optional) — Paper dimensions in inches-- `marginTop`, `marginBottom`, `marginLeft`, `marginRight` (optional) — Margins in inches-- `scale` (optional) — Print scale 0.1-2.0-- `pageRanges` (optional) — Pages (e.g., "1-3,5")-- `displayHeaderFooter` (optional) — `true` to show header/footer-- `headerTemplate`, `footerTemplate` (optional) — HTML templates-- `generateTaggedPDF` (optional) — `true` for accessible PDF-- `generateDocumentOutline` (optional) — `true` for document outline-- `output` (optional) — `json` (base64) or `file` (save to disk)--**Response (application/pdf):**-```-[Binary PDF data]-```--**Example (curl):**-```bash-curl "http://localhost:9867/tabs/tab-1/pdf?landscape=true" \- -o output.pdf-```-------## Aggregate Endpoints--### Get All Tabs (Across All Instances)--**Endpoint:**-```-GET /tabs-```--**Response:**-```json-[- {"instanceId": "work-9868", "tabId": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},- {"instanceId": "work-9868", "tabId": "tab-2", "url": "https://github.com", "title": "GitHub"},- {"instanceId": "scraping-9869", "tabId": "tab-3", "url": "https://api.pinchtab.com", "title": "API"}-]-```--**Example (curl):**-```bash-curl http://localhost:9867/tabs-```-------## Complete Agent Workflow Example--### Scenario: Login to LinkedIn, visit profile, take screenshot--```bash-#!/bin/bash--BASE="http://localhost:9867"--# 1. Create instance (headed mode to see what's happening)-# This STARTS Chrome immediately with visible window-echo "Creating instance..."-INST=$(curl -s -X POST $BASE/instances \- -H "Content-Type: application/json" \- -d '{"profile":"linkedin","headless":false}')-INST_ID=$(echo $INST | jq -r '.id')-echo "Instance: $INST_ID (Chrome now running and visible)"--# 2. Navigate to LinkedIn login (creates first tab)-# Chrome is already running, navigation is fast-echo "Navigating to LinkedIn..."-NAV=$(curl -s -X POST "$BASE/instances/$INST_ID/tabs/open" \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"https://linkedin.com/login"}')-TAB_ID=$(echo $NAV | jq -r '.tabId')-echo "Tab: $TAB_ID"--# 3. Get page structure-echo "Getting page structure..."-SNAP=$(curl -s "$BASE/instances/$INST_ID/snapshot?filter=interactive&tabId=$TAB_ID")-echo $SNAP | jq '.elements[]' | head -5--# 4. Find email input (ref=e1) and type-echo "Entering email..."-curl -s -X POST "$BASE/instances/$INST_ID/action" \- -H "Content-Type: application/json" \- -d "{\"kind\":\"type\",\"ref\":\"e1\",\"text\":\"[email protected]\",\"tabId\":\"$TAB_ID\"}"--# 5. Find password input (ref=e2) and type-echo "Entering password..."-curl -s -X POST "$BASE/instances/$INST_ID/action" \- -H "Content-Type: application/json" \- -d "{\"kind\":\"type\",\"ref\":\"e2\",\"text\":\"password123\",\"tabId\":\"$TAB_ID\"}"--# 6. Find sign-in button (ref=e3) and click-echo "Clicking sign in..."-curl -s -X POST "$BASE/instances/$INST_ID/action" \- -H "Content-Type: application/json" \- -d "{\"kind\":\"click\",\"ref\":\"e3\",\"tabId\":\"$TAB_ID\"}"--# 7. Wait for page load-sleep 3--# 8. Navigate to profile (creates new tab)-echo "Navigating to profile..."-NAV2=$(curl -s -X POST "$BASE/instances/$INST_ID/tabs/open" \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"https://linkedin.com/in/myprofile"}')-TAB_ID2=$(echo $NAV2 | jq -r '.tabId')-echo "New tab: $TAB_ID2"--# 9. Take screenshot-echo "Taking screenshot..."-curl -s "$BASE/tabs/$TAB_ID2/screenshot?quality=90" \- -o profile.jpg-echo "Saved: profile.jpg"--# 10. List all tabs on instance-echo "All tabs on instance:"-curl -s "$BASE/instances/$INST_ID/tabs" | jq '.'-```-------## Error Responses--### 400 Bad Request-```json-{- "error": "invalid request body",- "details": "..."-}-```--### 401 Unauthorized-```json-{- "error": "authentication required"-}-```--### 404 Not Found-```json-{- "error": "instance not found",- "id": "unknown-9868"-}-```--### 500 Server Error-```json-{- "error": "internal server error",- "details": "..."-}-```-------## Authentication--Include Bearer token if server requires auth:--```bash-curl -H "Authorization: Bearer YOUR_TOKEN" \- http://localhost:9867/instances-```--Set via `PINCHTAB_TOKEN` when starting the server:--```bash-PINCHTAB_TOKEN=secret_token pinchtab-```-------## Key Design Principles--1. **Instance-Scoped** - All operations target a specific instance-2. **Lazy Browser Init** - Chrome starts on first request, not at instance creation-3. **Tab Creation on Navigate** - `/navigate` always creates new tabs-4. **Profile & Mode per Instance** - Each instance has its own Chrome profile and headed/headless setting-5. **Stateful Operations** - Cookies, history, and session state persist within an instance-6. **Multi-Agent Safe** - Each agent gets its own instance with isolated state-------## CLI Equivalents--Most endpoints have CLI shortcuts:--```bash-# Create instance-pinchtab instances # List all-pinchtab launch --profile work --headed # Create--# Navigate & interact-pinchtab nav https://pinchtab.com # Navigate (on default instance)-pinchtab snap # Snapshot-pinchtab click e5 # Click-pinchtab type e1 "text" # Type--# List tabs-pinchtab tabs # All tabs across instances-```--See [CLI Commands Reference](cli-commands.md) for full CLI documentation.diff --git a/docs/architecture/index.md b/docs/architecture/index.mdnew file mode 100644index 00000000..5f4e6b99--- /dev/null+++ b/docs/architecture/index.md@@ -0,0 +1,124 @@+# Architecture++PinchTab is a local HTTP control plane for Chrome aimed at agent-driven browser automation. Callers talk to PinchTab over HTTP and JSON; PinchTab translates those requests into browser work through Chrome DevTools Protocol.++## Runtime Roles++PinchTab has two runtime roles:++- **Server**: `pinchtab` or `pinchtab server`+- **Bridge**: `pinchtab bridge`++Today, the main production shape is:++- the **server** manages profiles, instances, routing, and the dashboard+- each managed instance is a separate **bridge-backed** browser runtime+- the bridge owns one browser context and serves the single-instance browser API++PinchTab also supports an advanced attach path:++- the server can register an externally managed Chrome instance through `POST /instances/attach`+- attach is policy-gated by `attach.enabled`, `attach.allowHosts`, and `attach.allowSchemes`++The current managed implementation is bridge-backed. Any direct-CDP-only managed model is architectural discussion elsewhere, not the default runtime path in this codebase.++## System Overview++```mermaid+flowchart TD+ A["Agent / CLI / HTTP Client"] --> S["PinchTab Server"]++ S --> D["Dashboard + Config + Profiles API"]+ S --> O["Orchestrator + Strategy Layer"]+ S --> Q["Optional Scheduler"]++ O --> M1["Managed Instance"]+ O --> M2["Managed Instance"]++ M1 --> B1["pinchtab bridge"]+ M2 --> B2["pinchtab bridge"]++ B1 --> C1["Chrome"]+ B2 --> C2["Chrome"]++ C1 --> T1["Tabs"]+ C2 --> T2["Tabs"]++ S -. "advanced attach path" .-> E["Registered External Chrome"]+```++## Request Flow++For the normal multi-instance server path, the flow is:++```mermaid+flowchart LR+ R["HTTP Request"] --> M["Auth + Middleware"]+ M --> P["Policy Checks"]+ P --> X["Routing / Instance Resolution"]+ X --> B["Bridge Handler"]+ B --> C["Chrome via CDP"]+ C --> O["JSON / Text / PDF / Image Response"]+```++Important details:++- auth and common middleware run at the HTTP layer+- policy checks include attach policy and, when enabled, IDPI protections+- tab-scoped routes are resolved to the owning instance before execution+- the bridge runtime performs the actual CDP work++In bridge-only mode, the orchestrator and multi-instance routing layers are skipped, but the same browser handler model still applies.++## Current Architecture++The current implementation centers on these pieces:++- **Profiles**: persistent browser state stored on disk+- **Instances**: running browser runtimes associated with profiles or external CDP URLs+- **Tabs**: the main execution surface for navigation, extraction, and actions+- **Orchestrator**: launches, tracks, stops, and proxies managed instances+- **Bridge**: owns the browser context, tab registry, ref cache, and action execution++The main instance types in practice are:++- **managed bridge-backed instances** launched by the server+- **attached external instances** registered through the attach API++## Security And Policy Layer++PinchTab's protection logic lives in the HTTP handler layer, not in the caller and not in Chrome itself.++When `security.idpi` is enabled, the current implementation can:++- block or warn on navigation targets using domain policy+- scan `/text` output for common prompt-injection patterns+- scan `/snapshot` content for the same class of patterns+- wrap `/text` output in `<untrusted_web_content>` when configured++Architecturally, this keeps policy separate from routing and execution:++```text+request -> middleware/policy -> routing -> execution -> response+```++## Design Principles++- **HTTP for callers**: agents and tools talk to PinchTab over HTTP, not raw CDP+- **A11y-first interaction**: snapshots and refs are the primary structured interface+- **Instance isolation**: managed instances run separately and keep isolated browser state+- **Tab-scoped execution**: once a tab is known, actions route to that tab's owning runtime+- **Optional coordination layers**: strategy routing and the scheduler sit above the same browser execution surface++## Code Map++The most important packages for the current architecture are:++- `cmd/pinchtab`: process startup modes and CLI entrypoints+- `internal/orchestrator`: instance lifecycle, attach, and tab-to-instance proxying+- `internal/bridge`: browser runtime, tab state, and CDP execution+- `internal/handlers`: single-instance HTTP handlers+- `internal/profiles`: persistent profile management+- `internal/strategy`: server-side routing behavior for shorthand requests+- `internal/scheduler`: optional queued task dispatch+- `internal/config`: runtime and file config loadingdiff --git a/docs/architecture/instance-charts.md b/docs/architecture/instance-charts.mdnew file mode 100644index 00000000..82778675--- /dev/null+++ b/docs/architecture/instance-charts.md@@ -0,0 +1,110 @@+# Instance Charts++This page captures the current instance model in PinchTab.++It is intentionally limited to the instance types and relationships that exist now in the codebase.++## Chart 1: Current Instance Types++```mermaid+flowchart TD+ I["Instance"] --> M["Managed"]+ I --> A["Attached"]++ M --> MB["Bridge-backed"]+ A --> EX["External Chrome registration"]+```++Current meaning:++- **managed** means PinchTab launches and owns the runtime lifecycle+- **attached** means PinchTab registers an already running external Chrome+- **bridge-backed** means the server reaches the browser through a `pinchtab bridge` runtime++## Chart 2: Managed Instance Shape++```mermaid+flowchart LR+ S["PinchTab Server"] --> O["Orchestrator"]+ O --> B["pinchtab bridge child"]+ B --> C["Chrome"]+ C --> T["Tabs"]+ O --> P["Profile directory"]+```++For managed instances today:++- the orchestrator launches a bridge child process+- the bridge owns one browser runtime+- tabs live inside that runtime+- browser state is tied to the associated profile directory++## Chart 3: Attached Instance Shape++```mermaid+flowchart LR+ S["PinchTab Server"] --> O["Orchestrator"]+ O -. "attach via CDP URL" .-> E["External Chrome"]+ E --> T["Tabs"]+```++For attached instances today:++- PinchTab does not launch the browser+- PinchTab stores registration metadata in the instance registry+- ownership of the external browser process stays outside PinchTab+- attached registration exists today, but the normal managed-instance tab proxy path is still centered on bridge-backed instances++## Chart 4: Ownership Model++```mermaid+flowchart TD+ I["Instance"] --> L["Lifecycle owner"]++ L --> P["PinchTab"]+ L --> X["External process owner"]++ P --> M["Managed instance"]+ X --> A["Attached instance"]+```++This is the key distinction:++- managed instances are lifecycle-owned by PinchTab+- attached instances are tracked by PinchTab but not process-owned by PinchTab++## Chart 5: Routing Relationship++```mermaid+flowchart TD+ I["Instance"] --> T["Tabs"]+ T --> R["Tab-scoped routes"]+ R --> O["Owning instance resolution"]+```++The important runtime rule is:++- tabs belong to one instance+- for managed bridge-backed instances, tab-scoped server routes are resolved to the owning instance before proxying++## Current Instance Fields++The main instance fields surfaced by the current API are:++- `id`+- `profileId`+- `profileName`+- `port`+- `headless`+- `status`+- `startTime`+- `error`+- `attached`+- `cdpUrl`++Useful interpretation:++- `attached: false` usually means a managed bridge-backed instance+- `attached: true` means an externally registered instance+- `port` is relevant for managed bridge-backed instances+- `cdpUrl` is relevant for attached instancesdiff --git a/docs/architecture/instance-model-charts.md b/docs/architecture/instance-model-charts.mddeleted file mode 100644index 29d80c13..00000000--- a/docs/architecture/instance-model-charts.md+++ /dev/null@@ -1,106 +0,0 @@-# Instance Model Charts--This page collects the visual mental model for Pinchtab instances.--It complements:-- [Architecture](pinchtab-architecture.md)-- [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md)--## Chart 1: Current High-Level Model--```mermaid-flowchart LR- U["User / Agent"] --> S["Pinchtab Server"]-- S --> I1["Managed Instance"]- I1 --> B["Bridge process"]- B --> C["Chrome"]- C --> T["Tabs"]-- S -. attach .-> E["External Chrome"]- E --> T2["Tabs"]-```--## Chart 2: Instance Kinds--```mermaid-flowchart TD- I["Instance"] --> K{"Kind"}-- K --> A["attached-external"]- K --> B["managed-bridge"]- K --> C["managed-direct-cdp"]- K --> D["adopted / handover"]-- A --> A1["Pinchtab did not launch browser"]- B --> B1["Pinchtab launched bridge process"]- C --> C1["Pinchtab launched browser directly"]- D --> D1["Browser was created elsewhere, then handed to server"]-```--## Chart 3: Communication Paths--```mermaid-flowchart LR- S["Pinchtab Server"]-- S -->|HTTP| B["Bridge instance"]- B -->|CDP| C1["Chrome"]-- S -->|CDP| C2["Direct-CDP instance"]-- S -->|CDP| C3["Attached external Chrome"]-```--## Chart 4: Lifecycle Ownership--```mermaid-flowchart TD- M["Instance lifecycle"] --> L1["Launch by Pinchtab"]- M --> L2["Attach existing browser"]- M --> L3["Adopt then manage"]- M --> L4["Create then hand over"]-- L1 --> X1["Pinchtab owns start/stop"]- L2 --> X2["Pinchtab routes, but may not own process"]- L3 --> X3["Pinchtab takes over ownership after attach"]- L4 --> X4["Pinchtab creates browser, then another controller owns it"]-```--## Chart 5: Recommended Taxonomy--```mermaid-flowchart TD- S["Pinchtab Server / Control Plane"]-- S --> R["Instance Registry"]-- R --> I1["managed-bridge"]- R --> I2["managed-direct-cdp"]- R --> I3["attached-external"]-- I1 --> P1["Transport: HTTP -> bridge -> CDP"]- I2 --> P2["Transport: direct CDP"]- I3 --> P3["Transport: direct CDP"]-- P1 --> T1["Tabs"]- P2 --> T2["Tabs"]- P3 --> T3["Tabs"]-```--## Recommended Reading Of These Charts--The cleanest interpretation is:--- `source` answers who introduced the instance-- `runtime` answers how Pinchtab reaches the browser-- `ownership` answers who controls lifecycle--For the current architecture, the useful combinations are:--- `managed + bridge + pinchtab`-- `attached + direct-cdp + external`--And the main future option is:--- `managed + direct-cdp + pinchtab`diff --git a/docs/architecture/orchestration.md b/docs/architecture/orchestration.mdnew file mode 100644index 00000000..0cb76165--- /dev/null+++ b/docs/architecture/orchestration.md@@ -0,0 +1,155 @@+# Orchestration++This page describes the current orchestration layer in PinchTab: how the server launches, tracks, routes to, and stops browser instances.++## Scope++The orchestrator is part of server mode. It is responsible for:++- launching managed instances as child `pinchtab bridge` processes+- attaching externally managed Chrome instances when attach policy allows it+- tracking instance status and metadata+- routing tab-scoped requests to the owning managed instance+- stopping managed instances and cleaning up registry state++It does not execute browser actions directly. That work happens inside the bridge runtime.++## Current Runtime Shape++```mermaid+flowchart TD+ S["PinchTab Server"] --> O["Orchestrator"]++ O --> M1["Managed Instance"]+ O --> M2["Managed Instance"]+ O -.->|attach| A1["Attached External Instance"]++ M1 --> B1["pinchtab bridge child"]+ M2 --> B2["pinchtab bridge child"]++ B1 --> C1["Chrome"]+ B2 --> C2["Chrome"]+```++## Launch Flow++For a managed instance, the orchestration flow is:++```mermaid+flowchart LR+ R["Start Request"] --> V["Validate profile + port"]+ V --> W["Write child config"]+ W --> P["Spawn pinchtab bridge"]+ P --> H["Poll /health on loopback addresses"]+ H --> S{"Healthy before timeout?"}+ S -->|Yes| OK["Mark running"]+ S -->|No| ER["Mark error"]+```++What the code does today:++- validates the profile name before launch+- allocates a port when one is not supplied+- prevents more than one active managed instance per profile+- prevents reusing a port already in use+- writes a child config file under the profile state directory+- launches `pinchtab bridge`+- polls `/health` on `127.0.0.1`, `::1`, and `localhost`+- moves the instance from `starting` to `running` or `error`++## Attach Flow++Attach is a separate path for an already running browser.++```mermaid+flowchart LR+ R["POST /instances/attach"] --> P["Validate attach policy"]+ P --> A["Register external instance"]+ A --> L["Add to instance registry"]+```++Current attach behavior:++- requires `attach.enabled`+- validates the CDP URL against `attach.allowSchemes`+- validates the host against `attach.allowHosts`+- registers the instance as `attached: true`+- does not start or stop an external Chrome process++## Routing Model++The orchestrator is also the routing layer for multi-instance server mode.++```mermaid+flowchart LR+ R["Tab-scoped request"] --> T["Resolve tab owner"]+ T --> C["Locator cache"]+ C -->|hit| P["Proxy to instance port"]+ C -->|miss| F["Fetch /tabs from running instances"]+ F --> P+```++Today, tab routing works like this:++- for routes such as `/tabs/{id}/navigate` and `/tabs/{id}/action`, the server resolves which instance owns the tab+- it first tries the instance locator cache+- on cache miss, it falls back to scanning running instances through `/tabs`+- after resolution, it proxies the request to the owning bridge instance++This keeps the public server API stable while the bridge instances remain isolated.++Important limitation:++- this routing path is fully shaped around managed bridge-backed instances that expose loopback HTTP ports+- attached instances are registered and surfaced in the instance registry, but the normal tab-owner proxy path is not yet equally first-class for them++## Stop Flow++Stopping a managed instance is a server-owned lifecycle operation.++```mermaid+flowchart LR+ R["Stop Request"] --> S["Mark stopping"]+ S --> G["POST /shutdown to instance"]+ G --> W{"Exited?"}+ W -->|No| T["SIGTERM"]+ T --> K{"Exited?"}+ K -->|No| X["SIGKILL"]+ W -->|Yes| D["Remove from registry"]+ K -->|Yes| D+ X --> D+```++Current stop behavior:++- marks the instance as `stopping`+- tries graceful shutdown through the instance HTTP API+- falls back to process-group termination when needed+- releases the allocated port+- removes the instance from the registry and locator cache++For attached instances, there is no child process to kill; the orchestrator only removes its own registration state.++## Instance States++The main statuses surfaced today are:++- `starting`+- `running`+- `stopping`+- `stopped`+- `error`++The orchestrator also emits lifecycle events such as:++- `instance.started`+- `instance.stopped`+- `instance.error`+- `instance.attached`++## Relationship To Other Layers++- **Strategy layer** decides how shorthand requests are exposed or routed in server mode+- **Scheduler** is optional and sits above the same routed execution path+- **Bridge** owns browser state, tab state, and CDP execution+- **Profiles** provide persistent browser data on diskdiff --git a/docs/architecture/overall-system-chart.md b/docs/architecture/overall-system-chart.mddeleted file mode 100644index 274575eb..00000000--- a/docs/architecture/overall-system-chart.md+++ /dev/null@@ -1,195 +0,0 @@-# Overall System Chart--This page gives the full mental model of Pinchtab in one place.--It combines:-- the primary user path-- the server/bridge runtime split-- managed vs attached instances-- current routing and execution-- current security layer and future scheduling layer--## Chart 1: Overall Product Shape--```mermaid-flowchart TD- U["User / Agent / Tool"] --> S["Pinchtab Server"]-- S --> D["Dashboard / Profiles / Instance API"]- S --> R["Routing / Orchestrator"]- S --> X["Shorthand Browser API"]-- R --> M1["Managed Instance"]- R --> A1["Attached Instance"]-- M1 --> B["pinchtab bridge"]- B --> C1["Chrome"]- C1 --> T1["Tabs"]-- A1 --> C2["External Chrome"]- C2 --> T2["Tabs"]-```--## Chart 2: Primary Usage Path--```mermaid-flowchart LR- I["Install Pinchtab"] --> P["Run: pinchtab"]- P --> L["Local server on localhost:9867"]- L --> A["Agent / Tool connects over HTTP"]- A --> W["Browser work happens through Pinchtab"]-```--This is the primary user journey.--The normal user should think:-- install Pinchtab-- run `pinchtab`-- point the client at `http://localhost:9867`--They should not need to think about `pinchtab bridge` directly.--## Chart 3: Runtime Types--```mermaid-flowchart TD- I["Instance"] --> S{"source"}-- S --> M["managed"]- S --> A["attached"]-- M --> R1{"runtime"}- A --> R2{"runtime"}-- R1 --> B["bridge"]- R1 --> D["direct-cdp"]-- R2 --> D2["direct-cdp"]-```--Interpretation:-- `source` = who introduced the instance-- `runtime` = how the server reaches the browser--## Chart 4: Current And Future Execution Layers--```mermaid-flowchart LR- U["Agent Request"] --> P["Policy / Security Layer"]- P --> Q["Task Scheduling Layer"]- Q --> O["Orchestrator / Routing"]- O --> E["Bridge Executor or Direct CDP"]- E --> C["Chrome Tab"]-```--Meaning:-- **Policy / Security** decides whether a request should be admitted or sanitized-- **Task Scheduling** decides when and where admitted work should run-- **Orchestrator / Routing** decides which instance/tab path is used-- **Executor** performs the actual tab work--Today:-- execution exists-- routing exists-- security exists as a real IDPI defense layer-- scheduling is still mostly direct execution plus concurrency control--## Chart 4A: Current Security Layer--```mermaid-flowchart TD- R["Request"] --> N{"Navigation?"}- N -->|Yes| D["IDPI domain policy"]- N -->|No| X["Continue"]-- D --> D2{"Allowed?"}- D2 -->|No, strict| B["Block"]- D2 -->|No, warn| W["Add warning header"]- D2 -->|Yes| X-- X --> O{"Output content?"}- O -->|Text or Snapshot| S["IDPI content scan"]- O -->|Other| E["Execute / Return"]-- S --> S2{"Threat?"}- S2 -->|No| E- S2 -->|Yes, strict| B2["Block response"]- S2 -->|Yes, warn| W2["Add warning metadata"]-- W2 --> WR{"Wrap text?"}- WR -->|Yes| WT["Wrap as untrusted_web_content"]- WR -->|No| E- WT --> E-```--Current implementation shape:--- navigation checks happen before the tab opens or re-navigates-- content scanning happens on `/text` and `/snapshot`-- text wrapping is applied to `/text` output when enabled-- strict mode blocks, warn mode annotates--## Chart 5: Current Execution Model--```mermaid-flowchart TD- H["HTTP Request"] --> O["Orchestrator / Server"]- O --> T["Target Tab"]- T --> L["Per-tab lock"]- L --> G["Global concurrency limit"]- G --> E["Execute CDP action"]-```--This is the current model already present in the product:-- per-tab sequential execution-- bounded cross-tab parallelism-- direct request execution--That means the current architecture already has:--- a **security layer** for admission and output safety-- an **execution layer** for concurrency correctness--What it does not yet have as a first-class subsystem is:--- a true **task scheduling layer** with queued work, fairness, and dispatch policy--## Chart 6: Recommended Future Model--```mermaid-flowchart TD- H["HTTP Request"] --> A["Admission"]- A --> B{"Allowed?"}- B -->|No| X["Reject"]- B -->|Yes| Q["Queue"]- Q --> S["Scheduler"]- S --> R["Instance / Tab selection"]- R --> E["Executor"]- E --> C["Chrome"]-```--This is the cleaner model for multi-agent and parallel execution:-- requests become tasks-- tasks are admitted or rejected-- admitted tasks are queued-- the scheduler chooses what runs next-- existing executors still enforce per-tab correctness--## Reading Guide--Use the charts like this:--- **Chart 1** for the product overview-- **Chart 2** for onboarding and default usage-- **Chart 3** for instance taxonomy-- **Chart 4** for control-plane layering-- **Chart 5** for how execution works today-- **Chart 6** for the likely future scheduling architecture--## Related Docs--- [Architecture](pinchtab-architecture.md)-- [Instance Model Charts](instance-model-charts.md)-- [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md)-- [Expert Guide: Attach](../guides/expert-attach.md)-- [Expert Guide: Multi-Instance Strategies](../guides/expert-strategies.md)diff --git a/docs/architecture/overview.md b/docs/architecture/overview.mddeleted file mode 100644index cc5a1984..00000000--- a/docs/architecture/overview.md+++ /dev/null@@ -1,353 +0,0 @@-# Architecture--## Overview--Pinchtab is an HTTP server that wraps Chrome DevTools Protocol (CDP) to give AI agents browser control via a simple REST API.--The product has two process roles:-- **Server** — the default `pinchtab` process that manages profiles, instances, routing, and the dashboard-- **Bridge** — the single-instance `pinchtab bridge` runtime used for one managed browser--**Managed mode (default):** the Pinchtab server launches and manages bridge-backed Chrome instances.--```-┌─────────────┐ HTTP ┌──────────────┐ CDP ┌──────────────┐-│ AI Agent │ ────────────▶ │ Pinchtab │ ─────────────▶ │ Chrome │-│ (any LLM) │ ◀──────────── │ (Go binary) │ ◀───────────── │ self-launched │-└─────────────┘ JSON/text └──────────────┘ WebSocket └──────────────┘-```--**Attach mode (advanced):** the Pinchtab server can register an externally managed Chrome instance through the instance API when attach is enabled by policy.--```-┌─────────────┐ HTTP ┌──────────────┐ CDP ┌──────────────┐-│ Multiple │ ────────────▶ │ Pinchtab │ ─────────────▶ │ External │-│ Agents │ ◀──────────── │ Server │ ◀───────────── │ Chrome │-│ │ JSON/text │ │ WebSocket │ Instance │-└─────────────┘ └──────────────┘ └──────────────┘-```--Agents never touch CDP directly. They send HTTP requests, get back JSON.-The accessibility tree (a11y) is the primary interface — not screenshots, not DOM.--## Security Layer--Pinchtab now has a real security layer for indirect prompt injection defense.--This layer lives in the server path, not inside the agent and not inside Chrome.-Its job is to inspect untrusted web input before that content is passed back to an LLM-driven caller.--Current security responsibilities:--- **domain policy on navigation** — block or warn before navigating to non-approved domains-- **content scanning on output** — scan `/text` and `/snapshot` output for common prompt-injection phrases-- **content wrapping** — wrap extracted text in `<untrusted_web_content>` delimiters with a safety advisory--The important architectural distinction is:--- **security** decides whether content should be admitted, annotated, or blocked-- **routing** decides which instance/tab path handles the request-- **execution** performs the actual browser action--In other words:--```text-request- -> security / policy- -> routing- -> execution-```--The security layer is configured through `security.idpi` in config and supports:--- `enabled`-- `allowedDomains`-- `strictMode`-- `scanContent`-- `wrapContent`-- `customPatterns`--Strict mode blocks.-Warn mode allows the request but annotates the response with an IDPI warning.--## Instance Mental Model--The cleanest way to think about instances is with two axes:--- **Source** — who created or registered the instance-- **Runtime** — how the server reaches the browser--### Chart 1: Process Roles--```text-pinchtab server- ├─ manages profiles- ├─ manages instances- ├─ routes requests- └─ serves dashboard/API--pinchtab bridge- ├─ wraps one browser- ├─ exposes single-instance HTTP API- └─ is usually spawned by the server-```--### Chart 2: Instance Taxonomy--```text-Instance- ├─ source: managed- │ ├─ runtime: bridge- │ └─ runtime: direct-cdp (possible future model)- │- └─ source: attached- └─ runtime: direct-cdp-```--This separation matters:--- `managed` means Pinchtab owns instance lifecycle-- `attached` means Pinchtab registers an already running browser-- `bridge` means the server talks HTTP to a child Pinchtab runtime-- `direct-cdp` means the server talks to Chrome over CDP directly--### Suggested Instance Schema--If you model this explicitly in the instance object, the clean shape is:--```json-{- "id": "inst_0a89a5bb",- "name": "work",- "source": "managed",- "runtime": "bridge",- "ownership": "pinchtab",- "status": "starting",- "profileId": "prof_278be873",- "profileName": "work",- "port": "9868",- "baseUrl": "http://127.0.0.1:9868",- "cdpUrl": "",- "attached": false-}-```--Recommended fields:--- `id` — stable instance identifier-- `name` — human-oriented instance/profile label-- `source` — `managed` or `attached`-- `runtime` — `bridge` or `direct-cdp`-- `ownership` — `pinchtab`, `external`, or `adopted`-- `status` — `starting`, `running`, `stopping`, `stopped`, `error`-- `profileId` / `profileName` — associated profile, when relevant-- `port` / `baseUrl` — bridge-facing address when the instance has an HTTP runtime-- `cdpUrl` — discovered or attached CDP endpoint when relevant-- `attached` — compatibility field for old clients; derivable from `source == "attached"`--In other words:--```text-source = who introduced the instance-runtime = how the server reaches it-ownership = who controls its lifecycle-```--That gives these combinations:--```text-managed + bridge + pinchtab-managed + direct-cdp + pinchtab-attached + direct-cdp + external-```--### Chart 3: Routing Paths--```text-Managed + bridge- server -> bridge -> Chrome -> tabs--Managed + direct-cdp- server -> Chrome -> tabs--Attached + direct-cdp- server -> external Chrome -> tabs-```--### Chart 4: What Lives In The Pool--```text-Pinchtab server- └─ instance pool- ├─ instance A- │ └─ tabs- ├─ instance B- │ └─ tabs- └─ instance C- └─ tabs-```--The pool contains **instances**, not tabs.-Tabs always belong to an instance.--### Current And Future Scope--Today, the intended architecture is:--- `managed + bridge` for Pinchtab-launched instances-- `attached + direct-cdp` for externally managed browsers--A plausible future expansion is:--- `managed + direct-cdp` to remove the extra HTTP hop when the server can own Chrome directly--For a focused comparison, see [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md).-For the visual version of the model, see [Instance Model Charts](instance-model-charts.md).-For the full system picture, see [Overall System Chart](overall-system-chart.md).--## Design Principles--1. **A11y tree over screenshots** — 4x cheaper in tokens, works with any LLM-2. **HTTP over WebSocket** — Stateless requests, no connection management for agents-3. **Ref stability** — Snapshot refs (e0, e1...) are cached and reused by action endpoints-4. **Self-contained by default** — Launches and manages Chrome itself unless you explicitly use attach-5. **Layered Safety** — Security policy is enforced before untrusted web content reaches downstream agents-6. **Decoupled Architecture** — Interface-driven design for testability and maintainability--## Project Layout--The project follows the standard Go `internal/` pattern to ensure encapsulation and clean boundaries:--```-pinchtab/-├── 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/ # Deployment and automation scripts-```--## Core Components--### Bridge (`internal/bridge`)--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 `BackendDOMNodeID` without re-fetching the a11y tree.-- **State Logic** — Diffing snapshots and manage session persistence (`SaveState`/`RestoreState`).--### Orchestrator (`internal/orchestrator`)--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.--### Profiles (`internal/profiles`)--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:--```-Chrome a11y tree (CDP)- │- ▼- Raw JSON parse (RawAXNode) ← Manual parsing to avoid cdproto crash- │ on "uninteresting" PropertyName values- ▼- Flatten to []A11yNode ← DFS walk, assign refs (e0, e1, e2...)- │- ├──▶ JSON (default) ← Full structured output- ├──▶ Text (indented tree) ← Low-token format for agents- └──▶ YAML ← Alternative structured format-```--**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.--### Human Interaction (`internal/human`)--Two main simulation engines for anti-detection:--**`MouseMove`** — Cubic bezier curve from A to B:-- Random control points for natural curvature-- Step count scales with distance (5-30 steps)-- Per-step jitter and variable timing--**`Type`** — Keystroke-level simulation:-- Base delay: 80ms/char (40ms in fast mode)-- Random long pauses ("thinking")-- Simulated typos and backspace corrections--## Deployment--### Binary (recommended)-```bash-# Build-go build -o pinchtab ./cmd/pinchtab--# Run-PINCHTAB_TOKEN=secret ./pinchtab-```--### Docker-```bash-docker build -t pinchtab .-docker run -d -p 9867:9867 -e PINCHTAB_TOKEN=secret pinchtab-```-------## CDP Architecture--PinchTab sits between your tools/agents and Chrome:--```text-┌─────────────────────────────────────────┐-│ Your Tool/Agent │-│ (CLI, curl, Python, Node.js, etc.) │-└──────────────┬──────────────────────────┘- │- │ HTTP- ↓-┌─────────────────────────────────────────┐-│ PinchTab HTTP Server (Go) │-│ ┌─────────────────────────────────┐ │-│ │ Tab Manager │ │-│ │ (tracks tabs + sessions) │ │-│ └─────────────────────────────────┘ │-│ ┌─────────────────────────────────┐ │-│ │ Chrome DevTools Protocol (CDP) │ │-│ └─────────────────────────────────┘ │-└──────────────┬──────────────────────────┘- │- │ CDP WebSocket- ↓-┌─────────────────────────────────────────┐-│ Chrome Browser │-│ (Headless, headed, or external) │-└─────────────────────────────────────────┘-```--PinchTab wraps Chrome's DevTools Protocol (CDP) to translate HTTP requests into CDP commands, manage browser state, and deliver structured responses (accessibility trees, screenshots, PDFs) back to your agents.diff --git a/docs/architecture/system-charts.md b/docs/architecture/system-charts.mdnew file mode 100644index 00000000..6fef3da8--- /dev/null+++ b/docs/architecture/system-charts.md@@ -0,0 +1,107 @@+# System Charts++This page collects the main high-level charts for the current PinchTab architecture.++## Chart 1: Product Shape++```mermaid+flowchart TD+ U["Agent / CLI / Tool"] --> S["PinchTab Server"]++ S --> D["Dashboard + Config + Profiles API"]+ S --> O["Orchestrator + Strategy Layer"]++ O --> M1["Managed Instance"]+ O --> M2["Managed Instance"]++ M1 --> B1["pinchtab bridge"]+ M2 --> B2["pinchtab bridge"]++ B1 --> C1["Chrome"]+ B2 --> C2["Chrome"]++ C1 --> T1["Tabs"]+ C2 --> T2["Tabs"]++ S -. "advanced attach path" .-> E["Registered External Chrome"]+```++This is the default system shape today:++- agents talk to the server over HTTP+- the server manages profiles, instances, and routing+- managed instances are bridge-backed+- attach exists as an advanced external-browser registration path++## Chart 2: Primary Usage Path++```mermaid+flowchart LR+ I["Install PinchTab"] --> R["Run: pinchtab"]+ R --> L["Local server on localhost:9867"]+ L --> A["Agent / CLI sends HTTP requests"]+ A --> W["Browser work happens through PinchTab"]+```++This is the normal mental model for users. Most users should think about `pinchtab`, not `pinchtab bridge`.++## Chart 3: Runtime Shapes++```mermaid+flowchart LR+ subgraph S1["Server Mode"]+ C1["Client"] --> P1["pinchtab server"]+ P1 --> B1["pinchtab bridge"]+ B1 --> CH1["Chrome"]+ CH1 --> T1["Tabs"]+ end++ subgraph S2["Bridge Mode"]+ C2["Client"] --> B2["pinchtab bridge"]+ B2 --> CH2["Chrome"]+ CH2 --> T2["Tabs"]+ end+```++Meaning:++- **server mode** is the multi-instance control-plane path+- **bridge mode** is the single-instance browser runtime++## Chart 4: Current Request Paths++```mermaid+flowchart TD+ R["HTTP Request"] --> M["Auth + Middleware"]+ M --> T{"Route Type"}++ T -->|Direct browser route| X["Tab / Instance Resolution"]+ T -->|Task route, when enabled| Q["Scheduler"]+ T -->|Attach route| A["Attach Policy Check"]++ Q --> X+ X --> H["Bridge Handler"]+ H --> P["Handler-Level Policy Checks"]+ P --> C["Chrome via CDP"]+ C --> O["JSON / Text / PDF / Image Response"]++ A --> AR["Register External Instance"]+```++Important details:++- auth and shared middleware run at the HTTP layer+- attach policy is enforced on the attach route in the server+- IDPI and similar browser-facing checks run in handlers such as navigation, text, and snapshot+- tab-scoped routes are resolved to the owning instance before execution+- the scheduler is optional, server-only, and applies to `/tasks`+- bridge handlers perform the actual browser work++## Reading Guide++Use the charts like this:++- **Chart 1** for the product shape+- **Chart 2** for onboarding and default usage+- **Chart 3** for the difference between server mode and bridge mode+- **Chart 4** for the current execution pathdiff --git a/docs/guides/memory-monitoring.md b/docs/guides/memory-monitoring.mdindex d6df5653..d608a5ef 100644--- a/docs/guides/memory-monitoring.md+++ b/docs/guides/memory-monitoring.md@@ -1,4 +1,4 @@-# Memory Monitoring Guide+# Memory MonitoringPinchTab exposes memory information for the Chrome processes it launches. The current implementation measures browser memory at the process level and reports browser-wide aggregates for each instance.diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.mdindex 2aa7aabd..7c8e307e 100644--- a/docs/guides/multi-instance.md+++ b/docs/guides/multi-instance.md@@ -1,4 +1,4 @@-# Multi-Instance Workflows+# Multi-InstancePinchTab can run multiple isolated Chrome instances at the same time. Each running instance has its own browser process, port, tabs, and profile-backed state.diff --git a/docs/implementations/index.md b/docs/implementations/index.mdnew file mode 100644index 00000000..400e135d--- /dev/null+++ b/docs/implementations/index.md@@ -0,0 +1,5 @@+# Implementations++This section covers implementation-focused documents: how specific subsystems work in practice, what tradeoffs they make, and how the current code is structured.++Use these pages when you want lower-level detail than the architecture overview, but do not need full API reference material.diff --git a/docs/architecture/managed-bridge-vs-managed-direct-cdp.md b/docs/implementations/managed-bridge-vs-managed-direct-cdp.mdsimilarity index 100%rename from docs/architecture/managed-bridge-vs-managed-direct-cdp.mdrename to docs/implementations/managed-bridge-vs-managed-direct-cdp.mddiff --git a/docs/architecture/parallel-tab-execution.md b/docs/implementations/parallel-tab-execution.mdsimilarity index 100%rename from docs/architecture/parallel-tab-execution.mdrename to docs/implementations/parallel-tab-execution.mddiff --git a/docs/index.json b/docs/index.jsonindex 1b2afa40..9ffd4b25 100644--- a/docs/index.json+++ b/docs/index.json@@ -18,15 +18,12 @@"guides/raspberry-pi.md"],"architecture": [- "architecture/overview.md",- "architecture/overall-system-chart.md",- "architecture/instance-model-charts.md",- "architecture/managed-bridge-vs-managed-direct-cdp.md",- "architecture/chrome-lifecycle-and-orchestration.md",- "architecture/find.md",- "architecture/scheduler.md"+ "*"],"reference": ["*"+ ],+ "implementations": [+ "*"]}