sidekick-shared 0.13.2

package/dist/formatters/noiseClassifier.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Noise classification pipeline for session events.
+ *
+ * Multi-layer classification system that filters system noise, sidechains,
+ * synthetic messages, and soft noise (system-reminder tags, empty outputs).
+ * Inspired by tail-claude's noise filtering.
+ *
+ * @module formatters/noiseClassifier
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHardNoise = isHardNoise;
+exports.isHardNoiseFollowEvent = isHardNoiseFollowEvent;
+exports.getSoftNoiseReason = getSoftNoiseReason;
+exports.classifyMessage = classifyMessage;
+exports.classifyFollowEvent = classifyFollowEvent;
+exports.shouldMergeWithPrevious = shouldMergeWithPrevious;
+exports.classifyNoise = classifyNoise;
+// ── Hard Noise Detection ──
+/** Hard noise types that should be dropped entirely from display. */
+const HARD_NOISE_EVENT_TYPES = new Set([
+    'file-history-snapshot',
+    'queue-operation',
+    'progress',
+]);
+const SYNTHETIC_MODEL_PREFIX = '<synthetic>';
+/**
+ * Determines if an event is "hard noise" and should be dropped entirely.
+ *
+ * Hard noise includes:
+ * - System-type events (non-content)
+ * - Specific infrastructure event types (file-history-snapshot, queue-operation, progress)
+ * - Sidechain/subagent events (when filtering to main conversation)
+ * - Synthetic model entries (model starts with `<synthetic>`)
+ */
+function isHardNoise(event) {
+    // Sidechain events are noise for the main timeline
+    if (event.isSidechain)
+        return true;
+    // Check for known noise event types in raw data
+    const rawType = event.type;
+    if (HARD_NOISE_EVENT_TYPES.has(rawType))
+        return true;
+    // Synthetic model entries
+    if (event.message?.model?.startsWith(SYNTHETIC_MODEL_PREFIX))
+        return true;
+    return false;
+}
+/**
+ * FollowEvent variant of hard noise detection.
+ */
+function isHardNoiseFollowEvent(event) {
+    // System events that are just infrastructure
+    if (event.type === 'system') {
+        const summary = event.summary?.toLowerCase() ?? '';
+        // Keep "Session ended" type system events
+        if (summary.includes('session ended') || summary.includes('session started')) {
+            return false;
+        }
+        // Token count events from Codex are noise for timeline display
+        if (summary.startsWith('tokens:') || summary.startsWith('model:')) {
+            return true;
+        }
+    }
+    return false;
+}
+// ── Soft Noise Detection ──
+const SYSTEM_REMINDER_PATTERN = /<system-reminder>[\s\S]*?<\/system-reminder>/;
+const COMMAND_CAVEAT_PATTERNS = [
+    /IMPORTANT:.*?(?:never|always|must|should)/i,
+    /Note:.*?(?:do not|don't|avoid)/i,
+];
+const INTERRUPTION_MARKERS = [
+    'interrupted by user',
+    'operation cancelled',
+    'aborted',
+];
+/**
+ * Checks for soft noise that can be hidden but not dropped.
+ *
+ * Soft noise includes:
+ * - system-reminder XML tags in content
+ * - Command caveats (IMPORTANT/Note instructions)
+ * - Empty tool outputs
+ * - User interruption markers
+ *
+ * @returns A reason string if soft noise is detected, null otherwise.
+ */
+function getSoftNoiseReason(event) {
+    const content = extractContent(event);
+    if (content && SYSTEM_REMINDER_PATTERN.test(content)) {
+        return 'system-reminder';
+    }
+    for (const pattern of COMMAND_CAVEAT_PATTERNS) {
+        if (content && pattern.test(content)) {
+            return 'command-caveat';
+        }
+    }
+    // Empty tool results
+    if (event.type === 'tool_result') {
+        const output = event.result?.output;
+        if (output === '' || output === undefined || output === null) {
+            return 'empty-tool-output';
+        }
+    }
+    // Interruption markers
+    if (content) {
+        for (const marker of INTERRUPTION_MARKERS) {
+            if (content.toLowerCase().includes(marker)) {
+                return 'interruption';
+            }
+        }
+    }
+    return null;
+}
+// ── Message Classification ──
+/**
+ * Classifies a SessionEvent into semantic message categories.
+ *
+ * Categories:
+ * - `user` — human prompts
+ * - `ai` — assistant responses (text or tool calls)
+ * - `system` — tool results, compaction, infrastructure
+ * - `teammate` — teammate/subagent messages (from `<teammate-message>` blocks)
+ * - `compact` — compaction/summary events
+ */
+function classifyMessage(event) {
+    switch (event.type) {
+        case 'user': {
+            const content = extractContent(event);
+            // Check for teammate messages
+            if (content && content.includes('<teammate-message>')) {
+                return 'teammate';
+            }
+            return 'user';
+        }
+        case 'assistant':
+            return 'ai';
+        case 'summary':
+            return 'compact';
+        case 'tool_use':
+            return 'ai';
+        case 'tool_result':
+            return 'system';
+        default:
+            return 'system';
+    }
+}
+/**
+ * FollowEvent variant of message classification.
+ */
+function classifyFollowEvent(event) {
+    switch (event.type) {
+        case 'user':
+            return 'user';
+        case 'assistant':
+            return 'ai';
+        case 'tool_use':
+            return 'ai';
+        case 'tool_result':
+            return 'system';
+        case 'summary':
+            return 'compact';
+        case 'system':
+            return 'system';
+        default:
+            return 'system';
+    }
+}
+// ── Merge Detection ──
+/**
+ * Determines if the current event should be merged with the previous one.
+ *
+ * Consecutive assistant text messages (without tool calls between them)
+ * can be merged into a single display entry.
+ */
+function shouldMergeWithPrevious(current, previous) {
+    if (!previous)
+        return false;
+    // Merge consecutive assistant text messages
+    if (current.type === 'assistant' && previous.type === 'assistant') {
+        // Don't merge if either has tool_use content blocks
+        const currentContent = current.message?.content;
+        const previousContent = previous.message?.content;
+        if (hasToolUseBlocks(currentContent) || hasToolUseBlocks(previousContent)) {
+            return false;
+        }
+        return true;
+    }
+    return false;
+}
+// ── Full Classification ──
+/**
+ * Performs full noise classification on a SessionEvent.
+ * Combines hard noise detection, soft noise detection, and message classification.
+ */
+function classifyNoise(event) {
+    return {
+        isHardNoise: isHardNoise(event),
+        softNoiseReason: getSoftNoiseReason(event),
+        messageClassification: classifyMessage(event),
+    };
+}
+// ── Helpers ──
+function extractContent(event) {
+    const content = event.message?.content;
+    if (!content)
+        return null;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const texts = [];
+        for (const block of content) {
+            if (block.type === 'text' && typeof block.text === 'string') {
+                texts.push(block.text);
+            }
+        }
+        return texts.length > 0 ? texts.join('\n') : null;
+    }
+    return null;
+}
+function hasToolUseBlocks(content) {
+    if (!Array.isArray(content))
+        return false;
+    return content.some(b => b.type === 'tool_use');
+}

