cursor-opencode-provider 0.2.7 → 0.2.9

package/dist/replay-safety.js

@@ -0,0 +1,126 @@
+import { trace } from "./debug.js";
+import { readAllFieldsStrict } from "./protocol/struct.js";
+export class AttemptReplaySafety {
+    sessionId;
+    barrierReason;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    markBarrier(reason) {
+        if (this.barrierReason)
+            return;
+        this.barrierReason = reason;
+        trace(`replay barrier: reason=${reason} sessionId=${this.sessionId}`);
+    }
+    applyTo(failure) {
+        failure.replaySafe = this.barrierReason === undefined && failure.replaySafe;
+        if (this.barrierReason) {
+            trace(`replay suppressed: reason=${this.barrierReason} sessionId=${this.sessionId}`);
+        }
+        return failure;
+    }
+}
+const INTERACTION_UPDATE_FIELDS = new Set([1, 2, 3, 4, 7, 13, 14, 16, 17]);
+const INTERACTION_QUERY_FIELDS = new Set([2, 3, 4, 7, 8, 9, 10, 11, 12, 13, 14]);
+const TOP_LEVEL_FIELDS = new Set([1, 2, 3, 4, 5, 7]);
+function nestedFields(topLevel, field) {
+    if (topLevel?.fn !== field || topLevel.wt !== 2 || !topLevel.bytes)
+        return [];
+    return readAllFieldsStrict(topLevel.bytes) ?? [];
+}
+function analyzeExecWire(topLevel) {
+    const variants = nestedFields(topLevel, 2)
+        .filter((field) => ![1, 15, 19].includes(field.fn));
+    const exactVariant = (field) => variants.length === 1 && variants[0].fn === field && variants[0].wt === 2;
+    return {
+        exactRequestContext: exactVariant(10),
+        exactMcpState: exactVariant(36),
+    };
+}
+function validKvWire(topLevel) {
+    const variants = nestedFields(topLevel, 4).filter((field) => field.fn !== 1);
+    const variant = variants.length === 1 ? variants[0] : undefined;
+    const args = variant?.wt === 2 && variant.bytes
+        ? (readAllFieldsStrict(variant.bytes) ?? [])
+        : [];
+    const blobIds = args.filter((field) => field.fn === 1 && field.wt === 2 && (field.bytes?.length ?? 0) > 0);
+    return !!variant
+        && [2, 3].includes(variant.fn)
+        && variant.wt === 2
+        && blobIds.length === 1
+        && args.every((field) => field.wt === 2 && (field.fn === 1 || (variant.fn === 3 && field.fn === 2)));
+}
+function validInteractionUpdateWire(topLevel, decoded) {
+    if (!decoded)
+        return true;
+    const fields = nestedFields(topLevel, 1);
+    const update = fields.length === 1 ? fields[0] : undefined;
+    if (!update || update.wt !== 2 || !INTERACTION_UPDATE_FIELDS.has(update.fn))
+        return false;
+    if (![1, 4].includes(update.fn))
+        return true;
+    const delta = update.bytes ? (readAllFieldsStrict(update.bytes) ?? []) : [];
+    return delta.length === 1 && delta[0].fn === 1 && delta[0].wt === 2;
+}
+function validInteractionQueryWire(topLevel, decoded) {
+    if (!decoded)
+        return true;
+    const fields = nestedFields(topLevel, 7);
+    const ids = fields.filter((field) => field.fn === 1);
+    const variants = fields.filter((field) => field.fn !== 1);
+    return ids.length <= 1
+        && ids.every((field) => field.wt === 0)
+        && variants.length === 1
+        && variants[0].wt === 2
+        && INTERACTION_QUERY_FIELDS.has(variants[0].fn);
+}
+function decodedMatchesWire(topLevel, decoded) {
+    return !((topLevel?.fn === 1 && !decoded.interactionUpdate)
+        || (topLevel?.fn === 2 && !decoded.exec)
+        || (topLevel?.fn === 4 && !decoded.kv)
+        || (topLevel?.fn === 5 && !decoded.execControl)
+        || (topLevel?.fn === 7 && !decoded.interactionQuery));
+}
+function hasSemanticProgress(decoded) {
+    const update = decoded.interactionUpdate;
+    const text = update?.text_delta?.text;
+    const thinking = update?.thinking_delta?.text;
+    return (typeof text === "string" && text.length > 0)
+        || (typeof thinking === "string" && thinking.length > 0)
+        || !!update?.turn_ended
+        || !!update?.tool_call_started
+        || !!update?.tool_call_completed
+        || !!decoded.exec
+        || !!decoded.kv
+        || !!decoded.execControl
+        || !!decoded.interactionQuery
+        || !!decoded.checkpointBytes?.length;
+}
+/** Classify one decoded server frame without performing any protocol side effects. */
+export function analyzeReplayFrame(payload, decoded) {
+    const topLevelFields = readAllFieldsStrict(payload) ?? [];
+    const topLevel = topLevelFields.length === 1 ? topLevelFields[0] : undefined;
+    const exec = analyzeExecWire(topLevel);
+    const validKv = validKvWire(topLevel);
+    const malformed = !topLevel
+        || topLevel.wt !== 2
+        || !TOP_LEVEL_FIELDS.has(topLevel.fn)
+        || !validInteractionUpdateWire(topLevel, decoded.interactionUpdate)
+        || !validInteractionQueryWire(topLevel, decoded.interactionQuery)
+        || !decodedMatchesWire(topLevel, decoded)
+        || !!decoded.execControl;
+    let barrier;
+    if (decoded.interactionUpdate?.tool_call_started || decoded.interactionUpdate?.tool_call_completed) {
+        barrier = "display-tool-lifecycle";
+    }
+    else if (malformed || (topLevel.fn === 4 && !validKv)) {
+        barrier = "unknown-or-malformed-frame";
+    }
+    else if (topLevel.fn === 2 && !exec.exactRequestContext && !exec.exactMcpState) {
+        barrier = "non-control-exec";
+    }
+    return {
+        semanticProgress: hasSemanticProgress(decoded),
+        barrier,
+    };
+}

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 import type { BidiStream } from "./transport/connect.js";
 import { type CursorProviderError } from "./errors.js";
 import { type SessionActivitySource } from "./activity.js";
