pi-cursor-sdk 0.0.0 → 0.1.0

package/package.json

@@ -1,10 +1,42 @@
 {
   "name": "pi-cursor-sdk",
-  "version": "0.0.0",
-  "description": "Reserved package name. Real release coming soon.",
-  "type": "module",
-  "main": "index.js",
-  "license": "MIT",
+  "version": "0.1.0",
+  "description": "pi provider extension backed by @cursor/sdk local agents",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
-  "keywords": ["pi-package", "pi", "pi-extension", "extension", "cursor", "sdk"]
+  "license": "MIT",
+  "keywords": ["pi-package", "pi", "pi-extension", "cursor", "cursor-sdk", "ai", "extension"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fitchmultz/pi-cursor-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fitchmultz/pi-cursor-sdk/issues"
+  },
+  "homepage": "https://github.com/fitchmultz/pi-cursor-sdk#readme",
+  "files": ["src", "README.md", "docs", "LICENSE", "CHANGELOG.md"],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@cursor/sdk": "^1.0.12"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.72.1",
+    "@mariozechner/pi-ai": "^0.72.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  }
 }

package/src/bundled-context-windows.ts

@@ -0,0 +1,27 @@
+// Generated from Cursor SDK checkpoint tokenDetails.maxTokens on 2026-05-04.
+// These are default/non-Max-mode SDK context windows for Cursor models that do not
+// expose a catalog `context` parameter. Do not replace them with Max Mode values
+// unless the Cursor SDK exposes an exact Max Mode model selection and the extension
+// uses that selection for matching pi model IDs.
+export const BUNDLED_CONTEXT_WINDOWS = {
+	"claude-haiku-4-5": 200000,
+	"claude-opus-4-5": 200000,
+	"composer-1.5": 200000,
+	"composer-2": 200000,
+	default: 200000,
+	"gemini-2.5-flash": 200000,
+	"gemini-3-flash": 200000,
+	"gemini-3.1-pro": 200000,
+	"gpt-5-mini": 272000,
+	"gpt-5.1": 272000,
+	"gpt-5.1-codex-max": 272000,
+	"gpt-5.1-codex-mini": 272000,
+	"gpt-5.2": 272000,
+	"gpt-5.2-codex": 272000,
+	"gpt-5.3-codex": 272000,
+	"gpt-5.3-codex-spark": 128000,
+	"gpt-5.4-mini": 272000,
+	"gpt-5.4-nano": 272000,
+	"grok-4-20": 200000,
+	"kimi-k2.5": 262000,
+} as const satisfies Record<string, number>;

