cursor-opencode-provider 0.1.1

package/dist/protocol/request.d.ts

@@ -0,0 +1,36 @@
+import { type OpencodeToolDef } from "./tools.js";
+import type { ModelInfo } from "../models.js";
+export type RunRequestInput = {
+    text: string;
+    modelId: string;
+    conversationId: string;
+    systemPrompt?: string;
+    /**
+     * Opaque ConversationStateStructure bytes from the last
+     * conversation_checkpoint_update for this conversation_id. When set, echoed
+     * as AgentRunRequest.conversation_state (CLI parity). When absent, a seed
+     * state with the system prompt (or empty) is built for turn 1.
+     */
+    conversationState?: Uint8Array;
+    parameterValues?: Array<{
+        id: string;
+        value: string;
+    }>;
+    maxMode?: boolean;
+    messageId?: string;
+    availableModels?: ModelInfo[];
+    tools?: OpencodeToolDef[];
+    /** Prebuilt RequestContext (OpenCode-sourced). */
+    requestContext?: Record<string, unknown>;
+};
+/**
+ * Build an AgentClientMessage{run_request} for a conversation turn.
+ *
+ * Live `user_message.text` is the current prompt only — same as Cursor CLI.
+ * Cross-turn history is the last server checkpoint re-sent as conversation_state.
+ */
+export declare function buildRunRequest(input: RunRequestInput): Uint8Array;
+/**
+ * Build a heartbeat message.
+ */
+export declare function buildHeartbeat(): Uint8Array;

package/dist/protocol/request.js

@@ -0,0 +1,90 @@
+import { encodeMessage, getMessageTypes } from "./messages.js";
+import { toolsToDescriptors } from "./tools.js";
+/**
+ * Seed ConversationStateStructure for the first turn (no checkpoint yet).
+ *
+ * OpenCode needs a system prompt channel; we put it in root_prompt_messages_json
+ * as a JSON chat message. After the first checkpoint arrives we stop inventing
+ * state and echo the server's opaque structure instead (CLI behavior).
+ *
+ * We deliberately do NOT use `AgentRunRequest.custom_system_prompt` (#8): that
+ * field is the internal `--system-prompt` CLI override and the server rejects
+ * it for normal accounts.
+ */
+function buildSeedConversationState(systemPrompt) {
+    const root = getMessageTypes();
+    const type = root.lookupType("ConversationStateStructure");
+    const obj = {};
+    if (systemPrompt && systemPrompt.length > 0) {
+        obj.root_prompt_messages_json = [
+            JSON.stringify({ role: "system", content: systemPrompt }),
+        ];
+    }
+    return type.encode(type.fromObject(obj)).finish();
+}
+function buildAvailableModels(models) {
+    return models.map((m) => ({
+        model_id: m.id,
+        parameters: (m.variants ?? []).flatMap((v) => (v.parameterValues ?? []).map((p) => p)),
+    }));
+}
+/**
+ * Build an AgentClientMessage{run_request} for a conversation turn.
+ *
+ * Live `user_message.text` is the current prompt only — same as Cursor CLI.
+ * Cross-turn history is the last server checkpoint re-sent as conversation_state.
+ */
+export function buildRunRequest(input) {
+    const msgId = input.messageId ?? crypto.randomUUID();
+    // Advertise opencode's tools on the LIVE path: UserMessageAction.request_context
+    // (#2). AgentRunRequest.mcp_tools (#4) is prewarm-only / empty on real turns —
+    // putting tools only there is why the model fell back to native Grep/Read.
+    const tools = input.tools ?? [];
+    const mcpTools = tools.length > 0 ? toolsToDescriptors(tools) : [];
+    const requestContext = input.requestContext;
+    const userMessageAction = {
+        user_message: {
+            text: input.text,
+            message_id: msgId,
+        },
+    };
+    if (requestContext) {
+        userMessageAction.request_context = requestContext;
+    }
+    const conversationState = input.conversationState && input.conversationState.length > 0
+        ? input.conversationState
+        : buildSeedConversationState(input.systemPrompt);
+    const runRequest = {
+        conversation_id: input.conversationId,
+        action: {
+            user_message_action: userMessageAction,
+        },
+        requested_model: {
+            // The provider always selects a concrete model. Cursor's "default"
+            // pseudo-model (Auto) is never used here — we send the real id plus the
+            // chosen variant's parameter values.
+            model_id: input.modelId,
+            max_mode: input.maxMode ?? false,
+            parameters: input.parameterValues ?? [],
+        },
+        conversation_state: conversationState,
+        // Keep #4 populated too (harmless on real turns; useful for prewarm /
+        // older server builds that still read it).
+        mcp_tools: { mcp_tools: mcpTools },
+        unknown_flag: 0,
+        field_12: 0,
+        available_models: input.availableModels ? buildAvailableModels(input.availableModels) : [],
+        conversation_id_dup: input.conversationId,
+    };
+    return encodeMessage("AgentClientMessage", {
+        run_request: runRequest,
+    });
+}
+/**
+ * Build a heartbeat message.
+ */
+export function buildHeartbeat() {
+    return encodeMessage("AgentClientMessage", {
+        client_heartbeat: {},
+    });
+}

