pi-cursor-sdk 0.1.18 → 0.1.20

package/scripts/probe-mcp-coldstart.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Maintainer probe: measure Cursor SDK cold-start timing with/without ambient MCP settings
+ * and with the pi-cursor-sdk MCP connect timeout override installed.
+ */
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import {
+	installCursorMcpToolTimeoutOverride,
+	restoreCursorMcpToolTimeoutOverride,
+} from "../src/cursor-mcp-timeout-override.ts";
+import { scrubSensitiveText } from "./lib/cursor-probe-utils.mjs";
+import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./lib/cursor-sdk-output-filter.mjs";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const SCENARIOS = [
+	{ label: "with-all-settings", settingSources: ["all"] },
+	{ label: "with-all-settings+connect-override", settingSources: ["all"], installConnectOverride: true },
+	{ label: "no-setting-sources", settingSources: undefined },
+];
+
+function printHelp() {
+	console.log(`Measure Cursor SDK first-send MCP cold-start timing.
+
+Usage:
+  CURSOR_API_KEY=... npm run debug:mcp-coldstart
+  node scripts/probe-mcp-coldstart.mjs [options]
+
+Options:
+  --api-key <key>     Cursor API key. Prefer CURSOR_API_KEY to avoid shell history.
+  --scenario <label>  Run one scenario in this process. Used by the orchestrator.
+  -h, --help          Show this help without importing or calling the Cursor SDK.
+
+Stdout:
+  Emits one JSON object per scenario. Human status lines go to stderr.
+
+Scenarios:
+  with-all-settings                   Cursor settingSources=["all"]
+  with-all-settings+connect-override  Same, with pi-cursor-sdk timeout override installed
+  no-setting-sources                  No explicit settingSources
+
+Safety:
+  - --help never performs live Cursor calls.
+  - Each default scenario runs in a fresh child process before its first Cursor SDK import.
+  - SDK startup noise is suppressed.
+  - Error messages are scrubbed for API keys, bearer tokens, cookies, and bridge endpoints.`);
+}
+
+function fail(message, apiKey) {
+	console.error(`probe-mcp-coldstart: ${scrubSensitiveText(message, apiKey)}`);
+	process.exit(1);
+}
+
+function findScenario(label) {
+	return SCENARIOS.find((scenario) => scenario.label === label);
+}
+
+function parseArgs(argv, env = process.env) {
+	const args = {
+		apiKey: env.CURSOR_API_KEY?.trim() || undefined,
+		help: false,
+		scenario: undefined,
+	};
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		if (arg === "-h" || arg === "--help") {
+			args.help = true;
+			continue;
+		}
+		if (arg === "--api-key") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--api-key requires a value", args.apiKey);
+			args.apiKey = value.trim();
+			continue;
+		}
+		if (arg.startsWith("--api-key=")) {
+			args.apiKey = arg.slice("--api-key=".length).trim();
+			continue;
+		}
+		if (arg === "--scenario") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--scenario requires a value", args.apiKey);
+			args.scenario = value.trim();
+			continue;
+		}
+		if (arg.startsWith("--scenario=")) {
+			args.scenario = arg.slice("--scenario=".length).trim();
+			continue;
+		}
+		fail(`unknown argument: ${arg}`, args.apiKey);
+	}
+	if (args.scenario && !findScenario(args.scenario)) {
+		fail(`unknown scenario: ${args.scenario}`, args.apiKey);
+	}
+	return args;
+}
+
+async function probe(Agent, apiKey, label, { settingSources, installConnectOverride = false } = {}) {
+	let agent;
+	try {
+		const marks = [];
+		const t0 = performance.now();
+		const mark = (name) => marks.push({ name, ms: Math.round(performance.now() - t0) });
+
+		mark("start");
+		agent = await suppressCursorSdkOutput(() =>
+			Agent.create({
+				apiKey,
+				model: { id: "composer-2.5" },
+				local: settingSources
+					? { cwd: process.cwd(), settingSources }
+					: { cwd: process.cwd() },
+			}),
+		);
+		mark("agent.create");
+
+		let firstDeltaMs;
+		const run = await suppressCursorSdkOutput(() =>
+			agent.send("Reply with exactly: pong", {
+				onDelta: ({ update }) => {
+					if (firstDeltaMs === undefined && update.type === "text-delta") {
+						firstDeltaMs = Math.round(performance.now() - t0);
+						mark("first-delta");
+					}
+				},
+			}),
+		);
+		mark("agent.send-returned");
+
+		const result = await suppressCursorSdkOutput(() => run.wait());
+		mark("run.wait");
+
+		await suppressCursorSdkOutput(() => agent[Symbol.asyncDispose]());
+		agent = undefined;
+		mark("dispose");
+
+		const sendReturnedMs = marks.find((entry) => entry.name === "agent.send-returned")?.ms;
+		const mcpBlockingMs =
+			firstDeltaMs !== undefined && sendReturnedMs !== undefined ? firstDeltaMs - sendReturnedMs : undefined;
+
+		return {
+			label,
+			settingSources: settingSources ?? null,
+			installConnectOverride,
+			marks,
+			firstDeltaMs,
+			mcpBlockingMs,
+			status: result.status,
+			text: typeof result.result === "string" ? result.result.slice(0, 120) : null,
+		};
+	} finally {
+		if (agent) {
+			await suppressCursorSdkOutput(() => agent[Symbol.asyncDispose]()).catch(() => undefined);
+		}
+	}
+}
+
+async function runScenarioInThisProcess(args, scenario) {
+	const restoreOutputFilter = installCursorSdkOutputFilter();
+	try {
+		if (scenario.installConnectOverride) {
+			const state = installCursorMcpToolTimeoutOverride();
+			console.error(
+				`probe-mcp-coldstart: installed connect override (${state.connectTimeoutMs}ms initialize/listTools, ${state.timeoutMs}ms callTool)`,
+			);
+		}
+		const { Agent } = await suppressCursorSdkOutput(() => import("@cursor/sdk"));
+		console.log(JSON.stringify(await probe(Agent, args.apiKey, scenario.label, scenario)));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.log(
+			JSON.stringify({
+				label: scenario.label,
+				error: scrubSensitiveText(message, args.apiKey),
+			}),
+		);
+	} finally {
+		restoreCursorMcpToolTimeoutOverride();
+		restoreOutputFilter();
+	}
+}
+
+function runScenarioChild(args, scenario) {
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, [SCRIPT_PATH, "--scenario", scenario.label], {
+			cwd: process.cwd(),
+			env: { ...process.env, CURSOR_API_KEY: args.apiKey },
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.on("error", (error) => {
+			stderr += error instanceof Error ? error.message : String(error);
+		});
+		child.on("close", (code) => {
+			const scrubbedStderr = scrubSensitiveText(stderr, args.apiKey);
+			if (scrubbedStderr) process.stderr.write(scrubbedStderr.endsWith("\n") ? scrubbedStderr : `${scrubbedStderr}\n`);
+			if (code === 0 && stdout.trim()) {
+				process.stdout.write(stdout.endsWith("\n") ? stdout : `${stdout}\n`);
+				resolve();
+				return;
+			}
+			const error = scrubbedStderr.trim() || `child process exited with code ${code ?? "unknown"}`;
+			console.log(JSON.stringify({ label: scenario.label, error }));
+			resolve();
+		});
+	});
+}
+
+async function main(argv = process.argv.slice(2), env = process.env) {
+	const args = parseArgs(argv, env);
+	if (args.help) {
+		printHelp();
+		return;
+	}
+	if (!args.apiKey) {
+		fail("CURSOR_API_KEY is required. Set CURSOR_API_KEY or pass --api-key.");
+	}
+
+	const scenario = args.scenario ? findScenario(args.scenario) : undefined;
+	if (scenario) {
+		await runScenarioInThisProcess(args, scenario);
+		return;
+	}
+
+	for (const scenarioToRun of SCENARIOS) {
+		await runScenarioChild(args, scenarioToRun);
+	}
+}
+
+if (import.meta.url === new URL(process.argv[1], "file:").href) {
+	main().catch((error) => {
+		const message = error instanceof Error ? error.message : String(error);
+		fail(message, process.env.CURSOR_API_KEY);
+	});
+}

