cursor-opencode-provider 0.4.3 → 0.6.0

package/dist/protocol/messages.js

@@ -174,6 +174,12 @@ export function createMessageTypes() {
     addType(root, "AskQuestionArgs", [
         { id: 1, name: "title", type: "string" },
         { id: 2, name: "questions", type: "AskQuestionItem", repeated: true },
+        // #5/#6 drive Cursor's non-blocking AskQuestion: the client answers the
+        // interaction with `async` right away and delivers the real answers later
+        // through ConversationAction.async_ask_question_completion_action, keyed by
+        // the originating tool call id. See protocol/ask-question.ts.
+        { id: 5, name: "run_async", type: "bool" },
+        { id: 6, name: "async_original_tool_call_id", type: "string" },
     ]);
     addType(root, "AskQuestionToolCall", [{ id: 1, name: "args", type: "AskQuestionArgs" }]);
     addType(root, "FetchToolArgs", [
@@ -187,7 +193,23 @@ export function createMessageTypes() {
         { id: 2, name: "explanation", type: "string" },
         { id: 3, name: "tool_call_id", type: "string" },
     ]);
-    addType(root, "SwitchModeToolCall", [{ id: 1, name: "args", type: "SwitchModeToolArgs" }]);
+    // Display ToolCall.result (CLI success hardcodes from_mode_id=""); distinct from
+    // InteractionResponse approved/rejected, which is the consent gate.
+    addType(root, "SwitchModeSuccess", [
+        { id: 1, name: "from_mode_id", type: "string" },
+        { id: 2, name: "to_mode_id", type: "string" },
+    ]);
+    addType(root, "SwitchModeError", [{ id: 1, name: "error", type: "string" }]);
+    addType(root, "SwitchModeRejected", [{ id: 1, name: "reason", type: "string" }]);
+    addType(root, "SwitchModeResult", [
+        { id: 1, name: "success", type: "SwitchModeSuccess" },
+        { id: 2, name: "error", type: "SwitchModeError" },
+        { id: 3, name: "rejected", type: "SwitchModeRejected" },
+    ], [{ name: "result", fields: ["success", "error", "rejected"] }]);
+    addType(root, "SwitchModeToolCall", [
+        { id: 1, name: "args", type: "SwitchModeToolArgs" },
+        { id: 2, name: "result", type: "SwitchModeResult" },
+    ]);
     addType(root, "PiReadToolArgs", [
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "offset", type: "int32" },
@@ -258,7 +280,27 @@ export function createMessageTypes() {
         { id: 2, name: "file_path", type: "string" },
         { id: 5, name: "reference_image_paths", type: "string", repeated: true },
     ]);
-    addType(root, "GenerateImageToolCall", [{ id: 1, name: "args", type: "GenerateImageToolArgs" }]);
+    // Cursor generates the image server-side and returns it on the display
+    // tool_call frame. `image_data` is a base64 string, not bytes.
+    addType(root, "GenerateImageSuccess", [
+        { id: 1, name: "file_path", type: "string" },
+        { id: 2, name: "image_data", type: "string" },
+    ]);
+    addType(root, "GenerateImageError", [{ id: 1, name: "error", type: "string" }]);
+    addType(root, "GenerateImageResult", [
+        { id: 1, name: "success", type: "GenerateImageSuccess" },
+        { id: 2, name: "error", type: "GenerateImageError" },
+    ], [{ name: "result", fields: ["success", "error"] }]);
+    addType(root, "GenerateImageToolCall", [
+        { id: 1, name: "args", type: "GenerateImageToolArgs" },
+        { id: 2, name: "result", type: "GenerateImageResult" },
+    ]);
+    // InteractionQuery keeps query bodies opaque; decoded on demand like
+    // AskQuestionInteractionQuery.
+    addType(root, "GenerateImageRequestQuery", [
+        { id: 1, name: "args", type: "GenerateImageToolArgs" },
+        { id: 2, name: "tool_call_id", type: "string" },
+    ]);
     addType(root, "ToolCall", [
         { id: 57, name: "tool_call_id", type: "string" },
         { id: 1, name: "shell_tool_call", type: "ShellToolCall" },
@@ -455,10 +497,20 @@ export function createMessageTypes() {
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "error", type: "string" },
     ]);
+    // Cursor's own executor reports a refused write with this variant rather than
+    // a generic error, and its agent reads `operation` / `is_readonly` back.
+    addType(root, "WritePermissionDenied", [
+        { id: 1, name: "path", type: "string" },
+        { id: 2, name: "directory", type: "string" },
+        { id: 3, name: "operation", type: "string" },
+        { id: 4, name: "error", type: "string" },
+        { id: 5, name: "is_readonly", type: "bool" },
+    ]);
     addType(root, "WriteResult", [
         { id: 1, name: "success", type: "WriteSuccess" },
+        { id: 3, name: "permission_denied", type: "WritePermissionDenied" },
         { id: 5, name: "error", type: "WriteError" },
-    ], [{ name: "result", fields: ["success", "error"] }]);
+    ], [{ name: "result", fields: ["success", "permission_denied", "error"] }]);
     // agent.v1 Pi exec results. Cursor places Pi requests at ExecServerMessage
     // fields #45..#51 and their corresponding ExecClientMessage results at
     // #46..#52 (the result fields are deliberately offset by one).
