@playwo/opencode-cursor-oauth 0.1.0 → 0.3.0

package/README.md

@@ -1,103 +1,45 @@
-# @playwo/opencode-cursor-oauth
+# opencode-cursor-oauth
 
-OpenCode plugin that connects to Cursor's API, giving you access to Cursor
-models inside OpenCode with full tool-calling support.
+## Disclaimer
 
-## Install in OpenCode
+> [!NOTE]
+> This project is a **fork** of [ephraimduncan/opencode-cursor](https://github.com/ephraimduncan/opencode-cursor). Upstream may differ in behavior, features, or maintenance; treat this repository as its own line of development.
 
-Add this to `~/.config/opencode/opencode.json`:
+## What it does
 
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "@playwo/opencode-cursor-oauth"
-  ],
-  "provider": {
-    "cursor": {
-      "name": "Cursor"
-    }
-  }
-}
-```
-
-The `cursor` provider stub is required because OpenCode drops providers that do
-not already exist in its bundled provider catalog.
-
-OpenCode installs npm plugins automatically at startup, so users do not need to
-clone this repository.
-
-## Authenticate
-
-```sh
-opencode auth login --provider cursor
-```
-
-This opens Cursor OAuth in the browser. Tokens are stored in
-`~/.local/share/opencode/auth.json` and refreshed automatically.
-
-## Use
-
-Start OpenCode and select any Cursor model. The plugin starts a local
-OpenAI-compatible proxy on demand and routes requests through Cursor's gRPC API.
+This is an [OpenCode](https://opencode.ai) plugin that lets you use **Cursor cloud models** (Claude, GPT, Gemini, and whatever your Cursor account exposes) from inside OpenCode.
 
-## How it works
+- **OAuth login** to Cursor in the browser
+- **Model discovery** — loads the models available to your Cursor account
+- **Local OpenAI-compatible proxy** — translates OpenCode’s requests to Cursor’s gRPC API
+- **Token refresh** — refreshes access tokens so sessions keep working
 
-1. OAuth — browser-based login to Cursor via PKCE.
-2. Model discovery — queries Cursor's gRPC API for all available models; if discovery fails, the plugin disables the Cursor provider for that load and shows a visible error toast instead of crashing OpenCode.
-3. Local proxy — translates `POST /v1/chat/completions` into Cursor's
-   protobuf/Connect protocol.
-4. Native tool routing — rejects Cursor's built-in filesystem/shell tools and
-   exposes OpenCode's tool surface via Cursor MCP instead.
+There are **no extra runtime requirements** beyond what OpenCode already needs: you do not install Node, Python, or Docker separately for this plugin. Enable it in OpenCode’s config and complete login in the UI.
 
-Cursor agent streaming uses Cursor's `RunSSE` + `BidiAppend` transport, so the
-plugin runs entirely inside OpenCode without a Node sidecar.
+## Install
 
-## Architecture
+Add the package to your OpenCode configuration (for example `opencode.json`):
 
-```
-OpenCode  -->  /v1/chat/completions  -->  Bun.serve (proxy)
-                                              |
-                              RunSSE stream + BidiAppend writes
-                                              |
-                                Cursor Connect/SSE transport
-                                              |
-                                     api2.cursor.sh gRPC
-```
-
-### Tool call flow
-
-```
-1. Cursor model receives OpenAI tools via RequestContext (as MCP tool defs)
-2. Model tries native tools (readArgs, shellArgs, etc.)
-3. Proxy rejects each with typed error (ReadRejected, ShellRejected, etc.)
-4. Model falls back to MCP tool -> mcpArgs exec message
-5. Proxy emits OpenAI tool_calls SSE chunk, pauses the Cursor stream
-6. OpenCode executes tool, sends result in follow-up request
-7. Proxy resumes the Cursor stream with mcpResult and continues streaming
-```
-
-## Develop locally
-
-```sh
-bun install
-bun run build
-bun test/smoke.ts
+```json
+{
+  "plugin": ["@playwo/opencode-cursor-oauth"]
+}
 ```
 
