cursor-opencode-provider 0.1.3 → 0.1.5

package/README.md

@@ -2,7 +2,7 @@
 
 Use [Cursor](https://cursor.com) subscription models from [OpenCode](https://opencode.ai) by speaking Cursor's Connect-RPC agent protocol.
 
-This project is a custom **AI SDK provider** (`LanguageModelV3`) plus an **OpenCode plugin** that handles authentication and model discovery. Instead of calling a generic chat-completions API, it encodes and decodes Cursor's protobuf agent protocol over HTTP/2 to `agentn.global.api5.cursor.sh`.
+This project is a custom **AI SDK provider** (`LanguageModelV3`) plus an **OpenCode plugin** that handles authentication and model discovery. Instead of calling a generic chat-completions API, it encodes and decodes Cursor's protobuf agent protocol over HTTP/2 to Cursor's agent backend.
 
 > **Status:** Usable end-to-end in OpenCode (auth, models, streaming, tools). See [Known limitations](#known-limitations).
 
@@ -18,7 +18,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 - **Authentication** — browser OAuth (PKCE), or API key from [cursor.com/settings](https://cursor.com/settings)
 - **Model discovery** — fetches available models from Cursor's API and caches them locally
 - **Streaming** — bidirectional Connect-RPC stream for agent runs
-- **Tool calls** — maps Cursor exec-server messages to AI SDK tool-call parts
+- **Tool calls** — maps Cursor exec-server messages to AI SDK tool-call parts; strips OpenCode's `read` XML envelope (`<path>`/`<content>` + `N:` prefixes) before returning content to Cursor so the model cannot echo the wrapper into writes
 - **Thinking / reasoning** — surfaces extended-thinking deltas where the model supports it
 
 ## Requirements
@@ -47,7 +47,7 @@ Add the package name to OpenCode config. OpenCode installs npm plugins with Bun
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.1.3"`.
+Pin a version if you want: `"cursor-opencode-provider@0.1.5"`.
 
 ### From a local clone
 
@@ -128,26 +128,30 @@ import { createCursor } from "cursor-opencode-provider"
 const cursor = createCursor({
   name: "cursor",
   accessToken: process.env.CURSOR_ACCESS_TOKEN,
+  // apiBaseURL: "https://api2.cursor.sh",
+  // agentBaseURL: "https://agentn.us.api5.cursor.sh", // explicit Run host override
+  // telemetryEnabled: true, // opt in to GetServerConfig telemetry
 })
 
 const model = cursor.languageModel("composer-2.5")
 // model implements AI SDK LanguageModelV3 (doStream / doGenerate)
 ```
 
-Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `baseURL`, `headers`.
+Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `headers`, `telemetryEnabled`. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
 
 ## Environment variables
 
 | Variable | Description |
 |----------|-------------|
 | `CURSOR_WEBSITE_URL` | Override OAuth login base URL (default `https://cursor.com`) |
-| `CURSOR_API_BASE_URL` | Override API base for auth and model discovery (default `https://api2.cursor.sh`) |
+| `CURSOR_API_BASE_URL` | Override API base for auth, model discovery, and `GetServerConfig` agent URL resolution (default `https://api2.cursor.sh`) |
+| `CURSOR_GET_SERVER_CONFIG_TELEMETRY` | Set to `1` or `true` to opt the `GetServerConfig` lookup into telemetry in OpenCode/plugin usage |
 | `CURSOR_PROVIDER_DEBUG` | Set to `1` or `true` to enable wire-level debug logging |
 | `CURSOR_PROVIDER_DEBUG_FILE` | Debug log path (default `/tmp/cursor-provider-debug.log`) |
 | `XDG_CACHE_HOME` | When set, model/version caches go under `$XDG_CACHE_HOME/opencode/` instead of `~/.cache/opencode/` |
 | `XDG_DATA_HOME` | When set, OpenCode `auth.json` is read from `$XDG_DATA_HOME/opencode/` instead of `~/.local/share/opencode/` |
 
-`createCursor({ baseURL })` also overrides the agent Run host (default `https://agentn.global.api5.cursor.sh`).
+`createCursor({ agentBaseURL })` overrides the agent Run host. When unset, the provider resolves the host from Cursor's `GetServerConfig` API (`agentUrlConfig.agentnUrl`, region-specific — e.g. `agentn.us.api5.cursor.sh`, `agent-gcpp-uswest.api5.cursor.sh`) once per process and holds it in memory (never written to disk), so a held-open Run stream is never repointed mid-session. Explicit agent overrides and GetServerConfig results are validated as HTTPS `*.cursor.sh` hosts (Cursor's agent hostnames vary and may change); non-`cursor.sh` hosts are rejected. The lookup sends `{ "telem_enabled": false }` by default; set `telemetryEnabled: true` in provider config, or `CURSOR_GET_SERVER_CONFIG_TELEMETRY=1` for OpenCode/plugin usage, to opt in. If the lookup fails or does not return a valid Cursor agent host, the model call fails clearly instead of falling back to `agentn.global.api5.cursor.sh`.
 
 ## Development
 
@@ -167,7 +171,7 @@ OpenCode
         └── createCursor() → LanguageModelV3
               ├── session.ts  held-open Run stream + exec bridge
               ├── protocol/   protobuf messages, framing, tools, thinking
-              └── transport/  Connect-RPC over HTTP/2 to agentn.global.api5.cursor.sh
+              └── transport/  Connect-RPC over HTTP/2 to Cursor's agent backend
 ```
 
 | Module | Role |
@@ -177,8 +181,10 @@ OpenCode
 | `src/index.ts` | `createCursor` factory; default export is `CursorPlugin` |
 | `src/language-model.ts` | AI SDK `LanguageModelV3` adapter (`doStream`, `doGenerate`) |
 | `src/session.ts` | Held-open agent Run session and pending exec correlation |
+| `src/debug.ts` | Opt-in wire-level debug logging (`CURSOR_PROVIDER_DEBUG`) |
 | `src/auth.ts` | PKCE OAuth, API key exchange, JWT refresh |
 | `src/models.ts` | `AvailableModels` fetch and `cursor-models.json` cache |
+| `src/agent-url.ts` | `GetServerConfig` fetch + in-process memo (region-specific Run host) |
 | `src/transport/connect.ts` | HTTP/2 bidi stream and unary RPC calls |
 | `src/protocol/` | Protobuf encode/decode, checksum/device ids, tool-call mapping |
 
@@ -200,7 +206,8 @@ OpenCode
 | Auth / 401 errors mid-session | Re-login. OAuth and exchanged API-key JWTs refresh automatically when near expiry; a revoked refresh token needs a fresh login. |
 | “Too many connections from different devices” | Device IDs are derived from stable OS identifiers (same approach as the Cursor CLI). Avoid running multiple clients that invent different machine fingerprints for the same account. |
 | Empty or stale model list | Delete `~/.cache/opencode/cursor-models.json` (or under `$XDG_CACHE_HOME/opencode/`) and restart OpenCode. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
-| Stream hangs or HTTP/2 errors | Abort the turn and retry. The agent Run uses a bidirectional HTTP/2 stream to `agentn.global.api5.cursor.sh`; a dropped connection leaves the in-flight session unusable. |
+| Stream hangs or HTTP/2 errors | Abort the turn and retry. The agent Run uses a bidirectional HTTP/2 stream; a dropped connection leaves the in-flight session unusable. |
+| No response / silent 200 + close | The provider resolves the Run host from `GetServerConfig` (`agentUrlConfig.agentnUrl`). The URL is resolved once per process and not cached on disk. If resolution fails, the model call reports the endpoint-resolution error instead of falling back to `agentn.global.api5.cursor.sh`, which some accounts reject silently ("This region is not yet available for your team"). Set `CURSOR_PROVIDER_DEBUG=1` to confirm the resolved host in the debug log. |
 | Need wire-level logs | Set `CURSOR_PROVIDER_DEBUG=1` (optional `CURSOR_PROVIDER_DEBUG_FILE`, default `/tmp/cursor-provider-debug.log`) and reproduce the issue. |
 
 ## Known limitations
@@ -212,4 +219,4 @@ OpenCode
 
 ## License
 
-MIT
+MIT

package/dist/agent-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve the Run stream origin for this account via the `GetServerConfig`
+ * Connect RPC. Memoized for the process lifetime.
+ *
+ *   - already resolved → return the memo (no fetch)
+ *   - otherwise → fetch `agentUrlConfig.agentnUrl` (then `agentUrl`), memoize, return
+ *   - fetch fails / no valid `agentUrlConfig` → throw (no global-host fallback)
+ *
+ * Concurrent callers share a single in-flight fetch.
+ */
+export declare function resolveAgentUrl(token: string, options?: {
+    apiBaseURL?: string;
+    baseURL?: string;
+    telemetryEnabled?: boolean;
+}): Promise<string>;
+/** Reset the in-process memo. Tests only. */
+export declare function resetAgentUrlCache(): void;

package/dist/agent-url.js

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { fetchAgentUrl } from "./transport/connect.js";
+import { trace } from "./debug.js";
+import { CURSOR_API_HOST } from "./shared.js";
+const DEFAULT_API_BASE = `https://${CURSOR_API_HOST}`;
+// In-process memo of the region-specific Run stream origin (agentnUrl). Resolved
+// once per process — the auth loader warms it, and the first startSession reuses
+// it — and held for the process lifetime. Region routing is near-static, and
+// re-resolving mid-session would break a held-open bidi Run stream anyway.
+//
+// Unlike the models/version caches this is NOT persisted to disk. A wrong agent
+// host is fatal and silent (HTTP 200 + immediate close, "This region is not
+// available for your team"), so persisting it would risk pinning the process —
+// or the next process — to a stale region or the legacy global host that some
+// accounts reject. Resolving fresh per process is cheap (one unary RPC on the
+// API host) and self-heals after a Cursor-side region migration on restart.
+//
+function normalizeApiBaseURL(baseURL) {
+    if (!baseURL)
+        return DEFAULT_API_BASE;
+    return new URL(baseURL).origin;
+}
+function resolveCacheKey(token, options) {
+    const tokenHash = createHash("sha256").update(token).digest("hex").slice(0, 16);
+    return `${tokenHash}|${normalizeApiBaseURL(options.apiBaseURL ?? options.baseURL)}|telem:${options.telemetryEnabled === true}`;
+}
+const _resolved = new Map();
+// In-flight fetches share the same key as resolved URLs so concurrent callers dedup per account.
+const _inflight = new Map();
+/**
+ * Resolve the Run stream origin for this account via the `GetServerConfig`
+ * Connect RPC. Memoized for the process lifetime.
+ *
+ *   - already resolved → return the memo (no fetch)
+ *   - otherwise → fetch `agentUrlConfig.agentnUrl` (then `agentUrl`), memoize, return
+ *   - fetch fails / no valid `agentUrlConfig` → throw (no global-host fallback)
+ *
+ * Concurrent callers share a single in-flight fetch.
+ */
+export async function resolveAgentUrl(token, options = {}) {
+    const cacheKey = resolveCacheKey(token, options);
+    const memo = _resolved.get(cacheKey);
+    if (memo) {
+        trace(`agent-url: reuse in-process memo → ${memo}`);
+        return memo;
+    }
+    const inflight = _inflight.get(cacheKey);
+    if (inflight) {
+        trace("agent-url: awaiting in-flight GetServerConfig");
+        return inflight;
+    }
+    const promise = (async () => {
+        try {
+            const url = await fetchAgentUrl(token, options);
+            _resolved.set(cacheKey, url);
+            trace(`agent-url: resolved via GetServerConfig → ${url}`);
+            return url;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            trace(`agent-url: GetServerConfig failed (${reason}); no fallback agent host will be used`);
+            throw err;
+        }
+        finally {
+            _inflight.delete(cacheKey);
+        }
+    })();
+    _inflight.set(cacheKey, promise);
+    return promise;
+}
+/** Reset the in-process memo. Tests only. */
+export function resetAgentUrlCache() {
+    _resolved.clear();
+    _inflight.clear();
+}

package/dist/context/auth-store.js

@@ -7,7 +7,7 @@ function debugEnabled() {
 function debugAuthStore(message) {
     if (!debugEnabled())
         return;
-    console.error(`[cursor-opencode-provider] auth-store: ${message}`);
+    console.debug(`[cursor-opencode-provider] auth-store: ${message}`);
 }
 /**
  * Read a provider's credentials from OpenCode's `auth.json` (XDG data dir).

package/dist/debug.d.ts

@@ -0,0 +1 @@
+export declare function trace(msg: string): void;

package/dist/debug.js

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+// 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. Tokens / checksums should be redacted by callers.
+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 */
+    }
+}

package/dist/index.d.ts

@@ -3,8 +3,15 @@ export type CreateCursorOptions = {
     name: string;
     accessToken?: string;
     apiKey?: string;
+    /** API base for auth, model discovery, and GetServerConfig. */
+    apiBaseURL?: string;
+    /** Explicit Cursor agent Run host override. */
+    agentBaseURL?: string;
+    /** @deprecated Use agentBaseURL. Kept as the legacy agent Run host override. */
     baseURL?: string;
     headers?: Record<string, string>;
+    /** Opt in to telemetry on the GetServerConfig endpoint lookup. Defaults to false. */
+    telemetryEnabled?: boolean;
     /** OpenCode project / worktree directory for request_context collectors. */
     workspaceRoot?: string;
 };

package/dist/language-model.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { createHash } from "node:crypto";
-import { bidiRunStream, trace } from "./transport/connect.js";
+import { bidiRunStream, normalizeAgentRunOrigin } from "./transport/connect.js";
+import { trace } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
 import { decodeMessage } from "./protocol/messages.js";
@@ -12,6 +13,8 @@ import { sessionManager } from "./session.js";
 import { readCache, cacheFilePath, resolveVariantParameters } from "./models.js";
 import { buildRequestContext } from "./context/build.js";
 import { opencodeGlobalCacheDir } from "./context/paths.js";
+import { resolveAgentUrl } from "./agent-url.js";
+import { CURSOR_API_HOST } from "./shared.js";
 let _availableModels;
 // mtime of the cache file the last time we loaded it. Compared on each call
 // so discoverModels' background refresh is picked up without a process restart.
@@ -49,7 +52,7 @@ async function doStreamImpl(modelId, options, callOptions) {
     const token = await resolveBearerToken({
         accessToken: options.accessToken,
         apiKey: options.apiKey,
-        baseUrl: options.baseURL,
+        baseUrl: resolveApiBaseURL(options),
     });
     const prompt = callOptions.prompt;
     // ── Continuation vs fresh turn ──
@@ -76,6 +79,7 @@ async function doStreamImpl(modelId, options, callOptions) {
                     resultField: pending.resultField,
                     output: r.output,
                     error: r.error,
+                    toolName: pending.toolName ?? r.toolName,
                 })) {
                     session.stream.write(frame);
                 }
