cursor-opencode-provider 0.7.6 → 0.8.1

package/dist/image-save.js

@@ -8,7 +8,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { trace } from "./debug.js";
+import { errorMessage, trace } from "./debug.js";
 import { takePendingCursorImage } from "./image-staging.js";
 /**
  * Marks a refusal that must reach Cursor as `WriteResult.permission_denied`
@@ -126,31 +126,42 @@ export async function executeCursorImageSave(args, ctx) {
     // 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("\\", "/");
+    if (typeof ctx.ask === "function") {
+        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: "external_directory",
-                patterns: [glob],
-                always: [glob],
-                metadata: { filepath: contained.path, parentDir },
+                permission: "edit",
+                patterns: [editPattern],
+                always: ["*"],
+                metadata: {
+                    filepath: contained.path,
+                    mime: image.mime,
+                    bytes: image.data.length,
+                    source: "cursor-generate-image",
+                },
             });
         }
-        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 = errorMessage(error);
+            trace(`image save: permission refused path=${JSON.stringify(contained.path)} reason=${reason}`);
+            throw new Error(`${IMAGE_PERMISSION_DENIED_PREFIX} ${reason}`);
+        }
     }
-    catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
+    else if (ctx.ask === null) {
+        trace(`image save: host cannot prompt; writing after containment ` +
+            `path=${JSON.stringify(contained.path)}`);
+    }
+    else {
+        const reason = "this host did not provide a permission prompt for the write";
         trace(`image save: permission refused path=${JSON.stringify(contained.path)} reason=${reason}`);
         throw new Error(`${IMAGE_PERMISSION_DENIED_PREFIX} ${reason}`);
     }
@@ -165,7 +176,7 @@ export async function executeCursorImageSave(args, ctx) {
     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);
+        const reason = errorMessage(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.`);
@@ -185,5 +196,6 @@ export async function executeCursorImageSave(args, ctx) {
     return {
         title: editPattern,
         output: `Saved the generated image to ${contained.path} (${image.data.length} bytes).`,
+        bytes: image.data.length,
     };
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { CursorPlugin } from "./plugin.js";
 import type { CursorContinuationOptions } from "./session.js";
 import type { HostToolDialect } from "./protocol/tools.js";
+import type { AccessTokenProvider } from "./auth-renewal.js";
 export type CursorRetryOptions = {
     /** Total attempts including the initial request. Default: 3. */
     maxAttempts?: number;
