cursor-opencode-provider 0.8.1 → 0.8.3

package/dist/context/env.js

@@ -1,7 +1,21 @@
+import { statSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { trace } from "../debug.js";
 import { ensureOpencodeProjectDir } from "./paths.js";
+import { maintainRuntimeFiles, runtimeLayout } from "../runtime-files.js";
+function agentTranscriptsFolder(workspaceRoot) {
+    const configured = process.env.CURSOR_AGENT_TRANSCRIPTS_FOLDER;
+    if (!configured?.trim())
+        return undefined;
+    const folder = path.resolve(workspaceRoot, configured);
+    try {
+        return statSync(folder).isDirectory() ? folder : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function buildEnv(workspaceRoot) {
     const cwd = path.resolve(workspaceRoot);
     let timeZone = "UTC";
@@ -20,6 +34,16 @@ export function buildEnv(workspaceRoot) {
     // Cursor's project_folder is a metadata root (agent-tools, terminals, …),
     // not the git workspace. Keep dumps under OpenCode cache.
     const projectFolder = ensureOpencodeProjectDir(cwd);
+    let terminalsFolder;
+    try {
+        const layout = runtimeLayout(projectFolder, true);
+        terminalsFolder = layout.terminals;
+        maintainRuntimeFiles(layout);
+    }
+    catch (error) {
+        trace(`runtime folders unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const transcriptsFolder = agentTranscriptsFolder(cwd);
     // process_working_directory must match the workspace, not the host process
     // cwd. OpenCode 2.0's daemon is long-lived and often started from $HOME, so
     // process.cwd() would advertise the home folder to Cursor and the model would
@@ -32,15 +56,15 @@ export function buildEnv(workspaceRoot) {
         sandbox_supported: false,
         time_zone: timeZone,
         project_folder: projectFolder,
-        terminals_folder: path.join(projectFolder, "terminals"),
-        agent_transcripts_folder: path.join(projectFolder, "agent-transcripts"),
+        ...(terminalsFolder ? { terminals_folder: terminalsFolder } : {}),
+        ...(transcriptsFolder ? { agent_transcripts_folder: transcriptsFolder } : {}),
         process_working_directory: cwd,
         is_working_dir_home_dir: cwd === path.resolve(home),
     };
     trace(`buildEnv: workspace_paths=${JSON.stringify(env.workspace_paths)} ` +
         `project_folder=${env.project_folder} ` +
         `terminals_folder=${env.terminals_folder} ` +
-        `agent_transcripts_folder=${env.agent_transcripts_folder} ` +
+        `agent_transcripts_folder=${env.agent_transcripts_folder ?? "(none)"} ` +
         `process_working_directory=${env.process_working_directory}`);
     return env;
 }

package/dist/context/epoch.js

@@ -153,10 +153,13 @@ export function admitContextEpoch(input) {
         workspaceRoot: nextSnap.workspaceRoot || existing.snapshot.workspaceRoot,
     };
     const updates = renderSourceUpdates(existing.snapshot, observedSnap, input);
-    const changed = existing.snapshot.hostSystemHash !== observedSnap.hostSystemHash
-        || existing.snapshot.guidanceHash !== observedSnap.guidanceHash
-        || existing.snapshot.hostAgent !== observedSnap.hostAgent
-        || existing.snapshot.workspaceRoot !== observedSnap.workspaceRoot;
+    const changedSources = [
+        existing.snapshot.hostSystemHash !== observedSnap.hostSystemHash ? "hostSystem" : "",
+        existing.snapshot.guidanceHash !== observedSnap.guidanceHash ? "guidance" : "",
+        existing.snapshot.hostAgent !== observedSnap.hostAgent ? "hostAgent" : "",
+        existing.snapshot.workspaceRoot !== observedSnap.workspaceRoot ? "workspaceRoot" : "",
+    ].filter(Boolean);
+    const changed = changedSources.length > 0;
     if (changed) {
         existing.snapshot = observedSnap;
     }
@@ -165,7 +168,8 @@ export function admitContextEpoch(input) {
         const midConversationMessage = combineMessages([...updates, ...oneShots]);
         if (changed || oneShots.length) {
             trace(`context epoch: ${changed ? "updated" : "unchanged"} conversationId=${conversationId} ` +
-                `checkpoint=1 updates=${updates.length} oneShots=${oneShots.length}`);
+                `checkpoint=1 updates=${updates.length} oneShots=${oneShots.length}` +
+                (changedSources.length ? ` changed=[${changedSources.join(",")}]` : ""));
         }
         return {
             action: changed ? "updated" : "unchanged",

package/dist/context/git.d.ts

@@ -14,7 +14,10 @@ export type GitRepoInfo = {
     branch_name: string;
     remote_url?: string;
 };
-export declare function collectGit(workspaceRoot: string): Promise<{
+export type GitFacts = {
     repositoryInfo: RepoInfo[];
     gitRepos: GitRepoInfo[];
-}>;
+    /** False when `git status` failed or timed out, so the status is not the real one. */
+    statusComplete: boolean;
+};
+export declare function collectGit(workspaceRoot: string): Promise<GitFacts>;

package/dist/context/git.js

@@ -1,21 +1,29 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import path from "node:path";
+import { errorMessage, trace } from "../debug.js";
 const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT_MS = 5_000;
+/** Trimmed stdout, or `undefined` when git failed or timed out. */
 async function git(cwd, args) {
+    const started = Date.now();
     try {
-        const { stdout } = await execFileAsync("git", args, { cwd, encoding: "utf-8", timeout: 5000 });
+        const { stdout } = await execFileAsync("git", args, { cwd, encoding: "utf-8", timeout: GIT_TIMEOUT_MS });
         return stdout.trim();
     }
-    catch {
-        return "";
+    catch (error) {
+        const killed = error.killed === true;
+        trace(`git: \`${args.join(" ")}\` ${killed ? `timed out after ${GIT_TIMEOUT_MS}ms` : "failed"} ` +
+            `elapsedMs=${Date.now() - started}${killed ? "" : `: ${errorMessage(error).split("\n")[0]}`}`);
+        return undefined;
     }
 }
 export async function collectGit(workspaceRoot) {
+    const started = Date.now();
     const root = await git(workspaceRoot, ["rev-parse", "--show-toplevel"]);
     if (!root)
-        return { repositoryInfo: [], gitRepos: [] };
-    const remotesRaw = await git(root, ["remote", "-v"]);
+        return { repositoryInfo: [], gitRepos: [], statusComplete: true };
+    const remotesRaw = (await git(root, ["remote", "-v"])) ?? "";
     const remote_urls = [];
     const remote_names = [];
     for (const line of remotesRaw.split("\n")) {
@@ -34,7 +42,9 @@ export async function collectGit(workspaceRoot) {
         repo_name = gh[2];
     }
     const branch = (await git(root, ["rev-parse", "--abbrev-ref", "HEAD"])) || "HEAD";
+    const statusStarted = Date.now();
     const status = await git(root, ["status", "--porcelain", "-b"]);
+    trace(`git: discovery elapsedMs=${Date.now() - started} statusMs=${Date.now() - statusStarted} statusComplete=${status !== undefined}`);
     const repositoryInfo = [
         {
             relative_workspace_path: ".",
@@ -50,10 +60,10 @@ export async function collectGit(workspaceRoot) {
     const gitRepos = [
         {
             path: root,
-            status: status.slice(0, 4000),
+            status: (status ?? "").slice(0, 4000),
             branch_name: branch,
             ...(primary ? { remote_url: primary } : {}),
         },
     ];
-    return { repositoryInfo, gitRepos };
+    return { repositoryInfo, gitRepos, statusComplete: status !== undefined };
 }

package/dist/context/paths.d.ts

@@ -97,7 +97,7 @@ export declare function slugifyWorkspacePath(workspaceRoot: string): string;
  * Lives at `<host-cache>/projects/<slug>/` under the resolved OpenCode/host cache root.
  *
  * This is what Cursor's RequestContextEnv.project_folder / MCP
- * workspace_project_dir point at — agent-tools, terminals, transcripts, etc.
+ * workspace_project_dir point at — agent-tools, terminals, assets, etc.
  * Must NOT be the git workspace, or those dumps land in the repo.
  */
 export declare function opencodeProjectDir(workspaceRoot: string): string;

package/dist/context/paths.js

@@ -188,17 +188,20 @@ export function slugifyWorkspacePath(workspaceRoot) {
  * Lives at `<host-cache>/projects/<slug>/` under the resolved OpenCode/host cache root.
  *
  * This is what Cursor's RequestContextEnv.project_folder / MCP
- * workspace_project_dir point at — agent-tools, terminals, transcripts, etc.
+ * workspace_project_dir point at — agent-tools, terminals, assets, etc.
  * Must NOT be the git workspace, or those dumps land in the repo.
  */
 export function opencodeProjectDir(workspaceRoot) {
     const projectsRoot = path.join(opencodeGlobalCacheDir(), "projects");
     const slug = slugifyWorkspacePath(workspaceRoot);
-    let dir = path.join(projectsRoot, slug);
-    // Mirror Cursor's long-path guard so nested agent-tools paths stay usable.
+    const dir = path.join(projectsRoot, slug);
+    // Keep nested agent-tools paths short by cutting the name to 84 characters.
+    // While that cut falls after `projects/`, it only shortens the slug, and it
+    // is the name existing folders already have. With a longer root it would
+    // fall inside the root, so the folder is named by the hash alone.
     if (dir.length > 92) {
         const hash = createHash("sha256").update(dir).digest("hex").slice(0, 7);
-        dir = `${dir.slice(0, Math.min(84, dir.length))}-${hash}`;
+        return projectsRoot.length < 84 ? `${dir.slice(0, 84)}-${hash}` : path.join(projectsRoot, hash);
     }
     return dir;
 }

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;