sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/tokenSummary.js

@@ -0,0 +1,113 @@
+/**
+ * One vocabulary for token totals across every Sidekick surface.
+ *
+ * Every report, dashboard, status bar, and export derives its headline token
+ * numbers from here so "Total" means the same thing everywhere:
+ *
+ * - `total`   — every token the provider billed: uncached input, cache writes,
+ *               cache reads, and output. Matches `NormalizedUsage.totalTokens`
+ *               and the per-model `tokens` the `EventAggregator` keeps.
+ * - `context` — tokens that occupied the context window on the last request:
+ *               uncached input, cache writes, and cache reads. Output is
+ *               excluded, matching the input-only formula Claude Code uses for
+ *               its status-line `used_percentage`.
+ * - `output`  — output tokens as billed.
+ *
+ * Cache reads are usually the majority of a coding-agent session's tokens, so
+ * an "input + output" total silently drops most of the work. Sidekick used to
+ * do that on some surfaces and not others; this helper is the single place the
+ * arithmetic lives.
+ *
+ * Browser-safe: no Node imports.
+ *
+ * @module tokenSummary
+ */
+/** Column label for `TokenSummary.total` on any surface. */
+export const TOKEN_TOTAL_LABEL = 'Total (incl. cache)';
+/** Column label for `TokenSummary.context` on any surface. */
+export const TOKEN_CONTEXT_LABEL = 'Context';
+/** Label for a session's own (main-thread) tokens when subagents are shown beside it. */
+export const TOKEN_MAIN_THREAD_LABEL = 'Main thread';
+/** Label for the tokens a session's subagents used. */
+export const TOKEN_SUBAGENTS_LABEL = 'Subagents';
+/** Label for main thread plus subagents. */
+export const TOKEN_SESSION_TOTAL_LABEL = 'Session total (incl. subagents)';
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/** Derive the shared token vocabulary from any four-bucket token record. */
+export function summarizeTokens(totals) {
+    const input = count(totals.inputTokens);
+    const output = count(totals.outputTokens);
+    const cacheRead = count(totals.cacheReadTokens);
+    const cacheWrite = count(totals.cacheWriteTokens);
+    const context = input + cacheWrite + cacheRead;
+    const fourBucket = context + output;
+    const provided = totals.totalTokens;
+    const total = typeof provided === 'number' && Number.isFinite(provided) && provided >= 0
+        ? Math.floor(provided)
+        : fourBucket;
+    return {
+        total,
+        context,
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        cacheHitRatio: context > 0 ? cacheRead / context : null,
+        reasoning: count(totals.reasoningTokens),
+        billedOutsideBuckets: Math.max(0, total - fourBucket),
+    };
+}
+/**
+ * One-line breakdown whose parts add up to the headline:
+ * `1.2M total incl. cache (12k in · 1.1M cache read · 40k cache write · 30k out)`.
+ * Pass the surface's own number formatter; the default prints plain integers.
+ */
+export function formatTokenBreakdown(summary, fmt = (n) => String(n)) {
+    const parts = [
+        `${fmt(summary.input)} in`,
+        `${fmt(summary.cacheRead)} cache read`,
+        `${fmt(summary.cacheWrite)} cache write`,
+        `${fmt(summary.output)} out`,
+    ];
+    if (summary.billedOutsideBuckets > 0) {
+        parts.push(`${fmt(summary.billedOutsideBuckets)} reasoning`);
+    }
+    return `${fmt(summary.total)} total incl. cache (${parts.join(' · ')})`;
+}
+/**
+ * Sum several token records bucket-by-bucket before summarizing. `totalTokens`
+ * is summed only when every record carries one, so provider-aware totals
+ * survive the sum instead of falling back to the four-bucket arithmetic.
+ */
+export function sumTokenTotals(records) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheWriteTokens = 0;
+    let cacheReadTokens = 0;
+    let reasoningTokens = 0;
+    let totalTokens = 0;
+    let allHaveTotal = records.length > 0;
+    for (const record of records) {
+        inputTokens += count(record.inputTokens);
+        outputTokens += count(record.outputTokens);
+        cacheWriteTokens += count(record.cacheWriteTokens);
+        cacheReadTokens += count(record.cacheReadTokens);
+        reasoningTokens += count(record.reasoningTokens);
+        if (typeof record.totalTokens === 'number' && Number.isFinite(record.totalTokens)) {
+            totalTokens += count(record.totalTokens);
+        }
+        else {
+            allHaveTotal = false;
+        }
+    }
+    return {
+        inputTokens,
+        outputTokens,
+        cacheWriteTokens,
+        cacheReadTokens,
+        reasoningTokens,
+        ...(allHaveTotal ? { totalTokens } : {}),
+    };
+}

