pi-cursor-sdk 0.1.37 → 0.1.38

package/src/cursor-transcript-tool-formatters.ts

@@ -1,19 +1,29 @@
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
-import { scrubSensitiveText } from "./cursor-sensitive-text.js";
-import { extractWebFetchTarget, extractWebSearchQuery } from "./cursor-web-tool-activity.js";
-import { getFirstStringByKeys } from "./cursor-record-utils.js";
+import { extractWebFetchTarget, extractWebSearchQuery } from "./cursor-web-tool-args.js";
 import {
 	asRecord,
-	formatDisplayPath,
-	formatDiffHeaderLine,
-	formatDiffString,
-	formatError,
-	formatPathArg,
 	getArray,
 	getBoolean,
+	getFirstStringByKeys,
 	getNumber,
 	getRecord,
 	getString,
+} from "./cursor-record-utils.js";
+import {
+	collectTaskText,
+	getGenerateImageDisplayPath,
+	readMcpDisplayResult,
+	getReadLintDiagnostics,
+	getReadLintPaths,
+	getTaskDescription,
+	getTodoItems,
+} from "./cursor-tool-result-display-readers.js";
+
+import {
+	formatDisplayPath,
+	formatDiffString,
+	formatError,
+	formatPathArg,
 	joinSections,
 	limitItems,
 	limitText,
@@ -23,7 +33,6 @@ import {
 	DEFAULT_NATIVE_READ_DISPLAY_LINES,
 	readFilePreview,
 	stringifyUnknown,
-	firstNonEmptyLine,
 	truncateArg,
 	type NormalizedResult,
 	type TranscriptOptions,
@@ -445,38 +454,6 @@ export function formatDelete(args: Record<string, unknown>, result: NormalizedRe
 	return joinSections(`delete ${path}`, fileSize !== undefined ? `Deleted ${fileSize} bytes` : stringifyUnknown(result.value));
 }
 
-export function getReadLintPaths(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string[] {
-	const explicitPaths = Array.isArray(args.paths)
-		? args.paths.filter((entry): entry is string => typeof entry === "string")
-		: typeof args.path === "string"
-			? [args.path]
-			: [];
-	const resultPaths = (getArray(asRecord(result.value), "fileDiagnostics") ?? [])
-		.map((file) => getString(asRecord(file), "path"))
-		.filter((entry): entry is string => Boolean(entry));
-	return [...new Set([...explicitPaths, ...resultPaths].map((entry) => formatDisplayPath(entry, options.cwd)))];
-}
-
-export function getReadLintDiagnostics(result: NormalizedResult, options: TranscriptOptions): string[] {
-	const value = asRecord(result.value);
-	const files = getArray(value, "fileDiagnostics") ?? [];
-	const lines: string[] = [];
-	for (const file of files) {
-		const fileRecord = asRecord(file);
-		const pathValue = getString(fileRecord, "path");
-		const path = pathValue ? formatDisplayPath(pathValue, options.cwd) : "unknown";
-		const diagnostics = getArray(fileRecord, "diagnostics") ?? [];
-		for (const diagnostic of diagnostics) {
-			const diagnosticRecord = asRecord(diagnostic);
-			const severity = getString(diagnosticRecord, "severity") ?? "diagnostic";
-			const message = getString(diagnosticRecord, "message") ?? "";
-			const source = getString(diagnosticRecord, "source");
-			lines.push(`${path}: ${severity}${source ? ` ${source}` : ""}: ${message}`);
-		}
-	}
-	return lines;
-}
-
 export function formatReadLints(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const paths = getReadLintPaths(args, result, options);
 	const header = `readLints${paths.length > 0 ? ` ${paths.join(" ")}` : ""}`;
@@ -487,24 +464,6 @@ export function formatReadLints(args: Record<string, unknown>, result: Normalize
 	return joinSections(header, limitText(lines.join("\n") || stringifyUnknown(result.value), options));
 }
 
-export function getTodoItems(args: Record<string, unknown>, result: NormalizedResult): Array<{ content: string; status?: string }> {
-	const value = asRecord(result.value);
-	const rawTodos = getArray(value, "todos") ?? getArray(args, "todos") ?? [];
-	const todos: Array<{ content: string; status?: string }> = [];
-	for (const todo of rawTodos) {
-		const record = asRecord(todo);
-		const content = getString(record, "content");
-		if (!content) continue;
-		const status = getString(record, "status");
-		todos.push(status ? { content, status } : { content });
-	}
-	return todos;
-}
-
-export function getTodoTotalCount(args: Record<string, unknown>, result: NormalizedResult, todos: Array<{ content: string; status?: string }>): number {
-	return getNumber(asRecord(result.value), "totalCount") ?? getNumber(args, "totalCount") ?? todos.length;
-}
-
 function formatTodoStatus(status: string | undefined): string {
 	if (status === "completed") return "✓";
 	if (status === "inProgress") return "…";
@@ -527,32 +486,6 @@ export function formatPlan(args: Record<string, unknown>, result: NormalizedResu
 	return formatTodos(args, result, options, "createPlan");
 }
 
-export function getTaskDescription(args: Record<string, unknown>, result: NormalizedResult): string {
-	return getString(args, "description") ?? getString(asRecord(result.value), "description") ?? "task";
-}
-
-function getNestedRecord(record: Record<string, unknown> | undefined, ...keys: string[]): Record<string, unknown> | undefined {
-	let current = record;
-	for (const key of keys) {
-		current = getRecord(current, key);
-		if (!current) return undefined;
-	}
-	return current;
-}
-
-export function collectTaskText(result: NormalizedResult): string {
-	const value = asRecord(result.value);
-	const success = getNestedRecord(value, "result", "success");
-	const command = getString(success, "command");
-	const stdout = getString(success, "stdout");
-	const interleavedOutput = getString(success, "interleavedOutput");
-	const assistantMessages = (getArray(value, "conversationSteps") ?? [])
-		.map((step) => getString(getRecord(asRecord(step), "assistantMessage"), "text"))
-		.filter((entry): entry is string => Boolean(entry));
-	const parts = [command ? `$ ${command}` : undefined, stdout || interleavedOutput, ...assistantMessages].filter((part): part is string => Boolean(part));
-	return parts.join("\n");
-}
-
 export function formatTask(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const description = getTaskDescription(args, result);
 	if (result.status === "error") return joinSections(`task ${description}`, formatError(result.error));
@@ -560,34 +493,10 @@ export function formatTask(args: Record<string, unknown>, result: NormalizedResu
 	return joinSections(`task ${description}`, limitText(taskText || stringifyUnknown(result.value), options));
 }
 
-function getGenerateImageValue(result: NormalizedResult): Record<string, unknown> | undefined {
-	return asRecord(result.value);
-}
-
-export function getGenerateImagePath(args: Record<string, unknown>, result: NormalizedResult): string | undefined {
-	const value = getGenerateImageValue(result);
-	return getString(value, "filePath") ?? getString(args, "filePath") ?? getString(args, "path");
-}
-
-export function getGenerateImageDisplayPath(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string | undefined {
-	const path = getGenerateImagePath(args, result);
-	return path ? formatDisplayPath(path, options.cwd) : undefined;
-}
-
-export function inferImageMimeType(path: string | undefined): string | undefined {
-	const lower = path?.toLowerCase();
-	if (!lower) return undefined;
-	if (lower.endsWith(".png")) return "image/png";
-	if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
-	if (lower.endsWith(".gif")) return "image/gif";
-	if (lower.endsWith(".webp")) return "image/webp";
-	return undefined;
-}
-
 export function formatGenerateImage(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const prompt = getString(args, "prompt") ?? getString(args, "description") ?? "image";
 	if (result.status === "error") return joinSections(`generateImage ${prompt}`, formatError(result.error));
-	const value = getGenerateImageValue(result);
+	const value = asRecord(result.value);
 	const displayPath = getGenerateImageDisplayPath(args, result, options);
 	const hasImageData = typeof value?.imageData === "string" && value.imageData.length > 0;
 	const lines = [displayPath ? `Saved image: ${displayPath}` : undefined, hasImageData ? "Image data returned by Cursor SDK." : undefined].filter(
@@ -597,26 +506,6 @@ export function formatGenerateImage(args: Record<string, unknown>, result: Norma
 	return joinSections(`generateImage ${prompt}`, limitText(stringifyUnknown(result.value), options));
 }
 
-function getMcpContentText(entry: unknown): string | undefined {
-	const record = asRecord(entry);
-	const directText = getString(record, "text");
-	if (directText) return directText;
-	const nestedText = getRecord(record, "text");
-	return getString(nestedText, "text");
-}
-
-function describeNonTextMcpContent(entry: unknown): string {
-	const record = asRecord(entry);
-	const type = getString(record, "type") ?? "content";
-	if (type === "image") {
-		const mimeType = getString(record, "mimeType") ?? getString(record, "mime") ?? getString(record, "mediaType");
-		return `[image${mimeType ? ` ${mimeType}` : ""} omitted]`;
-	}
-	if (type === "audio") return "[audio omitted]";
-	if (type === "resource") return "[resource omitted]";
-	return `[${type} omitted]`;
-}
-
 export function formatSemSearch(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const query = getString(args, "query") ?? "semantic search";
 	const header = `semSearch ${truncateArg(query)}`;
@@ -681,69 +570,31 @@ export function formatRecordScreen(args: Record<string, unknown>, result: Normal
 	return joinSections(header, lines.join("\n"));
 }
 
-export function getMcpResultPreview(result: NormalizedResult): string | undefined {
-	if (result.status === "error") return undefined;
-	const value = asRecord(result.value);
-	const content = getArray(value, "content") ?? [];
-	for (const entry of content) {
-		const text = getMcpContentText(entry);
-		if (text) {
-			const line = firstNonEmptyLine(text);
-			if (line) return truncateArg(scrubSensitiveText(line), 120);
-		}
-		const summary = describeNonTextMcpContent(entry);
-		if (summary) return summary;
-	}
-	return undefined;
-}
-
 function formatWebToolBody(
 	toolLabel: string,
-	args: Record<string, unknown>,
 	result: NormalizedResult,
 	options: TranscriptOptions,
-	summaryArg: string | undefined,
 ): string {
 	if (result.status === "error") return joinSections(toolLabel, formatError(result.error));
-	const summary = summaryArg ? `${summaryArg}\n\n` : "";
-	const value = asRecord(result.value);
-	const isError = getBoolean(value, "isError");
-	const content = getArray(value, "content") ?? [];
-	const text = content
-		.map((entry) => getMcpContentText(entry))
-		.filter((entry): entry is string => Boolean(entry))
-		.join("\n");
-	const contentSummary = content.length > 0 ? content.map(describeNonTextMcpContent).join("\n") : stringifyUnknown(result.value);
-	const body = `${isError ? "[tool error]\n" : ""}${text || contentSummary}`;
-	return joinSections(toolLabel, limitText(`${summary}${body}`.trim(), options));
+	return joinSections(toolLabel, limitText(readMcpDisplayResult(result).body, options));
 }
 
 export function formatWebSearch(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const query = extractWebSearchQuery(args);
 	const header = query ? `web search ${query}` : "web search";
-	return formatWebToolBody(header, args, result, options, undefined);
+	return formatWebToolBody(header, result, options);
 }
 
 export function formatWebFetch(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const target = extractWebFetchTarget(args);
 	const header = target ? `web fetch ${target}` : "web fetch";
-	return formatWebToolBody(header, args, result, options, undefined);
+	return formatWebToolBody(header, result, options);
 }
 
 export function formatMcp(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const toolName = typeof args.toolName === "string" ? args.toolName : "mcp";
 	if (result.status === "error") return joinSections(toolName, formatError(result.error));
-
-	const value = asRecord(result.value);
-	const isError = getBoolean(value, "isError");
-	const content = getArray(value, "content") ?? [];
-	const text = content
-		.map((entry) => getMcpContentText(entry))
-		.filter((entry): entry is string => Boolean(entry))
-		.join("\n");
-	const contentSummary = content.length > 0 ? content.map(describeNonTextMcpContent).join("\n") : stringifyUnknown(result.value);
-	const body = `${isError ? "[tool error]\n" : ""}${text || contentSummary}`;
-	return joinSections(toolName, limitText(body, options));
+	return joinSections(toolName, limitText(readMcpDisplayResult(result).body, options));
 }
 
 const UNKNOWN_TOOL_FALLBACK_MAX_ARGS = 8;

package/src/cursor-transcript-tool-specs.ts

@@ -1,8 +1,8 @@
 import {
 	CURSOR_KNOWN_NORMALIZED_TOOL_NAMES,
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
-	getCursorReplayActivityTitle,
 	getCursorReplayCallSummary,
+	getCursorToolActivityTitle,
 	getCursorToolActivityReplaySpec,
 	getCursorToolGenerateImageReplaySpec,
 	type CursorNormalizedToolName,
@@ -12,21 +12,16 @@ import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
 import {
 	assembleCursorReplayActivityDetails,
 	assembleCursorReplayGenerateImageDetails,
-	buildCursorReplayNativeEditDetails,
-	buildCursorReplayNativeWriteDetails,
 	CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME,
 	type CursorReplayToolDetails,
 } from "./cursor-replay-tool-details.js";
+import { asRecord, getNumber, getString } from "./cursor-record-utils.js";
 import {
-	asRecord,
 	firstNonEmptyLine,
 	formatDisplayPath,
 	formatDiffString,
 	formatError,
-	getNumber,
-	getString,
 	limitText,
-	stringifyUnknown,
 	truncateArg,
 	type CursorPiToolDisplay,
 	type NormalizedResult,
@@ -68,8 +63,6 @@ import {
 	getShellOutput,
 	usesLocalReadPreview,
 } from "./cursor-transcript-tool-formatters.js";
-import type { CursorReplaySummaryArgs } from "./cursor-replay-summary-args.js";
-
 export interface ToolDisplayContext {
 	rawName: string;
 	name: string;
@@ -102,13 +95,6 @@ function buildCursorActivityDisplayArgs(
 	};
 }
 
-function buildRegistryReplaySummary(
-	sourceToolName: CursorReplayActivityToolName,
-	args: CursorReplaySummaryArgs,
-): string | undefined {
-	return getCursorReplayCallSummary(sourceToolName, args);
-}
-
 function buildReplaySummaryDisplay(
 	toolName: string,
 	args: Record<string, unknown>,
@@ -131,20 +117,16 @@ function buildReplaySummaryDisplay(
 	};
 }
 
-function getCursorToolActivityTitle(toolName: string): string {
-	return getCursorReplayActivityTitle(toolName) ?? buildGenericUnknownToolActivityTitle(toolName);
-}
-
 function buildActivityReplayDisplay(
 	sourceToolName: NeutralActivityReplayToolName,
 	context: ToolDisplayContext,
 ): CursorPiToolDisplay {
-	const spec = TOOL_DISPLAY_SPECS[sourceToolName];
+	const spec = TOOL_DISPLAY_IMPLEMENTATIONS[sourceToolName];
 	const activity = getCursorToolActivityReplaySpec(sourceToolName);
 	if (!activity) throw new Error(`Missing activity replay spec for ${sourceToolName}`);
-	const activityTitle = getCursorReplayActivityTitle(sourceToolName) ?? buildGenericUnknownToolActivityTitle(sourceToolName);
+	const activityTitle = getCursorToolActivityTitle(sourceToolName);
 	const replayArgs = activity.buildActivityArgs(context);
-	const activitySummary = buildRegistryReplaySummary(sourceToolName, replayArgs);
+	const activitySummary = getCursorReplayCallSummary(sourceToolName, replayArgs);
 	const activityArgs = buildCursorActivityDisplayArgs({ ...replayArgs }, activityTitle, activitySummary);
 	const contentText = spec.formatTranscript(context).trimEnd();
 	const activityFields = activity.buildDetails(context, contentText);
@@ -160,12 +142,12 @@ function buildActivityReplayDisplay(
 }
 
 function buildGenerateImageReplayDisplay(context: ToolDisplayContext): CursorPiToolDisplay {
-	const spec = TOOL_DISPLAY_SPECS.generateImage;
+	const spec = TOOL_DISPLAY_IMPLEMENTATIONS.generateImage;
 	const replay = getCursorToolGenerateImageReplaySpec("generateImage");
 	if (!replay) throw new Error("Missing generate image replay spec");
-	const activityTitle = getCursorReplayActivityTitle("generateImage") ?? "Cursor image generation";
+	const activityTitle = getCursorToolActivityTitle("generateImage");
 	const replayArgs = replay.buildActivityArgs(context);
-	const activitySummary = buildRegistryReplaySummary("generateImage", replayArgs);
+	const activitySummary = getCursorReplayCallSummary("generateImage", replayArgs);
 	const activityArgs = buildCursorActivityDisplayArgs({ ...replayArgs }, activityTitle, activitySummary);
 	const contentText = spec.formatTranscript(context).trimEnd();
 	const details = assembleCursorReplayGenerateImageDetails(
@@ -177,15 +159,10 @@ function buildGenerateImageReplayDisplay(context: ToolDisplayContext): CursorPiT
 	return buildReplaySummaryDisplay(CURSOR_REPLAY_ACTIVITY_TOOL_NAME, activityArgs, context.result, contentText, details);
 }
 
-function buildGenericUnknownToolActivityTitle(displayName: string): string {
-	if (displayName === "unknown") return "Cursor tool";
-	return `Cursor ${truncateArg(displayName)}`;
-}
-
 function buildGenericPiToolDisplay(context: ToolDisplayContext): CursorPiToolDisplay {
 	const { rawName, name, args, result, options } = context;
 	const displayName = rawName.trim() || name;
-	const activityTitle = buildGenericUnknownToolActivityTitle(displayName);
+	const activityTitle = getCursorToolActivityTitle(displayName);
 	const contentText = formatFallback(name, args, result, options);
 	const fallbackBody = contentText.includes("\n\n") ? contentText.slice(contentText.indexOf("\n\n") + 2) : "";
 	const activitySummary =
@@ -237,14 +214,15 @@ function buildEditPiToolDisplay(context: ToolDisplayContext): CursorPiToolDispla
 	const activityTitle = getCursorToolActivityTitle("edit");
 	const activityArgs = buildCursorActivityDisplayArgs(baseActivityArgs, activityTitle, displayPath);
 	const contentText = formatEdit(activityArgs, result, options);
-	const details = buildCursorReplayNativeEditDetails({
+	const details: CursorReplayToolDetails = {
+		variant: "nativeEdit",
 		path: displayPath,
 		linesAdded: getNumber(value, "linesAdded"),
 		linesRemoved: getNumber(value, "linesRemoved"),
 		diffString: normalizedDiff,
 		diff: normalizedDiff,
 		firstChangedLine: getNumber(value, "firstChangedLine"),
-	});
+	};
 	if (nativeEditArgs) {
 		return {
 			toolName: "edit",
@@ -284,13 +262,14 @@ function buildWritePiToolDisplay(context: ToolDisplayContext): CursorPiToolDispl
 	const displayArgs = buildWriteDisplayArgs(args, options);
 	const displayPath = typeof args.path === "string" ? formatDisplayPath(args.path, options.cwd) : undefined;
 	const contentText = formatWrite(args, result, options).trimEnd();
-	const details = buildCursorReplayNativeWriteDetails({
+	const details: CursorReplayToolDetails = {
+		variant: "nativeWrite",
 		path: displayPath,
 		linesCreated: getNumber(value, "linesCreated"),
 		fileSize: getNumber(value, "fileSize"),
 		fileContentAfterWrite: getString(value, "fileContentAfterWrite"),
 		expandedText: contentText,
-	});
+	};
 	if (content === undefined) {
 		const activityTitle = getCursorToolActivityTitle("write");
 		return buildReplaySummaryDisplay(
@@ -440,12 +419,8 @@ const TOOL_DISPLAY_IMPLEMENTATIONS: Record<CursorNormalizedToolName, ToolDisplay
 
 export const CURSOR_TOOL_DISPLAY_SPEC_KEYS = CURSOR_KNOWN_NORMALIZED_TOOL_NAMES;
 
-const TOOL_DISPLAY_SPECS = Object.fromEntries(
-	CURSOR_KNOWN_NORMALIZED_TOOL_NAMES.map((name) => [name, TOOL_DISPLAY_IMPLEMENTATIONS[name]]),
-) as Record<CursorNormalizedToolName, ToolDisplaySpec>;
-
 function getToolDisplaySpec(name: string): ToolDisplaySpec | undefined {
-	if (Object.hasOwn(TOOL_DISPLAY_SPECS, name)) return TOOL_DISPLAY_SPECS[name as CursorNormalizedToolName];
+	if (Object.hasOwn(TOOL_DISPLAY_IMPLEMENTATIONS, name)) return TOOL_DISPLAY_IMPLEMENTATIONS[name as CursorNormalizedToolName];
 	return undefined;
 }
 

package/src/cursor-transcript-utils.ts

@@ -1,8 +1,6 @@
 import { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
-import { asRecord, getFirstStringByKeys } from "./cursor-record-utils.js";
-
-export { asRecord, getFirstStringByKeys } from "./cursor-record-utils.js";
+import { asRecord, getArray, getRecord, getString, stringifyUnknown as stringifyUnknownValue } from "./cursor-record-utils.js";
 
 export interface TranscriptOptions {
 	maxChars?: number;
@@ -47,30 +45,6 @@ export function isLocalReadPreviewContent(text: string): boolean {
 	return text.startsWith(LOCAL_READ_PREVIEW_NOTICE);
 }
 
-export function getString(record: Record<string, unknown> | undefined, key: string): string | undefined {
-	const value = record?.[key];
-	return typeof value === "string" ? value : undefined;
-}
-
-export function getNumber(record: Record<string, unknown> | undefined, key: string): number | undefined {
-	const value = record?.[key];
-	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-
-export function getBoolean(record: Record<string, unknown> | undefined, key: string): boolean | undefined {
-	const value = record?.[key];
-	return typeof value === "boolean" ? value : undefined;
-}
-
-export function getRecord(record: Record<string, unknown> | undefined, key: string): Record<string, unknown> | undefined {
-	return asRecord(record?.[key]);
-}
-
-export function getArray(record: Record<string, unknown> | undefined, key: string): unknown[] | undefined {
-	const value = record?.[key];
-	return Array.isArray(value) ? value : undefined;
-}
-
 export function getToolName(toolCall: unknown): string {
 	const record = asRecord(toolCall);
 	return getString(record, "name") ?? getString(record, "type") ?? getString(record, "toolName") ?? "unknown";
@@ -96,13 +70,7 @@ export function normalizeResult(result: unknown): NormalizedResult {
 }
 
 export function stringifyUnknown(value: unknown): string {
-	if (value === undefined) return "";
-	if (typeof value === "string") return value;
-	try {
-		return JSON.stringify(value, null, 2) ?? String(value);
-	} catch {
-		return String(value);
-	}
+	return stringifyUnknownValue(value, { pretty: true });
 }
 
 export function limitText(text: string, options: TranscriptOptions = {}, knownTotalLines?: number): string {

package/src/cursor-usage-accounting.ts

@@ -3,9 +3,7 @@ import {
 	CURSOR_APPROX_CHARS_PER_TOKEN,
 	CURSOR_IMAGE_TOKEN_ESTIMATE,
 	estimateCursorContextTokens,
-	estimateCursorPromptTokens,
 	estimateCursorTextTokens,
-	type CursorPrompt,
 	type CursorPromptOptions,
 } from "./context.js";
 
@@ -28,10 +26,6 @@ export function getCursorPromptOptions(model: Model<Api>): CursorUsagePromptOpti
 	};
 }
 
-export function estimateCursorPromptInputTokens(prompt: CursorPrompt, options: Pick<CursorPromptOptions, "charsPerToken" | "imageTokenEstimate">): number {
-	return estimateCursorPromptTokens(prompt, options);
-}
-
 function stringifyUsageValue(value: unknown): string {
 	try {
 		return JSON.stringify(value) ?? "";

package/src/cursor-web-tool-activity.ts

@@ -1,23 +1,15 @@
+import { getFirstStringByKeys } from "./cursor-record-utils.js";
 import {
-	classifyCursorWebToolKind as classifyCursorWebToolKindFromRegistry,
-	type CursorWebToolKind,
+	classifyCursorWebToolKind,
+	normalizeCursorToolName as normalizeToolName,
 } from "./cursor-tool-presentation-registry.js";
-import { normalizeCursorToolName as normalizeToolName } from "./cursor-tool-presentation-registry.js";
-import { extractWebFetchTarget, extractWebSearchQuery } from "./cursor-web-tool-args.js";
-
-export type { CursorWebToolKind } from "./cursor-tool-presentation-registry.js";
-export { extractWebFetchTarget, extractWebSearchQuery } from "./cursor-web-tool-args.js";
 
 function getMcpToolName(args: Record<string, unknown>): string | undefined {
-	const toolName = typeof args.toolName === "string" ? args.toolName : typeof args.tool_name === "string" ? args.tool_name : undefined;
+	const toolName = getFirstStringByKeys(args, ["toolName", "tool_name"]);
 	const trimmed = toolName?.trim();
 	return trimmed || undefined;
 }
 
-export function classifyCursorWebToolKind(name: string | undefined): CursorWebToolKind | undefined {
-	return classifyCursorWebToolKindFromRegistry(name);
-}
-
 /**
  * Maps SDK/host/MCP tool names to transcript display keys.
  * Web search/fetch often arrives as MCP `toolName` values, not dedicated SDK ToolTypes.

package/src/cursor-web-tool-args.ts

@@ -1,17 +1,9 @@
-import { asRecord } from "./cursor-record-utils.js";
+import { asRecord, firstNonEmptyString } from "./cursor-record-utils.js";
 
 function getNestedMcpArgs(args: Record<string, unknown>): Record<string, unknown> {
 	return asRecord(args.args) ?? {};
 }
 
-function firstNonEmptyString(...values: Array<string | undefined>): string | undefined {
-	for (const value of values) {
-		const trimmed = value?.trim();
-		if (trimmed) return trimmed;
-	}
-	return undefined;
-}
-
 export function extractWebSearchQuery(args: Record<string, unknown>): string | undefined {
 	const nested = getNestedMcpArgs(args);
 	return firstNonEmptyString(

package/src/index.ts

@@ -1,26 +1,27 @@
-import type { ExtensionAPI, ExtensionContext, ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import { discoverModels, type CursorModelFallbackIssue } from "./model-discovery.js";
 import { registerCursorRuntimeControls } from "./cursor-state.js";
-import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display.js";
+import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display-registration.js";
 import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { registerCursorQuestionTool } from "./cursor-question-tool.js";
 import { registerCursorSkillTool } from "./cursor-skill-tool.js";
-import { registerCursorSessionCwd } from "./cursor-session-cwd.js";
-import { registerCursorAgentsContextDedup } from "./cursor-agents-context.js";
-import { registerCursorSessionAgent } from "./cursor-session-agent.js";
-import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
-import { streamCursor } from "./cursor-provider.js";
+import { registerCursorSessionScope } from "./cursor-session-scope.js";
+import { registerCursorSessionAgentLifecycle } from "./cursor-session-agent-lifecycle.js";
+import { streamCursorLazy } from "./cursor-provider-lazy.js";
 import { CURSOR_API_KEY_CONFIG_VALUE } from "./cursor-api-key.js";
+import { registerCursorFallbackIssueWarning } from "./cursor-fallback-warning.js";
+import { registerCursorAgentsContextDedup } from "./cursor-agents-context-registration.js";
 
 type CursorExtensionApi =
 	& Pick<ExtensionAPI, "registerProvider" | "registerCommand" | "on">
-	& Parameters<typeof registerCursorSessionCwd>[0]
-	& Parameters<typeof registerCursorSessionAgent>[0]
+	& Parameters<typeof registerCursorSessionScope>[0]
+	& Parameters<typeof registerCursorSessionAgentLifecycle>[0]
 	& Parameters<typeof registerCursorRuntimeControls>[0]
 	& Parameters<typeof registerCursorNativeToolDisplay>[0]
 	& Parameters<typeof registerCursorQuestionTool>[0]
 	& Parameters<typeof registerCursorSkillTool>[0]
 	& Parameters<typeof registerCursorPiToolBridge>[0]
+	& Parameters<typeof registerCursorFallbackIssueWarning>[0]
 	& Parameters<typeof registerCursorAgentsContextDedup>[0];
 
 function createCursorProviderConfig(models: ProviderModelConfig[]): ProviderConfig {
@@ -30,7 +31,7 @@ function createCursorProviderConfig(models: ProviderModelConfig[]): ProviderConf
 		apiKey: CURSOR_API_KEY_CONFIG_VALUE,
 		api: "cursor-sdk",
 		models,
-		streamSimple: streamCursor,
+		streamSimple: streamCursorLazy,
 	};
 }
 
@@ -40,9 +41,10 @@ function registerCursorProvider(pi: Pick<ExtensionAPI, "registerProvider">, mode
 
 export default async function (pi: CursorExtensionApi) {
 	// Session cwd must register before other session_start listeners that depend on it.
-	registerCursorSessionCwd(pi);
-	registerCursorSessionAgent(pi);
+	registerCursorSessionScope(pi);
+	registerCursorSessionAgentLifecycle(pi);
 	pi.on("session_before_compact", async () => {
+		const { prepareCursorSessionForCompaction } = await import("./cursor-session-compaction-prep.js");
 		await prepareCursorSessionForCompaction();
 	});
 	registerCursorRuntimeControls(pi);
@@ -59,10 +61,7 @@ export default async function (pi: CursorExtensionApi) {
 	});
 
 	if (fallbackIssue) {
-		const issue = fallbackIssue;
-		pi.on("session_start", async (_event, ctx) => {
-			if (ctx.hasUI) ctx.ui.notify(issue.message, "warning");
-		});
+		registerCursorFallbackIssueWarning(pi, fallbackIssue);
 	}
 
 	pi.registerCommand("cursor-refresh-models", {

package/src/model-discovery.ts

@@ -4,12 +4,11 @@ import type {
 	ModelParameterValue,
 	ModelSelection,
 } from "@cursor/sdk";
-import { AuthStorage, type ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import type { ModelThinkingLevel, ThinkingLevelMap } from "@earendil-works/pi-ai";
 import { loadContextWindowCache } from "./context-window-cache.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
-import { CURSOR_API_KEY_ENV_VAR, resolveCursorApiKey } from "./cursor-api-key.js";
-import { FALLBACK_MODEL_ITEMS } from "./cursor-fallback-models.generated.js";
+import { resolveCursorApiKey } from "./cursor-api-key.js";
 import {
 	fingerprintApiKey,
 	loadAnyCachedModelCatalog,
@@ -62,6 +61,7 @@ function getCliApiKeyFromArgv(argv: string[] = process.argv): string | undefined
 
 async function getStoredCursorApiKey(): Promise<string | undefined> {
 	try {
+		const { AuthStorage } = await import("@earendil-works/pi-coding-agent");
 		return resolveCursorApiKey(await AuthStorage.create().getApiKey(CURSOR_PROVIDER_ID, { includeFallback: false }));
 	} catch {
 		return undefined;
@@ -462,8 +462,9 @@ function sanitizeDiscoveryError(error: unknown, apiKey: string): string | undefi
 	return scrubbed || undefined;
 }
 
-function useFallbackModels(options: DiscoverModelsOptions, issue: CursorModelFallbackIssue): ProviderModelConfig[] {
+async function useFallbackModels(options: DiscoverModelsOptions, issue: CursorModelFallbackIssue): Promise<ProviderModelConfig[]> {
 	options.onFallback?.(issue);
+	const { FALLBACK_MODEL_ITEMS } = await import("./cursor-fallback-models.generated.js");
 	return registerModelItems(FALLBACK_MODEL_ITEMS);
 }