@shawnowen/comet-mcp 2.3.1 → 2.4.1

package/extension/window-policy.js

@@ -0,0 +1,162 @@
+// Shared extension window policy for MV3 service worker and sidepanel contexts.
+(function installCometWindowPolicy(globalScope) {
+  "use strict";
+
+  const TOP_DISPLAY_FULLSCREEN_WINDOW = Object.freeze({
+    left: 0,
+    top: -1440,
+    width: 2560,
+    height: 1440,
+    state: "normal",
+    focused: false,
+  });
+
+  const LOCKED_FULLSCREEN_DISPLAY_POLICY = Object.freeze({
+    mode: "locked",
+    topDisplayBounds: Object.freeze({
+      left: TOP_DISPLAY_FULLSCREEN_WINDOW.left,
+      top: TOP_DISPLAY_FULLSCREEN_WINDOW.top,
+      width: TOP_DISPLAY_FULLSCREEN_WINDOW.width,
+      height: TOP_DISPLAY_FULLSCREEN_WINDOW.height,
+    }),
+    windowState: TOP_DISPLAY_FULLSCREEN_WINDOW.state,
+    nativeFullscreen: false,
+  });
+
+  const LOCKED_GROUPS_PER_WINDOW_POLICY = Object.freeze({
+    value: 1,
+    mode: "hard",
+    locked: true,
+  });
+
+  const managedWindowIds = new Set();
+
+  function registerManagedWindow(windowId) {
+    if (windowId) managedWindowIds.add(windowId);
+  }
+
+  function isManagedWindow(windowId) {
+    return Boolean(windowId && managedWindowIds.has(windowId));
+  }
+
+  async function createTopDisplayFullscreenWindow(createData = {}) {
+    const win = await chrome.windows.create({
+      ...createData,
+      left: TOP_DISPLAY_FULLSCREEN_WINDOW.left,
+      top: TOP_DISPLAY_FULLSCREEN_WINDOW.top,
+      width: TOP_DISPLAY_FULLSCREEN_WINDOW.width,
+      height: TOP_DISPLAY_FULLSCREEN_WINDOW.height,
+      focused: TOP_DISPLAY_FULLSCREEN_WINDOW.focused,
+    });
+
+    if (win?.id) {
+      registerManagedWindow(win.id);
+      await chrome.windows.update(win.id, { state: "normal" }).catch(() => {});
+      await chrome.windows
+        .update(win.id, {
+          left: TOP_DISPLAY_FULLSCREEN_WINDOW.left,
+          top: TOP_DISPLAY_FULLSCREEN_WINDOW.top,
+          width: TOP_DISPLAY_FULLSCREEN_WINDOW.width,
+          height: TOP_DISPLAY_FULLSCREEN_WINDOW.height,
+          focused: TOP_DISPLAY_FULLSCREEN_WINDOW.focused,
+        })
+        .catch(() => {});
+      await chrome.windows.update(win.id, { state: "normal" }).catch(() => {});
+    }
+
+    return win;
+  }
+
+  async function enforceTopDisplayFullscreenWindow(windowId) {
+    if (!windowId) return;
+    await chrome.windows.update(windowId, { state: "normal" }).catch(() => {});
+    await chrome.windows
+      .update(windowId, {
+        left: TOP_DISPLAY_FULLSCREEN_WINDOW.left,
+        top: TOP_DISPLAY_FULLSCREEN_WINDOW.top,
+        width: TOP_DISPLAY_FULLSCREEN_WINDOW.width,
+        height: TOP_DISPLAY_FULLSCREEN_WINDOW.height,
+        focused: TOP_DISPLAY_FULLSCREEN_WINDOW.focused,
+      })
+      .catch(() => {});
+  }
+
+  async function moveGroupToDedicatedFullscreenWindow(group) {
+    const groupTabs = await chrome.tabs.query({ groupId: group.id });
+    if (!groupTabs.length) {
+      return { moved: false, groupId: group.id, group };
+    }
+
+    const win = await createTopDisplayFullscreenWindow({ tabId: groupTabs[0].id });
+    if (groupTabs.length > 1) {
+      await chrome.tabs.move(
+        groupTabs.slice(1).map((tab) => tab.id),
+        { windowId: win.id, index: -1 }
+      );
+    }
+
+    const regroupedId = await chrome.tabs.group({ tabIds: groupTabs.map((tab) => tab.id) });
+    await chrome.tabGroups.update(regroupedId, {
+      title: group.title || "",
+      color: group.color || "grey",
+      collapsed: group.collapsed || false,
+    });
+    const regrouped = await chrome.tabGroups.get(regroupedId);
+    await enforceTopDisplayFullscreenWindow(regrouped.windowId);
+    return { moved: true, groupId: regrouped.id, group: regrouped };
+  }
+
+  async function ensureOneGroupPerWindow(changedGroupId = null, options = {}) {
+    const groups = await chrome.tabGroups.query({});
+    if (changedGroupId && options.markChangedWindowManaged) {
+      const changedGroup = groups.find((group) => group.id === changedGroupId);
+      if (changedGroup?.windowId) registerManagedWindow(changedGroup.windowId);
+    }
+
+    const groupsByWindow = new Map();
+    for (const group of groups) {
+      if (!isManagedWindow(group.windowId)) continue;
+      const existing = groupsByWindow.get(group.windowId) || [];
+      existing.push(group);
+      groupsByWindow.set(group.windowId, existing);
+    }
+
+    let tracked = null;
+    for (const [windowId, windowGroups] of groupsByWindow.entries()) {
+      if (windowGroups.length <= LOCKED_GROUPS_PER_WINDOW_POLICY.value) {
+        await enforceTopDisplayFullscreenWindow(windowId);
+        if (changedGroupId && windowGroups[0]?.id === changedGroupId) {
+          tracked = { moved: false, groupId: windowGroups[0].id, group: windowGroups[0] };
+        }
+        continue;
+      }
+
+      const keepGroup =
+        windowGroups.find((group) => group.id !== changedGroupId) || windowGroups[0];
+      for (const group of windowGroups) {
+        if (group.id === keepGroup.id) continue;
+        const result = await moveGroupToDedicatedFullscreenWindow(group);
+        if (group.id === changedGroupId) tracked = result;
+      }
+      await enforceTopDisplayFullscreenWindow(keepGroup.windowId);
+    }
+
+    if (changedGroupId && !tracked) {
+      const group = await chrome.tabGroups.get(changedGroupId).catch(() => null);
+      if (group) tracked = { moved: false, groupId: group.id, group };
+    }
+
+    return tracked;
+  }
+
+  globalThis.CometWindowPolicy = Object.freeze({
+    TOP_DISPLAY_FULLSCREEN_WINDOW,
+    LOCKED_FULLSCREEN_DISPLAY_POLICY,
+    LOCKED_GROUPS_PER_WINDOW_POLICY,
+    createTopDisplayFullscreenWindow,
+    enforceTopDisplayFullscreenWindow,
+    ensureOneGroupPerWindow,
+    isManagedWindow,
+    registerManagedWindow,
+  });
+})(globalThis);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shawnowen/comet-mcp",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "description": "MCP Server that gives Claude Code superpowers with Perplexity Comet browser - agentic web browsing, deep research, and real-time monitoring",
   "type": "module",
   "main": "dist/index.js",
