cursor-opencode-provider 0.5.0 → 0.6.0

package/dist/protocol/tools.d.ts

@@ -71,9 +71,9 @@ export type HostSubagentDefinition = {
     description?: string;
 };
 export type HostSubagentCatalog = {
-    executor?: "task" | "actor";
+    executor?: "task";
     agents: HostSubagentDefinition[];
-    /** True when the host tool supplied its complete, permission-filtered catalog. */
+    /** True when the OpenCode task tool supplied its complete, permission-filtered catalog. */
     complete: boolean;
 };
 /** Extract the current host's permission-filtered Task/Actor recipient catalog. */
@@ -151,7 +151,28 @@ export declare function parseExecServerMessage(msg: Record<string, unknown>): Pa
 export declare function mapCursorArgsToOpencode(toolName: string, raw: Record<string, unknown>, execVariant?: string): {
     toolName: string;
     args: Record<string, unknown>;
+    binaryBytes?: Uint8Array;
 };
+/**
+ * Decode `WriteArgs.file_bytes`. `encoding_hint` names the file's original
+ * encoding; OpenCode's `write` takes a string, so an unknown encoding label
+ * falls back to UTF-8 rather than dropping the write.
+ *
+ * Returns undefined when the bytes are not text in that encoding. A non-fatal
+ * decode would replace every undecodable sequence with U+FFFD and hand the host
+ * a corrupted file that still reports success, so binary content must take the
+ * byte-preserving path instead (see `isBinaryWriteRequest`).
+ */
+export declare function decodeWriteBytes(bytes: Uint8Array, encodingHint?: string): string | undefined;
+/**
+ * True when a parsed `write` request carries bytes that are not text. Such a
+ * request cannot go to OpenCode's `write` tool at all — it takes a string, and
+ * additionally BOM-splits, diffs, and runs `Format.file()` on what it writes.
+ */
+export declare function binaryWritePayload(parsed: ParsedExecRequest): {
+    path: string;
+    data: Uint8Array;
+} | undefined;
 /**
  * Map Cursor McpArgs back to the OpenCode tool id.
  * Prefers provider_identifier + bare tool_name (github + create_pull_request
@@ -162,15 +183,10 @@ export declare function mcpRealToolName(mcpArgs: Record<string, unknown>, defaul
  * A read target addressed by URI scheme rather than by local filesystem path.
  *
  * Cursor's LocalReadExecutor only ever reads local files, so this provider
- * mirrors its pre-execution validation. Host read tools are not so limited:
- * oh-my-pi's `read` accepts "a path, URL, or internal URI", and mounts every
- * discoverable tool — including all MCP server tools — under `xd://<tool>`
- * device URLs that are read for their schema and written to for execution
- * (`tools.xdev`, on by default). Resolving those against the workspace root
- * mangles `xd://everything_echo` into `<root>/xd:/everything_echo`, which stats
- * as missing and gets refused as `file_not_found` — so the host's read tool is
- * never called and every xd://-mounted MCP tool is unreachable through this
- * provider. Such targets must be forwarded untouched and left to the host.
+ * mirrors its pre-execution validation. An advertised host read tool may also
+ * accept URLs or internal URI schemes. Resolving those against the workspace
+ * root mangles the URI and produces a false `file_not_found`, so URI targets
+ * are forwarded untouched and left to the advertised executor.
  *
  * Requires a scheme of two or more characters followed by `://`, so Windows
  * drive letters (`C:\src`, `C:/src`) stay local paths.

package/dist/protocol/tools.js

@@ -299,6 +299,10 @@ const PRESERVE_EMPTY_STRING_KEYS = new Set([
     "file_text",
     "fileText",
     "stream_content",
+    // Some advertised edit schemas use a single textual `input` payload. Preserve
+    // an empty value so the executor reports the real edit error rather than a
+    // misleading missing-property error.
+    "input",
     "oldString",
     "old_string",
     "newString",
@@ -396,18 +400,16 @@ function subagentTypeEnumValues(schema) {
 }
 /** Extract the current host's permission-filtered Task/Actor recipient catalog. */
 export function extractHostSubagentCatalog(tools) {
-    const executorTool = tools.find((tool) => tool.name === "actor") ??
-        tools.find((tool) => tool.name === "task");
+    const executorTool = tools.find((tool) => tool.name === "task");
     if (!executorTool)
         return { agents: [], complete: true };
     const described = parseSubagentDescriptionCatalog(executorTool.description);
     const enumNames = subagentTypeEnumValues(executorTool.inputSchema);
     const descriptions = new Map(described.agents.map((agent) => [agent.name, agent.description]));
-    // MiMo's Actor enum is stricter than its prose catalog (`mode: subagent`
-    // rather than every non-primary agent), so structured names are authoritative.
+    // A structured subagent_type enum is stricter than prose, so it is authoritative.
     const names = new Set(enumNames.length > 0 ? enumNames : described.agents.map((agent) => agent.name));
     return {
-        executor: executorTool.name,
+        executor: "task",
         agents: [...names].map((name) => ({
             name,
             ...(descriptions.get(name) ? { description: descriptions.get(name) } : {}),
@@ -467,9 +469,9 @@ export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catal
     if (parsed.resultField !== "subagent_result" || parsed.toolName !== "task")
         return;
     const advertised = new Set(advertisedToolNames);
-    const executor = advertised.has("actor") ? "actor" : advertised.has("task") ? "task" : undefined;
-    if (!executor)
+    if (!advertised.has("task"))
         return;
+    const executor = "task";
     const description = str(parsed.args.description) ?? "";
     const prompt = str(parsed.args.prompt) ?? "";
     const cursorSubagentType = str(parsed.resultMetadata?.cursor_subagent_type) ??
@@ -484,24 +486,12 @@ export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catal
     }
     const resumeAgentId = str(parsed.args.task_id);
     parsed.toolName = executor;
-    if (executor === "task") {
-        parsed.args = {
-            description,
-            prompt,
-            subagent_type: subagentType,
-            ...(resumeAgentId ? { task_id: resumeAgentId } : {}),
-            ...(parsed.args.background === true ? { background: true } : {}),
-        };
-        return;
-    }
     parsed.args = {
-        operation: {
-            action: parsed.args.background === true ? "spawn" : "run",
-            description,
-            prompt,
-            subagent_type: subagentType,
-            ...(resumeAgentId ? { actor_id: resumeAgentId } : {}),
-        },
+        description,
+        prompt,
+        subagent_type: subagentType,
+        ...(resumeAgentId ? { task_id: resumeAgentId } : {}),
+        ...(parsed.args.background === true ? { background: true } : {}),
     };
 }
 /** Matches Cursor's own pre-write read threshold (`local-exec` 52428800). */
@@ -682,6 +672,12 @@ export function remapCorrelatedEditWriteForCatalog(parsed, advertisedToolNames,
 export function remapEditToolsForCatalog(parsed, advertisedToolNames, workspaceRoot) {
     if (parsed.toolName !== "write" && parsed.toolName !== "edit")
         return;
+    // `apply_patch` envelopes are text. A binary write has no patch form at all,
+    // so it must stay a write and reach the byte-preserving path — converting it
+    // here would drop the bytes and report a patch-translation failure instead of
+    // the image Cursor asked to save.
+    if (binaryWritePayload(parsed))
+        return;
     const advertised = new Set(advertisedToolNames);
     if (advertised.has(parsed.toolName) || !advertised.has(APPLY_PATCH_TOOL))
         return;
@@ -940,7 +936,19 @@ export function parseExecServerMessage(msg) {
         toolName: mapped.toolName,
         args: mapped.args,
         resultField,
-        ...(resultMetadata ? { resultMetadata } : {}),
+        ...(resultMetadata || mapped.binaryBytes
+            ? {
+                resultMetadata: {
+                    ...resultMetadata,
+                    ...(mapped.binaryBytes
+                        ? {
+                            binaryWriteBytes: mapped.binaryBytes,
+                            path: str(rawArgs.path) ?? str(rawArgs.file_path) ?? "",
+                        }
+                        : {}),
+                },
+            }
+            : {}),
     };
 }
 function shellStreamResultMetadata(raw) {
@@ -1020,14 +1028,31 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant) {
             // non-empty and only falls back to `file_text`; mirror that order so a
             // byte-encoded write is not silently seen as empty content.
             const bytes = bytesValue(cleaned.file_bytes) ?? bytesValue(cleaned.fileBytes);
-            const content = bytes !== undefined
-                ? decodeWriteBytes(bytes, str(cleaned.encoding_hint) ?? str(cleaned.encodingHint))
-                : stringValue(cleaned.content) ?? stringValue(cleaned.file_text) ?? stringValue(cleaned.fileText);
+            let content;
+            if (bytes !== undefined) {
+                content = decodeWriteBytes(bytes, str(cleaned.encoding_hint) ?? str(cleaned.encodingHint));
+                if (content === undefined) {
+                    // Binary. Surface the raw bytes to the caller instead of a lossy
+                    // decode; `binaryWritePayload` picks them up after parsing.
+                    return { toolName: "write", args, binaryBytes: bytes };
+                }
+            }
+            else {
+                content = stringValue(cleaned.content)
+                    ?? stringValue(cleaned.file_text)
+                    ?? stringValue(cleaned.fileText);
+            }
             if (content !== undefined)
                 args.content = content;
             return { toolName: "write", args };
         }
         case "edit": {
+            // Preserve an opaque textual edit payload when the advertised executor
+            // accepts that generic shape; rebuilding only OpenCode's targeted fields
+            // would silently turn a valid call into `{}`.
+            if (typeof cleaned.input === "string") {
+                return { toolName: "edit", args: { input: cleaned.input } };
+            }
             const args = {};
             const filePath = str(cleaned.filePath) ?? str(cleaned.path) ?? str(cleaned.file_path);
             if (filePath)
@@ -1105,22 +1130,56 @@ function bytesValue(v) {
     }
     return undefined;
 }
+/** UTF-16/32 embed NUL bytes in ordinary text; 8-bit encodings do not. */
+const WIDE_TEXT_ENCODING = /^utf-?(16|32)/;
 /**
  * Decode `WriteArgs.file_bytes`. `encoding_hint` names the file's original
- * encoding; OpenCode's `write` takes a string, so anything Node cannot decode
+ * encoding; OpenCode's `write` takes a string, so an unknown encoding label
  * falls back to UTF-8 rather than dropping the write.
+ *
+ * Returns undefined when the bytes are not text in that encoding. A non-fatal
+ * decode would replace every undecodable sequence with U+FFFD and hand the host
+ * a corrupted file that still reports success, so binary content must take the
+ * byte-preserving path instead (see `isBinaryWriteRequest`).
  */
-function decodeWriteBytes(bytes, encodingHint) {
+export function decodeWriteBytes(bytes, encodingHint) {
     const encoding = encodingHint?.trim().toLowerCase().replace(/[_ ]/g, "-");
+    let decoder;
+    let label = "utf-8";
     if (encoding && encoding !== "utf-8" && encoding !== "utf8") {
         try {
-            return new TextDecoder(encoding, { fatal: false }).decode(bytes);
+            decoder = new TextDecoder(encoding, { fatal: true });
+            label = encoding;
         }
         catch {
             trace(`write: unsupported encoding_hint ${JSON.stringify(encodingHint)} — decoding as utf-8`);
         }
     }
-    return new TextDecoder("utf-8").decode(bytes);
+    if (!decoder)
+        decoder = new TextDecoder("utf-8", { fatal: true });
+    // Single-byte encodings decode any byte sequence without error, so a decode
+    // that cannot fail is not on its own evidence of text.
+    if (!WIDE_TEXT_ENCODING.test(label) && bytes.includes(0))
+        return undefined;
+    try {
+        return decoder.decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when a parsed `write` request carries bytes that are not text. Such a
+ * request cannot go to OpenCode's `write` tool at all — it takes a string, and
+ * additionally BOM-splits, diffs, and runs `Format.file()` on what it writes.
+ */
+export function binaryWritePayload(parsed) {
+    if (parsed.toolName !== "write")
+        return undefined;
+    const data = parsed.resultMetadata?.binaryWriteBytes;
+    if (!(data instanceof Uint8Array))
+        return undefined;
+    return { path: str(parsed.resultMetadata?.path) ?? "", data };
 }
 function num(v) {
     if (typeof v === "number" && Number.isFinite(v))
@@ -1203,15 +1262,10 @@ function untildify(input) {
  * A read target addressed by URI scheme rather than by local filesystem path.
  *
  * Cursor's LocalReadExecutor only ever reads local files, so this provider
- * mirrors its pre-execution validation. Host read tools are not so limited:
- * oh-my-pi's `read` accepts "a path, URL, or internal URI", and mounts every
- * discoverable tool — including all MCP server tools — under `xd://<tool>`
- * device URLs that are read for their schema and written to for execution
- * (`tools.xdev`, on by default). Resolving those against the workspace root
- * mangles `xd://everything_echo` into `<root>/xd:/everything_echo`, which stats
- * as missing and gets refused as `file_not_found` — so the host's read tool is
- * never called and every xd://-mounted MCP tool is unreachable through this
- * provider. Such targets must be forwarded untouched and left to the host.
+ * mirrors its pre-execution validation. An advertised host read tool may also
+ * accept URLs or internal URI schemes. Resolving those against the workspace
+ * root mangles the URI and produces a false `file_not_found`, so URI targets
+ * are forwarded untouched and left to the advertised executor.
  *
  * Requires a scheme of two or more characters followed by `://`, so Windows
  * drive letters (`C:\src`, `C:/src`) stay local paths.

package/dist/usage.d.ts

@@ -49,8 +49,8 @@ export declare function formatCursorCacheDiagnostics(counters: CursorUsageCounte
 export declare function formatTurnUsageValidation(counters: CursorUsageCounters, usage: LanguageModelV3Usage, tokenDetails?: CursorConversationTokenDetails, contextSource?: CursorContextUsageSource): string;
 /** OpenCode requires a usage object at every step boundary. */
 export declare function emptyLanguageModelV3Usage(): LanguageModelV3Usage;
-/** Mirror Kilo `Session.getUsage` / AI SDK flat fields from V3 nested usage. */
-export declare function kiloShapedUsageFromV3(usage: LanguageModelV3Usage): {
+/** Project nested V3 usage into the common flat AI-SDK counter shape. */
+export declare function flatUsageFromV3(usage: LanguageModelV3Usage): {
     inputTokens: number;
     outputTokens: number;
     reasoningTokens: number;

package/dist/usage.js

@@ -217,8 +217,8 @@ export function emptyLanguageModelV3Usage() {
         reasoningTokens: 0,
     });
 }
-/** Mirror Kilo `Session.getUsage` / AI SDK flat fields from V3 nested usage. */
-export function kiloShapedUsageFromV3(usage) {
+/** Project nested V3 usage into the common flat AI-SDK counter shape. */
+export function flatUsageFromV3(usage) {
     const input = usage.inputTokens;
     const output = usage.outputTokens;
     const noCache = input.noCache ?? 0;

package/dist/web-search-tool.d.ts

@@ -1,33 +1,29 @@
+import { executeOpenCodeWebSearch } from "./web-tools.js";
+type ToolFactory = {
+    tool: (input: Record<string, unknown>) => Record<string, unknown>;
+    schema: {
+        string: () => any;
+        number: () => any;
+        enum: (values: readonly string[]) => any;
+    };
+};
+/** Build the classic OpenCode web-search tool with the host's own Zod helper. */
+export declare function createOpenCodeWebSearchTool(factory: ToolFactory): Record<string, unknown>;
 /**
- * Classic-plugin web search tool registration.
- *
- * Kept apart from `./web-tools.ts` on purpose: this is a *value* import from
- * `@opencode-ai/plugin`, and the OpenCode 2.0 entrypoint shares the search
- * implementation in that module. 2.0's package root exports no `tool`, so
- * importing it from a module on the 2.0 graph would throw during plugin load.
- * Only `plugin.ts` (classic hooks) may import this file.
+ * Host-neutral JSON-schema fallback when the classic helper is unavailable.
+ * OpenCode's legacy schema adapter marks every listed property required, so
+ * expose only the genuinely required query rather than turning four optional
+ * tuning fields into mandatory inputs.
  */
 export declare const openCodeWebSearchTool: {
     description: string;
     args: {
-        query: import("zod").ZodString;
-        numResults: import("zod").ZodOptional<import("zod").ZodNumber>;
-        livecrawl: import("zod").ZodOptional<import("zod").ZodEnum<{
-            fallback: "fallback";
-            preferred: "preferred";
-        }>>;
-        type: import("zod").ZodOptional<import("zod").ZodEnum<{
-            fast: "fast";
-            auto: "auto";
-            deep: "deep";
-        }>>;
-        contextMaxCharacters: import("zod").ZodOptional<import("zod").ZodNumber>;
+        query: {
+            type: string;
+            description: string;
+        };
     };
-    execute(args: {
-        query: string;
-        numResults?: number | undefined;
-        livecrawl?: "fallback" | "preferred" | undefined;
-        type?: "fast" | "auto" | "deep" | undefined;
-        contextMaxCharacters?: number | undefined;
-    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+    execute: typeof executeOpenCodeWebSearch;
 };
+export type { ToolFactory as OpenCodeToolFactory };
+export declare function createOpenCodeWebSearchToolFromPlugin(pluginModule: any): Record<string, unknown>;

package/dist/web-search-tool.js

@@ -1,22 +1,32 @@
-import { tool } from "@opencode-ai/plugin";
 import { executeOpenCodeWebSearch } from "./web-tools.js";
+/** Build the classic OpenCode web-search tool with the host's own Zod helper. */
+export function createOpenCodeWebSearchTool(factory) {
+    const schema = factory.schema;
+    return factory.tool({
+        description: "Search the web for current information using OpenCode's web search backend.",
+        args: {
+            query: schema.string().describe("Web search query"),
+            numResults: schema.number().int().min(1).max(20).optional(),
+            livecrawl: schema.enum(["fallback", "preferred"]).optional(),
+            type: schema.enum(["auto", "fast", "deep"]).optional(),
+            contextMaxCharacters: schema.number().int().positive().optional(),
+        },
+        execute: executeOpenCodeWebSearch,
+    });
+}
 /**
- * Classic-plugin web search tool registration.
- *
- * Kept apart from `./web-tools.ts` on purpose: this is a *value* import from
- * `@opencode-ai/plugin`, and the OpenCode 2.0 entrypoint shares the search
- * implementation in that module. 2.0's package root exports no `tool`, so
- * importing it from a module on the 2.0 graph would throw during plugin load.
- * Only `plugin.ts` (classic hooks) may import this file.
+ * Host-neutral JSON-schema fallback when the classic helper is unavailable.
+ * OpenCode's legacy schema adapter marks every listed property required, so
+ * expose only the genuinely required query rather than turning four optional
+ * tuning fields into mandatory inputs.
  */
-export const openCodeWebSearchTool = tool({
+export const openCodeWebSearchTool = {
     description: "Search the web for current information using OpenCode's web search backend.",
     args: {
-        query: tool.schema.string().describe("Web search query"),
-        numResults: tool.schema.number().int().min(1).max(20).optional(),
-        livecrawl: tool.schema.enum(["fallback", "preferred"]).optional(),
-        type: tool.schema.enum(["auto", "fast", "deep"]).optional(),
-        contextMaxCharacters: tool.schema.number().int().positive().optional(),
+        query: { type: "string", description: "Web search query" },
     },
     execute: executeOpenCodeWebSearch,
-});
+};
+export function createOpenCodeWebSearchToolFromPlugin(pluginModule) {
+    return createOpenCodeWebSearchTool({ tool: pluginModule.tool, schema: pluginModule.tool.schema });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -55,6 +55,10 @@
     "./auth": {
       "types": "./dist/auth.d.ts",
       "import": "./dist/auth.js"
+    },
+    "./image-save": {
+      "types": "./dist/image-save.d.ts",
+      "import": "./dist/image-save.js"
     }
   },
   "files": [
@@ -80,11 +84,10 @@
     "protobufjs": "^7.6.5"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": "^1.17.13",
-    "@opencode-compat/profile": ">=0.1.0"
+    "@opencode-ai/plugin": "^1.17.13"
   },
   "peerDependenciesMeta": {
-    "@opencode-compat/profile": {
+    "@opencode-ai/plugin": {
       "optional": true
     }
   },