cursor-opencode-provider 0.5.0 → 0.6.1

package/dist/protocol/ask-question.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Cursor-native AskQuestion ⇄ OpenCode `question` translation.
+ *
+ * Cursor's AskQuestion is not a tool the client executes — the server raises an
+ * `InteractionQuery` (`ask_question_interaction_query`, field 3) and blocks the
+ * Run until the client answers with an `AskQuestionResult`. OpenCode has an
+ * equivalent host tool (`question`), so the provider translates rather than
+ * refusing: refusing made models narrate "the AskQuestion tool is unavailable"
+ * and fall back to prose instead of ever calling the advertised host tool.
+ *
+ * Every rule below mirrors Cursor CLI, decompiled at
+ * `~/Projects/cursor-mock-server/cursor/cli{,-local}`:
+ *
+ * - `src/utils/interaction-utils.ts` — `BU` (freeform option id), `Q7` (display
+ *   options), `iX` (selection → success), `N$` (rejection + default reason).
+ * - `chunk-7076/dist/ui.js` (`askQuestionInteractionQuery` case) and
+ *   `subagent/subagent-prompt-handler.js` (`requestAskQuestion`) — the
+ *   sync/async split and the exact rejection reasons.
+ *
+ * Keep the reason strings byte-identical to the CLI's: they reach the model as
+ * tool feedback, and Cursor's server-side prompting is tuned against them.
+ */
+/** Cursor's synthetic "type your own answer" option id (interaction-utils `BU`). */
+export declare const FREEFORM_OPTION_ID = "__freeform_other__";
+/**
+ * `PendingExec.resultField` marking a held-open AskQuestion. It is not an
+ * `ExecClientMessage` field: continuation dispatches on it to write an
+ * InteractionResponse or a ConversationAction instead of an exec result.
+ */
+export declare const ASK_QUESTION_RESULT_FIELD = "ask_question_interaction_response";
+/** Default rejection reason when the user skips (interaction-utils `N$`). */
+export declare const SKIPPED_REASON = "Questions skipped by user";
+/** Rejection used when the host dismisses the prompt (CLI `resolveAskQuestionPrompt`). */
+export declare const DISMISSED_REASON = "Ask-question prompt dismissed";
+export declare const MISSING_QUERY_REASON = "Missing ask-question query";
+export declare const MISSING_ARGS_REASON = "Missing ask-question arguments";
+export type CursorAskQuestionOption = {
+    id: string;
+    label: string;
+};
+export type CursorAskQuestionItem = {
+    id: string;
+    prompt: string;
+    options: CursorAskQuestionOption[];
+    allowMultiple: boolean;
+};
+export type CursorAskQuestionArgs = {
+    title: string;
+    questions: CursorAskQuestionItem[];
+    runAsync: boolean;
+};
+export type DecodedAskQuestionQuery = {
+    args: CursorAskQuestionArgs;
+    /**
+     * The exact `AskQuestionArgs` sub-message bytes. Async completion echoes
+     * `original_args` verbatim so fields this schema does not model survive.
+     */
+    rawArgs: Uint8Array;
+    toolCallId: string;
+};
+/** `AskQuestionResult` oneof, shaped for `encodeMessage`. */
+export type AskQuestionResultMessage = Record<string, unknown>;
+/**
+ * Decode an `ask_question_interaction_query` body. Returns undefined when the
+ * body carries no usable question set — the caller then rejects with the CLI's
+ * own "missing" reason rather than bridging an empty prompt to the host.
+ */
+export declare function decodeAskQuestionQuery(queryBytes: Uint8Array): DecodedAskQuestionQuery | undefined;
+/**
+ * Cursor CLI drops a trailing catch-all option before rendering, because it
+ * always appends its own freeform "Other" row (interaction-utils `Q7`).
+ * OpenCode's `question` tool does the same thing via `custom` (default true,
+ * and not settable from the tool schema), so the strip is required here too or
+ * the user sees two "Other" entries for one question.
+ */
+export declare function isCatchAllOptionLabel(label: string): boolean;
+/** Options as Cursor would display them: trailing catch-all removed. */
+export declare function displayOptions(question: CursorAskQuestionItem): CursorAskQuestionOption[];
+export type OpencodeQuestionInput = {
+    questions: Array<{
+        question: string;
+        header: string;
+        options: Array<{
+            label: string;
+            description: string;
+        }>;
+        multiple?: boolean;
+    }>;
+};
+/**
+ * Build the OpenCode `question` tool input. `Question.Prompt` requires
+ * `question`, `header`, and `options[{label, description}]`; Cursor options
+ * carry no description, so it stays empty rather than being invented.
+ */
+export declare function askQuestionToolInput(args: CursorAskQuestionArgs): OpencodeQuestionInput;
+/** `AskQuestionResult{rejected}` — interaction-utils `N$`. */
+export declare function rejectedResult(reason?: string): AskQuestionResultMessage;
+/** `AskQuestionResult{async}` — the immediate reply for `run_async` queries. */
+export declare function asyncResult(): AskQuestionResultMessage;
+/**
+ * Pull each question's answer text out of OpenCode's `question` tool output.
+ *
+ * The tool returns prose, not structured data (`metadata.answers` does not
+ * cross the AI SDK boundary):
+ *
+ *   User has answered your questions: "<q1>"="<a, b>", "<q2>"="Unanswered". You
+ *   can now continue with the user's answers in mind.
+ *
+ * The provider authored the question strings, so each answer is located by its
+ * own `"<question>"="` anchor scanning forward — robust against commas, quotes
+ * and `"="` inside question or answer text, and against duplicate questions.
+ * Returns undefined for a question whose anchor is absent, which is treated as
+ * unanswered rather than guessed at.
+ */
+export declare function parseAnswerSegments(questions: readonly CursorAskQuestionItem[], output: string): Array<string | undefined>;
+/**
+ * Map one question's answer labels back onto Cursor option ids.
+ *
+ * OpenCode returns labels, so a label that matches an option we sent becomes a
+ * `selected_option_id`; anything else is the user's custom answer and becomes
+ * `freeform_text`. Cursor CLI's `iX` substitutes the literal "Other" when the
+ * freeform row was chosen without text, so an empty custom answer does too.
+ */
+export declare function answerForQuestion(question: CursorAskQuestionItem, segment: string | undefined): Record<string, unknown>;
+/**
+ * Translate an OpenCode `question` tool result into an `AskQuestionResult`.
+ *
+ * A tool error means the host dismissed or failed the prompt — OpenCode's
+ * `Question.RejectedError` is the dismissal path — so it maps to the CLI's
+ * rejection rather than an empty success, which the model would read as "the
+ * user answered nothing".
+ */
+export declare function askQuestionResultFromToolOutput(args: CursorAskQuestionArgs, output: string, isError: boolean): AskQuestionResultMessage;

