cursor-opencode-provider 0.5.0 → 0.6.0

package/dist/protocol/create-plan.js

@@ -0,0 +1,373 @@
+/**
+ * Cursor-native CreatePlan → host-default plan file.
+ *
+ * Cursor raises `create_plan_request_query` (#7) with CreatePlanArgs and expects
+ * a CreatePlanResult carrying `plan_uri`. Cursor CLI writes under
+ * `~/.cursor/plans/*.plan.md` with YAML frontmatter; this provider deliberately
+ * does **not** — plans must stay host-portable so switching models does not
+ * strand users on Cursor-specific paths or frontmatter.
+ *
+ * Location mirrors OpenCode Session.plan shape, but the project-config segment
+ * comes from {@link hostPlansDir} / {@link opencodeProjectConfigDirs}
+ * (the active host's project config dir via the path bridge), never a
+ * hardcoded OpenCode-only directory name.
+ *
+ * Body is plain markdown (the same shape a plan-mode model would write with
+ * `write`). Cursor YAML frontmatter is never emitted.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { hostPlansDir } from "../context/paths.js";
+import { parseAnswerSegments, } from "./ask-question.js";
+import { decodeMessageSparse } from "./messages.js";
+const PLAN_ADJECTIVES = [
+    "brave",
+    "calm",
+    "clever",
+    "cosmic",
+    "crisp",
+    "curious",
+    "eager",
+    "gentle",
+    "glowing",
+    "happy",
+    "hidden",
+    "jolly",
+    "kind",
+    "lucky",
+    "mighty",
+    "misty",
+    "neon",
+    "nimble",
+    "playful",
+    "proud",
+    "quick",
+    "quiet",
+    "shiny",
+    "silent",
+    "stellar",
+    "sunny",
+    "swift",
+    "tidy",
+    "witty",
+];
+const PLAN_NOUNS = [
+    "cabin",
+    "cactus",
+    "canyon",
+    "circuit",
+    "comet",
+    "eagle",
+    "engine",
+    "falcon",
+    "forest",
+    "garden",
+    "harbor",
+    "island",
+    "knight",
+    "lagoon",
+    "meadow",
+    "moon",
+    "mountain",
+    "nebula",
+    "orchid",
+    "otter",
+    "panda",
+    "pixel",
+    "planet",
+    "river",
+    "rocket",
+    "sailor",
+    "squid",
+    "star",
+    "tiger",
+    "wizard",
+    "wolf",
+];
+/** Optional host plan-stage tool advertised by a compatible host. */
+export const CURSOR_PLAN_STAGE_TOOL = "cursor_plan_stage";
+/** Held InteractionQuery continuation field for a native host plan stage. */
+export const CREATE_PLAN_RESULT_FIELD = "create_plan_request_response";
+/** Upstream `PlanExitTool` wording, with the plan the provider just wrote. */
+export function createPlanApprovalQuestion(planLabel) {
+    const where = planLabel.trim();
+    return where
+        ? `Plan at ${where} is complete. Would you like to switch to the build agent and start implementing?`
+        : "The plan is complete. Would you like to switch to the build agent and start implementing?";
+}
+export const CREATE_PLAN_APPROVAL_HEADER = "Build Agent";
+const CREATE_PLAN_APPROVAL_YES = "Yes";
+const CREATE_PLAN_APPROVAL_NO = "No";
+/** Cursor-visible reason when the user wants the plan revised instead of run. */
+export const CREATE_PLAN_NOT_APPROVED_REASON = "The user did not approve executing this plan. Keep planning: refine the plan and "
+    + "propose it again when it is ready.";
+/**
+ * Resolve how this CreatePlan is satisfied. `planModeActive` is the provider's
+ * own record of an approved Cursor plan/spec mode: the approval prompt guards
+ * the transition *out of* planning, so a CreatePlan raised outside plan mode is
+ * written and acknowledged without one.
+ */
+export function resolveCreatePlanBridge(options) {
+    // A lifecycle turn (title generation, compaction) runs alongside the real one
+    // and must not write a second plan file or raise a second prompt.
+    if (!options.allowTools)
+        return { kind: "ack" };
+    if (options.canStage)
+        return { kind: "stage" };
+    const names = options.advertised instanceof Set ? options.advertised : new Set(options.advertised);
+    if (options.planModeActive && names.has("question"))
+        return { kind: "approve" };
+    return { kind: "ack" };
+}
+/** The synthetic AskQuestion item backing the emulated approval prompt. */
+function createPlanApprovalItem(question) {
+    return {
+        id: "create_plan_approval",
+        prompt: question,
+        options: [
+            { id: "yes", label: CREATE_PLAN_APPROVAL_YES },
+            { id: "no", label: CREATE_PLAN_APPROVAL_NO },
+        ],
+        allowMultiple: false,
+    };
+}
+/** Host `question` input mirroring upstream `PlanExitTool`'s own prompt. */
+export function createPlanApprovalQuestionInput(planLabel) {
+    return {
+        questions: [
+            {
+                question: createPlanApprovalQuestion(planLabel),
+                header: CREATE_PLAN_APPROVAL_HEADER,
+                options: [
+                    {
+                        label: CREATE_PLAN_APPROVAL_YES,
+                        description: "Switch to build agent and start implementing the plan",
+                    },
+                    {
+                        label: CREATE_PLAN_APPROVAL_NO,
+                        description: "Stay with plan agent to continue refining the plan",
+                    },
+                ],
+            },
+        ],
+    };
+}
+/**
+ * True when the emulated approval prompt came back as an explicit "Yes".
+ * An unanswered, dismissed, or failed prompt keeps the model planning rather
+ * than silently starting execution.
+ *
+ * `question` must be the exact prompt that was asked — the host echoes it back
+ * verbatim, and it is the anchor the answer is parsed from.
+ */
+export function createPlanApproved(output, isError, question) {
+    if (isError)
+        return false;
+    const [segment] = parseAnswerSegments([createPlanApprovalItem(question)], output);
+    return (segment ?? "").trim().toLowerCase() === CREATE_PLAN_APPROVAL_YES.toLowerCase();
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+function mapTodoStatus(status) {
+    if (typeof status === "string")
+        return status.toLowerCase();
+    if (typeof status === "number") {
+        // TodoStatus enum: PENDING=1, IN_PROGRESS=2, COMPLETED=3, CANCELLED=4
+        switch (status) {
+            case 2:
+                return "in_progress";
+            case 3:
+                return "completed";
+            case 4:
+                return "cancelled";
+            default:
+                return "pending";
+        }
+    }
+    return "pending";
+}
+function todoCheckbox(status) {
+    const s = status.toLowerCase();
+    if (s === "completed" || s === "complete" || s === "done")
+        return "[x]";
+    if (s === "cancelled" || s === "canceled")
+        return "[~]";
+    return "[ ]";
+}
+/** Decode a `create_plan_request_query` body, or undefined when unusable. */
+export function decodeCreatePlanQuery(queryBytes) {
+    let decoded;
+    try {
+        decoded = decodeMessageSparse("CreatePlanRequestQuery", queryBytes);
+    }
+    catch {
+        return undefined;
+    }
+    const args = asRecord(decoded.args);
+    if (!args)
+        return undefined;
+    const plan = str(args.plan);
+    const overview = str(args.overview);
+    const name = str(args.name);
+    const todos = Array.isArray(args.todos)
+        ? args.todos.flatMap((raw) => {
+            const item = asRecord(raw);
+            if (!item)
+                return [];
+            const content = str(item.content);
+            if (!content)
+                return [];
+            return [
+                {
+                    id: str(item.id),
+                    content,
+                    status: mapTodoStatus(item.status),
+                },
+            ];
+        })
+        : [];
+    // Empty args: CLI acknowledges with empty plan_uri; treat as no write.
+    if (!plan && !overview && !name && todos.length === 0)
+        return undefined;
+    return {
+        args: {
+            plan,
+            overview,
+            name,
+            isProject: args.is_project === true,
+            todos,
+        },
+        toolCallId: str(decoded.tool_call_id),
+    };
+}
+/** OpenCode-style adjective-noun slug (core/src/util/slug.ts). */
+export function randomPlanSlug(seed = Date.now()) {
+    const adj = PLAN_ADJECTIVES[seed % PLAN_ADJECTIVES.length];
+    const noun = PLAN_NOUNS[Math.floor(seed / PLAN_ADJECTIVES.length) % PLAN_NOUNS.length];
+    return `${adj}-${noun}`;
+}
+/** Slugify a human title into a filesystem-safe token. */
+export function slugifyPlanName(name) {
+    const slug = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return slug || randomPlanSlug();
+}
+/** Build the advertised host plan-stage artifact payload. */
+export function createPlanStageInput(args) {
+    const slug = slugifyPlanName(args.name);
+    return {
+        plan_uri: `local://${slug}-plan.md`,
+        content: renderOpencodePlanMarkdown(args),
+        title: slug,
+    };
+}
+/**
+ * Resolve the absolute plan file path via {@link hostPlansDir}.
+ * Filename shape matches OpenCode Session.plan: `<created>-<slug>.md`.
+ */
+export function resolveHostPlanPath(workspaceRoot, name, created = Date.now()) {
+    const slug = name?.trim() ? slugifyPlanName(name) : randomPlanSlug(created);
+    return path.join(hostPlansDir(workspaceRoot), `${created}-${slug}.md`);
+}
+/** @deprecated Prefer {@link resolveHostPlanPath}. */
+export const resolveOpencodePlanPath = resolveHostPlanPath;
+/**
+ * Render plain markdown for the plan file. No Cursor YAML frontmatter.
+ * Prefer `args.plan` as the body; prepend a title/overview when useful; append
+ * a markdown checklist for todos.
+ */
+export function renderOpencodePlanMarkdown(args) {
+    const parts = [];
+    const name = args.name.trim();
+    const overview = args.overview.trim();
+    const plan = args.plan.trim();
+    // Cursor usually repeats the plan name as the body's own leading H1. Strip it
+    // so the document keeps one title in the right place instead of opening with
+    // the same heading twice (or with the overview stranded above it).
+    const planLeadHeading = /^#\s+(.+?)\s*$/.exec(plan.split("\n", 1)[0] ?? "")?.[1];
+    const planBody = name
+        && planLeadHeading !== undefined
+        && planLeadHeading.trim().toLowerCase() === name.toLowerCase()
+        ? plan.slice(plan.indexOf("\n") + 1).trimStart()
+        : plan;
+    if (name) {
+        parts.push(`# ${name}`);
+        parts.push("");
+    }
+    if (overview) {
+        // Avoid duplicating overview when it already leads the plan body.
+        if (!planBody || !planBody.startsWith(overview)) {
+            parts.push(overview);
+            parts.push("");
+        }
+    }
+    if (planBody) {
+        parts.push(planBody);
+        if (!planBody.endsWith("\n"))
+            parts.push("");
+    }
+    if (args.todos.length > 0) {
+        if (parts.length > 0 && parts[parts.length - 1] !== "")
+            parts.push("");
+        parts.push("## Todos");
+        parts.push("");
+        for (const todo of args.todos) {
+            parts.push(`- ${todoCheckbox(todo.status)} ${todo.content}`);
+        }
+        parts.push("");
+    }
+    const body = parts.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+    return body ? `${body}\n` : "";
+}
+/**
+ * Write the plan under {@link hostPlansDir} and return a `file://` URI.
+ * Empty / missing content is the caller's responsibility (empty plan_uri ack).
+ */
+export function writeOpencodePlanFile(args, workspaceRoot, created = Date.now()) {
+    const markdown = renderOpencodePlanMarkdown(args);
+    if (!markdown.trim()) {
+        return { ok: false, error: "CreatePlan produced no plan content to write" };
+    }
+    const planPath = resolveHostPlanPath(workspaceRoot, args.name, created);
+    try {
+        mkdirSync(path.dirname(planPath), { recursive: true });
+        writeFileSync(planPath, markdown, "utf-8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `Failed to write plan file: ${message}` };
+    }
+    return {
+        ok: true,
+        planPath,
+        planUri: pathToFileURL(planPath).href,
+        markdown,
+    };
+}
+/**
+ * The plan as the user reads it before approving execution.
+ *
+ * Cursor routes the plan body through the interaction query rather than the
+ * text stream, so without this the user is asked to approve a plan they were
+ * never shown. It goes into the assistant message — the host renders markdown
+ * there, it scrolls, and it survives answering the prompt. It must not go into
+ * the question itself: OpenCode renders the question dock outside its
+ * scrollbox with `flexShrink={0}`, so a full plan there would push the
+ * conversation off screen.
+ */
+export function renderPlanReviewMessage(markdown, planPath) {
+    const body = markdown.trim();
+    const saved = `_Plan saved to ${planPath}_`;
+    return body ? `${body}\n\n${saved}\n` : `${saved}\n`;
+}

package/dist/protocol/generate-image.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cursor-native GenerateImage.
+ *
+ * Cursor generates the image on its own servers, then writes it to the client
+ * exactly like any other file — Cursor CLI's agent issues
+ * `WriteArgs{path, file_bytes, return_file_content_after_write: false}` to
+ * `<artifactsFolder|projectFolder>/assets/<basename(file_path)>` and reads the
+ * client's `WriteResult` back, checking for `permission_denied`
+ * (`agent-cli-local/src/index.ts:84752-84776`).
+ *
+ * The display `generate_image_tool_call.result.image_data` is **not** the write
+ * channel: the CLI feeds it to its terminal preview cache and falls back to
+ * reading the path off disk, so the file already exists by then. Never write
+ * from that frame — the bytes would be written twice.
+ *
+ * So the client-side work is: approve the interaction, then honour a binary
+ * write. OpenCode's `write` tool cannot carry bytes (string content, BOM split,
+ * diff, `Format.file()`), so the bytes are staged (`../image-staging.ts`) and
+ * committed by the `cursor_image_save` plugin tool, which raises OpenCode's
+ * `edit` permission. A refusal returns Cursor's own `permission_denied`.
+ */
+/** Host tool id that commits a staged image. Registered by the classic plugin. */
+export declare const CURSOR_IMAGE_SAVE_TOOL = "cursor_image_save";
+/** Cursor's agent always writes generated images into this subdirectory. */
+export declare const CURSOR_IMAGE_ASSETS_DIR = "assets";
+export type DecodedGenerateImageQuery = {
+    description: string;
+    /** Target path as Cursor asked for it; may be relative or empty. */
+    filePath: string;
+    referenceImagePaths: string[];
+    toolCallId: string;
+};
+/** Cursor names the target file; its extension is the only mime signal sent. */
+export declare function imageMimeForPath(filePath: string): string;
+/** Decode a `generate_image_request_query` body, or undefined when unusable. */
+export declare function decodeGenerateImageQuery(queryBytes: Uint8Array): DecodedGenerateImageQuery | undefined;
+export type ImageWriteRoots = {
+    /** Session workspace root (`request_context.env.workspace_paths[0]`). */
+    workspaceRoot: string;
+    /** What this provider advertises as `project_folder` / `workspace_project_dir`. */
+    projectDir: string;
+};
+/**
+ * Map Cursor's intended write target onto a real location under this host.
+ *
+ * Cursor composes the path from the `project_folder` this provider advertised,
+ * so an untouched target already resolves under the host cache project
+ * directory and is kept as-is. A target inside the workspace is also honoured
+ * verbatim — that is a location the user can see. Anything else (a path built
+ * from a folder we never advertised, or an attempted escape) is rebased onto
+ * `<projectDir>/assets/<basename>` rather than refused, so the model still gets
+ * a file where it expects one instead of a failed generation.
+ */
+export declare function remapCursorImageWritePath(target: string, roots: ImageWriteRoots): string;

package/dist/protocol/generate-image.js

@@ -0,0 +1,101 @@
+/**
+ * Cursor-native GenerateImage.
+ *
+ * Cursor generates the image on its own servers, then writes it to the client
+ * exactly like any other file — Cursor CLI's agent issues
+ * `WriteArgs{path, file_bytes, return_file_content_after_write: false}` to
+ * `<artifactsFolder|projectFolder>/assets/<basename(file_path)>` and reads the
+ * client's `WriteResult` back, checking for `permission_denied`
+ * (`agent-cli-local/src/index.ts:84752-84776`).
+ *
+ * The display `generate_image_tool_call.result.image_data` is **not** the write
+ * channel: the CLI feeds it to its terminal preview cache and falls back to
+ * reading the path off disk, so the file already exists by then. Never write
+ * from that frame — the bytes would be written twice.
+ *
+ * So the client-side work is: approve the interaction, then honour a binary
+ * write. OpenCode's `write` tool cannot carry bytes (string content, BOM split,
+ * diff, `Format.file()`), so the bytes are staged (`../image-staging.ts`) and
+ * committed by the `cursor_image_save` plugin tool, which raises OpenCode's
+ * `edit` permission. A refusal returns Cursor's own `permission_denied`.
+ */
+import path from "node:path";
+import { decodeMessageSparse } from "./messages.js";
+/** Host tool id that commits a staged image. Registered by the classic plugin. */
+export const CURSOR_IMAGE_SAVE_TOOL = "cursor_image_save";
+/** Cursor's agent always writes generated images into this subdirectory. */
+export const CURSOR_IMAGE_ASSETS_DIR = "assets";
+const IMAGE_MIME_BY_EXTENSION = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+/** Cursor names the target file; its extension is the only mime signal sent. */
+export function imageMimeForPath(filePath) {
+    const dot = path.basename(filePath).lastIndexOf(".");
+    if (dot <= 0)
+        return "image/png";
+    return IMAGE_MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] ?? "image/png";
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Decode a `generate_image_request_query` body, or undefined when unusable. */
+export function decodeGenerateImageQuery(queryBytes) {
+    let decoded;
+    try {
+        decoded = decodeMessageSparse("GenerateImageRequestQuery", queryBytes);
+    }
+    catch {
+        return undefined;
+    }
+    const args = asRecord(decoded.args);
+    if (!args)
+        return undefined;
+    const description = str(args.description);
+    if (!description)
+        return undefined;
+    return {
+        description,
+        filePath: str(args.file_path),
+        referenceImagePaths: Array.isArray(args.reference_image_paths)
+            ? args.reference_image_paths.filter((item) => typeof item === "string")
+            : [],
+        toolCallId: str(decoded.tool_call_id),
+    };
+}
+function isInside(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return relative !== "" && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/**
+ * Map Cursor's intended write target onto a real location under this host.
+ *
+ * Cursor composes the path from the `project_folder` this provider advertised,
+ * so an untouched target already resolves under the host cache project
+ * directory and is kept as-is. A target inside the workspace is also honoured
+ * verbatim — that is a location the user can see. Anything else (a path built
+ * from a folder we never advertised, or an attempted escape) is rebased onto
+ * `<projectDir>/assets/<basename>` rather than refused, so the model still gets
+ * a file where it expects one instead of a failed generation.
+ */
+export function remapCursorImageWritePath(target, roots) {
+    const projectDir = path.resolve(roots.projectDir);
+    const assets = path.join(projectDir, CURSOR_IMAGE_ASSETS_DIR);
+    const fallback = path.join(assets, path.basename(target) || "generated-image.png");
+    if (!target)
+        return fallback;
+    const absolute = path.isAbsolute(target) ? target : path.resolve(projectDir, target);
+    if (isInside(projectDir, absolute))
+        return path.resolve(absolute);
+    if (roots.workspaceRoot && isInside(roots.workspaceRoot, absolute))
+        return path.resolve(absolute);
+    return fallback;
+}

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;