cursor-opencode-provider 0.4.3 → 0.5.0

package/dist/protocol/blob-reachability.d.ts

@@ -0,0 +1,15 @@
+type ResolveBlob = (id: Uint8Array) => Uint8Array | undefined;
+/**
+ * Return the blob ids reachable from Cursor's latest ConversationStateStructure.
+ *
+ * This mirrors Cursor CLI's conversation-export traversal: turns lead to their
+ * user message and steps, shell turns lead to command/output, state-level
+ * summaries/todos/prompts are direct refs, and subagent states recurse. Unknown
+ * protobuf fields are deliberately ignored for forward compatibility.
+ *
+ * `resolveBlob` must also resolve Cursor's content-as-id values. Throwing on a
+ * missing hash or malformed referenced message makes the caller retain its full
+ * snapshot rather than risk publishing an incomplete restart graph.
+ */
+export declare function collectReachableConversationBlobIds(checkpoint: Uint8Array, resolveBlob: ResolveBlob): Set<string>;
+export {};

package/dist/protocol/blob-reachability.js

@@ -0,0 +1,140 @@
+import protobuf from "protobufjs";
+const MAX_NESTED_STATE_DEPTH = 64;
+function hex(bytes) {
+    let result = "";
+    for (let index = 0; index < bytes.length; index++) {
+        result += bytes[index].toString(16).padStart(2, "0");
+    }
+    return result;
+}
+/** Read only length-delimited fields while still validating the complete protobuf. */
+function bytesFields(data) {
+    const reader = protobuf.Reader.create(data);
+    const fields = [];
+    while (reader.pos < reader.len) {
+        const tag = reader.uint32();
+        const number = tag >>> 3;
+        const wireType = tag & 7;
+        if (number === 0)
+            throw new Error("invalid protobuf field zero");
+        if (wireType === 2)
+            fields.push({ number, bytes: reader.bytes() });
+        else
+            reader.skipType(wireType);
+    }
+    return fields;
+}
+function mapValue(entry) {
+    return bytesFields(entry).find((field) => field.number === 2)?.bytes;
+}
+/**
+ * Return the blob ids reachable from Cursor's latest ConversationStateStructure.
+ *
+ * This mirrors Cursor CLI's conversation-export traversal: turns lead to their
+ * user message and steps, shell turns lead to command/output, state-level
+ * summaries/todos/prompts are direct refs, and subagent states recurse. Unknown
+ * protobuf fields are deliberately ignored for forward compatibility.
+ *
+ * `resolveBlob` must also resolve Cursor's content-as-id values. Throwing on a
+ * missing hash or malformed referenced message makes the caller retain its full
+ * snapshot rather than risk publishing an incomplete restart graph.
+ */
+export function collectReachableConversationBlobIds(checkpoint, resolveBlob) {
+    const reachable = new Set();
+    const reference = (id) => {
+        if (id.length === 0)
+            return undefined;
+        reachable.add(hex(id));
+        const value = resolveBlob(id);
+        if (!value)
+            throw new Error(`missing referenced blob ${hex(id)}`);
+        return value;
+    };
+    const walkUserMessage = (data) => {
+        const selectedContext = bytesFields(data).find((field) => field.number === 3)?.bytes;
+        if (!selectedContext)
+            return;
+        for (const imageField of bytesFields(selectedContext)) {
+            if (imageField.number !== 1)
+                continue;
+            for (const imagePart of bytesFields(imageField.bytes)) {
+                if (imagePart.number === 1) {
+                    reference(imagePart.bytes);
+                }
+                else if (imagePart.number === 9) {
+                    const blobId = bytesFields(imagePart.bytes).find((field) => field.number === 1)?.bytes;
+                    if (blobId)
+                        reference(blobId);
+                }
+            }
+        }
+    };
+    const walkTurn = (data) => {
+        for (const turnField of bytesFields(data)) {
+            if (turnField.number === 1) {
+                for (const agentField of bytesFields(turnField.bytes)) {
+                    if (agentField.number === 1) {
+                        const userMessage = reference(agentField.bytes);
+                        if (userMessage)
+                            walkUserMessage(userMessage);
+                    }
+                    else if (agentField.number === 2) {
+                        reference(agentField.bytes);
+                    }
+                }
+                return;
+            }
+            if (turnField.number === 2) {
+                for (const shellField of bytesFields(turnField.bytes)) {
+                    if (shellField.number === 1 || shellField.number === 2) {
+                        reference(shellField.bytes);
+                    }
+                }
+                return;
+            }
+        }
+    };
+    const walkPersistedSubagent = (data, depth) => {
+        const nestedState = bytesFields(data).find((field) => field.number === 1)?.bytes;
+        if (nestedState)
+            walkState(nestedState, depth + 1);
+    };
+    const walkState = (data, depth) => {
+        if (depth > MAX_NESTED_STATE_DEPTH)
+            throw new Error("conversation state nesting is too deep");
+        for (const field of bytesFields(data)) {
+            switch (field.number) {
+                case 8: {
+                    const turn = reference(field.bytes);
+                    if (turn)
+                        walkTurn(turn);
+                    break;
+                }
+                case 1: // root_prompt_messages_json
+                case 3: // todos
+                case 6: // summary
+                case 7: // plan
+                case 13: // summary_archives
+                    reference(field.bytes);
+                    break;
+                case 16: { // map<string, SubagentPersistedState> subagent_states
+                    const persisted = mapValue(field.bytes);
+                    if (persisted)
+                        walkPersistedSubagent(persisted, depth);
+                    break;
+                }
+                case 31: { // map<string, bytes> subagent_state_refs
+                    const subagentId = mapValue(field.bytes);
+                    if (!subagentId)
+                        break;
+                    const persisted = reference(subagentId);
+                    if (persisted)
+                        walkPersistedSubagent(persisted, depth);
+                    break;
+                }
+            }
+        }
+    };
+    walkState(checkpoint, 0);
+    return reachable;
+}

