@shawnowen/comet-mcp 2.3.1 → 2.4.2

package/README.md

@@ -1,10 +1,6 @@
 # comet-mcp
 
-[![npm version](https://img.shields.io/npm/v/comet-mcp.svg)](https://www.npmjs.com/package/comet-mcp)
-
-<a href="https://glama.ai/mcp/servers/@hanzili/comet-mcp">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/@hanzili/comet-mcp/badge" />
-</a>
+[![npm version](https://img.shields.io/npm/v/@shawnowen/comet-mcp.svg)](https://www.npmjs.com/package/@shawnowen/comet-mcp)
 
 **Give Claude Code a browser that thinks.**
 
@@ -22,25 +18,29 @@ Return static text. No interaction, no login, no dynamic content. Great for quic
 ### 2. Browser Automation (browser-use, Puppeteer MCP, Playwright MCP)
 Can interact with pages, but use a **one-agent-do-all** approach: the same reasoning model that's writing your code is also deciding where to click, what to type, and how to navigate. This overwhelms the context window and fragments focus.
 
-### 3. Comet MCP: Multi-Agent Delegation
-**Comet MCP takes a different approach.** Instead of Claude controlling a browser directly, it delegates to [Perplexity Comet](https://www.perplexity.ai/comet) - an AI purpose-built for web research and browsing.
+### 3. Comet MCP: Direct Control + AI Delegation
+**Comet MCP gives you both.** Direct DOM interaction for deterministic tasks (clicking, typing, form filling) AND delegation to [Perplexity Comet](https://www.perplexity.ai/comet) for AI-powered research and complex browsing.
+
+- **Direct mode** — `comet_interact` and `comet_navigate` give Claude instant, precise control over any web page via CDP. No AI middleman. Click buttons, fill forms, read content in milliseconds
+- **AI mode** — `comet_ask` delegates to Perplexity for research, summarization, and complex browsing decisions
+- **Sidecar mode** — `comet_ask` with `sidecar: true` keeps the current page visible and uses the Perplexity Assistant sidebar for page-aware Q&A
+- **Result**: Deterministic precision when you need it, AI intelligence when you want it
 
-- **Claude** stays focused on your coding task
-- **Comet** handles the browsing: navigation, login walls, dynamic content, deep research
-- **Result**: Claude's coding intelligence + Perplexity's web intelligence, working together
+> **For full toolkit installation, see the [canonical install guide](../docs/INSTALLATION.md).**
+> Run `npx comet-browser-automation install` from any compatible repo to set up all configuration automatically.
 
 ## Quick Start
 
 ### 1. Configure Claude Code
 
-Add to `~/.claude.json` or `.mcp.json`:
+Add to `~/.claude/settings.json` or `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "comet-bridge": {
       "command": "npx",
-      "args": ["-y", "comet-mcp"]
+      "args": ["-y", "@shawnowen/comet-mcp"]
     }
   }
 }
@@ -62,17 +62,90 @@ You: "Log into my GitHub and check my notifications"
 Claude: [Comet handles the login flow and navigation]
 ```
 
-## Tools
+## Tools (26)
+
+### Direct Interaction (2) — No AI, pure CDP
+
+| Tool | Description |
+|------|-------------|
+| `comet_interact` | Click, type, fill, check/uncheck, select, scroll, extract text, or run JS on the active page. Supports chaining multiple actions in one call |
+| `comet_navigate` | Navigate the active tab to any URL (QBO, Mercury, GitHub, etc.) without opening Perplexity |
+
+**`comet_interact` actions:** `click`, `type`, `fill`, `press`, `check`, `uncheck`, `select`, `scroll`, `wait`, `extract`, `evaluate`
+
+### AI-Assisted Browsing (9)
 
 | Tool | Description |
 |------|-------------|
 | `comet_connect` | Connect to Comet (auto-starts if needed) |
-| `comet_ask` | Send a task and wait for response |
+| `comet_ask` | Send a task to Perplexity and wait for response. Use `sidecar: true` to keep current page and ask via the assistant sidebar |
 | `comet_poll` | Check progress on long-running tasks |
 | `comet_stop` | Stop current task |
 | `comet_screenshot` | Capture current page |
 | `comet_mode` | Switch modes: search, research, labs, learn |
-| `comet_tab_groups` | Manage Chrome tab groups (list, create, update, delete) |
+| `comet_shortcut` | Trigger a Comet Query Shortcut |
+| `comet_read_page` | Extract page as accessibility tree + clean text |
+| `comet_wait_for_idle` | Wait for network activity to settle |
+
+### Tab Groups (1)
+
+| Tool | Description |
+|------|-------------|
+| `comet_tab_groups` | Manage Chrome tab groups (list, create, update, delete, archive, restore) |
+
+### Lifecycle (4)
+
+| Tool | Description |
+|------|-------------|
+| `comet_lifecycle_start` | Register a new lifecycle run |
+| `comet_lifecycle_complete` | Mark a run as completed |
+| `comet_lifecycle_abort` | Abort a run with optional reason |
+| `comet_lifecycle_update` | Update run metadata |
+
+Lifecycle tools are binding-aware: `start` attaches the run ID to the active or supplied Codex window binding, `complete` transitions the binding to `completed`, and `abort` transitions it to `stale`.
+
+### Orchestration (3)
+
+| Tool | Description |
+|------|-------------|
+| `comet_task_status` | Get unified status (session manifest + extension events + lifecycle) |
+| `comet_delegate` | High-level task dispatch with direct Codex binding creation/reuse, URL, and lifecycle setup |
+| `comet_observe` | Passively observe browser state, binding owners, and stale/conflict/unbound windows without disrupting active agents |
+
+### Parity and Workflow Tools (6)
+
+| Tool | Description |
+|------|-------------|
+| `comet_pdf` | Generate PDF from current page or URL |
+| `comet_scrape` | Extract structured data: text, tables, JSON-LD, lists, attributes, multi-element content |
+| `comet_network` | Capture network traffic, block URL patterns, intercept and mock API responses |
+| `comet_monitor` | Monitor current page or URL for content changes with baselines, diffs, screenshots, and notifications |
+| `comet_automate` | Multi-step browser workflows with assertions and variables |
+| `comet_domain` | Domain playbooks for QBO, Mercury, GitHub, Google, and SALT |
+
+## Codex Window Bindings
+
+Comet MCP routes multi-agent browser work through Codex window bindings. Each binding records the owning Codex session, repo/worktree, branch, `windowId`, `tabGroupId`, `targetId`, sidecar context key, lifecycle run IDs, and status.
+
+Binding rules:
+
+- Normal session agents can operate only on their own binding.
+- Worktree and fleet orchestrators can observe wider scopes, but cross-session mutation requires explicit target binding, reason, and audit.
+- `comet_task_status`, `comet_peek`, sidecar artifacts, lifecycle transitions, and delegation all resolve through the binding index instead of the currently focused window.
+- `comet_delegate` no longer shells out to the legacy session controller. It creates or reuses a binding directly and returns `bindingId`, `windowId`, `tabGroupId`, and `dispatchStatus`.
+
+Focus-independent routing means browser actions use the resolved binding's `targetId`, `windowId`, and `tabGroupId`, not whatever Comet window happens to be frontmost. Orchestrator-only cross-session actions must carry the target binding and audit reason so ordinary agents cannot accidentally mutate another agent's window.
+
+### Choosing the Right Tool
+
+| Task | Use | Why |
+|------|-----|-----|
+| Click buttons, fill forms | `comet_interact` | Direct CDP, milliseconds |
+| Navigate to a URL | `comet_navigate` | Immediate, no AI |
+| Read page content | `comet_read_page` | Structured a11y tree |
+| Research a topic | `comet_ask` | Perplexity's strength |
+| "Summarize this page" | `comet_ask(sidecar: true)` | Sidecar sees active tab |
+| Take a screenshot | `comet_screenshot` | Direct CDP capture |
 
 ## Tab Groups
 
@@ -110,7 +183,8 @@ Claude Code → MCP Server → CDP → Extension Service Worker → chrome.tabGr
 For environments that can't use MCP directly (e.g., sandboxed VMs), an HTTP server exposes all tools as REST endpoints:
 
 ```bash
-npm run build && npm run http
+npx @shawnowen/comet-mcp --http
+# Or if installed locally: npm run http
 # Starts on http://localhost:3456
 ```
 
@@ -123,7 +197,11 @@ Claude Code  →  MCP Server  →  CDP  →  Comet Browser  →  Perplexity AI
    (reasoning)     (bridge)                              (web browsing)
 ```
 
-Claude sends high-level goals ("research X", "log into Y"). Comet figures out the clicks, scrolls, and searches. Results flow back to Claude.
+**Direct mode**: Claude sends DOM actions (`comet_interact`, `comet_navigate`) → CDP executes them instantly on the active page.
+
+**AI mode**: Claude sends high-level goals (`comet_ask`) → Comet/Perplexity figures out the clicks, scrolls, and searches → results flow back.
+
+**Sidecar mode**: Claude asks about the current page (`comet_ask` with `sidecar: true`) → Perplexity Assistant sees and interacts with the active tab → results flow back.
 
 ## Requirements
 
@@ -164,7 +242,7 @@ If Comet is installed in a non-standard location:
   "mcpServers": {
     "comet-bridge": {
       "command": "npx",
-      "args": ["-y", "comet-mcp"],
+      "args": ["-y", "@shawnowen/comet-mcp"],
       "env": {
         "COMET_PATH": "/path/to/your/Comet"
       }
@@ -193,4 +271,4 @@ MIT
 
 ---
 
-[Report Issues](https://github.com/hanzili/comet-mcp/issues) · [Contribute](https://github.com/hanzili/comet-mcp)
+[Report Issues](https://github.com/EQUAStart/equa-comet-browser-control/issues) · [Contribute](https://github.com/EQUAStart/equa-comet-browser-control)

package/dist/alert-dispatcher.d.ts

@@ -0,0 +1,23 @@
+import type { ErrorEvent, ErrorEventType, ErrorSeverity } from "./types.js";
+declare const mcpErrorQueue: ErrorEvent[];
+export interface DispatchOptions {
+    type: ErrorEventType;
+    message: string;
+    consumerId?: string | null;
+    sessionKey?: string | null;
+    context?: Record<string, unknown>;
+    suggestedAction?: string;
+    severity?: ErrorSeverity;
+}
+export declare function dispatchAlert(options: DispatchOptions): ErrorEvent;
+/**
+ * Drain the MCP error queue — call on each tool response to append alerts.
+ * Returns queued alerts and clears the queue.
+ */
+export declare function drainMcpAlertQueue(): ErrorEvent[];
+/**
+ * Format drained alerts as text to append to MCP tool responses.
+ */
+export declare function formatAlertsForResponse(events: ErrorEvent[]): string;
+export { mcpErrorQueue };
+//# sourceMappingURL=alert-dispatcher.d.ts.map

package/dist/alert-dispatcher.js

@@ -0,0 +1,101 @@
+// Alert Dispatcher — three-channel alert system (Spec 016, FR-011)
+// Channels: macOS notification, JSONL log file, in-memory MCP error queue
+// Routes alerts by severity and consumer role per BridgeConfig.alertRouting
+import { appendFileSync, mkdirSync } from "fs";
+import { execFile } from "child_process";
+import { dirname } from "path";
+import { randomUUID } from "crypto";
+import { loadBridgeConfig } from "./bridge-config.js";
+// In-memory MCP error queue — drained on next tool response
+const mcpErrorQueue = [];
+// Suggested actions by error type
+const SUGGESTED_ACTIONS = {
+    PERPLEXITY_VOICE_MODE: "Start a fresh Perplexity session by calling comet_connect with a new taskThreadId",
+    PERPLEXITY_IDLE_NO_NAV: "Retry the task. If persistent, use comet_stop then start a fresh session via comet_connect",
+    PERPLEXITY_CONTEXT_BLEED: "Start a fresh Perplexity session to prevent context from prior conversation bleeding into this task",
+    BROWSER_CRASH: "Browser is restarting automatically. Reconnect with comet_connect after restart completes",
+    CRASH_LOOP_CAP: "Automatic restart halted after 3 attempts in 10 minutes. Manual intervention required",
+    CDP_DISCONNECT: "Connection lost. Call comet_connect to re-establish",
+    ORPHAN_DETECTED: "Task Thread will be snapshot-closed at threshold",
+    ORPHAN_REAPED: "Task Thread snapshot-closed. Check snapshots directory for recovery",
+    DUPLICATE_PROCESS: "Multiple comet-mcp processes detected. Review and terminate extras",
+    PROTOCOL_VIOLATION: "Missing prerequisite step. Check error message for required sequence",
+};
+// Default severity by error type
+const DEFAULT_SEVERITY = {
+    BROWSER_CRASH: "critical",
+    CRASH_LOOP_CAP: "critical",
+    DUPLICATE_PROCESS: "operational",
+    ORPHAN_DETECTED: "operational",
+    ORPHAN_REAPED: "operational",
+    PERPLEXITY_VOICE_MODE: "warning",
+    PERPLEXITY_IDLE_NO_NAV: "warning",
+    PERPLEXITY_CONTEXT_BLEED: "warning",
+    CDP_DISCONNECT: "warning",
+    PROTOCOL_VIOLATION: "warning",
+};
+export function dispatchAlert(options) {
+    const config = loadBridgeConfig();
+    const severity = options.severity || DEFAULT_SEVERITY[options.type] || "warning";
+    const event = {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        type: options.type,
+        severity,
+        consumerId: options.consumerId ?? null,
+        sessionKey: options.sessionKey ?? null,
+        message: options.message,
+        context: options.context || {},
+        suggestedAction: options.suggestedAction || SUGGESTED_ACTIONS[options.type] || "",
+        delivered: { macosNotification: false, logFile: false, mcpQueue: false },
+    };
+    // Channel 1: JSONL log (always — durable record)
+    try {
+        mkdirSync(dirname(config.alerts.logPath), { recursive: true });
+        appendFileSync(config.alerts.logPath, JSON.stringify(event) + "\n");
+        event.delivered.logFile = true;
+    }
+    catch (logErr) {
+        console.error(`[comet-bridge] ALERT LOG FAILED: Could not write to ${config.alerts.logPath}: ${logErr instanceof Error ? logErr.message : logErr}`);
+    }
+    // Channel 2: macOS notification (if enabled and severity warrants)
+    if (config.alerts.macosNotifications && severity !== "warning") {
+        const title = `Comet Bridge [${severity.toUpperCase()}]`;
+        const msg = event.message.substring(0, 200);
+        // execFile is safe — no shell injection (arguments are array, not interpolated)
+        execFile("osascript", ["-e", `display notification "${msg.replace(/"/g, '\\"')}" with title "${title}"`], (err) => {
+            if (!err) {
+                event.delivered.macosNotification = true;
+            }
+            else if (severity === "critical") {
+                console.error(`[comet-bridge] macOS notification failed for ${severity} alert: ${err.message}`);
+            }
+        });
+    }
+    // Channel 3: MCP error queue (if enabled)
+    if (config.alerts.mcpErrorQueue) {
+        mcpErrorQueue.push(event);
+        event.delivered.mcpQueue = true;
+    }
+    return event;
+}
+/**
+ * Drain the MCP error queue — call on each tool response to append alerts.
+ * Returns queued alerts and clears the queue.
+ */
+export function drainMcpAlertQueue() {
+    const events = [...mcpErrorQueue];
+    mcpErrorQueue.length = 0;
+    return events;
+}
+/**
+ * Format drained alerts as text to append to MCP tool responses.
+ */
+export function formatAlertsForResponse(events) {
+    if (events.length === 0)
+        return "";
+    const lines = events.map((e) => `⚠️ [${e.severity.toUpperCase()}] ${e.type}: ${e.message}`);
+    return "\n\n--- Queued Alerts ---\n" + lines.join("\n");
+}
+export { mcpErrorQueue };
+//# sourceMappingURL=alert-dispatcher.js.map

