@playwo/opencode-cursor-oauth 0.0.0-dev.1b946f85e9b0 → 0.0.0-dev.65683458d3f1

package/README.md

@@ -1,103 +1,31 @@
-# @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.
+Use Cursor models (Claude, GPT, Gemini, etc.) inside [OpenCode](https://opencode.ai).
 
-## Install in OpenCode
+## What it does
 
-Add this to `~/.config/opencode/opencode.json`:
+- **OAuth login** to Cursor via browser
+- **Model discovery** — automatically fetches your available Cursor models
+- **Local proxy** — runs an OpenAI-compatible endpoint that translates to Cursor's gRPC protocol
+- **Auto-refresh** — handles token expiration automatically
 
-```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.
-
-## How it works
-
-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.
-
-Cursor agent streaming uses Cursor's `RunSSE` + `BidiAppend` transport, so the
-plugin runs entirely inside OpenCode without a Node sidecar.
+## Install
 
-## Architecture
+Add to your `opencode.json`:
 
+```json
+{
+  "plugin": ["@playwo/opencode-cursor-oauth"]
+}
 ```
-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
-```
-
-## Publish
 
-GitHub Actions publishes this package with `.github/workflows/publish-npm.yml`.
+Then authenticate via the OpenCode UI (Settings → Providers → Cursor → Login).
 
-- 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
-
-Repository secrets required:
+## Requirements
 
-- `NPM_TOKEN` for npm publish access
+- Cursor account with API access
+- OpenCode 1.2+
 
-## Requirements
+## License
 
-- [OpenCode](https://opencode.ai)
-- [Bun](https://bun.sh)
-- Active [Cursor](https://cursor.com) subscription
+MIT

package/dist/index.js

@@ -1,7 +1,7 @@
 import { generateCursorAuthParams, getTokenExpiry, pollCursorAuth, refreshCursorToken, } from "./auth";
 import { configurePluginLogger, errorDetails, logPluginError, logPluginWarn } from "./logger";
 import { getCursorModels } from "./models";
-import { startProxy, stopProxy } from "./proxy";
+import { OPENCODE_AGENT_HEADER, OPENCODE_MESSAGE_ID_HEADER, OPENCODE_SESSION_ID_HEADER, startProxy, stopProxy, } from "./proxy";
 const CURSOR_PROVIDER_ID = "cursor";
 let lastModelDiscoveryError = null;
 /**
@@ -128,6 +128,13 @@ export const CursorAuthPlugin = async (input) => {
                 },
             ],
         },
+        async "chat.headers"(input, output) {
+            if (input.model.providerID !== CURSOR_PROVIDER_ID)
+                return;
+            output.headers[OPENCODE_SESSION_ID_HEADER] = input.sessionID;
+            output.headers[OPENCODE_AGENT_HEADER] = input.agent;
+            output.headers[OPENCODE_MESSAGE_ID_HEADER] = input.message.id;
+        },
     };
 };
 function buildCursorProviderModels(models, port) {

package/dist/proxy.d.ts

@@ -1,3 +1,6 @@
+export declare const OPENCODE_SESSION_ID_HEADER = "x-opencode-session-id";
+export declare const OPENCODE_AGENT_HEADER = "x-opencode-agent";
+export declare const OPENCODE_MESSAGE_ID_HEADER = "x-opencode-message-id";
 interface CursorUnaryRpcOptions {
     accessToken: string;
     rpcPath: string;

package/dist/proxy.js

@@ -22,11 +22,15 @@ const CURSOR_API_URL = process.env.CURSOR_API_URL ?? "https://api2.cursor.sh";
 const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
 const CURSOR_CONNECT_PROTOCOL_VERSION = "1";
 const CONNECT_END_STREAM_FLAG = 0b00000010;
+export const OPENCODE_SESSION_ID_HEADER = "x-opencode-session-id";
+export const OPENCODE_AGENT_HEADER = "x-opencode-agent";
+export const OPENCODE_MESSAGE_ID_HEADER = "x-opencode-message-id";
 const SSE_HEADERS = {
     "Content-Type": "text/event-stream",
     "Cache-Control": "no-cache",
     Connection: "keep-alive",
 };
+const EPHEMERAL_CURSOR_AGENTS = new Set(["title", "summary"]);
 // Active bridges keyed by a session token (derived from conversation state).
 // When tool_calls are returned, the bridge stays alive. The next request
 // with tool results looks up the bridge and sends mcpResult messages.
@@ -471,7 +475,11 @@ export async function startProxy(getAccessToken, models = []) {
                         throw new Error("Cursor proxy access token provider not configured");
                     }
                     const accessToken = await proxyAccessTokenProvider();
-                    return handleChatCompletion(body, accessToken);
+                    return handleChatCompletion(body, accessToken, {
+                        sessionID: req.headers.get(OPENCODE_SESSION_ID_HEADER) ?? undefined,
+                        agent: req.headers.get(OPENCODE_AGENT_HEADER) ?? undefined,
+                        messageID: req.headers.get(OPENCODE_MESSAGE_ID_HEADER) ?? undefined,
+                    });
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
@@ -509,7 +517,7 @@ export function stopProxy() {
     activeBridges.clear();
     conversationStates.clear();
 }
-function handleChatCompletion(body, accessToken) {
+function handleChatCompletion(body, accessToken, requestScope = {}) {
     const { systemPrompt, userText, turns, toolResults } = parseMessages(body.messages);
     const modelId = body.model;
     const tools = body.tools ?? [];
@@ -523,8 +531,8 @@ function handleChatCompletion(body, accessToken) {
     }
     // bridgeKey: model-specific, for active tool-call bridges
     // convKey: model-independent, for conversation state that survives model switches
-    const bridgeKey = deriveBridgeKey(modelId, body.messages);
-    const convKey = deriveConversationKey(body.messages);
+    const bridgeKey = deriveBridgeKey(modelId, body.messages, requestScope);
+    const convKey = deriveConversationKey(body.messages, requestScope);
     const activeBridge = activeBridges.get(bridgeKey);
     if (activeBridge && toolResults.length > 0) {
         activeBridges.delete(bridgeKey);
@@ -546,7 +554,7 @@ function handleChatCompletion(body, accessToken) {
     let stored = conversationStates.get(convKey);
     if (!stored) {
         stored = {
-            conversationId: deterministicConversationId(convKey),
+            conversationId: crypto.randomUUID(),
             checkpoint: null,
             blobStore: new Map(),
             lastAccessMs: Date.now(),
@@ -908,6 +916,12 @@ function handleKvMessage(kvMsg, blobStore, sendFrame) {
         const blobId = kvMsg.message.value.blobId;
         const blobIdKey = Buffer.from(blobId).toString("hex");
         const blobData = blobStore.get(blobIdKey);
+        if (!blobData) {
+            logPluginWarn("Cursor requested missing blob", {
+                blobId: blobIdKey,
+                knownBlobCount: blobStore.size,
+            });
+        }
         sendKvResponse(kvMsg, "getBlobResult", create(GetBlobResultSchema, blobData ? { blobData } : {}), sendFrame);
     }
     else if (kvCase === "setBlobArgs") {
@@ -1073,16 +1087,25 @@ function sendExecResult(execMsg, messageCase, value, sendFrame) {
     sendFrame(toBinary(AgentClientMessageSchema, clientMessage));
 }
 /** Derive a key for active bridge lookup (tool-call continuations). Model-specific. */
-function deriveBridgeKey(modelId, messages) {
+function deriveBridgeKey(modelId, messages, requestScope) {
     const firstUserMsg = messages.find((m) => m.role === "user");
     const firstUserText = firstUserMsg ? textContent(firstUserMsg.content) : "";
     return createHash("sha256")
-        .update(`bridge:${modelId}:${firstUserText.slice(0, 200)}`)
+        .update(`bridge:${requestScope.sessionID ?? ""}:${requestScope.agent ?? ""}:${modelId}:${firstUserText.slice(0, 200)}`)
         .digest("hex")
         .slice(0, 16);
 }
 /** Derive a key for conversation state. Model-independent so context survives model switches. */
-function deriveConversationKey(messages) {
+function deriveConversationKey(messages, requestScope) {
+    if (requestScope.sessionID) {
+        const scope = shouldIsolateConversation(requestScope)
+            ? `${requestScope.sessionID}:${requestScope.agent ?? ""}:${requestScope.messageID ?? crypto.randomUUID()}`
+            : `${requestScope.sessionID}:${requestScope.agent ?? "default"}`;
+        return createHash("sha256")
+            .update(`conv:${scope}`)
+            .digest("hex")
+            .slice(0, 16);
+    }
     const firstUserMsg = messages.find((m) => m.role === "user");
     const firstUserText = firstUserMsg ? textContent(firstUserMsg.content) : "";
     return createHash("sha256")
@@ -1090,21 +1113,10 @@ function deriveConversationKey(messages) {
         .digest("hex")
         .slice(0, 16);
 }
-/** Deterministic UUID derived from convKey so Cursor's server-side conversation
- *  persists across proxy restarts. Formats 16 bytes of SHA-256 as a v4-shaped UUID. */
-function deterministicConversationId(convKey) {
-    const hex = createHash("sha256")
-        .update(`cursor-conv-id:${convKey}`)
-        .digest("hex")
-        .slice(0, 32);
-    // Format as UUID: xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx
-    return [
-        hex.slice(0, 8),
-        hex.slice(8, 12),
-        `4${hex.slice(13, 16)}`,
-        `${(0x8 | (parseInt(hex[16], 16) & 0x3)).toString(16)}${hex.slice(17, 20)}`,
-        hex.slice(20, 32),
-    ].join("-");
+function shouldIsolateConversation(requestScope) {
+    return Boolean(requestScope.agent
+        && EPHEMERAL_CURSOR_AGENTS.has(requestScope.agent)
+        && requestScope.messageID);
 }
 /** Create an SSE streaming Response that reads from a live bridge. */
 function createBridgeStreamResponse(bridge, heartbeatTimer, blobStore, mcpTools, modelId, bridgeKey, convKey) {
@@ -1156,6 +1168,7 @@ function createBridgeStreamResponse(bridge, heartbeatTimer, blobStore, mcpTools,
             };
             const tagFilter = createThinkingTagFilter();
             let mcpExecReceived = false;
+            let endStreamError = null;
             const processChunk = createConnectFrameParser((messageBytes) => {
                 try {
                     const serverMessage = fromBinary(AgentServerMessageSchema, messageBytes);
@@ -1215,9 +1228,14 @@ function createBridgeStreamResponse(bridge, heartbeatTimer, blobStore, mcpTools,
                     // Skip unparseable messages
                 }
             }, (endStreamBytes) => {
-                const endError = parseConnectEndStream(endStreamBytes);
-                if (endError) {
-                    sendSSE(makeChunk({ content: `\n[Error: ${endError.message}]` }));
+                endStreamError = parseConnectEndStream(endStreamBytes);
+                if (endStreamError) {
+                    logPluginError("Cursor stream returned Connect end-stream error", {
+                        modelId,
+                        bridgeKey,
+                        convKey,
+                        ...errorDetails(endStreamError),
+                    });
                 }
             });
             bridge.onData(processChunk);
@@ -1229,6 +1247,14 @@ function createBridgeStreamResponse(bridge, heartbeatTimer, blobStore, mcpTools,
                         stored.blobStore.set(k, v);
                     stored.lastAccessMs = Date.now();
                 }
+                if (endStreamError) {
+                    activeBridges.delete(bridgeKey);
+                    if (!closed) {
+                        closed = true;
+                        controller.error(endStreamError);
+                    }
+                    return;
+                }
                 if (!mcpExecReceived) {
                     const flushed = tagFilter.flush();
                     if (flushed.reasoning)
@@ -1318,7 +1344,7 @@ function handleToolResultResume(active, toolResults, modelId, bridgeKey, convKey
 async function handleNonStreamingResponse(payload, accessToken, modelId, convKey) {
     const completionId = `chatcmpl-${crypto.randomUUID().replace(/-/g, "").slice(0, 28)}`;
     const created = Math.floor(Date.now() / 1000);
-    const { text, usage } = await collectFullResponse(payload, accessToken, convKey);
+    const { text, usage } = await collectFullResponse(payload, accessToken, modelId, convKey);
     return new Response(JSON.stringify({
         id: completionId,
         object: "chat.completion",
@@ -1334,9 +1360,10 @@ async function handleNonStreamingResponse(payload, accessToken, modelId, convKey
         usage,
     }), { headers: { "Content-Type": "application/json" } });
 }
-async function collectFullResponse(payload, accessToken, convKey) {
-    const { promise, resolve } = Promise.withResolvers();
+async function collectFullResponse(payload, accessToken, modelId, convKey) {
+    const { promise, resolve, reject } = Promise.withResolvers();
     let fullText = "";
+    let endStreamError = null;
     const { bridge, heartbeatTimer } = await startBridge(accessToken, payload.requestBytes);
     const state = {
         toolCallIndex: 0,
@@ -1364,7 +1391,16 @@ async function collectFullResponse(payload, accessToken, convKey) {
         catch {
             // Skip
         }
-    }, () => { }));
+    }, (endStreamBytes) => {
+        endStreamError = parseConnectEndStream(endStreamBytes);
+        if (endStreamError) {
+            logPluginError("Cursor non-streaming response returned Connect end-stream error", {
+                modelId,
+                convKey,
+                ...errorDetails(endStreamError),
+            });
+        }
+    }));
     bridge.onClose(() => {
         clearInterval(heartbeatTimer);
         const stored = conversationStates.get(convKey);
@@ -1375,6 +1411,10 @@ async function collectFullResponse(payload, accessToken, convKey) {
         }
         const flushed = tagFilter.flush();
         fullText += flushed.content;
+        if (endStreamError) {
+            reject(endStreamError);
+            return;
+        }
         const usage = computeUsage(state);
         resolve({
             text: fullText,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwo/opencode-cursor-oauth",
-  "version": "0.0.0-dev.1b946f85e9b0",
+  "version": "0.0.0-dev.65683458d3f1",
   "description": "OpenCode plugin that connects Cursor's API to OpenCode via OAuth, model discovery, and a local OpenAI-compatible proxy.",
   "license": "MIT",
   "type": "module",