cursor-opencode-provider 0.7.6 → 0.8.1

package/dist/context/skills.js

@@ -1,110 +1,211 @@
-import { readdir, readFile, stat } from "node:fs/promises";
+import { statSync } from "node:fs";
 import path from "node:path";
-import { homedir } from "node:os";
-import { opencodeGlobalConfigDirs, opencodeProjectConfigDirs } from "./paths.js";
-async function exists(p) {
+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 {
-        await stat(p);
-        return true;
+        return statSync(file).isFile();
     }
     catch {
         return false;
     }
 }
-function parseFrontmatter(raw) {
-    if (!raw.startsWith("---"))
-        return { body: raw };
-    const end = raw.indexOf("\n---", 3);
-    if (end < 0)
-        return { body: raw };
-    const fm = raw.slice(3, end).trim();
-    const body = raw.slice(end + 4).replace(/^\n/, "");
-    let name;
-    let description;
-    for (const line of fm.split("\n")) {
-        const m = line.match(/^(\w+):\s*(.*)$/);
-        if (!m)
-            continue;
-        const key = m[1];
-        let val = m[2].trim();
-        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-            val = val.slice(1, -1);
+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;
+            }
         }
-        if (key === "name")
-            name = val;
-        if (key === "description")
-            description = val;
+        // Host URIs such as skill://name — keep for bridge hosts; no disk check.
+        return true;
     }
-    return { name, description, body };
+    return path.isAbsolute(value) && isFile(value);
 }
-async function loadSkillFile(file) {
-    try {
-        const raw = await readFile(file, "utf-8");
-        const { name, description, body } = parseFrontmatter(raw);
-        const dirName = path.basename(path.dirname(file));
-        return {
-            fullPath: path.resolve(file),
-            name: name || dirName,
-            description: description || "",
-            content: body.slice(0, 20_000),
-        };
-    }
-    catch {
-        return undefined;
+export function normalizeSkillLocation(location) {
+    const value = location.trim();
+    if (value.startsWith("file:")) {
+        try {
+            return fileURLToPath(value);
+        }
+        catch {
+            return value;
+        }
     }
+    return value;
 }
-async function scanSkillsRoot(root, out) {
-    if (!(await exists(root)))
-        return;
-    let entries;
-    try {
-        entries = await readdir(root);
+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);
     }
-    catch {
-        return;
+    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);
     }
-    entries.sort();
-    for (const name of entries) {
-        const skillMd = path.join(root, name, "SKILL.md");
-        if (!(await exists(skillMd)))
+}
+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;
-        const skill = await loadSkillFile(skillMd);
-        if (!skill)
+        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;
-        if (!out.has(skill.name))
-            out.set(skill.name, skill);
+        seen.add(name);
+        out.push({
+            key: name,
+            description: description.trim(),
+            location: location || undefined,
+        });
     }
+    return out;
 }
-async function walkAncestorsFor(dir, rel, stop, out) {
-    let cur = path.resolve(dir);
-    const root = path.resolve(stop);
-    for (;;) {
-        await scanSkillsRoot(path.join(cur, rel), out);
-        if (cur === root)
-            break;
-        const parent = path.dirname(cur);
-        if (parent === cur)
-            break;
-        cur = parent;
-    }
+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;
 }
 /**
- * Discover skills the way OpenCode does: `.opencode/skills`, global opencode,
- * plus `.claude/skills` and `.agents/skills` (project + home).
+ * path-desc `agent_skills` for cataloged skills that have a usable location,
+ * in catalog order. Descriptions come from the catalog (epoch-stable).
  */
