@pennyfarthing/core 11.2.0 → 11.2.2

package/packages/core/dist/consultation/tandem-metrics.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Tandem Metrics and Token Tracking for Story 86-6
+ *
+ * Tracks consultation token usage, frequency, and outcomes for overhead analysis.
+ * Extends the dialogue manager (86-3) with metrics collection and summary generation.
+ *
+ * All functions are pure or use simple computation — no external dependencies.
+ */
+import type { Outcome } from './dialogue-manager.js';
+/**
+ * Token and timing metrics for a single consultation exchange.
+ * These are tracked separately from leader session tokens (AC1).
+ */
+export interface ExchangeMetrics {
+    /** Tokens sent to the consultation partner (request) */
+    inputTokens: number;
+    /** Tokens received from the consultation partner (response) */
+    outputTokens: number;
+    /** Time in milliseconds for the partner to respond */
+    responseTimeMs: number;
+}
+/**
+ * A dialogue exchange extended with metrics fields.
+ * Mirrors DialogueExchange from dialogue-manager but adds token tracking.
+ */
+export interface MetricsExchange {
+    number: number;
+    timestamp: string;
+    leader: string;
+    partner: string;
+    question: string;
+    recommendation: string;
+    confidence: string;
+    outcome?: Outcome;
+    outcomeNote?: string;
+    /** Consultation-specific metrics (absent for exchanges without tracking) */
+    metrics?: ExchangeMetrics;
+}
+/**
+ * Aggregated metrics across all consultation exchanges in a dialogue.
+ */
+export interface TandemMetricsSummary {
+    /** Number of consultation exchanges */
+    consultationCount: number;
+    /** Total input tokens across all exchanges */
+    totalInputTokens: number;
+    /** Total output tokens across all exchanges */
+    totalOutputTokens: number;
+    /** Combined total tokens (input + output) */
+    totalTokens: number;
+    /** Average response time in milliseconds */
+    avgResponseTimeMs: number;
+    /** Distribution of outcomes: { applied: N, deferred: N, rejected: N, pending: N } */
+    outcomeDistribution: Record<string, number>;
+    /** Tandem overhead as percentage of baseline, or null if baseline not provided */
+    overheadPercent: number | null;
+}
+/**
+ * Aggregate metrics from a list of exchanges with metrics data.
+ * Exchanges without metrics are counted but excluded from token/timing calculations.
+ */
+export declare function aggregateMetrics(exchanges: MetricsExchange[]): TandemMetricsSummary;
+/**
+ * Calculate tandem overhead as a percentage of baseline token cost.
+ * Returns the percentage (e.g., 12.5 for 12.5%).
+ *
+ * @param tandemTokens - Total tokens used by tandem consultations
+ * @param baselineTokens - Total tokens used by the leader session (non-tandem)
+ * @returns Overhead percentage, or null if baselineTokens is zero
+ */
+export declare function calculateOverheadPercent(tandemTokens: number, baselineTokens: number): number | null;
+/**
+ * Check whether tandem overhead is within the acceptable budget threshold.
+ * Default threshold is 25% per story AC5.
+ *
+ * @param overheadPercent - The calculated overhead percentage
+ * @param threshold - Maximum acceptable overhead percentage (default: 25)
+ * @returns true if within budget, false if over
+ */
+export declare function isWithinBudget(overheadPercent: number | null, threshold?: number): boolean;
+/**
+ * Format a TandemMetricsSummary as markdown lines for the dialogue file summary section.
+ * Returns an array of markdown bullet lines (without the ## Summary header).
+ */
+export declare function formatMetricsSummary(metrics: TandemMetricsSummary): string[];
+/**
+ * Parse metrics fields from an existing dialogue file summary section.
+ * Returns null if no metrics are found in the summary.
+ */
+export declare function parseMetricsFromSummary(summaryContent: string): TandemMetricsSummary | null;
+//# sourceMappingURL=tandem-metrics.d.ts.map

package/packages/core/dist/consultation/tandem-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tandem-metrics.d.ts","sourceRoot":"","sources":["../../src/consultation/tandem-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAMrD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,oBAAoB,CAiCnF;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,MAAM,GAAG,IAAI,CAGf;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAIT;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAmB5E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CA8B3F"}

package/packages/core/dist/consultation/tandem-metrics.js

