0xray 2.0.0

package/dist/delegation/metrics-aggregator.js

@@ -0,0 +1,335 @@
+/**
+ * Metrics Aggregator
+ *
+ * Provides aggregation, reporting, and export functionality for delegation
+ * and orchestration metrics stored in stateManager.
+ *
+ * @version 1.0.0
+ * @since 2026-04-16
+ */
+const MAX_METRICS_ENTRIES = 100;
+export function getDelegationMetrics(stateManager) {
+    return stateManager.get("delegation_metrics") || [];
+}
+export function getOrchestrationMetrics(stateManager) {
+    return stateManager.get("orchestration_metrics") || [];
+}
+export function aggregateDelegationMetrics(stateManager) {
+    const metrics = getDelegationMetrics(stateManager);
+    return aggregateMetricsData(metrics, "delegation");
+}
+export function aggregateOrchestrationMetrics(stateManager) {
+    const metrics = getOrchestrationMetrics(stateManager);
+    return aggregateMetricsData(metrics, "orchestration");
+}
+function aggregateMetricsData(metrics, type) {
+    if (metrics.length === 0) {
+        return {
+            summary: {
+                totalEntries: 0,
+                timeRange: { start: Date.now(), end: Date.now() },
+                oldestEntry: 0,
+                newestEntry: 0,
+            },
+            byAgent: {},
+            byComplexityLevel: {},
+            byTimePeriod: {},
+        };
+    }
+    const timestamps = metrics.map((m) => m.timestamp);
+    const result = {
+        summary: {
+            totalEntries: metrics.length,
+            timeRange: { start: Math.min(...timestamps), end: Math.max(...timestamps) },
+            oldestEntry: Math.min(...timestamps),
+            newestEntry: Math.max(...timestamps),
+        },
+        byAgent: {},
+        byComplexityLevel: {},
+        byTimePeriod: {},
+    };
+    const byAgent = result.byAgent;
+    const byComplexityLevel = result.byComplexityLevel;
+    const byTimePeriod = result.byTimePeriod;
+    for (const metric of metrics) {
+        const agents = type === "delegation"
+            ? metric.agents
+            : metric.subAgents.map((s) => s.name);
+        for (const agent of agents) {
+            if (!byAgent[agent]) {
+                byAgent[agent] = {
+                    count: 0,
+                    operations: [],
+                    avgComplexity: 0,
+                    successRate: 0,
+                };
+            }
+            byAgent[agent].count++;
+            byAgent[agent].operations.push(metric.operation);
+            if (type === "delegation") {
+                const delMetric = metric;
+                const complexityScore = delMetric.complexity
+                    ?.score;
+                const success = delMetric.success;
+                byAgent[agent].avgComplexity += complexityScore || 0;
+                if (success) {
+                    byAgent[agent].successRate++;
+                }
+            }
+        }
+        const complexityLevel = type === "delegation"
+            ? metric.complexity
+                ?.level
+            : metric.complexityLevel;
+        const timePeriod = getTimePeriod(metric.timestamp);
+        if (complexityLevel) {
+            if (!byComplexityLevel[complexityLevel]) {
+                byComplexityLevel[complexityLevel] = {
+                    count: 0,
+                    avgDuration: 0,
+                    operations: [],
+                };
+            }
+            byComplexityLevel[complexityLevel].count++;
+            byComplexityLevel[complexityLevel].operations.push(metric.operation);
+            if (type === "delegation") {
+                const delMetric = metric;
+                byComplexityLevel[complexityLevel].avgDuration +=
+                    delMetric.totalTime || 0;
+            }
+        }
+        if (!byTimePeriod[timePeriod]) {
+            byTimePeriod[timePeriod] = {
+                count: 0,
+                operations: [],
+            };
+        }
+        byTimePeriod[timePeriod].count++;
+        byTimePeriod[timePeriod].operations.push(metric.operation);
+    }
+    for (const agent of Object.keys(byAgent)) {
+        const data = byAgent[agent];
+        if (data) {
+            data.operations = [...new Set(data.operations)];
+            data.avgComplexity = data.count > 0 ? data.avgComplexity / data.count : 0;
+            data.successRate = data.count > 0 ? (data.successRate / data.count) * 100 : 0;
+        }
+    }
+    for (const level of Object.keys(byComplexityLevel)) {
+        const data = byComplexityLevel[level];
+        if (data) {
+            data.operations = [...new Set(data.operations)];
+            data.avgDuration = data.count > 0 ? data.avgDuration / data.count : 0;
+        }
+    }
+    return result;
+}
+function getTimePeriod(timestamp) {
+    const date = new Date(timestamp);
+    const hour = date.getHours();
+    if (hour >= 0 && hour < 6)
+        return "night";
+    if (hour >= 6 && hour < 12)
+        return "morning";
+    if (hour >= 12 && hour < 18)
+        return "afternoon";
+    return "evening";
+}
+export function summarizeByAgent(stateManager, type = "delegation") {
+    const metrics = type === "delegation"
+        ? getDelegationMetrics(stateManager)
+        : getOrchestrationMetrics(stateManager);
+    const byAgent = {};
+    for (const metric of metrics) {
+        const agents = type === "delegation"
+            ? metric.agents
+            : metric.subAgents.map((s) => s.name);
+        for (const agent of agents) {
+            if (!byAgent[agent]) {
+                byAgent[agent] = {
+                    count: 0,
+                    operations: new Set(),
+                    avgComplexity: 0,
+                    successCount: 0,
+                };
+            }
+            byAgent[agent].count++;
+            byAgent[agent].operations.add(metric.operation);
+            if (type === "delegation") {
+                const delMetric = metric;
+                const complexityScore = delMetric.complexity
+                    ?.score;
+                byAgent[agent].avgComplexity += complexityScore || 0;
+                if (delMetric.success) {
+                    byAgent[agent].successCount++;
+                }
+            }
+        }
+    }
+    const result = {};
+    for (const [agent, data] of Object.entries(byAgent)) {
+        result[agent] = {
+            invocationCount: data.count,
+            operations: [...data.operations],
+            avgComplexity: data.count > 0 ? data.avgComplexity / data.count : 0,
+            successRate: data.count > 0 ? (data.successCount / data.count) * 100 : 0,
+        };
+    }
+    return result;
+}
+export function summarizeByComplexityLevel(stateManager, type = "delegation") {
+    const metrics = type === "delegation"
+        ? getDelegationMetrics(stateManager)
+        : getOrchestrationMetrics(stateManager);
+    const byLevel = {};
+    for (const metric of metrics) {
+        const complexityLevel = type === "delegation"
+            ? metric.complexity
+                ?.level
+            : metric.complexityLevel;
+        if (!complexityLevel)
+            continue;
+        if (!byLevel[complexityLevel]) {
+            byLevel[complexityLevel] = {
+                count: 0,
+                totalDuration: 0,
+                operations: new Set(),
+            };
+        }
+        byLevel[complexityLevel].count++;
+        byLevel[complexityLevel].operations.add(metric.operation);
+        if (type === "delegation") {
+            byLevel[complexityLevel].totalDuration +=
+                metric.totalTime || 0;
+        }
+    }
+    const result = {};
+    for (const [level, data] of Object.entries(byLevel)) {
+        result[level] = {
+            count: data.count,
+            avgDuration: data.count > 0 ? data.totalDuration / data.count : 0,
+            operations: [...data.operations],
+        };
+    }
+    return result;
+}
+export function summarizeByTimePeriod(stateManager, type = "delegation") {
+    const metrics = type === "delegation"
+        ? getDelegationMetrics(stateManager)
+        : getOrchestrationMetrics(stateManager);
+    const periods = {};
+    for (const metric of metrics) {
+        const period = getTimePeriod(metric.timestamp);
+        if (!periods[period]) {
+            periods[period] = {
+                count: 0,
+                operations: new Set(),
+            };
+        }
+        periods[period].count++;
+        periods[period].operations.add(metric.operation);
+    }
+    const result = {};
+    for (const [period, data] of Object.entries(periods)) {
+        result[period] = {
+            count: data.count,
+            operations: [...data.operations],
+        };
+    }
+    return result;
+}
+export function rotateMetrics(stateManager, maxEntries = MAX_METRICS_ENTRIES) {
+    const delegationMetrics = getDelegationMetrics(stateManager);
+    const orchestrationMetrics = getOrchestrationMetrics(stateManager);
+    const delegationRemoved = Math.max(0, delegationMetrics.length - maxEntries);
+    const orchestrationRemoved = Math.max(0, orchestrationMetrics.length - maxEntries);
+    const rotatedDelegation = delegationMetrics.slice(-maxEntries);
+    const rotatedOrchestration = orchestrationMetrics.slice(-maxEntries);
+    stateManager.set("delegation_metrics", rotatedDelegation);
+    stateManager.set("orchestration_metrics", rotatedOrchestration);
+    return {
+        delegation: delegationRemoved,
+        orchestration: orchestrationRemoved,
+    };
+}
+export function cleanupOldMetrics(stateManager, olderThan) {
+    const currentDelegation = getDelegationMetrics(stateManager);
+    const currentOrchestration = getOrchestrationMetrics(stateManager);
+    const cutoff = Date.now() - olderThan;
+    const filteredDelegation = currentDelegation.filter((m) => m.timestamp >= cutoff);
+    const filteredOrchestration = currentOrchestration.filter((m) => m.timestamp >= cutoff);
+    const removedDelegation = currentDelegation.length - filteredDelegation.length;
+    const removedOrchestration = currentOrchestration.length - filteredOrchestration.length;
+    stateManager.set("delegation_metrics", filteredDelegation);
+    stateManager.set("orchestration_metrics", filteredOrchestration);
+    return {
+        delegation: removedDelegation,
+        orchestration: removedOrchestration,
+    };
+}
+export function exportMetrics(stateManager, format = "json") {
+    const delegation = getDelegationMetrics(stateManager);
+    const orchestration = getOrchestrationMetrics(stateManager);
+    const exportedAt = Date.now();
+    switch (format) {
+        case "json": {
+            return {
+                format: "json",
+                data: {
+                    delegation,
+                    orchestration,
+                    exportedAt,
+                },
+                exportedAt,
+                entryCount: delegation.length + orchestration.length,
+            };
+        }
+        case "csv": {
+            const rows = [
+                ["type", "timestamp", "operation", "agents", "complexity", "success"].join(","),
+            ];
+            for (const d of delegation) {
+                const complexity = d.complexity?.level;
+                const agents = d.agents.join(";");
+                rows.push([
+                    "delegation",
+                    d.timestamp,
+                    d.operation,
+                    agents,
+                    complexity,
+                    d.success,
+                ].join(","));
+            }
+            for (const o of orchestration) {
+                const agents = o.subAgents.map((s) => s.name).join(";");
+                rows.push([
+                    "orchestration",
+                    o.timestamp,
+                    o.operation,
+                    agents,
+                    o.complexityLevel,
+                    "N/A",
+                ].join(","));
+            }
+            return {
+                format: "csv",
+                data: rows.join("\n"),
+                exportedAt,
+                entryCount: delegation.length + orchestration.length,
+            };
+        }
+        case "summary": {
+            return {
+                format: "summary",
+                data: {
+                    delegation: aggregateMetricsData(delegation, "delegation"),
+                    orchestration: aggregateMetricsData(orchestration, "orchestration"),
+                },
+                exportedAt,
+                entryCount: delegation.length + orchestration.length,
+            };
+        }
+        default:
+            return exportMetrics(stateManager, "json");
+    }
+}

