cursor-opencode-provider 0.8.1 → 0.8.3

package/dist/pricing.js

@@ -47,9 +47,9 @@ export function validateOpenCodeModelCost(value, path = "cost") {
 export function isOpenCodeModelCost(value) {
     return validateOpenCodeModelCost(value).valid;
 }
-/** Strip synthetic OpenCode suffixes (`…-1m`, `…-1m-2`, `…-1m-fast`, …). */
+/** Strip synthetic context suffixes (`…-1m`, `…-500k`, `…-500k-2-fast`, …). */
 export function wireModelIdForPricing(modelId) {
-    const match = /^(.*)-1m(?:-\d+)?(-fast)?$/.exec(modelId);
+    const match = /^(.*)-\d+(?:\.\d+)?[km](?:-\d+)?(-fast)?$/.exec(modelId);
     if (match) {
         return { baseId: `${match[1]}${match[2] ?? ""}`, longContextEntry: true };
     }
@@ -79,8 +79,11 @@ function asMutableCost(value) {
  * Synthetic `-fast` entries are stored as their own keys.
  */
 export function getCursorModelCost(modelId) {
-    const { baseId } = wireModelIdForPricing(modelId);
-    const found = CURSOR_MODEL_COSTS[baseId];
+    const costs = CURSOR_MODEL_COSTS;
+    // A priced wire id wins over suffix stripping (`-<n>k` / `-<n>m` may be real).
+    const found = Object.hasOwn(costs, modelId)
+        ? costs[modelId]
+        : costs[wireModelIdForPricing(modelId).baseId];
     if (!found)
         return undefined;
     return asMutableCost(found);

package/dist/process-shared.d.ts

@@ -0,0 +1,14 @@
+/**
+ * State shared by every copy of this package in one process.
+ *
+ * OpenCode 2 imports a separate copy of a plugin's module graph for each
+ * location (project directory) it serves, all in one realm. Module-level state
+ * then exists once per copy, so per-account work such as credential renewal ran
+ * once per location. Keep that state here instead.
+ *
+ * Store plain data only (maps, strings, numbers, promises): every copy has its
+ * own classes, so an instance stored by one copy fails `instanceof` in another.
+ * Name keys with a version suffix (`….v1`) and bump it when the stored shape
+ * changes, so two package versions in one process never read each other's data.
+ */
+export declare function processShared<T>(name: string, create: () => T): T;

package/dist/process-shared.js

@@ -0,0 +1,18 @@
+/**
+ * State shared by every copy of this package in one process.
+ *
+ * OpenCode 2 imports a separate copy of a plugin's module graph for each
+ * location (project directory) it serves, all in one realm. Module-level state
+ * then exists once per copy, so per-account work such as credential renewal ran
+ * once per location. Keep that state here instead.
+ *
+ * Store plain data only (maps, strings, numbers, promises): every copy has its
+ * own classes, so an instance stored by one copy fails `instanceof` in another.
+ * Name keys with a version suffix (`….v1`) and bump it when the stored shape
+ * changes, so two package versions in one process never read each other's data.
+ */
+export function processShared(name, create) {
+    const key = Symbol.for(`cursor-opencode-provider.${name}`);
+    const registry = globalThis;
+    return registry[key] ??= create();
+}

package/dist/protocol/apply-patch.d.ts

@@ -1,6 +1,6 @@
 /**
- * Synthesis of OpenCode `apply_patch` envelopes from Cursor's native write/edit
- * exec requests.
+ * Synthesis of OpenCode `apply_patch` (2.0: `patch`) envelopes from Cursor's
+ * native write/edit exec requests.
  *
  * ## Why this exists
  *
@@ -36,10 +36,12 @@
  *   `ctx.session.context(...)` hook exposing a mutable tool roster, and lists
  *   "Select `apply_patch` versus `edit` + `write`" as work to move out of the
  *   registry. Once that lands, a host-side opt-out replaces this shim.
- * - OpenCode 2.0 (`packages/core`) has **no** such gate: `apply_patch`, `edit`
- *   and `write` are all registered unconditionally in `tool/builtins.ts`. This
- *   translation is therefore 1.x-only in practice, but it is keyed off the
- *   advertised set rather than a version check, so it simply never fires on 2.0.
+ * - OpenCode 2.0 (`packages/core`) keeps the gate under a new name. The tool is
+ *   `patch` (still `{ patchText }`, same envelope format), and
+ *   `tool/plugin/patch.ts` applies the same model-id predicate in its session
+ *   `context`/`compaction`/`generate` hooks, deleting `edit` and `write` for GPT models and
+ *   `patch` for everyone else. Both names are recognised here; which one the
+ *   host offers is read from the advertised set rather than a version check.
  *
  * ## Why translation, not advertisement
  *
@@ -59,7 +61,7 @@
  * native requests arrive for every model. Those names are absent from
  * the catalog, so the request is refused before it reaches OpenCode.
  *
- * ## Format notes (verified against `packages/opencode/src/patch/index.ts`)
+ * ## Format notes (verified against `packages/opencode/src/patch/index.ts` and 2.0's `packages/util/src/patch.ts`)
  *
  * - `*** Add File:` **overwrites an existing file** — the tool's `add` case uses
  *   `oldContent = ""` and never stats the target (upstream test: "adds file
@@ -71,15 +73,25 @@
  * - Every payload line is prefixed with `+`, `-`, or a space, and the parser
  *   only breaks on *unprefixed* `***` / `@@`. Content lines that themselves
  *   begin with `***` or `@@` therefore survive a round trip unharmed.
- * - `Add File` content is rejoined with `\n` and normalized to exactly one
- *   trailing newline. A write of content with no trailing newline gains one.
+ * - `Add File` content is rejoined with `\n`; the tool appends a final newline
+ *   only when nonempty content lacks one. Keep the trailing empty payload line
+ *   so blank lines survive. Nonempty unterminated content cannot round-trip.
+ * - OpenCode 2's `patch` parser strips a trailing `\r` from every payload
+ *   line, unlike 1.x `apply_patch`. Refuse that lossy encoding on `patch`.
  * - Update chunks match **whole lines** via `seekSequence`, unlike OpenCode
  *   `edit`, which is substring-based. Substring edits must be expanded to line
  *   boundaries before they can be expressed as a patch — see `planSubstringEdit`.
- * - Renames are rejected by OpenCode 2.0's implementation ("apply_patch moves
- *   are not supported yet"), so `*** Move to:` is never emitted here.
+ * - Cursor's write/edit requests never rename, so `*** Move to:` is never
+ *   emitted here.
  */
+/** OpenCode 1.x name for the patch tool. */
 export declare const APPLY_PATCH_TOOL = "apply_patch";
+/** OpenCode 2.0 name for the same tool (renamed from `apply_patch`). */
+export declare const PATCH_TOOL = "patch";
+export type HostPatchTool = typeof APPLY_PATCH_TOOL | typeof PATCH_TOOL;
+/** The patch tool this host advertises in place of `edit`/`write`, if any. */
+export declare function hostPatchTool(advertised: ReadonlySet<string>): HostPatchTool | undefined;
+export declare function isHostPatchTool(name: string): name is HostPatchTool;
 /** One `@@` chunk: replace `oldLines` with `newLines`. */
 export type UpdateChunk = {
     oldLines: string[];
@@ -89,9 +101,9 @@ export type UpdateChunk = {
  * Whole-file write as `*** Add File:`. Valid whether or not the target exists —
  * OpenCode's add case overwrites unconditionally.
  */
-export declare function buildAddFilePatch(filePath: string, content: string): string;
+export declare function buildAddFilePatch(filePath: string, content: string, tool?: HostPatchTool): string;
 /** Targeted replacement as `*** Update File:` with one `@@` chunk per change. */
-export declare function buildUpdateFilePatch(filePath: string, chunks: UpdateChunk[]): string;
+export declare function buildUpdateFilePatch(filePath: string, chunks: UpdateChunk[], tool?: HostPatchTool): string;
 export type SubstringEditPlan = {
     ok: true;
     chunks: UpdateChunk[];

package/dist/protocol/apply-patch.js

@@ -1,6 +1,6 @@
 /**
- * Synthesis of OpenCode `apply_patch` envelopes from Cursor's native write/edit
- * exec requests.
+ * Synthesis of OpenCode `apply_patch` (2.0: `patch`) envelopes from Cursor's
+ * native write/edit exec requests.
  *
  * ## Why this exists
  *
@@ -36,10 +36,12 @@
  *   `ctx.session.context(...)` hook exposing a mutable tool roster, and lists
  *   "Select `apply_patch` versus `edit` + `write`" as work to move out of the
  *   registry. Once that lands, a host-side opt-out replaces this shim.
- * - OpenCode 2.0 (`packages/core`) has **no** such gate: `apply_patch`, `edit`
- *   and `write` are all registered unconditionally in `tool/builtins.ts`. This
- *   translation is therefore 1.x-only in practice, but it is keyed off the
- *   advertised set rather than a version check, so it simply never fires on 2.0.
+ * - OpenCode 2.0 (`packages/core`) keeps the gate under a new name. The tool is
+ *   `patch` (still `{ patchText }`, same envelope format), and
+ *   `tool/plugin/patch.ts` applies the same model-id predicate in its session
+ *   `context`/`compaction`/`generate` hooks, deleting `edit` and `write` for GPT models and
+ *   `patch` for everyone else. Both names are recognised here; which one the
+ *   host offers is read from the advertised set rather than a version check.
  *
  * ## Why translation, not advertisement
  *
@@ -59,7 +61,7 @@
  * native requests arrive for every model. Those names are absent from
  * the catalog, so the request is refused before it reaches OpenCode.
  *
- * ## Format notes (verified against `packages/opencode/src/patch/index.ts`)
+ * ## Format notes (verified against `packages/opencode/src/patch/index.ts` and 2.0's `packages/util/src/patch.ts`)
  *
  * - `*** Add File:` **overwrites an existing file** — the tool's `add` case uses
  *   `oldContent = ""` and never stats the target (upstream test: "adds file
@@ -71,37 +73,75 @@
  * - Every payload line is prefixed with `+`, `-`, or a space, and the parser
  *   only breaks on *unprefixed* `***` / `@@`. Content lines that themselves
  *   begin with `***` or `@@` therefore survive a round trip unharmed.
- * - `Add File` content is rejoined with `\n` and normalized to exactly one
- *   trailing newline. A write of content with no trailing newline gains one.
+ * - `Add File` content is rejoined with `\n`; the tool appends a final newline
+ *   only when nonempty content lacks one. Keep the trailing empty payload line
+ *   so blank lines survive. Nonempty unterminated content cannot round-trip.
+ * - OpenCode 2's `patch` parser strips a trailing `\r` from every payload
+ *   line, unlike 1.x `apply_patch`. Refuse that lossy encoding on `patch`.
  * - Update chunks match **whole lines** via `seekSequence`, unlike OpenCode
  *   `edit`, which is substring-based. Substring edits must be expanded to line
  *   boundaries before they can be expressed as a patch — see `planSubstringEdit`.
- * - Renames are rejected by OpenCode 2.0's implementation ("apply_patch moves
- *   are not supported yet"), so `*** Move to:` is never emitted here.
+ * - Cursor's write/edit requests never rename, so `*** Move to:` is never
+ *   emitted here.
  */
+/** OpenCode 1.x name for the patch tool. */
 export const APPLY_PATCH_TOOL = "apply_patch";
+/** OpenCode 2.0 name for the same tool (renamed from `apply_patch`). */
+export const PATCH_TOOL = "patch";
+/** The patch tool this host advertises in place of `edit`/`write`, if any. */
+export function hostPatchTool(advertised) {
+    if (advertised.has(APPLY_PATCH_TOOL))
+        return APPLY_PATCH_TOOL;
+    if (advertised.has(PATCH_TOOL))
+        return PATCH_TOOL;
+    return undefined;
+}
+export function isHostPatchTool(name) {
+    return name === APPLY_PATCH_TOOL || name === PATCH_TOOL;
+}
 const BEGIN = "*** Begin Patch";
 const END = "*** End Patch";
 /**
  * Whole-file write as `*** Add File:`. Valid whether or not the target exists —
  * OpenCode's add case overwrites unconditionally.
  */
-export function buildAddFilePatch(filePath, content) {
-    const lines = splitLines(content);
+export function buildAddFilePatch(filePath, content, tool = APPLY_PATCH_TOOL) {
+    assertPatchPath(filePath);
+    assertPatchText(content, tool);
+    if (content.startsWith("\uFEFF\uFEFF"))
+        throw new Error("the patch tool cannot preserve repeated leading byte-order marks");
+    if (content && !content.endsWith("\n"))
+        throw new Error("the patch tool cannot preserve content without a final newline");
+    const lines = content.split("\n");
     return [BEGIN, `*** Add File: ${filePath}`, ...lines.map((line) => `+${line}`), END].join("\n");
 }
 /** Targeted replacement as `*** Update File:` with one `@@` chunk per change. */
-export function buildUpdateFilePatch(filePath, chunks) {
+export function buildUpdateFilePatch(filePath, chunks, tool = APPLY_PATCH_TOOL) {
+    assertPatchPath(filePath);
     const body = [];
     for (const chunk of chunks) {
         body.push("@@");
-        for (const line of chunk.oldLines)
-            body.push(`-${line}`);
-        for (const line of chunk.newLines)
-            body.push(`+${line}`);
+        for (const [prefix, lines] of [["-", chunk.oldLines], ["+", chunk.newLines]]) {
+            for (const line of lines) {
+                if (line.includes("\n"))
+                    throw new Error("a patch payload line contains a newline");
+                assertPatchText(line, tool);
+                body.push(`${prefix}${line}`);
+            }
+        }
     }
     return [BEGIN, `*** Update File: ${filePath}`, ...body, END].join("\n");
 }
+function assertPatchPath(filePath) {
+    if (!filePath || filePath.trim() !== filePath || /[\0\r\n]/.test(filePath)) {
+        throw new Error("the target path cannot be represented exactly in a patch header");
+    }
+}
+function assertPatchText(text, tool) {
+    if (tool === PATCH_TOOL && /\r(?:\n|$)/.test(text)) {
+        throw new Error("the patch tool strips carriage returns from line endings; this content cannot be preserved");
+    }
+}
 /**
  * Expand a substring replacement to the whole lines it touches, because
  * `apply_patch` matches line sequences rather than substrings.
@@ -124,6 +164,13 @@ export function planSubstringEdit(source, oldString, newString, replaceAll = fal
             reason: `the text to replace appears ${offsets.length} times; it must be unique`,
         };
     }
+    const target = replaceAll ? source.replaceAll(oldString, () => newString) : source.replace(oldString, () => newString);
+    if (target.startsWith("\uFEFF\uFEFF") || (source.startsWith("\uFEFF") && !target.startsWith("\uFEFF"))) {
+        return { ok: false, reason: "the patch tool preserves one leading byte-order mark; this replacement cannot be preserved" };
+    }
+    if (target && !target.endsWith("\n")) {
+        return { ok: false, reason: "the patch tool cannot preserve content without a final newline" };
+    }
     const targets = replaceAll ? offsets : offsets.slice(0, 1);
     const chunks = [];
     let previousEnd = -1;
@@ -138,22 +185,24 @@ export function planSubstringEdit(source, oldString, newString, replaceAll = fal
         previousEnd = end;
         const before = source.slice(start, offset);
         const after = source.slice(offset + oldString.length, end);
-        chunks.push({
-            oldLines: splitLines(source.slice(start, end)),
-            newLines: splitLines(before + newString + after),
-        });
+        const oldLines = source.slice(start, end).split("\n");
+        // The host removes one final source terminator before matching. Interior
+        // empty lines are real context; stripping them deletes blank lines.
+        if (end === source.length && oldLines.at(-1) === "")
+            oldLines.pop();
+        chunks.push({ oldLines, newLines: (before + newString + after).split("\n") });
+    }
+    // The host also removes one terminator before applying updates, then adds it
+    // back only when the last line is nonempty. Restore an untouched blank tail
+    // explicitly; an EOF replacement already carries its complete terminator.
+    if (previousEnd < source.length && (target === "\n" || target.endsWith("\n\n"))) {
+        chunks.push({ oldLines: [], newLines: [""] });
     }
     return { ok: true, chunks };
 }
-/**
- * Split into patch payload lines. A trailing newline is dropped so it is not
- * emitted as a spurious empty line — OpenCode re-adds exactly one on apply.
- */
-function splitLines(text) {
-    const normalized = text.endsWith("\n") ? text.slice(0, -1) : text;
-    return normalized.split("\n");
-}
 function lineStart(source, offset) {
+    if (offset === 0)
+        return 0;
     const at = source.lastIndexOf("\n", offset - 1);
     return at === -1 ? 0 : at + 1;
 }

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

@@ -43,8 +43,12 @@ export declare function snapshotConversationBlobs(conversationId: string): Conve
  * 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.
+ * `keepInMemory`: snapshot only, for a Run still in progress, whose next
+ * checkpoint may reference blobs this one does not.
  */
-export declare function compactConversationBlobs(conversationId: string, checkpoint: Uint8Array | undefined): ConversationBlobCompaction;
+export declare function compactConversationBlobs(conversationId: string, checkpoint: Uint8Array | undefined, options?: {
+    keepInMemory?: boolean;
+}): 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). */

package/dist/protocol/blob-store.js

@@ -91,8 +91,10 @@ export function snapshotConversationBlobs(conversationId) {
  * 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.
+ * `keepInMemory`: snapshot only, for a Run still in progress, whose next
+ * checkpoint may reference blobs this one does not.
  */
-export function compactConversationBlobs(conversationId, checkpoint) {
+export function compactConversationBlobs(conversationId, checkpoint, options) {
     const current = byConversation.get(conversationId) ?? new Map();
     const before = retainedBlobStats(current);
     const beforeCount = before.count;
@@ -117,13 +119,15 @@ export function compactConversationBlobs(conversationId, checkpoint) {
             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);
+        if (!options?.keepInMemory) {
+            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),
+            blobs: [...retained].map(([id, data]) => ({ id, data: Uint8Array.from(data) })),
             beforeCount,
             beforeBytes,
             afterCount: retained.size,

package/dist/protocol/client-version.js

@@ -3,17 +3,19 @@ import path from "node:path";
 import { FALLBACK_CLIENT_VERSION, MODEL_CACHE_TTL_MS, VERSION_CACHE_FILE, } from "../shared.js";
 import { opencodeGlobalCacheDir } from "../context/paths.js";
 import { withAbortDeadline } from "../deadline.js";
+import { processShared } from "../process-shared.js";
 const INSTALL_URL = "https://cursor.com/install";
 const REMOTE_TIMEOUT_MS = 5_000;
 const BUILD_RE = /^\d{4}\.\d{2}\.\d{2}-[0-9A-Za-z][0-9A-Za-z.-]*$/;
 const CLIENT_VERSION_RE = /^cli-[0-9A-Za-z][0-9A-Za-z._-]*$/;
-let cachedResolution;
+// Once per process, not per copy of this package the host loads.
+const cache = processShared("client-version.v1", () => ({}));
 export function resetClientVersionCache() {
-    cachedResolution = undefined;
+    cache.resolution = undefined;
 }
 export function resolveClientVersion() {
-    cachedResolution ??= resolve();
-    return cachedResolution;
+    cache.resolution ??= resolve();
+    return cache.resolution;
 }
 async function resolve() {
     const env = process.env.CURSOR_CLIENT_VERSION?.trim();

package/dist/protocol/conversation-cache-header.d.ts

@@ -0,0 +1,23 @@
+import type { FileHandle } from "node:fs/promises";
+export declare const MAX_CACHE_HEADER_BYTES: number;
+export declare const MAX_CACHE_HEADER_INPUT_BYTES: number;
+export type ConversationCacheHeader = {
+    schemaVersion: number;
+    sessionKey: string;
+    conversationId: string;
+    updatedAt: number;
+};
+export type CacheHeaderResult = {
+    status: "metadata";
+    value: ConversationCacheHeader;
+} | {
+    status: "invalid" | "indeterminate";
+};
+/** A prefix is a retention hint, never evidence of payload/checksum validity. */
+export declare function parseConversationCacheHeader(bytes: Uint8Array): CacheHeaderResult | undefined;
+/**
+ * Inspect an opened generation without reading its checkpoint/blobs/context.
+ * Positional reads leave the handle's offset at zero for subsequent full loading.
+ * Stop BOTH streams on success; merely breaking consumption leaves inflation live.
+ */
+export declare function readConversationCacheHeader(handle: FileHandle, signal?: AbortSignal): Promise<CacheHeaderResult>;

package/dist/protocol/conversation-cache-header.js

@@ -0,0 +1,149 @@
+import { Readable } from "node:stream";
+import { createGunzip } from "node:zlib";
+import { CONVERSATION_CACHE_SCHEMA_VERSION } from "../shared.js";
+export const MAX_CACHE_HEADER_BYTES = 8 * 1024;
+export const MAX_CACHE_HEADER_INPUT_BYTES = 128 * 1024;
+/**
+ * Schema 3 wrote the same canonical fields 1-4 prefix as the current schema, so
+ * its persisted age is trustworthy even though its body is no longer loadable.
+ */
+const OLDEST_CANONICAL_PREFIX_SCHEMA_VERSION = 3;
+/** A prefix is a retention hint, never evidence of payload/checksum validity. */
+export function parseConversationCacheHeader(bytes) {
+    let position = 0;
+    const incomplete = Symbol("incomplete header");
+    const indeterminate = Symbol("noncanonical header");
+    const varint = () => {
+        let value = 0n;
+        for (let index = 0; index < 10; index++) {
+            if (position === bytes.length)
+                throw incomplete;
+            const byte = bytes[position++];
+            if (index === 9 && byte > 1)
+                throw new Error("invalid cache header varint");
+            value |= BigInt(byte & 127) << BigInt(index * 7);
+            if (!(byte & 128))
+                return value;
+        }
+        throw new Error("invalid cache header varint");
+    };
+    const string = () => {
+        const length = varint();
+        if (length > BigInt(MAX_CACHE_HEADER_BYTES))
+            throw indeterminate;
+        const end = position + Number(length);
+        if (end > bytes.length)
+            throw incomplete;
+        const value = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(position, end));
+        position = end;
+        return value;
+    };
+    try {
+        // Only our writer's canonical prefix is eligible for metadata-only pruning.
+        // Other protobuf orders remain loadable through the full decoder.
+        if (varint() !== 8n)
+            return { status: "indeterminate" };
+        // A newer schema may lay out its prefix differently; never age it here.
+        const schemaVersion = varint();
+        if (schemaVersion < BigInt(OLDEST_CANONICAL_PREFIX_SCHEMA_VERSION) ||
+            schemaVersion > BigInt(CONVERSATION_CACHE_SCHEMA_VERSION))
+            return { status: "indeterminate" };
+        if (varint() !== 18n)
+            return { status: "indeterminate" };
+        const sessionKey = string();
+        if (varint() !== 26n)
+            return { status: "indeterminate" };
+        const conversationId = string();
+        if (varint() !== 32n)
+            return { status: "indeterminate" };
+        const updatedAt = Number(varint());
+        if (!sessionKey || !conversationId || !Number.isSafeInteger(updatedAt) || updatedAt < 0) {
+            return { status: "invalid" };
+        }
+        return {
+            status: "metadata",
+            value: { schemaVersion: Number(schemaVersion), sessionKey, conversationId, updatedAt },
+        };
+    }
+    catch (error) {
+        // A fragmented varint/string is normal streaming input, not corrupt data.
+        if (error === incomplete)
+            return undefined;
+        if (error === indeterminate)
+            return { status: "indeterminate" };
+        return { status: "invalid" };
+    }
+}
+/**
+ * Inspect an opened generation without reading its checkpoint/blobs/context.
+ * Positional reads leave the handle's offset at zero for subsequent full loading.
+ * Stop BOTH streams on success; merely breaking consumption leaves inflation live.
+ */
+export function readConversationCacheHeader(handle, signal) {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const prefix = Buffer.alloc(MAX_CACHE_HEADER_BYTES);
+        let length = 0;
+        let inputBytes = 0;
+        let settled = false;
+        let pendingRead;
+        // Own the positional reads ourselves. Destroying a ReadStream can close an
+        // externally supplied fd on some runtimes, even with autoClose:false.
+        const input = Readable.from((async function* () {
+            let position = 0;
+            while (!settled && position < MAX_CACHE_HEADER_INPUT_BYTES) {
+                const chunk = Buffer.alloc(Math.min(4096, MAX_CACHE_HEADER_INPUT_BYTES - position));
+                const read = handle.read(chunk, 0, chunk.length, position);
+                pendingRead = read;
+                const { bytesRead } = await read;
+                pendingRead = undefined;
+                if (!bytesRead || settled)
+                    return;
+                position += bytesRead;
+                inputBytes += bytesRead;
+                yield chunk.subarray(0, bytesRead);
+            }
+        })(), { objectMode: false, highWaterMark: 4096 });
+        const unzip = createGunzip({ chunkSize: 1024 });
+        const finish = (value, error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", abort);
+            input.unpipe(unzip);
+            input.destroy();
+            unzip.destroy();
+            // A read-ahead operation must settle before the caller reuses/closes the
+            // pinned handle. The async generator cannot start another after settled.
+            void Promise.resolve(pendingRead).then(() => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            }, reject);
+        };
+        const abort = () => finish(undefined, signal?.reason ?? new Error("cache inspection aborted"));
+        input.on("error", (error) => finish(undefined, error));
+        unzip.on("error", () => finish({
+            status: inputBytes >= MAX_CACHE_HEADER_INPUT_BYTES ? "indeterminate" : "invalid",
+        }));
+        unzip.on("end", () => finish({
+            status: inputBytes >= MAX_CACHE_HEADER_INPUT_BYTES ? "indeterminate" : "invalid",
+        }));
+        unzip.on("data", (chunk) => {
+            const available = Math.min(chunk.length, prefix.length - length);
+            prefix.set(chunk.subarray(0, available), length);
+            length += available;
+            const result = parseConversationCacheHeader(prefix.subarray(0, length));
+            if (result)
+                finish(result);
+            else if (length === prefix.length)
+                finish({ status: "indeterminate" });
+        });
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        else
+            input.pipe(unzip);
+    });
+}

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

@@ -13,19 +13,39 @@ export type PersistedConversation = {
     systemPromptHash?: string;
     /** JSON-encoded TurnProvenance (what this provider emitted last). */
     turnProvenance?: string;
+    /**
+     * Host note bodies the last turn ended without delivering (ordered; encoded
+     * via encodePersistedHostNotes). The Cursor checkpoint does not hold them.
+     */
+    hostNote?: string;
+    /** Bounded early-steer delivery receipts for the saved checkpoint. */
+    earlySteers?: string;
+    /** JSON lost-request record: user text sent on a checkpoint Cursor never advanced. */
+    lostRequest?: string;
+    /** Content hashes of the history images `sentImagesCheckpoint` holds. */
+    sentImageHashes?: string[];
+    /** SHA-256 hex of the checkpoint `sentImageHashes` belongs to; without it no image counts as held. */
+    sentImagesCheckpoint?: string;
 };
 export type ConversationLoadStatus = "restored" | "missing" | "invalid" | "expired";
 export type PersistedConversationLoad = {
     status: ConversationLoadStatus;
     value?: PersistedConversation;
 };
+type PersistenceTestPhase = "maintenance-start" | "before-quarantine" | "after-quarantine" | "full-decode" | "directory-opened" | "before-write";
+declare let testHook: ((phase: PersistenceTestPhase, filePath: string) => Promise<void> | void) | undefined;
 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. */
+/** Readiness includes directory permissions only; maintenance never gates hydration. */
 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>;
+/** Turn provenance of the current snapshot, without decoding its payload. */
+export declare function getPersistedTurnProvenance(cacheDir: string, sessionKey: string, now?: number): Promise<{
+    conversationId: string;
+    turnProvenance: string;
+} | undefined>;
 /** 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;
@@ -33,4 +53,10 @@ export declare function persistConversation(cacheDir: string, value: Omit<Persis
 }, 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>;
+/** Full snapshots still held in memory; the store should keep heads only. */
+export declare function retainedConversationSnapshotsForTests(): Promise<number>;
 export declare function resetConversationPersistenceForTests(): void;
+/** Deterministic maintenance barriers/race injection; not a request-path API. */
+export declare function setConversationPersistenceHookForTests(hook?: typeof testHook): void;
+export declare function waitForConversationMaintenanceForTests(cacheDir: string, now?: number): Promise<void>;
+export {};