cursor-opencode-provider 0.2.5 → 0.2.7

package/README.md

@@ -47,7 +47,7 @@ Add the package name to OpenCode config. OpenCode installs npm plugins with Bun
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.2.5"`.
+Pin a version if you want: `"cursor-opencode-provider@0.2.6"`.
 
 ### From a local clone
 
@@ -102,15 +102,23 @@ Choose the **cursor** provider, then one of:
 | **Cursor account (browser login)** | PKCE OAuth — opens cursor.com to sign in |
 | **API key** | Paste a key from [cursor.com/settings](https://cursor.com/settings) (`sk-...`) |
 
-After login, the plugin fetches your available models and writes them to `~/.cache/opencode/cursor-models.json` (or `$XDG_CACHE_HOME/opencode/` when set). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails.
+After login, the plugin fetches your available models and writes them to `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails.
 
-### Paths (XDG)
+### Paths (host cache)
 
-| Kind | Default | Override |
-|------|---------|----------|
-| Model / version **cache** | `~/.cache/opencode/` | `$XDG_CACHE_HOME/opencode/` |
-| OpenCode **auth** (`auth.json`) | `~/.local/share/opencode/` | `$XDG_DATA_HOME/opencode/` |
-| OpenCode **config** (AGENTS, skills, …) | `~/.config/opencode/` | (config dir helper; not the model cache) |
+Model/version caches and Cursor project metadata live under a **host cache root**, resolved in this order:
+
+1. Explicit `createCursor({ cacheDir })` / Effect v2 `Path.cache`
+2. Optional `@opencode-compat/profile` `detect()` when that peer is installed and the host is supported
+3. Local heuristic: `$MIMOCODE_HOME/cache`, then host-named dirs under `$XDG_CACHE_HOME` (Kilo, then MiMo, then OpenCode)
+4. Default `~/.cache/opencode/`
+
+| Kind | Default (OpenCode) | Notes |
+|------|--------------------|-------|
+| Model / version **cache** | `~/.cache/opencode/` | MiMo: `$MIMOCODE_HOME/cache` or `~/.cache/mimocode/`; Kilo: `~/.cache/kilo/` |
+| Cursor **project metadata** (`agent-tools`, terminals, …) | `~/.cache/opencode/projects/<slug>/` | under `<host-cache>/projects/` |
+| OpenCode **auth** (`auth.json`) | `~/.local/share/opencode/` | `$XDG_DATA_HOME/opencode/` when set |
+| OpenCode **config** (AGENTS, skills, …) | `~/.config/opencode/` | still OpenCode-named for rule discovery |
 
 ### Select a model
 
@@ -157,6 +165,7 @@ const cursor = createCursor({
   // apiBaseURL: "https://api2.cursor.sh",
   // agentBaseURL: "https://agentn.us.api5.cursor.sh", // explicit Run host override
   // telemetryEnabled: true, // opt in to GetServerConfig telemetry
+  // cacheDir: "/path/to/host/cache", // optional; else host heuristic / ~/.cache/opencode
   // retry: { maxAttempts: 3, baseDelayMs: 500, maxDelayMs: 8_000 },
   // continuation: { heartbeatMs: 5_000, semanticIdleMs: 120_000, hardCapMs: 600_000 },
 })
@@ -165,7 +174,7 @@ const model = cursor.languageModel("composer-2.5")
 // model implements AI SDK LanguageModelV3 (doStream / doGenerate)
 ```
 
-Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. Retries occur only before visible output or stateful server activity; unsafe replay is surfaced instead of risking duplicate text or tool work. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
+Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `cacheDir`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. `cacheDir` pins the host cache root for model/version caches and Cursor project metadata; when omitted, the provider uses OCP `@opencode-compat/profile` detect (if installed) or the local MiMo/Kilo/OpenCode heuristic described in [Paths](#paths-host-cache). Transient failures resume from the latest checkpoint produced by that Run, matching Cursor CLI; without an eligible checkpoint, retries remain limited to replay-safe attempts so completed text or tool work is not duplicated. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
 
 ## Environment variables
 
@@ -176,7 +185,9 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-
 | `CURSOR_GET_SERVER_CONFIG_TELEMETRY` | Set to `1` or `true` to opt the `GetServerConfig` lookup into telemetry in OpenCode/plugin usage |
 | `CURSOR_PROVIDER_DEBUG` | Set to `1` or `true` to enable wire-level debug logging |
 | `CURSOR_PROVIDER_DEBUG_FILE` | Debug log path (default: `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) |
-| `XDG_CACHE_HOME` | When set, model/version caches go under `$XDG_CACHE_HOME/opencode/` instead of `~/.cache/opencode/` |
+| `XDG_CACHE_HOME` | Base for host cache dirs (`$XDG_CACHE_HOME/opencode/`, `…/mimocode/`, or `…/kilo/`) when no explicit `cacheDir` / OCP detect override |
+| `MIMOCODE_HOME` | When set, host cache is `$MIMOCODE_HOME/cache` (MiMo) |
+| `KILO_CONFIG_DIR` | When set (or `~/.config/kilo` exists), host cache is `$XDG_CACHE_HOME/kilo` |
 | `XDG_DATA_HOME` | When set, OpenCode `auth.json` is read from `$XDG_DATA_HOME/opencode/` instead of `~/.local/share/opencode/` |
 
 `createCursor({ agentBaseURL })` overrides the agent Run host. When unset, the provider resolves the host from Cursor's `GetServerConfig` API (`agentUrlConfig.agentnUrl`, region-specific — e.g. `agentn.us.api5.cursor.sh`, `agent-gcpp-uswest.api5.cursor.sh`) once per process and holds it in memory (never written to disk), so a held-open Run stream is never repointed mid-session. Explicit agent overrides and GetServerConfig results are validated as HTTPS `*.cursor.sh` hosts (Cursor's agent hostnames vary and may change); non-`cursor.sh` hosts are rejected. Shared HTTP/2 connections are rotated before they become server-aged, while existing Runs may finish on their original connection. The lookup sends `{ "telem_enabled": false }` by default; set `telemetryEnabled: true` in provider config, or `CURSOR_GET_SERVER_CONFIG_TELEMETRY=1` for OpenCode/plugin usage, to opt in. If the lookup fails or does not return a valid Cursor agent host, the model call fails clearly instead of falling back to `agentn.global.api5.cursor.sh`.
@@ -213,6 +224,7 @@ OpenCode
 | `src/debug.ts` | Opt-in wire-level debug logging (`CURSOR_PROVIDER_DEBUG`) |
 | `src/auth.ts` | PKCE OAuth, API key exchange, JWT refresh |
 | `src/models.ts` | `AvailableModels` fetch and `cursor-models.json` cache |
+| `src/context/paths.ts` | Host cache root + Cursor project metadata under `<host-cache>/projects/<slug>/` |
 | `src/agent-url.ts` | `GetServerConfig` fetch + in-process memo (region-specific Run host) |
 | `src/transport/connect.ts` | HTTP/2 bidi stream and unary RPC calls |
 | `src/protocol/` | Protobuf encode/decode, checksum/device ids, exec + display tool-call mapping (`tool-call-bridge.ts`) |
@@ -241,8 +253,8 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | No Cursor models in the picker | Confirm Cursor auth (`opencode auth login` → **cursor**). Restart OpenCode — if auth is present and the cache is empty, models are fetched on startup. Confirm `provider.cursor.npm` is the package name (or a built `file://…/dist/index.js`). |
 | Auth / 401 errors mid-session | Re-login. OAuth and exchanged API-key JWTs refresh automatically when near expiry; a revoked refresh token needs a fresh login. |
 | “Too many connections from different devices” | Device IDs are derived from stable OS identifiers (same approach as the Cursor CLI). Avoid running multiple clients that invent different machine fingerprints for the same account. |
-| Empty or stale model list | Delete `~/.cache/opencode/cursor-models.json` (or under `$XDG_CACHE_HOME/opencode/`) and restart OpenCode. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
-| Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, and transparently rebases once from full OpenCode history if the Run ends before `turn_ended`. Repeated interruption is surfaced as an error instead of a false successful stop; retry the turn after checking connectivity. With debug logging enabled, look for `Run interrupted` and `rebasing fresh Run`. Restart OpenCode after rebuilding a local `file://` install. |
+| Empty or stale model list | Delete `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`, or MiMo/Kilo host cache) and restart OpenCode. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
+| Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, resumes transient interruptions from the latest eligible Cursor checkpoint, and falls back to a fresh-history rebase only before stateful output when no checkpoint exists. Repeated interruption is surfaced as an error instead of a false successful stop; retry the turn after checking connectivity. With debug logging enabled, look for `Run interrupted`, `resuming … checkpoint`, or `rebasing fresh Run`. Restart OpenCode after rebuilding a local `file://` install. |
 | No response / silent 200 + close | HTTP 200 alone is not a successful agent turn: the provider now requires Cursor's explicit `turn_ended`, captures HTTP/2 trailers/GOAWAY, and recovers once from bare EOF. The Run host still comes from in-memory `GetServerConfig` resolution; set `CURSOR_PROVIDER_DEBUG=1` to confirm the host and termination reason. |
 | Visible `<shell_metadata>` timeout text | Rebuild and restart a local install. Cursor's shell timeout is carried on its exec request; the provider now removes OpenCode's internal timeout envelope before it is rendered or stored, then returns Cursor's typed timeout or background-handoff event instead of treating the text as successful stdout. |
 | `Unsupported Cursor exec variant …` | The error names the canonical Cursor CLI request field, its expected result field, and this provider's handling classification. `handling=unsupported` is a known Cursor-native capability without a safe OpenCode AI SDK bridge; `unknown request field` indicates new protocol drift; `handling=opencode-tool` or `provider-control` indicates a provider decoder/dispatch regression. Enable the debug log and report the full named error. |
@@ -255,15 +267,15 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 ## Known limitations
 
 - **Personal use / ToS** — this provider speaks Cursor’s private agent protocol (CLI-shaped client identity). Use only with an account you own; Cursor may change or restrict the API without notice.
-- **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
+- **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. `env.workspace_paths` / `process_working_directory` stay on the real git workspace; Cursor's metadata root (`project_folder`, MCP `workspace_project_dir`, terminals/transcripts) is advertised under `<host-cache>/projects/<slug>/` (default `~/.cache/opencode/projects/…`) so dumps like `agent-tools/` do not land in the repo. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
 - **Configured MCP tools keep their upstream server id** — OpenCode builtins and plugin/custom tools are advertised under a synthetic `opencode` MCP server. Tools whose flattened name matches an MCP server in merged `opencode.json` configuration (`github_create_pull_request`, …) are grouped into that server's `mcp_descriptors` / `provider_identifier` (`github`, …). Unknown underscore-containing names stay under `opencode` rather than being guessed incorrectly. Cursor's MCP-state exec probe is answered from the same advertised descriptors before the actual tool request, using the full canonical tool-definition identity required by native `get_mcp_tools`; exec still reconstructs the full OpenCode tool id.
 - **Display completions are notifications, not execution requests** — Cursor `tool_call_*` frames use a typed `ToolCall` oneof. The provider decodes them for diagnostics but only mirrors finalized todo/plan state (`update_todos_tool_call` / `create_plan_tool_call`) into advertised OpenCode `todowrite`; the completed payload already contains the authoritative final list. Interactive, data-returning, and side-effecting completions are never replayed as new tools because their result could not be returned to Cursor. Exec-backed native subagent/Task and Pi read/bash/edit/write/grep/find/ls calls use their typed request/result fields instead. Unknown display variants are logged. All 37 Cursor CLI exec request/result pairs are inventoried by field and name; known-but-unsupported and future unknown exec variants fail explicitly rather than receiving a guessed response that could deadlock the Run.
 - **Tool availability is per OpenCode agent** — Cursor can request native capabilities such as Task even when a child or restricted OpenCode agent did not advertise the corresponding host tool. The provider prompts Cursor with the exact current catalog and checks every decoded host-tool exec request against it. An unavailable request is answered on Cursor's correlated typed result channel and is never emitted as OpenCode's `invalid` tool.
-- **Background shells are non-interactive** — Cursor's native background-shell spawn is bridged through OpenCode's foreground-only `bash` tool by detaching the requested command, redirecting its output to `${TMPDIR:-/tmp}/cursor-opencode-bg.*`, and returning the real PID in Cursor's typed field-16 result. Shell-stream requests also preserve Cursor's foreground timeout, `timeout_behavior`, and `hard_timeout`: cancellation becomes a typed aborted exit, while a soft timeout requested with background behavior becomes a typed background handoff. OpenCode's internal `<shell_metadata>` envelope and the bridge's private markers are stripped before the result reaches the UI. Requests that require `write_shell_stdin` are rejected explicitly because OpenCode does not expose an interactive background-process lifecycle through its AI SDK tool interface.
+- **Background shells are non-interactive** — Cursor's native background-shell spawn and soft-background shell-stream timeouts are bridged through OpenCode's foreground-only `bash` tool. With bash/zsh, the classic plugin keeps the original permission/UI command and executes the wrapper through `shell.env` (`BASH_ENV` / `ZDOTDIR`); OpenCode's non-interactive sh/dash argv ignores those startup variables, so the plugin uses a short `exec /bin/sh '<wrapper-file>'` command backed by the same private wrapper. Native background-spawn requests also carry a self-contained marker-producing fallback when the classic hooks are absent. Spawn/soft-bg wrappers detach with `nohup`, redirect output under `${TMPDIR:-/tmp}/cursor-opencode-{bg,shell}.*`, and return the real PID (or typed timeout/exit) to Cursor. Private markers and OpenCode's `<shell_metadata>` envelope are stripped before storage/render, with a short still-running / started / timed-out status line left for the bash bubble. Requests that require `write_shell_stdin` are rejected explicitly because OpenCode does not expose an interactive background-process lifecycle through its AI SDK tool interface. The POSIX wrap path is not implemented for native Windows PowerShell/`cmd`.
 - **Cursor-native interaction queries remain headless** — Cursor UI/approval *queries* (as distinct from display tool calls) still cannot be surfaced through the AI SDK provider interface. The normal system prompt redirects questions, planning, plan-mode transitions, and known-URL fetching to equivalent OpenCode tools only when they are advertised (`question`, `todowrite`, `plan_enter` / `plan_exit`, `webfetch`); native web/PR/MCP/image/SCM requests are declined so they remain behind OpenCode's tools and permissions. Separately from display `create_plan_tool_call` → `todowrite` mirroring, interaction `create_plan_request_query` is auto-acked (CLI headless parity) with success and an empty `plan_uri`, so Cursor may treat the plan as accepted without an OpenCode UI confirm. Compaction prompts are unchanged. Unknown future interaction variants fail the turn explicitly instead of hanging the Run stream.
 - **Compaction resets Cursor conversation state** — the classic plugin marks OpenCode's `compaction` agent explicitly. On those turns the provider mints an isolated Cursor `conversation_id`, drops the prior checkpoint + KV blobs, preserves real tool outputs as OpenCode-host observations in the seed history, and re-advertises the session's last tool catalog while refusing execution during the summary itself. The first normal turn then rebases once more onto a fresh conversation seeded with OpenCode's compacted prompt and normal system instructions, so the summary-agent checkpoint cannot suppress later tool calls. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state.
 - **Conversation bindings and compaction catalogs are bounded** — process-global per-session bindings, prior tool catalogs, and pending post-compaction rebases use a 256-session LRU bound. Evicting a conversation binding also drops its checkpoint and KV blobs.
-- **Interrupted Runs rebase once** — a remote EOF, Connect end-stream, trailer error, failed continuation write, or closed pending-tool session is never emitted as a successful `stop`. The provider starts one fresh Cursor conversation seeded from the OpenCode prompt, retaining the live user request and trailing tool results as host observations without replaying stale historical tool output, re-advertises the same tools, and preserves compaction's no-execution behavior. A second interruption is returned as an explicit error. Recovery cannot see tokens already streamed to the UI on the interrupted attempt, so mid-generation recovery may briefly duplicate visible text/reasoning even though the rebase prompt asks the model not to repeat completed work.
+- **Interrupted Runs resume from checkpoints** — a remote EOF, Connect end-stream, or trailer error is never emitted as a successful `stop`. When the failed Run produced an eligible checkpoint, the provider opens a new RPC for the same conversation and sends that state with `ResumeAction`, so completed text and tool work are not replayed. Before any stateful output, an interruption without a checkpoint can still rebase from OpenCode history. Stateful interruptions without a checkpoint are surfaced because replay would be ambiguous; retry exhaustion remains explicit. A transport closure after `turn_ended` is treated as successful completion.
 - **No fallback models** — if Cursor’s `AvailableModels` API is unreachable and there is no local cache, the provider exposes no models.
 
 ## License

package/dist/context/build.js

@@ -7,6 +7,8 @@ import { collectPlugins } from "./plugins.js";
 import { collectGit } from "./git.js";
 import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
+import { ensureOpencodeProjectDir } from "./paths.js";
+import { traceRequestContextPaths } from "../debug.js";
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Sourced from OpenCode discovery (and .claude/.agents skill fallbacks).
@@ -27,6 +29,7 @@ export async function buildRequestContext(input) {
     const mcpServerNames = Object.keys(config.mcp ?? {});
     const flat = toolsToDescriptors(tools, providerIdentifier, mcpServerNames);
     const nested = toolsToMcpDescriptors(tools, providerIdentifier, mcpServerNames);
+    const projectDir = ensureOpencodeProjectDir(workspaceRoot);
     const ctx = {
         env: buildEnv(workspaceRoot),
         tools: flat,
@@ -50,7 +53,8 @@ export async function buildRequestContext(input) {
         })),
         mcp_file_system_options: {
             enabled: true,
-            workspace_project_dir: workspaceRoot,
+            // Cursor metadata root (mcps / agent-tools), not the git workspace.
+            workspace_project_dir: projectDir,
             mcp_descriptors: nested,
         },
         mcp_meta_tool_options: {
@@ -73,5 +77,6 @@ export async function buildRequestContext(input) {
             .map((p) => `opencode-plugin:${p.source}:${p.id}`)
             .join("\n");
     }
+    traceRequestContextPaths("buildRequestContext", ctx);
     return ctx;
 }

package/dist/context/env.d.ts

@@ -1 +1,7 @@
 export declare function buildEnv(workspaceRoot: string): Record<string, unknown>;
+/**
+ * Real workspace root for path resolution (edits, reads, …).
+ * Uses `env.workspace_paths[0]` — never `project_folder` /
+ * `mcp_file_system_options.workspace_project_dir` (those are Cursor metadata roots).
+ */
+export declare function workspaceRootFromRequestContext(requestContext: Record<string, unknown> | undefined): string;

package/dist/context/env.js

@@ -1,5 +1,7 @@
 import { homedir } from "node:os";
 import path from "node:path";
+import { trace } from "../debug.js";
+import { ensureOpencodeProjectDir } from "./paths.js";
 export function buildEnv(workspaceRoot) {
     const cwd = path.resolve(workspaceRoot);
     let timeZone = "UTC";
@@ -15,15 +17,45 @@ export function buildEnv(workspaceRoot) {
         const r = process.release?.version;
         return r ? `${p} ${r}` : p;
     })();
-    return {
+    // Cursor's project_folder is a metadata root (agent-tools, terminals, …),
+    // not the git workspace. Keep dumps under OpenCode cache.
+    const projectFolder = ensureOpencodeProjectDir(cwd);
+    const env = {
         os_version: osVersion,
         workspace_paths: [cwd],
         shell: process.env.SHELL || "/bin/bash",
         sandbox_enabled: false,
         sandbox_supported: false,
         time_zone: timeZone,
-        project_folder: cwd,
+        project_folder: projectFolder,
+        terminals_folder: path.join(projectFolder, "terminals"),
+        agent_transcripts_folder: path.join(projectFolder, "agent-transcripts"),
         process_working_directory: process.cwd(),
         is_working_dir_home_dir: path.resolve(process.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} ` +
+        `process_working_directory=${env.process_working_directory}`);
+    return env;
+}
+/**
+ * Real workspace root for path resolution (edits, reads, …).
+ * Uses `env.workspace_paths[0]` — never `project_folder` /
+ * `mcp_file_system_options.workspace_project_dir` (those are Cursor metadata roots).
+ */
+export function workspaceRootFromRequestContext(requestContext) {
+    const env = requestContext?.env;
+    if (env && typeof env === "object") {
+        const paths = env.workspace_paths;
+        if (Array.isArray(paths) && typeof paths[0] === "string" && paths[0].trim()) {
+            const root = path.resolve(paths[0]);
+            trace(`workspaceRootFromRequestContext: using workspace_paths[0]=${root}`);
+            return root;
+        }
+    }
+    const fallback = process.cwd();
+    trace(`workspaceRootFromRequestContext: workspace_paths missing; fallback cwd=${fallback}`);
+    return fallback;
 }

package/dist/context/index.d.ts

@@ -1,2 +1,2 @@
 export { buildRequestContext, type BuildRequestContextInput } from "./build.js";
-export { opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir } from "./paths.js";
+export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/index.js

@@ -1,2 +1,2 @@
 export { buildRequestContext } from "./build.js";
-export { opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir } from "./paths.js";
+export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/paths.d.ts

@@ -1,8 +1,30 @@
-/** OpenCode global config dir (`~/.config/opencode`). */
+export type HostPathEnv = NodeJS.ProcessEnv;
+/**
+ * Pin the process-wide cache root. Highest precedence for {@link opencodeGlobalCacheDir}.
+ * Use for host-injected `Path.cache` or an explicit `createCursor({ cacheDir })`.
+ */
+export declare function setHostCacheDirOverride(dir: string | undefined): void;
+export declare function getHostCacheDirOverride(): string | undefined;
+/**
+ * Resolve the host cache directory without an override.
+ * Mirrors OCP HostProfile drafts: MiMo (`mimocode` / `$MIMOCODE_HOME`), Kilo (`kilo`),
+ * then OpenCode (`opencode`). Prefer fork config dirs when several exist.
+ */
+export declare function resolveHostCacheDir(env?: HostPathEnv): string;
+/**
+ * Best-effort: if `@opencode-compat/profile` is installed, adopt `detect().profile.paths.cacheDir`
+ * when the host is supported. No-op when OCP is absent or detection fails.
+ */
+export declare function adoptCompatHostCacheDir(): Promise<string | undefined>;
+/** OpenCode / host global config dir (`~/.config/<app>`). Still OpenCode-named for rule discovery. */
 export declare function opencodeGlobalConfigDir(): string;
 /**
- * OpenCode global cache dir (`~/.cache/opencode`).
- * Uses `$XDG_CACHE_HOME/opencode` when set, otherwise `$HOME/.cache/opencode`.
+ * Host global cache dir for Cursor project metadata + model/version caches.
+ *
+ * Precedence:
+ * 1. {@link setHostCacheDirOverride} / `createCursor({ cacheDir })` (host `Path.cache`)
+ * 2. OCP `detect()` when {@link adoptCompatHostCacheDir} ran successfully
+ * 3. Local host heuristic ({@link resolveHostCacheDir})
  */
 export declare function opencodeGlobalCacheDir(): string;
 /**
@@ -11,4 +33,20 @@ export declare function opencodeGlobalCacheDir(): string;
  * Auth credentials live here in `auth.json`.
  */
 export declare function opencodeGlobalDataDir(): string;
+/**
+ * Cursor-compatible path slug (`/Users/a/b` → `Users-a-b`).
+ * Used for per-workspace metadata under the host cache.
+ */
+export declare function slugifyWorkspacePath(workspaceRoot: string): string;
+/**
+ * Cursor-style project metadata root for a workspace.
+ * Lives at `<host-cache>/projects/<slug>/` (OpenCode / MiMo / Kilo cache root).
+ *
+ * This is what Cursor's RequestContextEnv.project_folder / MCP
+ * workspace_project_dir point at — agent-tools, terminals, transcripts, etc.
+ * Must NOT be the git workspace, or those dumps land in the repo.
+ */
+export declare function opencodeProjectDir(workspaceRoot: string): string;
+/** Ensure {@link opencodeProjectDir} exists (mode 0o700) and return it. */
+export declare function ensureOpencodeProjectDir(workspaceRoot: string): string;
 export declare function resolveHomeRelative(p: string): string;

package/dist/context/paths.js

@@ -1,21 +1,92 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-function resolveHome() {
-    return process.env.HOME || process.env.USERPROFILE || homedir();
+import { trace } from "../debug.js";
+/** Explicit host cache root (e.g. Effect v2 `Path.cache`, or `createCursor({ cacheDir })`). */
+let hostCacheDirOverride;
+function resolveHome(env = process.env) {
+    return env.HOME || env.USERPROFILE || homedir();
 }
-/** OpenCode global config dir (`~/.config/opencode`). */
+function xdgCacheHome(env = process.env) {
+    if (env.XDG_CACHE_HOME && env.XDG_CACHE_HOME.length > 0)
+        return env.XDG_CACHE_HOME;
+    return path.join(resolveHome(env), ".cache");
+}
+function xdgConfigHome(env = process.env) {
+    if (env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.length > 0)
+        return env.XDG_CONFIG_HOME;
+    return path.join(resolveHome(env), ".config");
+}
+/**
+ * Pin the process-wide cache root. Highest precedence for {@link opencodeGlobalCacheDir}.
+ * Use for host-injected `Path.cache` or an explicit `createCursor({ cacheDir })`.
+ */
+export function setHostCacheDirOverride(dir) {
+    hostCacheDirOverride = dir && dir.length > 0 ? path.resolve(dir) : undefined;
+}
+export function getHostCacheDirOverride() {
+    return hostCacheDirOverride;
+}
+/**
+ * Resolve the host cache directory without an override.
+ * Mirrors OCP HostProfile drafts: MiMo (`mimocode` / `$MIMOCODE_HOME`), Kilo (`kilo`),
+ * then OpenCode (`opencode`). Prefer fork config dirs when several exist.
+ */
+export function resolveHostCacheDir(env = process.env) {
+    const mimoHome = env.MIMOCODE_HOME;
+    if (mimoHome && mimoHome.length > 0) {
+        return path.join(mimoHome, "cache");
+    }
+    const configHome = xdgConfigHome(env);
+    const cacheHome = xdgCacheHome(env);
+    const kiloConfig = env.KILO_CONFIG_DIR;
+    // Prefer more specific fork dirs before OpenCode (same order as OCP detect).
+    if ((kiloConfig && kiloConfig.length > 0) || existsSync(path.join(configHome, "kilo"))) {
+        return path.join(cacheHome, "kilo");
+    }
+    if (existsSync(path.join(configHome, "mimocode"))) {
+        return path.join(cacheHome, "mimocode");
+    }
+    return path.join(cacheHome, "opencode");
+}
+/**
+ * Best-effort: if `@opencode-compat/profile` is installed, adopt `detect().profile.paths.cacheDir`
+ * when the host is supported. No-op when OCP is absent or detection fails.
+ */
+export async function adoptCompatHostCacheDir() {
+    try {
+        const { detect } = await import("@opencode-compat/profile");
+        const result = detect();
+        if (!result.supported || result.id === "unknown")
+            return undefined;
+        const cacheDir = result.profile.paths.cacheDir;
+        if (!cacheDir || cacheDir.length === 0)
+            return undefined;
+        setHostCacheDirOverride(cacheDir);
+        trace(`host-cache: adopted OCP detect cacheDir=${cacheDir} host=${result.id}`);
+        return cacheDir;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** OpenCode / host global config dir (`~/.config/<app>`). Still OpenCode-named for rule discovery. */
 export function opencodeGlobalConfigDir() {
     return path.join(resolveHome(), ".config", "opencode");
 }
 /**
- * OpenCode global cache dir (`~/.cache/opencode`).
- * Uses `$XDG_CACHE_HOME/opencode` when set, otherwise `$HOME/.cache/opencode`.
+ * Host global cache dir for Cursor project metadata + model/version caches.
+ *
+ * Precedence:
+ * 1. {@link setHostCacheDirOverride} / `createCursor({ cacheDir })` (host `Path.cache`)
+ * 2. OCP `detect()` when {@link adoptCompatHostCacheDir} ran successfully
+ * 3. Local host heuristic ({@link resolveHostCacheDir})
  */
 export function opencodeGlobalCacheDir() {
-    if (process.env.XDG_CACHE_HOME) {
-        return path.join(process.env.XDG_CACHE_HOME, "opencode");
-    }
-    return path.join(resolveHome(), ".cache", "opencode");
+    if (hostCacheDirOverride)
+        return hostCacheDirOverride;
+    return resolveHostCacheDir();
 }
 /**
  * OpenCode global data dir (`~/.local/share/opencode`).
@@ -28,6 +99,47 @@ export function opencodeGlobalDataDir() {
     }
     return path.join(resolveHome(), ".local", "share", "opencode");
 }
+/**
+ * Cursor-compatible path slug (`/Users/a/b` → `Users-a-b`).
+ * Used for per-workspace metadata under the host cache.
+ */
+export function slugifyWorkspacePath(workspaceRoot) {
+    const resolved = path.resolve(workspaceRoot);
+    return resolved
+        .replace(/[^a-zA-Z0-9]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Cursor-style project metadata root for a workspace.
+ * Lives at `<host-cache>/projects/<slug>/` (OpenCode / MiMo / Kilo cache root).
+ *
+ * This is what Cursor's RequestContextEnv.project_folder / MCP
+ * workspace_project_dir point at — agent-tools, terminals, transcripts, 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.
+    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 dir;
+}
+/** Ensure {@link opencodeProjectDir} exists (mode 0o700) and return it. */
+export function ensureOpencodeProjectDir(workspaceRoot) {
+    const resolved = path.resolve(workspaceRoot);
+    const dir = opencodeProjectDir(resolved);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    trace(`project-dir: workspace=${resolved} slug=${slugifyWorkspacePath(resolved)} ` +
+        `dir=${dir} cache_root=${opencodeGlobalCacheDir()} ` +
+        `override=${hostCacheDirOverride ?? "(none)"} ` +
+        `xdg_cache_home=${process.env.XDG_CACHE_HOME ?? "(unset)"}`);
+    return dir;
+}
 export function resolveHomeRelative(p) {
     if (p.startsWith("~/"))
         return path.join(homedir(), p.slice(2));

package/dist/debug.d.ts

@@ -1,3 +1,5 @@
+/** 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). */
 export declare function resolveDebugLogPath(): string;
 /**
@@ -8,3 +10,8 @@ export declare function ensureSecureDebugLog(filePath: string, options?: {
     secureParent?: boolean;
 }): void;
 export declare function trace(msg: string): void;
+/**
+ * Compact path-advertising summary for RequestContext troubleshooting.
+ * Safe: no tokens / file contents — only workspace vs metadata roots.
+ */
+export declare function traceRequestContextPaths(label: string, requestContext: Record<string, unknown> | undefined): void;

package/dist/debug.js

@@ -10,6 +10,11 @@ const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
 let _traceInitialized = false;
 let _debugFile;
 let _debugFileUsesManagedDirectory = false;
+let _announcedLogPath = false;
+/** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
+export function isDebugEnabled() {
+    return DEBUG_ENABLED;
+}
 /** Resolve the debug log path (env override or per-uid tmpdir default). */
 export function resolveDebugLogPath() {
     if (process.env.CURSOR_PROVIDER_DEBUG_FILE) {
@@ -41,6 +46,18 @@ export function ensureSecureDebugLog(filePath, options = {}) {
     fs.writeFileSync(filePath, "", { mode: 0o600 });
     fs.chmodSync(filePath, 0o600);
 }
+function announceLogPath(filePath) {
+    if (_announcedLogPath)
+        return;
+    _announcedLogPath = true;
+    try {
+        // Visible in the OpenCode / terminal session so operators know where to look.
+        console.error(`[cursor-provider] CURSOR_PROVIDER_DEBUG logging to ${filePath}`);
+    }
+    catch {
+        /* ignore */
+    }
+}
 export function trace(msg) {
     if (!DEBUG_ENABLED)
         return;
@@ -53,6 +70,10 @@ export function trace(msg) {
             ensureSecureDebugLog(_debugFile, { secureParent: _debugFileUsesManagedDirectory });
             fs.writeFileSync(_debugFile, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`, { mode: 0o600 });
             _traceInitialized = true;
+            announceLogPath(_debugFile);
+            fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] debug: enabled file=${_debugFile} ` +
+                `xdg_cache_home=${process.env.XDG_CACHE_HOME ?? "(unset)"} ` +
+                `cwd=${process.cwd()}\n`);
         }
         fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${msg}\n`);
     }