-## Publish
+Install or update dependencies the way you normally do for OpenCode plugins (e.g. ensure the package is available to your OpenCode environment). You need **OpenCode 1.2+** and a **Cursor account** with API/model access.
 
-GitHub Actions publishes this package with `.github/workflows/publish-npm.yml`.
+## Connect auth and use it
 
-- branch pushes publish a `dev` build as `0.0.0-dev.<sha>`
-- versioned releases publish `latest` using the `package.json` version and upload the packed `.tgz` to the GitHub release
+1. Start OpenCode with the plugin enabled.
+2. Open **Settings → Providers → Cursor** (wording may vary slightly by OpenCode version).
+3. Choose **Login** (or equivalent) and complete **OAuth** in the browser when prompted.
+4. After login, pick a Cursor-backed model from the model list and use OpenCode as usual.
 
-Repository secrets required:
+If something fails, check that you are signed into the correct Cursor account and that your plan includes the models you expect.
 
-- `NPM_TOKEN` for npm publish access
+## Stability and issues
 
-## Requirements
+This integration can be **buggy** or break when Cursor or OpenCode change their APIs or UI.
 
-- [OpenCode](https://opencode.ai)
-- [Bun](https://bun.sh)
-- Active [Cursor](https://cursor.com) subscription
+> [!TIP]
+> If you hit problems, missing models, or confusing errors, please **[open an issue](https://github.com/PoolPirate/opencode-cursor/issues)** on this repository with steps to reproduce and logs or screenshots when possible.

package/dist/auth.js

@@ -111,7 +111,6 @@ export function getTokenExpiry(token) {
             return decoded.exp * 1000 - 5 * 60 * 1000;
         }
     }
-    catch {
-    }
+    catch { }
     return Date.now() + 3600 * 1000;
 }

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const CURSOR_PROVIDER_ID: "cursor";
+export declare const OPENCODE_TITLE_REQUEST_MARKER = "Generate a title for this conversation:";

package/dist/constants.js

@@ -0,0 +1,2 @@
+export const CURSOR_PROVIDER_ID = "cursor";
+export const OPENCODE_TITLE_REQUEST_MARKER = "Generate a title for this conversation:";

package/dist/cursor/bidi-session.d.ts

@@ -0,0 +1,12 @@
+import { type CursorBaseRequestOptions } from "./headers";
+export interface CursorSession {
+    write: (data: Uint8Array) => void;
+    end: () => void;
+    onData: (cb: (chunk: Buffer) => void) => void;
+    onClose: (cb: (code: number) => void) => void;
+    readonly alive: boolean;
+}
+export interface CreateCursorSessionOptions extends CursorBaseRequestOptions {
+    initialRequestBytes: Uint8Array;
+}
+export declare function createCursorSession(options: CreateCursorSessionOptions): Promise<CursorSession>;

package/dist/cursor/bidi-session.js

@@ -0,0 +1,164 @@
+import { connect as connectHttp2, } from "node:http2";
+import { CURSOR_API_URL, CURSOR_CONNECT_PROTOCOL_VERSION } from "./config";
+import { frameConnectMessage } from "./connect-framing";
+import { buildCursorHeaderValues, } from "./headers";
+import { errorDetails, logPluginError } from "../logger";
+const CURSOR_BIDI_RUN_PATH = "/agent.v1.AgentService/Run";
+export async function createCursorSession(options) {
+    if (options.initialRequestBytes.length === 0) {
+        throw new Error("Cursor sessions require an initial request message");
+    }
+    const target = new URL(CURSOR_BIDI_RUN_PATH, options.url ?? CURSOR_API_URL);
+    const authority = `${target.protocol}//${target.host}`;
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+        const cbs = {
+            data: null,
+            close: null,
+        };
+        let session;
+        let stream;
+        let alive = true;
+        let closeCode = 0;
+        let opened = false;
+        let settled = false;
+        let statusCode = 0;
+        const pendingChunks = [];
+        const errorChunks = [];
+        const closeTransport = () => {
+            try {
+                stream?.close();
+            }
+            catch { }
+            try {
+                session?.close();
+            }
+            catch { }
+        };
+        const finish = (code) => {
+            if (!alive)
+                return;
+            alive = false;
+            closeCode = code;
+            cbs.close?.(code);
+            closeTransport();
+        };
+        const rejectOpen = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            alive = false;
+            closeTransport();
+            reject(error);
+        };
+        const resolveOpen = (sessionHandle) => {
+            if (settled)
+                return;
+            settled = true;
+            opened = true;
+            resolve(sessionHandle);
+        };
+        const handleTransportError = (message, error) => {
+            logPluginError(message, {
+                requestId,
+                url: target.toString(),
+                ...errorDetails(error),
+            });
+            if (!opened) {
+                rejectOpen(new Error(error instanceof Error ? error.message : String(error ?? message)));
+                return;
+            }
+            finish(1);
+        };
+        const sessionHandle = {
+            get alive() {
+                return alive;
+            },
+            write(data) {
+                if (!alive || !stream)
+                    return;
+                try {
+                    stream.write(frameConnectMessage(data));
+                }
+                catch (error) {
+                    handleTransportError("Cursor HTTP/2 write failed", error);
+                }
+            },
+            end() {
+                finish(0);
+            },
+            onData(cb) {
+                cbs.data = cb;
+                while (pendingChunks.length > 0) {
+                    cb(pendingChunks.shift());
+                }
+            },
+            onClose(cb) {
+                if (!alive) {
+                    queueMicrotask(() => cb(closeCode));
+                }
+                else {
+                    cbs.close = cb;
+                }
+            },
+        };
+        try {
+            session = connectHttp2(authority);
+            session.once("error", (error) => {
+                handleTransportError("Cursor HTTP/2 session failed", error);
+            });
+            const headers = {
+                ":method": "POST",
+                ":path": `${target.pathname}${target.search}`,
+                ...buildCursorHeaderValues(options, "application/connect+proto", {
+                    accept: "application/connect+proto",
+                    "connect-protocol-version": CURSOR_CONNECT_PROTOCOL_VERSION,
+                }),
+            };
+            stream = session.request(headers);
+            stream.once("response", (responseHeaders) => {
+                const statusHeader = responseHeaders[":status"];
+                statusCode =
+                    typeof statusHeader === "number"
+                        ? statusHeader
+                        : Number(statusHeader ?? 0);
+                if (statusCode >= 200 && statusCode < 300) {
+                    resolveOpen(sessionHandle);
+                }
+            });
+            stream.on("data", (chunk) => {
+                const buffer = Buffer.from(chunk);
+                if (!opened && statusCode >= 400) {
+                    errorChunks.push(buffer);
+                    return;
+                }
+                if (cbs.data) {
+                    cbs.data(buffer);
+                }
+                else {
+                    pendingChunks.push(buffer);
+                }
+            });
+            stream.once("end", () => {
+                if (!opened) {
+                    const errorBody = Buffer.concat(errorChunks).toString("utf8").trim();
+                    logPluginError("Cursor HTTP/2 Run request failed", {
+                        requestId,
+                        status: statusCode,
+                        responseBody: errorBody,
+                    });
+                    rejectOpen(new Error(`Run failed: ${statusCode || 1}${errorBody ? ` ${errorBody}` : ""}`));
+                    return;
+                }
+                finish(statusCode >= 200 && statusCode < 300 ? 0 : statusCode || 1);
+            });
+            stream.once("error", (error) => {
+                handleTransportError("Cursor HTTP/2 stream failed", error);
+            });
+            stream.write(frameConnectMessage(options.initialRequestBytes));
+        }
+        catch (error) {
+            handleTransportError("Cursor HTTP/2 transport setup failed", error);
+        }
+    });
+}

