pi-cursor-sdk 0.1.17 → 0.1.19

package/src/cursor-session-agent.ts

@@ -16,10 +16,12 @@ import {
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
 import { getCursorSessionScopeKey, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export interface SessionCursorAgentSendState {
 	bootstrapped: boolean;
 	contextFingerprint: string;
+	incrementalSendCount: number;
 }
 
 export interface SessionCursorAgentLease {
@@ -74,6 +76,7 @@ interface SessionCursorAgentCreateParams {
 	modelSelection: ModelSelection;
 	settingSources?: SettingSource[];
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	debugRecorder?: CursorSdkEventDebugRecorder;
 	createAgent?: typeof Agent.create;
 }
 
@@ -150,13 +153,19 @@ async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?:
 	const entry = sessionAgentsByScope.get(scopeKey);
 	invalidatedScopeKeys.delete(scopeKey);
 	if (!entry) return;
+	const orphanedCreating = entry.creating;
 	sessionAgentsByScope.delete(scopeKey);
-	if (entry.creating || !entry.agent) return;
+	if (entry.creating || !entry.agent) {
+		orphanedCreating?.catch(() => {
+			// In-flight Agent.create was orphaned by scope disposal; active waiters surface errors elsewhere.
+		});
+		return;
+	}
 	await disposePoolEntry(entry);
 }
 
 function createInitialSendState(): SessionCursorAgentSendState {
-	return { bootstrapped: false, contextFingerprint: "" };
+	return { bootstrapped: false, contextFingerprint: "", incrementalSendCount: 0 };
 }
 
 function bindBridgeToolRequest(
@@ -173,6 +182,7 @@ function leaseFromEntry(
 	created: boolean,
 ): SessionCursorAgentLease {
 	bindBridgeToolRequest(entry, params.onBridgeToolRequest);
+	entry.bridgeRun?.setDebugRecorder(params.debugRecorder);
 	return {
 		scopeKey,
 		agent: entry.agent!,
@@ -192,6 +202,7 @@ async function createSessionAgentEntry(
 	if (registeredBridge) {
 		bridgeRun = await registeredBridge.createRun({
 			onToolRequest: params.onBridgeToolRequest,
+			debugRecorder: params.debugRecorder,
 		});
 		if (!bridgeRun.enabled || !bridgeRun.mcpServers) {
 			await bridgeRun.dispose();
@@ -230,13 +241,24 @@ async function createSessionAgentEntry(
 	};
 }
 
-export { shouldBootstrapCursorSend } from "./context.js";
+export {
+	buildCursorSessionSendPrompt,
+	MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP,
+	planCursorSessionSend,
+	type CursorSessionSendPlan,
+} from "./cursor-session-send-policy.js";
+export { shouldBootstrapCursorContext, shouldBootstrapCursorSend } from "./context.js";
 
 export function commitSessionAgentSend(scopeKey: string, context: Context, bootstrapped: boolean): void {
 	const entry = sessionAgentsByScope.get(scopeKey);
 	if (!entry) return;
 	entry.sendState.bootstrapped = bootstrapped || entry.sendState.bootstrapped;
 	entry.sendState.contextFingerprint = computeCursorContextFingerprint(context);
+	if (bootstrapped) {
+		entry.sendState.incrementalSendCount = 0;
+		return;
+	}
+	entry.sendState.incrementalSendCount += 1;
 }
 
 export function invalidateSessionAgent(scopeKey: string = getCursorSessionScopeKey()): void {

package/src/cursor-session-send-policy.ts

@@ -0,0 +1,43 @@
+import type { Context } from "@earendil-works/pi-ai";
+import {
+	buildCursorIncrementalPrompt,
+	buildCursorPrompt,
+	shouldBootstrapCursorContext,
+	type CursorPrompt,
+	type CursorPromptOptions,
+} from "./context.js";
+import type { SessionCursorAgentSendState } from "./cursor-session-agent.js";
+
+// Long-lived SDK session agents can drift tool-call behavior; recreate the agent after this many successful incremental sends.
+export const MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP = 20;
+
+export type CursorSessionSendMode = "bootstrap" | "incremental";
+
+export type CursorSessionSendReason = "initial" | "context_divergence" | "incremental_threshold" | "incremental";
+
+export interface CursorSessionSendPlan {
+	mode: CursorSessionSendMode;
+	resetAgent: boolean;
+	reason: CursorSessionSendReason;
+}
+
+export function planCursorSessionSend(sendState: SessionCursorAgentSendState, context: Context): CursorSessionSendPlan {
+	if (!sendState.bootstrapped) {
+		return { mode: "bootstrap", resetAgent: false, reason: "initial" };
+	}
+	if (sendState.incrementalSendCount >= MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP) {
+		return { mode: "bootstrap", resetAgent: true, reason: "incremental_threshold" };
+	}
+	if (shouldBootstrapCursorContext(sendState, context)) {
+		return { mode: "bootstrap", resetAgent: true, reason: "context_divergence" };
+	}
+	return { mode: "incremental", resetAgent: false, reason: "incremental" };
+}
+
+export function buildCursorSessionSendPrompt(
+	context: Context,
+	options: CursorPromptOptions,
+	plan: CursorSessionSendPlan,
+): CursorPrompt {
+	return plan.mode === "bootstrap" ? buildCursorPrompt(context, options) : buildCursorIncrementalPrompt(context, options);
+}

package/src/cursor-setting-sources.ts

@@ -0,0 +1,29 @@
+import type { SettingSource } from "@cursor/sdk";
+
+export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+
+export function resolveCursorSettingSources(raw?: string): SettingSource[] | undefined {
+	const trimmed = raw?.trim();
+	if (!trimmed) return ["all"];
+	const normalized = trimmed.toLowerCase();
+	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
+	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
+	return trimmed
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter((entry): entry is SettingSource => Boolean(entry));
+}
+
+export function getEffectiveCursorSettingSources(raw: string | undefined = process.env[CURSOR_SETTING_SOURCES_ENV]): SettingSource[] | undefined {
+	return resolveCursorSettingSources(raw);
+}
+
+export function cursorSettingSourcesLoadUserAgentsRules(settingSources: SettingSource[] | undefined): boolean {
+	if (!settingSources?.length) return false;
+	return settingSources.includes("all") || settingSources.includes("user");
+}
+
+export function cursorSettingSourcesLoadProjectAgentsRules(settingSources: SettingSource[] | undefined): boolean {
+	if (!settingSources?.length) return false;
+	return settingSources.includes("all") || settingSources.includes("project");
+}

package/src/cursor-state.ts

@@ -2,9 +2,9 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext, SessionStartEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isCursorModel } from "./cursor-model.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
 
-const CURSOR_PROVIDER = "cursor";
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const GLOBAL_CONFIG_FILE = "cursor-sdk.json";
 
@@ -94,10 +94,6 @@ function getEffectiveFast(baseModelId: string, modelId: string): boolean | undef
 	return sessionFastPreferences.get(baseModelId) ?? globalFastPreferences.get(baseModelId) ?? metadata.defaultFast;
 }
 
-function isCursorModel(model: CursorFastControlsModel): boolean {
-	return model?.provider === CURSOR_PROVIDER || model?.api === "cursor-sdk";
-}
-
 function updateCursorStatus(ctx: { model: CursorFastControlsModel; ui: Pick<ExtensionContext["ui"], "setStatus"> }, model = ctx.model): void {
 	if (!model || !isCursorModel(model)) {
 		ctx.ui.setStatus("cursor", undefined);

package/src/cursor-tool-lifecycle.ts

@@ -0,0 +1,111 @@
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { getCursorReplayDisplayLabel, type CursorReplayLegacyToolName } from "./cursor-tool-names.js";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+import { extractWebSearchQuery, resolveTranscriptToolName } from "./cursor-web-tool-activity.js";
+import { firstNonEmptyLine, getArray, getString, getToolArgs, getToolName, normalizeToolName, truncateArg } from "./cursor-transcript-utils.js";
+
+/** Defer pending lifecycle lines so fast start+complete pairs coalesce into the completed replay card only. */
+export const CURSOR_TOOL_LIFECYCLE_DEFER_MS = 75;
+
+const LIFECYCLE_ELIGIBLE_TOOLS = new Set(
+	["task", "shell", "mcp", "generateImage", "recordScreen", "semSearch", "webSearch", "webFetch", "createPlan", "updateTodos"].map(
+		(name) => name.toLowerCase(),
+	),
+);
+
+const LIFECYCLE_TITLE_KEYS: Partial<Record<string, CursorReplayLegacyToolName>> = {
+	task: "cursor_task",
+	mcp: "cursor_mcp",
+	generateimage: "cursor_generate_image",
+	recordscreen: "cursor_record_screen",
+	semsearch: "cursor_sem_search",
+	websearch: "cursor_web_search",
+	webfetch: "cursor_web_fetch",
+	createplan: "cursor_create_plan",
+	updatetodos: "cursor_update_todos",
+};
+
+export function isCursorToolLifecycleEligible(toolCall: unknown): boolean {
+	const args = getToolArgs(toolCall);
+	const name = resolveTranscriptToolName(getToolName(toolCall), args);
+	return LIFECYCLE_ELIGIBLE_TOOLS.has(normalizeToolName(name).toLowerCase());
+}
+
+function getCursorToolLifecycleTitle(toolCall: unknown): string {
+	const args = getToolArgs(toolCall);
+	const name = resolveTranscriptToolName(getToolName(toolCall), args);
+	const normalized = normalizeToolName(name).toLowerCase();
+	const labelKey = LIFECYCLE_TITLE_KEYS[normalized];
+	if (labelKey) return getCursorReplayDisplayLabel(labelKey);
+	if (normalized === "shell") return "Cursor shell";
+	return `Cursor ${normalizeToolName(name)}`;
+}
+
+/** Prefixes that commonly introduce path/URI values in free-text pending lifecycle details. */
+const LIFECYCLE_DETAIL_PATH_PREFIX = String.raw`(?:^|[\s'"({=,:;\[\]{}])`;
+
+function containsCursorLifecycleUnsafeDetail(text: string): boolean {
+	if (/\b[a-z][a-z0-9+.-]*:\/\//i.test(text)) return true;
+	if (/\bwww\.\S+/i.test(text)) return true;
+	if (new RegExp(`${LIFECYCLE_DETAIL_PATH_PREFIX}~\\/\\S*`).test(text)) return true;
+	if (new RegExp(`${LIFECYCLE_DETAIL_PATH_PREFIX}\\/\\S+`).test(text)) return true;
+	if (new RegExp(`${LIFECYCLE_DETAIL_PATH_PREFIX}[A-Za-z]:[\\\\/]`).test(text)) return true;
+	return false;
+}
+
+function scrubLifecycleDetail(value: string | undefined, apiKey?: string): string | undefined {
+	if (!value?.trim()) return undefined;
+	const scrubbed = truncateCursorDisplayLine(scrubSensitiveText(value, apiKey));
+	if (containsCursorLifecycleUnsafeDetail(scrubbed)) return undefined;
+	return scrubbed;
+}
+
+export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
+	const args = getToolArgs(toolCall);
+	const name = resolveTranscriptToolName(getToolName(toolCall), args);
+	const normalized = normalizeToolName(name).toLowerCase();
+
+	switch (normalized) {
+		case "task": {
+			return scrubLifecycleDetail(getString(args, "description"), apiKey) ?? "task";
+		}
+		case "shell": {
+			return "shell";
+		}
+		case "mcp": {
+			return scrubLifecycleDetail(getString(args, "toolName"), apiKey) ?? "mcp";
+		}
+		case "generateimage": {
+			return scrubLifecycleDetail(getString(args, "prompt") ?? getString(args, "description"), apiKey) ?? "image generation";
+		}
+		case "recordscreen": {
+			return scrubLifecycleDetail(getString(args, "mode"), apiKey) ?? "screen recording";
+		}
+		case "semsearch": {
+			return scrubLifecycleDetail(getString(args, "query"), apiKey) ?? "semantic search";
+		}
+		case "websearch": {
+			return scrubLifecycleDetail(extractWebSearchQuery(args), apiKey) ?? "web search";
+		}
+		case "webfetch": {
+			return "web fetch";
+		}
+		case "createplan": {
+			const plan = getString(args, "plan");
+			return scrubLifecycleDetail(plan ? firstNonEmptyLine(plan) ?? plan : undefined, apiKey) ?? "plan";
+		}
+		case "updatetodos": {
+			const todos = getArray(args, "todos") ?? getArray(args, "items");
+			if (todos && todos.length > 0) return truncateArg(`${todos.length} item${todos.length === 1 ? "" : "s"}`);
+			return "todos";
+		}
+		default:
+			return undefined;
+	}
+}
+
+export function formatCursorToolLifecycleProgressText(toolCall: unknown, apiKey?: string): string | undefined {
+	const label = buildCursorToolLifecycleLabel(toolCall, apiKey);
+	if (!label) return undefined;
+	return `${getCursorToolLifecycleTitle(toolCall)}: ${label}\n`;
+}

package/src/cursor-tool-names.ts

@@ -10,6 +10,10 @@ export const CURSOR_REPLAY_LEGACY_TOOL_NAMES = [
 	"cursor_create_plan",
 	"cursor_generate_image",
 	"cursor_mcp",
+	"cursor_sem_search",
+	"cursor_record_screen",
+	"cursor_web_search",
+	"cursor_web_fetch",
 ] as const;
 
 export type CursorReplayLegacyToolName = (typeof CURSOR_REPLAY_LEGACY_TOOL_NAMES)[number];
@@ -25,6 +29,10 @@ const CURSOR_REPLAY_SOURCE_TOOL_NAMES = {
 	cursor_create_plan: "createPlan",
 	cursor_generate_image: "generateImage",
 	cursor_mcp: "MCP",
+	cursor_sem_search: "semSearch",
+	cursor_record_screen: "recordScreen",
+	cursor_web_search: "web search",
+	cursor_web_fetch: "web fetch",
 } as const satisfies Record<CursorReplayLegacyToolName, string>;
 
 const CURSOR_REPLAY_PROMPT_LABELS = {
@@ -37,6 +45,10 @@ const CURSOR_REPLAY_PROMPT_LABELS = {
 	cursor_create_plan: "Cursor plan",
 	cursor_generate_image: "Cursor image generation",
 	cursor_mcp: "Cursor MCP",
+	cursor_sem_search: "Cursor semantic search",
+	cursor_record_screen: "Cursor screen recording",
+	cursor_web_search: "Cursor web search",
+	cursor_web_fetch: "Cursor web fetch",
 } as const satisfies Record<CursorReplayLegacyToolName, string>;
 
 export function isCursorReplayLegacyToolName(toolName: string): toolName is CursorReplayLegacyToolName {

package/src/cursor-tool-transcript.ts

@@ -14,6 +14,7 @@ import {
 	formatCursorToolTranscriptFromSpec,
 	type ToolDisplayContext,
 } from "./cursor-transcript-tool-specs.js";
+import { resolveTranscriptToolName } from "./cursor-web-tool-activity.js";
 
 export type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 
@@ -29,10 +30,11 @@ export function getCursorCreatePlanText(toolCall: unknown): string | undefined {
 
 function buildToolDisplayContext(toolCall: unknown, options: TranscriptOptions): ToolDisplayContext {
 	const rawName = getToolName(toolCall);
+	const args = getToolArgs(toolCall);
 	return {
 		rawName,
-		name: normalizeToolName(rawName),
-		args: getToolArgs(toolCall),
+		name: resolveTranscriptToolName(rawName, args),
+		args,
 		result: normalizeResult(getToolResult(toolCall)),
 		options,
 	};

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

@@ -1,4 +1,6 @@
 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 {
 	asRecord,
@@ -27,6 +29,21 @@ import {
 	type TranscriptOptions,
 } from "./cursor-transcript-utils.js";
 
+export function usesLocalReadPreview(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): boolean {
+	if (result.status === "error") return false;
+	const value = asRecord(result.value);
+	const resultContent = getString(value, "content");
+	if (resultContent && resultContent.length > 0) return false;
+	const rawPath = typeof args.path === "string" ? args.path : undefined;
+	if (!rawPath) return false;
+	const readOptions = {
+		...options,
+		maxChars: options.maxChars ?? DEFAULT_READ_TRANSCRIPT_CHARS,
+		maxLines: options.maxLines ?? DEFAULT_READ_TRANSCRIPT_LINES,
+	};
+	return readFilePreview(rawPath, readOptions) !== undefined;
+}
+
 function getReadContent(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const rawPath = typeof args.path === "string" ? args.path : undefined;
 	const readOptions = {
@@ -57,9 +74,17 @@ export function formatRead(args: Record<string, unknown>, result: NormalizedResu
 	return joinSections(`read ${path}`, limitText(getReadContent(args, result, options), readOptions, totalLines));
 }
 
-export function buildReadDisplayArgs(args: Record<string, unknown>, options: TranscriptOptions): Record<string, unknown> {
+export function buildReadDisplayArgs(
+	args: Record<string, unknown>,
+	options: TranscriptOptions,
+	result?: NormalizedResult,
+): Record<string, unknown> {
 	const rawPath = typeof args.path === "string" ? args.path : undefined;
-	return rawPath ? { ...args, path: formatDisplayPath(rawPath, options.cwd) } : args;
+	const displayArgs = rawPath ? { ...args, path: formatDisplayPath(rawPath, options.cwd) } : args;
+	if (result && usesLocalReadPreview(args, result, options)) {
+		return { ...displayArgs, localReadPreview: true };
+	}
+	return displayArgs;
 }
 
 function buildPathDisplayArgs(args: Record<string, unknown>, options: TranscriptOptions): Record<string, unknown> {
@@ -617,6 +642,153 @@ function describeNonTextMcpContent(entry: unknown): string {
 	return `[${type} omitted]`;
 }
 
+export function summarizeSemSearch(args: Record<string, unknown>): string {
+	const query = getString(args, "query") ?? "semantic search";
+	const targetDirectories = getArray(args, "targetDirectories");
+	const dirHint =
+		targetDirectories && targetDirectories.length > 0
+			? ` (${targetDirectories.length} dir${targetDirectories.length === 1 ? "" : "s"})`
+			: "";
+	return truncateArg(`${query}${dirHint}`);
+}
+
+export function formatSemSearch(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
+	const query = getString(args, "query") ?? "semantic search";
+	const header = `semSearch ${truncateArg(query)}`;
+	if (result.status === "error") return joinSections(header, formatError(result.error));
+
+	const value = asRecord(result.value);
+	const results = getString(value, "results");
+	const targetDirectories = getArray(args, "targetDirectories");
+	const explanation = getString(args, "explanation");
+	const lines: string[] = [];
+	if (explanation?.trim()) lines.push(`Explanation: ${explanation.trim()}`);
+	if (targetDirectories && targetDirectories.length > 0) {
+		const dirs = targetDirectories
+			.map((entry) => (typeof entry === "string" ? entry : stringifyUnknown(entry)))
+			.join(", ");
+		lines.push(`Scope: ${dirs}`);
+	}
+	if (results?.trim()) lines.push(results.trim());
+	const body = lines.length > 0 ? lines.join("\n\n") : stringifyUnknown(result.value);
+	return joinSections(header, limitText(body, options));
+}
+
+function formatRecordScreenMode(mode: string | undefined): string {
+	switch (mode) {
+		case "START_RECORDING":
+			return "start recording";
+		case "SAVE_RECORDING":
+			return "save recording";
+		case "DISCARD_RECORDING":
+			return "discard recording";
+		default:
+			return mode ?? "record screen";
+	}
+}
+
+function formatRecordingDurationMs(ms: number | undefined): string | undefined {
+	if (ms === undefined || !Number.isFinite(ms) || ms < 0) return undefined;
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const seconds = ms / 1000;
+	return seconds < 60 ? `${seconds.toFixed(1)}s` : `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
+}
+
+export function summarizeRecordScreen(
+	args: Record<string, unknown>,
+	result: NormalizedResult,
+	options: TranscriptOptions,
+): string {
+	const mode = getString(args, "mode");
+	if (result.status === "error") return formatRecordScreenMode(mode);
+	const value = asRecord(result.value);
+	const path = getString(value, "path");
+	const displayPath = path ? formatDisplayPath(path, options.cwd) : undefined;
+	const duration = formatRecordingDurationMs(getNumber(value, "recordingDurationMs"));
+	const modeLabel = formatRecordScreenMode(mode);
+	if (displayPath && duration) return `${displayPath} · ${duration}`;
+	if (displayPath) return displayPath;
+	if (duration) return `${modeLabel} · ${duration}`;
+	return modeLabel;
+}
+
+export function formatRecordScreen(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
+	const mode = getString(args, "mode");
+	const header = `recordScreen ${formatRecordScreenMode(mode)}`;
+	if (result.status === "error") return joinSections(header, formatError(result.error));
+
+	const value = asRecord(result.value);
+	const path = getString(value, "path");
+	const displayPath = path ? formatDisplayPath(path, options.cwd) : undefined;
+	const duration = formatRecordingDurationMs(getNumber(value, "recordingDurationMs"));
+	const wasCancelled = getBoolean(value, "wasPriorRecordingCancelled");
+	const lines: string[] = [];
+	if (displayPath) lines.push(`Recording: ${displayPath}`);
+	if (duration) lines.push(`Duration: ${duration}`);
+	if (wasCancelled === true) lines.push("Prior recording cancelled.");
+	if (lines.length === 0) {
+		if (mode === "START_RECORDING") lines.push("Recording started.");
+		else if (mode === "DISCARD_RECORDING") lines.push("Recording discarded.");
+		else lines.push("Screen recording updated.");
+	}
+	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;
+}
+
+export function summarizeMcp(args: Record<string, unknown>, result: NormalizedResult): string {
+	const toolName = truncateArg(getString(args, "toolName") ?? "mcp");
+	const preview = getMcpResultPreview(result);
+	return preview && preview !== toolName ? `${toolName} · ${preview}` : toolName;
+}
+
+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));
+}
+
+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);
+}
+
+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);
+}
+
 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));
@@ -633,9 +805,60 @@ export function formatMcp(args: Record<string, unknown>, result: NormalizedResul
 	return joinSections(toolName, limitText(body, options));
 }
 
+const UNKNOWN_TOOL_FALLBACK_MAX_ARGS = 8;
+const UNKNOWN_TOOL_FALLBACK_MAX_CHARS = 240;
+const UNKNOWN_TOOL_FALLBACK_MAX_LINES = 6;
+
+function summarizeUnknownToolArgValue(value: unknown): string {
+	if (typeof value === "string") return truncateArg(value);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) {
+		const preview = value.slice(0, 3).map((entry) => summarizeUnknownToolArgValue(entry)).join(", ");
+		const omitted = value.length - Math.min(value.length, 3);
+		return omitted > 0 ? `[${preview}, +${omitted} more]` : `[${preview}]`;
+	}
+	return truncateArg(stringifyUnknown(value).replace(/\s+/g, " "));
+}
+
+function summarizeUnknownToolArgs(args: Record<string, unknown>): string {
+	const entries = Object.entries(args).slice(0, UNKNOWN_TOOL_FALLBACK_MAX_ARGS);
+	if (entries.length === 0) return "";
+	const parts = entries.map(([key, value]) => `${key}=${summarizeUnknownToolArgValue(value)}`);
+	const omitted = Object.keys(args).length - entries.length;
+	const body = parts.join(", ");
+	return omitted > 0 ? `${body} (+${omitted} more)` : body;
+}
+
+function summarizeUnknownToolResult(value: unknown, options: TranscriptOptions): string {
+	const text = stringifyUnknown(value).trim();
+	if (!text) return "";
+	return limitText(text.replace(/\s+/g, " "), {
+		...options,
+		maxChars: options.maxChars ?? UNKNOWN_TOOL_FALLBACK_MAX_CHARS,
+		maxLines: options.maxLines ?? UNKNOWN_TOOL_FALLBACK_MAX_LINES,
+	});
+}
+
+function summarizeUnknownToolError(error: unknown, options: TranscriptOptions): string {
+	const text = formatError(error).trim();
+	if (!text) return "Error";
+	return limitText(text, {
+		...options,
+		maxChars: options.maxChars ?? UNKNOWN_TOOL_FALLBACK_MAX_CHARS,
+		maxLines: options.maxLines ?? UNKNOWN_TOOL_FALLBACK_MAX_LINES,
+	});
+}
+
 export function formatFallback(name: string, args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
 	const header = name === "unknown" ? "Cursor tool" : name;
-	if (result.status === "error") return joinSections(header, formatError(result.error));
-	const argsText = Object.keys(args).length > 0 ? `${stringifyUnknown(args)}\n\n` : "";
-	return joinSections(header, limitText(`${argsText}${stringifyUnknown(result.value)}`.trim(), options));
+	if (result.status === "error") {
+		const argsSummary = summarizeUnknownToolArgs(args);
+		const errorSummary = summarizeUnknownToolError(result.error, options);
+		const body = [argsSummary, errorSummary].filter(Boolean).join("\n\n");
+		return joinSections(header, body ? limitText(body, options) : undefined);
+	}
+	const argsSummary = summarizeUnknownToolArgs(args);
+	const resultSummary = summarizeUnknownToolResult(result.value, options);
+	const body = [argsSummary, resultSummary].filter(Boolean).join("\n\n");
+	return joinSections(header, body ? limitText(body, options) : undefined);
 }