package/dist/binding-reaper.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Window-binding TTL reaper (Spec 084).
+ *
+ * Schedules periodic reconciliation of persisted window bindings against the live
+ * CDP window set and prunes records whose window has been missing beyond a
+ * configurable TTL. Dependency-injected so it is deterministically unit-testable
+ * (fake live-window source, fake clock, fake archive) and free of CDP/timer setup.
+ *
+ * Wired into the long-lived bridge process (http-server.ts) after `server.listen`.
+ */
+import { type CodexWindowBinding, type ReapCycleResult, type ReapOptions } from "./window-bindings.js";
+export interface ReaperConfig {
+    enabled: boolean;
+    ttlMs: number;
+    intervalMs: number;
+}
+/** Minimal store surface the reaper depends on (injectable for tests). */
+export interface ReapableStore {
+    reapExpiredBindings(opts: ReapOptions): Promise<ReapCycleResult>;
+}
+export interface ReaperDeps {
+    /** Resolve the distinct live window ids. Return `null` when unknown (CDP down) → no-op cycle. */
+    getLiveWindowIds: () => Promise<number[] | null>;
+    /** Archive a binding (recovery snapshot + alert) before deletion. */
+    archive?: (binding: CodexWindowBinding) => Promise<void>;
+    /** Injectable clock. Defaults to Date.now. */
+    now?: () => number;
+    /** Structured logger. Defaults to console.log. */
+    log?: (msg: string) => void;
+    /** Binding store. Defaults to the shared `windowBindingStore` singleton. */
+    store?: ReapableStore;
+}
+/** Parse reaper configuration from the environment with safe defaults. */
+export declare function readReaperConfig(env?: NodeJS.ProcessEnv): ReaperConfig;
+/**
+ * Run a single reap cycle. Returns the cycle result, or `null` when the live
+ * window set could not be determined (in which case nothing is mutated).
+ */
+export declare function runReapCycle(cfg: ReaperConfig, deps: ReaperDeps): Promise<ReapCycleResult | null>;
+/**
+ * Start the reaper: one cycle on startup, then on the configured interval.
+ * Returns a `stop()` that clears the timer. When disabled, no cycle runs and no
+ * timer is scheduled, and `stop()` is a no-op.
+ */
+export declare function startBindingReaper(cfg: ReaperConfig, deps: ReaperDeps): () => void;
+//# sourceMappingURL=binding-reaper.d.ts.map