package/dist/esm/toolCategory.js

@@ -0,0 +1,82 @@
+/**
+ * One vocabulary for what a tool call does, across Claude Code, Codex, and
+ * OpenCode tool names. Browser-safe: no Node imports.
+ *
+ * @module toolCategory
+ */
+import { parseMcpToolName } from './parsers/mcpToolName';
+export const TOOL_CATEGORIES = [
+    'shell',
+    'file_read',
+    'file_edit',
+    'search',
+    'web',
+    'subagent',
+    'planning',
+    'mcp',
+    'other',
+];
+/** Lower-cased tool names of every provider, by category. */
+const CATEGORY_BY_NAME = new Map([
+    [
+        'shell',
+        [
+            'bash',
+            'bashoutput',
+            'killbash',
+            'killshell',
+            'exec_command',
+            'shell',
+            'local_shell',
+            'local_shell_call',
+            'container.exec',
+            'write_stdin',
+        ],
+    ],
+    ['file_read', ['read', 'notebookread', 'ls', 'list', 'view_image']],
+    [
+        'file_edit',
+        ['edit', 'multiedit', 'write', 'notebookedit', 'apply_patch', 'patch', 'patch_applied'],
+    ],
+    ['search', ['grep', 'glob', 'codesearch', 'toolsearch']],
+    ['web', ['webfetch', 'websearch', 'web_search', 'web_search_call', 'fetch']],
+    [
+        'subagent',
+        [
+            'task',
+            'agent',
+            'spawn_agent',
+            'wait_agent',
+            'send_message',
+            'followup_task',
+            'list_agents',
+            'wait',
+        ],
+    ],
+    [
+        'planning',
+        [
+            'todowrite',
+            'todoread',
+            'update_plan',
+            'updateplan',
+            'enterplanmode',
+            'exitplanmode',
+            'taskcreate',
+            'taskupdate',
+            'tasklist',
+            'askuserquestion',
+            'request_user_input',
+        ],
+    ],
+].flatMap(([category, names]) => names.map((name) => [name, category])));
+/**
+ * Classifies a tool name from any supported provider. `mcp__<server>__<tool>`
+ * names and calls with a known `mcpServer` are `mcp`; unknown names are
+ * `other`.
+ */
+export function classifyTool(name, options = {}) {
+    if (options.mcpServer || parseMcpToolName(name))
+        return 'mcp';
+    return CATEGORY_BY_NAME.get(name.trim().toLowerCase()) ?? 'other';
+}

package/dist/esm/transcript.js