@@ -1069,11 +1121,29 @@ export function createMessageTypes() {
     addType(root, "CancelAction", [
         { id: 1, name: "conversation_id", type: "string" },
     ]);
+    // Deferred answers for an AskQuestion the client already replied to with
+    // `async`. `original_args` is kept as raw bytes so the exact AskQuestionArgs
+    // Cursor sent — including fields this schema does not model — is echoed back
+    // verbatim rather than re-encoded from a lossy decode.
+    addType(root, "AsyncAskQuestionCompletionAction", [
+        { id: 1, name: "original_tool_call_id", type: "string" },
+        { id: 2, name: "original_args", type: "bytes" },
+        { id: 3, name: "result", type: "AskQuestionResult" },
+    ]);
     addType(root, "ConversationAction", [
         { id: 1, name: "user_message_action", type: "UserMessageAction" },
         { id: 2, name: "resume_action", type: "ResumeAction" },
         { id: 3, name: "cancel_action", type: "CancelAction" },
-    ], [{ name: "action", fields: ["user_message_action", "resume_action", "cancel_action"] }]);
+        { id: 8, name: "async_ask_question_completion_action", type: "AsyncAskQuestionCompletionAction" },
+    ], [{
+            name: "action",
+            fields: [
+                "user_message_action",
+                "resume_action",
+                "cancel_action",
+                "async_ask_question_completion_action",
+            ],
+        }]);
     // Seed ConversationStateStructure for turn 1 (system prompt as JSON strings
     // in #1). After the first conversation_checkpoint_update we echo opaque
     // server bytes instead — CLI's live structure uses blob-id bytes in #1/#8.
