@shawnowen/comet-mcp 2.3.1 → 2.4.2

package/dist/session-registry.js

@@ -0,0 +1,500 @@
+// Session Registry — per-agent session management with isolation guarantees (Spec 034)
+// NEVER kills the browser process. NEVER closes other agents' tabs.
+import CDP from "chrome-remote-interface";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { CometCDPClient } from "./cdp-client.js";
+import { CometAI } from "./comet-ai.js";
+import { tabGroupsClient } from "./tab-groups.js";
+import { captureTaskThreadSnapshot } from "./snapshot-capture.js";
+import { dispatchAlert } from "./alert-dispatcher.js";
+import { deriveCodexSessionIdentity, windowBindingStore } from "./window-bindings.js";
+const MANIFEST_PATH = join(homedir(), ".claude", "comet-browser", "session-manifest.json");
+const ORPHAN_THRESHOLD_MS = 120 * 60 * 1000; // 120 minutes (Spec 016, Clarification Q2 — activity-based, resets on any CDP/heartbeat/tool activity)
+// ---- Advisory Lock (FR-017) ----
+class Mutex {
+    queue = Promise.resolve();
+    async acquire() {
+        let release;
+        const next = new Promise((resolve) => {
+            release = resolve;
+        });
+        const prev = this.queue;
+        this.queue = next;
+        await prev;
+        return release;
+    }
+}
+function resolveAgentRuntimeProfile(profile) {
+    const requested = profile?.trim() || "agent";
+    const canonical = requested === "oe"
+        ? "agent"
+        : requested === "moon" || requested === "human"
+            ? "human"
+            : requested;
+    if (canonical !== "agent") {
+        throw new Error(`PROFILE_OWNERSHIP_VIOLATION: profile ${requested} is human-owned or unknown and cannot be used by normal agent sessions`);
+    }
+    return {
+        profileId: "agent",
+        profileAlias: requested === "agent" ? "oe" : requested,
+        profileOwner: "agent",
+    };
+}
+// Spec 037: Generate a concise session name from a task goal description
+export function generateSessionName(taskGoal) {
+    const fillers = [
+        /^(please\s+)/i,
+        /^(i\s+want\s+to\s+)/i,
+        /^(i\s+need\s+to\s+)/i,
+        /^(can\s+you\s+)/i,
+        /^(research\s+and\s+find\s+all\s+of\s+my\s+)/i,
+        /^(find\s+and\s+)/i,
+        /^(go\s+and\s+)/i,
+    ];
+    let text = taskGoal.trim();
+    for (const filler of fillers) {
+        text = text.replace(filler, "");
+    }
+    // Remove trailing periods and extra whitespace
+    text = text
+        .replace(/\.\s*$/, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    // Title case
+    text = text
+        .split(" ")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+    // Truncate to 50 chars at word boundary
+    if (text.length > 50) {
+        text = text.substring(0, 50).replace(/\s\S*$/, "");
+    }
+    return text || "Untitled Session";
+}
+// ---- Session Registry ----
+export class SessionRegistry {
+    sessions = new Map();
+    currentSessionKey = null;
+    tabGroupMutex = new Mutex();
+    async register(options = {}) {
+        const agentId = options.agentId || process.env.COMET_AGENT_ID || "claude-code";
+        const taskThreadId = options.taskThreadId || process.env.COMET_TASK_GROUP || `session-${Date.now()}`;
+        const url = options.url || "https://www.perplexity.ai/";
+        const tabGroupColor = options.tabGroupColor || "blue";
+        const port = options.port || 9222;
+        const sessionKey = `${agentId}:${taskThreadId}`;
+        const runtimeProfile = resolveAgentRuntimeProfile(options.profile);
+        const codexIdentity = deriveCodexSessionIdentity({
+            codexSessionId: options.codexSessionId,
+            projectThreadId: options.projectThreadId,
+            projectThreadFamily: options.projectThreadFamily,
+            worktreePath: options.worktreePath,
+            repoSlug: options.repoSlug,
+            branchName: options.branchName,
+            sessionKey: options.codexSessionKey,
+            role: options.codexSessionRole,
+            strict: options.strictCodexIdentity,
+            fallbackAgentId: agentId,
+            fallbackTaskThreadId: taskThreadId,
+        }, { cwd: process.cwd() });
+        // Reap orphaned sessions before creating new one (FR-015)
+        await this.reapOrphans();
+        // 1. Ensure browser is running (never kill, retry with backoff)
+        const startResult = await this.ensureBrowserRunning(port);
+        // 2. Create a dedicated top-display full-screen bounds window for this session.
+        const cdpClient = new CometCDPClient();
+        const initialUrl = `about:blank#comet-session-${encodeURIComponent(sessionKey)}-${Date.now()}`;
+        const windowTab = await tabGroupsClient.createTopDisplayFullscreenWindowWithTab(initialUrl);
+        const newTab = await cdpClient.waitForTargetUrl(initialUrl);
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        // 3. Connect to the new tab using its unique ID (FR-016)
+        await cdpClient.connect(newTab.id);
+        await cdpClient.navigate(url, true);
+        // 4. Position on top display
+        await cdpClient.positionOnTopDisplay(newTab.id);
+        // 5. Create tab group with advisory lock (FR-017)
+        let tabGroupId = null;
+        let chromeTabId = null;
+        let windowId = null;
+        const release = await this.tabGroupMutex.acquire();
+        try {
+            const result = await this.createTabGroup(cdpClient, newTab, taskThreadId, tabGroupColor, windowTab.tabId, windowTab.windowId);
+            tabGroupId = result.tabGroupId;
+            chromeTabId = result.chromeTabId;
+            windowId = result.windowId;
+        }
+        finally {
+            release();
+        }
+        windowId ??= windowTab.windowId ?? (await this.getWindowIdForTarget(newTab.id, port));
+        if (windowId === null) {
+            throw new Error(`Unable to resolve Comet window ID for target ${newTab.id}`);
+        }
+        // 6. Create CometAI bound to this session's CDP client (Spec 034, Phase 5)
+        const cometAI = new CometAI(cdpClient);
+        // Spec 037: Generate session name from task goal
+        const sessionName = options.taskGoal ? generateSessionName(options.taskGoal) : undefined;
+        // Spec 037 T024: Detect orchestrator/subagent hierarchy — if another session
+        // already owns this tab group, this session is a subagent of that orchestrator.
+        let role = options.role || "orchestrator";
+        let parentSessionId = null;
+        if (tabGroupId !== null) {
+            for (const [existingKey, existingSession] of this.sessions) {
+                if (existingKey !== sessionKey &&
+                    existingSession.tabGroupId === tabGroupId &&
+                    existingSession.role === "orchestrator") {
+                    role = "subagent";
+                    parentSessionId = existingKey;
+                    break;
+                }
+            }
+        }
+        const bindingWindowId = windowId ?? windowTab.windowId;
+        const bindingResult = await windowBindingStore.createOrReuse({
+            ...codexIdentity,
+            windowId: bindingWindowId,
+            tabGroupId,
+            targetId: newTab.id,
+            profileId: runtimeProfile.profileId,
+            profileAlias: runtimeProfile.profileAlias,
+            profileOwner: runtimeProfile.profileOwner,
+        });
+        const session = {
+            agentId,
+            taskThreadId,
+            sessionKey,
+            targetId: newTab.id,
+            chromeTabId,
+            tabGroupId,
+            tabGroupColor,
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+            status: "active",
+            role,
+            sessionName,
+            taskGoal: options.taskGoal,
+            orchestratorUrl: undefined,
+            parentSessionId,
+            codexIdentity,
+            codexBinding: bindingResult.binding,
+            profileId: runtimeProfile.profileId,
+            profileAlias: runtimeProfile.profileAlias,
+            profileOwner: runtimeProfile.profileOwner,
+            cdpClient,
+            cometAI,
+        };
+        this.sessions.set(sessionKey, session);
+        this.currentSessionKey = sessionKey;
+        this.persistManifest();
+        return session;
+    }
+    get(sessionKey) {
+        const session = this.sessions.get(sessionKey);
+        if (session) {
+            session.lastActivity = Date.now();
+        }
+        return session;
+    }
+    getCurrent() {
+        if (!this.currentSessionKey)
+            return undefined;
+        return this.get(this.currentSessionKey);
+    }
+    // Spec 037: Update orchestrator URL after first prompt creates the thread
+    updateSessionUrl(sessionKey, orchestratorUrl) {
+        const session = this.sessions.get(sessionKey);
+        if (session) {
+            session.orchestratorUrl = orchestratorUrl;
+            this.persistManifest();
+        }
+    }
+    // Spec 037: Get manifest entry for a taskThreadId (used by HTTP bridge)
+    getManifestEntryByThread(taskThreadId) {
+        const manifest = this.loadManifest();
+        if (!manifest)
+            return undefined;
+        return manifest.sessions.find((e) => e.taskThreadId === taskThreadId);
+    }
+    async release(sessionKey, options = {}) {
+        const session = this.sessions.get(sessionKey);
+        if (!session)
+            return;
+        session.status = "disconnecting";
+        // Completion-driven snapshot (Spec 016, FR-003, T029)
+        if (options.taskStatus) {
+            const reason = options.taskStatus === "success" ? "completion" : "manual";
+            try {
+                await captureTaskThreadSnapshot(session, reason, options.taskStatus);
+            }
+            catch (snapErr) {
+                console.warn(`[comet-bridge] Release snapshot failed for ${sessionKey}: ${snapErr instanceof Error ? snapErr.message : snapErr}`);
+            }
+        }
+        // Update tab group color on release
+        if (options.updateGroupColor && session.tabGroupId !== null) {
+            try {
+                const { tabGroupsClient } = await import("./tab-groups.js");
+                await tabGroupsClient.updateGroup({
+                    groupId: session.tabGroupId,
+                    color: options.updateGroupColor,
+                });
+            }
+            catch (extErr) {
+                console.warn(`[comet-bridge] Tab group color update failed for ${sessionKey}: ${extErr instanceof Error ? extErr.message : extErr}`);
+            }
+        }
+        // Optionally close only this agent's tabs (FR-014)
+        if (options.closeTabs && session.chromeTabId !== null) {
+            try {
+                await session.cdpClient.closeTab(session.targetId);
+            }
+            catch (closeErr) {
+                console.warn(`[comet-bridge] Tab close failed for ${sessionKey}: ${closeErr instanceof Error ? closeErr.message : closeErr}`);
+            }
+        }
+        // Disconnect CDP client — only this session's connection (FR-009)
+        try {
+            await session.cdpClient.disconnect();
+        }
+        catch (disconnErr) {
+            // Already disconnected — expected during cleanup
+        }
+        this.sessions.delete(sessionKey);
+        if (this.currentSessionKey === sessionKey) {
+            this.currentSessionKey = null;
+        }
+        this.persistManifest();
+    }
+    async reapOrphans() {
+        const manifest = this.loadManifest();
+        if (!manifest || manifest.sessions.length === 0)
+            return 0;
+        const now = Date.now();
+        let reaped = 0;
+        const surviving = [];
+        for (const entry of manifest.sessions) {
+            const age = now - entry.lastActivity;
+            const isOld = age > ORPHAN_THRESHOLD_MS;
+            const isOwnedByThisProcess = this.sessions.has(entry.sessionKey);
+            if (isOld && !isOwnedByThisProcess) {
+                // Snapshot before close (Spec 016, FR-003, T028)
+                const pseudoSession = {
+                    agentId: entry.agentId,
+                    taskThreadId: entry.taskThreadId,
+                    sessionKey: entry.sessionKey,
+                    targetId: entry.targetId,
+                    chromeTabId: null,
+                    tabGroupId: entry.tabGroupId,
+                    tabGroupColor: "grey",
+                    createdAt: entry.createdAt,
+                    lastActivity: entry.lastActivity,
+                    status: "orphaned",
+                    role: null,
+                };
+                let snapshotPath = null;
+                try {
+                    const snapshot = await captureTaskThreadSnapshot(pseudoSession, "orphan-cleanup");
+                    snapshotPath = `${snapshot.agentId}_${snapshot.taskThreadId}_${snapshot.capturedAt.replace(/[:.]/g, "-")}.json`;
+                }
+                catch (snapshotErr) {
+                    // Snapshot failed — skip reaping this session (fail safe, not fail silent)
+                    dispatchAlert({
+                        type: "ORPHAN_DETECTED",
+                        message: `Task Thread ${entry.sessionKey} abandoned (${Math.round(age / 60000)}min idle) but snapshot failed — skipping cleanup.`,
+                        consumerId: entry.agentId,
+                        sessionKey: entry.sessionKey,
+                        context: { age: Math.round(age / 60000), error: String(snapshotErr) },
+                    });
+                    surviving.push(entry);
+                    continue;
+                }
+                // Verify the target still exists before reaping
+                try {
+                    const response = await fetch(`http://127.0.0.1:9222/json/list`);
+                    if (response.ok) {
+                        const targets = (await response.json());
+                        const targetExists = targets.some((t) => t.id === entry.targetId);
+                        if (targetExists) {
+                            // Close the orphaned tab
+                            try {
+                                await fetch(`http://127.0.0.1:9222/json/close/${entry.targetId}`);
+                            }
+                            catch (closeErr) {
+                                console.warn(`[comet-bridge] Orphan tab close failed for ${entry.sessionKey}: ${closeErr instanceof Error ? closeErr.message : closeErr}`);
+                            }
+                        }
+                    }
+                }
+                catch (cdpErr) {
+                    console.warn(`[comet-bridge] CDP not reachable during orphan reap for ${entry.sessionKey}: ${cdpErr instanceof Error ? cdpErr.message : cdpErr}`);
+                }
+                // Clean up tab group if possible
+                if (entry.tabGroupId !== null) {
+                    try {
+                        const { tabGroupsClient } = await import("./tab-groups.js");
+                        await tabGroupsClient.updateGroup({
+                            groupId: entry.tabGroupId,
+                            collapsed: true,
+                            title: `[reaped] ${entry.agentId}`,
+                        });
+                    }
+                    catch (grpErr) {
+                        console.warn(`[comet-bridge] Orphan tab group update failed for ${entry.sessionKey}: ${grpErr instanceof Error ? grpErr.message : grpErr}`);
+                    }
+                }
+                // Emit ORPHAN_REAPED alert with snapshot path
+                dispatchAlert({
+                    type: "ORPHAN_REAPED",
+                    message: `Task Thread ${entry.sessionKey} snapshot-closed after ${Math.round(age / 60000)}min idle.`,
+                    consumerId: entry.agentId,
+                    sessionKey: entry.sessionKey,
+                    context: { age: Math.round(age / 60000), snapshotPath },
+                });
+                try {
+                    const runIds = entry.codexBinding?.runIds ?? [];
+                    if (runIds.length > 0) {
+                        await Promise.all(runIds.map((runId) => windowBindingStore.transitionByRunId(runId, "reaped")));
+                    }
+                    else if (entry.codexBinding?.bindingId) {
+                        await windowBindingStore.transition(entry.codexBinding.bindingId, "reaped");
+                    }
+                }
+                catch (bindingErr) {
+                    console.warn(`[comet-bridge] Orphan binding transition failed for ${entry.sessionKey}: ${bindingErr instanceof Error ? bindingErr.message : bindingErr}`);
+                }
+                reaped++;
+                console.warn(`[comet-bridge] Reaped orphaned session: ${entry.sessionKey} (age: ${Math.round(age / 60000)}min, snapshot: ${snapshotPath})`);
+            }
+            else {
+                surviving.push(entry);
+            }
+        }
+        if (reaped > 0) {
+            this.writeManifest({ sessions: surviving, lastUpdated: now });
+        }
+        return reaped;
+    }
+    async ensureBrowserRunning(port = 9222) {
+        // Pre-restart snapshot: if there are active sessions, snapshot them before restart attempt (Spec 016, T035)
+        if (this.sessions.size > 0) {
+            for (const [, session] of this.sessions) {
+                if (session.status === "active") {
+                    try {
+                        await captureTaskThreadSnapshot(session, "crash", "in-progress");
+                    }
+                    catch (snapErr) {
+                        console.error(`[comet-bridge] Pre-restart snapshot FAILED for ${session.sessionKey}: ${snapErr instanceof Error ? snapErr.message : snapErr}`);
+                        dispatchAlert({
+                            type: "BROWSER_CRASH",
+                            message: `Pre-restart snapshot failed for ${session.sessionKey}. Session state may be lost.`,
+                            sessionKey: session.sessionKey,
+                            context: { error: String(snapErr) },
+                        });
+                    }
+                }
+            }
+        }
+        const cdpClient = new CometCDPClient();
+        return cdpClient.startComet(port);
+    }
+    // ---- Private Helpers ----
+    async createTabGroup(cdpClient, newTab, threadId, color, chromeTabIdHint, windowIdHint) {
+        try {
+            // Find the Chrome tab ID for our new tab by matching target URL
+            const allTabs = await tabGroupsClient.listTabs();
+            const matchedTab = allTabs.find((t) => t.url === newTab.url || t.url === newTab.url + "/");
+            // If URL match fails, use the tab with the highest ID (most recently created)
+            // This is still safe under the mutex lock — only one connect runs at a time
+            const fallbackTab = allTabs.length > 0
+                ? allTabs.reduce((latest, tab) => (tab.id > latest.id ? tab : latest), allTabs[0])
+                : null;
+            const chromeTabId = chromeTabIdHint || matchedTab?.id || fallbackTab?.id || null;
+            const windowId = windowIdHint ?? matchedTab?.windowId ?? fallbackTab?.windowId ?? null;
+            if (chromeTabId !== null && chromeTabId > 0) {
+                const groupTitle = threadId.slice(0, 50);
+                const result = await tabGroupsClient.createGroup({
+                    tabIds: [chromeTabId],
+                    title: groupTitle,
+                    color: color,
+                });
+                return { tabGroupId: result.groupId, chromeTabId, windowId };
+            }
+            return { tabGroupId: null, chromeTabId: null, windowId: null };
+        }
+        catch (tgErr) {
+            console.warn(`[comet-bridge] Tab group creation failed for ${threadId}: ${tgErr instanceof Error ? tgErr.message : tgErr}`);
+            return { tabGroupId: null, chromeTabId: null, windowId: null };
+        }
+    }
+    async getWindowIdForTarget(targetId, port) {
+        const client = await CDP({ host: "127.0.0.1", port, target: targetId });
+        try {
+            const { windowId } = await client.Browser.getWindowForTarget();
+            return windowId;
+        }
+        finally {
+            try {
+                await client.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    loadManifest() {
+        try {
+            const data = readFileSync(MANIFEST_PATH, "utf-8");
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    writeManifest(manifest) {
+        try {
+            mkdirSync(dirname(MANIFEST_PATH), { recursive: true });
+            writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2));
+        }
+        catch (writeErr) {
+            console.error(`[comet-bridge] Manifest write failed: ${writeErr instanceof Error ? writeErr.message : writeErr}`);
+        }
+    }
+    persistManifest() {
+        const entries = [];
+        for (const [, session] of this.sessions) {
+            entries.push({
+                sessionKey: session.sessionKey,
+                agentId: session.agentId,
+                taskThreadId: session.taskThreadId,
+                targetId: session.targetId,
+                tabGroupId: session.tabGroupId,
+                createdAt: session.createdAt,
+                lastActivity: session.lastActivity,
+                pid: process.pid,
+                sessionName: session.sessionName,
+                taskGoal: session.taskGoal,
+                orchestratorUrl: session.orchestratorUrl,
+                role: session.role || "orchestrator",
+                parentSessionId: session.parentSessionId,
+                codexIdentity: session.codexIdentity,
+                codexBinding: session.codexBinding,
+                profileId: session.profileId,
+                profileAlias: session.profileAlias,
+                profileOwner: session.profileOwner,
+            });
+        }
+        // Merge with existing manifest (other processes' sessions)
+        const existing = this.loadManifest();
+        const otherSessions = existing
+            ? existing.sessions.filter((e) => !this.sessions.has(e.sessionKey))
+            : [];
+        this.writeManifest({
+            sessions: [...otherSessions, ...entries],
+            lastUpdated: Date.now(),
+        });
+    }
+}
+export const sessionRegistry = new SessionRegistry();
+//# sourceMappingURL=session-registry.js.map

package/dist/sidecar-artifacts.d.ts

@@ -0,0 +1,49 @@
+export type SidecarArtifactStatus = "submitted" | "working" | "completed" | "timed_out" | "failed";
+export interface SidecarResultArtifact {
+    sidecarResultId: string;
+    sidecarContextKey: string;
+    bindingId: string;
+    sessionKey: string;
+    projectThreadId: string;
+    windowId: number;
+    targetId: string | null;
+    prompt: string;
+    status: SidecarArtifactStatus;
+    currentPageUrl: string;
+    response: string;
+    steps: string[];
+    currentStep: string;
+    error: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SidecarArtifactSnapshot {
+    version: 1;
+    artifacts: Record<string, SidecarResultArtifact>;
+    updatedAt: string;
+}
+export interface CreateSidecarArtifactInput {
+    sidecarContextKey: string;
+    bindingId: string;
+    sessionKey: string;
+    projectThreadId: string;
+    windowId: number;
+    targetId: string | null;
+    prompt: string;
+    currentPageUrl?: string;
+}
+export type SidecarArtifactPatch = Partial<Pick<SidecarResultArtifact, "status" | "currentPageUrl" | "response" | "steps" | "currentStep" | "error">>;
+export declare class SidecarArtifactStore {
+    private readonly file;
+    private readonly dir;
+    private readonly lockDir;
+    constructor(storePath?: string);
+    get path(): string;
+    load(): Promise<SidecarArtifactSnapshot>;
+    create(input: CreateSidecarArtifactInput): Promise<SidecarResultArtifact>;
+    update(sidecarResultId: string, patch: SidecarArtifactPatch): Promise<SidecarResultArtifact>;
+    get(sidecarResultId: string): Promise<SidecarResultArtifact | null>;
+    latestForContext(sidecarContextKey: string): Promise<SidecarResultArtifact | null>;
+}
+export declare const sidecarArtifactStore: SidecarArtifactStore;
+//# sourceMappingURL=sidecar-artifacts.d.ts.map

package/dist/sidecar-artifacts.js

@@ -0,0 +1,146 @@
+import { randomUUID } from "crypto";
+import { mkdir, readFile, rename, rm, unlink, writeFile } from "fs/promises";
+import os from "os";
+import path from "path";
+const DEFAULT_DIR = path.join(os.homedir(), ".claude", "comet-browser");
+const DEFAULT_FILE = path.join(DEFAULT_DIR, "sidecar-results.json");
+const LOCK_RETRY_MS = 25;
+const LOCK_TIMEOUT_MS = 5_000;
+function nowIso() {
+    return new Date().toISOString();
+}
+function pathsFor(storePath) {
+    const file = storePath ?? DEFAULT_FILE;
+    return { file, dir: path.dirname(file), lockDir: `${file}.lock` };
+}
+function emptySnapshot() {
+    return { version: 1, artifacts: {}, updatedAt: nowIso() };
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withFileLock(lockDir, fn) {
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            await mkdir(lockDir);
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST" || Date.now() - startedAt > LOCK_TIMEOUT_MS)
+                throw err;
+            await sleep(LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await rm(lockDir, { recursive: true, force: true });
+    }
+}
+async function readSnapshot(file) {
+    try {
+        const raw = await readFile(file, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            version: 1,
+            artifacts: parsed.artifacts ?? {},
+            updatedAt: parsed.updatedAt ?? nowIso(),
+        };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return emptySnapshot();
+        throw err;
+    }
+}
+async function writeSnapshot(file, dir, snapshot) {
+    await mkdir(dir, { recursive: true });
+    const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
+    try {
+        await writeFile(tmp, `${JSON.stringify(snapshot, null, 2)}\n`, "utf-8");
+        await rename(tmp, file);
+    }
+    catch (err) {
+        try {
+            await unlink(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}
+export class SidecarArtifactStore {
+    file;
+    dir;
+    lockDir;
+    constructor(storePath) {
+        const paths = pathsFor(storePath);
+        this.file = paths.file;
+        this.dir = paths.dir;
+        this.lockDir = paths.lockDir;
+    }
+    get path() {
+        return this.file;
+    }
+    async load() {
+        return readSnapshot(this.file);
+    }
+    async create(input) {
+        return withFileLock(this.lockDir, async () => {
+            const snapshot = await readSnapshot(this.file);
+            const timestamp = nowIso();
+            const artifact = {
+                sidecarResultId: randomUUID(),
+                sidecarContextKey: input.sidecarContextKey,
+                bindingId: input.bindingId,
+                sessionKey: input.sessionKey,
+                projectThreadId: input.projectThreadId,
+                windowId: input.windowId,
+                targetId: input.targetId,
+                prompt: input.prompt,
+                status: "submitted",
+                currentPageUrl: input.currentPageUrl ?? "unknown",
+                response: "",
+                steps: [],
+                currentStep: "",
+                error: null,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+            };
+            snapshot.artifacts[artifact.sidecarResultId] = artifact;
+            snapshot.updatedAt = timestamp;
+            await writeSnapshot(this.file, this.dir, snapshot);
+            return artifact;
+        });
+    }
+    async update(sidecarResultId, patch) {
+        return withFileLock(this.lockDir, async () => {
+            const snapshot = await readSnapshot(this.file);
+            const artifact = snapshot.artifacts[sidecarResultId];
+            if (!artifact)
+                throw new Error(`Unknown sidecarResultId: ${sidecarResultId}`);
+            Object.assign(artifact, patch, { updatedAt: nowIso() });
+            snapshot.updatedAt = artifact.updatedAt;
+            await writeSnapshot(this.file, this.dir, snapshot);
+            return artifact;
+        });
+    }
+    async get(sidecarResultId) {
+        const snapshot = await readSnapshot(this.file);
+        return snapshot.artifacts[sidecarResultId] ?? null;
+    }
+    async latestForContext(sidecarContextKey) {
+        const snapshot = await readSnapshot(this.file);
+        const matches = Object.values(snapshot.artifacts)
+            .filter((artifact) => artifact.sidecarContextKey === sidecarContextKey)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return matches[0] ?? null;
+    }
+}
+export const sidecarArtifactStore = new SidecarArtifactStore();
+//# sourceMappingURL=sidecar-artifacts.js.map