cursor-opencode-provider 0.2.3 → 0.2.5

package/dist/errors.js

@@ -0,0 +1,199 @@
+/** Structured provider failure with retry and transport diagnostics. */
+export class CursorProviderError extends Error {
+    origin;
+    transient;
+    replaySafe;
+    statusCode;
+    grpcStatus;
+    rstCode;
+    code;
+    retryAfterMs;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "CursorProviderError";
+        this.origin = options.origin;
+        this.transient = options.transient;
+        this.replaySafe = options.replaySafe;
+        this.statusCode = options.statusCode;
+        this.grpcStatus = options.grpcStatus;
+        this.rstCode = options.rstCode;
+        this.code = options.code;
+        this.retryAfterMs = options.retryAfterMs;
+    }
+}
+export class CursorLocalCancellationError extends CursorProviderError {
+    constructor(message = "Cursor request cancelled locally", cause) {
+        super(message, {
+            origin: "local-cancel",
+            transient: false,
+            replaySafe: false,
+            cause,
+        });
+        this.name = "CursorLocalCancellationError";
+    }
+}
+export class CursorTransportError extends CursorProviderError {
+    constructor(message, options = {
+        transient: true,
+        replaySafe: true,
+    }) {
+        super(message, { ...options, origin: "transport" });
+        this.name = "CursorTransportError";
+    }
+}
+export class CursorServerError extends CursorProviderError {
+    constructor(message, options) {
+        super(message, { ...options, origin: "server" });
+        this.name = "CursorServerError";
+    }
+}
+export class CursorProtocolError extends CursorProviderError {
+    constructor(message, options = {}) {
+        super(message, {
+            ...options,
+            origin: "protocol",
+            transient: false,
+            replaySafe: false,
+        });
+        this.name = "CursorProtocolError";
+    }
+}
+export class CursorAuthError extends CursorProviderError {
+    constructor(message = "Cursor authentication failed; reauthenticate with Cursor", options = {}) {
+        super(message, {
+            ...options,
+            origin: "auth",
+            transient: false,
+            replaySafe: false,
+        });
+        this.name = "CursorAuthError";
+    }
+}
+export class CursorRetryExhaustedError extends CursorProviderError {
+    attempts;
+    constructor(attempts, last) {
+        super(`Cursor retry exhausted after ${attempts} attempts: ${last.message}`, {
+            origin: last.origin,
+            transient: false,
+            replaySafe: false,
+            statusCode: last.statusCode,
+            grpcStatus: last.grpcStatus,
+            rstCode: last.rstCode,
+            code: last.code,
+            retryAfterMs: last.retryAfterMs,
+            cause: last,
+        });
+        this.name = "CursorRetryExhaustedError";
+        this.attempts = attempts;
+    }
+}
+const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNABORTED",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETDOWN",
+    "ENETRESET",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EPIPE",
+    "ERR_HTTP2_GOAWAY_SESSION",
+    "ERR_HTTP2_SESSION_ERROR",
+    "ERR_HTTP2_STREAM_CANCEL",
+    "ERR_HTTP2_STREAM_ERROR",
+    "ETIMEDOUT",
+]);
+export function isTransientGrpcStatus(status) {
+    const normalized = String(status).toLowerCase().replaceAll("-", "_");
+    return (normalized === "8" ||
+        normalized === "13" ||
+        normalized === "14" ||
+        normalized === "internal" ||
+        normalized === "resource_exhausted" ||
+        normalized === "unavailable");
+}
+export function isAuthGrpcStatus(status) {
+    const normalized = String(status).toLowerCase().replaceAll("-", "_");
+    return (normalized === "7" ||
+        normalized === "16" ||
+        normalized === "permission_denied" ||
+        normalized === "unauthenticated");
+}
+export function cursorHttpError(operation, statusCode, diagnostics = {}) {
+    if (statusCode === 401 || statusCode === 403) {
+        return new CursorAuthError(`Cursor authentication failed (HTTP ${statusCode}); reauthenticate with Cursor`, { ...diagnostics, statusCode });
+    }
+    return new CursorServerError(`${operation} HTTP ${statusCode}`, {
+        ...diagnostics,
+        statusCode,
+        transient: statusCode === 429 || statusCode >= 500,
+        replaySafe: true,
+    });
+}
+export function cursorGrpcError(operation, grpcStatus, diagnostics = {}) {
+    if (isAuthGrpcStatus(grpcStatus)) {
+        return new CursorAuthError(`Cursor authentication failed (gRPC ${grpcStatus}); reauthenticate with Cursor`, { ...diagnostics, grpcStatus });
+    }
+    return new CursorServerError(`${operation} gRPC status ${grpcStatus}`, {
+        ...diagnostics,
+        grpcStatus,
+        transient: isTransientGrpcStatus(grpcStatus),
+        replaySafe: true,
+    });
+}
+export function errorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+export function toCursorProviderError(error, options = { replaySafe: false }) {
+    if (error instanceof CursorProviderError) {
+        error.replaySafe = options.replaySafe && error.replaySafe;
+        return error;
+    }
+    const code = errorCode(error);
+    const name = error instanceof Error ? error.name : "Error";
+    const message = error instanceof Error ? error.message : "";
+    if (name.startsWith("Auth") || /access token|api key|authentication/i.test(message)) {
+        return new CursorAuthError(undefined, { code, cause: error });
+    }
+    const httpStatus = /\bHTTP\s+(\d{3})\b/i.exec(message)?.[1];
+    if (httpStatus) {
+        const failure = cursorHttpError("Cursor request failed with", Number(httpStatus), { code });
+        failure.replaySafe = options.replaySafe && failure.replaySafe;
+        return failure;
+    }
+    if (code && TRANSIENT_NETWORK_CODES.has(code)) {
+        return new CursorTransportError(`Cursor transport failure (${code})`, {
+            transient: true,
+            replaySafe: options.replaySafe,
+            code,
+            cause: error,
+        });
+    }
+    if (error instanceof TypeError) {
+        return new CursorProtocolError(options.fallback ?? "Invalid Cursor provider configuration", {
+            code,
+            cause: error,
+        });
+    }
+    return new CursorProtocolError(options.fallback ?? `Cursor provider failure (${name})`, {
+        code,
+        cause: error,
+    });
+}
+export function retrySuppressedError(cause, reason, attempt, maxAttempts) {
+    const subject = cause.message.replace(/^Cursor Run stream /, "Cursor stream ");
+    return new CursorProviderError(`${subject} ${reason}; automatic retry unsafe (attempt ${attempt}/${maxAttempts})`, {
+        origin: cause.origin,
+        transient: false,
+        replaySafe: false,
+        statusCode: cause.statusCode,
+        grpcStatus: cause.grpcStatus,
+        rstCode: cause.rstCode,
+        code: cause.code,
+        retryAfterMs: cause.retryAfterMs,
+        cause,
+    });
+}

