cursor-opencode-provider 0.4.3 → 0.6.0

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;

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;
+}