@vib-rato/ai 0.16.0

package/src/providers/cursor.ts

@@ -0,0 +1,3396 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import http2 from "node:http2";
+import { create, fromBinary, fromJson, type JsonValue, toBinary, toJson } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import { $env, extractHttpStatusFromError, sanitizeText } from "@vib-rato/utils";
+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 { kCursorExecResolved } from "../utils/block-symbols";
+import { AssistantMessageEventStream } from "../utils/event-stream";
+import { getStreamIdleTimeoutMs } from "../utils/idle-iterator";
+import { captureUnicodeEscapeEvidence, parseStreamingJson } from "../utils/json-parse";
+import { connectProxiedSocket, getProxyForUrl } from "../utils/proxy";
+import { formatErrorMessageWithRetryAfter } from "../utils/retry-after";
+import { flattenToolRootCombinators, toolWireSchema } from "../utils/schema";
+import { CURSOR_COMPOSER_EDIT_DISCIPLINE_PROMPT, isComposerHarnessModel } from "./composer-discipline";
+import { CURSOR_CLIENT_VERSION } from "./cursor/client-version";
+import {
+	buildMcpStateResult,
+	buildNeutralHookResult,
+	buildPiBashError,
+	buildPiBashResult,
+	buildPiEditError,
+	buildPiEditRejected,
+	buildPiEditResult,
+	buildPiFindError,
+	buildPiFindResult,
+	buildPiGrepError,
+	buildPiGrepResult,
+	buildPiLsError,
+	buildPiLsResult,
+	buildPiReadError,
+	buildPiReadResult,
+	buildPiWriteError,
+	buildPiWriteRejected,
+	buildPiWriteResult,
+	piEscapeRegexLiteral,
+	piJoinPath,
+	piLimit,
+	piLsPath,
+	piReadDisplayPath,
+	piTimeout,
+} from "./cursor/exec-modern";
+import type { CursorRule, McpToolDefinition, RequestedModel_ModelParameterbytes } from "./cursor/gen/agent_pb";
+import {
+	AgentClientMessageSchema,
+	AgentConversationTurnStructureSchema,
+	AgentRunRequestSchema,
+	type AgentServerMessage,
+	AgentServerMessageSchema,
+	AssistantMessageSchema,
+	BackgroundShellSpawnResultSchema,
+	ClientHeartbeatSchema,
+	ComputerUseResultSchema,
+	ConversationActionSchema,
+	type ConversationStateStructure,
+	ConversationStateStructureSchema,
+	ConversationStepSchema,
+	ConversationTurnStructureSchema,
+	CursorRuleSchema,
+	CursorRuleSource,
+	CursorRuleTypeGlobalSchema,
+	CursorRuleTypeSchema,
+	DeleteErrorSchema,
+	DeleteRejectedSchema,
+	DeleteResultSchema,
+	DeleteSuccessSchema,
+	DiagnosticsErrorSchema,
+	DiagnosticsRejectedSchema,
+	DiagnosticsResultSchema,
+	DiagnosticsSuccessSchema,
+	ExecClientControlMessageSchema,
+	type ExecClientMessage,
+	ExecClientMessageSchema,
+	ExecClientStreamCloseSchema,
+	ExecClientThrowSchema,
+	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,
+	McpAllowlistPrecheckResultSchema,
+	McpErrorSchema,
+	McpImageContentSchema,
+	McpResultSchema,
+	McpSuccessSchema,
+	McpTextContentSchema,
+	McpToolDefinitionSchema,
+	McpToolNotFoundSchema,
+	McpToolResultContentItemSchema,
+	ModelDetailsSchema,
+	ReadErrorSchema,
+	ReadMcpResourceExecResultSchema,
+	ReadRejectedSchema,
+	ReadResultSchema,
+	ReadSuccessSchema,
+	RecordScreenResultSchema,
+	RequestContextResultSchema,
+	RequestContextSchema,
+	RequestContextSuccessSchema,
+	RequestedModel_ModelParameterbytesSchema,
+	RequestedModelSchema,
+	ResumeActionSchema,
+	SelectedContextSchema,
+	SelectedImageSchema,
+	SetBlobResultSchema,
+	ShellAllowlistPrecheckResultSchema,
+	type ShellArgs,
+	ShellFailureSchema,
+	ShellRejectedSchema,
+	type ShellResult,
+	ShellResultSchema,
+	type ShellStream,
+	ShellStreamExitSchema,
+	ShellStreamSchema,
+	ShellStreamStartSchema,
+	ShellStreamStderrSchema,
+	ShellStreamStdoutSchema,
+	ShellSuccessSchema,
+	UserMessageActionSchema,
+	UserMessageSchema,
+	WebFetchAllowlistPrecheckResultSchema,
+	WriteErrorSchema,
+	WriteRejectedSchema,
+	WriteResultSchema,
+	WriteShellStdinErrorSchema,
+	WriteShellStdinResultSchema,
+	WriteSuccessSchema,
+} from "./cursor/gen/agent_pb";
+
+export const CURSOR_API_URL = "https://api2.cursor.sh";
+export { CURSOR_CLIENT_VERSION };
+
+const conversationStateCache = new Map<string, ConversationStateStructure>();
+const conversationBlobStores = new Map<string, Map<string, Uint8Array>>();
+
+// F15: bound the module-global conversation caches so long-lived / many-session use cannot
+// grow them without limit. LRU by conversation count + TTL on idle conversations.
+const CURSOR_MAX_CONVERSATIONS = 64;
+const CURSOR_CONVERSATION_TTL_MS = 60 * 60 * 1000;
+const conversationLastAccess = new Map<string, number>();
+
+/** Drop all cached state + blob bytes for a conversation (F15 bound + session-teardown hook). */
+export function disposeCursorConversation(conversationId: string): void {
+	conversationStateCache.delete(conversationId);
+	conversationBlobStores.delete(conversationId);
+	conversationLastAccess.delete(conversationId);
+}
+
+/** Refresh recency for a conversation and evict TTL-stale / LRU-overflow entries (F15). */
+function touchCursorConversation(conversationId: string): void {
+	const now = Date.now();
+	for (const [id, ts] of conversationLastAccess) {
+		if (id !== conversationId && now - ts > CURSOR_CONVERSATION_TTL_MS) disposeCursorConversation(id);
+	}
+	conversationLastAccess.set(conversationId, now);
+	const state = conversationStateCache.get(conversationId);
+	if (state !== undefined) {
+		conversationStateCache.delete(conversationId);
+		conversationStateCache.set(conversationId, state);
+	}
+	while (conversationStateCache.size > CURSOR_MAX_CONVERSATIONS) {
+		const oldest = conversationStateCache.keys().next().value;
+		if (oldest === undefined || oldest === conversationId) break;
+		disposeCursorConversation(oldest);
+	}
+}
+
+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");
+	}
+}
+
+interface CursorRequestWriter {
+	enqueue(frame: Uint8Array): void;
+	isActive(): boolean;
+	registerShellGate(close: () => void): () => void;
+}
+
+class CursorRequestCoordinator implements CursorRequestWriter {
+	#state: "open" | "draining" | "failed" | "succeeded" = "open";
+	#tasks = new Set<Promise<void>>();
+	#taskChain = Promise.resolve();
+	#hasAdmittedTask = false;
+	#frames: Uint8Array[] = [];
+	#writing = false;
+	#drainWaiters: Array<() => void> = [];
+	#failure: Error | null = null;
+	#shellGates = new Set<() => void>();
+	#request: http2.ClientHttp2Stream;
+	#stopHeartbeat: () => void;
+	#onSuccess: () => void;
+	#onFailure: (error: Error) => void;
+	#drainTimer: NodeJS.Timeout | null = null;
+	#drainTimeoutMs: number | undefined;
+
+	constructor(
+		request: http2.ClientHttp2Stream,
+		stopHeartbeat: () => void,
+		onSuccess: () => void,
+		onFailure: (error: Error) => void,
+		drainTimeoutMs: number | undefined,
+	) {
+		this.#request = request;
+		this.#stopHeartbeat = stopHeartbeat;
+		this.#onSuccess = onSuccess;
+		this.#onFailure = onFailure;
+		this.#drainTimeoutMs = drainTimeoutMs;
+	}
+
+	isActive(): boolean {
+		return this.#state === "open" || this.#state === "draining";
+	}
+
+	canAdmitTask(): boolean {
+		return this.#state === "open";
+	}
+
+	hasTurnEnded(): boolean {
+		return this.#state === "draining" || this.#state === "succeeded";
+	}
+
+	failureError(): Error | null {
+		return this.#failure;
+	}
+
+	enqueue(frame: Uint8Array): void {
+		if (!this.isActive()) return;
+		this.#frames.push(Buffer.from(frame));
+		this.#writeNext();
+	}
+
+	registerShellGate(close: () => void): () => void {
+		if (!this.isActive()) {
+			close();
+			return () => {};
+		}
+		this.#shellGates.add(close);
+		return () => this.#shellGates.delete(close);
+	}
+
+	admit(taskFactory: () => Promise<void>): void {
+		if (!this.canAdmitTask()) return;
+		const orderedTask = this.#hasAdmittedTask
+			? this.#taskChain.then(() => {
+					if (this.#state === "failed" || this.#state === "succeeded") return;
+					return taskFactory();
+				})
+			: taskFactory();
+		this.#hasAdmittedTask = true;
+		this.#taskChain = orderedTask.then(
+			() => {},
+			error => {
+				this.fail(error instanceof Error ? error : new Error(String(error)));
+			},
+		);
+		this.#tasks.add(orderedTask);
+		void orderedTask.then(
+			() => this.#tasks.delete(orderedTask),
+			() => this.#tasks.delete(orderedTask),
+		);
+	}
+
+	turnEnded(): void {
+		if (this.#state !== "open") return;
+		this.#state = "draining";
+		this.#stopHeartbeat();
+		if (this.#drainTimeoutMs !== undefined && this.#drainTimeoutMs > 0) {
+			this.#drainTimer = setTimeout(() => {
+				this.fail(new Error(`Cursor admitted work drain timed out after ${this.#drainTimeoutMs}ms`));
+			}, this.#drainTimeoutMs);
+		}
+		void Promise.all([...this.#tasks]).then(
+			() => {
+				if (this.#state !== "draining") return;
+				this.#drain(() => {
+					if (this.#state !== "draining") return;
+					if (this.#drainTimer) {
+						clearTimeout(this.#drainTimer);
+						this.#drainTimer = null;
+					}
+					this.#state = "succeeded";
+					this.#onSuccess();
+				});
+			},
+			error => this.fail(error instanceof Error ? error : new Error(String(error))),
+		);
+	}
+
+	fail(error: Error): void {
+		if (this.#state === "failed" || this.#state === "succeeded") return;
+		this.#state = "failed";
+		this.#failure = error;
+		if (this.#drainTimer) {
+			clearTimeout(this.#drainTimer);
+			this.#drainTimer = null;
+		}
+		this.#stopHeartbeat();
+		for (const close of this.#shellGates) close();
+		this.#shellGates.clear();
+		this.#frames = [];
+		this.#writing = false;
+		this.#releaseDrains();
+		this.#request.close();
+		this.#onFailure(error);
+	}
+
+	#writeNext(): void {
+		if (this.#writing || !this.isActive()) return;
+		const frame = this.#frames.shift();
+		if (!frame) {
+			this.#releaseDrains();
+			return;
+		}
+		this.#writing = true;
+		try {
+			this.#request.write(frame, error => {
+				this.#writing = false;
+				if (error) {
+					this.fail(error);
+					return;
+				}
+				this.#writeNext();
+			});
+		} catch (error) {
+			this.#writing = false;
+			this.fail(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+
+	#drain(resolve: () => void): void {
+		if (!this.#writing && this.#frames.length === 0) {
+			resolve();
+			return;
+		}
+		this.#drainWaiters.push(resolve);
+	}
+
+	#releaseDrains(): void {
+		if (this.#writing || this.#frames.length > 0) return;
+		const waiters = this.#drainWaiters;
+		this.#drainWaiters = [];
+		for (const resolve of waiters) resolve();
+	}
+}
+
+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;
+}
+
+const CURSOR_MODEL_EFFORT_RE = /^(.*)-(minimal|low|medium|high|xhigh|max)(-fast)?$/;
+const CURSOR_GPT_MODEL_RE =
+	/^gpt-\d+(?:\.\d+){0,2}(?:-(?:codex-spark|codex-mini|codex-max|codex|luna|mini|max|nano|sol|terra))?$/;
+// `codex-max` is itself an intrinsic Cursor model, not an effort suffix. Keep
+// its canonical and canonical-fast forms intact before parsing effort aliases.
+const CURSOR_INTRINSIC_CODEX_MAX_RE = /^gpt-\d+(?:\.\d+){0,2}-codex-max(?:-fast)?$/;
+
+/** Build the ordered global USER rules Cursor expects for the current system prompt. */
+export function buildCursorRequestContextRules(systemPrompt: readonly string[] | undefined): CursorRule[] {
+	return normalizeSystemPrompts(systemPrompt).map((content, index) =>
+		create(CursorRuleSchema, {
+			fullPath: `/vib/system-prompt/${index}.mdc`,
+			content,
+			type: create(CursorRuleTypeSchema, {
+				type: {
+					case: "global",
+					value: create(CursorRuleTypeGlobalSchema, {}),
+				},
+			}),
+			source: CursorRuleSource.USER,
+		}),
+	);
+}
+
+export interface CursorWireModelResolution {
+	modelId: string;
+	parameters: RequestedModel_ModelParameterbytes[];
+	translated: boolean;
+}
+
+/** Resolve a Cursor model's GPT effort suffix into its wire model and parameter. */
+export function resolveCursorWireModelForTest(
+	model: Pick<Model<"cursor-agent">, "id" | "wireModelId">,
+): CursorWireModelResolution {
+	const wireModelId = model.wireModelId ?? model.id;
+	if (CURSOR_INTRINSIC_CODEX_MAX_RE.test(wireModelId)) {
+		return { modelId: wireModelId, parameters: [], translated: false };
+	}
+	const match = CURSOR_MODEL_EFFORT_RE.exec(wireModelId);
+	if (!match || !CURSOR_GPT_MODEL_RE.test(match[1])) {
+		return { modelId: wireModelId, parameters: [], translated: false };
+	}
+
+	const [, baseModelId, effort, fastSuffix] = match;
+	const modelId = `${baseModelId}${fastSuffix ?? ""}`;
+	return {
+		modelId,
+		parameters: [
+			create(RequestedModel_ModelParameterbytesSchema, {
+				id: "reasoning",
+				value: effort,
+			}),
+		],
+		translated: true,
+	};
+}
+
+/** Turn Cursor's opaque HTTP/2 failure into a useful transport diagnosis. */
+export function mapH2TransportError(error: unknown, baseUrl: string): unknown {
+	if (!error || typeof error !== "object") return error;
+	const candidate = error as { code?: unknown; message?: unknown };
+	if (candidate.code !== "ERR_HTTP2_ERROR" || typeof candidate.message !== "string") return error;
+	if (!/h2 is not supported/i.test(candidate.message)) return error;
+	return new Error(
+		`Cursor HTTP/2 is not supported by ${baseUrl}. Use an HTTP/2-capable endpoint, configure a proxy tunnel that preserves ALPN h2, or set providers.cursor.baseUrl to an HTTP/2 endpoint.`,
+		{ cause: error },
+	);
+}
+
+export const streamCursor: StreamFunction<"cursor-agent"> = (
+	model: Model<"cursor-agent">,
+	context: Context,
+	options?: CursorOptions,
+): AssistantMessageEventStream => {
+	const stream = new AssistantMessageEventStream();
+	const requestContextRules = buildCursorRequestContextRules(context.systemPrompt);
+
+	(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 proxiedSocket: Awaited<ReturnType<typeof connectProxiedSocket>> | null = null;
+		let heartbeatTimer: NodeJS.Timeout | null = null;
+		let onAbort: (() => void) | undefined;
+		let coordinator: CursorRequestCoordinator = undefined!;
+		const baseUrl = model.baseUrl || CURSOR_API_URL;
+
+		try {
+			const apiKey = options?.apiKey;
+			if (!apiKey) {
+				throw new Error("Cursor API key (access token) is required");
+			}
+			if (options?.signal?.aborted) {
+				throw new Error("Request was aborted");
+			}
+
+			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);
+			touchCursorConversation(conversationId);
+			const requestContextTools = buildMcpToolDefinitions(context.tools);
+			const targetUrl = new URL(baseUrl);
+			const proxyUrl = getProxyForUrl(model.provider, targetUrl);
+			if (options?.signal?.aborted) {
+				throw new Error("Request was aborted");
+			}
+			if (proxyUrl) {
+				proxiedSocket = await connectProxiedSocket(proxyUrl, baseUrl, {
+					signal: options?.signal,
+					timeoutMs: 30_000,
+				});
+				h2Client = http2.connect(baseUrl, { createConnection: () => proxiedSocket! });
+			} else {
+				h2Client = http2.connect(baseUrl);
+			}
+
+			options?.onStreamCreated?.();
+			h2Request = h2Client.request({
+				":method": "POST",
+				":path": "/agent.v1.AgentService/Run",
+				"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 stopHeartbeat = () => {
+				if (heartbeatTimer) {
+					clearInterval(heartbeatTimer);
+					heartbeatTimer = null;
+				}
+			};
+			let resolveH2: (() => void) | undefined;
+			let rejectH2: ((error: Error) => void) | undefined;
+			coordinator = new CursorRequestCoordinator(
+				h2Request,
+				stopHeartbeat,
+				() => {
+					const resolve = resolveH2;
+					resolveH2 = undefined;
+					resolve?.();
+				},
+				error => {
+					const reject = rejectH2;
+					rejectH2 = undefined;
+					reject?.(error);
+				},
+				options?.streamIdleTimeoutMs ?? getStreamIdleTimeoutMs(),
+			);
+			h2Client.on("error", error => coordinator.fail(error));
+			h2Request.on("error", error => coordinator.fail(error));
+
+			stream.push({ type: "start", partial: output });
+
+			let pendingBuffer = Buffer.alloc(0);
+			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);
+				touchCursorConversation(conversationId);
+			};
+
+			h2Request.on("trailers", trailers => {
+				const status = trailers["grpc-status"];
+				const msg = trailers["grpc-message"];
+				if (status && status !== "0") {
+					coordinator.fail(new Error(`gRPC error ${status}: ${decodeURIComponent(String(msg || ""))}`));
+				}
+			});
+			h2Request.on("end", () => {
+				if (!coordinator.hasTurnEnded()) {
+					coordinator.fail(new Error("Cursor stream ended before turnEnded"));
+				}
+			});
+			onAbort = () => {
+				coordinator.fail(new Error("Request was aborted"));
+			};
+			if (options?.signal) {
+				options.signal.addEventListener("abort", onAbort, { once: true });
+				if (options.signal.aborted) onAbort();
+			}
+
+			h2Request.on("data", (chunk: Buffer) => {
+				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) {
+							coordinator.fail(endError);
+						} else {
+							coordinator.turnEnded();
+						}
+						continue;
+					}
+
+					try {
+						const serverMessage = fromBinary(AgentServerMessageSchema, messageBytes);
+						const isTurnEnded =
+							serverMessage.message.case === "interactionUpdate" &&
+							serverMessage.message.value.message?.case === "turnEnded";
+						// Serialize handlers: exec messages can be asynchronous, and resolving the
+						// request on turnEnded before prior handlers finish loses their responses.
+						if (!coordinator.canAdmitTask()) continue;
+						coordinator.admit(() =>
+							handleServerMessage(
+								serverMessage,
+								output,
+								stream,
+								state,
+								blobStore,
+								coordinator,
+								options?.execHandlers,
+								options?.onToolResult,
+								usageState,
+								requestContextTools,
+								onConversationCheckpoint,
+								requestContextRules,
+							),
+						);
+
+						if (isTurnEnded) {
+							coordinator.turnEnded();
+						}
+					} catch (e) {
+						log("error", "parseServerMessage", { error: String(e) });
+					}
+				}
+			});
+
+			coordinator.enqueue(frameConnectMessage(requestBytes));
+
+			const sendHeartbeat = () => {
+				if (!coordinator.isActive()) return;
+				const heartbeatMessage = create(AgentClientMessageSchema, {
+					message: { case: "clientHeartbeat", value: create(ClientHeartbeatSchema, {}) },
+				});
+				const heartbeatBytes = toBinary(AgentClientMessageSchema, heartbeatMessage);
+				coordinator.enqueue(frameConnectMessage(heartbeatBytes));
+			};
+
+			heartbeatTimer = setInterval(sendHeartbeat, 5000);
+			await new Promise<void>((resolve, reject) => {
+				resolveH2 = resolve;
+				rejectH2 = reject;
+				const initialFailure = coordinator.failureError();
+				if (initialFailure) {
+					rejectH2 = undefined;
+					reject(initialFailure);
+				} else if (coordinator.hasTurnEnded() && !coordinator.isActive()) {
+					resolveH2 = undefined;
+					resolve();
+				}
+			});
+
+			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);
+				captureUnicodeEscapeEvidence(state.currentToolCall, 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) {
+			// Keep the completion promise terminal even for synchronous setup/write
+			// failures that may not emit a separate HTTP/2 error event.
+			const mappedError = mapH2TransportError(coordinator?.failureError() ?? error, baseUrl);
+			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
+			output.errorStatus = extractHttpStatusFromError(mappedError);
+			output.errorMessage = formatErrorMessageWithRetryAfter(mappedError);
+			output.duration = Date.now() - startTime;
+			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
+			stream.push({ type: "error", reason: output.stopReason, error: output });
+			stream.end();
+		} finally {
+			if (heartbeatTimer) {
+				clearInterval(heartbeatTimer);
+				heartbeatTimer = null;
+			}
+			if (options?.signal && onAbort) {
+				options.signal.removeEventListener("abort", onAbort);
+			}
+			if (h2Request && !h2Request.closed && !h2Request.destroyed) {
+				h2Request.end();
+			}
+			h2Client?.close();
+			proxiedSocket?.destroy();
+		}
+	})();
+
+	return stream;
+};
+
+type ToolCallState = ToolCall & {
+	index: number;
+	partialJson?: string;
+	kind: "mcp" | "todo_write" | "native" | "cursor-exec";
+	[kCursorExecResolved]?: true;
+};
+
+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>,
+	writer: CursorRequestWriter,
+	execHandlers: CursorExecHandlers | undefined,
+	onToolResult: CursorToolResultHandler | undefined,
+	usageState: UsageState,
+	requestContextTools: McpToolDefinition[],
+	onConversationCheckpoint?: (checkpoint: ConversationStateStructure) => void,
+	requestContextRules: CursorRule[] = [],
+): 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, writer);
+	} else if (msgCase === "execServerMessage") {
+		await handleExecServerMessage(
+			msg.message.value as ExecServerMessage,
+			writer,
+			execHandlers,
+			onToolResult,
+			requestContextTools,
+			output,
+			stream,
+			requestContextRules,
+		);
+	} else if (msgCase === "conversationCheckpointUpdate") {
+		handleConversationCheckpointUpdate(msg.message.value, output, usageState, onConversationCheckpoint);
+	}
+}
+
+function handleKvServerMessage(
+	kvMsg: KvServerMessage,
+	blobStore: Map<string, Uint8Array>,
+	writer: CursorRequestWriter,
+): 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);
+		writer.enqueue(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);
+		writer.enqueue(frameConnectMessage(responseBytes));
+
+		log("kvClient", "setBlobResult", { blobId: blobIdKey.slice(0, 40) });
+	}
+}
+
+function sendShellStreamEvent(
+	h2Request: CursorRequestWriter,
+	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: CursorRequestWriter,
+	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 = "";
+	let callbacksOpen = true;
+	const unregisterShellGate = h2Request.registerShellGate(() => {
+		callbacksOpen = false;
+		if (stdoutFlushTimer) clearTimeout(stdoutFlushTimer);
+		if (stderrFlushTimer) clearTimeout(stderrFlushTimer);
+	});
+
+	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) {
+			if (!callbacksOpen || !h2Request.isActive()) return;
+			stdoutBuffer += data;
+			if (stdoutBuffer.includes("\n") || stdoutBuffer.length > 4096) {
+				if (stdoutFlushTimer) {
+					clearTimeout(stdoutFlushTimer);
+					stdoutFlushTimer = null;
+				}
+				flushStdout();
+			} else {
+				scheduleStdoutFlush();
+			}
+		},
+		onStderr(data: string) {
+			if (!callbacksOpen || !h2Request.isActive()) return;
+			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);
+	callbacksOpen = false;
+	unregisterShellGate();
+
+	log("shellStream", "done", { elapsed: Date.now() - startTs });
+}
+
+function sendShellStreamExitFromResult(
+	h2Request: CursorRequestWriter,
+	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: CursorRequestWriter,
+	execHandlers: CursorExecHandlers | undefined,
+	onToolResult: CursorToolResultHandler | undefined,
+	requestContextTools: McpToolDefinition[],
+	output: AssistantMessage,
+	stream: AssistantMessageEventStream,
+	requestContextRules: CursorRule[] = [],
+): Promise<void> {
+	const execCase = execMsg.message.case;
+	log("exec", "dispatch", { execCase, execId: execMsg.execId, hasHandlers: !!execHandlers });
+	if (execCase === "requestContextArgs") {
+		const requestContext = create(RequestContextSchema, {
+			rules: requestContextRules,
+			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;
+		}
+		case "piReadArgs": {
+			const args = execMsg.message.value;
+			const toolCallId = crypto.randomUUID();
+			synthesizeCursorExecToolCall(output, stream, toolCallId, "read", {
+				path: piReadDisplayPath(args.path, args.offset, args.limit),
+			});
+			const call = { args, toolCallId };
+			const { execResult } = await resolveExecHandler(
+				call,
+				execHandlers?.piRead?.bind(execHandlers),
+				onToolResult,
+				buildPiReadResult,
+				buildPiReadError,
+				buildPiReadError,
+			);
+			sendExecClientMessage(h2Request, execMsg, "piReadResult", execResult);
+			return;
+		}
+		case "piBashArgs": {
+			const args = execMsg.message.value;
+			const toolCallId = crypto.randomUUID();
+			synthesizeCursorExecToolCall(output, stream, toolCallId, "bash", {
+				command: args.command,
+				timeout: piTimeout(args.timeout),
+			});
+			const call = { args, toolCallId };
+			const { execResult } = await resolveExecHandler(
+				call,
+				execHandlers?.piBash?.bind(execHandlers),
+				onToolResult,
+				buildPiBashResult,
+				buildPiBashError,
+				buildPiBashError,
+			);
+			sendExecClientMessage(h2Request, execMsg, "piBashResult", execResult);
+			return;
+		}
+		case "piEditArgs": {
+			const args = execMsg.message.value;
+			const toolCallId = crypto.randomUUID();
+			synthesizeCursorExecToolCall(output, stream, toolCallId, "edit", {
+				path: args.path,
+				edits: args.edits.map(edit => ({ old_text: edit.oldText, new_text: edit.newText })),
+			});
+			const call = { args, toolCallId };
+			const { execResult } = await resolveExecHandler(
+				call,
+				execHandlers?.piEdit?.bind(execHandlers),
+				onToolResult,
+				buildPiEditResult,
+				buildPiEditRejected,
+				buildPiEditError,
+			);
+			sendExecClientMessage(h2Request, execMsg, "piEditResult", execResult);
+			return;
+		}
+		case "piWriteArgs": {
+			const args = execMsg.message.value;
+			const toolCallId = crypto.randomUUID();
+			synthesizeCursorExecToolCall(output, stream, toolCallId, "write", {
+				path: args.path,
+				content: args.content,
+			});
+			const call = { args, toolCallId };
+			const { execResult } = await resolveExecHandler(
+				call,
+				execHandlers?.piWrite?.bind(execHandlers),
+				onToolResult,
+				buildPiWriteResult,
+				buildPiWriteRejected,
+				buildPiWriteError,
+			);
+			sendExecClientMessage(h2Request, execMsg, "piWriteResult", execResult);
+			return;
+		}
+		case "piGrepArgs": {
+			const args = execMsg.message.value;
+			const toolCallId = crypto.randomUUID();
+			synthesizeCursorExecToolCall(output, stream, toolCallId, "search", {
+				pattern: args.literal === true ? piEscapeRegexLiteral(args.pattern) : args.pattern,
+				paths: [args.glob ? piJoinPath(args.path, args.glob) : args.path || "."],
+				// The model-facing search schema uses `i: true` for
+				// case-insensitive matching. Keep the field absent otherwise.
+				...(args.ignoreCase === true ? { i: true } : {}),
+				context: args.context,
+				limit: piLimit(args.limit),
+			});
+			const call = { args, toolCallId };
+			const { execResult } = await resolveExecHandler(
+				call,
+				execHandlers?.piGrep?.bind(execHandlers),
+				onToolResult,
+				buildPiGrepResult,
+				buildPiGrepError,
+				buildPiGrepError,
+			);
+			sendExecClientMessage(h2Request, execMsg, "piGrepResult", execResult);
+			return;
+		}
+		case "piFindArgs": {
+			const args = execMsg.message.value;
+			const toolCallId = crypto.randomUUID();
+			synthesizeCursorExecToolCall(output, stream, toolCallId, "find", {
+				paths: [piJoinPath(args.path, args.pattern)],
+				limit: piLimit(args.limit),
+			});
+			const call = { args, toolCallId };
+			const { execResult } = await resolveExecHandler(
+				call,
+				execHandlers?.piFind?.bind(execHandlers),
+				onToolResult,
+				buildPiFindResult,
+				buildPiFindError,
+				buildPiFindError,
+			);
+			sendExecClientMessage(h2Request, execMsg, "piFindResult", execResult);
+			return;
+		}
+		case "piLsArgs": {
+			const args = execMsg.message.value;
+			const toolCallId = crypto.randomUUID();
+			synthesizeCursorExecToolCall(output, stream, toolCallId, "read", { path: piLsPath(args.path) });
+			const call = { args, toolCallId };
+			const { execResult } = await resolveExecHandler(
+				call,
+				execHandlers?.piLs?.bind(execHandlers),
+				onToolResult,
+				buildPiLsResult,
+				buildPiLsError,
+				buildPiLsError,
+			);
+			sendExecClientMessage(h2Request, execMsg, "piLsResult", execResult);
+			return;
+		}
+		case "mcpStateExecArgs": {
+			sendExecClientMessage(
+				h2Request,
+				execMsg,
+				"mcpStateExecResult",
+				buildMcpStateResult(requestContextTools, execMsg.message.value.serverIdentifiers),
+			);
+			return;
+		}
+		case "executeHookArgs": {
+			const execResult = buildNeutralHookResult(execMsg.message.value.request);
+			if (!execResult) {
+				sendExecClientThrow(
+					h2Request,
+					execMsg,
+					`Unsupported hook request: ${execMsg.message.value.request?.request.case ?? "unset"}`,
+					"unknown_hook_request",
+				);
+				return;
+			}
+			sendExecClientMessage(h2Request, execMsg, "executeHookResult", execResult);
+			return;
+		}
+		case "shellAllowlistPrecheckArgs": {
+			sendExecClientMessage(
+				h2Request,
+				execMsg,
+				"shellAllowlistPrecheckResult",
+				create(ShellAllowlistPrecheckResultSchema, { allowlisted: false }),
+			);
+			return;
+		}
+		case "mcpAllowlistPrecheckArgs": {
+			sendExecClientMessage(
+				h2Request,
+				execMsg,
+				"mcpAllowlistPrecheckResult",
+				create(McpAllowlistPrecheckResultSchema, { allowlisted: false }),
+			);
+			return;
+		}
+		case "webFetchAllowlistPrecheckArgs": {
+			sendExecClientMessage(
+				h2Request,
+				execMsg,
+				"webFetchAllowlistPrecheckResult",
+				create(WebFetchAllowlistPrecheckResultSchema, { allowlisted: false }),
+			);
+			return;
+		}
+		default: {
+			log("warn", "unhandledExecMessage", { execCase });
+			sendExecClientThrow(
+				h2Request,
+				execMsg,
+				`No handler for exec message of type ${execCase}`,
+				"exec_variant_unsupported",
+			);
+		}
+	}
+}
+
+function sendExecClientMessage<TCase extends NonNullable<ExecClientMessage["message"]["case"]>>(
+	h2Request: CursorRequestWriter,
+	execMsg: ExecServerMessage,
+	messageCase: TCase,
+	value: Extract<ExecClientMessage["message"], { case: TCase }>["value"],
+): void {
+	const execClientMessage = create(ExecClientMessageSchema, {
+		id: execMsg.id,
+		execId: execMsg.execId,
+		message: { case: messageCase, value } as ExecClientMessage["message"],
+	});
+
+	const clientMessage = create(AgentClientMessageSchema, {
+		message: { case: "execClientMessage", value: execClientMessage },
+	});
+
+	const responseBytes = toBinary(AgentClientMessageSchema, clientMessage);
+	h2Request.enqueue(frameConnectMessage(responseBytes));
+
+	log("execClientMessage", messageCase, value);
+}
+
+function sendExecClientThrow(
+	h2Request: CursorRequestWriter,
+	execMsg: ExecServerMessage,
+	error: string,
+	errorCode: string,
+): void {
+	const controlMessage = create(ExecClientControlMessageSchema, {
+		message: {
+			case: "throw",
+			value: create(ExecClientThrowSchema, { id: execMsg.id, error, errorCode }),
+		},
+	});
+	const clientMessage = create(AgentClientMessageSchema, {
+		message: { case: "execClientControlMessage", value: controlMessage },
+	});
+	h2Request.enqueue(frameConnectMessage(toBinary(AgentClientMessageSchema, clientMessage)));
+	sendExecClientStreamClose(h2Request, execMsg);
+}
+
+function sendExecClientStreamClose(h2Request: CursorRequestWriter, 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.enqueue(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) };
+	}
+}
+
+/** Exported for deterministic coverage of ordered server-message handling. */
+export function createCursorMessageQueueForTest(onError?: (error: unknown) => void): {
+	enqueue(handler: () => void | Promise<void>): Promise<void>;
+	drain(): Promise<void>;
+} {
+	let chain = Promise.resolve();
+	return {
+		enqueue(handler) {
+			const result = chain.then(handler);
+			chain = result.catch(error => {
+				onError?.(error);
+			});
+			return result;
+		},
+		drain() {
+			return chain;
+		},
+	};
+}
+
+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[] } };
+	tool?: { case?: string; value?: { args?: { todos?: CursorTodoItem[] } } };
+}
+
+function buildTodoWriteArgs(toolCall: CursorUpdateTodosToolCall): {
+	todos: Array<{ id?: string; content: string; activeForm: string; status: "pending" | "in_progress" | "completed" }>;
+} | null {
+	const updateCall =
+		toolCall.tool?.case === "updateTodosToolCall" ? toolCall.tool.value : toolCall.updateTodosToolCall;
+	const todos = updateCall?.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),
+		})),
+	};
+}
+
+// Map a cursor ToolCall oneof field name (e.g. "shellToolCall") to a display tool
+// name. Mirrors cli-jaw's cursorToolKindLabel (src/agent/events/cursor.ts) so the
+// two surfaces label cursor-native tools identically.
+const CURSOR_NATIVE_KIND_ALIASES: Record<string, string> = {
+	shell: "bash",
+	read: "read",
+	write: "write",
+	delete: "delete",
+	edit: "edit",
+	grep: "grep",
+	glob: "glob",
+	ls: "ls",
+	semSearch: "codebase_search",
+	webSearch: "web_search",
+	fetch: "fetch",
+	task: "task",
+	createPlan: "create_plan",
+	askQuestion: "ask_question",
+	readLints: "read_lints",
+	applyAgentDiff: "apply_diff",
+};
+
+function cursorNativeToolName(kindKey: string): string {
+	const base = kindKey.replace(/ToolCall$/i, "");
+	if (!base) return "tool";
+	return CURSOR_NATIVE_KIND_ALIASES[base] ?? base;
+}
+
+// Cursor's model sometimes calls its own native IDE tools (shell/glob/grep/…)
+// instead of the advertised MCP tools. Those arrive as ToolCall oneof variants we
+// do not otherwise handle (everything except mcpToolCall / updateTodosToolCall), so
+// without this they are silently dropped and never render. Build a generic toolCall
+// block from whichever *ToolCall field is set so the call (and its result) is shown.
+
+/** Hard node budget for one native-payload conversion; bounds hostile or cyclic graphs. */
+const CURSOR_JSON_SAFE_MAX_NODES = 10_000;
+const CURSOR_JSON_SAFE_MAX_DEPTH = 100;
+
+/**
+ * Total conversion of a Cursor protobuf payload into plain JSON-safe data.
+ *
+ * protobuf-es v2 messages are plain objects, but they carry `$typeName`
+ * markers, `bigint` fields (e.g. `fileSize`, `durationMs`, `timestampMs`,
+ * `fileOutputThresholdBytes`), and `Uint8Array` blobs. None of those may leak
+ * into assistant message content: toolCall `arguments` are staged into managed
+ * snapshots, persisted to the JSONL transcript, and replayed to providers —
+ * all of which require `JSON.stringify`-safe values. Attaching the raw payload
+ * is exactly the local-snapshot producer defect class behind issue #4578.
+ *
+ * Rules: `$typeName` is stripped, safe-range bigints become numbers (decimal
+ * strings beyond `Number.MAX_SAFE_INTEGER`), byte arrays become base64
+ * strings, dates become ISO strings, functions/symbols are dropped, cycles
+ * and over-depth values collapse to null, and containers stop accepting
+ * entries once the shared node budget is exhausted.
+ */
+function cursorJsonSafeValue(value: unknown, path?: Set<object>, budget?: { remaining: number }, depth = 0): unknown {
+	const seen = path ?? new Set<object>();
+	const nodes = budget ?? { remaining: CURSOR_JSON_SAFE_MAX_NODES };
+	if (nodes.remaining-- <= 0) return null;
+	if (depth >= CURSOR_JSON_SAFE_MAX_DEPTH) return null;
+	if (typeof value === "bigint") {
+		return value <= BigInt(Number.MAX_SAFE_INTEGER) && value >= BigInt(-Number.MAX_SAFE_INTEGER)
+			? Number(value)
+			: value.toString();
+	}
+	if (typeof value === "function" || typeof value === "symbol" || value === undefined) return null;
+	if (typeof value === "number" && !Number.isFinite(value)) return null;
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return null;
+	if (value instanceof Uint8Array)
+		return Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString("base64");
+	if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.toISOString() : null;
+	seen.add(value);
+	try {
+		if (Array.isArray(value)) {
+			const array: unknown[] = [];
+			for (const entry of value) {
+				if (nodes.remaining <= 0) break;
+				array.push(cursorJsonSafeValue(entry, seen, nodes, depth + 1));
+			}
+			return array;
+		}
+		const record: Record<string, unknown> = {};
+		for (const [key, entry] of Object.entries(value)) {
+			if (key === "$typeName") continue;
+			if (nodes.remaining <= 0) break;
+			record[key] = cursorJsonSafeValue(entry, seen, nodes, depth + 1);
+		}
+		return record;
+	} catch {
+		return null;
+	} finally {
+		seen.delete(value);
+	}
+}
+
+/** Exported for direct regression coverage of the JSON-safety boundary. */
+export function cursorJsonSafeValueForTest(value: unknown): unknown {
+	return cursorJsonSafeValue(value);
+}
+
+function selectMcpToolCall(toolCall: any): any {
+	return toolCall?.tool?.case === "mcpToolCall" ? toolCall.tool.value : toolCall?.mcpToolCall;
+}
+
+const CURSOR_EXEC_OWNED_TOOL_CASES = new Set([
+	"piReadToolCall",
+	"piBashToolCall",
+	"piEditToolCall",
+	"piWriteToolCall",
+	"piGrepToolCall",
+	"piFindToolCall",
+	"piLsToolCall",
+]);
+
+function isExecOwnedToolCall(toolCall: any): boolean {
+	return CURSOR_EXEC_OWNED_TOOL_CASES.has(toolCall?.tool?.case);
+}
+
+export function buildNativeToolCallBlock(
+	toolCall: Record<string, unknown>,
+	callId: string,
+	index: number,
+): ToolCallState | null {
+	const oneof = toolCall.tool as { case?: string; value?: unknown } | undefined;
+	if (oneof?.case && oneof.value && typeof oneof.value === "object") {
+		const args = (oneof.value as { args?: unknown }).args;
+		const convertedArgs = cursorJsonSafeValue(args ?? oneof.value);
+		return {
+			type: "toolCall",
+			id: callId,
+			name: cursorNativeToolName(oneof.case),
+			arguments:
+				convertedArgs && typeof convertedArgs === "object" && !Array.isArray(convertedArgs)
+					? (convertedArgs as Record<string, unknown>)
+					: { raw: convertedArgs },
+			index,
+			kind: "native",
+		};
+	}
+	for (const [key, payload] of Object.entries(toolCall)) {
+		if (!/ToolCall$/.test(key) || !payload || typeof payload !== "object") continue;
+		if (key === "mcpToolCall" || key === "updateTodosToolCall") continue;
+		const args = (payload as { args?: unknown }).args;
+		const hasObjectArgs = args !== null && typeof args === "object";
+		const convertedArgs = hasObjectArgs ? cursorJsonSafeValue(args) : undefined;
+		const safeArguments =
+			convertedArgs !== undefined &&
+			convertedArgs !== null &&
+			typeof convertedArgs === "object" &&
+			!Array.isArray(convertedArgs)
+				? (convertedArgs as Record<string, unknown>)
+				: { raw: hasObjectArgs ? convertedArgs : cursorJsonSafeValue(payload) };
+		return {
+			type: "toolCall",
+			id: callId,
+			name: cursorNativeToolName(key),
+			arguments: safeArguments,
+			index,
+			kind: "native",
+		};
+	}
+	return null;
+}
+
+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 synthesizeCursorExecToolCall(
+	output: AssistantMessage,
+	stream: AssistantMessageEventStream,
+	toolCallId: string,
+	name: string,
+	args: Record<string, unknown>,
+): void {
+	const block: ToolCallState = {
+		type: "toolCall",
+		id: toolCallId,
+		name,
+		arguments: cursorJsonSafeValue(args) as Record<string, unknown>,
+		index: output.content.length,
+		kind: "cursor-exec",
+		[kCursorExecResolved]: true,
+	};
+	output.content.push(block);
+	const contentIndex = output.content.length - 1;
+	stream.push({ type: "toolcall_start", contentIndex, partial: output });
+	delete (block as Partial<ToolCallState>).index;
+	delete (block as Partial<ToolCallState>).kind;
+	stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial: output });
+}
+
+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" && isExecOwnedToolCall(update.message.value.toolCall)) {
+		// Pi stream call IDs and exec IDs are distinct namespaces; without a shared
+		// correlation field, suppress the streamed variant and synthesize from exec.
+		log("exec", "streamedToolCallOwnedByExec", { case: update.message.value.toolCall?.tool?.case });
+	} else if (updateCase === "toolCallStarted") {
+		const toolCall = update.message.value.toolCall;
+		if (toolCall) {
+			const mcpCall = selectMcpToolCall(toolCall);
+			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 });
+				return;
+			}
+
+			// Fallback: cursor-native tool variants (shell/glob/grep/…) we don't model
+			// explicitly. Render them so the call and its result are visible instead of
+			// vanishing.
+			const nativeBlock = buildNativeToolCallBlock(
+				toolCall,
+				update.message.value.callId || crypto.randomUUID(),
+				output.content.length,
+			);
+			if (nativeBlock) {
+				output.content.push(nativeBlock);
+				state.setToolCall(nativeBlock);
+				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") {
+				captureUnicodeEscapeEvidence(state.currentToolCall, state.currentToolCall.partialJson ?? "");
+				const decodedArgs = decodeMcpArgsMap(selectMcpToolCall(toolCall)?.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 = flattenToolRootCombinators(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: "pi-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 last 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, modelId?: string): string[] {
+	const systemPrompts = normalizeSystemPrompts(systemPrompt);
+	const jsons =
+		systemPrompts.length === 0
+			? [JSON.stringify({ role: "system", content: "You are a helpful assistant." })]
+			: systemPrompts.map(content => JSON.stringify({ role: "system", content }));
+	// Composer-harness models need anchor/edit discipline pinned ahead of any
+	// host/default prompt (see composer-discipline.ts for the observed failure modes).
+	if (modelId !== undefined && isComposerHarnessModel(modelId)) {
+		jsons.unshift(JSON.stringify({ role: "system", content: CURSOR_COMPOSER_EDIT_DISCIPLINE_PROMPT }));
+	}
+	return jsons;
+}
+
+function buildRootPromptMessagesJson(
+	messages: Message[],
+	systemPromptIds: Uint8Array[],
+	blobStore: Map<string, Uint8Array>,
+): Uint8Array[] {
+	const entries: Uint8Array[] = [...systemPromptIds];
+	const lastUserIdx = findLastUserMessageIndex(messages);
+
+	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 === lastUserIdx) 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 last 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>): 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;
+		}
+
+		// Check if this is the last user message (which goes in the action, not turns)
+		let isLastUserMessage = true;
+		for (let j = i + 1; j < messages.length; j++) {
+			if (messages[j].role === "user" || messages[j].role === "developer") {
+				isLastUserMessage = false;
+				break;
+			}
+		}
+		if (isLastUserMessage) {
+			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[]): {
+	rootPromptMessagesJson: unknown[];
+	turnUserMessagesJson: JsonValue[];
+} {
+	const blobStore = new Map<string, Uint8Array>();
+	const rootPromptMessagesJson = buildRootPromptMessagesJson(messages, [], blobStore).map(blobId =>
+		JSON.parse(new TextDecoder().decode(readCursorBlob(blobStore, blobId))),
+	);
+	const turnUserMessagesJson: JsonValue[] = [];
+	for (const turnBlobId of buildConversationTurns(messages, blobStore)) {
+		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));
+	}
+	return { rootPromptMessagesJson, turnUserMessagesJson };
+}
+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, model.id).map(json =>
+		storeCursorBlob(blobStore, new TextEncoder().encode(json)),
+	);
+
+	const lastMessage = context.messages[context.messages.length - 1];
+	let userContent: string | (TextContent | ImageContent)[] | undefined;
+	let userText = "";
+	let hasUserImages = false;
+	if (lastMessage?.role === "user" || lastMessage?.role === "developer") {
+		userContent = lastMessage.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 the last user message).
+	// This populates the UI-side history view (`turns[]`).
+	const turns = buildConversationTurns(context.messages, blobStore);
+
+	// 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);
+
+	// 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 resolvedModel = resolveCursorWireModelForTest(model);
+	const modelDetails = create(ModelDetailsSchema, {
+		modelId: resolvedModel.modelId,
+		displayModelId: model.id,
+		displayName: model.name,
+	});
+
+	const runRequest = create(AgentRunRequestSchema, {
+		conversationState,
+		action,
+		modelDetails,
+		conversationId: state.conversationId,
+		...(resolvedModel.translated
+			? {
+					requestedModel: create(RequestedModelSchema, {
+						modelId: resolvedModel.modelId,
+						parameters: resolvedModel.parameters,
+					}),
+				}
+			: {}),
+	});
+
+	options?.onPayload?.(runRequest, model, options?.attemptScope);
+
+	// 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");
+}