pi-cursor-sdk 0.1.17 → 0.1.19

package/scripts/lib/cursor-sdk-output-filter.mjs

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const CURSOR_SDK_STARTUP_NOISE_PATTERNS = [
+	"[hooks]",
+	"managed_skills.",
+	"CursorPluginsAgentSkillsService load completed",
+	"LocalCursorRulesService load completed",
+	"AgentSkillsCursorRulesService load completed",
+	"Error initializing ignore mapping for",
+	"Ripgrep path not configured. Call configureRipgrepPath() at startup.",
+];
+
+const cursorSdkOutputSuppression = new AsyncLocalStorage();
+
+export function isCursorSdkOutputSuppressed() {
+	return cursorSdkOutputSuppression.getStore() === true;
+}
+
+export function suppressCursorSdkOutput(operation) {
+	return cursorSdkOutputSuppression.run(true, operation);
+}
+
+export function isCursorSdkStartupNoise(text) {
+	return CURSOR_SDK_STARTUP_NOISE_PATTERNS.some((pattern) => text.includes(pattern));
+}
+
+function createFilteredProcessWrite(write, stream) {
+	return (chunk, encodingOrCallback, callback) => {
+		const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) {
+			const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+			done?.();
+			return true;
+		}
+		return write.call(stream, chunk, encodingOrCallback, callback);
+	};
+}
+
+function createFilteredConsoleMethod(method) {
+	return (...args) => {
+		const text = args.map((arg) => (typeof arg === "string" ? arg : String(arg))).join(" ");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) return;
+		method(...args);
+	};
+}
+
+let activeOutputFilterInstalls = 0;
+let outputFilterOriginals;
+
+export function installCursorSdkOutputFilter() {
+	if (activeOutputFilterInstalls === 0) {
+		outputFilterOriginals = {
+			stdoutWrite: process.stdout.write,
+			stderrWrite: process.stderr.write,
+			consoleLog: console.log,
+			consoleInfo: console.info,
+			consoleWarn: console.warn,
+			consoleError: console.error,
+			consoleDebug: console.debug,
+		};
+		process.stdout.write = createFilteredProcessWrite(outputFilterOriginals.stdoutWrite, process.stdout);
+		process.stderr.write = createFilteredProcessWrite(outputFilterOriginals.stderrWrite, process.stderr);
+		console.log = createFilteredConsoleMethod(outputFilterOriginals.consoleLog);
+		console.info = createFilteredConsoleMethod(outputFilterOriginals.consoleInfo);
+		console.warn = createFilteredConsoleMethod(outputFilterOriginals.consoleWarn);
+		console.error = createFilteredConsoleMethod(outputFilterOriginals.consoleError);
+		console.debug = createFilteredConsoleMethod(outputFilterOriginals.consoleDebug);
+	}
+	activeOutputFilterInstalls += 1;
+
+	let restored = false;
+	return () => {
+		if (restored) return;
+		restored = true;
+		activeOutputFilterInstalls = Math.max(activeOutputFilterInstalls - 1, 0);
+		if (activeOutputFilterInstalls > 0 || !outputFilterOriginals) return;
+		process.stdout.write = outputFilterOriginals.stdoutWrite;
+		process.stderr.write = outputFilterOriginals.stderrWrite;
+		console.log = outputFilterOriginals.consoleLog;
+		console.info = outputFilterOriginals.consoleInfo;
+		console.warn = outputFilterOriginals.consoleWarn;
+		console.error = outputFilterOriginals.consoleError;
+		console.debug = outputFilterOriginals.consoleDebug;
+		outputFilterOriginals = undefined;
+	};
+}

package/scripts/validate-smoke-jsonl.mjs

