cursor-opencode-provider 0.5.0 → 0.6.0

package/README.md

@@ -126,7 +126,7 @@ For OpenCode builds that use the Effect/Promise **v2** plugin API (`plugins` fie
 
 Local clone equivalent: `"file:///absolute/path/to/cursor-opencode-provider/dist/plugin-v2.js"`.
 
-That entry registers the provider via `ctx.aisdk.sdk` / `ctx.aisdk.language`. Keep the classic `plugin` entry for auth.
+That entry registers the provider via `ctx.aisdk.sdk` / `ctx.aisdk.language`. Keep the classic `plugin` entry for auth **and** plugin tools (notably `cursor_image_save` / `custom_websearch`): the 1.18 `/v2/promise` API has no `tool` domain, so a v2-only load silently disables Cursor image generation.
 
 ### OpenCode 2.0 beta (`opencode2`)
 
@@ -243,23 +243,21 @@ 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) (`crsr_...`) |
 
-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. Completed conversation state is stored separately under `<host-cache>/cursor-conversations/`, with one independently replaced gzip-compressed protobuf snapshot per stable OpenCode session. Snapshots are refreshed at each successful Cursor `TurnEnded` and restored after provider restarts; records not updated for more than 24 hours are removed when the provider starts. Cursor's checkpoint is an index of content-addressed KV blobs rather than a self-contained transcript, so the snapshot retains the blobs reachable from the latest checkpoint and discards superseded blobs. This private Cursor state is not a copy of OpenCode's session database.
+After login, the plugin fetches your available models and writes them to `<host-cache>/cursor-models.json`. 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. Completed conversation state is stored separately under `<host-cache>/cursor-conversations/`, with one independently replaced gzip-compressed protobuf snapshot per stable host session. Snapshots are refreshed at each successful Cursor `TurnEnded` and restored after provider restarts; records not updated for more than 24 hours are removed when the provider starts. Cursor's checkpoint is an index of content-addressed KV blobs rather than a self-contained transcript, so the snapshot retains the blobs reachable from the latest checkpoint and discards superseded blobs. This private Cursor state is not a copy of the host's session database.
 
 ### Paths (host 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/`
+1. Explicit `createCursor({ cacheDir })` / host API cache override
+2. A structural host path bridge installed before the provider loads
+3. Native OpenCode: `$XDG_CACHE_HOME/opencode`, otherwise `~/.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.
+The provider never detects or names fork hosts. Compatibility layers own host identity and may inject cache, data, and config roots through the structural bridge; without one, standalone OpenCode behavior is unchanged.
 
 | Kind | Default (OpenCode) | Notes |
 |------|--------------------|-------|
-| Model, version, and 24-hour conversation **cache** | `~/.cache/opencode/` | MiMo: `$MIMOCODE_HOME/cache` or `~/.cache/mimocode/`; Kilo: `~/.cache/kilo/` |
+| Model, version, and 24-hour conversation **cache** | `~/.cache/opencode/` | A host bridge may replace the root |
 | 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 |
@@ -331,7 +329,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
+  // cacheDir: "/path/to/host/cache", // optional; else active-host heuristic
   // retry: { maxAttempts: 3, baseDelayMs: 500, maxDelayMs: 8_000 },
   // continuation: { heartbeatMs: 5_000, semanticIdleMs: 120_000, hardCapMs: 600_000 },
 })
@@ -340,7 +338,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 `crsr_...` 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`.
+Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `crsr_...` 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 an injected structural host path bridge or the native OpenCode XDG cache 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
 
@@ -352,7 +350,9 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `crs
 | `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>/`) |
 | `CURSOR_OPENCODE2_DEV_ENTRY` | **Local OpenCode 2.0 only.** Absolute path to a built entry file (usually `dist/index.js`). Rewrites the catalog's AI SDK package to `aisdk:file://…` so the daemon imports your local build instead of `npm install`-ing the published package. Export it **before** `opencode2 service start`, then restart after rebuilds. Unset in production. |
