cursor-opencode-provider 0.3.2 → 0.4.1

package/README.md

@@ -17,6 +17,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 - **OpenCode integration** — registers a `cursor` provider with auth hooks and cached model list
 - **Authentication** — browser OAuth (PKCE), or API key from [cursor.com/settings](https://cursor.com/settings)
 - **Model discovery** — fetches available models from Cursor's API and caches them locally
+- **Image input** — advertises vision only for supported models and forwards OpenCode image attachments to Cursor
 - **Streaming** — bidirectional Connect-RPC Runs with stale-session rotation, health checks, semantic/read-idle deadlines, bounded replay-safe recovery, and activity-aware held tool continuations
 - **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts, including catalog-aware native subagent execution: exact advertised custom agents win, `unspecified` / `generalPurpose` select `general`, read-oriented `bugbot` / `security-review` select `explore`, and `cursor-guide` selects enabled Kilo `scout` before `explore`; MiMo `actor` is used instead of its work-item `task` tool when advertised. The bridge also covers the Pi read/bash/edit/write/grep/find/ls request/result range, enforces the exact current OpenCode tool catalog, mirrors finalized display-only todo/plan state, and strips OpenCode's `read` XML envelope before returning content to Cursor.
 - **Thinking / reasoning** — surfaces extended-thinking deltas where the model supports it
@@ -47,7 +48,7 @@ Add the package to OpenCode config. OpenCode installs npm plugins with Bun at st
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.3.2"`.
+Pin a version if you want: `"cursor-opencode-provider@0.4.1"`.
 
 You can also install it yourself first:
 
@@ -117,7 +118,7 @@ browser login or an API key. `CURSOR_API_KEY` is also picked up automatically.
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.3.2/plugin/opencode2"`.
+Pin a version if you want: `"cursor-opencode-provider@0.4.1/plugin/opencode2"`.
 
 OpenCode 2.0 installs the published package into its host cache and loads the AI SDK
 entry from there (`aisdk:cursor-opencode-provider`). No extra env vars are required.
@@ -197,7 +198,7 @@ Feature parity with the classic plugin, and the two places 2.0 differs:
 | `chat.params` flags compaction turns | **No `chat.params` in 2.0** — the compaction agent is detected in `ctx.session.hook("context")` and correlated by session id |
 
 > **Beta.** OpenCode 2.0 and its plugin API are both beta and still changing. This
-> entrypoint is built against `@opencode-ai/plugin@next` (`0.0.0-next-16281`) and is
+> entrypoint is built against `@opencode-ai/plugin@next` (`0.0.0-next-17155`) and is
 > guarded by a compile-time conformance check, but expect churn.
 
 ### Authenticate
@@ -259,6 +260,28 @@ OpenCode’s context limit is static per model entry, while Cursor’s long-cont
 
 The Run still uses Cursor’s original model id; OpenCode’s synthetic `-1m` id is only for picking and limits.
 
+#### Context limit sources
+
+The provider resolves each catalog context limit in this order:
+
+1. Live `AvailableModels` metadata (variant `context` parameters first, then context-limit fields)
+2. Cursor’s published model table, generated from [`docs.md`](https://cursor.com/docs.md) alongside pricing data
+3. A conservative `200000` fallback when neither source publishes a limit
+
+The docs fallback only fills static catalog metadata. It does not invent Cursor variants or enable a long-context tier that `AvailableModels` did not advertise.
+
+#### Image input
+
+The provider advertises `text` + `image` input only when the selected Cursor model supports images; model output remains text. This works in the classic plugin, the 1.18 v2 plugin, and OpenCode 2.0.
+
+Image support is resolved in this order:
+
+1. Live `AvailableModels.supportsImages` metadata, including authoritative `false` values
+2. The `Capabilities` column in Cursor's [`docs.md`](https://cursor.com/docs.md), generated alongside context and pricing metadata
+3. Text-only when neither source describes the model
+
+OpenCode image file parts are decoded from bytes, base64/data URLs, local file URLs, or HTTP(S) URLs and sent through Cursor's `UserMessage.selected_context.selected_images` field. On fresh or rebased Runs, the provider also harvests image `file-data` from tool results and `file` parts from assistant history; previously sent history images are deduplicated by content hash per OpenCode session. Held-open continuation results remain text-only because Cursor's exec-result channel has no image field. Attachments are limited to 20 MiB total, matching OpenCode's desktop attachment budget. PDF, audio, and video inputs are not advertised or silently discarded.
+
 #### Max mode
 
 Cursor IDE has a separate **Max Mode** toggle that sets `requested_model.max_mode` and selects the default max / 1m variant. OpenCode has no equivalent custom toggle, so this provider approximates it:
@@ -337,6 +360,7 @@ OpenCode
 | `src/opencode2/` | 2.0-only catalog mapping, integration/auth, and local API types |
 | `src/plugin-core.ts` | Host-neutral SDK factory, package matching, API base/telemetry resolution |
 | `src/model-config.ts` | Cursor model → OpenCode model mapping shared by every plugin surface |
+| `src/image-input.ts` | AI SDK image attachment validation, decoding, and size limits |
 | `src/pricing.ts` / `src/pricing-data.ts` | Cursor docs token rates → classic `cost` and OpenCode 2.0 cost tiers |
 | `src/index.ts` | `createCursor` factory; default export is `CursorPlugin` |
 | `src/language-model.ts` | AI SDK `LanguageModelV3` adapter (`doStream`, `doGenerate`) |
@@ -355,11 +379,17 @@ The provider adds OpenCode-specific system guidance to normal tool-capable conve
 
 If this guidance causes issues, update `buildOpenCodeInteractionGuidance` in [`src/language-model.ts`](src/language-model.ts) and its focused coverage in [`test/prompt-history.test.ts`](test/prompt-history.test.ts).
 
+### Cursor edit handshakes
+
+Cursor's legacy `edit_tool_call` is implemented internally as a correlated `read_args` followed by a whole-file `write_args`; the write is transport mechanics, not a new decision to replace OpenCode's `edit` tool. The provider retains that correlation and exposes an existing-file mutation as one unique, line-bounded OpenCode `edit`. It still returns Cursor's expected typed `write_result`. New-file creation remains a `write`, and an `apply_patch`-only catalog receives the same targeted change as an `*** Update File:` patch.
+
+The prerequisite native read also preserves an existing final LF/CRLF. OpenCode's numbered read envelope cannot represent that terminator, and dropping it made Cursor's exact edit matcher reject valid replacements, retry reads, and eventually rewrite the file. This restoration applies only to confirmed-complete, unbounded reads; paged and capped reads keep their existing truncation behavior.
+
 ### `apply_patch` models (GPT-5 and friends)
 
 OpenCode 1.x does not simply add `apply_patch` for GPT-series models — it **removes** `edit` and `write` from the tool catalog and advertises `apply_patch` in their place (`ToolRegistry.tools`; the model id must contain `gpt-` and neither `oss` nor `gpt-4`). Cursor keeps sending its native write/edit requests regardless, so without translation every file change on a `gpt-5*` model is refused as an unavailable tool.
 
-The provider translates transparently: a native write becomes an `*** Add File:` patch, and a Pi edit becomes a minimal `*** Update File:` chunk widened to whole lines. This is keyed purely off what the host advertises — it is inert whenever `edit`/`write` are offered normally, and inert again when the host offers neither those nor `apply_patch`. An edit that cannot be expressed faithfully (target unreadable, or the text to replace is absent or ambiguous) is refused with a specific message rather than applied to the wrong region.
+The provider translates transparently: an uncorrelated native write becomes an `*** Add File:` patch, while a correlated legacy edit or Pi edit becomes a minimal `*** Update File:` chunk widened to whole lines. This is keyed purely off what the host advertises — it is inert whenever `edit`/`write` are offered normally, and inert again when the host offers neither those nor `apply_patch`. An edit that cannot be expressed faithfully (target unreadable, or the text to replace is absent or ambiguous) is refused with a specific message rather than applied to the wrong region.
 
 OpenCode 2.0 does not perform this substitution, so the path is 1.x-only in practice. See [`src/protocol/apply-patch.ts`](src/protocol/apply-patch.ts) for the upstream references.
 
@@ -401,7 +431,8 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | Visible `<shell_metadata>` timeout text | Rebuild and restart a local install. Cursor's shell timeout is carried on its exec request; the provider now removes OpenCode's internal timeout envelope before it is rendered or stored, then returns Cursor's typed timeout or background-handoff event instead of treating the text as successful stdout. |
 | `Unsupported Cursor exec variant …` | The error names the canonical Cursor CLI request field, its expected result field, and this provider's handling classification. `handling=unsupported` is a known Cursor-native capability without a safe OpenCode AI SDK bridge; `unknown request field` indicates new protocol drift; `handling=opencode-tool` or `provider-control` indicates a provider decoder/dispatch regression. Enable the debug log and report the full named error. |
 | Need wire-level logs | Set `CURSOR_PROVIDER_DEBUG=1` (optional `CURSOR_PROVIDER_DEBUG_FILE`; the default is `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) and reproduce the issue. |
-| Cache **write** tokens always show as `0` | Not a mapping bug in this provider. Cursor's `TurnEnded` protobuf includes `cache_write` (field 4) and this package forwards it as AI SDK `inputTokens.cacheWrite` / OpenCode `cache.write`. Real agent sessions send field 4 as `0` even when `cache_read` is large on later turns. With debug logging, confirm `turn_ended raw wire fields: … f4:wt0=0` and `v3CacheWrite=0 source=turn_ended`. Cache **read** counts from the same message do populate correctly. |
+| OpenCode compacts immediately after a tool-heavy task | Upgrade to a version containing the cumulative-usage fix. Cursor's final `TurnEnded` counters cover the entire held multi-step Run; older provider versions exposed that aggregate as the final request's context size, which made OpenCode compact far too early. Fixed versions keep the raw counters in `providerMetadata.cursor` and report a request-local context estimate instead. |
+| Cache **write** tokens always show as `0` | Cursor's `TurnEnded` protobuf includes `cache_write` (field 4), but captured Runs set it to `0` even when `cache_read` is large. Single-step Runs expose those counters directly. For multi-step Runs they remain in `providerMetadata.cursor` because Cursor reports only a cumulative whole-Run total, which cannot safely be used as one OpenCode request's context usage. With debug logging, confirm `turn_ended raw wire fields: … f4:wt0=0`. |
 
 ## Security
 
@@ -410,7 +441,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 ## Known limitations
 
 - **Personal use / ToS** — this provider speaks Cursor’s private agent protocol (CLI-shaped client identity). Use only with an account you own; Cursor may change or restrict the API without notice.
-- **`TurnEnded.cache_write` is unused by Cursor's agent** — usage comes from `interaction_update.turn_ended` (`input_tokens`, `output_tokens`, `cache_read`, `cache_write`, `reasoning_tokens`). The provider maps those 1:1 into AI SDK V3 nested usage. Captured live Runs consistently set `cache_write=0` on the wire while still reporting non-zero `cache_read` and `reasoning_tokens`; there is no alternate agent-stream field today that supplies write counts, so OpenCode/Kilo cannot show cache-write tokens for this provider until Cursor populates that counter.
+- **`TurnEnded` usage is whole-Run usage** — on a held multi-step Cursor Run, the final `interaction_update.turn_ended` counters aggregate every model invocation across tool boundaries. OpenCode usage is request-local and uses the latest assistant message to decide compaction, so publishing the aggregate there both double-counts earlier steps and causes premature compaction. The provider therefore uses a current-context estimate for multi-step AI SDK usage and preserves the exact cumulative counters in `providerMetadata.cursor`; single-step Runs still map the counters directly. Cursor also consistently sends `cache_write=0` in captured Runs, so no alternate write count is available.
 - **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. `env.workspace_paths` / `process_working_directory` stay on the real git workspace; Cursor's metadata root (`project_folder`, MCP `workspace_project_dir`, terminals/transcripts) is advertised under `<host-cache>/projects/<slug>/` (default `~/.cache/opencode/projects/…`) so dumps like `agent-tools/` do not land in the repo. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
 - **Configured MCP tools keep their upstream server id** — OpenCode builtins and plugin/custom tools are advertised under a synthetic `opencode` MCP server. Tools whose flattened name matches an MCP server in merged `opencode.json` configuration (`github_create_pull_request`, …) are grouped into that server's `mcp_descriptors` / `provider_identifier` (`github`, …). Unknown underscore-containing names stay under `opencode` rather than being guessed incorrectly. Cursor's MCP-state exec probe is answered from the same advertised descriptors before the actual tool request, using the full canonical tool-definition identity required by native `get_mcp_tools`; exec still reconstructs the full OpenCode tool id.
 - **Display completions are notifications, not execution requests** — Cursor `tool_call_*` frames use a typed `ToolCall` oneof. The provider decodes them for diagnostics but only mirrors finalized todo/plan state (`update_todos_tool_call` / `create_plan_tool_call`) into advertised OpenCode `todowrite`; the completed payload already contains the authoritative final list. Interactive, data-returning, and side-effecting completions are never replayed as new tools because their result could not be returned to Cursor. Exec-backed native subagent/Task and Pi read/bash/edit/write/grep/find/ls calls use their typed request/result fields instead. Unknown display variants are logged. All 37 Cursor CLI exec request/result pairs are inventoried by field and name; known-but-unsupported and future unknown exec variants fail explicitly rather than receiving a guessed response that could deadlock the Run.
@@ -426,4 +457,4 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 
 ## License
 
-MIT
+MIT

package/dist/context/paths.d.ts

@@ -26,15 +26,32 @@ type CompatDetector = () => CompatDetectResult;
  */
 export declare function setHostCacheDirOverride(dir: string | undefined): void;
 export declare function getHostCacheDirOverride(): string | undefined;
+declare const HOST_CACHE_DIRS: readonly ["mimocode", "kilo", "opencode"];
+export type HostCacheDir = (typeof HOST_CACHE_DIRS)[number];
+/**
+ * Host cache-dir name inferred from the running binary (`argv[0]` /
+ * `process.execPath`). A source-checkout provider can't be located by install
+ * path, but the binary that loaded it is authoritative: when this process IS
+ * `mimo` / `kilocode`, the cache root is that host's, not OpenCode's. Mirrors
+ * OCP `detect()` binaryHint semantics and tolerates the leading-dot Kilo binary
+ * (`.kilo`). Only `argv[0]` is inspected — later argv entries are arguments,
+ * not binary identity, and could otherwise cause false positives (e.g. an
+ * `--opencode-config=…` flag under a fork).
+ */
+export declare function hostCacheDirFromProcess(argv?: readonly string[], execPath?: string): HostCacheDir | undefined;
 /**
  * Resolve the host cache directory without an override.
  *
  * Explicit host environment wins. Otherwise, an installed provider inherits
- * the host-named cache containing its module. A source checkout or otherwise
- * unidentifiable install defaults to OpenCode. Merely having another host's
- * config directory installed is not evidence that it owns this process.
+ * the host-named cache containing its module; a source checkout is attributed
+ * by the running binary identity (see {@link hostCacheDirFromProcess}). Merely
+ * having another host's config directory installed is not evidence that it
+ * owns this process.
  */
-export declare function resolveHostCacheDir(env?: HostPathEnv, moduleUrl?: string): string;
+export declare function resolveHostCacheDir(env?: HostPathEnv, moduleUrl?: string, processIdentity?: {
+    argv?: readonly string[];
+    execPath?: string;
+}): string;
 /**
  * Best-effort: if `@opencode-compat/profile` is installed, adopt `detect().profile.paths.cacheDir`
  * when the host is supported. No-op when OCP is absent or detection fails.

package/dist/context/paths.js

@@ -48,15 +48,52 @@ export function setHostCacheDirOverride(dir) {
 export function getHostCacheDirOverride() {
     return hostCacheDirOverride;
 }
+const HOST_CACHE_DIRS = ["mimocode", "kilo", "opencode"];
+/**
+ * Host cache-dir name inferred from the running binary (`argv[0]` /
+ * `process.execPath`). A source-checkout provider can't be located by install
+ * path, but the binary that loaded it is authoritative: when this process IS
+ * `mimo` / `kilocode`, the cache root is that host's, not OpenCode's. Mirrors
+ * OCP `detect()` binaryHint semantics and tolerates the leading-dot Kilo binary
+ * (`.kilo`). Only `argv[0]` is inspected — later argv entries are arguments,
+ * not binary identity, and could otherwise cause false positives (e.g. an
+ * `--opencode-config=…` flag under a fork).
+ */
+export function hostCacheDirFromProcess(argv = process.argv, execPath = process.execPath) {
+    for (const raw of [argv[0], execPath]) {
+        if (!raw)
+            continue;
+        const name = path.basename(String(raw)).toLowerCase().replace(/^\.+/, "");
+        if (name === "mimo" ||
+            name === "mimocode" ||
+            name.startsWith("mimo-") ||
+            name.includes("mimocode")) {
+            return "mimocode";
+        }
+        if (name === "kilo" ||
+            name === "kilocode" ||
+            name.startsWith("kilo-") ||
+            name.includes("kilocode")) {
+            return "kilo";
+        }
+        if (name === "opencode" ||
+            name.startsWith("opencode-") ||
+            name.includes("opencode")) {
+            return "opencode";
+        }
+    }
+    return undefined;
+}
 /**
  * Resolve the host cache directory without an override.
  *
  * Explicit host environment wins. Otherwise, an installed provider inherits
- * the host-named cache containing its module. A source checkout or otherwise
- * unidentifiable install defaults to OpenCode. Merely having another host's
- * config directory installed is not evidence that it owns this process.
+ * the host-named cache containing its module; a source checkout is attributed
+ * by the running binary identity (see {@link hostCacheDirFromProcess}). Merely
+ * having another host's config directory installed is not evidence that it
+ * owns this process.
  */
-export function resolveHostCacheDir(env = process.env, moduleUrl = import.meta.url) {
+export function resolveHostCacheDir(env = process.env, moduleUrl = import.meta.url, processIdentity = {}) {
     const mimoHome = env.MIMOCODE_HOME;
     if (mimoHome && mimoHome.length > 0) {
         return path.join(mimoHome, "cache");
@@ -74,12 +111,17 @@ export function resolveHostCacheDir(env = process.env, moduleUrl = import.meta.u
         modulePath = undefined;
     }
     if (modulePath) {
-        for (const host of ["mimocode", "kilo", "opencode"]) {
+        for (const host of HOST_CACHE_DIRS) {
             const root = path.resolve(cacheHome, host);
             if (modulePath === root || modulePath.startsWith(`${root}${path.sep}`))
                 return root;
         }
     }
+    // Source checkout: the module path can't name the host, but the binary that
+    // loaded us can (running as `mimo` / `kilocode` / `opencode`).
+    const host = hostCacheDirFromProcess(processIdentity.argv ?? process.argv, processIdentity.execPath ?? process.execPath);
+    if (host)
+        return path.join(cacheHome, host);
     return path.join(cacheHome, "opencode");
 }
 /**

package/dist/image-input.d.ts

@@ -0,0 +1,31 @@
+export declare const MAX_CURSOR_IMAGE_INPUT_BYTES: number;
+export type CursorImageInput = {
+    data: Uint8Array;
+    filename: string;
+    mimeType: string;
+};
+export type CursorHistoryImageExtraction = {
+    images: CursorImageInput[];
+    hashes: string[];
+    candidateCount: number;
+    duplicateCount: number;
+};
+export type CursorPromptImageExtraction = CursorHistoryImageExtraction & {
+    userImageCount: number;
+};
+export declare function hasCursorUserImages(lastUser: Record<string, unknown> | undefined): boolean;
+export declare function assertCursorUserImageSupport(lastUser: Record<string, unknown> | undefined, supportsImages: boolean, modelId: string): void;
+export declare function extractCursorUserImages(lastUser: Record<string, unknown> | undefined, signal?: AbortSignal, maxBytes?: number): Promise<CursorImageInput[]>;
+export declare function extractCursorHistoryImages(prompt: readonly unknown[], options: {
+    supportsImages: boolean;
+    seenHashes?: ReadonlySet<string>;
+    signal?: AbortSignal;
+    maxBytes?: number;
+    filenameOffset?: number;
+}): Promise<CursorHistoryImageExtraction>;
+export declare function extractCursorPromptImages(prompt: readonly unknown[], lastUser: Record<string, unknown> | undefined, options: {
+    supportsImages: boolean;
+    seenHistoryHashes?: ReadonlySet<string>;
+    signal?: AbortSignal;
+    maxBytes?: number;
+}): Promise<CursorPromptImageExtraction>;

package/dist/image-input.js

@@ -0,0 +1,281 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+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;
+export function hasCursorUserImages(lastUser) {
+    return !!lastUser && Array.isArray(lastUser.content) && lastUser.content.some((part) => {
+        if (!part || typeof part !== "object")
+            return false;
+        const file = part;
+        return file.type === "file" && typeof file.mediaType === "string" && file.mediaType.startsWith("image/");
+    });
+}
+function unsupported(functionality, message) {
+    throw new UnsupportedFunctionalityError({ functionality, message });
+}
+export function assertCursorUserImageSupport(lastUser, supportsImages, modelId) {
+    if (!hasCursorUserImages(lastUser) || supportsImages)
+        return;
+    unsupported("image input", `Cursor model ${JSON.stringify(modelId)} does not support image input`);
+}
+function decodeBase64(value) {
+    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 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) {
+    if (!value.startsWith("data:")) {
+        return unsupported("image input", "Cursor provider supports base64-encoded image data URLs only");
+    }
+    const commaIndex = value.indexOf(",", 5);
+    if (commaIndex < 0) {
+        return unsupported("image input", "Cursor provider supports base64-encoded image data URLs only");
+    }
+    const metadata = value.slice(5, commaIndex);
+    const finalSeparator = metadata.lastIndexOf(";");
+    if (finalSeparator < 0 || metadata.slice(finalSeparator + 1) !== "base64") {
+        return unsupported("image input", "Cursor provider supports base64-encoded image data URLs only");
+    }
+    const firstSeparator = metadata.indexOf(";");
+    const mimeType = metadata.slice(0, firstSeparator);
+    return {
+        data: decodeBase64(value.slice(commaIndex + 1)),
+        mimeType: mimeType || undefined,
+    };
+}
+function inferImageMimeType(data) {
+    if (data.length >= 8 &&
+        data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47 &&
+        data[4] === 0x0d && data[5] === 0x0a && data[6] === 0x1a && data[7] === 0x0a)
+        return "image/png";
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (data.length >= 6) {
+        const header = Buffer.from(data.subarray(0, 6)).toString("ascii");
+        if (header === "GIF87a" || header === "GIF89a")
+            return "image/gif";
+    }
+    if (data.length >= 12 &&
+        Buffer.from(data.subarray(0, 4)).toString("ascii") === "RIFF" &&
+        Buffer.from(data.subarray(8, 12)).toString("ascii") === "WEBP")
+        return "image/webp";
+    return undefined;
+}
+function assertImageSize(size, remaining) {
+    if (size > remaining) {
+        unsupported("image input", `Cursor provider image attachments exceed the ${MAX_CURSOR_IMAGE_INPUT_BYTES / 1024 / 1024} MiB limit`);
+    }
+}
+function cursorImageBudget(value) {
+    if (!Number.isFinite(value))
+        return MAX_CURSOR_IMAGE_INPUT_BYTES;
+    return Math.min(MAX_CURSOR_IMAGE_INPUT_BYTES, Math.max(0, Math.floor(value)));
+}
+function imageContentHash(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+async function readResponseBytes(response, remaining) {
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > remaining) {
+        assertImageSize(declaredLength, remaining);
+    }
+    if (!response.body) {
+        const data = new Uint8Array(await response.arrayBuffer());
+        assertImageSize(data.length, remaining);
+        return data;
+    }
+    const chunks = [];
+    let total = 0;
+    const reader = response.body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.length;
+            if (total > remaining) {
+                await reader.cancel();
+                assertImageSize(total, remaining);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const data = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        data.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return data;
+}
+async function resolveImageData(value, remaining, signal) {
+    if (value instanceof Uint8Array)
+        return { data: Uint8Array.from(value) };
+    if (typeof value === "string") {
+        return value.startsWith("data:") ? decodeDataUrl(value) : { data: decodeBase64(value) };
+    }
+    if (value.protocol === "data:")
+        return decodeDataUrl(value.href);
+    if (value.protocol === "file:") {
+        const filePath = fileURLToPath(value);
+        const info = await stat(filePath);
+        assertImageSize(info.size, remaining);
+        return { data: Uint8Array.from(await readFile(filePath)), filename: path.basename(filePath) };
+    }
+    if (value.protocol !== "http:" && value.protocol !== "https:") {
+        return unsupported("image URL input", `Cursor provider does not support image URL protocol ${JSON.stringify(value.protocol)}`);
+    }
+    const response = await fetch(value, { signal });
+    if (!response.ok) {
+        return unsupported("image URL input", `Cursor provider could not fetch image URL (HTTP ${response.status})`);
+    }
+    return {
+        data: await readResponseBytes(response, remaining),
+        mimeType: response.headers.get("content-type")?.split(";", 1)[0]?.trim() || undefined,
+        filename: path.basename(value.pathname) || undefined,
+    };
+}
+async function decodeCursorImagePart(file, remaining, signal, defaultFilename, resolveLimit = remaining) {
+    if (typeof file.mediaType !== "string" || !file.mediaType.startsWith("image/")) {
+        return unsupported("file input", `Cursor provider supports image attachments only, not ${JSON.stringify(file.mediaType)}`);
+    }
+    if (!(file.data instanceof Uint8Array) && typeof file.data !== "string" && !(file.data instanceof URL)) {
+        return unsupported("image input", "Cursor provider received an invalid image data value");
+    }
+    const resolved = await resolveImageData(file.data, resolveLimit, signal);
+    assertImageSize(resolved.data.length, remaining);
+    const declaredMimeType = file.mediaType;
+    const mimeType = declaredMimeType === "image/*"
+        ? (resolved.mimeType?.startsWith("image/") ? resolved.mimeType : inferImageMimeType(resolved.data))
+        : declaredMimeType;
+    if (!mimeType?.startsWith("image/") || mimeType === "image/*") {
+        return unsupported("image input", "Cursor provider could not determine the image media type");
+    }
+    return {
+        data: resolved.data,
+        filename: (typeof file.filename === "string" && file.filename ? path.basename(file.filename) : undefined) ??
+            resolved.filename ??
+            defaultFilename,
+        mimeType,
+    };
+}
+export async function extractCursorUserImages(lastUser, signal, maxBytes = MAX_CURSOR_IMAGE_INPUT_BYTES) {
+    if (!lastUser || !Array.isArray(lastUser.content))
+        return [];
+    const byteBudget = cursorImageBudget(maxBytes);
+    const images = [];
+    let totalBytes = 0;
+    for (const part of lastUser.content) {
+        if (!part || typeof part !== "object")
+            continue;
+        const file = part;
+        if (file.type !== "file")
+            continue;
+        const image = await decodeCursorImagePart(file, byteBudget - totalBytes, signal, `image-${images.length + 1}`);
+        totalBytes += image.data.length;
+        images.push(image);
+    }
+    return images;
+}
+function cursorHistoryImageParts(prompt) {
+    const parts = [];
+    for (const message of prompt) {
+        if (!message || typeof message !== "object")
+            continue;
+        const record = message;
+        if (!Array.isArray(record.content))
+            continue;
+        if (record.role === "assistant") {
+            for (const part of record.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);
+            }
+            continue;
+        }
+        if (record.role !== "tool")
+            continue;
+        for (const part of record.content) {
+            if (!part || typeof part !== "object")
+                continue;
+            const toolResult = part;
+            if (toolResult.type !== "tool-result" || !toolResult.output || typeof toolResult.output !== "object") {
+                continue;
+            }
+            const output = toolResult.output;
+            if (output.type !== "content" || !Array.isArray(output.value))
+                continue;
+            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);
+            }
+        }
+    }
+    return parts;
+}
+export async function extractCursorHistoryImages(prompt, options) {
+    const candidates = cursorHistoryImageParts(prompt);
+    if (!options.supportsImages) {
+        return { images: [], hashes: [], candidateCount: candidates.length, duplicateCount: 0 };
+    }
+    const maxBytes = cursorImageBudget(options.maxBytes ?? MAX_CURSOR_IMAGE_INPUT_BYTES);
+    const images = [];
+    const hashes = [];
+    const hashesThisTurn = new Set();
+    let duplicateCount = 0;
+    let totalBytes = 0;
+    for (const file 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);
+        const hash = imageContentHash(image.data);
+        if (options.seenHashes?.has(hash) || hashesThisTurn.has(hash)) {
+            duplicateCount++;
+            continue;
+        }
+        assertImageSize(image.data.length, maxBytes - totalBytes);
+        totalBytes += image.data.length;
+        images.push(image);
+        hashes.push(hash);
+        hashesThisTurn.add(hash);
+    }
+    return { images, hashes, candidateCount: candidates.length, duplicateCount };
+}
+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 userBytes = userImages.reduce((total, image) => total + image.data.length, 0);
+    const history = await extractCursorHistoryImages(prompt, {
+        supportsImages: options.supportsImages,
+        seenHashes: options.seenHistoryHashes,
+        signal: options.signal,
+        maxBytes: maxBytes - userBytes,
+        filenameOffset: userImages.length,
+    });
+    return {
+        ...history,
+        images: [...userImages, ...history.images],
+        userImageCount: userImages.length,
+    };
+}

package/dist/language-model.d.ts

@@ -85,7 +85,7 @@ export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[
 export declare function estimateTokens(chars: number): number;
 /** Estimate current-request prompt tokens from the complete serialized V3 prompt. */
 export declare function estimatePromptTokens(prompt: LanguageModelV3CallOptions["prompt"]): number;
-/** Preserve cumulative Cursor counters as diagnostics, never as AI SDK request usage. */
+/** Preserve exact Cursor counters as diagnostics when they are cumulative across a multi-step Run. */
 export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>): {
     cursor: {
         usageVersion: number;