> ## Documentation Index > Fetch the complete documentation index at: https://docs.equa.cc/llms.txt > Use this file to discover all available pages before exploring further. # Comet browser # Comet Browser (Comet-Bridge) Comet-Bridge connects Equabot agents to [Perplexity Comet](https://www.perplexity.ai/comet) for **persistent browser automation**. Unlike the [equabot-managed browser](/tools/browser), which runs ephemeral sessions, Comet-Bridge maintains a long-lived browser with authenticated sessions, tab group isolation, and multi-agent safety controls. Use Comet-Bridge when your agent needs: * **Persistent login sessions** (QBO, Mercury, Google, GitHub, etc.) * **Multi-step workflows** across page navigations * **AI-powered web research** via Perplexity search/research modes * **Multi-agent tab isolation** in shared browser sessions * **Audit trails** for browser actions ## When to use which browser | Use [equabot-managed browser](/tools/browser) when | Use **Comet-Bridge** when | | -------------------------------------------------- | ----------------------------------------- | | Quick localhost checks and UI snapshots | Persistent authenticated sessions | | One-off page validation | Multi-step automation and playbooks | | Ephemeral, no login required | Need browser profile across many commands | | Minimal setup | Multi-agent tab isolation needed | Both can coexist. The routing rule is: prefer the equabot-managed browser for fast, ephemeral checks; use Comet-Bridge for persistent sessions and multi-step workflows. ## Prerequisites | Requirement | How to verify | | --------------------- | -------------------------------------------------------------------- | | **Node.js 18+** | `node --version` | | **Comet browser** | Download from [perplexity.ai/comet](https://www.perplexity.ai/comet) | | **Comet-Bridge repo** | Clone the repo; set `COMET_BRIDGE_ROOT` if not in the workspace | | **npm install** | Run `npm install` in the Comet-Bridge root | ## Quick start ```bash theme={null} # Start a Comet CDP session comet session start # Browse a page and capture content comet browse https://example.com --content # AI-powered search via Perplexity comet search "latest AI frameworks 2026" --format json # Take a screenshot comet screenshot --full # Run a multi-step workflow comet auto --steps workflow.json ``` ## Architecture ``` Agent (Cursor/CLI) │ ├── comet-mcp (MCP server) ──┐ │ ├── CDP ── Comet Browser (port 9222) └── comet CLI (cursor-comet.mjs) ──┘ │ Tab Groups Extension (chrome.tabGroups API) ``` * **comet-mcp**: MCP server that exposes 16 tools — 9 browsing (`comet_connect`, `comet_ask`, `comet_poll`, `comet_stop`, `comet_screenshot`, `comet_mode`, `comet_shortcut`, `comet_read_page`, `comet_wait_for_idle`), 1 tab management (`comet_tab_groups`), 4 lifecycle (`comet_lifecycle_start`, `comet_lifecycle_complete`, `comet_lifecycle_abort`, `comet_lifecycle_update`), and 2 task management (`comet_task_status`, `comet_delegate`). * **comet CLI**: Node wrapper (`comet `) that routes to core scripts with startup gating and lifecycle metadata. * **Tab Groups Extension**: Chrome MV3 extension loaded in Comet that enables programmatic tab group management. ### MCP-to-CLI fallback When `comet-mcp` is unavailable (not built, not registered, or the MCP transport fails), agents safely degrade to the `comet` CLI wrapper. Both paths enforce identical safety controls: identity requirements, tab ownership, startup gating, and audit masking. The `route` field in lifecycle metadata indicates which path was used (`mcp` or `cli`), and `fallbackUsed: true` flags runs that degraded from MCP. Tab-group and multi-agent operations that require the extension bridge are hard-blocked in both channels when the extension is missing -- fallback does not bypass safety gates. ## MCP server setup (comet-mcp) **Published package** — add to your Cursor MCP configuration (`~/.cursor/mcp.json`) or `~/.claude.json`: ```json theme={null} { "mcpServers": { "comet-bridge": { "command": "npx", "args": ["-y", "comet-mcp"] } } } ``` **Local development** — point to your local checkout with environment variables for the Comet binary and Command Center lifecycle endpoint: ```json theme={null} { "mcpServers": { "comet-bridge": { "command": "node", "args": ["/path/to/Comet-Bridge/comet-mcp/dist/index.js"], "env": { "COMET_PATH": "/Applications/Comet.app/Contents/MacOS/Comet", "COMET_CC_LIFECYCLE_URL": "http://localhost:3001/command-center/api/comet/lifecycle" } } } } ``` | Variable | Purpose | Default | | ------------------------ | ------------------------------------------------------ | ---------------------------------------------------------- | | `COMET_PATH` | Absolute path to the Comet browser binary | Auto-detected from standard install locations | | `COMET_CC_LIFECYCLE_URL` | Command Center lifecycle API endpoint for run tracking | `http://localhost:3001/command-center/api/comet/lifecycle` | ### MCP tools | Tool | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `comet_connect` | Connect to Comet browser (auto-starts CDP if needed) | | `comet_ask` | Send a task to Perplexity AI and wait for response | | `comet_poll` | Check progress on long-running tasks | | `comet_stop` | Stop current Perplexity task | | `comet_screenshot` | Capture current page | | `comet_mode` | Switch Perplexity modes: search, research, labs, learn | | `comet_shortcut` | Trigger a Comet Query Shortcut (reusable AI prompts with pre-configured modes) | | `comet_read_page` | Extract page content as accessibility tree and/or clean text | | `comet_wait_for_idle` | Wait for network activity to settle before proceeding | | `comet_tab_groups` | Manage Chrome tab groups (requires extension). Actions: `list`, `list_tabs`, `create`, `update`, `move`, `ungroup`, `delete`, `save_group`, `restore_group`, `archive_group`, `list_archived` | | `comet_lifecycle_start` | Register a new lifecycle run in Command Center | | `comet_lifecycle_complete` | Mark a run as completed | | `comet_lifecycle_abort` | Abort a run with optional reason | | `comet_lifecycle_update` | Update metadata on a running run (auditSessionId, tabGroupId, workflowId) | | `comet_task_status` | Check task thread status from the orchestration layer | | `comet_delegate` | Delegate a task to a sub-agent with lifecycle tracking | ## CLI reference The `comet` CLI is the unified wrapper for all Comet-Bridge commands. ```bash theme={null} comet [args...] ``` ### Commands | Command | Purpose | | ------------ | ---------------------------------------------------------------------- | | `session` | Start, stop, check status of Comet CDP sessions | | `browse` | Navigate to URL, capture content/links/title | | `search` | Perplexity AI search (text, JSON, or markdown output) | | `scrape` | Structured data extraction (tables, JSON-LD, CSS selectors) | | `interact` | Click, fill, scroll, evaluate on pages | | `screenshot` | Full page, viewport, selector, or clip screenshots | | `pdf` | Generate PDF from current page | | `network` | HAR capture, request interception, URL blocking, response mocking | | `monitor` | Page change detection with diffs and notifications | | `keepalive` | Prevent session timeouts for authenticated sites | | `auto` | Multi-step workflow execution from JSON step files | | `perf-audit` | Route regression testing and performance metrics extraction (Spec 050) | | `bootstrap` | Run readiness checks (app, CDP, MCP, extension, config) | | `readiness` | Generate readiness report (machine-readable + human-readable) | ### Lifecycle flags Browser commands (`browse`, `auto`, `interact`, etc.) accept lifecycle flags for run tracking: | Flag | Purpose | Default | | -------------------------- | ---------------------------- | ---------------------- | | `--route ` | Execution channel identifier | `cli` | | `--run-id ` | Unique run identifier | Auto-generated UUID | | `--agent-id ` | Agent identity for ownership | `COMET_AGENT_ID` env | | `--task-thread ` | Task-thread scope | `COMET_TASK_GROUP` env | These flags propagate into the [lifecycle envelope](#run-lifecycle) and audit artifacts. ### Session management ```bash theme={null} comet session start # Start Comet with CDP on default port comet session start --port 9333 # Custom port comet session status # Check if running comet session connect # Verify CDP connectivity comet session kill # Stop the session ``` ## Configuration Comet-Bridge uses `scripts/comet-config.mjs` for configuration, validated at load time. ### Environment overrides | Variable | Purpose | Default | | ------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------- | | `COMET_BRIDGE_ROOT` | Comet-Bridge repo root directory | Parent of `scripts/` | | `COMET_EXECUTABLE_PATH` | Comet browser binary path | `/Applications/Comet.app/Contents/MacOS/Comet` | | `COMET_CDP_PORT` | CDP debug port | `9222` | | `COMET_CDP_HOST` | CDP host | `127.0.0.1` | | `COMET_OUTPUT_BASE` | Output root for screenshots, PDFs, etc. | `~/.claude/comet-browser/output` | | `COMET_AGENT_ID` | Agent identity for tab ownership | (unset) | | `COMET_TASK_GROUP` | Task group / task-thread scope | (unset) | | `COMET_ISOLATE_GROUPS` | Override `isolateGroups` config (config default is `true`) | (unset; config default applies) | | `COMET_RUN_ID` | Run identifier for lifecycle tracking | (auto-generated UUID) | | `COMET_RUN_ROUTE` | Execution channel (`mcp`, `cli`, `http`) | `cli` | | `COMET_MCP_FALLBACK` | Set by agent when MCP-to-CLI fallback occurs | (unset) | | `COMET_RUN_STATUS` | Auto-propagated to child scripts by lifecycle engine | (auto; not user-set) | | `COMET_AUDIT_SESSION_ID` | Auto-propagated audit session link for child scripts | (auto; not user-set) | | `COMET_CC_LIFECYCLE_URL` | Command Center lifecycle endpoint URL | `http://localhost:3001/command-center/api/comet/lifecycle` | ### Output directories All output follows a standard contract under `COMET_OUTPUT_BASE`: ``` ~/.claude/comet-browser/output/ ├── screenshots/ ├── pdfs/ ├── scraped/ ├── har/ ├── audit/ ├── assistant/ ├── research/ └── labs/ ``` ## Multi-agent safety When multiple agents share the same Comet browser, Comet-Bridge enforces tab ownership and isolation to prevent cross-agent interference. ### Tab ownership Each tab is marked with an agent identity via a document title prefix: `[comet-agent:]`. Agents can only perform sensitive actions (click, fill, navigate) on tabs they own. ### Identity Multi-agent mode requires identity via CLI flags or environment: ```bash theme={null} # Via CLI flags comet auto --steps workflow.json --agent-id my-agent-1 # Via environment COMET_AGENT_ID=my-agent-1 comet auto --steps workflow.json # Task-thread scope COMET_TASK_GROUP=svf-1099-filing comet auto --steps workflow.json ``` ### Tab group isolation When `isolateGroups` is enabled (default), each agent/task gets its own Chrome tab group. The Comet Tab Groups Bridge extension is required for this feature. ### Enforcement layers Ownership is enforced at three tiers, each catching violations at a different level: | Tier | Guard | What it does | | ----------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | 1 -- Entry gate | `requireIdentityForMultiAgent()` | Blocks multi-agent runs that lack `agentId` or `taskThreadId` before any browser work starts. | | 2 -- Page proxy | `createGuardedPage(page, identity)` | Wraps a Playwright `Page` in a `Proxy` that intercepts every method call. Sensitive methods are routed through ownership checks automatically. | | 3 -- Action guard | `guardSensitiveAction(page, identity, action, fn)` | Per-action ownership verification. Checks the page title for the correct `[comet-agent:]` prefix before executing the action. | In single-agent mode (no `agentId`/`taskThreadId` set), all three tiers are effectively no-ops and impose no overhead. ### Sensitive actions The following 17 Playwright `Page` methods are classified as sensitive and require ownership verification in multi-agent mode: `goto`, `click`, `dblclick`, `fill`, `type`, `press`, `selectOption`, `setInputFiles`, `check`, `uncheck`, `hover`, `dragAndDrop`, `evaluate`, `setContent`, `reload`, `goBack`, `goForward` Non-sensitive methods (e.g. `title()`, `url()`, `screenshot()`, `content()`) pass through without ownership checks. ### Ownership errors When an agent attempts a sensitive action on a tab it does not own, Comet-Bridge throws an `OwnershipError`: | Property | Value | | -------------- | ------------------------------------------------------------------------------------------------------- | | `name` | `OwnershipError` | | `code` | `OWNERSHIP_VIOLATION` | | `agentId` | The agent that attempted the action | | `taskThreadId` | The task thread scope of the caller | | `pageUrl` | The URL of the tab (`sanitizeUrl` strips query params and hash fragments; invalid URLs preserved as-is) | | `action` | The Playwright method that was blocked (e.g. `click`) | Consumers can catch this error by checking `err.code === 'OWNERSHIP_VIOLATION'` or `err instanceof OwnershipError`. ## Startup gating The `comet` CLI enforces safety checks before running commands. These gates prevent unsafe multi-agent operations. ### Policy summary | Scenario | Behavior | | --------------------------------------------------------- | -------------------------------------------------------- | | Single-agent, any command | **Always allowed** | | Diagnostic commands (`bootstrap`, `readiness`, `session`) | **Always allowed** | | Multi-agent, no identity set | **Blocked** with remediation instructions | | Multi-agent, CDP not running | **Blocked** with start instructions | | Multi-agent + tab isolation, extension not loaded | **Blocked** with extension setup instructions | | Multi-agent, no tab isolation | **Warning** issued, proceeds with title-prefix ownership | ### Bypass Pass `--skip-gate` to bypass gating (not recommended for production): ```bash theme={null} comet auto --skip-gate --multi-agent --steps workflow.json ``` ### Opt out of tab isolation Pass `--no-isolate-groups` to use title-prefix-only ownership (no extension required): ```bash theme={null} COMET_AGENT_ID=agent-1 comet auto --no-isolate-groups --steps workflow.json ``` ## Run lifecycle Every browser run tracked by Comet-Bridge follows a lifecycle state machine. Both MCP and CLI paths emit identical lifecycle metadata using the shared `lifecycle-metadata.mjs` module. ### States | State | Terminal | Description | | ----------- | -------- | --------------------------------------------------------- | | `pending` | No | Run created but not yet started (e.g. queued or deferred) | | `running` | No | Run started; browser session active | | `completed` | Yes | Run finished successfully | | `aborted` | Yes | Run intentionally stopped (user cancel, timeout) | | `failed` | Yes | Run ended with error (script failure, CDP disconnect) | ### Transitions | From | Allowed transitions | | ----------- | -------------------------------------------------------------------- | | `pending` | `running` (start), `aborted` (cancel), `failed` (error before start) | | `running` | `completed` (success), `aborted` (cancel), `failed` (error) | | `completed` | None (terminal) | | `aborted` | None (terminal) | | `failed` | None (terminal) | Terminal states (`completed`, `aborted`, `failed`) allow no further transitions. Attempting an invalid transition throws a deterministic error. ### Lifecycle envelope fields Each run produces a lifecycle envelope with these fields: | Field | Type | Required | Description | | ---------------- | ------------------------- | ----------- | ----------------------------------------------------------- | | `taskThreadId` | string | Yes | Task-thread identifier from the orchestration layer | | `runId` | string | Yes | Unique run identifier (auto-generated UUID if omitted) | | `status` | enum | Yes | Current lifecycle state | | `startedAt` | ISO 8601 | Yes | When the run was created | | `route` | `mcp` \| `cli` \| `http` | No | Execution channel (`--route` flag or `COMET_RUN_ROUTE` env) | | `fallbackUsed` | boolean | No | `true` when MCP-to-CLI fallback occurred (default `false`) | | `agentId` | string | Multi-agent | Agent identity (`--agent-id` or `COMET_AGENT_ID`) | | `tabGroupId` | string | No | Chrome tab group ID when tab isolation is active | | `auditSessionId` | string | No | Links run to a browser-audit session artifact | | `workflowId` | string | No | Workflow or playbook identifier | | `completedAt` | ISO 8601 | No | Set automatically on terminal transitions | | `failureReason` | string | No | Human-readable reason on `aborted` or `failed` | | `metadata` | `Record` | No | Arbitrary key-value data attached via update operation | ### MCP/CLI parity Both execution paths produce identical 13-field envelopes: * **MCP path**: `comet-mcp` tools use `lifecycle-mcp-adapter.mjs` which calls `createLifecycleEnvelope({ route: 'mcp' })`. * **CLI path**: `cursor-comet.mjs` calls `createLifecycleEnvelope({ route: 'cli' })` for browser commands. The shared `lifecycle-metadata.mjs` module ensures field names, types, and transition rules are the same regardless of invocation channel. When MCP is unavailable and the agent falls back to CLI, the envelope carries `route: 'cli'` and `fallbackUsed: true`. ### Audit artifacts Lifecycle events are persisted as JSON files under `{COMET_OUTPUT_BASE}/audit/`: ``` audit/ ├── lifecycle-start-{runId}-{timestamp}.json ├── lifecycle-update-{runId}-{timestamp}.json ├── lifecycle-complete-{runId}-{timestamp}.json ├── lifecycle-abort-{runId}-{timestamp}.json └── lifecycle-fail-{runId}-{timestamp}.json ``` Each file contains the full lifecycle envelope plus the event type and timestamp. Audit sessions (`browser-audit.mjs`) also write lifecycle events to `lifecycle.jsonl` within the session directory. ### Dual-Stream Audit Architecture Comet-Bridge persists lifecycle events via two parallel audit streams that are always written together. They complement each other and serve different use cases. | Stream | Writer | Output Location | Granularity | | -------------- | ------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Session-scoped | `browser-audit.mjs` (`BrowserAuditSession`) | `~/equabot/audit/browser-sessions/{sessionId}/lifecycle.jsonl` + `metadata.json` | Per-session directory; includes per-action files and screenshots | | Run-oriented | `audit-logger.mjs` (`logLifecycleEvent()`) | `{COMET_OUTPUT_BASE}/audit/{runId}.jsonl` | Per-run JSONL; `lifecycle_*` events interleaved with `run_start`, `step`, `action`, `error`, `artifact`, and `run_end` events | The `runId` field is present in both streams and serves as the cross-correlation key. Given a `runId`, you can locate the corresponding session directory and run JSONL to reconstruct a complete audit picture of the run. ## Bootstrap and readiness Run readiness checks to verify all dependencies before using Comet-Bridge: ```bash theme={null} comet bootstrap # Human-readable output comet bootstrap --json # Machine-readable JSON ``` Checks performed: 1. Comet app binary exists and is executable 2. CDP connection is reachable 3. comet-mcp server is built 4. Tab Groups Bridge extension is loaded 5. Configuration is valid 6. Output directories are writable ### Exit codes | Code | Meaning | | ---- | ------------------------------------ | | `0` | All checks pass | | `1` | One or more critical checks failed | | `2` | Warnings only (degraded mode viable) | ### Readiness tiers The `comet readiness` command assesses readiness at two tiers: | Tier | Required checks | When to use | | --------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | **Pilot** | Comet app, CDP, config validity, output dirs | Single-agent or early multi-agent adoption. MCP and extension may show warnings. | | **Broad** | All 6 checks pass (app, CDP, MCP build, extension bridge, config, output) | Full multi-agent deployment with tab-group isolation and MCP tools. | ```bash theme={null} comet readiness --json # Includes "readiness.tier": "Pilot" or "Broad" ``` The tier assessment uses `assessReadinessTier()` internally: Pilot requires core + CDP + config + output; Broad additionally requires MCP build and extension bridge. ### Telemetry The readiness report includes an operational telemetry section aggregated by `collectTelemetrySummary()` from events persisted to `{COMET_OUTPUT_BASE}/audit/telemetry-events.jsonl`. Four event types are recorded: | Event type | What it tracks | | ------------ | --------------------------------------------------------------------------------- | | `route` | Which execution channel (`mcp`, `cli`, `http`) handled each run | | `fallback` | Runs that degraded from MCP to CLI (rate + count) | | `ownership` | Multi-agent ownership check outcomes (violations, passes) | | `completion` | Terminal state distribution (completed, aborted, failed) and average run duration | ```bash theme={null} comet readiness # Includes telemetry by default comet readiness --no-telemetry # Skip telemetry aggregation comet readiness --telemetry-days 7 # Adjust lookback window (default: 30) ``` ## Tab Groups Bridge extension The extension enables programmatic tab group management via the Chrome `tabGroups` API (not available through CDP alone). ### Setup 1. Open `comet://extensions` in Comet browser 2. Enable "Developer mode" (top-right toggle) 3. Click "Load unpacked" and select the `comet-mcp/extension/` directory in the Comet-Bridge repo 4. Verify the "Comet Tab Groups Bridge" extension appears with an active service worker ### Tab group operations Available via `comet_tab_groups` MCP tool or programmatically: | Action | Description | | --------------- | -------------------------------------------------------------------- | | `list` | List all tab groups | | `list_tabs` | List tabs in a specific group | | `create` | Create a new tab group | | `update` | Rename, recolor, or collapse a group | | `move` | Move tabs between groups | | `ungroup` | Remove tabs from a group | | `delete` | Close all tabs in a group | | `save_group` | Persist tab group state to the ETT archive (keyed by `taskThreadId`) | | `restore_group` | Restore an archived tab group and reopen its tabs | | `archive_group` | Collapse and archive a tab group for later restoration | Group colors: grey, blue, red, yellow, green, pink, purple, cyan, orange. ## Cookbook ### Authenticated session keepalive ```bash theme={null} # Keep a QBO session alive for 60 minutes, refreshing every 5 minutes comet keepalive --url "https://qbo.intuit.com" --interval 300 --duration 60 ``` ### Structured data extraction ```bash theme={null} # Extract tables from a page comet scrape "https://example.com/data" --table -o data.json # Extract content by CSS selector comet scrape "https://example.com" -s "main article" --output content.json ``` ### Multi-step workflow ```bash theme={null} # Run a JSON step file comet auto --steps workflow.json --agent-id agent-1 ``` ### Lifecycle-tracked workflow ```bash theme={null} # Run with explicit route and run-id (e.g. from MCP fallback path) comet auto --steps workflow.json --route cli --run-id abc-123 --agent-id bot-1 ``` Lifecycle flags attach run metadata to the output JSON and audit artifacts. See [Run lifecycle](#run-lifecycle) for details. ### Multi-viewport visual QA ```bash theme={null} # Capture screenshots in 4 viewports (desktop, laptop, tablet, mobile) comet screenshot "https://localhost:3000" --multi --full ``` ### Perplexity research workflow Use the MCP tools to run a deep research query and extract results: 1. `comet_connect` — attach to browser 2. `comet_mode` with mode `research` — switch to research mode 3. `comet_ask` with your research query — send the prompt 4. `comet_read_page` — extract the full response ### Network capture ```bash theme={null} # Record HAR for all requests comet network "https://example.com" --har --output traffic.har ``` ## Relationship to equabot browser Comet-Bridge and the [equabot-managed browser](/tools/browser) are complementary: * The **equabot browser** is built into the Gateway, uses Playwright, and is controlled via the `browser` agent tool. It launches isolated Chromium profiles for each run. * **Comet-Bridge** is an external connection to the Perplexity Comet browser. It maintains persistent sessions with authenticated sites and provides AI-powered search via Perplexity. They share no state, use different CDP ports (equabot: `18800+`, Comet: `9222`), and can run simultaneously. ## Troubleshooting ### CDP not reachable ```bash theme={null} # Check if Comet is running with CDP comet session status # Start Comet with CDP comet session start # Verify CDP manually curl http://127.0.0.1:9222/json/version ``` ### Extension not detected ```bash theme={null} # Run bootstrap to check extension status comet bootstrap # If extension-bridge shows WARN, reload the extension in comet://extensions ``` ### Multi-agent command blocked If you see `[comet-gating] BLOCKED`, check the error message for the specific issue: * **Missing identity**: set `COMET_AGENT_ID` or `COMET_TASK_GROUP` * **CDP unreachable**: start Comet with `comet session start` * **Extension missing**: load the Tab Groups Bridge extension ## Security * Comet-Bridge controls a real browser with real sessions. Treat CDP access as sensitive. * Keep CDP bound to loopback (`127.0.0.1`). Never expose port 9222 to the network. * Tab ownership prevents cross-agent interference but is not a security boundary; it is a safety mechanism for shared sessions. ### Audit masking Sensitive fields in audit logs and lifecycle events are masked automatically before persistence. Masking operates in four layers: | Layer | Source (`browser-audit.mjs`) | Count | What it matches | Examples | | ----------------------- | ---------------------------- | ----- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Field-name patterns** | `SENSITIVE_PATTERNS` | 20 | Regex patterns matched against JSON field names | `password`, `secret`, `token`, `apiKey`, `apikey`, `creditCard`, `cardNumber`, `cvv`, `ssn`, `socialSecurity`, `authorization`, `bearer`, `set-cookie`, `sessionCookie`, `jwt`, `privateKey`, `signingKey`, `otp`, `totp`, `mfaCode` | | **Partial masking** | `PARTIAL_MASK_PATTERNS` | 3 | Account, routing, and bank number fields — last 4 digits shown, middle digits replaced with `*` | `accountNumber`, `routingNumber`, `bankAccountNumber` | | **CDP URL masking** | `CDP_URL_FIELD_PATTERNS` | 4 | CDP/WebSocket URL fields where session tokens may appear in the path | `cdpUrl`, `wsEndpoint`, `debuggerUrl`, `websocketUrl` -- path and query are redacted, host:port preserved | | **Value heuristics** | Content-based | 4 | Secrets in non-standard fields detected by value shape | JWT tokens (`eyJ...`), `Bearer` prefixes, hex strings 40+ chars, base64 blobs 40+ chars | Additionally, `startRun()` in `audit-logger.mjs` filters argv arrays for 8 CLI flag-name patterns (`--password`, `--token`, `--secret`, `--key`, `--credential`, `--auth`, `--api-key`, `--private-key`), replacing the following value with `[REDACTED]`. Masking covers audit action logs, lifecycle event payloads, and metadata envelopes. Step data and results in verbose output are masked via `maskSensitiveData()`. Conversation logs apply the same masking before persistence. OwnershipError sanitizes `pageUrl` by stripping query parameters and hash fragments before storing, preventing accidental credential exposure in error messages.