-| `XDG_CACHE_HOME` | Base for host cache dirs (`$XDG_CACHE_HOME/opencode/`, `…/mimocode/`, or `…/kilo/`) when no explicit `cacheDir` / OCP detect override |
+| `XDG_CACHE_HOME` | Base for host cache dirs (`$XDG_CACHE_HOME/opencode/`, `…/mimocode/`, `…/kilo/`, or OMP's migrated `…/omp/`) when no explicit `cacheDir` / OCP detect override |
+| `PI_CODING_AGENT_DIR` | Custom Pi/OMP agent root; provider stores its private cache below `<agent-root>/cache/cursor-opencode/` |
+| `PI_CONFIG_DIR` | Custom Pi/OMP config root name used when deriving the default agent root |
 | `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/` |
@@ -446,6 +446,7 @@ Kilo `scout` is reserved for external documentation, dependency repositories, an
 | `cursor-opencode-provider/plugin/v2` | OpenCode 1.18 Effect/Promise v2 plugin (`ctx.aisdk.*`) |
 | `cursor-opencode-provider/plugin/opencode2` | OpenCode 2.0 beta plugin (self-registering: catalog + auth + tools) |
 | `cursor-opencode-provider/errors` | Structured provider error classes |
+| `cursor-opencode-provider/image-save` | Host-neutral `executeCursorImageSave` (pi-bridge / non-plugin hosts) |
 
 The package root intentionally stays plugin-safe for OpenCode's classic loader. `CursorPluginV2` and non-plugin runtime APIs are **not** re-exported from the package root; load them through their dedicated subpaths.
 
@@ -482,7 +483,11 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **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.
 - **MCP resource tools (`list_mcp_resources` / `read_mcp_resource`) also use collision-safe aliases, and Cursor's native resource exec is always answered** — OpenCode's resource tools (advertised only when a connected MCP server declares `capabilities.resources`) share bare names with two of Cursor's own native tool-call variants. Left unaliased, Cursor's client can route a call onto its native exec channel instead of the ordinary MCP tool path, which this provider does not translate — confirmed live: reading a resource was dispatched natively and killed the Run before this fix. The provider now aliases both names to `custom_list_mcp_resources` / `custom_read_mcp_resource` (same mechanism as web search/fetch) so normal calls execute through OpenCode's tools, and separately answers Cursor's native resource-exec fields directly on the protocol floor — an empty list, or a "server not found" error for read — so an unsolicited native request from Cursor can never fail the Run. Downloads (`download_path`) have no OpenCode equivalent and are always refused; binary resource content is subject to the same [50 KB / attachment-type limits](#known-limitations) as other 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.
+- **Cursor-native AskQuestion reaches you through OpenCode's question tool** — when Cursor asks a clarifying question, the provider translates the interaction into the host `question` tool, so the prompt appears in OpenCode with its real options and your answer is mapped back to Cursor's option ids (an answer you type yourself becomes Cursor's freeform text). Questions Cursor marks as non-blocking are acknowledged immediately and answered later, matching Cursor CLI. If the current agent does not offer `question` — most subagents deny it, and compaction turns have no tools — the request is declined with that reason and the model asks in its reply instead.
+- **Cursor-native SwitchMode reaches you through OpenCode plan enter/exit** — when Cursor raises `switch_mode_request_query`, the provider translates it into the host `plan_enter` or `plan_exit` tool (when advertised) and keeps Cursor waiting until you approve or reject, matching Cursor CLI. `plan`/`spec` enter plan mode; every other non-empty target (including `agent`, `build`, `chat`, `debug`, `edit`, `background`, `multitask`, `triage`, `project`, and unknowns) leaves plan via `plan_exit`. After approval, the provider injects a Cursor CLI-shaped `<system_reminder>` for that mode on later turns so the agent gets the same behavioral instructions the CLI would send.
+- **Cursor image generation saves through OpenCode's permission** — Cursor generates the image on its servers and then writes it to you like any other file. Because that write carries raw bytes, which OpenCode's text `write` tool cannot represent, the provider holds the bytes and asks OpenCode for the same permissions a normal write uses — the external-directory prompt when the target sits outside your project, then `edit` — naming the target file. Approve it and the image is written byte-for-byte to its path; deny it and nothing reaches disk — Cursor is told the write was denied, using its own permission-denied result, so the model knows the file is not there. Generation is only approved when the save path is available, so Cursor quota is never spent on an image that could not be saved. By default images land in the Cursor project folder under `assets/`, kept out of your git tree as agent artifacts. Ask for a specific path and the image is saved there instead. Editing an existing image with `reference_image_paths` is not supported yet. The approach is adapted from [`jkalasas/opencode-antigravity-image`](https://github.com/jkalasas/opencode-antigravity-image) (MIT) by jkalasas, which established writing image bytes from inside an OpenCode plugin tool.
+- **Cursor-native CreatePlan writes a host plan file, then asks before executing it** — when Cursor raises `create_plan_request_query`, the provider writes plain markdown to your host's own plans directory (`<hostGlobalDataDir>/plans/`, never your repository and never Cursor's `~/.cursor/plans`), with no Cursor YAML frontmatter. Writing the plan does not ask; running it does. If you are in plan mode, the provider prints the plan into the conversation — Cursor sends it over a side channel that would otherwise never display it — and then asks *"Plan at &lt;path&gt; is complete. Would you like to switch to the build agent and start implementing?"* — the same prompt OpenCode's own `plan_exit` uses — and keeps Cursor waiting for your answer. Answer **Yes** and the plan is reported as approved and implementation begins; answer **No** (or dismiss it) and Cursor is told the plan was not accepted, so the model refines it and proposes again instead of starting work. Hosts that advertise their own plan-staging tool run their native review UI instead, and it reports the same approve/refine outcome. Empty args still get the CLI empty-`plan_uri` success ack. Display `create_plan_tool_call` continues to mirror into `todowrite` separately.
+- **Other Cursor-native interaction queries remain headless** — remaining UI/approval *queries* (as distinct from display tool calls and the AskQuestion / SwitchMode / CreatePlan / GenerateImage bridges) still cannot be surfaced through the AI SDK provider interface. The normal system prompt redirects available web capabilities to executable host tools (`custom_websearch`, `custom_webfetch`); native web/PR/MCP/SCM requests are declined so they remain behind host tool permissions. Compaction prompts are unchanged. Unknown future interaction variants fail the turn explicitly instead of hanging the Run stream.
 - **Compaction resets Cursor conversation state without resetting stable workspace context** — 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. Across both id rotations, the frozen workspace/rules/environment base and its prior encoded-context comparison seed are transferred instead of rebuilt; tools, skills, agents, plugins, and MCP state are still rediscovered, and the complete context is reused only when its bytes remain identical. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state. Debug logs include system-prompt and encoded RequestContext hashes for cache-prefix verification.
 - **Conversation bindings survive provider restarts** — after each successful `TurnEnded`, the OpenCode-session binding, latest checkpoint, checkpoint-reachable KV blob graph, frozen request-context base, last real tool catalog, and pending post-compaction rebase marker are atomically replaced in that session's private `<host-cache>/cursor-conversations/*.pb.gz` snapshot. The protobuf stores checkpoints, blob ids/data, and request context as bytes without JSON/base64 expansion, then gzip compresses the complete record. A checkpoint alone is insufficient: Cursor requests its referenced hashes through `get_blob` when the next Run starts. Reachability follows Cursor CLI's export traversal (turns, messages, steps, images, summaries, todos, prompts, and nested subagents), pruning superseded blobs; decode failure or a missing referenced hash conservatively retains the complete blob set. The stable OpenCode session id selects the file; Cursor conversation ids may rotate during compaction and remain inside the snapshot. Independent files prevent concurrent OpenCode processes from losing unrelated sessions by replacing a shared aggregate cache. Startup restores records updated within 24 hours and safely flushes older ones without deleting a concurrently published fresh replacement. Experimental legacy JSON snapshots are discarded rather than migrated. Debug logs report hydration as `restored`, `missing`, `invalid`, or `expired`, plus the compressed and protobuf snapshot sizes. The restored catalog is a fallback only for lifecycle turns such as compaction; an ordinary restricted/no-tool turn never resurrects it. Process-global bindings and compaction catalogs still use a 256-session LRU bound; memory eviction drops the live checkpoint, blobs, and frozen context, which can be rehydrated from the restart cache on later use.
 - **Oversized checkpoint graphs rebase instead of flooding the Run stream** — before reusing a checkpoint, the provider measures its reachable KV graph. State above 100 MiB, or an incomplete graph with a missing/undecodable reference, rotates to a fresh Cursor conversation seeded from OpenCode's authoritative history. KV, request-context, MCP-state, interaction, and heartbeat writes are ordered per Run and await HTTP/2 drain, so a large blob reply cannot create an unbounded queue later misreported as heartbeat backpressure. Debug logs distinguish checkpoint-envelope bytes, reachable blob bytes, seed size, and encoded Run-request estimate; raw blob bytes are never presented as tokens.

package/dist/context/agents.d.ts

@@ -5,7 +5,7 @@ export type CollectedAgent = {
     prompt: string;
 };
 /**
- * Custom agents from the active OpenCode-compatible config roots. OCP may
+ * Custom agents from the active OpenCode-compatible config roots. A host bridge may
  * install a host-neutral bridge before loading this module; without one this
  * remains the direct OpenCode discovery path.
  */

package/dist/context/agents.js

@@ -120,7 +120,7 @@ async function scanAgentRoot(root, out) {
     await scanDir(path.join(root, "agents"), "agents");
 }
 /**
- * Custom agents from the active OpenCode-compatible config roots. OCP may
+ * Custom agents from the active OpenCode-compatible config roots. A host bridge may
  * install a host-neutral bridge before loading this module; without one this
  * remains the direct OpenCode discovery path.
  */

package/dist/context/auth-store.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { opencodeGlobalDataDir } from "./paths.js";
+import { hostGlobalDataDir } from "./paths.js";
 function debugEnabled() {
     return process.env.CURSOR_PROVIDER_DEBUG === "1" || process.env.CURSOR_PROVIDER_DEBUG === "true";
 }
@@ -26,7 +26,7 @@ export async function readStoredAuth(providerId) {
             return undefined;
         }
     }
-    const filePath = path.join(opencodeGlobalDataDir(), "auth.json");
+    const filePath = path.join(hostGlobalDataDir(), "auth.json");
     try {
         const raw = await readFile(filePath, "utf-8");
         try {

package/dist/context/build.d.ts

@@ -9,7 +9,9 @@ export type DynamicRequestContextKey = typeof DYNAMIC_REQUEST_CONTEXT_KEYS[numbe
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Sourced from OpenCode discovery (and .claude/.agents skill fallbacks).
- * Honors `instructions` globs the same way OpenCode does (including `.cursor/` if listed).
+ * Honors `instructions` globs the same way OpenCode does. The provider never
+ * looks in Cursor's own directories; a `.cursor/` path is read only when the
+ * user's own OpenCode config lists it, exactly as the host would read it.
  */
 export declare function buildRequestContext(input: BuildRequestContextInput): Promise<Record<string, unknown>>;
 /** Rediscover only capability/plugin sections that may change during a chat. */

package/dist/context/build.js

@@ -36,7 +36,7 @@ const DEFAULT_HOST_SUBAGENTS = [
 /**
  * Convert the raw host executor catalog into the exact subagent list advertised
  * to Cursor. `hostSubagents.complete` answers a narrow question: did the host's
- * task/actor tool itself expose an exhaustive recipient list (schema enum or
+ * task tool itself exposes an exhaustive recipient list (schema enum or
  * catalog marker)? OpenCode's task tool intentionally uses a plain string, so
  * that raw flag is false even though we can still advertise a complete Cursor
  * catalog by adding built-in defaults and discovered agent files.
@@ -60,7 +60,9 @@ function buildAdvertisedSubagentCatalog(hostSubagents, discoveredAgents) {
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Sourced from OpenCode discovery (and .claude/.agents skill fallbacks).
- * Honors `instructions` globs the same way OpenCode does (including `.cursor/` if listed).
+ * Honors `instructions` globs the same way OpenCode does. The provider never
+ * looks in Cursor's own directories; a `.cursor/` path is read only when the
+ * user's own OpenCode config lists it, exactly as the host would read it.
  */
 export async function buildRequestContext(input) {
     const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());

package/dist/context/index.d.ts

@@ -1,3 +1,3 @@
 export { buildDynamicRequestContext, buildRequestContext, DYNAMIC_REQUEST_CONTEXT_KEYS, materializeRequestContext, requestContextBase, type BuildRequestContextInput, } from "./build.js";
 export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestContext, MAX_FROZEN_REQUEST_CONTEXTS, resetFrozenRequestContextsForTests, setFrozenRequestContext, transferFrozenRequestContext, } from "./frozen.js";
-export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";
+export { HOST_PATH_BRIDGE, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, hostGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/index.js

@@ -1,3 +1,3 @@
 export { buildDynamicRequestContext, buildRequestContext, DYNAMIC_REQUEST_CONTEXT_KEYS, materializeRequestContext, requestContextBase, } from "./build.js";
 export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestContext, MAX_FROZEN_REQUEST_CONTEXTS, resetFrozenRequestContextsForTests, setFrozenRequestContext, transferFrozenRequestContext, } from "./frozen.js";
-export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";
+export { HOST_PATH_BRIDGE, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, hostGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/paths.d.ts

@@ -1,79 +1,61 @@
 export type HostPathEnv = NodeJS.ProcessEnv;
-/** Host-neutral bridge installed by OCP before an unchanged provider is loaded. */
-export declare const OPENCODE_PATH_BRIDGE: unique symbol;
+/** Structural host-path capability installed before an unchanged provider loads. */
+export declare const HOST_PATH_BRIDGE: unique symbol;
 export type OpenCodePathBridge = {
     projectConfigDirs: (workspaceRoot: string) => string[];
     globalConfigDirs: () => string[];
+    /** Optional host-owned durable data root; absent means native OpenCode defaults. */
+    globalDataDir?: () => string;
+    /** Optional host-owned cache root; absent means native OpenCode defaults. */
+    globalCacheDir?: () => string;
     configFileNames?: string[];
 };
 export declare function opencodeProjectConfigDirs(workspaceRoot: string): string[];
 export declare function opencodeGlobalConfigDirs(): string[];
 export declare function opencodeConfigFileNames(): string[];
-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;
-declare const HOST_CACHE_DIRS: readonly ["mimocode", "kilo", "opencode"];
-export type HostCacheDir = (typeof HOST_CACHE_DIRS)[number];
-/**
- * Host cache-dir name inferred from the running binary (`argv[0]` /
- * `process.execPath`). A source-checkout provider can't be located by install
- * path, but the binary that loaded it is authoritative: when this process IS
- * `mimo` / `kilocode`, the cache root is that host's, not OpenCode's. Mirrors
- * OCP `detect()` binaryHint semantics and tolerates the leading-dot Kilo binary
- * (`.kilo`). Only `argv[0]` is inspected — later argv entries are arguments,
- * not binary identity, and could otherwise cause false positives (e.g. an
- * `--opencode-config=…` flag under a fork).
- */
-export declare function hostCacheDirFromProcess(argv?: readonly string[], execPath?: string): HostCacheDir | 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 is attributed
- * by the running binary identity (see {@link hostCacheDirFromProcess}). Merely
- * having another host's config directory installed is not evidence that it
- * owns this process.
- */
-export declare function resolveHostCacheDir(env?: HostPathEnv, moduleUrl?: string, processIdentity?: {
-    argv?: readonly string[];
-    execPath?: 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. */
+/** Resolve the native OpenCode cache root when no host bridge is installed. */
+export declare function resolveHostCacheDir(env?: HostPathEnv): string;
+/** Native OpenCode global config dir. */
 export declare function opencodeGlobalConfigDir(): string;
 /**
  * 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})
+ * 2. An injected structural host path bridge
+ * 3. Native OpenCode XDG defaults ({@link resolveHostCacheDir})
  */
 export declare function opencodeGlobalCacheDir(): string;
+/** Native OpenCode global data root. */
+export declare function opencodeGlobalDataDir(env?: HostPathEnv): string;
+/** Host-portable durable data root; falls back to native OpenCode. */
+export declare function hostGlobalDataDir(env?: HostPathEnv): string;
 /**
- * OpenCode global data dir (`~/.local/share/opencode`).
- * Uses `$XDG_DATA_HOME/opencode` when set, otherwise `$HOME/.local/share/opencode`.
- * Auth credentials live here in `auth.json`.
+ * Directory for host plan files — always `<hostGlobalDataDir()>/plans`, and
+ * never inside the user's repository.
+ *
+ * OpenCode's own `Session.plan` branches on VCS and puts plans in the worktree
+ * (`<worktree>/.opencode/plans`) for a git project. The provider deliberately
+ * does *not* mirror that branch. Writing there means a throwaway plan lands in
+ * the user's tree untracked-but-unignored, and — because OpenCode installs
+ * `@opencode-ai/plugin` into every `.opencode` directory it discovers walking up
+ * from the cwd — creating that directory also bootstraps a project-local
+ * `node_modules`. The provider must add nothing to a repository it did not
+ * already contain.
+ *
+ * The global-data location is not a degraded fallback: it is the branch OpenCode
+ * itself uses when there is no VCS, and its plan agent allow-lists that path for
+ * `edit` / `external_directory` alongside the in-worktree one. {@link
+ * hostGlobalDataDir} carries an optional injected host translation; without a
+ * bridge it is the native OpenCode data root.
  */
-export declare function opencodeGlobalDataDir(): string;
+export declare function hostPlansDir(_workspaceRoot?: string): string;
 /**
  * Cursor-compatible path slug (`/Users/a/b` → `Users-a-b`).
  * Used for per-workspace metadata under the host cache.
@@ -81,7 +63,7 @@ export declare function opencodeGlobalDataDir(): string;
 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).
+ * 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.
@@ -91,4 +73,3 @@ 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

@@ -2,12 +2,11 @@ import { createHash } from "node:crypto";
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { trace } from "../debug.js";
-/** Host-neutral bridge installed by OCP before an unchanged provider is loaded. */
-export const OPENCODE_PATH_BRIDGE = Symbol.for("opencode.compat.path-bridge");
+/** Structural host-path capability installed before an unchanged provider loads. */
+export const HOST_PATH_BRIDGE = Symbol.for("opencode.host.path-bridge");
 function pathBridge() {
-    const value = globalThis[OPENCODE_PATH_BRIDGE];
+    const value = globalThis[HOST_PATH_BRIDGE];
     if (!value || typeof value !== "object")
         return undefined;
     const bridge = value;
@@ -15,6 +14,23 @@ function pathBridge() {
         ? bridge
         : undefined;
 }
+function openCodeGlobalDataDir(env = process.env) {
+    if (env.XDG_DATA_HOME && env.XDG_DATA_HOME.length > 0) {
+        return path.join(env.XDG_DATA_HOME, "opencode");
+    }
+    return path.join(resolveHome(env), ".local", "share", "opencode");
+}
+function openCodeGlobalCacheDir(env = process.env) {
+    return path.join(xdgCacheHome(env), "opencode");
+}
+function bridgeGlobalDataDir() {
+    const value = pathBridge()?.globalDataDir?.();
+    return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
+}
+function bridgeGlobalCacheDir() {
+    const value = pathBridge()?.globalCacheDir?.();
+    return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
+}
 export function opencodeProjectConfigDirs(workspaceRoot) {
     return pathBridge()?.projectConfigDirs(path.resolve(workspaceRoot)) ?? [
         path.join(path.resolve(workspaceRoot), ".opencode"),
@@ -48,110 +64,11 @@ export function setHostCacheDirOverride(dir) {
 export function getHostCacheDirOverride() {
     return hostCacheDirOverride;
 }
-const HOST_CACHE_DIRS = ["mimocode", "kilo", "opencode"];
-/**
- * Host cache-dir name inferred from the running binary (`argv[0]` /
- * `process.execPath`). A source-checkout provider can't be located by install
- * path, but the binary that loaded it is authoritative: when this process IS
- * `mimo` / `kilocode`, the cache root is that host's, not OpenCode's. Mirrors
- * OCP `detect()` binaryHint semantics and tolerates the leading-dot Kilo binary
- * (`.kilo`). Only `argv[0]` is inspected — later argv entries are arguments,
- * not binary identity, and could otherwise cause false positives (e.g. an
- * `--opencode-config=…` flag under a fork).
- */
-export function hostCacheDirFromProcess(argv = process.argv, execPath = process.execPath) {
-    for (const raw of [argv[0], execPath]) {
-        if (!raw)
-            continue;
-        const name = path.basename(String(raw)).toLowerCase().replace(/^\.+/, "");
-        if (name === "mimo" ||
-            name === "mimocode" ||
-            name.startsWith("mimo-") ||
-            name.includes("mimocode")) {
-            return "mimocode";
-        }
-        if (name === "kilo" ||
-            name === "kilocode" ||
-            name.startsWith("kilo-") ||
-            name.includes("kilocode")) {
-            return "kilo";
-        }
-        if (name === "opencode" ||
-            name.startsWith("opencode-") ||
-            name.includes("opencode")) {
-            return "opencode";
-        }
-    }
-    return 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 is attributed
- * by the running binary identity (see {@link hostCacheDirFromProcess}). 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, processIdentity = {}) {
-    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 HOST_CACHE_DIRS) {
-            const root = path.resolve(cacheHome, host);
-            if (modulePath === root || modulePath.startsWith(`${root}${path.sep}`))
-                return root;
-        }
-    }
-    // Source checkout: the module path can't name the host, but the binary that
-    // loaded us can (running as `mimo` / `kilocode` / `opencode`).
-    const host = hostCacheDirFromProcess(processIdentity.argv ?? process.argv, processIdentity.execPath ?? process.execPath);
-    if (host)
-        return path.join(cacheHome, host);
-    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;
-    }
+/** Resolve the native OpenCode cache root when no host bridge is installed. */
+export function resolveHostCacheDir(env = process.env) {
+    return bridgeGlobalCacheDir() ?? openCodeGlobalCacheDir(env);
 }
-/** OpenCode / host global config dir (`~/.config/<app>`). Still OpenCode-named for rule discovery. */
+/** Native OpenCode global config dir. */
 export function opencodeGlobalConfigDir() {
     return path.join(resolveHome(), ".config", "opencode");
 }
@@ -160,24 +77,43 @@ export function opencodeGlobalConfigDir() {
  *
  * 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})
+ * 2. An injected structural host path bridge
+ * 3. Native OpenCode XDG defaults ({@link resolveHostCacheDir})
  */
 export function opencodeGlobalCacheDir() {
     if (hostCacheDirOverride)
         return hostCacheDirOverride;
     return resolveHostCacheDir();
 }
+/** Native OpenCode global data root. */
+export function opencodeGlobalDataDir(env = process.env) {
+    return openCodeGlobalDataDir(env);
+}
+/** Host-portable durable data root; falls back to native OpenCode. */
+export function hostGlobalDataDir(env = process.env) {
+    return bridgeGlobalDataDir() ?? openCodeGlobalDataDir(env);
+}
 /**
- * OpenCode global data dir (`~/.local/share/opencode`).
- * Uses `$XDG_DATA_HOME/opencode` when set, otherwise `$HOME/.local/share/opencode`.
- * Auth credentials live here in `auth.json`.
+ * Directory for host plan files — always `<hostGlobalDataDir()>/plans`, and
+ * never inside the user's repository.
+ *
+ * OpenCode's own `Session.plan` branches on VCS and puts plans in the worktree
+ * (`<worktree>/.opencode/plans`) for a git project. The provider deliberately
+ * does *not* mirror that branch. Writing there means a throwaway plan lands in
+ * the user's tree untracked-but-unignored, and — because OpenCode installs
+ * `@opencode-ai/plugin` into every `.opencode` directory it discovers walking up
+ * from the cwd — creating that directory also bootstraps a project-local
+ * `node_modules`. The provider must add nothing to a repository it did not
+ * already contain.
+ *
+ * The global-data location is not a degraded fallback: it is the branch OpenCode
+ * itself uses when there is no VCS, and its plan agent allow-lists that path for
+ * `edit` / `external_directory` alongside the in-worktree one. {@link
+ * hostGlobalDataDir} carries an optional injected host translation; without a
+ * bridge it is the native OpenCode data root.
  */
-export function opencodeGlobalDataDir() {
-    if (process.env.XDG_DATA_HOME) {
-        return path.join(process.env.XDG_DATA_HOME, "opencode");
-    }
-    return path.join(resolveHome(), ".local", "share", "opencode");
+export function hostPlansDir(_workspaceRoot) {
+    return path.join(hostGlobalDataDir(), "plans");
 }
 /**
  * Cursor-compatible path slug (`/Users/a/b` → `Users-a-b`).
@@ -193,7 +129,7 @@ export function slugifyWorkspacePath(workspaceRoot) {
 }
 /**
  * Cursor-style project metadata root for a workspace.
- * Lives at `<host-cache>/projects/<slug>/` (OpenCode / MiMo / Kilo cache root).
+ * 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.

package/dist/context/rules.js

@@ -167,7 +167,7 @@ export async function loadMergedConfig(workspaceRoot) {
     if (isProjectConfigDisabled())
         return mergeConfig({}, globalConfig);
     // The bridge supplies native project config roots for an unchanged plugin:
-    // .opencode on OpenCode, .mimocode on MiMo, and .kilo/.kilocode on Kilo.
+    // The active host's project config directories are supplied by the path bridge; OpenCode defaults to .opencode.
     // Later roots have higher precedence, matching the host's native ordering.
     let projectConfig = await readJsonConfig(workspaceRoot);
     for (const configDir of opencodeProjectConfigDirs(workspaceRoot)) {

package/dist/image-save-tool.d.ts

@@ -0,0 +1,19 @@
+import { executeCursorImageSave } from "./image-save.js";
+/** Build the classic OpenCode image-save tool with the host's own Zod helper. */
+export declare function createCursorImageSaveTool(factory: {
+    tool: (input: Record<string, unknown>) => Record<string, unknown>;
+    schema: {
+        string: () => any;
+    };
+}): Record<string, unknown>;
+/** Host-neutral JSON-schema fallback for hosts with no classic helper. */
+export declare const cursorImageSaveTool: {
+    description: string;
+    args: {
+        image_id: {
+            type: string;
+            description: string;
+        };
+    };
+    execute: typeof executeCursorImageSave;
+};

package/dist/image-save-tool.js

@@ -0,0 +1,25 @@
+import { executeCursorImageSave } from "./image-save.js";
+/** Build the classic OpenCode image-save tool with the host's own Zod helper. */
+export function createCursorImageSaveTool(factory) {
+    return factory.tool({
+        description: "Save an image that Cursor generated during this session to its target path. "
+            + "Takes only the id of an already-generated image — it cannot write arbitrary "
+            + "files, and it is not a general-purpose file writer. You do not normally call "
+            + "this: the Cursor provider issues it after an image is generated.",
+        args: {
+            image_id: factory.schema.string().describe("Id of the pending Cursor-generated image to save"),
+        },
+        execute: executeCursorImageSave,
+    });
+}
+/** Host-neutral JSON-schema fallback for hosts with no classic helper. */
+export const cursorImageSaveTool = {
+    description: "Save an image that Cursor generated during this session to its target path. "
+        + "Takes only the id of an already-generated image — it cannot write arbitrary "
+        + "files, and it is not a general-purpose file writer. You do not normally call "
+        + "this: the Cursor provider issues it after an image is generated.",
+    args: {
+        image_id: { type: "string", description: "Id of the pending Cursor-generated image to save" },
+    },
+    execute: executeCursorImageSave,
+};