package/dist/delegation/session-coordinator.js

@@ -0,0 +1,352 @@
+/**
+ * Session Coordinator
+ *
+ * Manages cross-agent communication and coordination within sessions.
+ * Tracks delegation state, agent interactions, and conflict resolution.
+ *
+ * @version 1.0.0
+ * @since 2026-01-07
+ */
+import { frameworkLogger } from "../core/framework-logger.js";
+import * as crypto from "crypto";
+export class SessionCoordinator {
+    stateManager;
+    sessions = new Map();
+    constructor(stateManager) {
+        this.stateManager = stateManager;
+    }
+    /**
+     * Get read-only view of all sessions - avoids breaking encapsulation
+     */
+    getSessions() {
+        return new Map(this.sessions);
+    }
+    /**
+     * Get a specific session by ID
+     */
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /**
+     * Initialize session coordination for a new session
+     */
+    initializeSession(sessionId) {
+        if (!sessionId ||
+            typeof sessionId !== "string" ||
+            sessionId.trim() === "") {
+            throw new Error("Invalid session ID: must be a non-empty string");
+        }
+        const context = {
+            sessionId,
+            startTime: Date.now(),
+            activeDelegations: new Map(),
+            agentInteractions: new Map(),
+            conflictHistory: [],
+            coordinationState: {
+                activeAgents: new Set(),
+                pendingCommunications: [],
+                sharedContext: new Map(),
+                sessionMetrics: {
+                    totalInteractions: 0,
+                    successfulInteractions: 0,
+                    failedInteractions: 0,
+                    averageResponseTime: 0,
+                    conflictResolutionRate: 0,
+                    coordinationEfficiency: 0,
+                },
+            },
+            isActive: true,
+        };
+        // Initialize with default agents
+        const defaultAgents = [
+            "architect",
+            "bug-triage-specialist",
+            "code-reviewer",
+            "security-auditor",
+            "refactorer",
+            "testing-lead",
+        ];
+        defaultAgents.forEach((agentName) => {
+            context.coordinationState.activeAgents.add(agentName);
+        });
+        this.sessions.set(sessionId, context);
+        this.stateManager.set(`session:${sessionId}:coordinator`, context);
+        return {
+            sessionId,
+            createdAt: new Date(context.startTime),
+            active: context.isActive,
+            agentCount: context.coordinationState.activeAgents.size,
+        };
+    }
+    /**
+     * Register delegation execution in session
+     */
+    registerDelegation(sessionId, delegationId, delegation) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+        session.activeDelegations.set(delegationId, delegation);
+        if (delegation.agents && Array.isArray(delegation.agents)) {
+            delegation.agents.forEach((agentName) => {
+                session.coordinationState.activeAgents.add(agentName);
+            });
+        }
+        this.stateManager.set(`session:${sessionId}:delegations:${delegationId}`, delegation);
+    }
+    /**
+     * Record agent interaction within session
+     */
+    recordInteraction(sessionId, agentName, interaction) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        const fullInteraction = {
+            ...interaction,
+            timestamp: Date.now(),
+        };
+        if (!session.agentInteractions.has(agentName)) {
+            session.agentInteractions.set(agentName, []);
+        }
+        session.agentInteractions.get(agentName).push(fullInteraction);
+        this.updateSessionMetrics(session, fullInteraction);
+        this.stateManager.set(`session:${sessionId}:interactions:${agentName}`, session.agentInteractions.get(agentName));
+    }
+    /**
+     * Send message between agents within session
+     */
+    async sendMessage(sessionId, fromAgent, toAgent, message, priority = "medium") {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+        const communication = {
+            id: `comm_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`,
+            fromAgent,
+            toAgent,
+            message,
+            timestamp: Date.now(),
+            priority,
+        };
+        session.coordinationState.pendingCommunications.push(communication);
+        this.recordInteraction(sessionId, fromAgent, {
+            agentName: fromAgent,
+            action: "send_message",
+            result: { to: toAgent, message },
+            duration: 0,
+            success: true,
+        });
+    }
+    /**
+     * Receive pending messages for an agent
+     */
+    receiveMessages(sessionId, agentName) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return [];
+        }
+        const messages = session.coordinationState.pendingCommunications.filter((comm) => comm.toAgent === agentName);
+        session.coordinationState.pendingCommunications =
+            session.coordinationState.pendingCommunications.filter((comm) => comm.toAgent !== agentName);
+        if (messages.length > 0) {
+            this.recordInteraction(sessionId, agentName, {
+                agentName,
+                action: "receive_messages",
+                result: { count: messages.length },
+                duration: 0,
+                success: true,
+            });
+        }
+        return messages;
+    }
+    /**
+     * Share context data between agents
+     */
+    shareContext(sessionId, key, value, fromAgent) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+        const existing = session.coordinationState.sharedContext.get(key);
+        const newEntry = {
+            value,
+            fromAgent,
+            timestamp: Date.now(),
+        };
+        if (Array.isArray(existing)) {
+            existing.push(newEntry);
+        }
+        else {
+            session.coordinationState.sharedContext.set(key, [newEntry]);
+        }
+        this.stateManager.set(`session:${sessionId}:shared:${key}`, value);
+        try {
+            this.recordInteraction(sessionId, fromAgent, {
+                agentName: fromAgent,
+                action: "share_context",
+                result: { key, value },
+                duration: 0,
+                success: true,
+            });
+        }
+        catch (error) {
+            frameworkLogger.log("SessionCoordinator", "record-interaction", "warning", { error, message: "⚠️ Failed to record context sharing interaction:" });
+            // Continue operation despite recording failure
+        }
+    }
+    /**
+     * Get shared context data
+     */
+    getSharedContext(sessionId, key) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return undefined;
+        }
+        const contextData = session.coordinationState.sharedContext.get(key);
+        if (Array.isArray(contextData) && contextData.length > 0) {
+            const last = contextData[contextData.length - 1];
+            if (last) {
+                return { ...last.value, sharedBy: last.fromAgent };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Record conflict and resolution
+     */
+    recordConflict(sessionId, agents, resolution, outcome) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        const conflict = {
+            conflictId: `conflict_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`,
+            timestamp: Date.now(),
+            agents,
+            resolution,
+            outcome,
+        };
+        session.conflictHistory.push(conflict);
+        const totalConflicts = session.conflictHistory.length;
+        const successfulResolutions = session.conflictHistory.filter((c) => c.outcome !== undefined).length;
+        session.coordinationState.sessionMetrics.conflictResolutionRate =
+            successfulResolutions / totalConflicts;
+        this.stateManager.set(`session:${sessionId}:conflicts`, session.conflictHistory);
+    }
+    /**
+     * Complete delegation and cleanup
+     */
+    completeDelegation(sessionId, delegationId, result) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        const delegation = session.activeDelegations.get(delegationId);
+        if (delegation) {
+            session.activeDelegations.delete(delegationId);
+            this.stateManager.set(`session:${sessionId}:completed:${delegationId}`, {
+                delegation,
+                result,
+                completedAt: Date.now(),
+            });
+        }
+    }
+    /**
+     * Get session coordination status
+     */
+    getSessionStatus(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return null;
+        }
+        return {
+            active: session.isActive,
+            agentCount: session.coordinationState.activeAgents.size,
+        };
+    }
+    /**
+     * Resolve conflicts using specified strategy
+     */
+    resolveConflict(sessionId, conflictKey, strategy) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+        const sharedData = session.coordinationState.sharedContext.get(conflictKey);
+        if (!sharedData || !Array.isArray(sharedData)) {
+            return undefined;
+        }
+        let resolved;
+        switch (strategy) {
+            case "majority_vote":
+                // Find most common value
+                const counts = {};
+                sharedData.forEach((item) => {
+                    const value = JSON.stringify(item.value);
+                    counts[value] = (counts[value] || 0) + 1;
+                });
+                const majorityEntry = Object.entries(counts).reduce(([keyA, countA], [keyB, countB]) => (countA > countB ? [keyA, countA] : [keyB, countB]));
+                if (majorityEntry) {
+                    resolved = JSON.parse(majorityEntry[0]);
+                }
+                break;
+            case "expert_priority":
+                // Use security-auditor if available, otherwise first value
+                const expertItem = sharedData.find((item) => item.fromAgent === "security-auditor");
+                resolved = expertItem ? expertItem.value : sharedData[0]?.value;
+                break;
+            case "consensus":
+                // All values must be the same
+                const firstValue = sharedData[0]?.value;
+                const allSame = sharedData.every((item) => JSON.stringify(item.value) === JSON.stringify(firstValue));
+                resolved = allSame ? firstValue : undefined;
+                break;
+        }
+        // Record the conflict resolution
+        const agents = sharedData.map((item) => item.fromAgent);
+        this.recordConflict(sessionId, agents, strategy, resolved);
+        return resolved;
+    }
+    /**
+     * Cleanup session coordination data
+     */
+    cleanupSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        // Clear all session data
+        session.activeDelegations.clear();
+        session.agentInteractions.clear();
+        session.conflictHistory = [];
+        session.coordinationState.activeAgents.clear();
+        session.coordinationState.pendingCommunications = [];
+        session.coordinationState.sharedContext.clear();
+        // Remove session from active sessions map
+        this.sessions.delete(sessionId);
+        // Clear from state manager
+        this.stateManager.clear(`session:${sessionId}:coordinator`);
+    }
+    // Private methods
+    updateSessionMetrics(session, interaction) {
+        const metrics = session.coordinationState.sessionMetrics;
+        metrics.totalInteractions++;
+        if (interaction.success) {
+            metrics.successfulInteractions++;
+        }
+        else {
+            metrics.failedInteractions++;
+        }
+        const totalResponseTime = metrics.averageResponseTime * (metrics.totalInteractions - 1) +
+            interaction.duration;
+        metrics.averageResponseTime = totalResponseTime / metrics.totalInteractions;
+        const successRate = metrics.successfulInteractions / metrics.totalInteractions;
+        const conflictRate = session.conflictHistory.length / Math.max(metrics.totalInteractions, 1);
+        metrics.coordinationEfficiency = successRate * (1 - conflictRate);
+    }
+}
+// Export singleton instance factory
+export const createSessionCoordinator = (stateManager) => {
+    return new SessionCoordinator(stateManager);
+};