cursor-opencode-provider 0.7.6 → 0.8.1

package/dist/context/build.d.ts

@@ -1,5 +1,6 @@
 import { type OpencodeToolDef } from "../protocol/tools.js";
 import { type OpencodeJson } from "./rules.js";
+import { hostSkillFiles, loadBridgeSkills } from "./skills.js";
 export type BuildRequestContextInput = {
     workspaceRoot: string;
     tools?: OpencodeToolDef[];
@@ -11,20 +12,74 @@ export type BuildRequestContextInput = {
      * guidance MCP server ids). Skips a second `loadMergedConfig` disk read.
      */
     mergedConfig?: OpencodeJson;
+    /** Host system context to deliver as the frozen system-instructions rule. */
+    systemInstructions?: SystemInstructions;
+    /** Optional host session id for `opencode.host.skills` list(). */
+    sessionID?: string;
 };
-export declare const DYNAMIC_REQUEST_CONTEXT_KEYS: readonly ["tools", "agent_skills", "custom_subagents", "mcp_file_system_options", "mcp_meta_tool_options", "web_search_enabled", "web_fetch_enabled", "agent_skills_info_complete", "custom_subagents_info_complete", "mcp_file_system_info_complete", "mcp_info_complete", "hooks_additional_context"];
+/**
+ * Host system context (OpenCode's system prompt plus this provider's
+ * interaction guidance) for one Cursor conversation.
+ */
+export type SystemInstructions = {
+    text: string;
+    /**
+     * True when `text` is this conversation's own frozen baseline (a Context
+     * Epoch started in this process, or an ephemeral Run's prompt): it replaces
+     * any rule already frozen. False when a restart recovered the epoch without
+     * its bytes: the persisted rule wins and `text` only fills a missing one.
+     */
+    authoritative: boolean;
+};
+/** Rule name Cursor shows for the host system context (not a file). */
+export declare const SYSTEM_INSTRUCTIONS_RULE_PATH = "OpenCode system instructions";
+/**
+ * Cursor does not follow a client-seeded `system` message, and applies a rule
+ * only by its type. The Cursor CLI sends AGENTS.md as `alwaysApply`
+ * (`CursorRuleType.global`) and the IDE ships its own guidance as a non-file
+ * global rule; the host system context goes out the same way, once, frozen
+ * with the RequestContext base.
+ */
+export declare function systemInstructionsRule(text: string): Record<string, unknown>;
+/** Text of the frozen system-instructions rule, if the context carries one. */
+export declare function systemInstructionsRuleText(context: Record<string, unknown>): string | undefined;
+/**
+ * Return `context` with the system-instructions rule applied, or the same
+ * object when nothing changes (see `SystemInstructions.authoritative`).
+ */
+export declare function withSystemInstructions(context: Record<string, unknown>, instructions: SystemInstructions | undefined): Record<string, unknown>;
+export declare const DYNAMIC_REQUEST_CONTEXT_KEYS: readonly ["tools", "custom_subagents", "mcp_file_system_options", "mcp_meta_tool_options", "web_search_enabled", "web_fetch_enabled", "custom_subagents_info_complete", "mcp_file_system_info_complete", "mcp_info_complete", "hooks_additional_context"];
 export type DynamicRequestContextKey = typeof DYNAMIC_REQUEST_CONTEXT_KEYS[number];
+/**
+ * Derived from the system-instructions rule on every materialization (see
+ * `skills.ts`); never kept on a frozen base.
+ */
+export declare const HOST_DUPLICATED_REQUEST_CONTEXT_KEYS: readonly ["agent_skills", "agent_skills_info_complete"];
 /**
  * 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. 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.
+ * Workspace env/git/layout, the host system-instructions rule, and
+ * host-advertised tools and subagents. The provider never looks in Cursor's
+ * own directories.
  */
 export declare function buildRequestContext(input: BuildRequestContextInput): Promise<Record<string, unknown>>;