@@ -60,3 +81,24 @@ export function trace(msg) {
         /* ignore */
     }
 }
+/**
+ * Compact path-advertising summary for RequestContext troubleshooting.
+ * Safe: no tokens / file contents — only workspace vs metadata roots.
+ */
+export function traceRequestContextPaths(label, requestContext) {
+    if (!DEBUG_ENABLED)
+        return;
+    const env = requestContext?.env && typeof requestContext.env === "object"
+        ? requestContext.env
+        : undefined;
+    const mcp = requestContext?.mcp_file_system_options &&
+        typeof requestContext.mcp_file_system_options === "object"
+        ? requestContext.mcp_file_system_options
+        : undefined;
+    trace(`${label}: workspace_paths=${JSON.stringify(env?.workspace_paths ?? null)} ` +
+        `process_working_directory=${JSON.stringify(env?.process_working_directory ?? null)} ` +
+        `project_folder=${JSON.stringify(env?.project_folder ?? null)} ` +
+        `terminals_folder=${JSON.stringify(env?.terminals_folder ?? null)} ` +
+        `agent_transcripts_folder=${JSON.stringify(env?.agent_transcripts_folder ?? null)} ` +
+        `workspace_project_dir=${JSON.stringify(mcp?.workspace_project_dir ?? null)}`);
+}

