cursor-opencode-provider 0.8.1 → 0.8.3

package/dist/protocol/request.js

@@ -1,35 +1,42 @@
 import { encodeMessage, getMessageTypes } from "./messages.js";
 /**
- * Seed ConversationStateStructure for the first turn (no checkpoint yet).
+ * Empty ConversationStateStructure for a Run without a checkpoint (turn 1,
+ * compaction, rebase, reseed). After the first checkpoint arrives we stop
+ * inventing state and echo the server's opaque structure instead (CLI behavior).
  *
- * After the first checkpoint arrives we stop inventing state and echo the
- * server's opaque structure instead (CLI behavior). Compaction resets and
- * rebases also use this seed, with `history` carrying OpenCode's prompt turns
- * so Cursor can continue without the old checkpoint.
- *
- * No `system` entry is seeded: Cursor does not follow a client-authored
- * `system` root message, and neither Cursor client writes
- * `root_prompt_messages_json`. Host system context travels as the
- * system-instructions rule in RequestContext (`systemInstructionsRule`), so
- * `system` history entries are dropped here rather than duplicated.
+ * Nothing goes in `root_prompt_messages_json` (#1). Neither Cursor client
+ * writes it: Cursor checkpoints fill it with references to the conversation's
+ * own rendered root prompt. A client-written entry stands in for that prompt,
+ * so Cursor stops rendering RequestContext rules, skills and subagents — the
+ * host system-instructions rule included. Verified live 2026-10-09
+ * (claude-sonnet-5-5): two seeded history messages there gave checkpoint
+ * categories `rules:0, subagents:0` and a reply that ignored the rule; the same
+ * history in the user text kept both. History therefore travels in the user
+ * text ({@link seedHistoryUserText}).
  *
  * We deliberately do NOT use `AgentRunRequest.custom_system_prompt` (#8): that
  * field is the internal `--system-prompt` CLI override and the server rejects
  * it for normal accounts.
  */