@@ -5,6 +5,13 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 
+const REPLAY_TOOL_NOT_FOUND = [
+	"Tool grep not found",
+	"Tool cursor not found",
+	"Tool find not found",
+	"Tool ls not found",
+];
+
 function printHelp() {
 	console.log(`Validate assistant presence and usage metadata in pi smoke session JSONL files.
 
@@ -18,21 +25,27 @@ Arguments:
 
 Options:
   -h, --help                    Show this help.
+  --replay-errors               Also fail when JSONL contains native replay "Tool * not found" errors.
+  --replay-errors-only          Scan only for native replay "Tool * not found" errors (skip usage checks).
 
 Exit codes:
-  0  every scanned JSONL file has at least one assistant message and valid assistant usage metadata
-  1  invalid arguments, unreadable directory, invalid JSONL, empty/no-assistant files, or usage validation failures
+  0  every enforced invariant passed for the selected mode(s)
+  1  invalid arguments, unreadable directory, invalid JSONL, empty/no-assistant files, usage validation failures, or replay tool errors
   2  no JSONL files found under the smoke directory
 
-Enforced invariants:
+Enforced invariants (default mode):
   - each scanned JSONL file contains parseable JSONL records
   - each scanned JSONL file contains at least one persisted assistant message
   - every persisted assistant message has usage metadata
   - assistant usage input/output/totalTokens are non-negative numbers
   - assistant usage cacheRead/cacheWrite are exactly 0
 
+Replay error scan (--replay-errors / --replay-errors-only):
+  - 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.
+  - Prints one JSON summary line per scanned session file (usage mode) or one replay summary line (replay-only mode).
   - Does not print session message contents or secrets.`);
 }
 
@@ -88,6 +101,42 @@ 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 message = record?.type === "message" ? record.message : undefined;
+		if (!message) continue;
+		for (const needle of REPLAY_TOOL_NOT_FOUND) {
+			if (isReplayErrorMessage(message, needle)) {
+				hits.push({ line: index + 1, needle });
+			}
+		}
+	}
+	return hits;
+}
+
 function main() {
 	const args = process.argv.slice(2);
 	if (args.includes("-h") || args.includes("--help")) {
@@ -95,11 +144,15 @@ function main() {
 		return;
 	}
 
-	if (args.length > 1) {
+	const replayErrorsOnly = args.includes("--replay-errors-only");
+	const replayErrors = replayErrorsOnly || args.includes("--replay-errors");
+	const positional = args.filter((arg) => !arg.startsWith("-"));
+
+	if (positional.length > 1) {
 		fail("too many arguments; pass only the smoke directory");
 	}
 
-	const smokeDir = args[0] ?? process.env.SMOKE_DIR;
+	const smokeDir = positional[0] ?? process.env.SMOKE_DIR;
 	if (!smokeDir) {
 		fail("missing smoke directory; pass a path or set SMOKE_DIR");
 	}
@@ -117,6 +170,24 @@ function main() {
 	}
 
 	let failures = 0;
+	if (replayErrorsOnly) {
+		let replayHitCount = 0;
+		for (const file of files) {
+			const { records } = parseJsonlFile(file);
+			const hits = scanReplayErrors(file, records);
+			replayHitCount += hits.length;
+			if (hits.length > 0) failures += 1;
+			console.log(
+				JSON.stringify({
+					file: relative(smokeDir, file),
+					replayErrorCount: hits.length,
+					replayErrors: hits.slice(0, 5),
+				}),
+			);
+		}
+		process.exit(failures === 0 ? 0 : 1);
+	}
+
 	for (const file of files) {
 		let summary;
 		try {
@@ -125,7 +196,14 @@ function main() {
 			const assistants = messages.filter((message) => message?.role === "assistant");
 			const usage = assistants.map((message) => message.usage).filter(Boolean);
 			const badUsage = assistants.map((message) => message.usage).filter(isBadUsage);
-			const fileFailure = lineCount === 0 || parseErrorCount > 0 || assistants.length === 0 || usage.length !== assistants.length || badUsage.length > 0;
+			const replayHits = replayErrors ? scanReplayErrors(file, records) : [];
+			const fileFailure =
+				lineCount === 0 ||
+				parseErrorCount > 0 ||
+				assistants.length === 0 ||
+				usage.length !== assistants.length ||
+				badUsage.length > 0 ||
+				replayHits.length > 0;
 			if (fileFailure) failures += 1;
 			summary = {
 				file: relative(smokeDir, file),
@@ -135,6 +213,7 @@ function main() {
 				assistantCount: assistants.length,
 				usageCount: usage.length,
 				badUsageCount: badUsage.length,
+				replayErrorCount: replayHits.length,
 			};
 		} catch (error) {
 			failures += 1;

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.";
+}