package/scripts/validate-smoke-jsonl.mjs

@@ -41,7 +41,8 @@ Enforced invariants (default mode):
   - assistant usage cacheRead/cacheWrite are exactly 0
 
 Replay error scan (--replay-errors / --replay-errors-only):
-  - no JSONL record contains "Tool grep/cursor/find/ls not found"
+  - no persisted error toolResult or error assistant message contains "Tool grep/cursor/find/ls not found"
+  - successful tool/file reads that mention those strings in docs are ignored
 
 Notes:
   - Prints one JSON summary line per scanned session file (usage mode) or one replay summary line (replay-only mode).
@@ -100,12 +101,35 @@ function parseJsonlFile(file) {
 	return { lineCount: lines.length, records, parseErrorCount };
 }
 
+function getMessageText(message) {
+	if (!message || typeof message !== "object") return "";
+	const parts = [];
+	if (typeof message.errorMessage === "string") parts.push(message.errorMessage);
+	if (Array.isArray(message.content)) {
+		for (const block of message.content) {
+			if (block?.type === "text" && typeof block.text === "string") parts.push(block.text);
+		}
+	}
+	return parts.join("\n");
+}
+
+function isReplayErrorMessage(message, needle) {
+	const text = getMessageText(message);
+	if (!text.includes(needle)) return false;
+	if (message.role === "toolResult" && message.isError === true) return true;
+	if (message.role === "assistant" && (message.stopReason === "error" || typeof message.errorMessage === "string")) {
+		return true;
+	}
+	return false;
+}
+
 function scanReplayErrors(file, records) {
 	const hits = [];
 	for (const [index, record] of records.entries()) {
-		const blob = JSON.stringify(record);
+		const message = record?.type === "message" ? record.message : undefined;
+		if (!message) continue;
 		for (const needle of REPLAY_TOOL_NOT_FOUND) {
-			if (blob.includes(needle)) {
+			if (isReplayErrorMessage(message, needle)) {
 				hits.push({ line: index + 1, needle });
 			}
 		}

package/src/context.ts

@@ -20,6 +20,33 @@ export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
 export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
+export function getCursorToolTailGuardText(): string {
+	return "Tool boundary reminder: If a tool is needed, call an available Cursor SDK/MCP tool. Never print a tool card (for example Tool call/Shell/command) as assistant text.";
+}
+
+function getCursorToolBoundaryText(): string {
+	return [
+		"Cursor SDK tool boundary:",
+		"You can call only tools actually exposed by Cursor SDK in this run. Pi tool names, replay tool names, and transcript tool names are context only, not callable capabilities.",
+		getCursorPiBridgeContractText(),
+		"If asked to list or exercise available tools, list and exercise Cursor SDK tools only; do not claim access to pi-side tools from the system prompt unless Cursor exposes an equivalent tool that runs.",
+		"Use pi__cursor_ask_question for material choices if exposed.",
+		"Web: use Cursor web/search/browser/MCP or say web search is not configured; do not claim WebSearch/WebFetch unless Cursor executes them.",
+		"Replay: pi may display recorded Cursor tool activity as pi-style cards, but replay is display-only and not a capability to invoke.",
+		"Images: only latest user images are sent; ask to reattach or describe prior images.",
+	].join("\n");
+}
+
+function getCursorBootstrapTailSections(): string[] {
+	return [
+		[
+			"Answer the latest user request above using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from the system prompt as if they were available.",
+			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
+		].join("\n"),
+		getCursorToolTailGuardText(),
+	];
+}
+
 function normalizePiContextMessages(messages: Context["messages"]): Message[] {
 	return convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
 }
@@ -281,7 +308,7 @@ export function computeCursorContextFingerprint(context: Context): string {
 	return JSON.stringify(payload);
 }
 
-export function shouldBootstrapCursorSend(
+export function shouldBootstrapCursorContext(
 	sendState: { bootstrapped: boolean; contextFingerprint: string },
 	context: Context,
 ): boolean {
@@ -304,6 +331,14 @@ export function shouldBootstrapCursorSend(
 	return false;
 }
 
+/** @deprecated Use planCursorSessionSend() for send mode and shouldBootstrapCursorContext() for context-only checks. */
+export function shouldBootstrapCursorSend(
+	sendState: { bootstrapped: boolean; contextFingerprint: string },
+	context: Context,
+): boolean {
+	return shouldBootstrapCursorContext(sendState, context);
+}
+
 export function buildCursorIncrementalPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
 	// Incremental sends omit the full Cursor SDK tool boundary block; the session agent retains prior bootstrap context.
 	const messages = normalizePiContextMessages(context.messages);
@@ -324,35 +359,18 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 		options.maxInputTokens === undefined
 			? options
 			: { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
-	const parts = applyPromptBudget(sectionsBeforeMessages, latestUserMessageSections, [], latestUserMessageIndex, budgetOptions);
+	const parts = applyPromptBudget(
+		sectionsBeforeMessages,
+		latestUserMessageSections,
+		[getCursorToolTailGuardText()],
+		latestUserMessageIndex,
+		budgetOptions,
+	);
 	return { text: parts.join(SECTION_SEPARATOR), images };
 }
 
-export function buildCursorSendPrompt(
-	context: Context,
-	options: CursorPromptOptions,
-	sendState: { bootstrapped: boolean; contextFingerprint: string },
-): { prompt: CursorPrompt; bootstrap: boolean } {
-	const bootstrap = shouldBootstrapCursorSend(sendState, context);
-	if (bootstrap) {
-		return { prompt: buildCursorPrompt(context, options), bootstrap: true };
-	}
-	return { prompt: buildCursorIncrementalPrompt(context, options), bootstrap: false };
-}
-
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
-	const sectionsBeforeMessages: string[] = [
-		[
-			"Cursor SDK tool boundary:",
-			"You can call only tools actually exposed by Cursor SDK in this run. Pi tool names, replay tool names, and transcript tool names are context only, not callable capabilities.",
-			getCursorPiBridgeContractText(),
-			"If asked to list or exercise available tools, list and exercise Cursor SDK tools only; do not claim access to pi-side tools from the system prompt unless Cursor exposes an equivalent tool that runs.",
-			"Use pi__cursor_ask_question for material choices if exposed.",
-			"Web: use Cursor web/search/browser/MCP or say web search is not configured; do not claim WebSearch/WebFetch unless Cursor executes them.",
-			"Replay: pi may display recorded Cursor tool activity as pi-style cards, but replay is display-only and not a capability to invoke.",
-			"Images: only latest user images are sent; ask to reattach or describe prior images.",
-		].join("\n"),
-	];
+	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText()];
 
 	if (context.systemPrompt) {
 		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
@@ -365,12 +383,7 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 			return text ? { index, text } : undefined;
 		})
 		.filter((section): section is { index: number; text: string } => section !== undefined);
-	const sectionsAfterMessages = [
-		[
-			"Answer the latest user request above using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from the system prompt as if they were available.",
-			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
-		].join("\n"),
-	];
+	const sectionsAfterMessages = getCursorBootstrapTailSections();
 	const images = extractLatestImages(messages);
 	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
 	const budgetOptions =

package/src/cursor-agent-message-web-tools.ts

@@ -0,0 +1,172 @@
+import { Agent, type AgentMessage } from "@cursor/sdk";
+import { asRecord, getArray, getString, stringifyUnknown } from "./cursor-transcript-utils.js";
+
+const CURSOR_AGENT_MESSAGE_PAGE_LIMIT = 8;
+
+export interface CursorTranscriptCompletedToolCall {
+	identity: string;
+	toolCall: unknown;
+}
+
+interface CursorTranscriptWebToolPayload {
+	kind: "webSearch" | "webFetch";
+	payload: unknown;
+}
+
+function getOneofCaseValue(value: unknown, caseName: string): unknown {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	if (record.case === caseName) return record.value;
+	return record[caseName];
+}
+
+async function hasCursorAgentMessageAt(agentId: string, cwd: string, offset: number): Promise<boolean> {
+	const messages = await Agent.messages.list(agentId, { runtime: "local", cwd, limit: 1, offset });
+	return messages.length > 0;
+}
+
+export async function countCursorAgentMessages(agentId: string, cwd: string): Promise<number> {
+	let high = 1;
+	while (await hasCursorAgentMessageAt(agentId, cwd, high)) {
+		high *= 2;
+	}
+
+	let low = 0;
+	while (low < high) {
+		const mid = Math.floor((low + high) / 2);
+		if (await hasCursorAgentMessageAt(agentId, cwd, mid)) low = mid + 1;
+		else high = mid;
+	}
+	return low;
+}
+
+export async function loadCursorTranscriptWebToolCallsAfterOffset(options: {
+	agentId: string;
+	cwd: string;
+	offset: number | undefined;
+}): Promise<CursorTranscriptCompletedToolCall[]> {
+	if (options.offset === undefined) return [];
+	const messages = await Agent.messages.list(options.agentId, {
+		runtime: "local",
+		cwd: options.cwd,
+		limit: CURSOR_AGENT_MESSAGE_PAGE_LIMIT,
+		offset: options.offset,
+	});
+	return collectCursorTranscriptWebToolCalls(messages);
+}
+
+export function collectCursorTranscriptWebToolCalls(messages: readonly AgentMessage[]): CursorTranscriptCompletedToolCall[] {
+	const toolCalls: CursorTranscriptCompletedToolCall[] = [];
+	for (const [messageIndex, message] of messages.entries()) {
+		const messageId = message.uuid || `${message.agent_id || "cursor-agent"}:${messageIndex}`;
+		const steps = getAgentConversationSteps(message.message);
+		for (const [stepIndex, step] of steps.entries()) {
+			const webTool = getStepWebToolPayload(step);
+			if (!webTool) continue;
+			const converted = convertCursorTranscriptWebTool(webTool);
+			if (!converted) continue;
+			const args = asRecord(converted.args);
+			const toolCallId = getString(args, "toolCallId") ?? getString(args, "tool_call_id") ?? `${stepIndex}`;
+			toolCalls.push({
+				identity: `cursor-transcript:${messageId}:${webTool.kind}:${toolCallId}`,
+				toolCall: converted,
+			});
+		}
+	}
+	return toolCalls;
+}
+
+function getAgentConversationSteps(message: unknown): unknown[] {
+	const record = asRecord(message);
+	const turn = getOneofCaseValue(record?.turn, "agentConversationTurn") ?? record?.agentConversationTurn;
+	return getArray(asRecord(turn), "steps") ?? [];
+}
+
+function getStepToolCall(step: unknown): unknown {
+	const stepRecord = asRecord(step);
+	const message = asRecord(stepRecord?.message);
+	return getOneofCaseValue(message, "toolCall") ?? stepRecord?.toolCall ?? message?.toolCall;
+}
+
+function getStepWebToolPayload(step: unknown): CursorTranscriptWebToolPayload | undefined {
+	const toolCall = getStepToolCall(step);
+	const toolCallRecord = asRecord(toolCall);
+	const tool = toolCallRecord?.tool;
+	const webSearchPayload =
+		getOneofCaseValue(tool, "webSearchToolCall") ??
+		getOneofCaseValue(toolCall, "webSearchToolCall") ??
+		toolCallRecord?.webSearchToolCall;
+	if (webSearchPayload) return { kind: "webSearch", payload: webSearchPayload };
+
+	const webFetchPayload =
+		getOneofCaseValue(tool, "webFetchToolCall") ??
+		getOneofCaseValue(toolCall, "webFetchToolCall") ??
+		toolCallRecord?.webFetchToolCall;
+	if (webFetchPayload) return { kind: "webFetch", payload: webFetchPayload };
+	return undefined;
+}
+
+function convertCursorTranscriptWebTool(webTool: CursorTranscriptWebToolPayload): { name: string; args: Record<string, unknown>; result: unknown } | undefined {
+	const payload = asRecord(webTool.payload);
+	if (!payload) return undefined;
+	const rawArgs = asRecord(payload.args) ?? {};
+	const args = normalizeWebToolArgs(webTool.kind, rawArgs);
+	const result = normalizeWebToolResult(payload.result);
+	if (!result) return undefined;
+	return {
+		name: webTool.kind,
+		args,
+		result,
+	};
+}
+
+function normalizeWebToolArgs(kind: "webSearch" | "webFetch", rawArgs: Record<string, unknown>): Record<string, unknown> {
+	const args = { ...rawArgs };
+	if (kind === "webSearch") {
+		const query = getString(args, "searchTerm") ?? getString(args, "search_term") ?? getString(args, "query") ?? getString(args, "q");
+		if (query && !args.searchTerm) args.searchTerm = query;
+		return args;
+	}
+	const url = getString(args, "url") ?? getString(args, "uri") ?? getString(args, "href");
+	if (url && !args.url) args.url = url;
+	return args;
+}
+
+function normalizeWebToolResult(result: unknown): unknown | undefined {
+	if (result === undefined) return undefined;
+	const success = getTranscriptResultCase(result, "success");
+	if (success !== undefined) {
+		return {
+			status: "success",
+			value: { content: [{ type: "text", text: transcriptWebSuccessText(success) }] },
+		};
+	}
+
+	const error = getTranscriptResultCase(result, "error");
+	if (error !== undefined) return { status: "error", error };
+
+	return {
+		status: "success",
+		value: { content: [{ type: "text", text: transcriptWebSuccessText(result) }] },
+	};
+}
+
+function getTranscriptResultCase(result: unknown, caseName: "success" | "error"): unknown {
+	const record = asRecord(result);
+	return getOneofCaseValue(record?.result, caseName) ?? record?.[caseName];
+}
+
+function transcriptWebSuccessText(success: unknown): string {
+	const successRecord = asRecord(success);
+	const references = getArray(successRecord, "references");
+	const chunks = references
+		?.map((reference) => getString(asRecord(reference), "chunk"))
+		.filter((chunk): chunk is string => Boolean(chunk?.trim()));
+	if (chunks && chunks.length > 0) return chunks.join("\n\n");
+	const content = getArray(successRecord, "content");
+	const text = content
+		?.map((entry) => getString(asRecord(entry), "text"))
+		.filter((entry): entry is string => Boolean(entry?.trim()));
+	if (text && text.length > 0) return text.join("\n");
+	return stringifyUnknown(success).trim() || "Cursor web activity completed.";
+}