package/dist/index.d.ts

@@ -1,4 +1,13 @@
 import { CursorPlugin } from "./plugin.js";
+import type { CursorContinuationOptions } from "./session.js";
+export type CursorRetryOptions = {
+    /** Total attempts including the initial request. Default: 3. */
+    maxAttempts?: number;
+    /** Initial full-jitter backoff ceiling. Default: 500ms. */
+    baseDelayMs?: number;
+    /** Exponential backoff ceiling. Default: 8000ms. */
+    maxDelayMs?: number;
+};
 export type CreateCursorOptions = {
     name: string;
     accessToken?: string;
@@ -14,9 +23,14 @@ export type CreateCursorOptions = {
     telemetryEnabled?: boolean;
     /** OpenCode project / worktree directory for request_context collectors. */
     workspaceRoot?: 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. */
+    retry?: CursorRetryOptions;
 };
 export declare function createCursor(options: CreateCursorOptions): {
     languageModel(modelId: string): import("@ai-sdk/provider").LanguageModelV3;
 };
 export { CursorPlugin };
+export type { CursorContinuationOptions, CursorContinuationPolicy } from "./session.js";
 export default CursorPlugin;

package/dist/index.js

@@ -11,6 +11,10 @@ export function createCursor(options) {
 }
 export { CursorPlugin };
 export default CursorPlugin;
+// Keep root runtime exports plugin-safe. OpenCode's legacy plugin loader
+// treats package-root exports as potential plugins, so extra public runtime
+// APIs belong on subpaths such as "cursor-opencode-provider/errors".
+//
 // CursorPluginV2 is NOT re-exported here — see plugin-v2.ts.
 // OpenCode's legacy plugin loader (getLegacyPlugins) iterates all exports
 // and calls getServerPlugin on each; the v2 define() return is not a

package/dist/language-model.d.ts

@@ -1,11 +1,29 @@
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamPart } from "@ai-sdk/provider";
-import type { CreateCursorOptions } from "./index.js";
+import type { CreateCursorOptions, CursorRetryOptions } from "./index.js";
 import { type OpencodeToolDef } from "./protocol/tools.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;
