mercury-agent 0.4.5

package/examples/extensions/pinchtab/skill/references/api.md

@@ -0,0 +1,297 @@
+# Pinchtab API Reference
+
+Base URL for all examples: `http://localhost:9867`
+
+> **CLI alternative:** All endpoints have CLI equivalents. Use `pinchtab help` for the full list. Examples are shown as `# CLI:` comments below.
+
+## Navigate
+
+```bash
+# CLI: pinchtab nav https://example.com [--new-tab] [--block-images]
+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
+# CLI: pinchtab snap [-i] [-c] [-d] [-s main] [--max-tokens 2000]
+# 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
+# CLI: pinchtab click e5 / pinchtab type e12 hello / pinchtab press Enter
+# 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": "user@example.com"}'
+
+# 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
+# CLI: pinchtab text [--raw]
+# 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).
+
+## PDF export
+
+```bash
+# CLI: pinchtab pdf --tab TAB_ID [-o file.pdf] [--landscape] [--scale 0.8]
+# Returns base64 JSON
+curl "/tabs/TAB_ID/pdf"
+
+# Raw PDF bytes
+curl "/tabs/TAB_ID/pdf?raw=true" -o page.pdf
+
+# Save to disk
+curl "/tabs/TAB_ID/pdf?output=file&path=/tmp/page.pdf"
+
+# Landscape with custom scale
+curl "/tabs/TAB_ID/pdf?landscape=true&scale=0.8&raw=true" -o page.pdf
+
+# Custom paper size (Letter: 8.5x11, A4: 8.27x11.69)
+curl "/tabs/TAB_ID/pdf?paperWidth=8.5&paperHeight=11&marginTop=0.5&marginLeft=0.5&raw=true" -o custom.pdf
+
+# Export specific pages
+curl "/tabs/TAB_ID/pdf?pageRanges=1-5&raw=true" -o pages.pdf
+
+# With header/footer
+curl "/tabs/TAB_ID/pdf?displayHeaderFooter=true&headerTemplate=%3Cspan%20class=title%3E%3C/span%3E&raw=true" -o header.pdf
+
+# Accessible PDF with document outline
+curl "/tabs/TAB_ID/pdf?generateTaggedPDF=true&generateDocumentOutline=true&raw=true" -o accessible.pdf
+
+# Honor CSS page size
+curl "/tabs/TAB_ID/pdf?preferCSSPageSize=true&raw=true" -o css-sized.pdf
+```
+
+**Query Parameters:**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `paperWidth` | float | 8.5 | Paper width in inches |
+| `paperHeight` | float | 11.0 | Paper height in inches |
+| `landscape` | bool | false | Landscape orientation |
+| `marginTop` | float | 0.4 | Top margin in inches |
+| `marginBottom` | float | 0.4 | Bottom margin in inches |
+| `marginLeft` | float | 0.4 | Left margin in inches |
+| `marginRight` | float | 0.4 | Right margin in inches |
+| `scale` | float | 1.0 | Print scale (0.1–2.0) |
+| `pageRanges` | string | all | Pages to export (e.g., `1-3,5`) |
+| `displayHeaderFooter` | bool | false | Show header and footer |
+| `headerTemplate` | string | — | HTML template for header |
+| `footerTemplate` | string | — | HTML template for footer |
+| `preferCSSPageSize` | bool | false | Honor CSS `@page` size |
+| `generateTaggedPDF` | bool | false | Generate accessible/tagged PDF |
+| `generateDocumentOutline` | bool | false | Embed document outline |
+| `output` | string | JSON | `file` to save to disk, default returns base64 |
+| `path` | string | auto | Custom file path (with `output=file`) |
+| `raw` | bool | false | Return raw PDF bytes instead of JSON |
+
+Wraps `Page.printToPDF`. Prints background graphics by default.
+
+## 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
+# CLI: pinchtab ss [-o file.jpg] [-q 80]
+curl "/screenshot?raw=true" -o screenshot.jpg
+curl "/screenshot?raw=true&quality=50" -o screenshot.jpg
+```
+
+## Evaluate JavaScript
+
+```bash
+# CLI: pinchtab eval "document.title"
+curl -X POST /evaluate -H 'Content-Type: application/json' \
+  -d '{"expression": "document.title"}'
+```
+
+## Tab management
+
+```bash
+# CLI: pinchtab tabs / pinchtab tabs new <url> / pinchtab tabs close <id>
+# 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
+```

package/examples/extensions/pinchtab/skill/references/env.md