package/dist/cursor/config.d.ts

@@ -0,0 +1,4 @@
+export declare const CURSOR_API_URL: string;
+export declare const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
+export declare const CURSOR_CONNECT_PROTOCOL_VERSION = "1";
+export declare const CONNECT_END_STREAM_FLAG = 2;

package/dist/cursor/config.js

@@ -0,0 +1,4 @@
+export const CURSOR_API_URL = process.env.CURSOR_API_URL ?? "https://api2.cursor.sh";
+export const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
+export const CURSOR_CONNECT_PROTOCOL_VERSION = "1";
+export const CONNECT_END_STREAM_FLAG = 0b00000010;

package/dist/cursor/connect-framing.d.ts

@@ -0,0 +1,10 @@
+/** Connect protocol frame: [1-byte flags][4-byte BE length][payload] */
+export declare function frameConnectMessage(data: Uint8Array, flags?: number): Buffer;
+export declare function decodeConnectUnaryBody(payload: Uint8Array): Uint8Array | null;
+export declare function encodeVarint(value: number): Uint8Array;
+export declare function encodeProtoField(tag: number, wireType: number, value: Uint8Array): Uint8Array;
+export declare function encodeProtoStringField(tag: number, value: string): Uint8Array;
+export declare function encodeProtoMessageField(tag: number, value: Uint8Array): Uint8Array;
+export declare function encodeProtoVarintField(tag: number, value: number): Uint8Array;
+export declare function concatBytes(parts: Uint8Array[]): Uint8Array;
+export declare function toFetchBody(data: Uint8Array): ArrayBuffer;

