cursor-opencode-provider 0.4.3 → 0.6.0

package/dist/context/frozen.js

@@ -0,0 +1,168 @@
+import { buildDynamicRequestContext, buildRequestContext, materializeRequestContext, requestContextBase, } from "./build.js";
+import { trace } from "../debug.js";
+import { encodeMessage } from "../protocol/messages.js";
+/**
+ * Freeze the expensive RequestContext base for the life of a conversation_id.
+ *
+ * Cursor's current exec-daemon cache treats RequestContext as a baked stable
+ * base plus live plugin/tool overlays. Rebuilding volatile git/layout data on
+ * every Run shifts the prompt prefix and tanks prompt-cache hits.
+ *
+ * Skills, subagents, plugin metadata, and tool/MCP capabilities are rebuilt on
+ * each Run and overlaid on that base. If their encoded bytes did not change,
+ * the exact prior materialized object is reused. This matches Cursor's newer
+ * baked-context + live-overlay design without retaining stale capabilities.
+ */
+const byConversationId = new Map();
+const materializedByConversationId = new Map();
+const buildsByConversationId = new Map();
+export const MAX_FROZEN_REQUEST_CONTEXTS = 256;
+function freezeSnapshot(value, seen = new Set()) {
+    if (!value || typeof value !== "object")
+        return value;
+    const object = value;
+    if (seen.has(object) || ArrayBuffer.isView(object))
+        return value;
+    seen.add(object);
+    for (const child of Object.values(object))
+        freezeSnapshot(child, seen);
+    return Object.freeze(value);
+}
+function remember(conversationId, context) {
+    // Map insertion order is the LRU order. Refresh existing entries on use.
+    byConversationId.delete(conversationId);
+    // Clone + recursively freeze so session.requestContext cannot mutate the
+    // byte-stable snapshot retained for later Runs in the same conversation.
+    byConversationId.set(conversationId, freezeSnapshot(structuredClone(context)));
+    materializedByConversationId.delete(conversationId);
+    while (byConversationId.size > MAX_FROZEN_REQUEST_CONTEXTS) {
+        const oldest = byConversationId.keys().next().value;
+        if (!oldest)
+            break;
+        byConversationId.delete(oldest);
+        materializedByConversationId.delete(oldest);
+    }
+}
+/** Frozen stable RequestContext base for this conversation, if any. */
+export function getFrozenRequestContext(conversationId) {
+    const frozen = byConversationId.get(conversationId);
+    if (!frozen)
+        return undefined;
+    // Touch for LRU.
+    byConversationId.delete(conversationId);
+    byConversationId.set(conversationId, frozen);
+    return frozen;
+}
+/** Replace the frozen stable base, stripping any live capability fields. */
+export function setFrozenRequestContext(conversationId, context) {
+    if (!conversationId)
+        return;
+    remember(conversationId, requestContextBase(context));
+}
+/** Drop a conversation's frozen RequestContext (compaction / binding reset). */
+export function clearFrozenRequestContext(conversationId) {
+    byConversationId.delete(conversationId);
+    materializedByConversationId.delete(conversationId);
+}
+/**
+ * Move a stable workspace base across a conversation-id reset.
+ *
+ * Compaction changes Cursor's state/checkpoint identity, not the OpenCode
+ * workspace. Preserve the expensive base and the prior materialized bytes as a
+ * comparison seed; getOrBuildRequestContext still rediscovers live capability
+ * overlays and only reuses the complete context when those bytes also match.
+ */
+export function transferFrozenRequestContext(previousConversationId, nextConversationId) {
+    if (!previousConversationId || !nextConversationId)
+        return false;
+    const base = byConversationId.get(previousConversationId);
+    const materialized = materializedByConversationId.get(previousConversationId);
+    clearFrozenRequestContext(previousConversationId);
+    clearFrozenRequestContext(nextConversationId);
+    if (!base)
+        return false;
+    remember(nextConversationId, base);
+    if (materialized) {
+        materializedByConversationId.set(nextConversationId, {
+            context: materialized.context,
+            bytes: Uint8Array.from(materialized.bytes),
+        });
+    }
+    return true;
+}
+/** Test helper — wipe all frozen contexts. */
+export function resetFrozenRequestContextsForTests() {
+    byConversationId.clear();
+    materializedByConversationId.clear();
+    buildsByConversationId.clear();
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function rememberMaterialized(conversationId, context) {
+    const bytes = encodeMessage("RequestContext", context);
+    const previous = materializedByConversationId.get(conversationId);
+    if (previous && sameBytes(previous.bytes, bytes)) {
+        return { context: previous.context, reused: true };
+    }
+    const frozen = freezeSnapshot(structuredClone(context));
+    materializedByConversationId.set(conversationId, {
+        context: frozen,
+        bytes: Uint8Array.from(bytes),
+    });
+    return { context: frozen, reused: false };
+}
+/**
+ * Return a stable-base + live-overlay RequestContext for `conversationId`.
+ * The base is built once; capability sections are rediscovered every Run.
+ */
+export async function getOrBuildRequestContext(conversationId, input, opts) {
+    if (!opts?.refresh && conversationId) {
+        const base = getFrozenRequestContext(conversationId);
+        if (base) {
+            const dynamic = await buildDynamicRequestContext(input);
+            const materialized = rememberMaterialized(conversationId, materializeRequestContext(base, dynamic));
+            trace(`request_context: materialized conversationId=${conversationId} ` +
+                `tools=${Array.isArray(materialized.context.tools) ? materialized.context.tools.length : 0} ` +
+                `reused=${materialized.reused}`);
+            return materialized;
+        }
+    }
+    // Two overlapping model calls can open Runs for the same conversation. Share
+    // the first build so both Runs receive the same snapshot instead of racing
+    // two independently collected git/layout views into the cache.
+    if (!opts?.refresh && conversationId) {
+        const inFlight = buildsByConversationId.get(conversationId);
+        if (inFlight) {
+            await inFlight;
+            return getOrBuildRequestContext(conversationId, input);
+        }
+    }
+    const build = buildRequestContext(input);
+    if (conversationId)
+        buildsByConversationId.set(conversationId, build);
+    let context;
+    try {
+        context = await build;
+    }
+    finally {
+        if (conversationId && buildsByConversationId.get(conversationId) === build) {
+            buildsByConversationId.delete(conversationId);
+        }
+    }
+    if (conversationId)
+        setFrozenRequestContext(conversationId, context);
+    // The first full build already contains both base and live overlay.
+    const materialized = conversationId
+        ? rememberMaterialized(conversationId, context)
+        : { context: freezeSnapshot(structuredClone(context)), reused: false };
+    trace(`request_context: built+frozen conversationId=${conversationId || "(none)"} ` +
+        `tools=${Array.isArray(materialized.context.tools) ? materialized.context.tools.length : 0} ` +
+        `refresh=${!!opts?.refresh}`);
+    return { context: materialized.context, reused: false };
+}

package/dist/context/index.d.ts

@@ -1,2 +1,3 @@
-export { buildRequestContext, type BuildRequestContextInput } from "./build.js";
-export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";
+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 { HOST_PATH_BRIDGE, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, hostGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/index.js

@@ -1,2 +1,3 @@
-export { buildRequestContext } from "./build.js";
-export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";
+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 { 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.d.ts

@@ -9,6 +9,7 @@ export type OpencodeJson = {
     plugins?: string[];
     mcp?: Record<string, unknown>;
 };
+export declare function findGitWorktree(start: string): Promise<string>;
 /** Same truthy rule as OpenCode's Flag.OPENCODE_DISABLE_PROJECT_CONFIG. */
 export declare function isProjectConfigDisabled(): boolean;
 /** Fetch a remote instruction with one deadline covering headers and body. */

package/dist/context/rules.js

@@ -27,7 +27,7 @@ async function readJsonConfig(dir) {
     }
     return {};
 }
-async function findGitWorktree(start) {
+export async function findGitWorktree(start) {
     let dir = path.resolve(start);
     for (;;) {
         if (await exists(path.join(dir, ".git")))
@@ -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,
+};

package/dist/image-save.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Commit a staged Cursor image to disk, gated by OpenCode's own permission.
+ *
+ * Host-neutral on purpose: `./image-save-tool.ts` performs the `tool()` value
+ * import from `@opencode-ai/plugin`, which the OpenCode 2.0 entrypoint must not
+ * pull in (see the note in `./web-search-tool.ts`). Only that file may import
+ * the plugin package; this module is safe on every graph.
+ */
+/**
+ * Marks a refusal that must reach Cursor as `WriteResult.permission_denied`
+ * rather than a generic error — the variant its own executor returns and its
+ * agent branches on. Both sides of this string are ours, so matching on it is
+ * a contract, not a guess at someone else's message.
+ */
+export declare const IMAGE_PERMISSION_DENIED_PREFIX = "CursorImagePermissionDenied:";
+/** The subset of OpenCode's plugin ToolContext this needs. */
+export type ImageSaveToolContext = {
+    worktree: string;
+    directory: string;
+    ask(input: {
+        permission: string;
+        patterns: string[];
+        always: string[];
+        metadata: Record<string, unknown>;
+    }): Promise<void>;
+};
+export type ImageSaveResult = {
+    title: string;
+    output: string;
+    attachments?: Array<{
+        type: "file";
+        mime: string;
+        url: string;
+        filename?: string;
+    }>;
+};
+/**
+ * Prove the staged target still resolves inside one of the roots it was mapped
+ * into. `remapCursorImageWritePath` already chose the location; this re-checks
+ * it against the *real* paths, because a symlink planted between mapping and
+ * commit could otherwise redirect the write. Mirrors the containment rule the
+ * correlated-edit read applies before answering with complete file content.
+ */
+export declare function resolveContainedImagePath(target: string, allowedRoots: readonly string[]): {
+    path: string;
+    relative: string;
+    root: string;
+} | {
+    error: string;
+};
+/**
+ * Execute the commit. `image_id` is the only input: the path and bytes come
+ * from this process's staging table, so a caller without a real handle — the
+ * model of any provider, replaying a used id, or guessing — writes nothing.
+ */
+export declare function executeCursorImageSave(args: {
+    image_id?: unknown;
+}, ctx: ImageSaveToolContext): Promise<ImageSaveResult | string>;