cursor-opencode-provider 0.1.1

package/dist/session.d.ts

@@ -0,0 +1,81 @@
+import type { BidiStream } from "./transport/connect.js";
+export type Frame = {
+    flags: number;
+    payload: Uint8Array;
+};
+/**
+ * A held-open Run stream. Cursor drives the agentic loop server-side and
+ * expects tool results on the SAME bidi stream. opencode, by contrast, owns
+ * its tool loop: it calls `doStream`, gets a tool-call, executes it, then calls
+ * `doStream` again with the result. We bridge the two by keeping the Run stream
+ * (and its single frames iterator) alive in a session across `doStream` calls,
+ * keyed by the exec ids we are waiting results for.
+ */
+export type PendingExec = {
+    /** ExecClientMessage result field to reply with (matches the request variant). */
+    resultField: string;
+};
+export type CursorSession = {
+    /**
+     * Stable per-Run-stream id (distinct from Cursor's own conversation_id).
+     * Tags toolCallIds so two concurrent Run streams with overlapping exec ids
+     * (Cursor resets them per stream) can't cross-deliver results.
+     */
+    sessionId: string;
+    /**
+     * Cursor conversation_id for this Run — used to store/echo
+     * conversation_checkpoint_update (CLI parity).
+     */
+    conversationId: string;
+    stream: BidiStream;
+    frames: AsyncIterator<Frame>;
+    pending: Map<number, PendingExec>;
+    /** KV blob store: blob_id (hex) → data, for Cursor's out-of-band payload channel. */
+    blobs: Map<string, Uint8Array>;
+    /** McpToolDefinition list advertised this turn — echoed into the request_context reply. */
+    toolDescriptors: Array<Record<string, unknown>>;
+    /** Full RequestContext for exec #10 replies. */
+    requestContext: Record<string, unknown>;
+    /**
+     * False when OpenCode passed no tools (compaction/summary) or toolChoice "none".
+     * Cursor may still fire native Grep/etc.; we must refuse those on the Run
+     * stream instead of emitting tool-call parts OpenCode will reject.
+     */
+    allowTools: boolean;
+    /**
+     * True while a doStream pull() is actively reading this session's frames.
+     * Prevents a late cancel/abort from a prior ReadableStream from destroying
+     * the Run connection after tool results were delivered (pending cleared) but
+     * Cursor is still generating.
+     */
+    pumpActive: boolean;
+    heartbeat: ReturnType<typeof setInterval> | null;
+    expiresAt: number;
+};
+export declare class SessionManager {
+    private byExecId;
+    private readonly idleTimeoutMs;
+    constructor(idleTimeoutMs?: number);
+    touch(session: CursorSession): void;
+    /** Register that `session` is awaiting a result for `execId`. */
+    registerPending(execId: number, session: CursorSession, resultField: string): void;
+    /** The pending exec info for an id on a specific session, if still awaiting it. */
+    pendingFor(sessionId: string, execId: number): PendingExec | undefined;
+    /** Find the live session awaiting one of the given exec ids. */
+    findByExecIds(sessionId: string, execIds: number[]): CursorSession | undefined;
+    /** Mark an exec id as resolved (its result has been delivered). */
+    resolve(sessionId: string, execId: number): void;
+    private key;
+    close(session: CursorSession): void;
+    /**
+     * Close only if nothing is awaiting a tool result AND no pull() is actively
+     * pumping this session. OpenCode aborts each doStream after finishReason
+     * "tool-calls"; that abort must NOT tear down the Cursor Run stream.
+     * Equally, a late cancel from the previous ReadableStream must not destroy
+     * the session once the continuation has cleared pending and resumed pumping.
+     * Returns true if the session was closed.
+     */
+    closeUnlessPending(session: CursorSession): boolean;
+    dispose(): void;
+}
+export declare const sessionManager: SessionManager;

package/dist/session.js