package/dist/protocol/stream.d.ts

@@ -0,0 +1,38 @@
+export type StreamEvent = {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "reasoning-delta";
+    text: string;
+} | {
+    type: "finish";
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    finishReason: string;
+} | {
+    type: "tool-call-started";
+    callId: string;
+    toolName: string;
+    args: string;
+} | {
+    type: "tool-call-completed";
+    callId: string;
+    result: string;
+} | {
+    type: "tool-input-delta";
+    callId: string;
+    delta: string;
+} | {
+    type: "heartbeat";
+} | {
+    type: "step";
+};
+/**
+ * Parse an AgentServerMessage frame payload into a stream event.
+ * Returns null for frames that should be skipped.
+ */
+export declare function parseInteractionUpdate(payload: Uint8Array): StreamEvent | null;

package/dist/protocol/stream.js

@@ -0,0 +1,64 @@
+import { decodeMessage } from "./messages.js";
+/**
+ * Parse an AgentServerMessage frame payload into a stream event.
+ * Returns null for frames that should be skipped.
+ */
+export function parseInteractionUpdate(payload) {
+    const asm = decodeMessage("AgentServerMessage", payload);
+    const iu = asm.interaction_update;
+    if (!iu)
+        return null;
+    if (iu.heartbeat)
+        return { type: "heartbeat" };
+    if (iu.text_delta) {
+        const td = iu.text_delta;
+        return { type: "text-delta", text: td.text ?? "" };
+    }
+    if (iu.thinking_delta) {
+        const td = iu.thinking_delta;
+        return { type: "reasoning-delta", text: td.text ?? "" };
+    }
+    if (iu.turn_ended) {
+        const te = iu.turn_ended;
+        return {
+            type: "finish",
+            usage: {
+                input: te.input_tokens ?? 0,
+                output: te.output_tokens ?? 0,
+                cacheRead: te.cache_read ?? 0,
+                cacheWrite: te.cache_write ?? 0,
+            },
+            finishReason: "stop",
+        };
+    }
+    if (iu.tool_call_started) {
+        const tc = iu.tool_call_started;
+        const toolCall = tc.tool_call;
+        return {
+            type: "tool-call-started",
+            callId: tc.call_id ?? "",
+            toolName: toolCall?.tool_name ?? "",
+            args: toolCall?.args ?? "{}",
+        };
+    }
+    if (iu.tool_call_completed) {
+        const tc = iu.tool_call_completed;
+        return {
+            type: "tool-call-completed",
+            callId: tc.call_id ?? "",
+            result: tc.result ?? "{}",
+        };
+    }
+    if (iu.partial_tool_call) {
+        const ptc = iu.partial_tool_call;
+        return {
+            type: "tool-input-delta",
+            callId: ptc.call_id ?? "",
+            delta: ptc.args_text_delta ?? "",
+        };
+    }
+    if (iu.step_started || iu.step_completed) {
+        return { type: "step" };
+    }
+    return null;
+}

package/dist/protocol/struct.d.ts

@@ -0,0 +1,19 @@
+export type RawField = {
+    fn: number;
+    wt: number;
+    varint: number;
+    bytes?: Uint8Array;
+    i64?: Uint8Array;
+};
+/** Walk a protobuf message's top-level fields off the raw wire bytes. */
+export declare function readAllFields(b: Uint8Array): RawField[];
+/** Decode a google.protobuf.Value message (bytes) back into a JSON value. */
+export declare function decodeValueToJson(bytes: Uint8Array): unknown;
+/**
+ * Decode a `map<string, Value>` field that was captured as repeated map-entry
+ * messages (each `{1 key, 2 value}`) into a plain JSON object. Used for
+ * `McpArgs.args`, which arrives as repeated field #2 on the wire.
+ */
+export declare function decodeStructEntriesToJson(entries: Uint8Array[]): Record<string, unknown>;
+/** Encode an arbitrary JSON value as google.protobuf.Value bytes. */
+export declare function encodeJsonAsValue(v: unknown): Uint8Array;