-export async function collectSkills(workspaceRoot, worktree) {
-    const out = new Map();
-    const home = homedir();
-    for (const projectDir of opencodeProjectConfigDirs(workspaceRoot)) {
-        const relative = path.relative(workspaceRoot, projectDir);
-        await walkAncestorsFor(workspaceRoot, path.join(relative, "skills"), worktree, out);
+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");
     }
-    for (const globalDir of opencodeGlobalConfigDirs()) {
-        await scanSkillsRoot(path.join(globalDir, "skills"), out);
+    catch {
+        return undefined;
+    }
+}
+export function applyAgentSkillsToContext(context, skills) {
+    if (skills.length === 0) {
+        delete context.agent_skills;
+        delete context.agent_skills_info_complete;
+        return;
     }
-    await walkAncestorsFor(workspaceRoot, path.join(".claude", "skills"), worktree, out);
-    await scanSkillsRoot(path.join(home, ".claude", "skills"), out);
-    await walkAncestorsFor(workspaceRoot, path.join(".agents", "skills"), worktree, out);
-    await scanSkillsRoot(path.join(home, ".agents", "skills"), out);
-    return [...out.values()];
+    context.agent_skills = skills.map((skill) => ({
+        full_path: skill.full_path,
+        description: skill.description,
+    }));
+    context.agent_skills_info_complete = true;
 }

package/dist/debug.d.ts

@@ -1,5 +1,7 @@
 /** Soft cap for the debug log file; exceeded size triggers truncate + new header. */
 export declare const DEBUG_LOG_MAX_BYTES: number;
+/** Message of an unknown thrown value, for log lines and error text. */
+export declare function errorMessage(error: unknown): string;
 /** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
 export declare function isDebugEnabled(): boolean;
 /** Resolve the debug log path (env override or per-uid tmpdir default). */

package/dist/debug.js

@@ -18,6 +18,10 @@ let _traceInitialized = false;
 let _debugFile;
 let _debugFileUsesManagedDirectory = false;
 let _announcedLogPath = false;
+/** Message of an unknown thrown value, for log lines and error text. */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
 export function isDebugEnabled() {
     return DEBUG_ENABLED;

package/dist/errors.d.ts

@@ -17,6 +17,12 @@ export declare class CursorProviderError extends Error {
     readonly origin: CursorErrorOrigin;
     readonly transient: boolean;
     replaySafe: boolean;
+    /**
+     * The Run failed because Cursor could not restore the resumed checkpoint
+     * (it requested blobs this client does not hold) before producing anything.
+     * Recovery must reseed a new conversation instead of resuming that checkpoint.
+     */
+    checkpointUnusable?: boolean;
     readonly statusCode?: number;
     readonly grpcStatus?: number | string;
     readonly rstCode?: number;
@@ -41,8 +47,15 @@ export declare class CursorProtocolError extends CursorProviderError {
 export declare class CursorAuthError extends CursorProviderError {
     constructor(message?: string, options?: Partial<CursorErrorDiagnostics> & {
         cause?: unknown;
+        replaySafe?: boolean;
     });
 }
+/**
+ * Cursor refused the request's credential (HTTP 401 / gRPC unauthenticated),
+ * as opposed to refusing the account an action (403 / permission_denied).
+ * Only this case is worth one renewed-token retry.
+ */
+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

package/dist/errors.js

@@ -3,6 +3,12 @@ export class CursorProviderError extends Error {
     origin;
     transient;
     replaySafe;
+    /**
+     * The Run failed because Cursor could not restore the resumed checkpoint
+     * (it requested blobs this client does not hold) before producing anything.
+     * Recovery must reseed a new conversation instead of resuming that checkpoint.
+     */
+    checkpointUnusable;
     statusCode;
     grpcStatus;
     rstCode;
@@ -64,11 +70,27 @@ export class CursorAuthError extends CursorProviderError {
             ...options,
             origin: "auth",
             transient: false,
-            replaySafe: false,
+            replaySafe: options.replaySafe ?? false,
         });
         this.name = "CursorAuthError";
     }
 }
+function isUnauthenticatedStatus(status) {
+    if (status === undefined)
+        return false;
+    const normalized = String(status).toLowerCase().replaceAll("-", "_");
+    return normalized === "16" || normalized === "unauthenticated";
+}
+/**
+ * Cursor refused the request's credential (HTTP 401 / gRPC unauthenticated),
+ * as opposed to refusing the account an action (403 / permission_denied).
+ * Only this case is worth one renewed-token retry.
+ */
+export function isRejectedCredentialError(error) {
+    return error instanceof CursorAuthError && (error.statusCode === 401 ||
+        isUnauthenticatedStatus(error.grpcStatus) ||
+        isUnauthenticatedStatus(error.code));
+}
 /**
  * OpenCode's SessionRetry treats several substrings in provider error messages
  * as always-retryable — notably bare "unavailable" and "exhausted", plus a
@@ -141,7 +163,9 @@ export function isAuthGrpcStatus(status) {
 }
 export function cursorHttpError(operation, statusCode, diagnostics = {}) {
     if (statusCode === 401 || statusCode === 403) {
-        return new CursorAuthError(`Cursor authentication failed (HTTP ${statusCode}); reauthenticate with Cursor`, { ...diagnostics, statusCode });
+        // A rejected credential means the server did no work: replaying with a
+        // renewed token is safe unless the attempt already crossed a barrier.
+        return new CursorAuthError(`Cursor authentication failed (HTTP ${statusCode}); reauthenticate with Cursor`, { ...diagnostics, statusCode, replaySafe: statusCode === 401 });
     }
     return new CursorServerError(`${operation} HTTP ${statusCode}`, {
         ...diagnostics,
@@ -152,7 +176,7 @@ export function cursorHttpError(operation, statusCode, diagnostics = {}) {
 }
 export function cursorGrpcError(operation, grpcStatus, diagnostics = {}) {
     if (isAuthGrpcStatus(grpcStatus)) {
-        return new CursorAuthError(`Cursor authentication failed (gRPC ${grpcStatus}); reauthenticate with Cursor`, { ...diagnostics, grpcStatus });
+        return new CursorAuthError(`Cursor authentication failed (gRPC ${grpcStatus}); reauthenticate with Cursor`, { ...diagnostics, grpcStatus, replaySafe: isUnauthenticatedStatus(grpcStatus) });
     }
     return new CursorServerError(`${operation} gRPC status ${grpcStatus}`, {
         ...diagnostics,

package/dist/host-agent-mode.d.ts

@@ -4,19 +4,68 @@
  * The language model stays host-neutral: it records a canonical Cursor mode
  * (`plan`, `spec`, `agent`, ...). A host entrypoint may install this structural
  * callback when its public API can select the corresponding primary agent.
- * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents;
- * OpenCode 1.x continues to use advertised `plan_enter` / `plan_exit` tools.
+ * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents
+ * and continues the turn via `session.synthetic` (OpenCode 2 `switchAgent`
+ * only publishes the agent and would otherwise idle).
+ * On OpenCode 1.x hosts, advertised `plan_enter` / `plan_exit` tools stay
+ * authoritative; without `plan_enter`, the classic entrypoint selects the
+ * `plan` agent the 1.x way, with a synthetic user message for that agent.
  */
 export type HostAgentModeSwitchInput = {
     sessionID: string;
     targetModeID: string;
     /** Concrete Cursor Run that owns the switch. */
     cursorSessionID?: string;
+    /** Host primary agent the owning Run executed under, when the host reported it. */
+    hostAgent?: string;
 };
 export type HostAgentModeSwitchFn = (input: HostAgentModeSwitchInput) => void | Promise<void>;
-export declare function setHostAgentModeSwitch(fn: HostAgentModeSwitchFn | undefined): void;
-/** Queue only when this host installed a native primary-agent switch. */
+export type HostAgentModeSwitchOptions = {
+    /** The switch also starts the host turn that continues the conversation. */
+    resumesTurn?: boolean;
+    /** Queue-time filter: a request the switch would not apply stays provider-owned. */
+    accepts?: (input: HostAgentModeSwitchInput) => boolean;
+};
+/** Synthetic user text that carries an OpenCode 1.x primary-agent switch. */
+export declare function hostAgentSwitchPromptText(agent: "plan" | "build"): string;
+/**
+ * OpenCode 1.x shape of the switch: a 1.x session runs each turn under the
+ * agent of its latest user message, which is how the host's own plan_enter /
+ * plan_exit change agents.
+ *
+ * It accepts only a real transition of a session running one of the host's
+ * own primary agents: entering an existing `plan` agent from another primary
+ * agent, or leaving the observed `plan` agent. Subagent and hidden internal
+ * sessions (title, summary, compaction, task children) never get a user turn
+ * injected.
+ */
+export declare function createPromptHostAgentModeSwitch(prompt: (input: {
+    sessionID: string;
+    agent: "plan" | "build";
+    text: string;
+}) => Promise<unknown>, primaryAgents: () => ReadonlySet<string> | undefined): {
+    apply: HostAgentModeSwitchFn;
+    accepts: (input: HostAgentModeSwitchInput) => boolean;
+};
+/**
+ * Install this host's native switch; it is used until a newer one is
+ * installed. The returned disposer removes only this switch, so disposing an
+ * older setup never removes a newer setup's switch. `undefined` removes all.
+ */
+export declare function setHostAgentModeSwitch(fn: HostAgentModeSwitchFn | undefined, options?: HostAgentModeSwitchOptions): () => void;
+/**
+ * How this host applies a Cursor mode switch to its primary agents: `resumes`
+ * when the switch also starts the next host turn, `next-turn` when the user's
+ * next message runs under the new agent, undefined without a native switch.
+ */
+export declare function hostAgentModeSwitchKind(): "resumes" | "next-turn" | undefined;
+/** Queue only when this host installed a native primary-agent switch that accepts the request. */
 export declare function queueHostAgentModeSwitch(input: HostAgentModeSwitchInput): boolean;
+/**
+ * True while an approved switch into the host `plan` agent waits for its Run to
+ * end and will itself start the plan-agent turn that continues the work.
+ */
+export declare function isHostPlanEntryPending(sessionID: string | undefined): boolean;
 export declare function cancelHostAgentModeSwitch(sessionID: string | undefined): void;
 /**
  * Apply the switch only after its Cursor Run is terminal and owns no pending