cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/context/build.js

@@ -7,7 +7,8 @@ import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
 import { ensureOpencodeProjectDir } from "./paths.js";
 import { holdCapabilityOverlay } from "./overlay.js";
-import { traceRequestContextPaths } from "../debug.js";
+import { agentSkillsForCursor, applyAgentSkillsToContext, hostSkillFiles, loadBridgeSkills, skillToolAdvertised, } from "./skills.js";
+import { trace, traceRequestContextPaths } from "../debug.js";
 /** Rule name Cursor shows for the host system context (not a file). */
 export const SYSTEM_INSTRUCTIONS_RULE_PATH = "OpenCode system instructions";
 /**
@@ -74,8 +75,8 @@ export const DYNAMIC_REQUEST_CONTEXT_KEYS = [
     "hooks_additional_context",
 ];
 /**
- * The host system context (delivered as the system-instructions rule) already
- * carries these; never keep them on a frozen base.
+ * Derived from the system-instructions rule on every materialization (see
+ * `skills.ts`); never kept on a frozen base.
  */
 export const HOST_DUPLICATED_REQUEST_CONTEXT_KEYS = [
     "agent_skills",
@@ -94,6 +95,34 @@ function stripHostDuplicatedRequestContextFields(context) {
         delete context[key];
     keepSystemInstructionsRule(context);
 }
+/**
+ * How long one workspace's git and layout discovery serves later builds. A new
+ * session's first message opens two Runs moments apart (OpenCode's title
+ * request and the turn itself) on separate conversations; each froze its own
+ * copy, and `git status` dominates on a large repository (1.3 s warm on 35k
+ * tracked files; both discoveries of one observed session took about 5 s).
+ * Each conversation freezes what it got anyway.
+ */
+const WORKSPACE_FACTS_REUSE_MS = 30_000;
+const workspaceFacts = new Map();
+function collectWorkspaceFacts(workspaceRoot) {
+    const now = Date.now();
+    for (const [root, entry] of workspaceFacts) {
+        if (now - entry.at >= WORKSPACE_FACTS_REUSE_MS)
+            workspaceFacts.delete(root);
+    }
+    const cached = workspaceFacts.get(workspaceRoot);
+    if (cached) {
+        trace(`workspace facts: reused ageMs=${now - cached.at}`);
+        return cached.facts;
+    }
+    const facts = Promise.all([collectGit(workspaceRoot), collectProjectLayout(workspaceRoot)]);
+    workspaceFacts.set(workspaceRoot, { at: now, facts });
+    return facts;
+}
+export function resetWorkspaceFactsForTests() {
+    workspaceFacts.clear();
+}
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Workspace env/git/layout, the host system-instructions rule, and
@@ -103,10 +132,9 @@ function stripHostDuplicatedRequestContextFields(context) {
 export async function buildRequestContext(input) {
     const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());
     const config = input.mergedConfig ?? await loadMergedConfig(workspaceRoot);
-    const [dynamic, git, layout] = await Promise.all([
+    const [dynamic, [git, layout]] = await Promise.all([
         buildDynamicRequestContextFromDiscovery(input, workspaceRoot, config),
-        collectGit(workspaceRoot),
-        collectProjectLayout(workspaceRoot),
+        collectWorkspaceFacts(workspaceRoot),
     ]);
     const workspace = {
         env: buildEnv(workspaceRoot),
@@ -117,13 +145,29 @@ export async function buildRequestContext(input) {
         env_info_complete: true,
         repository_info_complete: true,
         git_repo_info_complete: true,
-        git_status_info_complete: true,
+        git_status_info_complete: git.statusComplete,
     };
     const base = withSystemInstructions(workspace, input.systemInstructions);
-    const ctx = materializeRequestContext(base, dynamic);
+    const skillLocations = await resolveSkillLocations(input, workspaceRoot);
+    const ctx = materializeRequestContext(base, dynamic, {
+        tools: input.tools,
+        ...skillLocations,
+    });
     traceRequestContextPaths("buildRequestContext", ctx);
     return ctx;
 }
+/** Locations for path-desc materialization (bridge, then remembered OC2 files). */
+export async function resolveSkillLocations(input, workspaceRoot) {
+    if (!skillToolAdvertised(input.tools))
+        return {};
+    return {
+        bridgeSkills: await loadBridgeSkills({
+            workspaceRoot,
+            sessionID: input.sessionID,
+        }),
+        skillFiles: hostSkillFiles(workspaceRoot),
+    };
+}
 async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, config) {
     const providerIdentifier = input.providerIdentifier ?? "opencode";
     const tools = input.tools ?? [];
@@ -184,8 +228,13 @@ export async function buildDynamicRequestContext(input) {
         : await loadMergedConfig(workspaceRoot);
     return buildDynamicRequestContextFromDiscovery(input, workspaceRoot, config);
 }
-/** Keep expensive workspace state frozen while replacing every live capability field. */
-export function materializeRequestContext(base, dynamic) {
+/**
+ * Keep expensive workspace state frozen while replacing every live capability
+ * field. Skill locations (bridge / OpenCode 2 files / OpenCode 1 catalog
+ * paths) turn the skill catalog in the system-instructions rule into Cursor's
+ * path-desc `agent_skills`.
+ */
+export function materializeRequestContext(base, dynamic, options) {
     const context = structuredClone(base);
     stripHostDuplicatedRequestContextFields(context);
     for (const key of DYNAMIC_REQUEST_CONTEXT_KEYS)
@@ -194,6 +243,12 @@ export function materializeRequestContext(base, dynamic) {
         if (Object.hasOwn(dynamic, key))
             context[key] = structuredClone(dynamic[key]);
     }
+    const skills = agentSkillsForCursor(systemInstructionsRuleText(context), {
+        skillToolAdvertised: skillToolAdvertised(options?.tools),
+        skillFiles: options?.skillFiles,
+        bridgeSkills: options?.bridgeSkills,
+    });
+    applyAgentSkillsToContext(context, skills);
     return context;
 }
 /** Strip live capability fields before retaining/persisting a conversation base. */

package/dist/context/dynamic-catalog.js

@@ -64,7 +64,12 @@ export function buildDynamicCatalogRoutingInstruction(options) {
         `- OpenCode host tools that are not in Cursor's native top-level list (including ${extras.join(" and ")}) ` +
             "are reached through GetDynamicTools / CallDynamicTool (or the host's equivalent dynamic catalog). " +
             "When a skill matches or project rules name an MCP server, discover and call those tools that way " +
-            "before Grep/Shell fallbacks. Do not narrate that they are unavailable.",
+            "before Grep/Shell fallbacks. Do not narrate that they are unavailable. " +
+            // Cursor's server answers lookups and calls in its own `cursor` namespace
+            // (built-in tools such as GenerateImage) and rejects any other name there.
+            `Host tools are in namespace \`${DEFAULT_TOOL_SERVER}\`` +
+            (mcpServers.length > 0 ? " and MCP tools in their server's namespace" : "") +
+            "; namespace `cursor` holds only Cursor's built-in tools.",
     ];
     if (hasSkill) {
         // Mirror OpenCode 1 SystemPrompt.skills / OC2 SkillInstructions.render.

package/dist/context/env.js

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

package/dist/context/epoch.js

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

package/dist/context/frozen.js

@@ -1,4 +1,4 @@
-import { buildDynamicRequestContext, buildRequestContext, materializeRequestContext, requestContextBase, withSystemInstructions, } from "./build.js";
+import { buildDynamicRequestContext, buildRequestContext, materializeRequestContext, requestContextBase, resolveSkillLocations, withSystemInstructions, } from "./build.js";
 import { clearContextEpoch, endContextEpoch, resetContextEpochsForTests } from "./epoch.js";
 import { clearOverlayHold, resetOverlayHoldsForTests, transferOverlayHold, } from "./overlay.js";
 import { trace } from "../debug.js";
@@ -174,7 +174,11 @@ export async function getOrBuildRequestContext(conversationId, input, opts) {
                     `authoritative=${input.systemInstructions?.authoritative ?? false}`);
             }
             const dynamic = await buildDynamicRequestContext(scoped);
-            const materialized = rememberMaterialized(conversationId, materializeRequestContext(base, dynamic));
+            const skillLocations = await resolveSkillLocations(scoped, scoped.workspaceRoot);
+            const materialized = rememberMaterialized(conversationId, materializeRequestContext(base, dynamic, {
+                tools: scoped.tools,
+                ...skillLocations,
+            }));
             trace(`request_context: materialized conversationId=${conversationId} ` +
                 `tools=${advertisedMetaToolCount(materialized.context)} ` +
                 `reused=${materialized.reused}`);

package/dist/context/git.d.ts

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

package/dist/context/git.js

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

package/dist/context/index.d.ts

@@ -4,3 +4,5 @@ export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestCo
 export { MAX_OVERLAY_HOLDS, holdCapabilityOverlay, resetOverlayHoldsForTests, } from "./overlay.js";
 export { admitContextEpoch, appendMidConversationMessage, clearContextEpoch, endContextEpoch, getContextEpoch, MAX_CONTEXT_EPOCHS, resetContextEpochsForTests, type AdmitContextEpochInput, type AdmitContextEpochResult, type ContextEpoch, type ContextSourceSnapshot, } from "./epoch.js";
 export { HOST_PATH_BRIDGE, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, hostGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";
+export { HOST_SKILLS_BRIDGE, setHostSkillsBridgeForTests, type HostSkill, type OpenCodeSkillsBridge, } from "./skills-bridge.js";
+export { agentSkillsForCursor, hostSkillFiles, rememberHostSkillFiles, resetHostSkillFilesForTests, skillToolAdvertised, } from "./skills.js";

package/dist/context/index.js

@@ -4,3 +4,5 @@ export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestCo
 export { MAX_OVERLAY_HOLDS, holdCapabilityOverlay, resetOverlayHoldsForTests, } from "./overlay.js";
 export { admitContextEpoch, appendMidConversationMessage, clearContextEpoch, endContextEpoch, getContextEpoch, MAX_CONTEXT_EPOCHS, resetContextEpochsForTests, } from "./epoch.js";
 export { HOST_PATH_BRIDGE, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, hostGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";
+export { HOST_SKILLS_BRIDGE, setHostSkillsBridgeForTests, } from "./skills-bridge.js";
+export { agentSkillsForCursor, hostSkillFiles, rememberHostSkillFiles, resetHostSkillFilesForTests, skillToolAdvertised, } from "./skills.js";

package/dist/context/paths.d.ts

@@ -9,7 +9,31 @@ export type OpenCodePathBridge = {
     /** Optional host-owned cache root; absent means native OpenCode defaults. */
     globalCacheDir?: () => string;
     configFileNames?: string[];
+    /**
+     * Optional host plan file for a session (the host's own plan location, which
+     * its `plan_exit` review reads). Absent on an installed bridge means the host
+     * defines none; without a bridge OpenCode's own location applies.
+     */
+    planFile?: (input: {
+        worktree: string;
+        vcs: boolean;
+        created: number;
+        slug: string;
+    }) => string | undefined;
 };
+/**
+ * The plan file of a session: OpenCode's own `Session.plan` location
+ * (`<worktree>/.opencode/plans` in a VCS project, else `<data>/plans`, named
+ * `<created>-<slug>.md`), which its plan agent and `plan_exit` use. An injected
+ * host path bridge owns host paths, so with one installed only its `planFile`
+ * defines the location.
+ */
+export declare function hostPlanFilePath(input: {
+    worktree: string;
+    vcs: boolean;
+    created: number;
+    slug: string;
+}, env?: HostPathEnv): string | undefined;
 export declare function opencodeProjectConfigDirs(workspaceRoot: string): string[];
 export declare function opencodeGlobalConfigDirs(): string[];
 export declare function opencodeConfigFileNames(): string[];
@@ -41,25 +65,28 @@ export declare function opencodeGlobalDataDir(env?: HostPathEnv): string;
 /** Host-portable durable data root; falls back to native OpenCode. */
 export declare function hostGlobalDataDir(env?: HostPathEnv): string;
 /**
- * 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.
+ * Select the entrypoint's native OpenCode plan directory. OpenCode 2.0 sets its
+ * Plan directory ({@link opencode2PlanDir}); OpenCode 1.x keeps the default.
+ * The returned disposer removes only this selection, so an older plugin setup
+ * disposed after a newer one leaves the newer selection in place. `undefined`
+ * removes all.
+ */
+export declare function setNativePlansDir(dir: string | undefined): () => void;
+/**
+ * OpenCode 2.0's Plan directory: `<home>/.opencode/plan`, where its Plan agent
+ * may write plan files (home is `OPENCODE_TEST_HOME`, else the OS home).
+ */
+export declare function opencode2PlanDir(env?: HostPathEnv): string;
+/**
+ * Directory for a new plan file when the session's own plan file
+ * ({@link hostPlanFilePath}) is not known.
  *
- * 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.
+ * An injected host path bridge owns host paths: `<globalDataDir()>/plans`.
+ * Otherwise the native OpenCode location of the running entrypoint: OpenCode
+ * 2.0's Plan directory, or OpenCode 1.x's no-VCS `Session.plan` base
+ * (`<data>/plans`).
  */
-export declare function hostPlansDir(_workspaceRoot?: string): string;
+export declare function hostPlansDir(_workspaceRoot?: string, env?: HostPathEnv): string;
 /**
  * Cursor-compatible path slug (`/workspace/a/b` → `workspace-a-b`).
  * Used for per-workspace metadata under the host cache.
@@ -70,7 +97,7 @@ export declare function slugifyWorkspacePath(workspaceRoot: string): string;
  * Lives at `<host-cache>/projects/<slug>/` under the resolved OpenCode/host cache root.
  *
  * This is what Cursor's RequestContextEnv.project_folder / MCP
- * workspace_project_dir point at — agent-tools, terminals, transcripts, etc.
+ * workspace_project_dir point at — agent-tools, terminals, assets, etc.
  * Must NOT be the git workspace, or those dumps land in the repo.
  */
 export declare function opencodeProjectDir(workspaceRoot: string): string;

package/dist/context/paths.js

@@ -27,6 +27,31 @@ function bridgeGlobalDataDir() {
     const value = pathBridge()?.globalDataDir?.();
     return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
 }
+/**
+ * The plan file of a session: OpenCode's own `Session.plan` location
+ * (`<worktree>/.opencode/plans` in a VCS project, else `<data>/plans`, named
+ * `<created>-<slug>.md`), which its plan agent and `plan_exit` use. An injected
+ * host path bridge owns host paths, so with one installed only its `planFile`
+ * defines the location.
+ */
+export function hostPlanFilePath(input, env = process.env) {
+    const bridge = pathBridge();
+    if (bridge) {
+        if (typeof bridge.planFile !== "function")
+            return undefined;
+        const value = bridge.planFile(input);
+        return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
+    }
+    const slug = input.slug.trim();
+    if (!slug || slug.includes("/") || slug.includes("\\") || slug.startsWith("."))
+        return undefined;
+    if (!Number.isSafeInteger(input.created) || input.created <= 0)
+        return undefined;
+    const base = input.vcs
+        ? path.join(path.resolve(input.worktree), ".opencode", "plans")
+        : path.join(openCodeGlobalDataDir(env), "plans");
+    return path.join(base, `${input.created}-${slug}.md`);
+}
 function bridgeGlobalCacheDir() {
     const value = pathBridge()?.globalCacheDir?.();
     return typeof value === "string" && value.length > 0 ? path.resolve(value) : undefined;
@@ -102,27 +127,49 @@ export function opencodeGlobalDataDir(env = process.env) {
 export function hostGlobalDataDir(env = process.env) {
     return bridgeGlobalDataDir() ?? openCodeGlobalDataDir(env);
 }
+/** Entrypoint plan directories, newest last (see {@link setNativePlansDir}). */
+const nativePlansDirs = [];
 /**
- * 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.
+ * Select the entrypoint's native OpenCode plan directory. OpenCode 2.0 sets its
+ * Plan directory ({@link opencode2PlanDir}); OpenCode 1.x keeps the default.
+ * The returned disposer removes only this selection, so an older plugin setup
+ * disposed after a newer one leaves the newer selection in place. `undefined`
+ * removes all.
+ */
+export function setNativePlansDir(dir) {
+    if (!dir) {
+        nativePlansDirs.length = 0;
+        return () => { };
+    }
+    const entry = { dir: path.resolve(dir) };
+    nativePlansDirs.push(entry);
+    return () => {
+        const index = nativePlansDirs.lastIndexOf(entry);
+        if (index >= 0)
+            nativePlansDirs.splice(index, 1);
+    };
+}
+/**
+ * OpenCode 2.0's Plan directory: `<home>/.opencode/plan`, where its Plan agent
+ * may write plan files (home is `OPENCODE_TEST_HOME`, else the OS home).
+ */
+export function opencode2PlanDir(env = process.env) {
+    return path.join(env.OPENCODE_TEST_HOME ?? homedir(), ".opencode", "plan");
+}
+/**
+ * Directory for a new plan file when the session's own plan file
+ * ({@link hostPlanFilePath}) is not known.
  *
- * 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.
+ * An injected host path bridge owns host paths: `<globalDataDir()>/plans`.
+ * Otherwise the native OpenCode location of the running entrypoint: OpenCode
+ * 2.0's Plan directory, or OpenCode 1.x's no-VCS `Session.plan` base
+ * (`<data>/plans`).
  */
-export function hostPlansDir(_workspaceRoot) {
-    return path.join(hostGlobalDataDir(), "plans");
+export function hostPlansDir(_workspaceRoot, env = process.env) {
+    const bridged = bridgeGlobalDataDir();
+    if (bridged)
+        return path.join(bridged, "plans");
+    return nativePlansDirs[nativePlansDirs.length - 1]?.dir ?? path.join(openCodeGlobalDataDir(env), "plans");
 }
 /**
  * Cursor-compatible path slug (`/workspace/a/b` → `workspace-a-b`).
@@ -141,17 +188,20 @@ export function slugifyWorkspacePath(workspaceRoot) {
  * Lives at `<host-cache>/projects/<slug>/` under the resolved OpenCode/host cache root.
  *
  * This is what Cursor's RequestContextEnv.project_folder / MCP
- * workspace_project_dir point at — agent-tools, terminals, transcripts, etc.
+ * workspace_project_dir point at — agent-tools, terminals, assets, etc.
  * Must NOT be the git workspace, or those dumps land in the repo.
  */
 export function opencodeProjectDir(workspaceRoot) {
     const projectsRoot = path.join(opencodeGlobalCacheDir(), "projects");
     const slug = slugifyWorkspacePath(workspaceRoot);
-    let dir = path.join(projectsRoot, slug);
-    // Mirror Cursor's long-path guard so nested agent-tools paths stay usable.
+    const dir = path.join(projectsRoot, slug);
+    // Keep nested agent-tools paths short by cutting the name to 84 characters.
+    // While that cut falls after `projects/`, it only shortens the slug, and it
+    // is the name existing folders already have. With a longer root it would
+    // fall inside the root, so the folder is named by the hash alone.
     if (dir.length > 92) {
         const hash = createHash("sha256").update(dir).digest("hex").slice(0, 7);
-        dir = `${dir.slice(0, Math.min(84, dir.length))}-${hash}`;
+        return projectsRoot.length < 84 ? `${dir.slice(0, 84)}-${hash}` : path.join(projectsRoot, hash);
     }
     return dir;
 }

package/dist/context/skills-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Structural host-skills capability installed before an unchanged provider loads.
+ * Same install timing as `opencode.host.path-bridge`.
+ */
+export declare const HOST_SKILLS_BRIDGE: unique symbol;
+/** One host catalog skill the provider may advertise to Cursor. */
+export type HostSkill = {
+    name: string;
+    id?: string;
+    description: string;
+    /** Absolute path, `file:` URL, or host URI (`skill://…`). Omit built-ins / markers. */
+    location?: string;
+};
+export type OpenCodeSkillsBridge = {
+    list(input: {
+        directory: string;
+        sessionID?: string;
+    }): Promise<HostSkill[]>;
+};
+export declare function skillsBridge(): OpenCodeSkillsBridge | undefined;
+/** Test helper: install or clear the structural skills bridge. */
+export declare function setHostSkillsBridgeForTests(bridge: OpenCodeSkillsBridge | undefined): void;

package/dist/context/skills-bridge.js

@@ -0,0 +1,20 @@
+/**
+ * Structural host-skills capability installed before an unchanged provider loads.
+ * Same install timing as `opencode.host.path-bridge`.
+ */
+export const HOST_SKILLS_BRIDGE = Symbol.for("opencode.host.skills");
+export function skillsBridge() {
+    const value = globalThis[HOST_SKILLS_BRIDGE];
+    if (!value || typeof value !== "object")
+        return undefined;
+    const bridge = value;
+    return typeof bridge.list === "function" ? bridge : undefined;
+}
+/** Test helper: install or clear the structural skills bridge. */
+export function setHostSkillsBridgeForTests(bridge) {
+    const globals = globalThis;
+    if (bridge)
+        globals[HOST_SKILLS_BRIDGE] = bridge;
+    else
+        delete globals[HOST_SKILLS_BRIDGE];
+}

package/dist/context/skills.d.ts

@@ -0,0 +1,34 @@
+import type { OpencodeToolDef } from "../protocol/tools.js";
+import { type HostSkill } from "./skills-bridge.js";
+export type HostSkillFileEntry = {
+    readonly id: string;
+    readonly path: string;
+};
+export type AgentSkillWire = {
+    readonly full_path: string;
+    readonly description: string;
+};
+/** Locations Cursor can advertise; markers / builtins are omitted. */
+export declare function isUsableSkillLocation(location: string | undefined): boolean;
+export declare function normalizeSkillLocation(location: string): string;
+export declare function skillToolAdvertised(tools: readonly OpencodeToolDef[] | undefined): boolean;
+/** Record skill files a Location's host currently registers (OpenCode 2 plugin). */
+export declare function rememberHostSkillFiles(directory: string, skills: readonly HostSkillFileEntry[]): void;
+export declare function hostSkillFiles(directory: string | undefined): ReadonlyMap<string, string> | undefined;
+/** Test helper. */
+export declare function resetHostSkillFilesForTests(): void;
+/**
+ * path-desc `agent_skills` for cataloged skills that have a usable location,
+ * in catalog order. Descriptions come from the catalog (epoch-stable).
+ */
+export declare function agentSkillsForCursor(systemText: string | undefined, options: {
+    skillToolAdvertised: boolean;
+    skillFiles?: ReadonlyMap<string, string>;
+    bridgeSkills?: readonly HostSkill[];
+}): AgentSkillWire[];
+/** Fetch locations from the structural bridge when installed. */
+export declare function loadBridgeSkills(input: {
+    workspaceRoot: string;
+    sessionID?: string;
+}): Promise<HostSkill[] | undefined>;
+export declare function applyAgentSkillsToContext(context: Record<string, unknown>, skills: readonly AgentSkillWire[]): void;