@newrelic/preflight 0.0.1-pre.1 → 1.0.0

package/dist/metrics/task-detector.js

@@ -0,0 +1,302 @@
+/**
+ * Task Boundary Detection — heuristically detects discrete "tasks" from
+ * the stream of tool calls.
+ *
+ * A task is the work Claude does between user messages: the user gives an
+ * instruction, Claude executes a series of tool calls, and eventually responds.
+ *
+ * Detection signals:
+ *   1. Idle gap > threshold (configurable, default 30s) → task complete
+ *   2. AskUserQuestion tool call → task complete (Claude is asking for direction)
+ *   3. TaskUpdate with status=completed → explicit task completion
+ */
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Internal mutable task accumulator
+// ---------------------------------------------------------------------------
+class ActiveTask {
+    taskId;
+    startTime;
+    toolCallCount = 0;
+    toolCallsByType = new Map();
+    filesReadSet = new Set();
+    filesModifiedSet = new Set();
+    rawToolCalls = [];
+    linesChanged = 0;
+    linesAdded = 0;
+    linesRemoved = 0;
+    bashCommandsRun = 0;
+    testsRun = 0;
+    testsPassed = 0;
+    buildRun = 0;
+    buildPassed = 0;
+    askedUserQuestions = 0;
+    subAgentsSpawned = 0;
+    constructor(taskId, startTime) {
+        this.taskId = taskId;
+        this.startTime = startTime;
+    }
+    addToolCall(record) {
+        this.toolCallCount++;
+        this.rawToolCalls.push(record);
+        const tool = record.toolName;
+        this.toolCallsByType.set(tool, (this.toolCallsByType.get(tool) ?? 0) + 1);
+        // File tracking
+        const filePath = record.filePath;
+        if (filePath) {
+            if (tool === 'Read') {
+                this.filesReadSet.add(filePath);
+            }
+            else if (tool === 'Write' || tool === 'Edit') {
+                this.filesModifiedSet.add(filePath);
+            }
+        }
+        // Line change tracking
+        if (tool === 'Write') {
+            const lineCount = record.lineCount;
+            if (lineCount != null) {
+                this.linesAdded += lineCount;
+                this.linesChanged += lineCount;
+            }
+        }
+        else if (tool === 'Edit') {
+            const newLines = record.newLineCount ?? 0;
+            const oldLines = record.oldLineCount ?? 0;
+            // Track actual additions and removals, not just net diff.
+            // An edit that replaces 10 lines with 15 lines: removed=10, added=15 (not added=5).
+            this.linesAdded += newLines;
+            this.linesRemoved += oldLines;
+            this.linesChanged += Math.abs(newLines - oldLines);
+        }
+        // Bash tracking
+        if (tool === 'Bash') {
+            this.bashCommandsRun++;
+            if (record.isTestCommand) {
+                this.testsRun++;
+                if (record.success)
+                    this.testsPassed++;
+            }
+            if (record.isBuildCommand) {
+                this.buildRun++;
+                if (record.success)
+                    this.buildPassed++;
+            }
+        }
+        // AskUserQuestion tracking
+        if (tool === 'AskUserQuestion') {
+            this.askedUserQuestions++;
+        }
+        // Agent tracking
+        if (tool === 'Agent') {
+            this.subAgentsSpawned++;
+        }
+    }
+    toCompleted(endTime, estimatedCostUsd, tokensUsed) {
+        const toolCallsByType = {};
+        for (const [tool, count] of this.toolCallsByType) {
+            toolCallsByType[tool] = count;
+        }
+        return {
+            taskId: this.taskId,
+            startTime: this.startTime,
+            endTime,
+            // Cap at 4 hours to guard against inflated durations from process suspension
+            // (laptop sleep or container pause) causing the idle timer to fire on resume.
+            durationMs: Math.min(endTime - this.startTime, 4 * 60 * 60 * 1000),
+            toolCallCount: this.toolCallCount,
+            toolCallsByType,
+            filesRead: [...this.filesReadSet].sort(),
+            filesModified: [...this.filesModifiedSet].sort(),
+            linesChanged: this.linesChanged,
+            linesAdded: this.linesAdded,
+            linesRemoved: this.linesRemoved,
+            bashCommandsRun: this.bashCommandsRun,
+            testsRun: this.testsRun,
+            testsPassed: this.testsPassed,
+            buildRun: this.buildRun,
+            buildPassed: this.buildPassed,
+            estimatedCostUsd,
+            tokensUsed,
+            askedUserQuestions: this.askedUserQuestions,
+            subAgentsSpawned: this.subAgentsSpawned,
+            toolCalls: [...this.rawToolCalls],
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// TaskDetector
+// ---------------------------------------------------------------------------
+const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_COMPLETED_TASKS = 100;
+export class TaskDetector {
+    idleTimeoutMs;
+    costTracker;
+    maxCompletedTasks;
+    activeTask = null;
+    completedTasks = [];
+    pendingEmission = [];
+    lifetimeCompletedCount = 0;
+    idleTimer = null;
+    // Cost/token snapshots at task start for computing deltas
+    costAtTaskStart = 0;
+    tokensAtTaskStart = 0;
+    constructor(options) {
+        this.idleTimeoutMs = options?.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+        this.costTracker = options?.costTracker ?? null;
+        this.maxCompletedTasks = options?.maxCompletedTasks ?? DEFAULT_MAX_COMPLETED_TASKS;
+    }
+    recordToolCall(record) {
+        // Start a new task if none is active
+        if (this.activeTask === null) {
+            this.startNewTask(record.timestamp);
+        }
+        // Accumulate the tool call
+        this.activeTask.addToolCall(record);
+        // Check for boundary signals
+        if (record.toolName === 'AskUserQuestion') {
+            this.closeCurrentTask(record.timestamp);
+            return; // Timer not needed — task is already closed
+        }
+        if (record.toolName === 'TaskUpdate' &&
+            record.taskStatus === 'completed') {
+            this.closeCurrentTask(record.timestamp);
+            return;
+        }
+        // Reset idle timer
+        this.resetIdleTimer();
+    }
+    getCurrentTask() {
+        if (this.activeTask === null)
+            return null;
+        const { costUsd, tokens } = this.computeCostDelta();
+        return this.activeTask.toCompleted(Date.now(), costUsd, tokens);
+    }
+    getCompletedTasks() {
+        return [...this.completedTasks];
+    }
+    /**
+     * Returns tasks completed since the last drain and clears the emission queue.
+     * Safe to call on every poll cycle — each task is returned exactly once.
+     */
+    drainNewlyCompletedTasks() {
+        const tasks = [...this.pendingEmission];
+        this.pendingEmission = [];
+        return tasks;
+    }
+    getActiveTaskId() {
+        return this.activeTask?.taskId ?? null;
+    }
+    getMetrics() {
+        const completed = this.completedTasks;
+        let avgDuration = null;
+        let avgToolCalls = null;
+        if (completed.length > 0) {
+            let totalDuration = 0;
+            let totalToolCalls = 0;
+            for (const task of completed) {
+                totalDuration += task.durationMs;
+                totalToolCalls += task.toolCallCount;
+            }
+            avgDuration = Math.round(totalDuration / completed.length);
+            avgToolCalls = Math.round((totalToolCalls / completed.length) * 100) / 100;
+        }
+        return {
+            totalTasksCompleted: this.lifetimeCompletedCount,
+            currentTaskActive: this.activeTask !== null,
+            currentTaskToolCalls: this.activeTask?.toolCallCount ?? 0,
+            averageTaskDurationMs: avgDuration,
+            averageToolCallsPerTask: avgToolCalls,
+            completedTasks: [...completed],
+        };
+    }
+    emitMetrics(aggregator) {
+        aggregator.record('ai.task.completed_count', this.completedTasks.length);
+        aggregator.record('ai.task.active', this.activeTask !== null ? 1 : 0);
+        for (const task of this.completedTasks) {
+            aggregator.record('ai.task.duration_ms', task.durationMs);
+            aggregator.record('ai.task.tool_call_count', task.toolCallCount);
+            if (task.estimatedCostUsd !== null) {
+                aggregator.record('ai.task.cost_usd', task.estimatedCostUsd);
+            }
+        }
+    }
+    reset() {
+        this.clearIdleTimer();
+        this.activeTask = null;
+        this.completedTasks = [];
+        this.pendingEmission = [];
+        this.costAtTaskStart = 0;
+        this.tokensAtTaskStart = 0;
+        this.lifetimeCompletedCount = 0;
+    }
+    dispose() {
+        this.clearIdleTimer();
+        if (this.activeTask !== null) {
+            this.closeCurrentTask(Date.now());
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    startNewTask(timestamp) {
+        this.activeTask = new ActiveTask(randomUUID(), timestamp);
+        this.snapshotCostState();
+    }
+    closeCurrentTask(endTime) {
+        if (this.activeTask === null)
+            return;
+        const { costUsd, tokens } = this.computeCostDelta();
+        const completed = this.activeTask.toCompleted(endTime, costUsd, tokens);
+        this.completedTasks.push(completed);
+        this.pendingEmission.push(completed);
+        this.lifetimeCompletedCount++;
+        // Cap completed tasks to prevent unbounded memory
+        while (this.completedTasks.length > this.maxCompletedTasks) {
+            this.completedTasks.shift();
+        }
+        // Cap pendingEmission to the same limit (drainNewlyCompletedTasks may
+        // never be called in abnormal shutdown paths)
+        while (this.pendingEmission.length > this.maxCompletedTasks) {
+            this.pendingEmission.shift();
+        }
+        this.activeTask = null;
+        this.clearIdleTimer();
+    }
+    snapshotCostState() {
+        if (this.costTracker === null) {
+            this.costAtTaskStart = 0;
+            this.tokensAtTaskStart = 0;
+            return;
+        }
+        const metrics = this.costTracker.getMetrics();
+        this.costAtTaskStart = metrics.sessionTotalCostUsd ?? 0;
+        this.tokensAtTaskStart =
+            metrics.totalInputTokens + metrics.totalOutputTokens + metrics.totalThinkingTokens;
+    }
+    computeCostDelta() {
+        if (this.costTracker === null) {
+            return { costUsd: null, tokens: 0 };
+        }
+        const metrics = this.costTracker.getMetrics();
+        const currentCost = metrics.sessionTotalCostUsd ?? 0;
+        const currentTokens = metrics.totalInputTokens + metrics.totalOutputTokens + metrics.totalThinkingTokens;
+        return {
+            costUsd: Math.max(0, currentCost - this.costAtTaskStart),
+            tokens: Math.max(0, currentTokens - this.tokensAtTaskStart),
+        };
+    }
+    resetIdleTimer() {
+        this.clearIdleTimer();
+        this.idleTimer = setTimeout(() => {
+            this.closeCurrentTask(Date.now());
+        }, this.idleTimeoutMs);
+        this.idleTimer.unref();
+    }
+    clearIdleTimer() {
+        if (this.idleTimer !== null) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=task-detector.js.map

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

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

package/dist/metrics/tool-selection-scorer.d.ts

@@ -0,0 +1,39 @@
+import type { ToolCallRecord } from '../storage/types.js';
+export interface ToolSelectionPenalty {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly reason: 'redundant_read' | 'repeated_failure' | 'unused_output';
+    readonly penaltyScore: number;
+    readonly detail: string;
+}
+export interface ToolSelectionMetrics {
+    readonly score: number;
+    readonly totalCalls: number;
+    readonly penalizedCalls: number;
+    readonly penalties: readonly ToolSelectionPenalty[];
+    readonly worstOffenders: readonly ToolSelectionPenalty[];
+    readonly redundantReadCount: number;
+    readonly repeatedFailureCount: number;
+    readonly unusedOutputCount: number;
+}
+export interface ToolSelectionScorerOptions {
+    readonly redundantReadPenalty?: number;
+    readonly repeatedFailurePenalty?: number;
+    readonly unusedOutputPenalty?: number;
+    readonly unusedOutputSizeThreshold?: number;
+    readonly worstOffenderCount?: number;
+}
+export declare class ToolSelectionScorer {
+    private readonly redundantReadPenalty;
+    private readonly repeatedFailurePenalty;
+    private readonly unusedOutputPenalty;
+    private readonly unusedOutputSizeThreshold;
+    private readonly worstOffenderCount;
+    constructor(options?: ToolSelectionScorerOptions);
+    scoreSession(toolCalls: readonly ToolCallRecord[]): ToolSelectionMetrics;
+    private findRedundantReads;
+    private findRepeatedFailures;
+    private findUnusedOutputs;
+    private isOutputReferenced;
+}
+//# sourceMappingURL=tool-selection-scorer.d.ts.map

package/dist/metrics/tool-selection-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-selection-scorer.d.ts","sourceRoot":"","sources":["../../src/metrics/tool-selection-scorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,CAAC;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAC5C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAkCD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAS;IACnD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAEhC,OAAO,CAAC,EAAE,0BAA0B;IAUhD,YAAY,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,oBAAoB;IA4CxE,OAAO,CAAC,kBAAkB;IAiD1B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,iBAAiB;IA0BzB,OAAO,CAAC,kBAAkB;CAqB3B"}

package/dist/metrics/tool-selection-scorer.js

@@ -0,0 +1,193 @@
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_REDUNDANT_READ_PENALTY = 0.03;
+const DEFAULT_REPEATED_FAILURE_PENALTY = 0.08;
+const DEFAULT_UNUSED_OUTPUT_PENALTY = 0.04;
+const DEFAULT_UNUSED_OUTPUT_SIZE_THRESHOLD = 4000;
+const DEFAULT_WORST_OFFENDER_COUNT = 10;
+// Tools whose output is terminal — they perform an action and their output is
+// a confirmation or result, not raw data to be consumed by later tool calls.
+// Penalizing these for "unused output" is nonsensical.
+const TERMINAL_OUTPUT_TOOLS = new Set([
+    'Edit',
+    'Write',
+    'Agent',
+    'NotebookEdit',
+    'Bash',
+    'TaskCreate',
+    'TaskUpdate',
+    'TaskList',
+    'TaskGet',
+    'SendMessage',
+    'EnterPlanMode',
+    'ExitPlanMode',
+]);
+// ---------------------------------------------------------------------------
+// ToolSelectionScorer
+// ---------------------------------------------------------------------------
+export class ToolSelectionScorer {
+    redundantReadPenalty;
+    repeatedFailurePenalty;
+    unusedOutputPenalty;
+    unusedOutputSizeThreshold;
+    worstOffenderCount;
+    constructor(options) {
+        this.redundantReadPenalty = options?.redundantReadPenalty ?? DEFAULT_REDUNDANT_READ_PENALTY;
+        this.repeatedFailurePenalty =
+            options?.repeatedFailurePenalty ?? DEFAULT_REPEATED_FAILURE_PENALTY;
+        this.unusedOutputPenalty = options?.unusedOutputPenalty ?? DEFAULT_UNUSED_OUTPUT_PENALTY;
+        this.unusedOutputSizeThreshold =
+            options?.unusedOutputSizeThreshold ?? DEFAULT_UNUSED_OUTPUT_SIZE_THRESHOLD;
+        this.worstOffenderCount = options?.worstOffenderCount ?? DEFAULT_WORST_OFFENDER_COUNT;
+    }
+    scoreSession(toolCalls) {
+        if (toolCalls.length === 0) {
+            return {
+                score: 1,
+                totalCalls: 0,
+                penalizedCalls: 0,
+                penalties: [],
+                worstOffenders: [],
+                redundantReadCount: 0,
+                repeatedFailureCount: 0,
+                unusedOutputCount: 0,
+            };
+        }
+        const penalties = [];
+        penalties.push(...this.findRedundantReads(toolCalls));
+        penalties.push(...this.findRepeatedFailures(toolCalls));
+        penalties.push(...this.findUnusedOutputs(toolCalls));
+        const rawPenalty = penalties.reduce((sum, p) => sum + p.penaltyScore, 0);
+        // Normalize: cap penalty contribution relative to session size so that a
+        // 1000-call session with 10 redundant reads isn't unfairly punished the
+        // same as a 15-call session with 10 redundant reads. Effective penalty is
+        // at most 70% (floor of 0.3 ensures even bad sessions aren't demoralizingly low).
+        const totalPenalty = Math.min(rawPenalty, 0.7);
+        const score = Math.max(0, Math.round((1 - totalPenalty) * 1000) / 1000);
+        const worstOffenders = [...penalties]
+            .sort((a, b) => b.penaltyScore - a.penaltyScore)
+            .slice(0, this.worstOffenderCount);
+        return {
+            score,
+            totalCalls: toolCalls.length,
+            penalizedCalls: penalties.length,
+            penalties,
+            worstOffenders,
+            redundantReadCount: penalties.filter((p) => p.reason === 'redundant_read').length,
+            repeatedFailureCount: penalties.filter((p) => p.reason === 'repeated_failure').length,
+            unusedOutputCount: penalties.filter((p) => p.reason === 'unused_output').length,
+        };
+    }
+    findRedundantReads(toolCalls) {
+        const penalties = [];
+        const readFiles = new Map();
+        for (let i = 0; i < toolCalls.length; i++) {
+            const call = toolCalls[i];
+            if (call.toolName !== 'Read')
+                continue;
+            const file = call.filePath;
+            if (!file)
+                continue;
+            const entry = readFiles.get(file) ?? { count: 0, ids: [], indices: [] };
+            entry.count++;
+            entry.ids.push(call.id);
+            entry.indices.push(i);
+            readFiles.set(file, entry);
+        }
+        for (const [file, entry] of readFiles) {
+            if (entry.count <= 1)
+                continue;
+            // Only penalize reads beyond the 2nd — one re-read after editing is
+            // normal verification; 3+ reads of the same file suggests lost context.
+            for (let i = 2; i < entry.ids.length; i++) {
+                // Skip if there was an Edit/Write to this file between reads (re-read
+                // after modification is intentional, not redundant).
+                const prevIdx = entry.indices[i - 1];
+                const currIdx = entry.indices[i];
+                let editBetween = false;
+                for (let j = prevIdx + 1; j < currIdx; j++) {
+                    const tc = toolCalls[j];
+                    if ((tc.toolName === 'Edit' || tc.toolName === 'Write') && tc.filePath === file) {
+                        editBetween = true;
+                        break;
+                    }
+                }
+                if (editBetween)
+                    continue;
+                penalties.push({
+                    callId: entry.ids[i],
+                    toolName: 'Read',
+                    reason: 'redundant_read',
+                    penaltyScore: this.redundantReadPenalty,
+                    detail: `Redundant read of ${file} (read #${i + 1} of ${entry.count})`,
+                });
+            }
+        }
+        return penalties;
+    }
+    findRepeatedFailures(toolCalls) {
+        const penalties = [];
+        // Track consecutive failures: reset streak when the tool succeeds or a
+        // different tool is called. Only penalize back-to-back failures.
+        const consecutiveFailures = new Map();
+        for (const call of toolCalls) {
+            if (call.success) {
+                consecutiveFailures.set(call.toolName, 0);
+                continue;
+            }
+            const streak = (consecutiveFailures.get(call.toolName) ?? 0) + 1;
+            consecutiveFailures.set(call.toolName, streak);
+            if (streak > 1) {
+                penalties.push({
+                    callId: call.id,
+                    toolName: call.toolName,
+                    reason: 'repeated_failure',
+                    penaltyScore: this.repeatedFailurePenalty,
+                    detail: `Consecutive failure of ${call.toolName} (${streak} in a row)`,
+                });
+            }
+        }
+        return penalties;
+    }
+    findUnusedOutputs(toolCalls) {
+        const penalties = [];
+        for (let i = 0; i < toolCalls.length; i++) {
+            const call = toolCalls[i];
+            if (TERMINAL_OUTPUT_TOOLS.has(call.toolName))
+                continue;
+            const outputSize = call.outputSizeBytes ?? 0;
+            if (outputSize < this.unusedOutputSizeThreshold)
+                continue;
+            if (!call.success)
+                continue;
+            const isReferenced = this.isOutputReferenced(call, toolCalls.slice(i + 1));
+            if (!isReferenced) {
+                penalties.push({
+                    callId: call.id,
+                    toolName: call.toolName,
+                    reason: 'unused_output',
+                    penaltyScore: this.unusedOutputPenalty,
+                    detail: `Large output (${outputSize} bytes) from ${call.toolName} not referenced in subsequent turns`,
+                });
+            }
+        }
+        return penalties;
+    }
+    isOutputReferenced(sourceCall, subsequentCalls) {
+        // If the source was a Read, check if the file is referenced in subsequent Edits/Writes
+        if (sourceCall.toolName === 'Read') {
+            const filePath = sourceCall.filePath;
+            if (filePath) {
+                for (const call of subsequentCalls) {
+                    if ((call.toolName === 'Edit' || call.toolName === 'Write') &&
+                        call.filePath === filePath) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=tool-selection-scorer.js.map

package/dist/metrics/tool-selection-scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-selection-scorer.js","sourceRoot":"","sources":["../../src/metrics/tool-selection-scorer.ts"],"names":[],"mappings":"AAiCA,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAC5C,MAAM,gCAAgC,GAAG,IAAI,CAAC;AAC9C,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAC3C,MAAM,oCAAoC,GAAG,IAAI,CAAC;AAClD,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAExC,8EAA8E;AAC9E,6EAA6E;AAC7E,uDAAuD;AACvD,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,MAAM;IACN,OAAO;IACP,OAAO;IACP,cAAc;IACd,MAAM;IACN,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,SAAS;IACT,aAAa;IACb,eAAe;IACf,cAAc;CACf,CAAC,CAAC;AAEH,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,OAAO,mBAAmB;IACb,oBAAoB,CAAS;IAC7B,sBAAsB,CAAS;IAC/B,mBAAmB,CAAS;IAC5B,yBAAyB,CAAS;IAClC,kBAAkB,CAAS;IAE5C,YAAY,OAAoC;QAC9C,IAAI,CAAC,oBAAoB,GAAG,OAAO,EAAE,oBAAoB,IAAI,8BAA8B,CAAC;QAC5F,IAAI,CAAC,sBAAsB;YACzB,OAAO,EAAE,sBAAsB,IAAI,gCAAgC,CAAC;QACtE,IAAI,CAAC,mBAAmB,GAAG,OAAO,EAAE,mBAAmB,IAAI,6BAA6B,CAAC;QACzF,IAAI,CAAC,yBAAyB;YAC5B,OAAO,EAAE,yBAAyB,IAAI,oCAAoC,CAAC;QAC7E,IAAI,CAAC,kBAAkB,GAAG,OAAO,EAAE,kBAAkB,IAAI,4BAA4B,CAAC;IACxF,CAAC;IAED,YAAY,CAAC,SAAoC;QAC/C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,KAAK,EAAE,CAAC;gBACR,UAAU,EAAE,CAAC;gBACb,cAAc,EAAE,CAAC;gBACjB,SAAS,EAAE,EAAE;gBACb,cAAc,EAAE,EAAE;gBAClB,kBAAkB,EAAE,CAAC;gBACrB,oBAAoB,EAAE,CAAC;gBACvB,iBAAiB,EAAE,CAAC;aACrB,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAA2B,EAAE,CAAC;QAE7C,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;QACtD,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC;QACxD,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC;QAErD,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;QACzE,yEAAyE;QACzE,wEAAwE;QACxE,0EAA0E;QAC1E,kFAAkF;QAClF,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAExE,MAAM,cAAc,GAAG,CAAC,GAAG,SAAS,CAAC;aAClC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;aAC/C,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAErC,OAAO;YACL,KAAK;YACL,UAAU,EAAE,SAAS,CAAC,MAAM;YAC5B,cAAc,EAAE,SAAS,CAAC,MAAM;YAChC,SAAS;YACT,cAAc;YACd,kBAAkB,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,gBAAgB,CAAC,CAAC,MAAM;YACjF,oBAAoB,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,kBAAkB,CAAC,CAAC,MAAM;YACrF,iBAAiB,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC,MAAM;SAChF,CAAC;IACJ,CAAC;IAEO,kBAAkB,CAAC,SAAoC;QAC7D,MAAM,SAAS,GAA2B,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,IAAI,GAAG,EAA+D,CAAC;QAEzF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,IAAI,CAAC,QAAQ,KAAK,MAAM;gBAAE,SAAS;YACvC,MAAM,IAAI,GAAG,IAAI,CAAC,QAA8B,CAAC;YACjD,IAAI,CAAC,IAAI;gBAAE,SAAS;YAEpB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;YACxE,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACtB,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7B,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;YACtC,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC;gBAAE,SAAS;YAC/B,oEAAoE;YACpE,wEAAwE;YACxE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC1C,sEAAsE;gBACtE,qDAAqD;gBACrD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACrC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACjC,IAAI,WAAW,GAAG,KAAK,CAAC;gBACxB,KAAK,IAAI,CAAC,GAAG,OAAO,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC3C,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;oBACxB,IAAI,CAAC,EAAE,CAAC,QAAQ,KAAK,MAAM,IAAI,EAAE,CAAC,QAAQ,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;wBAChF,WAAW,GAAG,IAAI,CAAC;wBACnB,MAAM;oBACR,CAAC;gBACH,CAAC;gBACD,IAAI,WAAW;oBAAE,SAAS;gBAE1B,SAAS,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;oBACpB,QAAQ,EAAE,MAAM;oBAChB,MAAM,EAAE,gBAAgB;oBACxB,YAAY,EAAE,IAAI,CAAC,oBAAoB;oBACvC,MAAM,EAAE,qBAAqB,IAAI,WAAW,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,KAAK,GAAG;iBACvE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,oBAAoB,CAAC,SAAoC;QAC/D,MAAM,SAAS,GAA2B,EAAE,CAAC;QAC7C,uEAAuE;QACvE,iEAAiE;QACjE,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAkB,CAAC;QAEtD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;gBAC1C,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACjE,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/C,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBACf,SAAS,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,MAAM,EAAE,kBAAkB;oBAC1B,YAAY,EAAE,IAAI,CAAC,sBAAsB;oBACzC,MAAM,EAAE,0BAA0B,IAAI,CAAC,QAAQ,KAAK,MAAM,YAAY;iBACvE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,iBAAiB,CAAC,SAAoC;QAC5D,MAAM,SAAS,GAA2B,EAAE,CAAC;QAE7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,SAAS;YACvD,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,IAAI,CAAC,CAAC;YAC7C,IAAI,UAAU,GAAG,IAAI,CAAC,yBAAyB;gBAAE,SAAS;YAC1D,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,SAAS;YAE5B,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAE3E,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,SAAS,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,MAAM,EAAE,eAAe;oBACvB,YAAY,EAAE,IAAI,CAAC,mBAAmB;oBACtC,MAAM,EAAE,iBAAiB,UAAU,gBAAgB,IAAI,CAAC,QAAQ,qCAAqC;iBACtG,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,kBAAkB,CACxB,UAA0B,EAC1B,eAA0C;QAE1C,uFAAuF;QACvF,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YACnC,MAAM,QAAQ,GAAG,UAAU,CAAC,QAA8B,CAAC;YAC3D,IAAI,QAAQ,EAAE,CAAC;gBACb,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;oBACnC,IACE,CAAC,IAAI,CAAC,QAAQ,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC;wBACvD,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAC1B,CAAC;wBACD,OAAO,IAAI,CAAC;oBACd,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/metrics/trend-analyzer.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Cross-Session Trend Analysis — computes longitudinal metrics from stored
+ * session data for weekly trends, comparisons, and text summaries.
+ *
+ * Operates on `FullSessionSummary[]` loaded from `SessionStore`, grouping
+ * by ISO week to compute efficiency, cost, task success, tool call, and
+ * anti-pattern trends over time.
+ */
+import type { MetricAggregator } from '../shared/index.js';
+import type { SessionStore } from '../storage/session-store.js';
+export interface WeeklyDataPoint {
+    readonly week: string;
+    readonly value: number;
+}
+export interface AntiPatternWeeklyPoint {
+    readonly week: string;
+    readonly counts: Record<string, number>;
+}
+export interface TrendData {
+    readonly weeklyEfficiencyTrend: WeeklyDataPoint[];
+    readonly weeklyCostTrend: WeeklyDataPoint[];
+    readonly weeklyTaskSuccessTrend: WeeklyDataPoint[];
+    readonly weeklyToolCallTrend: WeeklyDataPoint[];
+    readonly weeklyAntiPatternTrend: AntiPatternWeeklyPoint[];
+}
+export interface WeekComparison {
+    readonly weekA: string;
+    readonly weekB: string;
+    readonly efficiencyDelta: number | null;
+    readonly efficiencyPctChange: number | null;
+    readonly costDelta: number;
+    readonly costPctChange: number | null;
+    readonly taskSuccessDelta: number;
+    readonly taskSuccessPctChange: number | null;
+    readonly toolCallDelta: number;
+    readonly toolCallPctChange: number | null;
+}
+export interface DeveloperComparison {
+    readonly developer: string;
+    readonly week: string;
+    readonly developerEfficiency: number | null;
+    readonly teamEfficiency: number | null;
+    readonly developerCost: number;
+    readonly teamCost: number;
+    readonly developerTaskSuccess: number;
+    readonly teamTaskSuccess: number;
+}
+export interface ModelComparison {
+    readonly modelA: string;
+    readonly modelB: string;
+    readonly modelACost: number;
+    readonly modelBCost: number;
+    readonly modelAEfficiency: number | null;
+    readonly modelBEfficiency: number | null;
+    readonly modelASessionCount: number;
+    readonly modelBSessionCount: number;
+}
+/**
+ * Simple moving average over a series of values.
+ * For indices where the full window is not available, uses whatever
+ * values are available (partial window at the start).
+ */
+export declare function movingAverage(values: number[], windowSize: number): number[];
+/**
+ * Percentage change from old to new value.
+ * Returns null when oldValue is 0 and newValue is non-zero (undefined growth from zero baseline).
+ * Returns 0 when both are 0.
+ */
+export declare function percentChange(oldValue: number, newValue: number): number | null;
+/**
+ * Detects whether the last value in the array is a significant outlier.
+ * Uses z-score: computes mean and std of all values except the last,
+ * then checks if the last value is beyond `threshold` standard deviations.
+ */
+export declare function significantChange(values: number[], threshold?: number): boolean;
+export declare class TrendAnalyzer {
+    private readonly sessionStore;
+    constructor(options: {
+        sessionStore: SessionStore;
+    });
+    computeTrends(options?: {
+        since?: Date;
+        developer?: string;
+    }): TrendData;
+    compareWeeks(weekA: string, weekB: string): WeekComparison;
+    compareDeveloperToTeam(developer: string, weekId: string): DeveloperComparison;
+    detectModelMigrationImpact(modelA: string, modelB: string): ModelComparison;
+    generateWeekSummary(weekId: string): string;
+    emitWeeklySummaryEvent(weekId: string, aggregator: MetricAggregator): void;
+    private loadWeekAggregate;
+}
+//# sourceMappingURL=trend-analyzer.d.ts.map

package/dist/metrics/trend-analyzer.d.ts.map

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