cursor-opencode-provider 0.7.2 → 0.7.3

package/dist/context/overlay.js

@@ -0,0 +1,96 @@
+/**
+ * Epoch-hold live RequestContext overlay lists (skills, subagents, plugins).
+ *
+ * Same policy as the tool catalog: first nonempty freeze is UTF-16 by id,
+ * equal ids keep frozen bytes (including content), new ids append at the
+ * tail, shrink keeps the epoch advertisement. Discovery still runs every
+ * Run; this only canonicalizes what is advertised.
+ */
+export const MAX_OVERLAY_HOLDS = 256;
+const byConversationId = new Map();
+function utf16(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function inFixedOrder(items, idOf) {
+    return items
+        .map((item) => ({ ...item }))
+        .sort((left, right) => utf16(idOf(left), idOf(right)));
+}
+function holdList(cached, incoming, idOf) {
+    const orderedIncoming = inFixedOrder(incoming, idOf);
+    if (!cached || cached.length === 0)
+        return orderedIncoming;
+    const cachedIds = new Set(cached.map(idOf));
+    const hasNew = orderedIncoming.some((item) => !cachedIds.has(idOf(item)));
+    if (!hasNew)
+        return cached;
+    const newcomers = inFixedOrder(orderedIncoming.filter((item) => !cachedIds.has(idOf(item))), idOf);
+    return [...cached, ...newcomers];
+}
+function remember(conversationId, hold) {
+    const stored = {
+        skills: structuredClone(hold.skills),
+        subagents: structuredClone(hold.subagents),
+        plugins: structuredClone(hold.plugins),
+    };
+    byConversationId.delete(conversationId);
+    byConversationId.set(conversationId, stored);
+    while (byConversationId.size > MAX_OVERLAY_HOLDS) {
+        const oldest = byConversationId.keys().next().value;
+        if (!oldest)
+            break;
+        byConversationId.delete(oldest);
+    }
+    return stored;
+}
+function skillId(skill) {
+    return skill.id || skill.full_path;
+}
+function toWire(hold) {
+    return {
+        skills: hold.skills.map(({ full_path, content, description }) => ({
+            full_path,
+            content,
+            description,
+        })),
+        subagents: hold.subagents,
+        plugins: hold.plugins,
+    };
+}
+/** Merge live discovery into the conversation overlay epoch. */
+export function holdCapabilityOverlay(conversationId, live) {
+    if (!conversationId) {
+        return toWire({
+            skills: inFixedOrder(live.skills, skillId),
+            subagents: inFixedOrder(live.subagents, (agent) => agent.name),
+            plugins: inFixedOrder(live.plugins, (plugin) => plugin.id),
+        });
+    }
+    const cached = byConversationId.get(conversationId);
+    const next = {
+        skills: holdList(cached?.skills, live.skills, skillId),
+        subagents: holdList(cached?.subagents, live.subagents, (agent) => agent.name),
+        plugins: holdList(cached?.plugins, live.plugins, (plugin) => plugin.id),
+    };
+    if (next.skills.length === 0 && next.subagents.length === 0 && next.plugins.length === 0) {
+        byConversationId.delete(conversationId);
+        return toWire(next);
+    }
+    return toWire(remember(conversationId, next));
+}
+export function clearOverlayHold(conversationId) {
+    byConversationId.delete(conversationId);
+}
+export function transferOverlayHold(previousConversationId, nextConversationId) {
+    if (!previousConversationId || !nextConversationId)
+        return;
+    const hold = byConversationId.get(previousConversationId);
+    byConversationId.delete(previousConversationId);
+    byConversationId.delete(nextConversationId);
+    if (!hold)
+        return;
+    remember(nextConversationId, hold);
+}
+export function resetOverlayHoldsForTests() {
+    byConversationId.clear();
+}

package/dist/debug.d.ts

@@ -1,14 +1,22 @@
+/** Soft cap for the debug log file; exceeded size triggers truncate + new header. */
+export declare const DEBUG_LOG_MAX_BYTES: number;
 /** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
 export declare function isDebugEnabled(): boolean;
 /** Resolve the debug log path (env override or per-uid tmpdir default). */
 export declare function resolveDebugLogPath(): string;
 /**
- * Ensure the log directory is 0o700 and create/truncate the log file as 0o600.
+ * Ensure the log directory is 0o700 and the log file exists as 0o600.
+ * Does **not** truncate an existing file — mid-run re-init must keep prior lines.
  * Exported for tests; callers normally go through `trace`.
  */
 export declare function ensureSecureDebugLog(filePath: string, options?: {
     secureParent?: boolean;
 }): void;
+/**
+ * If `filePath` is at least `maxBytes`, truncate it and write a size-cap header.
+ * Returns true when a truncate happened. Exported for tests.
+ */
+export declare function truncateDebugLogIfOversized(filePath: string, maxBytes?: number): boolean;
 export declare function trace(msg: string): void;
 /**
  * Compact path-advertising summary for RequestContext troubleshooting.

package/dist/debug.js

@@ -4,9 +4,16 @@ import path from "node:path";
 // Wire-level diagnostics. Opt in with CURSOR_PROVIDER_DEBUG=1 (or "true").
 // Default path mirrors Cursor CLI: $TMPDIR/cursor-provider-logs-<uid>/debug-<pid>.log
 // with directory mode 0o700 and file mode 0o600. Override with CURSOR_PROVIDER_DEBUG_FILE.
-// Truncated once per process. Tokens / checksums should be redacted by callers.
+// First init in a fresh file writes a header; later inits (module reload / second
+// isolate sharing CURSOR_PROVIDER_DEBUG_FILE) append another header instead of
+// wiping earlier EMITTED lines. Operators who want a clean run should truncate
+// the override path before starting the host. Independently, when the file reaches
+// DEBUG_LOG_MAX_BYTES it is size-capped (truncated + new header) so self-verify
+// runs cannot grow without bound. Tokens / checksums: redact in callers.
 const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
     process.env.CURSOR_PROVIDER_DEBUG === "true";
+/** Soft cap for the debug log file; exceeded size triggers truncate + new header. */
+export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
 let _traceInitialized = false;
 let _debugFile;
 let _debugFileUsesManagedDirectory = false;
@@ -24,7 +31,8 @@ export function resolveDebugLogPath() {
     return path.join(os.tmpdir(), `cursor-provider-logs-${uid}`, `debug-${process.pid}.log`);
 }
 /**
- * Ensure the log directory is 0o700 and create/truncate the log file as 0o600.
+ * Ensure the log directory is 0o700 and the log file exists as 0o600.
+ * Does **not** truncate an existing file — mid-run re-init must keep prior lines.
  * Exported for tests; callers normally go through `trace`.
  */
 export function ensureSecureDebugLog(filePath, options = {}) {
@@ -43,7 +51,9 @@ export function ensureSecureDebugLog(filePath, options = {}) {
         }
         fs.chmodSync(dir, 0o700);
     }
-    fs.writeFileSync(filePath, "", { mode: 0o600 });
+    if (!fs.existsSync(filePath)) {
+        fs.writeFileSync(filePath, "", { mode: 0o600 });
+    }
     fs.chmodSync(filePath, 0o600);
 }
 function announceLogPath(filePath) {
@@ -58,6 +68,25 @@ function announceLogPath(filePath) {
         /* ignore */
     }
 }