-export function buildSeedConversationState(input) {
-    const root = getMessageTypes();
-    const type = root.lookupType("ConversationStateStructure");
-    const messages = [];
-    for (const entry of input?.history ?? []) {
-        if (!entry.content || entry.role === "system")
-            continue;
-        messages.push(JSON.stringify({ role: entry.role, content: entry.content }));
-    }
-    const obj = {};
-    if (messages.length > 0)
-        obj.root_prompt_messages_json = messages;
-    return type.encode(type.fromObject(obj)).finish();
+export function buildSeedConversationState() {
+    const type = getMessageTypes().lookupType("ConversationStateStructure");
+    return type.encode(type.fromObject({})).finish();
+}
+const SEED_HISTORY_TAGS = /<\/(conversation_history|user|assistant)>/gi;
+/**
+ * Prior turns of a Run without a checkpoint, as a transcript ahead of the live
+ * user text. `system` entries are dropped: host system context travels as the
+ * system-instructions rule in RequestContext. Closing tags inside a message are
+ * escaped so a message cannot end its own block early.
+ */
+export function seedHistoryUserText(text, history) {
+    const entries = (history ?? []).filter((entry) => entry.content && entry.role !== "system");
+    if (entries.length === 0)
+        return text;
+    const transcript = entries
+        .map((entry) => `<${entry.role}>\n${entry.content.replace(SEED_HISTORY_TAGS, "<\\/$1>")}\n</${entry.role}>`)
+        .join("\n\n");
+    return `<conversation_history>\n${transcript}\n</conversation_history>\n\n${text}`;
 }
 /**
  * Build an AgentClientMessage{run_request} for a conversation turn.
@@ -43,8 +50,9 @@ export function buildRunRequest(input) {
     // mcp_meta_tool_options. AgentRunRequest.mcp_tools (#4) stays empty on real
     // turns (CLI prewarm-only). Full defs are session.toolDescriptors + exec #36.
     const requestContext = input.requestContext;
+    const seeded = !(input.conversationState && input.conversationState.length > 0);
     const userMessage = {
-        text: input.text,
+        text: seeded ? seedHistoryUserText(input.text, input.history) : input.text,
         message_id: msgId,
     };
     if (input.mode !== undefined)
@@ -65,9 +73,9 @@ export function buildRunRequest(input) {
     const action = input.action === "resume"
         ? { resume_action: {} }
         : { user_message_action: userMessageAction };
-    const conversationState = input.conversationState && input.conversationState.length > 0
-        ? input.conversationState
-        : buildSeedConversationState({ history: input.history });
+    const conversationState = seeded
+        ? buildSeedConversationState()
+        : input.conversationState;
     const runRequest = {
         conversation_id: input.conversationId,
         conversation_group_id: input.conversationGroupId ?? input.conversationId,
@@ -98,3 +106,20 @@ export function buildHeartbeat() {
         client_heartbeat: {},
     });
 }
+/**
+ * ACM #5 `exec_client_control_message.heartbeat{id}`: Cursor CLI sends it every
+ * 3 s for each exec it is still running, keyed by the exec message id. The CLI
+ * leaves a zero id out, as proto3 does for a default scalar; protobufjs would
+ * write it explicitly, so it is omitted here to send the CLI's exact bytes.
+ */
+export function buildExecHeartbeat(execId) {
+    return encodeMessage("AgentClientMessage", {
+        exec_client_control_message: { heartbeat: execId === 0 ? {} : { id: execId } },
+    });
+}
+/** Stops the live Run, as Cursor CLI does on a user Stop before it closes the stream. */
+export function buildCancelAction(reason) {
+    return encodeMessage("AgentClientMessage", {
+        conversation_action: { cancel_action: { reason } },
+    });
+}

package/dist/protocol/sent-history-images.d.ts

@@ -0,0 +1,49 @@
+/** `hashes` is shared between entries and never mutated. */
+type HeldImages = {
+    conversationId: string;
+    checkpoint: string;
+    hashes: readonly string[];
+};
+/**
+ * One Run's view: `held` by the checkpoint it last stood on, `checkpointed` sent
+ * before Cursor's latest checkpoint arrived, `sent` since, each with the last
+ * frame arrival at its send. Only a turn that ends on a checkpoint of its own
+ * moves `checkpointed` into `held`.
+ */
+export type RunHistoryImages = {
+    held: readonly string[];
+    checkpointed: string[];
+    sent: Array<{
+        hash: string;
+        afterArrival: number;
+    }>;
+};
+export declare function checkpointFingerprint(checkpoint: Uint8Array): string;
+/** The images `checkpoint` is known to hold. */
+export declare function heldHistoryImageHashes(sessionKey: string, conversationId: string, checkpoint: Uint8Array): ReadonlySet<string> | undefined;
+export declare function runHistoryImages(held?: ReadonlySet<string>): RunHistoryImages;
+/** `lastArrival`: the last frame arrival once the images are written. */
+export declare function noteHistoryImagesSent(run: RunHistoryImages, hashes: readonly string[], lastArrival?: number): void;
+/**
+ * Cursor's checkpoints extend the one the Run started on, so each holds at least what that one held.
+ * A checkpoint that arrived before images were written (read only after a host tool's result) holds none of them.
+ */
+export declare function noteHistoryImageCheckpoint(run: RunHistoryImages, sessionKey: string, conversationId: string, checkpoint: Uint8Array, arrival?: number): void;
+/**
+ * The turn ended. On a checkpoint of its own, that checkpoint holds what the Run
+ * sent before it; without one, nothing the Run sent counts as held.
+ */
+export declare function confirmHistoryImagesAtTurnEnd(run: RunHistoryImages, sessionKey: string, conversationId: string, checkpoint: Uint8Array | undefined): void;
+/** For the restart snapshot: the set the checkpoint being saved holds. */
+export declare function heldHistoryImagesSnapshot(sessionKey: string, conversationId: string, checkpoint: Uint8Array | undefined): {
+    checkpoint: string;
+    hashes: string[];
+} | undefined;
+export declare function restoreHeldHistoryImages(sessionKey: string, conversationId: string, saved: {
+    checkpoint?: string;
+    hashes?: readonly string[];
+}): void;
+export declare function forgetHeldHistoryImages(sessionKey: string): void;
+export declare function snapshotHeldHistoryImagesForTests(sessionKey: string): HeldImages[];
+export declare function resetHeldHistoryImagesForTests(): void;
+export {};

package/dist/protocol/sent-history-images.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+// Content hashes of the history images a session's Cursor conversation holds, so
+// growing history does not re-upload old screenshots. Each set belongs to one
+// checkpoint: a Run skips an image only when it sends exactly that checkpoint.
+/** Mirrors MAX_TURN_STATE_SESSIONS. */
+const MAX_SESSIONS = 256;
+const MAX_IMAGES_PER_SESSION = 256;
+/** A stopped or failed turn leaves the next Run on one of its intermediate checkpoints. */
+const MAX_CHECKPOINTS_PER_SESSION = 32;
+/** Newest first. */
+const heldBySession = new Map();
+export function checkpointFingerprint(checkpoint) {
+    return createHash("sha256").update(checkpoint).digest("hex");
+}
+function newest(hashes) {
+    const unique = [...new Set([...hashes].reverse())].reverse();
+    return unique.slice(Math.max(0, unique.length - MAX_IMAGES_PER_SESSION));
+}
+function touch(sessionKey, entries) {
+    heldBySession.delete(sessionKey);
+    if (entries.length === 0)
+        return;
+    heldBySession.set(sessionKey, entries.slice(0, MAX_CHECKPOINTS_PER_SESSION));
+    while (heldBySession.size > MAX_SESSIONS) {
+        const oldest = heldBySession.keys().next().value;
+        if (!oldest)
+            break;
+        heldBySession.delete(oldest);
+    }
+}
+function find(sessionKey, conversationId, checkpoint) {
+    const entries = heldBySession.get(sessionKey);
+    if (!entries)
+        return undefined;
+    const fingerprint = checkpointFingerprint(checkpoint);
+    return entries.find((entry) => entry.conversationId === conversationId && entry.checkpoint === fingerprint);
+}
+/** The images `checkpoint` is known to hold. */
+export function heldHistoryImageHashes(sessionKey, conversationId, checkpoint) {
+    const entry = find(sessionKey, conversationId, checkpoint);
+    if (!entry)
+        return undefined;
+    touch(sessionKey, heldBySession.get(sessionKey));
+    return new Set(entry.hashes);
+}
+function recordHeldHistoryImages(sessionKey, conversationId, checkpoint, hashes) {
+    if (hashes.length === 0)
+        return;
+    const entry = { conversationId, checkpoint: checkpointFingerprint(checkpoint), hashes };
+    const others = (heldBySession.get(sessionKey) ?? [])
+        .filter((other) => other.conversationId !== conversationId || other.checkpoint !== entry.checkpoint);
+    touch(sessionKey, [entry, ...others]);
+}
+export function runHistoryImages(held) {
+    return { held: [...(held ?? [])], checkpointed: [], sent: [] };
+}
+/** `lastArrival`: the last frame arrival once the images are written. */
+export function noteHistoryImagesSent(run, hashes, lastArrival = 0) {
+    run.sent.push(...hashes.map((hash) => ({ hash, afterArrival: lastArrival })));
+}
+/**
+ * Cursor's checkpoints extend the one the Run started on, so each holds at least what that one held.
+ * A checkpoint that arrived before images were written (read only after a host tool's result) holds none of them.
+ */
+export function noteHistoryImageCheckpoint(run, sessionKey, conversationId, checkpoint, arrival = Infinity) {
+    const later = run.sent.findIndex((image) => image.afterArrival >= arrival);
+    const earlier = later < 0 ? run.sent.length : later;
+    run.checkpointed.push(...run.sent.slice(0, earlier).map((image) => image.hash));
+    run.sent = run.sent.slice(earlier);
+    recordHeldHistoryImages(sessionKey, conversationId, checkpoint, run.held);
+}
+/**
+ * The turn ended. On a checkpoint of its own, that checkpoint holds what the Run
+ * sent before it; without one, nothing the Run sent counts as held.
+ */
+export function confirmHistoryImagesAtTurnEnd(run, sessionKey, conversationId, checkpoint) {
+    if (checkpoint?.length) {
+        run.held = newest([...run.held, ...run.checkpointed]);
+        recordHeldHistoryImages(sessionKey, conversationId, checkpoint, run.held);
+    }
+    run.checkpointed = [];
+    run.sent = [];
+}
+/** For the restart snapshot: the set the checkpoint being saved holds. */
+export function heldHistoryImagesSnapshot(sessionKey, conversationId, checkpoint) {
+    const entry = checkpoint?.length ? find(sessionKey, conversationId, checkpoint) : undefined;
+    return entry ? { checkpoint: entry.checkpoint, hashes: [...entry.hashes] } : undefined;
+}
+export function restoreHeldHistoryImages(sessionKey, conversationId, saved) {
+    touch(sessionKey, saved.checkpoint && saved.hashes?.length
+        ? [{ conversationId, checkpoint: saved.checkpoint, hashes: newest(saved.hashes) }]
+        : []);
+}
+export function forgetHeldHistoryImages(sessionKey) {
+    heldBySession.delete(sessionKey);
+}
+export function snapshotHeldHistoryImagesForTests(sessionKey) {
+    return (heldBySession.get(sessionKey) ?? []).map((entry) => ({ ...entry, hashes: [...entry.hashes] }));
+}
+export function resetHeldHistoryImagesForTests() {
+    heldBySession.clear();
+}

package/dist/protocol/tool-call-bridge.d.ts

@@ -77,3 +77,5 @@ export declare function extractProtobufSubmessage(buf: Uint8Array, path: number[
  * can correlate display tool_call_started with the authoritative exec path.
  */
 export declare function extractExecDisplayCallId(execMsg: Record<string, unknown>): string | undefined;
+/** File paths a display TaskToolCall attaches; Cursor reads each one before its subagent request. */
+export declare function taskToolCallAttachments(toolCall: Record<string, unknown> | undefined): string[];

package/dist/protocol/tool-call-bridge.js

@@ -731,3 +731,13 @@ export function extractExecDisplayCallId(execMsg) {
     }
     return undefined;
 }
+/** File paths a display TaskToolCall attaches; Cursor reads each one before its subagent request. */
+export function taskToolCallAttachments(toolCall) {
+    if (!toolCall || findToolVariant(toolCall) !== "task_tool_call")
+        return [];
+    const payload = asRecord(toolCall.task_tool_call);
+    const attachments = payload ? unwrapArgs(payload).attachments : undefined;
+    if (!Array.isArray(attachments))
+        return [];
+    return attachments.filter((item) => typeof item === "string" && item.trim().length > 0);
+}

package/dist/protocol/tools.d.ts

@@ -1,3 +1,4 @@
+import type { HookAdditionalContext } from "./host-notes.js";
 import type { CursorImageInput } from "../image-input.js";
 import { type CursorExecVariant } from "./exec-variants.js";
 import { type CursorShellOutcome } from "../shell-timeout.js";
@@ -124,6 +125,30 @@ export declare function resolveCursorSubagentType(subagentType: string, catalog?
 export declare function mapCursorSubagentTypeToOpenCode(subagentType: string): string;
 /** Resolve a native Cursor subagent request to this turn's executor and catalog. */
 export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, catalog?: HostSubagentCatalog): void;
+/**
+ * Who answers the private read Cursor sends under an edit's call id. Both the
+ * exec handler and the early tool row decide from this, so a row never opens
+ * for an edit whose read becomes its own host call.
+ *
+ * - `empty`: no target. The provider answers an empty file; creation continues.
+ * - `complete`: a readable regular file within Cursor's edit limit whose real
+ *   path is inside the workspace. The provider answers its complete content.
+ * - `external`: an existing target not proven inside the workspace by real
+ *   path, including through a symlink rooted in it. OpenCode's
+ *   permission-aware `read` answers; once authorized, the continuation
+ *   upgrades the result to the complete content.
+ * - `host`: any other existing target (not a regular file, too large,
+ *   unreadable, or not stat-able). OpenCode's `read` answers as is.
+ */
+export type CursorEditReadAnswer = "empty" | "complete" | "external" | "host";
+export declare function cursorEditReadAnswer(absolutePath: string, workspaceRoot: string): CursorEditReadAnswer;
+/**
+ * The edit's private read becomes its own host `read` call. A read the edit
+ * handshake leaves to the host can still be answered by the provider's
+ * missing-target validation (a dangling symlink, a directory); that read
+ * never reaches the host.
+ */
+export declare function cursorEditReadReachesHost(absolutePath: string, workspaceRoot: string): boolean;
 /**
  * Complete the private read inside Cursor's legacy edit transaction without
  * routing it through OpenCode's user-facing `read` tool. The latter caps every
@@ -134,6 +159,28 @@ export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest,
  * file named by an active `edit_tool_call` and is contained by the workspace.
  */
 export declare function buildCompleteEditReadMessages(execId: number, sourcePath: string, resultPath?: string): Uint8Array[] | undefined;
+/**
+ * Answer Cursor's read of a Task attachment without the file's bytes. Cursor
+ * puts them only in SubagentArgs.selected_context, which OpenCode's subagent
+ * tools cannot take, yet refuses the Task unless the read returns binary data.
+ * The path reaches the subagent prompt instead ({@link appendTaskAttachments})
+ * and the child reads it under its own permissions. A missing or non-regular
+ * target gets the same typed rejection as any native read.
+ */
+export declare function buildTaskAttachmentReadMessages(execId: number, sourcePath: string, resultPath?: string): Uint8Array[];
+/** List Cursor's Task attachments at the end of the subagent prompt as absolute paths. */
+export declare function appendTaskAttachments(parsed: ParsedExecRequest, attachments: readonly string[], workspaceRoot: string): void;
+/**
+ * Host tool a Cursor edit announcement will become, using the same file facts
+ * as `remapCorrelatedEditWriteForCatalog` and `remapEditToolsForCatalog`. An
+ * existing file becomes `edit`, else the patch tool. A missing file is a
+ * creation, which stays `write`, else becomes the patch tool's Add File; so
+ * does an empty file, which has no text for an `edit` to replace. A name is
+ * withheld when those remaps would refuse the file or not produce that tool:
+ * no workspace for a relative path, not a regular file, too large,
+ * unreadable, or `patch` with carriage returns.
+ */
+export declare function hostToolForCursorEdit(filePath: string, catalog: ReadonlySet<string>, workspaceRoot?: string): string | undefined;
 /**
  * Preserve a legacy Cursor edit's intent when its internal executor follows
  * `edit_tool_call` with a whole-file `write_args` request.
@@ -143,19 +190,19 @@ export declare function buildCompleteEditReadMessages(execId: number, sourcePath
  */
 export declare function remapCorrelatedEditWriteForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, editPath: string, workspaceRoot?: string): boolean;
 /**
- * Express a native Cursor write/edit as `apply_patch` when the host swapped the
+ * Express a native Cursor write/edit as a patch call when the host swapped the
  * edit-tool family out from under us.
  *
- * OpenCode 1.x removes `edit` and `write` from the catalog for GPT models and
- * advertises `apply_patch` in their place — see the module comment in
- * `./apply-patch.ts` for the upstream reasoning and citations. Cursor keeps
- * using its native write/edit exec channel regardless, so without this the
- * request is refused as an unavailable tool and the model loses the ability to
- * change files at all.
+ * Both OpenCode majors remove `edit` and `write` from the catalog for GPT
+ * models and advertise a patch tool in their place (`apply_patch` on 1.x,
+ * `patch` on 2.0) — see the module comment in `./apply-patch.ts` for the
+ * upstream reasoning and citations. Cursor keeps using its native write/edit
+ * exec channel regardless, so without this the request is refused as an
+ * unavailable tool.
  *
  * Keyed purely off the advertised set: this is inert whenever the host offers
  * `write`/`edit` normally, and equally inert when it offers neither those nor
- * `apply_patch` (the caller's unavailable-tool rejection still applies).
+ * a patch tool (the caller's unavailable-tool rejection still applies).
  */
 export declare function remapEditToolsForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, workspaceRoot?: string): void;
 export type ParsedExecRequest = {
@@ -268,6 +315,8 @@ export type ToolResultInput = {
     resultField: string;
     output: string;
     error?: string;
+    refusal?: "permission_denied" | "rejected";
+    interrupted?: boolean;
     executionTimeMs?: number;
     /**
      * Resolved opencode tool name (read/write/grep/…). Gates read-envelope
@@ -304,6 +353,16 @@ export declare function execResultImages(resultField: string, images: readonly C
  * shell execs hang on heartbeats forever).
  */
 export declare function buildExecClientMessages(input: ToolResultInput): Uint8Array[];
+/**
+ * Attach host notes to an exec result as Cursor CLI postToolUse hook context:
+ * `ExecClientMessage.hook_additional_contexts` (#45) on a unary result, or a
+ * `ShellStream.hook_context` (#8) event after the stream's own events and
+ * before `stream_close` (CLI agent-exec hook wrapper). Cursor renders it as a
+ * system reminder on that tool result, so it never mixes into file content.
+ * Returns undefined when the frames carry no exec result (bridged
+ * interaction replies have no such field).
+ */
+export declare function attachHookAdditionalContexts(frames: readonly Uint8Array[], contexts: readonly HookAdditionalContext[]): Uint8Array[] | undefined;
 /** ACM #5 exec_client_control_message { stream_close { id } }. */
 export declare function buildExecStreamClose(execId: number): Uint8Array;
 export declare function buildUnsupportedExecDeny(input: {
@@ -331,6 +390,13 @@ export declare function buildUnsupportedExecDeny(input: {
  * alone is not a tool-identity check.
  */
 export declare function unwrapReadOutput(output: string): string;
+/**
+ * OpenCode's read tool appends newly discovered instructions after the
+ * envelope's unnumbered `</content>`, in one `<system-reminder>` block.
+ * The numbered-body parser stops before that block, so callers must lift it
+ * out before the file text is encoded.
+ */
+export declare function extractOpenCodeReadInstruction(output: string): string | undefined;
 /**
  * Map OpenCode tool text into the agent.v1 result oneof for each exec variant.
  * OpenCode returns free-form text; we wrap it in the minimal success shape the