swarm-engine 1.41.0 → 1.43.0

package/dist/runtime/benefits.d.ts

@@ -0,0 +1,170 @@
+/**
+ * BenefitsCollector — aggregates optimization metrics during orchestration
+ * and produces a user-facing summary of what the engine did for them.
+ */
+export interface TokenSavings {
+    /** Tokens saved by smart phase output routing (review/test phases get filtered context) */
+    smartRoutingSaved: number;
+    /** Tokens saved by prompt compression (markdown boilerplate removal) */
+    promptCompressionSaved: number;
+    /** Tokens saved by context compaction (stripping re-retrievable content) */
+    verbatimCompactionSaved: number;
+    /** Tokens saved by context decay (older phases summarized) */
+    contextDecaySaved: number;
+    /** Cost saved by prompt cache hits on shared prefixes */
+    cacheSavingsUsd: number;
+    /** Total tokens saved across all techniques */
+    totalTokensSaved: number;
+    /** Savings as percentage of what would have been used without optimizations */
+    savingsPercent: number;
+}
+export interface GraphBenefits {
+    /** Number of context routing decisions made by the knowledge graph */
+    contextRoutingDecisions: number;
+    /** Co-modification hints injected (related files suggested to agents) */
+    coModHintsInjected: number;
+    /** Phase confidence gates evaluated */
+    confidenceGatesEvaluated: number;
+    /** Gates that fired warnings or halts */
+    gatesTriggered: number;
+    /** Historical pattern stats available (shows learning over time) */
+    patternRunsRecorded: number;
+    /** Success rate for this pattern from historical data */
+    historicalSuccessRate: number | null;
+    /** Review findings recorded back to the graph */
+    reviewFindingsRecorded: number;
+}
+export interface MLBenefits {
+    /** GNN failure risk predictions made before execution */
+    gnnPredictionsMade: number;
+    /** High-risk nodes identified by GNN (>70% failure probability) */
+    highRiskNodesIdentified: number;
+    /** Agents dropped by predictive dropout (ML-based) */
+    agentsDroppedML: number;
+    /** Agents dropped by rule-based dropout */
+    agentsDroppedRules: number;
+    /** Estimated tokens saved by dropping redundant agents */
+    dropoutTokensSaved: number;
+    /** Model tier escalations from affinity routing (poor history → upgrade) */
+    affinityEscalations: number;
+    /** Trajectory predictions made (success probability forecasts) */
+    trajectoryPredictionsMade: number;
+}
+export interface AdaptiveBenefits {
+    /** Phases skipped by adaptive replanning */
+    phasesSkipped: number;
+    /** Model downgrades applied (cheaper model used where safe) */
+    modelDowngrades: number;
+    /** Model upgrades applied (more capable model where needed) */
+    modelUpgrades: number;
+    /** Cascade tier changes (started cheap, escalated on failure) */
+    cascadeTierChanges: number;
+    /** Budget warnings issued */
+    budgetWarnings: number;
+    /** Living spec updates (spec refined as orchestration progressed) */
+    livingSpecUpdates: number;
+}
+export interface BenefitsSummary {
+    tokens: TokenSavings;
+    graph: GraphBenefits;
+    ml: MLBenefits;
+    adaptive: AdaptiveBenefits;
+    /** Actual orchestration cost */
+    actualCostUsd: number;
+    /** Historical average cost for this pattern (null if no history) */
+    historicalAvgCostUsd: number | null;
+    /** Cost delta vs history (negative = saved money) */
+    costDeltaUsd: number | null;
+    /** Total wall-clock duration ms */
+    durationMs: number;
+    /** Total agents executed */
+    agentsExecuted: number;
+    /** Total phases executed */
+    phasesExecuted: number;
+}
+/**
+ * Collects benefits metrics during orchestration execution.
+ * Call increment methods as optimizations occur, then call `build()` at the end.
+ */
+export declare class BenefitsCollector {
+    private _smartRoutingSaved;
+    private _promptCompressionSaved;
+    private _verbatimCompactionSaved;
+    private _contextDecaySaved;
+    private _cacheSavingsUsd;
+    private _contextRoutingDecisions;
+    private _coModHintsInjected;
+    private _confidenceGatesEvaluated;
+    private _gatesTriggered;
+    private _reviewFindingsRecorded;
+    private _gnnPredictionsMade;
+    private _highRiskNodesIdentified;
+    private _agentsDroppedML;
+    private _agentsDroppedRules;
+    private _dropoutTokensSaved;
+    private _affinityEscalations;
+    private _trajectoryPredictionsMade;
+    private _phasesSkipped;
+    private _modelDowngrades;
+    private _modelUpgrades;
+    private _cascadeTierChanges;
+    private _budgetWarnings;
+    private _livingSpecUpdates;
+    addSmartRoutingSaved(tokens: number): void;
+    addPromptCompressionSaved(tokens: number): void;
+    addVerbatimCompactionSaved(tokens: number): void;
+    addContextDecaySaved(tokens: number): void;
+    addCacheSavingsUsd(usd: number): void;
+    addContextRoutingDecision(): void;
+    addCoModHintInjected(): void;
+    addConfidenceGateEvaluated(triggered: boolean): void;
+    addReviewFindingRecorded(): void;
+    addGnnPrediction(highRiskCount: number): void;
+    addAgentDroppedML(estimatedTokensSaved: number): void;
+    addAgentDroppedRules(): void;
+    addAffinityEscalation(): void;
+    addTrajectoryPrediction(): void;
+    addPhaseSkipped(): void;
+    addModelDowngrade(): void;
+    addModelUpgrade(): void;
+    addCascadeTierChange(): void;
+    addBudgetWarning(): void;
+    addLivingSpecUpdate(): void;
+    /**
+     * 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.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: {
+        actualTotalTokens: number;
+        actualCostUsd: number;
+        durationMs: number;
+        agentsExecuted: number;
+        phasesExecuted: number;
+        historicalAvgCostUsd?: number | null;
+        patternRunsRecorded?: number;
+        historicalSuccessRate?: number | null;
+    }): BenefitsSummary;
+    /** Reset all counters */
+    reset(): void;
+}
+/**
+ * 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 declare function formatBenefitsSummary(summary: BenefitsSummary): string;
+/**
+ * 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 declare function formatBenefitsTable(summary: BenefitsSummary): string;
+//# sourceMappingURL=benefits.d.ts.map

package/dist/runtime/benefits.d.ts.map

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