pi-cursor-sdk 0.1.19 → 0.1.21

package/src/cursor-provider-turn-prepare.ts

@@ -0,0 +1,216 @@
+import type { SimpleStreamOptions } from "@earendil-works/pi-ai";
+import { Agent } from "@cursor/sdk";
+import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
+import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./cursor-sdk-output-filter.js";
+import {
+	acquireSessionCursorAgent,
+	buildCursorSessionSendPrompt,
+	planCursorSessionSend,
+	resetSessionCursorAgent,
+} from "./cursor-session-agent.js";
+import type { CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
+import { estimateCursorPromptInputTokens, getCursorPromptOptions } from "./cursor-usage-accounting.js";
+import { getActiveContextToolNames } from "./cursor-context-tools.js";
+import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
+import { abandonSessionCursorAgent, cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { createCursorNativeReplayId } from "./cursor-provider-live-run-drain.js";
+import { getEffectiveCursorAgentMode, getEffectiveFastForModelId } from "./cursor-state.js";
+import { buildCursorModelSelection } from "./model-discovery.js";
+import { getEffectiveCursorSettingSources } from "./cursor-setting-sources.js";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-snapshot.js";
+import {
+	buildCursorToolManifestText,
+	resolveCursorToolManifestEnabled,
+} from "./cursor-tool-manifest.js";
+import { isCursorNativeToolDisplayRuntimeEnabled } from "./cursor-native-tool-display.js";
+import { MISSING_CURSOR_API_KEY_MESSAGE } from "./cursor-provider-errors.js";
+import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
+import { resolveCursorApiKey } from "./cursor-provider-turn-api-key.js";
+import type {
+	CursorProviderTurnPrepareResult,
+	CursorProviderTurnRunnerParams,
+} from "./cursor-provider-turn-types.js";
+import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+
+export interface PrepareCursorProviderTurnParams {
+	params: CursorProviderTurnRunnerParams;
+	cwd: string;
+	resolvedApiKey: string;
+	sdkEventDebug: CursorSdkEventDebugSink | undefined;
+	throwIfAborted: () => void;
+}
+
+export async function prepareCursorProviderTurn(
+	prepareParams: PrepareCursorProviderTurnParams,
+): Promise<CursorProviderTurnPrepareResult> {
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted } = prepareParams;
+	const { model, context, options } = params;
+
+	let restoreCursorSdkOutputFilter: (() => void) | undefined;
+	let sessionAgentScopeKey: string | undefined;
+	let liveRun: CursorLiveRun | undefined;
+	let completed = false;
+
+	try {
+		const fastEnabled = getEffectiveFastForModelId(model.id);
+		const agentMode = getEffectiveCursorAgentMode();
+		const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
+		const settingSources = getEffectiveCursorSettingSources();
+
+		installCursorMcpToolTimeoutOverride();
+		restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
+		const queuedBridgeRequestsBeforeLiveRun: CursorPiBridgeToolRequest[] = [];
+		let liveRunForBridgeQueue: CursorLiveRun | undefined;
+
+		const sessionAgentAcquireParams = {
+			apiKey: resolvedApiKey,
+			agentMode,
+			cwd,
+			modelSelection: selection,
+			settingSources,
+			debugRecorder: sdkEventDebug,
+			onBridgeToolRequest: (request: CursorPiBridgeToolRequest) => {
+				if (liveRunForBridgeQueue && !liveRunForBridgeQueue.disposed) {
+					cursorLiveRuns.queueEvent(liveRunForBridgeQueue, { type: "bridge-tool", request });
+				} else {
+					queuedBridgeRequestsBeforeLiveRun.push(request);
+				}
+			},
+			createAgent: (createOptions: Parameters<typeof Agent.create>[0]) =>
+				suppressCursorSdkOutput(() => Agent.create(createOptions)),
+		};
+		let sessionAgentLease = await acquireSessionCursorAgent(sessionAgentAcquireParams);
+		sessionAgentScopeKey = sessionAgentLease.scopeKey;
+		throwIfAborted();
+
+		const buildPromptOptions = (plan: ReturnType<typeof planCursorSessionSend>) => {
+			const promptOptions = getCursorPromptOptions(model);
+			if (plan.mode !== "bootstrap" || !resolveCursorToolManifestEnabled()) {
+				return promptOptions;
+			}
+			return {
+				...promptOptions,
+				toolManifest: buildCursorToolManifestText({
+					bridgeSnapshot: sessionAgentLease.bridgeRun?.snapshot,
+					piBridgeEnabled: resolveCursorPiToolBridgeEnabled(),
+				}),
+			};
+		};
+		let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+		let promptOptions = buildPromptOptions(sendPlan);
+		let prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
+		if (sendPlan.resetAgent) {
+			await resetSessionCursorAgent(sessionAgentScopeKey);
+			sessionAgentLease = await acquireSessionCursorAgent(sessionAgentAcquireParams);
+			sessionAgentScopeKey = sessionAgentLease.scopeKey;
+			sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+			promptOptions = buildPromptOptions(sendPlan);
+			prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
+		}
+		const bootstrap = sendPlan.mode === "bootstrap";
+		const agent = sessionAgentLease.agent;
+		const bridgeRun = sessionAgentLease.bridgeRun;
+		const sendPayload = {
+			text: prompt.text,
+			images: prompt.images.length > 0 ? prompt.images : undefined,
+		};
+		const sessionBridgeRun = bridgeRun;
+		const promptInputTokens = estimateCursorPromptInputTokens(prompt, promptOptions);
+		const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+		const activeToolNames = getActiveContextToolNames(context);
+		sdkEventDebug?.recordProviderMeta({
+			model: {
+				id: model.id,
+				provider: model.provider,
+				api: model.api,
+				reasoning: options?.reasoning ?? "off",
+				fastEnabled,
+				selection,
+			},
+			settingSources: settingSources ?? null,
+			sendState: sessionAgentLease.sendState,
+			sendPlan,
+			promptOptions,
+			toolManifestEnabled: resolveCursorToolManifestEnabled(),
+			agentMode,
+			activeToolNames: activeToolNames ? [...activeToolNames] : [],
+			sessionAgentScopeKey,
+			bridgeRunId: bridgeRun?.id,
+		});
+		const nativeReplayId = createCursorNativeReplayId();
+		const textDeltas: string[] = [];
+		const useLiveRun = useNativeToolReplay || bridgeRun !== undefined;
+		liveRun = useLiveRun
+			? cursorLiveRuns.start({
+					id: useNativeToolReplay ? nativeReplayId : bridgeRun?.id ?? nativeReplayId,
+					agent,
+					bridgeRun,
+					sessionBridgeRun,
+					sessionAgentScopeKey,
+					promptInputTokens,
+					textDeltas,
+					debugRecorder: sdkEventDebug,
+				})
+			: undefined;
+		if (liveRun) {
+			liveRunForBridgeQueue = liveRun;
+			for (const request of queuedBridgeRequestsBeforeLiveRun.splice(0)) {
+				cursorLiveRuns.queueEvent(liveRun, { type: "bridge-tool", request });
+			}
+		}
+		const turnCoordinator = new CursorSdkTurnCoordinator({
+			stream: params.stream,
+			partial: params.partial,
+			cwd,
+			resolvedApiKey,
+			liveRun,
+			useNativeToolReplay,
+			activeToolNames,
+			nativeReplayId,
+			textDeltas,
+			debugRecorder: sdkEventDebug,
+		});
+
+		completed = true;
+		return {
+			agent,
+			cwd,
+			payload: sendPayload,
+			meta: {
+				sendPlan,
+				prompt,
+				bootstrap,
+				promptInputTokens,
+				useNativeToolReplay,
+				bridgeEnabled: bridgeRun !== undefined,
+				nativeReplayId,
+				agentMode,
+			},
+			contextWindowAgentId: agent.agentId,
+			textDeltas,
+			sessionAgentScopeKey,
+			sessionAgentLease,
+			restoreCursorSdkOutputFilter,
+			runtime: liveRun
+				? { kind: "live", liveRun, turnCoordinator }
+				: { kind: "direct", turnCoordinator },
+		};
+	} finally {
+		if (!completed) {
+			if (liveRun && !liveRun.disposed) {
+				await cursorLiveRuns
+					.release(liveRun)
+					.catch(() => abandonSessionCursorAgent(sessionAgentScopeKey).catch(() => {}));
+			} else {
+				await abandonSessionCursorAgent(sessionAgentScopeKey).catch(() => {});
+			}
+			restoreCursorSdkOutputFilter?.();
+		}
+	}
+}
+
+export function requireCursorApiKey(options: SimpleStreamOptions | undefined): string {
+	const apiKey = resolveCursorApiKey(options?.apiKey);
+	if (!apiKey) throw new Error(MISSING_CURSOR_API_KEY_MESSAGE);
+	return apiKey;
+}

package/src/cursor-provider-turn-runner.ts

@@ -0,0 +1,138 @@
+import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import { drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
+import { getCursorSessionCwd } from "./cursor-session-cwd.js";
+import { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
+import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
+import {
+	discardIncompleteToolsFromPrepared,
+	emitCursorLiveTurn,
+} from "./cursor-provider-turn-emit.js";
+import { CursorRunFinalizer, type CursorLiveRunCompletion } from "./cursor-provider-run-finalizer.js";
+import { prepareCursorProviderTurn, requireCursorApiKey } from "./cursor-provider-turn-prepare.js";
+import { sendCursorProviderTurn } from "./cursor-provider-turn-send.js";
+import type {
+	CursorProviderTurnPrepareResult,
+	CursorProviderTurnRunnerParams,
+	CursorProviderTurnSendResult,
+} from "./cursor-provider-turn-types.js";
+
+export { resolveCursorApiKey } from "./cursor-provider-turn-api-key.js";
+export type { CursorProviderTurnRunnerParams } from "./cursor-provider-turn-types.js";
+
+export class CursorProviderTurnRunner {
+	private sdkEventDebug: CursorSdkEventDebugSink | undefined;
+	private resolvedApiKey: string | undefined;
+
+	constructor(private readonly params: CursorProviderTurnRunnerParams) {}
+
+	private get options() {
+		return this.params.options;
+	}
+
+	private throwIfAborted(): void {
+		if (this.options?.signal?.aborted) throw new CursorLiveRunAbortError();
+	}
+
+	private discardIncompleteTools(
+		prepared: CursorProviderTurnPrepareResult | undefined,
+		outcome: import("./cursor-incomplete-tool-visibility.js").IncompleteCursorToolRunOutcomeInput,
+	): void {
+		discardIncompleteToolsFromPrepared(prepared, outcome);
+	}
+
+	async run(sdkAbortErrorSuppression: ReturnType<typeof installCursorSdkAbortErrorSuppression>): Promise<void> {
+		const { stream, partial, model, context, options, sdkEventDebugRef } = this.params;
+		let prepared: CursorProviderTurnPrepareResult | undefined;
+		let sendResult: CursorProviderTurnSendResult | undefined;
+		let liveCompletion: CursorLiveRunCompletion | undefined;
+		const runFinalizer = new CursorRunFinalizer({
+			runnerParams: this.params,
+			sdkEventDebug: () => this.sdkEventDebug,
+			sdkAbortErrorSuppression,
+			resolvedApiKey: () => this.resolvedApiKey,
+		});
+
+		try {
+			stream.push({ type: "start", partial });
+			this.throwIfAborted();
+			const cwd = getCursorSessionCwd();
+			this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
+				cwd,
+				modelId: model.id,
+				provider: model.provider,
+			});
+			sdkEventDebugRef.current = this.sdkEventDebug;
+			this.sdkEventDebug?.recordContextSnapshot(context);
+			if (
+				(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+				"stream_ended"
+			) {
+				return;
+			}
+
+			this.resolvedApiKey = requireCursorApiKey(options);
+			prepared = await prepareCursorProviderTurn({
+				params: this.params,
+				cwd,
+				resolvedApiKey: this.resolvedApiKey,
+				sdkEventDebug: this.sdkEventDebug,
+				throwIfAborted: () => this.throwIfAborted(),
+			});
+
+			sendResult = await sendCursorProviderTurn({
+				params: this.params,
+				prepared,
+				sdkEventDebug: this.sdkEventDebug,
+				sdkAbortErrorSuppression,
+				throwIfAborted: () => this.throwIfAborted(),
+			});
+			const { send } = sendResult;
+
+			if (prepared.runtime.kind === "live") {
+				liveCompletion = runFinalizer.startLiveRunCompletion({
+					send,
+					prepared,
+					modelId: model.id,
+					discardIncompleteTools: (outcome) => this.discardIncompleteTools(prepared, outcome),
+				});
+				await emitCursorLiveTurn({
+					params: this.params,
+					prepared,
+					sdkEventDebug: this.sdkEventDebug,
+					discardIncompleteTools: (outcome) => this.discardIncompleteTools(prepared, outcome),
+				});
+				return;
+			}
+
+			const outcome = await awaitFinalizeCursorRunOutcome({
+				run: send.run,
+				prepared,
+				cursorAgentMessageOffset: send.cursorAgentMessageOffset,
+				modelId: model.id,
+				signal: options?.signal,
+				runResultFallback: send.run.result,
+				resolvedApiKey: this.resolvedApiKey,
+				optionsApiKey: options?.apiKey,
+				sdkEventDebug: this.sdkEventDebug,
+				contextWindowAgentId: prepared.contextWindowAgentId,
+			});
+			await runFinalizer.applyTerminalEvent({ kind: "direct", prepared, outcome });
+		} catch (error) {
+			await runFinalizer.applyTerminalEvent({ kind: "error", prepared, error });
+		} finally {
+			await runFinalizer.cleanup(prepared, sendResult, liveCompletion);
+		}
+	}
+
+	async handleOuterCatch(error: unknown): Promise<void> {
+		const runFinalizer = new CursorRunFinalizer({
+			runnerParams: this.params,
+			sdkEventDebug: () => this.sdkEventDebug,
+			sdkAbortErrorSuppression: installCursorSdkAbortErrorSuppression(),
+			resolvedApiKey: () => this.resolvedApiKey,
+		});
+		await runFinalizer.applyTerminalEvent({ kind: "error", prepared: undefined, error });
+		await runFinalizer.cleanup(undefined, undefined, undefined);
+	}
+}

package/src/cursor-provider-turn-sdk-normalizer.ts

@@ -0,0 +1,88 @@
+import { mergeCursorToolCalls } from "./cursor-tool-transcript.js";
+import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
+import {
+	mergeShellOutputDeltasIntoCursorToolCall,
+	type CursorShellOutputTracker,
+} from "./cursor-provider-turn-shell-output.js";
+import type { CursorToolCompletionLedger } from "./cursor-provider-turn-tool-ledger.js";
+
+export type CursorToolCompletionSource = "delta" | "step";
+
+export type ToolCompletionResolution =
+	| { action: "ignore-bridge"; identity?: string }
+	| {
+			action: "handle";
+			toolCall: unknown;
+			identity?: string;
+			source?: "started" | "fallback";
+			matchedStartedCallId?: string;
+	  };
+
+export interface ResolveCursorToolCompletionOptions {
+	source: CursorToolCompletionSource;
+	callId: unknown;
+	toolCall: unknown;
+	startedToolCall?: unknown;
+	liveRun?: CursorLiveRun;
+	ledger: CursorToolCompletionLedger;
+	shellOutput: CursorShellOutputTracker;
+	onClearStartedCallId?: (callId: string) => void;
+}
+
+export function resolveCursorToolCompletion(options: ResolveCursorToolCompletionOptions): ToolCompletionResolution {
+	const bridgeStartedCallId = options.ledger.takeBridgeStartedCallId(
+		typeof options.callId === "string" ? options.callId : "",
+	);
+	if (bridgeStartedCallId) {
+		options.ledger.recordCompletedIdentity(`cursor-tool:${bridgeStartedCallId}`);
+		return { action: "ignore-bridge", identity: `cursor-tool:${bridgeStartedCallId}` };
+	}
+
+	let matchedStartedCallId: string | undefined;
+	let resolvedToolCall: unknown;
+	let identity: string | undefined;
+	let source: "started" | "fallback" | undefined;
+
+	if (options.source === "delta") {
+		const callId = options.callId;
+		identity = typeof callId === "string" ? `cursor-tool:${callId}` : undefined;
+		resolvedToolCall = mergeCursorToolCalls(options.startedToolCall, options.toolCall);
+		if (typeof callId === "string") {
+			options.onClearStartedCallId?.(callId);
+			options.ledger.clearStartedToolCall(callId);
+		}
+		resolvedToolCall = mergeShellOutputDeltasIntoCursorToolCall(
+			resolvedToolCall,
+			typeof callId === "string" ? options.shellOutput.takeDeltasForCall(callId) : undefined,
+		);
+		source = identity ? "started" : "fallback";
+	} else {
+		matchedStartedCallId = options.ledger.removeStartedToolCallForStep(options.toolCall, options.callId);
+		if (matchedStartedCallId) {
+			options.onClearStartedCallId?.(matchedStartedCallId);
+		}
+		resolvedToolCall = mergeShellOutputDeltasIntoCursorToolCall(
+			options.toolCall,
+			matchedStartedCallId ? options.shellOutput.takeDeltasForCall(matchedStartedCallId) : undefined,
+		);
+		const identityId = typeof options.callId === "string" ? options.callId : matchedStartedCallId;
+		identity = identityId ? `cursor-tool:${identityId}` : undefined;
+	}
+
+	if (options.liveRun?.bridgeRun?.isBridgeMcpToolCall(resolvedToolCall)) {
+		const bridgeIdentity =
+			options.source === "step" && matchedStartedCallId ? `cursor-tool:${matchedStartedCallId}` : identity;
+		if (bridgeIdentity) options.ledger.recordCompletedIdentity(bridgeIdentity);
+		return { action: "ignore-bridge", identity: bridgeIdentity };
+	}
+
+	if (options.source === "delta") {
+		return { action: "handle", toolCall: resolvedToolCall, identity, source };
+	}
+	return {
+		action: "handle",
+		toolCall: resolvedToolCall,
+		identity,
+		matchedStartedCallId,
+	};
+}

package/src/cursor-provider-turn-send.ts

@@ -0,0 +1,103 @@
+import type { SendOptions } from "@cursor/sdk";
+import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { getCursorAgentMessageOffset } from "./cursor-provider-turn-message-offset.js";
+import type { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
+import type {
+	CursorProviderTurnRunnerParams,
+	CursorProviderTurnPrepareResult,
+	CursorProviderTurnSendResult,
+} from "./cursor-provider-turn-types.js";
+import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+
+export interface SendCursorProviderTurnParams {
+	params: CursorProviderTurnRunnerParams;
+	prepared: CursorProviderTurnPrepareResult;
+	sdkEventDebug: CursorSdkEventDebugSink | undefined;
+	sdkAbortErrorSuppression: ReturnType<typeof installCursorSdkAbortErrorSuppression>;
+	throwIfAborted: () => void;
+}
+
+export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnParams): Promise<CursorProviderTurnSendResult> {
+	const { params, prepared, sdkEventDebug, sdkAbortErrorSuppression, throwIfAborted } = sendParams;
+	const { options } = params;
+	const { agent, cwd, payload, meta, runtime } = prepared;
+	const { turnCoordinator, liveRun } = runtime;
+
+	let completed = false;
+	let sdkRun: Awaited<ReturnType<typeof agent.send>> | null = null;
+	const abortListener = () => {
+		sdkAbortErrorSuppression.suppressAbortErrors();
+		liveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
+		if (sdkRun) {
+			sdkRun.cancel().catch(() => {});
+		}
+	};
+	const abortSignal = options?.signal;
+	const abortRegistration = abortSignal
+		? { signal: abortSignal, listener: abortListener }
+		: undefined;
+
+	try {
+		abortRegistration?.signal.addEventListener("abort", abortListener, { once: true });
+		throwIfAborted();
+		const cursorAgentMessageOffset = await getCursorAgentMessageOffset(agent.agentId, cwd, sdkEventDebug);
+		throwIfAborted();
+		sdkEventDebug?.recordSendMeta({
+			mode: meta.sendPlan.mode,
+			reason: meta.sendPlan.reason,
+			resetAgent: meta.sendPlan.resetAgent,
+			bootstrap: meta.bootstrap,
+			promptText: meta.prompt.text,
+			imageCount: meta.prompt.images.length,
+			useNativeToolReplay: meta.useNativeToolReplay,
+			bridgeEnabled: meta.bridgeEnabled,
+			nativeReplayId: meta.nativeReplayId,
+			promptInputTokens: meta.promptInputTokens,
+			agentMode: meta.agentMode,
+		});
+		sdkEventDebug?.recordSendPayload(payload);
+		sdkEventDebug?.recordProviderEvent("agent_send_start", payload);
+		const sendOptions: SendOptions = {
+			mode: meta.agentMode,
+			onDelta: (args) => {
+				sdkEventDebug?.recordOnDelta(args.update);
+				turnCoordinator.handleDelta(args.update);
+			},
+			onStep: (args) => {
+				sdkEventDebug?.recordOnStep(args.step);
+				turnCoordinator.handleStep(args.step);
+			},
+		};
+		const run = await agent.send(payload, sendOptions);
+		sdkRun = run;
+		sdkEventDebug?.recordRunMeta({
+			runId: run.id,
+			agentId: run.agentId,
+			status: run.status,
+		});
+		sdkEventDebug?.attachRunStream(run);
+		sdkEventDebug?.recordProviderEvent("agent_send_returned", {
+			runId: run.id,
+			agentId: run.agentId,
+			status: run.status,
+		});
+		if (liveRun) cursorLiveRuns.attachSdkRun(liveRun, run);
+		if (options?.signal?.aborted) {
+			sdkAbortErrorSuppression.suppressAbortErrors();
+			liveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
+			await run.cancel().catch(() => {});
+			throw new CursorLiveRunAbortError();
+		}
+
+		completed = true;
+		return {
+			send: { run, cursorAgentMessageOffset },
+			abortRegistration,
+		};
+	} finally {
+		if (!completed && abortRegistration) {
+			abortRegistration.signal.removeEventListener("abort", abortRegistration.listener);
+		}
+	}
+}

package/src/cursor-provider-turn-shell-output.ts

@@ -0,0 +1,107 @@
+import type { InteractionUpdate } from "@cursor/sdk";
+import { asRecord, getField, hasUsableText } from "./cursor-record-utils.js";
+import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
+
+export interface CursorShellOutputDelta {
+	stream: "stdout" | "stderr";
+	data: string;
+}
+
+export interface CursorShellOutputDeltas {
+	stdout: string[];
+	stderr: string[];
+}
+
+export function isCursorShellToolCall(toolCall: unknown): boolean {
+	return classifyCursorToolVisibility(toolCall).normalizedKey === "shell";
+}
+
+export function getCursorShellOutputDelta(update: InteractionUpdate): CursorShellOutputDelta | undefined {
+	if (update.type !== "shell-output-delta") return undefined;
+	const event = getField(update, "event");
+	const eventCase = getField(event, "case");
+	if (eventCase !== "stdout" && eventCase !== "stderr") return undefined;
+	const value = getField(event, "value");
+	const data = getField(value, "data");
+	if (typeof data !== "string" || data.length === 0) return undefined;
+	return { stream: eventCase, data };
+}
+
+export function mergeShellOutputDeltasIntoCursorToolCall(
+	toolCall: unknown,
+	deltas: CursorShellOutputDeltas | undefined,
+): unknown {
+	if (!deltas) return toolCall;
+	const stdout = deltas.stdout.join("");
+	const stderr = deltas.stderr.join("");
+	if (!hasUsableText(stdout) && !hasUsableText(stderr)) return toolCall;
+
+	const toolRecord = asRecord(toolCall);
+	const result = getField(toolRecord, "result");
+	const resultRecord = asRecord(result);
+	if (!toolRecord || !resultRecord || resultRecord.status !== "success") return toolCall;
+
+	const value = getField(resultRecord, "value");
+	const valueRecord = asRecord(value);
+	const completedStdout = getField(valueRecord, "stdout");
+	const completedStderr = getField(valueRecord, "stderr");
+	if (hasUsableText(typeof completedStdout === "string" ? completedStdout : undefined)) return toolCall;
+	if (hasUsableText(typeof completedStderr === "string" ? completedStderr : undefined)) return toolCall;
+
+	return {
+		...toolRecord,
+		result: {
+			...resultRecord,
+			value: {
+				...(valueRecord ?? {}),
+				stdout,
+				stderr,
+			},
+		},
+	};
+}
+
+export class CursorShellOutputTracker {
+	private readonly activeShellCallIds = new Set<string>();
+	private readonly ambiguousShellOutputCallIds = new Set<string>();
+	private readonly shellOutputDeltasByCallId = new Map<string, CursorShellOutputDeltas>();
+
+	onShellToolStarted(callId: string): void {
+		this.activeShellCallIds.add(callId);
+	}
+
+	onShellToolCleared(callId: string): void {
+		this.activeShellCallIds.delete(callId);
+		this.ambiguousShellOutputCallIds.delete(callId);
+	}
+
+	appendShellOutputDelta(delta: CursorShellOutputDelta): void {
+		if (this.activeShellCallIds.size !== 1) {
+			for (const activeCallId of this.activeShellCallIds) {
+				this.ambiguousShellOutputCallIds.add(activeCallId);
+				this.shellOutputDeltasByCallId.delete(activeCallId);
+			}
+			return;
+		}
+		const [callId] = this.activeShellCallIds;
+		if (!callId || this.ambiguousShellOutputCallIds.has(callId)) return;
+		let deltas = this.shellOutputDeltasByCallId.get(callId);
+		if (!deltas) {
+			deltas = { stdout: [], stderr: [] };
+			this.shellOutputDeltasByCallId.set(callId, deltas);
+		}
+		deltas[delta.stream].push(delta.data);
+	}
+
+	takeDeltasForCall(callId: string): CursorShellOutputDeltas | undefined {
+		const deltas = this.shellOutputDeltasByCallId.get(callId);
+		this.shellOutputDeltasByCallId.delete(callId);
+		return deltas;
+	}
+
+	clear(): void {
+		this.activeShellCallIds.clear();
+		this.ambiguousShellOutputCallIds.clear();
+		this.shellOutputDeltasByCallId.clear();
+	}
+}