@@ -0,0 +1,257 @@
+import { calculateNormalizedUsageCost, extractNormalizedUsage, } from './usageNormalization';
+const EMPTY_TOTALS = {
+    uncachedInputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    cacheInclusiveInputTokens: 0,
+    billableOutputTokens: 0,
+    totalTokens: 0,
+};
+/** Project canonical provider events into a bounded or full-fidelity transcript. */
+export function projectSessionTranscript(events, options = {}) {
+    const fidelity = options.fidelity ?? 'snippet';
+    const requestedMax = options.maxContentChars ?? 2_000;
+    const maxContentChars = Number.isFinite(requestedMax) ? Math.max(0, requestedMax) : 2_000;
+    const messages = [];
+    const tools = [];
+    const commands = [];
+    const models = new Set();
+    const usageEvents = [];
+    const usageCosts = [];
+    const totals = { ...EMPTY_TOTALS };
+    const toolsById = new Map();
+    let cwd;
+    let gitBranch;
+    events.forEach((event, eventIndex) => {
+        if (nonEmpty(event.cwd))
+            cwd = event.cwd;
+        if (nonEmpty(event.gitBranch))
+            gitBranch = event.gitBranch;
+        const message = event.message;
+        const source = {
+            provider: options.provider ?? event.providerMetadata?.providerId,
+            sessionId: options.sessionId,
+            sourcePath: options.sourcePath,
+            source: event.providerMetadata?.source,
+            entrypoint: event.entrypoint,
+            isMeta: event.isMeta,
+            isSidechain: event.isSidechain,
+            ...(event.isCompactSummary !== undefined ? { isCompactSummary: event.isCompactSummary } : {}),
+            ...(event.origin?.kind !== undefined ? { originKind: event.origin.kind } : {}),
+            ...(event.promptSource !== undefined ? { promptSource: event.promptSource } : {}),
+            originalRole: message?.role,
+            eventIndex,
+            eventType: event.type,
+            eventId: message?.id,
+        };
+        const usage = extractNormalizedUsage(event) ?? undefined;
+        if (usage) {
+            usageEvents.push(usage);
+            addUsage(totals, usage);
+        }
+        const cost = usage
+            ? calculateNormalizedUsageCost({ usage, modelId: message?.model })
+            : undefined;
+        if (cost)
+            usageCosts.push(cost);
+        if (message?.model)
+            models.add(message.model);
+        const blocks = contentBlocks(message?.content, fidelity, maxContentChars, options.includeUnknownBlocks);
+        if (event.type === 'summary' && event.summary && blocks.length === 0) {
+            blocks.push({ type: 'text', ...boundedText(event.summary, fidelity, maxContentChars) });
+        }
+        if (event.type === 'tool_use') {
+            blocks.push({
+                type: 'tool_use',
+                toolName: event.tool.name,
+                input: boundedValue(event.tool.input, fidelity, maxContentChars),
+            });
+        }
+        if (event.type === 'tool_result') {
+            blocks.push({
+                type: 'tool_result',
+                toolUseId: event.result.tool_use_id,
+                output: boundedValue(event.result.output, fidelity, maxContentChars),
+                isError: event.result.is_error,
+            });
+        }
+        const messageTools = [];
+        for (const block of blocks) {
+            if (block.type === 'tool_use' && block.toolName) {
+                const command = block.command ?? commandFromTool(block.toolName, block.input);
+                const call = {
+                    id: block.toolUseId,
+                    name: block.toolName,
+                    timestamp: event.timestamp,
+                    input: block.input,
+                    command,
+                    source,
+                };
+                tools.push(call);
+                messageTools.push(call);
+                if (call.id)
+                    toolsById.set(call.id, call);
+                if (command)
+                    commands.push(command);
+            }
+            else if (block.type === 'tool_result' && block.toolUseId) {
+                const call = toolsById.get(block.toolUseId);
+                if (call) {
+                    call.output = block.output;
+                    call.isError = block.isError;
+                }
+            }
+        }
+        if (blocks.length === 0 && !usage && event.type !== 'summary')
+            return;
+        messages.push({
+            id: message?.id,
+            role: roleForEvent(event),
+            timestamp: event.timestamp,
+            model: message?.model,
+            sourceLabel: message?.sourceLabel,
+            content: blocks,
+            text: blocks
+                .filter((block) => block.type === 'text' || block.type === 'thinking')
+                .map((block) => block.text ?? '')
+                .filter(Boolean)
+                .join('\n'),
+            usage,
+            cost,
+            tools: messageTools,
+            commands: messageTools.flatMap((tool) => (tool.command ? [tool.command] : [])),
+            source,
+        });
+    });
+    return {
+        provider: options.provider,
+        sessionId: options.sessionId,
+        sourcePath: options.sourcePath,
+        cwd,
+        gitBranch,
+        startedAt: events[0]?.timestamp,
+        endedAt: events.at(-1)?.timestamp,
+        models: [...models],
+        messages,
+        tools,
+        commands: [...new Set(commands)],
+        usage: {
+            events: usageEvents,
+            costs: usageCosts,
+            totals,
+            totalCostUsd: usageCosts.length > 0 && usageCosts.every((cost) => cost.costUsd !== null)
+                ? usageCosts.reduce((sum, cost) => sum + (cost.costUsd ?? 0), 0)
+                : null,
+            pricedCostUsd: usageCosts.reduce((sum, cost) => sum + (cost.costUsd ?? 0), 0),
+            unpricedEvents: usageCosts.filter((cost) => cost.costUsd === null).length,
+        },
+        provenance: { source: 'session-events', fidelity, eventCount: events.length },
+    };
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function roleForEvent(event) {
+    if (event.type === 'summary')
+        return 'summary';
+    if (event.type === 'system')
+        return 'system';
+    if (event.type === 'tool_use' || event.type === 'tool_result')
+        return 'tool';
+    return event.type;
+}
+function contentBlocks(content, fidelity, maxChars, includeUnknown = false) {
+    if (typeof content === 'string')
+        return [{ type: 'text', ...boundedText(content, fidelity, maxChars) }];
+    if (!Array.isArray(content))
+        return [];
+    const result = [];
+    for (const raw of content) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const block = raw;
+        if (block.type === 'text' && typeof block.text === 'string') {
+            result.push({ type: 'text', ...boundedText(block.text, fidelity, maxChars) });
+        }
+        else if ((block.type === 'thinking' || block.type === 'reasoning') &&
+            (typeof block.thinking === 'string' || typeof block.text === 'string')) {
+            result.push({
+                type: 'thinking',
+                ...boundedText(String(block.thinking ?? block.text), fidelity, maxChars),
+            });
+        }
+        else if (block.type === 'tool_use' && typeof block.name === 'string') {
+            result.push({
+                type: 'tool_use',
+                toolName: block.name,
+                toolUseId: typeof block.id === 'string' ? block.id : undefined,
+                input: boundedValue(block.input, fidelity, maxChars),
+                command: commandFromTool(block.name, block.input),
+            });
+        }
+        else if (block.type === 'tool_result') {
+            result.push({
+                type: 'tool_result',
+                toolUseId: typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined,
+                output: boundedValue(block.content, fidelity, maxChars),
+                isError: block.is_error === true,
+            });
+        }
+        else if (block.type === 'image') {
+            result.push({
+                type: 'image',
+                text: '[Image content]',
+                ...(fidelity === 'full' ? { raw } : {}),
+            });
+        }
+        else if (includeUnknown) {
+            result.push({ type: 'unknown', raw: boundedValue(raw, fidelity, maxChars) });
+        }
+    }
+    return result;
+}
+function boundedText(text, fidelity, maxChars) {
+    if (fidelity === 'full' || text.length <= maxChars)
+        return { text, truncated: false };
+    return { text: text.slice(0, maxChars), truncated: true };
+}
+function boundedValue(value, fidelity, maxChars) {
+    if (fidelity === 'full' || value === undefined)
+        return value;
+    if (typeof value === 'string')
+        return boundedText(value, fidelity, maxChars).text;
+    try {
+        const json = JSON.stringify(value);
+        return json.length <= maxChars ? value : json.slice(0, maxChars);
+    }
+    catch {
+        return String(value).slice(0, maxChars);
+    }
+}
+function commandFromTool(name, input) {
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const value = input;
+    if (!['bash', 'shell', 'execcommand', 'exec_command', 'local_shell'].includes(name.toLowerCase())) {
+        return undefined;
+    }
+    if (typeof value.command === 'string')
+        return value.command;
+    if (Array.isArray(value.command))
+        return value.command.map(String).join(' ');
+    if (typeof value.cmd === 'string')
+        return value.cmd;
+    return undefined;
+}
+function addUsage(total, usage) {
+    total.uncachedInputTokens += usage.uncachedInputTokens;
+    total.cacheReadTokens += usage.cacheReadTokens;
+    total.cacheWriteTokens += usage.cacheWriteTokens;
+    total.outputTokens += usage.outputTokens;
+    total.reasoningTokens += usage.reasoningTokens;
+    total.cacheInclusiveInputTokens += usage.cacheInclusiveInputTokens;
+    total.billableOutputTokens += usage.billableOutputTokens;
+    total.totalTokens += usage.totalTokens;
+}