cursor-opencode-provider 0.2.6 → 0.2.8

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.6"`.
+Pin a version if you want: `"cursor-opencode-provider@0.2.8"`.
 
 ### From a local clone
 
@@ -102,15 +102,26 @@ 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 it reports strong environment, binary, or package identity
+3. Explicit `$MIMOCODE_HOME` / `KILO_CONFIG_DIR`, then the provider's host-named install path under `$XDG_CACHE_HOME`
+4. Default `~/.cache/opencode/`
+
+Config-directory presence is deliberately ignored: having MiMo or Kilo installed
+must not redirect a native OpenCode process into that host's cache.
+
+| 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 +168,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 +177,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`. 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`.
+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 +188,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, 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 +227,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,7 +256,7 @@ 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. |
+| 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. |
@@ -255,12 +270,13 @@ 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 and soft-background shell-stream timeouts are bridged through OpenCode's foreground-only `bash` tool. The OpenCode UI keeps the original command; wrapping happens via the classic plugin's `shell.env` injectors (`BASH_ENV` / `ZDOTDIR`) so permissions still see the real user command. 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.
+- **Host web tools use collision-safe aliases** — Cursor sees `custom_websearch` / `custom_webfetch`, and the held Run maps each alias back to an executable OpenCode tool with its schema, permission check, and correlated result intact. The plugin registers its search fallback directly as `custom_websearch`, avoiding OpenCode's reserved `websearch` id filter for third-party providers and taking precedence over MCP search providers such as Brave without host environment configuration. Exact host `webfetch` is translated the same way. Cursor's UI-bound native web interactions stay disabled because their approval replies cannot carry OpenCode tool results.
+- **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 available web capabilities to executable host tools (`question`, `todowrite`, `plan_enter` / `plan_exit`, `custom_websearch`, `custom_webfetch`); native web/PR/MCP/image/SCM requests are declined so they remain behind host tool 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 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.
@@ -268,4 +284,4 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 
 ## License
 
-MIT
+MIT

package/dist/agent-url.d.ts

@@ -1,3 +1,9 @@
+type AgentUrlOptions = {
+    apiBaseURL?: string;
+    baseURL?: string;
+    telemetryEnabled?: boolean;
+    timeoutMs?: number;
+};
 /**
  * Resolve the Run stream origin for this account via the `GetServerConfig`
  * Connect RPC. Memoized for the process lifetime.
@@ -8,10 +14,7 @@
  *
  * Concurrent callers share a single in-flight fetch.
  */
-export declare function resolveAgentUrl(token: string, options?: {
-    apiBaseURL?: string;
-    baseURL?: string;
-    telemetryEnabled?: boolean;
-}): Promise<string>;
+export declare function resolveAgentUrl(token: string, options?: AgentUrlOptions): Promise<string>;
 /** Reset the in-process memo. Tests only. */
 export declare function resetAgentUrlCache(): void;
+export {};

package/dist/auth.js

@@ -1,5 +1,7 @@
 import { CURSOR_API_HOST, CURSOR_WEBSITE_HOST } from "./shared.js";
+import { withAbortDeadline } from "./deadline.js";
 const API_BASE = `https://${CURSOR_API_HOST}`;
+const AUTH_REQUEST_TIMEOUT_MS = 5_000;
 export class AuthExchangeError extends Error {
     cause;
     constructor(message, cause) {
@@ -72,37 +74,67 @@ export function useAuthToken(token) {
     return { accessToken: token };
 }
 export async function exchangeApiKey(apiKey, baseUrl = API_BASE) {
-    const res = await fetch(`${baseUrl}/auth/exchange_user_api_key`, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${apiKey}`,
-        },
-        body: "{}",
+    return withAbortDeadline(AUTH_REQUEST_TIMEOUT_MS, () => new AuthExchangeError("API key exchange timed out"), async (signal) => {
+        let res;
+        try {
+            res = await fetch(`${baseUrl}/auth/exchange_user_api_key`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: "{}",
+                signal,
+            });
+        }
+        catch (cause) {
+            throw new AuthExchangeError("API key exchange request failed", cause);
+        }
+        if (!res.ok) {
+            throw new AuthExchangeError(`API key exchange failed: ${res.status} ${res.statusText}`);
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch (cause) {
+            throw new AuthExchangeError("API key exchange returned malformed JSON", cause);
+        }
+        if (typeof body.accessToken !== "string" || typeof body.refreshToken !== "string") {
+            throw new AuthExchangeError("Exchange response missing tokens");
+        }
+        return { accessToken: body.accessToken, refreshToken: body.refreshToken };
     });
-    if (!res.ok) {
-        throw new AuthExchangeError(`API key exchange failed: ${res.status} ${res.statusText}`);
-    }
-    const body = await res.json();
-    if (!body.accessToken || !body.refreshToken) {
-        throw new AuthExchangeError("Exchange response missing tokens");
-    }
-    return { accessToken: body.accessToken, refreshToken: body.refreshToken };
 }
 export async function refreshAccessToken(refreshToken, baseUrl = API_BASE) {
-    const res = await fetch(`${baseUrl}/auth/token`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ refreshToken }),
+    return withAbortDeadline(AUTH_REQUEST_TIMEOUT_MS, () => new AuthRefreshError("Token refresh timed out"), async (signal) => {
+        let res;
+        try {
+            res = await fetch(`${baseUrl}/auth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ refreshToken }),
+                signal,
+            });
+        }
+        catch (cause) {
+            throw new AuthRefreshError("Token refresh request failed", cause);
+        }
+        if (!res.ok) {
+            throw new AuthRefreshError(`Token refresh failed: ${res.status} ${res.statusText}`);
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch (cause) {
+            throw new AuthRefreshError("Token refresh returned malformed JSON", cause);
+        }
+        if (typeof body.accessToken !== "string" || typeof body.refreshToken !== "string") {
+            throw new AuthRefreshError("Refresh response missing tokens");
+        }
+        return { accessToken: body.accessToken, refreshToken: body.refreshToken };
     });