package/dist/cursor/connect-framing.js

@@ -0,0 +1,80 @@
+import { CONNECT_END_STREAM_FLAG } from "./config";
+/** Connect protocol frame: [1-byte flags][4-byte BE length][payload] */
+export function frameConnectMessage(data, flags = 0) {
+    const frame = Buffer.alloc(5 + data.length);
+    frame[0] = flags;
+    frame.writeUInt32BE(data.length, 1);
+    frame.set(data, 5);
+    return frame;
+}
+export function decodeConnectUnaryBody(payload) {
+    if (payload.length < 5)
+        return null;
+    let offset = 0;
+    while (offset + 5 <= payload.length) {
+        const flags = payload[offset];
+        const view = new DataView(payload.buffer, payload.byteOffset + offset, payload.byteLength - offset);
+        const messageLength = view.getUint32(1, false);
+        const frameEnd = offset + 5 + messageLength;
+        if (frameEnd > payload.length)
+            return null;
+        if ((flags & 0b0000_0001) !== 0)
+            return null;
+        if ((flags & CONNECT_END_STREAM_FLAG) === 0) {
+            return payload.subarray(offset + 5, frameEnd);
+        }
+        offset = frameEnd;
+    }
+    return null;
+}
+export function encodeVarint(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`Unsupported varint value: ${value}`);
+    }
+    const bytes = [];
+    let current = value;
+    while (current >= 0x80) {
+        bytes.push((current & 0x7f) | 0x80);
+        current = Math.floor(current / 128);
+    }
+    bytes.push(current);
+    return Uint8Array.from(bytes);
+}
+export function encodeProtoField(tag, wireType, value) {
+    const key = encodeVarint((tag << 3) | wireType);
+    const out = new Uint8Array(key.length + value.length);
+    out.set(key, 0);
+    out.set(value, key.length);
+    return out;
+}
+export function encodeProtoStringField(tag, value) {
+    const bytes = new TextEncoder().encode(value);
+    const len = encodeVarint(bytes.length);
+    const payload = new Uint8Array(len.length + bytes.length);
+    payload.set(len, 0);
+    payload.set(bytes, len.length);
+    return encodeProtoField(tag, 2, payload);
+}
+export function encodeProtoMessageField(tag, value) {
+    const len = encodeVarint(value.length);
+    const payload = new Uint8Array(len.length + value.length);
+    payload.set(len, 0);
+    payload.set(value, len.length);
+    return encodeProtoField(tag, 2, payload);
+}
+export function encodeProtoVarintField(tag, value) {
+    return encodeProtoField(tag, 0, encodeVarint(value));
+}
+export function concatBytes(parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+export function toFetchBody(data) {
+    return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+}

package/dist/cursor/headers.d.ts

@@ -0,0 +1,6 @@
+export interface CursorBaseRequestOptions {
+    accessToken: string;
+    url?: string;
+}
+export declare function buildCursorHeaders(options: CursorBaseRequestOptions, contentType: string, extra?: Record<string, string>): Headers;
+export declare function buildCursorHeaderValues(options: CursorBaseRequestOptions, contentType: string, extra?: Record<string, string>): Record<string, string>;

package/dist/cursor/headers.js

@@ -0,0 +1,16 @@
+import { CURSOR_CLIENT_VERSION } from "./config";
+export function buildCursorHeaders(options, contentType, extra = {}) {
+    const headers = new Headers(buildCursorHeaderValues(options, contentType, extra));
+    return headers;
+}
+export function buildCursorHeaderValues(options, contentType, extra = {}) {
+    return {
+        authorization: `Bearer ${options.accessToken}`,
+        "content-type": contentType,
+        "x-ghost-mode": "true",
+        "x-cursor-client-version": CURSOR_CLIENT_VERSION,
+        "x-cursor-client-type": "cli",
+        "x-request-id": crypto.randomUUID(),
+        ...extra,
+    };
+}

package/dist/cursor/index.d.ts

@@ -0,0 +1,5 @@
+export { CURSOR_API_URL, CURSOR_CLIENT_VERSION, CURSOR_CONNECT_PROTOCOL_VERSION, CONNECT_END_STREAM_FLAG, } from "./config";
+export { concatBytes, decodeConnectUnaryBody, encodeProtoMessageField, encodeProtoStringField, encodeProtoVarintField, encodeVarint, frameConnectMessage, toFetchBody, } from "./connect-framing";
+export { buildCursorHeaders, buildCursorHeaderValues, type CursorBaseRequestOptions, } from "./headers";
+export { createCursorSession, type CreateCursorSessionOptions, type CursorSession, } from "./bidi-session";
+export { callCursorUnaryRpc, type CursorUnaryRpcOptions } from "./unary-rpc";

package/dist/cursor/index.js

@@ -0,0 +1,5 @@
+export { CURSOR_API_URL, CURSOR_CLIENT_VERSION, CURSOR_CONNECT_PROTOCOL_VERSION, CONNECT_END_STREAM_FLAG, } from "./config";
+export { concatBytes, decodeConnectUnaryBody, encodeProtoMessageField, encodeProtoStringField, encodeProtoVarintField, encodeVarint, frameConnectMessage, toFetchBody, } from "./connect-framing";
+export { buildCursorHeaders, buildCursorHeaderValues, } from "./headers";
+export { createCursorSession, } from "./bidi-session";
+export { callCursorUnaryRpc } from "./unary-rpc";

package/dist/cursor/unary-rpc.d.ts

@@ -0,0 +1,12 @@
+export interface CursorUnaryRpcOptions {
+    accessToken: string;
+    rpcPath: string;
+    requestBody: Uint8Array;
+    url?: string;
+    timeoutMs?: number;
+}
+export declare function callCursorUnaryRpc(options: CursorUnaryRpcOptions): Promise<{
+    body: Uint8Array;
+    exitCode: number;
+    timedOut: boolean;
+}>;

package/dist/cursor/unary-rpc.js

@@ -0,0 +1,124 @@
+import { connect as connectHttp2, } from "node:http2";
+import { CURSOR_API_URL, CURSOR_CONNECT_PROTOCOL_VERSION } from "./config";
+import { buildCursorHeaderValues } from "./headers";
+import { errorDetails, logPluginError } from "../logger";
+export async function callCursorUnaryRpc(options) {
+    const target = new URL(options.rpcPath, options.url ?? CURSOR_API_URL);
+    return callCursorUnaryRpcOverHttp2(options, target);
+}
+async function callCursorUnaryRpcOverHttp2(options, target) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const authority = `${target.protocol}//${target.host}`;
+    return new Promise((resolve) => {
+        let settled = false;
+        let timedOut = false;
+        let session;
+        let stream;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            try {
+                stream?.close();
+            }
+            catch { }
+            try {
+                session?.close();
+            }
+            catch { }
+            resolve(result);
+        };
+        const timeout = timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                finish({
+                    body: new Uint8Array(),
+                    exitCode: 124,
+                    timedOut: true,
+                });
+            }, timeoutMs)
+            : undefined;
+        try {
+            session = connectHttp2(authority);
+            session.once("error", (error) => {
+                logPluginError("Cursor unary HTTP/2 session failed", {
+                    rpcPath: options.rpcPath,
+                    url: target.toString(),
+                    timedOut,
+                    ...errorDetails(error),
+                });
+                finish({
+                    body: new Uint8Array(),
+                    exitCode: timedOut ? 124 : 1,
+                    timedOut,
+                });
+            });
+            const headers = {
+                ":method": "POST",
+                ":path": `${target.pathname}${target.search}`,
+                ...buildCursorHeaderValues(options, "application/proto", {
+                    accept: "application/proto, application/json",
+                    "connect-protocol-version": CURSOR_CONNECT_PROTOCOL_VERSION,
+                    "connect-timeout-ms": String(timeoutMs),
+                }),
+            };
+            stream = session.request(headers);
+            let statusCode = 0;
+            const chunks = [];
+            stream.once("response", (responseHeaders) => {
+                const statusHeader = responseHeaders[":status"];
+                statusCode =
+                    typeof statusHeader === "number"
+                        ? statusHeader
+                        : Number(statusHeader ?? 0);
+            });
+            stream.on("data", (chunk) => {
+                chunks.push(Buffer.from(chunk));
+            });
+            stream.once("end", () => {
+                const body = new Uint8Array(Buffer.concat(chunks));
+                finish({
+                    body,
+                    exitCode: statusCode >= 200 && statusCode < 300 ? 0 : statusCode || 1,
+                    timedOut,
+                });
+            });
+            stream.once("error", (error) => {
+                logPluginError("Cursor unary HTTP/2 stream failed", {
+                    rpcPath: options.rpcPath,
+                    url: target.toString(),
+                    timedOut,
+                    ...errorDetails(error),
+                });
+                finish({
+                    body: new Uint8Array(),
+                    exitCode: timedOut ? 124 : 1,
+                    timedOut,
+                });
+            });
+            // Bun's node:http2 client currently breaks on end(Buffer.alloc(0)) against
+            // Cursor's HTTPS endpoint, but a header-only end() succeeds for empty unary bodies.
+            if (options.requestBody.length > 0) {
+                stream.end(Buffer.from(options.requestBody));
+            }
+            else {
+                stream.end();
+            }
+        }
+        catch (error) {
+            logPluginError("Cursor unary HTTP/2 setup failed", {
+                rpcPath: options.rpcPath,
+                url: target.toString(),
+                timedOut,
+                ...errorDetails(error),
+            });
+            finish({
+                body: new Uint8Array(),
+                exitCode: timedOut ? 124 : 1,
+                timedOut,
+            });
+        }
+    });
+}

package/dist/index.d.ts

@@ -1,14 +1,2 @@
-/**
- * OpenCode Cursor Auth Plugin
- *
- * Enables using Cursor models (Claude, GPT, etc.) inside OpenCode via:
- * 1. Browser-based OAuth login to Cursor
- * 2. Local proxy translating OpenAI format → Cursor gRPC protocol
- */
-import type { Plugin } from "@opencode-ai/plugin";
-/**
- * OpenCode plugin that provides Cursor authentication and model access.
- * Register in opencode.json: { "plugin": ["opencode-cursor-oauth"] }
- */
-export declare const CursorAuthPlugin: Plugin;
-export default CursorAuthPlugin;
+export { CursorAuthPlugin } from "./plugin/cursor-auth-plugin";
+export { CursorAuthPlugin as default } from "./plugin/cursor-auth-plugin";