@newrelic/preflight 0.0.1-pre.1 → 1.0.0

package/dist/metrics/api-failure-tracker.d.ts.map

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

package/dist/metrics/api-failure-tracker.js

@@ -0,0 +1,202 @@
+import { createLogger } from '../shared/index.js';
+import { computePercentile } from './percentile.js';
+const logger = createLogger('api-failure-tracker');
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_THROTTLE_THRESHOLD = 3;
+const DEFAULT_THROTTLE_WINDOW_MINUTES = 10;
+const DEFAULT_MAX_EVENTS = 500;
+const DEFAULT_COST_PER_TOKEN_USD = 0.000003;
+// ---------------------------------------------------------------------------
+// ApiFailureTracker
+// ---------------------------------------------------------------------------
+export class ApiFailureTracker {
+    throttleThreshold;
+    throttleWindowMinutes;
+    maxEvents;
+    costPerTokenUsd;
+    onThrottleAlert;
+    events = [];
+    throttleAlerts = [];
+    totalRequests = 0;
+    latenciesByModel = new Map();
+    constructor(options) {
+        this.throttleThreshold = options?.throttleAlertThreshold ?? DEFAULT_THROTTLE_THRESHOLD;
+        this.throttleWindowMinutes =
+            options?.throttleAlertWindowMinutes ?? DEFAULT_THROTTLE_WINDOW_MINUTES;
+        this.maxEvents = options?.maxEvents ?? DEFAULT_MAX_EVENTS;
+        this.costPerTokenUsd = options?.costPerTokenUsd ?? DEFAULT_COST_PER_TOKEN_USD;
+        this.onThrottleAlert = options?.onThrottleAlert ?? null;
+    }
+    recordRequest(model, latencyMs) {
+        this.totalRequests++;
+        if (!this.latenciesByModel.has(model) && this.latenciesByModel.size >= 50) {
+            return; // Cap total models to prevent unbounded memory under high model churn
+        }
+        const arr = this.latenciesByModel.get(model) ?? [];
+        arr.push(latencyMs);
+        if (arr.length > this.maxEvents) {
+            arr.shift();
+        }
+        this.latenciesByModel.set(model, arr);
+    }
+    recordFailure(event) {
+        const totalTurns = event.totalTurnsInSession ?? 30;
+        const phase = this.computePhase(event.turnNumber, totalTurns);
+        const failure = {
+            errorType: event.errorType,
+            model: event.model,
+            timestamp: Date.now(),
+            turnNumber: event.turnNumber,
+            tokensInFlight: event.tokensInFlight,
+            recoveryMs: event.recoveryMs ?? null,
+            retryCount: event.retryCount ?? 0,
+            recoverySucceeded: event.recoverySucceeded ?? null,
+            sessionPhase: phase,
+            duringToolExecution: event.duringToolExecution ?? false,
+        };
+        this.events.push(failure);
+        if (this.events.length > this.maxEvents) {
+            this.events.shift();
+        }
+        this.checkThrottleRate(event.model);
+        return failure;
+    }
+    getMetrics() {
+        const byErrorType = {
+            rate_limit: 0,
+            timeout: 0,
+            connection_error: 0,
+            server_error: 0,
+            context_length_exceeded: 0,
+            authentication: 0,
+            unknown: 0,
+        };
+        const byPhase = { early: 0, middle: 0, late: 0 };
+        let totalTokensLost = 0;
+        const recoveryTimes = [];
+        for (const event of this.events) {
+            byErrorType[event.errorType]++;
+            byPhase[event.sessionPhase]++;
+            totalTokensLost += event.tokensInFlight;
+            if (event.recoveryMs !== null) {
+                recoveryTimes.push(event.recoveryMs);
+            }
+        }
+        const meanRecovery = recoveryTimes.length > 0
+            ? Math.round(recoveryTimes.reduce((a, b) => a + b, 0) / recoveryTimes.length)
+            : null;
+        return {
+            totalFailures: this.events.length,
+            byErrorType,
+            byModel: this.computeModelScorecards(),
+            bySessionPhase: byPhase,
+            totalTokensLost,
+            totalEstimatedCostLostUsd: Math.round(totalTokensLost * this.costPerTokenUsd * 10000) / 10000,
+            meanTimeToRecoveryMs: meanRecovery,
+            throttleAlerts: this.throttleAlerts,
+            recentFailures: this.events.slice(-20),
+        };
+    }
+    emitMetrics(aggregator) {
+        const metrics = this.getMetrics();
+        aggregator.record('ai.api.failures_total', metrics.totalFailures);
+        aggregator.record('ai.api.tokens_lost', metrics.totalTokensLost);
+        for (const [type, count] of Object.entries(metrics.byErrorType)) {
+            if (count > 0) {
+                aggregator.record('ai.api.failure_by_type', count, { error_type: type });
+            }
+        }
+        for (const [model, scorecard] of Object.entries(metrics.byModel)) {
+            if (scorecard.failureRate !== null) {
+                aggregator.record('ai.api.model_failure_rate', scorecard.failureRate, { model });
+            }
+            if (scorecard.meanRecoveryMs !== null) {
+                aggregator.record('ai.api.model_mean_recovery_ms', scorecard.meanRecoveryMs, { model });
+            }
+        }
+    }
+    reset(_sessionId) {
+        this.events.length = 0;
+        this.throttleAlerts.length = 0;
+        this.totalRequests = 0;
+        this.latenciesByModel.clear();
+    }
+    computePhase(turnNumber, totalTurns) {
+        const ratio = turnNumber / totalTurns;
+        if (ratio <= 0.33)
+            return 'early';
+        if (ratio <= 0.67)
+            return 'middle';
+        return 'late';
+    }
+    checkThrottleRate(model) {
+        const windowMs = this.throttleWindowMinutes * 60 * 1000;
+        const now = Date.now();
+        const recentThrottles = this.events.filter((e) => e.model === model && e.errorType === 'rate_limit' && now - e.timestamp <= windowMs);
+        if (recentThrottles.length >= this.throttleThreshold) {
+            // Dedupe: don't fire if we already alerted for this model in this window
+            const alreadyAlerted = this.throttleAlerts.some((a) => a.model === model && now - a.timestamp <= windowMs);
+            if (alreadyAlerted)
+                return;
+            const alert = {
+                model,
+                count: recentThrottles.length,
+                windowMinutes: this.throttleWindowMinutes,
+                timestamp: now,
+            };
+            this.throttleAlerts.push(alert);
+            logger.warn('Throttle rate exceeded', {
+                model,
+                count: alert.count,
+                windowMinutes: alert.windowMinutes,
+            });
+            if (this.onThrottleAlert) {
+                this.onThrottleAlert(alert);
+            }
+        }
+    }
+    computeModelScorecards() {
+        const scorecards = {};
+        // Group events by model
+        const eventsByModel = new Map();
+        for (const event of this.events) {
+            const arr = eventsByModel.get(event.model) ?? [];
+            arr.push(event);
+            eventsByModel.set(event.model, arr);
+        }
+        for (const [model, modelEvents] of eventsByModel) {
+            const latencies = this.latenciesByModel.get(model) ?? [];
+            const sortedLatencies = [...latencies].sort((a, b) => a - b);
+            // Only use latencies.length as total — modelEvents are failures only, so
+            // using them as both numerator and denominator would always give rate=1.0.
+            const totalModelRequests = latencies.length;
+            const throttles = modelEvents.filter((e) => e.errorType === 'rate_limit');
+            const recoveryTimes = modelEvents
+                .map((e) => e.recoveryMs)
+                .filter((r) => r !== null);
+            const tokensLost = modelEvents.reduce((sum, e) => sum + e.tokensInFlight, 0);
+            scorecards[model] = {
+                model,
+                totalRequests: totalModelRequests,
+                failureCount: modelEvents.length,
+                failureRate: totalModelRequests > 0
+                    ? Math.round((modelEvents.length / totalModelRequests) * 1000) / 1000
+                    : null,
+                throttleCount: throttles.length,
+                throttleFrequency: totalModelRequests > 0
+                    ? Math.round((throttles.length / totalModelRequests) * 1000) / 1000
+                    : null,
+                meanRecoveryMs: recoveryTimes.length > 0
+                    ? Math.round(recoveryTimes.reduce((a, b) => a + b, 0) / recoveryTimes.length)
+                    : null,
+                p95LatencyMs: sortedLatencies.length > 0 ? (computePercentile(sortedLatencies, 0.95) ?? null) : null,
+                tokensLost,
+                estimatedCostLostUsd: Math.round(tokensLost * this.costPerTokenUsd * 10000) / 10000,
+            };
+        }
+        return scorecards;
+    }
+}
+//# sourceMappingURL=api-failure-tracker.js.map