package/dist/index.d.ts

@@ -23,6 +23,12 @@ export type CreateCursorOptions = {
     telemetryEnabled?: boolean;
     /** OpenCode project / worktree directory for request_context collectors. */
     workspaceRoot?: string;
+    /**
+     * Host cache root for Cursor project metadata + model/version caches.
+     * Prefer the host's Path.cache (Effect v2) when available; otherwise the
+     * provider resolves OpenCode / MiMo / Kilo XDG cache dirs automatically.
+     */
+    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. */

package/dist/language-model.d.ts

@@ -20,10 +20,17 @@ export declare function pumpWithRecovery(input: {
     abortSignal?: AbortSignal;
     promptTokens?: number;
     retryPolicy?: CursorRetryPolicy;
-    recover: () => Promise<CursorSession>;
+    recover: (recovery: CursorRunRecovery) => Promise<CursorSession>;
     onSession?: (session: CursorSession) => void;
     maxRecoveries?: number;
 }): Promise<CursorSession>;
+export type CursorRunRecovery = {
+    kind: "rebase";
+} | {
+    kind: "resume";
+    conversationId: string;
+    checkpoint: Uint8Array;
+};
 /**
  * OpenCode re-sends the full tool-result history on every continuation. Prefer
  * the newest result that still has a live pending exec on its tagged session.
@@ -50,6 +57,9 @@ export declare function pump(session: CursorSession, controller: ReadableStreamD
     textId: string;
     reasoningId: string;
     promptTokens?: number;
+    requestUsage?: {
+        outputChars: number;
+    };
 }, abortSignal?: AbortSignal): Promise<void>;
 type ExtractedToolResult = {
     toolCallId: string;