@@ -1090,10 +1160,30 @@ export function createMessageTypes() {
     addType(root, "ConversationTurn", [
         { id: 1, name: "agent_conversation_turn", type: "AgentConversationTurn" },
     ], [{ name: "turn", fields: ["agent_conversation_turn"] }]);
-    // Seed-only schema (JSON strings). Checkpoint bytes are never decoded here —
-    // AgentRunRequest.conversation_state is typed as bytes and carries them opaque.
+    // Cursor checkpoints carry authoritative context occupancy in field #5. The
+    // provider still transports the complete checkpoint as opaque bytes; these
+    // declarations support targeted diagnostics/tests without a re-encode.
+    addType(root, "PromptTokenBreakdownCategory", [
+        { id: 1, name: "id", type: "string" },
+        { id: 2, name: "label", type: "string" },
+        { id: 3, name: "estimated_tokens", type: "uint32" },
+        { id: 4, name: "character_count", type: "uint32" },
+    ]);
+    addType(root, "PromptTokenBreakdownSnapshot", [
+        { id: 1, name: "total_used_tokens", type: "uint32" },
+        { id: 2, name: "max_tokens", type: "uint32" },
+        { id: 3, name: "categories", type: "PromptTokenBreakdownCategory", repeated: true },
+    ]);
+    addType(root, "ConversationTokenDetails", [
+        { id: 1, name: "used_tokens", type: "uint32" },
+        { id: 2, name: "max_tokens", type: "uint32" },
+        { id: 3, name: "breakdown", type: "PromptTokenBreakdownSnapshot" },
+    ]);
+    // Seed schema (JSON strings). AgentRunRequest.conversation_state remains
+    // bytes, so live checkpoints are never decoded/re-encoded on transport.
     addType(root, "ConversationStateStructure", [
         { id: 1, name: "root_prompt_messages_json", type: "string", repeated: true },
+        { id: 5, name: "token_details", type: "ConversationTokenDetails" },
         { id: 8, name: "turns", type: "ConversationTurn", repeated: true },
     ]);
     addType(root, "ModelDetails", [
@@ -1113,6 +1203,7 @@ export function createMessageTypes() {
         { id: 12, name: "field_12", type: "uint32" },
         { id: 14, name: "selected_subagent_models", type: "RequestedModel", repeated: true },
         { id: 16, name: "conversation_group_id", type: "string" },
+        { id: 25, name: "run_id", type: "string" },
     ]);
     // ── Client heartbeat ──
     addType(root, "ClientHeartbeat", []);
@@ -1151,18 +1242,42 @@ export function createMessageTypes() {
         { id: 2, name: "rejected", type: "WebSearchRequestRejected" },
     ], [{ name: "result", fields: ["approved", "rejected"] }]);
     addType(root, "AskQuestionRejected", [{ id: 1, name: "reason", type: "string" }]);
+    addType(root, "AskQuestionError", [{ id: 1, name: "error_message", type: "string" }]);
+    addType(root, "AskQuestionAsync", []);
+    addType(root, "AskQuestionSuccessAnswer", [
+        { id: 1, name: "question_id", type: "string" },
+        { id: 2, name: "selected_option_ids", type: "string", repeated: true },
+        { id: 3, name: "freeform_text", type: "string" },
+    ]);
+    addType(root, "AskQuestionSuccess", [
+        { id: 1, name: "answers", type: "AskQuestionSuccessAnswer", repeated: true },
+    ]);
     addType(root, "AskQuestionResult", [
+        { id: 1, name: "success", type: "AskQuestionSuccess" },
+        { id: 2, name: "error", type: "AskQuestionError" },
         { id: 3, name: "rejected", type: "AskQuestionRejected" },
-    ], [{ name: "result", fields: ["rejected"] }]);
+        { id: 4, name: "async", type: "AskQuestionAsync" },
+    ], [{ name: "result", fields: ["success", "error", "rejected", "async"] }]);
     addType(root, "AskQuestionInteractionResponse", [
         { id: 1, name: "result", type: "AskQuestionResult" },
     ]);
+    // InteractionQuery keeps query bodies opaque (see the InteractionQuery
+    // comment); this type decodes only the ask-question body on demand.
+    addType(root, "AskQuestionInteractionQuery", [
+        { id: 1, name: "args", type: "AskQuestionArgs" },
+        { id: 2, name: "tool_call_id", type: "string" },
+    ]);
     addType(root, "SwitchModeRequestApproved", []);
     addType(root, "SwitchModeRequestRejected", [{ id: 1, name: "reason", type: "string" }]);
     addType(root, "SwitchModeRequestResponse", [
         { id: 1, name: "approved", type: "SwitchModeRequestApproved" },
         { id: 2, name: "rejected", type: "SwitchModeRequestRejected" },
     ], [{ name: "result", fields: ["approved", "rejected"] }]);
