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. 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 /api/comet/lifecycle
                               └─ taskThreads.ts lifecycle adapter
                                    └─ src/data/comet-runs/*.json

Channel routing

The browser-automation-routing rule 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 — native browser tool (distinct from Comet-Bridge)
• Sub-agents — spawning background agent runs
• Comet-Bridge repository — source code and setup docs