mercury-agent 0.4.5

package/examples/extensions/pinchtab/index.ts

@@ -0,0 +1,199 @@
+export default function (mercury: {
+  cli(opts: { name: string; install: string }): void;
+  skill(relativePath: string): void;
+  permission(opts: { defaultRoles: string[] }): void;
+  /** biome-ignore lint/suspicious/noExplicitAny: minimal stub matching MercuryExtensionAPI subset */
+  on(event: string, handler: (event: any, ctx: any) => Promise<any>): void;
+}) {
+  mercury.cli({
+    name: "pinchtab",
+    install:
+      'npm install -g pinchtab playwright && npx playwright install --with-deps chromium && CHROMIUM=$(NODE_PATH="$(npm root -g)" node -e "try{process.stdout.write(require(\'playwright\').chromium.executablePath())}catch(e){}" 2>/dev/null) && { test -x "$CHROMIUM" || CHROMIUM=$(find /home/mercury/.cache/ms-playwright -type f -path \'*/chrome-linux/chrome\' ! -path \'*headless_shell*\' 2>/dev/null | head -1); } && test -n "$CHROMIUM" && test -x "$CHROMIUM" && ln -sf "$CHROMIUM" /usr/local/bin/chromium && ln -sf "$CHROMIUM" /usr/bin/chromium && rm -rf /var/lib/apt/lists/*',
+  });
+  mercury.permission({ defaultRoles: ["admin", "member"] });
+  mercury.skill("./skill");
+
+  // Chrome needs --no-sandbox when running inside Docker (no user namespace for sandboxing).
+  // Also inject search engine preference and authenticated-session support into system prompt.
+  mercury.on("before_container", async () => {
+    // Bash ${...} must be escaped as \${...} so this TS template is valid.
+    const pinchtabEnsure = `pinchtab_ensure() {
+  local bind="\${BRIDGE_BIND:-127.0.0.1}"
+  local port="\${BRIDGE_PORT:-9867}"
+  local log="\${PINCHTAB_LOG:-/tmp/pinchtab.log}"
+  local max_wait="\${1:-120}"
+  mkdir -p "$(dirname "$log")" 2>/dev/null || true
+  : >"$log"
+  if [ ! -x "\${CHROME_BINARY:-}" ]; then
+    for _c in /usr/local/bin/chromium /usr/bin/chromium; do
+      if [ -x "$_c" ]; then export CHROME_BINARY="$_c"; break; fi
+    done
+  fi
+  if [ ! -x "\${CHROME_BINARY:-}" ]; then
+    echo "No executable Chromium (CHROME_BINARY=\${CHROME_BINARY:-}; tried /usr/local/bin/chromium, /usr/bin/chromium). Rebuild mercury-agent-ext (restart Mercury)." | tee -a "$log"
+    return 1
+  fi
+  _pinchtab_port_open() { (echo >/dev/tcp/$bind/$port) 2>/dev/null; }
+  if command -v pinchtab >/dev/null 2>&1 && _pinchtab_port_open; then
+    return 0
+  fi
+  pkill -f '[p]inchtab' 2>/dev/null || true
+  nohup pinchtab >>"$log" 2>&1 &
+  local pid=$!
+  sleep 2
+  if ! kill -0 "$pid" 2>/dev/null; then
+    echo "pinchtab exited immediately (pid $pid). Log:" >&2
+    tail -120 "$log" >&2
+    return 1
+  fi
+  local i=0
+  while [ "$i" -lt "$max_wait" ]; do
+    if _pinchtab_port_open; then
+      return 0
+    fi
+    if ! kill -0 "$pid" 2>/dev/null; then
+      echo "pinchtab died during startup. Log:" >&2
+      tail -120 "$log" >&2
+      return 1
+    fi
+    sleep 1
+    i=$((i+1))
+  done
+  echo "pinchtab did not listen on $bind:$port within \${max_wait}s. Log:" >&2
+  tail -120 "$log" >&2
+  return 1
+}`;
+
+    let sessionFunctions = "";
+    let navExampleCommand = 'pinchtab nav "https://search.brave.com/search?q=your+query+here"';
+    let sessionPromptFragment = "";
+
+    if (process.env.MERCURY_BROWSER_SESSIONS) {
+      // Node.js injection script — pure ES5-style, no backticks or ${} so no TS escaping needed.
+      // Reads MERCURY_BROWSER_SESSIONS from env, looks up the domain, injects cookies +
+      // localStorage via the pinchtab HTTP bridge, then reloads. Exits 0 on success (session
+      // found and injected), 1 if no session for this domain, 2 on unexpected error.
+      const nodeInjectScript = `var url = process.argv[2];
+if (!url) process.exit(1);
+var raw = process.env.MERCURY_BROWSER_SESSIONS;
+if (!raw) process.exit(1);
+var sessions;
+try { sessions = JSON.parse(Buffer.from(raw, "base64").toString()); } catch (e) { process.exit(1); }
+var hostname = (new URL(url)).hostname;
+var parts = hostname.split(".");
+var multiPartTld = /\.(co|com|org|net|gov|ac|edu|or|ne|gr|gen|plc|ltd|me)\.[a-z]{2}$/i;
+var domain = parts.length <= 2 ? hostname : (multiPartTld.test(hostname) ? parts.slice(-3).join(".") : parts.slice(-2).join("."));
+var b64 = sessions[domain];
+if (!b64) process.exit(1);
+var state;
+try { state = JSON.parse(Buffer.from(b64, "base64").toString()); } catch (e) { process.exit(1); }
+var bind = process.env.BRIDGE_BIND || "127.0.0.1";
+var port = process.env.BRIDGE_PORT || "9867";
+var bridge = "http://" + bind + ":" + port;
+Promise.resolve()
+  .then(function () {
+    return fetch(bridge + "/navigate", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url: url }),
+    });
+  })
+  .then(function () {
+    if (!state.cookies || !state.cookies.length) return;
+    return fetch(bridge + "/cookies", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url: url, cookies: state.cookies }),
+    }).catch(function () {});
+  })
+  .then(function () {
+    var origins = state.origins || [];
+    return origins.reduce(function (p, o) {
+      return p.then(function () {
+        if (!o.localStorage || !o.localStorage.length) return;
+        var script =
+          "(function(){" +
+          o.localStorage
+            .map(function (i) {
+              return "localStorage.setItem(" + JSON.stringify(i.name) + "," + JSON.stringify(i.value) + ")";
+            })
+            .join(";") +
+          "})()";
+        return fetch(bridge + "/evaluate", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ expression: script }),
+        }).catch(function () {});
+      });
+    }, Promise.resolve());
+  })
+  .then(function () {
+    return fetch(bridge + "/evaluate", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ expression: "window.location.reload()" }),
+    }).catch(function () {});
+  })
+  .then(function () {
+    process.exit(0);
+  })
+  .catch(function (e) {
+    console.error(e.message);
+    process.exit(2);
+  });`;
+
+      // Single-quoted heredoc (<< 'JSSCRIPT') so the JS code is written verbatim.
+      // JSSCRIPT terminator must stay at column 0 — do not indent it.
+      sessionFunctions = `
+_pinchtab_write_inject() {
+  cat > /tmp/_pinchtab_inject.js << 'JSSCRIPT'
+${nodeInjectScript}
+JSSCRIPT
+}
+
+pinchtab_nav() {
+  local url="$1"
+  pinchtab_ensure || return 1
+  if [ ! -f /tmp/_pinchtab_inject.js ]; then
+    _pinchtab_write_inject
+  fi
+  if node /tmp/_pinchtab_inject.js "$url" 2>/dev/null; then
+    return 0
+  fi
+  pinchtab nav "$url"
+}`;
+
+      navExampleCommand = 'pinchtab_nav "https://search.brave.com/search?q=your+query+here"';
+      sessionPromptFragment =
+        "\n\nAuthenticated browser sessions are available. Use `pinchtab_nav <url>` instead of `pinchtab nav <url>` for all navigations — it automatically injects the saved session (cookies + localStorage) before navigation when one is available for the domain. If after navigating you land on a login or authentication page (session expired), tell the user their session has expired.";
+      if (process.env.MERCURY_CONSOLE_URL) {
+        sessionPromptFragment += ` Include a re-authentication link: ${process.env.MERCURY_CONSOLE_URL}/dashboard/browser-sessions?recapture=<eTLD+1-of-the-site> (e.g. for chase.com: ${process.env.MERCURY_CONSOLE_URL}/dashboard/browser-sessions?recapture=chase.com). Never attempt to enter credentials on the user's behalf.`;
+      }
+    }
+
+    return {
+      env: {
+        CHROME_BINARY: "/usr/local/bin/chromium",
+        CHROME_FLAGS: "--no-sandbox --disable-dev-shm-usage",
+        // container-runner strips MERCURY_ prefix on passthrough, so the inner
+        // container only gets BROWSER_SESSIONS. The inject script reads
+        // MERCURY_BROWSER_SESSIONS, so re-add it explicitly via extraEnv
+        // (extraEnv keys are passed verbatim, not stripped).
+        ...(process.env.MERCURY_BROWSER_SESSIONS
+          ? { MERCURY_BROWSER_SESSIONS: process.env.MERCURY_BROWSER_SESSIONS }
+          : {}),
+      },
+      systemPrompt: `When searching the web, always use Brave Search. Never use Google.
+
+Before any pinchtab CLI use in Docker, define and run:
+
+\`\`\`bash
+${pinchtabEnsure}${sessionFunctions}
+pinchtab_ensure || exit 1
+${navExampleCommand}
+sleep 3
+pinchtab text
+\`\`\`${sessionPromptFragment}`,
+    };
+  });
+}

