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

package/dist/builtin/cursor/src/transport-native-client.ts

@@ -0,0 +1,161 @@
+import { parseJsonObject } from "./config.js";
+import {
+	formatCursorH2NativeLoadFailure,
+	loadCursorH2NativeBinding,
+	type CursorH2NativeBinding,
+	type CursorH2NativeStream,
+} from "./native-loader.js";
+import { CursorTransportError, toTransportError } from "./transport-errors.js";
+import { nextNativeOperationId, raceWithAbort, withTimeout } from "./transport-timeouts.js";
+import type {
+	CursorHttp2Client,
+	CursorHttp2StreamHandle,
+	CursorHttp2UnaryResponse,
+	CursorWriteOptions,
+} from "./transport-types.js";
+
+export function createDefaultCursorHttp2Client(): CursorHttp2Client {
+	return new LazyNativeHttp2CursorClient();
+}
+
+class LazyNativeHttp2CursorClient implements CursorHttp2Client {
+	#client: NativeHttp2CursorClient | undefined;
+
+	private get client(): NativeHttp2CursorClient {
+		if (this.#client) return this.#client;
+		const native = loadCursorH2NativeBinding();
+		if (!native.ok) throw new CursorTransportError("NetworkError", formatCursorH2NativeLoadFailure(native));
+		this.#client = new NativeHttp2CursorClient(native.binding);
+		return this.#client;
+	}
+
+	async requestUnary(request: { readonly baseUrl: string; readonly path: string; readonly headers: Record<string, string>; readonly body: Uint8Array; readonly signal?: AbortSignal; readonly timeoutMs?: number }): Promise<CursorHttp2UnaryResponse> {
+		return this.client.requestUnary(request);
+	}
+
+	async openStream(request: { readonly baseUrl: string; readonly path: string; readonly headers: Record<string, string>; readonly signal?: AbortSignal; readonly initialBody?: Uint8Array; readonly timeoutMs?: number }): Promise<CursorHttp2StreamHandle> {
+		return this.client.openStream(request);
+	}
+
+	async dispose(): Promise<void> {
+		await this.#client?.dispose();
+	}
+}
+
+class NativeHttp2CursorClient implements CursorHttp2Client {
+	constructor(readonly binding: CursorH2NativeBinding) {}
+
+	async requestUnary(request: { readonly baseUrl: string; readonly path: string; readonly headers: Record<string, string>; readonly body: Uint8Array; readonly signal?: AbortSignal; readonly timeoutMs?: number }): Promise<CursorHttp2UnaryResponse> {
+		if (request.signal?.aborted) throw new CursorTransportError("Aborted", "Cursor native HTTP/2 request aborted before start.");
+		const operationId = nextNativeOperationId();
+		try {
+			const response = await raceWithAbort(
+				this.binding.cursorH2RequestUnary(JSON.stringify({ baseUrl: request.baseUrl, path: request.path, headers: request.headers, operationId, timeoutMs: request.timeoutMs }), Buffer.from(request.body)),
+				request.signal,
+				"Cursor native HTTP/2 request aborted.",
+				undefined,
+				() => this.binding.cursorH2CancelOperation(operationId),
+			);
+			return {
+				statusCode: nativeStatusCode(response.statusCode ?? response.status_code),
+				headers: parseNativeHeaders(response.headersJson ?? response.headers_json),
+				body: new Uint8Array(response.body),
+			};
+		} catch (error) {
+			throw toTransportError(error);
+		}
+	}
+
+	async openStream(request: { readonly baseUrl: string; readonly path: string; readonly headers: Record<string, string>; readonly signal?: AbortSignal; readonly initialBody?: Uint8Array; readonly timeoutMs?: number }): Promise<CursorHttp2StreamHandle> {
+		if (request.signal?.aborted) throw new CursorTransportError("Aborted", "Cursor native HTTP/2 stream aborted before start.");
+		const operationId = nextNativeOperationId();
+		try {
+			const stream = await raceWithAbort(
+				this.binding.cursorH2OpenStream(
+					JSON.stringify({ baseUrl: request.baseUrl, path: request.path, headers: request.headers, operationId, timeoutMs: request.timeoutMs }),
+					request.initialBody ? Buffer.from(request.initialBody) : null,
+				),
+				request.signal,
+				"Cursor native HTTP/2 stream aborted while opening.",
+				(lateStream) => lateStream.cancel().catch(() => undefined),
+				() => this.binding.cursorH2CancelOperation(operationId),
+			);
+			return new NativeCursorStreamHandle(stream);
+		} catch (error) {
+			throw toTransportError(error);
+		}
+	}
+
+	async dispose(): Promise<void> {
+		// Native streams own their HTTP/2 sessions and dispose when closed/cancelled.
+	}
+}
+
+export function createNativeCursorHttp2ClientForTest(binding: CursorH2NativeBinding): CursorHttp2Client {
+	return new NativeHttp2CursorClient(binding);
+}
+
+class NativeCursorStreamHandle implements CursorHttp2StreamHandle {
+	readonly frames: AsyncIterable<Uint8Array>;
+	#closed = false;
+
+	constructor(readonly stream: CursorH2NativeStream) {
+		this.frames = this.createFrames();
+	}
+
+	async write(data: Uint8Array, options: CursorWriteOptions = {}): Promise<void> {
+		if (this.#closed) throw new CursorTransportError("ProtocolError", "Cannot write to a closed Cursor native stream.");
+		if (options.signal?.aborted) throw new CursorTransportError("Aborted", "Cursor native stream write aborted before start.");
+		try {
+			await raceWithAbort(
+				withTimeout(
+					this.stream.write(Buffer.from(data), options.timeoutMs ?? null),
+					options.timeoutMs,
+					"Cursor native stream write timed out.",
+				),
+				options.signal,
+				"Cursor native stream write aborted.",
+				undefined,
+				() => this.cancel().catch(() => undefined),
+			);
+		} catch (error) {
+			await this.cancel().catch(() => undefined);
+			throw error;
+		}
+	}
+
+	async close(): Promise<void> {
+		if (this.#closed) return;
+		this.#closed = true;
+		await this.stream.finishInput();
+	}
+
+	async cancel(): Promise<void> {
+		if (this.#closed) return;
+		this.#closed = true;
+		await this.stream.cancel();
+	}
+
+	private async *createFrames(): AsyncIterable<Uint8Array> {
+		while (true) {
+			const frame = await this.stream.nextFrame();
+			if (!frame) break;
+			yield new Uint8Array(frame);
+		}
+	}
+}
+
+function nativeStatusCode(value: number | undefined): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function parseNativeHeaders(headersJson: string | undefined): Record<string, string> {
+	if (!headersJson) return {};
+	const parsed = parseJsonObject(headersJson);
+	if (!parsed) return {};
+	const headers: Record<string, string> = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		if (typeof value === "string") headers[key] = value;
+	}
+	return headers;
+}

package/dist/builtin/cursor/src/transport-run-stream.ts

@@ -0,0 +1,188 @@
+import type {
+	CursorControlMessage,
+	CursorHttp2StreamHandle,
+	CursorProtocolCodec,
+	CursorProtocolMessage,
+	CursorRunStream,
+	CursorServerMessage,
+	CursorToolResultMessage,
+	CursorWriteOptions,
+} from "./transport-types.js";
+import { CursorTransportError, throwIfCursorEndStreamError, toError } from "./transport-errors.js";
+import { CursorConnectFrameDecoder, encodeCursorConnectFrame } from "./transport-frame.js";
+
+const DEFAULT_CANCEL_WRITE_TIMEOUT_MS = 1_000;
+
+function isCursorControlMessage(message: CursorProtocolMessage): message is CursorControlMessage {
+	return message.type === "kvGetBlob" || message.type === "kvSetBlob" || message.type === "conversationCheckpoint" || message.type === "requestContext";
+}
+
+export class Http2CursorRunStream implements CursorRunStream {
+	readonly messages: AsyncIterable<CursorServerMessage>;
+	#closed = false;
+	#cancelled = false;
+	readonly #heartbeatTimer?: ReturnType<typeof setInterval>;
+	readonly #messageQueue: CursorServerMessage[] = [];
+	readonly #messageReaders: Array<{
+		readonly resolve: (value: IteratorResult<CursorServerMessage>) => void;
+		readonly reject: (error: unknown) => void;
+	}> = [];
+	#messageQueueFinished = false;
+	#messageQueueError: Error | undefined;
+
+	constructor(
+		readonly id: string,
+		readonly handle: CursorHttp2StreamHandle,
+		readonly codec: CursorProtocolCodec,
+		readonly secrets: readonly string[],
+		heartbeatIntervalMs: number,
+		readonly onCancel: () => void,
+		readonly onClose: () => void,
+	) {
+		this.messages = this.createMessages();
+		void this.pumpMessages();
+		if (heartbeatIntervalMs > 0) {
+			this.#heartbeatTimer = setInterval(() => {
+				this.handle.write(encodeCursorConnectFrame(this.codec.encodeHeartbeatRequest())).catch(() => {
+					this.cancel().catch(() => undefined);
+				});
+			}, heartbeatIntervalMs);
+			this.#heartbeatTimer.unref?.();
+		}
+	}
+
+	async writeToolResult(result: CursorToolResultMessage, options?: CursorWriteOptions): Promise<void> {
+		if (this.#closed) throw new CursorTransportError("ProtocolError", "Cannot write Cursor tool result to a closed stream.");
+		try {
+			await this.handle.write(encodeCursorConnectFrame(this.codec.encodeToolResult(result)), options);
+		} catch (error) {
+			await this.cancel().catch(() => undefined);
+			throw error;
+		}
+	}
+
+	async cancel(): Promise<void> {
+		if (this.#cancelled) return;
+		this.#cancelled = true;
+		this.clearHeartbeat();
+		let cancelError: Error | undefined;
+		try {
+			await this.handle.write(encodeCursorConnectFrame(this.codec.encodeCancelRequest()), { timeoutMs: DEFAULT_CANCEL_WRITE_TIMEOUT_MS }).catch(() => undefined);
+		} finally {
+			this.onCancel();
+			try {
+				await this.handle.cancel();
+			} catch (error) {
+				cancelError = toError(error);
+			} finally {
+				this.finishMessageQueue();
+				if (!this.#closed) {
+					this.#closed = true;
+					this.codec.disposeRun?.(this.id);
+					this.onClose();
+				}
+			}
+		}
+		if (cancelError) throw cancelError;
+	}
+
+	async close(): Promise<void> {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.clearHeartbeat();
+		try {
+			await this.handle.close();
+		} finally {
+			this.finishMessageQueue();
+			this.codec.disposeRun?.(this.id);
+			this.onClose();
+		}
+	}
+
+	private clearHeartbeat(): void {
+		if (this.#heartbeatTimer) clearInterval(this.#heartbeatTimer);
+	}
+
+	private async pumpMessages(): Promise<void> {
+		const decoder = new CursorConnectFrameDecoder();
+		try {
+			for await (const raw of this.handle.frames) {
+				if (this.#closed || this.#cancelled) break;
+				for (const frame of decoder.push(raw)) {
+					if (this.#closed || this.#cancelled) break;
+					if (frame.endStream) {
+						try {
+							throwIfCursorEndStreamError(frame.data, this.secrets);
+						} catch (error) {
+							this.codec.discardRun?.(this.id);
+							throw error;
+						}
+						continue;
+					}
+					for (const message of this.codec.decodeRunFrame(frame)) {
+						if (this.#closed || this.#cancelled) break;
+						const response = this.codec.encodeServerResponse?.(message, this.id);
+						if (response) {
+							await this.handle.write(encodeCursorConnectFrame(response));
+							continue;
+						}
+						if (!isCursorControlMessage(message)) this.enqueueMessage(message);
+					}
+				}
+			}
+			decoder.finish();
+			this.finishMessageQueue();
+		} catch (error) {
+			this.finishMessageQueue(toError(error));
+		}
+	}
+
+	private enqueueMessage(message: CursorServerMessage): void {
+		if (this.#messageQueueFinished) return;
+		this.#messageQueue.push(message);
+		this.flushMessageReaders();
+	}
+
+	private finishMessageQueue(error?: Error): void {
+		if (this.#messageQueueFinished) return;
+		this.#messageQueueFinished = true;
+		this.#messageQueueError = error;
+		this.flushMessageReaders();
+	}
+
+	private flushMessageReaders(): void {
+		while (this.#messageReaders.length > 0) {
+			const reader = this.#messageReaders.shift();
+			if (!reader) return;
+			const message = this.#messageQueue.shift();
+			if (message !== undefined) {
+				reader.resolve({ value: message, done: false });
+			} else if (this.#messageQueueError) {
+				reader.reject(this.#messageQueueError);
+			} else if (this.#messageQueueFinished) {
+				reader.resolve({ value: undefined, done: true });
+			} else {
+				this.#messageReaders.unshift(reader);
+				return;
+			}
+		}
+	}
+
+	private nextMessage(): Promise<IteratorResult<CursorServerMessage>> {
+		const message = this.#messageQueue.shift();
+		if (message !== undefined) return Promise.resolve({ value: message, done: false });
+		if (this.#messageQueueError) return Promise.reject(this.#messageQueueError);
+		if (this.#messageQueueFinished) return Promise.resolve({ value: undefined, done: true });
+		return new Promise((resolve, reject) => {
+			this.#messageReaders.push({ resolve, reject });
+		});
+	}
+
+	private async *createMessages(): AsyncIterable<CursorServerMessage> {
+		while (true) {
+			const next = await this.nextMessage();
+			if (next.done) return;
+			yield next.value;
+		}
+	}
+}

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

@@ -0,0 +1,87 @@
+import { CursorTransportError } from "./transport-errors.js";
+
+export async function runWithDeadline<T>(operation: (signal: AbortSignal | undefined) => Promise<T>, timeoutMs: number, parentSignal: AbortSignal | undefined, timeoutMessage: string): Promise<T> {
+	if (parentSignal?.aborted) throw new CursorTransportError("Aborted", "Cursor request aborted.");
+	const controller = new AbortController();
+	let rejectAbort: ((error: CursorTransportError) => void) | undefined;
+	const onAbort = (): void => {
+		controller.abort();
+		rejectAbort?.(new CursorTransportError("Aborted", "Cursor request aborted."));
+	};
+	parentSignal?.addEventListener("abort", onAbort, { once: true });
+	let timeout: ReturnType<typeof setTimeout> | undefined;
+	const abortPromise = parentSignal ? new Promise<never>((_resolve, reject) => {
+		rejectAbort = reject;
+	}) : undefined;
+	const timeoutPromise = timeoutMs > 0 ? new Promise<never>((_resolve, reject) => {
+		timeout = setTimeout(() => {
+			controller.abort();
+			reject(new CursorTransportError("NetworkError", timeoutMessage));
+		}, timeoutMs);
+		timeout.unref?.();
+	}) : undefined;
+	try {
+		return await Promise.race([operation(controller.signal), ...(abortPromise ? [abortPromise] : []), ...(timeoutPromise ? [timeoutPromise] : [])]);
+	} finally {
+		if (timeout) clearTimeout(timeout);
+		parentSignal?.removeEventListener("abort", onAbort);
+		rejectAbort = undefined;
+	}
+}
+
+let nativeOperationCounter = 0;
+
+export function nextNativeOperationId(): string {
+	nativeOperationCounter = (nativeOperationCounter + 1) % Number.MAX_SAFE_INTEGER;
+	return `cursor-h2-${Date.now().toString(36)}-${nativeOperationCounter.toString(36)}`;
+}
+
+export async function withTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, timeoutMessage: string): Promise<T> {
+	if (!timeoutMs || timeoutMs <= 0) return promise;
+	let timeout: ReturnType<typeof setTimeout> | undefined;
+	const timeoutPromise = new Promise<never>((_resolve, reject) => {
+		timeout = setTimeout(() => reject(new CursorTransportError("NetworkError", timeoutMessage)), timeoutMs);
+		timeout.unref?.();
+	});
+	try {
+		return await Promise.race([promise, timeoutPromise]);
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
+
+export async function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined, message: string, onLateResolve?: (value: T) => void | Promise<void>, onAbort?: () => void | Promise<void>): Promise<T> {
+	if (signal?.aborted) throw new CursorTransportError("Aborted", message);
+	if (!signal) return promise;
+	let settled = false;
+	let rejectAbort: ((error: CursorTransportError) => void) | undefined;
+	const abortPromise = new Promise<never>((_resolve, reject) => {
+		rejectAbort = reject;
+	});
+	const abort = (): void => {
+		void onAbort?.();
+		rejectAbort?.(new CursorTransportError("Aborted", message));
+	};
+	signal.addEventListener("abort", abort, { once: true });
+	try {
+		return await Promise.race([
+			promise.then(async (value) => {
+				settled = true;
+				if (signal.aborted) {
+					if (onLateResolve) await onLateResolve(value);
+					throw new CursorTransportError("Aborted", message);
+				}
+				return value;
+			}),
+			abortPromise,
+		]);
+	} finally {
+		signal.removeEventListener("abort", abort);
+		rejectAbort = undefined;
+		if (!settled) {
+			promise.then((value) => {
+				if (signal.aborted) void onLateResolve?.(value);
+			}).catch(() => undefined);
+		}
+	}
+}

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

@@ -0,0 +1,140 @@
+import type { Context, Model, Api, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { CursorUsableModel } from "./model-mapper.js";
+
+export interface CursorTransportLifecycleSnapshot {
+	readonly openStreams: number;
+	readonly cancelledStreams: number;
+	readonly closedStreams: number;
+}
+
+export interface CursorRunRequest {
+	readonly accessToken: string;
+	readonly requestId: string;
+	readonly conversationId?: string;
+	readonly model: Model<Api>;
+	readonly resolvedModelId: string;
+	readonly thinkingLevel?: ThinkingLevel;
+	readonly context: Context;
+	readonly signal?: AbortSignal;
+	readonly openTimeoutMs?: number;
+}
+
+export type CursorDoneReason = "stop" | "length" | "toolUse";
+
+export interface CursorToolCallMessage {
+	readonly type: "toolCall";
+	readonly id: string;
+	readonly name: string;
+	readonly argumentsJson: string;
+	readonly execId?: string;
+	readonly execNumericId?: number;
+}
+
+export type CursorServerMessage =
+	| { readonly type: "textDelta"; readonly text: string }
+	| { readonly type: "thinkingDelta"; readonly text: string }
+	| CursorToolCallMessage
+	| { readonly type: "usage"; readonly kind?: "checkpoint"; readonly inputTokens?: number; readonly outputTokens?: number; readonly cacheReadTokens?: number; readonly cacheWriteTokens?: number; readonly usedTokens?: number }
+	| { readonly type: "usage"; readonly kind: "outputDelta"; readonly outputTokens: number }
+	| { readonly type: "nonMcpExec"; readonly fieldNumber: number; readonly execId?: string; readonly execNumericId?: number }
+	| { readonly type: "done"; readonly reason: CursorDoneReason };
+
+export type CursorControlMessage =
+	| { readonly type: "kvGetBlob"; readonly id: number; readonly blobId: Uint8Array }
+	| { readonly type: "kvSetBlob"; readonly id: number; readonly blobId: Uint8Array; readonly blobData: Uint8Array }
+	| { readonly type: "conversationCheckpoint"; readonly checkpoint: Uint8Array }
+	| { readonly type: "requestContext"; readonly execNumericId?: number; readonly execId?: string };
+
+export type CursorProtocolMessage = CursorServerMessage | CursorControlMessage;
+
+export interface CursorToolResultMessage {
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly text: string;
+	readonly isError: boolean;
+	readonly execId?: string;
+	readonly execNumericId?: number;
+}
+
+export interface CursorWriteOptions {
+	readonly signal?: AbortSignal;
+	readonly timeoutMs?: number;
+}
+
+export interface CursorRunStream {
+	readonly id: string;
+	readonly messages: AsyncIterable<CursorServerMessage>;
+	writeToolResult(result: CursorToolResultMessage, options?: CursorWriteOptions): Promise<void>;
+	cancel(): Promise<void>;
+	close(): Promise<void>;
+}
+
+export interface CursorAgentTransport {
+	getUsableModels(accessToken: string, requestId: string, signal?: AbortSignal): Promise<readonly CursorUsableModel[]>;
+	run(request: CursorRunRequest): Promise<CursorRunStream>;
+	dispose(): Promise<void>;
+	discardConversation?(conversationId: string): void;
+	getLifecycleSnapshot(): CursorTransportLifecycleSnapshot;
+}
+
+export interface CursorConnectFrame {
+	readonly flags: number;
+	readonly data: Uint8Array;
+	readonly endStream: boolean;
+}
+
+export interface CursorHttp2UnaryResponse {
+	readonly statusCode?: number;
+	readonly body: Uint8Array;
+	readonly headers: Record<string, string>;
+}
+
+export interface CursorHttp2StreamHandle {
+	readonly frames: AsyncIterable<Uint8Array>;
+	write(data: Uint8Array, options?: CursorWriteOptions): Promise<void>;
+	close(): Promise<void>;
+	cancel(): Promise<void>;
+}
+
+export interface CursorHttp2Client {
+	requestUnary(request: {
+		readonly baseUrl: string;
+		readonly path: string;
+		readonly headers: Record<string, string>;
+		readonly body: Uint8Array;
+		readonly signal?: AbortSignal;
+		readonly timeoutMs?: number;
+	}): Promise<CursorHttp2UnaryResponse>;
+	openStream(request: {
+		readonly baseUrl: string;
+		readonly path: string;
+		readonly headers: Record<string, string>;
+		readonly signal?: AbortSignal;
+		readonly initialBody?: Uint8Array;
+		readonly timeoutMs?: number;
+	}): Promise<CursorHttp2StreamHandle>;
+	dispose(): Promise<void>;
+}
+
+export interface CursorProtocolCodec {
+	encodeGetUsableModelsRequest(): Uint8Array;
+	decodeGetUsableModelsResponse(data: Uint8Array): readonly CursorUsableModel[];
+	encodeRunRequest(request: CursorRunRequest): Uint8Array;
+	decodeRunFrame(frame: CursorConnectFrame): readonly CursorProtocolMessage[];
+	encodeToolResult(result: CursorToolResultMessage): Uint8Array;
+	encodeCancelRequest(): Uint8Array;
+	encodeHeartbeatRequest(): Uint8Array;
+	encodeServerResponse?(message: CursorProtocolMessage, requestId: string): Uint8Array | undefined;
+	disposeRun?(requestId: string): void;
+	discardRun?(requestId: string): void;
+	discardConversation?(conversationId: string): void;
+}
+
+export interface Http2CursorAgentTransportOptions {
+	readonly baseUrl?: string;
+	readonly client?: CursorHttp2Client;
+	readonly codec?: CursorProtocolCodec;
+	readonly requestTimeoutMs?: number;
+	readonly streamOpenTimeoutMs?: number;
+	readonly heartbeatIntervalMs?: number;
+}