package/dist/binding-reaper.js

@@ -0,0 +1,73 @@
+/**
+ * Window-binding TTL reaper (Spec 084).
+ *
+ * Schedules periodic reconciliation of persisted window bindings against the live
+ * CDP window set and prunes records whose window has been missing beyond a
+ * configurable TTL. Dependency-injected so it is deterministically unit-testable
+ * (fake live-window source, fake clock, fake archive) and free of CDP/timer setup.
+ *
+ * Wired into the long-lived bridge process (http-server.ts) after `server.listen`.
+ */
+import { windowBindingStore, } from "./window-bindings.js";
+const DEFAULT_TTL_HOURS = 6;
+const DEFAULT_INTERVAL_SEC = 1800;
+function positiveNumber(raw, fallback) {
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Parse reaper configuration from the environment with safe defaults. */
+export function readReaperConfig(env = process.env) {
+    const enabled = (env.COMET_BINDING_REAP_ENABLED ?? "1") !== "0";
+    const ttlHours = positiveNumber(env.COMET_BINDING_REAP_TTL_HOURS, DEFAULT_TTL_HOURS);
+    const intervalSec = positiveNumber(env.COMET_BINDING_REAP_INTERVAL_SEC, DEFAULT_INTERVAL_SEC);
+    return {
+        enabled,
+        ttlMs: ttlHours * 3_600_000,
+        intervalMs: intervalSec * 1000,
+    };
+}
+/**
+ * Run a single reap cycle. Returns the cycle result, or `null` when the live
+ * window set could not be determined (in which case nothing is mutated).
+ */
+export async function runReapCycle(cfg, deps) {
+    const log = deps.log ?? ((m) => console.log(m));
+    const liveIds = await deps.getLiveWindowIds();
+    if (liveIds == null) {
+        log("[binding-reaper] live window set unknown — cycle skipped (no mutation)");
+        return null;
+    }
+    const store = deps.store ?? windowBindingStore;
+    const result = await store.reapExpiredBindings({
+        liveWindowIds: liveIds,
+        ttlMs: cfg.ttlMs,
+        now: deps.now ? deps.now() : undefined,
+        archive: deps.archive,
+    });
+    log(`[binding-reaper] evaluated=${result.evaluated} newlyMissing=${result.newlyMissing} ` +
+        `retainedLive=${result.retainedLive} reaped=${result.reaped} skippedOwned=${result.skippedOwned}`);
+    return result;
+}
+/**
+ * Start the reaper: one cycle on startup, then on the configured interval.
+ * Returns a `stop()` that clears the timer. When disabled, no cycle runs and no
+ * timer is scheduled, and `stop()` is a no-op.
+ */
+export function startBindingReaper(cfg, deps) {
+    const log = deps.log ?? ((m) => console.log(m));
+    if (!cfg.enabled) {
+        log("[binding-reaper] disabled (COMET_BINDING_REAP_ENABLED=0)");
+        return () => { };
+    }
+    log(`[binding-reaper] enabled — ttl=${Math.round(cfg.ttlMs / 3_600_000)}h interval=${Math.round(cfg.intervalMs / 1000)}s`);
+    // Startup cycle (fire-and-forget; errors are swallowed per-cycle).
+    void runReapCycle(cfg, deps).catch((err) => log(`[binding-reaper] startup cycle error: ${err instanceof Error ? err.message : err}`));
+    const timer = setInterval(() => {
+        void runReapCycle(cfg, deps).catch((err) => log(`[binding-reaper] cycle error: ${err instanceof Error ? err.message : err}`));
+    }, cfg.intervalMs);
+    // Never hold the process open solely for the reaper.
+    if (typeof timer.unref === "function")
+        timer.unref();
+    return () => clearInterval(timer);
+}
+//# sourceMappingURL=binding-reaper.js.map

package/dist/bound-session.d.ts

@@ -0,0 +1,23 @@
+import type { AgentSession } from "./types.js";
+import { type CodexIdentityInput, type CodexSessionIdentity, type CodexWindowBinding, type CodexWindowBindingStore } from "./window-bindings.js";
+export type BoundSessionErrorCode = "MISSING_SESSION" | "MISSING_IDENTITY" | "MISSING_BINDING" | "STALE_BINDING" | "CONFLICT_BINDING" | "OWNERSHIP_VIOLATION";
+export declare class BoundSessionError extends Error {
+    readonly code: BoundSessionErrorCode;
+    readonly repairAction: string;
+    readonly status: number;
+    constructor(code: BoundSessionErrorCode, message: string, repairAction: string, status?: number);
+    toMcpText(toolName: string): string;
+}
+export interface BoundSessionResolution {
+    session: AgentSession;
+    identity: CodexSessionIdentity;
+    binding: CodexWindowBinding;
+}
+export interface BoundHttpResolution {
+    identity: CodexSessionIdentity;
+    binding: CodexWindowBinding;
+}
+export declare function validateBoundTargetHints(binding: CodexWindowBinding, args?: Record<string, unknown>): void;
+export declare function resolveBoundSession(session: AgentSession | undefined, args?: Record<string, unknown>, store?: CodexWindowBindingStore): Promise<BoundSessionResolution>;
+export declare function resolveHttpBoundSession(input: CodexIdentityInput, args?: Record<string, unknown>, store?: CodexWindowBindingStore): Promise<BoundHttpResolution>;
+//# sourceMappingURL=bound-session.d.ts.map

package/dist/bound-session.js

@@ -0,0 +1,119 @@
+import { assertBindingProfileAllowed, deriveCodexSessionIdentity, isBindingInWorktreeScope, windowBindingStore, } from "./window-bindings.js";
+export class BoundSessionError extends Error {
+    code;
+    repairAction;
+    status;
+    constructor(code, message, repairAction, status = 409) {
+        super(message);
+        this.code = code;
+        this.repairAction = repairAction;
+        this.status = status;
+        this.name = "BoundSessionError";
+    }
+    toMcpText(toolName) {
+        return [
+            `Binding error (${this.code}) before ${toolName}: ${this.message}`,
+            `Safe repair action: ${this.repairAction}`,
+        ].join("\n\n");
+    }
+}
+const TARGET_HINT_KEYS = ["targetId"];
+const WINDOW_HINT_KEYS = ["windowId"];
+const TAB_GROUP_HINT_KEYS = ["tabGroupId", "groupId"];
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function numberValue(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function getHintArgs(args) {
+    return args ?? {};
+}
+export function validateBoundTargetHints(binding, args) {
+    const hints = getHintArgs(args);
+    for (const key of TARGET_HINT_KEYS) {
+        const targetId = stringValue(hints[key]);
+        if (targetId && targetId !== binding.targetId) {
+            throw new BoundSessionError("OWNERSHIP_VIOLATION", `${key}=${targetId} is outside binding ${binding.bindingId}`, binding.targetId
+                ? `Use the bound targetId ${binding.targetId} or reconnect with comet_connect.`
+                : "Reconnect with comet_connect so the binding has a targetId before targeting a page.");
+        }
+    }
+    for (const key of WINDOW_HINT_KEYS) {
+        const windowId = numberValue(hints[key]);
+        if (windowId !== undefined && windowId !== binding.windowId) {
+            throw new BoundSessionError("OWNERSHIP_VIOLATION", `${key}=${windowId} is outside binding ${binding.bindingId}`, `Use the bound windowId ${binding.windowId} or reconnect with comet_connect.`);
+        }
+    }
+    for (const key of TAB_GROUP_HINT_KEYS) {
+        const tabGroupId = numberValue(hints[key]);
+        if (tabGroupId !== undefined && tabGroupId !== binding.tabGroupId) {
+            throw new BoundSessionError("OWNERSHIP_VIOLATION", `${key}=${tabGroupId} is outside binding ${binding.bindingId}`, binding.tabGroupId !== null
+                ? `Use the bound tabGroupId ${binding.tabGroupId} or reconnect with comet_connect.`
+                : "Reconnect with comet_connect so the binding has a tabGroupId before targeting a group.");
+        }
+    }
+    const sessionKey = stringValue(hints.sessionKey);
+    if (sessionKey && sessionKey !== binding.sessionKey) {
+        throw new BoundSessionError("OWNERSHIP_VIOLATION", `sessionKey=${sessionKey} is outside binding ${binding.bindingId}`, `Use the bound sessionKey ${binding.sessionKey}.`);
+    }
+    const projectThreadId = stringValue(hints.projectThreadId) ?? stringValue(hints.threadId);
+    if (projectThreadId && projectThreadId !== binding.projectThreadId) {
+        throw new BoundSessionError("OWNERSHIP_VIOLATION", `projectThreadId=${projectThreadId} is outside binding ${binding.bindingId}`, `Use the bound projectThreadId ${binding.projectThreadId}.`);
+    }
+}
+async function resolveBindingByArgs(store, identity, args) {
+    const bindingId = stringValue(args?.bindingId);
+    if (bindingId)
+        return store.get(bindingId);
+    const runId = stringValue(args?.runId);
+    if (runId)
+        return store.findByRunId(runId);
+    return store.findActiveByIdentity(identity);
+}
+function assertBindingUsable(identity, binding) {
+    if (!binding) {
+        throw new BoundSessionError("MISSING_BINDING", "No active Codex window binding exists for this caller.", "Call comet_connect with Codex identity fields to create or repair the binding.");
+    }
+    if (binding.status === "stale" || binding.status === "reaped" || binding.status === "completed") {
+        throw new BoundSessionError("STALE_BINDING", `Binding ${binding.bindingId} is ${binding.status}.`, "Call comet_connect to repair or replace the stale binding.");
+    }
+    if (binding.status === "conflict") {
+        throw new BoundSessionError("CONFLICT_BINDING", `Binding ${binding.bindingId} is in conflict.`, "Resolve the conflicting window ownership before using browser tools.");
+    }
+    if (!isBindingInWorktreeScope(identity, binding)) {
+        throw new BoundSessionError("OWNERSHIP_VIOLATION", `Caller ${identity.sessionKey} is not authorized for binding ${binding.bindingId}.`, "Use the caller's own binding or an authorized orchestrator identity.");
+    }
+    try {
+        assertBindingProfileAllowed(identity, binding);
+    }
+    catch (err) {
+        throw new BoundSessionError("OWNERSHIP_VIOLATION", err instanceof Error ? err.message : String(err), "Use an agent-owned Comet runtime profile or reconnect with comet_connect.", 403);
+    }
+    return binding;
+}
+export async function resolveBoundSession(session, args, store = windowBindingStore) {
+    if (!session) {
+        throw new BoundSessionError("MISSING_SESSION", "No active session is registered.", "Call comet_connect before using bound browser tools.");
+    }
+    if (!session.codexIdentity) {
+        throw new BoundSessionError("MISSING_IDENTITY", `Session ${session.sessionKey} has no Codex identity metadata.`, "Reconnect with comet_connect so Codex identity can be derived and persisted.");
+    }
+    const binding = assertBindingUsable(session.codexIdentity, await resolveBindingByArgs(store, session.codexIdentity, args));
+    validateBoundTargetHints(binding, args);
+    return { session, identity: session.codexIdentity, binding };
+}
+export async function resolveHttpBoundSession(input, args, store = windowBindingStore) {
+    const identity = deriveCodexSessionIdentity({ ...input, strict: true });
+    const binding = assertBindingUsable(identity, await resolveBindingByArgs(store, identity, args));
+    validateBoundTargetHints(binding, args);
+    return { identity, binding };
+}
+//# sourceMappingURL=bound-session.js.map

package/dist/bridge-config.d.ts

@@ -0,0 +1,6 @@
+import type { BridgeConfig } from "./types.js";
+declare const CONFIG_PATH: string;
+declare const DEFAULTS: BridgeConfig;
+export declare function loadBridgeConfig(): BridgeConfig;
+export { CONFIG_PATH, DEFAULTS };
+//# sourceMappingURL=bridge-config.d.ts.map

package/dist/bridge-config.js

@@ -0,0 +1,78 @@
+// Bridge Configuration — unified config for MCP server, extension, and scripts (Spec 016, FR-013)
+// Reads from ~/.claude/comet-browser/bridge-config.json with typed defaults.
+// Re-reads on each access — no caching, so config changes take effect on next tool call.
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const CONFIG_PATH = join(homedir(), ".claude", "comet-browser", "bridge-config.json");
+const DEFAULTS = {
+    version: "1.0.0",
+    cleanup: {
+        orphanThresholdMinutes: 120,
+        snapshotBeforeClose: true,
+        snapshotDir: join(homedir(), ".claude", "comet-browser", "snapshots"),
+    },
+    crashRecovery: {
+        maxRestarts: 3,
+        windowMinutes: 10,
+        autoRestart: true,
+        crashHistoryPath: join(homedir(), ".claude", "comet-browser", "crash-history.json"),
+    },
+    alerts: {
+        logPath: join(homedir(), ".local", "log", "comet-alerts.log"),
+        macosNotifications: true,
+        mcpErrorQueue: true,
+        routing: {
+            critical: "operator-direct",
+            operational: "orchestrator-first",
+            warning: "orchestrator-only",
+        },
+    },
+    roles: {
+        operatorId: "operator",
+        orchestratorAgentId: null,
+    },
+    protocolEnforcement: {
+        requireConnectBeforeBrowse: true,
+        warnMissingTabGroup: true,
+    },
+};
+export function loadBridgeConfig() {
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8");
+        try {
+            const parsed = JSON.parse(raw);
+            return deepMerge(DEFAULTS, parsed);
+        }
+        catch (parseErr) {
+            console.error(`[comet-bridge] CONFIG PARSE ERROR in ${CONFIG_PATH}: ${parseErr instanceof Error ? parseErr.message : parseErr}. Using defaults.`);
+            return { ...DEFAULTS };
+        }
+    }
+    catch (readErr) {
+        if (readErr?.code !== "ENOENT") {
+            console.error(`[comet-bridge] CONFIG READ ERROR: ${readErr?.message}. Using defaults.`);
+        }
+        return { ...DEFAULTS };
+    }
+}
+function deepMerge(defaults, overrides) {
+    const result = { ...defaults };
+    for (const key of Object.keys(overrides)) {
+        const val = overrides[key];
+        if (val !== undefined && val !== null) {
+            if (typeof val === "object" &&
+                !Array.isArray(val) &&
+                typeof result[key] === "object" &&
+                result[key] !== null) {
+                result[key] = deepMerge(result[key], val);
+            }
+            else {
+                result[key] = val;
+            }
+        }
+    }
+    return result;
+}
+export { CONFIG_PATH, DEFAULTS };
+//# sourceMappingURL=bridge-config.js.map