cursor-opencode-provider 0.4.3 → 0.5.0

package/README.md

@@ -243,7 +243,7 @@ Choose the **cursor** provider, then one of:
 | **Cursor account (browser login)** | PKCE OAuth — opens cursor.com to sign in |
 | **API key** | Paste a key from [cursor.com/settings](https://cursor.com/settings) (`crsr_...`) |
 
-After login, the plugin fetches your available models and writes them to `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails.
+After login, the plugin fetches your available models and writes them to `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails. Completed conversation state is stored separately under `<host-cache>/cursor-conversations/`, with one independently replaced gzip-compressed protobuf snapshot per stable OpenCode session. Snapshots are refreshed at each successful Cursor `TurnEnded` and restored after provider restarts; records not updated for more than 24 hours are removed when the provider starts. Cursor's checkpoint is an index of content-addressed KV blobs rather than a self-contained transcript, so the snapshot retains the blobs reachable from the latest checkpoint and discards superseded blobs. This private Cursor state is not a copy of OpenCode's session database.
 
 ### Paths (host cache)
 
@@ -259,7 +259,7 @@ must not redirect a native OpenCode process into that host's cache.
 
 | Kind | Default (OpenCode) | Notes |
 |------|--------------------|-------|
-| Model / version **cache** | `~/.cache/opencode/` | MiMo: `$MIMOCODE_HOME/cache` or `~/.cache/mimocode/`; Kilo: `~/.cache/kilo/` |
+| Model, version, and 24-hour conversation **cache** | `~/.cache/opencode/` | MiMo: `$MIMOCODE_HOME/cache` or `~/.cache/mimocode/`; Kilo: `~/.cache/kilo/` |
 | Cursor **project metadata** (`agent-tools`, terminals, …) | `~/.cache/opencode/projects/<slug>/` | under `<host-cache>/projects/` |
 | OpenCode **auth** (`auth.json`) | `~/.local/share/opencode/` | `$XDG_DATA_HOME/opencode/` when set |
 | OpenCode **config** (AGENTS, skills, …) | `~/.config/opencode/` | still OpenCode-named for rule discovery |
@@ -397,6 +397,7 @@ OpenCode
 | `src/debug.ts` | Opt-in wire-level debug logging (`CURSOR_PROVIDER_DEBUG`) |
 | `src/auth.ts` | PKCE OAuth, API key exchange, JWT refresh |
 | `src/models.ts` | `AvailableModels` fetch and `cursor-models.json` cache |
+| `src/protocol/conversation-persistence.ts` | Atomic per-session restart snapshots under the 24-hour `cursor-conversations/` cache |
 | `src/context/paths.ts` | Host cache root + Cursor project metadata under `<host-cache>/projects/<slug>/` |
 | `src/agent-url.ts` | `GetServerConfig` fetch + in-process memo (region-specific Run host) |
 | `src/transport/connect.ts` | HTTP/2 bidi stream and unary RPC calls |
@@ -410,9 +411,11 @@ If this guidance causes issues, update `buildOpenCodeInteractionGuidance` in [`s
 
 ### 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.
+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. For regular files inside the workspace, the provider answers that private prerequisite read directly with the complete file (up to Cursor's own 50 MB edit limit), because routing it through OpenCode's ordinary 50 KB-capped `read` tool makes Cursor calculate a truncated replacement. This shortcut is restricted to the exact path named by the active edit call and rejects symlink escapes. External paths first take OpenCode's permission-aware read path; after that exact read succeeds, the provider upgrades its private result to complete content so an explicitly authorized external edit does not inherit OpenCode's preview cap.
 
-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.
+The provider retains the correlation and exposes the resulting 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.
+
+Ordinary complete native reads also preserve an existing final LF/CRLF. OpenCode's numbered read envelope cannot represent that terminator, and dropping it made exact edit matching fail. 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)
 
@@ -459,9 +462,10 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | No response / silent 200 + close | HTTP 200 alone is not a successful agent turn: the provider now requires Cursor's explicit `turn_ended`, captures HTTP/2 trailers/GOAWAY, and recovers once from bare EOF. The Run host still comes from in-memory `GetServerConfig` resolution; set `CURSOR_PROVIDER_DEBUG=1` to confirm the host and termination reason. |
 | 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. |
-| 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. An over-budget guard also catches single-step or parallel Runs whose counters are cumulative even without a visible tool boundary. |
-| 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`. |
+| 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. Every completed turn emits a `turn usage validation: status=ok|mismatch` line confirming token-accounting integrity and a `cache diagnosis:` line showing warm/cold checkpoint continuity, raw read/write/uncached tokens, cache-read coverage of the prior context, context/category deltas, stable RequestContext hashes, and Run step/tool counts. Checkpoint lines include Cursor's current category totals. Cursor does not expose per-model-call cache splits, so the diagnostic labels that value unavailable instead of inferring it from aggregate `TurnEnded` counters. |
+| OpenCode token totals grow once per tool call | Upgrade to a version containing the held-Run usage fix. OpenCode sums every AI SDK step, so the provider emits zero usage at intermediate tool boundaries and emits Cursor's final checkpoint total exactly once when the held Run closes. If the current Run has no token snapshot, the prior checkpoint total remains visible as stale; with no known snapshot, standard usage stays zero instead of mislabeling `TurnEnded` as context. Raw request counters remain in `providerMetadata.cursor`. |
+| Context percentage jumps after a long tool turn or compaction | Cursor reports its authoritative context snapshot in checkpoint `token_details`. The provider makes the final AI SDK input + output equal `usedTokens`, proportionally partitions input into cached/uncached subsets, and exposes `maxTokens`, percentage, and category breakdown under `providerMetadata.cursor.context`. Intermediate held-Run tool boundaries remain zero, and compaction naturally replaces the prior snapshot with Cursor's smaller total. |
+| 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. The provider forwards the request-local value when Cursor supplies one; it cannot infer a missing write count. With debug logging, confirm `turn_ended raw wire fields: … f4:wt0=0`. |
 
 ## Security
 
@@ -470,8 +474,8 @@ 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` 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 map the counters directly only when they are close to the request-local estimate, while an over-budget guard handles cumulative no-boundary Runs. 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.
+- **Cursor's checkpoint controls displayed totals** — live continuation captures show `TurnEnded` counters can decrease between turns and can represent aggregate model work rather than final context occupancy. When a checkpoint contains `ConversationStateStructure.token_details`, the provider makes AI SDK input + output equal Cursor's `used_tokens`; output/reasoning remain based on `TurnEnded`, while uncached/cache-read/cache-write input are proportionally normalized to the remaining context input. OpenCode can therefore display and compact against Cursor's total without double counting cache. A Run without fresh token details retains the previous checkpoint snapshot and marks `providerMetadata.cursor.context` as `source: "checkpoint-previous-turn", stale: true`. If no checkpoint has ever supplied token details, standard usage is zero and context metadata is absent, so `TurnEnded` is never misrepresented as occupancy; its exact values remain under `providerMetadata.cursor.*Raw`. The full known snapshot includes `usedTokens`, `maxTokens`, percentage, category breakdown, source, and staleness. Intermediate tool-call boundaries report zero so a held Run is recorded only once. Cursor 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). Expensive workspace state (rules, environment, repository, git, and layout) is frozen per Cursor conversation and persisted for restart recovery. Tools/MCP descriptors, skills, subagents, and plugin metadata are rediscovered and overlaid each Run; unchanged overlays reuse byte-identical encoded context, while enabling/disabling a capability becomes visible on the next turn. Concurrent first Runs share one base build, and compaction/reset clears it. 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.
 - **Tool availability is per OpenCode agent** — Cursor can request native capabilities such as Task even when a child or restricted OpenCode agent did not advertise the corresponding host tool. The provider prompts Cursor with the exact current catalog and checks every decoded host-tool exec request against it. An unavailable request is answered on Cursor's correlated typed result channel and is never emitted as OpenCode's `invalid` tool.
@@ -479,10 +483,11 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **MCP resource tools (`list_mcp_resources` / `read_mcp_resource`) also use collision-safe aliases, and Cursor's native resource exec is always answered** — OpenCode's resource tools (advertised only when a connected MCP server declares `capabilities.resources`) share bare names with two of Cursor's own native tool-call variants. Left unaliased, Cursor's client can route a call onto its native exec channel instead of the ordinary MCP tool path, which this provider does not translate — confirmed live: reading a resource was dispatched natively and killed the Run before this fix. The provider now aliases both names to `custom_list_mcp_resources` / `custom_read_mcp_resource` (same mechanism as web search/fetch) so normal calls execute through OpenCode's tools, and separately answers Cursor's native resource-exec fields directly on the protocol floor — an empty list, or a "server not found" error for read — so an unsolicited native request from Cursor can never fail the Run. Downloads (`download_path`) have no OpenCode equivalent and are always refused; binary resource content is subject to the same [50 KB / attachment-type limits](#known-limitations) as other tool results.
 - **Background shells are non-interactive** — Cursor's native background-shell spawn and soft-background shell-stream timeouts are bridged through OpenCode's foreground-only `bash` tool. With bash/zsh, the classic plugin keeps the original permission/UI command and executes the wrapper through `shell.env` (`BASH_ENV` / `ZDOTDIR`); OpenCode's non-interactive sh/dash argv ignores those startup variables, so the plugin uses a short `exec /bin/sh '<wrapper-file>'` command backed by the same private wrapper. Native background-spawn requests also carry a self-contained marker-producing fallback when the classic hooks are absent. Spawn/soft-bg wrappers detach with `nohup`, redirect output under `${TMPDIR:-/tmp}/cursor-opencode-{bg,shell}.*`, and return the real PID (or typed timeout/exit) to Cursor. Private markers and OpenCode's `<shell_metadata>` envelope are stripped before storage/render, with a short still-running / started / timed-out status line left for the bash bubble. Requests that require `write_shell_stdin` are rejected explicitly because OpenCode does not expose an interactive background-process lifecycle through its AI SDK tool interface. The POSIX wrap path is not implemented for native Windows PowerShell/`cmd`.
 - **Cursor-native interaction queries remain headless** — Cursor UI/approval *queries* (as distinct from display tool calls) still cannot be surfaced through the AI SDK provider interface. The normal system prompt redirects questions, planning, plan-mode transitions, and available web capabilities to executable host tools (`question`, `todowrite`, `plan_enter` / `plan_exit`, `custom_websearch`, `custom_webfetch`); native web/PR/MCP/image/SCM requests are declined so they remain behind host tool permissions. Separately from display `create_plan_tool_call` → `todowrite` mirroring, interaction `create_plan_request_query` is auto-acked (CLI headless parity) with success and an empty `plan_uri`, so Cursor may treat the plan as accepted without an OpenCode UI confirm. Compaction prompts are unchanged. Unknown future interaction variants fail the turn explicitly instead of hanging the Run stream.
-- **Compaction resets Cursor conversation state** — the classic plugin marks OpenCode's `compaction` agent explicitly. On those turns the provider mints an isolated Cursor `conversation_id`, drops the prior checkpoint + KV blobs, preserves real tool outputs as OpenCode-host observations in the seed history, and re-advertises the session's last tool catalog while refusing execution during the summary itself. The first normal turn then rebases once more onto a fresh conversation seeded with OpenCode's compacted prompt and normal system instructions, so the summary-agent checkpoint cannot suppress later tool calls. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state.
-- **Conversation bindings and compaction catalogs are bounded** — process-global per-session bindings, prior tool catalogs, and pending post-compaction rebases use a 256-session LRU bound. Evicting a conversation binding also drops its checkpoint and KV blobs.
+- **Compaction resets Cursor conversation state without resetting stable workspace context** — the classic plugin marks OpenCode's `compaction` agent explicitly. On those turns the provider mints an isolated Cursor `conversation_id`, drops the prior checkpoint + KV blobs, preserves real tool outputs as OpenCode-host observations in the seed history, and re-advertises the session's last tool catalog while refusing execution during the summary itself. The first normal turn then rebases once more onto a fresh conversation seeded with OpenCode's compacted prompt and normal system instructions, so the summary-agent checkpoint cannot suppress later tool calls. Across both id rotations, the frozen workspace/rules/environment base and its prior encoded-context comparison seed are transferred instead of rebuilt; tools, skills, agents, plugins, and MCP state are still rediscovered, and the complete context is reused only when its bytes remain identical. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state. Debug logs include system-prompt and encoded RequestContext hashes for cache-prefix verification.
+- **Conversation bindings survive provider restarts** — after each successful `TurnEnded`, the OpenCode-session binding, latest checkpoint, checkpoint-reachable KV blob graph, frozen request-context base, last real tool catalog, and pending post-compaction rebase marker are atomically replaced in that session's private `<host-cache>/cursor-conversations/*.pb.gz` snapshot. The protobuf stores checkpoints, blob ids/data, and request context as bytes without JSON/base64 expansion, then gzip compresses the complete record. A checkpoint alone is insufficient: Cursor requests its referenced hashes through `get_blob` when the next Run starts. Reachability follows Cursor CLI's export traversal (turns, messages, steps, images, summaries, todos, prompts, and nested subagents), pruning superseded blobs; decode failure or a missing referenced hash conservatively retains the complete blob set. The stable OpenCode session id selects the file; Cursor conversation ids may rotate during compaction and remain inside the snapshot. Independent files prevent concurrent OpenCode processes from losing unrelated sessions by replacing a shared aggregate cache. Startup restores records updated within 24 hours and safely flushes older ones without deleting a concurrently published fresh replacement. Experimental legacy JSON snapshots are discarded rather than migrated. Debug logs report hydration as `restored`, `missing`, `invalid`, or `expired`, plus the compressed and protobuf snapshot sizes. The restored catalog is a fallback only for lifecycle turns such as compaction; an ordinary restricted/no-tool turn never resurrects it. Process-global bindings and compaction catalogs still use a 256-session LRU bound; memory eviction drops the live checkpoint, blobs, and frozen context, which can be rehydrated from the restart cache on later use.
+- **Oversized checkpoint graphs rebase instead of flooding the Run stream** — before reusing a checkpoint, the provider measures its reachable KV graph. State above 100 MiB, or an incomplete graph with a missing/undecodable reference, rotates to a fresh Cursor conversation seeded from OpenCode's authoritative history. KV, request-context, MCP-state, interaction, and heartbeat writes are ordered per Run and await HTTP/2 drain, so a large blob reply cannot create an unbounded queue later misreported as heartbeat backpressure. Debug logs distinguish checkpoint-envelope bytes, reachable blob bytes, seed size, and encoded Run-request estimate; raw blob bytes are never presented as tokens.
 - **Interrupted Runs resume from checkpoints** — a remote EOF, Connect end-stream, or trailer error is never emitted as a successful `stop`. When the failed Run produced an eligible checkpoint, the provider opens a new RPC for the same conversation and sends that state with `ResumeAction`, so completed text and tool work are not replayed. Before any stateful output, an interruption without a checkpoint can still rebase from OpenCode history. Stateful interruptions without a checkpoint are surfaced because replay would be ambiguous; retry exhaustion remains explicit. A transport closure after `turn_ended` is treated as successful completion.
-- **Large reads are capped at 50 KB by OpenCode, and the cap is reported** — OpenCode's `read` tool stops at `MAX_BYTES = 50 * 1024`, cutting on a whole-line boundary, and appends `(Output capped at 50 KB. Showing lines X-Y. Use offset=N to continue.)`. The provider strips that envelope before returning content to Cursor so the model cannot echo wrappers into a later write, but it re-states the cap: a capped native read appends a `[Partial read: …]` marker after the content, a capped MCP read gets a separate notice content item, and a Pi read carries structured `PiReadExecSuccess.truncation`. The structured `truncated` flag alone is not enough — verified against live `gpt-5.4-mini` and `grok-4.5` sessions, both of which asserted "highly confident" that partial content was the whole file until the textual marker was added. Deliberately paged reads (explicit `offset`/`limit`) are not marked. Without that signal the model treats a capped read as the whole file and rewrites it truncated, discarding everything past the cap. The cap is hardcoded in OpenCode's read tool — it is not the configurable `tool_output.max_bytes`, which governs `Truncate.Service` and not read's line accumulation — so the only lever is paging with `offset`. Prefer `edit` over whole-file `write` on files above 50 KB.
+- **Large reads are capped at 50 KB by OpenCode, and the cap is reported** — OpenCode's `read` tool stops at `MAX_BYTES = 50 * 1024`, cutting on a whole-line boundary, and appends `(Output capped at 50 KB. Showing lines X-Y. Use offset=N to continue.)`. The provider strips that envelope before returning content to Cursor so the model cannot echo wrappers into a later write, but it re-states the cap: a capped native read appends a `[Partial read: …]` marker after the content, a capped MCP read gets a separate notice content item, and a Pi read carries structured `PiReadExecSuccess.truncation`. The structured `truncated` flag alone is not enough — verified against live `gpt-5.4-mini` and `grok-4.5` sessions, both of which asserted "highly confident" that partial content was the whole file until the textual marker was added. Deliberately paged reads (explicit `offset`/`limit`) are not marked. Whole-file writes and overwriting `Add File` patches that echo the marker are rejected before OpenCode executes them; targeted edits remain possible, including edits to source that quotes the warning text. Cursor's private legacy-edit read is handled separately as described above, so an edit can operate on a workspace file larger than 50 KB without turning the capped preview into a replacement. The cap is hardcoded in OpenCode's read tool — it is not the configurable `tool_output.max_bytes`, which governs `Truncate.Service` and not read's line accumulation — so ordinary model reads still require paging with `offset`.
 - **No fallback models** — if Cursor’s `AvailableModels` API is unreachable and there is no local cache, the provider exposes no models.
 
 ## License

package/dist/context/build.d.ts

@@ -4,9 +4,17 @@ export type BuildRequestContextInput = {
     tools?: OpencodeToolDef[];
     providerIdentifier?: string;
 };
+export declare const DYNAMIC_REQUEST_CONTEXT_KEYS: readonly ["tools", "agent_skills", "custom_subagents", "mcp_file_system_options", "mcp_meta_tool_options", "web_search_enabled", "web_fetch_enabled", "agent_skills_info_complete", "custom_subagents_info_complete", "mcp_file_system_info_complete", "mcp_info_complete", "hooks_additional_context"];
+export type DynamicRequestContextKey = typeof DYNAMIC_REQUEST_CONTEXT_KEYS[number];
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Sourced from OpenCode discovery (and .claude/.agents skill fallbacks).
  * Honors `instructions` globs the same way OpenCode does (including `.cursor/` if listed).
  */
 export declare function buildRequestContext(input: BuildRequestContextInput): Promise<Record<string, unknown>>;
+/** Rediscover only capability/plugin sections that may change during a chat. */
+export declare function buildDynamicRequestContext(input: BuildRequestContextInput): Promise<Record<string, unknown>>;
+/** Keep expensive workspace state frozen while replacing every live capability field. */
+export declare function materializeRequestContext(base: Record<string, unknown>, dynamic: Record<string, unknown>): Record<string, unknown>;
+/** Strip live capability fields before retaining/persisting a conversation base. */
+export declare function requestContextBase(context: Record<string, unknown>): Record<string, unknown>;

package/dist/context/build.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { extractHostSubagentCatalog, toolsToDescriptors, toolsToMcpDescriptors, } from "../protocol/tools.js";
-import { collectRules } from "./rules.js";
+import { collectRules, findGitWorktree, loadMergedConfig, } from "./rules.js";
 import { collectSkills } from "./skills.js";
 import { collectAgents } from "./agents.js";
 import { collectPlugins } from "./plugins.js";
@@ -9,6 +9,20 @@ import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
 import { ensureOpencodeProjectDir } from "./paths.js";
 import { traceRequestContextPaths } from "../debug.js";
+export const DYNAMIC_REQUEST_CONTEXT_KEYS = [
+    "tools",
+    "agent_skills",
+    "custom_subagents",
+    "mcp_file_system_options",
+    "mcp_meta_tool_options",
+    "web_search_enabled",
+    "web_fetch_enabled",
+    "agent_skills_info_complete",
+    "custom_subagents_info_complete",
+    "mcp_file_system_info_complete",
+    "mcp_info_complete",
+    "hooks_additional_context",
+];
 const DEFAULT_HOST_SUBAGENTS = [
     {
         name: "general",
@@ -50,15 +64,38 @@ function buildAdvertisedSubagentCatalog(hostSubagents, discoveredAgents) {
  */
 export async function buildRequestContext(input) {
     const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());
+    const { rules, config, worktree } = await collectRules(workspaceRoot);
+    const [dynamic, git, layout] = await Promise.all([
+        buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config),
+        collectGit(workspaceRoot),
+        collectProjectLayout(workspaceRoot),
+    ]);
+    const base = {
+        env: buildEnv(workspaceRoot),
+        rules: rules.map((r) => ({
+            full_path: r.fullPath,
+            content: r.content,
+        })),
+        repository_info: git.repositoryInfo,
+        git_repos: git.gitRepos,
+        project_layouts: [layout],
+        rules_info_complete: true,
+        env_info_complete: true,
+        repository_info_complete: true,
+        git_repo_info_complete: true,
+        git_status_info_complete: true,
+    };
+    const ctx = materializeRequestContext(base, dynamic);
+    traceRequestContextPaths("buildRequestContext", ctx);
+    return ctx;
+}
+async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config) {
     const providerIdentifier = input.providerIdentifier ?? "opencode";
     const tools = input.tools ?? [];
-    const { rules, config, worktree } = await collectRules(workspaceRoot);
-    const [skills, agents, plugins, git, layout] = await Promise.all([
+    const [skills, agents, plugins] = await Promise.all([
         collectSkills(workspaceRoot, worktree),
         collectAgents(workspaceRoot),
         collectPlugins(workspaceRoot, config),
-        collectGit(workspaceRoot),
-        collectProjectLayout(workspaceRoot),
     ]);
     const mcpServerNames = Object.keys(config.mcp ?? {});
     const flat = toolsToDescriptors(tools, providerIdentifier, mcpServerNames);
@@ -84,16 +121,8 @@ export async function buildRequestContext(input) {
                 `Delegate to the host-configured ${agent.name} subagent; its host instructions and tools apply.`,
         };
     });
-    const ctx = {
-        env: buildEnv(workspaceRoot),
+    const dynamic = {
         tools: flat,
-        rules: rules.map((r) => ({
-            full_path: r.fullPath,
-            content: r.content,
-        })),
-        repository_info: git.repositoryInfo,
-        git_repos: git.gitRepos,
-        project_layouts: [layout],
         agent_skills: skills.map((s) => ({
             full_path: s.fullPath,
             content: s.content,
@@ -116,22 +145,42 @@ export async function buildRequestContext(input) {
         // custom_web* aliases instead of routing through a query doomed to fail.
         web_search_enabled: false,
         web_fetch_enabled: false,
-        // Completeness: true only for sections we actually gathered.
-        rules_info_complete: true,
-        env_info_complete: true,
-        repository_info_complete: true,
-        git_repo_info_complete: true,
-        git_status_info_complete: true,
         agent_skills_info_complete: true,
         custom_subagents_info_complete: advertisedSubagents.complete,
         mcp_file_system_info_complete: true,
         mcp_info_complete: true,
     };
     if (plugins.length > 0) {
-        ctx.hooks_additional_context = plugins
+        dynamic.hooks_additional_context = plugins
             .map((p) => `opencode-plugin:${p.source}:${p.id}`)
             .join("\n");
     }
-    traceRequestContextPaths("buildRequestContext", ctx);
-    return ctx;
+    return dynamic;
+}
+/** Rediscover only capability/plugin sections that may change during a chat. */
+export async function buildDynamicRequestContext(input) {
+    const workspaceRoot = path.resolve(input.workspaceRoot || process.cwd());
+    const [worktree, config] = await Promise.all([
+        findGitWorktree(workspaceRoot),
+        loadMergedConfig(workspaceRoot),
+    ]);
+    return buildDynamicRequestContextFromDiscovery(input, workspaceRoot, worktree, config);
+}
+/** Keep expensive workspace state frozen while replacing every live capability field. */
+export function materializeRequestContext(base, dynamic) {
+    const context = structuredClone(base);
+    for (const key of DYNAMIC_REQUEST_CONTEXT_KEYS)
+        delete context[key];
+    for (const key of DYNAMIC_REQUEST_CONTEXT_KEYS) {
+        if (Object.hasOwn(dynamic, key))
+            context[key] = structuredClone(dynamic[key]);
+    }
+    return context;
+}
+/** Strip live capability fields before retaining/persisting a conversation base. */
+export function requestContextBase(context) {
+    const base = structuredClone(context);
+    for (const key of DYNAMIC_REQUEST_CONTEXT_KEYS)
+        delete base[key];
+    return base;
 }

package/dist/context/frozen.d.ts

@@ -0,0 +1,29 @@
+import { type BuildRequestContextInput } from "./build.js";
+export declare const MAX_FROZEN_REQUEST_CONTEXTS = 256;
+/** Frozen stable RequestContext base for this conversation, if any. */
+export declare function getFrozenRequestContext(conversationId: string): Record<string, unknown> | undefined;
+/** Replace the frozen stable base, stripping any live capability fields. */
+export declare function setFrozenRequestContext(conversationId: string, context: Record<string, unknown>): void;
+/** Drop a conversation's frozen RequestContext (compaction / binding reset). */
+export declare function clearFrozenRequestContext(conversationId: string): void;
+/**
+ * Move a stable workspace base across a conversation-id reset.
+ *
+ * Compaction changes Cursor's state/checkpoint identity, not the OpenCode
+ * workspace. Preserve the expensive base and the prior materialized bytes as a
+ * comparison seed; getOrBuildRequestContext still rediscovers live capability
+ * overlays and only reuses the complete context when those bytes also match.
+ */
+export declare function transferFrozenRequestContext(previousConversationId: string, nextConversationId: string): boolean;
+/** Test helper — wipe all frozen contexts. */
+export declare function resetFrozenRequestContextsForTests(): void;
+/**
+ * Return a stable-base + live-overlay RequestContext for `conversationId`.
+ * The base is built once; capability sections are rediscovered every Run.
+ */
+export declare function getOrBuildRequestContext(conversationId: string, input: BuildRequestContextInput, opts?: {
+    refresh?: boolean;
+}): Promise<{
+    context: Record<string, unknown>;
+    reused: boolean;
+}>;

package/dist/context/frozen.js

@@ -0,0 +1,168 @@
+import { buildDynamicRequestContext, buildRequestContext, materializeRequestContext, requestContextBase, } from "./build.js";
+import { trace } from "../debug.js";
+import { encodeMessage } from "../protocol/messages.js";
+/**
+ * Freeze the expensive RequestContext base for the life of a conversation_id.
+ *
+ * Cursor's current exec-daemon cache treats RequestContext as a baked stable
+ * base plus live plugin/tool overlays. Rebuilding volatile git/layout data on
+ * every Run shifts the prompt prefix and tanks prompt-cache hits.
+ *
+ * Skills, subagents, plugin metadata, and tool/MCP capabilities are rebuilt on
+ * each Run and overlaid on that base. If their encoded bytes did not change,
+ * the exact prior materialized object is reused. This matches Cursor's newer
+ * baked-context + live-overlay design without retaining stale capabilities.
+ */
+const byConversationId = new Map();
+const materializedByConversationId = new Map();
+const buildsByConversationId = new Map();
+export const MAX_FROZEN_REQUEST_CONTEXTS = 256;
+function freezeSnapshot(value, seen = new Set()) {
+    if (!value || typeof value !== "object")
+        return value;
+    const object = value;
+    if (seen.has(object) || ArrayBuffer.isView(object))
+        return value;
+    seen.add(object);
+    for (const child of Object.values(object))
+        freezeSnapshot(child, seen);
+    return Object.freeze(value);
+}
+function remember(conversationId, context) {
+    // Map insertion order is the LRU order. Refresh existing entries on use.
+    byConversationId.delete(conversationId);
+    // Clone + recursively freeze so session.requestContext cannot mutate the
+    // byte-stable snapshot retained for later Runs in the same conversation.
+    byConversationId.set(conversationId, freezeSnapshot(structuredClone(context)));
+    materializedByConversationId.delete(conversationId);
+    while (byConversationId.size > MAX_FROZEN_REQUEST_CONTEXTS) {
+        const oldest = byConversationId.keys().next().value;
+        if (!oldest)
+            break;
+        byConversationId.delete(oldest);
+        materializedByConversationId.delete(oldest);
+    }
+}
+/** Frozen stable RequestContext base for this conversation, if any. */
+export function getFrozenRequestContext(conversationId) {
+    const frozen = byConversationId.get(conversationId);
+    if (!frozen)
+        return undefined;
+    // Touch for LRU.
+    byConversationId.delete(conversationId);
+    byConversationId.set(conversationId, frozen);
+    return frozen;
+}
+/** Replace the frozen stable base, stripping any live capability fields. */
+export function setFrozenRequestContext(conversationId, context) {
+    if (!conversationId)
+        return;
+    remember(conversationId, requestContextBase(context));
+}
+/** Drop a conversation's frozen RequestContext (compaction / binding reset). */
+export function clearFrozenRequestContext(conversationId) {
+    byConversationId.delete(conversationId);
+    materializedByConversationId.delete(conversationId);
+}
+/**
+ * Move a stable workspace base across a conversation-id reset.
+ *
+ * Compaction changes Cursor's state/checkpoint identity, not the OpenCode
+ * workspace. Preserve the expensive base and the prior materialized bytes as a
+ * comparison seed; getOrBuildRequestContext still rediscovers live capability
+ * overlays and only reuses the complete context when those bytes also match.
+ */
+export function transferFrozenRequestContext(previousConversationId, nextConversationId) {
+    if (!previousConversationId || !nextConversationId)
+        return false;
+    const base = byConversationId.get(previousConversationId);
+    const materialized = materializedByConversationId.get(previousConversationId);
+    clearFrozenRequestContext(previousConversationId);
+    clearFrozenRequestContext(nextConversationId);
+    if (!base)
+        return false;
+    remember(nextConversationId, base);
+    if (materialized) {
+        materializedByConversationId.set(nextConversationId, {
+            context: materialized.context,
+            bytes: Uint8Array.from(materialized.bytes),
+        });
+    }
+    return true;
+}
+/** Test helper — wipe all frozen contexts. */
+export function resetFrozenRequestContextsForTests() {
+    byConversationId.clear();
+    materializedByConversationId.clear();
+    buildsByConversationId.clear();
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function rememberMaterialized(conversationId, context) {
+    const bytes = encodeMessage("RequestContext", context);
+    const previous = materializedByConversationId.get(conversationId);
+    if (previous && sameBytes(previous.bytes, bytes)) {
+        return { context: previous.context, reused: true };
+    }
+    const frozen = freezeSnapshot(structuredClone(context));
+    materializedByConversationId.set(conversationId, {
+        context: frozen,
+        bytes: Uint8Array.from(bytes),
+    });
+    return { context: frozen, reused: false };
+}
+/**
+ * Return a stable-base + live-overlay RequestContext for `conversationId`.
+ * The base is built once; capability sections are rediscovered every Run.
+ */
+export async function getOrBuildRequestContext(conversationId, input, opts) {
+    if (!opts?.refresh && conversationId) {
+        const base = getFrozenRequestContext(conversationId);
+        if (base) {
+            const dynamic = await buildDynamicRequestContext(input);
+            const materialized = rememberMaterialized(conversationId, materializeRequestContext(base, dynamic));
+            trace(`request_context: materialized conversationId=${conversationId} ` +
+                `tools=${Array.isArray(materialized.context.tools) ? materialized.context.tools.length : 0} ` +
+                `reused=${materialized.reused}`);
+            return materialized;
+        }
+    }
+    // Two overlapping model calls can open Runs for the same conversation. Share
+    // the first build so both Runs receive the same snapshot instead of racing
+    // two independently collected git/layout views into the cache.
+    if (!opts?.refresh && conversationId) {
+        const inFlight = buildsByConversationId.get(conversationId);
+        if (inFlight) {
+            await inFlight;
+            return getOrBuildRequestContext(conversationId, input);
+        }
+    }
+    const build = buildRequestContext(input);
+    if (conversationId)
+        buildsByConversationId.set(conversationId, build);
+    let context;
+    try {
+        context = await build;
+    }
+    finally {
+        if (conversationId && buildsByConversationId.get(conversationId) === build) {
+            buildsByConversationId.delete(conversationId);
+        }
+    }
+    if (conversationId)
+        setFrozenRequestContext(conversationId, context);
+    // The first full build already contains both base and live overlay.
+    const materialized = conversationId
+        ? rememberMaterialized(conversationId, context)
+        : { context: freezeSnapshot(structuredClone(context)), reused: false };
+    trace(`request_context: built+frozen conversationId=${conversationId || "(none)"} ` +
+        `tools=${Array.isArray(materialized.context.tools) ? materialized.context.tools.length : 0} ` +
+        `refresh=${!!opts?.refresh}`);
+    return { context: materialized.context, reused: false };
+}

package/dist/context/index.d.ts

@@ -1,2 +1,3 @@
-export { buildRequestContext, type BuildRequestContextInput } from "./build.js";
+export { buildDynamicRequestContext, buildRequestContext, DYNAMIC_REQUEST_CONTEXT_KEYS, materializeRequestContext, requestContextBase, type BuildRequestContextInput, } from "./build.js";
+export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestContext, MAX_FROZEN_REQUEST_CONTEXTS, resetFrozenRequestContextsForTests, setFrozenRequestContext, transferFrozenRequestContext, } from "./frozen.js";
 export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/index.js

@@ -1,2 +1,3 @@
-export { buildRequestContext } from "./build.js";
+export { buildDynamicRequestContext, buildRequestContext, DYNAMIC_REQUEST_CONTEXT_KEYS, materializeRequestContext, requestContextBase, } from "./build.js";
+export { clearFrozenRequestContext, getFrozenRequestContext, getOrBuildRequestContext, MAX_FROZEN_REQUEST_CONTEXTS, resetFrozenRequestContextsForTests, setFrozenRequestContext, transferFrozenRequestContext, } from "./frozen.js";
 export { adoptCompatHostCacheDir, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/rules.d.ts

@@ -9,6 +9,7 @@ export type OpencodeJson = {
     plugins?: string[];
     mcp?: Record<string, unknown>;
 };
+export declare function findGitWorktree(start: string): Promise<string>;
 /** Same truthy rule as OpenCode's Flag.OPENCODE_DISABLE_PROJECT_CONFIG. */
 export declare function isProjectConfigDisabled(): boolean;
 /** Fetch a remote instruction with one deadline covering headers and body. */

package/dist/context/rules.js

@@ -27,7 +27,7 @@ async function readJsonConfig(dir) {
     }
     return {};
 }
-async function findGitWorktree(start) {
+export async function findGitWorktree(start) {
     let dir = path.resolve(start);
     for (;;) {
         if (await exists(path.join(dir, ".git")))

package/dist/language-model.d.ts

@@ -1,10 +1,15 @@
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamPart } from "@ai-sdk/provider";
 import type { CreateCursorOptions, CursorRetryOptions } from "./index.js";
 import { type OpencodeToolDef } from "./protocol/tools.js";
+import { cursorContextUsageMetadata, type CursorContextUsageSource, type CursorConversationTokenDetails } from "./protocol/token-details.js";
+import { type ConversationBlobGraphStats } from "./protocol/blob-store.js";
 import { type CursorSession } from "./session.js";
 import { CursorProviderError } from "./errors.js";
 import type { SeedHistoryMessage } from "./protocol/request.js";
 export declare const MAX_TURN_STATE_SESSIONS = 256;
+/** Cursor's own conversation export path treats state above 100 MiB as large. */
+export declare const MAX_CHECKPOINT_BLOB_GRAPH_BYTES: number;
+export declare function checkpointBlobGraphRequiresRebase(stats: ConversationBlobGraphStats, maxBytes?: number): boolean;
 export type CursorRetryPolicy = {
     maxAttempts: number;
     baseDelayMs: number;
@@ -12,13 +17,14 @@ 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. */
+export declare function restoreTurnToolCatalog(sessionKey: string, tools: OpencodeToolDef[]): void;
 type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
 export declare function pumpWithRecovery(input: {
     initialSession: CursorSession;
     controller: ReadableStreamDefaultController<V3Part>;
     abortSignal?: AbortSignal;
-    promptTokens?: number;
     retryPolicy?: CursorRetryPolicy;
     recover: (recovery: CursorRunRecovery) => Promise<CursorSession>;
     onSession?: (session: CursorSession) => void;
@@ -56,10 +62,6 @@ export declare function deliverContinuationResults(session: CursorSession, trail
 export declare function pump(session: CursorSession, controller: ReadableStreamDefaultController<V3Part>, ids: {
     textId: string;
     reasoningId: string;
-    promptTokens?: number;
-    requestUsage?: {
-        outputChars: number;
-    };
 }, abortSignal?: AbortSignal): Promise<void>;
 type ExtractedToolResult = {
     toolCallId: string;
@@ -83,10 +85,8 @@ export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOp
 export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean, workspaceRoot: string): string | undefined;
 /** Rough char→token estimate for mid-turn usage before TurnEnded arrives. */
 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 exact Cursor counters as diagnostics when they are cumulative across a multi-step Run. */
-export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>): {
+/** Preserve exact request-local Cursor counters as diagnostics. */
+export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>, tokenDetails?: CursorConversationTokenDetails, contextSource?: CursorContextUsageSource): {
     cursor: {
         usageVersion: number;
         inputTokensRaw: number;
@@ -94,6 +94,7 @@ export declare function cursorTurnEndedProviderMetadata(te: Record<string, unkno
         cacheReadRaw: number;
         cacheWriteRaw: number;
         reasoningTokensRaw: number;
+        context?: ReturnType<typeof cursorContextUsageMetadata>;
     };
 };
 /**