@shawnowen/comet-mcp 2.4.1 → 2.4.2

package/README.md

@@ -62,7 +62,7 @@ You: "Log into my GitHub and check my notifications"
 Claude: [Comet handles the login flow and navigation]
 ```
 
-## Tools (25)
+## Tools (26)
 
 ### Direct Interaction (2) — No AI, pure CDP
 
@@ -112,6 +112,17 @@ Lifecycle tools are binding-aware: `start` attaches the run ID to the active or
 | `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.

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/http-server.js

@@ -12,10 +12,12 @@ import { homedir } from "node:os";
 import { cometClient } from "./cdp-client.js";
 import { cometAI } from "./comet-ai.js";
 import { tabGroupsClient } from "./tab-groups.js";
+import { startBindingReaper, readReaperConfig } from "./binding-reaper.js";
 import { BoundSessionError, resolveHttpBoundSession } from "./bound-session.js";
 import { createOrReuseDelegateBinding } from "./delegate-binding.js";
 import { deriveCodexSessionIdentity, windowBindingStore, } from "./window-bindings.js";
 import { readAgentRegistry, classifyAgentStatus, getHealth, getSnapshot, getStatus, getDetail, formatHealth, formatSnapshot, } from "./observer.js";
+import { dispatchAlert } from "./alert-dispatcher.js";
 const PORT = parseInt(process.env.COMET_HTTP_PORT || "3456", 10);
 // Lifecycle + orchestration paths (mirrored from index.ts)
 const CC_LIFECYCLE_URL = process.env.COMET_CC_LIFECYCLE_URL || "http://localhost:3001/command-center/api/comet/lifecycle";
@@ -134,6 +136,67 @@ async function getWindowIdForTarget(targetId) {
         }
     }
 }