@@ -171,6 +175,14 @@ async function startSession(modelId, token, callOptions, options) {
     const systemPrompt = extractSystemPrompt(prompt);
     const tools = extractTools(callOptions);
     await loadAvailableModels();
+    // Resolve the region-specific Run stream origin once per process (memoized
+    // in agent-url.ts). Explicit agent host overrides skip GetServerConfig but
+    // still go through the Cursor agent-host allowlist.
+    const agentBaseUrl = resolveExplicitAgentBaseURL(options) ??
+        (await resolveAgentUrl(token, {
+            apiBaseURL: resolveApiBaseURL(options),
+            telemetryEnabled: resolveTelemetryEnabled(options),
+        }));
     const providerOptions = callOptions.providerOptions?.cursor;
     const reasoningEffort = providerOptions?.reasoningEffort;
     const maxMode = !!(providerOptions?.maxMode ?? false);
@@ -180,7 +192,7 @@ async function startSession(modelId, token, callOptions, options) {
     // that signal when a turn ends with tool-calls; the Cursor stream must stay
     // open until we write the exec results on the next doStream.
     const stream = await bidiRunStream(token, {
-        baseURL: options.baseURL,
+        baseURL: agentBaseUrl,
         headers: options.headers,
     });
     // Build the tool descriptors once — advertised in AgentRunRequest #4 mcp_tools
@@ -321,6 +333,25 @@ async function loadAvailableModels() {
     }
     catch { /* ignore */ }
 }
+function resolveApiBaseURL(options) {
+    return options.apiBaseURL ?? process.env.CURSOR_API_BASE_URL ?? `https://${CURSOR_API_HOST}`;
+}
+function resolveTelemetryEnabled(options) {
+    return options.telemetryEnabled ?? isTruthyEnv(process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY);
+}
+function resolveExplicitAgentBaseURL(options) {
+    const raw = options.agentBaseURL ?? options.baseURL;
+    if (!raw)
+        return undefined;
+    const normalized = normalizeAgentRunOrigin(raw);
+    if (!normalized) {
+        throw new Error("Invalid Cursor agent base URL override: expected https://*.cursor.sh");
+    }
+    return normalized;
+}
+function isTruthyEnv(value) {
+    return value === "1" || value === "true";
+}
 /**
  * Read the held-open stream, emitting stream parts, until the turn boundary:
  *  - a tool call (exec_server_message) → emit tool-call, finish "tool-calls",
@@ -546,6 +577,7 @@ async function pump(session, controller, ids, abortSignal) {
                                     resultField: parsed.resultField,
                                     output: "",
                                     error: reason,
+                                    toolName: parsed.toolName,
                                 })) {
                                     session.stream.write(frame);
                                 }
@@ -557,7 +589,7 @@ async function pump(session, controller, ids, abortSignal) {
                         }
                         const tc = buildToolCallPart(parsed, session.sessionId);
                         // Keep the stream open; the result arrives on the next doStream call.
-                        sessionManager.registerPending(parsed.id, session, parsed.resultField);
+                        sessionManager.registerPending(parsed.id, session, parsed.resultField, parsed.toolName);
                         // tc.input is already a JSON string (LanguageModelV3ToolCall.input).
                         trace(`exec: EMITTED tool-call toolCallId=${tc.toolCallId} toolName=${tc.toolName} inputLen=${tc.input.length}`);
                         // Close open text/reasoning spans before tool-call (required by AI SDK V3).

package/dist/plugin.js

@@ -3,6 +3,7 @@ import { pollForTokens, exchangeApiKey, refreshAccessToken, isExpiringSoon, gene
 import { readCache, discoverModels, isCacheFresh } from "./models.js";
 import { opencodeGlobalCacheDir } from "./context/paths.js";
 import { readStoredAuth } from "./context/auth-store.js";
+import { resolveAgentUrl } from "./agent-url.js";
 const MODULE_URL = new URL("./index.js", import.meta.url).href;
 /**
  * Strip characters that break rendering in the OpenCode Desktop webview from a
@@ -93,8 +94,16 @@ function modelsToConfig(models) {
     }
     return out;
 }
+function cursorApiBaseURL() {
+    return process.env.CURSOR_API_BASE_URL ?? `https://${CURSOR_API_HOST}`;
+}
+function cursorGetServerConfigTelemetryEnabled() {
+    return (process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY === "1" ||
+        process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY === "true");
+}
 export async function CursorPlugin(input) {
     const cacheDir = opencodeGlobalCacheDir();
+    const apiBaseURL = cursorApiBaseURL();
     // Last access token successfully resolved in this plugin instance. Config's
     // loadModels can only read OpenCode's durable store (auth.json /
     // OPENCODE_AUTH_CONTENT); auth.loader gets live credentials via getAuth().
@@ -139,7 +148,7 @@ export async function CursorPlugin(input) {
             // it the same way as OAuth when it is expiring / already expired.
             if (refreshToken && isExpiringSoon(auth.key)) {
                 try {
-                    const newTokens = await refreshAccessToken(refreshToken);
+                    const newTokens = await refreshAccessToken(refreshToken, apiBaseURL);
                     accessToken = newTokens.accessToken;
                     await persistAuthBestEffort({
                         type: "api",
@@ -166,7 +175,7 @@ export async function CursorPlugin(input) {
             if (!auth.refresh)
                 return undefined;
             try {
-                const newTokens = await refreshAccessToken(auth.refresh);
+                const newTokens = await refreshAccessToken(auth.refresh, apiBaseURL);
                 // Preserve optional OAuth fields (v2 Auth / plugin may carry these).
                 const extras = auth;
                 // Use the new token even if persisting back to OpenCode fails.
@@ -197,7 +206,7 @@ export async function CursorPlugin(input) {
                 const accessToken = await resolveAccessToken(auth);
                 if (accessToken) {
                     try {
-                        const models = await discoverModels(accessToken, cacheDir);
+                        const models = await discoverModels(accessToken, cacheDir, { baseURL: apiBaseURL });
                         return modelsToConfig(models);
                     }
                     catch {
@@ -280,7 +289,7 @@ export async function CursorPlugin(input) {
                         if (!apiKey)
                             return { type: "failed" };
                         try {
-                            const result = await exchangeApiKey(apiKey);
+                            const result = await exchangeApiKey(apiKey, apiBaseURL);
                             return {
                                 type: "success",
                                 key: result.accessToken,
@@ -306,8 +315,16 @@ export async function CursorPlugin(input) {
                     if (!cached || cached.models.length === 0 || !isCacheFresh(cached)) {
                         // Await so an empty/missing cache is written before the loader returns
                         // (fire-and-forget often loses the race on short-lived CLI commands).
-                        await discoverModels(accessToken, cacheDir).catch(() => { });
+                        await discoverModels(accessToken, cacheDir, { baseURL: apiBaseURL }).catch(() => { });
                     }
+                    // Resolve the region-specific Run stream origin so the first turn
+                    // does not spend time on GetServerConfig. Best-effort: a failure is
+                    // surfaced by startSession, which can fail the actual model call with
+                    // a clear endpoint-resolution error instead of using global fallback.
+                    await resolveAgentUrl(accessToken, {
+                        apiBaseURL,
+                        telemetryEnabled: cursorGetServerConfigTelemetryEnabled(),
+                    }).catch(() => { });
                 }
                 return {
                     ...(accessToken ? { accessToken } : {}),

package/dist/protocol/tools.d.ts

@@ -53,6 +53,12 @@ export type ToolResultInput = {
     output: string;
     error?: string;
     executionTimeMs?: number;
+    /**
+     * Resolved opencode tool name (read/write/grep/…). Gates read-envelope
+     * unwrapping on the mcp_result path so non-read MCP output is never
+     * rewritten. read_result is always a read, so it unwraps regardless.
+     */
+    toolName?: string;
 };
 /**
  * Build one or more ExecClientMessage frames for a tool result.
@@ -64,12 +70,33 @@ export type ToolResultInput = {
 export declare function buildExecClientMessages(input: ToolResultInput): Uint8Array[];
 /** ACM #5 exec_client_control_message { stream_close { id } }. */
 export declare function buildExecStreamClose(execId: number): Uint8Array;
