cursor-opencode-provider 0.7.2 → 0.7.3

package/README.md

@@ -189,7 +189,7 @@ Image support is resolved in this order:
 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.
+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 and historical user messages (the trailing user message stays owned by last-user extraction); 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
 
@@ -229,6 +229,8 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `crs
 | `CURSOR_WEBSITE_URL` | Override OAuth login base URL (default `https://cursor.com`) |
 | `CURSOR_API_BASE_URL` | Override API base for auth, model discovery, and `GetServerConfig` agent URL resolution (default `https://api2.cursor.sh`) |
 | `CURSOR_GET_SERVER_CONFIG_TELEMETRY` | Set to `1` or `true` to opt the `GetServerConfig` lookup into telemetry in OpenCode/plugin usage |
+| `HTTPS_PROXY` / `https_proxy` | HTTP CONNECT proxy for HTTPS. Bun `fetch` uses this for unary RPCs; the Run HTTP/2 session also tunnels through it (see `NO_PROXY`). The Run tunnel supports only `http://` proxy URLs (Basic auth via userinfo); `https://` and SOCKS proxy URLs leave the Run on a direct connection. `HTTP_PROXY` is not used for HTTPS |
+| `NO_PROXY` / `no_proxy` | Comma/space hosts that bypass the proxy (`*`, exact host, or `.suffix` / `suffix` domain forms; a `host:port` entry bypasses only that port) |
 | `CURSOR_PROVIDER_DEBUG` | Set to `1` or `true` to enable wire-level debug logging |
 | `CURSOR_PROVIDER_DEBUG_FILE` | Debug log path (default: `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) |
 | `CURSOR_OPENCODE2_DEV_ENTRY` | **Local OpenCode 2.0 only.** Absolute path to a built entry file (usually `dist/index.js`). Rewrites the AI SDK package to `aisdk:file://…` so the daemon imports your local build instead of `npm install`-ing the published package. Export it **before** `opencode2 service start`, then restart after rebuilds. Unset in production. See [OpenCode 2.0 local clone](docs/opencode-2.md#from-a-local-clone-cursor_opencode2_dev_entry). |
@@ -284,6 +286,7 @@ OpenCode
 | `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 |
+| `src/transport/https-proxy.ts` | `HTTPS_PROXY` / `NO_PROXY` CONNECT tunnel for Run sessions |
 | `src/protocol/` | Protobuf encode/decode, checksum/device ids, exec + display tool-call mapping (`tool-call-bridge.ts`) |
 
 ### Injected system guidance
@@ -345,7 +348,7 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | Local OpenCode 2.0 still runs the published package | Set `CURSOR_OPENCODE2_DEV_ENTRY` to an absolute `…/dist/index.js` path **before** starting the daemon, persist it with `opencode2 service set env CURSOR_OPENCODE2_DEV_ENTRY …`, rebuild (`bun run build`), then `opencode2 service restart`. Loading only `dist/plugin-opencode2.js` is not enough — without the env var, 2.0 still `npm install`s the published package into the host cache. |
 | “Too many connections from different devices” | Device IDs are derived from stable OS identifiers (same approach as the Cursor CLI). Avoid running multiple clients that invent different machine fingerprints for the same account. |
 | Empty or stale model list | Delete `<host-cache>/cursor-models.json` (native default `~/.cache/opencode/`) and restart OpenCode. A compatibility layer may supply a different host-cache root through the structural path bridge. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
-| Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, resumes transient interruptions from the latest eligible Cursor checkpoint, and falls back to a fresh-history rebase only before stateful output when no checkpoint exists. Repeated interruption is surfaced as an error instead of a false successful stop; retry the turn after checking connectivity. With debug logging enabled, look for `Run interrupted`, `resuming … checkpoint`, or `rebasing fresh Run`. Restart OpenCode after rebuilding a local `file://` install. |
+| Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, resumes transient interruptions from the latest eligible Cursor checkpoint, and falls back to a fresh-history rebase only before stateful output when no checkpoint exists. Repeated interruption is surfaced as an error instead of a false successful stop; retry the turn after checking connectivity. Behind an HTTP proxy, set `HTTPS_PROXY` (and `NO_PROXY` as needed): unary `fetch` and the Run HTTP/2 CONNECT tunnel both honor them. With debug logging enabled, look for `Run interrupted`, `resuming … checkpoint`, `rebasing fresh Run`, or `h2 connect via HTTPS proxy`. Restart OpenCode after rebuilding a local `file://` install. |
 | 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. Known `handling=unsupported` variants (Cursor-native capabilities without a safe OpenCode AI SDK bridge) are now soft-denied on the wire with a populated typed error/`rejected`/`allowlisted:false` result and the Run continues — look for `exec: SOFT-DENIED …` in the debug log and a `Workspace root: …` suffix in the deny text — while `unknown request field` still hard-fails as protocol drift; `handling=opencode-tool` or `provider-control` indicates a provider decoder/dispatch regression. Enable the debug log and report the full named error. |
@@ -362,8 +365,8 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 
 - **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.
 - **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`; at `TurnEnded`, output/reasoning remain based on `TurnEnded`, while uncached/cache-read/cache-write input are proportionally normalized to the remaining context input. OpenCode TUI/GUI replace each assistant message's tokens (TUI requires `tokens.output > 0`) and add cost per step, so mid-turn tool boundaries emit the last-known occupancy snapshot rather than a delta or a billed zero. Those snapshots set `output=1` so the footer updates and `providerMetadata.copilot.totalNanoAiu: 0` so OpenCode's getUsage reports $0 instead of charging occupancy as a new prompt. 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. 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.
+- **`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 each Run then epoch-held (equal ids keep frozen bytes; new ids append); unchanged overlays reuse byte-identical encoded context. 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` / GetDynamicTools; exec still reconstructs the full OpenCode tool id. That discovery call is Cursor-native (not an OpenCode catalog tool). Oversized catalogs spill through `write_args` into `agent-tools/<uuid>.txt`; `WriteSuccess.path` echoes the requested path so the model receives a real `filePath` instead of an empty spill.
 - **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` → `todowrite`, `read_todos_tool_call` → `todoread`, `create_plan_tool_call` → `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 variants are soft-denied on the held Run with a populated typed error/`rejected`/`allowlisted:false` result (or `throw` when the CLI has no typed error shape) so the turn continues; unknown future request fields still fail the Run explicitly rather than receiving a guessed response that could deadlock it.
 - **Progress-only fragments can get one continuation** — if a real tool-enabled turn ends with a short progress fragment ("Checking the workspace", "Looking into it now") and no host tool call, the provider opens one follow-up Run with a synthetic user nudge so the model can call a listed tool or finish the answer. Complete answers that merely start with those verbs are not continued. Title/compaction turns (`allowTools=false`) never continue. If the continuation fails, the original `turn_ended` is still reported as a successful stop.
 - **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.
@@ -377,7 +380,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **Other Cursor-native interaction queries remain headless** — remaining UI/approval *queries* (as distinct from display tool calls and the AskQuestion / SwitchMode / CreatePlan / GenerateImage bridges) still cannot be surfaced through the AI SDK provider interface. The normal system prompt redirects available web capabilities to executable host tools (`custom_websearch`, `custom_webfetch`); native web/PR/MCP/SCM requests are declined so they remain behind host tool permissions. Compaction prompts are unchanged. Unknown future interaction variants fail the turn explicitly instead of hanging the Run stream.
 - **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, host agent, stable system-prompt hash, 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, agent switches, or prompt changes 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 prompt/catalog state 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.
+- **Oversized / incomplete checkpoint graphs warn but do not remint** — before reusing a checkpoint, the provider measures its reachable KV graph. State above 100 MiB (Cursor CLI export/transfer budget) or an incomplete graph is logged (`action=warm-reuse`) and the sticky conversation is kept, matching CLI soft-reuse. 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 by OpenCode, and the cap is reported** — OpenCode 1.x `read` stops at `MAX_BYTES = 50 * 1024` and appends `(Output capped at 50 KB. Showing lines X-Y. Use offset=N to continue.)`. OpenCode 2 prints `Read file <path>, lines <start>-<end>` with `N: ` prefixes and, when the page ends before EOF, `[Output truncated. Continue reading with offset: N]` (50 KB or 2,000 lines); it also shortens each individual line after 2,000 characters. The provider strips either envelope before returning content to Cursor so the model cannot echo wrappers into a later write, but it re-states every partial result: a native read appends a `[Partial read: …]` marker after the content, an MCP read gets a separate notice content item, and a Pi read carries structured `PiReadExecSuccess.truncation`. Relative grep, glob, and directory entries are resolved against the workspace root. Shell stdout absolutizes only relative path tokens, not prose. Checkpointed turns, which do not resend the system prompt, get that same root on the user message. 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 unless the host also hits the byte cap or character-truncates a line. 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.

package/dist/context/agents.js

@@ -70,7 +70,7 @@ async function scanAgentRoot(root, out) {
         let entries;
         try {
             entries = await readdir(dir, { withFileTypes: true });
-            entries.sort((a, b) => a.name.localeCompare(b.name));
+            entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
         }
         catch {
             return;

package/dist/context/build.d.ts

@@ -3,6 +3,8 @@ export type BuildRequestContextInput = {
     workspaceRoot: string;
     tools?: OpencodeToolDef[];
     providerIdentifier?: string;
+    /** When set, skills/subagents/plugins are epoch-held for this conversation. */
+    conversationId?: 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];

package/dist/context/build.js

@@ -8,6 +8,7 @@ import { collectGit } from "./git.js";
 import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
 import { ensureOpencodeProjectDir } from "./paths.js";
+import { holdCapabilityOverlay } from "./overlay.js";
 import { traceRequestContextPaths } from "../debug.js";
 export const DYNAMIC_REQUEST_CONTEXT_KEYS = [
     "tools",
@@ -123,14 +124,27 @@ async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, wor
                 `Delegate to the host-configured ${agent.name} subagent; its host instructions and tools apply.`,
         };
     });
+    const liveSkills = skills.map((s) => ({
+        id: s.name,
+        full_path: s.fullPath,
+        content: s.content,
+        description: s.description,
+    }));
+    const livePlugins = plugins.map((p) => ({
+        id: p.id,
+        line: `opencode-plugin:${p.source}:${p.id}`,
+    }));
+    const overlay = input.conversationId
+        ? holdCapabilityOverlay(input.conversationId, {
+            skills: liveSkills,
+            subagents: customSubagents,
+            plugins: livePlugins,
+        })
+        : { skills: liveSkills.map(({ full_path, content, description }) => ({ full_path, content, description })), subagents: customSubagents, plugins: livePlugins };
     const dynamic = {
         tools: flat,
-        agent_skills: skills.map((s) => ({
-            full_path: s.fullPath,
-            content: s.content,
-            description: s.description,
-        })),
-        custom_subagents: customSubagents,
+        agent_skills: overlay.skills,
+        custom_subagents: overlay.subagents,
         mcp_file_system_options: {
             enabled: true,
             // Cursor metadata root (mcps / agent-tools), not the git workspace.
@@ -152,10 +166,8 @@ async function buildDynamicRequestContextFromDiscovery(input, workspaceRoot, wor
         mcp_file_system_info_complete: true,
         mcp_info_complete: true,
     };
-    if (plugins.length > 0) {
-        dynamic.hooks_additional_context = plugins
-            .map((p) => `opencode-plugin:${p.source}:${p.id}`)
-            .join("\n");
+    if (overlay.plugins.length > 0) {
+        dynamic.hooks_additional_context = overlay.plugins.map((p) => p.line).join("\n");
     }
     return dynamic;
 }

package/dist/context/epoch.d.ts

@@ -0,0 +1,59 @@
+export declare const MAX_CONTEXT_EPOCHS = 256;
+export type ContextSourceSnapshot = {
+    hostSystemHash: string;
+    guidanceHash: string;
+    hostAgent: string;
+    workspaceRoot: string;
+};
+export type ContextEpoch = {
+    conversationId: string;
+    /** Exact system text seeded at epoch start. Empty when recovered from checkpoint. */
+    baselineSystemPrompt: string;
+    baselineHash: string;
+    /** True when restart hydrated past a checkpoint without the original baseline bytes. */
+    recovered: boolean;
+    snapshot: ContextSourceSnapshot;
+};
+export type AdmitContextEpochInput = {
+    conversationId: string;
+    /** True when this Run carries conversation_state (no systemPrompt on the wire). */
+    hasCheckpoint: boolean;
+    hostSystem?: string;
+    guidance?: string;
+    hostAgent?: string;
+    workspaceRoot: string;
+    /**
+     * One-shot reminders already wrapped (mode / kickoff). Always chronological —
+     * never folded into the frozen baseline.
+     */
+    oneShotReminders?: readonly string[];
+};
+export type AdmitContextEpochResult = {
+    action: "initialize" | "unchanged" | "updated" | "recovered";
+    /** Wire systemPrompt for seed Runs only — always the frozen baseline once set. */
+    seedSystemPrompt?: string;
+    /** Combined Mid-Conversation System Message (append after user text). */
+    midConversationMessage?: string;
+    epoch: ContextEpoch;
+};
+/**
+ * Admit System Context at a Safe Provider-Turn Boundary.
+ *
+ * - First seed: freeze baseline, return it as seedSystemPrompt; one-shots → mid.
+ * - Checkpoint turn: never returns seedSystemPrompt; source diffs + one-shots → mid.
+ * - Reseed same epoch: return frozen baseline bytes (not live host text).
+ * - Recovered (restart past a checkpoint, original bytes unknown): never freeze
+ *   live host text as a new baseline and never send a seed systemPrompt.
+ */
+export declare function admitContextEpoch(input: AdmitContextEpochInput): AdmitContextEpochResult;
+export declare function getContextEpoch(conversationId: string): ContextEpoch | undefined;
+/** Drop epoch state (compaction remint / binding clear). */
+export declare function clearContextEpoch(conversationId: string): void;
+/**
+ * Compaction remints conversation_id. RequestContext workspace base transfers;
+ * System Context baseline does not — the destination starts a fresh epoch.
+ */
+export declare function endContextEpoch(previousConversationId: string, nextConversationId?: string): void;
+export declare function resetContextEpochsForTests(): void;
+/** Append a mid-conversation message after user text (V2: user precedes update). */
+export declare function appendMidConversationMessage(userText: string, midConversationMessage: string | undefined): string;

package/dist/context/epoch.js

@@ -0,0 +1,224 @@
+/**
+ * Context Epoch — V2-style immutable system baseline + chronological updates.
+ *
+ * Mirrors OpenCode research CONTEXT.md:
+ * - One Baseline System Context per conversation_id (provider-cache prefix)
+ * - Later Context Source changes → Mid-Conversation System Message on the
+ *   user turn (Cursor checkpoint Runs cannot rewrite systemPrompt)
+ * - Epoch ends on conversation remint (compaction / post-compaction rebase)
+ *
+ * Cursor constraint: systemPrompt is only sent on seed Runs. Checkpointed
+ * Runs admit updates exclusively via the live user message.
+ */
+import { createHash } from "node:crypto";
+import { trace } from "../debug.js";
+export const MAX_CONTEXT_EPOCHS = 256;
+const byConversationId = new Map();
+function sha(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function joinSections(parts) {
+    return parts.map((part) => part?.trim()).filter((part) => !!part).join("\n\n");
+}
+function snapshotOf(input) {
+    return {
+        hostSystemHash: sha(input.hostSystem?.trim() || ""),
+        guidanceHash: sha(input.guidance?.trim() || ""),
+        hostAgent: input.hostAgent?.trim() || "",
+        workspaceRoot: input.workspaceRoot,
+    };
+}
+function buildBaseline(input) {
+    // Durable System Context only. Mode/kickoff one-shots stay chronological.
+    return joinSections([input.hostSystem, input.guidance]);
+}
+function wrapReminder(body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.startsWith("<system_reminder>"))
+        return trimmed;
+    return `<system_reminder>\n${trimmed}\n</system_reminder>`;
+}
+function renderSourceUpdates(previous, next, live) {
+    const parts = [];
+    if (next.hostAgent && previous.hostAgent !== next.hostAgent) {
+        parts.push(wrapReminder(`Host primary agent is now ${JSON.stringify(next.hostAgent)}. ` +
+            "Follow this agent's instructions and tool permissions for the rest of the turn. " +
+            "This is a chronological context update; the original system baseline is unchanged."));
+    }
+    if (live.hostSystem?.trim() && previous.hostSystemHash !== next.hostSystemHash) {
+        parts.push(wrapReminder("Host system instructions were updated for this session. Effective instructions:\n\n" +
+            live.hostSystem.trim()));
+    }
+    if (live.guidance?.trim() && previous.guidanceHash !== next.guidanceHash) {
+        parts.push(wrapReminder("OpenCode interaction guidance was updated for this session:\n\n" + live.guidance.trim()));
+    }
+    if (previous.workspaceRoot !== next.workspaceRoot && next.workspaceRoot) {
+        parts.push(wrapReminder(`Workspace root is now ${JSON.stringify(next.workspaceRoot)}. ` +
+            "Resolve workspace paths against exactly this root; never invent an absolute prefix."));
+    }
+    return parts.filter(Boolean);
+}
+function touch(epoch) {
+    byConversationId.delete(epoch.conversationId);
+    byConversationId.set(epoch.conversationId, epoch);
+    while (byConversationId.size > MAX_CONTEXT_EPOCHS) {
+        const oldest = byConversationId.keys().next().value;
+        if (!oldest)
+            break;
+        byConversationId.delete(oldest);
+    }
+}
+function combineMessages(parts) {
+    const text = parts.map((part) => part.trim()).filter(Boolean).join("\n\n");
+    return text || undefined;
+}
+/**
+ * Admit System Context at a Safe Provider-Turn Boundary.
+ *
+ * - First seed: freeze baseline, return it as seedSystemPrompt; one-shots → mid.
+ * - Checkpoint turn: never returns seedSystemPrompt; source diffs + one-shots → mid.
+ * - Reseed same epoch: return frozen baseline bytes (not live host text).
+ * - Recovered (restart past a checkpoint, original bytes unknown): never freeze
+ *   live host text as a new baseline and never send a seed systemPrompt.
+ */
+export function admitContextEpoch(input) {
+    const conversationId = input.conversationId;
+    const nextSnap = snapshotOf(input);
+    const oneShots = (input.oneShotReminders ?? []).map((part) => part.trim()).filter(Boolean);
+    const existing = byConversationId.get(conversationId);
+    if (!existing) {
+        if (input.hasCheckpoint) {
+            // Restart / soft-evict recovery: Cursor already holds the baseline in the
+            // checkpoint. Record the live snapshot without reseeding systemPrompt.
+            const epoch = {
+                conversationId,
+                baselineSystemPrompt: "",
+                baselineHash: "",
+                recovered: true,
+                snapshot: nextSnap,
+            };
+            touch(epoch);
+            const midConversationMessage = combineMessages(oneShots);
+            trace(`context epoch: recovered conversationId=${conversationId} ` +
+                `oneShots=${oneShots.length}`);
+            return { action: "recovered", midConversationMessage, epoch };
+        }
+        const baselineSystemPrompt = buildBaseline(input);
+        const baselineHash = sha(baselineSystemPrompt);
+        const epoch = {
+            conversationId,
+            baselineSystemPrompt,
+            baselineHash,
+            recovered: false,
+            snapshot: nextSnap,
+        };
+        touch(epoch);
+        trace(`context epoch: initialize conversationId=${conversationId} ` +
+            `baselineHash=${baselineHash.slice(0, 16)} baselineLen=${baselineSystemPrompt.length} ` +
+            `oneShots=${oneShots.length}`);
+        return {
+            action: "initialize",
+            seedSystemPrompt: baselineSystemPrompt || undefined,
+            midConversationMessage: combineMessages(oneShots),
+            epoch,
+        };
+    }
+    // Optional sources may be unavailable on a turn. Absence is not an explicit
+    // deletion signal: carrying the prior observation avoids synthetic context
+    // churn and preserves the warm prefix.
+    const observedSnap = {
+        hostSystemHash: input.hostSystem?.trim()
+            ? nextSnap.hostSystemHash
+            : existing.snapshot.hostSystemHash,
+        guidanceHash: input.guidance?.trim()
+            ? nextSnap.guidanceHash
+            : existing.snapshot.guidanceHash,
+        hostAgent: input.hostAgent?.trim()
+            ? nextSnap.hostAgent
+            : existing.snapshot.hostAgent,
+        workspaceRoot: nextSnap.workspaceRoot || existing.snapshot.workspaceRoot,
+    };
+    const updates = renderSourceUpdates(existing.snapshot, observedSnap, input);
+    const changed = existing.snapshot.hostSystemHash !== observedSnap.hostSystemHash
+        || existing.snapshot.guidanceHash !== observedSnap.guidanceHash
+        || existing.snapshot.hostAgent !== observedSnap.hostAgent
+        || existing.snapshot.workspaceRoot !== observedSnap.workspaceRoot;
+    if (changed) {
+        existing.snapshot = observedSnap;
+    }
+    touch(existing);
+    if (input.hasCheckpoint) {
+        const midConversationMessage = combineMessages([...updates, ...oneShots]);
+        if (changed || oneShots.length) {
+            trace(`context epoch: ${changed ? "updated" : "unchanged"} conversationId=${conversationId} ` +
+                `checkpoint=1 updates=${updates.length} oneShots=${oneShots.length}`);
+        }
+        return {
+            action: changed ? "updated" : "unchanged",
+            midConversationMessage,
+            epoch: existing,
+        };
+    }
+    // Recovered epochs have no original baseline bytes. A later seed Run must
+    // not freeze live host text as if it were the prefix Cursor already holds.
+    if (existing.recovered && !existing.baselineSystemPrompt) {
+        const midConversationMessage = combineMessages([...updates, ...oneShots]);
+        trace(`context epoch: recovered-hold conversationId=${conversationId} ` +
+            `checkpoint=0 updates=${updates.length} oneShots=${oneShots.length} seed=omitted`);
+        return {
+            action: changed ? "updated" : "recovered",
+            midConversationMessage,
+            epoch: existing,
+        };
+    }
+    const midConversationMessage = combineMessages([...updates, ...oneShots]);
+    if (changed) {
+        trace(`context epoch: updated conversationId=${conversationId} checkpoint=0 ` +
+            `updates=${updates.length} seed=frozen-baseline`);
+    }
+    return {
+        action: changed ? "updated" : "unchanged",
+        seedSystemPrompt: existing.baselineSystemPrompt || undefined,
+        midConversationMessage,
+        epoch: existing,
+    };
+}
+export function getContextEpoch(conversationId) {
+    const epoch = byConversationId.get(conversationId);
+    if (!epoch)
+        return undefined;
+    touch(epoch);
+    return epoch;
+}
+/** Drop epoch state (compaction remint / binding clear). */
+export function clearContextEpoch(conversationId) {
+    if (!conversationId)
+        return;
+    if (byConversationId.delete(conversationId)) {
+        trace(`context epoch: cleared conversationId=${conversationId}`);
+    }
+}
+/**
+ * Compaction remints conversation_id. RequestContext workspace base transfers;
+ * System Context baseline does not — the destination starts a fresh epoch.
+ */
+export function endContextEpoch(previousConversationId, nextConversationId) {
+    clearContextEpoch(previousConversationId);
+    if (nextConversationId)
+        clearContextEpoch(nextConversationId);
+}
+export function resetContextEpochsForTests() {
+    byConversationId.clear();
+}
+/** Append a mid-conversation message after user text (V2: user precedes update). */
+export function appendMidConversationMessage(userText, midConversationMessage) {
+    if (!midConversationMessage?.trim())
+        return userText;
+    if (!userText.trim())
+        return midConversationMessage.trim();
+    if (userText.includes(midConversationMessage.trim()))
+        return userText;
+    return `${userText}\n\n${midConversationMessage.trim()}`;
+}

package/dist/context/frozen.d.ts

@@ -12,14 +12,16 @@ export declare function clearFrozenRequestContext(conversationId: string): void;
  * 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.
+ * overlays (then epoch-holds them) 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.
+ * The base is built once; capability sections are rediscovered every Run
+ * and then epoch-held.
  */
 export declare function getOrBuildRequestContext(conversationId: string, input: BuildRequestContextInput, opts?: {
     refresh?: boolean;

package/dist/context/frozen.js

@@ -1,4 +1,6 @@
 import { buildDynamicRequestContext, buildRequestContext, materializeRequestContext, requestContextBase, } from "./build.js";
+import { clearContextEpoch, endContextEpoch, resetContextEpochsForTests } from "./epoch.js";
+import { clearOverlayHold, resetOverlayHoldsForTests, transferOverlayHold, } from "./overlay.js";
 import { trace } from "../debug.js";
 import { encodeMessage } from "../protocol/messages.js";
 /**
@@ -8,10 +10,10 @@ import { encodeMessage } from "../protocol/messages.js";
  * 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.
+ * Skills, subagents, plugin metadata, and tool/MCP capabilities are rediscovered
+ * each Run, then epoch-held (equal ids keep frozen bytes; new ids append) and
+ * overlaid on that base. If the encoded overlay bytes did not change, the exact
+ * prior materialized object is reused.
  */
 const byConversationId = new Map();
 const materializedByConversationId = new Map();
@@ -41,6 +43,7 @@ function remember(conversationId, context) {
             break;
         byConversationId.delete(oldest);
         materializedByConversationId.delete(oldest);
+        clearOverlayHold(oldest);
     }
 }
 /** Frozen stable RequestContext base for this conversation, if any. */
@@ -63,6 +66,8 @@ export function setFrozenRequestContext(conversationId, context) {
 export function clearFrozenRequestContext(conversationId) {
     byConversationId.delete(conversationId);
     materializedByConversationId.delete(conversationId);
+    clearOverlayHold(conversationId);
+    clearContextEpoch(conversationId);
 }
 /**
  * Move a stable workspace base across a conversation-id reset.
@@ -70,15 +75,24 @@ export function clearFrozenRequestContext(conversationId) {
  * 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.
+ * overlays (then epoch-holds them) 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);
+    // System Context epoch does not transfer — compaction starts a fresh baseline.
+    // Overlay hold does transfer: same workspace, same advertised skill/agent/plugin
+    // bytes, so the comparison seed can still match. clearFrozenRequestContext
+    // also drops epoch state for each id.
+    endContextEpoch(previousConversationId, nextConversationId);
+    transferOverlayHold(previousConversationId, nextConversationId);
+    byConversationId.delete(previousConversationId);
+    materializedByConversationId.delete(previousConversationId);
+    byConversationId.delete(nextConversationId);
+    materializedByConversationId.delete(nextConversationId);
     if (!base)
         return false;
     remember(nextConversationId, base);
@@ -95,6 +109,8 @@ export function resetFrozenRequestContextsForTests() {
     byConversationId.clear();
     materializedByConversationId.clear();
     buildsByConversationId.clear();
+    resetOverlayHoldsForTests();
+    resetContextEpochsForTests();
 }
 function sameBytes(a, b) {
     if (a.length !== b.length)
@@ -119,13 +135,17 @@ function rememberMaterialized(conversationId, context) {
 }
 /**
  * Return a stable-base + live-overlay RequestContext for `conversationId`.
- * The base is built once; capability sections are rediscovered every Run.
+ * The base is built once; capability sections are rediscovered every Run
+ * and then epoch-held.
  */
 export async function getOrBuildRequestContext(conversationId, input, opts) {
+    const scoped = conversationId ? { ...input, conversationId } : input;
+    if (opts?.refresh && conversationId)
+        clearOverlayHold(conversationId);
     if (!opts?.refresh && conversationId) {
         const base = getFrozenRequestContext(conversationId);
         if (base) {
-            const dynamic = await buildDynamicRequestContext(input);
+            const dynamic = await buildDynamicRequestContext(scoped);
             const materialized = rememberMaterialized(conversationId, materializeRequestContext(base, dynamic));
             trace(`request_context: materialized conversationId=${conversationId} ` +
                 `tools=${Array.isArray(materialized.context.tools) ? materialized.context.tools.length : 0} ` +
@@ -140,10 +160,10 @@ export async function getOrBuildRequestContext(conversationId, input, opts) {
         const inFlight = buildsByConversationId.get(conversationId);
         if (inFlight) {
             await inFlight;
-            return getOrBuildRequestContext(conversationId, input);
+            return getOrBuildRequestContext(conversationId, scoped);
         }
     }
-    const build = buildRequestContext(input);
+    const build = buildRequestContext(scoped);
     if (conversationId)
         buildsByConversationId.set(conversationId, build);
     let context;

package/dist/context/index.d.ts

@@ -1,3 +1,5 @@
 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 { MAX_OVERLAY_HOLDS, holdCapabilityOverlay, resetOverlayHoldsForTests, } from "./overlay.js";
+export { admitContextEpoch, appendMidConversationMessage, clearContextEpoch, endContextEpoch, getContextEpoch, MAX_CONTEXT_EPOCHS, resetContextEpochsForTests, type AdmitContextEpochInput, type AdmitContextEpochResult, type ContextEpoch, type ContextSourceSnapshot, } from "./epoch.js";
 export { HOST_PATH_BRIDGE, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, hostGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/index.js

@@ -1,3 +1,5 @@
 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 { MAX_OVERLAY_HOLDS, holdCapabilityOverlay, resetOverlayHoldsForTests, } from "./overlay.js";
+export { admitContextEpoch, appendMidConversationMessage, clearContextEpoch, endContextEpoch, getContextEpoch, MAX_CONTEXT_EPOCHS, resetContextEpochsForTests, } from "./epoch.js";
 export { HOST_PATH_BRIDGE, getHostCacheDirOverride, opencodeGlobalCacheDir, opencodeGlobalConfigDir, opencodeGlobalDataDir, hostGlobalDataDir, resolveHostCacheDir, setHostCacheDirOverride, } from "./paths.js";

package/dist/context/overlay.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Epoch-hold live RequestContext overlay lists (skills, subagents, plugins).
+ *
+ * Same policy as the tool catalog: first nonempty freeze is UTF-16 by id,
+ * equal ids keep frozen bytes (including content), new ids append at the
+ * tail, shrink keeps the epoch advertisement. Discovery still runs every
+ * Run; this only canonicalizes what is advertised.
+ */
+export declare const MAX_OVERLAY_HOLDS = 256;
+export type OverlaySkill = {
+    id: string;
+    full_path: string;
+    content: string;
+    description: string;
+};
+export type OverlaySubagent = {
+    full_path: string;
+    name: string;
+    description: string;
+    prompt: string;
+};
+export type OverlayPlugin = {
+    id: string;
+    line: string;
+};
+export type OverlayHold = {
+    skills: OverlaySkill[];
+    subagents: OverlaySubagent[];
+    plugins: OverlayPlugin[];
+};
+export type OverlayWire = {
+    skills: Array<{
+        full_path: string;
+        content: string;
+        description: string;
+    }>;
+    subagents: OverlaySubagent[];
+    plugins: OverlayPlugin[];
+};
+/** Merge live discovery into the conversation overlay epoch. */
+export declare function holdCapabilityOverlay(conversationId: string, live: OverlayHold): OverlayWire;
+export declare function clearOverlayHold(conversationId: string): void;
+export declare function transferOverlayHold(previousConversationId: string, nextConversationId: string): void;
+export declare function resetOverlayHoldsForTests(): void;