cursor-opencode-provider 0.8.0 → 0.8.1

package/dist/host-plan-file.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OpenCode's own plan file per session, resolved while the session runs under
+ * the `plan` agent. CreatePlan records the plan there so the `plan_exit` review
+ * reads exactly the file the user approves.
+ *
+ * Resolution is structural: session `slug` / `time.created` from the classic
+ * client, project VCS and worktree from the plugin input, and the location
+ * from OpenCode's `Session.plan` rule (or an injected host path bridge).
+ */
+export declare function hostPlanFileFor(sessionID: string | undefined): string | undefined;
+/** True once the session's plan file is known, including known to be absent. */
+export declare function isHostPlanFileResolved(sessionID: string | undefined): boolean;
+/**
+ * Record a session's plan file. `null` records that the host defines none, so
+ * it is not looked up again; `undefined` forgets it, so the next request retries.
+ */
+export declare function setHostPlanFile(sessionID: string, file: string | null | undefined): void;
+export declare function resetHostPlanFilesForTests(): void;
+/**
+ * Resolve and remember the host plan file for one session. A session without
+ * one is remembered as such; a failed lookup is not, so a later request retries.
+ */
+export declare function resolveHostPlanFile(input: {
+    sessionID: string;
+    getSession: (sessionID: string) => Promise<unknown>;
+    worktree: string | undefined;
+    vcs: boolean;
+}): Promise<string | undefined>;

package/dist/host-plan-file.js