package/dist/formatters/sessionDump.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Session dump formatters — text, markdown, and JSON output.
+ *
+ * Extracted from sidekick-cli's dump command so both the CLI and VS Code
+ * extension can produce identical session reports from AggregatedMetrics.
+ *
+ * @module formatters/sessionDump
+ */
+import type { AggregatedMetrics } from '../aggregation/types';
+/** Options for text and markdown formatters. */
+export interface SessionDumpOptions {
+    /** Terminal width for text output (default 120). */
+    width?: number;
+    /** Show noise-classified events (default false hides them). */
+    expand?: boolean;
+    /** Session file name to display in markdown summary table. */
+    sessionFileName?: string;
+}
+/**
+ * Serialize aggregated metrics as pretty-printed JSON.
+ */
+export declare function formatSessionJson(metrics: AggregatedMetrics): string;
+/**
+ * Format aggregated metrics as a plain-text report.
+ */
+export declare function formatSessionText(metrics: AggregatedMetrics, options?: SessionDumpOptions): string;
+/**
+ * Format aggregated metrics as a markdown report.
+ */
+export declare function formatSessionMarkdown(metrics: AggregatedMetrics, options?: SessionDumpOptions): string;
+/** @internal Exported for tests. */
+export declare function fmtTokens(n: number): string;
+/** @internal Exported for tests. */
+export declare function fmtCost(cost: number): string;
+/** @internal Exported for tests. */
+export declare function formatTimestamp(iso: string): string;
+/** @internal Exported for tests. */
+export declare function formatDuration(start: string | null, end: string | null): string;