+/** Locations for path-desc materialization (bridge, then remembered OC2 files). */
+export declare function resolveSkillLocations(input: Pick<BuildRequestContextInput, "tools" | "sessionID">, workspaceRoot: string): Promise<{
+    bridgeSkills?: Awaited<ReturnType<typeof loadBridgeSkills>>;
+    skillFiles?: ReturnType<typeof hostSkillFiles>;
+}>;
 /** Rediscover only capability/plugin sections that may change during a chat. */
 export declare function buildDynamicRequestContext(input: BuildRequestContextInput): Promise<Record<string, unknown>>;
-/** Keep expensive workspace state frozen while replacing every live capability field. */
-export declare function materializeRequestContext(base: Record<string, unknown>, dynamic: Record<string, unknown>): Record<string, unknown>;
+export type MaterializeRequestContextOptions = {
+    tools?: OpencodeToolDef[];
+    skillFiles?: ReadonlyMap<string, string>;
+    bridgeSkills?: Awaited<ReturnType<typeof loadBridgeSkills>>;
+};
+/**
+ * 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 declare function materializeRequestContext(base: Record<string, unknown>, dynamic: Record<string, unknown>, options?: MaterializeRequestContextOptions): Record<string, unknown>;
 /** Strip live capability fields before retaining/persisting a conversation base. */
 export declare function requestContextBase(context: Record<string, unknown>): Record<string, unknown>;

package/dist/context/build.js

@@ -1,84 +1,116 @@
 import path from "node:path";
-import { extractHostSubagentCatalog, toolsToDescriptors, toolsToMcpDescriptors, } from "../protocol/tools.js";
-import { collectRules, findGitWorktree, loadMergedConfig, } from "./rules.js";
-import { collectSkills } from "./skills.js";
-import { collectAgents } from "./agents.js";
+import { extractHostSubagentCatalog, toolsToMcpDescriptors, } from "../protocol/tools.js";
+import { loadMergedConfig, } from "./rules.js";
 import { collectPlugins } from "./plugins.js";
 import { collectGit } from "./git.js";
 import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
 import { ensureOpencodeProjectDir } from "./paths.js";
 import { holdCapabilityOverlay } from "./overlay.js";
