swarm-engine 1.3.0 → 1.38.0

package/dist/runtime/graph-analyzer.js

@@ -0,0 +1,321 @@
+// ─── Analyzer ─────────────────────────────────────────────────────
+/**
+ * Pre-execution analysis (centrality, failure prediction) and post-execution
+ * insights (topology-driven suggestions) over the execution knowledge graph.
+ *
+ * All analysis is purely structural — no LLM calls, just graph topology.
+ */
+export class GraphAnalyzer {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    /**
+     * Find "god nodes" — nodes with highest degree, excluding orchestration
+     * hubs (which are structurally central by definition, not interesting).
+     */
+    findGodNodes(options) {
+        const limit = options?.limit ?? 10;
+        const typeFilter = options?.type;
+        let candidates;
+        if (typeFilter) {
+            candidates = this.graph.getNodesByType(typeFilter);
+        }
+        else {
+            // Default: phase + agent + file nodes (the interesting ones)
+            candidates = [
+                ...this.graph.getNodesByType('phase'),
+                ...this.graph.getNodesByType('agent'),
+                ...this.graph.getNodesByType('file'),
+            ];
+        }
+        // Orchestration nodes are hubs by definition — exclude unless explicitly requested
+        if (!typeFilter) {
+            candidates = candidates.filter((n) => n.type !== 'orchestration');
+        }
+        const godNodes = candidates.map((node) => {
+            const outEdges = this.graph.getEdges(node.id, 'outgoing');
+            const inEdges = this.graph.getEdges(node.id, 'incoming');
+            const fanOut = new Set(outEdges.map((e) => e.target)).size;
+            return {
+                node,
+                degree: outEdges.length + inEdges.length,
+                inDegree: inEdges.length,
+                outDegree: outEdges.length,
+                fanOut,
+            };
+        });
+        return godNodes.sort((a, b) => b.degree - a.degree).slice(0, limit);
+    }
+    /**
+     * Sampling-based betweenness centrality approximation.
+     *
+     * Samples random node pairs, finds shortest paths between them, and counts
+     * how often each intermediate node appears on those paths. Nodes that
+     * frequently appear as bridges score highest.
+     *
+     * O(samples × avgPathLength) vs O(V×E) for exact Brandes algorithm.
+     * Normalizes by valid paths found (not total samples) for meaningful scores.
+     */
+    computeCentrality(sampleSize) {
+        const samples = sampleSize ?? 50;
+        const centrality = new Map();
+        const nodes = [
+            ...this.graph.getNodesByType('phase'),
+            ...this.graph.getNodesByType('agent'),
+            ...this.graph.getNodesByType('file'),
+        ];
+        if (nodes.length < 3)
+            return centrality;
+        let validPaths = 0;
+        for (let i = 0; i < samples; i++) {
+            const source = nodes[Math.floor(Math.random() * nodes.length)];
+            const target = nodes[Math.floor(Math.random() * nodes.length)];
+            if (source.id === target.id)
+                continue;
+            const path = this.graph.shortestPath(source.id, target.id, 8);
+            if (!path || path.nodes.length <= 2)
+                continue; // need intermediates
+            validPaths++;
+            // Only count intermediate nodes (skip endpoints)
+            for (let j = 1; j < path.nodes.length - 1; j++) {
+                const nodeId = path.nodes[j].id;
+                centrality.set(nodeId, (centrality.get(nodeId) ?? 0) + 1);
+            }
+        }
+        // Normalize by valid path count for meaningful 0–1 scores
+        if (validPaths > 0) {
+            for (const [id, count] of centrality) {
+                centrality.set(id, count / validPaths);
+            }
+        }
+        return centrality;
+    }
+    /**
+     * Predict which agents are most likely to fail based on graph signals:
+     *
+     * - Historical fail rate for the agent type (min 3 samples)
+     * - Files with prior error associations (caused_by edges)
+     * - Ambiguous inbound dependencies
+     * - High fan-in (more dependencies = more that can go wrong)
+     */
+    predictFailures(orchestrationId, files) {
+        const predictions = [];
+        // Scope agent nodes to orchestration, specific files, or all
+        let agentNodes;
+        if (files && files.length > 0) {
+            // Find agents that have previously touched any of the specified files
+            const agentIds = new Set();
+            for (const filePath of files) {
+                const fileId = filePath.startsWith('file:') ? filePath : `file:${filePath}`;
+                const touchEdges = this.graph.getEdges(fileId, 'incoming').filter((e) => e.type === 'touched_file');
+                for (const edge of touchEdges) {
+                    agentIds.add(edge.source);
+                }
+            }
+            agentNodes = [...agentIds]
+                .map((id) => this.graph.getNode(id))
+                .filter((n) => n !== null && n.type === 'agent');
+        }
+        else if (orchestrationId) {
+            const subgraph = this.graph.bfs(orchestrationId, 2);
+            agentNodes = subgraph.nodes.filter((n) => n.type === 'agent');
+        }
+        else {
+            agentNodes = this.graph.getNodesByType('agent');
+        }
+        // Build historical fail rates per agent type across the full graph
+        const typeStats = new Map();
+        for (const agent of this.graph.getNodesByType('agent')) {
+            const aType = agent.properties.agentType || agent.label;
+            const stats = typeStats.get(aType) ?? { total: 0, failed: 0 };
+            stats.total++;
+            const status = agent.properties.status;
+            if (status === 'error' || status === 'timeout') {
+                stats.failed++;
+            }
+            typeStats.set(aType, stats);
+        }
+        for (const agent of agentNodes) {
+            const aType = agent.properties.agentType || agent.label;
+            const stats = typeStats.get(aType);
+            // Require minimum 3 samples for historical rate to be meaningful
+            const historicalFailRate = stats && stats.total >= 3 ? stats.failed / stats.total : 0;
+            const reasons = [];
+            let riskScore = historicalFailRate;
+            // Check files this agent touches for prior error associations
+            const files = this.graph.getNeighbors(agent.id, 'touched_file');
+            for (const file of files) {
+                const errorEdges = this.graph.getEdges(file.id, 'incoming').filter((e) => e.type === 'caused_by');
+                if (errorEdges.length > 0) {
+                    riskScore += 0.2;
+                    reasons.push(`File "${file.label}" has ${errorEdges.length} historical error(s)`);
+                }
+            }
+            // Ambiguous dependencies increase uncertainty
+            const ambiguousInEdges = this.graph.getEdges(agent.id, 'incoming').filter((e) => e.confidence === 'AMBIGUOUS');
+            if (ambiguousInEdges.length > 0) {
+                riskScore += 0.1 * ambiguousInEdges.length;
+                reasons.push(`${ambiguousInEdges.length} ambiguous dependency edge(s)`);
+            }
+            // High fan-in = more can go wrong
+            const allInEdges = this.graph.getEdges(agent.id, 'incoming');
+            if (allInEdges.length > 5) {
+                riskScore += 0.1;
+                reasons.push(`High fan-in: ${allInEdges.length} incoming edges`);
+            }
+            if (historicalFailRate > 0) {
+                reasons.push(`Historical fail rate: ${(historicalFailRate * 100).toFixed(0)}% ` + `(${stats.failed}/${stats.total})`);
+            }
+            if (riskScore > 0 || reasons.length > 0) {
+                predictions.push({
+                    nodeId: agent.id,
+                    label: agent.label,
+                    riskScore: Math.min(riskScore, 1),
+                    reasons,
+                    historicalFailRate,
+                });
+            }
+        }
+        return predictions.sort((a, b) => b.riskScore - a.riskScore);
+    }
+    /**
+     * Post-execution topology-driven suggestions.
+     *
+     * Detects structural issues without any LLM:
+     * 1. Isolated outputs — agents whose work was never consumed
+     * 2. High-centrality bottlenecks — single points of failure
+     * 3. Ambiguous dependencies — edges that need verification
+     */
+    suggestImprovements(orchestrationId) {
+        const suggestions = [];
+        let scopeNodes;
+        let scopeEdges;
+        if (orchestrationId) {
+            const subgraph = this.graph.bfs(orchestrationId, 3);
+            scopeNodes = subgraph.nodes;
+            // Deduplicate edges — BFS collects all edges of each visited node,
+            // so edge A→B appears when visiting both A and B
+            const seen = new Set();
+            scopeEdges = subgraph.edges.filter((e) => {
+                const key = `${e.source}:${e.target}:${e.type}`;
+                if (seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            });
+        }
+        else {
+            scopeNodes = [...this.graph.getNodesByType('agent'), ...this.graph.getNodesByType('phase')];
+            // Collect relevant edges across all types (not just 'contains')
+            const edgeTypes = [
+                'contains',
+                'spawned',
+                'produced',
+                'consumed',
+                'touched_file',
+                'caused_by',
+                'learned_from',
+            ];
+            const nodeIds = new Set(scopeNodes.map((n) => n.id));
+            const seen = new Set();
+            scopeEdges = [];
+            for (const edgeType of edgeTypes) {
+                for (const edge of this.graph.getEdgesByType(edgeType)) {
+                    if (nodeIds.has(edge.source) || nodeIds.has(edge.target)) {
+                        const key = `${edge.source}:${edge.target}:${edge.type}`;
+                        if (!seen.has(key)) {
+                            seen.add(key);
+                            scopeEdges.push(edge);
+                        }
+                    }
+                }
+            }
+        }
+        // 1. Isolated outputs: agents that completed but whose output was never consumed
+        const agents = scopeNodes.filter((n) => n.type === 'agent');
+        for (const agent of agents) {
+            if (agent.properties.status !== 'idle')
+                continue;
+            const producedEdges = this.graph.getEdges(agent.id, 'outgoing').filter((e) => e.type === 'produced');
+            const consumedEdges = this.graph.getEdges(agent.id, 'outgoing').filter((e) => e.type === 'consumed');
+            if (producedEdges.length === 0 && consumedEdges.length === 0) {
+                suggestions.push({
+                    type: 'isolated_output',
+                    message: `Agent "${agent.label}" completed but its output was never consumed by downstream agents`,
+                    nodeIds: [agent.id],
+                    severity: 'warning',
+                });
+            }
+        }
+        // 2. High-centrality bottlenecks
+        const centrality = this.computeCentrality(30);
+        const centralityThreshold = 0.3;
+        for (const [nodeId, score] of centrality) {
+            if (score >= centralityThreshold) {
+                const node = this.graph.getNode(nodeId);
+                if (node) {
+                    suggestions.push({
+                        type: 'high_centrality',
+                        message: `"${node.label}" is a structural bottleneck (centrality: ${score.toFixed(2)})` +
+                            ` — failure here affects many downstream nodes`,
+                        nodeIds: [nodeId],
+                        severity: score >= 0.5 ? 'critical' : 'warning',
+                    });
+                }
+            }
+        }
+        // 3. Ambiguous dependencies that need human verification
+        const ambiguousEdges = scopeEdges.filter((e) => e.confidence === 'AMBIGUOUS');
+        if (ambiguousEdges.length > 0) {
+            suggestions.push({
+                type: 'ambiguous_dependency',
+                message: `${ambiguousEdges.length} edge(s) have AMBIGUOUS confidence — verify these dependencies are real`,
+                nodeIds: [...new Set(ambiguousEdges.map((e) => e.source))],
+                severity: ambiguousEdges.length >= 3 ? 'warning' : 'info',
+            });
+        }
+        return suggestions;
+    }
+    /**
+     * Evaluate whether a phase should proceed, warn, or halt based on
+     * reflection confidence and historical pattern success rates.
+     */
+    evaluatePhaseConfidence(phase, reflection, patternStats, config) {
+        const minHistoricalSuccessRate = config?.minHistoricalSuccessRate ?? 0.3;
+        const mediumSuccessThreshold = config?.minHistoricalSuccessRate ? config.minHistoricalSuccessRate + 0.2 : 0.5;
+        const haltOnLow = config?.haltOnLowConfidence ?? true;
+        const warnOnMedium = config?.warnOnMediumConfidence ?? true;
+        if (reflection.confidence === 'low' && patternStats && patternStats.successRate < minHistoricalSuccessRate) {
+            return {
+                result: haltOnLow ? 'halt' : 'warn',
+                reason: `Low confidence reflection combined with poor historical success rate (${Math.round(patternStats.successRate * 100)}%)`,
+                confidence: reflection.confidence,
+                historicalSuccessRate: patternStats.successRate,
+            };
+        }
+        if (reflection.confidence === 'low') {
+            return {
+                result: 'warn',
+                reason: 'Low confidence reflection — consider re-running or reviewing outputs',
+                confidence: reflection.confidence,
+                historicalSuccessRate: patternStats?.successRate,
+            };
+        }
+        if (reflection.confidence === 'medium' && patternStats && patternStats.successRate < mediumSuccessThreshold) {
+            return {
+                result: warnOnMedium ? 'warn' : 'pass',
+                reason: `Medium confidence with below-average historical success rate (${Math.round(patternStats.successRate * 100)}%)`,
+                confidence: reflection.confidence,
+                historicalSuccessRate: patternStats.successRate,
+            };
+        }
+        return {
+            result: 'pass',
+            reason: 'Phase confidence is acceptable',
+            confidence: reflection.confidence,
+            historicalSuccessRate: patternStats?.successRate,
+        };
+    }
+}
+//# sourceMappingURL=graph-analyzer.js.map

package/dist/runtime/graph-analyzer.js.map

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

package/dist/runtime/graph-causal.d.ts

@@ -0,0 +1,91 @@
+import type { ExecutionGraph } from './execution-graph.js';
+export type CausalVar = 'model' | 'agentType' | 'fileSetSize' | 'contextQuality' | 'outcome';
+export interface Observation {
+    orchestrationId: string;
+    model: string;
+    agentType: string;
+    fileSetSize: 'small' | 'medium' | 'large';
+    contextQuality: 'low' | 'medium' | 'high';
+    outcome: 'success' | 'failure';
+}
+export interface CausalEstimate {
+    effect: number;
+    confidence: 'low' | 'medium' | 'high';
+    sampleCount: number;
+    adjustedFor: CausalVar[];
+    method: 'raw' | 'stratified' | 'backdoor';
+}
+export interface InterventionSuggestion {
+    intervention: {
+        variable: CausalVar;
+        from: string;
+        to: string;
+    };
+    estimatedEffect: number;
+    confidence: 'low' | 'medium' | 'high';
+    reasoning: string;
+}
+/**
+ * Causal inference engine that builds structural causal models from execution
+ * traces and estimates causal effects using backdoor adjustment.
+ *
+ * Extracts observations from the execution knowledge graph, computes normalized
+ * mutual information between variables, identifies confounders, and estimates
+ * average treatment effects using a tiered approach (raw → stratified → backdoor).
+ */
+export declare class CausalGraphEngine {
+    private graph;
+    constructor(graph: ExecutionGraph);
+    /**
+     * Extract observations from the execution graph.
+     *
+     * Walks orchestration → phase → agent subgraphs via BFS (depth 3),
+     * mapping each agent to an observation with model, agentType, fileSetSize,
+     * contextQuality, and outcome.
+     */
+    extractObservations(orchestrationId?: string): Observation[];
+    /**
+     * Compute Normalized Mutual Information between two categorical variables.
+     *
+     * NMI = I(X;Y) / sqrt(H(X) * H(Y))
+     * where H(X) = -Σ p(x) log2(p(x))
+     * and I(X;Y) = Σ p(x,y) log2(p(x,y) / (p(x)*p(y)))
+     *
+     * Returns 0 when either variable has zero entropy (constant).
+     * Returns 1.0 when a variable is compared with itself.
+     */
+    computeNMI(observations: Observation[], var1: CausalVar, var2: CausalVar): number;
+    /**
+     * Identify confounders for a treatment → outcome relationship.
+     *
+     * A variable C is a confounder if:
+     *   NMI(C, treatment) > 0.05 AND NMI(C, outcome) > 0.05
+     */
+    identifyConfounders(observations: Observation[], treatment: CausalVar): CausalVar[];
+    /**
+     * Estimate Average Treatment Effect using a tiered approach:
+     *
+     * - Tier 1 (N < 3): insufficient data → effect=0, low confidence
+     * - Tier 2 (3–9): raw comparison of success rates
+     * - Tier 3 (10–49): stratify by top 1 confounder, weighted average
+     * - Tier 4 (50+): full backdoor adjustment with all confounders
+     *
+     * Effect is always clamped to [-1, 1].
+     */
+    estimateCausalEffect(treatment: CausalVar, treatmentValue: string, controlValue: string, orchestrationId?: string): CausalEstimate;
+    /**
+     * Suggest interventions for a failed orchestration by estimating the causal
+     * effect of switching each variable to an alternative value observed in
+     * historical data.
+     *
+     * Returns suggestions ranked by estimated effect (descending), filtered
+     * to only positive effects.
+     */
+    suggestIntervention(failedOrchestrationId: string): InterventionSuggestion[];
+    /**
+     * Compute stratified ATE: partition observations by confounder strata,
+     * compute per-stratum ATE, then take a weighted average (weight = stratum size).
+     */
+    private stratifiedATE;
+}
+//# sourceMappingURL=graph-causal.d.ts.map

package/dist/runtime/graph-causal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-causal.d.ts","sourceRoot":"","sources":["../../src/runtime/graph-causal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,WAAW,GAAG,aAAa,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC1C,cAAc,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC1C,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,MAAM,EAAE,KAAK,GAAG,YAAY,GAAG,UAAU,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE;QAAE,QAAQ,EAAE,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,cAAc;IAEzC;;;;;;OAMG;IACH,mBAAmB,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE;IAkD5D;;;;;;;;;OASG;IACH,UAAU,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM;IA6CjF;;;;;OAKG;IACH,mBAAmB,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE;IAiBnF;;;;;;;;;OASG;IACH,oBAAoB,CAClB,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc;IA2DjB;;;;;;;OAOG;IACH,mBAAmB,CAAC,qBAAqB,EAAE,MAAM,GAAG,sBAAsB,EAAE;IA4D5E;;;OAGG;IACH,OAAO,CAAC,aAAa;CAiCtB"}