@bastani/atomic 0.8.31-alpha.4 → 0.9.0-alpha.1

package/dist/builtin/cursor/src/stream.ts

@@ -1,43 +1,24 @@
 import { createHash, randomUUID as nodeRandomUUID } from "node:crypto";
-import {
-	type Api,
-	type AssistantMessage,
-	type AssistantMessageEventStream,
-	calculateCost,
-	type Context,
-	createAssistantMessageEventStream,
-	type Model,
-	type SimpleStreamOptions,
-} from "@earendil-works/pi-ai";
+import { type Api, type AssistantMessage, type AssistantMessageEventStream, calculateCost, type Context, createAssistantMessageEventStream, type Model, type SimpleStreamOptions } from "@earendil-works/pi-ai";
 import { parseJsonObject, sanitizeDiagnosticText } from "./config.js";
 import { CursorConversationStateStore, type CursorConversationSnapshot } from "./conversation-state.js";
 import { resolveCursorModelVariant } from "./model-mapper.js";
 import type { CursorAgentTransport, CursorRunStream, CursorServerMessage, CursorToolCallMessage, CursorToolResultMessage } from "./transport.js";
 
 export interface CursorStreamAdapterOptions {
-	readonly transport: CursorAgentTransport;
-	readonly conversationState?: CursorConversationStateStore;
-	readonly uuid?: () => string;
-	readonly pausedTurnIdleTimeoutMs?: number;
-	readonly streamReadTimeoutMs?: number;
+	readonly transport: CursorAgentTransport; readonly conversationState?: CursorConversationStateStore; readonly uuid?: () => string;
+	readonly pausedTurnIdleTimeoutMs?: number; readonly streamReadTimeoutMs?: number;
 }
-
 interface CursorStreamRuntime {
-	readonly transport: CursorAgentTransport;
-	readonly conversationState: CursorConversationStateStore;
-	readonly uuid: () => string;
-	readonly pausedTurnIdleTimeoutMs: number;
-	readonly streamReadTimeoutMs: number;
+	readonly transport: CursorAgentTransport; readonly conversationState: CursorConversationStateStore; readonly uuid: () => string;
+	readonly pausedTurnIdleTimeoutMs: number; readonly streamReadTimeoutMs: number;
 }
 
 const DEFAULT_PAUSED_TURN_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
 const DEFAULT_STREAM_READ_TIMEOUT_MS = 10 * 60 * 1000;
 const TOOL_CALL_BATCH_IDLE_TIMEOUT_MS = 100;
 
-type IteratorReadResult =
-	| { readonly kind: "message"; readonly result: IteratorResult<CursorServerMessage> }
-	| { readonly kind: "aborted" };
-
+type IteratorReadResult = { readonly kind: "message"; readonly result: IteratorResult<CursorServerMessage> } | { readonly kind: "aborted" };
 type CursorReadRaceResult =
 	| { readonly kind: "message"; readonly result: IteratorResult<CursorServerMessage>; readonly read: CursorMessageReadHandle }
 	| { readonly kind: "error"; readonly error: Error; readonly read: CursorMessageReadHandle }