package/dist/protocol/struct.js

@@ -0,0 +1,186 @@
+// Minimal encoder for google.protobuf.Value / Struct / ListValue.
+//
+// Cursor's per-turn tool descriptors carry the tool `input_schema` (a JSON
+// Schema object) as a `google.protobuf.Value` whose `struct_value` holds the
+// schema — NOT a JSON string. Verified against a live capture
+// (request_context #7 → McpToolDescriptor #3):
+//   2a 9a07  0a10 0a04 74797065 1208 1a06 6f626a656374 ...
+//   = Value{#5 struct_value: Struct{#1 fields: {"type": Value{#3 string "object"}}}}
+//
+// Field numbers (well-known types):
+//   Value:     1 null_value, 2 number_value(double), 3 string_value,
+//              4 bool_value, 5 struct_value(Struct), 6 list_value(ListValue)
+//   Struct:    1 fields (map<string, Value>) — each entry msg{1 key, 2 value}
+//   ListValue: 1 values (repeated Value)
+function writeVarint(out, n) {
+    let v = n >>> 0;
+    while (v > 0x7f) {
+        out.push((v & 0x7f) | 0x80);
+        v >>>= 7;
+    }
+    out.push(v);
+}
+function writeTag(out, field, wire) {
+    writeVarint(out, (field << 3) | wire);
+}
+function writeLengthDelimited(out, field, bytes) {
+    writeTag(out, field, 2);
+    writeVarint(out, bytes.length);
+    for (let i = 0; i < bytes.length; i++)
+        out.push(bytes[i]);
+}
+function writeString(out, field, str) {
+    writeLengthDelimited(out, field, new TextEncoder().encode(str));
+}
+function writeDouble(out, field, num) {
+    writeTag(out, field, 1); // 64-bit
+    const buf = new ArrayBuffer(8);
+    new DataView(buf).setFloat64(0, num, true); // little-endian
+    const view = new Uint8Array(buf);
+    for (let i = 0; i < 8; i++)
+        out.push(view[i]);
+}
+function readVarintAt(b, i) {
+    let r = 0, s = 0;
+    while (i < b.length) {
+        const x = b[i++];
+        r |= (x & 0x7f) << s;
+        if (!(x & 0x80))
+            break;
+        s += 7;
+    }
+    return [r >>> 0, i];
+}
+/** Walk a protobuf message's top-level fields off the raw wire bytes. */
+export function readAllFields(b) {
+    let i = 0;
+    const out = [];
+    while (i < b.length) {
+        let key;
+        [key, i] = readVarintAt(b, i);
+        const fn = key >>> 3, wt = key & 7;
+        if (wt === 0) {
+            let v;
+            [v, i] = readVarintAt(b, i);
+            out.push({ fn, wt, varint: v });
+        }
+        else if (wt === 2) {
+            let len;
+            [len, i] = readVarintAt(b, i);
+            out.push({ fn, wt, varint: 0, bytes: b.subarray(i, i + len) });
+            i += len;
+        }
+        else if (wt === 1) {
+            out.push({ fn, wt, varint: 0, i64: b.subarray(i, i + 8) });
+            i += 8;
+        }
+        else if (wt === 5) {
+            i += 4; // i32 — not used by Value
+        }
+        else
+            break;
+    }
+    return out;
+}
+function decodeStructBytes(b) {
+    const obj = {};
+    for (const f of readAllFields(b)) {
+        if (f.fn !== 1 || !f.bytes)
+            continue; // Struct.fields (map) entries
+        const { key, valBytes } = readMapEntry(f.bytes);
+        if (key !== undefined)
+            obj[key] = valBytes ? decodeValueToJson(valBytes) : null;
+    }
+    return obj;
+}
+function decodeListBytes(b) {
+    const arr = [];
+    for (const f of readAllFields(b)) {
+        if (f.fn === 1 && f.bytes)
+            arr.push(decodeValueToJson(f.bytes));
+    }
+    return arr;
+}
+function readMapEntry(b) {
+    let key;
+    let valBytes;
+    for (const e of readAllFields(b)) {
+        if (e.fn === 1 && e.bytes)
+            key = new TextDecoder().decode(e.bytes);
+        else if (e.fn === 2 && e.bytes)
+            valBytes = e.bytes;
+    }
+    return { key, valBytes };
+}
+/** Decode a google.protobuf.Value message (bytes) back into a JSON value. */
+export function decodeValueToJson(bytes) {
+    const fs = readAllFields(bytes);
+    if (fs.length === 0)
+        return null;
+    const f = fs[0];
+    switch (f.fn) {
+        case 1: return null; // null_value
+        case 2: return f.i64 ? new DataView(f.i64.buffer, f.i64.byteOffset, 8).getFloat64(0, true) : 0;
+        case 3: return f.bytes ? new TextDecoder().decode(f.bytes) : "";
+        case 4: return f.varint !== 0;
+        case 5: return f.bytes ? decodeStructBytes(f.bytes) : {};
+        case 6: return f.bytes ? decodeListBytes(f.bytes) : [];
+        default: return null;
+    }
+}
+/**
+ * Decode a `map<string, Value>` field that was captured as repeated map-entry
+ * messages (each `{1 key, 2 value}`) into a plain JSON object. Used for
+ * `McpArgs.args`, which arrives as repeated field #2 on the wire.
+ */
+export function decodeStructEntriesToJson(entries) {
+    const obj = {};
+    for (const entry of entries) {
+        const { key, valBytes } = readMapEntry(entry);
+        if (key !== undefined)
+            obj[key] = valBytes ? decodeValueToJson(valBytes) : null;
+    }
+    return obj;
+}
+/** Encode an arbitrary JSON value as google.protobuf.Value bytes. */
+export function encodeJsonAsValue(v) {
+    const out = [];
+    if (v === null || v === undefined) {
+        writeTag(out, 1, 0); // null_value = 0
+        writeVarint(out, 0);
+    }
+    else if (typeof v === "number") {
+        writeDouble(out, 2, v);
+    }
+    else if (typeof v === "boolean") {
+        writeTag(out, 4, 0);
+        writeVarint(out, v ? 1 : 0);
+    }
+    else if (typeof v === "string") {
+        writeString(out, 3, v);
+    }
+    else if (Array.isArray(v)) {
+        const lv = [];
+        for (const item of v)
+            writeLengthDelimited(lv, 1, encodeJsonAsValue(item));
+        writeLengthDelimited(out, 6, new Uint8Array(lv));
+    }
+    else if (typeof v === "object") {
+        const st = [];
+        for (const [key, val] of Object.entries(v)) {
+            if (val === undefined)
+                continue;
+            const entry = [];
+            writeString(entry, 1, key);
+            writeLengthDelimited(entry, 2, encodeJsonAsValue(val));
+            writeLengthDelimited(st, 1, new Uint8Array(entry));
+        }
+        writeLengthDelimited(out, 5, new Uint8Array(st));
+    }
+    else {
+        // Fallback: treat as null.
+        writeTag(out, 1, 0);
+        writeVarint(out, 0);
+    }
+    return new Uint8Array(out);
+}

