cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/context/skills.js

@@ -0,0 +1,211 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { skillsBridge, } from "./skills-bridge.js";
+/**
+ * Cursor path-desc `agent_skills`: `{ full_path, description }` only, plus
+ * `agent_skills_info_complete: true`. Catalog text in the frozen system-
+ * instructions rule is the permission filter and order; locations come from
+ * the structural `opencode.host.skills` bridge, else OpenCode 2 `skill.list()`
+ * files remembered by the plugin, else OpenCode 1 catalog `<location>`.
+ *
+ * No content on the wire. Built-in / marker locations stay on the host `skill`
+ * tool only.
+ */
+// Plugin and language-model can load separate module graphs (see image-staging).
+const HOST_SKILL_FILES = Symbol.for("cursor-opencode-provider.host-skill-files");
+const globals = globalThis;
+const byDirectory = globals[HOST_SKILL_FILES] ??= new Map();
+const MAX_DIRECTORIES = 64;
+const CATALOG = /<available_skills>([\s\S]*?)<\/available_skills>/;
+// Names and descriptions are unescaped; OpenCode 1 escapes locations only.
+const ENTRY_OC2 = /<skill>\s*<id>([\s\S]*?)<\/id>\s*<name>[\s\S]*?<\/name>\s*<description>([\s\S]*?)<\/description>\s*<\/skill>/g;
+const ENTRY_OC1 = /<skill>\s*<name>([\s\S]*?)<\/name>\s*<description>([\s\S]*?)<\/description>\s*<location>([\s\S]*?)<\/location>\s*<\/skill>/g;
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function hasUriScheme(value) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value);
+}
+/** Locations Cursor can advertise; markers / builtins are omitted. */
+export function isUsableSkillLocation(location) {
+    if (typeof location !== "string")
+        return false;
+    const value = location.trim();
+    if (!value)
+        return false;
+    if (value === "<built-in>" || value === "builtin")
+        return false;
+    if (value.startsWith("/builtin/"))
+        return false;
+    if (hasUriScheme(value)) {
+        if (value.startsWith("file:")) {
+            try {
+                const filePath = fileURLToPath(value);
+                return path.isAbsolute(filePath) && isFile(filePath);
+            }
+            catch {
+                return false;
+            }
+        }
+        // Host URIs such as skill://name — keep for bridge hosts; no disk check.
+        return true;
+    }
+    return path.isAbsolute(value) && isFile(value);
+}
+export function normalizeSkillLocation(location) {
+    const value = location.trim();
+    if (value.startsWith("file:")) {
+        try {
+            return fileURLToPath(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+export function skillToolAdvertised(tools) {
+    return (tools ?? []).some((tool) => tool?.name === "skill");
+}
+/** Record skill files a Location's host currently registers (OpenCode 2 plugin). */
+export function rememberHostSkillFiles(directory, skills) {
+    const key = path.resolve(directory);
+    const files = new Map();
+    for (const skill of skills) {
+        if (typeof skill?.id !== "string" || typeof skill.path !== "string")
+            continue;
+        if (!path.isAbsolute(skill.path) || !isFile(skill.path))
+            continue;
+        files.set(skill.id, skill.path);
+    }
+    byDirectory.delete(key);
+    byDirectory.set(key, files);
+    while (byDirectory.size > MAX_DIRECTORIES) {
+        const oldest = byDirectory.keys().next().value;
+        if (oldest === undefined)
+            break;
+        byDirectory.delete(oldest);
+    }
+}
+export function hostSkillFiles(directory) {
+    return directory ? byDirectory.get(path.resolve(directory)) : undefined;
+}
+/** Test helper. */
+export function resetHostSkillFilesForTests() {
+    byDirectory.clear();
+}
+/** Undo OpenCode 1's escapeHtml once; literal entity text in paths must survive. */
+function decodeCatalogLocation(value) {
+    const entities = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'" };
+    return value.replace(/&(?:amp|lt|gt|quot|#39);/g, (entity) => entities[entity]);
+}
+function parseCatalogEntries(systemText) {
+    const catalog = CATALOG.exec(systemText)?.[1];
+    if (!catalog)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const match of catalog.matchAll(ENTRY_OC2)) {
+        const id = match[1]?.trim();
+        const description = match[2] ?? "";
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        out.push({ key: id, description: description.trim() });
+    }
+    if (out.length > 0)
+        return out;
+    for (const match of catalog.matchAll(ENTRY_OC1)) {
+        const name = match[1]?.trim();
+        const description = match[2] ?? "";
+        const location = match[3] ? decodeCatalogLocation(match[3].trim()) : undefined;
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        out.push({
+            key: name,
+            description: description.trim(),
+            location: location || undefined,
+        });
+    }
+    return out;
+}
+function locationFromBridge(entry, bridgeSkills) {
+    if (!bridgeSkills?.length)
+        return undefined;
+    const byId = bridgeSkills.find((skill) => skill.id === entry.key && isUsableSkillLocation(skill.location));
+    if (byId?.location)
+        return normalizeSkillLocation(byId.location);
+    const byName = bridgeSkills.find((skill) => skill.name === entry.key && isUsableSkillLocation(skill.location));
+    if (byName?.location)
+        return normalizeSkillLocation(byName.location);
+    return undefined;
+}
+/**
+ * path-desc `agent_skills` for cataloged skills that have a usable location,
+ * in catalog order. Descriptions come from the catalog (epoch-stable).
+ */
+export function agentSkillsForCursor(systemText, options) {
+    if (!options.skillToolAdvertised || !systemText)
+        return [];
+    const entries = parseCatalogEntries(systemText);
+    if (entries.length === 0)
+        return [];
+    const out = [];
+    const seenPaths = new Set();
+    for (const entry of entries) {
+        let location = locationFromBridge(entry, options.bridgeSkills);
+        if (!location) {
+            const file = options.skillFiles?.get(entry.key);
+            if (file && isUsableSkillLocation(file))
+                location = file;
+        }
+        if (!location && entry.location && isUsableSkillLocation(entry.location)) {
+            location = normalizeSkillLocation(entry.location);
+        }
+        if (!location || seenPaths.has(location))
+            continue;
+        seenPaths.add(location);
+        out.push({ full_path: location, description: entry.description });
+    }
+    return out;
+}
+/** Fetch locations from the structural bridge when installed. */
+export async function loadBridgeSkills(input) {
+    const bridge = skillsBridge();
+    if (!bridge)
+        return undefined;
+    try {
+        const listed = await bridge.list({
+            directory: path.resolve(input.workspaceRoot),
+            sessionID: input.sessionID,
+        });
+        if (!Array.isArray(listed))
+            return undefined;
+        return listed.filter((skill) => !!skill
+            && typeof skill === "object"
+            && typeof skill.name === "string"
+            && typeof skill.description === "string");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function applyAgentSkillsToContext(context, skills) {
+    if (skills.length === 0) {
+        delete context.agent_skills;
+        delete context.agent_skills_info_complete;
+        return;
+    }
+    context.agent_skills = skills.map((skill) => ({
+        full_path: skill.full_path,
+        description: skill.description,
+    }));
+    context.agent_skills_info_complete = true;
+}

package/dist/debug.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { processShared } from "./process-shared.js";
 // Wire-level diagnostics. Opt in with CURSOR_PROVIDER_DEBUG=1 (or "true").
 // Default path mirrors Cursor CLI: $TMPDIR/cursor-provider-logs-<uid>/debug-<pid>.log
 // with directory mode 0o700 and file mode 0o600. Override with CURSOR_PROVIDER_DEBUG_FILE.
@@ -14,6 +15,11 @@ const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
     process.env.CURSOR_PROVIDER_DEBUG === "true";
 /** Soft cap for the debug log file; exceeded size triggers truncate + new header. */
 export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
+// A host can load this package more than once in one process (a plugin and an
+// AI SDK package import, or one plugin import per location). Count the copies so
+// each banner names its copy and, once there are several, every line says which.
+const moduleCopies = processShared("debug.module-copies.v1", () => ({ count: 0 }));
+const MODULE_COPY = ++moduleCopies.count;
 let _traceInitialized = false;
 let _debugFile;
 let _debugFileUsesManagedDirectory = false;
@@ -73,7 +79,12 @@ function announceLogPath(filePath) {
     }
 }
 function debugBannerLine() {
-    return `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`;
+    return `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ` +
+        `copy=#${MODULE_COPY} module=${import.meta.url} ---\n`;
+}
+/** `#N` on each line once a second copy of this module exists in the process. */
+function copyTag() {
+    return moduleCopies.count > 1 ? `#${MODULE_COPY} ` : "";
 }
 /**
  * If `filePath` is at least `maxBytes`, truncate it and write a size-cap header.
@@ -120,7 +131,7 @@ export function trace(msg) {
                 `\n`);
         }
         truncateDebugLogIfOversized(_debugFile);
-        fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${msg}\n`);
+        fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${copyTag()}${msg}\n`);
     }
     catch {
         /* ignore */

package/dist/early-tool-rows.d.ts

@@ -0,0 +1,60 @@
+/** Shown when an announced edit never becomes a host tool call. */
+export declare const EARLY_ROW_CLOSED = "Cursor did not finish this tool call.";
+/**
+ * Shown when the announced call runs as a host tool the row did not predict,
+ * such as a rewrite with unchanged content, which stays a `write`. The row's
+ * tool name cannot change once started (OpenCode 2 rejects a renamed call),
+ * so it completes and names the call that carries on.
+ */
+export declare function earlyRowHandoff(toolName: string): string;
+export type EarlyToolRow = {
+    cursorCallId: string;
+    toolCallId: string;
+    toolName: string;
+    path: string;
+};
+/**
+ * Does not match `cursor_<session>_<execId>`. Continuation finds a bound row
+ * through the session route table; a row that was closed never gets a route.
+ * Cursor's call id is digested, not embedded: it can hold a newline and run to
+ * ~90 characters, and the host keeps this id in history for every provider.
+ */
+export declare function earlyRowToolCallId(sessionId: string, cursorCallId: string): string;
+/** No exec has this id: the result is this provider's, but its exec is unknown. */
+export declare const UNBOUND_EXEC_ID = -1;
+/**
+ * An early-row id whose route is gone (process restart, evicted route) still
+ * belongs to this provider. Its result proves the Run lost a completed call,
+ * so it must rebuild from host history like any other orphaned result.
+ * The session id is a UUID, so it ends at the first underscore.
+ */
+export declare function parseEarlyRowToolCallId(toolCallId: string): {
+    sessionId: string;
+    execId: number;
+} | undefined;
+/** Edit path from a `partial_tool_call`, once Cursor has included one. */
+export declare function cursorEditAnnouncement(partial: unknown): {
+    callId: string;
+    path: string;
+} | undefined;
+/**
+ * Open only while this step cannot end before the exec arrives. A parallel
+ * step that is holding can take another row. Otherwise the step ends on the
+ * first host call, so a row is useful only before any call or owed exec.
+ */
+export declare function shouldOpenEarlyRow(input: {
+    allowTools: boolean;
+    hostInterrupted: boolean;
+    holdingParallelStep: boolean;
+    emittedHostTools: number;
+    owedPending: number;
+}): boolean;
+export declare class EarlyToolRows {
+    private readonly open;
+    private readonly skipped;
+    seen(callId: string): boolean;
+    openRow(row: EarlyToolRow): void;
+    skip(callId: string): void;
+    claim(callId: string | undefined): EarlyToolRow | undefined;
+    drain(): EarlyToolRow[];
+}

package/dist/early-tool-rows.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+/** Shown when an announced edit never becomes a host tool call. */
+export const EARLY_ROW_CLOSED = "Cursor did not finish this tool call.";
+/**
+ * Shown when the announced call runs as a host tool the row did not predict,
+ * such as a rewrite with unchanged content, which stays a `write`. The row's
+ * tool name cannot change once started (OpenCode 2 rejects a renamed call),
+ * so it completes and names the call that carries on.
+ */
+export function earlyRowHandoff(toolName) {
+    return `Cursor continued this call as \`${toolName}\`.`;
+}
+const EARLY_ROW_PREFIX = "cursor-early_";
+/**
+ * Does not match `cursor_<session>_<execId>`. Continuation finds a bound row
+ * through the session route table; a row that was closed never gets a route.
+ * Cursor's call id is digested, not embedded: it can hold a newline and run to
+ * ~90 characters, and the host keeps this id in history for every provider.
+ */
+export function earlyRowToolCallId(sessionId, cursorCallId) {
+    const digest = createHash("sha256").update(cursorCallId).digest("hex").slice(0, 12);
+    return `${EARLY_ROW_PREFIX}${sessionId}_${digest}`;
+}
+/** No exec has this id: the result is this provider's, but its exec is unknown. */
+export const UNBOUND_EXEC_ID = -1;
+/**
+ * An early-row id whose route is gone (process restart, evicted route) still
+ * belongs to this provider. Its result proves the Run lost a completed call,
+ * so it must rebuild from host history like any other orphaned result.
+ * The session id is a UUID, so it ends at the first underscore.
+ */
+export function parseEarlyRowToolCallId(toolCallId) {
+    if (!toolCallId.startsWith(EARLY_ROW_PREFIX))
+        return undefined;
+    const rest = toolCallId.slice(EARLY_ROW_PREFIX.length);
+    const separator = rest.indexOf("_");
+    if (separator <= 0 || separator === rest.length - 1)
+        return undefined;
+    return { sessionId: rest.slice(0, separator), execId: UNBOUND_EXEC_ID };
+}
+/** Edit path from a `partial_tool_call`, once Cursor has included one. */
+export function cursorEditAnnouncement(partial) {
+    if (!partial || typeof partial !== "object")
+        return undefined;
+    const callId = partial.call_id;
+    const toolCall = partial.tool_call;
+    const edit = toolCall && typeof toolCall === "object"
+        ? toolCall.edit_tool_call
+        : undefined;
+    const args = edit && typeof edit === "object" ? edit.args : undefined;
+    const filePath = args && typeof args === "object" ? args.path : undefined;
+    if (typeof callId !== "string" || callId.length === 0)
+        return undefined;
+    if (typeof filePath !== "string" || filePath.trim().length === 0)
+        return undefined;
+    return { callId, path: filePath };
+}
+/**
+ * Open only while this step cannot end before the exec arrives. A parallel
+ * step that is holding can take another row. Otherwise the step ends on the
+ * first host call, so a row is useful only before any call or owed exec.
+ */
+export function shouldOpenEarlyRow(input) {
+    if (!input.allowTools || input.hostInterrupted)
+        return false;
+    if (input.holdingParallelStep)
+        return true;
+    return input.emittedHostTools === 0 && input.owedPending === 0;
+}
+export class EarlyToolRows {
+    open = new Map();
+    skipped = new Set();
+    seen(callId) {
+        return this.open.has(callId) || this.skipped.has(callId);
+    }
+    openRow(row) {
+        this.open.set(row.cursorCallId, row);
+    }
+    skip(callId) {
+        this.skipped.add(callId);
+    }
+    claim(callId) {
+        if (!callId)
+            return undefined;
+        const row = this.open.get(callId);
+        if (!row)
+            return undefined;
+        this.open.delete(callId);
+        return row;
+    }
+    drain() {
+        const rows = [...this.open.values()];
+        this.open.clear();
+        return rows;
+    }
+}

package/dist/errors.d.ts

@@ -10,6 +10,8 @@ export type CursorProviderErrorOptions = CursorErrorDiagnostics & {
     origin: CursorErrorOrigin;
     transient: boolean;
     replaySafe: boolean;
+    retryable?: boolean;
+    hostRetryable?: boolean;
     cause?: unknown;
 };
 /** Structured provider failure with retry and transport diagnostics. */
@@ -28,8 +30,37 @@ export declare class CursorProviderError extends Error {
     readonly rstCode?: number;
     readonly code?: string;
     readonly retryAfterMs?: number;
+    /** Cursor's classified verdict, or false once provider retries must stop. */
+    readonly retryable?: boolean;
+    /**
+     * 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.
+     */
+    readonly hostRetryable?: boolean;
+    /** What the failed attempt did that a replay inside the Run would repeat. */
+    replayBarrier?: "output-only" | "stateful";
     constructor(message: string, options: CursorProviderErrorOptions);
 }
+/**
+ * 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 declare function hostFacingError(error: unknown): Error;
 export declare class CursorLocalCancellationError extends CursorProviderError {
     constructor(message?: string, cause?: unknown);
 }
@@ -57,13 +88,12 @@ export declare class CursorAuthError extends CursorProviderError {
  */
 export declare function isRejectedCredentialError(error: unknown): error is CursorAuthError;
 /**
- * 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`).
+ * 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 declare function sanitizeHostTerminalMessage(message: string): string;
 export declare class CursorRetryExhaustedError extends CursorProviderError {
@@ -79,4 +109,16 @@ export declare function toCursorProviderError(error: unknown, options?: {
     replaySafe: boolean;
     fallback?: string;
 }): CursorProviderError;
+/**
+ * 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 declare function hostRetryError(cause: CursorProviderError, beforeOutput?: boolean): CursorProviderError;
+/**
+ * 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 declare function noProgressResumeError(cause: CursorProviderError, resumes: number): CursorProviderError;
 export declare function retrySuppressedError(cause: CursorProviderError, reason: string, attempt: number, maxAttempts: number): CursorProviderError;