@shawnowen/comet-mcp 2.3.1 → 2.4.1

package/dist/task-thread-canonical.js

@@ -0,0 +1,116 @@
+/**
+ * Canonical Task Thread Types & Status Rule Set — Phase A
+ *
+ * AUTHORITATIVE LOCATION (FR-004): This file is the single source of truth
+ * for the Phase A canonical status vocabulary, conflict-resolution precedence,
+ * and valid lifecycle transition rules for the Comet browser surface worktree.
+ *
+ * In Phase B this document MUST link to or be replaced by the canonical rule
+ * from equa-taskthreads spec 003 (core API).
+ *
+ * Spec: specs/041-task-thread-sync/spec.md
+ * Plan: specs/041-task-thread-sync/plan.md §Canonical Status Rule Set
+ */
+/** Terminal statuses — once set by the lifecycle layer, cannot revert (FR-008) */
+export const TERMINAL_STATUSES = new Set(["Completed", "Aborted", "Archived"]);
+export function isTerminal(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+// ─── State Machine — Valid Transitions (FR-017, FR-019) ──────────────────────
+/**
+ * Maps each canonical status to the set of write actions the user may invoke
+ * from that state. The extension renders exactly these buttons (FR-017).
+ *
+ * Action names match the payload `action` field for POST /api/task-threads/:id/transition.
+ */
+export const VALID_TRANSITIONS = {
+    Dispatched: ["Start", "Abort"],
+    Running: ["Pause", "Mark Complete", "Abort"],
+    Paused: ["Resume", "Abort"],
+    Completed: ["Archive"],
+    Aborted: ["Archive"],
+    Archived: [], // terminal — no further transitions
+};
+// ─── Canonical Status Resolver (FR-002, FR-006–FR-009) ───────────────────────
+/**
+ * Derives exactly one canonical status from the union of underlying layer states.
+ *
+ * Precedence (FR-006, FR-007):
+ *   1. Lifecycle layer (highest authority — Lifecycle wins)
+ *   2. Snapshot layer
+ *   3. Session manifest layer
+ *   4. Archive layer
+ *   5. Alert log layer
+ *   6. Unknown → Archived (safe display fallback)
+ *
+ * Terminal states (Completed, Aborted, Archived) are sticky once set by
+ * the lifecycle layer (FR-008).
+ */
+export function resolveCanonicalStatus(layers) {
+    // 1. Lifecycle layer — highest authority
+    if (layers.lifecycle !== null) {
+        switch (layers.lifecycle) {
+            case "started": return "Running";
+            case "dispatched": return "Dispatched";
+            case "paused": return "Paused";
+            case "completed": return "Completed"; // terminal — sticky
+            case "aborted": return "Aborted"; // terminal — sticky
+        }
+    }
+    // 2. Snapshot layer
+    if (layers.snapshot !== null) {
+        switch (layers.snapshot) {
+            case "success": return "Completed";
+            case "failed":
+            case "abandoned": return "Aborted";
+            case "in-progress": return "Running";
+        }
+    }
+    // 3. Session manifest layer
+    if (layers.sessionManifest !== null) {
+        switch (layers.sessionManifest) {
+            case "active":
+            case "disconnecting": return "Running";
+            case "orphaned": return "Aborted"; // agent dead, no explicit transition
+        }
+    }
+    // 4. Archive layer
+    if (layers.archive !== null) {
+        switch (layers.archive) {
+            case "archived":
+            case "saved": return "Archived";
+        }
+    }
+    // 5. Alert log layer
+    if (layers.alertLog !== null) {
+        if (layers.alertLog === "ORPHAN_DETECTED" || layers.alertLog === "ORPHAN_REAPED") {
+            return "Aborted";
+        }
+        // Other alert types — fallthrough to Archived as safe default
+    }
+    // 6. No layer has a record — safe display fallback
+    return "Archived";
+}
+// ─── Transition Validation (FR-019) ──────────────────────────────────────────
+export class InvalidTransitionError extends Error {
+    fromStatus;
+    action;
+    constructor(fromStatus, action) {
+        super(`Action "${action}" is not valid from status "${fromStatus}". ` +
+            `Valid actions: ${VALID_TRANSITIONS[fromStatus].join(", ") || "none"}.`);
+        this.fromStatus = fromStatus;
+        this.action = action;
+        this.name = "InvalidTransitionError";
+    }
+}
+/**
+ * Throws InvalidTransitionError if the action is not valid from the given status.
+ * Does NOT perform the transition — call this before executing any write.
+ */
+export function assertValidTransition(status, action) {
+    const allowed = VALID_TRANSITIONS[status];
+    if (!allowed.includes(action)) {
+        throw new InvalidTransitionError(status, action);
+    }
+}
+//# sourceMappingURL=task-thread-canonical.js.map

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { CodexSessionIdentity, CodexWindowBinding } from "./window-bindings.js";
 export interface CDPTarget {
     id: string;
     type: string;
@@ -41,6 +42,8 @@ export interface CometState {
     port: number;
     currentUrl?: string;
     activeTabId?: string;
+    profileId?: string;
+    profileOwner?: "agent" | "human" | "shared_legacy" | "unknown";
 }
 export interface NetworkIdleResult {
     idle: boolean;
@@ -67,4 +70,238 @@ export interface TabInfo {
     url: string;
     active: boolean;
 }
+export type AgentActivityStatus = "active" | "idle" | "orphaned";
+export interface ObserverAgentStatus {
+    agentId: string;
+    agentType: string;
+    label: string;
+    status: AgentActivityStatus;
+    lastHeartbeat: string;
+    lastActivity: string | null;
+    idleSince: string | null;
+}
+export interface ObserverTabInfo {
+    id: string;
+    url: string;
+    title: string;
+    loadState: "complete" | "loading" | "error";
+    thumbnail: string | null;
+}
+export interface ObserverBindingInfo {
+    bindingId: string;
+    codexSessionId: string;
+    projectThreadId: string;
+    repoSlug: string;
+    worktreePath: string;
+    branchName: string;
+    sessionKey: string;
+    role: CodexSessionIdentity["role"];
+    sidecarContextKey: string;
+    status: CodexWindowBinding["status"];
+    windowId: number;
+    tabGroupId: number | null;
+    targetId: string | null;
+    runIds: string[];
+    updatedAt: string;
+}
+export interface ObserverWindowBindingInfo {
+    windowId: number;
+    binding: ObserverBindingInfo | null;
+    bindingStatus: CodexWindowBinding["status"] | "unbound";
+}
+export interface ObserverTabGroupInfo {
+    id: number;
+    title: string;
+    color: string;
+    collapsed: boolean;
+    windowId: number;
+    tabs: ObserverTabInfo[];
+    tabCount: number;
+    agent: ObserverAgentStatus | null;
+    binding: ObserverBindingInfo | null;
+    bindingStatus: CodexWindowBinding["status"] | "unbound";
+}
+export interface BrowserHealth {
+    running: boolean;
+    cdpConnected: boolean;
+    extensionAvailable: boolean;
+    tabCount: number;
+    groupCount: number;
+}
+export interface BrowserSnapshot {
+    timestamp: string;
+    browser: BrowserHealth;
+    groups: ObserverTabGroupInfo[];
+    ungroupedTabs: ObserverTabInfo[];
+    windows: ObserverWindowBindingInfo[];
+    bindings: ObserverBindingInfo[];
+    totalTabs: number;
+    totalGroups: number;
+}
+export interface ObserverFilters {
+    group?: string;
+    agentId?: string;
+    urlPattern?: string;
+    thumbnails?: boolean;
+    codexIdentity?: CodexSessionIdentity;
+}
+export interface AgentRegistryEntry {
+    agentId: string;
+    agentType: string;
+    label: string;
+    lane: number;
+    status: string;
+    taskGroup: string | null;
+    tabGroupId: number | null;
+    tabGroupColor: string | null;
+    currentUrl: string | null;
+    taskDescription: string | null;
+    startedAt: string | null;
+    lastHeartbeat: string;
+    completedAt: string | null;
+    errorMessage: string | null;
+    capabilities?: string[];
+}
+export interface AgentRegistry {
+    schema: string;
+    lastUpdated: string;
+    agents: Record<string, AgentRegistryEntry>;
+}
+export type ConsumerRole = "orchestrator" | "subagent";
+export type ErrorEventType = "PERPLEXITY_VOICE_MODE" | "PERPLEXITY_IDLE_NO_NAV" | "PERPLEXITY_CONTEXT_BLEED" | "BROWSER_CRASH" | "CRASH_LOOP_CAP" | "CDP_DISCONNECT" | "ORPHAN_DETECTED" | "ORPHAN_REAPED" | "DUPLICATE_PROCESS" | "PROTOCOL_VIOLATION";
+export type ErrorSeverity = "critical" | "operational" | "warning";
+export type AlertRoutingTarget = "operator-direct" | "orchestrator-first" | "orchestrator-only";
+export interface DeliveryStatus {
+    macosNotification: boolean;
+    logFile: boolean;
+    mcpQueue: boolean;
+}
+export interface ErrorEvent {
+    id: string;
+    timestamp: string;
+    type: ErrorEventType;
+    severity: ErrorSeverity;
+    consumerId: string | null;
+    sessionKey: string | null;
+    message: string;
+    context: Record<string, unknown>;
+    suggestedAction: string;
+    delivered: DeliveryStatus;
+}
+export interface AlertRouting {
+    critical: AlertRoutingTarget;
+    operational: AlertRoutingTarget;
+    warning: AlertRoutingTarget;
+}
+export interface RoleConfig {
+    operatorId: string;
+    orchestratorAgentId: string | null;
+}
+export interface BridgeConfig {
+    version: string;
+    cleanup: {
+        orphanThresholdMinutes: number;
+        snapshotBeforeClose: boolean;
+        snapshotDir: string;
+    };
+    crashRecovery: {
+        maxRestarts: number;
+        windowMinutes: number;
+        autoRestart: boolean;
+        crashHistoryPath: string;
+    };
+    alerts: {
+        logPath: string;
+        macosNotifications: boolean;
+        mcpErrorQueue: boolean;
+        routing: AlertRouting;
+    };
+    roles: RoleConfig;
+    protocolEnforcement: {
+        requireConnectBeforeBrowse: boolean;
+        warnMissingTabGroup: boolean;
+    };
+}
+export interface TabSnapshot {
+    url: string;
+    title: string;
+    chromeTabId: number;
+    targetId: string;
+    active: boolean;
+}
+export interface SidecarSnapshot {
+    threadUrl: string;
+    parentTabUrl: string;
+    lastQuery: string | null;
+}
+export interface WindowMetadata {
+    windowId: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    displayIndex: number;
+}
+export type SnapshotReason = "orphan-cleanup" | "completion" | "crash" | "manual";
+export type TaskThreadStatus = "success" | "failed" | "abandoned" | "in-progress";
+export interface TaskThreadSnapshot {
+    sessionKey: string;
+    agentId: string;
+    taskThreadId: string;
+    capturedAt: string;
+    reason: SnapshotReason;
+    taskStatus: TaskThreadStatus;
+    tabs: TabSnapshot[];
+    sidecarThreads: SidecarSnapshot[];
+    windowMetadata: WindowMetadata | null;
+    tabGroupId: number | null;
+    tabGroupColor: TabGroupColor;
+}
+export type SessionStatus = "active" | "disconnecting" | "orphaned";
+export interface AgentSession {
+    agentId: string;
+    taskThreadId: string;
+    sessionKey: string;
+    targetId: string;
+    chromeTabId: number | null;
+    tabGroupId: number | null;
+    tabGroupColor: TabGroupColor;
+    createdAt: number;
+    lastActivity: number;
+    status: SessionStatus;
+    role: ConsumerRole | null;
+    sessionName?: string;
+    taskGoal?: string;
+    orchestratorUrl?: string;
+    parentSessionId?: string | null;
+    codexIdentity?: CodexSessionIdentity;
+    codexBinding?: CodexWindowBinding;
+    profileId?: string;
+    profileOwner?: "agent" | "human" | "shared_legacy" | "unknown";
+    profileAlias?: string | null;
+}
+export interface ManifestEntry {
+    sessionKey: string;
+    agentId: string;
+    taskThreadId: string;
+    targetId: string;
+    tabGroupId: number | null;
+    createdAt: number;
+    lastActivity: number;
+    pid: number;
+    sessionName?: string;
+    taskGoal?: string;
+    orchestratorUrl?: string;
+    role?: "orchestrator" | "subagent";
+    parentSessionId?: string | null;
+    codexIdentity?: CodexSessionIdentity;
+    codexBinding?: CodexWindowBinding;
+    profileId?: string;
+    profileOwner?: "agent" | "human" | "shared_legacy" | "unknown";
+    profileAlias?: string | null;
+}
+export interface SessionManifest {
+    sessions: ManifestEntry[];
+    lastUpdated: number;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/window-bindings.d.ts

@@ -0,0 +1,112 @@
+export type CodexBindingStatus = "active" | "completed" | "stale" | "reaped" | "conflict";
+export type CodexSessionRole = "session_agent" | "worktree_orchestrator" | "fleet_orchestrator";
+export type ProfileOwnershipDomain = "agent" | "human" | "shared_legacy" | "unknown";
+export interface CodexSessionIdentity {
+    codexSessionId: string;
+    projectThreadId: string;
+    projectThreadFamily?: string;
+    worktreePath: string;
+    repoSlug: string;
+    branchName: string;
+    sessionKey: string;
+    role: CodexSessionRole;
+}
+export interface CodexIdentityInput {
+    codexSessionId?: string;
+    projectThreadId?: string;
+    projectThreadFamily?: string;
+    worktreePath?: string;
+    repoSlug?: string;
+    branchName?: string;
+    sessionKey?: string;
+    role?: string;
+    strict?: boolean;
+    fallbackAgentId?: string;
+    fallbackTaskThreadId?: string;
+}
+export interface CodexIdentityContext {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+export interface CodexWindowBinding extends CodexSessionIdentity {
+    bindingId: string;
+    runIds: string[];
+    windowId: number;
+    tabGroupId: number | null;
+    targetId: string | null;
+    profileId: string;
+    profileAlias: string | null;
+    profileOwner: ProfileOwnershipDomain;
+    sidecarContextKey: string;
+    status: CodexBindingStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RunBindingIndexEntry {
+    runId: string;
+    bindingId: string;
+    updatedAt: string;
+}
+export interface WindowBindingSnapshot {
+    version: 1;
+    bindings: Record<string, CodexWindowBinding>;
+    runBindingIndex: Record<string, RunBindingIndexEntry>;
+    updatedAt: string;
+}
+export interface CreateBindingInput extends CodexSessionIdentity {
+    windowId: number;
+    tabGroupId?: number | null;
+    targetId?: string | null;
+    profileId?: string;
+    profileAlias?: string | null;
+    profileOwner?: ProfileOwnershipDomain;
+    runIds?: string[];
+    sidecarContextKey?: string;
+}
+export interface CreateOrReuseResult {
+    binding: CodexWindowBinding;
+    action: "created" | "reused" | "repaired";
+}
+export interface BindingMutationOptions {
+    targetBindingId?: string;
+    reason?: string;
+    audit?: boolean;
+}
+export declare class WindowBindingConflictError extends Error {
+    readonly conflicts: CodexWindowBinding[];
+    constructor(message: string, conflicts: CodexWindowBinding[]);
+}
+export declare class CodexIdentityError extends Error {
+    readonly missingFields: string[];
+    constructor(message: string, missingFields: string[]);
+}
+export declare function resolveCodexSessionRole(role?: string): CodexSessionRole;
+export declare function deriveCodexSessionIdentity(input?: CodexIdentityInput, context?: CodexIdentityContext): CodexSessionIdentity;
+export declare function isBindingInWorktreeScope(caller: CodexSessionIdentity, binding: CodexWindowBinding): boolean;
+export declare function canReadBinding(caller: CodexSessionIdentity, binding: CodexWindowBinding): boolean;
+export declare function canMutateBinding(caller: CodexSessionIdentity, binding: CodexWindowBinding, options?: BindingMutationOptions): boolean;
+export declare function assertBindingMutationAllowed(caller: CodexSessionIdentity, binding: CodexWindowBinding, options?: BindingMutationOptions): void;
+export declare function normalizeProfileOwner(owner?: string): ProfileOwnershipDomain;
+export declare function assertBindingProfileAllowed(identity: CodexSessionIdentity, binding: Pick<CodexWindowBinding, "profileId" | "profileOwner">): void;
+export declare class CodexWindowBindingStore {
+    private readonly file;
+    private readonly dir;
+    private readonly lockDir;
+    constructor(storePath?: string);
+    get path(): string;
+    load(): Promise<WindowBindingSnapshot>;
+    list(): Promise<CodexWindowBinding[]>;
+    get(bindingId: string): Promise<CodexWindowBinding | null>;
+    findActiveByIdentity(identity: CodexSessionIdentity): Promise<CodexWindowBinding | null>;
+    findByRunId(runId: string): Promise<CodexWindowBinding | null>;
+    createOrReuse(input: CreateBindingInput): Promise<CreateOrReuseResult>;
+    addRunId(bindingId: string, runId: string): Promise<CodexWindowBinding>;
+    transition(bindingId: string, status: Exclude<CodexBindingStatus, "conflict">): Promise<CodexWindowBinding>;
+    transitionByRunId(runId: string, status: Exclude<CodexBindingStatus, "conflict">): Promise<CodexWindowBinding | null>;
+    classifyConflicts(): Promise<CodexWindowBinding[]>;
+    markStaleForMissingWindows(liveWindowIds: Iterable<number>): Promise<CodexWindowBinding[]>;
+    private assertNoActiveConflicts;
+    private findActiveConflicts;
+}
+export declare const windowBindingStore: CodexWindowBindingStore;
+//# sourceMappingURL=window-bindings.d.ts.map