cursor-opencode-provider 0.2.9 → 0.3.1

package/dist/protocol/apply-patch.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Synthesis of OpenCode `apply_patch` envelopes from Cursor's native write/edit
+ * exec requests.
+ *
+ * ## Why this exists
+ *
+ * OpenCode 1.x does not merely *add* `apply_patch` for GPT models — it removes
+ * `edit` and `write` from the catalog in exchange. From
+ * `packages/opencode/src/tool/registry.ts` (`ToolRegistry.tools`):
+ *
+ * ```ts
+ * // use apply tool in same format as codex
+ * const usePatch =
+ *   input.modelID.includes("gpt-") && !input.modelID.includes("oss") && !input.modelID.includes("gpt-4")
+ * if (tool.id === ApplyPatchTool.id) return usePatch
+ * if (tool.id === EditTool.id || tool.id === WriteTool.id) return !usePatch
+ * ```
+ *
+ * The predicate runs on the *API* model id, so every Cursor `gpt-5*` model
+ * matches (and, as a quirk of substring matching, `gpt-3.5-*` does too while
+ * `gpt-4o` does not).
+ *
+ * Upstream context, in case this ever needs revisiting:
+ *
+ * - Introduced by opencode PR #9127 ("apply_patch tool for openai models"). The
+ *   intent is to hand GPT/Codex models the tool surface they were post-trained
+ *   on; the same commit tells the codex system prompt to prefer `apply_patch`.
+ * - The *exclusivity* is deliberate. On opencode issue #34491 a maintainer
+ *   describes the gate as a "band-aid", "intentionally minimal", whose purpose
+ *   is that "GPT no longer receives edit + write + apply_patch simultaneously",
+ *   and notes that a plugin-side opt-out "isn't feasible today".
+ * - opencode issue #19942 reported exactly this hazard — model-conditional tool
+ *   substitution makes model-agnostic integrations impossible — and was closed
+ *   `not_planned` by a stale bot.
+ * - opencode issue #35408 (open, milestone 2.0) proposes a
+ *   `ctx.session.context(...)` hook exposing a mutable tool roster, and lists
+ *   "Select `apply_patch` versus `edit` + `write`" as work to move out of the
+ *   registry. Once that lands, a host-side opt-out replaces this shim.
+ * - OpenCode 2.0 (`packages/core`) has **no** such gate: `apply_patch`, `edit`
+ *   and `write` are all registered unconditionally in `tool/builtins.ts`. This
+ *   translation is therefore 1.x-only in practice, but it is keyed off the
+ *   advertised set rather than a version check, so it simply never fires on 2.0.
+ *
+ * ## Why translation, not advertisement
+ *
+ * `toolsToDescriptors` forwards every advertised host tool to Cursor verbatim,
+ * so `opencode-apply_patch` already appears in Cursor's catalog whenever
+ * OpenCode advertises it, and an `mcp_args` call naming it already executes.
+ * What breaks is Cursor's *native* write/edit channel (`write_args`,
+ * `pi_edit_args`), which this provider resolves to the fixed host names
+ * `write`/`edit`.
+ *
+ * Translating on our side is the only option: Cursor's agent protocol has no
+ * patch-format edit tool at all (its `ToolCall` oneof offers whole-file
+ * `edit_tool_call`/`write_args` and substring `pi_edit_tool_call`/`pi_edit_args`;
+ * `apply_agent_diff_tool_call` is unrelated — it applies a cloud agent's diff by
+ * `agent_id`). Cursor's CLI also contains no model-conditional branching
+ * whatsoever, and `ModelDetails` carries no tool-capability flags, so the same
+ * native requests arrive for every model. Those names are absent from
+ * the catalog, so the request is refused before it reaches OpenCode.
+ *
+ * ## Format notes (verified against `packages/opencode/src/patch/index.ts`)
+ *
+ * - `*** Add File:` **overwrites an existing file** — the tool's `add` case uses
+ *   `oldContent = ""` and never stats the target (upstream test: "adds file
+ *   overwriting existing file"). A whole-file write therefore needs no diff and
+ *   no existence check.
+ * - An empty `@@` header is a valid chunk start: the parser stores
+ *   `change_context: contextLine || undefined`, and a missing context simply
+ *   means "match `old_lines` from the current scan position".
+ * - Every payload line is prefixed with `+`, `-`, or a space, and the parser
+ *   only breaks on *unprefixed* `***` / `@@`. Content lines that themselves
+ *   begin with `***` or `@@` therefore survive a round trip unharmed.
+ * - `Add File` content is rejoined with `\n` and normalized to exactly one
+ *   trailing newline. A write of content with no trailing newline gains one.
+ * - Update chunks match **whole lines** via `seekSequence`, unlike OpenCode
+ *   `edit`, which is substring-based. Substring edits must be expanded to line
+ *   boundaries before they can be expressed as a patch — see `planSubstringEdit`.
+ * - Renames are rejected by OpenCode 2.0's implementation ("apply_patch moves
+ *   are not supported yet"), so `*** Move to:` is never emitted here.
+ */
+export declare const APPLY_PATCH_TOOL = "apply_patch";
+/** One `@@` chunk: replace `oldLines` with `newLines`. */
+export type UpdateChunk = {
+    oldLines: string[];
+    newLines: string[];
+};
+/**
+ * Whole-file write as `*** Add File:`. Valid whether or not the target exists —
+ * OpenCode's add case overwrites unconditionally.
+ */
+export declare function buildAddFilePatch(filePath: string, content: string): string;
+/** Targeted replacement as `*** Update File:` with one `@@` chunk per change. */
+export declare function buildUpdateFilePatch(filePath: string, chunks: UpdateChunk[]): string;
+export type SubstringEditPlan = {
+    ok: true;
+    chunks: UpdateChunk[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Expand a substring replacement to the whole lines it touches, because
+ * `apply_patch` matches line sequences rather than substrings.
+ *
+ * Refuses rather than guessing: an absent match, or an ambiguous one without
+ * `replaceAll`, would otherwise be silently applied to the wrong region.
+ */
+export declare function planSubstringEdit(source: string, oldString: string, newString: string, replaceAll?: boolean): SubstringEditPlan;

package/dist/protocol/apply-patch.js

@@ -0,0 +1,163 @@
+/**
+ * Synthesis of OpenCode `apply_patch` envelopes from Cursor's native write/edit
+ * exec requests.
+ *
+ * ## Why this exists
+ *
+ * OpenCode 1.x does not merely *add* `apply_patch` for GPT models — it removes
+ * `edit` and `write` from the catalog in exchange. From
+ * `packages/opencode/src/tool/registry.ts` (`ToolRegistry.tools`):
+ *
+ * ```ts
+ * // use apply tool in same format as codex
+ * const usePatch =
+ *   input.modelID.includes("gpt-") && !input.modelID.includes("oss") && !input.modelID.includes("gpt-4")
+ * if (tool.id === ApplyPatchTool.id) return usePatch
+ * if (tool.id === EditTool.id || tool.id === WriteTool.id) return !usePatch
+ * ```
+ *
+ * The predicate runs on the *API* model id, so every Cursor `gpt-5*` model
+ * matches (and, as a quirk of substring matching, `gpt-3.5-*` does too while
+ * `gpt-4o` does not).
+ *
+ * Upstream context, in case this ever needs revisiting:
+ *
+ * - Introduced by opencode PR #9127 ("apply_patch tool for openai models"). The
+ *   intent is to hand GPT/Codex models the tool surface they were post-trained
+ *   on; the same commit tells the codex system prompt to prefer `apply_patch`.
+ * - The *exclusivity* is deliberate. On opencode issue #34491 a maintainer
+ *   describes the gate as a "band-aid", "intentionally minimal", whose purpose
+ *   is that "GPT no longer receives edit + write + apply_patch simultaneously",
+ *   and notes that a plugin-side opt-out "isn't feasible today".
+ * - opencode issue #19942 reported exactly this hazard — model-conditional tool
+ *   substitution makes model-agnostic integrations impossible — and was closed
+ *   `not_planned` by a stale bot.
+ * - opencode issue #35408 (open, milestone 2.0) proposes a
+ *   `ctx.session.context(...)` hook exposing a mutable tool roster, and lists
+ *   "Select `apply_patch` versus `edit` + `write`" as work to move out of the
+ *   registry. Once that lands, a host-side opt-out replaces this shim.
+ * - OpenCode 2.0 (`packages/core`) has **no** such gate: `apply_patch`, `edit`
+ *   and `write` are all registered unconditionally in `tool/builtins.ts`. This
+ *   translation is therefore 1.x-only in practice, but it is keyed off the
+ *   advertised set rather than a version check, so it simply never fires on 2.0.
+ *
+ * ## Why translation, not advertisement
+ *
+ * `toolsToDescriptors` forwards every advertised host tool to Cursor verbatim,
+ * so `opencode-apply_patch` already appears in Cursor's catalog whenever
+ * OpenCode advertises it, and an `mcp_args` call naming it already executes.
+ * What breaks is Cursor's *native* write/edit channel (`write_args`,
+ * `pi_edit_args`), which this provider resolves to the fixed host names
+ * `write`/`edit`.
+ *
+ * Translating on our side is the only option: Cursor's agent protocol has no
+ * patch-format edit tool at all (its `ToolCall` oneof offers whole-file
+ * `edit_tool_call`/`write_args` and substring `pi_edit_tool_call`/`pi_edit_args`;
+ * `apply_agent_diff_tool_call` is unrelated — it applies a cloud agent's diff by
+ * `agent_id`). Cursor's CLI also contains no model-conditional branching
+ * whatsoever, and `ModelDetails` carries no tool-capability flags, so the same
+ * native requests arrive for every model. Those names are absent from
+ * the catalog, so the request is refused before it reaches OpenCode.
+ *
+ * ## Format notes (verified against `packages/opencode/src/patch/index.ts`)
+ *
+ * - `*** Add File:` **overwrites an existing file** — the tool's `add` case uses
+ *   `oldContent = ""` and never stats the target (upstream test: "adds file
+ *   overwriting existing file"). A whole-file write therefore needs no diff and
+ *   no existence check.
+ * - An empty `@@` header is a valid chunk start: the parser stores
+ *   `change_context: contextLine || undefined`, and a missing context simply
+ *   means "match `old_lines` from the current scan position".
+ * - Every payload line is prefixed with `+`, `-`, or a space, and the parser
+ *   only breaks on *unprefixed* `***` / `@@`. Content lines that themselves
+ *   begin with `***` or `@@` therefore survive a round trip unharmed.
+ * - `Add File` content is rejoined with `\n` and normalized to exactly one
+ *   trailing newline. A write of content with no trailing newline gains one.
+ * - Update chunks match **whole lines** via `seekSequence`, unlike OpenCode
+ *   `edit`, which is substring-based. Substring edits must be expanded to line
+ *   boundaries before they can be expressed as a patch — see `planSubstringEdit`.
+ * - Renames are rejected by OpenCode 2.0's implementation ("apply_patch moves
+ *   are not supported yet"), so `*** Move to:` is never emitted here.
+ */
+export const APPLY_PATCH_TOOL = "apply_patch";
+const BEGIN = "*** Begin Patch";
+const END = "*** End Patch";
+/**
+ * Whole-file write as `*** Add File:`. Valid whether or not the target exists —
+ * OpenCode's add case overwrites unconditionally.
+ */
+export function buildAddFilePatch(filePath, content) {
+    const lines = splitLines(content);
+    return [BEGIN, `*** Add File: ${filePath}`, ...lines.map((line) => `+${line}`), END].join("\n");
+}
+/** Targeted replacement as `*** Update File:` with one `@@` chunk per change. */
+export function buildUpdateFilePatch(filePath, chunks) {
+    const body = [];
+    for (const chunk of chunks) {
+        body.push("@@");
+        for (const line of chunk.oldLines)
+            body.push(`-${line}`);
+        for (const line of chunk.newLines)
+            body.push(`+${line}`);
+    }
+    return [BEGIN, `*** Update File: ${filePath}`, ...body, END].join("\n");
+}
+/**
+ * Expand a substring replacement to the whole lines it touches, because
+ * `apply_patch` matches line sequences rather than substrings.
+ *
+ * Refuses rather than guessing: an absent match, or an ambiguous one without
+ * `replaceAll`, would otherwise be silently applied to the wrong region.
+ */
+export function planSubstringEdit(source, oldString, newString, replaceAll = false) {
+    if (oldString === "")
+        return { ok: false, reason: "the text to replace is empty" };
+    const offsets = [];
+    for (let at = source.indexOf(oldString); at !== -1; at = source.indexOf(oldString, at + oldString.length)) {
+        offsets.push(at);
+    }
+    if (offsets.length === 0)
+        return { ok: false, reason: "the text to replace was not found in the file" };
+    if (offsets.length > 1 && !replaceAll) {
+        return {
+            ok: false,
+            reason: `the text to replace appears ${offsets.length} times; it must be unique`,
+        };
+    }
+    const targets = replaceAll ? offsets : offsets.slice(0, 1);
+    const chunks = [];
+    let previousEnd = -1;
+    for (const offset of targets) {
+        const start = lineStart(source, offset);
+        const end = lineEnd(source, offset + oldString.length);
+        // Overlapping expansions would emit the same original lines twice, and the
+        // second chunk could never match after the first replaced them.
+        if (start < previousEnd) {
+            return { ok: false, reason: "overlapping replacements cannot be expressed as a patch" };
+        }
+        previousEnd = end;
+        const before = source.slice(start, offset);
+        const after = source.slice(offset + oldString.length, end);
+        chunks.push({
+            oldLines: splitLines(source.slice(start, end)),
+            newLines: splitLines(before + newString + after),
+        });
+    }
+    return { ok: true, chunks };
+}
+/**
+ * Split into patch payload lines. A trailing newline is dropped so it is not
+ * emitted as a spurious empty line — OpenCode re-adds exactly one on apply.
+ */
+function splitLines(text) {
+    const normalized = text.endsWith("\n") ? text.slice(0, -1) : text;
+    return normalized.split("\n");
+}
+function lineStart(source, offset) {
+    const at = source.lastIndexOf("\n", offset - 1);
+    return at === -1 ? 0 : at + 1;
+}
+function lineEnd(source, offset) {
+    const at = source.indexOf("\n", offset);
+    return at === -1 ? source.length : at;
+}

package/dist/protocol/messages.d.ts

@@ -3,6 +3,16 @@ export declare function createMessageTypes(): protobuf.Root;
 export declare function getMessageTypes(): protobuf.Root;
 export declare function encodeMessage(typeName: string, message: Record<string, unknown>): Uint8Array;
 export declare function decodeMessage<T = Record<string, unknown>>(typeName: string, data: Uint8Array): T;
+/**
+ * Diagnostic-only: walk AgentServerMessage.interaction_update(1).turn_ended(14)
+ * without going through our hand-written TurnEnded schema, so a `cache_write`/
+ * `reasoning_tokens` question can be checked against the raw wire instead of
+ * guessed. Confirmed field ids 1-5 (input/output/cache_read/cache_write/
+ * reasoning) decode correctly. Live captures routinely include `f4` explicitly
+ * as `0` while `f3` (cache_read) and `f5` (reasoning) are non-zero — Cursor's
+ * agent TurnEnded populates the field but does not report write counts here.
+ */
+export declare function debugWalkTurnEnded(payload: Uint8Array): string;
 /**
  * Decode a protobuf sub-message from a frame payload that wraps it in
  * a top-level field key + length varint.  Skips the outer wrapper and

package/dist/protocol/messages.js

@@ -434,15 +434,22 @@ export function createMessageTypes() {
         { id: 1, name: "success", type: "GrepSuccess" },
         { id: 2, name: "error", type: "GrepError" },
     ], [{ name: "result", fields: ["success", "error"] }]);
+    // agent.v1.WriteArgs. Cursor's own LocalWriteExecutor reads `file_bytes`
+    // first and only falls back to `file_text`, so a write whose content arrives
+    // as bytes decodes to an empty string unless field 5 is declared here.
     addType(root, "WriteArgs", [
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "file_text", type: "string" },
         { id: 3, name: "tool_call_id", type: "string" },
+        { id: 4, name: "return_file_content_after_write", type: "bool" },
+        { id: 5, name: "file_bytes", type: "bytes" },
+        { id: 6, name: "encoding_hint", type: "string" },
     ]);
     addType(root, "WriteSuccess", [
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "lines_created", type: "int32" },
         { id: 3, name: "file_size", type: "int32" },
+        { id: 4, name: "file_content_after_write", type: "string" },
     ]);
     addType(root, "WriteError", [
         { id: 1, name: "path", type: "string" },
@@ -476,7 +483,26 @@ export function createMessageTypes() {
         { id: 2, name: "error", type: "PiWriteError" },
         { id: 3, name: "rejected", type: "PiWriteRejected" },
     ], [{ name: "result", fields: ["success", "error", "rejected"] }]);
-    addType(root, "PiOutputSuccess", [{ id: 1, name: "output", type: "string" }]);
+    // agent.v1.PiTruncation. Every Pi *ExecSuccess shares output(1)+truncation(2)
+    // and only diverges at field 3, so the shared PiOutputSuccess can carry it.
+    // Cursor's own CLI always reports truncation rather than silently shortening
+    // a payload; emitting this keeps a capped read distinguishable from a
+    // complete one.
+    addType(root, "PiTruncation", [
+        { id: 1, name: "truncated", type: "bool" },
+        { id: 2, name: "truncated_by", type: "string" },
+        { id: 3, name: "total_lines", type: "uint32" },
+        { id: 4, name: "output_lines", type: "uint32" },
+        { id: 5, name: "output_bytes", type: "uint32" },
+        { id: 6, name: "max_lines", type: "uint32" },
+        { id: 7, name: "max_bytes", type: "uint32" },
+        { id: 8, name: "first_line_exceeds_limit", type: "bool" },
+        { id: 9, name: "last_line_partial", type: "bool" },
+    ]);
+    addType(root, "PiOutputSuccess", [
+        { id: 1, name: "output", type: "string" },
+        { id: 2, name: "truncation", type: "PiTruncation" },
+    ]);
     addType(root, "PiExecError", [{ id: 1, name: "error", type: "string" }]);
     addType(root, "PiExecRejected", [{ id: 1, name: "reason", type: "string" }]);
     for (const resultType of [
@@ -1209,6 +1235,62 @@ export function decodeMessage(typeName, data) {
     const decoded = type.decode(data);
     return type.toObject(decoded, { defaults: true, json: true, longs: Number });
 }
+/** Schema-free walk of one message's top-level wire fields (no nested descent). */
+function readRawFields(buf) {
+    const reader = protobuf.Reader.create(buf);
+    const fields = [];
+    while (reader.pos < reader.len) {
+        const tag = reader.uint32();
+        const field = tag >>> 3;
+        const wireType = tag & 7;
+        switch (wireType) {
+            case 0:
+                fields.push({ field, wireType, varint: reader.uint64().toString() });
+                break;
+            case 1:
+                fields.push({ field, wireType, fixed: reader.fixed64().toString() });
+                break;
+            case 2:
+                fields.push({ field, wireType, bytes: reader.bytes() });
+                break;
+            case 5:
+                fields.push({ field, wireType, fixed: reader.fixed32() });
+                break;
+            default:
+                // Groups (3/4) aren't used on this wire; bail rather than desync the reader.
+                return fields;
+        }
+    }
+    return fields;
+}
+/**
+ * Diagnostic-only: walk AgentServerMessage.interaction_update(1).turn_ended(14)
+ * without going through our hand-written TurnEnded schema, so a `cache_write`/
+ * `reasoning_tokens` question can be checked against the raw wire instead of
+ * guessed. Confirmed field ids 1-5 (input/output/cache_read/cache_write/
+ * reasoning) decode correctly. Live captures routinely include `f4` explicitly
+ * as `0` while `f3` (cache_read) and `f5` (reasoning) are non-zero — Cursor's
+ * agent TurnEnded populates the field but does not report write counts here.
+ */
+export function debugWalkTurnEnded(payload) {
+    try {
+        const top = readRawFields(payload);
+        const iuField = top.find((f) => f.field === 1 && f.wireType === 2);
+        if (!iuField?.bytes)
+            return "(no interaction_update field)";
+        const iu = readRawFields(iuField.bytes);
+        const teField = iu.find((f) => f.field === 14 && f.wireType === 2);
+        if (!teField?.bytes)
+            return "(no turn_ended field in interaction_update)";
+        const te = readRawFields(teField.bytes);
+        return te
+            .map((f) => `f${f.field}:wt${f.wireType}=${f.varint ?? f.fixed ?? (f.bytes ? `bytes[${f.bytes.length}]` : "?")}`)
+            .join(" ");
+    }
+    catch (e) {
+        return `(walk failed: ${e.message})`;
+    }
+}
 /**
  * Decode a protobuf sub-message from a frame payload that wraps it in
  * a top-level field key + length varint.  Skips the outer wrapper and

package/dist/protocol/tools.d.ts

@@ -87,6 +87,22 @@ export declare function resolveCursorSubagentType(subagentType: string, catalog?
 export declare function mapCursorSubagentTypeToOpenCode(subagentType: string): string;
 /** Resolve a native Cursor subagent request to this turn's executor and catalog. */
 export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, catalog?: HostSubagentCatalog): void;
+/**
+ * Express a native Cursor write/edit as `apply_patch` when the host swapped the
+ * edit-tool family out from under us.
+ *
+ * OpenCode 1.x removes `edit` and `write` from the catalog for GPT models and
+ * advertises `apply_patch` in their place — see the module comment in
+ * `./apply-patch.ts` for the upstream reasoning and citations. Cursor keeps
+ * using its native write/edit exec channel regardless, so without this the
+ * request is refused as an unavailable tool and the model loses the ability to
+ * change files at all.
+ *
+ * Keyed purely off the advertised set: this is inert whenever the host offers
+ * `write`/`edit` normally, and equally inert when it offers neither those nor
+ * `apply_patch` (the caller's unavailable-tool rejection still applies).
+ */
+export declare function remapEditToolsForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, workspaceRoot?: string): void;
 export type ParsedExecRequest = {
     id: number;
     execId: string;
@@ -158,6 +174,13 @@ export type ToolResultInput = {
     resultMetadata?: Record<string, unknown>;
     /** Structured shell completion captured by the OpenCode plugin hook. */
     shellOutcome?: CursorShellOutcome;
+    /**
+     * Workspace root for result shapes that must name a directory
+     * (grep_result workspace_results keys, ls_result directory_tree_root).
+     * Must not fall back to process.cwd() — the OpenCode 2.0 daemon's cwd is
+     * often $HOME and would re-advertise the wrong folder to the model.
+     */
+    workspaceRoot?: string;
 };
 /**
  * Build one or more ExecClientMessage frames for a tool result.
@@ -195,7 +218,7 @@ export declare function unwrapReadOutput(output: string): string;
  * OpenCode returns free-form text; we wrap it in the minimal success shape the
  * server accepts (verified against agent.v1 wire captures).
  */
-export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>, shellOutcome?: CursorShellOutcome): Record<string, unknown>;
+export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>, shellOutcome?: CursorShellOutcome, workspaceRoot?: string): Record<string, unknown>;
 export declare function buildToolCallPart(execMsg: ParsedExecRequest, sessionId: string): {
     toolCallId: string;
     toolName: string;