@aryee337/aery-ai 0.2.27 → 0.2.29

package/src/providers/cursor.ts

@@ -0,0 +1,2621 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import http2 from "node:http2";
+import { $env, extractHttpStatusFromError, sanitizeText } from "@aryee337/aery-utils";
+import { create, fromBinary, fromJson, type JsonValue, toBinary, toJson } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import { calculateCost } from "../models";
+import type {
+	Api,
+	AssistantMessage,
+	Context,
+	CursorExecHandlerResult,
+	CursorExecHandlers,
+	CursorMcpCall,
+	CursorShellStreamCallbacks,
+	CursorToolResultHandler,
+	ImageContent,
+	Message,
+	Model,
+	StreamFunction,
+	StreamOptions,
+	TextContent,
+	ThinkingContent,
+	Tool,
+	ToolCall,
+	ToolResultMessage,
+} from "../types";
+import { normalizeSystemPrompts } from "../utils";
+import { AssistantMessageEventStream } from "../utils/event-stream";
+import { parseStreamingJson } from "../utils/json-parse";
+import { createRequestDebugSession, isRequestDebugEnabled, type RequestDebugResponseLog } from "../utils/request-debug";
+import { formatErrorMessageWithRetryAfter } from "../utils/retry-after";
+import { toolWireSchema } from "../utils/schema/wire";
+import type { McpToolDefinition } from "./cursor/gen/agent_pb";
+import {
+	AgentClientMessageSchema,
+	AgentConversationTurnStructureSchema,
+	AgentRunRequestSchema,
+	type AgentServerMessage,
+	AgentServerMessageSchema,
+	AssistantMessageSchema,
+	BackgroundShellSpawnResultSchema,
+	ClientHeartbeatSchema,
+	ComputerUseResultSchema,
+	ConversationActionSchema,
+	type ConversationStateStructure,
+	ConversationStateStructureSchema,
+	ConversationStepSchema,
+	ConversationTurnStructureSchema,
+	DeleteErrorSchema,
+	DeleteRejectedSchema,
+	DeleteResultSchema,
+	DeleteSuccessSchema,
+	DiagnosticsErrorSchema,
+	DiagnosticsRejectedSchema,
+	DiagnosticsResultSchema,
+	DiagnosticsSuccessSchema,
+	ExecClientControlMessageSchema,
+	type ExecClientMessage,
+	ExecClientMessageSchema,
+	ExecClientStreamCloseSchema,
+	type ExecServerMessage,
+	FetchErrorSchema,
+	FetchResultSchema,
+	GetBlobResultSchema,
+	GrepContentMatchSchema,
+	GrepContentResultSchema,
+	GrepCountResultSchema,
+	GrepErrorSchema,
+	type GrepFileCount,
+	GrepFileCountSchema,
+	GrepFileMatchSchema,
+	GrepFilesResultSchema,
+	GrepResultSchema,
+	GrepSuccessSchema,
+	type GrepUnionResult,
+	GrepUnionResultSchema,
+	KvClientMessageSchema,
+	type KvServerMessage,
+	ListMcpResourcesExecResultSchema,
+	type LsDirectoryTreeNode,
+	type LsDirectoryTreeNode_File,
+	LsDirectoryTreeNode_FileSchema,
+	LsDirectoryTreeNodeSchema,
+	LsErrorSchema,
+	LsRejectedSchema,
+	LsResultSchema,
+	LsSuccessSchema,
+	McpErrorSchema,
+	McpImageContentSchema,
+	McpResultSchema,
+	McpSuccessSchema,
+	McpTextContentSchema,
+	McpToolDefinitionSchema,
+	McpToolNotFoundSchema,
+	McpToolResultContentItemSchema,
+	ModelDetailsSchema,
+	ReadErrorSchema,
+	ReadMcpResourceExecResultSchema,
+	ReadRejectedSchema,
+	ReadResultSchema,
+	ReadSuccessSchema,
+	RecordScreenResultSchema,
+	RequestContextResultSchema,
+	RequestContextSchema,
+	RequestContextSuccessSchema,
+	ResumeActionSchema,
+	SelectedContextSchema,
+	SelectedImageSchema,
+	SetBlobResultSchema,
+	type ShellArgs,
+	ShellFailureSchema,
+	ShellRejectedSchema,
+	type ShellResult,
+	ShellResultSchema,
+	type ShellStream,
+	ShellStreamExitSchema,
+	ShellStreamSchema,
+	ShellStreamStartSchema,
+	ShellStreamStderrSchema,
+	ShellStreamStdoutSchema,
+	ShellSuccessSchema,
+	UserMessageActionSchema,
+	UserMessageSchema,
+	WriteErrorSchema,
+	WriteRejectedSchema,
+	WriteResultSchema,
+	WriteShellStdinErrorSchema,
+	WriteShellStdinResultSchema,
+	WriteSuccessSchema,
+} from "./cursor/gen/agent_pb";
+
+export const CURSOR_API_URL = "https://api2.cursor.sh";
+export const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
+
+const conversationStateCache = new Map<string, ConversationStateStructure>();
+const conversationBlobStores = new Map<string, Map<string, Uint8Array>>();
+
+export interface CursorOptions extends StreamOptions {
+	customSystemPrompt?: string;
+	conversationId?: string;
+	execHandlers?: CursorExecHandlers;
+	onToolResult?: CursorToolResultHandler;
+}
+
+const CONNECT_END_STREAM_FLAG = 0b00000010;
+
+interface CursorLogEntry {
+	ts: number;
+	type: string;
+	subtype?: string;
+	data?: unknown;
+}
+
+async function appendCursorDebugLog(entry: CursorLogEntry): Promise<void> {
+	const logPath = $env.DEBUG_CURSOR_LOG;
+	if (!logPath) return;
+	try {
+		await fs.appendFile(logPath, `${JSON.stringify(entry, debugReplacer)}\n`);
+	} catch {
+		// Ignore debug log failures
+	}
+}
+
+function log(type: string, subtype?: string, data?: unknown): void {
+	if (!$env.DEBUG_CURSOR) return;
+	const normalizedData = data ? decodeLogData(data) : data;
+	const entry: CursorLogEntry = { ts: Date.now(), type, subtype, data: normalizedData };
+	const verbose = $env.DEBUG_CURSOR === "2" || $env.DEBUG_CURSOR === "verbose";
+	const dataStr = verbose && normalizedData ? ` ${JSON.stringify(normalizedData, debugReplacer)?.slice(0, 500)}` : "";
+	console.error(`[CURSOR] ${type}${subtype ? `: ${subtype}` : ""}${dataStr}`);
+	void appendCursorDebugLog(entry);
+}
+
+function frameConnectMessage(data: Uint8Array, flags = 0): Buffer {
+	const frame = Buffer.alloc(5 + data.length);
+	frame[0] = flags;
+	frame.writeUInt32BE(data.length, 1);
+	frame.set(data, 5);
+	return frame;
+}
+
+function parseConnectEndStream(data: Uint8Array): Error | null {
+	try {
+		const payload = JSON.parse(new TextDecoder().decode(data));
+		const error = payload?.error;
+		if (error) {
+			const code = typeof error.code === "string" ? error.code : "unknown";
+			const message = typeof error.message === "string" ? error.message : "Unknown error";
+			return new Error(`Connect error ${code}: ${message}`);
+		}
+		return null;
+	} catch {
+		return new Error("Failed to parse Connect end stream");
+	}
+}
+
+function debugBytes(bytes: Uint8Array, asHex: boolean): string {
+	if (asHex) {
+		return Buffer.from(bytes).toString("hex");
+	}
+	try {
+		const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		if (/^[\x20-\x7E\s]*$/.test(text)) return text;
+	} catch {}
+	return Buffer.from(bytes).toString("hex");
+}
+
+function debugReplacer(key: string, value: unknown): unknown {
+	if (
+		value instanceof Uint8Array ||
+		(value && typeof value === "object" && "type" in value && value.type === "Buffer")
+	) {
+		const bytes = value instanceof Uint8Array ? value : new Uint8Array((value as any).data);
+		const asHex = key === "blobId" || key === "blob_id" || key.endsWith("Id") || key.endsWith("_id");
+		return debugBytes(bytes, asHex);
+	}
+	if (typeof value === "bigint") return value.toString();
+	return value;
+}
+
+function extractLogBytes(value: unknown): Uint8Array | null {
+	if (value instanceof Uint8Array) {
+		return value;
+	}
+	if (value && typeof value === "object" && "type" in value && value.type === "Buffer") {
+		const data = (value as { data?: number[] }).data;
+		if (Array.isArray(data)) {
+			return new Uint8Array(data);
+		}
+	}
+	return null;
+}
+
+function decodeMcpArgsForLog(args?: Record<string, unknown>): Record<string, unknown> | undefined {
+	if (!args) {
+		return undefined;
+	}
+	let mutated = false;
+	const decoded: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(args)) {
+		const bytes = extractLogBytes(value);
+		if (bytes) {
+			decoded[key] = decodeMcpArgValue(bytes);
+			mutated = true;
+			continue;
+		}
+		const normalizedValue = decodeLogData(value);
+		decoded[key] = normalizedValue;
+		if (normalizedValue !== value) {
+			mutated = true;
+		}
+	}
+	return mutated ? decoded : args;
+}
+
+function decodeLogData(value: unknown): unknown {
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+	if (Array.isArray(value)) {
+		return value.map(entry => decodeLogData(entry));
+	}
+	const record = value as Record<string, unknown>;
+	const typeName = record.$typeName;
+	const stripTypeName = typeof typeName === "string" && typeName.startsWith("agent.v1.");
+
+	if (typeName === "agent.v1.McpArgs") {
+		const decodedArgs = decodeMcpArgsForLog(record.args as Record<string, unknown> | undefined);
+		const base = stripTypeName ? omitTypeName(record) : record;
+		return decodedArgs ? { ...base, args: decodedArgs } : base;
+	}
+	if (typeName === "agent.v1.McpToolCall") {
+		const argsRecord = record.args as Record<string, unknown> | undefined;
+		const decodedArgs = decodeMcpArgsForLog(argsRecord?.args as Record<string, unknown> | undefined);
+		const base = stripTypeName ? omitTypeName(record) : record;
+		if (decodedArgs && argsRecord) {
+			return { ...base, args: { ...argsRecord, args: decodedArgs } };
+		}
+		return base;
+	}
+
+	let mutated = stripTypeName;
+	const decoded: Record<string, unknown> = {};
+	for (const [key, entry] of Object.entries(record)) {
+		if (stripTypeName && key === "$typeName") {
+			continue;
+		}
+		const normalizedEntry = decodeLogData(entry);
+		decoded[key] = normalizedEntry;
+		if (normalizedEntry !== entry) {
+			mutated = true;
+		}
+	}
+	return mutated ? decoded : record;
+}
+
+function omitTypeName(record: Record<string, unknown>): Record<string, unknown> {
+	const { $typeName: _, ...rest } = record;
+	return rest;
+}
+
+export const streamCursor: StreamFunction<"cursor-agent"> = (
+	model: Model<"cursor-agent">,
+	context: Context,
+	options?: CursorOptions,
+): AssistantMessageEventStream => {
+	const stream = new AssistantMessageEventStream();
+
+	(async () => {
+		const startTime = Date.now();
+		let firstTokenTime: number | undefined;
+
+		const output: AssistantMessage = {
+			role: "assistant",
+			content: [],
+			api: "cursor-agent" as Api,
+			provider: model.provider,
+			model: model.id,
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: Date.now(),
+		};
+
+		let h2Client: http2.ClientHttp2Session | null = null;
+		let h2Request: http2.ClientHttp2Stream | null = null;
+		let heartbeatTimer: NodeJS.Timeout | null = null;
+		let debugResponseLogPromise: Promise<RequestDebugResponseLog | undefined> | undefined;
+
+		try {
+			const apiKey = options?.apiKey;
+			if (!apiKey) {
+				throw new Error("Cursor API key (access token) is required");
+			}
+
+			const conversationId = options?.conversationId ?? options?.sessionId ?? crypto.randomUUID();
+			const blobStore = conversationBlobStores.get(conversationId) ?? new Map<string, Uint8Array>();
+			conversationBlobStores.set(conversationId, blobStore);
+			const cachedState = conversationStateCache.get(conversationId);
+			const { requestBytes, conversationState } = buildGrpcRequest(model, context, options, {
+				conversationId,
+				blobStore,
+				conversationState: cachedState,
+			});
+			conversationStateCache.set(conversationId, conversationState);
+			const requestContextTools = buildMcpToolDefinitions(context.tools);
+
+			const baseUrl = model.baseUrl || CURSOR_API_URL;
+			const requestPath = "/agent.v1.AgentService/Run";
+			const requestHeaders = {
+				":method": "POST",
+				":path": requestPath,
+				"content-type": "application/connect+proto",
+				"connect-protocol-version": "1",
+				te: "trailers",
+				authorization: `Bearer ${apiKey}`,
+				"x-ghost-mode": "true",
+				"x-cursor-client-version": CURSOR_CLIENT_VERSION,
+				"x-cursor-client-type": "cli",
+				"x-request-id": crypto.randomUUID(),
+			};
+			const debugSession = isRequestDebugEnabled()
+				? await createRequestDebugSession({
+						protocol: "http2",
+						method: "POST",
+						url: new URL(requestPath, baseUrl).toString(),
+						headers: requestHeaders,
+						bodyBase64: Buffer.from(requestBytes).toString("base64"),
+					})
+				: undefined;
+
+			h2Client = http2.connect(baseUrl);
+
+			h2Request = h2Client.request(requestHeaders);
+
+			stream.push({ type: "start", partial: output });
+
+			let pendingBuffer = Buffer.alloc(0);
+			let endStreamError: Error | null = null;
+			let currentTextBlock: (TextContent & { index: number }) | null = null;
+			let currentThinkingBlock: (ThinkingContent & { index: number }) | null = null;
+			let currentToolCall: ToolCallState | null = null;
+			const usageState: UsageState = { sawTokenDelta: false };
+
+			const state: BlockState = {
+				get currentTextBlock() {
+					return currentTextBlock;
+				},
+				get currentThinkingBlock() {
+					return currentThinkingBlock;
+				},
+				get currentToolCall() {
+					return currentToolCall;
+				},
+				get firstTokenTime() {
+					return firstTokenTime;
+				},
+				setTextBlock: b => {
+					currentTextBlock = b;
+				},
+				setThinkingBlock: b => {
+					currentThinkingBlock = b;
+				},
+				setToolCall: t => {
+					currentToolCall = t;
+				},
+				setFirstTokenTime: () => {
+					if (!firstTokenTime) firstTokenTime = Date.now();
+				},
+			};
+
+			const onConversationCheckpoint = (checkpoint: ConversationStateStructure) => {
+				conversationStateCache.set(conversationId, checkpoint);
+			};
+
+			let resolveH2: (() => void) | undefined;
+
+			h2Request.on("response", headers => {
+				debugResponseLogPromise = debugSession?.openResponseLog(
+					`HTTP/2 ${headers[":status"] ?? ""}`.trim(),
+					headers,
+				);
+			});
+
+			h2Request.on("data", (chunk: Buffer) => {
+				if (debugResponseLogPromise) {
+					void debugResponseLogPromise.then(log => {
+						log?.write(chunk);
+					});
+				}
+				pendingBuffer = Buffer.concat([pendingBuffer, chunk]);
+
+				while (pendingBuffer.length >= 5) {
+					const flags = pendingBuffer[0];
+					const msgLen = pendingBuffer.readUInt32BE(1);
+					if (pendingBuffer.length < 5 + msgLen) break;
+
+					const messageBytes = pendingBuffer.subarray(5, 5 + msgLen);
+					pendingBuffer = pendingBuffer.subarray(5 + msgLen);
+
+					if (flags & CONNECT_END_STREAM_FLAG) {
+						const endError = parseConnectEndStream(messageBytes);
+						if (endError) {
+							endStreamError = endError;
+							h2Request?.close();
+						}
+						continue;
+					}
+
+					try {
+						const serverMessage = fromBinary(AgentServerMessageSchema, messageBytes);
+						const isTurnEnded =
+							serverMessage.message.case === "interactionUpdate" &&
+							serverMessage.message.value.message?.case === "turnEnded";
+						void handleServerMessage(
+							serverMessage,
+							output,
+							stream,
+							state,
+							blobStore,
+							h2Request!,
+							options?.execHandlers,
+							options?.onToolResult,
+							usageState,
+							requestContextTools,
+							onConversationCheckpoint,
+						).catch(error => {
+							log("error", "handleServerMessage", { error: String(error) });
+						});
+
+						// Resolve only on explicit turnEnded. stopReason defaults to "stop"
+						// and is not a reliable signal for stream completion.
+						if (isTurnEnded && resolveH2) {
+							const r = resolveH2;
+							resolveH2 = undefined;
+							r();
+						}
+					} catch (e) {
+						log("error", "parseServerMessage", { error: String(e) });
+					}
+				}
+			});
+
+			h2Request.write(frameConnectMessage(requestBytes));
+
+			const sendHeartbeat = () => {
+				if (!h2Request || h2Request.closed) {
+					return;
+				}
+				const heartbeatMessage = create(AgentClientMessageSchema, {
+					message: { case: "clientHeartbeat", value: create(ClientHeartbeatSchema, {}) },
+				});
+				const heartbeatBytes = toBinary(AgentClientMessageSchema, heartbeatMessage);
+				h2Request.write(frameConnectMessage(heartbeatBytes));
+			};
+
+			heartbeatTimer = setInterval(sendHeartbeat, 5000);
+
+			await new Promise<void>((resolve, reject) => {
+				resolveH2 = resolve;
+
+				const closeDebugLog = async (): Promise<void> => {
+					const log = await debugResponseLogPromise;
+					await log?.close();
+				};
+
+				h2Request!.on("trailers", trailers => {
+					const status = trailers["grpc-status"];
+					const msg = trailers["grpc-message"];
+					if (status && status !== "0") {
+						void closeDebugLog().finally(() => {
+							reject(new Error(`gRPC error ${status}: ${decodeURIComponent(String(msg || ""))}`));
+						});
+					}
+				});
+
+				h2Request!.on("end", () => {
+					resolveH2 = undefined;
+					void closeDebugLog()
+						.then(() => {
+							if (endStreamError) {
+								reject(endStreamError);
+								return;
+							}
+							resolve();
+						})
+						.catch(reject);
+				});
+
+				h2Request!.on("error", error => {
+					void closeDebugLog().finally(() => reject(error));
+				});
+
+				if (options?.signal) {
+					options.signal.addEventListener("abort", () => {
+						h2Request?.close();
+						void closeDebugLog().finally(() => {
+							reject(new Error("Request was aborted"));
+						});
+					});
+				}
+			});
+
+			if (state.currentTextBlock) {
+				const idx = output.content.indexOf(state.currentTextBlock);
+				stream.push({
+					type: "text_end",
+					contentIndex: idx,
+					content: state.currentTextBlock.text,
+					partial: output,
+				});
+			}
+			if (state.currentThinkingBlock) {
+				const idx = output.content.indexOf(state.currentThinkingBlock);
+				stream.push({
+					type: "thinking_end",
+					contentIndex: idx,
+					content: state.currentThinkingBlock.thinking,
+					partial: output,
+				});
+			}
+			if (state.currentToolCall) {
+				const idx = output.content.indexOf(state.currentToolCall);
+				state.currentToolCall.arguments = parseStreamingJson(state.currentToolCall.partialJson);
+				delete (state.currentToolCall as any).partialJson;
+				delete (state.currentToolCall as any).index;
+				stream.push({
+					type: "toolcall_end",
+					contentIndex: idx,
+					toolCall: state.currentToolCall,
+					partial: output,
+				});
+			}
+
+			calculateCost(model, output.usage);
+
+			output.duration = Date.now() - startTime;
+			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
+			stream.push({
+				type: "done",
+				reason: output.stopReason as "stop" | "length" | "toolUse",
+				message: output,
+			});
+			stream.end();
+		} catch (error) {
+			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
+			output.errorStatus = extractHttpStatusFromError(error);
+			output.errorMessage = formatErrorMessageWithRetryAfter(error);
+			output.duration = Date.now() - startTime;
+			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
+			stream.push({ type: "error", reason: output.stopReason, error: output });
+			stream.end();
+		} finally {
+			const log = await debugResponseLogPromise;
+			await log?.close();
+			if (heartbeatTimer) {
+				clearInterval(heartbeatTimer);
+				heartbeatTimer = null;
+			}
+			h2Request?.close();
+			h2Client?.close();
+		}
+	})();
+
+	return stream;
+};
+
+type ToolCallState = ToolCall & { index: number; partialJson?: string; kind: "mcp" | "todo_write" };
+
+interface BlockState {
+	currentTextBlock: (TextContent & { index: number }) | null;
+	currentThinkingBlock: (ThinkingContent & { index: number }) | null;
+	currentToolCall: ToolCallState | null;
+	firstTokenTime: number | undefined;
+	setTextBlock: (b: (TextContent & { index: number }) | null) => void;
+	setThinkingBlock: (b: (ThinkingContent & { index: number }) | null) => void;
+	setToolCall: (t: ToolCallState | null) => void;
+	setFirstTokenTime: () => void;
+}
+
+interface UsageState {
+	sawTokenDelta: boolean;
+}
+
+async function handleServerMessage(
+	msg: AgentServerMessage,
+	output: AssistantMessage,
+	stream: AssistantMessageEventStream,
+	state: BlockState,
+	blobStore: Map<string, Uint8Array>,
+	h2Request: http2.ClientHttp2Stream,
+	execHandlers: CursorExecHandlers | undefined,
+	onToolResult: CursorToolResultHandler | undefined,
+	usageState: UsageState,
+	requestContextTools: McpToolDefinition[],
+	onConversationCheckpoint?: (checkpoint: ConversationStateStructure) => void,
+): Promise<void> {
+	const msgCase = msg.message.case;
+
+	log("serverMessage", msgCase, msg.message.value);
+
+	if (msgCase === "interactionUpdate") {
+		processInteractionUpdate(msg.message.value, output, stream, state, usageState);
+	} else if (msgCase === "kvServerMessage") {
+		handleKvServerMessage(msg.message.value as KvServerMessage, blobStore, h2Request);
+	} else if (msgCase === "execServerMessage") {
+		await handleExecServerMessage(
+			msg.message.value as ExecServerMessage,
+			h2Request,
+			execHandlers,
+			onToolResult,
+			requestContextTools,
+		);
+	} else if (msgCase === "conversationCheckpointUpdate") {
+		handleConversationCheckpointUpdate(msg.message.value, output, usageState, onConversationCheckpoint);
+	}
+}
+
+function handleKvServerMessage(
+	kvMsg: KvServerMessage,
+	blobStore: Map<string, Uint8Array>,
+	h2Request: http2.ClientHttp2Stream,
+): void {
+	const kvCase = kvMsg.message.case;
+
+	if (kvCase === "getBlobArgs") {
+		const blobId = kvMsg.message.value.blobId;
+		const blobIdKey = Buffer.from(blobId).toString("hex");
+
+		const blobData = blobStore.get(blobIdKey);
+
+		const response = create(KvClientMessageSchema, {
+			id: kvMsg.id,
+			message: {
+				case: "getBlobResult",
+				value: create(GetBlobResultSchema, blobData ? { blobData } : {}),
+			},
+		});
+
+		const kvClientMessage = create(AgentClientMessageSchema, {
+			message: { case: "kvClientMessage", value: response },
+		});
+
+		const responseBytes = toBinary(AgentClientMessageSchema, kvClientMessage);
+		h2Request.write(frameConnectMessage(responseBytes));
+
+		log("kvClient", "getBlobResult", { blobId: blobIdKey.slice(0, 40) });
+	} else if (kvCase === "setBlobArgs") {
+		const { blobId, blobData } = kvMsg.message.value;
+		const blobIdKey = Buffer.from(blobId).toString("hex");
+		blobStore.set(blobIdKey, blobData);
+
+		const response = create(KvClientMessageSchema, {
+			id: kvMsg.id,
+			message: {
+				case: "setBlobResult",
+				value: create(SetBlobResultSchema, {}),
+			},
+		});
+
+		const kvClientMessage = create(AgentClientMessageSchema, {
+			message: { case: "kvClientMessage", value: response },
+		});
+
+		const responseBytes = toBinary(AgentClientMessageSchema, kvClientMessage);
+		h2Request.write(frameConnectMessage(responseBytes));
+
+		log("kvClient", "setBlobResult", { blobId: blobIdKey.slice(0, 40) });
+	}
+}
+
+function sendShellStreamEvent(
+	h2Request: http2.ClientHttp2Stream,
+	execMsg: ExecServerMessage,
+	event: ShellStream["event"],
+): void {
+	sendExecClientMessage(h2Request, execMsg, "shellStream", create(ShellStreamSchema, { event }));
+}
+
+function sanitizeShellExecResult(execResult: ShellResult): ShellResult {
+	const result = execResult.result;
+	if (!result) return execResult;
+
+	switch (result.case) {
+		case "success":
+		case "failure": {
+			const value = result.value;
+			return {
+				...execResult,
+				result: {
+					case: result.case,
+					value: {
+						...value,
+						stdout: value.stdout ? sanitizeText(value.stdout) : value.stdout,
+						stderr: value.stderr ? sanitizeText(value.stderr) : value.stderr,
+					},
+				},
+			} as ShellResult;
+		}
+		default:
+			return execResult;
+	}
+}
+
+async function handleShellStreamArgs(
+	args: ShellArgs,
+	execMsg: ExecServerMessage,
+	h2Request: http2.ClientHttp2Stream,
+	execHandlers: CursorExecHandlers | undefined,
+	onToolResult: CursorToolResultHandler | undefined,
+): Promise<void> {
+	const normalizedWorkingDirectory = args.workingDirectory || process.cwd();
+	const normalizedArgs: ShellArgs = { ...args, workingDirectory: normalizedWorkingDirectory };
+	const startTs = Date.now();
+	log("shellStream", "start", {
+		command: (args as any).command,
+		workingDirectory: normalizedWorkingDirectory,
+		execId: execMsg.execId,
+		hasExecHandlers: !!execHandlers,
+		hasShell: !!execHandlers?.shell,
+		hasShellStream: !!execHandlers?.shellStream,
+	});
+
+	sendShellStreamEvent(h2Request, execMsg, { case: "start", value: create(ShellStreamStartSchema, {}) });
+
+	// Buffer for incomplete ANSI sequences across chunks
+	let stdoutBuffer = "";
+	let stderrBuffer = "";
+
+	const incompleteEscapeRegex = /\x1b(|\[|\[\d*|\[\?|\[\?\d*|\]\d*;?)$/;
+
+	const flushStdout = () => {
+		if (stdoutBuffer) {
+			let safeEnd = stdoutBuffer.length;
+			const match = stdoutBuffer.match(incompleteEscapeRegex);
+			if (match && match[0].length > 0) {
+				safeEnd = stdoutBuffer.length - match[0].length;
+			}
+			const toSend = stdoutBuffer.slice(0, safeEnd);
+			const remaining = stdoutBuffer.slice(safeEnd);
+			if (toSend) {
+				sendShellStreamEvent(h2Request, execMsg, {
+					case: "stdout",
+					value: create(ShellStreamStdoutSchema, { data: sanitizeText(toSend) }),
+				});
+			}
+			stdoutBuffer = remaining;
+		}
+	};
+
+	const flushStderr = () => {
+		if (stderrBuffer) {
+			let safeEnd = stderrBuffer.length;
+			const match = stderrBuffer.match(incompleteEscapeRegex);
+			if (match && match[0].length > 0) {
+				safeEnd = stderrBuffer.length - match[0].length;
+			}
+			const toSend = stderrBuffer.slice(0, safeEnd);
+			const remaining = stderrBuffer.slice(safeEnd);
+			if (toSend) {
+				sendShellStreamEvent(h2Request, execMsg, {
+					case: "stderr",
+					value: create(ShellStreamStderrSchema, { data: sanitizeText(toSend) }),
+				});
+			}
+			stderrBuffer = remaining;
+		}
+	};
+
+	let stdoutFlushTimer: NodeJS.Timeout | null = null;
+	let stderrFlushTimer: NodeJS.Timeout | null = null;
+
+	const scheduleStdoutFlush = () => {
+		if (!stdoutFlushTimer) {
+			stdoutFlushTimer = setTimeout(() => {
+				stdoutFlushTimer = null;
+				flushStdout();
+			}, 100);
+		}
+	};
+
+	const scheduleStderrFlush = () => {
+		if (!stderrFlushTimer) {
+			stderrFlushTimer = setTimeout(() => {
+				stderrFlushTimer = null;
+				flushStderr();
+			}, 100);
+		}
+	};
+
+	const streamCallbacks: CursorShellStreamCallbacks = {
+		onStdout(data: string) {
+			stdoutBuffer += data;
+			if (stdoutBuffer.includes("\n") || stdoutBuffer.length > 4096) {
+				if (stdoutFlushTimer) {
+					clearTimeout(stdoutFlushTimer);
+					stdoutFlushTimer = null;
+				}
+				flushStdout();
+			} else {
+				scheduleStdoutFlush();
+			}
+		},
+		onStderr(data: string) {
+			stderrBuffer += data;
+			if (stderrBuffer.includes("\n") || stderrBuffer.length > 4096) {
+				if (stderrFlushTimer) {
+					clearTimeout(stderrFlushTimer);
+					stderrFlushTimer = null;
+				}
+				flushStderr();
+			} else {
+				scheduleStderrFlush();
+			}
+		},
+	};
+
+	// Prefer the streaming handler — it forwards output chunks in real time.
+	// Falls back to the batch shell handler otherwise.
+	const streamHandler = execHandlers?.shellStream?.bind(execHandlers);
+	const batchHandler = execHandlers?.shell?.bind(execHandlers);
+	const handler = streamHandler ? (shellArgs: ShellArgs) => streamHandler(shellArgs, streamCallbacks) : batchHandler;
+
+	const { execResult } = await resolveExecHandler(
+		args as any,
+		handler as typeof batchHandler,
+		onToolResult,
+		toolResult => buildShellResultFromToolResult(normalizedArgs as any, toolResult),
+		reason =>
+			buildShellRejectedResult((normalizedArgs as any).command, (normalizedArgs as any).workingDirectory, reason),
+		error =>
+			buildShellFailureResult((normalizedArgs as any).command, (normalizedArgs as any).workingDirectory, error),
+	);
+
+	// When using the batch handler (no shellStream), send buffered stdout/stderr
+	// after execution completes. With shellStream these were already sent in real time.
+	const sendBufferedOutput = !streamHandler;
+	const sanitizedExecResult = sanitizeShellExecResult(execResult);
+
+	// Flush any remaining buffered output before sending results
+	if (stdoutFlushTimer) clearTimeout(stdoutFlushTimer);
+	if (stderrFlushTimer) clearTimeout(stderrFlushTimer);
+	flushStdout();
+	flushStderr();
+
+	sendShellStreamExitFromResult(h2Request, execMsg, sanitizedExecResult, sendBufferedOutput);
+	// Cursor can keep the turn pending when it receives only stream deltas.
+	// Send the final structured shellResult as completion acknowledgement.
+	sendExecClientMessage(h2Request, execMsg, "shellResult", sanitizedExecResult);
+	sendExecClientStreamClose(h2Request, execMsg);
+
+	log("shellStream", "done", { elapsed: Date.now() - startTs });
+}
+
+function sendShellStreamExitFromResult(
+	h2Request: http2.ClientHttp2Stream,
+	execMsg: ExecServerMessage,
+	execResult: ShellResult,
+	sendBufferedOutput: boolean,
+): void {
+	const result = execResult.result;
+	switch (result.case) {
+		case "success": {
+			const value = result.value;
+			if (sendBufferedOutput) {
+				if (value.stdout) {
+					sendShellStreamEvent(h2Request, execMsg, {
+						case: "stdout",
+						value: create(ShellStreamStdoutSchema, { data: sanitizeText(value.stdout) }),
+					});
+				}
+				if (value.stderr) {
+					sendShellStreamEvent(h2Request, execMsg, {
+						case: "stderr",
+						value: create(ShellStreamStderrSchema, { data: sanitizeText(value.stderr) }),
+					});
+				}
+			}
+			sendShellStreamEvent(h2Request, execMsg, {
+				case: "exit",
+				value: create(ShellStreamExitSchema, {
+					code: value.exitCode,
+					cwd: value.workingDirectory,
+					aborted: false,
+				}),
+			});
+			return;
+		}
+		case "failure": {
+			const value = result.value;
+			if (sendBufferedOutput) {
+				if (value.stdout) {
+					sendShellStreamEvent(h2Request, execMsg, {
+						case: "stdout",
+						value: create(ShellStreamStdoutSchema, { data: sanitizeText(value.stdout) }),
+					});
+				}
+				if (value.stderr) {
+					sendShellStreamEvent(h2Request, execMsg, {
+						case: "stderr",
+						value: create(ShellStreamStderrSchema, { data: sanitizeText(value.stderr) }),
+					});
+				}
+			}
+			sendShellStreamEvent(h2Request, execMsg, {
+				case: "exit",
+				value: create(ShellStreamExitSchema, {
+					code: value.exitCode,
+					cwd: value.workingDirectory,
+					aborted: value.aborted,
+					abortReason: value.abortReason,
+				}),
+			});
+			return;
+		}
+		case "rejected": {
+			sendShellStreamEvent(h2Request, execMsg, { case: "rejected", value: result.value });
+			sendShellStreamEvent(h2Request, execMsg, {
+				case: "exit",
+				value: create(ShellStreamExitSchema, {
+					code: 1,
+					cwd: result.value.workingDirectory,
+					aborted: false,
+				}),
+			});
+			return;
+		}
+		case "timeout": {
+			const value = result.value;
+			sendShellStreamEvent(h2Request, execMsg, {
+				case: "stderr",
+				value: create(ShellStreamStderrSchema, {
+					data: `Command timed out after ${value.timeoutMs}ms`,
+				}),
+			});
+			sendShellStreamEvent(h2Request, execMsg, {
+				case: "exit",
+				value: create(ShellStreamExitSchema, {
+					code: 1,
+					cwd: value.workingDirectory,
+					aborted: true,
+				}),
+			});
+			return;
+		}
+		case "permissionDenied": {
+			sendShellStreamEvent(h2Request, execMsg, { case: "permissionDenied", value: result.value });
+			sendShellStreamEvent(h2Request, execMsg, {
+				case: "exit",
+				value: create(ShellStreamExitSchema, {
+					code: 1,
+					cwd: result.value.workingDirectory,
+					aborted: false,
+				}),
+			});
+			return;
+		}
+		default:
+			return;
+	}
+}
+
+async function handleExecServerMessage(
+	execMsg: ExecServerMessage,
+	h2Request: http2.ClientHttp2Stream,
+	execHandlers: CursorExecHandlers | undefined,
+	onToolResult: CursorToolResultHandler | undefined,
+	requestContextTools: McpToolDefinition[],
+): Promise<void> {
+	const execCase = execMsg.message.case;
+	log("exec", "dispatch", { execCase, execId: execMsg.execId, hasHandlers: !!execHandlers });
+	if (execCase === "requestContextArgs") {
+		const requestContext = create(RequestContextSchema, {
+			rules: [],
+			repositoryInfo: [],
+			tools: requestContextTools,
+			gitRepos: [],
+			projectLayouts: [],
+			mcpInstructions: [],
+			fileContents: {},
+			customSubagents: [],
+		});
+
+		const requestContextResult = create(RequestContextResultSchema, {
+			result: {
+				case: "success",
+				value: create(RequestContextSuccessSchema, { requestContext }),
+			},
+		});
+
+		sendExecClientMessage(h2Request, execMsg, "requestContextResult", requestContextResult);
+		log("execClient", "requestContextResult");
+		return;
+	}
+
+	if (!execCase) {
+		return;
+	}
+
+	switch (execCase) {
+		case "readArgs": {
+			const args = execMsg.message.value;
+			const { execResult } = await resolveExecHandler(
+				args,
+				execHandlers?.read?.bind(execHandlers),
+				onToolResult,
+				toolResult => buildReadResultFromToolResult(args.path, toolResult),
+				reason => buildReadRejectedResult(args.path, reason),
+				error => buildReadErrorResult(args.path, error),
+			);
+			sendExecClientMessage(h2Request, execMsg, "readResult", execResult);
+			return;
+		}
+		case "lsArgs": {
+			const args = execMsg.message.value;
+			const { execResult } = await resolveExecHandler(
+				args,
+				execHandlers?.ls?.bind(execHandlers),
+				onToolResult,
+				toolResult => buildLsResultFromToolResult(args.path, toolResult),
+				reason => buildLsRejectedResult(args.path, reason),
+				error => buildLsErrorResult(args.path, error),
+			);
+			sendExecClientMessage(h2Request, execMsg, "lsResult", execResult);
+			return;
+		}
+		case "grepArgs": {
+			const args = execMsg.message.value;
+			const { execResult } = await resolveExecHandler(
+				args,
+				execHandlers?.grep?.bind(execHandlers),
+				onToolResult,
+				toolResult => buildGrepResultFromToolResult(args, toolResult),
+				reason => buildGrepErrorResult(reason),
+				error => buildGrepErrorResult(error),
+			);
+			sendExecClientMessage(h2Request, execMsg, "grepResult", execResult);
+			return;
+		}
+		case "writeArgs": {
+			const args = execMsg.message.value;
+			const { execResult } = await resolveExecHandler(
+				args,
+				execHandlers?.write?.bind(execHandlers),
+				onToolResult,
+				toolResult =>
+					buildWriteResultFromToolResult(
+						{
+							path: args.path,
+							fileText: args.fileText,
+							fileBytes: args.fileBytes,
+							returnFileContentAfterWrite: args.returnFileContentAfterWrite,
+						},
+						toolResult,
+					),
+				reason => buildWriteRejectedResult(args.path, reason),
+				error => buildWriteErrorResult(args.path, error),
+			);
+			sendExecClientMessage(h2Request, execMsg, "writeResult", execResult);
+			return;
+		}
+		case "deleteArgs": {
+			const args = execMsg.message.value;
+			const { execResult } = await resolveExecHandler(
+				args,
+				execHandlers?.delete?.bind(execHandlers),
+				onToolResult,
+				toolResult => buildDeleteResultFromToolResult(args.path, toolResult),
+				reason => buildDeleteRejectedResult(args.path, reason),
+				error => buildDeleteErrorResult(args.path, error),
+			);
+			sendExecClientMessage(h2Request, execMsg, "deleteResult", execResult);
+			return;
+		}
+		case "shellArgs": {
+			const args = execMsg.message.value;
+			const normalizedArgs: ShellArgs = { ...args, workingDirectory: args.workingDirectory || process.cwd() };
+			const { execResult } = await resolveExecHandler(
+				args,
+				execHandlers?.shell?.bind(execHandlers),
+				onToolResult,
+				toolResult => buildShellResultFromToolResult(normalizedArgs, toolResult),
+				reason => buildShellRejectedResult(normalizedArgs.command, normalizedArgs.workingDirectory, reason),
+				error => buildShellFailureResult(normalizedArgs.command, normalizedArgs.workingDirectory, error),
+			);
+			const sanitizedExecResult = sanitizeShellExecResult(execResult);
+			sendExecClientMessage(h2Request, execMsg, "shellResult", sanitizedExecResult);
+			return;
+		}
+		case "shellStreamArgs": {
+			const args = execMsg.message.value;
+			await handleShellStreamArgs(args, execMsg, h2Request, execHandlers, onToolResult);
+			return;
+		}
+		case "backgroundShellSpawnArgs": {
+			const args = execMsg.message.value;
+			const execResult = create(BackgroundShellSpawnResultSchema, {
+				result: {
+					case: "rejected",
+					value: create(ShellRejectedSchema, {
+						command: args.command,
+						workingDirectory: args.workingDirectory,
+						reason: "Not implemented",
+						isReadonly: false,
+					}),
+				},
+			});
+			sendExecClientMessage(h2Request, execMsg, "backgroundShellSpawnResult", execResult);
+			return;
+		}
+		case "writeShellStdinArgs": {
+			const execResult = create(WriteShellStdinResultSchema, {
+				result: {
+					case: "error",
+					value: create(WriteShellStdinErrorSchema, {
+						error: "Not implemented",
+					}),
+				},
+			});
+			sendExecClientMessage(h2Request, execMsg, "writeShellStdinResult", execResult);
+			return;
+		}
+		case "fetchArgs": {
+			const args = execMsg.message.value;
+			const execResult = create(FetchResultSchema, {
+				result: {
+					case: "error",
+					value: create(FetchErrorSchema, {
+						url: args.url,
+						error: "Not implemented",
+					}),
+				},
+			});
+			sendExecClientMessage(h2Request, execMsg, "fetchResult", execResult);
+			return;
+		}
+		case "diagnosticsArgs": {
+			const args = execMsg.message.value;
+			const { execResult } = await resolveExecHandler(
+				args,
+				execHandlers?.diagnostics?.bind(execHandlers),
+				onToolResult,
+				toolResult => buildDiagnosticsResultFromToolResult(args.path, toolResult),
+				reason => buildDiagnosticsRejectedResult(args.path, reason),
+				error => buildDiagnosticsErrorResult(args.path, error),
+			);
+			sendExecClientMessage(h2Request, execMsg, "diagnosticsResult", execResult);
+			return;
+		}
+		case "mcpArgs": {
+			const args = execMsg.message.value;
+			const mcpCall = decodeMcpCall(args);
+			const { execResult } = await resolveExecHandler(
+				mcpCall,
+				execHandlers?.mcp?.bind(execHandlers),
+				onToolResult,
+				toolResult => buildMcpResultFromToolResult(mcpCall, toolResult),
+				_reason => buildMcpToolNotFoundResult(mcpCall),
+				error => buildMcpErrorResult(error),
+			);
+			sendExecClientMessage(h2Request, execMsg, "mcpResult", execResult);
+			return;
+		}
+		case "listMcpResourcesExecArgs": {
+			const execResult = create(ListMcpResourcesExecResultSchema, {});
+			sendExecClientMessage(h2Request, execMsg, "listMcpResourcesExecResult", execResult);
+			return;
+		}
+		case "readMcpResourceExecArgs": {
+			const execResult = create(ReadMcpResourceExecResultSchema, {});
+			sendExecClientMessage(h2Request, execMsg, "readMcpResourceExecResult", execResult);
+			return;
+		}
+		case "recordScreenArgs": {
+			const execResult = create(RecordScreenResultSchema, {});
+			sendExecClientMessage(h2Request, execMsg, "recordScreenResult", execResult);
+			return;
+		}
+		case "computerUseArgs": {
+			const execResult = create(ComputerUseResultSchema, {});
+			sendExecClientMessage(h2Request, execMsg, "computerUseResult", execResult);
+			return;
+		}
+		default: {
+			log("warn", "unhandledExecMessage", { execCase });
+			// Send a bare ExecClientMessage (id + execId only, no typed result) so the
+			// server gets an acknowledgement and doesn't hang waiting forever.
+			const ack = create(ExecClientMessageSchema, {
+				id: execMsg.id,
+				execId: execMsg.execId,
+			});
+			const clientMessage = create(AgentClientMessageSchema, {
+				message: { case: "execClientMessage", value: ack },
+			});
+			h2Request.write(frameConnectMessage(toBinary(AgentClientMessageSchema, clientMessage)));
+		}
+	}
+}
+
+function sendExecClientMessage<T>(
+	h2Request: http2.ClientHttp2Stream,
+	execMsg: ExecServerMessage,
+	messageCase: ExecClientMessage["message"]["case"],
+	value: T,
+): void {
+	const execClientMessage = create(ExecClientMessageSchema, {
+		id: execMsg.id,
+		execId: execMsg.execId,
+		message: {
+			case: messageCase,
+			value: value as any,
+		},
+	});
+
+	const clientMessage = create(AgentClientMessageSchema, {
+		message: { case: "execClientMessage", value: execClientMessage },
+	});
+
+	const responseBytes = toBinary(AgentClientMessageSchema, clientMessage);
+	h2Request.write(frameConnectMessage(responseBytes));
+
+	log("execClientMessage", messageCase, value);
+}
+
+function sendExecClientStreamClose(h2Request: http2.ClientHttp2Stream, execMsg: ExecServerMessage): void {
+	const closeMessage = create(ExecClientControlMessageSchema, {
+		message: {
+			case: "streamClose",
+			value: create(ExecClientStreamCloseSchema, {
+				id: execMsg.id,
+			}),
+		},
+	});
+	const clientMessage = create(AgentClientMessageSchema, {
+		message: { case: "execClientControlMessage", value: closeMessage },
+	});
+	const responseBytes = toBinary(AgentClientMessageSchema, clientMessage);
+	h2Request.write(frameConnectMessage(responseBytes));
+	log("execClientControl", "streamClose", { id: execMsg.id, execId: execMsg.execId });
+}
+
+/** Exported for tests: verifies handler is invoked with correct `this` when passed as bound. */
+export async function resolveExecHandler<TArgs, TResult>(
+	args: TArgs,
+	handler: ((args: TArgs) => Promise<CursorExecHandlerResult<TResult>>) | undefined,
+	onToolResult: CursorToolResultHandler | undefined,
+	buildFromToolResult: (toolResult: ToolResultMessage) => TResult,
+	buildRejected: (reason: string) => TResult,
+	buildError: (error: string) => TResult,
+): Promise<{ execResult: TResult; toolResult?: ToolResultMessage }> {
+	if (!handler) {
+		return { execResult: buildRejected("Tool not available") };
+	}
+
+	try {
+		const handlerResult = await handler(args);
+		const { execResult, toolResult } = splitExecHandlerResult(handlerResult);
+		const finalToolResult = await applyToolResultHandler(toolResult, onToolResult);
+
+		if (execResult) {
+			return { execResult, toolResult: finalToolResult };
+		}
+		if (finalToolResult) {
+			return { execResult: buildFromToolResult(finalToolResult), toolResult: finalToolResult };
+		}
+		return { execResult: buildRejected("Tool returned no result") };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { execResult: buildError(message) };
+	}
+}
+
+function splitExecHandlerResult<TResult>(result: CursorExecHandlerResult<TResult>): {
+	execResult?: TResult;
+	toolResult?: ToolResultMessage;
+} {
+	if (isToolResultMessage(result)) {
+		return { toolResult: result };
+	}
+	if (result && typeof result === "object") {
+		const record = result as Record<string, unknown>;
+		if ("execResult" in record) {
+			const { execResult, toolResult } = record as {
+				execResult: TResult;
+				toolResult?: ToolResultMessage;
+			};
+			return { execResult, toolResult };
+		}
+		if ("toolResult" in record && !isToolResultMessage(record)) {
+			const { result: execResult, toolResult } = record as {
+				result?: TResult;
+				toolResult?: ToolResultMessage;
+			};
+			return { execResult, toolResult };
+		}
+		if ("result" in record && !("$typeName" in record)) {
+			const { result: execResult, toolResult } = record as {
+				result: TResult;
+				toolResult?: ToolResultMessage;
+			};
+			return { execResult, toolResult };
+		}
+	}
+	return { execResult: result as TResult };
+}
+
+function isToolResultMessage(value: unknown): value is ToolResultMessage {
+	return !!value && typeof value === "object" && (value as ToolResultMessage).role === "toolResult";
+}
+
+async function applyToolResultHandler(
+	toolResult: ToolResultMessage | undefined,
+	onToolResult: CursorToolResultHandler | undefined,
+): Promise<ToolResultMessage | undefined> {
+	if (!toolResult || !onToolResult) {
+		return toolResult;
+	}
+	const updated = await onToolResult(toolResult);
+	return updated ?? toolResult;
+}
+
+function toolResultToText(toolResult: ToolResultMessage): string {
+	return toolResult.content.map(item => (item.type === "text" ? item.text : `[${item.mimeType} image]`)).join("\n");
+}
+
+function toolResultWasTruncated(toolResult: ToolResultMessage): boolean {
+	if (!toolResult.details || typeof toolResult.details !== "object") {
+		return false;
+	}
+	const truncation = (toolResult.details as { truncation?: { truncated?: boolean } }).truncation;
+	return !!truncation?.truncated;
+}
+
+function toolResultDetailBoolean(toolResult: ToolResultMessage, key: string): boolean {
+	if (!toolResult.details || typeof toolResult.details !== "object") {
+		return false;
+	}
+	const value = (toolResult.details as Record<string, unknown>)[key];
+	return typeof value === "boolean" ? value : false;
+}
+
+function buildReadResultFromToolResult(path: string, toolResult: ToolResultMessage) {
+	const text = toolResultToText(toolResult);
+	if (toolResult.isError) {
+		return buildReadErrorResult(path, text || "Read failed");
+	}
+	const totalLines = text ? text.split("\n").length : 0;
+	return create(ReadResultSchema, {
+		result: {
+			case: "success",
+			value: create(ReadSuccessSchema, {
+				path,
+				totalLines,
+				fileSize: BigInt(Buffer.byteLength(text, "utf-8")),
+				truncated: toolResultWasTruncated(toolResult),
+				output: { case: "content", value: text },
+			}),
+		},
+	});
+}
+
+function buildReadErrorResult(path: string, error: string) {
+	return create(ReadResultSchema, {
+		result: {
+			case: "error",
+			value: create(ReadErrorSchema, { path, error }),
+		},
+	});
+}
+
+function buildReadRejectedResult(path: string, reason: string) {
+	return create(ReadResultSchema, {
+		result: {
+			case: "rejected",
+			value: create(ReadRejectedSchema, { path, reason }),
+		},
+	});
+}
+
+function buildWriteResultFromToolResult(
+	args: { path: string; fileText?: string; fileBytes?: Uint8Array; returnFileContentAfterWrite?: boolean },
+	toolResult: ToolResultMessage,
+) {
+	const text = toolResultToText(toolResult);
+	if (toolResult.isError) {
+		return buildWriteErrorResult(args.path, text || "Write failed");
+	}
+	const fileText = args.fileText ?? "";
+	const fileSize = args.fileBytes?.length ?? Buffer.byteLength(fileText, "utf-8");
+	const linesCreated = fileText ? fileText.split("\n").length : 0;
+	return create(WriteResultSchema, {
+		result: {
+			case: "success",
+			value: create(WriteSuccessSchema, {
+				path: args.path,
+				linesCreated,
+				fileSize,
+				fileContentAfterWrite: args.returnFileContentAfterWrite ? fileText : undefined,
+			}),
+		},
+	});
+}
+
+function buildWriteErrorResult(path: string, error: string) {
+	return create(WriteResultSchema, {
+		result: {
+			case: "error",
+			value: create(WriteErrorSchema, { path, error }),
+		},
+	});
+}
+
+function buildWriteRejectedResult(path: string, reason: string) {
+	return create(WriteResultSchema, {
+		result: {
+			case: "rejected",
+			value: create(WriteRejectedSchema, { path, reason }),
+		},
+	});
+}
+
+function buildDeleteResultFromToolResult(path: string, toolResult: ToolResultMessage) {
+	const text = toolResultToText(toolResult);
+	if (toolResult.isError) {
+		return buildDeleteErrorResult(path, text || "Delete failed");
+	}
+	return create(DeleteResultSchema, {
+		result: {
+			case: "success",
+			value: create(DeleteSuccessSchema, {
+				path,
+				deletedFile: path,
+				fileSize: BigInt(0),
+				prevContent: "",
+			}),
+		},
+	});
+}
+
+function buildDeleteErrorResult(path: string, error: string) {
+	return create(DeleteResultSchema, {
+		result: {
+			case: "error",
+			value: create(DeleteErrorSchema, { path, error }),
+		},
+	});
+}
+
+function buildDeleteRejectedResult(path: string, reason: string) {
+	return create(DeleteResultSchema, {
+		result: {
+			case: "rejected",
+			value: create(DeleteRejectedSchema, { path, reason }),
+		},
+	});
+}
+
+function buildShellResultFromToolResult(
+	args: { command: string; workingDirectory: string },
+	toolResult: ToolResultMessage,
+) {
+	const output = toolResultToText(toolResult);
+	if (toolResult.isError) {
+		return buildShellFailureResult(args.command, args.workingDirectory, output || "Shell failed");
+	}
+	return create(ShellResultSchema, {
+		result: {
+			case: "success",
+			value: create(ShellSuccessSchema, {
+				command: args.command,
+				workingDirectory: args.workingDirectory,
+				exitCode: 0,
+				signal: "",
+				stdout: output,
+				stderr: "",
+				executionTime: 0,
+			}),
+		},
+	});
+}
+
+function buildShellFailureResult(command: string, workingDirectory: string, error: string) {
+	return create(ShellResultSchema, {
+		result: {
+			case: "failure",
+			value: create(ShellFailureSchema, {
+				command,
+				workingDirectory,
+				exitCode: 1,
+				signal: "",
+				stdout: "",
+				stderr: error,
+				executionTime: 0,
+				aborted: false,
+			}),
+		},
+	});
+}
+
+function buildShellRejectedResult(command: string, workingDirectory: string, reason: string) {
+	return create(ShellResultSchema, {
+		result: {
+			case: "rejected",
+			value: create(ShellRejectedSchema, {
+				command,
+				workingDirectory,
+				reason,
+				isReadonly: false,
+			}),
+		},
+	});
+}
+
+function buildLsResultFromToolResult(path: string, toolResult: ToolResultMessage) {
+	const text = toolResultToText(toolResult);
+	if (toolResult.isError) {
+		return buildLsErrorResult(path, text || "Ls failed");
+	}
+	const rootPath = path || ".";
+	const entries = text
+		.split("\n")
+		.map(line => line.trim())
+		.filter(line => line.length > 0 && !line.startsWith("["));
+	const childrenDirs: LsDirectoryTreeNode[] = [];
+	const childrenFiles: LsDirectoryTreeNode_File[] = [];
+
+	for (const entry of entries) {
+		const name = entry.split(" (")[0];
+		if (name.endsWith("/")) {
+			const dirName = name.slice(0, -1);
+			childrenDirs.push(
+				create(LsDirectoryTreeNodeSchema, {
+					absPath: `${rootPath.replace(/\/$/, "")}/${dirName}`,
+					childrenDirs: [],
+					childrenFiles: [],
+					childrenWereProcessed: false,
+					fullSubtreeExtensionCounts: {},
+					numFiles: 0,
+				}),
+			);
+		} else {
+			childrenFiles.push(create(LsDirectoryTreeNode_FileSchema, { name }));
+		}
+	}
+
+	const root = create(LsDirectoryTreeNodeSchema, {
+		absPath: rootPath,
+		childrenDirs,
+		childrenFiles,
+		childrenWereProcessed: true,
+		fullSubtreeExtensionCounts: {},
+		numFiles: childrenFiles.length,
+	});
+
+	return create(LsResultSchema, {
+		result: {
+			case: "success",
+			value: create(LsSuccessSchema, { directoryTreeRoot: root }),
+		},
+	});
+}
+
+function buildLsErrorResult(path: string, error: string) {
+	return create(LsResultSchema, {
+		result: {
+			case: "error",
+			value: create(LsErrorSchema, { path, error }),
+		},
+	});
+}
+
+function buildLsRejectedResult(path: string, reason: string) {
+	return create(LsResultSchema, {
+		result: {
+			case: "rejected",
+			value: create(LsRejectedSchema, { path, reason }),
+		},
+	});
+}
+
+function buildGrepResultFromToolResult(
+	args: { pattern: string; path?: string; outputMode?: string },
+	toolResult: ToolResultMessage,
+) {
+	const text = toolResultToText(toolResult);
+	if (toolResult.isError) {
+		return buildGrepErrorResult(text || "Grep failed");
+	}
+
+	const outputMode = args.outputMode || "content";
+	const clientTruncated = toolResultDetailBoolean(toolResult, "truncated");
+	const lines = text
+		.split("\n")
+		.map(line => line.trimEnd())
+		.filter(line => line.length > 0 && !line.startsWith("[") && !line.toLowerCase().startsWith("no matches"));
+
+	const workspaceKey = args.path || ".";
+	let unionResult: GrepUnionResult;
+
+	if (outputMode === "files_with_matches") {
+		const files = lines;
+		unionResult = create(GrepUnionResultSchema, {
+			result: {
+				case: "files",
+				value: create(GrepFilesResultSchema, {
+					files,
+					totalFiles: files.length,
+					clientTruncated,
+					ripgrepTruncated: false,
+				}),
+			},
+		});
+	} else if (outputMode === "count") {
+		const counts = lines
+			.map(line => {
+				const separatorIndex = line.lastIndexOf(":");
+				if (separatorIndex === -1) {
+					return null;
+				}
+				const file = line.slice(0, separatorIndex);
+				const count = Number.parseInt(line.slice(separatorIndex + 1), 10);
+				if (!file || Number.isNaN(count)) {
+					return null;
+				}
+				return create(GrepFileCountSchema, { file, count });
+			})
+			.filter((entry): entry is GrepFileCount => entry !== null);
+		const totalMatches = counts.reduce((sum, entry) => sum + entry.count, 0);
+		unionResult = create(GrepUnionResultSchema, {
+			result: {
+				case: "count",
+				value: create(GrepCountResultSchema, {
+					counts,
+					totalFiles: counts.length,
+					totalMatches,
+					clientTruncated,
+					ripgrepTruncated: false,
+				}),
+			},
+		});
+	} else {
+		const matchMap = new Map<string, Array<{ line: number; content: string; isContextLine: boolean }>>();
+		let totalMatchedLines = 0;
+
+		for (const line of lines) {
+			const matchLine = line.match(/^(.+?):(\d+):\s?(.*)$/);
+			const contextLine = line.match(/^(.+?)-(\d+)-\s?(.*)$/);
+			const match = matchLine ?? contextLine;
+			if (!match) {
+				continue;
+			}
+			const [, file, lineNumber, content] = match;
+			const isContextLine = Boolean(contextLine);
+			const list = matchMap.get(file) ?? [];
+			list.push({ line: Number(lineNumber), content, isContextLine });
+			matchMap.set(file, list);
+			if (!isContextLine) {
+				totalMatchedLines += 1;
+			}
+		}
+
+		const matches = Array.from(matchMap.entries()).map(([file, matches]) =>
+			create(GrepFileMatchSchema, {
+				file,
+				matches: matches.map(entry =>
+					create(GrepContentMatchSchema, {
+						lineNumber: entry.line,
+						content: entry.content,
+						contentTruncated: false,
+						isContextLine: entry.isContextLine,
+					}),
+				),
+			}),
+		);
+		const totalLines = matches.reduce((sum, entry) => sum + entry.matches.length, 0);
+		unionResult = create(GrepUnionResultSchema, {
+			result: {
+				case: "content",
+				value: create(GrepContentResultSchema, {
+					matches,
+					totalLines,
+					totalMatchedLines,
+					clientTruncated,
+					ripgrepTruncated: false,
+				}),
+			},
+		});
+	}
+
+	return create(GrepResultSchema, {
+		result: {
+			case: "success",
+			value: create(GrepSuccessSchema, {
+				pattern: args.pattern,
+				path: args.path || "",
+				outputMode,
+				workspaceResults: { [workspaceKey]: unionResult },
+			}),
+		},
+	});
+}
+
+function buildGrepErrorResult(error: string) {
+	return create(GrepResultSchema, {
+		result: {
+			case: "error",
+			value: create(GrepErrorSchema, { error }),
+		},
+	});
+}
+
+function buildDiagnosticsResultFromToolResult(path: string, toolResult: ToolResultMessage) {
+	const text = toolResultToText(toolResult);
+	if (toolResult.isError) {
+		return buildDiagnosticsErrorResult(path, text || "Diagnostics failed");
+	}
+	return create(DiagnosticsResultSchema, {
+		result: {
+			case: "success",
+			value: create(DiagnosticsSuccessSchema, {
+				path,
+				diagnostics: [],
+				totalDiagnostics: 0,
+			}),
+		},
+	});
+}
+
+function buildDiagnosticsErrorResult(_path: string, error: string) {
+	return create(DiagnosticsResultSchema, {
+		result: {
+			case: "error",
+			value: create(DiagnosticsErrorSchema, { error }),
+		},
+	});
+}
+
+function buildDiagnosticsRejectedResult(path: string, reason: string) {
+	return create(DiagnosticsResultSchema, {
+		result: {
+			case: "rejected",
+			value: create(DiagnosticsRejectedSchema, { path, reason }),
+		},
+	});
+}
+
+function parseToolArgsJson(text: string): unknown {
+	const trimmed = text.trim();
+	if (!trimmed) {
+		return text;
+	}
+	try {
+		const normalized = trimmed
+			.replace(/\bNone\b/g, "null")
+			.replace(/\bTrue\b/g, "true")
+			.replace(/\bFalse\b/g, "false");
+		return Bun.JSON5.parse(normalized);
+	} catch {}
+	return text;
+}
+
+function decodeMcpArgValue(value: Uint8Array): unknown {
+	try {
+		const parsedValue = fromBinary(ValueSchema, value);
+		const jsonValue = toJson(ValueSchema, parsedValue) as JsonValue;
+		if (typeof jsonValue === "string") {
+			return parseToolArgsJson(jsonValue);
+		}
+		return jsonValue;
+	} catch {}
+	const text = new TextDecoder().decode(value);
+	return parseToolArgsJson(text);
+}
+
+function decodeMcpArgsMap(args?: Record<string, Uint8Array>): Record<string, unknown> | undefined {
+	if (!args) {
+		return undefined;
+	}
+	const decoded: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(args)) {
+		decoded[key] = decodeMcpArgValue(value);
+	}
+	return decoded;
+}
+
+function decodeMcpCall(args: {
+	name: string;
+	args: Record<string, Uint8Array>;
+	toolCallId: string;
+	providerIdentifier: string;
+	toolName: string;
+}): CursorMcpCall {
+	const decodedArgs: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(args.args ?? {})) {
+		decodedArgs[key] = decodeMcpArgValue(value);
+	}
+	return {
+		name: args.name,
+		providerIdentifier: args.providerIdentifier,
+		toolName: args.toolName || args.name,
+		toolCallId: args.toolCallId,
+		args: decodedArgs,
+		rawArgs: args.args ?? {},
+	};
+}
+
+function mapTodoStatusValue(status?: number): "pending" | "in_progress" | "completed" {
+	switch (status) {
+		case 2:
+			return "in_progress";
+		case 3:
+			return "completed";
+		default:
+			return "pending";
+	}
+}
+
+interface CursorTodoItem {
+	id?: string;
+	content?: string;
+	status?: number;
+}
+
+interface CursorUpdateTodosToolCall {
+	updateTodosToolCall?: { args?: { todos?: CursorTodoItem[] } };
+}
+
+function buildTodoWriteArgs(toolCall: CursorUpdateTodosToolCall): {
+	todos: Array<{ id?: string; content: string; activeForm: string; status: "pending" | "in_progress" | "completed" }>;
+} | null {
+	const todos = toolCall.updateTodosToolCall?.args?.todos;
+	if (!todos) return null;
+	return {
+		todos: todos.map(todo => ({
+			id: typeof todo.id === "string" && todo.id.length > 0 ? todo.id : undefined,
+			content: typeof todo.content === "string" ? todo.content : "",
+			activeForm: typeof todo.content === "string" ? todo.content : "",
+			status: mapTodoStatusValue(typeof todo.status === "number" ? todo.status : undefined),
+		})),
+	};
+}
+
+function buildMcpResultFromToolResult(_mcpCall: CursorMcpCall, toolResult: ToolResultMessage) {
+	if (toolResult.isError) {
+		return buildMcpErrorResult(toolResultToText(toolResult) || "MCP tool failed");
+	}
+	const content = toolResult.content.map(item => {
+		if (item.type === "image") {
+			return create(McpToolResultContentItemSchema, {
+				content: {
+					case: "image",
+					value: create(McpImageContentSchema, {
+						data: Uint8Array.from(Buffer.from(item.data, "base64")),
+						mimeType: item.mimeType,
+					}),
+				},
+			});
+		}
+		return create(McpToolResultContentItemSchema, {
+			content: {
+				case: "text",
+				value: create(McpTextContentSchema, { text: item.text }),
+			},
+		});
+	});
+
+	return create(McpResultSchema, {
+		result: {
+			case: "success",
+			value: create(McpSuccessSchema, {
+				content,
+				isError: false,
+			}),
+		},
+	});
+}
+
+function buildMcpToolNotFoundResult(mcpCall: CursorMcpCall) {
+	return create(McpResultSchema, {
+		result: {
+			case: "toolNotFound",
+			value: create(McpToolNotFoundSchema, { name: mcpCall.toolName, availableTools: [] }),
+		},
+	});
+}
+
+function buildMcpErrorResult(error: string) {
+	return create(McpResultSchema, {
+		result: {
+			case: "error",
+			value: create(McpErrorSchema, { error }),
+		},
+	});
+}
+
+function processInteractionUpdate(
+	update: any,
+	output: AssistantMessage,
+	stream: AssistantMessageEventStream,
+	state: BlockState,
+	usageState: UsageState,
+): void {
+	const updateCase = update.message?.case;
+
+	log("interactionUpdate", updateCase, update.message?.value);
+
+	if (updateCase === "textDelta") {
+		state.setFirstTokenTime();
+		const delta = update.message.value.text || "";
+		if (!state.currentTextBlock) {
+			const block: TextContent & { index: number } = {
+				type: "text",
+				text: "",
+				index: output.content.length,
+			};
+			output.content.push(block);
+			state.setTextBlock(block);
+			stream.push({ type: "text_start", contentIndex: output.content.length - 1, partial: output });
+		}
+		state.currentTextBlock!.text += delta;
+		const idx = output.content.indexOf(state.currentTextBlock!);
+		stream.push({ type: "text_delta", contentIndex: idx, delta, partial: output });
+	} else if (updateCase === "thinkingDelta") {
+		state.setFirstTokenTime();
+		const delta = update.message.value.text || "";
+		if (!state.currentThinkingBlock) {
+			const block: ThinkingContent & { index: number } = {
+				type: "thinking",
+				thinking: "",
+				index: output.content.length,
+			};
+			output.content.push(block);
+			state.setThinkingBlock(block);
+			stream.push({ type: "thinking_start", contentIndex: output.content.length - 1, partial: output });
+		}
+		state.currentThinkingBlock!.thinking += delta;
+		const idx = output.content.indexOf(state.currentThinkingBlock!);
+		stream.push({ type: "thinking_delta", contentIndex: idx, delta, partial: output });
+	} else if (updateCase === "thinkingCompleted") {
+		if (state.currentThinkingBlock) {
+			const idx = output.content.indexOf(state.currentThinkingBlock);
+			delete (state.currentThinkingBlock as any).index;
+			stream.push({
+				type: "thinking_end",
+				contentIndex: idx,
+				content: state.currentThinkingBlock.thinking,
+				partial: output,
+			});
+			state.setThinkingBlock(null);
+		}
+	} else if (updateCase === "toolCallStarted") {
+		const toolCall = update.message.value.toolCall;
+		if (toolCall) {
+			const mcpCall = toolCall.mcpToolCall;
+			if (mcpCall) {
+				const args = mcpCall.args || {};
+				const block: ToolCallState = {
+					type: "toolCall",
+					id: args.toolCallId || crypto.randomUUID(),
+					name: args.name || args.toolName || "",
+					arguments: {},
+					index: output.content.length,
+					partialJson: "",
+					kind: "mcp",
+				};
+				output.content.push(block);
+				state.setToolCall(block);
+				stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });
+				return;
+			}
+
+			const todoArgs = buildTodoWriteArgs(toolCall);
+			if (todoArgs) {
+				const callId = update.message.value.callId || crypto.randomUUID();
+				const block: ToolCallState = {
+					type: "toolCall",
+					id: callId,
+					name: "todo_write",
+					arguments: todoArgs,
+					index: output.content.length,
+					kind: "todo_write",
+				};
+				output.content.push(block);
+				state.setToolCall(block);
+				stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });
+			}
+		}
+	} else if (updateCase === "toolCallDelta" || updateCase === "partialToolCall") {
+		if (state.currentToolCall?.kind === "mcp") {
+			const delta = update.message.value.argsTextDelta || "";
+			state.currentToolCall.partialJson = `${state.currentToolCall.partialJson ?? ""}${delta}`;
+			state.currentToolCall.arguments = parseStreamingJson(state.currentToolCall.partialJson ?? "");
+			const idx = output.content.indexOf(state.currentToolCall);
+			stream.push({ type: "toolcall_delta", contentIndex: idx, delta, partial: output });
+		}
+	} else if (updateCase === "toolCallCompleted") {
+		if (state.currentToolCall) {
+			const toolCall = update.message.value.toolCall;
+			if (state.currentToolCall.kind === "mcp") {
+				const decodedArgs = decodeMcpArgsMap(toolCall?.mcpToolCall?.args?.args);
+				if (decodedArgs) {
+					state.currentToolCall.arguments = decodedArgs;
+				}
+			} else if (state.currentToolCall.kind === "todo_write" && toolCall) {
+				const todoArgs = buildTodoWriteArgs(toolCall);
+				if (todoArgs) {
+					state.currentToolCall.arguments = todoArgs;
+				}
+			}
+			const idx = output.content.indexOf(state.currentToolCall);
+			delete (state.currentToolCall as any).partialJson;
+			delete (state.currentToolCall as any).index;
+			delete (state.currentToolCall as any).kind;
+			stream.push({ type: "toolcall_end", contentIndex: idx, toolCall: state.currentToolCall, partial: output });
+			state.setToolCall(null);
+		}
+	} else if (updateCase === "turnEnded") {
+		output.stopReason = "stop";
+	} else if (updateCase === "tokenDelta") {
+		const tokenDelta = update.message.value;
+		usageState.sawTokenDelta = true;
+		output.usage.output += tokenDelta.tokens || 0;
+		output.usage.totalTokens = output.usage.input + output.usage.output;
+	}
+}
+
+function handleConversationCheckpointUpdate(
+	checkpoint: ConversationStateStructure,
+	output: AssistantMessage,
+	usageState: UsageState,
+	onConversationCheckpoint?: (checkpoint: ConversationStateStructure) => void,
+): void {
+	onConversationCheckpoint?.(checkpoint);
+	if (usageState.sawTokenDelta) {
+		return;
+	}
+	const usedTokens = checkpoint.tokenDetails?.usedTokens ?? 0;
+	if (usedTokens <= 0) {
+		return;
+	}
+	if (output.usage.output !== usedTokens) {
+		output.usage.output = usedTokens;
+		output.usage.totalTokens = output.usage.input + output.usage.output;
+	}
+}
+
+function createBlobId(data: Uint8Array): Uint8Array {
+	return new Uint8Array(createHash("sha256").update(data).digest());
+}
+
+function storeCursorBlob(blobStore: Map<string, Uint8Array>, data: Uint8Array): Uint8Array {
+	const blobId = createBlobId(data);
+	blobStore.set(Buffer.from(blobId).toString("hex"), data);
+	return blobId;
+}
+
+function readCursorBlob(blobStore: Map<string, Uint8Array>, blobId: Uint8Array): Uint8Array {
+	const data = blobStore.get(Buffer.from(blobId).toString("hex"));
+	if (!data) {
+		throw new Error("Cursor blob not found");
+	}
+	return data;
+}
+
+const CURSOR_NATIVE_TOOL_NAMES = new Set(["bash", "read", "write", "delete", "ls", "grep", "lsp", "todo_write"]);
+
+function buildMcpToolDefinitions(tools: Tool[] | undefined): McpToolDefinition[] {
+	if (!tools || tools.length === 0) {
+		return [];
+	}
+
+	const advertisedTools = tools.filter(tool => !CURSOR_NATIVE_TOOL_NAMES.has(tool.name));
+	if (advertisedTools.length === 0) {
+		return [];
+	}
+
+	return advertisedTools.map(tool => {
+		const jsonSchema = toolWireSchema(tool);
+		const schemaValue: JsonValue =
+			jsonSchema && typeof jsonSchema === "object"
+				? (jsonSchema as JsonValue)
+				: { type: "object", properties: {}, required: [] };
+		const inputSchema = toBinary(ValueSchema, fromJson(ValueSchema, schemaValue));
+		return create(McpToolDefinitionSchema, {
+			name: tool.name,
+			description: tool.description || "",
+			providerIdentifier: "aery-agent",
+			toolName: tool.name,
+			inputSchema,
+		});
+	});
+}
+
+/**
+ * Extract text content from a user or developer message.
+ */
+function extractUserMessageText(msg: Message): string {
+	if (msg.role !== "user" && msg.role !== "developer") return "";
+	const content = msg.content;
+	if (typeof content === "string") return content.trim();
+	const text = content
+		.filter((c): c is TextContent => c.type === "text")
+		.map(c => c.text)
+		.join("\n");
+	return text.trim();
+}
+
+function hasUserMessageImages(msg: Message): boolean {
+	return (
+		(msg.role === "user" || msg.role === "developer") &&
+		Array.isArray(msg.content) &&
+		msg.content.some(item => item.type === "image")
+	);
+}
+
+type CursorRootPromptContentPart = { type: "text"; text: string } | { type: "image"; image: string; mediaType: string };
+
+function buildCursorRootPromptContent(content: string | (TextContent | ImageContent)[]): CursorRootPromptContentPart[] {
+	if (typeof content === "string") {
+		const text = content.trim();
+		return text ? [{ type: "text", text }] : [];
+	}
+	const parts: CursorRootPromptContentPart[] = [];
+	for (const item of content) {
+		if (item.type === "text") {
+			const text = item.text.trim();
+			if (text) {
+				parts.push({ type: "text", text });
+			}
+		} else {
+			parts.push({ type: "image", image: item.data, mediaType: item.mimeType });
+		}
+	}
+	return parts;
+}
+
+function cursorUserContentKey(content: string | (TextContent | ImageContent)[]): string {
+	if (typeof content === "string") {
+		return content.trim();
+	}
+	const hash = createHash("sha256");
+	for (const item of content) {
+		hash.update(item.type);
+		if (item.type === "text") {
+			hash.update(item.text);
+		} else {
+			hash.update(item.mimeType);
+			hash.update(item.data);
+		}
+	}
+	return hash.digest("hex");
+}
+
+/**
+ * Extract text content from an assistant message.
+ */
+function extractAssistantMessageText(msg: Message): string {
+	if (msg.role !== "assistant") return "";
+	if (!Array.isArray(msg.content)) return "";
+	return msg.content
+		.filter((c): c is TextContent => c.type === "text")
+		.map(c => c.text)
+		.join("\n");
+}
+
+/**
+ * Derive a stable, UUID-formatted `message_id` from a content key.
+ * Ensures identical historical messages hash to the same blob IDs across
+ * requests, so `conversationBlobStores` does not grow unboundedly and
+ * unchanged history reuses existing blob IDs.
+ */
+type CursorMessageId = `${string}-${string}-${string}-${string}-${string}`;
+
+function deterministicMessageId(key: string): CursorMessageId {
+	const hex = createHash("sha256").update(key).digest("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/**
+ * Index of the last user/developer message in `messages`, or -1 if none.
+ * Used to exclude the current user turn from history builders — it goes in
+ * `ConversationActionSchema.userMessageAction`, not in history structures.
+ */
+function findLastUserMessageIndex(messages: Message[]): number {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const role = messages[i].role;
+		if (role === "user" || role === "developer") {
+			return i;
+		}
+	}
+	return -1;
+}
+
+/**
+ * Build `ConversationStateStructure.rootPromptMessagesJson` blob IDs for the
+ * system prompt plus prior conversation history, as JSON blobs matching
+ * Cursor's internal Vercel-AI-SDK-shaped message format.
+ *
+ * Cursor's server uses `rootPromptMessagesJson` (not `turns[]`) to build the
+ * actual model prompt. `turns[]` is UI/display metadata. Without populating
+ * this field, multi-turn conversations lose prior context — the model sees
+ * only an empty placeholder where historical user turns should be.
+ * The active user message is excluded because it is sent in the action.
+ */
+/**
+ * Build one Cursor system-message JSON blob per ordered system prompt. Emitting separate blobs
+ * (rather than a single `\n\n`-joined string) lets Cursor's blob cache hit independently per
+ * entry: changing only the last prompt does not invalidate earlier blob ids, so the prefix
+ * up to the changed prompt remains cached on the server side.
+ *
+ * When no system prompts are provided, returns a single default greeting so we never emit
+ * an empty `rootPromptMessagesJson` head.
+ */
+export function buildCursorSystemPromptJsons(systemPrompt: readonly string[] | undefined): string[] {
+	const systemPrompts = normalizeSystemPrompts(systemPrompt);
+	if (systemPrompts.length === 0) {
+		return [JSON.stringify({ role: "system", content: "You are a helpful assistant." })];
+	}
+	return systemPrompts.map(content => JSON.stringify({ role: "system", content }));
+}
+
+function buildRootPromptMessagesJson(
+	messages: Message[],
+	systemPromptIds: Uint8Array[],
+	blobStore: Map<string, Uint8Array>,
+	activeUserMessageIndex = findLastUserMessageIndex(messages),
+): Uint8Array[] {
+	const entries: Uint8Array[] = [...systemPromptIds];
+	const pushJson = (obj: unknown) => {
+		const bytes = new TextEncoder().encode(JSON.stringify(obj));
+		entries.push(storeCursorBlob(blobStore, bytes));
+	};
+
+	for (let i = 0; i < messages.length; i++) {
+		if (i === activeUserMessageIndex) break;
+		const msg = messages[i];
+		if (msg.role === "user" || msg.role === "developer") {
+			const content = buildCursorRootPromptContent(msg.content);
+			if (content.length === 0) continue;
+			pushJson({ role: "user", content });
+		} else if (msg.role === "assistant") {
+			const text = extractAssistantMessageText(msg);
+			if (!text) continue;
+			pushJson({ role: "assistant", content: [{ type: "text", text }] });
+		} else if (msg.role === "toolResult") {
+			const text = toolResultToText(msg);
+			if (!text) continue;
+			pushJson({
+				role: "user",
+				content: [{ type: "text", text: `[Tool Result]\n${text}` }],
+			});
+		}
+	}
+
+	return entries;
+}
+
+/**
+ * Convert context.messages to Cursor's ConversationTurnStructure blob IDs.
+ * Groups messages into turns: each turn is a user message followed by the assistant's response.
+ * Excludes the active user message (which goes in the action).
+ *
+ * Each `AgentConversationTurnStructure.user_message`, `steps[]`, and the outer
+ * `ConversationStateStructure.turns[]` entry is a blob ID into `blobStore`.
+ */
+function buildConversationTurns(
+	messages: Message[],
+	blobStore: Map<string, Uint8Array>,
+	activeUserMessageIndex = findLastUserMessageIndex(messages),
+): Uint8Array[] {
+	const turns: Uint8Array[] = [];
+
+	// Find turn boundaries - each turn starts with a user message
+	let i = 0;
+	while (i < messages.length) {
+		const msg = messages[i];
+
+		// Skip non-user messages at the start
+		if (msg.role !== "user" && msg.role !== "developer") {
+			i++;
+			continue;
+		}
+
+		// The active user message goes in the action, not turns. A prior user
+		// followed by assistant/tool-result messages is complete history and
+		// must remain serialized for resume actions.
+		if (i === activeUserMessageIndex) {
+			break;
+		}
+
+		// Create and serialize user message
+		const userText = extractUserMessageText(msg);
+		if (userText.length === 0 && !hasUserMessageImages(msg)) {
+			i++;
+			continue;
+		}
+
+		const userMessage = createCursorUserMessage(
+			msg.content,
+			userText,
+			deterministicMessageId(`u:${turns.length}:${cursorUserContentKey(msg.content)}`),
+		);
+		const userMessageBytes = toBinary(UserMessageSchema, userMessage);
+		const userMessageBlobId = storeCursorBlob(blobStore, userMessageBytes);
+
+		// Collect and serialize steps until next user message
+		const stepBlobIds: Uint8Array[] = [];
+		i++;
+
+		while (i < messages.length && messages[i].role !== "user" && messages[i].role !== "developer") {
+			const stepMsg = messages[i];
+
+			if (stepMsg.role === "assistant") {
+				const text = extractAssistantMessageText(stepMsg);
+				if (text) {
+					const step = create(ConversationStepSchema, {
+						message: {
+							case: "assistantMessage",
+							value: create(AssistantMessageSchema, { text }),
+						},
+					});
+					stepBlobIds.push(storeCursorBlob(blobStore, toBinary(ConversationStepSchema, step)));
+				}
+			} else if (stepMsg.role === "toolResult") {
+				// Include tool results as assistant text for context
+				const text = toolResultToText(stepMsg);
+				if (text) {
+					const step = create(ConversationStepSchema, {
+						message: {
+							case: "assistantMessage",
+							value: create(AssistantMessageSchema, { text: `[Tool Result]\n${text}` }),
+						},
+					});
+					stepBlobIds.push(storeCursorBlob(blobStore, toBinary(ConversationStepSchema, step)));
+				}
+			}
+
+			i++;
+		}
+
+		// Create the serialized turn using Structure types. The bytes fields
+		// (user_message, steps) are blob IDs resolved through the KV store.
+		const agentTurn = create(AgentConversationTurnStructureSchema, {
+			userMessage: userMessageBlobId,
+			steps: stepBlobIds,
+		});
+		const turn = create(ConversationTurnStructureSchema, {
+			turn: {
+				case: "agentConversationTurn",
+				value: agentTurn,
+			},
+		});
+		turns.push(storeCursorBlob(blobStore, toBinary(ConversationTurnStructureSchema, turn)));
+	}
+
+	return turns;
+}
+
+/** Exported for tests: decodes Cursor history blobs built from conversation messages. */
+export function buildCursorHistoryForTest(
+	messages: Message[],
+	activeUserMessageIndex = findLastUserMessageIndex(messages),
+): {
+	rootPromptMessagesJson: unknown[];
+	turnUserMessagesJson: JsonValue[];
+	turnStepMessagesJson: JsonValue[][];
+} {
+	const blobStore = new Map<string, Uint8Array>();
+	const rootPromptMessagesJson = buildRootPromptMessagesJson(messages, [], blobStore, activeUserMessageIndex).map(
+		blobId => JSON.parse(new TextDecoder().decode(readCursorBlob(blobStore, blobId))),
+	);
+	const turnUserMessagesJson: JsonValue[] = [];
+	const turnStepMessagesJson: JsonValue[][] = [];
+	for (const turnBlobId of buildConversationTurns(messages, blobStore, activeUserMessageIndex)) {
+		const turn = fromBinary(ConversationTurnStructureSchema, readCursorBlob(blobStore, turnBlobId));
+		if (turn.turn.case !== "agentConversationTurn") {
+			continue;
+		}
+		const userMessage = fromBinary(UserMessageSchema, readCursorBlob(blobStore, turn.turn.value.userMessage));
+		turnUserMessagesJson.push(toJson(UserMessageSchema, userMessage));
+		turnStepMessagesJson.push(
+			turn.turn.value.steps.map(stepBlobId => {
+				const step = fromBinary(ConversationStepSchema, readCursorBlob(blobStore, stepBlobId));
+				return toJson(ConversationStepSchema, step);
+			}),
+		);
+	}
+	return { rootPromptMessagesJson, turnUserMessagesJson, turnStepMessagesJson };
+}
+function createCursorUserMessage(
+	content: string | (TextContent | ImageContent)[],
+	text: string,
+	messageId = crypto.randomUUID(),
+) {
+	const images = typeof content === "string" ? [] : extractImages(content);
+	return create(UserMessageSchema, {
+		text,
+		messageId,
+		...(images.length > 0
+			? {
+					selectedContext: create(SelectedContextSchema, {
+						selectedImages: images,
+					}),
+				}
+			: {}),
+	});
+}
+
+function extractImages(content: (TextContent | ImageContent)[]) {
+	return content
+		.filter((item): item is ImageContent => item.type === "image")
+		.map(image =>
+			create(SelectedImageSchema, {
+				uuid: crypto.randomUUID(),
+				mimeType: image.mimeType,
+				dataOrBlobId: {
+					case: "data",
+					value: Uint8Array.from(Buffer.from(image.data, "base64")),
+				},
+			}),
+		);
+}
+
+function buildGrpcRequest(
+	model: Model<"cursor-agent">,
+	context: Context,
+	options: CursorOptions | undefined,
+	state: {
+		conversationId: string;
+		blobStore: Map<string, Uint8Array>;
+		conversationState?: ConversationStateStructure;
+	},
+): {
+	requestBytes: Uint8Array;
+	blobStore: Map<string, Uint8Array>;
+	conversationState: ConversationStateStructure;
+} {
+	const blobStore = state.blobStore;
+
+	const systemPromptIds = buildCursorSystemPromptJsons(context.systemPrompt).map(json =>
+		storeCursorBlob(blobStore, new TextEncoder().encode(json)),
+	);
+
+	const activeUserMessageIndex = context.messages.length - 1;
+	const activeMessage = context.messages[activeUserMessageIndex];
+	const activeUserMessage =
+		activeMessage?.role === "user" || activeMessage?.role === "developer" ? activeMessage : undefined;
+	let userContent: string | (TextContent | ImageContent)[] | undefined;
+	let userText = "";
+	let hasUserImages = false;
+	if (activeUserMessage?.role === "user" || activeUserMessage?.role === "developer") {
+		userContent = activeUserMessage.content;
+		if (typeof userContent === "string") {
+			userText = userContent.trim();
+		} else {
+			userText = extractText(userContent);
+			hasUserImages = hasImages(userContent);
+		}
+	}
+
+	const action = create(ConversationActionSchema, {
+		action:
+			userContent && (userText.trim().length > 0 || hasUserImages)
+				? {
+						case: "userMessageAction",
+						value: create(UserMessageActionSchema, {
+							userMessage: createCursorUserMessage(userContent, userText),
+						}),
+					}
+				: {
+						case: "resumeAction",
+						value: create(ResumeActionSchema, {}),
+					},
+	});
+
+	// Build conversation turns from prior messages, excluding only the active user message
+	// when the request is sending one. Resume actions must preserve trailing tool results.
+	const turns = buildConversationTurns(context.messages, blobStore, activeUserMessage ? activeUserMessageIndex : -1);
+
+	// Build `rootPromptMessagesJson` from prior messages. Cursor's server uses this
+	// field (not `turns[]`) to construct the actual model prompt; if we only send the
+	// system prompt here, multi-turn conversations lose prior context and the model
+	// sees only the current user message.
+	const rootPromptMessagesJson = buildRootPromptMessagesJson(
+		context.messages,
+		systemPromptIds,
+		blobStore,
+		activeUserMessage ? activeUserMessageIndex : -1,
+	);
+
+	// Preserve cached non-history state fields (todos, file states, summaries, etc.)
+	// when the system prompt is unchanged; otherwise start fresh.
+	const cachedPromptHead = state.conversationState?.rootPromptMessagesJson?.slice(0, systemPromptIds.length) ?? [];
+	const hasMatchingPrompt =
+		cachedPromptHead.length === systemPromptIds.length &&
+		systemPromptIds.every((id, idx) => Buffer.from(cachedPromptHead[idx]).equals(id));
+	const baseState =
+		state.conversationState && hasMatchingPrompt
+			? state.conversationState
+			: create(ConversationStateStructureSchema, {
+					rootPromptMessagesJson: systemPromptIds,
+					turns: [],
+					todos: [],
+					pendingToolCalls: [],
+					previousWorkspaceUris: [],
+					fileStates: {},
+					fileStatesV2: {},
+					summaryArchives: [],
+					turnTimings: [],
+					subagentStates: {},
+					selfSummaryCount: 0,
+					readPaths: [],
+				});
+
+	// Always override `rootPromptMessagesJson` and `turns` with content freshly built from
+	// `context.messages`. The server-echoed checkpoint replaces historical user entries
+	// with empty placeholders, so we cannot rely on the cached `rootPromptMessagesJson`.
+	const conversationState = create(ConversationStateStructureSchema, {
+		...baseState,
+		rootPromptMessagesJson,
+		turns,
+	});
+
+	const modelDetails = create(ModelDetailsSchema, {
+		modelId: model.id,
+		displayModelId: model.id,
+		displayName: model.name,
+	});
+
+	const runRequest = create(AgentRunRequestSchema, {
+		conversationState,
+		action,
+		modelDetails,
+		conversationId: state.conversationId,
+	});
+
+	options?.onPayload?.(runRequest);
+
+	// Tools are sent later via requestContext (exec handshake)
+
+	if (options?.customSystemPrompt) {
+		runRequest.customSystemPrompt = options.customSystemPrompt;
+	}
+
+	const clientMessage = create(AgentClientMessageSchema, {
+		message: { case: "runRequest", value: runRequest },
+	});
+
+	const requestBytes = toBinary(AgentClientMessageSchema, clientMessage);
+
+	const toolNames = context.tools?.map(tool => tool.name) ?? [];
+	const detail =
+		$env.DEBUG_CURSOR === "2"
+			? ` ${JSON.stringify(clientMessage.message.value, debugReplacer, 2)?.slice(0, 2000)}`
+			: "";
+	log("info", "builtRunRequest", {
+		bytes: requestBytes.length,
+		tools: toolNames.length,
+		toolNames: toolNames.slice(0, 20),
+		detail: detail || undefined,
+	});
+
+	return { requestBytes, blobStore, conversationState };
+}
+
+function hasImages(content: (TextContent | ImageContent)[]): boolean {
+	return content.some(item => item.type === "image");
+}
+function extractText(content: (TextContent | ImageContent)[]): string {
+	return content
+		.filter((c): c is TextContent => c.type === "text")
+		.map(c => c.text)
+		.join("\n");
+}