package/dist/protocol/thinking.d.ts

@@ -0,0 +1,15 @@
+export type EffortConfig = {
+    reasoningEffort?: string;
+    maxMode?: boolean;
+};
+/**
+ * Build RequestedModel parameter list from a model's variant parameters
+ * and optional overrides from providerOptions.
+ */
+export declare function buildRequestedModelParams(variantParameters: Array<{
+    id: string;
+    value: string;
+}>, options?: EffortConfig): Array<{
+    id: string;
+    value: string;
+}>;

package/dist/protocol/thinking.js

@@ -0,0 +1,17 @@
+// Reasoning effort / max mode → RequestedModel parameters
+/**
+ * Build RequestedModel parameter list from a model's variant parameters
+ * and optional overrides from providerOptions.
+ */
+export function buildRequestedModelParams(variantParameters, options) {
+    // Start with variant's parameters as base
+    const params = variantParameters.map((p) => ({ ...p }));
+    // Override effort if specified
+    if (options?.reasoningEffort) {
+        const effortIdx = params.findIndex((p) => p.id === "effort" || p.id === "reasoning");
+        if (effortIdx >= 0) {
+            params[effortIdx] = { ...params[effortIdx], value: options.reasoningEffort };
+        }
+    }
+    return params;
+}

package/dist/protocol/tools.d.ts

