cursor-opencode-provider 0.4.3 → 0.6.0

package/dist/protocol/interactions.d.ts

@@ -1,14 +1,98 @@
+import { type AskQuestionResultMessage, type DecodedAskQuestionQuery } from "./ask-question.js";
+import { type DecodedGenerateImageQuery } from "./generate-image.js";
+import { CURSOR_PLAN_STAGE_TOOL, type CreatePlanBridge, type DecodedCreatePlanQuery, createPlanApprovalQuestionInput } from "./create-plan.js";
+import { type DecodedSwitchModeQuery, type SwitchModeBridge, type SwitchModeHostTool } from "./switch-mode.js";
 export type InteractionQueryWireInfo = {
     id?: number;
     variantField?: number;
     variantName?: string;
+    /** Raw bytes of the selected variant sub-message, when it is length-delimited. */
+    variantBytes?: Uint8Array;
 };
 export type HandledInteraction = {
     id: number;
     variantField: number;
     variantName: string;
-    outcome: "rejected" | "acknowledged" | "failed";
-    reply: Uint8Array;
+    outcome: "rejected" | "acknowledged" | "failed" | "bridged" | "approved";
+    /**
+     * Immediate reply for this query. Absent for bridged *synchronous* AskQuestion
+     * or SwitchMode: Cursor blocks until the host tool returns, exactly as its own
+     * CLI does while the user is choosing / approving the mode switch.
+     */
+    reply?: Uint8Array;
+    /** Present when `outcome === "bridged"`: the question set to hand OpenCode. */
+    askQuestion?: DecodedAskQuestionQuery;
+    /**
+     * Present when SwitchMode should mutate session mode — bridged to a host
+     * tool, or approved outright when entering plan mode needs none. Absent on
+     * lifecycle soft-acks (`ack`): those reply `approved{}` without recording
+     * a mode. The caller reads `bridge` to decide whether a tool call is emitted,
+     * and `args.targetModeId` to record the active Cursor mode when present.
+     */
+    switchMode?: DecodedSwitchModeQuery & {
+        bridge: SwitchModeBridge;
+        toolName?: SwitchModeHostTool | "question";
+    };
+    /**
+     * Present when CreatePlan needs a host tool: either a native plan stage that
+     * owns the write *and* the approval, or the emulated `question` prompt the
+     * provider raises after writing the plan itself. `planUri` is set only for
+     * the emulated path, where the provider already knows the file it wrote.
+     */
+    createPlan?: DecodedCreatePlanQuery & {
+        bridge: CreatePlanBridge;
+        toolName: typeof CURSOR_PLAN_STAGE_TOOL | "question";
+        planUri?: string;
+        /** Filesystem path of the plan the provider just wrote (emulated path). */
+        planPath?: string;
+        questionInput?: ReturnType<typeof createPlanApprovalQuestionInput>;
+        /** The plan to show the user before they approve it (emulated path only). */
+        planReview?: string;
+    };
+    /** Present when an image generation was approved: the target to expect. */
+    generateImage?: DecodedGenerateImageQuery;
+};
+export type HandleInteractionQueryOptions = {
+    /**
+     * True when the host advertises `question` on this turn and tool calls are
+     * allowed, i.e. the provider can actually surface the prompt to the user.
+     */
+    canBridgeAskQuestion?: boolean;
+    /**
+     * True when tool calls are allowed this turn (needed before advertising can
+     * be checked for plan_enter / plan_exit).
+     */
+    allowTools?: boolean;
+    /**
+     * Host tool names advertised this turn. Used to resolve SwitchMode →
+     * plan_enter / plan_exit only when the matching tool is present.
+     */
+    advertisedTools?: ReadonlySet<string> | Iterable<string>;
+    /**
+     * True when `cursor_image_save` is advertised, i.e. a generated image can be
+     * committed to disk under OpenCode's permission. Approving generation the
+     * provider cannot then save would spend the user's Cursor quota for nothing.
+     */
+    canSaveGeneratedImage?: boolean;
+    /**
+     * Session workspace root used to place CreatePlan files via {@link hostPlansDir}
+     * (host project-config `plans/` in a git worktree, else host global data/plans).
+     */
+    workspaceRoot?: string;
+    /** True when the advertised host plan-stage tool is available. */
+    canBridgeCreatePlan?: boolean;
+    /**
+     * True when the provider has recorded an approved Cursor plan/spec mode for
+     * this session. A written plan then ends with an execution-approval prompt,
+     * which is the transition out of planning; outside plan mode there is none.
+     */
+    planModeActive?: boolean;
+    /**
+     * Cursor unified mode currently recorded for this session. A SwitchMode to
+     * the mode already in effect needs no approval, matching Cursor's own IDE
+     * handler and keeping the plan-approval prompt from firing twice.
+     */
+    activeCursorModeId?: string;
 };
 export declare class UnsupportedInteractionQueryError extends Error {
     constructor(info: InteractionQueryWireInfo);
@@ -20,11 +104,29 @@ export declare class UnsupportedInteractionQueryError extends Error {
  */
 export declare function inspectInteractionQueryWire(agentServerPayload: Uint8Array): InteractionQueryWireInfo;
 /**
- * Build the immediate typed response required by Cursor's Run RPC.
+ * Build the typed response required by Cursor's Run RPC.
+ *
+ * OpenCode has no Cursor UI callbacks, so UI-bound queries get a conservative
+ * headless policy (reject; ack a few no-UI cases).
  *
- * OpenCode has no Cursor UI callbacks, so every InteractionQuery is answered
- * here with a conservative headless policy (reject UI-bound prompts; ack a few
- * no-UI cases). See case 7 / F14 for create_plan auto-ack parity with Cursor
- * CLI headless mode.
+ * Bridged / persisted exceptions:
+ * - AskQuestion (#3) → OpenCode `question` tool
+ * - SwitchMode (#4) → OpenCode `plan_enter` / `plan_exit` when advertised
+ * - CreatePlan (#7) → host-calculated plan file via hostPlansDir (project-config
+ *   `plans/` in a git worktree, else host global data/plans); empty args still
+ *   get the CLI empty-`plan_uri` success ack
+ * - GenerateImage (#12) → approve when `cursor_image_save` is advertised
+ */
+export declare function handleInteractionQuery(query: Record<string, unknown>, agentServerPayload: Uint8Array, options?: HandleInteractionQueryOptions): HandledInteraction;
+/** `AgentClientMessage{interaction_response{ask_question_interaction_response}}`. */
+export declare function buildAskQuestionInteractionReply(id: number, result: AskQuestionResultMessage): Uint8Array;
+/** `AgentClientMessage{interaction_response{switch_mode_request_response}}`. */
+export declare function buildSwitchModeInteractionReply(id: number, result: Record<string, unknown>): Uint8Array;
+/** `AgentClientMessage{interaction_response{create_plan_request_response}}`. */
+export declare function buildCreatePlanInteractionReply(id: number, result: Record<string, unknown>): Uint8Array;
+/**
+ * Deferred answers for a query already acknowledged with `async`.
+ * `originalArgs` must be the server's own `AskQuestionArgs` bytes so Cursor can
+ * correlate the completion with the tool call it raised.
  */
-export declare function handleInteractionQuery(query: Record<string, unknown>, agentServerPayload: Uint8Array): HandledInteraction;
+export declare function buildAsyncAskQuestionCompletion(originalToolCallId: string, originalArgs: Uint8Array, result: AskQuestionResultMessage): Uint8Array;

package/dist/protocol/interactions.js

@@ -1,6 +1,18 @@
 import { encodeMessage } from "./messages.js";
 import { readAllFields } from "./struct.js";
+import { decodeAskQuestionQuery, MISSING_ARGS_REASON, MISSING_QUERY_REASON, } from "./ask-question.js";
+import { decodeGenerateImageQuery, } from "./generate-image.js";
+import { CURSOR_PLAN_STAGE_TOOL, createPlanApprovalQuestionInput, decodeCreatePlanQuery, renderPlanReviewMessage, resolveCreatePlanBridge, writeOpencodePlanFile, } from "./create-plan.js";
+import { decodeSwitchModeQuery, MISSING_ARGS_REASON as SWITCH_MODE_MISSING_ARGS_REASON, MISSING_QUERY_REASON as SWITCH_MODE_MISSING_QUERY_REASON, resolveSwitchModeBridge, switchModeApprovedResult, } from "./switch-mode.js";
 const HEADLESS_REASON = "This Cursor interaction requires UI approval and is not available through the OpenCode provider.";
+/**
+ * Rejection used when AskQuestion cannot be bridged because the current
+ * OpenCode agent does not advertise `question` (subagents deny it by default,
+ * and compaction turns advertise no tools at all). Naming the actual reason
+ * keeps the model from concluding that asking is impossible in general.
+ */
+const ASK_QUESTION_UNAVAILABLE_REASON = "The OpenCode `question` tool is not available to the current agent, so questions "
+    + "cannot be shown to the user this turn. State the question in your reply instead.";
 const variantNames = {
     2: "web_search_request_query",
     3: "ask_question_interaction_query",
@@ -39,27 +51,37 @@ export function inspectInteractionQueryWire(agentServerPayload) {
     // zero, not a malformed/missing correlation id.
     let id = 0;
     let variantField;
+    let variantBytes;
     for (const field of readAllFields(queryBytes)) {
         if (field.fn === 1 && field.wt === 0)
             id = field.varint;
-        else if (field.wt === 2 && variantField === undefined)
+        else if (field.wt === 2 && variantField === undefined) {
             variantField = field.fn;
+            variantBytes = field.bytes;
+        }
     }
     return {
         id,
         variantField,
         variantName: variantField === undefined ? undefined : variantNames[variantField],
+        variantBytes,
     };
 }
 /**
- * Build the immediate typed response required by Cursor's Run RPC.
+ * Build the typed response required by Cursor's Run RPC.
  *
- * OpenCode has no Cursor UI callbacks, so every InteractionQuery is answered
- * here with a conservative headless policy (reject UI-bound prompts; ack a few
- * no-UI cases). See case 7 / F14 for create_plan auto-ack parity with Cursor
- * CLI headless mode.
+ * OpenCode has no Cursor UI callbacks, so UI-bound queries get a conservative
+ * headless policy (reject; ack a few no-UI cases).
+ *
+ * Bridged / persisted exceptions:
+ * - AskQuestion (#3) → OpenCode `question` tool
+ * - SwitchMode (#4) → OpenCode `plan_enter` / `plan_exit` when advertised
+ * - CreatePlan (#7) → host-calculated plan file via hostPlansDir (project-config
+ *   `plans/` in a git worktree, else host global data/plans); empty args still
+ *   get the CLI empty-`plan_uri` success ack
+ * - GenerateImage (#12) → approve when `cursor_image_save` is advertised
  */
-export function handleInteractionQuery(query, agentServerPayload) {
+export function handleInteractionQuery(query, agentServerPayload, options = {}) {
     const info = inspectInteractionQueryWire(agentServerPayload);
     if (info.id === undefined || info.variantField === undefined || !info.variantName) {
         throw new UnsupportedInteractionQueryError(info);
@@ -67,6 +89,18 @@ export function handleInteractionQuery(query, agentServerPayload) {
     if (typeof query.id === "number" && query.id !== info.id) {
         throw new Error(`Cursor interaction query id mismatch: decoded=${query.id} wire=${info.id}`);
     }
+    if (info.variantField === 3) {
+        return handleAskQuestionQuery(info.id, info.variantBytes, options);
+    }
+    if (info.variantField === 4) {
+        return handleSwitchModeQuery(info.id, info.variantBytes, options);
+    }
+    if (info.variantField === 7) {
+        return handleCreatePlanQuery(info.id, info.variantBytes, options);
+    }
+    if (info.variantField === 12) {
+        return handleGenerateImageQuery(info.id, info.variantBytes, options);
+    }
     let response;
     let outcome;
     switch (info.variantField) {
@@ -74,30 +108,6 @@ export function handleInteractionQuery(query, agentServerPayload) {
             response = { web_search_request_response: { rejected: { reason: HEADLESS_REASON } } };
             outcome = "rejected";
             break;
-        case 3:
-            response = {
-                ask_question_interaction_response: {
-                    result: { rejected: { reason: "Questions must be asked through OpenCode's question tool." } },
-                },
-            };
-            outcome = "rejected";
-            break;
-        case 4:
-            response = { switch_mode_request_response: { rejected: { reason: HEADLESS_REASON } } };
-            outcome = "rejected";
-            break;
-        case 7:
-            // F14: create_plan_request_query auto-ack (Cursor CLI headless parity).
-            // Cursor CLI's headless fallback acknowledges plan creation without a
-            // client-side URI (`success` + empty `plan_uri`); the plan remains in
-            // conversation state / checkpoints. This provider mirrors that reply so
-            // the Run RPC does not deadlock waiting for UI approval. Impact: Cursor
-            // may treat the plan as accepted without an OpenCode UI confirm; local
-            // tool execution is still gated by OpenCode permissions. Do not change
-            // this to reject/prompt without CLI parity evidence.
-            response = { create_plan_request_response: { result: { success: {}, plan_uri: "" } } };
-            outcome = "acknowledged";
-            break;
         case 8:
             // OpenCode owns the local environment; there is no Cursor VM to create.
             response = { setup_vm_environment_result: { success: {} } };
@@ -115,10 +125,6 @@ export function handleInteractionQuery(query, agentServerPayload) {
             response = { mcp_auth_request_response: { rejected: { reason: HEADLESS_REASON } } };
             outcome = "rejected";
             break;
-        case 12:
-            response = { generate_image_request_response: { rejected: { reason: HEADLESS_REASON } } };
-            outcome = "rejected";
-            break;
         case 13:
             response = {
                 replace_env_result: {
@@ -147,3 +153,257 @@ export function handleInteractionQuery(query, agentServerPayload) {
         }),
     };
 }
+/**
+ * AskQuestion is the one interaction OpenCode can genuinely satisfy, so it is
+ * translated instead of refused. Cursor CLI's own handler is mirrored: reject
+ * a malformed query, answer `async` immediately when the server asked for a
+ * non-blocking prompt, and otherwise hold the query open until the user picks.
+ */
+function handleAskQuestionQuery(id, variantBytes, options) {
+    const base = { id, variantField: 3, variantName: "ask_question_interaction_query" };
+    const reject = (reason) => ({
+        ...base,
+        outcome: "rejected",
+        reply: buildAskQuestionInteractionReply(id, { rejected: { reason } }),
+    });
+    if (!variantBytes)
+        return reject(MISSING_QUERY_REASON);
+    const decoded = decodeAskQuestionQuery(variantBytes);
+    if (!decoded)
+        return reject(MISSING_ARGS_REASON);
+    if (!options.canBridgeAskQuestion)
+        return reject(ASK_QUESTION_UNAVAILABLE_REASON);
+    return {
+        ...base,
+        outcome: "bridged",
+        askQuestion: decoded,
+        // Async queries are unblocked now and answered later through a
+        // ConversationAction; synchronous ones keep Cursor waiting, which is what
+        // its CLI does while the user is still choosing.
+        reply: decoded.args.runAsync
+            ? buildAskQuestionInteractionReply(id, { async: {} })
+            : undefined,
+    };
+}
+/** `AgentClientMessage{interaction_response{ask_question_interaction_response}}`. */
+export function buildAskQuestionInteractionReply(id, result) {
+    return encodeMessage("AgentClientMessage", {
+        interaction_response: {
+            id,
+            ask_question_interaction_response: { result },
+        },
+    });
+}
+/**
+ * SwitchMode is bridged to OpenCode `plan_enter` / `plan_exit` when advertised.
+ * Cursor CLI blocks until the user approves or rejects; we hold the query open
+ * until the host tool returns, then reply approved{} or rejected{reason}.
+ */
+function handleSwitchModeQuery(id, variantBytes, options) {
+    const base = { id, variantField: 4, variantName: "switch_mode_request_query" };
+    const reject = (reason) => ({
+        ...base,
+        outcome: "rejected",
+        reply: buildSwitchModeInteractionReply(id, { rejected: { reason } }),
+    });
+    if (!variantBytes)
+        return reject(SWITCH_MODE_MISSING_QUERY_REASON);
+    const decoded = decodeSwitchModeQuery(variantBytes);
+    if (!decoded)
+        return reject(SWITCH_MODE_MISSING_ARGS_REASON);
+    const bridge = resolveSwitchModeBridge(decoded.args.targetModeId, {
+        allowTools: options.allowTools === true,
+        advertised: options.advertisedTools ?? [],
+        ...(options.activeCursorModeId ? { activeModeId: options.activeCursorModeId } : {}),
+    });
+    if (bridge.kind === "reject")
+        return reject(bridge.reason);
+    // Lifecycle turn: approve on the wire so the model never sees a rejection, but
+    // do not attach switchMode — the real turn owns session mode.
+    if (bridge.kind === "ack") {
+        return {
+            ...base,
+            outcome: "acknowledged",
+            reply: buildSwitchModeInteractionReply(id, switchModeApprovedResult()),
+        };
+    }
+    if (bridge.kind === "approve") {
+        // Entering plan mode needs no host tool, so Cursor is released at once and
+        // the caller records the mode for the reminder injected on later Runs.
+        return {
+            ...base,
+            outcome: "approved",
+            switchMode: { ...decoded, bridge },
+            reply: buildSwitchModeInteractionReply(id, switchModeApprovedResult()),
+        };
+    }
+    return {
+        ...base,
+        outcome: "bridged",
+        switchMode: {
+            ...decoded,
+            bridge,
+            toolName: bridge.kind === "native" ? bridge.toolName : "question",
+        },
+        // Keep Cursor waiting until the host tool returns, matching CLI blocking on
+        // the mode-switch approval prompt.
+        reply: undefined,
+    };
+}
+/** `AgentClientMessage{interaction_response{switch_mode_request_response}}`. */
+export function buildSwitchModeInteractionReply(id, result) {
+    return encodeMessage("AgentClientMessage", {
+        interaction_response: {
+            id,
+            switch_mode_request_response: result,
+        },
+    });
+}
+/** `AgentClientMessage{interaction_response{create_plan_request_response}}`. */
+export function buildCreatePlanInteractionReply(id, result) {
+    return encodeMessage("AgentClientMessage", {
+        interaction_response: {
+            id,
+            create_plan_request_response: { result },
+        },
+    });
+}
+/**
+ * Deferred answers for a query already acknowledged with `async`.
+ * `originalArgs` must be the server's own `AskQuestionArgs` bytes so Cursor can
+ * correlate the completion with the tool call it raised.
+ */
+export function buildAsyncAskQuestionCompletion(originalToolCallId, originalArgs, result) {
+    return encodeMessage("AgentClientMessage", {
+        conversation_action: {
+            async_ask_question_completion_action: {
+                original_tool_call_id: originalToolCallId,
+                original_args: originalArgs,
+                result,
+            },
+        },
+    });
+}
+/**
+ * CreatePlan persistence and execution approval. Cursor CLI writes
+ * `~/.cursor/plans/*.plan.md` with YAML frontmatter; this provider writes plain
+ * markdown under the host's calculated plans dir (`hostPlansDir` / path bridge)
+ * so switching models and hosts stays coherent. Empty / missing args keep the
+ * CLI empty-`plan_uri` success ack (nothing to write).
+ *
+ * Writing the plan never asks; executing it always does. Which channel raises
+ * that prompt is resolved from the advertised catalog by
+ * {@link resolveCreatePlanBridge}, and every channel reports the same outcome:
+ * `success` means the user approved execution, `error` means the plan was
+ * written but not accepted, so the model keeps planning.
+ */
+function handleCreatePlanQuery(id, variantBytes, options) {
+    const base = { id, variantField: 7, variantName: "create_plan_request_query" };
+    const reply = (result) => ({
+        ...base,
+        outcome: result.error ? "failed" : "acknowledged",
+        reply: encodeMessage("AgentClientMessage", {
+            interaction_response: {
+                id,
+                create_plan_request_response: { result },
+            },
+        }),
+    });
+    // Missing / empty args: CLI headless fallback — success with empty plan_uri.
+    if (!variantBytes)
+        return reply({ success: {}, plan_uri: "" });
+    const decoded = decodeCreatePlanQuery(variantBytes);
+    if (!decoded)
+        return reply({ success: {}, plan_uri: "" });
+    const bridge = resolveCreatePlanBridge({
+        allowTools: options.allowTools === true,
+        canStage: options.canBridgeCreatePlan === true,
+        planModeActive: options.planModeActive === true,
+        advertised: options.advertisedTools ?? [],
+    });
+    // The host plan-stage tool owns the write and the approval prompt together.
+    if (bridge.kind === "stage") {
+        return {
+            ...base,
+            outcome: "bridged",
+            createPlan: { ...decoded, bridge, toolName: CURSOR_PLAN_STAGE_TOOL },
+            reply: undefined,
+        };
+    }
+    // A lifecycle turn (title generation, compaction) runs alongside the real one
+    // and would otherwise write a second, throwaway plan file for the same
+    // request. Ack it the CLI way instead of persisting anything.
+    if (options.allowTools !== true)
+        return reply({ success: {}, plan_uri: "" });
+    const workspaceRoot = options.workspaceRoot?.trim();
+    if (!workspaceRoot) {
+        return reply({
+            error: { error: "CreatePlan requires a workspace root to write the plan file" },
+            plan_uri: "",
+        });
+    }
+    const written = writeOpencodePlanFile(decoded.args, workspaceRoot);
+    if (!written.ok) {
+        return reply({ error: { error: written.error }, plan_uri: "" });
+    }
+    // The plan is on disk either way; only execution needs the user. Hold Cursor's
+    // query open while the host asks, exactly as the CLI blocks on its own prompt.
+    if (bridge.kind === "approve") {
+        return {
+            ...base,
+            outcome: "bridged",
+            createPlan: {
+                ...decoded,
+                bridge,
+                toolName: "question",
+                planUri: written.planUri,
+                planPath: written.planPath,
+                questionInput: createPlanApprovalQuestionInput(written.planPath),
+                planReview: renderPlanReviewMessage(written.markdown, written.planPath),
+            },
+            reply: undefined,
+        };
+    }
+    return reply({ success: {}, plan_uri: written.planUri });
+}
+/**
+ * GenerateImage approval. Cursor renders its own confirmation in the CLI; here
+ * the meaningful gate is OpenCode's `edit` permission raised by
+ * `cursor_image_save` when the finished bytes are written, so generation itself
+ * is approved whenever the provider can actually commit the result. Approving
+ * without a commit path would spend Cursor quota on an image that then has
+ * nowhere to go.
+ */
+function handleGenerateImageQuery(id, variantBytes, options) {
+    const base = { id, variantField: 12, variantName: "generate_image_request_query" };
+    const reject = (reason) => ({
+        ...base,
+        outcome: "rejected",
+        reply: encodeMessage("AgentClientMessage", {
+            interaction_response: { id, generate_image_request_response: { rejected: { reason } } },
+        }),
+    });
+    if (!variantBytes)
+        return reject("Missing generate image query");
+    const decoded = decodeGenerateImageQuery(variantBytes);
+    if (!decoded)
+        return reject("Missing generate image arguments");
+    if (!options.canSaveGeneratedImage) {
+        return reject("This OpenCode agent cannot save a generated image, so generating one would "
+            + "produce nothing. Describe the image in your reply instead.");
+    }
+    return {
+        ...base,
+        outcome: "acknowledged",
+        generateImage: decoded,
+        reply: encodeMessage("AgentClientMessage", {
+            interaction_response: {
+                id,
+                // Cursor's CLI returns the description the user may have edited at the
+                // prompt. There is no text field on OpenCode's permission, so the
+                // model's own description is passed through unchanged.
+                generate_image_request_response: { approved: { description: decoded.description } },
+            },
+        }),
+    };
+}

package/dist/protocol/kv.d.ts

@@ -16,6 +16,7 @@ import type { CursorSession } from "../session.js";
  */
 export declare function handleKvServerMessage(ksm: Record<string, unknown>, session: CursorSession): {
     reply: Uint8Array;
+    replyBlobBytes: number;
     kind: "set" | "get";
     id: number;
     blobIdHex: string;

package/dist/protocol/kv.js

@@ -38,6 +38,7 @@ export function handleKvServerMessage(ksm, session) {
             id,
             blobIdHex: key,
             found: true,
+            replyBlobBytes: 0,
             reply: encodeMessage("AgentClientMessage", {
                 kv_client_message: { id, set_blob_result: {} },
             }),
@@ -72,6 +73,7 @@ export function handleKvServerMessage(ksm, session) {
             blobIdHex: key,
             found,
             echoed,
+            replyBlobBytes: blobData.length,
             reply: encodeMessage("AgentClientMessage", {
                 kv_client_message: { id, get_blob_result: { blob_data: blobData } },
             }),

package/dist/protocol/messages.d.ts

@@ -3,6 +3,8 @@ export declare function createMessageTypes(): protobuf.Root;
 export declare function getMessageTypes(): protobuf.Root;
 export declare function encodeMessage(typeName: string, message: Record<string, unknown>): Uint8Array;
 export declare function decodeMessage<T = Record<string, unknown>>(typeName: string, data: Uint8Array): T;
+/** Decode without inventing absent proto defaults (used for byte-stable snapshots). */
+export declare function decodeMessageSparse<T = Record<string, unknown>>(typeName: string, data: Uint8Array): T;
 /**
  * Diagnostic-only: walk AgentServerMessage.interaction_update(1).turn_ended(14)
  * without going through our hand-written TurnEnded schema, so a `cache_write`/