+/**
+ * Strip opencode's `read` envelope, leaving raw file content.
+ *
+ * opencode's read tool (opencode `tool/read.ts`) wraps content in an XML-ish
+ * envelope its own models are trained on, but Cursor's are not:
+ *   <path>{abs}</path>\n<type>file</type>\n<content>\n{N}: {line}\n…\n\n{footer}\n</content>
+ * Forwarding that envelope verbatim made Cursor's model treat the wrapper as
+ * literal file content and write `<path>`/`<content>` tags + `N:` line prefixes
+ * back into files (silent corruption — the write still reports success; seen
+ * across 8+ sessions, e.g. language-model.ts rewritten starting with
+ * `<path>…</path>\n<type>file</type>\n<content>\n1: import fs…`).
+ *
+ * Returns the raw file body (line numbers + footer + `<system-reminder>` dropped).
+ *
+ * Deliberately exception-safe: if the expected envelope is absent — non-read
+ * output, already-raw text, or a future opencode format change — it returns the
+ * input unchanged, so a result is never broken and we never throw mid-turn.
+ * Callers must still gate `mcp_result` on `toolName === "read"`; this helper
+ * alone is not a tool-identity check.
+ */
+export declare function unwrapReadOutput(output: string): string;
 /**
  * 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 buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string): Record<string, unknown>;
 export declare function buildToolCallPart(execMsg: ParsedExecRequest, sessionId: string): {
     toolCallId: string;
     toolName: string;

package/dist/protocol/tools.js

@@ -1,5 +1,6 @@
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
+import { trace } from "../debug.js";
 // Exec variant field number whose reply is the server-initiated request_context
 // probe (ExecServerMessage #10 → ExecClientMessage #10). request/result share a
 // field number for every exec variant, so this is also the result field.
@@ -394,7 +395,7 @@ export function buildExecClientMessages(input) {
             id: input.execId,
             local_execution_time_ms: input.executionTimeMs ?? 0,
         };
-        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error);
+        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName);
         frames.push(encodeMessage("AgentClientMessage", {
             exec_client_message: clientMsg,
         }));
@@ -411,21 +412,90 @@ export function buildExecStreamClose(execId) {
         },
     });
 }
+/**
+ * Strip opencode's `read` envelope, leaving raw file content.
+ *
+ * opencode's read tool (opencode `tool/read.ts`) wraps content in an XML-ish
+ * envelope its own models are trained on, but Cursor's are not:
+ *   <path>{abs}</path>\n<type>file</type>\n<content>\n{N}: {line}\n…\n\n{footer}\n</content>
+ * Forwarding that envelope verbatim made Cursor's model treat the wrapper as
+ * literal file content and write `<path>`/`<content>` tags + `N:` line prefixes
+ * back into files (silent corruption — the write still reports success; seen
+ * across 8+ sessions, e.g. language-model.ts rewritten starting with
+ * `<path>…</path>\n<type>file</type>\n<content>\n1: import fs…`).
+ *
+ * Returns the raw file body (line numbers + footer + `<system-reminder>` dropped).
+ *
+ * Deliberately exception-safe: if the expected envelope is absent — non-read
+ * output, already-raw text, or a future opencode format change — it returns the
+ * input unchanged, so a result is never broken and we never throw mid-turn.
+ * Callers must still gate `mcp_result` on `toolName === "read"`; this helper
+ * alone is not a tool-identity check.
+ */
+export function unwrapReadOutput(output) {
+    if (typeof output !== "string" || output.length === 0)
+        return output;
+    // Require the full opencode read-envelope skeleton *before* `<content>`
+    // (read.ts opens with <path>…</path>, <type>file</type>, <content>) so a
+    // stray "<content>" later in tool chatter can't trigger unwrapping just
+    // because path/type tags appear elsewhere in the payload.
+    const contentHeaderIdx = output.indexOf("<content>");
+    if (contentHeaderIdx === -1)
+        return output;
+    const header = output.slice(0, contentHeaderIdx);
+    const hasSkeleton = header.indexOf("<path>") !== -1 &&
+        header.indexOf("<type>file</type>") !== -1;
+    if (!hasSkeleton) {
+        // Saw "<content>" but not the read skeleton ahead of it — almost certainly
+        // a non-read payload, or an opencode format drift. Surface it so drift
+        // can't silently resurrect the wrapper-corruption bug, but still fail
+        // safe (no mutate).
+        trace("unwrapReadOutput: <content> present without leading <path>/<type>file> skeleton — leaving output unchanged (possible non-read payload or opencode read format drift)");
+        return output;
+    }
+    // Body starts right after "<content>\n". opencode emits one numbered line per
+    // file line ("N: <line>"), then a blank, a "(…)" footer, and a standalone
+    // "</content>". The body is a *contiguous run* of /^N: / lines — so we stop at
+    // the first non-numbered line. Critically we do NOT search for a closing
+    // "</content>" substring: a file line that literally contains "</content>"
+    // is rendered as "N: </content>" (a body line), and a raw indexOf would
+    // truncate the read there.
+    let rest = output.slice(contentHeaderIdx + "<content>".length);
+    if (rest.startsWith("\n"))
+        rest = rest.slice(1);
+    const raw = [];
+    for (const line of rest.split("\n")) {
+        const m = /^(\d+):[ \t]?(.*)$/.exec(line);
+        if (!m)
+            break; // blank / "(footer)" / "</content>" → end of body run
+        // Strip only the leading "N: " prefix; a line that itself begins with
+        // digits+colon keeps its content (we remove just the first match). Blank
+        // file lines render as "N: " and are preserved (capture group is "").
+        raw.push(m[2]);
+    }
+    // Envelope confirmed but no numbered body → empty file. Return "" rather
+    // than the envelope (the envelope is exactly what Cursor echoes into writes).
+    return raw.join("\n");
+}
 /**
  * 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 function buildTypedExecResult(resultField, output, error) {
+export function buildTypedExecResult(resultField, output, error, toolName) {
     switch (resultField) {
         case "read_result":
             if (error)
                 return { error: { path: "", error } };
+            // Strip opencode's <path>/<content> envelope so Cursor's model receives
+            // raw file content and can't echo the wrapper into subsequent writes.
+            // reads route here only for native read_args; most arrive via mcp_result.
+            const content = unwrapReadOutput(output);
             return {
                 success: {
                     path: extractPathTag(output) ?? "",
-                    content: output,
-                    total_lines: countLines(output),
+                    content,
+                    total_lines: countLines(content),
                 },
             };
         case "grep_result": {
@@ -492,9 +562,15 @@ export function buildTypedExecResult(resultField, output, error) {
         case "mcp_result":
             if (error)
                 return { error: { error } };
+            // opencode built-ins (read/write/grep/…) are advertised as MCP tools, so
+            // a read call returns through mcp_result. Scope the unwrap to toolName
+            // "read" so a non-read MCP tool whose output merely contains a
+            // "<content>"-like block is never rewritten.
             return {
                 success: {
-                    content: [{ text: { text: output } }],
+                    content: [
+                        { text: { text: toolName === "read" ? unwrapReadOutput(output) : output } },
+                    ],
                     is_error: false,
                 },
             };

package/dist/session.d.ts

@@ -14,6 +14,11 @@ export type Frame = {
 export type PendingExec = {
     /** ExecClientMessage result field to reply with (matches the request variant). */
     resultField: string;