package/dist/metrics/api-failure-tracker.js.map

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

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

@@ -0,0 +1,60 @@
+export type BudgetPeriod = 'session' | 'daily' | 'weekly';
+export interface BudgetThresholdEvent {
+    readonly period: BudgetPeriod;
+    readonly thresholdPct: 50 | 80 | 100;
+    readonly spentUsd: number;
+    readonly budgetUsd: number;
+    readonly timestamp: number;
+}
+export interface BudgetStatus {
+    readonly session: {
+        readonly budgetUsd: number | null;
+        readonly spentUsd: number;
+        readonly remainingUsd: number | null;
+        readonly pctUsed: number | null;
+        readonly exceeded: boolean;
+    };
+    readonly daily: {
+        readonly budgetUsd: number | null;
+        readonly spentUsd: number;
+        readonly remainingUsd: number | null;
+        readonly pctUsed: number | null;
+        readonly exceeded: boolean;
+    };
+    readonly weekly: {
+        readonly budgetUsd: number | null;
+        readonly spentUsd: number;
+        readonly remainingUsd: number | null;
+        readonly pctUsed: number | null;
+        readonly exceeded: boolean;
+    };
+    readonly alerts: readonly BudgetThresholdEvent[];
+}
+export interface BudgetOptions {
+    readonly sessionBudgetUsd: number | null;
+    readonly dailyBudgetUsd: number | null;
+    readonly weeklyBudgetUsd: number | null;
+    readonly onThreshold?: (event: BudgetThresholdEvent) => void;
+}
+export declare class BudgetTracker {
+    private readonly sessionBudgetUsd;
+    private readonly dailyBudgetUsd;
+    private readonly weeklyBudgetUsd;
+    private onThreshold;
+    private sessionSpentUsd;
+    private dailySpentUsd;
+    private weeklySpentUsd;
+    private firedThresholds;
+    private alerts;
+    constructor(options: BudgetOptions);
+    setOnThreshold(callback: (event: BudgetThresholdEvent) => void): void;
+    updateCost(sessionCostUsd: number, dailyCostUsd: number, weeklyCostUsd: number): void;
+    private currentPeriodId;
+    private pruneStaleThresholds;
+    private checkThresholds;
+    private checkPeriod;
+    getStatus(): BudgetStatus;
+    private buildPeriodStatus;
+    resetSession(): void;
+}
+//# sourceMappingURL=budget-tracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget-tracker.d.ts","sourceRoot":"","sources":["../../src/metrics/budget-tracker.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAC9D;AAMD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgB;IAChD,OAAO,CAAC,WAAW,CAAsD;IAEzE,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAG3B,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,MAAM,CAA8B;gBAEhC,OAAO,EAAE,aAAa;IAOlC,cAAc,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,IAAI;IAIrE,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAOrF,OAAO,CAAC,eAAe;IA0BvB,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,WAAW;IAwBnB,SAAS,IAAI,YAAY;IASzB,OAAO,CAAC,iBAAiB;IAqBzB,YAAY,IAAI,IAAI;CAOrB"}