package/src/context-window-cache.ts

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { BUNDLED_CONTEXT_WINDOWS } from "./bundled-context-windows.js";
+
+const CONTEXT_WINDOW_CACHE_FILE = "cursor-sdk-context-windows.json";
+
+interface ContextWindowCacheFile {
+	contextWindows?: Record<string, number>;
+}
+
+function getCachePath(): string {
+	return join(getAgentDir(), CONTEXT_WINDOW_CACHE_FILE);
+}
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function loadUserContextWindowOverrides(): Map<string, number> {
+	const path = getCachePath();
+	const overrides = new Map<string, number>();
+	if (!existsSync(path)) return overrides;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as ContextWindowCacheFile;
+		for (const [modelId, contextWindow] of Object.entries(parsed.contextWindows ?? {})) {
+			if (isPositiveInteger(contextWindow)) overrides.set(modelId, contextWindow);
+		}
+	} catch {
+		return overrides;
+	}
+	return overrides;
+}
+
+export function loadContextWindowCache(): Map<string, number> {
+	const cache = new Map<string, number>(Object.entries(BUNDLED_CONTEXT_WINDOWS));
+	for (const [modelId, contextWindow] of loadUserContextWindowOverrides()) {
+		cache.set(modelId, contextWindow);
+	}
+	return cache;
+}
+
+export function getCachedContextWindow(modelId: string): number | undefined {
+	return loadContextWindowCache().get(modelId);
+}
+
+export function getCheckpointContextWindow(checkpoint: unknown): number | undefined {
+	if (checkpoint === null || typeof checkpoint !== "object") return undefined;
+	const tokenDetails = (checkpoint as Record<PropertyKey, unknown>).tokenDetails;
+	if (tokenDetails === null || typeof tokenDetails !== "object") return undefined;
+	const maxTokens = (tokenDetails as Record<PropertyKey, unknown>).maxTokens;
+	if (!isPositiveInteger(maxTokens)) return undefined;
+	return maxTokens;
+}
+
+export function saveCachedContextWindow(modelId: string, contextWindow: number): void {
+	if (!isPositiveInteger(contextWindow)) return;
+	const overrides = loadUserContextWindowOverrides();
+	const bundledContextWindow = BUNDLED_CONTEXT_WINDOWS[modelId as keyof typeof BUNDLED_CONTEXT_WINDOWS];
+	if (bundledContextWindow === contextWindow) {
+		if (!overrides.has(modelId)) return;
+		overrides.delete(modelId);
+	} else {
+		if (overrides.get(modelId) === contextWindow) return;
+		overrides.set(modelId, contextWindow);
+	}
+	const path = getCachePath();
+	mkdirSync(dirname(path), { recursive: true });
+	const data: ContextWindowCacheFile = {
+		contextWindows: Object.fromEntries([...overrides.entries()].sort(([a], [b]) => a.localeCompare(b))),
+	};
+	writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+
+export const __testUtils = {
+	getCachePath,
+};

package/src/context.ts

@@ -0,0 +1,100 @@
+import type { Context, Message, ToolCall } from "@mariozechner/pi-ai";
+import type { SDKImage } from "@cursor/sdk";
+
+export interface CursorPrompt {
+	text: string;
+	images: SDKImage[];
+}
+
+function isTextBlock(block: { type: string }): block is { type: "text"; text: string } {
+	return block.type === "text";
+}
+
+function isImageBlock(block: { type: string }): block is { type: "image"; data: string; mimeType: string } {
+	return block.type === "image";
+}
+
+function isToolCallBlock(block: { type: string }): block is ToolCall {
+	return block.type === "toolCall";
+}
+
+function extractLatestImages(messages: Message[]): SDKImage[] {
+	// Find the last user message and extract images only from it
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role !== "user") continue;
+		if (typeof msg.content === "string") return [];
+
+		const images: SDKImage[] = [];
+		for (const block of msg.content) {
+			if (isImageBlock(block) && block.data && block.mimeType) {
+				images.push({ data: block.data, mimeType: block.mimeType });
+			}
+		}
+		return images;
+	}
+	return [];
+}
+
+function formatContentBlocks(content: string | { type: string; text?: string; data?: string; mimeType?: string }[]): string {
+	if (typeof content === "string") return content;
+	return content
+		.map((block) => {
+			if (isTextBlock(block)) return block.text;
+			if (isImageBlock(block)) return "[image omitted from transcript]";
+			return "";
+		})
+		.filter(Boolean)
+		.join("\n");
+}
+
+function formatToolCall(toolCall: ToolCall): string {
+	const args = JSON.stringify(toolCall.arguments);
+	return `Tool call (${toolCall.name}, call ${toolCall.id}): ${args}`;
+}
+
+export function buildCursorPrompt(context: Context): CursorPrompt {
+	const parts: string[] = [];
+
+	if (context.systemPrompt) {
+		parts.push(`System instructions from pi:\n${context.systemPrompt}`);
+	}
+
+	for (const msg of context.messages) {
+		switch (msg.role) {
+			case "user": {
+				const text = formatContentBlocks(msg.content);
+				if (text) parts.push(`User: ${text}`);
+				break;
+			}
+			case "assistant": {
+				const blocks = Array.isArray(msg.content) ? msg.content : [{ type: "text" as const, text: String(msg.content) }];
+				const textParts: string[] = [];
+				for (const block of blocks) {
+					if (isTextBlock(block)) {
+						textParts.push(block.text);
+					} else if (isToolCallBlock(block)) {
+						textParts.push(formatToolCall(block));
+					}
+					// Omit thinking content from transcript
+				}
+				if (textParts.length > 0) {
+					parts.push(`Assistant: ${textParts.join("\n")}`);
+				}
+				break;
+			}
+			case "toolResult": {
+				const text = formatContentBlocks(msg.content);
+				const label = msg.isError ? "Tool error" : "Tool result";
+				parts.push(`${label} (${msg.toolName}, call ${msg.toolCallId}): ${text}`);
+				break;
+			}
+		}
+	}
+
+	parts.push("Answer the latest user request above using your capabilities. Do not assume access to pi tools.");
+
+	const images = extractLatestImages(context.messages);
+
+	return { text: parts.join("\n\n"), images };
+}