@@ -0,0 +1,94 @@
+export declare const REQUEST_CONTEXT_RESULT_FIELD = 10;
+export type OpencodeToolDef = {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+};
+/**
+ * Convert opencode's per-turn tool list into Cursor `McpToolDefinition`
+ * entries for `request_context.tools` (#7) and `AgentRunRequest.mcp_tools`.
+ *
+ * opencode tools are already namespaced (e.g. `read`, `grep`, or
+ * `<server>_<tool>` for MCP). We advertise them all under a synthetic
+ * `opencode` provider so Cursor routes their calls back to us as
+ * `mcp_args` on the exec channel. The composite `name` is what the model
+ * calls and what comes back as `McpArgs.name`.
+ */
+export declare function toolsToDescriptors(tools: OpencodeToolDef[], providerIdentifier?: string): Array<Record<string, unknown>>;
+/**
+ * Build the nested McpFileSystemOptions / McpMetaToolOptions shape used by
+ * requestContext.#23 / #34. Groups every tool under one synthetic server so
+ * Cursor's IDE-style decoder also sees the list.
+ */
+export declare function toolsToMcpDescriptors(tools: OpencodeToolDef[], providerIdentifier?: string): Array<Record<string, unknown>>;
+/**
+ * @deprecated Prefer `buildRequestContext` from `../context/build.js`.
+ * Kept as a sync tools-only fallback for unit tests that don't need collectors.
+ */
+export declare function buildLiveRequestContext(tools: OpencodeToolDef[], providerIdentifier?: string): Record<string, unknown>;
+export declare function mapExecServerToToolName(execField: string): string | undefined;
+export declare function mapToolNameToExecField(toolName: string): string | undefined;
+export type ParsedExecRequest = {
+    id: number;
+    execId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    /** ExecClientMessage result field to reply with (matches the request variant). */
+    resultField: string;
+};
+export declare function parseExecServerMessage(msg: Record<string, unknown>): ParsedExecRequest | undefined;
+/**
+ * Remap Cursor exec / MCP arg shapes onto OpenCode's Effect Schema keys.
+ * Without this, OpenCode rejects calls with InvalidArgumentsError
+ * (e.g. `path` instead of `filePath`, `file_text` instead of `content`).
+ */
+export declare function mapCursorArgsToOpencode(toolName: string, raw: Record<string, unknown>, execVariant?: string): {
+    toolName: string;
+    args: Record<string, unknown>;
+};
+export type ToolResultInput = {
+    execId: number;
+    /** ExecClientMessage result field (from ParsedExecRequest.resultField). */
+    resultField: string;
+    output: string;
+    error?: string;
+    executionTimeMs?: number;
+};
+/**
+ * Build one or more ExecClientMessage frames for a tool result.
+ * Shell replies are a sequence of ShellStream oneofs under the same id —
+ * Start → stdout/stderr → exit — then an ACM #5 stream_close so the server
+ * knows the client finished streaming (CLI always sends this; without it
+ * shell execs hang on heartbeats forever).
+ */
+export declare function buildExecClientMessages(input: ToolResultInput): Uint8Array[];
+/** ACM #5 exec_client_control_message { stream_close { id } }. */
+export declare function buildExecStreamClose(execId: number): Uint8Array;
+/**
+ * Map OpenCode tool text into the agent.v1 result oneof for each exec variant.
+ * 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): Record<string, unknown>;
+export declare function buildToolCallPart(execMsg: ParsedExecRequest, sessionId: string): {
+    toolCallId: string;
+    toolName: string;
+    input: string;
+};
+export declare function parseExecIdFromToolCallId(toolCallId: string): {
+    sessionId: string;
+    execId: number;
+} | undefined;
+/**
+ * Find the exec variant field number from the raw (gunzipped) AgentServerMessage
+ * payload: peel field #2 (exec_server_message), then return the first
+ * message-typed field that isn't id(#1)/exec_id(#15)/span_context(#19).
+ * Returns undefined if there is no exec_server_message or no variant set.
+ */
+export declare function detectExecVariantField(agentServerPayload: Uint8Array): number | undefined;
+/** Build ExecClientMessage{1:id, <resultField>: empty} as raw bytes. */
+export declare function buildRawEmptyExecReply(execId: number, resultField: number): Uint8Array;
+/**
+ * Encode exec #10 request_context_result from a prebuilt RequestContext payload.
+ */
+export declare function buildRequestContextResult(execId: number, requestContext: Record<string, unknown>): Uint8Array;