cursor-opencode-provider 0.8.1 → 0.8.3

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { APICallError } from "@ai-sdk/provider";
 /** Structured provider failure with retry and transport diagnostics. */
 export class CursorProviderError extends Error {
     origin;
@@ -14,6 +15,16 @@ export class CursorProviderError extends Error {
     rstCode;
     code;
     retryAfterMs;
+    /** Cursor's classified verdict, or false once provider retries must stop. */
+    retryable;
+    /**
+     * The provider stopped, but the host may send the turn again: the failed
+     * attempt only showed text or reasoning, before any checkpoint. Cursor CLI
+     * resends the same action in this case.
+     */
+    hostRetryable;
+    /** What the failed attempt did that a replay inside the Run would repeat. */
+    replayBarrier;
     constructor(message, options) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
         this.name = "CursorProviderError";
@@ -25,8 +36,82 @@ export class CursorProviderError extends Error {
         this.rstCode = options.rstCode;
         this.code = options.code;
         this.retryAfterMs = options.retryAfterMs;
+        this.retryable = options.retryable;
+        this.hostRetryable = options.hostRetryable;
     }
 }
+/** Connect error code → HTTP status, per https://connectrpc.com/docs/protocol/#error-codes. */
+const CONNECT_CODE_HTTP_STATUS = {
+    canceled: 499,
+    unknown: 500,
+    invalid_argument: 400,
+    deadline_exceeded: 504,
+    not_found: 404,
+    already_exists: 409,
+    permission_denied: 403,
+    resource_exhausted: 429,
+    failed_precondition: 400,
+    aborted: 409,
+    out_of_range: 400,
+    unimplemented: 501,
+    internal: 500,
+    unavailable: 503,
+    data_loss: 500,
+    unauthenticated: 401,
+};
+/** Status for a final failure whose Connect code maps to 5xx (internal, unknown, …). */
+const NON_RETRYABLE_SERVER_STATUS = 400;
+/**
+ * The error the host receives. Like Cursor CLI, a request Cursor declared not
+ * retryable (see `cursorCliRetryable`), a spent/unsafe provider retry, or an
+ * authentication failure ends the turn: it becomes an AI SDK `APICallError`
+ * with `isRetryable: false` and the
+ * conventional `x-should-retry: false` header, which OpenCode 2 checks first
+ * (it retries a failure with no status or recognized code). OpenCode 1.x
+ * ignores both and retries any status >= 500 or a message matching its retry
+ * patterns, so the status is the Connect code's HTTP status capped below 500
+ * (Cursor CLI decides from the verdict, never the code) and the message is
+ * sanitized. The original code stays on `cause`.
+ *
+ * A `hostRetryable` failure is the opposite: Cursor CLI would send the same
+ * action again, but output the host already shows stops the provider from
+ * doing so. It becomes an `APICallError` with `isRetryable: true`, which
+ * OpenCode 1.x retries as the same step, and `x-should-retry: true` without a
+ * status, which OpenCode 2 continues after the shown output.
+ */
+export function hostFacingError(error) {
+    if (!(error instanceof Error))
+        return new Error(String(error));
+    const auth = error instanceof CursorAuthError;
+    if (!auth && error instanceof CursorProviderError && error.hostRetryable) {
+        return new APICallError({
+            message: error.message,
+            url: "cursor://agent.v1.AgentService/Run",
+            requestBodyValues: {},
+            responseHeaders: {
+                "x-should-retry": "true",
+                ...(error.retryAfterMs === undefined ? {} : { "retry-after-ms": String(error.retryAfterMs) }),
+            },
+            isRetryable: true,
+            cause: error,
+        });
+    }
+    if (!auth && (!(error instanceof CursorProviderError) || error.retryable !== false))
+        return error;
+    const connectStatus = error.code !== undefined && Object.hasOwn(CONNECT_CODE_HTTP_STATUS, error.code)
+        ? CONNECT_CODE_HTTP_STATUS[error.code]
+        : CONNECT_CODE_HTTP_STATUS.unknown;
+    const status = auth ? (error.statusCode === 403 ? 403 : 401) : connectStatus;
+    return new APICallError({
+        message: sanitizeHostTerminalMessage(error.message),
+        url: "cursor://agent.v1.AgentService/Run",
+        requestBodyValues: {},
+        statusCode: status >= 500 ? NON_RETRYABLE_SERVER_STATUS : status,
+        responseHeaders: { "x-should-retry": "false" },
+        isRetryable: false,
+        cause: error,
+    });
+}
 export class CursorLocalCancellationError extends CursorProviderError {
     constructor(message = "Cursor request cancelled locally", cause) {
         super(message, {
@@ -92,22 +177,53 @@ export function isRejectedCredentialError(error) {
         isUnauthenticatedStatus(error.code));
 }
 /**
- * OpenCode's SessionRetry treats several substrings in provider error messages
- * as always-retryable — notably bare "unavailable" and "exhausted", plus a
- * broader regex set (resource_exhausted, service unavailable, …).
- *
- * When this provider has already spent its Run retry budget, or has decided a
- * replay would be unsafe, the host-facing message must not re-arm that loop.
- * Keep the real gRPC/HTTP code on structured fields (`code`, `grpcStatus`).
+ * OpenCode 1.x SessionRetry retries an error whose message matches these
+ * patterns even when it is marked non-retryable (`RETRYABLE_MESSAGE_PATTERNS`
+ * and the `exhausted` / `unavailable` / `too_many_requests` substrings in
+ * upstream `packages/opencode/src/session/retry.ts`, v1.19). The status
+ * patterns match anywhere, so "$1500" or "500k" also re-arm it.
+ */
+const HOST_RETRY_MESSAGE_PATTERNS = [
+    /429|500|502|503|504|524/gi,
+    /rate increased too quickly|rate limit|rate-limit|rate_limit|too many requests|too_many_requests/gi,
+    /overloaded|service unavailable|service_unavailable|service-unavailable|internal error|internal_error|internal server error|server error|server_error|server-error|provider returned error|provider_returned_error|provider-returned-error/gi,
+    /terminated|fetch failed|failed to fetch|network[-_\s]error|upstream connect|connection error|connection refused|connection lost|socket connection was closed|socket hang up|reset before headers|getaddrinfo|enotfound|eai_again|econnrefused|econnreset|etimedout/gi,
+    /^timeout$|\b(?:request|response|connection|network|stream|read) (?:timeout|timed out|time out)\b/gi,
+    /try your request again|retry your request|resource exhausted|resource_exhausted/gi,
+    /\btry again (?:later|in\b)|\b(?:currently|temporarily) at capacity\b/gi,
+    /exhausted|unavailable/gi,
+];
+/** Invisible U+2060 WORD JOINER: the text reads the same but no longer matches. */
+const WORD_JOINER = "\u2060";
+/**
+ * When this provider has already spent its Run retry budget, decided a replay
+ * would be unsafe, or Cursor declared the request not retryable, the
+ * host-facing message must not re-arm OpenCode's SessionRetry loop. Common
+ * trigger words get readable replacements; any remaining match (status-like
+ * digits, Cursor's own wording) is split with a word joiner. Keep the real
+ * gRPC/HTTP code on structured fields (`code`, `grpcStatus`).
  */
 export function sanitizeHostTerminalMessage(message) {
-    return message
+    let text = message
         .replace(/\bresource[_\s-]?exhausted\b/gi, "capacity_limit")
         .replace(/\bservice[_\s-]?unavailable\b/gi, "capacity_limit")
         .replace(/\bunavailable\b/gi, "capacity_limit")
         .replace(/\boverloaded\b/gi, "capacity_limit")
         .replace(/\bretry exhausted\b/gi, "retries finished")
         .replace(/\bexhausted\b/gi, "finished");
+    // A joiner can add a `\b` boundary, so repeat until nothing matches.
+    for (let pass = 0; pass < 4; pass++) {
+        let changed = false;
+        for (const pattern of HOST_RETRY_MESSAGE_PATTERNS) {
+            text = text.replace(pattern, (match) => {
+                changed = true;
+                return `${match[0]}${WORD_JOINER}${match.slice(1)}`;
+            });
+        }
+        if (!changed)
+            break;
+    }
+    return text;
 }
 export class CursorRetryExhaustedError extends CursorProviderError {
     attempts;
@@ -118,6 +234,7 @@ export class CursorRetryExhaustedError extends CursorProviderError {
             origin: last.origin,
             transient: false,
             replaySafe: false,
+            retryable: false,
             statusCode: last.statusCode,
             grpcStatus: last.grpcStatus,
             rstCode: last.rstCode,
@@ -227,12 +344,50 @@ export function toCursorProviderError(error, options = { replaySafe: false }) {
         cause: error,
     });
 }
+/**
+ * A transient failure after the attempt showed only text or reasoning, before
+ * any checkpoint of the turn. Cursor CLI sends the same action again; the host
+ * does that here (see `hostFacingError`), and the lost-request record carries
+ * the user's request once.
+ */
+export function hostRetryError(cause, beforeOutput = false) {
+    return new CursorProviderError(beforeOutput
+        ? `${cause.message}; the Run could not start and the turn can be sent again`
+        : `${cause.message} after visible output, before Cursor saved a checkpoint; the turn can be sent again`, {
+        origin: cause.origin,
+        transient: false,
+        replaySafe: false,
+        hostRetryable: true,
+        statusCode: cause.statusCode,
+        grpcStatus: cause.grpcStatus,
+        rstCode: cause.rstCode,
+        code: cause.code,
+        retryAfterMs: cause.retryAfterMs,
+        cause,
+    });
+}
+/**
+ * Cursor CLI stops automatic resumes after two resumed attempts that streamed
+ * but saved no checkpoint, so the turn does not repeat the same work forever.
+ */
+export function noProgressResumeError(cause, resumes) {
+    return new CursorProviderError(`Cursor Run stopped after ${resumes} resume attempts made no progress; ` +
+        "send a message to continue from the last saved state", {
+        origin: cause.origin,
+        transient: false,
+        replaySafe: false,
+        retryable: false,
+        code: cause.code,
+        cause,
+    });
+}
 export function retrySuppressedError(cause, reason, attempt, maxAttempts) {
     const subject = sanitizeHostTerminalMessage(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,
+        retryable: false,
         statusCode: cause.statusCode,
         grpcStatus: cause.grpcStatus,
         rstCode: cause.rstCode,

package/dist/host-interrupt.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `openCodeSessionId` undefined: every session (the host is shutting down).
+ * `at`: when the host stopped, on this process's clock.
+ */
+export type HostInterruptListener = (openCodeSessionId: string | undefined, reason: string, at: number) => void | Promise<void>;
+export declare function onHostInterrupt(listener: HostInterruptListener): () => void;
+/**
+ * The host stopped this session's execution (OpenCode 2 never aborts `doStream`
+ * for it). `reason: "shutdown"` keeps the turn for the next server start: its
+ * state is saved, nothing is cancelled. Resolves once every listener settled.
+ */
+export declare function notifyHostInterrupt(openCodeSessionId: string | undefined, reason: string, at?: number): Promise<void>;

package/dist/host-interrupt.js

@@ -0,0 +1,18 @@
+// OpenCode 2 can evaluate the plugin and the AI SDK model as separate copies
+// of this module (one per Location); the copy holding the Run must hear the
+// plugin's interrupt.
+const LISTENERS = Symbol.for("cursor-opencode-provider.host-interrupt-listeners");
+const globals = globalThis;
+const listeners = globals[LISTENERS] ??= new Set();
+export function onHostInterrupt(listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}
+/**
+ * The host stopped this session's execution (OpenCode 2 never aborts `doStream`
+ * for it). `reason: "shutdown"` keeps the turn for the next server start: its
+ * state is saved, nothing is cancelled. Resolves once every listener settled.
+ */
+export async function notifyHostInterrupt(openCodeSessionId, reason, at = Date.now()) {
+    await Promise.allSettled([...listeners].map(async (listener) => listener(openCodeSessionId, reason, at)));
+}

package/dist/host-steer.d.ts

@@ -0,0 +1,71 @@
+export type HostSteer = {
+    sessionID: string;
+    inboxID: string;
+    text: string;
+};
+export type EarlySteer = HostSteer & {
+    injectionId: string;
+    /** The Cursor Run (`CursorSession.sessionId`) it was injected into, or the Run resumed from its checkpoint. */
+    run: string;
+    delivered: boolean;
+    /** A checkpoint arrived after Cursor delivered it, so a Run resumed from that checkpoint holds it. */
+    checkpointed: boolean;
+    /** Its Run reached `turn_ended` after delivering it, so the model has answered it. */
+    answered: boolean;
+    /** OpenCode's own copy came after the step's tool results and was left out of the continuation. */
+    promoted?: boolean;
+    /** Prompt boundary at which the host supplied its copy; distinct later replies do not match it. */
+    hostTurn?: string;
+};
+/** undefined when another plugin copy already announced the steer. */
+export declare function announceHostSteer(steer: HostSteer): boolean | undefined;
+/** Remember a queued message, so a later switch to `steer` can announce it. */
+export declare function rememberQueuedSteer(steer: HostSteer): void;
+export declare function takeQueuedSteer(inboxID: string): HostSteer | undefined;
+export declare function listenForHostSteers(sessionID: string, listener: (steer: HostSteer) => boolean): () => void;
+/** false when there is no room to track it; OpenCode's own copy then runs as usual. */
+export declare function recordEarlySteer(steer: EarlySteer): boolean;
+export declare function isEarlySteerTracked(sessionID: string, injectionId: string): boolean;
+/** An injection Cursor never accepted. A promoted one stays, to be sent at `turn_ended`. */
+export declare function forgetUndeliveredEarlySteer(sessionID: string, injectionId: string): void;
+/** The host withdrew the message, so no copy of it will come. */
+export declare function forgetEarlySteerOfInbox(sessionID: string, inboxID: string): void;
+/** true when the injection is an early steer. */
+export declare function markEarlySteerDelivered(sessionID: string | undefined, injectionId: string | undefined): boolean;
+export declare function markEarlySteersCheckpointed(sessionID: string | undefined, run: string): void;
+/**
+ * At `turn_ended`: a delivered steer is answered and waits for OpenCode's copy; one Cursor never took is
+ * forgotten, so OpenCode's copy runs as an ordinary message. A promoted one has no copy left to come:
+ * one Cursor never took is returned for a follow-up Run and stays, as sent, until a checkpoint holds it.
+ * Answered receipts survive retries and are retired when a later Run finishes.
+ */
+export declare function settleEarlySteers(sessionID: string | undefined, run: string): {
+    answered: number;
+    undelivered: EarlySteer[];
+    leftToHost: number;
+};
+/**
+ * A failed Run's steers: those its checkpoint holds go to the Run resumed from it (`to`), and so does a
+ * promoted one it does not hold, to be sent at that Run's `turn_ended`. The rest are forgotten, so
+ * OpenCode's own copy of each runs as an ordinary message. A rebase (`to` undefined) seeds from host
+ * history, which already holds a promoted copy.
+ */
+export declare function handOverEarlySteers(sessionID: string | undefined, from: string, to: string | undefined): void;
+/** The host may add `<system-reminder>` parts to a promoted copy; any other difference is another message. */
+export declare function carriesSteer(message: string, text: string): boolean;
+/** The record each message carries, or nothing unless every message carries one. */
+export declare function matchEarlySteers(sessionID: string | undefined, messages: readonly string[], accept: (record: EarlySteer) => boolean): EarlySteer[];
+export declare function forgetEarlySteerRecords(sessionID: string, records: readonly EarlySteer[]): void;
+/**
+ * A steer of a Run that ended without answering it (a stop, a failed recovery) that only host history
+ * holds reliably: OpenCode placed it in its history (a checkpoint may hold it too, and resuming would
+ * then send it twice), or a checkpoint holds it while OpenCode's copy is still to come.
+ */
+export declare function needsHostHistory(sessionID: string | undefined, openRun: string | undefined): boolean;
+/** Keep answered receipts until the new turn succeeds, so a host retry still omits its copies. */
+export declare function clearUnansweredEarlySteers(sessionID: string | undefined): void;
+/** Private restart metadata, saved atomically with the checkpoint it describes. */
+export declare function serializeEarlySteers(sessionID: string): string | undefined;
+export declare function restoreEarlySteers(sessionID: string, encoded: string | undefined): void;
+export declare function forgetEarlySteers(sessionID: string): void;
+export declare function resetHostSteersForTests(): void;

package/dist/host-steer.js

@@ -0,0 +1,232 @@
+import { processShared } from "./process-shared.js";
+const MAX_RECORDS_PER_SESSION = 32;
+const MAX_REMEMBERED = 256;
+// The plugin and the model can be separate copies of this module, and each plugin copy sees every event.
+const state = processShared("host-steers.v1", () => ({
+    listeners: new Map(),
+    injected: new Map(),
+    queued: new Map(),
+    announced: new Set(),
+}));
+function remember(entries, key) {
+    while (entries.size > MAX_REMEMBERED) {
+        const oldest = entries.keys().next().value;
+        if (oldest === undefined || oldest === key)
+            break;
+        entries.delete(oldest);
+    }
+}
+/** undefined when another plugin copy already announced the steer. */
+export function announceHostSteer(steer) {
+    if (state.announced.has(steer.inboxID))
+        return undefined;
+    state.announced.add(steer.inboxID);
+    remember(state.announced, steer.inboxID);
+    const listener = state.listeners.get(steer.sessionID);
+    return listener ? listener(steer) : false;
+}
+/** Remember a queued message, so a later switch to `steer` can announce it. */
+export function rememberQueuedSteer(steer) {
+    if (state.announced.has(steer.inboxID))
+        return;
+    state.queued.delete(steer.inboxID);
+    state.queued.set(steer.inboxID, steer);
+    remember(state.queued, steer.inboxID);
+}
+export function takeQueuedSteer(inboxID) {
+    const steer = state.queued.get(inboxID);
+    state.queued.delete(inboxID);
+    return steer;
+}
+export function listenForHostSteers(sessionID, listener) {
+    state.listeners.set(sessionID, listener);
+    return () => {
+        if (state.listeners.get(sessionID) === listener)
+            state.listeners.delete(sessionID);
+    };
+}
+/** false when there is no room to track it; OpenCode's own copy then runs as usual. */
+export function recordEarlySteer(steer) {
+    const records = state.injected.get(steer.sessionID);
+    if (records ? records.length >= MAX_RECORDS_PER_SESSION : state.injected.size >= MAX_REMEMBERED)
+        return false;
+    state.injected.set(steer.sessionID, [...records ?? [], steer]);
+    return true;
+}
+function keep(sessionID, records) {
+    if (records.length === 0)
+        state.injected.delete(sessionID);
+    else
+        state.injected.set(sessionID, records);
+}
+export function isEarlySteerTracked(sessionID, injectionId) {
+    return !!state.injected.get(sessionID)?.some((record) => record.injectionId === injectionId);
+}
+/** An injection Cursor never accepted. A promoted one stays, to be sent at `turn_ended`. */
+export function forgetUndeliveredEarlySteer(sessionID, injectionId) {
+    keep(sessionID, (state.injected.get(sessionID) ?? [])
+        .filter((record) => record.injectionId !== injectionId || record.delivered || record.promoted));
+}
+/** The host withdrew the message, so no copy of it will come. */
+export function forgetEarlySteerOfInbox(sessionID, inboxID) {
+    keep(sessionID, (state.injected.get(sessionID) ?? []).filter((record) => record.inboxID !== inboxID));
+}
+/** true when the injection is an early steer. */
+export function markEarlySteerDelivered(sessionID, injectionId) {
+    const record = sessionID && injectionId
+        ? state.injected.get(sessionID)?.find((candidate) => candidate.injectionId === injectionId)
+        : undefined;
+    if (record)
+        record.delivered = true;
+    return !!record;
+}
+export function markEarlySteersCheckpointed(sessionID, run) {
+    for (const record of (sessionID && state.injected.get(sessionID)) || []) {
+        if (record.run === run && record.delivered)
+            record.checkpointed = true;
+    }
+}
+/**
+ * At `turn_ended`: a delivered steer is answered and waits for OpenCode's copy; one Cursor never took is
+ * forgotten, so OpenCode's copy runs as an ordinary message. A promoted one has no copy left to come:
+ * one Cursor never took is returned for a follow-up Run and stays, as sent, until a checkpoint holds it.
+ * Answered receipts survive retries and are retired when a later Run finishes.
+ */
+export function settleEarlySteers(sessionID, run) {
+    const records = sessionID ? state.injected.get(sessionID) : undefined;
+    if (!records)
+        return { answered: 0, undelivered: [], leftToHost: 0 };
+    let answered = 0;
+    let leftToHost = 0;
+    const undelivered = [];
+    const kept = records.filter((record) => {
+        if (record.run !== run)
+            return !record.answered;
+        if (record.promoted) {
+            if (record.delivered) {
+                if (!record.answered) {
+                    record.answered = true;
+                    answered++;
+                }
+                return true;
+            }
+            undelivered.push(record);
+            record.delivered = true;
+            return true;
+        }
+        if (!record.delivered) {
+            leftToHost++;
+            return false;
+        }
+        if (!record.answered) {
+            record.answered = true;
+            answered++;
+        }
+        return true;
+    });
+    keep(sessionID, kept);
+    return { answered, undelivered, leftToHost };
+}
+/**
+ * A failed Run's steers: those its checkpoint holds go to the Run resumed from it (`to`), and so does a
+ * promoted one it does not hold, to be sent at that Run's `turn_ended`. The rest are forgotten, so
+ * OpenCode's own copy of each runs as an ordinary message. A rebase (`to` undefined) seeds from host
+ * history, which already holds a promoted copy.
+ */
+export function handOverEarlySteers(sessionID, from, to) {
+    const records = sessionID ? state.injected.get(sessionID) : undefined;
+    if (!records)
+        return;
+    keep(sessionID, records.filter((record) => {
+        if (record.run !== from || record.answered)
+            return true;
+        if (!to || (!record.checkpointed && !record.promoted))
+            return false;
+        record.run = to;
+        if (!record.checkpointed)
+            record.delivered = false;
+        return true;
+    }));
+}
+const SYSTEM_REMINDER = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
+/** The host may add `<system-reminder>` parts to a promoted copy; any other difference is another message. */
+export function carriesSteer(message, text) {
+    return message.replace(SYSTEM_REMINDER, "").trim() === text.trim();
+}
+/** The record each message carries, or nothing unless every message carries one. */
+export function matchEarlySteers(sessionID, messages, accept) {
+    const records = sessionID ? state.injected.get(sessionID) : undefined;
+    if (!records?.length || messages.length === 0)
+        return [];
+    const candidates = [...records];
+    const matched = [];
+    for (const message of messages) {
+        const index = candidates.findIndex((record) => accept(record) && carriesSteer(message, record.text));
+        if (index === -1)
+            return [];
+        matched.push(...candidates.splice(index, 1));
+    }
+    return matched;
+}
+export function forgetEarlySteerRecords(sessionID, records) {
+    keep(sessionID, (state.injected.get(sessionID) ?? []).filter((record) => !records.includes(record)));
+}
+/**
+ * A steer of a Run that ended without answering it (a stop, a failed recovery) that only host history
+ * holds reliably: OpenCode placed it in its history (a checkpoint may hold it too, and resuming would
+ * then send it twice), or a checkpoint holds it while OpenCode's copy is still to come.
+ */
+export function needsHostHistory(sessionID, openRun) {
+    return !!sessionID && !!state.injected.get(sessionID)?.some((record) => !record.answered && record.run !== openRun && (record.promoted || record.checkpointed));
+}
+/** Keep answered receipts until the new turn succeeds, so a host retry still omits its copies. */
+export function clearUnansweredEarlySteers(sessionID) {
+    if (sessionID)
+        keep(sessionID, (state.injected.get(sessionID) ?? []).filter((record) => record.answered));
+}
+/** Private restart metadata, saved atomically with the checkpoint it describes. */
+export function serializeEarlySteers(sessionID) {
+    const records = state.injected.get(sessionID);
+    return records?.length ? JSON.stringify({ version: 1, records }) : undefined;
+}
+export function restoreEarlySteers(sessionID, encoded) {
+    if (!encoded || state.injected.has(sessionID) || state.injected.size >= MAX_REMEMBERED)
+        return;
+    let value;
+    try {
+        value = JSON.parse(encoded);
+    }
+    catch {
+        return;
+    }
+    if (!value || value.version !== 1 || !Array.isArray(value.records) || value.records.length > MAX_RECORDS_PER_SESSION)
+        return;
+    const records = [];
+    for (const record of value.records) {
+        if (!record || record.sessionID !== sessionID
+            || ![record.inboxID, record.injectionId, record.run, record.text].every((part) => typeof part === "string" && part.length > 0)
+            || ![record.delivered, record.checkpointed, record.answered].every((part) => typeof part === "boolean")
+            || ((record.checkpointed || record.answered) && !record.delivered)
+            || (record.promoted !== undefined && typeof record.promoted !== "boolean")
+            || (record.hostTurn !== undefined && (typeof record.hostTurn !== "string" || !/^[a-f0-9]{64}$/.test(record.hostTurn))))
+            return;
+        records.push({
+            sessionID, inboxID: record.inboxID, injectionId: record.injectionId, run: record.run, text: record.text,
+            delivered: record.delivered, checkpointed: record.checkpointed, answered: record.answered,
+            ...(record.promoted !== undefined ? { promoted: record.promoted } : {}),
+            ...(record.hostTurn !== undefined ? { hostTurn: record.hostTurn } : {}),
+        });
+    }
+    if (records.length)
+        state.injected.set(sessionID, records);
+}
+export function forgetEarlySteers(sessionID) {
+    state.injected.delete(sessionID);
+    state.listeners.delete(sessionID);
+}
+export function resetHostSteersForTests() {
+    state.listeners.clear();
+    state.injected.clear();
+    state.queued.clear();
+    state.announced.clear();
+}

package/dist/image-input.js

@@ -374,10 +374,11 @@ export async function extractCursorPromptImages(prompt, lastUser, options) {
         return true;
     }) : await extractCursorUserImages(lastUser, options.signal, maxBytes);
     const userBytes = userImages.reduce((total, image) => total + image.data.length, 0);
+    const userHashes = toolCaption ? captionHashes : userImages.map((image) => imageContentHash(image.data));
     // 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.
-    for (const image of userImages)
-        seenHashes.add(imageContentHash(image.data));
+    for (const hash of userHashes)
+        seenHashes.add(hash);
     const history = await extractCursorHistoryImages(prompt, {
         supportsImages: options.supportsImages,
         seenHashes,
@@ -387,7 +388,7 @@ export async function extractCursorPromptImages(prompt, lastUser, options) {
     });
     return {
         ...history,
-        hashes: [...captionHashes, ...history.hashes],
+        hashes: [...userHashes, ...history.hashes],
         duplicateCount: history.duplicateCount + captionDuplicates,
         images: [...userImages, ...history.images],
         userImageCount: toolCaption ? 0 : userImages.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;