package/src/cursor-provider.ts

@@ -0,0 +1,342 @@
+import {
+	type Api,
+	type AssistantMessageEventStream,
+	type Context,
+	createAssistantMessageEventStream,
+	type Model,
+	type SimpleStreamOptions,
+	type AssistantMessage,
+} from "@mariozechner/pi-ai";
+import { Agent, createAgentPlatform } from "@cursor/sdk";
+import type { InteractionUpdate, SDKAgent } from "@cursor/sdk";
+import { buildCursorPrompt } from "./context.js";
+import { getEffectiveFastForModelId } from "./cursor-state.js";
+import { buildCursorModelSelection } from "./model-discovery.js";
+import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-window-cache.js";
+
+function makeInitialMessage(model: Model<Api>): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: model.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(),
+	};
+}
+
+class CursorAbortError extends Error {
+	constructor() {
+		super("aborted");
+		this.name = "CursorAbortError";
+	}
+}
+
+const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
+const MISSING_API_KEY_MESSAGE =
+	"Cursor SDK runs require CURSOR_API_KEY or pi --api-key. Set CURSOR_API_KEY before starting pi, or restart pi with --api-key.";
+const GENERIC_CURSOR_SDK_ERROR_MESSAGE =
+	"Cursor SDK request failed. The API key may be missing, invalid, or unauthorized. Verify CURSOR_API_KEY or pass --api-key, then retry.";
+const AUTH_CURSOR_SDK_ERROR_MESSAGE =
+	"Cursor SDK request failed because the API key may be invalid or unauthorized. Verify CURSOR_API_KEY or pass --api-key, then retry.";
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function scrubSensitiveText(text: string, apiKey?: string): string {
+	let scrubbed = text;
+	const trimmedKey = apiKey?.trim();
+	if (trimmedKey) {
+		scrubbed = scrubbed.replace(new RegExp(escapeRegExp(trimmedKey), "g"), "[redacted]");
+	}
+	return scrubbed
+		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+		.replace(/(authorization\s*[:=]\s*)[^\s,;}]+/gi, "$1[redacted]")
+		.replace(/(api[_-]?key\s*[:=]\s*)[^\s,;}]+/gi, "$1[redacted]")
+		.replace(/(token\s*[:=]\s*)[^\s,;}]+/gi, "$1[redacted]")
+		.replace(/(cookie\s*[:=]\s*)[^\n]+/gi, "$1[redacted]")
+		.replace(/(session\s*[:=]\s*)[^\s,;}]+/gi, "$1[redacted]");
+}
+
+function isGenericErrorMessage(message: string): boolean {
+	const normalized = message.trim().toLowerCase();
+	return normalized === "" || normalized === "error" || normalized === "unknown error";
+}
+
+function isLikelyAuthError(message: string): boolean {
+	return /\b(unauthorized|unauthorised|forbidden|invalid api key|invalid key|authentication|auth|401|403)\b/i.test(message);
+}
+
+function hasEnvCursorApiKey(): boolean {
+	return Boolean(process.env.CURSOR_API_KEY?.trim());
+}
+
+function isMissingCursorApiKey(apiKey?: string): boolean {
+	return !apiKey || (apiKey === CURSOR_API_KEY_ENV_VAR && !hasEnvCursorApiKey());
+}
+
+function sanitizeError(error: unknown, apiKey?: string): string {
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	if (message === MISSING_API_KEY_MESSAGE) return MISSING_API_KEY_MESSAGE;
+	const scrubbed = scrubSensitiveText(message, apiKey).trim();
+	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;
+	if (isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
+	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
+}
+
+function getObjectField(value: unknown, field: string): unknown {
+	if (!value || typeof value !== "object") return undefined;
+	return (value as Record<string, unknown>)[field];
+}
+
+function getCursorToolName(toolCall: unknown): string {
+	if (!toolCall || typeof toolCall !== "object") return "unknown";
+	const data = toolCall as Record<string, unknown>;
+	if (typeof data.name === "string") return data.name;
+	if (typeof data.type === "string") return data.type;
+	return "unknown";
+}
+
+function getCursorToolResult(toolCall: unknown): unknown {
+	return getObjectField(toolCall, "result");
+}
+
+async function cacheSdkContextWindow(agentId: string, modelId: string): Promise<void> {
+	try {
+		const platform = await createAgentPlatform();
+		const checkpoint = await platform.checkpointStore.loadLatest(agentId);
+		const contextWindow = getCheckpointContextWindow(checkpoint);
+		if (contextWindow) saveCachedContextWindow(modelId, contextWindow);
+	} catch {
+		// Context-window cache failures must not affect response streaming.
+	}
+}
+
+function summarizeCursorToolResult(result: unknown): string {
+	if (result === undefined) return "";
+	const parts: string[] = [];
+	const status = getObjectField(result, "status");
+	if (typeof status === "string") parts.push(status);
+	const value = getObjectField(result, "value");
+	const exitCode = getObjectField(value, "exitCode") ?? getObjectField(result, "exitCode");
+	if (typeof exitCode === "number") parts.push(`exit ${exitCode}`);
+	return parts.length > 0 ? `: ${parts.join(", ")}` : "";
+}
+
+export function streamCursor(
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const stream = createAssistantMessageEventStream();
+
+	(async () => {
+		const partial = makeInitialMessage(model);
+		let agent: SDKAgent | null = null;
+		let abortSignal: AbortSignal | undefined;
+		let abortListener: (() => void) | undefined;
+
+		try {
+			const throwIfAborted = (): void => {
+				if (options?.signal?.aborted) throw new CursorAbortError();
+			};
+
+			stream.push({ type: "start", partial });
+			throwIfAborted();
+
+			const apiKey = options?.apiKey;
+			if (isMissingCursorApiKey(apiKey)) throw new Error(MISSING_API_KEY_MESSAGE);
+
+			const cwd = process.cwd();
+			const fastEnabled = getEffectiveFastForModelId(model.id);
+			const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
+
+			agent = await Agent.create({
+				apiKey,
+				model: selection,
+				// Do not pass settingSources here. The Cursor SDK currently writes
+				// setting/rule loading INFO logs directly to process output, which corrupts pi's TUI.
+				local: { cwd },
+			});
+			throwIfAborted();
+
+			const prompt = buildCursorPrompt(context);
+			let textContentIndex = -1;
+			let thinkingContentIndex = -1;
+			const textDeltas: string[] = [];
+
+			const appendBufferedTextDelta = (text: string): void => {
+				textDeltas.push(text);
+			};
+
+			const appendTraceDelta = (text: string): void => {
+				if (thinkingContentIndex < 0) {
+					thinkingContentIndex = partial.content.length;
+					partial.content.push({ type: "thinking", thinking: "" });
+					stream.push({ type: "thinking_start", contentIndex: thinkingContentIndex, partial });
+				}
+				const block = partial.content[thinkingContentIndex];
+				if (block.type === "thinking") {
+					block.thinking += text;
+					stream.push({
+						type: "thinking_delta",
+						contentIndex: thinkingContentIndex,
+						delta: text,
+						partial,
+					});
+				}
+			};
+
+			const appendCursorToolStatus = (text: string): void => {
+				appendTraceDelta(`${text}\n`);
+			};
+
+			const flushBufferedText = (fallbackText?: string): void => {
+				const deltas = textDeltas.length > 0 ? textDeltas : fallbackText ? [fallbackText] : [];
+				if (deltas.length === 0) return;
+				textContentIndex = partial.content.length;
+				partial.content.push({ type: "text", text: "" });
+				stream.push({ type: "text_start", contentIndex: textContentIndex, partial });
+				const block = partial.content[textContentIndex];
+				if (block.type !== "text") return;
+				for (const delta of deltas) {
+					block.text += delta;
+					stream.push({
+						type: "text_delta",
+						contentIndex: textContentIndex,
+						delta,
+						partial,
+					});
+				}
+				stream.push({
+					type: "text_end",
+					contentIndex: textContentIndex,
+					content: block.text,
+					partial,
+				});
+			};
+
+			const onDelta = (args: { update: InteractionUpdate }): void => {
+				const update = args.update;
+
+				if (update.type === "text-delta") {
+					appendBufferedTextDelta(update.text);
+				} else if (update.type === "thinking-delta") {
+					appendTraceDelta(update.text);
+				} else if (update.type === "thinking-completed") {
+					if (thinkingContentIndex >= 0) {
+						const block = partial.content[thinkingContentIndex];
+						if (block.type === "thinking") {
+							stream.push({
+								type: "thinking_end",
+								contentIndex: thinkingContentIndex,
+								content: block.thinking,
+								partial,
+							});
+						}
+						thinkingContentIndex = -1;
+					}
+				} else if (update.type === "tool-call-started") {
+					appendCursorToolStatus(`Cursor tool started (${getCursorToolName(update.toolCall)}, call ${update.callId})`);
+				} else if (update.type === "tool-call-completed") {
+					const suffix = summarizeCursorToolResult(getCursorToolResult(update.toolCall));
+					appendCursorToolStatus(`Cursor tool completed (${getCursorToolName(update.toolCall)}, call ${update.callId})${suffix}`);
+				} else if (update.type === "summary") {
+					appendCursorToolStatus(`Cursor summary: ${update.summary}`);
+				} else if (update.type === "turn-ended" && update.usage) {
+					partial.usage.input = update.usage.inputTokens;
+					partial.usage.output = update.usage.outputTokens;
+					partial.usage.cacheRead = update.usage.cacheReadTokens;
+					partial.usage.cacheWrite = update.usage.cacheWriteTokens;
+					partial.usage.totalTokens =
+						update.usage.inputTokens + update.usage.outputTokens + update.usage.cacheReadTokens + update.usage.cacheWriteTokens;
+				}
+				// partial-tool-call, summary-started, summary-completed,
+				// shell-output-delta, token-delta, step-* are intentionally not surfaced.
+			};
+
+			// Handle abort signal
+			let run: Awaited<ReturnType<SDKAgent["send"]>> | null = null;
+			abortListener = () => {
+				if (run) {
+					run.cancel().catch(() => {});
+				}
+			};
+			abortSignal = options?.signal;
+			abortSignal?.addEventListener("abort", abortListener, { once: true });
+
+			throwIfAborted();
+			run = await agent.send(
+				{ text: prompt.text, images: prompt.images.length > 0 ? prompt.images : undefined },
+				{ onDelta },
+			);
+			if (options?.signal?.aborted) {
+				await run.cancel().catch(() => {});
+				throw new CursorAbortError();
+			}
+
+			const result = await run.wait();
+			await cacheSdkContextWindow(agent.agentId, model.id);
+
+			// Close open thinking/trace before flushing final assistant text so saved
+			// message content is trace first, final answer second.
+			if (thinkingContentIndex >= 0) {
+				const block = partial.content[thinkingContentIndex];
+				if (block.type === "thinking") {
+					stream.push({
+						type: "thinking_end",
+						contentIndex: thinkingContentIndex,
+						content: block.thinking,
+						partial,
+					});
+				}
+				thinkingContentIndex = -1;
+			}
+
+			flushBufferedText(result.result);
+
+			if (result.status === "cancelled") {
+				partial.stopReason = "aborted";
+				stream.push({ type: "error", reason: "aborted", error: partial });
+			} else {
+				stream.push({ type: "done", reason: "stop", message: partial });
+			}
+		} catch (error) {
+			if (error instanceof CursorAbortError) {
+				partial.stopReason = "aborted";
+				stream.push({ type: "error", reason: "aborted", error: partial });
+			} else {
+				partial.stopReason = "error";
+				partial.errorMessage = sanitizeError(error, options?.apiKey);
+				stream.push({ type: "error", reason: "error", error: partial });
+			}
+		} finally {
+			if (abortSignal && abortListener) {
+				abortSignal.removeEventListener("abort", abortListener);
+			}
+
+			if (agent) {
+				try {
+					await agent[Symbol.asyncDispose]();
+				} catch {
+					// disposal failure should not mask original error
+				}
+				agent = null;
+			}
+		}
+
+		stream.end();
+	})();
+
+	return stream;
+}