@@ -0,0 +1,76 @@
+/**
+ * OpenCode's own plan file per session, resolved while the session runs under
+ * the `plan` agent. CreatePlan records the plan there so the `plan_exit` review
+ * reads exactly the file the user approves.
+ *
+ * Resolution is structural: session `slug` / `time.created` from the classic
+ * client, project VCS and worktree from the plugin input, and the location
+ * from OpenCode's `Session.plan` rule (or an injected host path bridge).
+ */
+import { hostPlanFilePath } from "./context/paths.js";
+import { errorMessage, trace } from "./debug.js";
+/** Session → its plan file, or `null` when the host defines none for it. */
+const hostPlanFiles = new Map();
+const MAX_HOST_PLAN_FILES = 256;
+export function hostPlanFileFor(sessionID) {
+    const key = sessionID?.trim();
+    return (key ? hostPlanFiles.get(key) : undefined) ?? undefined;
+}
+/** True once the session's plan file is known, including known to be absent. */
+export function isHostPlanFileResolved(sessionID) {
+    const key = sessionID?.trim();
+    return !!key && hostPlanFiles.has(key);
+}
+/**
+ * Record a session's plan file. `null` records that the host defines none, so
+ * it is not looked up again; `undefined` forgets it, so the next request retries.
+ */
+export function setHostPlanFile(sessionID, file) {
+    const key = sessionID.trim();
+    if (!key)
+        return;
+    hostPlanFiles.delete(key);
+    if (file === undefined || file === "")
+        return;
+    hostPlanFiles.set(key, file);
+    while (hostPlanFiles.size > MAX_HOST_PLAN_FILES) {
+        const oldest = hostPlanFiles.keys().next().value;
+        if (!oldest)
+            break;
+        hostPlanFiles.delete(oldest);
+    }
+}
+export function resetHostPlanFilesForTests() {
+    hostPlanFiles.clear();
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Resolve and remember the host plan file for one session. A session without
+ * one is remembered as such; a failed lookup is not, so a later request retries.
+ */
+export async function resolveHostPlanFile(input) {
+    try {
+        const response = record(await input.getSession(input.sessionID));
+        const info = record(response?.data) ?? response;
+        const slug = typeof info?.slug === "string" ? info.slug : "";
+        const created = record(info?.time)?.created;
+        if (!slug || typeof created !== "number" || !input.worktree) {
+            setHostPlanFile(input.sessionID, null);
+            return undefined;
+        }
+        const file = hostPlanFilePath({ worktree: input.worktree, vcs: input.vcs, created, slug });
+        setHostPlanFile(input.sessionID, file ?? null);
+        if (file)
+            trace(`host-plan-file: sessionID=${input.sessionID} file=${file}`);
+        return file;
+    }
+    catch (error) {
+        trace(`host-plan-file: unresolved sessionID=${input.sessionID} err=${errorMessage(error)}`);
+        setHostPlanFile(input.sessionID, undefined);
+        return undefined;
+    }
+}

package/dist/image-input.d.ts

@@ -9,6 +9,8 @@ export type CursorHistoryImageExtraction = {
     hashes: string[];
     candidateCount: number;
     duplicateCount: number;
+    /** Unreadable optional tool media; explicit user attachments still fail loudly. */
+    omittedCount?: number;
 };
 export type CursorPromptImageExtraction = CursorHistoryImageExtraction & {
     userImageCount: number;
@@ -23,6 +25,22 @@ export declare function extractCursorHistoryImages(prompt: readonly unknown[], o
     maxBytes?: number;
     filenameOffset?: number;
 }): Promise<CursorHistoryImageExtraction>;
+/**
+ * Decode the images a host tool returned (its own `file-data` / `image-data`
+ * parts, or the `file` parts OpenCode moves into the trailing
+ * `Attached media from tool result:` message) for a held-Run exec result.
+ * Non-image parts are skipped; a part that cannot be decoded is dropped so the
+ * text result is still delivered.
+ */
+export declare function extractCursorToolResultImages(parts: readonly unknown[], options?: {
+    signal?: AbortSignal;
+    maxBytes?: number;
+    maxImages?: number;
+}): Promise<{
+    images: CursorImageInput[];
+    hashes: string[];
+    omittedCount: number;
+}>;
 export declare function extractCursorPromptImages(prompt: readonly unknown[], lastUser: Record<string, unknown> | undefined, options: {
     supportsImages: boolean;
     seenHistoryHashes?: ReadonlySet<string>;

package/dist/image-input.js

@@ -4,8 +4,14 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { UnsupportedFunctionalityError } from "@ai-sdk/provider";
 export const MAX_CURSOR_IMAGE_INPUT_BYTES = 20 * 1024 * 1024;
+function isToolMediaCaption(message) {
+    if (!message || !Array.isArray(message.content))
+        return false;
+    const first = message.content[0];
+    return first?.type === "text" && first.text === "Attached media from tool result:";
+}
 export function hasCursorUserImages(lastUser) {
-    return !!lastUser && Array.isArray(lastUser.content) && lastUser.content.some((part) => {
+    return !isToolMediaCaption(lastUser) && !!lastUser && Array.isArray(lastUser.content) && lastUser.content.some((part) => {
         if (!part || typeof part !== "object")
             return false;
         const file = part;
@@ -20,18 +26,20 @@ export function assertCursorUserImageSupport(lastUser, supportsImages, modelId)
         return;
     unsupported("image input", `Cursor model ${JSON.stringify(modelId)} does not support image input`);
 }
-function decodeBase64(value) {
+function decodeBase64(value, remaining) {
     const normalized = value.replace(/\s/g, "");
     if (!normalized || !/^[A-Za-z0-9+/_-]*={0,2}$/.test(normalized)) {
         return unsupported("image input", "Cursor provider received invalid base64 image data");
     }
+    const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+    assertImageSize(Math.floor((normalized.length - padding) * 3 / 4), remaining);
     const data = Uint8Array.from(Buffer.from(normalized, "base64"));
     if (data.length === 0) {
         return unsupported("image input", "Cursor provider received an empty image");
     }
     return data;
 }
-function decodeDataUrl(value) {
+function decodeDataUrl(value, remaining) {
     if (!value.startsWith("data:")) {
         return unsupported("image input", "Cursor provider supports base64-encoded image data URLs only");
     }
@@ -47,7 +55,7 @@ function decodeDataUrl(value) {
     const firstSeparator = metadata.indexOf(";");
     const mimeType = metadata.slice(0, firstSeparator);
     return {
-        data: decodeBase64(value.slice(commaIndex + 1)),
+        data: decodeBase64(value.slice(commaIndex + 1), remaining),
         mimeType: mimeType || undefined,
     };
 }
@@ -121,13 +129,15 @@ async function readResponseBytes(response, remaining) {
     return data;
 }
 async function resolveImageData(value, remaining, signal) {
-    if (value instanceof Uint8Array)
+    if (value instanceof Uint8Array) {
+        assertImageSize(value.length, remaining);
         return { data: Uint8Array.from(value) };
+    }
     if (typeof value === "string") {
-        return value.startsWith("data:") ? decodeDataUrl(value) : { data: decodeBase64(value) };
+        return value.startsWith("data:") ? decodeDataUrl(value, remaining) : { data: decodeBase64(value, remaining) };
     }
     if (value.protocol === "data:")
-        return decodeDataUrl(value.href);
+        return decodeDataUrl(value.href, remaining);
     if (value.protocol === "file:") {
         const filePath = fileURLToPath(value);
         const info = await stat(filePath);
@@ -183,21 +193,33 @@ export async function extractCursorUserImages(lastUser, signal, maxBytes = MAX_C
         const file = part;
         if (file.type !== "file")
             continue;
-        const image = await decodeCursorImagePart(file, byteBudget - totalBytes, signal, `image-${images.length + 1}`);
+        const image = await decodeCursorImagePart(toolImagePart(file) ?? file, byteBudget - totalBytes, signal, `image-${images.length + 1}`);
         totalBytes += image.data.length;
         images.push(image);
     }
     return images;
 }
-function pushImageFileParts(parts, content) {
+/** Normalize OpenCode / AI SDK attachment shapes before either delivery path. */
+function toolImagePart(part) {
+    if (!part || typeof part !== "object")
+        return undefined;
+    const file = part;
+    if (!["file", "file-data", "image-data", "image-url", "media", "image"].includes(String(file.type)))
+        return undefined;
+    const mediaType = typeof file.mediaType === "string" ? file.mediaType
+        : file.type === "image-url" ? "image/*" : file.mime;
+    if (typeof mediaType !== "string" || !mediaType.startsWith("image/"))
+        return undefined;
+    const source = file.url ?? file.uri;
+    const data = file.data ?? (typeof source === "string" && /^(?:https?|file):/.test(source) && URL.canParse(source)
+        ? new URL(source) : source);
+    return { ...file, mediaType, data };
+}
+function pushImageFileParts(parts, content, toolResult = false) {
     for (const part of content) {
-        if (!part || typeof part !== "object")
-            continue;
-        const file = part;
-        if (file.type === "file" &&
-            typeof file.mediaType === "string" &&
-            file.mediaType.startsWith("image/"))
-            parts.push(file);
+        const file = toolImagePart(part);
+        if (file?.type === "file")
+            parts.push({ file, toolResult });
     }
 }
 function cursorHistoryImageParts(prompt) {
@@ -222,7 +244,7 @@ function cursorHistoryImageParts(prompt) {
         if (record.role === "user") {
             if (i === lastUserIndex)
                 continue;
-            pushImageFileParts(parts, record.content);
+            pushImageFileParts(parts, record.content, isToolMediaCaption(record));
             continue;
         }
         if (record.role === "assistant") {
@@ -244,11 +266,9 @@ function cursorHistoryImageParts(prompt) {
             for (const value of output.value) {
                 if (!value || typeof value !== "object")
                     continue;
-                const file = value;
-                if (file.type === "file-data" &&
-                    typeof file.mediaType === "string" &&
-                    file.mediaType.startsWith("image/"))
-                    parts.push(file);
+                const file = toolImagePart(value);
+                if (file)
+                    parts.push({ file, toolResult: true });
             }
         }
     }
@@ -264,11 +284,22 @@ export async function extractCursorHistoryImages(prompt, options) {
     const hashes = [];
     const hashesThisTurn = new Set();
     let duplicateCount = 0;
+    let omittedCount = 0;
     let totalBytes = 0;
-    for (const file of candidates) {
+    for (const { file, toolResult } of candidates) {
         // Resolve against the per-image cap first so a previously sent duplicate
         // does not fail merely because little combined budget remains this turn.
-        const image = await decodeCursorImagePart(file, MAX_CURSOR_IMAGE_INPUT_BYTES, options.signal, `image-${(options.filenameOffset ?? 0) + images.length + 1}`, MAX_CURSOR_IMAGE_INPUT_BYTES);
+        let image;
+        try {
+            image = await decodeCursorImagePart(file, MAX_CURSOR_IMAGE_INPUT_BYTES, options.signal, `image-${(options.filenameOffset ?? 0) + images.length + 1}`);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (!toolResult || (error instanceof Error && error.name === "AbortError"))
+                throw error;
+            omittedCount++;
+            continue;
+        }
         const hash = imageContentHash(image.data);
         if (options.seenHashes?.has(hash) || hashesThisTurn.has(hash)) {
             duplicateCount++;
@@ -280,15 +311,71 @@ export async function extractCursorHistoryImages(prompt, options) {
         hashes.push(hash);
         hashesThisTurn.add(hash);
     }
-    return { images, hashes, candidateCount: candidates.length, duplicateCount };
+    return { images, hashes, candidateCount: candidates.length, duplicateCount, ...(omittedCount > 0 ? { omittedCount } : {}) };
+}
+/**
+ * Decode the images a host tool returned (its own `file-data` / `image-data`
+ * parts, or the `file` parts OpenCode moves into the trailing
+ * `Attached media from tool result:` message) for a held-Run exec result.
+ * Non-image parts are skipped; a part that cannot be decoded is dropped so the
+ * text result is still delivered.
+ */
+export async function extractCursorToolResultImages(parts, options = {}) {
+    const maxBytes = cursorImageBudget(options.maxBytes ?? MAX_CURSOR_IMAGE_INPUT_BYTES);
+    const images = [];
+    const hashes = [];
+    let totalBytes = 0;
+    let omittedCount = 0;
+    options.signal?.throwIfAborted();
+    for (const part of parts) {
+        options.signal?.throwIfAborted();
+        const file = toolImagePart(part);
+        if (!file)
+            continue;
+        if (images.length >= (options.maxImages ?? Infinity) || totalBytes >= maxBytes) {
+            omittedCount++;
+            continue;
+        }
+        try {
+            const image = await decodeCursorImagePart(file, maxBytes - totalBytes, options.signal, `image-${images.length + 1}`);
+            options.signal?.throwIfAborted();
+            totalBytes += image.data.length;
+            images.push(image);
+            hashes.push(imageContentHash(image.data));
+        }
+        catch (error) {
+            // Tool media is optional: a missing file or failed download must not
+            // strand every pending exec. Cancellation still belongs to the caller.
+            options.signal?.throwIfAborted();
+            if (error instanceof Error && error.name === "AbortError")
+                throw error;
+            omittedCount++;
+        }
+    }
+    return { images, hashes, omittedCount };
 }
 export async function extractCursorPromptImages(prompt, lastUser, options) {
     const maxBytes = cursorImageBudget(options.maxBytes ?? MAX_CURSOR_IMAGE_INPUT_BYTES);
-    const userImages = await extractCursorUserImages(lastUser, options.signal, maxBytes);
+    const toolCaption = isToolMediaCaption(lastUser);
+    const caption = toolCaption && options.supportsImages
+        ? await extractCursorToolResultImages(lastUser.content, { signal: options.signal, maxBytes })
+        : undefined;
+    const captionHashes = [];
+    const seenHashes = new Set(options.seenHistoryHashes);
+    let captionDuplicates = 0;
+    const userImages = toolCaption ? (caption?.images ?? []).filter((_image, index) => {
+        const hash = caption.hashes[index];
+        if (seenHashes.has(hash)) {
+            captionDuplicates++;
+            return false;
+        }
+        seenHashes.add(hash);
+        captionHashes.push(hash);
+        return true;
+    }) : await extractCursorUserImages(lastUser, options.signal, maxBytes);
     const userBytes = userImages.reduce((total, image) => total + image.data.length, 0);
     // Seed history dedupe with this-turn last-user hashes so the same bytes on an
     // earlier user/assistant/tool message are not attached twice in one Run.
-    const seenHashes = new Set(options.seenHistoryHashes);
     for (const image of userImages)
         seenHashes.add(imageContentHash(image.data));
     const history = await extractCursorHistoryImages(prompt, {
@@ -300,7 +387,11 @@ export async function extractCursorPromptImages(prompt, lastUser, options) {
     });
     return {
         ...history,
+        hashes: [...captionHashes, ...history.hashes],
+        duplicateCount: history.duplicateCount + captionDuplicates,
         images: [...userImages, ...history.images],
-        userImageCount: userImages.length,
+        userImageCount: toolCaption ? 0 : userImages.length,
+        ...((history.omittedCount ?? 0) + (caption?.omittedCount ?? 0) > 0
+            ? { omittedCount: (history.omittedCount ?? 0) + (caption?.omittedCount ?? 0) } : {}),
     };
 }

package/dist/image-save.d.ts

@@ -17,16 +17,24 @@ export declare const IMAGE_PERMISSION_DENIED_PREFIX = "CursorImagePermissionDeni
 export type ImageSaveToolContext = {
     worktree: string;
     directory: string;
-    ask(input: {
+    /**
+     * Classic OpenCode 1.x `ToolContext.ask`. A host whose tool context has no
+     * permission prompt (OpenCode 2.0's public `ToolContext`) passes `null`
+     * explicitly: the commit then writes after containment, gated only by the
+     * tool's catalog permission. A missing `ask` is refused, never treated as
+     * permission.
+     */
+    ask: ((input: {
         permission: string;
         patterns: string[];
         always: string[];
         metadata: Record<string, unknown>;
-    }): Promise<void>;
+    }) => Promise<void>) | null;
 };
 export type ImageSaveResult = {
     title: string;
     output: string;
+    bytes: number;
     attachments?: Array<{
         type: "file";
         mime: string;

package/dist/image-save.js

@@ -126,31 +126,42 @@ export async function executeCursorImageSave(args, ctx) {
     // case `assertExternalDirectory` exists for. Asking only for `edit` would
     // quietly skip a boundary the host enforces for every one of its own writes.
     const editPattern = path.relative(realRoot(workspace), contained.path);
-    try {
-        if (!isInsideProject(contained.path, workspace, ctx.directory)) {
-            const parentDir = path.dirname(contained.path);
-            const glob = path.join(parentDir, "*").replaceAll("\\", "/");
+    if (typeof ctx.ask === "function") {
+        try {
+            if (!isInsideProject(contained.path, workspace, ctx.directory)) {
+                const parentDir = path.dirname(contained.path);
+                const glob = path.join(parentDir, "*").replaceAll("\\", "/");
+                await ctx.ask({
+                    permission: "external_directory",
+                    patterns: [glob],
+                    always: [glob],
+                    metadata: { filepath: contained.path, parentDir },
+                });
+            }
             await ctx.ask({
-                permission: "external_directory",
-                patterns: [glob],
-                always: [glob],
-                metadata: { filepath: contained.path, parentDir },
+                permission: "edit",
+                patterns: [editPattern],
+                always: ["*"],
+                metadata: {
+                    filepath: contained.path,
+                    mime: image.mime,
+                    bytes: image.data.length,
+                    source: "cursor-generate-image",
+                },
             });
         }
-        await ctx.ask({
-            permission: "edit",
-            patterns: [editPattern],
-            always: ["*"],
-            metadata: {
-                filepath: contained.path,
-                mime: image.mime,
-                bytes: image.data.length,
-                source: "cursor-generate-image",
-            },
-        });
+        catch (error) {
+            const reason = errorMessage(error);
+            trace(`image save: permission refused path=${JSON.stringify(contained.path)} reason=${reason}`);
+            throw new Error(`${IMAGE_PERMISSION_DENIED_PREFIX} ${reason}`);
+        }
     }
-    catch (error) {
-        const reason = errorMessage(error);
+    else if (ctx.ask === null) {
+        trace(`image save: host cannot prompt; writing after containment ` +
+            `path=${JSON.stringify(contained.path)}`);
+    }
+    else {
+        const reason = "this host did not provide a permission prompt for the write";
         trace(`image save: permission refused path=${JSON.stringify(contained.path)} reason=${reason}`);
         throw new Error(`${IMAGE_PERMISSION_DENIED_PREFIX} ${reason}`);
     }
@@ -185,5 +196,6 @@ export async function executeCursorImageSave(args, ctx) {
     return {
         title: editPattern,
         output: `Saved the generated image to ${contained.path} (${image.data.length} bytes).`,
+        bytes: image.data.length,
     };
 }

package/dist/language-model.d.ts

@@ -7,6 +7,7 @@ import { type CursorSession } from "./session.js";
 import { CursorProviderError } from "./errors.js";
 import { type ModelInfo } from "./models.js";
 import type { SeedHistoryMessage } from "./protocol/request.js";
+import { type CursorImageInput } from "./image-input.js";
 type PromptIdentity = {
     hostAgent?: string;
     systemPromptHash?: string;
@@ -36,7 +37,7 @@ export type CursorRetryPolicy = {
 };
 export declare function resolveRetryPolicy(options: CursorRetryOptions | undefined): CursorRetryPolicy;
 export declare function connectFrameError(payload: string): CursorProviderError;
-/** Restore the last real catalog solely for lifecycle turns such as compaction. */
+/** Restore the epoch catalog for the next nonempty host turn. */
 export declare function restoreTurnToolCatalog(sessionKey: string, tools: OpencodeToolDef[]): void;
 /** Record the authoritative host todo list for an OpenCode session. */
 export declare function rememberMirroredTodos(sessionKey: string | undefined, todos: ReadonlyArray<Record<string, unknown>>): void;
@@ -48,6 +49,8 @@ export declare function snapshotMirroredTodosBySession(sessionKey: string | unde
  * churn have a single no-op definition.
  */
 export declare function promptIdentityWouldRemint(_previous: PromptIdentity, _current: PromptIdentity): boolean;
+/** Test helper: content hashes recorded after a successful held-Run image write. */
+export declare function snapshotSentHistoryImageHashesForTests(sessionKey: string): string[];
 type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
 export declare function pumpWithRecovery(input: {
@@ -96,12 +99,14 @@ export declare function isProperCatalogSubset(incoming: ReadonlyArray<{
 }>): boolean;
 /**
  * An open parent Run for this OpenCode session whose catalog strictly contains
- * the incoming tools is treated as an in-session helper. Those calls must not
- * cancel/supersede the parent (that remints on the trailing tool result).
+ * the incoming tools is treated as an in-session helper unless the request
+ * carries a result for that parent's pending call. A result can precede a new
+ * user message or agent-change reminder and still needs to reach the parent.
+ * Helper calls must not cancel/supersede the parent.
  */
 export declare function shouldIsolateInSessionHelper(openCodeSessionId: string | undefined, incomingTools: ReadonlyArray<{
     name?: string;
-}>): boolean;
+}>, historicalResults?: ExtractedToolResult[]): boolean;
 /** How long a fresh-turn drain may wait for Cursor `turn_ended` after bridged settle. */
 export declare const FRESH_TURN_DRAIN_TIMEOUT_MS = 8000;
 /**
@@ -119,6 +124,9 @@ export declare const FRESH_TURN_PENDING_CANCEL_REASON = "Host started a new user
  */
 export declare function preparePriorSessionForFreshTurn(openCodeSessionId: string | undefined, opts?: {
     timeoutMs?: number;
+    /** Tool results already in this prompt; deliver any that match held pendings before cancel. */
+    toolResults?: ExtractedToolResult[];
+    hostAgent?: string;
 }): Promise<"drained" | "settled-only" | "busy" | "none">;
 /**
  * Write error/reject results for every still-open non-bridged pending on the
@@ -135,33 +143,46 @@ export declare function cancelPendingExecsForFreshTurn(session: CursorSession):
 export declare function drainSessionUntilTurnEnded(session: CursorSession, opts?: {
     timeoutMs?: number;
 }): Promise<"turn-ended" | "busy" | "timeout" | "interrupted" | "skipped">;
-/**
- * Deliver trailing tool results onto a live continuation session.
- * Returns the same session when writes succeed (or only bridged results were
- * cleared). Returns undefined after closing the session when a write fails, so
- * the caller can rebase onto a fresh Run instead of pumping a dead stream.
- */
-export declare function deliverContinuationResults(session: CursorSession, trailingToolResults: ExtractedToolResult[]): CursorSession | undefined;
+export declare function deliverContinuationResults(session: CursorSession, trailingToolResults: ExtractedToolResult[], 
+/** Host primary agent of the request that carries these results. */
+delivery?: {
+    hostAgent?: string;
+}): CursorSession | undefined;
 /**
  * Read the held-open stream, emitting stream parts, until the turn boundary:
- *  - a tool call (exec_server_message) → emit tool-call, finish "tool-calls",
- *    and KEEP the session open for the result on the next doStream call;
+ *  - tool call(s) for one Cursor generation → emit each tool-call as it
+ *    arrives; finish "tool-calls" once Cursor's listed count (field 27) is
+ *    met (or immediately when the process has never seen field 27); KEEP the
+ *    session open for results on the next doStream call;
  *  - turn_ended → finish "stop" and close the session;
- *  - transport EOF before turn_ended → throw for one fresh-Run recovery.
+ *  - transport EOF before turn_ended → throw for one fresh-Run recovery
+ *    (after host tools were already emitted, finish "tool-calls" instead and
+ *    let the continuation rebase).
  */
 export declare function pump(session: CursorSession, controller: ReadableStreamDefaultController<V3Part>, ids: {
     textId: string;
     reasoningId: string;
 }, abortSignal?: AbortSignal): Promise<void>;
-type ExtractedToolResult = {
+type ToolResultContent = {
     toolCallId: string;
-    sessionId: string;
-    execId: number;
     toolName: string;
     output: string;
     error?: string;
+    /** Host media parts of this result (own content, or the trailing media message). */
+    media?: unknown[];
+    /** `media` decoded for the exec result, with content hashes in the same order. */
+    images?: CursorImageInput[];
+    imageHashes?: string[];
+    /** Host updates that a binary read cannot carry in its output oneof. */
+    notes?: string;
+};
+type ExtractedToolResult = ToolResultContent & {
+    sessionId: string;
+    execId: number;
 };
 export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOptions["prompt"]): ExtractedToolResult[];
+/** Decode only image-bearing pending execs, under one continuation-wide budget. */
+export declare function decodeTrailingToolImages(session: CursorSession, results: ExtractedToolResult[], signal?: AbortSignal, maxBytes?: number): Promise<ExtractedToolResult[]>;
 /** Detect a host-owned canonical plan review, excluding Cursor exec replies. */
 export declare function hasApprovedUncorrelatedPlanStageResult(prompt: LanguageModelV3CallOptions["prompt"]): boolean;
 /**
@@ -179,6 +200,7 @@ export declare function groundCheckpointTurnText(userText: string, checkpoint: b
  */
 export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean, workspaceRoot: string, options?: {
     knownMcpServers?: Iterable<string>;
+    allowTools?: boolean;
 }): string | undefined;
 /** Rough char→token estimate for mid-turn usage before TurnEnded arrives. */
 export declare function estimateTokens(chars: number): number;
@@ -250,6 +272,12 @@ export declare function spanEndParts(opts: {
 }>;
 /** Exported for tests — false for compaction/summary (no tools) and toolChoice none. */
 export declare function computeAllowTools(toolCount: number, toolChoice: LanguageModelV3CallOptions["toolChoice"] | undefined): boolean;
+/**
+ * OpenCode title/summary take the first non-empty line of the answer. After a
+ * lifecycle refuse, Cursor often narrates that tools are unavailable — drop
+ * that so it does not become the session title.
+ */
+export declare function shouldDropLifecycleToollessText(text: string, refusedExec: boolean): boolean;
 export declare function resolveTurnToolState(input: {
     sessionKey?: string;
     incomingTools: OpencodeToolDef[];