pi-cursor-sdk 0.1.62 → 0.3.6

package/dist/cursor-transcript-tool-specs.js

@@ -0,0 +1,284 @@
+import { CURSOR_KNOWN_NORMALIZED_TOOL_NAMES, CURSOR_REPLAY_ACTIVITY_TOOL_NAME, getCursorReplayCallSummary, getCursorToolActivityTitle, getCursorToolActivityReplaySpec, getCursorToolGenerateImageReplaySpec, } from "./cursor-tool-presentation-registry.js";
+import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
+import { assembleCursorReplayActivityDetails, assembleCursorReplayGenerateImageDetails, CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME, } from "./cursor-replay-tool-details.js";
+import { asRecord, getNumber, getString } from "./cursor-record-utils.js";
+import { firstNonEmptyLine, formatDisplayPath, formatDiffString, formatError, limitText, truncateArg, } from "./cursor-transcript-utils.js";
+import { buildCursorEditActivityDisplayArgs, buildFindDisplayArgs, buildGrepDisplayArgs, buildNativeEditDisplayArgs, buildReadDisplayArgs, buildShellDisplayArgs, buildWriteDisplayArgs, formatDelete, formatEdit, formatFallback, formatGenerateImage, formatGlob, formatGrep, formatLs, formatMcp, formatWebFetch, formatWebSearch, formatPlan, formatRecordScreen, formatSemSearch, formatRead, formatReadLints, formatShell, formatTask, formatTodos, formatWrite, formatNativeReadDisplayContent, getCursorWriteArgContent, getGlobBody, getGrepBody, getLsBody, getShellOutput, usesLocalReadPreview, } from "./cursor-transcript-tool-formatters.js";
+function textToolResult(text, details) {
+    return { content: [{ type: "text", text }], details };
+}
+function buildCursorActivityDisplayArgs(args, activityTitle, activitySummary) {
+    const trimmedSummary = activitySummary?.trim();
+    return {
+        ...args,
+        activityTitle,
+        ...(trimmedSummary ? { activitySummary: trimmedSummary } : {}),
+    };
+}
+function buildReplaySummaryDisplay(toolName, args, result, contentText, details) {
+    const isError = result.status === "error";
+    const expandedText = details.expandedText ?? contentText;
+    const summary = details.summary;
+    return {
+        toolName,
+        args,
+        result: textToolResult(contentText, {
+            ...details,
+            summary,
+            expandedText,
+        }),
+        isError,
+    };
+}
+function buildActivityReplayDisplay(sourceToolName, context) {
+    const spec = TOOL_DISPLAY_IMPLEMENTATIONS[sourceToolName];
+    const activity = getCursorToolActivityReplaySpec(sourceToolName);
+    if (!activity)
+        throw new Error(`Missing activity replay spec for ${sourceToolName}`);
+    const activityTitle = getCursorToolActivityTitle(sourceToolName);
+    const replayArgs = activity.buildActivityArgs(context);
+    const activitySummary = getCursorReplayCallSummary(sourceToolName, replayArgs);
+    const activityArgs = buildCursorActivityDisplayArgs({ ...replayArgs }, activityTitle, activitySummary);
+    const contentText = spec.formatTranscript(context).trimEnd();
+    const activityFields = activity.buildDetails(context, contentText);
+    const details = assembleCursorReplayActivityDetails(sourceToolName, activityTitle, activityFields, contentText, context.result.status === "error", activitySummary);
+    return buildReplaySummaryDisplay(CURSOR_REPLAY_ACTIVITY_TOOL_NAME, activityArgs, context.result, contentText, details);
+}
+function buildGenerateImageReplayDisplay(context) {
+    const spec = TOOL_DISPLAY_IMPLEMENTATIONS.generateImage;
+    const replay = getCursorToolGenerateImageReplaySpec("generateImage");
+    if (!replay)
+        throw new Error("Missing generate image replay spec");
+    const activityTitle = getCursorToolActivityTitle("generateImage");
+    const replayArgs = replay.buildActivityArgs(context);
+    const activitySummary = getCursorReplayCallSummary("generateImage", replayArgs);
+    const activityArgs = buildCursorActivityDisplayArgs({ ...replayArgs }, activityTitle, activitySummary);
+    const contentText = spec.formatTranscript(context).trimEnd();
+    const details = assembleCursorReplayGenerateImageDetails(replay.buildDetails(context, contentText), contentText, context.result.status === "error", activitySummary);
+    return buildReplaySummaryDisplay(CURSOR_REPLAY_ACTIVITY_TOOL_NAME, activityArgs, context.result, contentText, details);
+}
+function buildGenericPiToolDisplay(context) {
+    const { rawName, name, args, result, options } = context;
+    const displayName = rawName.trim() || name;
+    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 = result.status === "error" ? undefined : firstNonEmptyLine(fallbackBody);
+    const activityArgs = buildCursorActivityDisplayArgs({}, activityTitle, activitySummary);
+    const summary = result.status === "error"
+        ? undefined
+        : activitySummary ?? truncateArg(displayName === "unknown" ? "tool" : displayName);
+    return buildReplaySummaryDisplay(CURSOR_REPLAY_ACTIVITY_TOOL_NAME, activityArgs, result, contentText, assembleCursorReplayActivityDetails(CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME, activityTitle, { summary, expandedText: contentText }, contentText, result.status === "error", activitySummary));
+}
+function buildEditActivitySummary(displayPath, value) {
+    const path = displayPath ?? "replayed";
+    const linesAdded = getNumber(value, "linesAdded");
+    const linesRemoved = getNumber(value, "linesRemoved");
+    const parts = [
+        linesAdded ? `added ${linesAdded} line${linesAdded === 1 ? "" : "s"}` : undefined,
+        linesRemoved ? `removed ${linesRemoved} line${linesRemoved === 1 ? "" : "s"}` : undefined,
+    ].filter((part) => Boolean(part));
+    if (parts.length > 0)
+        return `${path} ${parts.join(", ")}`;
+    return path;
+}
+function buildEditPiToolDisplay(context) {
+    const { rawName, args, result, options } = context;
+    const value = asRecord(result.value);
+    const rawDiff = resolveCursorEditDiff(value);
+    const normalizedDiff = formatDiffString(rawDiff, options);
+    const nativeEditArgs = buildNativeEditDisplayArgs(rawName, args, options);
+    const baseActivityArgs = buildCursorEditActivityDisplayArgs(args, options);
+    const displayPath = typeof baseActivityArgs.path === "string" ? baseActivityArgs.path : undefined;
+    const activityTitle = getCursorToolActivityTitle("edit");
+    const activityArgs = buildCursorActivityDisplayArgs(baseActivityArgs, activityTitle, displayPath);
+    const contentText = formatEdit(activityArgs, result, options);
+    const details = {
+        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",
+            args: nativeEditArgs,
+            result: textToolResult(contentText, details),
+            isError: result.status === "error",
+        };
+    }
+    return buildReplaySummaryDisplay(CURSOR_REPLAY_ACTIVITY_TOOL_NAME, activityArgs, result, contentText.trimEnd(), assembleCursorReplayActivityDetails("edit", activityTitle, {
+        path: displayPath,
+        summary: result.status === "error" ? undefined : buildEditActivitySummary(displayPath, value ?? {}),
+        expandedText: contentText.trimEnd(),
+        diffString: normalizedDiff,
+        diff: normalizedDiff,
+        linesAdded: getNumber(value, "linesAdded"),
+        linesRemoved: getNumber(value, "linesRemoved"),
+    }, contentText.trimEnd(), result.status === "error", displayPath));
+}
+function buildWritePiToolDisplay(context) {
+    const { args, result, options } = context;
+    const value = asRecord(result.value);
+    const content = getCursorWriteArgContent(args);
+    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 = {
+        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(CURSOR_REPLAY_ACTIVITY_TOOL_NAME, buildCursorActivityDisplayArgs(displayArgs, activityTitle, displayPath ?? "file"), result, contentText, assembleCursorReplayActivityDetails("write", activityTitle, {
+            path: displayPath,
+            summary: result.status === "error" ? undefined : displayPath ?? "wrote file",
+            expandedText: contentText,
+            fileContentAfterWrite: getString(value, "fileContentAfterWrite"),
+        }, contentText, result.status === "error", displayPath ?? "file"));
+    }
+    return {
+        toolName: "write",
+        args: displayArgs,
+        result: textToolResult(contentText, details),
+        isError: result.status === "error",
+    };
+}
+const TOOL_DISPLAY_IMPLEMENTATIONS = {
+    read: {
+        formatTranscript: ({ args, result, options }) => formatRead(args, result, options),
+        buildPiToolDisplay: ({ args, result, options }) => {
+            const isError = result.status === "error";
+            const usesLocalPreview = !isError && usesLocalReadPreview(args, result, options);
+            return {
+                toolName: "read",
+                args: buildReadDisplayArgs(args, options, result),
+                result: textToolResult(isError ? formatError(result.error) : formatNativeReadDisplayContent(args, result, options), usesLocalPreview ? { localReadPreview: true } : undefined),
+                isError,
+            };
+        },
+    },
+    shell: {
+        formatTranscript: ({ args, result, options }) => formatShell(args, result, options),
+        buildPiToolDisplay: ({ args, result, options }) => {
+            const shellOutput = getShellOutput(result, args);
+            const isError = result.status === "error" || shellOutput.timedOut || (shellOutput.exitCode !== undefined && shellOutput.exitCode !== 0);
+            return {
+                toolName: "bash",
+                args: buildShellDisplayArgs(args),
+                result: textToolResult(result.status === "error" ? formatError(result.error) : limitText(shellOutput.text, options)),
+                isError,
+            };
+        },
+    },
+    grep: {
+        formatTranscript: ({ args, result, options }) => formatGrep(args, result, options),
+        buildPiToolDisplay: ({ args, result, options }) => {
+            const isError = result.status === "error";
+            return {
+                toolName: "grep",
+                args: buildGrepDisplayArgs(args, options),
+                result: textToolResult(isError ? formatError(result.error) : getGrepBody(result, options)),
+                isError,
+            };
+        },
+    },
+    glob: {
+        formatTranscript: ({ args, result, options }) => formatGlob(args, result, options),
+        buildPiToolDisplay: ({ args, result, options }) => {
+            const isError = result.status === "error";
+            return {
+                toolName: "find",
+                args: buildFindDisplayArgs(args, options),
+                result: textToolResult(isError ? formatError(result.error) : getGlobBody(result, options)),
+                isError,
+            };
+        },
+    },
+    ls: {
+        formatTranscript: ({ args, result, options }) => formatLs(args, result, options),
+        buildPiToolDisplay: ({ args, result, options }) => ({
+            toolName: "ls",
+            args,
+            result: textToolResult(result.status === "error" ? formatError(result.error) : getLsBody(result, options).trim()),
+            isError: result.status === "error",
+        }),
+    },
+    edit: {
+        formatTranscript: ({ args, result, options }) => formatEdit(args, result, options),
+        buildPiToolDisplay: buildEditPiToolDisplay,
+    },
+    write: {
+        formatTranscript: ({ args, result, options }) => formatWrite(args, result, options),
+        buildPiToolDisplay: buildWritePiToolDisplay,
+    },
+    delete: {
+        formatTranscript: ({ args, result, options }) => formatDelete(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("delete", context),
+    },
+    readLints: {
+        formatTranscript: ({ args, result, options }) => formatReadLints(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("readLints", context),
+    },
+    updateTodos: {
+        formatTranscript: ({ args, result, options }) => formatTodos(args, result, options, "updateTodos"),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("updateTodos", context),
+    },
+    createPlan: {
+        formatTranscript: ({ args, result, options }) => formatPlan(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("createPlan", context),
+    },
+    task: {
+        formatTranscript: ({ args, result, options }) => formatTask(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("task", context),
+    },
+    generateImage: {
+        formatTranscript: ({ args, result, options }) => formatGenerateImage(args, result, options),
+        buildPiToolDisplay: (context) => buildGenerateImageReplayDisplay(context),
+    },
+    mcp: {
+        formatTranscript: ({ args, result, options }) => formatMcp(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("mcp", context),
+    },
+    semSearch: {
+        formatTranscript: ({ args, result, options }) => formatSemSearch(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("semSearch", context),
+    },
+    recordScreen: {
+        formatTranscript: ({ args, result, options }) => formatRecordScreen(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("recordScreen", context),
+    },
+    webSearch: {
+        formatTranscript: ({ args, result, options }) => formatWebSearch(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("webSearch", context),
+    },
+    webFetch: {
+        formatTranscript: ({ args, result, options }) => formatWebFetch(args, result, options),
+        buildPiToolDisplay: (context) => buildActivityReplayDisplay("webFetch", context),
+    },
+};
+export const CURSOR_TOOL_DISPLAY_SPEC_KEYS = CURSOR_KNOWN_NORMALIZED_TOOL_NAMES;
+function getToolDisplaySpec(name) {
+    if (Object.hasOwn(TOOL_DISPLAY_IMPLEMENTATIONS, name))
+        return TOOL_DISPLAY_IMPLEMENTATIONS[name];
+    return undefined;
+}
+export function formatCursorToolTranscriptFromSpec(context) {
+    const spec = getToolDisplaySpec(context.name);
+    if (spec)
+        return spec.formatTranscript(context);
+    return formatFallback(context.name, context.args, context.result, context.options);
+}
+export function buildCursorPiToolDisplayFromSpec(context) {
+    const spec = getToolDisplaySpec(context.name);
+    if (spec)
+        return spec.buildPiToolDisplay(context);
+    return buildGenericPiToolDisplay(context);
+}

package/dist/cursor-transcript-utils.js

@@ -0,0 +1,170 @@
+import { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { asRecord, getRecord, getString, stringifyUnknown as stringifyUnknownValue } from "./cursor-record-utils.js";
+export const DEFAULT_MAX_TRANSCRIPT_CHARS = 24000;
+export const DEFAULT_MAX_TRANSCRIPT_LINES = 800;
+export const DEFAULT_MAX_LIST_ITEMS = 200;
+export const DEFAULT_READ_TRANSCRIPT_CHARS = 4000;
+export const DEFAULT_READ_TRANSCRIPT_LINES = 12;
+export const DEFAULT_NATIVE_READ_DISPLAY_LINES = 20;
+export const LOCAL_READ_PREVIEW_NOTICE = "[local file preview at transcript time; Cursor read result content was unavailable]";
+export function isLocalReadPreviewContent(text) {
+    return text.startsWith(LOCAL_READ_PREVIEW_NOTICE);
+}
+export function getToolName(toolCall) {
+    const record = asRecord(toolCall);
+    return getString(record, "name") ?? getString(record, "type") ?? getString(record, "toolName") ?? "unknown";
+}
+export function getToolArgs(toolCall) {
+    const record = asRecord(toolCall);
+    return getRecord(record, "args") ?? getRecord(record, "input") ?? {};
+}
+export function getToolResult(toolCall) {
+    const record = asRecord(toolCall);
+    return record?.result;
+}
+export function normalizeResult(result) {
+    const record = asRecord(result);
+    const status = getString(record, "status");
+    if (status === "success" || status === "error") {
+        return { status, value: record?.value, error: record?.error };
+    }
+    return { status, value: result, error: undefined };
+}
+export function stringifyUnknown(value) {
+    return stringifyUnknownValue(value, { pretty: true });
+}
+export function limitText(text, options = {}, knownTotalLines) {
+    const maxChars = options.maxChars ?? DEFAULT_MAX_TRANSCRIPT_CHARS;
+    const maxLines = options.maxLines ?? DEFAULT_MAX_TRANSCRIPT_LINES;
+    const lines = text.split("\n");
+    let limitedLines = lines.slice(0, maxLines);
+    let limited = limitedLines.join("\n");
+    let truncatedLines = Math.max((knownTotalLines ?? lines.length) - limitedLines.length, 0);
+    let truncatedChars = 0;
+    if (limited.length > maxChars) {
+        truncatedChars += limited.length - maxChars;
+        limited = limited.slice(0, maxChars);
+        limitedLines = limited.split("\n");
+        truncatedLines = Math.max(truncatedLines, Math.max((knownTotalLines ?? lines.length) - limitedLines.length, 0));
+    }
+    if (text.length > limited.length) {
+        truncatedChars += Math.max(text.length - limited.length - truncatedChars, 0);
+    }
+    const suffixParts = [];
+    if (truncatedLines > 0)
+        suffixParts.push(`${truncatedLines} more lines`);
+    if (truncatedChars > 0 && truncatedLines === 0)
+        suffixParts.push(`${truncatedChars} more chars`);
+    return suffixParts.length > 0 ? `${limited}\n... (${suffixParts.join(", ")} truncated)` : limited;
+}
+export function limitItems(items, options = {}) {
+    const maxListItems = options.maxListItems ?? DEFAULT_MAX_LIST_ITEMS;
+    return { items: items.slice(0, maxListItems), omitted: Math.max(items.length - maxListItems, 0) };
+}
+export function joinSections(header, body) {
+    const trimmedBody = body?.trimEnd();
+    return trimmedBody ? `${header}\n\n${trimmedBody}\n` : `${header}\n`;
+}
+export function formatError(error) {
+    const text = stringifyUnknown(error).trim();
+    return text ? `Error: ${text}` : "Error";
+}
+function normalizeDisplaySeparators(path) {
+    return path.replace(/\\/g, "/");
+}
+export function formatDisplayPath(path, cwd = process.cwd()) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return trimmed;
+    if (!isAbsolute(trimmed))
+        return normalizeDisplaySeparators(trimmed);
+    const relativePath = relative(cwd, trimmed);
+    if (!relativePath || relativePath === "")
+        return ".";
+    if (relativePath.startsWith("..") || isAbsolute(relativePath))
+        return normalizeDisplaySeparators(trimmed);
+    return normalizeDisplaySeparators(relativePath);
+}
+export function formatDiffPath(path, cwd = process.cwd()) {
+    if (path === "/dev/null")
+        return path;
+    return formatDisplayPath(path, cwd);
+}
+export function formatDiffHeaderLine(line, options) {
+    const match = /^(---|\+\+\+)\s+((?:[ab]\/)?)(.+)$/.exec(line);
+    if (!match)
+        return line;
+    const [, marker, prefix, rawPath] = match;
+    if (!prefix && rawPath !== "/dev/null")
+        return line;
+    const displayPath = formatDiffPath(rawPath, options.cwd);
+    return `${marker} ${prefix}${displayPath}`;
+}
+export function formatDiffString(diff, options) {
+    return diff
+        ?.split("\n")
+        .map((line) => formatDiffHeaderLine(line, options))
+        .join("\n");
+}
+export function resolveFilePath(path, cwd = process.cwd()) {
+    return isAbsolute(path) ? path : resolve(cwd, path);
+}
+export function isPathWithinCwd(filePath, cwd = process.cwd()) {
+    const relativePath = relative(cwd, filePath);
+    return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+export function isSensitivePreviewPath(filePath) {
+    const segments = filePath.split(/[\\/]+/).map((segment) => segment.toLowerCase());
+    const basename = segments.at(-1) ?? "";
+    return (segments.includes(".ssh") ||
+        segments.includes("secrets") ||
+        basename === ".env" ||
+        basename.startsWith(".env.") ||
+        basename === ".npmrc" ||
+        basename === ".netrc" ||
+        basename === "credentials" ||
+        basename === "id_rsa" ||
+        basename === "id_ed25519" ||
+        /\.(?:pem|key|p12|pfx)$/i.test(basename));
+}
+export function readFilePreview(path, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const filePath = resolveFilePath(path, cwd);
+    const maxChars = options.maxChars ?? DEFAULT_READ_TRANSCRIPT_CHARS;
+    const maxBytes = Math.max(8192, maxChars * 4);
+    let fd;
+    try {
+        const realCwd = realpathSync(cwd);
+        const realFilePath = realpathSync(filePath);
+        if (!isPathWithinCwd(realFilePath, realCwd) || isSensitivePreviewPath(filePath) || isSensitivePreviewPath(realFilePath))
+            return undefined;
+        const stat = statSync(realFilePath);
+        if (!stat.isFile())
+            return undefined;
+        fd = openSync(realFilePath, "r");
+        const buffer = Buffer.alloc(Math.min(stat.size, maxBytes));
+        const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
+        const text = buffer.toString("utf8", 0, bytesRead);
+        if (text.includes("\0"))
+            return undefined;
+        return text;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+export function formatPathArg(args, options, key = "path") {
+    const path = args[key];
+    return typeof path === "string" && path.trim() ? formatDisplayPath(path, options.cwd) : undefined;
+}
+export function firstNonEmptyLine(text) {
+    return text.split("\n").find((line) => line.trim())?.trim();
+}
+export function truncateArg(value, maxLength = 120) {
+    return value.length > maxLength ? `${value.slice(0, maxLength - 1)}…` : value;
+}

package/dist/cursor-usage-accounting.js

@@ -0,0 +1,166 @@
+import { CURSOR_APPROX_CHARS_PER_TOKEN, CURSOR_IMAGE_TOKEN_ESTIMATE, estimateCursorContextTokens, estimateCursorTextTokens, } from "./context.js";
+import { asRecord, getNumber } from "./cursor-record-utils.js";
+function getPromptInputTokenBudget(model) {
+    const outputReserveTokens = Math.min(model.maxTokens, Math.max(1, Math.floor(model.contextWindow * 0.2)));
+    return Math.max(1, model.contextWindow - outputReserveTokens);
+}
+export function getCursorPromptOptions(model) {
+    return {
+        maxInputTokens: getPromptInputTokenBudget(model),
+        charsPerToken: CURSOR_APPROX_CHARS_PER_TOKEN,
+        imageTokenEstimate: CURSOR_IMAGE_TOKEN_ESTIMATE,
+    };
+}
+function getNonNegativeTokenCount(record, key) {
+    const value = getNumber(record, key);
+    return value === undefined || value < 0 ? undefined : Math.floor(value);
+}
+export function readCursorSdkTurnUsage(value) {
+    const record = asRecord(value);
+    const inputTokens = getNonNegativeTokenCount(record, "inputTokens");
+    const outputTokens = getNonNegativeTokenCount(record, "outputTokens");
+    const cacheReadTokens = getNonNegativeTokenCount(record, "cacheReadTokens");
+    const cacheWriteTokens = getNonNegativeTokenCount(record, "cacheWriteTokens");
+    if (inputTokens === undefined || outputTokens === undefined || cacheReadTokens === undefined || cacheWriteTokens === undefined)
+        return undefined;
+    return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens };
+}
+export function readCursorSdkTurnUsageFromUpdate(update) {
+    const record = asRecord(update);
+    return record?.type === "turn-ended" ? readCursorSdkTurnUsage(record.usage) : undefined;
+}
+function stringifyUsageValue(value) {
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return String(value);
+    }
+}
+export function estimateCursorAssistantSessionOutputTokens(message) {
+    const parts = message.content
+        .map((block) => {
+        if (block.type === "text")
+            return block.text;
+        if (block.type === "thinking")
+            return block.thinking;
+        if (block.type === "toolCall") {
+            return `Tool call (${block.name}, call ${block.id}): ${stringifyUsageValue(block.arguments)}`;
+        }
+        return "";
+    })
+        .filter(Boolean);
+    return estimateCursorTextTokens(parts.join("\n"), { charsPerToken: CURSOR_APPROX_CHARS_PER_TOKEN });
+}
+function withAssistantMessage(context, partial) {
+    return { ...context, messages: [...context.messages, partial] };
+}
+export function estimateCursorContextTotalTokens(partial, model, context) {
+    return estimateCursorContextTokens(withAssistantMessage(context, partial), getCursorPromptOptions(model));
+}
+function getCursorSdkUncachedInputTokens(turnUsage) {
+    // Observed raw local turn-ended.usage: inputTokens is the full prompt; cache fields partition it.
+    // Published SDK toTokenUsage instead sums all four into totalTokens — do not use that transform here.
+    return turnUsage.inputTokens - turnUsage.cacheReadTokens - turnUsage.cacheWriteTokens;
+}
+export function isCursorSdkUsagePartitionSafe(turnUsage, model) {
+    const counts = [turnUsage.inputTokens, turnUsage.outputTokens, turnUsage.cacheReadTokens, turnUsage.cacheWriteTokens];
+    const uncachedInput = getCursorSdkUncachedInputTokens(turnUsage);
+    return (counts.every((count) => Number.isFinite(count) && count >= 0) &&
+        Number.isFinite(uncachedInput) &&
+        uncachedInput >= 0 &&
+        turnUsage.outputTokens <= model.maxTokens);
+}
+export function isCursorSdkUsageSafeForPiMessage(turnUsage, model) {
+    return (isCursorSdkUsagePartitionSafe(turnUsage, model) &&
+        turnUsage.inputTokens + turnUsage.outputTokens <= model.contextWindow);
+}
+export function applyCursorSdkUsage(partial, turnUsage) {
+    // Pi treats input/cacheRead/cacheWrite as disjoint additive prompt components.
+    partial.usage.input = getCursorSdkUncachedInputTokens(turnUsage);
+    partial.usage.output = turnUsage.outputTokens;
+    partial.usage.cacheRead = turnUsage.cacheReadTokens;
+    partial.usage.cacheWrite = turnUsage.cacheWriteTokens;
+    // totalTokens is context occupancy (full prompt + output), not the sum of spend components alone.
+    partial.usage.totalTokens = turnUsage.inputTokens + turnUsage.outputTokens;
+}
+function isCompatibleCursorAssistantMeasurement(assistant, model) {
+    return assistant.api === model.api && assistant.provider === model.provider && assistant.model === model.id;
+}
+function getLatestCompactionBoundary(context) {
+    for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+        const message = context.messages[index];
+        if (message.role !== "compactionSummary")
+            continue;
+        const tokensBefore = message.tokensBefore;
+        return {
+            index,
+            tokensBefore: Number.isFinite(tokensBefore) && tokensBefore !== undefined && tokensBefore > 0 ? Math.floor(tokensBefore) : undefined,
+        };
+    }
+    return undefined;
+}
+function getLastAcceptedContextOccupancy(context, model) {
+    const boundary = getLatestCompactionBoundary(context);
+    for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+        if (boundary && index < boundary.index)
+            break;
+        const message = context.messages[index];
+        if (message.role !== "assistant" || !("usage" in message))
+            continue;
+        const assistant = message;
+        if (assistant.stopReason === "aborted" || assistant.stopReason === "error" || !assistant.usage)
+            continue;
+        if (!isCompatibleCursorAssistantMeasurement(assistant, model))
+            continue;
+        const { usage } = assistant;
+        const total = usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+        if (!Number.isFinite(total) || total <= 0 || total > model.contextWindow)
+            continue;
+        if (boundary?.tokensBefore !== undefined && total >= boundary.tokensBefore)
+            continue;
+        return total;
+    }
+    return 0;
+}
+export function applyCursorApproximateUsage(partial, model, context, sessionInputTokens) {
+    const outputTokens = estimateCursorAssistantSessionOutputTokens(partial);
+    partial.usage.input = Math.max(0, sessionInputTokens);
+    partial.usage.output = outputTokens;
+    partial.usage.cacheRead = 0;
+    partial.usage.cacheWrite = 0;
+    // Never report less occupancy than the last compatible same-model in-window assistant measurement.
+    partial.usage.totalTokens = Math.max(partial.usage.input + partial.usage.output, estimateCursorContextTotalTokens(partial, model, context), getLastAcceptedContextOccupancy(context, model));
+}
+function applyCursorOccupancyEstimate(partial, model, context) {
+    partial.usage.totalTokens = Math.max(estimateCursorContextTotalTokens(partial, model, context), getLastAcceptedContextOccupancy(context, model));
+}
+function isCurrentLocalOccupancy(turn, model, context) {
+    if (!isCursorSdkUsageSafeForPiMessage(turn, model))
+        return false;
+    const tokensBefore = getLatestCompactionBoundary(context)?.tokensBefore;
+    return tokensBefore === undefined || turn.inputTokens + turn.outputTokens < tokensBefore;
+}
+function applyResolvedCursorOccupancy(partial, model, context, localTurn) {
+    if (localTurn && isCurrentLocalOccupancy(localTurn, model, context)) {
+        partial.usage.totalTokens = localTurn.inputTokens + localTurn.outputTokens;
+        return;
+    }
+    applyCursorOccupancyEstimate(partial, model, context);
+}
+export function applyCursorUsage(partial, model, context, sessionInputTokens, sdkUsage) {
+    const billed = sdkUsage?.billed;
+    const localTurn = sdkUsage?.runtime === "local" ? sdkUsage.turn : undefined;
+    if (billed && isCursorSdkUsagePartitionSafe(billed, model)) {
+        applyCursorSdkUsage(partial, billed);
+        applyResolvedCursorOccupancy(partial, model, context, localTurn);
+        return;
+    }
+    // Only local raw turn-ended usage has a captured full-prompt/cache-partition occupancy contract.
+    if (localTurn && isCursorSdkUsageSafeForPiMessage(localTurn, model)) {
+        applyCursorSdkUsage(partial, localTurn);
+        applyResolvedCursorOccupancy(partial, model, context, localTurn);
+        return;
+    }
+    applyCursorApproximateUsage(partial, model, context, sessionInputTokens);
+}

package/dist/cursor-web-tool-activity.js

@@ -0,0 +1,23 @@
+import { getFirstStringByKeys } from "./cursor-record-utils.js";
+import { classifyCursorWebToolKind, normalizeCursorToolName as normalizeToolName, } from "./cursor-tool-presentation-registry.js";
+function getMcpToolName(args) {
+    const toolName = getFirstStringByKeys(args, ["toolName", "tool_name"]);
+    const trimmed = toolName?.trim();
+    return trimmed || undefined;
+}
+/**
+ * Maps SDK/host/MCP tool names to transcript display keys.
+ * Web search/fetch often arrives as MCP `toolName` values, not dedicated SDK ToolTypes.
+ */
+export function resolveTranscriptToolName(rawName, args) {
+    const normalized = normalizeToolName(rawName);
+    const directWebKind = classifyCursorWebToolKind(rawName) ?? classifyCursorWebToolKind(normalized);
+    if (directWebKind)
+        return directWebKind;
+    if (normalized === "mcp") {
+        const mcpWebKind = classifyCursorWebToolKind(getMcpToolName(args));
+        if (mcpWebKind)
+            return mcpWebKind;
+    }
+    return normalized;
+}

package/dist/cursor-web-tool-args.js

@@ -0,0 +1,12 @@
+import { asRecord, firstNonEmptyString } from "./cursor-record-utils.js";
+function getNestedMcpArgs(args) {
+    return asRecord(args.args) ?? {};
+}
+export function extractWebSearchQuery(args) {
+    const nested = getNestedMcpArgs(args);
+    return firstNonEmptyString(typeof args.search_term === "string" ? args.search_term : undefined, typeof args.searchTerm === "string" ? args.searchTerm : undefined, typeof args.query === "string" ? args.query : undefined, typeof args.q === "string" ? args.q : undefined, typeof nested.search_term === "string" ? nested.search_term : undefined, typeof nested.searchTerm === "string" ? nested.searchTerm : undefined, typeof nested.query === "string" ? nested.query : undefined, typeof nested.q === "string" ? nested.q : undefined);
+}
+export function extractWebFetchTarget(args) {
+    const nested = getNestedMcpArgs(args);
+    return firstNonEmptyString(typeof args.url === "string" ? args.url : undefined, typeof args.uri === "string" ? args.uri : undefined, typeof args.href === "string" ? args.href : undefined, typeof nested.url === "string" ? nested.url : undefined, typeof nested.uri === "string" ? nested.uri : undefined, typeof nested.href === "string" ? nested.href : undefined);
+}