@newrelic/preflight 0.0.1-pre.1 → 1.0.0

package/dist/metrics/proxy-metrics.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Proxy Metrics Aggregation — tracks per-server call counts, latency
+ * percentiles, error rates, tool popularity, and proxy overhead for
+ * upstream MCP server traffic flowing through the proxy.
+ */
+import type { MetricAggregator } from '../shared/index.js';
+import type { ProxyToolCallRecord, ProxyRequestRecord } from '../proxy/types.js';
+import { type DurationStats } from './session-tracker.js';
+export interface ServerStats {
+    callCount: number;
+    latencyMs: DurationStats;
+    errorRate: number;
+    errorsByType: Record<string, number>;
+    avgRequestSizeBytes: number;
+    avgResponseSizeBytes: number;
+}
+export interface ProxyMetrics {
+    perServer: Record<string, ServerStats>;
+    toolPopularity: Array<{
+        tool: string;
+        server: string;
+        count: number;
+    }>;
+    totalProxiedCalls: number;
+    avgProxyOverheadMs: number;
+}
+export declare class ProxyMetricsTracker {
+    private serverCalls;
+    private serverLatencies;
+    private serverErrors;
+    private serverErrorsByType;
+    private serverRequestSizes;
+    private serverResponseSizes;
+    private toolServerCounts;
+    private proxyOverheadValues;
+    private totalCalls;
+    /**
+     * Record a proxied tools/call. Updates all per-server aggregates,
+     * tool popularity, and proxy overhead tracking.
+     */
+    recordProxyCall(record: ProxyToolCallRecord): void;
+    /**
+     * Record a proxied discovery request (tools/list, resources/list, etc.).
+     * Updates server-level stats but not tool popularity.
+     */
+    recordProxyRequest(record: ProxyRequestRecord): void;
+    /** Return a snapshot of all proxy metrics. */
+    getMetrics(): ProxyMetrics;
+    /** Emit aggregated metrics to a MetricAggregator for NR ingestion. */
+    emitMetrics(aggregator: MetricAggregator): void;
+    /** Clear all internal state. */
+    reset(): void;
+}
+//# sourceMappingURL=proxy-metrics.d.ts.map

package/dist/metrics/proxy-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-metrics.d.ts","sourceRoot":"","sources":["../../src/metrics/proxy-metrics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAMhF,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAYD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,YAAY,CAAwD;IAC5E,OAAO,CAAC,kBAAkB,CAA0C;IACpE,OAAO,CAAC,kBAAkB,CAA+B;IACzD,OAAO,CAAC,mBAAmB,CAA+B;IAC1D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,mBAAmB,CAAgB;IAC3C,OAAO,CAAC,UAAU,CAAK;IAEvB;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IA4DlD;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAgDpD,8CAA8C;IAC9C,UAAU,IAAI,YAAY;IAyD1B,sEAAsE;IACtE,WAAW,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAgC/C,gCAAgC;IAChC,KAAK,IAAI,IAAI;CAWd"}

package/dist/metrics/proxy-metrics.js