package/dist/protocol/blob-store.d.ts

@@ -6,10 +6,47 @@
  * fails ("Unexpected token ... is not valid JSON").
  *
  * This store is keyed by conversation_id and survives across Run streams.
+ * At a successful TurnEnded it is compacted to the graph reachable from the
+ * latest checkpoint, matching Cursor CLI's conversation-export traversal.
  */
 export declare function setConversationBlob(conversationId: string, blobId: Uint8Array, blobData: Uint8Array): string;
 export declare function getConversationBlob(conversationId: string, blobId: Uint8Array): Uint8Array | undefined;
 export declare function conversationBlobCount(conversationId: string): number;
+export type ConversationBlobSnapshot = {
+    id: string;
+    data: Uint8Array;
+};
+export type ConversationBlobCompaction = {
+    blobs: ConversationBlobSnapshot[];
+    beforeCount: number;
+    beforeBytes: number;
+    afterCount: number;
+    afterBytes: number;
+    compacted: boolean;
+    fallbackReason?: string;
+};
+export type ConversationBlobGraphStats = {
+    count: number;
+    bytes: number;
+    complete: boolean;
+    fallbackReason?: string;
+};
+/**
+ * Measure the checkpoint-reachable blob graph without mutating the store.
+ * Incomplete graphs conservatively report the complete retained bucket, since
+ * that is what the KV channel may have to serve if the checkpoint is used.
+ */
+export declare function inspectConversationBlobGraph(conversationId: string, checkpoint: Uint8Array | undefined): ConversationBlobGraphStats;
+/** Copy all durable blobs so a completed turn can be persisted atomically. */
+export declare function snapshotConversationBlobs(conversationId: string): ConversationBlobSnapshot[];
+/**
+ * Keep only blobs reachable from the latest checkpoint and snapshot them.
+ * Malformed/unknown state or a missing referenced hash falls back to retaining
+ * every blob: cache size must never come at the cost of restart correctness.
+ */
+export declare function compactConversationBlobs(conversationId: string, checkpoint: Uint8Array | undefined): ConversationBlobCompaction;
+/** Replace the in-memory blob bucket when restoring a persisted conversation. */
+export declare function restoreConversationBlobs(conversationId: string, blobs: readonly ConversationBlobSnapshot[]): void;
 /** Drop all blobs for a conversation (compaction conversation reset). */
 export declare function clearConversationBlobs(conversationId: string): void;
 /** SHA-256 content hashes are 32 non-text bytes — never echo those as content. */