+import type { HostSubagentCatalog, ToolAliasRegistry } from "./protocol/tools.js";
 export type Frame = {
     flags: number;
     payload: Uint8Array;
@@ -117,6 +118,10 @@ export type CursorSession = {
     blobs: Map<string, Uint8Array>;
     /** McpToolDefinition list advertised this turn — echoed into the request_context reply. */
     toolDescriptors: Array<Record<string, unknown>>;
+    /** Cursor-facing web alias → exact executable host tool for this Run. */
+    toolAliases?: ToolAliasRegistry;
+    /** Spawnable host agents extracted from this turn's Task/Actor definition. */
+    subagentCatalog?: HostSubagentCatalog;
     /** Full RequestContext for exec #10 replies. */
     requestContext: Record<string, unknown>;
     /**

package/dist/transport/connect.d.ts

@@ -5,6 +5,7 @@ export declare function unaryAvailableModels(token: string, options?: {
     apiBaseURL?: string;
     baseURL?: string;
     headers?: Record<string, string>;
+    timeoutMs?: number;
 }): Promise<Record<string, unknown>>;
 /**
  * Cursor Run stream hosts from GetServerConfig / agentBaseURL.
@@ -30,6 +31,7 @@ export declare function fetchAgentUrl(token: string, options?: {
     apiBaseURL?: string;
     baseURL?: string;
     telemetryEnabled?: boolean;
+    timeoutMs?: number;
 }): Promise<string>;
 export type BidiStream = {
     write(msg: Uint8Array): boolean | void;

package/dist/transport/connect.js

@@ -5,8 +5,25 @@ import { getDeviceIds } from "../protocol/device-id.js";
 import { resolveClientVersion } from "../protocol/client-version.js";
 import { trace } from "../debug.js";
 import { CursorLocalCancellationError, CursorProtocolError, CursorTransportError, cursorGrpcError, cursorHttpError, errorCode, CursorProviderError, } from "../errors.js";
+import { withAbortDeadline } from "../deadline.js";
 import http2 from "node:http2";
 const API_BASE = `https://${CURSOR_API_HOST}`;
+const DEFAULT_UNARY_TIMEOUT_MS = 5_000;
+const MAX_TIMER_MS = 2_147_483_647;
+function unaryTimeoutMs(operation, value) {
+    const timeoutMs = value ?? DEFAULT_UNARY_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMER_MS) {
+        throw new CursorProtocolError(`${operation} timeout must be a positive integer no greater than ${MAX_TIMER_MS}`, { code: "CURSOR_INVALID_TIMEOUT" });
+    }
+    return timeoutMs;
+}
+async function withUnaryDeadline(operation, timeoutMs, timeoutCode, run) {
+    return withAbortDeadline(timeoutMs, () => new CursorTransportError(`${operation} timed out after ${timeoutMs}ms`, {
+        transient: true,
+        replaySafe: true,
+        code: timeoutCode,
+    }), run);
+}
 function resolveApiBaseURL(options) {
     return new URL(options.apiBaseURL ?? options.baseURL ?? API_BASE).origin;
 }
@@ -33,42 +50,46 @@ export function buildBaseHeaders(token, clientVersion, extra) {
 export async function unaryAvailableModels(token, options = {}) {
     const base = resolveApiBaseURL(options);
     const url = `${base}/aiserver.v1.AiService/AvailableModels`;
-    const clientVersion = await resolveClientVersion();
-    const headers = buildBaseHeaders(token, clientVersion, options.headers);
-    let res;
-    try {
-        res = await fetch(url, {
-            method: "POST",
-            headers: {
-                ...headers,
-                "content-type": "application/json",
-                accept: "application/json",
-            },
-            // Request parameterized effort/context/fast variants like Cursor IDE.
-            body: JSON.stringify({
-                includeLongContextModels: true,
-                useModelParameters: true,
-                useCloudAgentEffortModes: true,
-            }),
-        });
-    }
-    catch (cause) {
-        throw new CursorTransportError("AvailableModels network request failed", {
-            transient: true,
-            replaySafe: true,
-            code: errorCode(cause),
-            cause,
-        });
-    }
-    if (!res.ok) {
-        throw await cursorHttpResponseError("AvailableModels failed:", res);
-    }
-    try {
-        return (await res.json());
-    }
-    catch (cause) {
-        throw new CursorProtocolError("AvailableModels returned malformed JSON", { cause });
-    }
+    const timeoutMs = unaryTimeoutMs("AvailableModels", options.timeoutMs);
+    return withUnaryDeadline("AvailableModels", timeoutMs, "CURSOR_AVAILABLE_MODELS_TIMEOUT", async (signal) => {
+        const clientVersion = await resolveClientVersion();
+        const headers = buildBaseHeaders(token, clientVersion, options.headers);
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    ...headers,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                // Request parameterized effort/context/fast variants like Cursor IDE.
+                body: JSON.stringify({
+                    includeLongContextModels: true,
+                    useModelParameters: true,
+                    useCloudAgentEffortModes: true,
+                }),
+                signal,
+            });
+        }
+        catch (cause) {
+            throw new CursorTransportError("AvailableModels network request failed", {
+                transient: true,
+                replaySafe: true,
+                code: errorCode(cause),
+                cause,
+            });
+        }
+        if (!res.ok) {
+            throw await cursorHttpResponseError("AvailableModels failed:", res);
+        }
+        try {
+            return (await res.json());
+        }
+        catch (cause) {
+            throw new CursorProtocolError("AvailableModels returned malformed JSON", { cause });
+        }
+    });
 }
 // ── Unary (GetServerConfig) ──
 /**
@@ -116,51 +137,55 @@ export function normalizeAgentRunOrigin(raw) {
 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}`);
-    let res;
-    try {
-        res = await fetch(url, {
-            method: "POST",
-            headers: {
-                ...headers,
-                "content-type": "application/json",
-                accept: "application/json",
-            },
-            body: JSON.stringify({ telem_enabled: options.telemetryEnabled ?? false }),
-        });
-    }
-    catch (cause) {
-        throw new CursorTransportError("GetServerConfig network request failed", {
-            transient: true,
-            replaySafe: true,
-            code: errorCode(cause),
-            cause,
-        });
-    }
-    if (!res.ok) {
-        throw await cursorHttpResponseError("GetServerConfig failed:", res);
-    }
-    let body;
-    try {
-        body = (await res.json());
-    }
-    catch (cause) {
-        throw new CursorProtocolError("GetServerConfig returned malformed JSON", { cause });
-    }
-    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 CursorProtocolError(raw
-            ? "GetServerConfig returned an invalid Cursor agent URL"
-            : "GetServerConfig response missing agentUrlConfig.agentnUrl");
-    }
-    return normalized;
+    const timeoutMs = unaryTimeoutMs("GetServerConfig", options.timeoutMs);
+    return withUnaryDeadline("GetServerConfig", timeoutMs, "CURSOR_AGENT_URL_TIMEOUT", async (signal) => {
+        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}`);
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    ...headers,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                body: JSON.stringify({ telem_enabled: options.telemetryEnabled ?? false }),
+                signal,
+            });
+        }
+        catch (cause) {
+            throw new CursorTransportError("GetServerConfig network request failed", {
+                transient: true,
+                replaySafe: true,
+                code: errorCode(cause),
+                cause,
+            });
+        }
+        if (!res.ok) {
+            throw await cursorHttpResponseError("GetServerConfig failed:", res);
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch (cause) {
+            throw new CursorProtocolError("GetServerConfig returned malformed JSON", { cause });
+        }
+        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 CursorProtocolError(raw
+                ? "GetServerConfig returned an invalid Cursor agent URL"
+                : "GetServerConfig response missing agentUrlConfig.agentnUrl");
+        }
+        return normalized;
+    });
 }
 export class CursorRunInterruptedError extends CursorTransportError {
     constructor(message = "Cursor Run ended before turn_ended", options) {
@@ -217,7 +242,6 @@ const CONNECT_TIMEOUT_MS = 15_000;
 const DEFAULT_SESSION_PING_TIMEOUT_MS = 5_000;
 const DEFAULT_READ_IDLE_MS = 120_000;
 const WRITE_DRAIN_TIMEOUT_CODE = "CURSOR_WRITE_DRAIN_TIMEOUT";
-const MAX_TIMER_MS = 2_147_483_647;
 export const HTTP2_SESSION_MAX_AGE_MS = 15 * 60_000;
 export function shouldReuseHttp2Session(state, createdAt, now = Date.now()) {
     return !state.destroyed && !state.closed && now - createdAt < HTTP2_SESSION_MAX_AGE_MS;

package/dist/web-tools.d.ts

@@ -0,0 +1,34 @@
+import { type ToolContext, type ToolResult } from "@opencode-ai/plugin";
+export type OpenCodeWebSearchArgs = {
+    query: string;
+    numResults?: number;
+    livecrawl?: "fallback" | "preferred";
+    type?: "auto" | "fast" | "deep";
+    contextMaxCharacters?: number;
+};
+export declare function parseOpenCodeWebSearchResponse(raw: string): string | undefined;
+export declare function executeOpenCodeWebSearch(args: OpenCodeWebSearchArgs, context: ToolContext, fetchImpl?: typeof fetch): Promise<ToolResult>;
+export declare const openCodeWebSearchTool: {
+    description: string;
+    args: {
+        query: import("zod").ZodString;
+        numResults: import("zod").ZodOptional<import("zod").ZodNumber>;
+        livecrawl: import("zod").ZodOptional<import("zod").ZodEnum<{
+            fallback: "fallback";
+            preferred: "preferred";
+        }>>;
+        type: import("zod").ZodOptional<import("zod").ZodEnum<{
+            fast: "fast";
+            auto: "auto";
+            deep: "deep";
+        }>>;
+        contextMaxCharacters: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        query: string;
+        numResults?: number | undefined;
+        livecrawl?: "fallback" | "preferred" | undefined;
+        type?: "fast" | "auto" | "deep" | undefined;
+        contextMaxCharacters?: number | undefined;
+    }, context: ToolContext): Promise<ToolResult>;
+};

package/dist/web-tools.js

@@ -0,0 +1,127 @@
+import { tool } from "@opencode-ai/plugin";
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+const WEB_SEARCH_TIMEOUT_MS = 25_000;
+function exaMcpUrl() {
+    const apiKey = process.env.EXA_API_KEY;
+    if (!apiKey)
+        return EXA_MCP_URL;
+    const url = new URL(EXA_MCP_URL);
+    url.searchParams.set("exaApiKey", apiKey);
+    return url.href;
+}
+function mcpText(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const result = value.result;
+    if (!result || typeof result !== "object")
+        return undefined;
+    const content = result.content;
+    if (!Array.isArray(content))
+        return undefined;
+    for (const item of content) {
+        if (item &&
+            typeof item === "object" &&
+            item.type === "text" &&
+            typeof item.text === "string") {
+            return item.text;
+        }
+    }
+    return undefined;
+}
+export function parseOpenCodeWebSearchResponse(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const text = mcpText(JSON.parse(trimmed));
+        if (text)
+            return text;
+    }
+    catch {
+        // MCP may respond as an SSE stream instead of one JSON object.
+    }
+    for (const line of raw.split("\n")) {
+        if (!line.startsWith("data: "))
+            continue;
+        try {
+            const text = mcpText(JSON.parse(line.slice(6)));
+            if (text)
+                return text;
+        }
+        catch {
+            // Ignore non-JSON SSE events.
+        }
+    }
+    return undefined;
+}
+export async function executeOpenCodeWebSearch(args, context, fetchImpl = fetch) {
+    await context.ask({
+        permission: "websearch",
+        patterns: [args.query],
+        always: ["*"],
+        metadata: {
+            query: args.query,
+            numResults: args.numResults,
+            livecrawl: args.livecrawl,
+            type: args.type,
+            contextMaxCharacters: args.contextMaxCharacters,
+            provider: "exa",
+        },
+    });
+    const controller = new AbortController();
+    const abort = () => controller.abort(context.abort.reason);
+    if (context.abort.aborted)
+        abort();
+    else
+        context.abort.addEventListener("abort", abort, { once: true });
+    const timeout = setTimeout(() => controller.abort(new Error("Web search timed out")), WEB_SEARCH_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(exaMcpUrl(), {
+            method: "POST",
+            headers: {
+                accept: "application/json, text/event-stream",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "tools/call",
+                params: {
+                    name: "web_search_exa",
+                    arguments: {
+                        query: args.query,
+                        type: args.type ?? "auto",
+                        numResults: args.numResults ?? 8,
+                        livecrawl: args.livecrawl ?? "fallback",
+                        contextMaxCharacters: args.contextMaxCharacters,
+                    },
+                },
+            }),
+            signal: controller.signal,
+        });
+        const raw = await response.text();
+        if (!response.ok)
+            throw new Error(`Web search failed (${response.status}): ${raw.slice(0, 500)}`);
+        const output = parseOpenCodeWebSearchResponse(raw) ?? "No search results found. Please try a different query.";
+        return {
+            title: `Exa Web Search: ${args.query}`,
+            output,
+            metadata: { provider: "exa" },
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+        context.abort.removeEventListener("abort", abort);
+    }
+}
+export const openCodeWebSearchTool = tool({
+    description: "Search the web for current information using OpenCode's web search backend.",
+    args: {
+        query: tool.schema.string().describe("Web search query"),
+        numResults: tool.schema.number().int().min(1).max(20).optional(),
+        livecrawl: tool.schema.enum(["fallback", "preferred"]).optional(),
+        type: tool.schema.enum(["auto", "fast", "deep"]).optional(),
+        contextMaxCharacters: tool.schema.number().int().positive().optional(),
+    },
+    execute: executeOpenCodeWebSearch,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -75,4 +75,4 @@
     "@types/node": "^22.15.3",
     "typescript": "^5.8.3"
   }
-}
+}