@@ -0,0 +1,228 @@
+/**
+ * Proxy Metrics Aggregation — tracks per-server call counts, latency
+ * percentiles, error rates, tool popularity, and proxy overhead for
+ * upstream MCP server traffic flowing through the proxy.
+ */
+import { computeDurationStats } from './session-tracker.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_SAMPLES = 1_000;
+// ---------------------------------------------------------------------------
+// ProxyMetricsTracker
+// ---------------------------------------------------------------------------
+export class ProxyMetricsTracker {
+    serverCalls = new Map();
+    serverLatencies = new Map();
+    serverErrors = new Map();
+    serverErrorsByType = new Map();
+    serverRequestSizes = new Map();
+    serverResponseSizes = new Map();
+    toolServerCounts = new Map();
+    proxyOverheadValues = [];
+    totalCalls = 0;
+    /**
+     * Record a proxied tools/call. Updates all per-server aggregates,
+     * tool popularity, and proxy overhead tracking.
+     */
+    recordProxyCall(record) {
+        const server = record.serverName;
+        this.totalCalls++;
+        // Per-server call count
+        this.serverCalls.set(server, (this.serverCalls.get(server) ?? 0) + 1);
+        // Latency
+        if (record.durationMs != null) {
+            const latencies = this.serverLatencies.get(server);
+            if (latencies) {
+                appendBounded(latencies, record.durationMs);
+            }
+            else {
+                this.serverLatencies.set(server, [record.durationMs]);
+            }
+        }
+        // Error tracking
+        const errorEntry = this.serverErrors.get(server) ?? { total: 0, failed: 0 };
+        errorEntry.total++;
+        if (!record.success) {
+            errorEntry.failed++;
+            const errorType = record.errorType ?? 'unknown';
+            let typeMap = this.serverErrorsByType.get(server);
+            if (!typeMap) {
+                typeMap = new Map();
+                this.serverErrorsByType.set(server, typeMap);
+            }
+            typeMap.set(errorType, (typeMap.get(errorType) ?? 0) + 1);
+        }
+        this.serverErrors.set(server, errorEntry);
+        // Payload sizes
+        if (record.inputSizeBytes != null) {
+            const sizes = this.serverRequestSizes.get(server);
+            if (sizes) {
+                appendBounded(sizes, record.inputSizeBytes);
+            }
+            else {
+                this.serverRequestSizes.set(server, [record.inputSizeBytes]);
+            }
+        }
+        if (record.outputSizeBytes != null) {
+            const sizes = this.serverResponseSizes.get(server);
+            if (sizes) {
+                appendBounded(sizes, record.outputSizeBytes);
+            }
+            else {
+                this.serverResponseSizes.set(server, [record.outputSizeBytes]);
+            }
+        }
+        // Tool popularity (keyed by tool|server)
+        const toolKey = `${record.toolName}|${server}`;
+        this.toolServerCounts.set(toolKey, (this.toolServerCounts.get(toolKey) ?? 0) + 1);
+        // Proxy overhead
+        if (record.proxyOverheadMs != null) {
+            appendBounded(this.proxyOverheadValues, record.proxyOverheadMs);
+        }
+    }
+    /**
+     * Record a proxied discovery request (tools/list, resources/list, etc.).
+     * Updates server-level stats but not tool popularity.
+     */
+    recordProxyRequest(record) {
+        const server = record.serverName;
+        this.totalCalls++;
+        // Per-server call count
+        this.serverCalls.set(server, (this.serverCalls.get(server) ?? 0) + 1);
+        // Latency
+        if (record.durationMs != null) {
+            const latencies = this.serverLatencies.get(server);
+            if (latencies) {
+                appendBounded(latencies, record.durationMs);
+            }
+            else {
+                this.serverLatencies.set(server, [record.durationMs]);
+            }
+        }
+        // Error tracking
+        const errorEntry = this.serverErrors.get(server) ?? { total: 0, failed: 0 };
+        errorEntry.total++;
+        if (!record.success) {
+            errorEntry.failed++;
+            const errorType = record.error ?? 'unknown';
+            let typeMap = this.serverErrorsByType.get(server);
+            if (!typeMap) {
+                typeMap = new Map();
+                this.serverErrorsByType.set(server, typeMap);
+            }
+            typeMap.set(errorType, (typeMap.get(errorType) ?? 0) + 1);
+        }
+        this.serverErrors.set(server, errorEntry);
+        // Response payload size
+        if (record.responseSizeBytes != null) {
+            const sizes = this.serverResponseSizes.get(server);
+            if (sizes) {
+                appendBounded(sizes, record.responseSizeBytes);
+            }
+            else {
+                this.serverResponseSizes.set(server, [record.responseSizeBytes]);
+            }
+        }
+        // Proxy overhead
+        if (record.proxyOverheadMs != null) {
+            appendBounded(this.proxyOverheadValues, record.proxyOverheadMs);
+        }
+    }
+    /** Return a snapshot of all proxy metrics. */
+    getMetrics() {
+        const perServer = {};
+        for (const [server, callCount] of this.serverCalls) {
+            const latencies = this.serverLatencies.get(server) ?? [];
+            const errorEntry = this.serverErrors.get(server) ?? { total: 0, failed: 0 };
+            const errorsByType = {};
+            const typeMap = this.serverErrorsByType.get(server);
+            if (typeMap) {
+                for (const [type, count] of typeMap) {
+                    errorsByType[type] = count;
+                }
+            }
+            const requestSizes = this.serverRequestSizes.get(server) ?? [];
+            const responseSizes = this.serverResponseSizes.get(server) ?? [];
+            perServer[server] = {
+                callCount,
+                latencyMs: computeDurationStats(latencies),
+                errorRate: errorEntry.total > 0 ? errorEntry.failed / errorEntry.total : 0,
+                errorsByType,
+                avgRequestSizeBytes: requestSizes.length > 0
+                    ? requestSizes.reduce((a, b) => a + b, 0) / requestSizes.length
+                    : 0,
+                avgResponseSizeBytes: responseSizes.length > 0
+                    ? responseSizes.reduce((a, b) => a + b, 0) / responseSizes.length
+                    : 0,
+            };
+        }
+        // Tool popularity — sorted descending by count
+        const toolPopularity = [];
+        for (const [key, count] of this.toolServerCounts) {
+            const parts = key.split('|');
+            const tool = parts[0] ?? 'unknown';
+            const server = parts[1] ?? 'unknown';
+            toolPopularity.push({ tool, server, count });
+        }
+        toolPopularity.sort((a, b) => b.count - a.count);
+        // Average proxy overhead
+        const avgProxyOverheadMs = this.proxyOverheadValues.length > 0
+            ? this.proxyOverheadValues.reduce((a, b) => a + b, 0) / this.proxyOverheadValues.length
+            : 0;
+        return {
+            perServer,
+            toolPopularity,
+            totalProxiedCalls: this.totalCalls,
+            avgProxyOverheadMs,
+        };
+    }
+    /** Emit aggregated metrics to a MetricAggregator for NR ingestion. */
+    emitMetrics(aggregator) {
+        for (const [server, callCount] of this.serverCalls) {
+            aggregator.record('ai.mcp.server_call_count', callCount, { server });
+            const latencies = this.serverLatencies.get(server) ?? [];
+            if (latencies.length > 0) {
+                const avg = latencies.reduce((a, b) => a + b, 0) / latencies.length;
+                aggregator.record('ai.mcp.server_latency_ms', avg, { server });
+            }
+            const errorEntry = this.serverErrors.get(server);
+            if (errorEntry && errorEntry.total > 0) {
+                aggregator.record('ai.mcp.server_error_rate', errorEntry.failed / errorEntry.total, {
+                    server,
+                });
+            }
+        }
+        // Global proxy overhead
+        if (this.proxyOverheadValues.length > 0) {
+            const avg = this.proxyOverheadValues.reduce((a, b) => a + b, 0) / this.proxyOverheadValues.length;
+            aggregator.record('ai.mcp.proxy_overhead_ms', avg);
+        }
+        // Tool popularity
+        for (const [key, count] of this.toolServerCounts) {
+            const [tool = 'unknown', server = 'unknown'] = key.split('|');
+            aggregator.record('ai.mcp.tool_popularity', count, { tool, server });
+        }
+    }
+    /** Clear all internal state. */
+    reset() {
+        this.serverCalls.clear();
+        this.serverLatencies.clear();
+        this.serverErrors.clear();
+        this.serverErrorsByType.clear();
+        this.serverRequestSizes.clear();
+        this.serverResponseSizes.clear();
+        this.toolServerCounts.clear();
+        this.proxyOverheadValues = [];
+        this.totalCalls = 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function appendBounded(arr, value) {
+    if (arr.length >= MAX_SAMPLES)
+        arr.shift();
+    arr.push(value);
+}
+//# sourceMappingURL=proxy-metrics.js.map

package/dist/metrics/proxy-metrics.js.map

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

package/dist/metrics/quality-proxy-tracker.d.ts

@@ -0,0 +1,51 @@
+import type { MetricAggregator } from '../shared/index.js';
+import type { ToolCallRecord } from '../storage/types.js';
+export type QualitySignal = 'diff_applied_clean' | 'diff_failed' | 'test_pass' | 'test_fail' | 'backtrack' | 'self_correction';
+export interface QualityEvent {
+    readonly signal: QualitySignal;
+    readonly turnNumber: number;
+    readonly timestamp: number;
+    readonly toolName: string;
+}
+export interface TurnQualityBucket {
+    readonly turnRange: string;
+    readonly totalSignals: number;
+    readonly positiveSignals: number;
+    readonly negativeSignals: number;
+    readonly qualityRatio: number | null;
+}
+export interface QualityProxyMetrics {
+    readonly totalSignals: number;
+    readonly diffApplyRate: number | null;
+    readonly testPassRate: number | null;
+    readonly backtrackCount: number;
+    readonly selfCorrectionCount: number;
+    readonly qualityByTurnBucket: readonly TurnQualityBucket[];
+    readonly degradationDetected: boolean;
+    readonly events: readonly QualityEvent[];
+}
+export interface QualityProxyOptions {
+    readonly bucketSize?: number;
+    readonly maxEvents?: number;
+    readonly degradationThreshold?: number;
+}
+export declare class QualityProxyTracker {
+    private readonly bucketSize;
+    private readonly maxEvents;
+    private readonly degradationThreshold;
+    private turnCounter;
+    private readonly events;
+    private lastEditFile;
+    private lastEditTurn;
+    private lastEditSuccess;
+    constructor(options?: QualityProxyOptions);
+    recordToolCall(record: ToolCallRecord): void;
+    getMetrics(): QualityProxyMetrics;
+    emitMetrics(aggregator: MetricAggregator): void;
+    reset(_sessionId: string): void;
+    private addEvent;
+    private computeTurnBuckets;
+    private detectDegradation;
+    private averageQualityRatio;
+}
+//# sourceMappingURL=quality-proxy-tracker.d.ts.map

package/dist/metrics/quality-proxy-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-proxy-tracker.d.ts","sourceRoot":"","sources":["../../src/metrics/quality-proxy-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM1D,MAAM,MAAM,aAAa,GACrB,oBAAoB,GACpB,aAAa,GACb,WAAW,GACX,WAAW,GACX,WAAW,GACX,iBAAiB,CAAC;AAEtB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAcD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAE9C,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAS;gBAEpB,OAAO,CAAC,EAAE,mBAAmB;IAMzC,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAwD5C,UAAU,IAAI,mBAAmB;IA0BjC,WAAW,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAe/C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAQ/B,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,mBAAmB;CAK5B"}

package/dist/metrics/quality-proxy-tracker.js

@@ -0,0 +1,162 @@
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_BUCKET_SIZE = 10;
+const DEFAULT_MAX_EVENTS = 500;
+const DEFAULT_DEGRADATION_THRESHOLD = 0.3;
+// ---------------------------------------------------------------------------
+// QualityProxyTracker
+// ---------------------------------------------------------------------------
+export class QualityProxyTracker {
+    bucketSize;
+    maxEvents;
+    degradationThreshold;
+    turnCounter = 0;
+    events = [];
+    lastEditFile = null;
+    lastEditTurn = 0;
+    lastEditSuccess = false;
+    constructor(options) {
+        this.bucketSize = options?.bucketSize ?? DEFAULT_BUCKET_SIZE;
+        this.maxEvents = options?.maxEvents ?? DEFAULT_MAX_EVENTS;
+        this.degradationThreshold = options?.degradationThreshold ?? DEFAULT_DEGRADATION_THRESHOLD;
+    }
+    recordToolCall(record) {
+        this.turnCounter++;
+        const turn = this.turnCounter;
+        // Detect self-correction BEFORE updating lastEditFile/lastEditTurn
+        if ((record.toolName === 'Edit' || record.toolName === 'Write') && this.lastEditFile !== null) {
+            const filePath = record.filePath;
+            if (filePath === this.lastEditFile && turn - this.lastEditTurn <= 3) {
+                const recentFailure = this.events.some((e) => e.signal === 'test_fail' && e.turnNumber > this.lastEditTurn && e.turnNumber < turn);
+                if (recentFailure) {
+                    this.addEvent('self_correction', turn, record.toolName);
+                }
+            }
+        }
+        // Detect backtrack: Read of a recently-edited file only when the edit failed
+        // or a test failure prompted the re-read. A normal post-edit verification read
+        // (edit succeeded, no test failure) is not a backtrack.
+        if (record.toolName === 'Read' && this.lastEditFile !== null) {
+            const filePath = record.filePath;
+            if (filePath === this.lastEditFile && turn - this.lastEditTurn <= 2) {
+                const recentTestFail = this.events.some((e) => e.signal === 'test_fail' && e.turnNumber > this.lastEditTurn && e.turnNumber < turn);
+                if (!this.lastEditSuccess || recentTestFail) {
+                    this.addEvent('backtrack', turn, record.toolName);
+                }
+            }
+        }
+        if (record.toolName === 'Edit' || record.toolName === 'Write') {
+            if (record.success) {
+                this.addEvent('diff_applied_clean', turn, record.toolName);
+            }
+            else {
+                this.addEvent('diff_failed', turn, record.toolName);
+            }
+            this.lastEditFile = record.filePath ?? null;
+            this.lastEditTurn = turn;
+            this.lastEditSuccess = record.success ?? false;
+        }
+        if (record.toolName === 'Bash') {
+            if (record.isTestCommand) {
+                if (record.success) {
+                    this.addEvent('test_pass', turn, record.toolName);
+                }
+                else {
+                    this.addEvent('test_fail', turn, record.toolName);
+                }
+            }
+        }
+    }
+    getMetrics() {
+        const diffApplied = this.events.filter((e) => e.signal === 'diff_applied_clean').length;
+        const diffFailed = this.events.filter((e) => e.signal === 'diff_failed').length;
+        const testPass = this.events.filter((e) => e.signal === 'test_pass').length;
+        const testFail = this.events.filter((e) => e.signal === 'test_fail').length;
+        const backtrackCount = this.events.filter((e) => e.signal === 'backtrack').length;
+        const selfCorrectionCount = this.events.filter((e) => e.signal === 'self_correction').length;
+        const totalDiffs = diffApplied + diffFailed;
+        const totalTests = testPass + testFail;
+        const buckets = this.computeTurnBuckets();
+        const degradationDetected = this.detectDegradation(buckets);
+        return {
+            totalSignals: this.events.length,
+            diffApplyRate: totalDiffs > 0 ? Math.round((diffApplied / totalDiffs) * 1000) / 1000 : null,
+            testPassRate: totalTests > 0 ? Math.round((testPass / totalTests) * 1000) / 1000 : null,
+            backtrackCount,
+            selfCorrectionCount,
+            qualityByTurnBucket: buckets,
+            degradationDetected,
+            events: this.events,
+        };
+    }
+    emitMetrics(aggregator) {
+        const metrics = this.getMetrics();
+        if (metrics.diffApplyRate !== null) {
+            aggregator.record('ai.quality.diff_apply_rate', metrics.diffApplyRate);
+        }
+        if (metrics.testPassRate !== null) {
+            aggregator.record('ai.quality.test_pass_rate', metrics.testPassRate);
+        }
+        aggregator.record('ai.quality.backtrack_count', metrics.backtrackCount);
+        aggregator.record('ai.quality.self_correction_count', metrics.selfCorrectionCount);
+        if (metrics.degradationDetected) {
+            aggregator.record('ai.quality.degradation_detected', 1);
+        }
+    }
+    reset(_sessionId) {
+        this.turnCounter = 0;
+        this.events.length = 0;
+        this.lastEditFile = null;
+        this.lastEditTurn = 0;
+        this.lastEditSuccess = false;
+    }
+    addEvent(signal, turnNumber, toolName) {
+        this.events.push({ signal, turnNumber, timestamp: Date.now(), toolName });
+        if (this.events.length > this.maxEvents) {
+            this.events.shift();
+        }
+    }
+    computeTurnBuckets() {
+        if (this.events.length === 0)
+            return [];
+        const maxTurn = this.events.reduce((m, e) => Math.max(m, e.turnNumber), 0);
+        const buckets = [];
+        for (let start = 1; start <= maxTurn; start += this.bucketSize) {
+            const end = start + this.bucketSize - 1;
+            const inBucket = this.events.filter((e) => e.turnNumber >= start && e.turnNumber <= end);
+            const positive = inBucket.filter((e) => e.signal === 'diff_applied_clean' || e.signal === 'test_pass').length;
+            const negative = inBucket.filter((e) => e.signal === 'diff_failed' || e.signal === 'test_fail' || e.signal === 'backtrack').length;
+            const total = positive + negative;
+            buckets.push({
+                turnRange: `${start}-${end}`,
+                totalSignals: inBucket.length,
+                positiveSignals: positive,
+                negativeSignals: negative,
+                qualityRatio: total > 0 ? Math.round((positive / total) * 1000) / 1000 : null,
+            });
+        }
+        return buckets;
+    }
+    detectDegradation(buckets) {
+        if (buckets.length < 3)
+            return false;
+        // Compare first third vs last third of buckets
+        const third = Math.floor(buckets.length / 3);
+        const earlyBuckets = buckets.slice(0, third);
+        const lateBuckets = buckets.slice(-third);
+        const earlyRatio = this.averageQualityRatio(earlyBuckets);
+        const lateRatio = this.averageQualityRatio(lateBuckets);
+        if (earlyRatio === null || lateRatio === null)
+            return false;
+        const drop = earlyRatio - lateRatio;
+        return drop >= this.degradationThreshold;
+    }
+    averageQualityRatio(buckets) {
+        const ratios = buckets.map((b) => b.qualityRatio).filter((r) => r !== null);
+        if (ratios.length === 0)
+            return null;
+        return ratios.reduce((a, b) => a + b, 0) / ratios.length;
+    }
+}
+//# sourceMappingURL=quality-proxy-tracker.js.map

package/dist/metrics/quality-proxy-tracker.js.map

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

package/dist/metrics/recommendation-engine.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 type { MetricAggregator } from '../shared/index.js';
+import type { SessionStore } from '../storage/session-store.js';
+import type { TrendAnalyzer } from './trend-analyzer.js';
+import type { CollaborationProfiler } from './collaboration-profile.js';
+import type { ClaudeMdTracker } from './claudemd-tracker.js';
+import type { PromptFeedbackEngine } from './prompt-feedback.js';
+import type { CostPerOutcomeAnalyzer } from './cost-per-outcome.js';
+import type { TaskDetector } from './task-detector.js';
+export interface Recommendation {
+    readonly id: string;
+    readonly category: string;
+    readonly priority: 'high' | 'medium' | 'low';
+    readonly title: string;
+    readonly detail: string;
+    readonly evidence: string;
+    readonly estimatedSavings?: string;
+}
+export declare class RecommendationEngine {
+    private readonly sessionStore;
+    private readonly trendAnalyzer;
+    private readonly collaborationProfiler;
+    private readonly claudeMdTracker;
+    private readonly promptFeedbackEngine;
+    private readonly costPerOutcomeAnalyzer;
+    private readonly taskDetector?;
+    constructor(options: {
+        sessionStore: SessionStore;
+        trendAnalyzer: TrendAnalyzer;
+        collaborationProfiler: CollaborationProfiler;
+        claudeMdTracker: ClaudeMdTracker;
+        promptFeedbackEngine: PromptFeedbackEngine;
+        costPerOutcomeAnalyzer: CostPerOutcomeAnalyzer;
+        taskDetector?: TaskDetector;
+    });
+    /**
+     * Generate all recommendations from all sub-analyzers, deduplicate,
+     * sort by priority, and optionally limit to topN.
+     */
+    generateAllRecommendations(developer: string, options?: {
+        topN?: number;
+        since?: Date;
+    }): Recommendation[];
+    /**
+     * Team-level recommendations aggregating patterns across developers.
+     */
+    generateTeamRecommendations(options?: {
+        since?: Date;
+    }): Recommendation[];
+    /**
+     * Emit recommendation metrics to New Relic.
+     */
+    emitMetrics(aggregator: MetricAggregator, developer: string, options?: {
+        since?: Date;
+    }): void;
+    private getCostRecommendations;
+    private getEfficiencyRecommendations;
+    private getPromptRecommendations;
+    private getClaudeMdRecommendations;
+    private getModelRecommendations;
+}
+//# sourceMappingURL=recommendation-engine.d.ts.map

package/dist/metrics/recommendation-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-engine.d.ts","sourceRoot":"","sources":["../../src/metrics/recommendation-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQvD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAYD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuB;IAC5D,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAyB;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;gBAEjC,OAAO,EAAE;QACnB,YAAY,EAAE,YAAY,CAAC;QAC3B,aAAa,EAAE,aAAa,CAAC;QAC7B,qBAAqB,EAAE,qBAAqB,CAAC;QAC7C,eAAe,EAAE,eAAe,CAAC;QACjC,oBAAoB,EAAE,oBAAoB,CAAC;QAC3C,sBAAsB,EAAE,sBAAsB,CAAC;QAC/C,YAAY,CAAC,EAAE,YAAY,CAAC;KAC7B;IAUD;;;OAGG;IACH,0BAA0B,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,IAAI,CAAA;KAAE,GACxC,cAAc,EAAE;IAkCnB;;OAEG;IACH,2BAA2B,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAA;KAAE,GAAG,cAAc,EAAE;IAkCzE;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI;IAqB9F,OAAO,CAAC,sBAAsB;IA4C9B,OAAO,CAAC,4BAA4B;IAiCpC,OAAO,CAAC,wBAAwB;IAkBhC,OAAO,CAAC,0BAA0B;IAoClC,OAAO,CAAC,uBAAuB;CAuChC"}