@@ -0,0 +1,96 @@
+import { trace } from "./transport/connect.js";
+export class SessionManager {
+    // Composite key `${sessionId}:${execId}` → owning session. Composite keying
+    // means two Run streams that both register an execId of 1 (Cursor resets
+    // counters per stream) coexist instead of overwriting each other.
+    byExecId = new Map();
+    idleTimeoutMs;
+    constructor(idleTimeoutMs = 300_000) {
+        this.idleTimeoutMs = idleTimeoutMs;
+    }
+    touch(session) {
+        session.expiresAt = Date.now() + this.idleTimeoutMs;
+    }
+    /** Register that `session` is awaiting a result for `execId`. */
+    registerPending(execId, session, resultField) {
+        session.pending.set(execId, { resultField });
+        this.byExecId.set(this.key(session.sessionId, execId), session);
+        this.touch(session);
+    }
+    /** The pending exec info for an id on a specific session, if still awaiting it. */
+    pendingFor(sessionId, execId) {
+        return this.byExecId.get(this.key(sessionId, execId))?.pending.get(execId);
+    }
+    /** Find the live session awaiting one of the given exec ids. */
+    findByExecIds(sessionId, execIds) {
+        for (const id of execIds) {
+            const s = this.byExecId.get(this.key(sessionId, id));
+            if (s && Date.now() < s.expiresAt)
+                return s;
+            if (s)
+                this.close(s);
+        }
+        return undefined;
+    }
+    /** Mark an exec id as resolved (its result has been delivered). */
+    resolve(sessionId, execId) {
+        const k = this.key(sessionId, execId);
+        const s = this.byExecId.get(k);
+        if (s)
+            s.pending.delete(execId);
+        this.byExecId.delete(k);
+    }
+    key(sessionId, execId) {
+        return `${sessionId}:${execId}`;
+    }
+    close(session) {
+        trace(`sessionManager.close: pending=[${[...session.pending.keys()].join(",")}] blobs=${session.blobs.size}`);
+        if (session.heartbeat)
+            clearInterval(session.heartbeat);
+        session.heartbeat = null;
+        session.stream.destroy();
+        for (const id of session.pending.keys())
+            this.byExecId.delete(this.key(session.sessionId, id));
+        session.pending.clear();
+    }
+    /**
+     * Close only if nothing is awaiting a tool result AND no pull() is actively
+     * pumping this session. OpenCode aborts each doStream after finishReason
+     * "tool-calls"; that abort must NOT tear down the Cursor Run stream.
+     * Equally, a late cancel from the previous ReadableStream must not destroy
+     * the session once the continuation has cleared pending and resumed pumping.
+     * Returns true if the session was closed.
+     */
+    closeUnlessPending(session) {
+        if (session.pending.size > 0 || session.pumpActive) {
+            trace(`sessionManager.closeUnlessPending: KEEP open pending=[${[...session.pending.keys()].join(",")}] pumpActive=${session.pumpActive}`);
+            return false;
+        }
+        this.close(session);
+        return true;
+    }
+    dispose() {
+        const seen = new Set();
+        for (const s of this.byExecId.values()) {
+            if (seen.has(s))
+                continue;
+            seen.add(s);
+            this.close(s);
+        }
+        this.byExecId.clear();
+    }
+}
+export const sessionManager = new SessionManager();
+function installProcessCleanup() {
+    const dispose = () => {
+        try {
+            sessionManager.dispose();
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    process.once("exit", dispose);
+    process.once("beforeExit", dispose);
+}
+installProcessCleanup();

package/dist/shared.d.ts

@@ -0,0 +1,15 @@
+export declare const CURSOR_AGENT_HOST = "agentn.global.api5.cursor.sh";
+export declare const CURSOR_API_HOST = "api2.cursor.sh";
+export declare const CURSOR_WEBSITE_HOST = "cursor.com";
+export declare const FALLBACK_CLIENT_VERSION = "cli-2026.07.09-a3815c0";
+export declare const CURSOR_PROVIDER_ID = "cursor";
+export declare const TOKEN_EXPIRY_THRESHOLD_S = 300;
+export declare const RUN_PATH = "/agent.v1.AgentService/Run";
+export declare const AVAILABLE_MODELS_PATH = "/aiserver.v1.AiService/AvailableModels";
+export declare const MODEL_CACHE_FILE = "cursor-models.json";
+export declare const MODEL_CACHE_TTL_MS = 86400000;
+export declare const VERSION_CACHE_FILE = "cursor-client-version.json";
+export declare const CONTENT_TYPE_CONNECT_PROTO = "application/connect+proto";
+export declare const CONNECT_PROTOCOL_VERSION = "1";
+export type ReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
+export type ContextOption = "200k" | "272k" | "300k" | "1m";

package/dist/shared.js

@@ -0,0 +1,13 @@
+export const CURSOR_AGENT_HOST = "agentn.global.api5.cursor.sh";
+export const CURSOR_API_HOST = "api2.cursor.sh";
+export const CURSOR_WEBSITE_HOST = "cursor.com";
+export const FALLBACK_CLIENT_VERSION = "cli-2026.07.09-a3815c0";
+export const CURSOR_PROVIDER_ID = "cursor";
+export const TOKEN_EXPIRY_THRESHOLD_S = 300;
+export const RUN_PATH = "/agent.v1.AgentService/Run";
+export const AVAILABLE_MODELS_PATH = "/aiserver.v1.AiService/AvailableModels";
+export const MODEL_CACHE_FILE = "cursor-models.json";
+export const MODEL_CACHE_TTL_MS = 86_400_000;
+export const VERSION_CACHE_FILE = "cursor-client-version.json";
+export const CONTENT_TYPE_CONNECT_PROTO = "application/connect+proto";
+export const CONNECT_PROTOCOL_VERSION = "1";

package/dist/transport/connect.d.ts

@@ -0,0 +1,23 @@
+export declare function trace(msg: string): void;
+export declare function buildBaseHeaders(token: string, clientVersion: string, extra?: Record<string, string>): Record<string, string>;
+export declare function unaryAvailableModels(token: string, options?: {
+    baseURL?: string;
+    headers?: Record<string, string>;
+}): Promise<Record<string, unknown>>;
+export type BidiStream = {
+    write(msg: Uint8Array): void;
+    end(): void;
+    frames(): AsyncIterable<{
+        flags: number;
+        payload: Uint8Array;
+    }>;
+    destroy(): void;
+};
+/** Resolve the HTTP/2 connect origin for a Run stream (exported for tests). */
+export declare function resolveAgentOrigin(baseURL?: string): string;
+export declare function bidiRunStream(token: string, options?: {
+    signal?: AbortSignal;
+    baseURL?: string;
+    headers?: Record<string, string>;
+}): Promise<BidiStream>;
+export declare function makeRequestId(): string;

package/dist/transport/connect.js

@@ -0,0 +1,275 @@
+import { CURSOR_API_HOST, CURSOR_AGENT_HOST, CONNECT_PROTOCOL_VERSION } from "../shared.js";
+import { encodeFrame, streamFrames } from "../protocol/framing.js";
+import { createCursorChecksumHeader } from "../protocol/checksum.js";
+import { getDeviceIds } from "../protocol/device-id.js";
+import { resolveClientVersion } from "../protocol/client-version.js";
+import http2 from "node:http2";
+import fs from "node:fs";
+const API_BASE = `https://${CURSOR_API_HOST}`;
+const AGENT = CURSOR_AGENT_HOST;
+// Wire-level diagnostics. Opt in with CURSOR_PROVIDER_DEBUG=1 (or "true").
+// Writes to CURSOR_PROVIDER_DEBUG_FILE (default /tmp/cursor-provider-debug.log).
+// Truncated once per process. Captures h2 response status, parsed frames, and
+// stream errors. Tokens / checksums are redacted in header dumps.
+const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
+    process.env.CURSOR_PROVIDER_DEBUG === "true";
+const DEBUG_FILE = process.env.CURSOR_PROVIDER_DEBUG_FILE || "/tmp/cursor-provider-debug.log";
+let _traceInitialized = false;
+export function trace(msg) {
+    if (!DEBUG_ENABLED)
+        return;
+    try {
+        if (!_traceInitialized) {
+            _traceInitialized = true;
+            fs.writeFileSync(DEBUG_FILE, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`);
+        }
+        fs.appendFileSync(DEBUG_FILE, `[${new Date().toISOString()}] ${msg}\n`);
+    }
+    catch { /* ignore */ }
+}
+trace("connect.ts module loaded");
+export function buildBaseHeaders(token, clientVersion, extra) {
+    const { machineId, macMachineId } = getDeviceIds();
+    return {
+        authorization: `Bearer ${token}`,
+        "connect-protocol-version": CONNECT_PROTOCOL_VERSION,
+        "x-cursor-client-type": "cli",
+        "x-cursor-client-version": clientVersion,
+        "x-cursor-checksum": createCursorChecksumHeader(machineId, macMachineId),
+        "x-ghost-mode": "true",
+        "x-request-id": crypto.randomUUID(),
+        ...extra,
+    };
+}
+// ── Unary (AvailableModels) ──
+export async function unaryAvailableModels(token, options = {}) {
+    const base = options.baseURL ?? API_BASE;
+    const url = `${base}/aiserver.v1.AiService/AvailableModels`;
+    const clientVersion = await resolveClientVersion();
+    const headers = buildBaseHeaders(token, clientVersion, options.headers);
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...headers,
+            "content-type": "application/json",
+            accept: "application/json",
+        },
+        body: "{}",
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`AvailableModels failed: ${res.status} ${res.statusText}${text ? ` - ${text.slice(0, 200)}` : ""}`);
+    }
+    return (await res.json());
+}
+// Cache http2 sessions keyed by origin so a custom baseURL never reuses a
+// connection opened to the default agent host — and vice versa.
+const _http2Sessions = new Map();
+// In-flight connects for the same origin share one Promise (avoid parallel races).
+const _http2Connecting = new Map();
+// Bound the time we'll wait for the initial connect. Without this, a dead or
+// unreachable host (DNS failure, network partition) hangs the provider forever
+// because the 'connect' / 'error' event may never fire.
+const CONNECT_TIMEOUT_MS = 15_000;
+/** Resolve the HTTP/2 connect origin for a Run stream (exported for tests). */
+export function resolveAgentOrigin(baseURL) {
+    // baseURL may be https://host or https://host:port — http2.connect accepts both.
+    return (baseURL ? new URL(baseURL) : new URL(`https://${AGENT}`)).origin;
+}
+function dropSession(origin, session) {
+    if (_http2Sessions.get(origin) === session)
+        _http2Sessions.delete(origin);
+}
+function getSession(baseURL) {
+    const origin = resolveAgentOrigin(baseURL);
+    const existing = _http2Sessions.get(origin);
+    if (existing && !existing.destroyed && !existing.closed) {
+        return Promise.resolve(existing);
+    }
+    const inflight = _http2Connecting.get(origin);
+    if (inflight)
+        return inflight;
+    const promise = new Promise((resolve, reject) => {
+        const session = http2.connect(origin);
+        const cleanup = () => {
+            clearTimeout(timer);
+            session.removeListener("error", onError);
+            session.removeListener("connect", onConnect);
+        };
+        const onError = (err) => {
+            cleanup();
+            _http2Connecting.delete(origin);
+            dropSession(origin, session);
+            try {
+                session.destroy();
+            }
+            catch { /* ignore */ }
+            reject(err);
+        };
+        const onConnect = () => {
+            cleanup();
+            _http2Connecting.delete(origin);
+            // Future post-connect errors (GOAWAY, RST_STREAM) must invalidate the
+            // cache; otherwise subsequent getSession() calls reuse a degraded session.
+            const onCloseOrError = () => dropSession(origin, session);
+            session.once("close", onCloseOrError);
+            session.on("error", onCloseOrError);
+            _http2Sessions.set(origin, session);
+            resolve(session);
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            _http2Connecting.delete(origin);
+            dropSession(origin, session);
+            try {
+                session.destroy();
+            }
+            catch { /* ignore */ }
+            reject(new Error(`HTTP/2 connect to ${origin} timed out after ${CONNECT_TIMEOUT_MS}ms`));
+        }, CONNECT_TIMEOUT_MS);
+        session.on("error", onError);
+        session.on("connect", onConnect);
+    });
+    _http2Connecting.set(origin, promise);
+    return promise;
+}
+export async function bidiRunStream(token, options = {}) {
+    const [session, clientVersion] = await Promise.all([
+        getSession(options.baseURL),
+        resolveClientVersion(),
+    ]);
+    const headers = {
+        ...buildBaseHeaders(token, clientVersion, options.headers),
+        ":method": "POST",
+        ":path": "/agent.v1.AgentService/Run",
+        "content-type": "application/connect+proto",
+        "connect-accept-encoding": "gzip,br",
+        // The CLI's streaming interceptor sets this on the bidi Run stream
+        // (decompiled client.ts:1190). Without it Cursor may treat the stream as
+        // non-streaming.
+        "x-cursor-streaming": "true",
+        "user-agent": "connect-es/1.6.1",
+    };
+    const stream = session.request(headers, {
+        endStream: false,
+    });
+    let writable = true;
+    let closed = false;
+    let responseStatus = 0;
+    let responseHeaders = {};
+    let streamError = null;
+    // Capture the HTTP/2 response status/headers and any stream-level error.
+    // Without this, a non-200 or RST_STREAM surfaces as a silent clean end
+    // (frames() just stops) — which looks exactly like "no response, no error".
+    stream.on("response", (h) => {
+        responseHeaders = h;
+        responseStatus = h[":status"] !== undefined ? Number(h[":status"]) : 0;
+        trace(`h2 response: status=${responseStatus} headers=${JSON.stringify(stripPseudo(h))}`);
+    });
+    stream.on("error", (err) => {
+        streamError = err;
+        trace(`h2 stream error: ${err?.name}: ${err?.message}`);
+    });
+    stream.on("close", () => trace(`h2 stream closed (status=${responseStatus}, err=${streamError?.message ?? "none"})`));
+    if (options.signal) {
+        options.signal.addEventListener("abort", () => {
+            if (!closed) {
+                closed = true;
+                writable = false;
+                stream.close();
+            }
+        }, { once: true });
+    }
+    return {
+        write(msg) {
+            if (!writable)
+                throw new Error("Stream not writable");
+            const frame = encodeFrame(0x00, msg);
+            stream.write(frame);
+        },
+        end() {
+            writable = false;
+            stream.end();
+        },
+        async *frames() {
+            const buffer = [];
+            for await (const chunk of stream) {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                if (closed)
+                    return;
+                buffer.push(new Uint8Array(buf));
+                // Try to parse frames from accumulated data
+                const merged = mergeBuffers(buffer);
+                const parsed = Array.from(streamFrames(merged));
+                if (parsed.length > 0) {
+                    const consumed = parsed.reduce((sum, f) => sum + 5 + f.payload.length, 0);
+                    // Only clear if we fully consumed all pending data
+                    if (consumed === merged.length) {
+                        buffer.length = 0;
+                    }
+                    else {
+                        buffer.length = 0;
+                        buffer.push(merged.subarray(consumed));
+                    }
+                    for (const frame of parsed) {
+                        trace(`frame yield: flags=0x${frame.flags.toString(16)} payload=${frame.payload.length}B`);
+                        yield frame;
+                    }
+                }
+            }
+            closed = true;
+            // Surface connection-level failures instead of ending silently. A
+            // non-200, a Connect error in the trailers, or an RST_STREAM would
+            // otherwise look like an empty successful response.
+            if (streamError)
+                throw streamError;
+            if (responseStatus !== 0 && responseStatus !== 200) {
+                throw new Error(`Cursor Run HTTP ${responseStatus} ${JSON.stringify(stripPseudo(responseHeaders))}`);
+            }
+            const grpcStatus = responseHeaders["grpc-status"];
+            if (grpcStatus !== undefined && String(grpcStatus) !== "0") {
+                throw new Error(`Cursor Run gRPC status ${grpcStatus}: ${responseHeaders["grpc-message"] ?? ""}`.trim());
+            }
+        },
+        destroy() {
+            if (!closed) {
+                closed = true;
+                writable = false;
+                stream.close();
+            }
+        },
+    };
+}
+function mergeBuffers(buffers) {
+    if (buffers.length === 0)
+        return new Uint8Array(0);
+    if (buffers.length === 1)
+        return buffers[0];
+    const total = buffers.reduce((s, b) => s + b.length, 0);
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const b of buffers) {
+        merged.set(b, offset);
+        offset += b.length;
+    }
+    return merged;
+}
+export function makeRequestId() {
+    return crypto.randomUUID();
+}
+function stripPseudo(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h)) {
+        if (k.startsWith(":")) {
+            if (k === ":status")
+                out[k] = v;
+            continue;
+        }
+        if (k === "authorization" || k === "x-cursor-checksum") {
+            out[k] = "<redacted>";
+            continue;
+        }
+        out[k] = v;
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "cursor-opencode-provider",
+  "version": "0.1.1",
+  "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
+  "type": "module",
+  "license": "MIT",
+  "author": "oakimov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oakimov/cursor-opencode-provider.git"
+  },
+  "bugs": {
+    "url": "https://github.com/oakimov/cursor-opencode-provider/issues"
+  },
+  "homepage": "https://github.com/oakimov/cursor-opencode-provider#readme",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "cursor",
+    "ai-sdk",
+    "provider",
+    "plugin"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./plugin/v2": {
+      "types": "./dist/plugin-v2.d.ts",
+      "import": "./dist/plugin-v2.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "3.0.8",
+    "protobufjs": "^7.4.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "~1.17.13"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "~1.17.13",
+    "@tsconfig/node22": "^22.0.1",
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}