package/dist/formatters/sessionDump.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Session dump formatters — text, markdown, and JSON output.
+ *
+ * Extracted from sidekick-cli's dump command so both the CLI and VS Code
+ * extension can produce identical session reports from AggregatedMetrics.
+ *
+ * @module formatters/sessionDump
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSessionJson = formatSessionJson;
+exports.formatSessionText = formatSessionText;
+exports.formatSessionMarkdown = formatSessionMarkdown;
+exports.fmtTokens = fmtTokens;
+exports.fmtCost = fmtCost;
+exports.formatTimestamp = formatTimestamp;
+exports.formatDuration = formatDuration;
+// ── JSON output ──
+/**
+ * Serialize aggregated metrics as pretty-printed JSON.
+ */
+function formatSessionJson(metrics) {
+    return JSON.stringify(metrics, null, 2) + '\n';
+}
+// ── Text output ──
+/**
+ * Format aggregated metrics as a plain-text report.
+ */
+function formatSessionText(metrics, options = {}) {
+    const width = options.width ?? 120;
+    const expand = options.expand ?? false;
+    const lines = [];
+    const hr = '\u2500'.repeat(Math.min(width, 80));
+    // Header
+    lines.push(hr);
+    lines.push(formatHeader(metrics));
+    lines.push(hr);
+    lines.push('');
+    // Token summary
+    lines.push(formatTokenSummary(metrics));
+    lines.push('');
+    // Model stats
+    if (metrics.modelStats.length > 0) {
+        lines.push('Models:');
+        for (const m of metrics.modelStats) {
+            lines.push(`  ${m.model}: ${m.calls} calls, ${fmtTokens(m.tokens)} tokens, ${fmtCost(m.cost)}`);
+        }
+        lines.push('');
+    }
+    // Tool stats
+    if (metrics.toolStats.length > 0) {
+        lines.push('Tools:');
+        const sorted = [...metrics.toolStats].sort((a, b) => (b.successCount + b.failureCount) - (a.successCount + a.failureCount));
+        for (const t of sorted) {
+            const total = t.successCount + t.failureCount;
+            const failStr = t.failureCount > 0 ? ` (${t.failureCount} failed)` : '';
+            const avgMs = t.completedCount > 0 ? Math.round(t.totalDuration / t.completedCount) : 0;
+            const durationStr = avgMs > 0 ? ` avg ${avgMs}ms` : '';
+            lines.push(`  ${t.name}: ${total}${failStr}${durationStr}`);
+        }
+        lines.push('');
+    }
+    // Compaction / truncation
+    if (metrics.compactionCount > 0 || metrics.truncationCount > 0) {
+        const parts = [];
+        if (metrics.compactionCount > 0)
+            parts.push(`${metrics.compactionCount} compaction(s)`);
+        if (metrics.truncationCount > 0)
+            parts.push(`${metrics.truncationCount} truncation(s)`);
+        lines.push(`Context: ${parts.join(', ')}`);
+        lines.push('');
+    }
+    // Timeline
+    lines.push(hr);
+    lines.push('Timeline:');
+    lines.push(hr);
+    const filteredEvents = expand
+        ? metrics.timeline
+        : metrics.timeline.filter(e => e.noiseLevel !== 'noise');
+    if (filteredEvents.length === 0) {
+        lines.push('  (no events)');
+    }
+    else {
+        for (const event of filteredEvents) {
+            const ts = formatTimestamp(event.timestamp);
+            const icon = getTimelineEventIcon(event.type);
+            const summary = truncateToWidth(event.description, width - ts.length - 4);
+            lines.push(`${ts} ${icon} ${summary}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+// ── Markdown output ──
+/**
+ * Format aggregated metrics as a markdown report.
+ */
+function formatSessionMarkdown(metrics, options = {}) {
+    const expand = options.expand ?? false;
+    const sessionFileName = options.sessionFileName;
+    const lines = [];
+    // Title
+    lines.push('# Session Report');
+    lines.push('');
+    // Summary
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    if (sessionFileName) {
+        lines.push(`| Session file | \`${sessionFileName}\` |`);
+    }
+    lines.push(`| Started | ${metrics.sessionStartTime || 'N/A'} |`);
+    lines.push(`| Last event | ${metrics.lastEventTime || 'N/A'} |`);
+    lines.push(`| Duration | ${formatDuration(metrics.sessionStartTime, metrics.lastEventTime)} |`);
+    lines.push(`| Messages | ${metrics.messageCount} |`);
+    lines.push(`| Events | ${metrics.eventCount} |`);
+    lines.push(`| Model | ${metrics.currentModel || 'N/A'} |`);
+    lines.push(`| Provider | ${metrics.providerId || 'N/A'} |`);
+    lines.push('');
+    // Tokens
+    lines.push('## Tokens');
+    lines.push('');
+    lines.push(`| Category | Count |`);
+    lines.push(`|----------|-------|`);
+    lines.push(`| Input | ${fmtTokens(metrics.tokens.inputTokens)} |`);
+    lines.push(`| Output | ${fmtTokens(metrics.tokens.outputTokens)} |`);
+    lines.push(`| Cache write | ${fmtTokens(metrics.tokens.cacheWriteTokens)} |`);
+    lines.push(`| Cache read | ${fmtTokens(metrics.tokens.cacheReadTokens)} |`);
+    lines.push(`| Total | ${fmtTokens(metrics.tokens.inputTokens + metrics.tokens.outputTokens)} |`);
+    if (metrics.tokens.reportedCost > 0) {
+        lines.push(`| Cost | ${fmtCost(metrics.tokens.reportedCost)} |`);
+    }
+    lines.push('');
+    // Model stats
+    if (metrics.modelStats.length > 0) {
+        lines.push('## Models');
+        lines.push('');
+        lines.push(`| Model | Calls | Tokens | Cost |`);
+        lines.push(`|-------|-------|--------|------|`);
+        for (const m of metrics.modelStats) {
+            lines.push(`| ${m.model} | ${m.calls} | ${fmtTokens(m.tokens)} | ${fmtCost(m.cost)} |`);
+        }
+        lines.push('');
+    }
+    // Tool calls
+    if (metrics.toolStats.length > 0) {
+        lines.push('## Tool Calls');
+        lines.push('');
+        lines.push(`| Tool | Total | Failed | Avg Duration |`);
+        lines.push(`|------|-------|--------|--------------|`);
+        const sorted = [...metrics.toolStats].sort((a, b) => (b.successCount + b.failureCount) - (a.successCount + a.failureCount));
+        for (const t of sorted) {
+            const total = t.successCount + t.failureCount;
+            const avgMs = t.completedCount > 0 ? Math.round(t.totalDuration / t.completedCount) : 0;
+            lines.push(`| ${t.name} | ${total} | ${t.failureCount} | ${avgMs > 0 ? `${avgMs}ms` : '-'} |`);
+        }
+        lines.push('');
+    }
+    // Context events
+    if (metrics.compactionCount > 0 || metrics.truncationCount > 0) {
+        lines.push('## Context Management');
+        lines.push('');
+        if (metrics.compactionCount > 0) {
+            lines.push(`- **Compactions:** ${metrics.compactionCount}`);
+            for (const c of metrics.compactionEvents) {
+                lines.push(`  - At ${formatTimestamp(c.timestamp instanceof Date ? c.timestamp.toISOString() : String(c.timestamp))}: ${fmtTokens(c.contextBefore)} -> ${fmtTokens(c.contextAfter)} tokens`);
+            }
+        }
+        if (metrics.truncationCount > 0) {
+            lines.push(`- **Truncations:** ${metrics.truncationCount}`);
+        }
+        lines.push('');
+    }
+    // Subagents
+    if (metrics.subagents.length > 0) {
+        lines.push('## Subagents');
+        lines.push('');
+        lines.push(`| Type | Description | Status | Duration |`);
+        lines.push(`|------|-------------|--------|----------|`);
+        for (const s of metrics.subagents) {
+            const dur = s.durationMs ? `${Math.round(s.durationMs / 1000)}s` : '-';
+            lines.push(`| ${s.subagentType} | ${s.description} | ${s.status} | ${dur} |`);
+        }
+        lines.push('');
+    }
+    // Timeline
+    lines.push('## Timeline');
+    lines.push('');
+    const filteredEvents = expand
+        ? metrics.timeline
+        : metrics.timeline.filter(e => e.noiseLevel !== 'noise');
+    if (filteredEvents.length === 0) {
+        lines.push('_(no events)_');
+    }
+    else {
+        lines.push('```');
+        for (const event of filteredEvents) {
+            const ts = formatTimestamp(event.timestamp);
+            const icon = getTimelineEventIcon(event.type);
+            lines.push(`${ts} ${icon} ${event.description}`);
+        }
+        lines.push('```');
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+// ── Formatting helpers ──
+function formatHeader(metrics) {
+    const parts = [];
+    if (metrics.providerId)
+        parts.push(metrics.providerId);
+    if (metrics.currentModel)
+        parts.push(metrics.currentModel);
+    const duration = formatDuration(metrics.sessionStartTime, metrics.lastEventTime);
+    if (duration !== 'N/A')
+        parts.push(duration);
+    parts.push(`${metrics.messageCount} messages`);
+    parts.push(`${metrics.eventCount} events`);
+    return parts.join(' | ');
+}
+function formatTokenSummary(metrics) {
+    const t = metrics.tokens;
+    const total = t.inputTokens + t.outputTokens;
+    const parts = [
+        `Tokens: ${fmtTokens(total)} total`,
+        `(${fmtTokens(t.inputTokens)} in`,
+        `${fmtTokens(t.outputTokens)} out`,
+    ];
+    if (t.cacheReadTokens > 0)
+        parts.push(`${fmtTokens(t.cacheReadTokens)} cache-read`);
+    if (t.cacheWriteTokens > 0)
+        parts.push(`${fmtTokens(t.cacheWriteTokens)} cache-write`);
+    const line = parts.join(', ');
+    if (t.reportedCost > 0)
+        return `${line})  Cost: ${fmtCost(t.reportedCost)}`;
+    return line + ')';
+}
+/** @internal Exported for tests. */
+function fmtTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return String(n);
+}
+/** @internal Exported for tests. */
+function fmtCost(cost) {
+    if (cost <= 0)
+        return '$0.00';
+    if (cost < 0.01)
+        return `$${cost.toFixed(4)}`;
+    return `$${cost.toFixed(2)}`;
+}
+/** @internal Exported for tests. */
+function formatTimestamp(iso) {
+    try {
+        const d = new Date(iso);
+        if (isNaN(d.getTime()))
+            return '??:??:??';
+        const h = d.getHours().toString().padStart(2, '0');
+        const m = d.getMinutes().toString().padStart(2, '0');
+        const s = d.getSeconds().toString().padStart(2, '0');
+        return `${h}:${m}:${s}`;
+    }
+    catch {
+        return '??:??:??';
+    }
+}
+/** @internal Exported for tests. */
+function formatDuration(start, end) {
+    if (!start || !end)
+        return 'N/A';
+    try {
+        const ms = new Date(end).getTime() - new Date(start).getTime();
+        if (ms < 0)
+            return 'N/A';
+        const totalSec = Math.floor(ms / 1000);
+        const hours = Math.floor(totalSec / 3600);
+        const minutes = Math.floor((totalSec % 3600) / 60);
+        const seconds = totalSec % 60;
+        if (hours > 0)
+            return `${hours}h ${minutes}m ${seconds}s`;
+        if (minutes > 0)
+            return `${minutes}m ${seconds}s`;
+        return `${seconds}s`;
+    }
+    catch {
+        return 'N/A';
+    }
+}
+/** Map TimelineEvent.type to a display icon. */
+function getTimelineEventIcon(type) {
+    switch (type) {
+        case 'user_prompt': return '\u25b6'; // right-pointing triangle
+        case 'assistant_response': return '\u2726'; // four-pointed star
+        case 'tool_call': return '\u2699'; // gear
+        case 'tool_result': return '\u2190'; // left arrow
+        case 'compaction': return '\u21bb'; // clockwise arrow
+        case 'error': return '\u2718'; // heavy ballot X
+        case 'session_start': return '\u25cf'; // black circle
+        case 'session_end': return '\u25cb'; // white circle
+        default: return ' ';
+    }
+}
+function truncateToWidth(text, maxLen) {
+    if (maxLen < 10)
+        maxLen = 10;
+    const clean = text.replace(/\s+/g, ' ').trim();
+    if (clean.length <= maxLen)
+        return clean;
+    return clean.substring(0, maxLen - 3) + '...';
+}

package/dist/formatters/toolSummary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Rich tool summary formatters.
+ *
+ * Registry of per-tool formatters that produce contextual one-liner summaries.
+ * Replaces the generic field-fallback `summarizeToolInput()` with tool-specific
+ * formatting inspired by tail-claude's 19+ tool formatters.
+ *
+ * @module formatters/toolSummary
+ */
+declare function truncate(text: string, maxLen: number): string;
+/**
+ * Produces a contextual one-liner summary for a tool call.
+ *
+ * Uses a registry of per-tool formatters for known tools (Read, Write, Edit,
+ * Bash, Grep, Glob, Task, WebFetch, WebSearch, etc.) and falls back to
+ * generic field extraction for unknown tools.
+ *
+ * @param toolName - The canonical tool name (e.g., "Read", "Bash")
+ * @param input - The tool's input parameters
+ * @returns A human-readable one-liner summary (may be empty string)
+ */
+export declare function formatToolSummary(toolName: string, input: Record<string, unknown>): string;
+export { truncate };