@newrelic/preflight 0.0.1-pre.1 → 1.0.0

package/dist/metrics/recommendation-engine.js

@@ -0,0 +1,207 @@
+/**
+ * Unified Recommendation Engine — synthesizes all Phase 4 analyzers into
+ * a single prioritized, deduplicated recommendation list.
+ *
+ * Categories:
+ *   - cost_optimization  — from CostPerOutcomeAnalyzer
+ *   - efficiency         — from TrendAnalyzer
+ *   - prompt_engineering — from PromptFeedbackEngine
+ *   - claudemd           — from ClaudeMdTracker
+ *   - model_selection    — from TrendAnalyzer.detectModelMigrationImpact()
+ */
+import { createHash } from 'node:crypto';
+import { createLogger } from '../shared/index.js';
+const logger = createLogger('recommendation-engine');
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const PRIORITY_ORDER = { high: 0, medium: 1, low: 2 };
+// ---------------------------------------------------------------------------
+// RecommendationEngine
+// ---------------------------------------------------------------------------
+export class RecommendationEngine {
+    sessionStore;
+    trendAnalyzer;
+    collaborationProfiler;
+    claudeMdTracker;
+    promptFeedbackEngine;
+    costPerOutcomeAnalyzer;
+    taskDetector;
+    constructor(options) {
+        this.sessionStore = options.sessionStore;
+        this.trendAnalyzer = options.trendAnalyzer;
+        this.collaborationProfiler = options.collaborationProfiler;
+        this.claudeMdTracker = options.claudeMdTracker;
+        this.promptFeedbackEngine = options.promptFeedbackEngine;
+        this.costPerOutcomeAnalyzer = options.costPerOutcomeAnalyzer;
+        this.taskDetector = options.taskDetector;
+    }
+    /**
+     * Generate all recommendations from all sub-analyzers, deduplicate,
+     * sort by priority, and optionally limit to topN.
+     */
+    generateAllRecommendations(developer, options) {
+        const recs = [];
+        recs.push(...this.getCostRecommendations(developer, options));
+        recs.push(...this.getEfficiencyRecommendations(developer, options));
+        recs.push(...this.getPromptRecommendations(developer, options));
+        recs.push(...this.getClaudeMdRecommendations());
+        recs.push(...this.getModelRecommendations());
+        // Deduplicate by id
+        const seen = new Set();
+        const deduped = [];
+        for (const rec of recs) {
+            if (!seen.has(rec.id)) {
+                seen.add(rec.id);
+                deduped.push(rec);
+            }
+        }
+        // Sort by priority
+        deduped.sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 2) - (PRIORITY_ORDER[b.priority] ?? 2));
+        if (options?.topN != null && options.topN > 0) {
+            return deduped.slice(0, options.topN);
+        }
+        logger.debug('Recommendations generated', {
+            developer,
+            total: deduped.length,
+        });
+        return deduped;
+    }
+    /**
+     * Team-level recommendations aggregating patterns across developers.
+     */
+    generateTeamRecommendations(options) {
+        const recs = [];
+        const baseline = this.collaborationProfiler.computeTeamBaseline(options);
+        // High team-wide correction rate
+        const teamCorrectionPct = round((1 - baseline.dimensions.correctionRate) * 100, 0);
+        if (teamCorrectionPct > 30) {
+            recs.push(makeRec('efficiency', 'high', 'High team correction rate', 'The team average correction rate is high. Consider improving initial prompt context across the team.', `Team correction rate: ${teamCorrectionPct}%`));
+        }
+        // Low team autonomy
+        if (baseline.dimensions.autonomy < 0.5) {
+            recs.push(makeRec('prompt_engineering', 'medium', 'Low team autonomy', 'The team has low autonomy scores. Consider team-wide adoption of /plan mode for complex tasks.', `Team autonomy: ${round(baseline.dimensions.autonomy, 2)}`));
+        }
+        return recs;
+    }
+    /**
+     * Emit recommendation metrics to New Relic.
+     */
+    emitMetrics(aggregator, developer, options) {
+        const recs = this.generateAllRecommendations(developer, options);
+        for (const rec of recs) {
+            aggregator.record('ai.recommendation', 1, {
+                developer,
+                category: rec.category,
+                priority: rec.priority,
+            });
+        }
+        logger.debug('Recommendation metrics emitted', {
+            developer,
+            count: recs.length,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Sub-analyzer recommendation collectors
+    // -------------------------------------------------------------------------
+    getCostRecommendations(_developer, _options) {
+        const recs = [];
+        const completed = this.taskDetector?.getCompletedTasks() ?? [];
+        const current = this.taskDetector?.getCurrentTask();
+        const tasks = current ? [...completed, current] : completed;
+        if (tasks.length === 0)
+            return recs;
+        const attribution = this.costPerOutcomeAnalyzer.attributeCosts(tasks);
+        // High waste ratio
+        if (attribution.wasteRatio > 0.2) {
+            const wastePct = round(attribution.wasteRatio * 100, 0);
+            recs.push(makeRec('cost_optimization', 'high', 'High failed attempt ratio', 'Failed attempts represent a significant portion of spend. Consider breaking complex tasks into smaller steps.', `Failed attempts: ${wastePct}% of total cost ($${round(attribution.costPerFailedAttempt, 2)} avg per failed attempt)`, `Reducing failed attempts by half could save ~$${round((attribution.costPerFailedAttempt * (attribution.outcomeDistribution['failed_attempt']?.count ?? 0)) / 2, 2)}`));
+        }
+        // Expensive investigations
+        if (attribution.costPerInvestigation > 2) {
+            recs.push(makeRec('cost_optimization', 'medium', 'Expensive investigation tasks', 'Investigation tasks cost more than expected. Consider using Grep/Glob before asking AI to explore.', `Investigation tasks cost $${round(attribution.costPerInvestigation, 2)} avg`));
+        }
+        return recs;
+    }
+    getEfficiencyRecommendations(developer, options) {
+        const recs = [];
+        const trends = this.trendAnalyzer.computeTrends({
+            since: options?.since,
+            developer,
+        });
+        const effTrend = trends.weeklyEfficiencyTrend;
+        if (effTrend.length >= 2) {
+            const latest = effTrend[effTrend.length - 1];
+            const previous = effTrend[effTrend.length - 2];
+            const drop = previous.value - latest.value;
+            if (drop > 0.1) {
+                const dropPct = round(drop * 100, 0);
+                recs.push(makeRec('efficiency', 'high', 'Efficiency score dropped', `Your efficiency score dropped ${dropPct}% from ${previous.week} to ${latest.week}. Check for increased anti-patterns.`, `Efficiency: ${round(previous.value, 2)} → ${round(latest.value, 2)}`));
+            }
+        }
+        return recs;
+    }
+    getPromptRecommendations(developer, options) {
+        const promptRecs = this.promptFeedbackEngine.generatePromptRecommendations(developer, options);
+        return promptRecs.map((pr) => makeRec('prompt_engineering', pr.priority, pr.category, pr.message, pr.evidence, pr.estimatedImpact));
+    }
+    getClaudeMdRecommendations() {
+        const recs = [];
+        const changes = this.claudeMdTracker.getChanges();
+        if (changes.length > 0) {
+            const latestChange = changes[changes.length - 1];
+            const impact = this.claudeMdTracker.computeImpact(latestChange.timestamp);
+            if (impact.verdict.startsWith('Negative')) {
+                recs.push(makeRec('claudemd', 'high', 'Negative CLAUDE.md impact', 'Recent CLAUDE.md change degraded metrics. Consider reverting or refining the changes.', `${impact.verdict}. Efficiency delta: ${impact.deltas.efficiencyScore?.percentChange ?? 'N/A'}%`));
+            }
+            if (impact.contextTokensForClaudeMd !== null && impact.contextTokensForClaudeMd > 3000) {
+                recs.push(makeRec('claudemd', 'medium', 'Large CLAUDE.md context cost', `CLAUDE.md consumes ~${impact.contextTokensForClaudeMd} tokens per turn. Consider condensing rarely-used sections.`, `${impact.contextTokensForClaudeMd} tokens/turn`));
+            }
+        }
+        return recs;
+    }
+    getModelRecommendations() {
+        const recs = [];
+        const sessions = this.sessionStore.loadAllSessions();
+        const models = new Set(sessions.map((s) => s.model).filter(Boolean));
+        if (models.size >= 2) {
+            const modelArr = [...models];
+            const comparison = this.trendAnalyzer.detectModelMigrationImpact(modelArr[0], modelArr[1]);
+            if (comparison.modelASessionCount >= 2 &&
+                comparison.modelBSessionCount >= 2 &&
+                comparison.modelACost > 0 &&
+                comparison.modelBCost > 0) {
+                const costRatio = round(comparison.modelACost / comparison.modelBCost, 1);
+                const effA = comparison.modelAEfficiency ?? 0;
+                const effB = comparison.modelBEfficiency ?? 0;
+                const effDiff = round(Math.abs(effA - effB) * 100, 0);
+                const actualRatio = costRatio > 1 ? costRatio : 1 / costRatio;
+                if (actualRatio > 2 && effDiff < 15) {
+                    const cheaper = costRatio > 1 ? modelArr[1] : modelArr[0];
+                    recs.push(makeRec('model_selection', 'medium', 'Cost-inefficient model usage', `One model costs ${actualRatio}x more but only improves efficiency by ${effDiff}%. Consider using ${cheaper} for routine tasks.`, `${modelArr[0]}: $${round(comparison.modelACost, 2)}/session, ${modelArr[1]}: $${round(comparison.modelBCost, 2)}/session`));
+                }
+            }
+        }
+        return recs;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeRec(category, priority, title, detail, evidence, estimatedSavings) {
+    const hash = createHash('sha256').update(`${category}:${title}`).digest('hex').slice(0, 12);
+    return {
+        id: `rec-${category}-${hash}`,
+        category,
+        priority,
+        title,
+        detail,
+        evidence,
+        ...(estimatedSavings != null && { estimatedSavings }),
+    };
+}
+function round(value, decimals) {
+    const factor = Math.pow(10, decimals);
+    return Math.round(value * factor) / factor;
+}
+//# sourceMappingURL=recommendation-engine.js.map

package/dist/metrics/recommendation-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-engine.js","sourceRoot":"","sources":["../../src/metrics/recommendation-engine.ts"],"names":[],"mappings":"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"}

package/dist/metrics/retry-detector.d.ts

@@ -0,0 +1,43 @@
+import type { MetricAggregator } from '../shared/index.js';
+import type { ToolCallRecord } from '../storage/types.js';
+export interface ThrashingAlert {
+    readonly toolName: string;
+    readonly occurrences: number;
+    readonly windowSize: number;
+    readonly similarity: number;
+    readonly tokensWastedEstimate: number;
+    readonly timestamp: number;
+}
+export interface RetryDetectorMetrics {
+    readonly alerts: readonly ThrashingAlert[];
+    readonly totalTokensWasted: number;
+    readonly totalAlertsEmitted: number;
+}
+export interface RetryDetectorOptions {
+    readonly minOccurrences?: number;
+    readonly windowSize?: number;
+    readonly similarityThreshold?: number;
+    readonly onAlert?: (alert: ThrashingAlert) => void;
+}
+export declare function normalizedLevenshteinSimilarity(a: string, b: string): number;
+export declare class RetryDetector {
+    private readonly minOccurrences;
+    private readonly windowSize;
+    private readonly similarityThreshold;
+    private readonly onAlert;
+    private readonly recentCalls;
+    private readonly alerts;
+    private totalTokensWasted;
+    private readonly firedKeys;
+    private callCounter;
+    constructor(options?: RetryDetectorOptions);
+    recordToolCall(record: ToolCallRecord): ThrashingAlert | null;
+    getMetrics(): RetryDetectorMetrics;
+    emitMetrics(aggregator: MetricAggregator): void;
+    reset(_sessionId: string): void;
+    private checkWindow;
+    private computeGroupSimilarity;
+    private serializeInput;
+    private estimateTokensWasted;
+}
+//# sourceMappingURL=retry-detector.d.ts.map

package/dist/metrics/retry-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-detector.d.ts","sourceRoot":"","sources":["../../src/metrics/retry-detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACpD;AAeD,wBAAgB,+BAA+B,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAa5E;AA+BD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IAEnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,iBAAiB,CAAK;IAE9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,WAAW,CAAK;gBAEZ,OAAO,CAAC,EAAE,oBAAoB;IAO1C,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,GAAG,IAAI;IAY7D,UAAU,IAAI,oBAAoB;IAQlC,WAAW,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAO/C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAQ/B,OAAO,CAAC,WAAW;IAyDnB,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,oBAAoB;CAO7B"}

package/dist/metrics/retry-detector.js

@@ -0,0 +1,179 @@
+import { createLogger } from '../shared/index.js';
+const logger = createLogger('retry-detector');
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_MIN_OCCURRENCES = 3;
+const DEFAULT_WINDOW_SIZE = 5;
+const DEFAULT_SIMILARITY_THRESHOLD = 0.8;
+const BYTES_PER_TOKEN_ESTIMATE = 4;
+// ---------------------------------------------------------------------------
+// Levenshtein similarity
+// ---------------------------------------------------------------------------
+export function normalizedLevenshteinSimilarity(a, b) {
+    if (a === b)
+        return 1;
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    // Truncate long strings to avoid O(n^2) on massive inputs
+    const limit = 2000;
+    const sa = a.length > limit ? a.slice(0, limit) : a;
+    const sb = b.length > limit ? b.slice(0, limit) : b;
+    const effectiveMax = Math.max(sa.length, sb.length);
+    const distance = levenshteinDistance(sa, sb);
+    return 1 - distance / effectiveMax;
+}
+function levenshteinDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    // Single-row DP for space efficiency
+    const row = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        row[j] = j;
+    for (let i = 1; i <= m; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const temp = row[j];
+            if (a[i - 1] === b[j - 1]) {
+                row[j] = prev;
+            }
+            else {
+                row[j] = 1 + Math.min(prev, row[j], row[j - 1]);
+            }
+            prev = temp;
+        }
+    }
+    return row[n];
+}
+// ---------------------------------------------------------------------------
+// RetryDetector
+// ---------------------------------------------------------------------------
+export class RetryDetector {
+    minOccurrences;
+    windowSize;
+    similarityThreshold;
+    onAlert;
+    recentCalls = [];
+    alerts = [];
+    totalTokensWasted = 0;
+    // Track which tool+window combos already fired to avoid spamming
+    firedKeys = new Set();
+    callCounter = 0;
+    constructor(options) {
+        this.minOccurrences = options?.minOccurrences ?? DEFAULT_MIN_OCCURRENCES;
+        this.windowSize = options?.windowSize ?? DEFAULT_WINDOW_SIZE;
+        this.similarityThreshold = options?.similarityThreshold ?? DEFAULT_SIMILARITY_THRESHOLD;
+        this.onAlert = options?.onAlert ?? null;
+    }
+    recordToolCall(record) {
+        this.recentCalls.push(record);
+        this.callCounter++;
+        // Only keep the window we need
+        if (this.recentCalls.length > this.windowSize * 2) {
+            this.recentCalls.splice(0, this.recentCalls.length - this.windowSize * 2);
+        }
+        return this.checkWindow();
+    }
+    getMetrics() {
+        return {
+            alerts: this.alerts,
+            totalTokensWasted: this.totalTokensWasted,
+            totalAlertsEmitted: this.alerts.length,
+        };
+    }
+    emitMetrics(aggregator) {
+        if (this.alerts.length > 0) {
+            aggregator.record('ai.retry.alerts_total', this.alerts.length);
+            aggregator.record('ai.retry.tokens_wasted', this.totalTokensWasted);
+        }
+    }
+    reset(_sessionId) {
+        this.recentCalls.length = 0;
+        this.alerts.length = 0;
+        this.totalTokensWasted = 0;
+        this.firedKeys.clear();
+        this.callCounter = 0;
+    }
+    checkWindow() {
+        const window = this.recentCalls.slice(-this.windowSize);
+        if (window.length < this.minOccurrences)
+            return null;
+        // Group calls by tool name within the window
+        const byTool = new Map();
+        for (const call of window) {
+            const arr = byTool.get(call.toolName) ?? [];
+            arr.push(call);
+            byTool.set(call.toolName, arr);
+        }
+        for (const [toolName, calls] of byTool) {
+            if (calls.length < this.minOccurrences)
+                continue;
+            // Check: either all failed, or inputs are highly similar
+            const allFailed = calls.every((c) => !c.success);
+            const similarity = this.computeGroupSimilarity(calls);
+            const isSimilar = similarity >= this.similarityThreshold;
+            if (!allFailed && !isSimilar)
+                continue;
+            // Dedupe: use the call counter so alerts can fire again after new calls arrive
+            const dedupeKey = `${toolName}:${this.callCounter}`;
+            if (this.firedKeys.has(dedupeKey))
+                continue;
+            this.firedKeys.add(dedupeKey);
+            const tokensWasted = this.estimateTokensWasted(calls);
+            const alert = {
+                toolName,
+                occurrences: calls.length,
+                windowSize: this.windowSize,
+                similarity,
+                tokensWastedEstimate: tokensWasted,
+                timestamp: Date.now(),
+            };
+            this.alerts.push(alert);
+            this.totalTokensWasted += tokensWasted;
+            logger.warn('Thrashing detected', {
+                tool: toolName,
+                occurrences: calls.length,
+                similarity: Math.round(similarity * 100),
+                tokensWasted,
+            });
+            if (this.onAlert) {
+                this.onAlert(alert);
+            }
+            return alert;
+        }
+        return null;
+    }
+    computeGroupSimilarity(calls) {
+        if (calls.length < 2)
+            return 0;
+        const inputs = calls.map((c) => this.serializeInput(c));
+        let totalSimilarity = 0;
+        let comparisons = 0;
+        // Compare each pair against the first (reference) input
+        const reference = inputs[0];
+        for (let i = 1; i < inputs.length; i++) {
+            totalSimilarity += normalizedLevenshteinSimilarity(reference, inputs[i]);
+            comparisons++;
+        }
+        return comparisons > 0 ? totalSimilarity / comparisons : 0;
+    }
+    serializeInput(record) {
+        const { id: _id, sessionId: _s, timestamp: _t, durationMs: _d, success: _su, errorType: _e, error: _er, inputSizeBytes: _is, outputSizeBytes: _os, inputHash: _ih, toolUseId: _tu, ...rest } = record;
+        try {
+            return JSON.stringify(rest, null, 0);
+        }
+        catch {
+            return '';
+        }
+    }
+    estimateTokensWasted(calls) {
+        let totalBytes = 0;
+        for (const call of calls) {
+            totalBytes += (call.inputSizeBytes ?? 0) + (call.outputSizeBytes ?? 0);
+        }
+        return Math.ceil(totalBytes / BYTES_PER_TOKEN_ESTIMATE);
+    }
+}
+//# sourceMappingURL=retry-detector.js.map

package/dist/metrics/retry-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-detector.js","sourceRoot":"","sources":["../../src/metrics/retry-detector.ts"],"names":[],"mappings":"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"}

package/dist/metrics/session-tracker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Session Metrics Aggregation — maintains running aggregates for a coding session.
+ *
+ * Tracks tool call counts, durations, success rates, file access patterns,
+ * and provides both a plain snapshot (for MCP tool responses) and metric
+ * emission (for NR ingestion via MetricAggregator).
+ */
+import type { MetricAggregator } from '../shared/index.js';
+import type { ToolCallRecord } from '../storage/types.js';
+export interface DurationStats {
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    p95: number;
+}
+export interface TimelineEntry {
+    timestamp: number;
+    toolName: string;
+    durationMs: number | null;
+    success: boolean;
+}
+export interface SessionMetrics {
+    sessionId: string;
+    sessionName: string | null;
+    sessionStartTime: number;
+    sessionDurationMs: number;
+    toolCallCount: number;
+    toolCallCountByTool: Record<string, number>;
+    toolDurationMsByTool: Record<string, DurationStats>;
+    toolSuccessRate: number | null;
+    toolSuccessRateByTool: Record<string, number>;
+    toolErrorCount: number;
+    toolErrorsByType: Record<string, number>;
+    uniqueFilesRead: number;
+    uniqueFilesWritten: number;
+    bashCommandsRun: number;
+    bashExitCodes: Record<string, number>;
+    /** Per-bash-category call counts (e.g. git, test-runner, build). Only populated for Bash tool calls. */
+    bashCallsByCategory: Record<string, number>;
+    searchQueries: number;
+    toolCallTimeline: TimelineEntry[];
+    /** True when the timeline was capped at MAX_TIMELINE_ENTRIES; callers should not assume they have the full history. */
+    timelineTruncated: boolean;
+    /** Lifetime total of timeline entries, including those dropped by the cap. */
+    timelineEntryCount: number;
+}
+export declare function computeP95(values: number[]): number;
+export declare function computeDurationStats(durations: number[]): DurationStats;
+export declare class SessionTracker {
+    private sessionId;
+    private sessionName;
+    private sessionStartTime;
+    private toolCallCount;
+    private toolErrorCount;
+    private successCount;
+    private bashCommandsRun;
+    private searchQueries;
+    private readonly toolCallCountByTool;
+    private readonly toolDurationsByTool;
+    private readonly toolSuccessByTool;
+    private readonly toolErrorsByType;
+    private readonly filesRead;
+    private readonly filesWritten;
+    private readonly bashExitCodes;
+    private readonly bashCallsByCategory;
+    private timeline;
+    private timelineEntryCount;
+    constructor(sessionId: string);
+    recordToolCall(record: ToolCallRecord): void;
+    getMetrics(): SessionMetrics;
+    emitMetrics(aggregator: MetricAggregator): void;
+    reset(sessionId: string): void;
+}
+//# sourceMappingURL=session-tracker.d.ts.map

package/dist/metrics/session-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-tracker.d.ts","sourceRoot":"","sources":["../../src/metrics/session-tracker.ts"],"names":[],"mappings":"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"}