mercury-agent 0.5.0 → 0.5.2

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

@@ -1,45 +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` |
+# 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

@@ -1,107 +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"
-```
+# 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

@@ -1,102 +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");
-}
+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");
+}