+export type CursorRetryPolicy = {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+};
+export declare function resolveRetryPolicy(options: CursorRetryOptions | undefined): CursorRetryPolicy;
+export declare function connectFrameError(payload: string): CursorProviderError;
 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: () => Promise<CursorSession>;
+    onSession?: (session: CursorSession) => void;
+    maxRecoveries?: number;
+}): Promise<CursorSession>;
 /**
  * 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.
@@ -14,17 +32,27 @@ export declare function findContinuationSession(toolResults: Array<{
     sessionId: string;
     execId: number;
 }>): CursorSession | undefined;
+/**
+ * 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;
 /**
  * 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;
- *  - turn_ended / stream end → finish "stop" and close the session.
+ *  - turn_ended → finish "stop" and close the session;
+ *  - transport EOF before turn_ended → throw for one fresh-Run recovery.
  */
 export declare function pump(session: CursorSession, controller: ReadableStreamDefaultController<V3Part>, ids: {
     textId: string;
     reasoningId: string;
+    promptTokens?: number;
 }, abortSignal?: AbortSignal): Promise<void>;
 type ExtractedToolResult = {
+    toolCallId: string;
     sessionId: string;
     execId: number;
     toolName: string;
@@ -42,15 +70,34 @@ export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOp
  * Redirect only to OpenCode tools that are genuinely advertised this turn;
  * compaction keeps its dedicated summary prompt unchanged.
  */
-export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean): string | undefined;
+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 cumulative Cursor counters as diagnostics, never as AI SDK request usage. */
+export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>): {
+    cursor: {
+        usageVersion: number;
+        inputTokensRaw: number;
+        outputTokensRaw: number;
+        cacheReadRaw: number;
+        cacheWriteRaw: number;
+        reasoningTokensRaw: number;
+    };
+};
 /**
- * Prior prompt turns for a seed ConversationStateStructure after compaction
- * reset. Drops the trailing user message (live action), but preserves tool
- * result payloads as labeled assistant observations for Cursor's text history.
+ * Prior prompt turns for a seed ConversationStateStructure. Tool results must
+ * never be replayed as assistant-authored prose: that teaches the model to
+ * counterfeit `Tool result (...)` text instead of emitting a real tool call.
+ * Normal rebases omit old results; compaction can retain all results and
+ * interrupted continuations retain only the trailing live result suffix as
+ * explicit OpenCode-host observations.
  */
-export declare function extractPromptHistory(prompt: LanguageModelV3CallOptions["prompt"]): SeedHistoryMessage[];
+export declare function extractPromptHistory(prompt: LanguageModelV3CallOptions["prompt"], options?: {
+    preserveTrailingUser?: boolean;
+    toolResults?: "omit" | "all" | "trailing";
+}): SeedHistoryMessage[];
 /** OpenCode session id header, if present. */
 export declare function opencodeSessionKey(callOptions: LanguageModelV3CallOptions): string | undefined;
 /**