@@ -80,7 +61,6 @@ export class CursorStreamAdapter {
 	getLifecycleSnapshot(): CursorConversationSnapshot {
 		return this.#runtime.conversationState.snapshot(this.#runtime.transport.getLifecycleSnapshot());
 	}
-
 	#messageReaderFor(runStream: CursorRunStream): CursorMessageReader {
 		const existing = this.#messageReaders.get(runStream);
 		if (existing) return existing;
@@ -88,7 +68,6 @@ export class CursorStreamAdapter {
 		this.#messageReaders.set(runStream, reader);
 		return reader;
 	}
-
 	async #runStream(
 		stream: AssistantMessageEventStream,
 		model: Model<Api>,
@@ -97,7 +76,6 @@ export class CursorStreamAdapter {
 	): Promise<void> {
 		const output = createOutputMessage(model);
 		stream.push({ type: "start", partial: output });
-
 		let runStream: CursorRunStream | undefined;
 		let activeConversationKey: string | undefined;
 		let textIndex: number | undefined;
@@ -106,7 +84,6 @@ export class CursorStreamAdapter {
 		let sawToolCall = false;
 		const pendingToolCalls: CursorToolCallMessage[] = [];
 		const effectiveTimeoutMs = options?.timeoutMs ?? this.#runtime.streamReadTimeoutMs;
-
 		try {
 			if (!options?.apiKey) {
 				throw new Error("Cursor OAuth credentials are required. Run /login and select Cursor.");
@@ -117,7 +94,6 @@ export class CursorStreamAdapter {
 			if (options.signal?.aborted) {
 				throw new CursorStreamAbortError();
 			}
-
 			const requestId = this.#runtime.uuid();
 			const conversationIdentity = deriveCursorConversationIdentity(context, options.sessionId);
 			activeConversationKey = conversationIdentity.activeKey;
@@ -188,7 +164,6 @@ export class CursorStreamAdapter {
 					break;
 				}
 			}
-
 			if (!terminalEventSent) {
 				closeOpenContent(stream, output, textIndex, thinkingIndex);
 				if (pendingToolCalls.length > 0 && runStream) {
@@ -224,7 +199,6 @@ export class CursorStreamAdapter {
 				try {
 					await this.#runtime.conversationState.cancelTurn(activeConversationKey);
 				} catch {
-					// Terminal events must not be suppressed by best-effort cleanup failures.
 				} finally {
 					runStream = undefined;
 				}
@@ -241,53 +215,41 @@ export class CursorStreamAdapter {
 		}
 	}
 }
-
 class CursorStreamAbortError extends Error {
 	constructor() {
 		super("Cursor stream aborted.");
 		this.name = "CursorStreamAbortError";
 	}
 }
-
 class CursorStreamTimeoutError extends Error {
 	constructor() {
 		super("Cursor stream timed out while waiting for provider output.");
 		this.name = "CursorStreamTimeoutError";
 	}
 }
-
 interface CursorPendingMessageRead {
 	readonly promise: Promise<IteratorResult<CursorServerMessage>>;
 	consumed: boolean;
 }
-
 interface CursorMessageReadHandle {
 	readonly promise: Promise<IteratorResult<CursorServerMessage>>;
 	consumeResult(result: IteratorResult<CursorServerMessage>): void;
 	consumeError(error: Error): void;
 }
-
 type CursorBufferedMessageRead =
 	| { readonly kind: "result"; readonly result: IteratorResult<CursorServerMessage> }
 	| { readonly kind: "error"; readonly error: Error };
-
-// A Cursor tool turn can pause by timing out while an iterator.next() is still
-// waiting for the first post-tool provider message. Reuse and buffer that exact
-// read across resume calls so the message is not consumed by an abandoned race.
 class CursorMessageReader {
 	readonly #iterator: AsyncIterator<CursorServerMessage>;
 	#pending: CursorPendingMessageRead | undefined;
 	#buffered: CursorBufferedMessageRead | undefined;
-
 	constructor(messages: AsyncIterable<CursorServerMessage>) {
 		this.#iterator = messages[Symbol.asyncIterator]();
 	}
-
 	unread(result: IteratorResult<CursorServerMessage>): void {
 		if (this.#buffered) return;
 		this.#buffered = { kind: "result", result };
 	}
-
 	peek(): CursorMessageReadHandle {
 		if (this.#buffered) return this.peekBuffered(this.#buffered);
 		const pending = this.#pending ?? this.startRead();
@@ -305,7 +267,6 @@ class CursorMessageReader {
 			},
 		};
 	}
-
 	private peekBuffered(buffered: CursorBufferedMessageRead): CursorMessageReadHandle {
 		return {
 			promise: buffered.kind === "result" ? Promise.resolve(buffered.result) : Promise.reject(buffered.error),
@@ -317,7 +278,6 @@ class CursorMessageReader {
 			},
 		};
 	}
-
 	private startRead(): CursorPendingMessageRead {
 		const pending: CursorPendingMessageRead = {
 			promise: this.#iterator.next().catch((error: Error) => {
@@ -342,11 +302,9 @@ class CursorMessageReader {
 		return pending;
 	}
 }
-
 function normalizeCursorReadError(error: Error): Error {
 	return error instanceof Error ? error : new Error(String(error));
 }
-
 function createOutputMessage(model: Model<Api>): AssistantMessage {
 	return {
 		role: "assistant",
@@ -366,7 +324,6 @@ function createOutputMessage(model: Model<Api>): AssistantMessage {
 		timestamp: Date.now(),
 	};
 }
-
 function getTrailingToolResults(context: Context): CursorToolResultMessage[] {
 	const results: CursorToolResultMessage[] = [];
 	for (let index = context.messages.length - 1; index >= 0; index--) {
@@ -376,11 +333,9 @@ function getTrailingToolResults(context: Context): CursorToolResultMessage[] {
 	}
 	return results;
 }
-
 function textFromToolResult(message: Extract<Context["messages"][number], { readonly role: "toolResult" }>): string {
 	return message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n");
 }
-
 function textFromMessage(message: Context["messages"][number]): string {
 	if (message.role === "user") {
 		if (typeof message.content === "string") return message.content;
@@ -395,40 +350,31 @@ function textFromMessage(message: Context["messages"][number]): string {
 	}
 	return textFromToolResult(message);
 }
-
 interface CursorConversationIdentity {
 	readonly activeKey: string;
 	readonly wireConversationId: string;
 }
-
 function deriveCursorConversationIdentity(context: Context, sessionId: string | undefined): CursorConversationIdentity {
 	const bridgeKey = deriveCursorConversationKey("bridge", context, sessionId);
 	const conversationKey = deriveCursorConversationKey("conv", context, sessionId);
 	return { activeKey: bridgeKey, wireConversationId: deterministicCursorConversationId(conversationKey) };
 }
-
 function deriveCursorBridgeKeyFromSessionId(sessionId: string): string {
 	return hashCursorKey("bridge", sessionId);
 }
-
 function deriveCursorWireConversationIdFromSessionId(sessionId: string): string {
 	return deterministicCursorConversationId(hashCursorKey("conv", sessionId));
 }
-
 function deriveCursorConversationKey(prefix: "bridge" | "conv", context: Context, sessionId: string | undefined): string {
 	const trimmedSessionId = sessionId?.trim();
 	if (trimmedSessionId) return hashCursorKey(prefix, trimmedSessionId);
 	const firstUserMessage = context.messages.find((message) => message.role === "user");
-	// No-session runs lack a durable session id, so this fallback is best-effort
-	// and can collide for conversations with the same leading user text.
 	const firstUserText = firstUserMessage ? textFromMessage(firstUserMessage).slice(0, 200) : "";
 	return hashCursorKey(prefix, firstUserText);
 }
-
 function hashCursorKey(prefix: "bridge" | "conv", value: string): string {
 	return createHash("sha256").update(`${prefix}:${value}`).digest("hex").slice(0, 16);
 }
-
 function deterministicCursorConversationId(conversationKey: string): string {
 	const hex = createHash("sha256").update(`cursor-conv-id:${conversationKey}`).digest("hex").slice(0, 32);
 	const variantNibble = (0x8 | (Number.parseInt(hex[16] ?? "0", 16) & 0x3)).toString(16);
@@ -440,7 +386,6 @@ function deterministicCursorConversationId(conversationKey: string): string {
 		hex.slice(20, 32),
 	].join("-");
 }
-
 function hasImageInput(context: Context): boolean {
 	for (const message of context.messages) {
 		if (message.role === "user") {
@@ -451,7 +396,6 @@ function hasImageInput(context: Context): boolean {
 	}
 	return false;
 }
-
 function appendTextDelta(stream: AssistantMessageEventStream, output: AssistantMessage, existingIndex: number | undefined, delta: string): number {
 	const contentIndex = existingIndex ?? output.content.length;
 	if (existingIndex === undefined) {
@@ -465,7 +409,6 @@ function appendTextDelta(stream: AssistantMessageEventStream, output: AssistantM
 	stream.push({ type: "text_delta", contentIndex, delta, partial: output });
 	return contentIndex;
 }
-
 function appendThinkingDelta(stream: AssistantMessageEventStream, output: AssistantMessage, existingIndex: number | undefined, delta: string): number {
 	const contentIndex = existingIndex ?? output.content.length;
 	if (existingIndex === undefined) {
@@ -479,7 +422,6 @@ function appendThinkingDelta(stream: AssistantMessageEventStream, output: Assist
 	stream.push({ type: "thinking_delta", contentIndex, delta, partial: output });
 	return contentIndex;
 }
-
 function appendToolCall(stream: AssistantMessageEventStream, output: AssistantMessage, id: string, name: string, argumentsJson: string): void {
 	const contentIndex = output.content.length;
 	const parsedArguments = parseJsonObject(argumentsJson) ?? {};
@@ -493,7 +435,6 @@ function appendToolCall(stream: AssistantMessageEventStream, output: AssistantMe
 		partial: output,
 	});
 }
-
 function closeOpenContent(stream: AssistantMessageEventStream, output: AssistantMessage, textIndex: number | undefined, thinkingIndex: number | undefined): void {
 	if (textIndex !== undefined) {
 		const block = output.content[textIndex];
@@ -508,14 +449,11 @@ function closeOpenContent(stream: AssistantMessageEventStream, output: Assistant
 		}
 	}
 }
-
 function updateUsage(output: AssistantMessage, model: Model<Api>, message: Extract<CursorServerMessage, { readonly type: "usage" }>): void {
 	if (message.kind === "outputDelta") {
 		output.usage.output += message.outputTokens;
 	} else {
 		if (message.inputTokens !== undefined) output.usage.input = message.inputTokens;
-		// Cursor checkpoint `usedTokens` omits a dedicated input field on some
-		// frames, so estimate input from already-seen output/cache counters.
 		else if (message.usedTokens !== undefined) output.usage.input = Math.max(0, message.usedTokens - output.usage.output - output.usage.cacheRead - output.usage.cacheWrite);
 		if (message.outputTokens !== undefined) output.usage.output = message.outputTokens;
 		if (message.cacheReadTokens !== undefined) output.usage.cacheRead = message.cacheReadTokens;
@@ -524,7 +462,6 @@ function updateUsage(output: AssistantMessage, model: Model<Api>, message: Extra
 	output.usage.totalTokens = output.usage.input + output.usage.output + output.usage.cacheRead + output.usage.cacheWrite;
 	output.usage.cost = calculateCost(model, output.usage);
 }
-
 async function readNextCursorMessage(reader: CursorMessageReader, signal: AbortSignal | undefined, timeoutMs: number): Promise<IteratorReadResult> {
 	if (signal?.aborted) return { kind: "aborted" };
 	let abortListener: (() => void) | undefined;
@@ -558,7 +495,6 @@ async function readNextCursorMessage(reader: CursorMessageReader, signal: AbortS
 		if (timeout) clearTimeout(timeout);
 	}
 }
-
 export function createCursorStreamAdapter(options: CursorStreamAdapterOptions): CursorStreamAdapter {
 	return new CursorStreamAdapter(options);
 }

package/dist/builtin/cursor/src/transport-errors.ts

@@ -0,0 +1,74 @@
+import {
+	CURSOR_CLIENT_VERSION,
+	readStringField,
+	sanitizeDiagnosticText,
+	type JsonObject,
+} from "./config.js";
+
+export type CursorTransportErrorCode = "Unauthorized" | "CursorApiRejected" | "Aborted" | "NetworkError" | "ProtocolError";
+
+export class CursorTransportError extends Error {
+	constructor(
+		readonly code: CursorTransportErrorCode,
+		message: string,
+	) {
+		super(message);
+		this.name = "CursorTransportError";
+	}
+}
+const textDecoder = new TextDecoder();
+
+export function sanitizeCursorTransportError(error: Error, secrets: readonly string[] = []): Error {
+	const message = sanitizeDiagnosticText(error.message, secrets);
+	return error instanceof CursorTransportError ? new CursorTransportError(error.code, message) : new CursorTransportError("ProtocolError", message);
+}
+
+export function throwIfCursorEndStreamError(data: Uint8Array, secrets: readonly string[]): void {
+	let parsed: JsonObject;
+	try {
+		const value = JSON.parse(textDecoder.decode(data)) as unknown;
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return;
+		parsed = value as JsonObject;
+	} catch {
+		throw new CursorTransportError("ProtocolError", "Failed to parse Cursor Connect end stream.");
+	}
+	const errorValue = parsed.error;
+	if (!errorValue) return;
+	if (typeof errorValue !== "object" || Array.isArray(errorValue)) {
+		throw new CursorTransportError("CursorApiRejected", `Cursor stream ended with unknown: ${sanitizeDiagnosticText(String(errorValue), secrets)}.`);
+	}
+	const error = errorValue as JsonObject;
+	const code = readStringField(error, "code") ?? "unknown";
+	const message = readStringField(error, "message") ?? "Unknown error";
+	throw new CursorTransportError(classifyConnectErrorCode(code), `Cursor stream ended with ${code}: ${sanitizeDiagnosticText(message, secrets)}.`);
+}
+
+function classifyConnectErrorCode(code: string): CursorTransportErrorCode {
+	if (code === "unauthenticated") return "Unauthorized";
+	if (code === "canceled") return "Aborted";
+	if (code === "resource_exhausted" || code === "unavailable") return "NetworkError";
+	return "CursorApiRejected";
+}
+
+export function assertSuccessfulStatus(statusCode: number | undefined, body: Uint8Array, secrets: readonly string[]): void {
+	if (statusCode === undefined || (statusCode >= 200 && statusCode < 300)) return;
+	const detail = sanitizeDiagnosticText(textDecoder.decode(body), secrets);
+	const versionHint = cursorClientVersionHint(statusCode);
+	const message = `Cursor API rejected request with HTTP ${statusCode}${detail ? `: ${detail}` : ""}${versionHint}`;
+	if (statusCode === 401 || statusCode === 403) throw new CursorTransportError("Unauthorized", message);
+	throw new CursorTransportError("CursorApiRejected", message);
+}
+
+function cursorClientVersionHint(statusCode: number): string {
+	if (statusCode !== 403 && statusCode !== 426) return "";
+	return ` Cursor may be rejecting the bundled Cursor CLI-compatible client version (${CURSOR_CLIENT_VERSION}); refresh CURSOR_CLIENT_VERSION from current Cursor CLI traffic if authentication still succeeds in Cursor itself.`;
+}
+
+export function toError(error: unknown): Error {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+export function toTransportError(error: unknown): CursorTransportError {
+	if (error instanceof CursorTransportError) return error;
+	return new CursorTransportError("NetworkError", toError(error).message);
+}

package/dist/builtin/cursor/src/transport-frame.ts

@@ -0,0 +1,56 @@
+import type { CursorConnectFrame } from "./transport-types.js";
+
+const CONNECT_END_STREAM_FLAG = 0b10;
+export function encodeCursorConnectFrame(data: Uint8Array, flags = 0): Uint8Array {
+	const frame = new Uint8Array(5 + data.length);
+	frame[0] = flags;
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	view.setUint32(1, data.length, false);
+	frame.set(data, 5);
+	return frame;
+}
+
+export function decodeCursorConnectFrames(data: Uint8Array): readonly CursorConnectFrame[] {
+	const decoder = new CursorConnectFrameDecoder();
+	const frames = decoder.push(data);
+	decoder.finish();
+	return frames;
+}
+
+export class CursorConnectFrameDecoder {
+	#buffer: Uint8Array<ArrayBufferLike> = new Uint8Array();
+
+	push(data: Uint8Array): readonly CursorConnectFrame[] {
+		this.#buffer = concatBytes(this.#buffer, data);
+		const frames: CursorConnectFrame[] = [];
+		let offset = 0;
+		while (this.#buffer.length - offset >= 5) {
+			const flags = this.#buffer[offset] ?? 0;
+			const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset + offset, this.#buffer.byteLength - offset);
+			const length = view.getUint32(1, false);
+			const bodyStart = offset + 5;
+			const bodyEnd = bodyStart + length;
+			if (bodyEnd > this.#buffer.length) break;
+			frames.push({ flags, data: this.#buffer.slice(bodyStart, bodyEnd), endStream: (flags & CONNECT_END_STREAM_FLAG) !== 0 });
+			offset = bodyEnd;
+		}
+		this.#buffer = this.#buffer.slice(offset);
+		return frames;
+	}
+
+	finish(): void {
+		if (this.#buffer.length === 0) return;
+		if (this.#buffer.length < 5) throw new Error("Incomplete Cursor Connect frame header.");
+		throw new Error("Incomplete Cursor Connect frame body.");
+	}
+}
+
+function concatBytes(...parts: readonly Uint8Array[]): Uint8Array {
+	const output = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		output.set(part, offset);
+		offset += part.length;
+	}
+	return output;
+}

package/dist/builtin/cursor/src/transport-http2.ts

@@ -0,0 +1,122 @@
+import type { CursorUsableModel } from "./model-mapper.js";
+import {
+	buildCursorRpcHeaders,
+	CURSOR_API_BASE_URL,
+	CURSOR_GET_USABLE_MODELS_PATH,
+	CURSOR_RUN_PATH,
+} from "./config.js";
+import { CursorProtobufProtocolCodec } from "./proto/protobuf-codec.js";
+import { assertSuccessfulStatus, CursorTransportError, sanitizeCursorTransportError, toError } from "./transport-errors.js";
+import { encodeCursorConnectFrame } from "./transport-frame.js";
+import { createDefaultCursorHttp2Client } from "./transport-native-client.js";
+import { Http2CursorRunStream } from "./transport-run-stream.js";
+import { runWithDeadline } from "./transport-timeouts.js";
+import type {
+	CursorAgentTransport,
+	CursorHttp2Client,
+	CursorProtocolCodec,
+	CursorRunRequest,
+	CursorRunStream,
+	CursorTransportLifecycleSnapshot,
+	Http2CursorAgentTransportOptions,
+} from "./transport-types.js";
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+
+export class Http2CursorAgentTransport implements CursorAgentTransport {
+	readonly #baseUrl: string;
+	readonly #client: CursorHttp2Client;
+	readonly #codec: CursorProtocolCodec;
+	readonly #requestTimeoutMs: number;
+	readonly #streamOpenTimeoutMs: number;
+	readonly #heartbeatIntervalMs: number;
+	#openStreams = 0;
+	#cancelledStreams = 0;
+	#closedStreams = 0;
+
+	constructor(baseUrlOrOptions: string | Http2CursorAgentTransportOptions = CURSOR_API_BASE_URL) {
+		const options = typeof baseUrlOrOptions === "string" ? { baseUrl: baseUrlOrOptions } : baseUrlOrOptions;
+		this.#baseUrl = options.baseUrl ?? CURSOR_API_BASE_URL;
+		this.#client = options.client ?? createDefaultCursorHttp2Client();
+		this.#codec = options.codec ?? new CursorProtobufProtocolCodec();
+		this.#requestTimeoutMs = options.requestTimeoutMs ?? 60_000;
+		this.#streamOpenTimeoutMs = options.streamOpenTimeoutMs ?? 60_000;
+		this.#heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+	}
+
+	async getUsableModels(accessToken: string, requestId: string, signal?: AbortSignal): Promise<readonly CursorUsableModel[]> {
+		if (signal?.aborted) {
+			throw new CursorTransportError("Aborted", "Cursor model discovery was aborted before the request started.");
+		}
+		const headers = buildCursorRpcHeaders(accessToken, requestId, "application/proto");
+		try {
+			const response = await runWithDeadline(
+				(parentSignal) => this.#client.requestUnary({
+					baseUrl: this.#baseUrl,
+					path: CURSOR_GET_USABLE_MODELS_PATH,
+					headers,
+					body: this.#codec.encodeGetUsableModelsRequest(),
+					signal: parentSignal,
+					timeoutMs: this.#requestTimeoutMs,
+				}),
+				this.#requestTimeoutMs,
+				signal,
+				"Cursor model discovery timed out.",
+			);
+			assertSuccessfulStatus(response.statusCode, response.body, [accessToken]);
+			// GetUsableModels uses application/proto unary bodies, not Connect
+			// stream envelopes; pass the raw protobuf response to the codec.
+			return this.#codec.decodeGetUsableModelsResponse(response.body);
+		} catch (error) {
+			throw sanitizeCursorTransportError(toError(error), [accessToken]);
+		}
+	}
+
+	async run(request: CursorRunRequest): Promise<CursorRunStream> {
+		if (request.signal?.aborted) {
+			throw new CursorTransportError("Aborted", "Cursor stream was aborted before the request started.");
+		}
+		const headers = {
+			...buildCursorRpcHeaders(request.accessToken, request.requestId, "application/connect+proto"),
+			"connect-protocol-version": "1",
+		};
+		try {
+			const initialBody = encodeCursorConnectFrame(this.#codec.encodeRunRequest(request));
+			const handle = await runWithDeadline(
+				(parentSignal) => this.#client.openStream({ baseUrl: this.#baseUrl, path: CURSOR_RUN_PATH, headers, signal: parentSignal, initialBody, timeoutMs: request.openTimeoutMs ?? this.#streamOpenTimeoutMs }),
+				request.openTimeoutMs ?? this.#streamOpenTimeoutMs,
+				request.signal,
+				"Cursor stream open timed out.",
+			);
+			this.#openStreams += 1;
+			return new Http2CursorRunStream(
+				request.requestId,
+				handle,
+				this.#codec,
+				[request.accessToken],
+				this.#heartbeatIntervalMs,
+				() => {
+					this.#cancelledStreams += 1;
+				},
+				() => {
+					this.#closedStreams += 1;
+					this.#openStreams = Math.max(0, this.#openStreams - 1);
+				},
+			);
+		} catch (error) {
+			throw sanitizeCursorTransportError(toError(error), [request.accessToken]);
+		}
+	}
+
+	async dispose(): Promise<void> {
+		await this.#client.dispose();
+	}
+
+	discardConversation(conversationId: string): void {
+		this.#codec.discardConversation?.(conversationId);
+	}
+
+	getLifecycleSnapshot(): CursorTransportLifecycleSnapshot {
+		return { openStreams: this.#openStreams, cancelledStreams: this.#cancelledStreams, closedStreams: this.#closedStreams };
+	}
+}