package/dist/protocol/ask-question.js

@@ -0,0 +1,320 @@
+/**
+ * Cursor-native AskQuestion ⇄ OpenCode `question` translation.
+ *
+ * Cursor's AskQuestion is not a tool the client executes — the server raises an
+ * `InteractionQuery` (`ask_question_interaction_query`, field 3) and blocks the
+ * Run until the client answers with an `AskQuestionResult`. OpenCode has an
+ * equivalent host tool (`question`), so the provider translates rather than
+ * refusing: refusing made models narrate "the AskQuestion tool is unavailable"
+ * and fall back to prose instead of ever calling the advertised host tool.
+ *
+ * Every rule below mirrors Cursor CLI, decompiled at
+ * `~/Projects/cursor-mock-server/cursor/cli{,-local}`:
+ *
+ * - `src/utils/interaction-utils.ts` — `BU` (freeform option id), `Q7` (display
+ *   options), `iX` (selection → success), `N$` (rejection + default reason).
+ * - `chunk-7076/dist/ui.js` (`askQuestionInteractionQuery` case) and
+ *   `subagent/subagent-prompt-handler.js` (`requestAskQuestion`) — the
+ *   sync/async split and the exact rejection reasons.
+ *
+ * Keep the reason strings byte-identical to the CLI's: they reach the model as
+ * tool feedback, and Cursor's server-side prompting is tuned against them.
+ */
+import { decodeMessageSparse } from "./messages.js";
+/** Cursor's synthetic "type your own answer" option id (interaction-utils `BU`). */
+export const FREEFORM_OPTION_ID = "__freeform_other__";
+/**
+ * `PendingExec.resultField` marking a held-open AskQuestion. It is not an
+ * `ExecClientMessage` field: continuation dispatches on it to write an
+ * InteractionResponse or a ConversationAction instead of an exec result.
+ */
+export const ASK_QUESTION_RESULT_FIELD = "ask_question_interaction_response";
+/** Default rejection reason when the user skips (interaction-utils `N$`). */
+export const SKIPPED_REASON = "Questions skipped by user";
+/** Rejection used when the host dismisses the prompt (CLI `resolveAskQuestionPrompt`). */
+export const DISMISSED_REASON = "Ask-question prompt dismissed";
+export const MISSING_QUERY_REASON = "Missing ask-question query";
+export const MISSING_ARGS_REASON = "Missing ask-question arguments";
+/** OpenCode's `question` tool caps its short header label at 30 chars. */
+const HEADER_MAX_LENGTH = 30;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+/**
+ * Extract the raw bytes of `AskQuestionInteractionQuery.args` (#1) without
+ * decoding. protobufjs hands back a decoded copy that would silently drop
+ * unknown fields on re-encode; the async completion action must echo the
+ * server's own bytes.
+ */
+function extractArgsBytes(queryBytes) {
+    let offset = 0;
+    while (offset < queryBytes.length) {
+        let key = 0;
+        let shift = 0;
+        while (offset < queryBytes.length) {
+            const byte = queryBytes[offset++];
+            key |= (byte & 0x7f) << shift;
+            if ((byte & 0x80) === 0)
+                break;
+            shift += 7;
+            if (shift > 28)
+                return undefined;
+        }
+        const fieldNumber = key >>> 3;
+        const wireType = key & 7;
+        if (wireType === 2) {
+            let length = 0;
+            let lengthShift = 0;
+            while (offset < queryBytes.length) {
+                const byte = queryBytes[offset++];
+                length |= (byte & 0x7f) << lengthShift;
+                if ((byte & 0x80) === 0)
+                    break;
+                lengthShift += 7;
+                if (lengthShift > 28)
+                    return undefined;
+            }
+            if (offset + length > queryBytes.length)
+                return undefined;
+            if (fieldNumber === 1)
+                return queryBytes.subarray(offset, offset + length);
+            offset += length;
+        }
+        else if (wireType === 0) {
+            while (offset < queryBytes.length && (queryBytes[offset++] & 0x80) !== 0) {
+                // skip varint continuation bytes
+            }
+        }
+        else if (wireType === 5) {
+            offset += 4;
+        }
+        else if (wireType === 1) {
+            offset += 8;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Decode an `ask_question_interaction_query` body. Returns undefined when the
+ * body carries no usable question set — the caller then rejects with the CLI's
+ * own "missing" reason rather than bridging an empty prompt to the host.
+ */
+export function decodeAskQuestionQuery(queryBytes) {
+    let decoded;
+    try {
+        decoded = decodeMessageSparse("AskQuestionInteractionQuery", queryBytes);
+    }
+    catch {
+        return undefined;
+    }
+    const rawArgs = extractArgsBytes(queryBytes);
+    const argsRecord = asRecord(decoded.args);
+    if (!argsRecord || !rawArgs)
+        return undefined;
+    const questions = Array.isArray(argsRecord.questions)
+        ? argsRecord.questions.flatMap((raw) => {
+            const item = asRecord(raw);
+            if (!item)
+                return [];
+            const prompt = str(item.prompt);
+            if (!prompt)
+                return [];
+            const options = Array.isArray(item.options)
+                ? item.options.flatMap((rawOption) => {
+                    const option = asRecord(rawOption);
+                    if (!option)
+                        return [];
+                    const label = str(option.label);
+                    if (!label)
+                        return [];
+                    return [{ id: str(option.id), label }];
+                })
+                : [];
+            return [{
+                    id: str(item.id),
+                    prompt,
+                    options,
+                    allowMultiple: item.allow_multiple === true,
+                }];
+        })
+        : [];
+    if (questions.length === 0)
+        return undefined;
+    return {
+        args: {
+            title: str(argsRecord.title),
+            questions,
+            runAsync: argsRecord.run_async === true,
+        },
+        rawArgs,
+        toolCallId: str(decoded.tool_call_id),
+    };
+}
+/**
+ * Cursor CLI drops a trailing catch-all option before rendering, because it
+ * always appends its own freeform "Other" row (interaction-utils `Q7`).
+ * OpenCode's `question` tool does the same thing via `custom` (default true,
+ * and not settable from the tool schema), so the strip is required here too or
+ * the user sees two "Other" entries for one question.
+ */
+export function isCatchAllOptionLabel(label) {
+    const normalized = label.toLowerCase().trim();
+    return (normalized === "other"
+        || normalized === "something else"
+        || normalized.startsWith("other:")
+        || normalized.startsWith("other -")
+        || normalized.startsWith("other (")
+        || normalized.startsWith("something else:")
+        || normalized.startsWith("something else -")
+        || normalized.startsWith("something else ("));
+}
+/** Options as Cursor would display them: trailing catch-all removed. */
+export function displayOptions(question) {
+    const last = question.options.at(-1);
+    if (last && isCatchAllOptionLabel(last.label))
+        return question.options.slice(0, -1);
+    return question.options.slice();
+}
+function header(title) {
+    const trimmed = title.trim();
+    if (!trimmed)
+        return "Question";
+    return trimmed.length > HEADER_MAX_LENGTH
+        ? trimmed.slice(0, HEADER_MAX_LENGTH - 1).trimEnd() + "…"
+        : trimmed;
+}
+/**
+ * Build the OpenCode `question` tool input. `Question.Prompt` requires
+ * `question`, `header`, and `options[{label, description}]`; Cursor options
+ * carry no description, so it stays empty rather than being invented.
+ */
+export function askQuestionToolInput(args) {
+    return {
+        questions: args.questions.map((question) => ({
+            question: question.prompt,
+            header: header(args.title),
+            options: displayOptions(question).map((option) => ({
+                label: option.label,
+                description: "",
+            })),
+            ...(question.allowMultiple ? { multiple: true } : {}),
+        })),
+    };
+}
+/** `AskQuestionResult{rejected}` — interaction-utils `N$`. */
+export function rejectedResult(reason) {
+    return { rejected: { reason: reason ?? SKIPPED_REASON } };
+}
+/** `AskQuestionResult{async}` — the immediate reply for `run_async` queries. */
+export function asyncResult() {
+    return { async: {} };
+}
+/**
+ * Pull each question's answer text out of OpenCode's `question` tool output.
+ *
+ * The tool returns prose, not structured data (`metadata.answers` does not
+ * cross the AI SDK boundary):
+ *
+ *   User has answered your questions: "<q1>"="<a, b>", "<q2>"="Unanswered". You
+ *   can now continue with the user's answers in mind.
+ *
+ * The provider authored the question strings, so each answer is located by its
+ * own `"<question>"="` anchor scanning forward — robust against commas, quotes
+ * and `"="` inside question or answer text, and against duplicate questions.
+ * Returns undefined for a question whose anchor is absent, which is treated as
+ * unanswered rather than guessed at.
+ */
+export function parseAnswerSegments(questions, output) {
+    const answers = [];
+    let cursor = 0;
+    for (const question of questions) {
+        const anchor = `"${question.prompt}"="`;
+        const start = output.indexOf(anchor, cursor);
+        if (start < 0) {
+            answers.push(undefined);
+            continue;
+        }
+        const valueStart = start + anchor.length;
+        // The value ends at the last quote before the next anchor (or the trailing
+        // `. You can now continue…`). Searching backwards from the next anchor
+        // keeps quoted text inside an answer intact.
+        const nextAnchorStart = questions
+            .map((other) => output.indexOf(`"${other.prompt}"="`, valueStart))
+            .filter((index) => index > valueStart)
+            .reduce((min, index) => (min < 0 || index < min ? index : min), -1);
+        const searchEnd = nextAnchorStart >= 0 ? nextAnchorStart : output.length;
+        const valueEnd = output.lastIndexOf('"', searchEnd - 1);
+        if (valueEnd < valueStart) {
+            answers.push(undefined);
+            continue;
+        }
+        answers.push(output.slice(valueStart, valueEnd));
+        cursor = valueEnd;
+    }
+    return answers;
+}
+/** OpenCode's placeholder for a question the user left blank. */
+const UNANSWERED = "Unanswered";
+/**
+ * Map one question's answer labels back onto Cursor option ids.
+ *
+ * OpenCode returns labels, so a label that matches an option we sent becomes a
+ * `selected_option_id`; anything else is the user's custom answer and becomes
+ * `freeform_text`. Cursor CLI's `iX` substitutes the literal "Other" when the
+ * freeform row was chosen without text, so an empty custom answer does too.
+ */
+export function answerForQuestion(question, segment) {
+    const answer = { question_id: question.id };
+    if (segment === undefined || segment.trim().length === 0 || segment.trim() === UNANSWERED) {
+        return answer;
+    }
+    const byLabel = new Map(displayOptions(question).map((option) => [option.label.trim().toLowerCase(), option.id]));
+    const selected = [];
+    const custom = [];
+    // `multiple: true` answers arrive joined with ", " (question tool `formatted`).
+    for (const piece of segment.split(", ")) {
+        const label = piece.trim();
+        if (!label)
+            continue;
+        const optionId = byLabel.get(label.toLowerCase());
+        if (optionId !== undefined)
+            selected.push(optionId);
+        else
+            custom.push(label);
+    }
+    if (selected.length > 0)
+        answer.selected_option_ids = selected;
+    if (custom.length > 0)
+        answer.freeform_text = custom.join(", ");
+    else if (selected.length === 0)
+        answer.freeform_text = "Other";
+    return answer;
+}
+/**
+ * Translate an OpenCode `question` tool result into an `AskQuestionResult`.
+ *
+ * A tool error means the host dismissed or failed the prompt — OpenCode's
+ * `Question.RejectedError` is the dismissal path — so it maps to the CLI's
+ * rejection rather than an empty success, which the model would read as "the
+ * user answered nothing".
+ */
+export function askQuestionResultFromToolOutput(args, output, isError) {
+    if (isError) {
+        const reason = output.trim();
+        return rejectedResult(reason.length > 0 ? reason : DISMISSED_REASON);
+    }
+    const segments = parseAnswerSegments(args.questions, output);
+    return {
+        success: {
+            answers: args.questions.map((question, index) => answerForQuestion(question, segments[index])),
+        },
+    };
+}

package/dist/protocol/conversation-bind.d.ts

@@ -24,6 +24,7 @@ export declare function peekConversationId(sessionKey: string): string;
  */
 export declare function bindConversationId(sessionKey: string | undefined, opts?: {
     reset?: boolean;
+    ephemeral?: boolean;
 }): {
     conversationId: string;
     reset: boolean;

package/dist/protocol/conversation-bind.js

@@ -76,6 +76,9 @@ export function peekConversationId(sessionKey) {
  * mint a new id so TurnEnded cache_read cannot keep overflowing OpenCode.
  */
 export function bindConversationId(sessionKey, opts) {
+    if (opts?.ephemeral) {
+        return { conversationId: crypto.randomUUID(), reset: false };
+    }
     if (!sessionKey) {
         return { conversationId: crypto.randomUUID(), reset: !!opts?.reset };
     }

package/dist/protocol/create-plan.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 { type OpencodeQuestionInput } from "./ask-question.js";
+export type CursorPlanTodo = {
+    id: string;
+    content: string;
+    status: string;
+};
+export type CursorCreatePlanArgs = {
+    plan: string;
+    overview: string;
+    name: string;
+    isProject: boolean;
+    todos: CursorPlanTodo[];
+};
+export type DecodedCreatePlanQuery = {
+    args: CursorCreatePlanArgs;
+    toolCallId: string;
+};
+export type CreatePlanWriteResult = {
+    ok: true;
+    planPath: string;
+    planUri: string;
+    markdown: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Optional host plan-stage tool advertised by a compatible host. */
+export declare const CURSOR_PLAN_STAGE_TOOL = "cursor_plan_stage";
+/** Held InteractionQuery continuation field for a native host plan stage. */
+export declare const CREATE_PLAN_RESULT_FIELD = "create_plan_request_response";
+export type CursorPlanStageInput = {
+    plan_uri: string;
+    content: string;
+    title: string;
+};
+/**
+ * How a CreatePlan query is satisfied this turn. Keyed only on the advertised
+ * catalog and the provider's own plan-mode state — never on host identity.
+ *
+ * - `stage`   a host plan-stage tool is advertised; the host writes the plan
+ *             *and* owns the execution-approval prompt, and its tool result is
+ *             the approval outcome (success = approved, error = not approved).
+ * - `approve` no such tool, but the host advertises `question`: the provider
+ *             writes the plan itself and then asks the same thing with upstream
+ *             `PlanExitTool`'s own prompt.
+ * - `ack`     nothing to ask with (or a lifecycle turn): write, or for a
+ *             lifecycle turn skip the write, and acknowledge the CLI way.
+ *
+ * The plan is always persisted before any prompt: writing needs no approval,
+ * executing does.
+ */
+export type CreatePlanBridge = {
+    kind: "stage";
+} | {
+    kind: "approve";
+} | {
+    kind: "ack";
+};
+/** Upstream `PlanExitTool` wording, with the plan the provider just wrote. */
+export declare function createPlanApprovalQuestion(planLabel: string): string;
+export declare const CREATE_PLAN_APPROVAL_HEADER = "Build Agent";
+/** Cursor-visible reason when the user wants the plan revised instead of run. */
+export declare const CREATE_PLAN_NOT_APPROVED_REASON: string;
+/**
+ * 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 declare function resolveCreatePlanBridge(options: {
+    allowTools: boolean;
+    canStage?: boolean;
+    planModeActive?: boolean;
+    advertised: ReadonlySet<string> | Iterable<string>;
+}): CreatePlanBridge;
+/** Host `question` input mirroring upstream `PlanExitTool`'s own prompt. */
+export declare function createPlanApprovalQuestionInput(planLabel: string): OpencodeQuestionInput;
+/**
+ * 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 declare function createPlanApproved(output: string, isError: boolean, question: string): boolean;
+/** Decode a `create_plan_request_query` body, or undefined when unusable. */
+export declare function decodeCreatePlanQuery(queryBytes: Uint8Array): DecodedCreatePlanQuery | undefined;
+/** OpenCode-style adjective-noun slug (core/src/util/slug.ts). */
+export declare function randomPlanSlug(seed?: number): string;
+/** Slugify a human title into a filesystem-safe token. */
+export declare function slugifyPlanName(name: string): string;
+/** Build the advertised host plan-stage artifact payload. */
+export declare function createPlanStageInput(args: CursorCreatePlanArgs): CursorPlanStageInput;
+/**
+ * Resolve the absolute plan file path via {@link hostPlansDir}.
+ * Filename shape matches OpenCode Session.plan: `<created>-<slug>.md`.
+ */
+export declare function resolveHostPlanPath(workspaceRoot: string, name?: string, created?: number): string;
+/** @deprecated Prefer {@link resolveHostPlanPath}. */
+export declare const resolveOpencodePlanPath: typeof 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 declare function renderOpencodePlanMarkdown(args: CursorCreatePlanArgs): string;
+/**
+ * Write the plan under {@link hostPlansDir} and return a `file://` URI.
+ * Empty / missing content is the caller's responsibility (empty plan_uri ack).
+ */
+export declare function writeOpencodePlanFile(args: CursorCreatePlanArgs, workspaceRoot: string, created?: number): CreatePlanWriteResult;
+/**
+ * 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 declare function renderPlanReviewMessage(markdown: string, planPath: string): string;