@bastani/atomic 0.8.28-alpha.4 → 0.8.29-alpha.2

package/dist/builtin/cursor/src/model-mapper.ts

@@ -0,0 +1,270 @@
+import type { ThinkingLevel, ThinkingLevelMap } from "@earendil-works/pi-ai";
+import { CURSOR_API, CURSOR_API_BASE_URL } from "./config.js";
+import rawFallbackModels from "./cursor-models-raw.json" with { type: "json" };
+
+export type CursorCatalogSource = "live" | "estimated";
+export type CursorEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max" | "default";
+
+export interface CursorUsableModel {
+	readonly id: string;
+	readonly name?: string;
+	readonly displayName?: string;
+	readonly contextWindow?: number;
+	readonly maxTokens?: number;
+	readonly supportsReasoning?: boolean;
+	readonly supportsThinking?: boolean;
+}
+
+export interface CursorModelCatalog {
+	readonly source: CursorCatalogSource;
+	readonly fetchedAt: number;
+	readonly note?: string;
+	readonly models: readonly CursorUsableModel[];
+}
+
+export interface CursorProviderModelDefinition {
+	readonly id: string;
+	readonly name: string;
+	readonly api?: string;
+	readonly baseUrl?: string;
+	readonly reasoning: boolean;
+	readonly thinkingLevelMap?: ThinkingLevelMap;
+	readonly input: ["text"];
+	readonly cost: { readonly input: number; readonly output: number; readonly cacheRead: number; readonly cacheWrite: number };
+	readonly contextWindow: number;
+	readonly maxTokens: number;
+}
+
+interface CursorVariant {
+	readonly id: string;
+	readonly baseId: string;
+	readonly displayName: string;
+	readonly effort?: CursorEffort;
+	readonly fast: boolean;
+	readonly thinking: boolean;
+	readonly contextWindow?: number;
+	readonly maxTokens?: number;
+	readonly supportsReasoning?: boolean;
+	readonly supportsThinking?: boolean;
+}
+
+interface CursorVariantGroup {
+	readonly baseId: string;
+	readonly primaryId: string;
+	readonly displayName: string;
+	readonly variants: readonly CursorVariant[];
+}
+
+const CURSOR_FALLBACK_RAW_MODELS = rawFallbackModels satisfies readonly CursorUsableModel[];
+const PARSEABLE_EFFORTS: readonly Exclude<CursorEffort, "default">[] = ["none", "low", "medium", "high", "xhigh", "max"];
+const EFFORT_ORDER: readonly CursorEffort[] = ["none", "low", "default", "medium", "high", "xhigh", "max"];
+const THINKING_LEVEL_EFFORT_PREFERENCES: Record<ThinkingLevel, readonly CursorEffort[]> = {
+	minimal: ["none", "low", "default"],
+	low: ["low", "none", "default"],
+	medium: ["medium", "default", "low"],
+	high: ["high", "medium", "default"],
+	xhigh: ["max", "xhigh", "high"],
+};
+
+const ESTIMATED_CONTEXT_WINDOW = 200_000;
+const ESTIMATED_MAX_TOKENS = 64_000;
+
+export function createEstimatedCursorCatalog(now = Date.now()): CursorModelCatalog {
+	return {
+		source: "estimated",
+		fetchedAt: now,
+		note: "static fallback; Cursor private API metadata and limits are estimated; token costs are reported as zero for subscription usage",
+		models: CURSOR_FALLBACK_RAW_MODELS.map((model) => ({
+			...model,
+			supportsReasoning: supportsReasoningModelId(model.id),
+			...(model.id.endsWith("-thinking") || model.id.includes("-thinking-") ? { supportsThinking: true } : {}),
+		})),
+	};
+}
+
+export function mapCursorCatalogToProviderModels(catalog: CursorModelCatalog): CursorProviderModelDefinition[] {
+	return groupCursorModels(catalog.models).map((group) => {
+		const effortVariants = collectEffortVariants(group.variants, group.primaryId);
+		const supportsEffort = group.variants.some((variant) => Boolean(variant.effort)) || effortVariants.size >= 2;
+		const supportsReasoning = supportsReasoningModelId(group.primaryId);
+		const name = catalog.source === "estimated" ? `${group.displayName} (estimated)` : group.displayName;
+		return {
+			id: group.primaryId,
+			name,
+			api: CURSOR_API,
+			baseUrl: CURSOR_API_BASE_URL,
+			reasoning: supportsReasoning,
+			thinkingLevelMap: supportsEffort ? buildThinkingLevelMap(effortVariants, group.primaryId) : undefined,
+			input: ["text"],
+			cost: subscriptionCost(),
+			contextWindow: chooseLargestNumber(group.variants.map((variant) => variant.contextWindow)) ?? ESTIMATED_CONTEXT_WINDOW,
+			maxTokens: chooseLargestNumber(group.variants.map((variant) => variant.maxTokens)) ?? ESTIMATED_MAX_TOKENS,
+		};
+	});
+}
+
+export function resolveCursorModelVariant(
+	baseModelId: string,
+	thinkingLevelMap: ThinkingLevelMap | undefined,
+	thinkingLevel: ThinkingLevel | undefined,
+): string {
+	if (!thinkingLevel || !thinkingLevelMap) return baseModelId;
+	const mapped = thinkingLevelMap[thinkingLevel];
+	if (!mapped || mapped === "default") return baseModelId;
+	if (isCursorEffort(mapped)) return replaceEffortBeforeCursorSuffix(baseModelId, mapped);
+	return mapped;
+}
+
+export function insertEffortBeforeCursorSuffix(modelId: string, effort: CursorEffort): string {
+	if (effort === "default") return modelId;
+	let base = modelId;
+	let fast = false;
+	let thinking = false;
+	if (base.endsWith("-fast")) {
+		fast = true;
+		base = base.slice(0, -"-fast".length);
+	}
+	if (base.endsWith("-thinking")) {
+		thinking = true;
+		base = base.slice(0, -"-thinking".length);
+	}
+	return `${base}-${effort}${thinking ? "-thinking" : ""}${fast ? "-fast" : ""}`;
+}
+
+function replaceEffortBeforeCursorSuffix(modelId: string, effort: CursorEffort): string {
+	if (effort === "default") return modelId;
+	const variant = parseCursorVariant({ id: modelId });
+	return `${variant.baseId}-${effort}${variant.thinking ? "-thinking" : ""}${variant.fast ? "-fast" : ""}`;
+}
+
+export function parseCursorVariant(model: CursorUsableModel): CursorVariant {
+	let base = model.id;
+	let fast = false;
+	let thinking = false;
+	if (base.endsWith("-fast")) {
+		fast = true;
+		base = base.slice(0, -"-fast".length);
+	}
+	if (base.endsWith("-thinking")) {
+		thinking = true;
+		base = base.slice(0, -"-thinking".length);
+	}
+	const effort = PARSEABLE_EFFORTS.find((candidate) => base.endsWith(`-${candidate}`));
+	if (effort) {
+		base = base.slice(0, -effort.length - 1);
+	}
+	return {
+		id: model.id,
+		baseId: base,
+		displayName: model.displayName ?? model.name ?? titleCaseModelId(base),
+		effort,
+		fast,
+		thinking,
+		contextWindow: model.contextWindow,
+		maxTokens: model.maxTokens,
+		supportsReasoning: model.supportsReasoning,
+		supportsThinking: model.supportsThinking,
+	};
+}
+
+function groupCursorModels(models: readonly CursorUsableModel[]): CursorVariantGroup[] {
+	const groups = new Map<string, CursorVariant[]>();
+	for (const model of models) {
+		const variant = parseCursorVariant(model);
+		const key = cursorVariantGroupKey(variant);
+		const existing = groups.get(key) ?? [];
+		existing.push(variant);
+		groups.set(key, existing);
+	}
+	return [...groups.values()]
+		.map((variants) => {
+			const baseId = variants[0]?.baseId ?? "cursor";
+			const primaryId = choosePrimaryId(variants, baseId);
+			return {
+				baseId,
+				primaryId,
+				displayName: chooseDisplayName(variants, baseId, primaryId),
+				variants,
+			};
+		})
+		.sort((left, right) => left.primaryId.localeCompare(right.primaryId));
+}
+
+function cursorVariantGroupKey(variant: CursorVariant): string {
+	return `${variant.baseId}|fast=${variant.fast ? "1" : "0"}|thinking=${variant.thinking ? "1" : "0"}`;
+}
+
+function collectEffortVariants(variants: readonly CursorVariant[], primaryId: string): ReadonlyMap<CursorEffort, string> {
+	const byEffort = new Map<CursorEffort, string>();
+	for (const variant of variants) {
+		const effort = variant.effort ?? (variant.id === primaryId || variant.supportsReasoning || variant.supportsThinking || variant.thinking ? "default" : undefined);
+		if (effort && !byEffort.has(effort)) byEffort.set(effort, variant.id);
+	}
+	return byEffort;
+}
+
+function buildThinkingLevelMap(effortVariants: ReadonlyMap<CursorEffort, string>, primaryId: string): ThinkingLevelMap {
+	return {
+		minimal: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.minimal, primaryId),
+		low: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.low, primaryId),
+		medium: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.medium, primaryId),
+		high: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.high, primaryId),
+		xhigh: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.xhigh, primaryId),
+	};
+}
+
+function chooseEffortVariant(effortVariants: ReadonlyMap<CursorEffort, string>, preferences: readonly CursorEffort[], _primaryId: string): string | null {
+	for (const effort of preferences) {
+		const variantId = effortVariants.get(effort);
+		if (variantId) return variantId;
+	}
+	for (const effort of EFFORT_ORDER) {
+		const variantId = effortVariants.get(effort);
+		if (variantId) return variantId;
+	}
+	return null;
+}
+
+function isCursorEffort(value: string): value is CursorEffort {
+	return value === "default" || (PARSEABLE_EFFORTS as readonly string[]).includes(value);
+}
+
+function chooseLargestNumber(values: readonly (number | undefined)[]): number | undefined {
+	const finiteValues = values.filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+	return finiteValues.length > 0 ? Math.max(...finiteValues) : undefined;
+}
+
+function choosePrimaryId(variants: readonly CursorVariant[], baseId: string): string {
+	if (variants.some((variant) => variant.effort)) {
+		const representative = variants[0];
+		return `${baseId}${representative?.thinking ? "-thinking" : ""}${representative?.fast ? "-fast" : ""}`;
+	}
+	return variants.find((variant) => variant.id === baseId)?.id ?? variants[0]?.id ?? baseId;
+}
+
+function chooseDisplayName(variants: readonly CursorVariant[], baseId: string, primaryId: string): string {
+	return variants.find((variant) => variant.id === primaryId)?.displayName
+		?? variants.find((variant) => variant.effort === "medium")?.displayName
+		?? variants.find((variant) => !variant.effort)?.displayName
+		?? variants[0]?.displayName
+		?? titleCaseModelId(baseId);
+}
+
+function supportsReasoningModelId(id: string): boolean {
+	const variant = parseCursorVariant({ id });
+	if (variant.effort || variant.thinking) return true;
+	if (variant.baseId === "default") return true;
+	return /^(claude|composer|gemini|gpt|grok|kimi)(-|$)/iu.test(variant.baseId);
+}
+
+function titleCaseModelId(id: string): string {
+	return id
+		.split(/[-_/]+/u)
+		.filter((part) => part.length > 0)
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join(" ");
+}
+
+function subscriptionCost(): { readonly input: number; readonly output: number; readonly cacheRead: number; readonly cacheWrite: number } {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}

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