+function debugBannerLine() {
+    return `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`;
+}
+/**
+ * If `filePath` is at least `maxBytes`, truncate it and write a size-cap header.
+ * Returns true when a truncate happened. Exported for tests.
+ */
+export function truncateDebugLogIfOversized(filePath, maxBytes = DEBUG_LOG_MAX_BYTES) {
+    if (!fs.existsSync(filePath))
+        return false;
+    const size = fs.statSync(filePath).size;
+    if (size < maxBytes)
+        return false;
+    fs.writeFileSync(filePath, debugBannerLine() +
+        `[${new Date().toISOString()}] debug: size-cap truncate file=${filePath} ` +
+        `wasBytes=${size} maxBytes=${maxBytes}\n`, { mode: 0o600 });
+    fs.chmodSync(filePath, 0o600);
+    return true;
+}
 export function trace(msg) {
     if (!DEBUG_ENABLED)
         return;
@@ -68,13 +97,25 @@ export function trace(msg) {
         }
         if (!_traceInitialized) {
             ensureSecureDebugLog(_debugFile, { secureParent: _debugFileUsesManagedDirectory });
-            fs.writeFileSync(_debugFile, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`, { mode: 0o600 });
+            // Drop oversized leftovers from a prior run before appending a reinit banner.
+            truncateDebugLogIfOversized(_debugFile);
+            const banner = debugBannerLine();
+            const preexisting = fs.existsSync(_debugFile) && fs.statSync(_debugFile).size > 0;
+            if (preexisting) {
+                fs.appendFileSync(_debugFile, banner);
+            }
+            else {
+                fs.writeFileSync(_debugFile, banner, { mode: 0o600 });
+            }
             _traceInitialized = true;
             announceLogPath(_debugFile);
             fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] debug: enabled file=${_debugFile} ` +
                 `xdg_cache_home=${process.env.XDG_CACHE_HOME ?? "(unset)"} ` +
-                `cwd=${process.cwd()}\n`);
+                `cwd=${process.cwd()}` +
+                (preexisting ? " reinit=append" : "") +
+                `\n`);
         }