package/dist/metrics/budget-tracker.js

@@ -0,0 +1,130 @@
+const THRESHOLD_LEVELS = [50, 80, 100];
+const MAX_ALERTS = 100;
+export class BudgetTracker {
+    sessionBudgetUsd;
+    dailyBudgetUsd;
+    weeklyBudgetUsd;
+    onThreshold;
+    sessionSpentUsd = 0;
+    dailySpentUsd = 0;
+    weeklySpentUsd = 0;
+    // Map from threshold key (e.g., "daily_50") to period ID (e.g., "day:2026-05-27")
+    firedThresholds = new Map();
+    alerts = [];
+    constructor(options) {
+        this.sessionBudgetUsd = options.sessionBudgetUsd;
+        this.dailyBudgetUsd = options.dailyBudgetUsd;
+        this.weeklyBudgetUsd = options.weeklyBudgetUsd;
+        this.onThreshold = options.onThreshold;
+    }
+    setOnThreshold(callback) {
+        this.onThreshold = callback;
+    }
+    updateCost(sessionCostUsd, dailyCostUsd, weeklyCostUsd) {
+        this.sessionSpentUsd = sessionCostUsd;
+        this.dailySpentUsd = dailyCostUsd;
+        this.weeklySpentUsd = weeklyCostUsd;
+        this.checkThresholds();
+    }
+    currentPeriodId(period) {
+        const now = new Date();
+        if (period === 'session') {
+            return 'session:infinite';
+        }
+        if (period === 'daily') {
+            const year = now.getFullYear();
+            const month = String(now.getMonth() + 1).padStart(2, '0');
+            const day = String(now.getDate()).padStart(2, '0');
+            return `day:${year}-${month}-${day}`;
+        }
+        if (period === 'weekly') {
+            // ISO 8601 week number — correct across year boundaries.
+            // The ISO week year can differ from the calendar year in early Jan / late Dec.
+            const d = new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+            const dayOfWeek = d.getUTCDay() || 7; // 1=Mon … 7=Sun
+            d.setUTCDate(d.getUTCDate() + 4 - dayOfWeek); // nearest Thursday
+            const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+            const week = Math.ceil(((d.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7);
+            const isoYear = d.getUTCFullYear();
+            const weekNum = String(week).padStart(2, '0');
+            return `week:${isoYear}-W${weekNum}`;
+        }
+        return '';
+    }
+    pruneStaleThresholds() {
+        for (const [key, periodId] of this.firedThresholds.entries()) {
+            const period = key.split('_')[0];
+            const currentPeriod = this.currentPeriodId(period);
+            if (periodId !== currentPeriod) {
+                this.firedThresholds.delete(key);
+            }
+        }
+    }
+    checkThresholds() {
+        this.pruneStaleThresholds();
+        this.checkPeriod('session', this.sessionSpentUsd, this.sessionBudgetUsd);
+        this.checkPeriod('daily', this.dailySpentUsd, this.dailyBudgetUsd);
+        this.checkPeriod('weekly', this.weeklySpentUsd, this.weeklyBudgetUsd);
+    }
+    checkPeriod(period, spent, budget) {
+        if (budget === null || budget <= 0)
+            return;
+        const pctUsed = (spent / budget) * 100;
+        const currentPeriod = this.currentPeriodId(period);
+        for (const level of THRESHOLD_LEVELS) {
+            const key = `${period}_${level}`;
+            if (pctUsed >= level && !this.firedThresholds.has(key)) {
+                this.firedThresholds.set(key, currentPeriod);
+                const event = {
+                    period,
+                    thresholdPct: level,
+                    spentUsd: spent,
+                    budgetUsd: budget,
+                    timestamp: Date.now(),
+                };
+                this.alerts.push(event);
+                if (this.alerts.length > MAX_ALERTS) {
+                    this.alerts.shift();
+                }
+                this.onThreshold?.(event);
+            }
+        }
+    }
+    getStatus() {
+        return {
+            session: this.buildPeriodStatus(this.sessionSpentUsd, this.sessionBudgetUsd),
+            daily: this.buildPeriodStatus(this.dailySpentUsd, this.dailyBudgetUsd),
+            weekly: this.buildPeriodStatus(this.weeklySpentUsd, this.weeklyBudgetUsd),
+            alerts: [...this.alerts],
+        };
+    }
+    buildPeriodStatus(spent, budget) {
+        if (budget === null) {
+            return {
+                budgetUsd: null,
+                spentUsd: spent,
+                remainingUsd: null,
+                pctUsed: null,
+                exceeded: false,
+            };
+        }
+        const remaining = Math.max(0, budget - spent);
+        const pctUsed = Math.round((spent / budget) * 1000) / 10;
+        return {
+            budgetUsd: budget,
+            spentUsd: spent,
+            remainingUsd: remaining,
+            pctUsed,
+            exceeded: spent > budget,
+        };
+    }
+    resetSession() {
+        this.sessionSpentUsd = 0;
+        for (const key of this.firedThresholds.keys()) {
+            if (key.startsWith('session_'))
+                this.firedThresholds.delete(key);
+        }
+        this.alerts = this.alerts.filter((a) => a.period !== 'session');
+    }
+}
+//# sourceMappingURL=budget-tracker.js.map

package/dist/metrics/budget-tracker.js.map

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

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

@@ -0,0 +1,108 @@
+/**
+ * CLAUDE.md Change Impact Tracking — detects modifications to CLAUDE.md
+ * and `.claude/` configuration files, computes before/after metric deltas
+ * from stored sessions, estimates token context costs, and emits NR metrics.
+ *
+ * Change detection:
+ *   - Within a session: Write/Edit tool calls targeting CLAUDE.md or .claude/
+ *   - Between sessions: SHA-256 hash comparison of CLAUDE.md content
+ *
+ * Impact analysis:
+ *   - Partitions sessions into before/after windows around a change timestamp
+ *   - Compares efficiency, cost, correction rate, tool calls per task, and
+ *     task success rate across the two windows
+ *   - Generates a verdict string: "Positive impact", "Negative impact", or
+ *     "Mixed impact" with the top changed metrics
+ */
+import type { MetricAggregator } from '../shared/index.js';
+import type { SessionStore } from '../storage/session-store.js';
+import type { ToolCallRecord } from '../storage/types.js';
+export interface ClaudeMdChange {
+    readonly timestamp: number;
+    readonly sessionId: string;
+    readonly filePath: string;
+    readonly changeType: 'created' | 'modified' | 'deleted';
+    readonly diffSummary: string;
+    readonly linesAdded: number;
+    readonly linesRemoved: number;
+}
+export interface AggregateMetrics {
+    readonly avgEfficiencyScore: number | null;
+    readonly avgCostUsd: number;
+    readonly avgCorrectionRate: number;
+    readonly avgToolCallsPerTask: number;
+    readonly avgTaskSuccessRate: number | null;
+    readonly sessionCount: number;
+}
+export interface MetricDelta {
+    readonly value: number;
+    readonly percentChange: number | null;
+    readonly improved: boolean;
+}
+export interface ClaudeMdImpactReport {
+    readonly changeDescription: string;
+    readonly beforeMetrics: AggregateMetrics;
+    readonly afterMetrics: AggregateMetrics;
+    readonly deltas: {
+        readonly efficiencyScore: MetricDelta | null;
+        readonly cost: MetricDelta;
+        readonly correctionRate: MetricDelta;
+        readonly toolCallsPerTask: MetricDelta;
+        readonly taskSuccessRate: MetricDelta | null;
+    };
+    readonly contextTokensForClaudeMd: number | null;
+    readonly verdict: string;
+}
+export interface ContextCostEstimate {
+    readonly filePath: string;
+    readonly charCount: number;
+    readonly estimatedTokens: number;
+    readonly perSessionCostUsd: number;
+    readonly perTurnCostUsd: number;
+}
+export declare class ClaudeMdTracker {
+    private readonly sessionStore;
+    private readonly changes;
+    private lastEmittedIndex;
+    private cachedImpact;
+    constructor(options: {
+        sessionStore: SessionStore;
+    });
+    /**
+     * Examine a tool call record and detect if it modifies a CLAUDE.md or
+     * `.claude/` file. Returns the change event if detected, null otherwise.
+     */
+    detectChange(toolCall: ToolCallRecord): ClaudeMdChange | null;
+    /** Returns all detected changes in this tracker's lifetime. */
+    getChanges(): readonly ClaudeMdChange[];
+    /**
+     * Compute SHA-256 hash of a file's content.
+     * Throws if the file does not exist.
+     */
+    static computeFileHash(filePath: string): string;
+    /**
+     * Detect whether CLAUDE.md changed between sessions by comparing hashes.
+     * Returns true if hashes differ. Returns false when previousHash is null
+     * (first session ever — no prior state to compare against, so no change).
+     */
+    static detectBetweenSessionChange(previousHash: string | null, currentHash: string): boolean;
+    /**
+     * Compare metrics in the N days before vs N days after a change timestamp.
+     * Returns a full impact report with deltas, context cost estimate, and verdict.
+     */
+    computeImpact(changeTimestamp: number, windowDays?: number): ClaudeMdImpactReport;
+    private appendChange;
+    private getCachedImpact;
+    /**
+     * Estimate the per-session and per-turn cost of loading a CLAUDE.md file
+     * into context. Reads the file and computes token estimate.
+     */
+    static estimateContextCost(claudeMdPath: string): ContextCostEstimate;
+    /**
+     * Emit custom events and delta metrics for newly detected changes only.
+     * Impact report is cached and only recomputed when a new change arrives.
+     */
+    emitMetrics(aggregator: MetricAggregator): void;
+    reset(): void;
+}
+//# sourceMappingURL=claudemd-tracker.d.ts.map

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

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