@@ -0,0 +1,131 @@
+/**
+ * Tandem Metrics and Token Tracking for Story 86-6
+ *
+ * Tracks consultation token usage, frequency, and outcomes for overhead analysis.
+ * Extends the dialogue manager (86-3) with metrics collection and summary generation.
+ *
+ * All functions are pure or use simple computation — no external dependencies.
+ */
+// =============================================================================
+// Metrics Calculation
+// =============================================================================
+/**
+ * Aggregate metrics from a list of exchanges with metrics data.
+ * Exchanges without metrics are counted but excluded from token/timing calculations.
+ */
+export function aggregateMetrics(exchanges) {
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalResponseTimeMs = 0;
+    let metricsCount = 0;
+    const outcomeDistribution = {
+        applied: 0,
+        deferred: 0,
+        rejected: 0,
+        pending: 0,
+    };
+    for (const ex of exchanges) {
+        if (ex.metrics) {
+            totalInputTokens += ex.metrics.inputTokens;
+            totalOutputTokens += ex.metrics.outputTokens;
+            totalResponseTimeMs += ex.metrics.responseTimeMs;
+            metricsCount++;
+        }
+        const outcome = ex.outcome ?? 'pending';
+        outcomeDistribution[outcome] = (outcomeDistribution[outcome] ?? 0) + 1;
+    }
+    return {
+        consultationCount: exchanges.length,
+        totalInputTokens,
+        totalOutputTokens,
+        totalTokens: totalInputTokens + totalOutputTokens,
+        avgResponseTimeMs: metricsCount > 0 ? Math.round(totalResponseTimeMs / metricsCount) : 0,
+        outcomeDistribution,
+        overheadPercent: null,
+    };
+}
+/**
+ * Calculate tandem overhead as a percentage of baseline token cost.
+ * Returns the percentage (e.g., 12.5 for 12.5%).
+ *
+ * @param tandemTokens - Total tokens used by tandem consultations
+ * @param baselineTokens - Total tokens used by the leader session (non-tandem)
+ * @returns Overhead percentage, or null if baselineTokens is zero
+ */
+export function calculateOverheadPercent(tandemTokens, baselineTokens) {
+    if (baselineTokens === 0)
+        return null;
+    return Math.round((tandemTokens / baselineTokens) * 1000) / 10;
+}
+/**
+ * Check whether tandem overhead is within the acceptable budget threshold.
+ * Default threshold is 25% per story AC5.
+ *
+ * @param overheadPercent - The calculated overhead percentage
+ * @param threshold - Maximum acceptable overhead percentage (default: 25)
+ * @returns true if within budget, false if over
+ */
+export function isWithinBudget(overheadPercent, threshold) {
+    if (overheadPercent === null)
+        return true;
+    const limit = threshold ?? 25;
+    return overheadPercent < limit;
+}
+// =============================================================================
+// Summary Formatting
+// =============================================================================
+/**
+ * Format a TandemMetricsSummary as markdown lines for the dialogue file summary section.
+ * Returns an array of markdown bullet lines (without the ## Summary header).
+ */
+export function formatMetricsSummary(metrics) {
+    const lines = [];
+    lines.push(`- **Consultations:** ${metrics.consultationCount}`);
+    lines.push(`- **Tokens:** ${metrics.totalTokens} (input: ${metrics.totalInputTokens}, output: ${metrics.totalOutputTokens})`);
+    lines.push(`- **Avg Response Time:** ${metrics.avgResponseTimeMs}ms`);
+    const dist = metrics.outcomeDistribution;
+    const parts = ['applied', 'deferred', 'rejected', 'pending']
+        .map(k => `${k}: ${dist[k] ?? 0}`)
+        .join(', ');
+    lines.push(`- **Outcomes:** ${parts}`);
+    if (metrics.overheadPercent !== null) {
+        lines.push(`- **Overhead:** ${metrics.overheadPercent}%`);
+    }
+    else {
+        lines.push(`- **Overhead:** N/A`);
+    }
+    return lines;
+}
+/**
+ * Parse metrics fields from an existing dialogue file summary section.
+ * Returns null if no metrics are found in the summary.
+ */
+export function parseMetricsFromSummary(summaryContent) {
+    const consultMatch = summaryContent.match(/\*\*Consultations:\*\*\s*(\d+)/);
+    const tokensMatch = summaryContent.match(/\*\*Tokens:\*\*\s*(\d+)\s*\(input:\s*(\d+),\s*output:\s*(\d+)\)/);
+    const responseMatch = summaryContent.match(/\*\*Avg Response Time:\*\*\s*(\d+)ms/);
+    if (!consultMatch || !tokensMatch)
+        return null;
+    const outcomesMatch = summaryContent.match(/\*\*Outcomes:\*\*\s*(.+)/);
+    const outcomeDistribution = { applied: 0, deferred: 0, rejected: 0, pending: 0 };
+    if (outcomesMatch) {
+        for (const part of outcomesMatch[1].split(',')) {
+            const [key, val] = part.trim().split(':').map(s => s.trim());
+            if (key && val !== undefined) {
+                outcomeDistribution[key] = parseInt(val, 10);
+            }
+        }
+    }
+    const overheadMatch = summaryContent.match(/\*\*Overhead:\*\*\s*([\d.]+)%/);
+    const overheadPercent = overheadMatch ? parseFloat(overheadMatch[1]) : null;
+    return {
+        consultationCount: parseInt(consultMatch[1], 10),
+        totalTokens: parseInt(tokensMatch[1], 10),
+        totalInputTokens: parseInt(tokensMatch[2], 10),
+        totalOutputTokens: parseInt(tokensMatch[3], 10),
+        avgResponseTimeMs: responseMatch ? parseInt(responseMatch[1], 10) : 0,
+        outcomeDistribution,
+        overheadPercent,
+    };
+}
+//# sourceMappingURL=tandem-metrics.js.map

package/packages/core/dist/consultation/tandem-metrics.js.map

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

package/packages/core/dist/consultation/tandem-metrics.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tests for Story 86-6: Tandem Metrics and Token Tracking
+ *
+ * RED state tests for consultation token usage, frequency, and outcome metrics.
+ * These metrics are tracked separately from leader session tokens and written
+ * to the dialogue file summary section.
+ *
+ * ACs covered:
+ *   AC1: Consultation tokens logged separately from leader session tokens
+ *   AC2: Metrics captured: count, total tokens, avg response time, outcome distribution
+ *   AC3: Metrics written to dialogue file summary section
+ *   AC4: Session summary includes tandem overhead percentage
+ *   AC5: Target: consultation overhead < 25% of baseline story token cost
+ *
+ * Run with: npm test
+ */
+export {};
+//# sourceMappingURL=tandem-metrics.test.d.ts.map

package/packages/core/dist/consultation/tandem-metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tandem-metrics.test.d.ts","sourceRoot":"","sources":["../../src/consultation/tandem-metrics.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}