+        truncateDebugLogIfOversized(_debugFile);
         fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${msg}\n`);
     }
     catch {

package/dist/host-event-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Optional host-neutral event capability installed by a compatibility layer.
+ *
+ * The provider does not interpret host-specific event payloads here. It only
+ * forwards the canonical OpenCode plugin event and the structural host values
+ * that were supplied to the plugin at load time.
+ */
+export declare const HOST_EVENT_BRIDGE: unique symbol;
+export type HostEventBridge = {
+    handle(input: {
+        event: unknown;
+        client: unknown;
+        directory: string;
+        serverUrl: URL;
+    }): void | Promise<void>;
+};
+export declare function dispatchHostEventBridge(input: {
+    event: unknown;
+    client: unknown;
+    directory: string;
+    serverUrl: URL;
+}): Promise<void>;

package/dist/host-event-bridge.js

@@ -0,0 +1,22 @@
+/**
+ * Optional host-neutral event capability installed by a compatibility layer.
+ *
+ * The provider does not interpret host-specific event payloads here. It only
+ * forwards the canonical OpenCode plugin event and the structural host values
+ * that were supplied to the plugin at load time.
+ */
+export const HOST_EVENT_BRIDGE = Symbol.for("opencode.host.event-bridge");
+export async function dispatchHostEventBridge(input) {
+    const bridge = globalThis[HOST_EVENT_BRIDGE];
+    if (!bridge || typeof bridge !== "object")
+        return;
+    const handle = bridge.handle;
+    if (typeof handle !== "function")
+        return;
+    try {
+        await handle.call(bridge, input);
+    }
+    catch {
+        // An optional compatibility capability must not break the native plugin.
+    }
+}

package/dist/image-input.js

@@ -189,24 +189,44 @@ export async function extractCursorUserImages(lastUser, signal, maxBytes = MAX_C
     }
     return images;
 }
+function pushImageFileParts(parts, content) {
+    for (const part of content) {
+        if (!part || typeof part !== "object")
+            continue;
+        const file = part;
+        if (file.type === "file" &&
+            typeof file.mediaType === "string" &&
+            file.mediaType.startsWith("image/"))
+            parts.push(file);
+    }
+}
 function cursorHistoryImageParts(prompt) {
     const parts = [];
-    for (const message of prompt) {
+    // Last user attachments stay owned by extractCursorUserImages so a prompt that
+    // still carries images on the trailing user message is not double-attached.
+    let lastUserIndex = -1;
+    for (let i = 0; i < prompt.length; i++) {
+        const message = prompt[i];
+        if (!message || typeof message !== "object")
+            continue;
+        if (message.role === "user")
+            lastUserIndex = i;
+    }
+    for (let i = 0; i < prompt.length; i++) {
+        const message = prompt[i];
         if (!message || typeof message !== "object")
             continue;
         const record = message;
         if (!Array.isArray(record.content))
             continue;
+        if (record.role === "user") {
+            if (i === lastUserIndex)
+                continue;
+            pushImageFileParts(parts, record.content);
+            continue;
+        }
         if (record.role === "assistant") {
-            for (const part of record.content) {
-                if (!part || typeof part !== "object")
-                    continue;
-                const file = part;
-                if (file.type === "file" &&
-                    typeof file.mediaType === "string" &&
-                    file.mediaType.startsWith("image/"))
-                    parts.push(file);
-            }
+            pushImageFileParts(parts, record.content);
             continue;
         }
         if (record.role !== "tool")
@@ -266,9 +286,14 @@ export async function extractCursorPromptImages(prompt, lastUser, options) {
     const maxBytes = cursorImageBudget(options.maxBytes ?? MAX_CURSOR_IMAGE_INPUT_BYTES);
     const userImages = await extractCursorUserImages(lastUser, options.signal, maxBytes);
     const userBytes = userImages.reduce((total, image) => total + image.data.length, 0);
+    // Seed history dedupe with this-turn last-user hashes so the same bytes on an
+    // earlier user/assistant/tool message are not attached twice in one Run.
+    const seenHashes = new Set(options.seenHistoryHashes);
+    for (const image of userImages)
+        seenHashes.add(imageContentHash(image.data));
     const history = await extractCursorHistoryImages(prompt, {
         supportsImages: options.supportsImages,
-        seenHashes: options.seenHistoryHashes,
+        seenHashes,
         signal: options.signal,
         maxBytes: maxBytes - userBytes,
         filenameOffset: userImages.length,

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { CursorPlugin } from "./plugin.js";
 import type { CursorContinuationOptions } from "./session.js";
+import type { HostToolDialect } from "./protocol/tools.js";
 export type CursorRetryOptions = {
     /** Total attempts including the initial request. Default: 3. */
     maxAttempts?: number;
@@ -33,6 +34,8 @@ export type CreateCursorOptions = {
     continuation?: CursorContinuationOptions;
     /** Fresh-turn retry policy. Defaults: 3 attempts, 500ms base, 8000ms cap. */
     retry?: CursorRetryOptions;
+    /** Fallback host dialect when schemas are omitted or ambiguous. Default: OpenCode 1.x. */
+    defaultDialect?: HostToolDialect;
 };
 export declare function createCursor(options: CreateCursorOptions): import("./plugin-core.js").CursorSdk;
 export { CursorPlugin };

package/dist/language-model.d.ts

@@ -11,9 +11,16 @@ type PromptIdentity = {
     systemPromptHash?: string;
 };
 export declare const MAX_TURN_STATE_SESSIONS = 256;
-/** Cursor's own conversation export path treats state above 100 MiB as large. */
+/**
+ * Cursor CLI's conversation **export / transfer-to-cloud** path treats state
+ * above 100 MiB as large (`conversation-export.ts` default `104857600`). That
+ * budget must not remint a sticky conversation on resume — CLI soft-reuses.
+ */
 export declare const MAX_CHECKPOINT_BLOB_GRAPH_BYTES: number;
-export declare function checkpointBlobGraphRequiresRebase(stats: ConversationBlobGraphStats, maxBytes?: number): boolean;
+/** @deprecated Never remints; kept for call-site/tests. Always false. */
+export declare function checkpointBlobGraphRequiresRebase(_stats: ConversationBlobGraphStats, _maxBytes?: number): boolean;
+/** Warn-only concern for incomplete / oversized checkpoint graphs (no remint). */
+export declare function checkpointBlobGraphConcern(stats: ConversationBlobGraphStats, maxBytes?: number): "incomplete-checkpoint-graph" | "oversized-checkpoint-graph" | undefined;
 export type CursorRetryPolicy = {
     maxAttempts: number;
     baseDelayMs: number;
@@ -27,6 +34,12 @@ export declare function restoreTurnToolCatalog(sessionKey: string, tools: Openco
 export declare function rememberMirroredTodos(sessionKey: string | undefined, todos: ReadonlyArray<Record<string, unknown>>): void;
 /** Copy of the last known host todo list for an OpenCode session, if any. */
 export declare function snapshotMirroredTodosBySession(sessionKey: string | undefined): Array<Record<string, unknown>> | undefined;
+/**
+ * Prompt identity is diagnostics / persistence only and never drives remint.
+ * Kept as a named helper so call sites / tests that still mention identity
+ * churn have a single no-op definition.
+ */
+export declare function promptIdentityWouldRemint(_previous: PromptIdentity, _current: PromptIdentity): boolean;
 type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
 export declare function pumpWithRecovery(input: {
@@ -55,6 +68,39 @@ export declare function findContinuationSession(toolResults: Array<{
     sessionId: string;
     execId: number;
 }>): CursorSession | undefined;
+/** How long a fresh-turn drain may wait for Cursor `turn_ended` after bridged settle. */
+export declare const FRESH_TURN_DRAIN_TIMEOUT_MS = 8000;
+/**
+ * Error text written onto Cursor execs that the host abandoned by starting a
+ * new user turn before returning the tool result. Completing the held Run with
+ * this cancel (then draining to `turn_ended`) keeps the same conversation
+ * prefix instead of `superseded-by-new-run` mid-exec.
+ */
+export declare const FRESH_TURN_PENDING_CANCEL_REASON = "Host started a new user turn before this tool result was delivered";
+/**
+ * Before opening a new user-turn Run, finish the prior held-open Run cleanly:
+ * settle display-only bridged pendings, cancel any real execs still waiting on
+ * the host, then drain for `turn_ended`. That preserves the same
+ * conversation_id / checkpoint prefix instead of aborting mid-tool.
+ */
+export declare function preparePriorSessionForFreshTurn(openCodeSessionId: string | undefined, opts?: {
+    timeoutMs?: number;
+}): Promise<"drained" | "settled-only" | "busy" | "none">;
+/**
+ * Write error/reject results for every still-open non-bridged pending on the
+ * held Run so Cursor can finish the agent turn instead of being superseded.
+ *
+ * @returns number of pendings successfully cancelled
+ */
+export declare function cancelPendingExecsForFreshTurn(session: CursorSession): number;
+/**
+ * Read remaining frames on an idle held-open Run until `turn_ended`, a
+ * response-requiring request we cannot answer without the host, or timeout.
+ * Used only on the fresh-turn settle path — not a general pump substitute.
+ */
+export declare function drainSessionUntilTurnEnded(session: CursorSession, opts?: {
+    timeoutMs?: number;
+}): Promise<"turn-ended" | "busy" | "timeout" | "interrupted" | "skipped">;
 /**
  * Deliver trailing tool results onto a live continuation session.
  * Returns the same session when writes succeed (or only bridged results were
@@ -162,9 +208,11 @@ export declare function resolveTurnToolState(input: {
 export declare function resolveTurnConversationReset(input: {
     sessionKey?: string;
     isCompaction: boolean;
+    historyRewrite?: boolean;
+    /** @deprecated Ignored — prompt identity never remints. Kept for call-site compat. */
     promptIdentity?: PromptIdentity;
 }): {
     reset: boolean;
-    reason?: "compaction" | "post-compaction-rebase" | "agent-change" | "system-prompt-change";
+    reason?: "compaction" | "post-compaction-rebase" | "history-rewrite";
 };
 export declare function resetTurnStateForTests(): void;