+import { agentSkillsForCursor, applyAgentSkillsToContext, hostSkillFiles, loadBridgeSkills, skillToolAdvertised, } from "./skills.js";
 import { 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";
+/**
+ * Cursor does not follow a client-seeded `system` message, and applies a rule
+ * only by its type. The Cursor CLI sends AGENTS.md as `alwaysApply`
+ * (`CursorRuleType.global`) and the IDE ships its own guidance as a non-file
+ * global rule; the host system context goes out the same way, once, frozen
+ * with the RequestContext base.
+ */
+export function systemInstructionsRule(text) {
+    return {
+        full_path: SYSTEM_INSTRUCTIONS_RULE_PATH,
+        content: text,
+        type: { global: {} },
+    };
+}
+function isSystemInstructionsRule(rule) {
+    if (!rule || typeof rule !== "object")
+        return false;
+    const record = rule;
+    const type = record.type;
+    return record.full_path === SYSTEM_INSTRUCTIONS_RULE_PATH && !!type?.global
+        && typeof record.content === "string";
+}
+/** Text of the frozen system-instructions rule, if the context carries one. */
+export function systemInstructionsRuleText(context) {
+    const rules = Array.isArray(context.rules) ? context.rules : [];
+    const rule = rules.find(isSystemInstructionsRule);
+    return rule ? rule.content : undefined;
+}
+/**
+ * Return `context` with the system-instructions rule applied, or the same
+ * object when nothing changes (see `SystemInstructions.authoritative`).
+ */
+export function withSystemInstructions(context, instructions) {
+    const text = instructions?.text.trim() ? instructions.text : undefined;
+    if (!text)
+        return context;
+    const current = systemInstructionsRuleText(context);
+    if (current !== undefined && (current === text || !instructions.authoritative))
+        return context;
+    return { ...context, rules: [systemInstructionsRule(text)] };
+}
+/** Keep only the system-instructions rule; older bases carried untyped rules Cursor never applied. */
+function keepSystemInstructionsRule(context) {
+    if (!Object.hasOwn(context, "rules"))
+        return;
+    const rules = Array.isArray(context.rules) ? context.rules.filter(isSystemInstructionsRule) : [];
+    if (rules.length > 0)
+        context.rules = rules.slice(0, 1);
+    else
+        delete context.rules;
+}
 export const DYNAMIC_REQUEST_CONTEXT_KEYS = [
     "tools",
-    "agent_skills",
     "custom_subagents",
     "mcp_file_system_options",
     "mcp_meta_tool_options",
     "web_search_enabled",
     "web_fetch_enabled",
-    "agent_skills_info_complete",
     "custom_subagents_info_complete",
     "mcp_file_system_info_complete",
     "mcp_info_complete",
     "hooks_additional_context",
 ];
-const DEFAULT_HOST_SUBAGENTS = [
-    {
-        name: "general",
-        description: "General-purpose agent for complex research and multi-step tasks.",
-    },
-    {
-        name: "explore",
-        description: "Read-only agent for searching and understanding the local codebase.",
-    },
+/**
+ * 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",
+    "agent_skills_info_complete",
 ];
 /**
- * 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 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.
- *
- * `custom_subagents_info_complete` must describe the final advertised list, not
- * the raw extraction source. If there is no executor, the empty list is
- * complete. If the host catalog is complete, use it verbatim. Otherwise we make
- * the advertised set complete by augmenting with default host agents and all
- * locally discovered agents.
+ * Advertise only what the host `task` / `subagent` catalog already named.
  */
-function buildAdvertisedSubagentCatalog(hostSubagents, discoveredAgents) {
+function buildAdvertisedSubagentCatalog(hostSubagents) {
     if (!hostSubagents.executor)
         return { agents: [], complete: true };
-    if (hostSubagents.complete)
-        return { agents: hostSubagents.agents, complete: true };
-    return {
-        agents: [...DEFAULT_HOST_SUBAGENTS, ...hostSubagents.agents, ...discoveredAgents],
-        complete: true,
-    };
+    return { agents: hostSubagents.agents, complete: hostSubagents.complete };
+}
+function stripHostDuplicatedRequestContextFields(context) {
+    for (const key of HOST_DUPLICATED_REQUEST_CONTEXT_KEYS)
+        delete context[key];
+    keepSystemInstructionsRule(context);
 }
 /**
  * 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. 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.
+ * Workspace env/git/layout, the host system-instructions rule, and
+ * host-advertised tools and subagents. The provider never looks in Cursor's
+ * own directories.
  */
 export async function buildRequestContext(input) {
     const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());
-    const { rules, config, worktree } = await collectRules(workspaceRoot, input.mergedConfig);
+    const config = input.mergedConfig ?? await loadMergedConfig(workspaceRoot);
     const [dynamic, git, layout] = await Promise.all([
-        buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config),
+        buildDynamicRequestContextFromDiscovery(input, workspaceRoot, config),
         collectGit(workspaceRoot),
         collectProjectLayout(workspaceRoot),
     ]);
-    const base = {
+    const workspace = {
         env: buildEnv(workspaceRoot),
-        rules: rules.map((r) => ({
-            full_path: r.fullPath,
-            content: r.content,
-        })),
         repository_info: git.repositoryInfo,
         git_repos: git.gitRepos,
         project_layouts: [layout],
@@ -88,47 +120,41 @@ export async function buildRequestContext(input) {
         git_repo_info_complete: true,
         git_status_info_complete: true,
     };
-    const ctx = materializeRequestContext(base, dynamic);
+    const base = withSystemInstructions(workspace, input.systemInstructions);
+    const skillLocations = await resolveSkillLocations(input, workspaceRoot);
+    const ctx = materializeRequestContext(base, dynamic, {
+        tools: input.tools,
+        ...skillLocations,
+    });
     traceRequestContextPaths("buildRequestContext", ctx);
     return ctx;
 }
-async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config) {
+/** 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 ?? [];
-    const [skills, agents, plugins] = await Promise.all([
-        collectSkills(workspaceRoot, worktree),
-        collectAgents(workspaceRoot),
-        collectPlugins(workspaceRoot, config),
-    ]);
+    const plugins = await collectPlugins(workspaceRoot, config);
     const mcpServerNames = Object.keys(config.mcp ?? {});
-    const flat = toolsToDescriptors(tools, providerIdentifier, mcpServerNames);
-    const nested = toolsToMcpDescriptors(tools, providerIdentifier, mcpServerNames);
+    const slim = toolsToMcpDescriptors(tools, providerIdentifier, mcpServerNames, { namesOnly: true });
     const projectDir = ensureOpencodeProjectDir(workspaceRoot);
     const hostSubagents = extractHostSubagentCatalog(tools);
-    const advertisedSubagents = buildAdvertisedSubagentCatalog(hostSubagents, agents);
-    const discoveredByName = new Map(agents.map((agent) => [agent.name, agent]));
-    const advertisedByName = new Map();
-    for (const agent of advertisedSubagents.agents) {
-        if (!advertisedByName.has(agent.name))
-            advertisedByName.set(agent.name, agent);
-    }
-    const customSubagents = [...advertisedByName.values()].map((agent) => {
-        const discovered = discoveredByName.get(agent.name);
-        return {
-            full_path: discovered?.fullPath ?? "",
-            name: agent.name,
-            description: discovered?.description || agent.description || "Host-configured subagent.",
-            // The host applies the real configured prompt when Task/Actor executes.
-            // Cursor only needs enough context to select the recipient intentionally.
-            prompt: discovered?.prompt ||
-                `Delegate to the host-configured ${agent.name} subagent; its host instructions and tools apply.`,
-        };
-    });
-    const liveSkills = skills.map((s) => ({
-        id: s.name,
-        full_path: s.fullPath,
-        content: s.content,
-        description: s.description,
+    const advertisedSubagents = buildAdvertisedSubagentCatalog(hostSubagents);
+    const customSubagents = advertisedSubagents.agents.map((agent) => ({
+        full_path: "",
+        name: agent.name,
+        description: agent.description || "Host-configured subagent.",
+        prompt: `Delegate to the host-configured ${agent.name} subagent; its host instructions and tools apply.`,
     }));
     const livePlugins = plugins.map((p) => ({
         id: p.id,
@@ -136,24 +162,19 @@ async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, wor
     }));
     const overlay = input.conversationId
         ? holdCapabilityOverlay(input.conversationId, {
-            skills: liveSkills,
             subagents: customSubagents,
             plugins: livePlugins,
         })
-        : { skills: liveSkills.map(({ full_path, content, description }) => ({ full_path, content, description })), subagents: customSubagents, plugins: livePlugins };
+        : { subagents: customSubagents, plugins: livePlugins };
     const dynamic = {
-        tools: flat,
-        agent_skills: overlay.skills,
-        custom_subagents: overlay.subagents,
         mcp_file_system_options: {
             enabled: true,
             // Cursor metadata root (mcps / agent-tools), not the git workspace.
             workspace_project_dir: projectDir,
-            mcp_descriptors: nested,
         },
         mcp_meta_tool_options: {
             enabled: true,
-            mcp_descriptors: nested,
+            ...(slim.length > 0 ? { mcp_descriptors: slim } : {}),
         },
         // This provider always rejects native web_search/web_fetch interaction
         // queries with a headless-UI reason (see interactions.ts). Advertise that
@@ -161,11 +182,12 @@ async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, wor
         // custom_web* aliases instead of routing through a query doomed to fail.
         web_search_enabled: false,
         web_fetch_enabled: false,
-        agent_skills_info_complete: true,
         custom_subagents_info_complete: advertisedSubagents.complete,
         mcp_file_system_info_complete: true,
         mcp_info_complete: true,
     };
+    if (overlay.subagents.length > 0)
+        dynamic.custom_subagents = overlay.subagents;
     if (overlay.plugins.length > 0) {
         dynamic.hooks_additional_context = overlay.plugins.map((p) => p.line).join("\n");
     }
@@ -174,28 +196,38 @@ async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, wor
 /** Rediscover only capability/plugin sections that may change during a chat. */
 export async function buildDynamicRequestContext(input) {
     const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());
-    const [worktree, config] = await Promise.all([
-        findGitWorktree(workspaceRoot),
-        input.mergedConfig
-            ? Promise.resolve(input.mergedConfig)
-            : loadMergedConfig(workspaceRoot),
-    ]);
-    return buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config);
+    const config = input.mergedConfig
+        ? input.mergedConfig
+        : 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)
         delete context[key];
     for (const key of DYNAMIC_REQUEST_CONTEXT_KEYS) {
         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. */
 export function requestContextBase(context) {
     const base = structuredClone(context);
+    stripHostDuplicatedRequestContextFields(base);
     for (const key of DYNAMIC_REQUEST_CONTEXT_KEYS)
         delete base[key];
     return base;

package/dist/context/dynamic-catalog.d.ts

@@ -1,10 +1,3 @@
-export type AgentSkillLike = {
-    /** OpenCode skill id (frontmatter `name`, else directory name). */
-    id?: unknown;
-    full_path?: unknown;
-    description?: unknown;
-    content?: unknown;
-};
 /**
  * Configured MCP servers that own at least one advertised tool. Uses the same
  * server resolution as the RequestContext descriptors, so guidance never names
@@ -12,63 +5,14 @@ export type AgentSkillLike = {
  * `sourceName` when present).
  */
 export declare function listAdvertisedMcpServers(toolNames: Iterable<string>, knownMcpServers?: Iterable<string>): string[];
-/** Skill id OpenCode's `skill` tool expects: the discovered id, else `…/skills/<id>/SKILL.md`. */
-export declare function skillNameFromAgentSkill(skill: AgentSkillLike): string | undefined;
 /**
  * Shared system-guidance line: name advertised dynamic-catalog tools and prefer
  * them over Grep/Shell when skills or project rules apply. Concrete skill ids
- * stay out of the frozen baseline (they live in RequestContext `agent_skills`
- * and in Mid-Conversation updates when the catalog changes — same split as
+ * stay out of the frozen baseline (they live in the host system prompt / skill
+ * tool, and in host `<system-update>` when the catalog changes — same split as
  * OpenCode's SkillGuidance / SkillInstructions).
  */
 export declare function buildDynamicCatalogRoutingInstruction(options: {
     toolNames: Iterable<string>;
     knownMcpServers?: Iterable<string>;
 }): string | undefined;
-/**
- * OpenCode-shaped Mid-Conversation skill update.
- *
- * Pure: compare `previousSkillIds` (null = not yet admitted this conversation)
- * to the current catalog. First admission returns undefined — baseline
- * RequestContext + routing instruction already carry the list. Later turns
- * only speak when the id set changes (agent switch / discovery growth), matching
- * `SkillGuidance.update` / `SkillInstructions.update`.
- */
-export declare function buildSkillCatalogChangeReminder(options: {
-    hasSkillTool: boolean;
-    skills: readonly AgentSkillLike[];
-    /** Sorted skill ids already admitted; `null` means first admission this conversation. */
-    previousSkillIds: readonly string[] | null;
-    /**
-     * Host skill parameter key from the advertised schema.
-     * OpenCode 1.x: `name`. OpenCode 2.0: `id`.
-     */
-    skillArgKey?: "name" | "id";
-}): {
-    text: string | undefined;
-    nextSkillIds: string[];
-};
-/**
- * Admit the current skill catalog for a conversation and return a Mid-Conversation
- * reminder only when OpenCode would (catalog changed after baseline admission).
- */
-export declare function takeSkillCatalogChangeReminder(conversationId: string, options: {
-    hasSkillTool: boolean;
-    skills: readonly AgentSkillLike[];
-    skillArgKey?: "name" | "id";
-}): string | undefined;
-export declare function clearSkillCatalogAdmission(conversationId: string): void;
-export declare function transferSkillCatalogAdmission(previousConversationId: string, nextConversationId: string): void;
-export declare function resetSkillCatalogAdmissionsForTests(): void;
-/**
- * @deprecated Prefer `buildSkillCatalogChangeReminder` / `takeSkillCatalogChangeReminder`.
- * Kept as a thin alias for callers that still expect the old name; always returns
- * undefined for userText-based matching (OpenCode never did per-turn id nudges).
- */
-export declare function buildSkillCatalogNudge(options: {
-    hasSkillTool: boolean;
-    skills: readonly AgentSkillLike[];
-    userText?: string;
-    skillArgKey?: "name" | "id";
-    previousSkillIds?: readonly string[] | null;
-}): string | undefined;