@@ -0,0 +1,54 @@
+import { createEstimatedCursorCatalog, type CursorModelCatalog } from "./model-mapper.js";
+import { CursorTransportError, type CursorAgentTransport, type CursorTransportErrorCode } from "./transport.js";
+
+export type CursorDiscoveryErrorCode = CursorTransportErrorCode | "NoUsableModels";
+
+export class CursorModelDiscoveryError extends Error {
+	constructor(
+		readonly code: CursorDiscoveryErrorCode,
+		message: string,
+	) {
+		super(message);
+		this.name = "CursorModelDiscoveryError";
+	}
+}
+
+export interface CursorModelDiscoveryServiceOptions {
+	readonly transport: CursorAgentTransport;
+	readonly now?: () => number;
+}
+
+export class CursorModelDiscoveryService {
+	readonly #transport: CursorAgentTransport;
+	readonly #now: () => number;
+
+	constructor(options: CursorModelDiscoveryServiceOptions) {
+		this.#transport = options.transport;
+		this.#now = options.now ?? Date.now;
+	}
+
+	async discover(accessToken: string, requestId: string, signal?: AbortSignal): Promise<CursorModelCatalog> {
+		try {
+			const models = await this.#transport.getUsableModels(accessToken, requestId, signal);
+			if (models.length === 0) {
+				throw new CursorModelDiscoveryError("NoUsableModels", "Cursor account has no usable models.");
+			}
+			return { source: "live", fetchedAt: this.#now(), models };
+		} catch (error) {
+			if (error instanceof CursorModelDiscoveryError) {
+				throw error;
+			}
+			if (error instanceof CursorTransportError) {
+				throw new CursorModelDiscoveryError(error.code, error.message);
+			}
+			if (signal?.aborted) {
+				throw new CursorModelDiscoveryError("Aborted", "Cursor model discovery was aborted.");
+			}
+			throw new CursorModelDiscoveryError("ProtocolError", error instanceof Error ? error.message : "Cursor model discovery failed.");
+		}
+	}
+
+	fallbackCatalog(): CursorModelCatalog {
+		return createEstimatedCursorCatalog(this.#now());
+	}
+}

package/dist/builtin/cursor/src/native-loader.ts

@@ -0,0 +1,71 @@
+import { createRequire } from "node:module";
+
+export const CURSOR_H2_NATIVE_PACKAGE = "@bastani/atomic-natives";
+
+export interface CursorH2NativeUnaryResponse {
+	readonly statusCode?: number;
+	readonly status_code?: number;
+	readonly headersJson?: string;
+	readonly headers_json?: string;
+	readonly body: Uint8Array;
+}
+
+export interface CursorH2NativeStream {
+	write(data: Uint8Array, timeoutMs?: number | null): Promise<void>;
+	finishInput(): Promise<void>;
+	nextFrame(): Promise<Uint8Array | null>;
+	cancel(): Promise<void>;
+}
+
+export interface CursorH2NativeBinding {
+	cursorH2RequestUnary(configJson: string, body: Uint8Array): Promise<CursorH2NativeUnaryResponse>;
+	cursorH2OpenStream(configJson: string, initialBody?: Uint8Array | null): Promise<CursorH2NativeStream>;
+	cursorH2CancelOperation(operationId: string): Promise<void> | void;
+}
+
+export type CursorH2NativeLoadResult =
+	| { readonly ok: true; readonly binding: CursorH2NativeBinding; readonly packageName: string }
+	| { readonly ok: false; readonly error: Error; readonly packageName: string };
+
+let cachedLoadResult: CursorH2NativeLoadResult | undefined;
+
+export function resetCursorH2NativeBindingCache(): void {
+	cachedLoadResult = undefined;
+}
+
+export function loadCursorH2NativeBinding(): CursorH2NativeLoadResult {
+	if (cachedLoadResult) return cachedLoadResult;
+	const requireNative = createRequire(import.meta.url);
+	try {
+		const loaded = requireNative(CURSOR_H2_NATIVE_PACKAGE) as Partial<CursorH2NativeBinding>;
+		if (typeof loaded.cursorH2RequestUnary !== "function" || typeof loaded.cursorH2OpenStream !== "function" || typeof loaded.cursorH2CancelOperation !== "function") {
+			cachedLoadResult = {
+				ok: false,
+				packageName: CURSOR_H2_NATIVE_PACKAGE,
+				error: new Error(`Cursor HTTP/2 native package ${CURSOR_H2_NATIVE_PACKAGE} is missing required N-API exports.`),
+			};
+			return cachedLoadResult;
+		}
+		cachedLoadResult = { ok: true, binding: loaded as CursorH2NativeBinding, packageName: CURSOR_H2_NATIVE_PACKAGE };
+		return cachedLoadResult;
+	} catch (error) {
+		cachedLoadResult = {
+			ok: false,
+			packageName: CURSOR_H2_NATIVE_PACKAGE,
+			error: new Error(`Cursor HTTP/2 native package ${CURSOR_H2_NATIVE_PACKAGE} is unavailable for ${process.platform}-${process.arch}: ${error instanceof Error ? error.message : String(error)}`),
+		};
+		return cachedLoadResult;
+	}
+}
+
+export function formatCursorH2NativeLoadFailure(result: Extract<CursorH2NativeLoadResult, { ok: false }>): string {
+	return [
+		result.error.message,
+		`Install or rebuild ${result.packageName} so its NAPI-RS optional dependency for ${process.platform}-${process.arch} is available.`,
+		"If you installed Atomic from npm/Bun, reinstall @bastani/atomic. If you are developing locally, run `bun --cwd packages/natives run build`."
+	].join("\n");
+}
+
+export function cursorH2NativeLoadSummary(result: CursorH2NativeLoadResult): string {
+	return result.ok ? `loaded ${result.packageName}` : result.error.message;
+}

package/dist/builtin/cursor/src/proto/README.md

@@ -0,0 +1,34 @@
+# Cursor protocol notes
+
+This directory contains the isolated Cursor protobuf protocol codec and vendored generated protobuf descriptors. The codec intentionally follows the MIT-licensed [`ndraiman/pi-cursor-provider`](https://github.com/ndraiman/pi-cursor-provider) implementation at commit `82fc4e73f9ae820d87b34ac36713b18989910a36`: request and control messages are built with the generated `agent_pb.ts` descriptors and `@bufbuild/protobuf`, not with hand-maintained field concatenation.
+
+Known private endpoints:
+
+- Browser login: `https://cursor.com/loginDeepControl?challenge=<pkce>&uuid=<uuid>&mode=login&redirectTarget=cli`
+- Login poll: `https://api2.cursor.sh/auth/poll?uuid=<uuid>&verifier=<verifier>`
+- Refresh: `POST https://api2.cursor.sh/auth/exchange_user_api_key`
+- Model discovery: `POST https://api2.cursor.sh/agent.v1.AgentService/GetUsableModels`
+- Agent stream: `POST https://api2.cursor.sh/agent.v1.AgentService/Run`
+
+`src/transport.ts` exposes an injectable HTTP/2 client and protocol codec seam plus buffered Connect frame helpers. Production defaults use `CursorProtobufProtocolCodec` and the Rust/N-API HTTP/2 native binding in `@bastani/atomic-natives` (`crates/atomic-natives`) because Bun's `node:http2` behavior is not reliable against Cursor's private API.
+
+Protocol behavior intentionally copied from the reference provider:
+
+- `AgentClientMessage.run_request = 1`, `exec_client_message = 2`, `kv_client_message = 3`, `conversation_action = 4`, `client_heartbeat = 7`.
+- Run requests use generated `AgentRunRequest`, `ConversationStateStructure`, `ConversationAction`, `UserMessage`, and `ModelDetails` messages.
+- `UserMessage.message_id`, `UserMessage.correlation_id`, and reconstructed historical turn request ids are UUIDs generated the same way as the reference provider.
+- Conversation ids are deterministic UUIDs derived from the hashed conversation key (`conv:<session-or-first-user-text>`), matching the reference provider rather than sending raw Atomic session ids to Cursor.
+- Static fallback models are the reference `cursor-models-raw.json`; live model discovery is opportunistic and only replaces the registered catalog when Cursor returns usable models.
+- Tool definitions are returned in response to `ExecServerMessage.request_context_args = 10`; `McpArgs` messages become Atomic tool calls and active tool results are sent back as generated `ExecClientMessage.mcp_result` frames.
+- Checkpoint and blob-store state is persisted per Cursor conversation id and discarded on Cursor end-stream errors such as `not_found`.
+- `InteractionUpdate.turn_ended` is non-terminal; the stream closes on the Connect stream ending.
+
+Manual smoke-test procedure after Cursor releases:
+
+1. Sign in to the current Cursor CLI/app and capture a successful `api2.cursor.sh` model discovery or agent `Run` request.
+2. Update `CURSOR_CLIENT_VERSION` in `src/config.ts` from the captured `x-cursor-client-version` header if it changed.
+3. In Atomic, run `/login`, select **Cursor**, complete browser auth, then confirm `/model` lists `cursor/<model-id>` entries from live discovery.
+4. Select a Cursor model and run one chat turn plus one tool-using turn; verify the process exits cleanly for a one-shot/noninteractive run.
+5. Re-run the Cursor unit tests and update these notes for any changed protobuf paths.
+
+If Cursor changes the private protocol, update the vendored generated protobuf descriptors from the reference/source protocol before changing the codec behavior.