@@ -11,7 +12,16 @@ export type CursorRetryOptions = {
 };
 export type CreateCursorOptions = {
     name: string;
+    /**
+     * Current Cursor access token, asked for every time a Run opens. Takes
+     * precedence over `accessToken` and `apiKey`; hosts use it to renew the
+     * login without exposing a secret in serializable options. `forceRefresh`
+     * is set once after Cursor rejected the previous token.
+     */
+    getAccessToken?: AccessTokenProvider;
+    /** Access token sent as-is (no renewal). Used when `getAccessToken` is absent. */
     accessToken?: string;
+    /** Raw `crsr_` API key, exchanged and renewed. Used only when neither of the above is given. */
     apiKey?: string;
     /** API base for auth, model discovery, and GetServerConfig. */
     apiBaseURL?: string;

package/dist/language-model.d.ts

@@ -5,7 +5,9 @@ import { cursorContextUsageMetadata, type CursorContextUsageSource, type CursorC
 import { type ConversationBlobGraphStats } from "./protocol/blob-store.js";
 import { type CursorSession } from "./session.js";
 import { CursorProviderError } from "./errors.js";
+import { type ModelInfo } from "./models.js";
 import type { SeedHistoryMessage } from "./protocol/request.js";
+import { type CursorImageInput } from "./image-input.js";
 type PromptIdentity = {
     hostAgent?: string;
     systemPromptHash?: string;
@@ -21,6 +23,13 @@ export declare const MAX_CHECKPOINT_BLOB_GRAPH_BYTES: number;
 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;
+/**
+ * True when the raw frame holds exactly one control message: a KV request, a
+ * checkpoint update, or an interaction update that is only a heartbeat. Extra
+ * fields inside a KV request are tolerated (Cursor has sent them live); extra
+ * top-level fields are not.
+ */
+export declare function isSoleControlFrame(payload: Uint8Array): boolean;
 export type CursorRetryPolicy = {
     maxAttempts: number;
     baseDelayMs: number;
@@ -28,7 +37,7 @@ 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. */
+/** Restore the epoch catalog for the next nonempty host turn. */
 export declare function restoreTurnToolCatalog(sessionKey: string, tools: OpencodeToolDef[]): void;
 /** Record the authoritative host todo list for an OpenCode session. */
 export declare function rememberMirroredTodos(sessionKey: string | undefined, todos: ReadonlyArray<Record<string, unknown>>): void;
@@ -40,6 +49,8 @@ export declare function snapshotMirroredTodosBySession(sessionKey: string | unde
  * churn have a single no-op definition.
  */
 export declare function promptIdentityWouldRemint(_previous: PromptIdentity, _current: PromptIdentity): boolean;
+/** Test helper: content hashes recorded after a successful held-Run image write. */
+export declare function snapshotSentHistoryImageHashesForTests(sessionKey: string): string[];
 type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
 export declare function pumpWithRecovery(input: {
@@ -50,9 +61,17 @@ export declare function pumpWithRecovery(input: {
     recover: (recovery: CursorRunRecovery) => Promise<CursorSession>;
     onSession?: (session: CursorSession) => void;
     maxRecoveries?: number;
+    /**
+     * Set when the credential source can renew: called once per turn after
+     * Cursor rejects the token (401 / unauthenticated) before the attempt did
+     * anything, so the reopened Run uses a force-renewed token. This retry does
+     * not count against the transient-failure budget.
+     */
+    renewRejectedCredential?: () => void;
 }): Promise<CursorSession>;
 export type CursorRunRecovery = {
     kind: "rebase";
+    reason?: "checkpoint-unusable";
 } | {
     kind: "resume";
     conversationId: string;
@@ -80,12 +99,14 @@ export declare function isProperCatalogSubset(incoming: ReadonlyArray<{
 }>): boolean;
 /**
  * An open parent Run for this OpenCode session whose catalog strictly contains
- * the incoming tools is treated as an in-session helper. Those calls must not
- * cancel/supersede the parent (that remints on the trailing tool result).
+ * the incoming tools is treated as an in-session helper unless the request
+ * carries a result for that parent's pending call. A result can precede a new
+ * user message or agent-change reminder and still needs to reach the parent.
+ * Helper calls must not cancel/supersede the parent.
  */
 export declare function shouldIsolateInSessionHelper(openCodeSessionId: string | undefined, incomingTools: ReadonlyArray<{
     name?: string;
-}>): boolean;
+}>, historicalResults?: ExtractedToolResult[]): boolean;
 /** How long a fresh-turn drain may wait for Cursor `turn_ended` after bridged settle. */
 export declare const FRESH_TURN_DRAIN_TIMEOUT_MS = 8000;
 /**
@@ -103,6 +124,9 @@ export declare const FRESH_TURN_PENDING_CANCEL_REASON = "Host started a new user
  */
 export declare function preparePriorSessionForFreshTurn(openCodeSessionId: string | undefined, opts?: {
     timeoutMs?: number;
+    /** Tool results already in this prompt; deliver any that match held pendings before cancel. */
+    toolResults?: ExtractedToolResult[];
+    hostAgent?: string;
 }): Promise<"drained" | "settled-only" | "busy" | "none">;
 /**
  * Write error/reject results for every still-open non-bridged pending on the
@@ -119,44 +143,51 @@ export declare function cancelPendingExecsForFreshTurn(session: CursorSession):
 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
- * cleared). Returns undefined after closing the session when a write fails, so
- * the caller can rebase onto a fresh Run instead of pumping a dead stream.
- */
-export declare function deliverContinuationResults(session: CursorSession, trailingToolResults: ExtractedToolResult[]): CursorSession | undefined;
+export declare function deliverContinuationResults(session: CursorSession, trailingToolResults: ExtractedToolResult[], 
+/** Host primary agent of the request that carries these results. */
+delivery?: {
+    hostAgent?: string;
+}): CursorSession | undefined;
 /**
  * Read the held-open stream, emitting stream parts, until the turn boundary:
- *  - a tool call (exec_server_message) → emit tool-call, finish "tool-calls",
- *    and KEEP the session open for the result on the next doStream call;
+ *  - tool call(s) for one Cursor generation → emit each tool-call as it
+ *    arrives; finish "tool-calls" once Cursor's listed count (field 27) is
+ *    met (or immediately when the process has never seen field 27); KEEP the
+ *    session open for results on the next doStream call;
  *  - turn_ended → finish "stop" and close the session;
- *  - transport EOF before turn_ended → throw for one fresh-Run recovery.
+ *  - transport EOF before turn_ended → throw for one fresh-Run recovery
+ *    (after host tools were already emitted, finish "tool-calls" instead and
+ *    let the continuation rebase).
  */
 export declare function pump(session: CursorSession, controller: ReadableStreamDefaultController<V3Part>, ids: {
     textId: string;
     reasoningId: string;
 }, abortSignal?: AbortSignal): Promise<void>;
-type ExtractedToolResult = {
+type ToolResultContent = {
     toolCallId: string;
-    sessionId: string;
-    execId: number;
     toolName: string;
     output: string;
     error?: string;
+    /** Host media parts of this result (own content, or the trailing media message). */
+    media?: unknown[];
+    /** `media` decoded for the exec result, with content hashes in the same order. */
+    images?: CursorImageInput[];
+    imageHashes?: string[];
+    /** Host updates that a binary read cannot carry in its output oneof. */
+    notes?: string;
+};
+type ExtractedToolResult = ToolResultContent & {
+    sessionId: string;
+    execId: number;
 };
-/**
- * Tool results that form a live continuation: only the trailing run of `tool`
- * messages after the last non-tool message. Mid-prompt historical tool results
- * are ignored — they are conversation history, not replies for a held-open Run.
- */
 export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOptions["prompt"]): ExtractedToolResult[];
+/** Decode only image-bearing pending execs, under one continuation-wide budget. */
+export declare function decodeTrailingToolImages(session: CursorSession, results: ExtractedToolResult[], signal?: AbortSignal, maxBytes?: number): Promise<ExtractedToolResult[]>;
 /** Detect a host-owned canonical plan review, excluding Cursor exec replies. */
 export declare function hasApprovedUncorrelatedPlanStageResult(prompt: LanguageModelV3CallOptions["prompt"]): boolean;
 /**
- * Checkpointed Runs do not resend the system prompt. Keep the workspace root
- * on the live user message, and require absolute `path` arguments when that is
- * the host's file-tool dialect.
+ * Keep the workspace root on a checkpointed turn's live user message too, and
+ * require absolute `path` arguments when that is the host's file-tool dialect.
  */
 export declare function groundCheckpointTurnText(userText: string, checkpoint: boolean, workspaceRoot: string, tools: readonly {
     name?: string;
@@ -169,6 +200,7 @@ export declare function groundCheckpointTurnText(userText: string, checkpoint: b
  */
 export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean, workspaceRoot: string, options?: {
     knownMcpServers?: Iterable<string>;
+    allowTools?: boolean;
 }): string | undefined;
 /** Rough char→token estimate for mid-turn usage before TurnEnded arrives. */
 export declare function estimateTokens(chars: number): number;
@@ -196,6 +228,21 @@ export declare function extractPromptHistory(prompt: LanguageModelV3CallOptions[
     preserveTrailingUser?: boolean;
     toolResults?: "omit" | "all" | "trailing";
 }): SeedHistoryMessage[];
+/** Share of the target context a foreign-history rebase may fill before compaction. */
+export declare const FOREIGN_HISTORY_REBASE_CONTEXT_SHARE = 0.8;
+/**
+ * A foreign-history rebase replays the full host history. When that cannot fit,
+ * fail before opening a Run with an error hosts classify as context overflow
+ * (HTTP 413 + "prompt is too long"), so the host compacts and retries.
+ */
+export declare function assertForeignHistoryRebaseFits(input: {
+    modelInfo: ModelInfo | undefined;
+    cursorModelId: string;
+    maxMode: boolean;
+    history: SeedHistoryMessage[];
+    systemPrompt: string | undefined;
+    userText: string;
+}): void;
 /** OpenCode session id header, if present. */
 export declare function opencodeSessionKey(callOptions: LanguageModelV3CallOptions): string | undefined;
 /**
@@ -205,6 +252,14 @@ export declare function opencodeSessionKey(callOptions: LanguageModelV3CallOptio
  */
 export declare function resolveConversationId(callOptions: LanguageModelV3CallOptions): string;
 export { sessionIdToUuid } from "./protocol/conversation-bind.js";
+/**
+ * Grow the held Run's advertised + permitted catalog from this `doStream`
+ * call. Continuation skips `startSession`, so without this, exec #36 and
+ * permission keep the freeze from Run open. MCP server ids stay those of the
+ * Run's one merged-config load (`startSession`); a tool that connects later
+ * still gets its identity from that set.
+ */
+export declare function refreshHeldSessionToolCatalog(session: CursorSession, callOptions: LanguageModelV3CallOptions): Promise<void>;
 /** Exported for tests — AI SDK V3 span ends that must precede finish / tool-call. */
 export declare function spanEndParts(opts: {
     textStarted: boolean;
@@ -217,6 +272,12 @@ export declare function spanEndParts(opts: {
 }>;
 /** Exported for tests — false for compaction/summary (no tools) and toolChoice none. */
 export declare function computeAllowTools(toolCount: number, toolChoice: LanguageModelV3CallOptions["toolChoice"] | undefined): boolean;
+/**
+ * OpenCode title/summary take the first non-empty line of the answer. After a
+ * lifecycle refuse, Cursor often narrates that tools are unavailable — drop
+ * that so it does not become the session title.
+ */
+export declare function shouldDropLifecycleToollessText(text: string, refusedExec: boolean): boolean;
 export declare function resolveTurnToolState(input: {
     sessionKey?: string;
     incomingTools: OpencodeToolDef[];