cursor-opencode-provider 0.4.3 → 0.6.0

package/dist/image-save.js

@@ -0,0 +1,189 @@
+/**
+ * Commit a staged Cursor image to disk, gated by OpenCode's own permission.
+ *
+ * Host-neutral on purpose: `./image-save-tool.ts` performs the `tool()` value
+ * import from `@opencode-ai/plugin`, which the OpenCode 2.0 entrypoint must not
+ * pull in (see the note in `./web-search-tool.ts`). Only that file may import
+ * the plugin package; this module is safe on every graph.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { trace } from "./debug.js";
+import { takePendingCursorImage } from "./image-staging.js";
+/**
+ * Marks a refusal that must reach Cursor as `WriteResult.permission_denied`
+ * rather than a generic error — the variant its own executor returns and its
+ * agent branches on. Both sides of this string are ours, so matching on it is
+ * a contract, not a guess at someone else's message.
+ */
+export const IMAGE_PERMISSION_DENIED_PREFIX = "CursorImagePermissionDenied:";
+/**
+ * Prove the staged target still resolves inside one of the roots it was mapped
+ * into. `remapCursorImageWritePath` already chose the location; this re-checks
+ * it against the *real* paths, because a symlink planted between mapping and
+ * commit could otherwise redirect the write. Mirrors the containment rule the
+ * correlated-edit read applies before answering with complete file content.
+ */
+export function resolveContainedImagePath(target, allowedRoots) {
+    const roots = allowedRoots.filter(Boolean).map((root) => path.resolve(root));
+    if (roots.length === 0)
+        return { error: "no writable root is configured" };
+    const absolute = path.isAbsolute(target) ? path.resolve(target) : path.resolve(roots[0], target);
+    // The file need not exist yet; its closest existing ancestor must still
+    // resolve inside an allowed root.
+    let probe = absolute;
+    let realProbe;
+    while (true) {
+        try {
+            realProbe = fs.realpathSync(probe);
+            break;
+        }
+        catch {
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                break;
+            probe = parent;
+        }
+    }
+    if (realProbe === undefined)
+        return { error: "target path could not be resolved" };
+    const suffix = path.relative(probe, absolute);
+    const realTarget = suffix ? path.join(realProbe, suffix) : realProbe;
+    for (const root of roots) {
+        let realRoot;
+        try {
+            realRoot = fs.realpathSync(root);
+        }
+        catch {
+            realRoot = root;
+        }
+        const relative = path.relative(realRoot, realTarget);
+        if (relative && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+            // Report the root as the caller supplied it (resolved but not realpathed)
+            // so callers can compare it against their own roots — on macOS a temp dir
+            // realpaths from /var to /private/var and would never match otherwise.
+            return { path: realTarget, relative, root };
+        }
+    }
+    return { error: "target path resolves outside the workspace and project folder" };
+}
+/**
+ * Resolve a root the same way the target was resolved. Comparing a realpath
+ * target against a lexical root misreads a symlinked project root (macOS
+ * /var → /private/var, or a worktree reached through a link) as external.
+ */
+function realRoot(root) {
+    const resolved = path.resolve(root);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * Mirror of OpenCode's `containsPath`: a target inside the session directory or
+ * worktree is internal. A worktree of `/` is skipped there because it would
+ * match every absolute path and silently disable the external gate.
+ */
+function isInsideProject(target, worktree, directory) {
+    for (const root of [directory, worktree]) {
+        if (!root || root === "/")
+            continue;
+        const relative = path.relative(realRoot(root), target);
+        if (relative === "")
+            return true;
+        if (relative && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+            return true;
+    }
+    return false;
+}
+/**
+ * Execute the commit. `image_id` is the only input: the path and bytes come
+ * from this process's staging table, so a caller without a real handle — the
+ * model of any provider, replaying a used id, or guessing — writes nothing.
+ */
+export async function executeCursorImageSave(args, ctx) {
+    const imageId = typeof args.image_id === "string" ? args.image_id : "";
+    if (!imageId)
+        return "No image id was provided, so there is nothing to save.";
+    const image = takePendingCursorImage(imageId);
+    if (!image) {
+        // Expired, already committed, or never existed. Identical response for all
+        // three: nothing here should confirm whether an id was ever valid.
+        return "No pending Cursor image matches that id. It may have already been saved or expired.";
+    }
+    const workspace = ctx.worktree || ctx.directory;
+    const contained = resolveContainedImagePath(image.path, [image.projectDir, workspace].filter((root) => !!root));
+    if ("error" in contained) {
+        trace(`image save: refused path=${JSON.stringify(image.path)} reason=${contained.error}`);
+        return `Refusing to save the generated image: ${contained.error}.`;
+    }
+    // Mirror what OpenCode's own `write` tool does, in the same order: an
+    // external-directory gate for targets outside the project, then the `edit`
+    // permission. Cursor writes generated images into the project folder, which
+    // is under the host cache and therefore *outside* the worktree — exactly the
+    // case `assertExternalDirectory` exists for. Asking only for `edit` would
+    // quietly skip a boundary the host enforces for every one of its own writes.
+    const editPattern = path.relative(realRoot(workspace), contained.path);
+    try {
+        if (!isInsideProject(contained.path, workspace, ctx.directory)) {
+            const parentDir = path.dirname(contained.path);
+            const glob = path.join(parentDir, "*").replaceAll("\\", "/");
+            await ctx.ask({
+                permission: "external_directory",
+                patterns: [glob],
+                always: [glob],
+                metadata: { filepath: contained.path, parentDir },
+            });
+        }
+        await ctx.ask({
+            permission: "edit",
+            patterns: [editPattern],
+            always: ["*"],
+            metadata: {
+                filepath: contained.path,
+                mime: image.mime,
+                bytes: image.data.length,
+                source: "cursor-generate-image",
+            },
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        trace(`image save: permission refused path=${JSON.stringify(contained.path)} reason=${reason}`);
+        throw new Error(`${IMAGE_PERMISSION_DENIED_PREFIX} ${reason}`);
+    }
+    // Cursor writes generated images into an `assets/` subdirectory that will not
+    // exist on a first generation, so the parent chain is created here — after
+    // the permission, so a refusal leaves no directories behind.
+    const directory = path.dirname(contained.path);
+    try {
+        fs.mkdirSync(directory, { recursive: true });
+        fs.writeFileSync(contained.path, image.data);
+    }
+    catch (error) {
+        // Most often something already occupies a path component (EEXIST/ENOTDIR).
+        // Say which path is blocked; the raw errno alone tells the model nothing.
+        const reason = error instanceof Error ? error.message : String(error);
+        trace(`image save: write failed path=${JSON.stringify(contained.path)} reason=${reason}`);
+        throw new Error(`Could not save the generated image to ${contained.path}: ${reason}. `
+            + `Check that ${directory} is a writable directory.`);
+    }
+    trace(`image save: wrote path=${JSON.stringify(contained.path)} ` +
+        `bytes=${image.data.length} mime=${image.mime}`);
+    // No `attachments`, deliberately. OpenCode gates media-in-tool-result on an
+    // allowlist of `model.api.npm` values (@ai-sdk/anthropic, @ai-sdk/openai, …)
+    // that no third-party provider can join, so an image attachment is always
+    // "extracted to be sent as a separate user message" (message-v2.ts:299-305).
+    // That trailing user message makes the next turn stop looking like a tool
+    // continuation, so the provider opens a fresh Run and Cursor never receives
+    // the write result it is waiting for — observed live: the Run was superseded
+    // with pending=1 and a full 1.7 MB rebase was paid. Text only keeps the
+    // held-Run contract intact; the file is on disk and Cursor holds the image
+    // server-side already.
+    return {
+        title: editPattern,
+        output: `Saved the generated image to ${contained.path} (${image.data.length} bytes).`,
+    };
+}

package/dist/image-staging.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Staging for images Cursor generated server-side.
+ *
+ * Cursor's GenerateImage runs on its servers and hands the client finished
+ * bytes. OpenCode's `write` tool takes a string and additionally BOM-splits,
+ * diffs, and runs `Format.file()` on what it writes, so image bytes cannot pass
+ * through it — the bytes have to be written by provider code.
+ *
+ * That write still must raise OpenCode's permission, and `ctx.ask` is only
+ * reachable inside a plugin tool's `execute`. So the bytes wait here, keyed by
+ * a single-use id, and the tool that commits them takes only that id: no path
+ * and no content ever crosses the tool boundary. A tool visible in the catalog
+ * therefore cannot be used to write arbitrary bytes anywhere — it can only
+ * commit an image this provider already received, or do nothing.
+ *
+ * Approach adapted from jkalasas/opencode-antigravity-image (MIT), which
+ * established writing image bytes from inside a plugin tool rather than through
+ * the host's text `write`. No code was copied; the permission gate, the
+ * handle-only tool surface, and the containment checks are this provider's.
+ */
+export type PendingCursorImage = {
+    id: string;
+    /** Absolute target, already remapped onto a real location under this host. */
+    path: string;
+    /** Host project folder the target was mapped into; an allowed write root. */
+    projectDir?: string;
+    mime: string;
+    data: Uint8Array;
+    /** OpenCode session that may commit this image. */
+    sessionId?: string;
+    createdAt: number;
+};
+export type StageCursorImageInput = {
+    path: string;
+    projectDir?: string;
+    mime: string;
+    data: Uint8Array;
+    sessionId?: string;
+};
+/** Cursor's own edit ceiling is 50 MB; images are far smaller in practice. */
+export declare const MAX_STAGED_IMAGE_BYTES: number;
+/** A staged image is committed within one tool round-trip or it is stale. */
+export declare const STAGED_IMAGE_TTL_MS: number;
+export declare class StagedImageTooLargeError extends Error {
+    constructor(bytes: number);
+}
+/** Hold generated bytes and return the handle the commit tool will be given. */
+export declare function stageCursorImage(input: StageCursorImageInput, now?: number): string;
+/**
+ * Claim a staged image. Single use: a replayed or guessed id finds nothing, so
+ * the commit tool cannot be driven twice or by a caller that never had a real
+ * handle.
+ */
+export declare function takePendingCursorImage(id: string, now?: number): PendingCursorImage | undefined;
+/** Drop a staged image whose turn ended without committing it. */
+export declare function discardPendingCursorImage(id: string): void;
+/** Test seam. */
+export declare function clearPendingCursorImages(): void;
+export declare function pendingCursorImageCount(): number;

package/dist/image-staging.js

@@ -0,0 +1,91 @@
+/**
+ * Staging for images Cursor generated server-side.
+ *
+ * Cursor's GenerateImage runs on its servers and hands the client finished
+ * bytes. OpenCode's `write` tool takes a string and additionally BOM-splits,
+ * diffs, and runs `Format.file()` on what it writes, so image bytes cannot pass
+ * through it — the bytes have to be written by provider code.
+ *
+ * That write still must raise OpenCode's permission, and `ctx.ask` is only
+ * reachable inside a plugin tool's `execute`. So the bytes wait here, keyed by
+ * a single-use id, and the tool that commits them takes only that id: no path
+ * and no content ever crosses the tool boundary. A tool visible in the catalog
+ * therefore cannot be used to write arbitrary bytes anywhere — it can only
+ * commit an image this provider already received, or do nothing.
+ *
+ * Approach adapted from jkalasas/opencode-antigravity-image (MIT), which
+ * established writing image bytes from inside a plugin tool rather than through
+ * the host's text `write`. No code was copied; the permission gate, the
+ * handle-only tool surface, and the containment checks are this provider's.
+ */
+import { randomUUID } from "node:crypto";
+/** Cursor's own edit ceiling is 50 MB; images are far smaller in practice. */
+export const MAX_STAGED_IMAGE_BYTES = 50 * 1024 * 1024;
+/** A staged image is committed within one tool round-trip or it is stale. */
+export const STAGED_IMAGE_TTL_MS = 10 * 60_000;
+/** Bounds memory if a turn generates several images and none are committed. */
+const MAX_PENDING = 8;
+const pending = new Map();
+export class StagedImageTooLargeError extends Error {
+    constructor(bytes) {
+        super(`Generated image is ${bytes} bytes, above the ${MAX_STAGED_IMAGE_BYTES} byte limit`);
+        this.name = "StagedImageTooLargeError";
+    }
+}
+function prune(now) {
+    for (const [id, image] of pending) {
+        if (now - image.createdAt > STAGED_IMAGE_TTL_MS)
+            pending.delete(id);
+    }
+    // Oldest-first eviction: Map preserves insertion order and ids are only ever
+    // appended, so the first entries are the oldest.
+    while (pending.size >= MAX_PENDING) {
+        const oldest = pending.keys().next().value;
+        if (oldest === undefined)
+            break;
+        pending.delete(oldest);
+    }
+}
+/** Hold generated bytes and return the handle the commit tool will be given. */
+export function stageCursorImage(input, now = Date.now()) {
+    if (input.data.length > MAX_STAGED_IMAGE_BYTES) {
+        throw new StagedImageTooLargeError(input.data.length);
+    }
+    prune(now);
+    const id = `cursor-image-${randomUUID()}`;
+    pending.set(id, {
+        id,
+        path: input.path,
+        projectDir: input.projectDir,
+        mime: input.mime,
+        data: input.data,
+        sessionId: input.sessionId,
+        createdAt: now,
+    });
+    return id;
+}
+/**
+ * Claim a staged image. Single use: a replayed or guessed id finds nothing, so
+ * the commit tool cannot be driven twice or by a caller that never had a real
+ * handle.
+ */
+export function takePendingCursorImage(id, now = Date.now()) {
+    const image = pending.get(id);
+    if (!image)
+        return undefined;
+    pending.delete(id);
+    if (now - image.createdAt > STAGED_IMAGE_TTL_MS)
+        return undefined;
+    return image;
+}
+/** Drop a staged image whose turn ended without committing it. */
+export function discardPendingCursorImage(id) {
+    pending.delete(id);
+}
+/** Test seam. */
+export function clearPendingCursorImages() {
+    pending.clear();
+}
+export function pendingCursorImageCount() {
+    return pending.size;
+}

package/dist/index.d.ts

@@ -26,7 +26,7 @@ export type CreateCursorOptions = {
     /**
      * Host cache root for Cursor project metadata + model/version caches.
      * Prefer the host's Path.cache (Effect v2) when available; otherwise the
-     * provider resolves OpenCode / MiMo / Kilo XDG cache dirs automatically.
+     * provider resolves the native OpenCode cache dir, or an injected host path bridge.
      */
     cacheDir?: string;
     /** Held-stream policy. Defaults: heartbeat 5s, semantic idle 120s, tool inactivity 10m. */

package/dist/language-model.d.ts

@@ -1,10 +1,15 @@
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamPart } from "@ai-sdk/provider";
 import type { CreateCursorOptions, CursorRetryOptions } from "./index.js";
 import { type OpencodeToolDef } from "./protocol/tools.js";
+import { cursorContextUsageMetadata, type CursorContextUsageSource, type CursorConversationTokenDetails } from "./protocol/token-details.js";
+import { type ConversationBlobGraphStats } from "./protocol/blob-store.js";
 import { type CursorSession } from "./session.js";
 import { CursorProviderError } from "./errors.js";
 import type { SeedHistoryMessage } from "./protocol/request.js";
 export declare const MAX_TURN_STATE_SESSIONS = 256;
+/** Cursor's own conversation export path treats state above 100 MiB as large. */
+export declare const MAX_CHECKPOINT_BLOB_GRAPH_BYTES: number;
+export declare function checkpointBlobGraphRequiresRebase(stats: ConversationBlobGraphStats, maxBytes?: number): boolean;
 export type CursorRetryPolicy = {
     maxAttempts: number;
     baseDelayMs: number;
@@ -12,13 +17,14 @@ export type CursorRetryPolicy = {
 };
 export declare function resolveRetryPolicy(options: CursorRetryOptions | undefined): CursorRetryPolicy;
 export declare function connectFrameError(payload: string): CursorProviderError;
+/** Restore the last real catalog solely for lifecycle turns such as compaction. */
+export declare function restoreTurnToolCatalog(sessionKey: string, tools: OpencodeToolDef[]): void;
 type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
 export declare function pumpWithRecovery(input: {
     initialSession: CursorSession;
     controller: ReadableStreamDefaultController<V3Part>;
     abortSignal?: AbortSignal;
-    promptTokens?: number;
     retryPolicy?: CursorRetryPolicy;
     recover: (recovery: CursorRunRecovery) => Promise<CursorSession>;
     onSession?: (session: CursorSession) => void;
@@ -56,10 +62,6 @@ export declare function deliverContinuationResults(session: CursorSession, trail
 export declare function pump(session: CursorSession, controller: ReadableStreamDefaultController<V3Part>, ids: {
     textId: string;
     reasoningId: string;
-    promptTokens?: number;
-    requestUsage?: {
-        outputChars: number;
-    };
 }, abortSignal?: AbortSignal): Promise<void>;
 type ExtractedToolResult = {
     toolCallId: string;
@@ -83,10 +85,8 @@ export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOp
 export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean, workspaceRoot: string): string | undefined;
 /** Rough char→token estimate for mid-turn usage before TurnEnded arrives. */
 export declare function estimateTokens(chars: number): number;
-/** Estimate current-request prompt tokens from the complete serialized V3 prompt. */
-export declare function estimatePromptTokens(prompt: LanguageModelV3CallOptions["prompt"]): number;
-/** Preserve exact Cursor counters as diagnostics when they are cumulative across a multi-step Run. */
-export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>): {
+/** Preserve exact request-local Cursor counters as diagnostics. */
+export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>, tokenDetails?: CursorConversationTokenDetails, contextSource?: CursorContextUsageSource): {
     cursor: {
         usageVersion: number;
         inputTokensRaw: number;
@@ -94,6 +94,7 @@ export declare function cursorTurnEndedProviderMetadata(te: Record<string, unkno
         cacheReadRaw: number;
         cacheWriteRaw: number;
         reasoningTokensRaw: number;
+        context?: ReturnType<typeof cursorContextUsageMetadata>;
     };
 };
 /**
@@ -134,10 +135,11 @@ export declare function resolveTurnToolState(input: {
     incomingTools: OpencodeToolDef[];
     toolChoice?: LanguageModelV3CallOptions["toolChoice"];
     isCompaction: boolean;
-}): {
+    abortSignal?: AbortSignal;
+}): Promise<{
     advertisedTools: OpencodeToolDef[];
     allowTools: boolean;
-};
+}>;
 export declare function resolveTurnConversationReset(input: {
     sessionKey?: string;
     isCompaction: boolean;