-    if (!res.ok) {
-        throw new AuthRefreshError(`Token refresh failed: ${res.status} ${res.statusText}`);
-    }
-    const body = await res.json();
-    if (!body.accessToken || !body.refreshToken) {
-        throw new AuthRefreshError("Refresh response missing tokens");
-    }
-    return { accessToken: body.accessToken, refreshToken: body.refreshToken };
 }
 // Cache JWTs obtained via API-key exchange so doStream doesn't re-exchange
 // on every turn when the caller only supplied `apiKey`.

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,13 +53,20 @@ 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: {
             enabled: true,
             mcp_descriptors: nested,
         },
+        // This provider always rejects native web_search/web_fetch interaction
+        // queries with a headless-UI reason (see interactions.ts). Advertise that
+        // unavailability up front so Cursor prefers the collision-safe
+        // custom_web* aliases instead of routing through a query doomed to fail.
+        web_search_enabled: false,
+        web_fetch_enabled: false,
         // Completeness: true only for sections we actually gathered.
         rules_info_complete: true,
         env_info_complete: true,
@@ -73,5 +83,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,44 @@
-/** OpenCode global config dir (`~/.config/opencode`). */
+export type HostPathEnv = NodeJS.ProcessEnv;
+type CompatDetectResult = {
+    id: string;
+    supported: boolean;
+    source?: string;
+    profile: {
+        paths: {
+            cacheDir: string;
+        };
+    };
+};
+type CompatDetector = () => CompatDetectResult;
+/**
+ * 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.
+ *
+ * Explicit host environment wins. Otherwise, an installed provider inherits
+ * the host-named cache containing its module. A source checkout or otherwise
+ * unidentifiable install defaults to OpenCode. Merely having another host's
+ * config directory installed is not evidence that it owns this process.
+ */
+export declare function resolveHostCacheDir(env?: HostPathEnv, moduleUrl?: string): 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(detector?: CompatDetector): 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. Strong OCP `detect()` identity when {@link adoptCompatHostCacheDir} ran successfully
+ * 3. Explicit host environment / provider install path ({@link resolveHostCacheDir})
  */
 export declare function opencodeGlobalCacheDir(): string;
 /**
@@ -11,4 +47,21 @@ 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;
+export {};

package/dist/context/paths.js

@@ -1,21 +1,106 @@
+import { createHash } from "node:crypto";
+import { 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 { fileURLToPath } from "node:url";
+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");
+}
+/**
+ * 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.
+ *
+ * Explicit host environment wins. Otherwise, an installed provider inherits
+ * the host-named cache containing its module. A source checkout or otherwise
+ * unidentifiable install defaults to OpenCode. Merely having another host's
+ * config directory installed is not evidence that it owns this process.
+ */
+export function resolveHostCacheDir(env = process.env, moduleUrl = import.meta.url) {
+    const mimoHome = env.MIMOCODE_HOME;
+    if (mimoHome && mimoHome.length > 0) {
+        return path.join(mimoHome, "cache");
+    }
+    const cacheHome = xdgCacheHome(env);
+    const kiloConfig = env.KILO_CONFIG_DIR;
+    if (kiloConfig && kiloConfig.length > 0) {
+        return path.join(cacheHome, "kilo");
+    }
+    let modulePath;
+    try {
+        modulePath = moduleUrl.startsWith("file:") ? fileURLToPath(moduleUrl) : path.resolve(moduleUrl);
+    }
+    catch {
+        modulePath = undefined;
+    }
+    if (modulePath) {
+        for (const host of ["mimocode", "kilo", "opencode"]) {
+            const root = path.resolve(cacheHome, host);
+            if (modulePath === root || modulePath.startsWith(`${root}${path.sep}`))
+                return root;
+        }
+    }
+    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(detector) {
+    if (hostCacheDirOverride)
+        return hostCacheDirOverride;
+    try {
+        const detect = detector ?? (await import("@opencode-compat/profile")).detect;
+        const result = detect();
+        if (!result.supported || result.id === "unknown")
+            return undefined;
+        if (!result.source || !["env", "binary", "package"].includes(result.source)) {
+            trace(`host-cache: ignored weak OCP detect host=${result.id} source=${result.source ?? "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. Strong OCP `detect()` identity when {@link adoptCompatHostCacheDir} ran successfully
+ * 3. Explicit host environment / provider install path ({@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 +113,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/deadline.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bound a complete async operation, not only fetch(). Response body readers can
+ * ignore abort signals, so Promise.race remains the authoritative deadline.
+ *
+ * Rejects with `timeoutError()` before aborting so callers observe the domain
+ * timeout error rather than a generic AbortError.
+ */
+export declare function withAbortDeadline<T>(timeoutMs: number, timeoutError: () => Error, run: (signal: AbortSignal) => Promise<T>): Promise<T>;