+    /**
+     * Resolved opencode tool name (read/write/grep/…). Used on continuation so
+     * mcp_result can unwrap read envelopes even if the prompt omits toolName.
+     */
+    toolName?: string;
 };
 export type CursorSession = {
     /**
@@ -58,7 +63,7 @@ export declare class SessionManager {
     constructor(idleTimeoutMs?: number);
     touch(session: CursorSession): void;
     /** Register that `session` is awaiting a result for `execId`. */
-    registerPending(execId: number, session: CursorSession, resultField: string): void;
+    registerPending(execId: number, session: CursorSession, resultField: string, toolName?: 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. */

package/dist/session.js

@@ -1,4 +1,4 @@
-import { trace } from "./transport/connect.js";
+import { trace } from "./debug.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
@@ -12,8 +12,8 @@ export class SessionManager {
         session.expiresAt = Date.now() + this.idleTimeoutMs;
     }
     /** Register that `session` is awaiting a result for `execId`. */
-    registerPending(execId, session, resultField) {
-        session.pending.set(execId, { resultField });
+    registerPending(execId, session, resultField, toolName) {
+        session.pending.set(execId, { resultField, toolName });
         this.byExecId.set(this.key(session.sessionId, execId), session);
         this.touch(session);
     }

package/dist/shared.d.ts

@@ -1,4 +1,3 @@
-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";
@@ -6,6 +5,7 @@ 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 SERVER_CONFIG_PATH = "/aiserver.v1.ServerConfigService/GetServerConfig";
 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";

package/dist/shared.js

@@ -1,4 +1,3 @@
-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";
@@ -6,6 +5,7 @@ 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 SERVER_CONFIG_PATH = "/aiserver.v1.ServerConfigService/GetServerConfig";
 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";

package/dist/transport/connect.d.ts

@@ -1,9 +1,34 @@
-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?: {
+    apiBaseURL?: string;
     baseURL?: string;
     headers?: Record<string, string>;
 }): Promise<Record<string, unknown>>;
+/**
+ * Cursor Run stream hosts from GetServerConfig / agentBaseURL.
+ * Any HTTPS subdomain of cursor.sh is accepted — hostnames vary
+ * (agentn.*, agent.*, agent-gcpp-*, api5 / api5lat, …) and may change.
+ */
+export declare function isAllowedAgentHost(hostname: string): boolean;
+/**
+ * Normalize a GetServerConfig agent URL to an https origin.
+ * Returns null for missing, malformed, non-https, or non-*.cursor.sh hosts.
+ */
+export declare function normalizeAgentRunOrigin(raw: string | undefined): string | null;
+/**
+ * Fetch the Cursor server config (a Connect unary RPC on the API host) and
+ * return the `agentUrlConfig.agentnUrl` field — the region-specific Run stream
+ * origin the server routes this account/team to (e.g. `agentn.us.api5.cursor.sh`).
+ *
+ * Region-routed accounts can be silently rejected by the wrong regional host, so
+ * this lookup fails closed instead of substituting any host on error. Any
+ * authoritative `*.cursor.sh` origin from GetServerConfig is accepted.
+ */
+export declare function fetchAgentUrl(token: string, options?: {
+    apiBaseURL?: string;
+    baseURL?: string;
+    telemetryEnabled?: boolean;
+}): Promise<string>;
 export type BidiStream = {
     write(msg: Uint8Array): void;
     end(): void;
@@ -14,10 +39,10 @@ export type BidiStream = {
     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?: {
+export declare function resolveAgentOrigin(baseURL: string): string;
+export declare function bidiRunStream(token: string, options: {
     signal?: AbortSignal;
-    baseURL?: string;
+    baseURL: string;
     headers?: Record<string, string>;
 }): Promise<BidiStream>;
 export declare function makeRequestId(): string;

package/dist/transport/connect.js

@@ -1,31 +1,13 @@
-import { CURSOR_API_HOST, CURSOR_AGENT_HOST, CONNECT_PROTOCOL_VERSION } from "../shared.js";
+import { CURSOR_API_HOST, CONNECT_PROTOCOL_VERSION, SERVER_CONFIG_PATH } 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 { trace } from "../debug.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 */ }
+function resolveApiBaseURL(options) {
+    return new URL(options.apiBaseURL ?? options.baseURL ?? API_BASE).origin;
 }
 trace("connect.ts module loaded");
 export function buildBaseHeaders(token, clientVersion, extra) {
@@ -43,7 +25,7 @@ export function buildBaseHeaders(token, clientVersion, extra) {
 }
 // ── Unary (AvailableModels) ──
 export async function unaryAvailableModels(token, options = {}) {
-    const base = options.baseURL ?? API_BASE;
+    const base = resolveApiBaseURL(options);
     const url = `${base}/aiserver.v1.AiService/AvailableModels`;
     const clientVersion = await resolveClientVersion();
     const headers = buildBaseHeaders(token, clientVersion, options.headers);
@@ -62,6 +44,82 @@ export async function unaryAvailableModels(token, options = {}) {
     }
     return (await res.json());
 }
+// ── Unary (GetServerConfig) ──
+/**
+ * Cursor Run stream hosts from GetServerConfig / agentBaseURL.
+ * Any HTTPS subdomain of cursor.sh is accepted — hostnames vary
+ * (agentn.*, agent.*, agent-gcpp-*, api5 / api5lat, …) and may change.
+ */
+export function isAllowedAgentHost(hostname) {
+    return /^([a-z0-9-]+\.)+cursor\.sh$/i.test(hostname);
+}
+/**
+ * Normalize a GetServerConfig agent URL to an https origin.
+ * Returns null for missing, malformed, non-https, or non-*.cursor.sh hosts.
+ */
+export function normalizeAgentRunOrigin(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    const trimmed = String(raw).trim();
+    if (!trimmed)
+        return null;
+    try {
+        const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+        const parsed = new URL(withScheme);
+        if (parsed.protocol !== "https:")
+            return null;
+        if (parsed.username || parsed.password)
+            return null;
+        if (!isAllowedAgentHost(parsed.hostname))
+            return null;
+        return parsed.origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch the Cursor server config (a Connect unary RPC on the API host) and
+ * return the `agentUrlConfig.agentnUrl` field — the region-specific Run stream
+ * origin the server routes this account/team to (e.g. `agentn.us.api5.cursor.sh`).
+ *
+ * Region-routed accounts can be silently rejected by the wrong regional host, so
+ * this lookup fails closed instead of substituting any host on error. Any
+ * authoritative `*.cursor.sh` origin from GetServerConfig is accepted.
+ */
+export async function fetchAgentUrl(token, options = {}) {
+    const base = resolveApiBaseURL(options);
+    const url = `${base}${SERVER_CONFIG_PATH}`;
+    const clientVersion = await resolveClientVersion();
+    // Match Cursor CLI: GetServerConfig uses base headers only — session headers belong on Run.
+    const headers = buildBaseHeaders(token, clientVersion);
+    trace(`GetServerConfig POST ${url}`);
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...headers,
+            "content-type": "application/json",
+            accept: "application/json",
+        },
+        body: JSON.stringify({ telem_enabled: options.telemetryEnabled ?? false }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`GetServerConfig failed: ${res.status} ${res.statusText}${text ? ` - ${text.slice(0, 200)}` : ""}`);
+    }
+    const body = (await res.json());
+    const cfg = body.agentUrlConfig;
+    const raw = cfg?.agentnUrl || cfg?.agentUrl;
+    const normalized = normalizeAgentRunOrigin(raw);
+    trace(`GetServerConfig reply: agentnUrl=${cfg?.agentnUrl ?? "<missing>"} ` +
+        `agentUrl=${cfg?.agentUrl ?? "<missing>"} → ${normalized ?? "<invalid>"}`);
+    if (!normalized) {
+        throw new Error(raw
+            ? "GetServerConfig returned an invalid Cursor agent URL"
+            : "GetServerConfig response missing agentUrlConfig.agentnUrl");
+    }
+    return normalized;
+}
 // 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();
@@ -73,8 +131,11 @@ const _http2Connecting = new Map();
 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;
+    const origin = normalizeAgentRunOrigin(baseURL);
+    if (!origin) {
+        throw new Error("Cursor Run stream requires an allowlisted Cursor agent base URL");
+    }
+    return origin;
 }
 function dropSession(origin, session) {
     if (_http2Sessions.get(origin) === session)
@@ -133,7 +194,7 @@ function getSession(baseURL) {
     _http2Connecting.set(origin, promise);
     return promise;
 }
-export async function bidiRunStream(token, options = {}) {
+export async function bidiRunStream(token, options) {
     const [session, clientVersion] = await Promise.all([
         getSession(options.baseURL),
         resolveClientVersion(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -54,12 +54,12 @@
     "protobufjs": "^7.4.0"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": "~1.17.13"
+    "@opencode-ai/plugin": "^1.17.13"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "~1.17.13",
+    "@opencode-ai/plugin": "^1.17.13",
     "@tsconfig/node22": "^22.0.1",
     "@types/node": "^22.15.3",
     "typescript": "^5.8.3"
   }
-}
+}