> ## 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 bridge

# Comet-Bridge (Cursor browser automation)

Comet-Bridge is a **CDP-based browser automation orchestrator** used by Cursor agents for persistent, authenticated browser sessions. It connects to the Perplexity Comet browser via Chrome DevTools Protocol and provides multi-step workflow execution, tab-group management, and identity-aware ownership enforcement.

Comet-Bridge is distinct from the [Equabot-managed browser](/tools/browser). Use Comet-Bridge for persistent authenticated sessions (QBO, Mercury, Google) and multi-step playbooks. Use the Equabot browser for quick in-IDE checks and ephemeral validation.

## Architecture

```
Cursor Agent
   │
   ├─ MCP tools (comet_connect, comet_ask, comet_lifecycle_*)
   │     └─ comet-mcp stdio server ──► Comet Browser (CDP)
   │                                      └─ Tab Groups Extension
   │
   ├─ CLI fallback (comet auto/browse/scrape/...)
   │     └─ cursor-comet.mjs ──► Comet scripts ──► Comet Browser
   │
   └─ Lifecycle sync ──► Command Center /command-center/api/comet/lifecycle
                               └─ taskThreads.ts lifecycle adapter
                                    └─ src/data/comet-runs/*.json
```

## Channel routing

The [browser-automation-routing rule](https://github.com/EQUAStart/equanaut-command-center-main/blob/main/.cursor/rules/browser-automation-routing.mdc) selects the channel by intent:

| Use case                                   | Channel                   | Why                               |
| ------------------------------------------ | ------------------------- | --------------------------------- |
| Quick localhost checks, UI snapshots       | `cursor-ide-browser` MCP  | Fast, ephemeral, no setup         |
| Persistent sessions, multi-step automation | Comet-Bridge (MCP or CLI) | CDP profile, keepalive, ownership |

When Comet MCP is unavailable, agents fall back to the `comet` CLI wrapper. The safety protocol (identity, ownership) is enforced on both paths.

## Run lifecycle

Every Comet browser run has a lifecycle tracked by the Command Center lifecycle store.

### States

| State       | Description                                           |
| ----------- | ----------------------------------------------------- |
| `pending`   | Run created, not yet started (queued or deferred)     |
| `running`   | Run in progress; browser session active               |
| `completed` | Run finished successfully                             |
| `aborted`   | Run intentionally stopped (user cancel, timeout)      |
| `failed`    | Run ended with error (script failure, CDP disconnect) |

### Transition table

| From / To     | pending | running | completed | aborted | failed |
| ------------- | ------- | ------- | --------- | ------- | ------ |
| **pending**   | --      | start   | --        | abort   | fail   |
| **running**   | --      | --      | complete  | abort   | fail   |
| **completed** | --      | --      | --        | --      | --     |
| **aborted**   | --      | --      | --        | --      | --     |
| **failed**    | --      | --      | --        | --      | --     |

`completed`, `aborted`, and `failed` are terminal (no further transitions). Operations are idempotent from terminal states.

### Operations

| Operation    | Meaning                                                                      |
| ------------ | ---------------------------------------------------------------------------- |
| **start**    | Create/register run; transitions to `running` (or `pending` if deferred)     |
| **update**   | Update run metadata while `running` (auditSessionId, tabGroupId, workflowId) |
| **complete** | Mark run as successfully finished                                            |
| **abort**    | Mark run as intentionally stopped                                            |
| **fail**     | Mark run as failed with a reason                                             |

### Identity fields

| Field          | Required         | Meaning                                        |
| -------------- | ---------------- | ---------------------------------------------- |
| `runId`        | Yes              | Unique identifier for this browser run         |
| `taskThreadId` | Yes              | Links run to a task thread in Command Center   |
| `agentId`      | Multi-agent only | Agent identity for tab ownership and isolation |
| `route`        | No               | Channel used: `mcp`, `cli`, or `http`          |
| `fallbackUsed` | No               | `true` if execution used a fallback path       |

In multi-agent mode, both `taskThreadId` and `agentId` are required. Single-agent runs may omit `agentId`.

### Graceful degradation

Lifecycle sync to Command Center is best-effort on both execution paths:

| Path                                    | Timeout | Source                      |
| --------------------------------------- | ------- | --------------------------- |
| CLI (`auto.mjs` → `lifecycle-sync.mjs`) | 2 s     | `AbortSignal.timeout(2000)` |
| MCP (`comet-mcp/src/index.ts`)          | 5 s     | `AbortSignal.timeout(5000)` |

On failure (timeout or non-2xx response), the sync function logs a `[lifecycle-sync]` warning and returns `null`. The run itself continues uninterrupted.

A local JSON backup (`auto-{timestamp}.json`) is always written regardless of whether the sync succeeds, so run data is never lost. The endpoint URL can be overridden via the `COMET_CC_LIFECYCLE_URL` environment variable.

## MCP tools

Comet-Bridge exposes tools via its MCP server (`comet-mcp`):

| Tool                       | Purpose                                                                   |
| -------------------------- | ------------------------------------------------------------------------- |
| `comet_connect`            | Connect to Comet browser (auto-starts if needed)                          |
| `comet_ask`                | Send prompt to Perplexity and wait for response                           |
| `comet_poll`               | Check status of long-running tasks                                        |
| `comet_stop`               | Stop current task                                                         |
| `comet_screenshot`         | Capture current page                                                      |
| `comet_mode`               | Switch Perplexity mode (search/research/labs/learn)                       |
| `comet_shortcut`           | Trigger a Comet Query Shortcut (reusable AI prompts)                      |
| `comet_read_page`          | Extract page content as accessibility tree / clean text                   |
| `comet_wait_for_idle`      | Wait for network activity to settle                                       |
| `comet_tab_groups`         | Manage Chrome tab groups (requires extension)                             |
| `comet_lifecycle_start`    | Register a new lifecycle run                                              |
| `comet_lifecycle_complete` | Mark a run as completed                                                   |
| `comet_lifecycle_abort`    | Abort a run                                                               |
| `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                    |

## Tab ownership

In multi-agent mode, tabs are owned by a single identity (`agentId` or `taskThreadId`). Ownership is marked via the document title prefix `[comet-agent:<id>]` and enforced at three tiers:

1. **Entry gate** -- identity required before browser work begins
2. **Page-level** -- tab assigned to the requesting identity
3. **Action-level** -- every sensitive action (click, fill, navigate) verifies ownership

Cross-identity access is blocked with a deterministic `OwnershipError`.

## See also

* [Equabot-managed browser](/tools/browser) -- native browser tool (distinct from Comet-Bridge)
* [Sub-agents](/tools/subagents) -- spawning background agent runs
* [Comet-Bridge repository](https://github.com/equabot/Comet-Bridge) -- source code and setup docs