swarm-engine 1.41.0 → 1.51.0

package/dist/runtime/benefits.js

@@ -0,0 +1,775 @@
+/**
+ * BenefitsCollector — aggregates optimization metrics during orchestration
+ * and produces a user-facing summary of what the engine did for them.
+ */
+// ─── Constants ────────────────────────────────────────────────
+/** Approximate base payload loaded per Claude Code session spawn (system prompt + tool schemas + MCP + skills).
+ * Dropped from ~45k to ~31k in Wave 1 via ENABLE_TOOL_SEARCH (deferred tool loading). */
+export const BASE_PAYLOAD_TOKENS_PER_AGENT = 31_000;
+/** Cache-read pricing model: cache_read is billed at ~10% of regular input rate, so each
+ *  cache_read token represents ~90% savings vs the equivalent regular input token.
+ *  For Opus 4.6 we assume $5/MTok regular input → $4.5/MTok (90%) savings per cache_read token. */
+export const CACHE_SAVINGS_RATE = 4.5 / 1_000_000;
+/** Minimum cache-read ratio over the window for cliff detection to fire
+ *  (if baseline is already low, the "cliff" isn't meaningful). */
+const CLIFF_BASELINE_FLOOR = 0.2;
+/** Current-ratio-vs-baseline drop threshold — >50% drop = cliff. */
+const CLIFF_DROP_RATIO = 0.5;
+/** Token floor for cliff detection — noise floor avoids flagging tiny requests. */
+const CLIFF_NOISE_FLOOR_TOKENS = 1000;
+/** Rolling history window size per agentType for baseline computation. */
+const CLIFF_HISTORY_WINDOW = 10;
+/** Minimum number of prior samples required before cliff detection activates. */
+const CLIFF_MIN_HISTORY = 3;
+// ─── Collector ────────────────────────────────────────────────
+/**
+ * Collects benefits metrics during orchestration execution.
+ * Call increment methods as optimizations occur, then call `build()` at the end.
+ */
+export class BenefitsCollector {
+    // Token savings accumulators
+    _smartRoutingSaved = 0;
+    _promptCompressionSaved = 0;
+    _verbatimCompactionSaved = 0;
+    _contextDecaySaved = 0;
+    _contextFilteringSaved = 0;
+    /** Pre-computed estimate accumulated via {@link addCacheSavingsUsd} (caller-side guess
+     *  from shared-prefix length × parallel agent count). Used as a fallback only when
+     *  no real API cache_read data has been recorded. */
+    _cacheSavingsUsdEstimate = 0;
+    /** Real savings accumulated via {@link recordApiUsage} from API-reported cache_read
+     *  tokens. Takes priority over {@link _cacheSavingsUsdEstimate} in {@link build}. */
+    _cacheSavingsUsdReal = 0;
+    // Graph counters
+    _contextRoutingDecisions = 0;
+    _coModHintsInjected = 0;
+    _confidenceGatesEvaluated = 0;
+    _gatesTriggered = 0;
+    _reviewFindingsRecorded = 0;
+    // ML counters
+    _gnnPredictionsMade = 0;
+    _highRiskNodesIdentified = 0;
+    _agentsDroppedML = 0;
+    _agentsDroppedRules = 0;
+    _dropoutTokensSaved = 0;
+    _affinityEscalations = 0;
+    _trajectoryPredictionsMade = 0;
+    // Adaptive counters
+    _phasesSkipped = 0;
+    _modelDowngrades = 0;
+    _modelUpgrades = 0;
+    _cascadeTierChanges = 0;
+    _budgetWarnings = 0;
+    _livingSpecUpdates = 0;
+    // Cache cliff detection state
+    _cacheCliffs = 0;
+    _agentCacheRatios = new Map(); // agentType → recent ratios (last CLIFF_HISTORY_WINDOW)
+    // Cold-wake counter (incremented via recordColdWake, typically wired to 'cache:cold-wake' events)
+    _coldWakes = 0;
+    bus = null;
+    constructor(bus) {
+        this.bus = bus ?? null;
+    }
+    // ─── Token savings methods ────────────────────────────────
+    addSmartRoutingSaved(tokens) {
+        this._smartRoutingSaved += tokens;
+    }
+    addPromptCompressionSaved(tokens) {
+        this._promptCompressionSaved += tokens;
+    }
+    addVerbatimCompactionSaved(tokens) {
+        this._verbatimCompactionSaved += tokens;
+    }
+    addContextDecaySaved(tokens) {
+        this._contextDecaySaved += tokens;
+    }
+    addContextFilteringSaved(tokens) {
+        this._contextFilteringSaved += tokens;
+    }
+    /**
+     * Add a pre-computed cache savings estimate (caller-side). Used by the engine
+     * for shared-prefix-across-parallel-agents projections before any real API data
+     * is available. This estimate is **superseded** by real data from
+     * {@link recordApiUsage} in {@link build} — the two are tracked separately to
+     * avoid double-counting.
+     */
+    addCacheSavingsUsd(usd) {
+        this._cacheSavingsUsdEstimate += usd;
+    }
+    /**
+     * Record actual API usage and credit real cache savings based on cache_read tokens
+     * reported by the Claude API. When any real data is recorded, the value reported
+     * by {@link build} switches to the real total, ignoring the caller-side estimate
+     * accumulated via {@link addCacheSavingsUsd} (the two were previously double-counted).
+     *
+     * Pricing: see {@link CACHE_SAVINGS_RATE} ($4.5/MTok cache_read).
+     *
+     * Also performs **cross-phase** cache-cliff detection per agentType — when an agent's
+     * cache_read ratio drops >{@link CLIFF_DROP_RATIO} vs its rolling baseline (over
+     * {@link CLIFF_HISTORY_WINDOW} prior samples), emits `cache:cliff` to the EventBus
+     * (if any) and increments the cliff counter.
+     *
+     * **Limitation**: detection happens at agent-execution granularity (one call per
+     * AgentInstance.usage roll-up). Mid-conversation cache TTL expiry within a single
+     * agent run is NOT detected here — that would require a per-API-call hook in the
+     * backend (see BackendOptions for per-call observability options if/when added).
+     */
+    recordApiUsage(usage, agentType) {
+        // ─── Real savings credit (separate accumulator from estimate) ─────────
+        this._cacheSavingsUsdReal += (usage.cacheReadInputTokens ?? 0) * CACHE_SAVINGS_RATE;
+        // ─── Cache cliff detection ────────────────────────────
+        // Only meaningful when we know which agentType this call belongs to.
+        if (!agentType)
+            return;
+        const cacheRead = usage.cacheReadInputTokens ?? 0;
+        const input = usage.inputTokens ?? 0;
+        const totalInput = cacheRead + input;
+        // Noise floor — avoid false positives on tiny requests where ratios swing wildly.
+        if (totalInput < CLIFF_NOISE_FLOOR_TOKENS)
+            return;
+        const ratio = cacheRead / totalInput;
+        const history = this._agentCacheRatios.get(agentType) ?? [];
+        if (history.length >= CLIFF_MIN_HISTORY) {
+            // Need at least CLIFF_MIN_HISTORY prior samples to establish a meaningful baseline.
+            const baseline = history.reduce((a, b) => a + b, 0) / history.length;
+            // Only flag when baseline was non-trivial AND dropped by more than the threshold.
+            if (baseline > CLIFF_BASELINE_FLOOR && ratio < baseline * CLIFF_DROP_RATIO) {
+                this._cacheCliffs++;
+                // Regular-vs-cache price delta: ($5 - $0.5) / 1M = $4.5/MTok extra cost per token
+                // moved from cache to regular input. Approximate cost of the missed cache.
+                const estimatedExtraCostUsd = (totalInput * (baseline - ratio) * (5 - 0.5)) / 1_000_000;
+                this.bus?.emit('cache:cliff', {
+                    agentType,
+                    previousRatio: baseline,
+                    currentRatio: ratio,
+                    estimatedExtraCostUsd,
+                }, 'benefits-collector');
+            }
+        }
+        history.push(ratio);
+        if (history.length > CLIFF_HISTORY_WINDOW)
+            history.shift();
+        this._agentCacheRatios.set(agentType, history);
+    }
+    /**
+     * Record a cold-wake event — fired when an agent's idle gap exceeds the prompt cache
+     * TTL (typically 5 minutes), so the next invocation rebuilds the cache from cold and
+     * pays full input price. Typically wired to the `cache:cold-wake` event from
+     * AgentRunner via `bus.on(...)` in the engine.
+     */
+    recordColdWake() {
+        this._coldWakes++;
+    }
+    // ─── Graph methods ────────────────────────────────────────
+    addContextRoutingDecision() {
+        this._contextRoutingDecisions++;
+    }
+    addCoModHintInjected() {
+        this._coModHintsInjected++;
+    }
+    addConfidenceGateEvaluated(triggered) {
+        this._confidenceGatesEvaluated++;
+        if (triggered)
+            this._gatesTriggered++;
+    }
+    addReviewFindingRecorded() {
+        this._reviewFindingsRecorded++;
+    }
+    // ─── ML methods ───────────────────────────────────────────
+    addGnnPrediction(highRiskCount) {
+        this._gnnPredictionsMade++;
+        this._highRiskNodesIdentified += highRiskCount;
+    }
+    addAgentDroppedML(estimatedTokensSaved) {
+        this._agentsDroppedML++;
+        this._dropoutTokensSaved += estimatedTokensSaved;
+    }
+    addAgentDroppedRules() {
+        this._agentsDroppedRules++;
+    }
+    addAffinityEscalation() {
+        this._affinityEscalations++;
+    }
+    addTrajectoryPrediction() {
+        this._trajectoryPredictionsMade++;
+    }
+    // ─── Adaptive methods ─────────────────────────────────────
+    addPhaseSkipped() {
+        this._phasesSkipped++;
+    }
+    addModelDowngrade() {
+        this._modelDowngrades++;
+    }
+    addModelUpgrade() {
+        this._modelUpgrades++;
+    }
+    addCascadeTierChange() {
+        this._cascadeTierChanges++;
+    }
+    addBudgetWarning() {
+        this._budgetWarnings++;
+    }
+    addLivingSpecUpdate() {
+        this._livingSpecUpdates++;
+    }
+    // ─── Build ────────────────────────────────────────────────
+    /**
+     * Build the final summary. Call at orchestration end.
+     *
+     * @param opts.actualTotalTokens — total input tokens actually consumed (used to compute savingsPercent)
+     * @param opts.actualCostUsd — total USD cost of the orchestration
+     * @param opts.durationMs — wall-clock duration in milliseconds
+     * @param opts.agentsExecuted — number of agents that ran
+     * @param opts.totalAgentTurns — sum of per-agent turns (each turn re-sends full context in stateless loop)
+     * @param opts.phasesExecuted — number of phases that ran
+     * @param opts.historicalAvgCostUsd — average cost for this pattern from history (null if none)
+     * @param opts.patternRunsRecorded — how many historical runs exist for this pattern
+     * @param opts.historicalSuccessRate — success rate from history (null if none)
+     */
+    build(opts) {
+        const totalTokensSaved = this._smartRoutingSaved +
+            this._promptCompressionSaved +
+            this._verbatimCompactionSaved +
+            this._contextDecaySaved +
+            this._contextFilteringSaved +
+            this._dropoutTokensSaved;
+        // What would have been used without optimizations = actual + saved
+        const wouldHaveUsed = opts.actualTotalTokens + totalTokensSaved;
+        const savingsPercent = totalTokensSaved > 0 && wouldHaveUsed > 0 ? Math.round((totalTokensSaved / wouldHaveUsed) * 100) : 0;
+        const costDelta = opts.historicalAvgCostUsd != null ? opts.actualCostUsd - opts.historicalAvgCostUsd : null;
+        // Real API data takes priority over caller-side estimate to avoid double-counting.
+        // If any real data was recorded (recordApiUsage with cache_read), use that exclusively;
+        // otherwise fall back to the pre-computed estimate (addCacheSavingsUsd).
+        const cacheSavingsUsd = this._cacheSavingsUsdReal > 0 ? this._cacheSavingsUsdReal : this._cacheSavingsUsdEstimate;
+        const cacheSavingsMeasured = this._cacheSavingsUsdReal > 0;
+        // ─── Turn-based compounding ──────────────────────────────
+        // The stateless loop re-sends full context every turn, so per-prompt/per-context
+        // savings compound across turns. Use conservative floor of avgTurns.
+        const totalAgentTurns = opts.totalAgentTurns ?? opts.agentsExecuted;
+        const avgTurns = totalAgentTurns / Math.max(opts.agentsExecuted, 1);
+        // Only compound savings that are part of the persistent re-sent context
+        const compoundable = this._smartRoutingSaved + this._promptCompressionSaved + this._contextDecaySaved + this._contextFilteringSaved;
+        // Non-compounding savings (output-side compaction or spawn-avoidance)
+        const nonCompounding = this._verbatimCompactionSaved + this._dropoutTokensSaved;
+        // Conservative: use floor of avgTurns (under-estimate)
+        const compoundedTotalSaved = Math.floor(compoundable * Math.floor(avgTurns)) + nonCompounding;
+        return {
+            tokens: {
+                smartRoutingSaved: this._smartRoutingSaved,
+                promptCompressionSaved: this._promptCompressionSaved,
+                verbatimCompactionSaved: this._verbatimCompactionSaved,
+                contextDecaySaved: this._contextDecaySaved,
+                contextFilteringSaved: this._contextFilteringSaved,
+                cacheSavingsUsd: Math.round(cacheSavingsUsd * 10000) / 10000,
+                cacheSavingsMeasured,
+                totalTokensSaved,
+                compoundedTotalSaved,
+                savingsPercent,
+            },
+            graph: {
+                contextRoutingDecisions: this._contextRoutingDecisions,
+                coModHintsInjected: this._coModHintsInjected,
+                confidenceGatesEvaluated: this._confidenceGatesEvaluated,
+                gatesTriggered: this._gatesTriggered,
+                patternRunsRecorded: opts.patternRunsRecorded ?? 0,
+                historicalSuccessRate: opts.historicalSuccessRate ?? null,
+                reviewFindingsRecorded: this._reviewFindingsRecorded,
+            },
+            ml: {
+                gnnPredictionsMade: this._gnnPredictionsMade,
+                highRiskNodesIdentified: this._highRiskNodesIdentified,
+                agentsDroppedML: this._agentsDroppedML,
+                agentsDroppedRules: this._agentsDroppedRules,
+                dropoutTokensSaved: this._dropoutTokensSaved,
+                affinityEscalations: this._affinityEscalations,
+                trajectoryPredictionsMade: this._trajectoryPredictionsMade,
+            },
+            adaptive: {
+                phasesSkipped: this._phasesSkipped,
+                modelDowngrades: this._modelDowngrades,
+                modelUpgrades: this._modelUpgrades,
+                cascadeTierChanges: this._cascadeTierChanges,
+                budgetWarnings: this._budgetWarnings,
+                livingSpecUpdates: this._livingSpecUpdates,
+            },
+            actualCostUsd: Math.round(opts.actualCostUsd * 10000) / 10000,
+            historicalAvgCostUsd: opts.historicalAvgCostUsd ?? null,
+            costDeltaUsd: costDelta != null ? Math.round(costDelta * 10000) / 10000 : null,
+            durationMs: opts.durationMs,
+            agentsExecuted: opts.agentsExecuted,
+            phasesExecuted: opts.phasesExecuted,
+            totalAgentTurns,
+            avgTurnsPerAgent: Math.round(avgTurns * 100) / 100,
+            cacheCliffs: this._cacheCliffs,
+            coldWakes: this._coldWakes,
+            basePayloadEstimateTokens: totalAgentTurns * BASE_PAYLOAD_TOKENS_PER_AGENT,
+        };
+    }
+    /** Reset all counters */
+    reset() {
+        this._smartRoutingSaved = 0;
+        this._promptCompressionSaved = 0;
+        this._verbatimCompactionSaved = 0;
+        this._contextDecaySaved = 0;
+        this._contextFilteringSaved = 0;
+        this._cacheSavingsUsdEstimate = 0;
+        this._cacheSavingsUsdReal = 0;
+        this._contextRoutingDecisions = 0;
+        this._coModHintsInjected = 0;
+        this._confidenceGatesEvaluated = 0;
+        this._gatesTriggered = 0;
+        this._reviewFindingsRecorded = 0;
+        this._gnnPredictionsMade = 0;
+        this._highRiskNodesIdentified = 0;
+        this._agentsDroppedML = 0;
+        this._agentsDroppedRules = 0;
+        this._dropoutTokensSaved = 0;
+        this._affinityEscalations = 0;
+        this._trajectoryPredictionsMade = 0;
+        this._phasesSkipped = 0;
+        this._modelDowngrades = 0;
+        this._modelUpgrades = 0;
+        this._cascadeTierChanges = 0;
+        this._budgetWarnings = 0;
+        this._livingSpecUpdates = 0;
+        this._cacheCliffs = 0;
+        this._agentCacheRatios.clear();
+        this._coldWakes = 0;
+    }
+}
+// ─── Formatter ────────────────────────────────────────────────
+/** Format a number with commas: 12345 → "12,345" */
+function fmtNum(n) {
+    return n.toLocaleString('en-US');
+}
+/** Format a USD amount to 4 decimal places */
+function fmtUsd(n) {
+    return `$${n.toFixed(4)}`;
+}
+/**
+ * Format a BenefitsSummary into a human-readable string.
+ * Only shows sections that have at least one non-zero metric.
+ * Uses plain text (no box-drawing characters).
+ */
+export function formatBenefitsSummary(summary) {
+    const sections = [];
+    // ─── Token Efficiency ───────────────────────────────────
+    const t = summary.tokens;
+    const tokenLines = [];
+    if (t.smartRoutingSaved > 0) {
+        tokenLines.push(`  Smart routing saved ~${fmtNum(t.smartRoutingSaved)} tokens (filtered irrelevant phase outputs)`);
+    }
+    if (t.promptCompressionSaved > 0) {
+        tokenLines.push(`  Prompt compression saved ~${fmtNum(t.promptCompressionSaved)} tokens (stripped markdown boilerplate)`);
+    }
+    if (t.verbatimCompactionSaved > 0) {
+        tokenLines.push(`  Verbatim compaction saved ~${fmtNum(t.verbatimCompactionSaved)} tokens (replaced file reads with refs)`);
+    }
+    if (t.contextDecaySaved > 0) {
+        tokenLines.push(`  Context decay saved ~${fmtNum(t.contextDecaySaved)} tokens (older phases summarized)`);
+    }
+    if (t.contextFilteringSaved > 0) {
+        tokenLines.push(`  Context filtering saved ~${fmtNum(t.contextFilteringSaved)} tokens (per-agent file-scope filtering)`);
+    }
+    if (t.cacheSavingsUsd > 0) {
+        const cacheTag = t.cacheSavingsMeasured ? '(measured)' : '(est.)';
+        tokenLines.push(`  Cache savings ${cacheTag}: ${fmtUsd(t.cacheSavingsUsd)} (shared prefix caching across parallel agents)`);
+    }
+    if (t.totalTokensSaved > 0) {
+        tokenLines.push(`  Per-injection total: ~${fmtNum(t.totalTokensSaved)} tokens saved (${t.savingsPercent}% reduction)`);
+    }
+    if (t.compoundedTotalSaved > 0 && t.compoundedTotalSaved !== t.totalTokensSaved) {
+        tokenLines.push(`  Compounded savings (conservative est.): ~${fmtNum(t.compoundedTotalSaved)} tokens (x avg ${fmtNum(summary.avgTurnsPerAgent)} turns/agent)`);
+    }
+    if (tokenLines.length > 0) {
+        sections.push(`TOKEN EFFICIENCY\n${tokenLines.join('\n')}`);
+    }
+    // ─── Knowledge Graph ────────────────────────────────────
+    const g = summary.graph;
+    const graphLines = [];
+    if (g.contextRoutingDecisions > 0) {
+        graphLines.push(`  ${fmtNum(g.contextRoutingDecisions)} context routing decisions (graph-optimized context per agent)`);
+    }
+    if (g.coModHintsInjected > 0) {
+        graphLines.push(`  ${fmtNum(g.coModHintsInjected)} co-modification hints (suggested related files from history)`);
+    }
+    if (g.confidenceGatesEvaluated > 0) {
+        const triggeredPart = g.gatesTriggered > 0
+            ? `, ${fmtNum(g.gatesTriggered)} triggered (prevented low-quality handoff)`
+            : ', 0 triggered';
+        graphLines.push(`  ${fmtNum(g.confidenceGatesEvaluated)} confidence gates evaluated${triggeredPart}`);
+    }
+    if (g.patternRunsRecorded > 0 && g.historicalSuccessRate != null) {
+        graphLines.push(`  Pattern has ${g.historicalSuccessRate}% success rate across ${fmtNum(g.patternRunsRecorded)} historical runs`);
+    }
+    if (g.reviewFindingsRecorded > 0) {
+        graphLines.push(`  ${fmtNum(g.reviewFindingsRecorded)} review findings recorded to graph`);
+    }
+    if (graphLines.length > 0) {
+        sections.push(`KNOWLEDGE GRAPH\n${graphLines.join('\n')}`);
+    }
+    // ─── ML/GNN Predictions ─────────────────────────────────
+    const m = summary.ml;
+    const mlLines = [];
+    if (m.gnnPredictionsMade > 0) {
+        mlLines.push(`  ${fmtNum(m.gnnPredictionsMade)} GNN risk predictions, ${fmtNum(m.highRiskNodesIdentified)} high-risk nodes identified`);
+    }
+    if (m.agentsDroppedML > 0) {
+        mlLines.push(`  ${fmtNum(m.agentsDroppedML)} agents dropped by predictive dropout (saved ~${fmtNum(m.dropoutTokensSaved)} tokens)`);
+    }
+    if (m.agentsDroppedRules > 0) {
+        mlLines.push(`  ${fmtNum(m.agentsDroppedRules)} agents dropped by rule-based dropout`);
+    }
+    if (m.affinityEscalations > 0) {
+        mlLines.push(`  ${fmtNum(m.affinityEscalations)} affinity escalation${m.affinityEscalations === 1 ? '' : 's'} (upgraded model for historically-difficult files)`);
+    }
+    if (m.trajectoryPredictionsMade > 0) {
+        mlLines.push(`  ${fmtNum(m.trajectoryPredictionsMade)} trajectory predictions (success probability forecasts)`);
+    }
+    if (mlLines.length > 0) {
+        sections.push(`ML/GNN PREDICTIONS\n${mlLines.join('\n')}`);
+    }
+    // ─── Adaptive Optimization ──────────────────────────────
+    const a = summary.adaptive;
+    const adaptiveLines = [];
+    if (a.phasesSkipped > 0) {
+        adaptiveLines.push(`  ${fmtNum(a.phasesSkipped)} phase${a.phasesSkipped === 1 ? '' : 's'} skipped (replanner determined ${a.phasesSkipped === 1 ? 'it was' : 'they were'} redundant)`);
+    }
+    if (a.modelDowngrades > 0) {
+        adaptiveLines.push(`  ${fmtNum(a.modelDowngrades)} model downgrade${a.modelDowngrades === 1 ? '' : 's'} (used cheaper model where safe)`);
+    }
+    if (a.modelUpgrades > 0) {
+        adaptiveLines.push(`  ${fmtNum(a.modelUpgrades)} model upgrade${a.modelUpgrades === 1 ? '' : 's'} (used more capable model where needed)`);
+    }
+    if (a.cascadeTierChanges > 0) {
+        adaptiveLines.push(`  ${fmtNum(a.cascadeTierChanges)} cascade tier change${a.cascadeTierChanges === 1 ? '' : 's'} (started cheap, escalated on failure)`);
+    }
+    if (a.budgetWarnings > 0) {
+        adaptiveLines.push(`  ${fmtNum(a.budgetWarnings)} budget warning${a.budgetWarnings === 1 ? '' : 's'} issued`);
+    }
+    if (a.livingSpecUpdates > 0) {
+        adaptiveLines.push(`  Living spec refined ${fmtNum(a.livingSpecUpdates)} time${a.livingSpecUpdates === 1 ? '' : 's'} during execution`);
+    }
+    if (adaptiveLines.length > 0) {
+        sections.push(`ADAPTIVE OPTIMIZATION\n${adaptiveLines.join('\n')}`);
+    }
+    // ─── Cost line ──────────────────────────────────────────
+    let costLine = `COST: ${fmtUsd(summary.actualCostUsd)}`;
+    if (summary.historicalAvgCostUsd != null && summary.costDeltaUsd != null) {
+        const direction = summary.costDeltaUsd <= 0 ? 'saved' : 'over';
+        const delta = Math.abs(summary.costDeltaUsd);
+        costLine += ` (historical avg: ${fmtUsd(summary.historicalAvgCostUsd)}, ${direction} ${fmtUsd(delta)} vs baseline)`;
+    }
+    sections.push(costLine);
+    return sections.join('\n\n');
+}
+// ─── Styled Table Formatter ──────────────────────────────────
+/** Measure display width in a monospace terminal (ASCII = 1 col) */
+function displayWidth(s) {
+    let w = 0;
+    for (const ch of s) {
+        // East Asian wide characters take 2 columns; everything else takes 1.
+        // Simplified: codepoints above 0x1100 that are CJK/emoji get 2, rest get 1.
+        const cp = ch.codePointAt(0) ?? 0;
+        if ((cp >= 0x1100 && cp <= 0x115f) ||
+            (cp >= 0x2e80 && cp <= 0xa4cf) ||
+            (cp >= 0xac00 && cp <= 0xd7a3) ||
+            (cp >= 0xf900 && cp <= 0xfaff) ||
+            (cp >= 0xfe10 && cp <= 0xfe6f) ||
+            (cp >= 0xff01 && cp <= 0xff60) ||
+            (cp >= 0xffe0 && cp <= 0xffe6) ||
+            (cp >= 0x1f000 && cp <= 0x1faff) ||
+            (cp >= 0x20000 && cp <= 0x2fa1f)) {
+            w += 2;
+        }
+        else {
+            w += 1;
+        }
+    }
+    return w;
+}
+/** Right-pad a string to a target display width */
+function padTo(s, target) {
+    const gap = target - displayWidth(s);
+    return s + ' '.repeat(Math.max(gap, 0));
+}
+/**
+ * Format a BenefitsSummary as a styled box-drawing table.
+ * Only shows sections that have at least one non-zero metric.
+ * No emojis inside the box — uses text labels to avoid alignment issues.
+ */
+export function formatBenefitsTable(summary) {
+    const sections = [];
+    // ─── Token Efficiency ───────────────────────────────────
+    const t = summary.tokens;
+    const tokenRows = [];
+    if (t.smartRoutingSaved > 0) {
+        tokenRows.push({
+            label: 'Smart routing',
+            value: `-${fmtNum(t.smartRoutingSaved)} tok`,
+            detail: 'filtered phase outputs',
+        });
+    }
+    if (t.promptCompressionSaved > 0) {
+        tokenRows.push({
+            label: 'Prompt compression',
+            value: `-${fmtNum(t.promptCompressionSaved)} tok`,
+            detail: 'stripped boilerplate',
+        });
+    }
+    if (t.verbatimCompactionSaved > 0) {
+        tokenRows.push({
+            label: 'Verbatim compaction',
+            value: `-${fmtNum(t.verbatimCompactionSaved)} tok`,
+            detail: 'replaced with refs',
+        });
+    }
+    if (t.contextDecaySaved > 0) {
+        tokenRows.push({
+            label: 'Context decay',
+            value: `-${fmtNum(t.contextDecaySaved)} tok`,
+            detail: 'older phases summarized',
+        });
+    }
+    if (t.contextFilteringSaved > 0) {
+        tokenRows.push({
+            label: 'Context filtering',
+            value: `-${fmtNum(t.contextFilteringSaved)} tok`,
+            detail: 'file-scope filtering',
+        });
+    }
+    if (t.cacheSavingsUsd > 0) {
+        const cacheLabel = t.cacheSavingsMeasured ? 'Cache savings (measured)' : 'Cache savings (est.)';
+        tokenRows.push({ label: cacheLabel, value: fmtUsd(t.cacheSavingsUsd), detail: 'prefix sharing' });
+    }
+    if (t.totalTokensSaved > 0) {
+        tokenRows.push({
+            label: 'Per-injection saved',
+            value: `-${fmtNum(t.totalTokensSaved)} tok`,
+            detail: `${t.savingsPercent}% reduction`,
+        });
+    }
+    if (t.compoundedTotalSaved > 0 && t.compoundedTotalSaved !== t.totalTokensSaved) {
+        tokenRows.push({
+            label: 'Compounded (est.)',
+            value: `~${fmtNum(t.compoundedTotalSaved)} tok`,
+            detail: `x avg ${fmtNum(summary.avgTurnsPerAgent)} turns/agent (conservative)`,
+        });
+    }
+    if (summary.basePayloadEstimateTokens > 0) {
+        const avgT = summary.avgTurnsPerAgent;
+        tokenRows.push({
+            label: 'Base-payload tax',
+            value: `+${fmtNum(summary.basePayloadEstimateTokens)} tok`,
+            detail: `${fmtNum(summary.totalAgentTurns)} turns x ~31k/turn (${fmtNum(summary.agentsExecuted)} agents, avg ${fmtNum(avgT)} turns)`,
+        });
+    }
+    if (summary.cacheCliffs > 0) {
+        tokenRows.push({
+            label: 'Cache cliffs',
+            value: `${summary.cacheCliffs} detected`,
+            detail: 'cache_read ratio dropped >50%',
+        });
+    }
+    if (summary.coldWakes > 0) {
+        tokenRows.push({
+            label: 'Cold wakes',
+            value: `${summary.coldWakes} detected`,
+            detail: 'idle gap > prompt cache TTL',
+        });
+    }
+    if (tokenRows.length > 0) {
+        sections.push({ title: 'TOKEN EFFICIENCY', rows: tokenRows });
+    }
+    // ─── Knowledge Graph ────────────────────────────────────
+    const g = summary.graph;
+    const graphRows = [];
+    if (g.contextRoutingDecisions > 0) {
+        graphRows.push({
+            label: 'Context routing',
+            value: `${fmtNum(g.contextRoutingDecisions)}`,
+            detail: 'graph-optimized per agent',
+        });
+    }
+    if (g.coModHintsInjected > 0) {
+        graphRows.push({
+            label: 'Co-mod hints',
+            value: `${fmtNum(g.coModHintsInjected)}`,
+            detail: 'related files from history',
+        });
+    }
+    if (g.confidenceGatesEvaluated > 0) {
+        const detail = g.gatesTriggered > 0 ? `${g.gatesTriggered} blocked handoff` : 'all passed';
+        graphRows.push({ label: 'Confidence gates', value: `${fmtNum(g.confidenceGatesEvaluated)} eval`, detail });
+    }
+    if (g.patternRunsRecorded > 0 && g.historicalSuccessRate != null) {
+        graphRows.push({
+            label: 'Pattern history',
+            value: `${g.historicalSuccessRate}% success`,
+            detail: `${fmtNum(g.patternRunsRecorded)} runs`,
+        });
+    }
+    if (g.reviewFindingsRecorded > 0) {
+        graphRows.push({
+            label: 'Review findings',
+            value: `${fmtNum(g.reviewFindingsRecorded)}`,
+            detail: 'recorded to graph',
+        });
+    }
+    if (graphRows.length > 0) {
+        sections.push({ title: 'KNOWLEDGE GRAPH', rows: graphRows });
+    }
+    // ─── ML/GNN ─────────────────────────────────────────────
+    const m = summary.ml;
+    const mlRows = [];
+    if (m.gnnPredictionsMade > 0) {
+        mlRows.push({
+            label: 'GNN risk scan',
+            value: `${fmtNum(m.highRiskNodesIdentified)} high-risk`,
+            detail: `${fmtNum(m.gnnPredictionsMade)} predictions`,
+        });
+    }
+    if (m.agentsDroppedML > 0) {
+        mlRows.push({
+            label: 'Predictive dropout',
+            value: `${fmtNum(m.agentsDroppedML)} agents`,
+            detail: `-${fmtNum(m.dropoutTokensSaved)} tok saved`,
+        });
+    }
+    if (m.agentsDroppedRules > 0) {
+        mlRows.push({
+            label: 'Rule-based dropout',
+            value: `${fmtNum(m.agentsDroppedRules)} agents`,
+            detail: 'redundant removed',
+        });
+    }
+    if (m.affinityEscalations > 0) {
+        mlRows.push({
+            label: 'Affinity escalation',
+            value: `${fmtNum(m.affinityEscalations)}`,
+            detail: 'model upgraded for hard files',
+        });
+    }
+    if (m.trajectoryPredictionsMade > 0) {
+        mlRows.push({
+            label: 'Trajectory forecast',
+            value: `${fmtNum(m.trajectoryPredictionsMade)}`,
+            detail: 'success probabilities',
+        });
+    }
+    if (mlRows.length > 0) {
+        sections.push({ title: 'ML / GNN', rows: mlRows });
+    }
+    // ─── Adaptive ───────────────────────────────────────────
+    const a = summary.adaptive;
+    const adaptiveRows = [];
+    if (a.phasesSkipped > 0) {
+        adaptiveRows.push({ label: 'Phases skipped', value: `${fmtNum(a.phasesSkipped)}`, detail: 'replanner: redundant' });
+    }
+    if (a.modelDowngrades > 0) {
+        adaptiveRows.push({
+            label: 'Model downgrades',
+            value: `${fmtNum(a.modelDowngrades)}`,
+            detail: 'cheaper where safe',
+        });
+    }
+    if (a.modelUpgrades > 0) {
+        adaptiveRows.push({
+            label: 'Model upgrades',
+            value: `${fmtNum(a.modelUpgrades)}`,
+            detail: 'stronger where needed',
+        });
+    }
+    if (a.cascadeTierChanges > 0) {
+        adaptiveRows.push({
+            label: 'Cascade changes',
+            value: `${fmtNum(a.cascadeTierChanges)}`,
+            detail: 'start cheap, escalate',
+        });
+    }
+    if (a.livingSpecUpdates > 0) {
+        adaptiveRows.push({
+            label: 'Living spec',
+            value: `${fmtNum(a.livingSpecUpdates)} updates`,
+            detail: 'refined during run',
+        });
+    }
+    if (adaptiveRows.length > 0) {
+        sections.push({ title: 'ADAPTIVE', rows: adaptiveRows });
+    }
+    // ─── Pre-compute cost bar to include in width calc ──────
+    const costParts = [`$${summary.actualCostUsd.toFixed(2)}`];
+    if (summary.historicalAvgCostUsd != null && summary.costDeltaUsd != null) {
+        const dir = summary.costDeltaUsd <= 0 ? 'saved' : 'over';
+        costParts.push(`${dir} $${Math.abs(summary.costDeltaUsd).toFixed(2)} vs avg`);
+    }
+    if (summary.tokens.savingsPercent > 0) {
+        costParts.push(`${summary.tokens.savingsPercent}% tokens saved`);
+    }
+    costParts.push(`${fmtNum(summary.agentsExecuted)} agents`);
+    costParts.push(`${fmtNum(summary.phasesExecuted)} phases`);
+    costParts.push(`${(summary.durationMs / 1000).toFixed(1)}s`);
+    let costText = costParts.join('  |  ');
+    // ─── Compute column widths ──────────────────────────────
+    const allRows = sections.flatMap((s) => s.rows);
+    const treePrefix = 5; // "  ├─ " or "  └─ "
+    const labelW = Math.max(20, ...allRows.map((r) => displayWidth(r.label)));
+    const valueW = Math.max(14, ...allRows.map((r) => displayWidth(r.value)));
+    const detailW = Math.max(20, ...allRows.map((r) => displayWidth(r.detail)));
+    // Row content: "  " + tree + label + "  " + value + "  " + detail + "  "
+    const rowInnerW = 2 + treePrefix + labelW + 2 + valueW + 2 + detailW + 2;
+    // Cost bar wraps if needed — don't let it blow out the table width
+    const costInnerW = Math.min(2 + displayWidth(costText) + 2, rowInnerW + 10);
+    const innerW = Math.max(rowInnerW, costInnerW, 64);
+    // ─── Build table ────────────────────────────────────────
+    const H = '\u2500'; // ─
+    const V = '\u2502'; // │
+    const TL = '\u250c'; // ┌
+    const TR = '\u2510'; // ┐
+    const BL = '\u2514'; // └
+    const BR = '\u2518'; // ┘
+    const LT = '\u251c'; // ├
+    const RT = '\u2524'; // ┤
+    const bottomBorder = `${BL}${H.repeat(innerW)}${BR}`;
+    const separator = `${LT}${H.repeat(innerW)}${RT}`;
+    const emptyRow = `${V}${' '.repeat(innerW)}${V}`;
+    const lines = [];
+    // Title row
+    const title = ' Engine Benefits ';
+    const titlePad = innerW - displayWidth(title) - 1;
+    lines.push(`${TL}${H}${title}${H.repeat(Math.max(0, titlePad))}${TR}`);
+    // Cost bar at top — truncate if wider than table
+    const maxCostW = innerW - 4; // 2 padding each side
+    if (displayWidth(costText) > maxCostW) {
+        // Trim from the end (drop duration/phases if needed)
+        let trimmed = costText;
+        while (displayWidth(trimmed) > maxCostW - 3 && trimmed.length > 0) {
+            trimmed = trimmed.slice(0, -1);
+        }
+        costText = trimmed.trimEnd() + '...';
+    }
+    lines.push(`${V}  ${padTo(costText, innerW - 2)}${V}`);
+    lines.push(separator);
+    for (let si = 0; si < sections.length; si++) {
+        const section = sections[si];
+        // Section header
+        lines.push(`${V}  ${padTo(section.title, innerW - 2)}${V}`);
+        for (let ri = 0; ri < section.rows.length; ri++) {
+            const row = section.rows[ri];
+            const isLast = ri === section.rows.length - 1;
+            const tree = isLast ? '\u2514\u2500' : '\u251c\u2500'; // └─ or ├─
+            const labelPart = `${tree} ${padTo(row.label, labelW)}`;
+            const valuePart = padTo(row.value, valueW);
+            const detailPart = padTo(row.detail, detailW);
+            const content = `${labelPart}  ${valuePart}  ${detailPart}`;
+            lines.push(`${V}  ${padTo(content, innerW - 2)}${V}`);
+        }
+        // Add separator between sections (not after last)
+        if (si < sections.length - 1) {
+            lines.push(emptyRow);
+        }
+    }
+    lines.push(bottomBorder);
+    return lines.join('\n');
+}
+//# sourceMappingURL=benefits.js.map