cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/image-save.js

@@ -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 = errorMessage(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}`);
     }
@@ -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

@@ -3,7 +3,7 @@ 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. */
+    /** Optional total attempt ceiling (including the initial request), across host retries. */
     maxAttempts?: number;
     /** Initial full-jitter backoff ceiling. Default: 500ms. */
     baseDelayMs?: number;
@@ -42,7 +42,7 @@ export type CreateCursorOptions = {
     cacheDir?: string;
     /** Held-stream policy. Defaults: heartbeat 5s, semantic idle 120s, tool inactivity 10m. */
     continuation?: CursorContinuationOptions;
-    /** Fresh-turn retry policy. Defaults: 3 attempts, 500ms base, 8000ms cap. */
+    /** Run retry policy. Defaults: 10 transport / 3 server retries, 500ms base, 8000ms delay cap. */
     retry?: CursorRetryOptions;
     /** Fallback host dialect when schemas are omitted or ambiguous. Default: OpenCode 1.x. */
     defaultDialect?: HostToolDialect;

package/dist/language-model.d.ts

@@ -1,12 +1,16 @@
+import { type RetryBudget } from "./retry-budget.js";
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamPart } from "@ai-sdk/provider";
 import type { CreateCursorOptions, CursorRetryOptions } from "./index.js";
+import { type ToolRefusal } from "./opencode2/tool-results.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 ModelInfo } from "./models.js";
+import { type ModelInfo, type ModelParameterValue } from "./models.js";
 import type { SeedHistoryMessage } from "./protocol/request.js";
+import { type CursorImageInput } from "./image-input.js";
+import { type HostNoteBatch } from "./protocol/host-notes.js";
 type PromptIdentity = {
     hostAgent?: string;
     systemPromptHash?: string;
@@ -30,13 +34,13 @@ export declare function checkpointBlobGraphConcern(stats: ConversationBlobGraphS
  */
 export declare function isSoleControlFrame(payload: Uint8Array): boolean;
 export type CursorRetryPolicy = {
-    maxAttempts: number;
+    maxAttempts?: number;
     baseDelayMs: number;
     maxDelayMs: number;
 };
 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;
@@ -48,6 +52,11 @@ 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: the release `startSession` performs, then the host-note stores. */
+export declare function releaseHostNoteInjectionsForTests(sessionKey: string): {
+    inFlight: string[][];
+    undelivered: string[];
+};
 type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
 export declare function pumpWithRecovery(input: {
@@ -55,6 +64,9 @@ export declare function pumpWithRecovery(input: {
     controller: ReadableStreamDefaultController<V3Part>;
     abortSignal?: AbortSignal;
     retryPolicy?: CursorRetryPolicy;
+    retryBudget?: RetryBudget;
+    /** Proven completed host results can seed history without replaying their calls. */
+    canRebaseFromHistory?: (session: CursorSession) => boolean;
     recover: (recovery: CursorRunRecovery) => Promise<CursorSession>;
     onSession?: (session: CursorSession) => void;
     maxRecoveries?: number;
@@ -68,7 +80,7 @@ export declare function pumpWithRecovery(input: {
 }): Promise<CursorSession>;
 export type CursorRunRecovery = {
     kind: "rebase";
-    reason?: "checkpoint-unusable";
+    reason?: "checkpoint-unusable" | "unfinished-prior-run" | "completed-tool-results";
 } | {
     kind: "resume";
     conversationId: string;
@@ -76,10 +88,6 @@ export type CursorRunRecovery = {
 };
 /** Start (or replace) the per-session heartbeat. In-flight writes from a prior attach are ignored. */
 export declare function attachSessionHeartbeat(session: CursorSession): void;
-/**
- * OpenCode re-sends the full tool-result history on every continuation. Prefer
- * the newest result that still has a live pending exec on its tagged session.
- */
 export declare function findContinuationSession(toolResults: Array<{
     sessionId: string;
     execId: number;
@@ -96,12 +104,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;
 /**
@@ -112,13 +122,16 @@ export declare const FRESH_TURN_DRAIN_TIMEOUT_MS = 8000;
  */
 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.
+ * Before opening a new user-turn Run, settle the held Run's pending results
+ * and drain its terminal checkpoint. The unseen follow-up to results settled
+ * here can finish through Cursor's cancellation contract; an unacknowledged
+ * turn must rebase.
  */
 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
@@ -126,42 +139,132 @@ export declare function preparePriorSessionForFreshTurn(openCodeSessionId: strin
  *
  * @returns number of pendings successfully cancelled
  */
-export declare function cancelPendingExecsForFreshTurn(session: CursorSession): number;
+export declare function cancelPendingExecsForFreshTurn(session: CursorSession): Promise<number>;
+/**
+ * While the host runs a step's tools nothing pumps the Run, but Cursor keeps
+ * writing: right after a step it sends `tool_requests_listed` or a checkpoint,
+ * then KV blob writes, and it may abort an exec. Cursor CLI's single reader
+ * handles KV and exec control on their own channels at once; an unanswered KV
+ * write left Cursor waiting until the tool finished (seen live). Answer KV,
+ * apply an abort for an exec still waiting on the host, and skip heartbeats;
+ * queue every other frame in `heldFrames`, in arrival order, for the next pump.
+ * An abort whose exec request is still queued stays queued behind it.
+ *
+ * The reader peeks the shared `pendingFrameRead`: a pump that starts meanwhile
+ * awaits the same read, and the reader leaves that frame to it.
+ */
+export declare function readHeldRun(session: CursorSession): void;
+/** How long a Run must wait on host tools before its state is saved for a restart. */
+export declare const HELD_RUN_SAVE_DELAY_MS = 1000;
+/** How long a cancelled Run may take to end by itself before its stream is closed. */
+export declare const HOST_INTERRUPT_GRACE_MS = 3000;
+/**
+ * The host stopped the turn. OpenCode 2 never aborts `doStream` for that, so
+ * the Run would keep generating, and a held one would wait on results that
+ * never come. Cancel it as Cursor CLI's Stop does: forget what the host owed,
+ * send `cancel_action`, give Cursor a moment to end the Run, then close it.
+ * A Run that ends without `turn_ended` is saved with the last checkpoint
+ * Cursor sent, so the next turn resumes it and recognizes the stopped step.
+ */
+export declare function cancelRunForHostInterrupt(session: CursorSession, reason: string, opts?: {
+    graceMs?: number;
+}): Promise<void>;
+/**
+ * Test helper: wait for host-interrupt cancels and in-progress Run saves, which
+ * write after the call that started them returned. Close the Runs first, so a
+ * held Run's save timer finds them closed instead of starting another save.
+ */
+export declare function settleRunSavesForTests(): Promise<void>;
+export declare function cancelIfHostStoppedSince(session: CursorSession): void;
 /**
  * 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.
+ * Used only to settle a Run the host left (a fresh turn, a host interrupt) —
+ * not a general pump substitute. `cancelReason` sends `cancel_action` first;
+ * `cancelled`: the caller already sent it. Either way nothing the Run still
+ * sends (display updates, an exec already in flight) needs the host, and
+ * Cursor's closing frames (the final checkpoint) are worth reading.
  */
 export declare function drainSessionUntilTurnEnded(session: CursorSession, opts?: {
     timeoutMs?: number;
-}): Promise<"turn-ended" | "busy" | "timeout" | "interrupted" | "skipped">;
+    cancelReason?: string;
+    cancelled?: boolean;
+}): Promise<"turn-ended" | "cancelled" | "busy" | "timeout" | "interrupted" | "skipped">;
+export declare function deliverContinuationResults(session: CursorSession, trailingToolResults: ExtractedToolResult[], delivery?: {
+    hostAgent?: string;
+}): Promise<CursorSession | undefined>;
+/** Notes the restart snapshot kept for this session's next user turn. */
+export declare function restorePersistedHostNotes(sessionKey: string, persisted: string | undefined): void;
 /**
- * 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.
+ * Host notes a new Run's user turn carries, as `<system_reminder>` blocks:
+ * notes no earlier Run delivered, then notes OpenCode placed before this user
+ * message (they exist only in host history, which a checkpointed Run does not
+ * resend). Call `sent()` once the Run request is written.
  */
-export declare function deliverContinuationResults(session: CursorSession, trailingToolResults: ExtractedToolResult[]): CursorSession | undefined;
+export declare function prepareUserTurnHostNotes(input: {
+    sessionKey?: string;
+    prompt: LanguageModelV3CallOptions["prompt"];
+    startedWithCheckpoint: boolean;
+    isCompaction: boolean;
+    ephemeralRun: boolean;
+    resuming: boolean;
+    /** The history actually seeded by a Run without a checkpoint. */
+    seedHistory?: readonly SeedHistoryMessage[];
+    /** Messages carried as the live action, rather than replayed in seed history. */
+    liveTurnStart?: number;
+}): {
+    reminders: string[];
+    carriedNotes: HostNoteBatch[];
+    sent: () => void;
+};
 /**
  * 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;
+    refusal?: ToolRefusal;
+    interrupted?: boolean;
+    /** 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[];
+    /** Raw host note bodies that trailed the step (attached after typed result build). */
+    notes?: string[];
+    /** Notices about this result its typed shape cannot carry (hook context on this result). */
+    notices?: string[];
 };
+type ExtractedToolResult = ToolResultContent & {
+    sessionId: string;
+    execId: number;
+};
+/**
+ * Host notes between the previous reply and the closing user message, e.g. an
+ * OpenCode 2 `<system-update>` after MCP servers reconnect. The host's leading
+ * system prompt is never one of them. Empty unless the prompt ends with a
+ * user message that is not itself a note.
+ */
+export declare function hostNotesBeforeUserTurn(prompt: LanguageModelV3CallOptions["prompt"]): string[];
 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[]>;
+/** Debug summary of the last prompt messages: roles, part kinds, short text previews. */
+export declare function describePromptTail(prompt: LanguageModelV3CallOptions["prompt"], count?: number): string;
 /** Detect a host-owned canonical plan review, excluding Cursor exec replies. */
 export declare function hasApprovedUncorrelatedPlanStageResult(prompt: LanguageModelV3CallOptions["prompt"]): boolean;
 /**
@@ -179,6 +282,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;
@@ -194,6 +298,13 @@ export declare function cursorTurnEndedProviderMetadata(te: Record<string, unkno
         context?: ReturnType<typeof cursorContextUsageMetadata>;
     };
 };
+/** Partial assistant output may grow on a host retry; it is not a new user turn. */
+export declare function retryTurnKey(prompt: LanguageModelV3CallOptions["prompt"], withoutLastInterruptionNotice?: boolean): string;
+/** All user messages after the last assistant/tool boundary form one live user turn. */
+export declare function liveUserTurn(prompt: LanguageModelV3CallOptions["prompt"]): {
+    start: number;
+    text: string;
+} | undefined;
 /**
  * Prior prompt turns for a seed ConversationStateStructure. Tool results must
  * never be replayed as assistant-authored prose: that teaches the model to
@@ -205,6 +316,7 @@ export declare function cursorTurnEndedProviderMetadata(te: Record<string, unkno
 export declare function extractPromptHistory(prompt: LanguageModelV3CallOptions["prompt"], options?: {
     preserveTrailingUser?: boolean;
     toolResults?: "omit" | "all" | "trailing";
+    liveTurnStart?: number;
 }): SeedHistoryMessage[];
 /** Share of the target context a foreign-history rebase may fill before compaction. */
 export declare const FOREIGN_HISTORY_REBASE_CONTEXT_SHARE = 0.8;
@@ -217,6 +329,8 @@ export declare function assertForeignHistoryRebaseFits(input: {
     modelInfo: ModelInfo | undefined;
     cursorModelId: string;
     maxMode: boolean;
+    /** Resolved variant tuple; its `context` is the Run's window when present. */
+    parameters?: ModelParameterValue[];
     history: SeedHistoryMessage[];
     systemPrompt: string | undefined;
     userText: string;
@@ -248,8 +362,13 @@ export declare function spanEndParts(opts: {
     type: "text-end" | "reasoning-end";
     id: string;
 }>;
-/** 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[];