package/dist/protocol/blob-store.js

@@ -6,7 +6,10 @@
  * fails ("Unexpected token ... is not valid JSON").
  *
  * This store is keyed by conversation_id and survives across Run streams.
+ * At a successful TurnEnded it is compacted to the graph reachable from the
+ * latest checkpoint, matching Cursor CLI's conversation-export traversal.
  */
+import { collectReachableConversationBlobIds } from "./blob-reachability.js";
 function hex(b) {
     let s = "";
     for (let i = 0; i < b.length; i++)
@@ -14,6 +17,12 @@ function hex(b) {
     return s;
 }
 const byConversation = new Map();
+function retainedBlobStats(current) {
+    let bytes = 0;
+    for (const data of current.values())
+        bytes += data.length;
+    return { count: current.size, bytes };
+}
 function bucket(conversationId) {
     let m = byConversation.get(conversationId);
     if (!m) {
@@ -34,6 +43,112 @@ export function getConversationBlob(conversationId, blobId) {
 export function conversationBlobCount(conversationId) {
     return byConversation.get(conversationId)?.size ?? 0;
 }
+/**
+ * Measure the checkpoint-reachable blob graph without mutating the store.
+ * Incomplete graphs conservatively report the complete retained bucket, since
+ * that is what the KV channel may have to serve if the checkpoint is used.
+ */
+export function inspectConversationBlobGraph(conversationId, checkpoint) {
+    const current = byConversation.get(conversationId) ?? new Map();
+    const retainedStats = (fallbackReason) => ({
+        ...retainedBlobStats(current),
+        complete: fallbackReason === undefined,
+        ...(fallbackReason ? { fallbackReason } : {}),
+    });
+    if (!checkpoint?.length)
+        return retainedStats("checkpoint unavailable");
+    try {
+        const reachable = collectReachableConversationBlobIds(checkpoint, (id) => {
+            const stored = current.get(hex(id));
+            if (stored)
+                return stored;
+            return isBlobIdHash(id) ? undefined : id;
+        });
+        let count = 0;
+        let bytes = 0;
+        for (const id of reachable) {
+            const data = current.get(id);
+            if (!data)
+                continue;
+            count++;
+            bytes += data.length;
+        }
+        return { count, bytes, complete: true };
+    }
+    catch (error) {
+        return retainedStats(error instanceof Error ? error.message : String(error));
+    }
+}
+/** Copy all durable blobs so a completed turn can be persisted atomically. */
+export function snapshotConversationBlobs(conversationId) {
+    return [...(byConversation.get(conversationId) ?? [])].map(([id, data]) => ({
+        id,
+        data: Uint8Array.from(data),
+    }));
+}
+/**
+ * Keep only blobs reachable from the latest checkpoint and snapshot them.
+ * Malformed/unknown state or a missing referenced hash falls back to retaining
+ * every blob: cache size must never come at the cost of restart correctness.
+ */
+export function compactConversationBlobs(conversationId, checkpoint) {
+    const current = byConversation.get(conversationId) ?? new Map();
+    const before = retainedBlobStats(current);
+    const beforeCount = before.count;
+    const beforeBytes = before.bytes;
+    const fallback = (reason) => ({
+        blobs: snapshotConversationBlobs(conversationId),
+        beforeCount,
+        beforeBytes,
+        afterCount: beforeCount,
+        afterBytes: beforeBytes,
+        compacted: false,
+        fallbackReason: reason,
+    });
+    if (!checkpoint?.length)
+        return fallback("checkpoint unavailable");
+    try {
+        const reachable = collectReachableConversationBlobIds(checkpoint, (id) => {
+            const stored = current.get(hex(id));
+            if (stored)
+                return stored;
+            // Cursor occasionally uses short literal content as its own id.
+            return isBlobIdHash(id) ? undefined : id;
+        });
+        const retained = new Map([...current].filter(([id]) => reachable.has(id)));
+        if (retained.size > 0)
+            byConversation.set(conversationId, retained);
+        else
+            byConversation.delete(conversationId);
+        const afterBytes = [...retained.values()].reduce((total, data) => total + data.length, 0);
+        return {
+            blobs: snapshotConversationBlobs(conversationId),
+            beforeCount,
+            beforeBytes,
+            afterCount: retained.size,
+            afterBytes,
+            compacted: true,
+        };
+    }
+    catch (error) {
+        return fallback(error instanceof Error ? error.message : String(error));
+    }
+}
+/** Replace the in-memory blob bucket when restoring a persisted conversation. */
+export function restoreConversationBlobs(conversationId, blobs) {
+    if (!conversationId)
+        return;
+    const restored = new Map();
+    for (const blob of blobs) {
+        if (!/^(?:[0-9a-f]{2})+$/i.test(blob.id))
+            continue;
+        restored.set(blob.id.toLowerCase(), Uint8Array.from(blob.data));
+    }
+    if (restored.size > 0)
+        byConversation.set(conversationId, restored);
+    else
+        byConversation.delete(conversationId);
+}
 /** Drop all blobs for a conversation (compaction conversation reset). */
 export function clearConversationBlobs(conversationId) {
     byConversation.delete(conversationId);

package/dist/protocol/conversation-bind.d.ts

@@ -1,7 +1,20 @@
 export declare const MAX_ACTIVE_CONVERSATION_BINDINGS = 256;
 export declare function resetConversationBindingsForTests(): void;
+export declare function hasConversationBinding(sessionKey: string): boolean;
+export declare function isActiveConversationBinding(sessionKey: string, conversationId: string): boolean;
+/** Restore a validated durable binding before resolving the next Run. */
+export declare function restoreConversationBinding(sessionKey: string, conversationId: string): void;
 /** Deterministic UUID (version-4 shape) from an arbitrary session key. */
 export declare function sessionIdToUuid(sessionId: string): string;
+/**
+ * Stable Cursor conversation group for one OpenCode session.
+ *
+ * Individual conversation ids are reminted for compaction/rebase boundaries,
+ * while the native Cursor CLI keeps the enclosing agent-store group stable.
+ * With no host session identity, the current conversation is the only safe
+ * grouping scope available.
+ */
+export declare function resolveConversationGroupId(sessionKey: string | undefined, conversationId: string): string;
 /** Current Cursor conversation_id for an OpenCode session key, creating the default binding if needed. */
 export declare function peekConversationId(sessionKey: string): string;
 /**

package/dist/protocol/conversation-bind.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { clearCheckpoint } from "./checkpoint.js";
 import { clearConversationBlobs } from "./blob-store.js";
+import { clearFrozenRequestContext, transferFrozenRequestContext, } from "../context/frozen.js";
 /**
  * OpenCode session key → active Cursor conversation_id.
  *
@@ -22,11 +23,24 @@ function rememberConversation(sessionKey, conversationId) {
         activeBySession.delete(oldest[0]);
         clearCheckpoint(oldest[1]);
         clearConversationBlobs(oldest[1]);
+        clearFrozenRequestContext(oldest[1]);
     }
 }
 export function resetConversationBindingsForTests() {
     activeBySession.clear();
 }
+export function hasConversationBinding(sessionKey) {
+    return activeBySession.has(sessionKey);
+}
+export function isActiveConversationBinding(sessionKey, conversationId) {
+    return activeBySession.get(sessionKey) === conversationId;
+}
+/** Restore a validated durable binding before resolving the next Run. */
+export function restoreConversationBinding(sessionKey, conversationId) {
+    if (!sessionKey || !conversationId)
+        return;
+    rememberConversation(sessionKey, conversationId);
+}
 /** Deterministic UUID (version-4 shape) from an arbitrary session key. */
 export function sessionIdToUuid(sessionId) {
     const hash = createHash("sha256").update(`cursor-opencode-provider:conv:${sessionId}`).digest();
@@ -36,6 +50,17 @@ export function sessionIdToUuid(sessionId) {
     const hex = bytes.toString("hex");
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
+/**
+ * Stable Cursor conversation group for one OpenCode session.
+ *
+ * Individual conversation ids are reminted for compaction/rebase boundaries,
+ * while the native Cursor CLI keeps the enclosing agent-store group stable.
+ * With no host session identity, the current conversation is the only safe
+ * grouping scope available.
+ */
+export function resolveConversationGroupId(sessionKey, conversationId) {
+    return sessionKey ? sessionIdToUuid(sessionKey) : conversationId;
+}
 /** Current Cursor conversation_id for an OpenCode session key, creating the default binding if needed. */
 export function peekConversationId(sessionKey) {
     let id = activeBySession.get(sessionKey);
@@ -56,9 +81,10 @@ export function bindConversationId(sessionKey, opts) {
     }
     if (opts?.reset) {
         const previousId = activeBySession.get(sessionKey) ?? sessionIdToUuid(sessionKey);
+        const conversationId = crypto.randomUUID();
         clearCheckpoint(previousId);
         clearConversationBlobs(previousId);
-        const conversationId = crypto.randomUUID();
+        transferFrozenRequestContext(previousId, conversationId);
         rememberConversation(sessionKey, conversationId);
         return { conversationId, reset: true, previousId };
     }

package/dist/protocol/conversation-persistence.d.ts

@@ -0,0 +1,32 @@
+import type { ConversationBlobSnapshot } from "./blob-store.js";
+import type { OpencodeToolDef } from "./tools.js";
+export type PersistedConversation = {
+    sessionKey: string;
+    conversationId: string;
+    updatedAt: number;
+    checkpoint?: Uint8Array;
+    blobs: ConversationBlobSnapshot[];
+    requestContext: Record<string, unknown>;
+    toolCatalog: OpencodeToolDef[];
+    postCompactionRebase: boolean;
+};
+export type ConversationLoadStatus = "restored" | "missing" | "invalid" | "expired";
+export type PersistedConversationLoad = {
+    status: ConversationLoadStatus;
+    value?: PersistedConversation;
+};
+export declare function conversationCacheDirectoryPath(cacheDir: string): string;
+export declare function conversationCacheFilePath(cacheDir: string, sessionKey: string): string;
+/** Create the per-session cache directory and prune records older than 24 hours once per process. */
+export declare function initializeConversationPersistence(cacheDir: string, now?: number): Promise<void>;
+export declare function getPersistedConversation(cacheDir: string, sessionKey: string, now?: number): Promise<PersistedConversation | undefined>;
+/** Read a snapshot together with the reason restart hydration did not restore it. */
+export declare function loadPersistedConversation(cacheDir: string, sessionKey: string, now?: number): Promise<PersistedConversationLoad>;
+/** Replace one session's durable snapshot and refresh its 24-hour lease. */
+export declare function persistConversation(cacheDir: string, value: Omit<PersistedConversation, "updatedAt" | "postCompactionRebase" | "toolCatalog"> & {
+    postCompactionRebase?: boolean;
+    toolCatalog?: OpencodeToolDef[];
+}, now?: number): Promise<void>;
+/** Delete only the expected binding so an overlapping newer turn cannot be removed. */
+export declare function deletePersistedConversation(cacheDir: string, sessionKey: string, expectedConversationId?: string): Promise<void>;
+export declare function resetConversationPersistenceForTests(): void;