@@ -8,12 +8,15 @@
     "comet-mcp": "dist/index.js"
   },
   "files": [
-    "dist",
-    "extension",
+    "dist/**",
+    "vendor/**",
+    "extension/**",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!**/*.map"
   ],
   "scripts": {
+    "prebuild": "node -e \"const fs=require('fs'),p=require('path');const src=p.resolve('../scripts');const dst=p.resolve('vendor');fs.mkdirSync(dst,{recursive:true});for(const f of ['lifecycle-mcp-adapter.mjs','lifecycle-metadata.mjs','readiness-report.mjs'])fs.copyFileSync(p.join(src,f),p.join(dst,f));console.log('vendored lifecycle scripts -> vendor/');\"",
     "build": "tsc",
     "test": "vitest run",
     "prepublishOnly": "npm run build",
@@ -37,11 +40,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ShawnOwen/Comet-Bridge.git"
+    "url": "git+https://github.com/EQUAStart/equa-comet-browser-control.git"
   },
-  "homepage": "https://github.com/ShawnOwen/Comet-Bridge#readme",
+  "homepage": "https://github.com/EQUAStart/equa-comet-browser-control#readme",
   "bugs": {
-    "url": "https://github.com/ShawnOwen/Comet-Bridge/issues"
+    "url": "https://github.com/EQUAStart/equa-comet-browser-control/issues"
   },
   "engines": {
     "node": ">=18.0.0"

package/vendor/lifecycle-mcp-adapter.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * MCP lifecycle adapter (Spec 070, S070-T015).
+ *
+ * Ensures MCP tool calls emit the same lifecycle metadata as the CLI path
+ * (cursor-comet.mjs), satisfying AC-3, AC-5, AC-6 parity requirements.
+ *
+ * MCP servers import this adapter to wrap tool executions with lifecycle
+ * events that produce identical fields to the CLI path. Both paths use
+ * the shared lifecycle-metadata.mjs module.
+ *
+ * Usage from comet-mcp or any MCP handler:
+ *   import { wrapMCPToolCall, createMCPLifecycleEnvelope } from '../scripts/lifecycle-mcp-adapter.mjs';
+ *
+ *   // Option A: wrap an entire tool call
+ *   const result = await wrapMCPToolCall({ taskThreadId, agentId, toolName }, async (envelope) => {
+ *     // ... tool execution ...
+ *     return toolResult;
+ *   });
+ *
+ *   // Option B: manual envelope management
+ *   const envelope = createMCPLifecycleEnvelope({ taskThreadId });
+ *   emitLifecycleEvent('start', envelope);
+ *   // ... tool execution ...
+ *   transitionEnvelope(envelope, 'completed');
+ *   emitLifecycleEvent('complete', envelope);
+ *
+ * @module lifecycle-mcp-adapter
+ */
+
+import {
+  createLifecycleEnvelope,
+  transitionEnvelope,
+  emitLifecycleEvent,
+  lifecycleEnvVars,
+  validateEnvelope,
+} from "./lifecycle-metadata.mjs";
+
+/**
+ * Create a lifecycle envelope pre-configured for the MCP route.
+ * Equivalent to what cursor-comet.mjs creates for CLI, but with route='mcp'.
+ *
+ * @param {object} opts
+ * @param {string} [opts.taskThreadId]
+ * @param {string} [opts.agentId]
+ * @param {string} [opts.runId]
+ * @param {string} [opts.toolName] - MCP tool name (stored as workflowId for traceability)
+ * @param {boolean} [opts.fallbackUsed] - True if this is a fallback from failed CLI/HTTP path
+ * @returns {object} Lifecycle envelope with route='mcp'
+ */
+export function createMCPLifecycleEnvelope(opts = {}) {
+  return createLifecycleEnvelope({
+    ...opts,
+    route: "mcp",
+    workflowId: opts.toolName || opts.workflowId,
+  });
+}
+
+/**
+ * Wrap an MCP tool call with lifecycle events.
+ * Creates an envelope, emits start, runs the handler, and emits complete/fail.
+ *
+ * The handler receives the envelope and may update it (e.g. set auditSessionId).
+ *
+ * @param {object} opts - Lifecycle identity options
+ * @param {string} [opts.taskThreadId]
+ * @param {string} [opts.agentId]
+ * @param {string} [opts.runId]
+ * @param {string} [opts.toolName]
+ * @param {boolean} [opts.fallbackUsed]
+ * @param {(envelope: object) => Promise<any>} handler - Tool execution function
+ * @returns {Promise<{ result: any, envelope: object }>}
+ */
+export async function wrapMCPToolCall(opts, handler) {
+  const envelope = createMCPLifecycleEnvelope(opts);
+  emitLifecycleEvent("start", envelope, { persist: true });
+
+  try {
+    const result = await handler(envelope);
+    transitionEnvelope(envelope, "completed");
+    emitLifecycleEvent("complete", envelope, { persist: true });
+    return { result, envelope };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    transitionEnvelope(envelope, "failed", { failureReason: reason });
+    emitLifecycleEvent("fail", envelope, { persist: true });
+    throw err;
+  }
+}
+
+// Re-export shared primitives for convenience
+export {
+  createLifecycleEnvelope,
+  transitionEnvelope,
+  emitLifecycleEvent,
+  lifecycleEnvVars,
+  validateEnvelope,
+};
+
+export default {
+  createMCPLifecycleEnvelope,
+  wrapMCPToolCall,
+};

package/vendor/lifecycle-metadata.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Shared lifecycle metadata emitter (Spec 070, S070-T015).
+ *
+ * Both the CLI path (cursor-comet.mjs) and MCP path (lifecycle-mcp-adapter)
+ * use this module to create and emit lifecycle envelopes, ensuring both
+ * routes produce equivalent fields per integration-contract.md §1.
+ *
+ * @module lifecycle-metadata
+ */
+
+import { randomUUID } from "crypto";
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { recordTelemetryEvent } from "./readiness-report.mjs";
+
+/** Canonical lifecycle fields per integration-contract.md §1.1 / §1.2 */
+const REQUIRED_FIELDS = ["taskThreadId", "runId", "status", "startedAt"];
+const OPTIONAL_FIELDS = [
+  "agentId",
+  "tabGroupId",
+  "auditSessionId",
+  "workflowId",
+  "completedAt",
+  "failureReason",
+  "route",
+  "fallbackUsed",
+];
+
+/**
+ * Create a lifecycle envelope with the canonical fields.
+ * Missing required fields are auto-filled with sensible defaults.
+ *
+ * @param {object} opts
+ * @param {string} opts.taskThreadId - Task-thread identifier.
+ * @param {string} [opts.agentId] - Agent identity.
+ * @param {string} [opts.runId] - Run id (auto-generated if omitted).
+ * @param {'pending'|'running'|'completed'|'aborted'|'failed'} [opts.status] - Initial status.
+ * @param {'mcp'|'cli'|'http'} [opts.route] - Execution channel.
+ * @param {boolean} [opts.fallbackUsed] - Whether a fallback path was used.
+ * @param {string} [opts.tabGroupId]
+ * @param {string} [opts.auditSessionId]
+ * @param {string} [opts.workflowId]
+ * @param {boolean} [opts.deferred] - If true, start as 'pending' instead of 'running'.
+ * @returns {object} Lifecycle envelope
+ */
+export function createLifecycleEnvelope(opts = {}) {
+  const now = new Date().toISOString();
+  return {
+    taskThreadId: opts.taskThreadId || process.env.COMET_TASK_GROUP || "unknown",
+    agentId: opts.agentId || process.env.COMET_AGENT_ID || undefined,
+    runId: opts.runId || randomUUID(),
+    status: opts.deferred ? "pending" : opts.status || "running",
+    startedAt: opts.startedAt || now,
+    route: opts.route || "cli",
+    fallbackUsed: opts.fallbackUsed ?? false,
+    tabGroupId: opts.tabGroupId || undefined,
+    auditSessionId: opts.auditSessionId || undefined,
+    workflowId: opts.workflowId || undefined,
+    completedAt: undefined,
+    failureReason: undefined,
+  };
+}
+
+/**
+ * Transition a lifecycle envelope to a new status, enforcing the
+ * transition table from integration-contract.md §2.3.
+ *
+ * @param {object} envelope - Existing lifecycle envelope.
+ * @param {'running'|'completed'|'aborted'|'failed'} newStatus
+ * @param {{ failureReason?: string }} [meta]
+ * @returns {object} Updated envelope (mutated in place + returned)
+ */
+export function transitionEnvelope(envelope, newStatus, meta = {}) {
+  const ALLOWED = {
+    pending: new Set(["running", "aborted", "failed"]),
+    running: new Set(["completed", "aborted", "failed"]),
+    completed: new Set(),
+    aborted: new Set(),
+    failed: new Set(),
+  };
+
+  const allowed = ALLOWED[envelope.status];
+  if (!allowed || !allowed.has(newStatus)) {
+    throw new Error(
+      `Invalid lifecycle transition for run ${envelope.runId}: ${envelope.status} → ${newStatus}`
+    );
+  }
+
+  envelope.status = newStatus;
+  if (newStatus === "completed" || newStatus === "aborted" || newStatus === "failed") {
+    envelope.completedAt = new Date().toISOString();
+  }
+  if (meta.failureReason) {
+    envelope.failureReason = meta.failureReason;
+  }
+  return envelope;
+}
+
+/**
+ * Emit a lifecycle event to stderr (human-readable) and optionally persist
+ * a JSON artifact under the output audit directory.
+ *
+ * @param {'start'|'update'|'complete'|'abort'|'fail'} eventType
+ * @param {object} envelope - The lifecycle envelope.
+ * @param {{ silent?: boolean, outputDir?: string, persist?: boolean }} [opts]
+ */
+export function emitLifecycleEvent(eventType, envelope, opts = {}) {
+  const event = {
+    event: eventType,
+    timestamp: new Date().toISOString(),
+    ...envelope,
+  };
+
+  if (!opts.silent) {
+    const routeTag = envelope.route ? `[${envelope.route}]` : "[unknown]";
+    const statusTag = envelope.status || "?";
+    console.error(
+      `[comet-lifecycle] ${routeTag} ${eventType} run=${envelope.runId} task=${envelope.taskThreadId} status=${statusTag}`
+    );
+  }
+
+  if (opts.persist !== false) {
+    const outDir = opts.outputDir || getDefaultAuditDir();
+    persistEvent(outDir, event);
+  }
+
+  // S070-T019: feed operational telemetry pipeline
+  emitTelemetryForLifecycle(eventType, envelope);
+
+  return event;
+}
+
+/**
+ * Validate that an envelope has all required fields.
+ * Returns { valid: true } or { valid: false, missing: string[] }.
+ */
+export function validateEnvelope(envelope) {
+  const missing = REQUIRED_FIELDS.filter((f) => !envelope[f]);
+  return missing.length === 0 ? { valid: true, missing: [] } : { valid: false, missing };
+}
+
+/**
+ * Build environment variables map to propagate lifecycle context to child scripts.
+ * Child scripts can read these to participate in the same lifecycle scope.
+ */
+export function lifecycleEnvVars(envelope) {
+  const vars = {
+    COMET_RUN_ID: envelope.runId,
+    COMET_RUN_ROUTE: envelope.route || "cli",
+    COMET_RUN_STATUS: envelope.status,
+  };
+  if (envelope.taskThreadId && envelope.taskThreadId !== "unknown") {
+    vars.COMET_TASK_GROUP = envelope.taskThreadId;
+  }
+  if (envelope.agentId) {
+    vars.COMET_AGENT_ID = envelope.agentId;
+  }
+  if (envelope.auditSessionId) {
+    vars.COMET_AUDIT_SESSION_ID = envelope.auditSessionId;
+  }
+  return vars;
+}
+
+/**
+ * Collect lifecycle context from environment variables.
+ * Inverse of lifecycleEnvVars; used by child scripts to discover parent lifecycle.
+ */
+export function readLifecycleFromEnv() {
+  return {
+    runId: process.env.COMET_RUN_ID || null,
+    route: process.env.COMET_RUN_ROUTE || null,
+    status: process.env.COMET_RUN_STATUS || null,
+    taskThreadId: process.env.COMET_TASK_GROUP || null,
+    agentId: process.env.COMET_AGENT_ID || null,
+    auditSessionId: process.env.COMET_AUDIT_SESSION_ID || null,
+  };
+}
+
+// ── Internal helpers ───────────────────────────────────────────
+
+/**
+ * Map lifecycle events to operational telemetry (S070-T019).
+ * Captures route usage on start, fallback triggers, and completion outcomes.
+ */
+function emitTelemetryForLifecycle(eventType, envelope) {
+  try {
+    if (eventType === "start") {
+      recordTelemetryEvent({
+        type: "route",
+        route: envelope.route || "cli",
+        channel: `comet-${envelope.route || "cli"}`,
+        agentId: envelope.agentId,
+        taskThreadId: envelope.taskThreadId,
+        runId: envelope.runId,
+      });
+      if (envelope.fallbackUsed) {
+        recordTelemetryEvent({
+          type: "fallback",
+          fallbackUsed: true,
+          fallbackReason: `primary-${envelope.route === "cli" ? "mcp" : envelope.route}-unavailable`,
+          agentId: envelope.agentId,
+          taskThreadId: envelope.taskThreadId,
+          runId: envelope.runId,
+        });
+      }
+    }
+    if (eventType === "complete" || eventType === "abort" || eventType === "fail") {
+      const outcomeMap = { complete: "completed", abort: "aborted", fail: "failed" };
+      const durationMs =
+        envelope.startedAt && envelope.completedAt
+          ? new Date(envelope.completedAt).getTime() - new Date(envelope.startedAt).getTime()
+          : undefined;
+      recordTelemetryEvent({
+        type: "completion",
+        outcome: outcomeMap[eventType] || envelope.status,
+        runId: envelope.runId,
+        taskThreadId: envelope.taskThreadId,
+        agentId: envelope.agentId,
+        durationMs: durationMs > 0 ? durationMs : undefined,
+      });
+    }
+  } catch {
+    // telemetry is best-effort
+  }
+}
+
+function getDefaultAuditDir() {
+  const base =
+    process.env.COMET_OUTPUT_BASE ||
+    join(process.env.HOME || "/tmp", ".claude/comet-browser/output");
+  return join(base, "audit");
+}
+
+function persistEvent(dir, event) {
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const filename = `lifecycle-${event.event}-${event.runId}-${Date.now()}.json`;
+    writeFileSync(join(dir, filename), JSON.stringify(event, null, 2));
+  } catch (err) {
+    console.error(`[comet-lifecycle] Failed to persist event: ${err.message}`);
+  }
+}
+
+export default {
+  createLifecycleEnvelope,
+  transitionEnvelope,
+  emitLifecycleEvent,
+  validateEnvelope,
+  lifecycleEnvVars,
+  readLifecycleFromEnv,
+};