package/examples/extensions/pinchtab/lib/session-injector.ts

@@ -0,0 +1,144 @@
+/**
+ * Browser session injector for pinchtab.
+ *
+ * Reads MERCURY_BROWSER_SESSIONS from env at module load, parses the base64
+ * JSON manifest into an in-memory map, and exposes injectSessionIfPresent()
+ * which injects cookies + localStorage via pinchtab's HTTP API before navigation.
+ *
+ * Used by the pinchtab before_container system prompt fragment — the agent is
+ * instructed to call the standalone inject-and-nav binary before navigating
+ * to any URL when authenticated sessions are available.
+ */
+
+export interface StorageStateCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires: number;
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: "Strict" | "Lax" | "None";
+}
+
+export interface StorageStateOrigin {
+  origin: string;
+  localStorage: Array<{ name: string; value: string }>;
+}
+
+export interface StorageState {
+  cookies: StorageStateCookie[];
+  origins: StorageStateOrigin[];
+}
+
+/** Extract the eTLD+1 from a URL hostname. e.g. "bank.chase.com" → "chase.com" */
+export function extractDomain(urlOrHostname: string): string {
+  let hostname = urlOrHostname;
+  try {
+    hostname = new URL(urlOrHostname).hostname;
+  } catch {
+    // Input was already a hostname
+  }
+  const parts = hostname.split(".");
+  if (parts.length <= 2) return hostname;
+  return parts.slice(-2).join(".");
+}
+
+/** Parse MERCURY_BROWSER_SESSIONS env var into domain → StorageState map. */
+function loadSessionMap(): Map<string, StorageState> {
+  const raw = process.env.MERCURY_BROWSER_SESSIONS;
+  if (!raw) return new Map();
+
+  try {
+    const manifest = JSON.parse(Buffer.from(raw, "base64").toString("utf8")) as Record<string, string>;
+    const map = new Map<string, StorageState>();
+    for (const [domain, b64] of Object.entries(manifest)) {
+      try {
+        const state = JSON.parse(Buffer.from(b64, "base64").toString("utf8")) as StorageState;
+        map.set(domain, state);
+      } catch (e) {
+        console.warn(`[session-injector] Failed to parse session for domain "${domain}":`, e);
+      }
+    }
+    return map;
+  } catch (e) {
+    console.warn("[session-injector] Failed to parse MERCURY_BROWSER_SESSIONS:", e);
+    return new Map();
+  }
+}
+
+const sessionMap = loadSessionMap();
+
+const PINCHTAB_BASE = `http://${process.env.BRIDGE_BIND ?? "127.0.0.1"}:${process.env.BRIDGE_PORT ?? "9867"}`;
+
+/** Returns true if there is a saved session for this URL's domain. */
+export function hasSession(url: string): boolean {
+  return sessionMap.has(extractDomain(url));
+}
+
+/**
+ * Inject cookies + localStorage for the URL's domain via pinchtab's HTTP API,
+ * then navigate to the URL and reload so the site picks up the injected state.
+ *
+ * If no session is found for this domain, falls through to a plain navigate.
+ * Errors during injection are logged but do not prevent navigation.
+ */
+export async function injectSessionIfPresent(url: string): Promise<void> {
+  const domain = extractDomain(url);
+  const session = sessionMap.get(domain);
+
+  // Navigate first (creates context, sets tab)
+  const navRes = await fetch(`${PINCHTAB_BASE}/navigate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ url }),
+  });
+  if (!navRes.ok) {
+    throw new Error(`pinchtab navigate failed: ${navRes.status} ${await navRes.text()}`);
+  }
+
+  if (!session) return;
+
+  // Inject cookies
+  if (session.cookies.length > 0) {
+    const cookieRes = await fetch(`${PINCHTAB_BASE}/cookies`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url, cookies: session.cookies }),
+    });
+    if (!cookieRes.ok) {
+      console.warn(`[session-injector] Cookie injection partial failure for "${domain}": ${cookieRes.status}`);
+    }
+  }
+
+  // Inject localStorage per origin
+  for (const originEntry of session.origins) {
+    if (originEntry.localStorage.length === 0) continue;
+    try {
+      const script = `(function(){${originEntry.localStorage
+        .map((item) => `localStorage.setItem(${JSON.stringify(item.name)},${JSON.stringify(item.value)})`)
+        .join(";")}})()`;
+      const evalRes = await fetch(`${PINCHTAB_BASE}/evaluate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ expression: script }),
+      });
+      if (!evalRes.ok) {
+        console.warn(`[session-injector] localStorage injection failed for "${originEntry.origin}": ${evalRes.status}`);
+      }
+    } catch (e) {
+      console.warn(`[session-injector] localStorage injection error for "${originEntry.origin}":`, e);
+    }
+  }
+
+  // Reload so the site picks up injected cookies + localStorage
+  try {
+    await fetch(`${PINCHTAB_BASE}/evaluate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ expression: "window.location.reload()" }),
+    });
+  } catch {
+    // Non-fatal — session may still be partially usable
+  }
+}

package/examples/extensions/pinchtab/skill/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: pinchtab
+description: Control a headless or headed Chrome browser via Pinchtab's HTTP API for web automation, scraping, form filling, navigation, screenshots, and extraction with stable accessibility refs.
+metadata:
+  short-description: Browser automation via Pinchtab HTTP API
+---
+
+# Pinchtab
+
+Fast, lightweight browser control for AI agents via HTTP + accessibility tree.
+
+**Security Note:** Pinchtab runs entirely locally. It does not contact external services, send telemetry, or exfiltrate data. However, it controls a real Chrome instance — if pointed at a profile with saved logins, agents can access authenticated sites. Always use a dedicated empty profile and set BRIDGE_TOKEN when exposing the API. See [TRUST.md](TRUST.md) for the full security model.
+
+## Quick Start (Agent Workflow)
+
+The 30-second pattern for browser tasks:
+
+```bash
+# 1. Start Pinchtab (runs forever, local on :9867)
+pinchtab &
+
+# 2. In your agent, follow this loop:
+#    a) Navigate to a URL
+#    b) Snapshot the page (get refs like e0, e5, e12)
+#    c) Act on a ref (click e5, type e12 "search text")
+#    d) Snapshot again to see the result
+#    e) Repeat step c-d until done
+```
+
+**That's it.** Refs are stable—you don't need to re-snapshot before every action. Only snapshot when the page changes significantly.
+
+## Mercury / Docker (required)
+
+In the Mercury agent container, `pinchtab &` plus a short `sleep` often races the HTTP bridge: the CLI then hits `127.0.0.1:9867` before the daemon listens (`connection refused`). The host injects `CHROME_BINARY` and `CHROME_FLAGS` (`--no-sandbox` as root). **Always** wait until the port is open and capture daemon logs.
+
+```bash
+pinchtab_ensure() {
+  local bind="${BRIDGE_BIND:-127.0.0.1}"
+  local port="${BRIDGE_PORT:-9867}"
+  local log="${PINCHTAB_LOG:-/tmp/pinchtab.log}"
+  local max_wait="${1:-120}"
+  mkdir -p "$(dirname "$log")" 2>/dev/null || true
+  : >"$log"
+  if [ ! -x "${CHROME_BINARY:-}" ]; then
+    for _c in /usr/local/bin/chromium /usr/bin/chromium; do
+      if [ -x "$_c" ]; then export CHROME_BINARY="$_c"; break; fi
+    done
+  fi
+  if [ ! -x "${CHROME_BINARY:-}" ]; then
+    echo "No executable Chromium (CHROME_BINARY=${CHROME_BINARY:-}; tried /usr/local/bin/chromium, /usr/bin/chromium). Rebuild mercury-agent-ext (restart Mercury)." | tee -a "$log"
+    return 1
+  fi
+  _pinchtab_port_open() { (echo >/dev/tcp/$bind/$port) 2>/dev/null; }
+  if command -v pinchtab >/dev/null 2>&1 && _pinchtab_port_open; then
+    return 0
+  fi
+  pkill -f '[p]inchtab' 2>/dev/null || true
+  nohup pinchtab >>"$log" 2>&1 &
+  local pid=$!
+  sleep 2
+  if ! kill -0 "$pid" 2>/dev/null; then
+    echo "pinchtab exited immediately (pid $pid). Log:" >&2
+    tail -120 "$log" >&2
+    return 1
+  fi
+  local i=0
+  while [ "$i" -lt "$max_wait" ]; do
+    if _pinchtab_port_open; then
+      return 0
+    fi
+    if ! kill -0 "$pid" 2>/dev/null; then
+      echo "pinchtab died during startup. Log:" >&2
+      tail -120 "$log" >&2
+      return 1
+    fi
+    sleep 1
+    i=$((i+1))
+  done
+  echo "pinchtab did not listen on $bind:$port within ${max_wait}s. Log:" >&2
+  tail -120 "$log" >&2
+  return 1
+}
+```
+
+Use it before every navigation/snapshot/text workflow:
+
+```bash
+pinchtab_ensure || { echo "pinchtab failed — see /tmp/pinchtab.log"; exit 1; }
+pinchtab nav "https://example.com"
+sleep 3
+pinchtab text
+```
+
+If `pinchtab_ensure` fails, show the user the tail of `/tmp/pinchtab.log`; do not only increase `sleep` and retry blindly.
+
+### Recommended Secure Setup
+
+```bash
+# Best practice for AI agents
+BRIDGE_BIND=127.0.0.1 \
+BRIDGE_TOKEN="your-strong-secret" \
+BRIDGE_PROFILE=~/.pinchtab/automation-profile \
+pinchtab &
+```
+
+**Never expose to 0.0.0.0 without a token. Never point at your daily Chrome profile.**
+
+## Setup
+
+```bash
+# Headless (default) — no visible window
+pinchtab &
+
+# Headed — visible Chrome window for human debugging
+BRIDGE_HEADLESS=false pinchtab &
+
+# With auth token
+BRIDGE_TOKEN="your-secret-token" pinchtab &
+
+# Custom port
+BRIDGE_PORT=8080 pinchtab &
+```
+
+Default: **port 9867**, no auth required (local). Set `BRIDGE_TOKEN` for remote access.
+
+For advanced setup, see [references/profiles.md](references/profiles.md) and [references/env.md](references/env.md).
+
+## What a Snapshot Looks Like
+
+After calling `/snapshot`, you get the page's accessibility tree as JSON—flat list of elements with refs:
+
+```json
+{
+  "refs": [
+    {"id": "e0", "role": "link", "text": "Sign In", "selector": "a[href='/login']"},
+    {"id": "e1", "role": "textbox", "label": "Email", "selector": "input[name='email']"},
+    {"id": "e2", "role": "button", "text": "Submit", "selector": "button[type='submit']"}
+  ],
+  "text": "... readable text version of page ...",
+  "title": "Login Page"
+}
+```
+
+Then you act on refs: `click e0`, `type e1 "user@example.com"`, `press e2 Enter`.
+
+## Core Workflow
+
+The typical agent loop:
+
+1. **Navigate** to a URL
+2. **Snapshot** the accessibility tree (get refs)
+3. **Act** on refs (click, type, press)
+4. **Snapshot** again to see results
+
+Refs (e.g. `e0`, `e5`, `e12`) are cached per tab after each snapshot — no need to re-snapshot before every action unless the page changed significantly.
+
+### Quick examples
+
+```bash
+pinchtab nav https://example.com
+pinchtab snap -i -c                    # interactive + compact
+pinchtab click e5
+pinchtab type e12 hello world
+pinchtab press Enter
+pinchtab text                          # readable text (~1K tokens)
+pinchtab text | jq .text               # pipe to jq
+pinchtab ss -o page.jpg                # screenshot
+pinchtab eval "document.title"         # run JavaScript
+pinchtab pdf --tab TAB_ID -o page.pdf  # export PDF
+```
+
+For the full HTTP API (curl examples, download, upload, cookies, stealth, batch actions, PDF export with full parameter control), see [references/api.md](references/api.md).
+
+## Token Cost Guide
+
+| Method | Typical tokens | When to use |
+|---|---|---|
+| `/text` | ~800 | Reading page content |
+| `/snapshot?filter=interactive` | ~3,600 | Finding buttons/links to click |
+| `/snapshot?diff=true` | varies | Multi-step workflows (only changes) |
+| `/snapshot?format=compact` | ~56-64% less | One-line-per-node, best efficiency |
+| `/snapshot` | ~10,500 | Full page understanding |
+| `/screenshot` | ~2K (vision) | Visual verification |
+| `/tabs/{id}/pdf` | 0 (binary) | Export page as PDF (no token cost) |
+
+**Strategy**: Start with `?filter=interactive&format=compact`. Use `?diff=true` on subsequent snapshots. Use `/text` when you only need readable content. Full `/snapshot` only when needed.
+
+## Agent Optimization
+
+**Validated Feb 2026**: Testing with AI agents revealed a critical pattern for reliable, token-efficient scraping.
+
+**See the full guide:** [docs/agent-optimization.md](../../docs/agent-optimization.md)
+
+### Quick Summary
+
+**The 3-second pattern** — wait after navigate before snapshot:
+
+```bash
+curl -X POST http://localhost:9867/navigate \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}' && \
+sleep 3 && \
+curl http://localhost:9867/snapshot | jq '.nodes[] | select(.name | length > 15) | .name'
+```
+
+**Token savings:** 93% reduction (3,842 → 272 tokens) when using prescriptive instructions vs. exploratory agent approach.
+
+For detailed findings, system prompt templates, and site-specific notes, see [docs/agent-optimization.md](../../docs/agent-optimization.md).
+
+## Tips
+
+- **Always pass `tabId` explicitly** when working with multiple tabs
+- Refs are stable between snapshot and actions — no need to re-snapshot before clicking
+- After navigation or major page changes, take a new snapshot for fresh refs
+- Pinchtab persists sessions — tabs survive restarts (disable with `BRIDGE_NO_RESTORE=true`)
+- Chrome profile is persistent — cookies/logins carry over between runs
+- Use `BRIDGE_BLOCK_IMAGES=true` or `"blockImages": true` on navigate for read-heavy tasks
+- **Wait 3+ seconds after navigate before snapshot** — Chrome needs time to render 2000+ accessibility tree nodes
+
+## Authenticated Browser Sessions
+
+If the user has saved a browser session for a site (via the Browser Sessions page in the console), the agent will automatically use it when navigating to that domain. No special instructions are needed — just navigate to the URL normally. The session (cookies + localStorage) is pre-loaded into the container environment and injected transparently before the first page load on the matched domain.
+
+Sites behind login walls (banks, airlines, HR portals, niche SaaS) can be accessed this way without any copy-pasting or API key setup. If a session seems stale or the site still shows a login screen, the user can re-capture the session from the Browser Sessions page.

package/examples/extensions/pinchtab/skill/TRUST.md

@@ -0,0 +1,69 @@
+# Pinchtab Security & Trust
+
+**TL;DR**: Pinchtab is a local, sandboxed browser control tool. It does not phone home, steal credentials, or exfiltrate data. Source code is public; binaries are signed and published via GitHub.
+
+## What Pinchtab Does
+
+- Launches a Chrome browser (local, under your control)
+- Exposes navigation, clicking, typing, and page inspection via HTTP API
+- Extracts the page's accessibility tree (for AI agents)
+- Runs screenshots, PDFs, and JavaScript evaluation
+
+**All of this stays local.** No telemetry. No external API calls (except to sites you navigate to).
+
+## What Pinchtab Does NOT Do
+
+- ❌ Doesn't access your saved passwords/credentials (Chrome sandboxing)
+- ❌ Doesn't exfiltrate data to remote servers
+- ❌ Doesn't inject ads, malware, or miners
+- ❌ Doesn't track browsing or send analytics
+- ❌ Doesn't modify system files outside its state directory (`~/.pinchtab`)
+
+## Builds & Verification
+
+Every release includes **checksums** alongside binaries:
+
+```bash
+# After downloading, verify:
+sha256sum -c checksums.txt
+```
+
+Binaries are built automatically from tagged commits via GitHub Actions (publicly visible at https://github.com/pinchtab/pinchtab/actions).
+
+## Open Source
+
+- **Source**: https://github.com/pinchtab/pinchtab (MIT)
+- **Releases**: https://github.com/pinchtab/pinchtab/releases
+- **Latest**: v0.7.0 (Feb 2026)
+
+If you're concerned, audit the source—it's 12MB, zero external dependencies, mostly Go stdlib.
+
+## VirusTotal Flag
+
+Pinchtab may trigger heuristic scanners on VirusTotal because:
+
+- ✓ It launches Chrome (subprocess execution — flagged by AV heuristics)
+- ✓ It runs JavaScript evaluation (eval-like operations)
+- ✓ It makes HTTP requests (network activity)
+
+These are **intentional design features**, not security flaws. Your browser does all three things by default.
+
+**False positives are common for development tools.** The VT flag is a known false positive for chromedp-based tools (subprocess + HTTP server). Always verify SHA256 checksums from GitHub releases before running.
+
+For maximum confidence, use the npm package (`npm install -g pinchtab`) or Docker image, which undergo additional validation.
+
+## Sandboxing
+
+Pinchtab runs a separate Chrome process with:
+
+- Isolated profile directory (default: `~/.pinchtab`)
+- No access to your user's home files (unless you explicitly navigate to `file://` URLs)
+- Standard Chrome security model (site isolation, CSP, etc.)
+
+Set `BRIDGE_PROFILE_DIR` to use a custom directory if needed.
+
+## Questions?
+
+- Source code: https://github.com/pinchtab/pinchtab
+- Issues/security reports: https://github.com/pinchtab/pinchtab/issues
+- Docs: https://pinchtab.com