+/**
+ * Resolve the distinct live window ids for the window-binding reaper (Spec 084).
+ * Returns `null` when the live set cannot be determined (CDP unreachable, or page
+ * targets exist but none resolved) so the reaper performs a safe no-op instead of
+ * treating every binding as missing.
+ */
+async function getLiveWindowIds() {
+    try {
+        const resp = await fetch("http://127.0.0.1:9222/json", {
+            signal: AbortSignal.timeout(5000),
+        });
+        const targets = (await resp.json());
+        const pages = targets.filter((t) => t.type === "page" && typeof t.id === "string");
+        const ids = new Set();
+        for (const t of pages) {
+            try {
+                ids.add(await getWindowIdForTarget(t.id));
+            }
+            catch {
+                /* per-target resolution failure — skip this target */
+            }
+        }
+        // Page targets existed but none resolved → treat live set as unknown (no-op).
+        if (pages.length > 0 && ids.size === 0)
+            return null;
+        return [...ids];
+    }
+    catch {
+        return null; // CDP unreachable → unknown
+    }
+}
+/**
+ * Archive a recovery snapshot of a binding before the reaper deletes it
+ * (Spec 084 FR-006). Writes a JSON record into the snapshots dir; throwing here
+ * causes the reaper to skip the delete (fail-safe).
+ */
+async function archiveBindingForReap(binding) {
+    const dir = join(homedir(), ".claude", "comet-browser", "snapshots");
+    mkdirSync(dir, { recursive: true });
+    const safeId = binding.bindingId.replace(/[^a-zA-Z0-9_-]/g, "");
+    const file = join(dir, `reaped-binding-${safeId}-${Date.now()}.json`);
+    writeFileSync(file, JSON.stringify({ reapedAt: new Date().toISOString(), reason: "ttl-reaper", binding }, null, 2));
+    dispatchAlert({
+        type: "ORPHAN_REAPED",
+        message: `Window binding ${binding.bindingId} reaped by TTL reaper after recovery snapshot.`,
+        consumerId: binding.codexSessionId,
+        sessionKey: binding.sessionKey,
+        context: {
+            bindingId: binding.bindingId,
+            runIds: binding.runIds,
+            windowId: binding.windowId,
+            tabGroupId: binding.tabGroupId,
+            targetId: binding.targetId,
+            repoSlug: binding.repoSlug,
+            branchName: binding.branchName,
+            snapshotPath: file,
+            reaperReason: "ttl-reaper",
+        },
+    });
+    console.log(`[binding-reaper] archived recovery snapshot -> ${file}`);
+}
 function writeBoundError(res, err) {
     if (err instanceof BoundSessionError) {
         errorJson(res, `${err.code}: ${err.message}. ${err.repairAction}`, err.status);
@@ -2190,6 +2253,13 @@ async function handleTabGroupsListTabs(res) {
     if (result)
         json(res, result);
 }
+async function handleTabGroupsMetadataList(res) {
+    const result = await withMutex(res, async () => {
+        return await tabGroupsClient.listExtensionMetadata();
+    });
+    if (result)
+        json(res, result);
+}
 async function handleTabGroupsCreate(res, body) {
     const result = await withMutex(res, async () => {
         const tabIds = body.tabIds;
@@ -2227,6 +2297,26 @@ async function handleTabGroupsUpdate(res, body) {
             json(res, result);
     }
 }
+async function handleTabGroupsMetadataUpdate(res, body) {
+    const result = await withMutex(res, async () => {
+        return await tabGroupsClient.updateExtensionMetadata({
+            entityType: body.entityType,
+            entityId: body.entityId,
+            windowId: body.windowId,
+            activeWindowId: body.activeWindowId,
+            taskThreadId: body.taskThreadId,
+            tabIndex: body.tabIndex,
+            sourceFamily: body.sourceFamily,
+            policyTier: body.policyTier,
+            description: body.description,
+            title: body.title,
+            label: body.label,
+            status: body.status,
+        });
+    });
+    if (result)
+        json(res, result);
+}
 async function handleTabGroupsDelete(res, body) {
     const result = await withMutex(res, async () => {
         const groupId = body.groupId;
@@ -2329,6 +2419,9 @@ const server = createServer(async (req, res) => {
         else if (path === "/api/tab-groups/tabs" && req.method === "GET") {
             await handleTabGroupsListTabs(res);
         }
+        else if (path === "/api/tab-groups/metadata" && req.method === "GET") {
+            await handleTabGroupsMetadataList(res);
+        }
         else if (path === "/api/tab-groups" && req.method === "POST") {
             const body = await readBody(req);
             await handleTabGroupsCreate(res, body);
@@ -2337,6 +2430,10 @@ const server = createServer(async (req, res) => {
             const body = await readBody(req);
             await handleTabGroupsUpdate(res, body);
         }
+        else if (path === "/api/tab-groups/metadata/update" && req.method === "POST") {
+            const body = await readBody(req);
+            await handleTabGroupsMetadataUpdate(res, body);
+        }
         else if (path === "/api/tab-groups/delete" && req.method === "POST") {
             const body = await readBody(req);
             await handleTabGroupsDelete(res, body);
@@ -2476,8 +2573,32 @@ server.listen(PORT, () => {
     console.log(`\n  --- Tab Groups ---`);
     console.log(`  GET  /api/tab-groups       - List all tab groups`);
     console.log(`  GET  /api/tab-groups/tabs  - List all tabs with group info`);
+    console.log(`  GET  /api/tab-groups/metadata - List extension metadata`);
     console.log(`  POST /api/tab-groups       - Create group {tabIds, title?, color?}`);
     console.log(`  POST /api/tab-groups/update - Update group {groupId, title?, color?, collapsed?}`);
+    console.log(`  POST /api/tab-groups/metadata/update - Update extension metadata`);
     console.log(`  POST /api/tab-groups/delete - Delete group {groupId}`);
+    // --- Window-binding TTL reaper (Spec 084) ---
+    // Periodically prune binding records whose Comet window has been gone past the
+    // TTL, so the Session Manager / mirror stop accumulating "Display unknown" phantoms.
+    const reaperConfig = readReaperConfig();
+    const stopReaper = startBindingReaper(reaperConfig, {
+        getLiveWindowIds,
+        archive: archiveBindingForReap,
+        log: (m) => console.log(m),
+    });
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.once(sig, () => {
+            try {
+                stopReaper();
+            }
+            catch {
+                /* ignore */
+            }
+            const exitCode = sig === "SIGINT" ? 130 : 143;
+            server.close(() => process.exit(exitCode));
+            server.closeAllConnections?.();
+        });
+    }
 });
 //# sourceMappingURL=http-server.js.map