+    // InteractionQuery keeps query bodies opaque; decoded on demand like
+    // AskQuestionInteractionQuery / CreatePlanRequestQuery.
+    addType(root, "SwitchModeRequestQuery", [
+        { id: 1, name: "args", type: "SwitchModeToolArgs" },
+    ]);
     addType(root, "CreatePlanSuccess", []);
     addType(root, "CreatePlanError", [{ id: 1, name: "error", type: "string" }]);
     addType(root, "CreatePlanResult", [
@@ -1173,6 +1288,12 @@ export function createMessageTypes() {
     addType(root, "CreatePlanRequestResponse", [
         { id: 1, name: "result", type: "CreatePlanResult" },
     ]);
+    // InteractionQuery keeps query bodies opaque; decoded on demand like
+    // AskQuestionInteractionQuery / GenerateImageRequestQuery.
+    addType(root, "CreatePlanRequestQuery", [
+        { id: 1, name: "args", type: "CreatePlanArgs" },
+        { id: 2, name: "tool_call_id", type: "string" },
+    ]);
     addType(root, "SetupVmEnvironmentSuccess", []);
     addType(root, "SetupVmEnvironmentResult", [
         { id: 1, name: "success", type: "SetupVmEnvironmentSuccess" },
@@ -1273,10 +1394,22 @@ export function createMessageTypes() {
         { id: 1, name: "run_request", type: "AgentRunRequest" },
         { id: 2, name: "exec_client_message", type: "ExecClientMessage" },
         { id: 3, name: "kv_client_message", type: "KvClientMessage" },
+        { id: 4, name: "conversation_action", type: "ConversationAction" },
         { id: 5, name: "exec_client_control_message", type: "ExecClientControlMessage" },
         { id: 6, name: "interaction_response", type: "InteractionResponse" },
         { id: 7, name: "client_heartbeat", type: "ClientHeartbeat" },
-    ], [{ name: "message", fields: ["run_request", "exec_client_message", "kv_client_message", "exec_client_control_message", "interaction_response", "client_heartbeat"] }]);
+    ], [{
+            name: "message",
+            fields: [
+                "run_request",
+                "exec_client_message",
+                "kv_client_message",
+                "conversation_action",
+                "exec_client_control_message",
+                "interaction_response",
+                "client_heartbeat",
+            ],
+        }]);
     // ── AgentServerMessage ──
     addType(root, "AgentServerMessage", [
         { id: 1, name: "interaction_update", type: "InteractionUpdate" },
@@ -1343,6 +1476,13 @@ export function decodeMessage(typeName, data) {
     const decoded = type.decode(data);
     return type.toObject(decoded, { defaults: true, json: true, longs: Number });
 }
+/** Decode without inventing absent proto defaults (used for byte-stable snapshots). */
+export function decodeMessageSparse(typeName, data) {
+    const root = getMessageTypes();
+    const type = root.lookupType(typeName);
+    const decoded = type.decode(data);
+    return type.toObject(decoded, { json: true, longs: Number });
+}
 /** Schema-free walk of one message's top-level wire fields (no nested descent). */
 function readRawFields(buf) {
     const reader = protobuf.Reader.create(buf);

package/dist/protocol/request.d.ts

@@ -9,6 +9,8 @@ export type RunRequestInput = {
     images?: CursorImageInput[];
     modelId: string;
     conversationId: string;
+    /** Stable parent group; unlike conversationId, this survives compaction/rebase. */
+    conversationGroupId?: string;
     systemPrompt?: string;
     /**
      * Prior chat turns for a seed ConversationStateStructure (no checkpoint).

package/dist/protocol/request.js

@@ -76,6 +76,8 @@ export function buildRunRequest(input) {
         });
     const runRequest = {
         conversation_id: input.conversationId,
+        conversation_group_id: input.conversationGroupId ?? input.conversationId,
+        run_id: msgId,
         action,
         requested_model: {
             // The provider always selects a concrete model. Cursor's "default"

package/dist/protocol/switch-mode.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Cursor-native SwitchMode ⇄ OpenCode `plan_enter` / `plan_exit`.
+ *
+ * Cursor raises `switch_mode_request_query` (#4) with SwitchModeArgs and blocks
+ * until the client replies approved{} or rejected{reason} (no async variant).
+ * Cursor CLI prompts the user, then flips unifiedMode and injects a
+ * `<system_reminder>` describing how to behave in that mode.
+ * Display `switch_mode_tool_call` (#25) is a separate transcript record and is
+ * not replayed as a host tool.
+ *
+ * Host mapping (advertisement-gated):
+ * - plan, spec → plan_enter
+ * - every other non-empty target → plan_exit (leave plan for OpenCode build),
+ *   then inject the Cursor CLI-shaped mode reminder for that target
+ *
+ * Upstream OpenCode's plan tools are not mode flags. Each one asks the user
+ * through the Question service and, on "Yes", injects a synthetic user message
+ * carrying `agent: "plan" | "build"`, which `createUserMessage` turns into a
+ * `setAgentModel` primary-agent switch (opencode `tool/plan.ts`,
+ * `session/prompt.ts`). A provider cannot reach `setAgentModel`, but the two
+ * observable halves — the approval gate and the behavioural contract — are both
+ * reachable, so the bridge degrades instead of refusing when the host tool is
+ * missing (`plan_enter` is commented out upstream and `plan_exit` is gated
+ * behind OPENCODE_EXPERIMENTAL_PLAN_MODE + CLI client):
+ *
+ * - entering plan/spec needs no host tool at all — approve immediately and let
+ *   the injected <system_reminder> carry the contract, exactly as Cursor CLI's
+ *   own plan mode is prompt-enforced.
+ * - leaving plan mode is the gate the user must actually see, so it falls back
+ *   to the host `question` tool and only rejects when that is absent too.
+ *
+ * Resolution is keyed solely on the advertised catalog under canonical tool
+ * names — never on host identity or model id. A compatibility layer may restate
+ * alternate host vocabulary under canonical names before the provider sees the
+ * catalog, so the bridge itself remains OpenCode-shaped.
+ *
+ * CLI reject reason for user declines: "Mode switch rejected by user"
+ * (chunk-7076/dist/ui.js onSwitchModeReject).
+ */
+import { type OpencodeQuestionInput } from "./ask-question.js";
+/**
+ * `PendingExec.resultField` for a held-open SwitchMode InteractionQuery.
+ * Continuation writes an InteractionResponse, not an ExecClientMessage.
+ */
+export declare const SWITCH_MODE_RESULT_FIELD = "switch_mode_request_response";
+/** CLI verbatim when the user rejects the mode switch. */
+export declare const USER_REJECTED_REASON = "Mode switch rejected by user";
+export declare const MISSING_QUERY_REASON = "Missing switch-mode query";
+export declare const MISSING_ARGS_REASON = "Missing switch-mode arguments";
+export declare const MISSING_TARGET_REASON = "Missing targetModeId";
+/**
+ * A turn that cannot call host tools is a lifecycle turn (title generation,
+ * compaction, summarization). OpenCode opens one alongside the real Run, and it
+ * must not mutate session state — approving there flips plan mode twice and
+ * lets the throwaway turn write its own plan file.
+ *
+ * Soft-ack with `approved{}` instead of `rejected{reason}`: a hard reject lands
+ * in the transcript and the real turn narrates "mode switches are blocked"
+ * even though the next Run will succeed. CreatePlan already soft-acks the same
+ * case; SwitchMode must match.
+ */
+export declare const PLAN_EXIT_UNAVAILABLE_REASON: string;
+/** Upstream `PlanExitTool` wording, minus a plan path the provider cannot verify. */
+export declare const SWITCH_MODE_EXIT_QUESTION = "Planning is complete. Would you like to switch to the build agent and start implementing?";
+export declare const SWITCH_MODE_EXIT_HEADER = "Build Agent";
+export type SwitchModeHostTool = "plan_enter" | "plan_exit";
+/**
+ * How a SwitchMode query is satisfied this turn.
+ *
+ * - `native`   the host advertises the matching plan tool; bridge to it.
+ * - `approve`  entering plan mode needs no host tool — approve immediately.
+ * - `ack`      lifecycle turn (`allowTools=false`): approve on the wire without
+ *              mutating session mode (same soft-ack pattern as CreatePlan).
+ * - `question` leaving plan mode falls back to the host `question` prompt.
+ * - `reject`   nothing can satisfy it; `reason` names the real cause.
+ */
+export type SwitchModeBridge = {
+    kind: "native";
+    toolName: SwitchModeHostTool;
+} | {
+    kind: "approve";
+} | {
+    kind: "ack";
+} | {
+    kind: "question";
+    input: OpencodeQuestionInput;
+} | {
+    kind: "reject";
+    reason: string;
+};
+export type CursorSwitchModeArgs = {
+    targetModeId: string;
+    explanation: string;
+    toolCallId: string;
+};
+export type DecodedSwitchModeQuery = {
+    args: CursorSwitchModeArgs;
+    toolCallId: string;
+};
+export type SwitchModeMapping = {
+    ok: true;
+    toolName: SwitchModeHostTool;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Normalize Cursor mode ids for comparison. */
+export declare function normalizeSwitchModeId(targetModeId: string): string;
+/**
+ * Map a Cursor unified-mode id onto an OpenCode plan enter/exit tool.
+ * Does not check advertisement — callers gate on the host catalog.
+ *
+ * plan/spec enter plan; every other non-empty target leaves plan via plan_exit
+ * (host-portable primary switch) and relies on {@link cursorModeSystemReminder}
+ * for CLI-shaped behavioral guidance.
+ */
+export declare function mapSwitchModeTarget(targetModeId: string): SwitchModeMapping;
+/** Host `question` input mirroring upstream `PlanExitTool`'s own prompt. */
+export declare function switchModeExitQuestionInput(): OpencodeQuestionInput;
+/**
+ * Resolve how this SwitchMode target is satisfied, keyed only on the advertised
+ * catalog under canonical tool names.
+ *
+ * A missing plan tool is not a refusal: entering plan mode needs no host tool,
+ * and leaving it degrades to the `question` prompt so the user still approves
+ * before any execution starts.
+ */
+export declare function resolveSwitchModeBridge(targetModeId: string, options: {
+    allowTools: boolean;
+    advertised: ReadonlySet<string> | Iterable<string>;
+    /** Cursor unified mode currently recorded for this session, if any. */
+    activeModeId?: string;
+}): SwitchModeBridge;
+/** Decode a `switch_mode_request_query` body, or undefined when unusable. */
+export declare function decodeSwitchModeQuery(queryBytes: Uint8Array): DecodedSwitchModeQuery | undefined;
+/** OpenCode plan_enter / plan_exit advertise empty input. */
+export declare function switchModeToolInput(): Record<string, never>;
+/** Shape `approved{}` / `rejected{reason}` for encodeMessage. */
+export declare function switchModeApprovedResult(): Record<string, unknown>;
+export declare function switchModeRejectedResult(reason: string): Record<string, unknown>;
+/**
+ * Host tool outcome → Cursor SwitchModeRequestResponse.
+ * Question/permission declines and empty failures use the CLI user-reject string.
+ */
+export declare function switchModeResultFromToolOutput(output: string, isError: boolean): Record<string, unknown>;
+/**
+ * Host `question` outcome → Cursor SwitchModeRequestResponse, for the emulated
+ * plan exit. Only an explicit "Yes" approves; an unanswered or dismissed prompt
+ * keeps the model in plan mode rather than silently starting execution.
+ */
+export declare function switchModeResultFromQuestionOutput(output: string, isError: boolean): Record<string, unknown>;
+/** Record the approved Cursor mode for later system-reminder injection. */
+export declare function setActiveCursorMode(sessionKey: string | undefined, targetModeId: string, options?: {
+    bridgedPlanEntered?: boolean;
+}): void;
+export declare function getActiveCursorMode(sessionKey: string | undefined): string | undefined;
+/** True while the provider has an approved Cursor plan/spec mode for this session. */
+export declare function isCursorPlanModeActive(sessionKey: string | undefined): boolean;
+/** True after a bridged plan/spec Run has observed plan_enter removed by the host. */
+export declare function isBridgedCursorPlanModeActive(sessionKey: string | undefined): boolean;
+export declare function clearActiveCursorMode(sessionKey: string | undefined): void;
+export declare function resetActiveCursorModesForTests(): void;
+/**
+ * Cursor CLI-shaped mode reminder for the active unified mode.
+ * Tool names are adapted to OpenCode (`task`, `question`) where the CLI names
+ * Cursor-only tools; the behavioral contract matches the CLI reminders.
+ */
+export declare function cursorModeSystemReminder(targetModeId: string, options?: {
+    firstTurn?: boolean;
+    planExitAdvertised?: boolean;
+}): string | undefined;
+/**
+ * Consume the active-mode reminder for this OpenCode session.
+ * Marks the mode as no longer first-turn after the first successful read.
+ */
+export declare function takeActiveCursorModeReminder(sessionKey: string | undefined, options?: {
+    advertisedTools?: ReadonlySet<string> | Iterable<string>;
+}): string | undefined;