@@ -0,0 +1,45 @@
+# 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 |
+| `BRIDGE_USER_AGENT` | (none) | Custom User-Agent string; also overrides Sec-Ch-Ua client hints via CDP |
+| `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 |
+
+## CLI client
+
+| Var | Default | Description |
+|---|---|---|
+| `PINCHTAB_URL` | `http://localhost:9867` | Pinchtab server URL for CLI commands |
+| `PINCHTAB_TOKEN` | (none) | Auth token for CLI (sent as `Authorization: Bearer`) |
+
+## Dashboard (`pinchtab`)
+
+| 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` |

package/examples/extensions/pinchtab/skill/references/profiles.md

@@ -0,0 +1,107 @@
+# Profile Management
+
+When running `pinchtab`, 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"}'
+```
+
+## CLI usage with profiles
+
+The CLI doesn't have profile subcommands yet — use `curl` for profile management.
+Once a profile instance is running, point the CLI at it:
+
+```bash
+# Get the instance port, then use CLI
+PINCHTAB_URL=http://localhost:9868 pinchtab snap -i
+```
+
+## 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
+
+# Agent resolves the profile endpoint
+PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"
+curl "$PINCHTAB_BASE_URL/health"
+```

package/examples/extensions/tradestation/host/refresh.ts

@@ -0,0 +1,102 @@
+export const TRADESTATION_EXT = "tradestation" as const;
+
+type Db = {
+  getExtState(ext: string, key: string): string | null;
+  setExtState(ext: string, key: string, value: string): void;
+  deleteExtState(ext: string, key: string): boolean;
+};
+
+const TRADESTATION_TOKEN_URL = "https://signin.tradestation.com/oauth/token";
+
+export async function runTradeStationTokenRefresh(
+  db: Db,
+  log: { info(msg: string): void; warn(msg: string): void; error(msg: string): void },
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  const clientId =
+    process.env.MERCURY_TS_CLIENT_ID?.trim() ||
+    process.env.TS_CLIENT_ID?.trim() ||
+    null;
+  if (!clientId) {
+    log.warn("[ts-refresh] no client_id — skipping");
+    return;
+  }
+
+  const clientSecret = process.env.MERCURY_TS_CLIENT_SECRET?.trim() || null;
+
+  let refreshToken =
+    db.getExtState(TRADESTATION_EXT, "refresh_token") ??
+    process.env.MERCURY_TRADESTATION_REFRESH_TOKEN?.trim() ??
+    process.env.TS_REFRESH_TOKEN?.trim() ??
+    null;
+
+  if (!refreshToken) {
+    log.warn("[ts-refresh] no refresh_token — skipping");
+    return;
+  }
+
+  const accessToken = db.getExtState(TRADESTATION_EXT, "access_token");
+  const expiryRaw = db.getExtState(TRADESTATION_EXT, "token_expiry_ms");
+  if (accessToken && expiryRaw) {
+    const expiry = Number(expiryRaw);
+    if (expiry > Date.now() + 60_000) {
+      return;
+    }
+  }
+
+  const bodyParams: Record<string, string> = {
+    grant_type: "refresh_token",
+    client_id: clientId,
+    refresh_token: refreshToken,
+  };
+  if (clientSecret) bodyParams.client_secret = clientSecret;
+  const body = new URLSearchParams(bodyParams);
+
+  let res: Response;
+  try {
+    res = await fetchImpl(TRADESTATION_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error(`[ts-refresh] fetch error: ${msg}`);
+    db.setExtState(TRADESTATION_EXT, "auth_error", "refresh_failed:network");
+    return;
+  }
+
+  if (!res.ok) {
+    log.warn(`[ts-refresh] token refresh failed: ${res.status}`);
+    db.setExtState(TRADESTATION_EXT, "auth_error", `refresh_failed:${res.status}`);
+    return;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = (await res.json()) as Record<string, unknown>;
+  } catch {
+    db.setExtState(TRADESTATION_EXT, "auth_error", "refresh_failed:invalid_json");
+    return;
+  }
+
+  const newAccess = typeof data.access_token === "string" ? data.access_token : null;
+  if (!newAccess) {
+    db.setExtState(TRADESTATION_EXT, "auth_error", "refresh_failed:no_access_token");
+    return;
+  }
+
+  db.setExtState(TRADESTATION_EXT, "access_token", newAccess);
+  if (typeof data.refresh_token === "string" && data.refresh_token) {
+    db.setExtState(TRADESTATION_EXT, "refresh_token", data.refresh_token);
+  }
+  if (typeof data.expires_in === "number") {
+    db.setExtState(
+      TRADESTATION_EXT,
+      "token_expiry_ms",
+      String(Date.now() + data.expires_in * 1000),
+    );
+  }
+  db.deleteExtState(TRADESTATION_EXT, "auth_error");
+  log.info("[ts-refresh] tokens refreshed");
+}