0xray 4.0.13 → 4.0.14

package/dist/mcps/orchestrator/handlers/complexity-handler.js

@@ -0,0 +1,285 @@
+/**
+ * Complexity Handler
+ *
+ * Handles complexity analysis requests
+ */
+import { frameworkLogger } from '../../../core/framework-logger.js';
+import { buildLeadDevPlan, buildSynthesisCheckpointPlan, isLeadDevModeActive, persistLeadDevPlan, } from '../../../nucleus/autonomy-kernel.js';
+import { formatConferQuorumReport, isConferEnabled, runConferQuorum, } from '../../../nucleus/confer.js';
+import { bindPlanToSession } from '../../../nucleus/lead-dev-plan-persistence.js';
+import { clearPendingDelegations } from '../../../nucleus/pending-delegations.js';
+import { isAutoProvisionWorktreeEnabled, provisionGitWorktree, } from '../../../nucleus/aside-worktree.js';
+import { buildUserAsidePlan, formatUserAsideSummary, isUserAsidesEnabled, loadUserAside, mergeUserAsideIntake, saveUserAside, setActiveAsideId, UserAsideValidationError, } from '../../../nucleus/user-aside.js';
+import { getExecutionPlanner } from '../execution/execution-planner.js';
+import { addObservations, extractComplexityObservations } from '../aside-context.js';
+function normalizeAnalyzeTasks(raw) {
+    return raw.map((task, index) => {
+        let deps;
+        if (Array.isArray(task.dependencies)) {
+            deps = task.dependencies;
+        }
+        else if (typeof task.dependencies === 'number' && Number.isFinite(task.dependencies)) {
+            deps = task.dependencies;
+        }
+        else if (typeof task.dependencyCount === 'number' &&
+            Number.isFinite(task.dependencyCount)) {
+            deps = task.dependencyCount;
+        }
+        const normalized = {
+            id: task.id ?? `task-${index + 1}`,
+            description: task.description ?? '',
+            type: task.type ?? 'implement',
+        };
+        if (task.priority)
+            normalized.priority = task.priority;
+        if (deps !== undefined)
+            normalized.dependencies = deps;
+        if (task.estimatedComplexity !== undefined) {
+            normalized.estimatedComplexity = task.estimatedComplexity;
+        }
+        return normalized;
+    });
+}
+/**
+ * Complexity Handler
+ * Processes analyze-complexity requests
+ */
+export class ComplexityHandler {
+    planner = getExecutionPlanner();
+    /**
+     * Handle analyze-complexity request
+     */
+    async handleAnalyzeComplexity(args, asideId) {
+        const tasks = normalizeAnalyzeTasks(args.tasks ?? []);
+        await frameworkLogger.log('orchestrator.server', 'analyze-complexity-start', 'info', { taskCount: tasks.length });
+        try {
+            const analysis = await this.planner.analyzeTaskComplexity(tasks);
+            const recommendations = this.generateRecommendations(analysis);
+            if (asideId) {
+                addObservations(asideId, extractComplexityObservations(analysis));
+            }
+            const primaryDescription = tasks.map((t) => t.description).filter(Boolean).join(' ');
+            const taskTypes = tasks.map((t) => t.type).filter(Boolean);
+            const planTaskInputs = tasks
+                .filter((t) => t.description?.trim())
+                .map((t) => ({ description: t.description, type: t.type }));
+            const synthesisCheckpoint = args.synthesisCheckpoint === true;
+            const projectRoot = process.cwd();
+            const userAsideIntake = !synthesisCheckpoint &&
+                Boolean(args.userAsideId?.trim()) &&
+                isUserAsidesEnabled(projectRoot);
+            let userAsideReport = '';
+            let leadDevPlan = synthesisCheckpoint
+                ? buildSynthesisCheckpointPlan(args.synthesisDueReason ?? null, projectRoot)
+                : userAsideIntake
+                    ? null
+                    : isLeadDevModeActive() && (primaryDescription || planTaskInputs.length > 0)
+                        ? buildLeadDevPlan(primaryDescription, taskTypes.length ? taskTypes : ['implement'], planTaskInputs, analysis.overallComplexity, projectRoot)
+                        : null;
+            let planPersisted = synthesisCheckpoint
+                ? leadDevPlan !== null
+                : userAsideIntake
+                    ? false
+                    : !leadDevPlan;
+            if (userAsideIntake && args.userAsideId) {
+                try {
+                    const asideId = args.userAsideId.trim();
+                    const title = args.userAsideTitle?.trim() || asideId;
+                    const existing = loadUserAside(asideId, projectRoot);
+                    const userAside = existing
+                        ? mergeUserAsideIntake(existing, primaryDescription || existing.description, planTaskInputs, analysis.overallComplexity, projectRoot)
+                        : buildUserAsidePlan(asideId, title, primaryDescription || title, planTaskInputs, analysis.overallComplexity, projectRoot);
+                    if (!userAside) {
+                        planPersisted = false;
+                    }
+                    else {
+                        if (args.worktree)
+                            userAside.worktree = args.worktree;
+                        if (args.branch)
+                            userAside.branch = args.branch;
+                        if (args.sessionId)
+                            userAside.sessionId = args.sessionId;
+                        if (args.userAsideTitle)
+                            userAside.title = title;
+                        let worktreeProvisionNote = '';
+                        if (args.worktree?.trim() &&
+                            args.branch?.trim() &&
+                            isAutoProvisionWorktreeEnabled(projectRoot)) {
+                            const provision = provisionGitWorktree({
+                                projectRoot,
+                                worktree: args.worktree.trim(),
+                                branch: args.branch.trim(),
+                            });
+                            if (!provision.ok) {
+                                throw new UserAsideValidationError(`Worktree auto-provision failed: ${provision.message}`);
+                            }
+                            worktreeProvisionNote = provision.created
+                                ? `\n\n**Worktree provisioned:** \`${provision.path}\` (branch \`${args.branch.trim()}\`)`
+                                : `\n\n**Worktree ready:** \`${provision.path}\``;
+                        }
+                        const asidePath = saveUserAside(userAside, projectRoot);
+                        const activate = args.setActiveAside !== false;
+                        if (activate) {
+                            clearPendingDelegations(projectRoot);
+                            setActiveAsideId(asideId, projectRoot, args.sessionId ?? null);
+                        }
+                        planPersisted = true;
+                        userAsideReport = `\n\n## User aside\n\n${formatUserAsideSummary(userAside)}${worktreeProvisionNote}`;
+                        if (activate) {
+                            userAsideReport += `\n\n**Active aside:** \`${asideId}\` — spawns route to \`${asideId}.a.*\` todos.`;
+                        }
+                        await frameworkLogger.log('orchestrator.server', 'user-aside-persisted', 'info', {
+                            asidePath,
+                            asideId,
+                            todoCount: userAside.plan.phases.reduce((n, p) => n + p.todos.length, 0),
+                            activated: activate,
+                        });
+                    }
+                }
+                catch (err) {
+                    planPersisted = false;
+                    const message = err instanceof Error ? err.message : String(err);
+                    userAsideReport = `\n\n❌ User aside intake failed: ${message}`;
+                    await frameworkLogger.log('orchestrator.server', 'user-aside-persist-failed', 'warning', {
+                        error: message,
+                        validation: err instanceof UserAsideValidationError,
+                    });
+                }
+            }
+            else if (leadDevPlan) {
+                try {
+                    const sessionId = args.sessionId ?? `analyze-${Date.now()}`;
+                    if (!synthesisCheckpoint) {
+                        clearPendingDelegations();
+                    }
+                    const planPath = persistLeadDevPlan(leadDevPlan);
+                    const bound = bindPlanToSession(sessionId);
+                    planPersisted = true;
+                    await frameworkLogger.log('orchestrator.server', synthesisCheckpoint ? 'synthesis-plan-persisted' : 'lead-dev-plan-persisted', 'info', {
+                        planPath,
+                        sessionId,
+                        planGeneration: bound?.planGeneration,
+                        phaseCount: leadDevPlan.phases.length,
+                        todoCount: leadDevPlan.phases.reduce((n, p) => n + p.todos.length, 0),
+                        synthesisCheckpoint,
+                    });
+                }
+                catch (err) {
+                    planPersisted = false;
+                    await frameworkLogger.log('orchestrator.server', synthesisCheckpoint ? 'synthesis-plan-persist-failed' : 'lead-dev-plan-persist-failed', 'warning', { error: err instanceof Error ? err.message : String(err) });
+                }
+            }
+            let conferReport = '';
+            if (synthesisCheckpoint &&
+                leadDevPlan &&
+                planPersisted &&
+                isConferEnabled() &&
+                args.sessionId) {
+                const conferOpts = {
+                    dueReason: args.synthesisDueReason ?? null,
+                    fixture: args.conferFixture === true,
+                };
+                if (args.collocatedText)
+                    conferOpts.collocatedText = args.collocatedText;
+                const conferResult = await runConferQuorum(process.cwd(), args.sessionId, conferOpts);
+                conferReport = `\n\n${formatConferQuorumReport(conferResult)}`;
+                await frameworkLogger.log('orchestrator.server', 'confer-quorum', conferResult.status === 'completed' ? 'info' : 'warning', {
+                    status: conferResult.status,
+                    agentCount: conferResult.agents.length,
+                    sessionId: args.sessionId,
+                });
+            }
+            const ok = planPersisted;
+            return {
+                ok,
+                content: [
+                    {
+                        type: 'text',
+                        text: this.formatComplexityResponse(analysis, recommendations, tasks.length, leadDevPlan, synthesisCheckpoint) + conferReport + userAsideReport,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Complexity analysis failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * Generate recommendations based on complexity analysis
+     */
+    generateRecommendations(analysis) {
+        const recommendations = [];
+        if (analysis.overallComplexity > 70) {
+            recommendations.push('Consider breaking down complex tasks into smaller subtasks');
+            recommendations.push('Use sequential execution mode for high-complexity workflows');
+        }
+        if (analysis.parallelPotential > 0.7) {
+            recommendations.push('High parallel potential - consider parallel execution mode');
+        }
+        if (analysis.parallelPotential < 0.3) {
+            recommendations.push('Many dependencies - sequential or optimized mode recommended');
+        }
+        for (const assignment of analysis.agentAssignments) {
+            if (assignment.utilization > 80) {
+                recommendations.push(`${assignment.agent} is at ${assignment.utilization}% utilization - consider adding more agents`);
+            }
+        }
+        if (recommendations.length === 0) {
+            recommendations.push('Task distribution looks optimal');
+        }
+        return recommendations;
+    }
+    /**
+     * Format complexity response
+     */
+    formatComplexityResponse(analysis, recommendations, taskCount, leadDevPlan = null, synthesisCheckpoint = false) {
+        const leadDevSection = leadDevPlan
+            ? `
+
+**Lead-dev plan (codex ${leadDevPlan.codexTerms.join(', ')}):**
+${leadDevPlan.phases
+                .map((p) => `### ${p.id} — ${p.name}\n${p.todos
+                .map((t) => `- [ ] ${t.id} (${t.subagent}): ${t.task}`)
+                .join('\n')}`)
+                .join('\n\n')}
+
+**Test protocol:** ${leadDevPlan.testProtocol.hint}
+
+\`\`\`json
+${JSON.stringify(leadDevPlan, null, 2)}
+\`\`\``
+            : '';
+        const header = synthesisCheckpoint
+            ? '🔄 Synthesis Checkpoint — Reflect & Realign'
+            : '🔍 Complexity Analysis Results';
+        return `${header}
+
+**Tasks Analyzed:** ${taskCount}
+**Overall Complexity:** ${analysis.overallComplexity}/100
+**Recommended Strategy:** ${analysis.recommendedStrategy}
+
+**Complexity Breakdown:**
+${analysis.taskComplexity
+            .map((task, index) => `• Task ${index + 1}: ${task.complexity}/100 (${task.category})`)
+            .join('\n')}
+
+**Agent Assignments:**
+${analysis.agentAssignments
+            .map((assignment) => `• ${assignment.agent}: ${assignment.taskCount} tasks (${assignment.utilization}%)`)
+            .join('\n')}
+
+**Recommendations:**
+${recommendations.map((r) => `• 💡 ${r}`).join('\n')}
+
+**Execution Estimate:** ${analysis.estimatedDuration}ms
+**Parallel Potential:** ${Math.round(analysis.parallelPotential * 100)}%${leadDevSection}`;
+    }
+}

package/dist/mcps/orchestrator/handlers/status-handler.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Status Handler
+ *
+ * Handles orchestration status requests
+ */
+import type { OrchestrationResult } from '../types.js';
+interface HistoryItem {
+    sessionId: string;
+    description: string;
+    tasks: number;
+    result: OrchestrationResult;
+    timestamp: string;
+}
+interface StatusHandlerDeps {
+    activeTasks: Map<string, unknown>;
+    taskHistory: HistoryItem[];
+    asideCount?: number;
+    asideIds?: string[];
+}
+/**
+ * Status Handler
+ * Processes get-orchestration-status requests
+ */
+export declare class StatusHandler {
+    /**
+     * Handle get-orchestration-status request
+     */
+    handleGetOrchestrationStatus(args: {
+        sessionId?: string;
+        detailed?: boolean;
+    }, deps: StatusHandlerDeps): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+    /**
+     * Handle cancel-orchestration request
+     */
+    handleCancelOrchestration(args: {
+        sessionId?: string;
+        taskId?: string;
+        force?: boolean;
+    }, deps: StatusHandlerDeps): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+    /**
+     * Handle optimize-orchestration request
+     */
+    handleOptimizeOrchestration(args: {
+        history?: boolean;
+        recommendations?: boolean;
+    }): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+    /**
+     * Get overall orchestration status
+     */
+    private getOverallStatus;
+    /**
+     * Format status response
+     */
+    private formatStatusResponse;
+}
+export {};

package/dist/mcps/orchestrator/handlers/status-handler.js

@@ -0,0 +1,239 @@
+/**
+ * Status Handler
+ *
+ * Handles orchestration status requests
+ */
+import { frameworkLogger } from '../../../core/framework-logger.js';
+/**
+ * Status Handler
+ * Processes get-orchestration-status requests
+ */
+export class StatusHandler {
+    /**
+     * Handle get-orchestration-status request
+     */
+    async handleGetOrchestrationStatus(args, deps) {
+        const { sessionId, detailed = false } = args;
+        await frameworkLogger.log('orchestrator.server', 'get-status-start', 'info', { sessionId, detailed });
+        try {
+            let status;
+            if (sessionId) {
+                status = deps.activeTasks.get(sessionId);
+                if (!status) {
+                    // Check history
+                    const historyItem = deps.taskHistory.find((h) => h.sessionId === sessionId);
+                    if (historyItem) {
+                        status = { completed: true, ...historyItem.result };
+                    }
+                    else {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `❌ Session not found: ${sessionId}`,
+                                },
+                            ],
+                        };
+                    }
+                }
+            }
+            else {
+                // Overall status
+                status = this.getOverallStatus(deps);
+            }
+            let response = this.formatStatusResponse(status, detailed);
+            if (detailed && deps.asideCount !== undefined) {
+                response += `\n\n**Active Aside Contexts:**`;
+                response += `\n• Count: ${deps.asideCount}`;
+                if (deps.asideIds && deps.asideIds.length > 0) {
+                    response += `\n• IDs: ${deps.asideIds.join(', ')}`;
+                }
+            }
+            return { content: [{ type: 'text', text: response }] };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Status check failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * Handle cancel-orchestration request
+     */
+    async handleCancelOrchestration(args, deps) {
+        const { sessionId, taskId, force = false } = args;
+        await frameworkLogger.log('orchestrator.server', 'cancel-orchestration-start', 'info', { sessionId, taskId, force });
+        try {
+            if (!sessionId) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: '❌ sessionId is required for cancellation',
+                        },
+                    ],
+                };
+            }
+            // Check if session exists
+            const existingTask = deps.activeTasks.get(sessionId);
+            if (!existingTask) {
+                // Check history
+                const historyItem = deps.taskHistory.find((h) => h.sessionId === sessionId);
+                if (historyItem) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `❌ Session already completed: ${sessionId}`,
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Session not found: ${sessionId}`,
+                        },
+                    ],
+                };
+            }
+            // Cancel the session
+            deps.activeTasks.delete(sessionId);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `✅ Orchestration cancelled: ${sessionId}${taskId ? ` (task: ${taskId})` : ''}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Cancellation failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * Handle optimize-orchestration request
+     */
+    async handleOptimizeOrchestration(args) {
+        const { history = true, recommendations = true } = args;
+        await frameworkLogger.log('orchestrator.server', 'optimize-orchestration-start', 'info', { history, recommendations });
+        try {
+            const optimizations = [];
+            if (recommendations) {
+                optimizations.push('Consider using "optimized" execution mode for most workflows');
+                optimizations.push('Batch similar tasks together for better agent utilization');
+                optimizations.push('Monitor agent utilization and adjust concurrent task limits');
+            }
+            if (history) {
+                optimizations.push('Review historical data to identify recurring patterns');
+                optimizations.push('Use complexity analysis to pre-plan task distribution');
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `🔧 Orchestration Optimization Results
+
+**Optimizations Available:**
+${optimizations.map((o) => `• ${o}`).join('\n')}
+
+**Current Best Practices:**
+• Use "optimized" mode for mixed task types
+• Set appropriate timeouts based on task complexity
+• Monitor bottleneck agents and redistribute load
+• Leverage task dependencies for correct execution order`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Optimization failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * Get overall orchestration status
+     */
+    getOverallStatus(deps) {
+        const agentUtilization = {};
+        // Aggregate from active tasks
+        for (const [, task] of deps.activeTasks) {
+            const taskAny = task;
+            if (taskAny.agentUtilization) {
+                const util = taskAny.agentUtilization;
+                for (const [agent, count] of Object.entries(util)) {
+                    agentUtilization[agent] = (agentUtilization[agent] || 0) + count;
+                }
+            }
+        }
+        // Get recent sessions from history
+        const recentSessions = deps.taskHistory
+            .slice(-10)
+            .map((h) => ({
+            sessionId: h.sessionId,
+            status: 'completed',
+            tasks: h.tasks,
+            duration: h.result.duration,
+        }));
+        return {
+            activeSessions: deps.activeTasks.size,
+            totalTasks: deps.taskHistory.reduce((sum, h) => sum + h.tasks, 0),
+            agentUtilization,
+            recentSessions,
+        };
+    }
+    /**
+     * Format status response
+     */
+    formatStatusResponse(status, detailed) {
+        const statusAny = status;
+        // Check if it's a completed session
+        if (statusAny.completed) {
+            const result = statusAny;
+            return `📊 Session Status: COMPLETED
+
+**Success:** ${result.success ? '✅ Yes' : '❌ No'}
+**Duration:** ${result.duration}ms
+**Tasks:** ${result.completedTasks + result.failedTasks} (${result.completedTasks} ✅, ${result.failedTasks} ❌)`;
+        }
+        // Overall status
+        const orchStatus = status;
+        let response = `📊 Orchestration Status
+
+**Active Sessions:** ${orchStatus.activeSessions}
+**Total Tasks Executed:** ${orchStatus.totalTasks}`;
+        if (Object.keys(orchStatus.agentUtilization).length > 0) {
+            response += `\n\n**Agent Utilization:**`;
+            for (const [agent, count] of Object.entries(orchStatus.agentUtilization)) {
+                response += `\n• ${agent}: ${count} tasks`;
+            }
+        }
+        if (detailed && orchStatus.recentSessions.length > 0) {
+            response += `\n\n**Recent Sessions:**`;
+            for (const session of orchStatus.recentSessions) {
+                response += `\n• ${session.sessionId}: ${session.tasks} tasks, ${session.duration}ms`;
+            }
+        }
+        return response;
+    }
+}

package/dist/mcps/orchestrator/handlers/task-handler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Task Handler
+ *
+ * Handles task orchestration requests
+ */
+import type { OrchestrationResult, OrchestrationTask } from '../types.js';
+export interface TaskHandlerDeps {
+    taskHistory: OrchestrationHistoryItem[];
+    activeTasks: Map<string, unknown>;
+    asideId?: string;
+}
+interface OrchestrationHistoryItem {
+    sessionId: string;
+    description: string;
+    tasks: number;
+    result: OrchestrationResult;
+    timestamp: string;
+}
+/**
+ * Task Handler
+ * Processes orchestrate-task requests
+ */
+export declare class TaskHandler {
+    private planner;
+    /**
+     * Handle orchestrate-task request
+     */
+    handleOrchestrateTask(args: {
+        description: string;
+        tasks?: OrchestrationTask[];
+        sessionId?: string;
+        executionMode?: string;
+        timeout?: number;
+        confer?: boolean;
+        conferFixture?: boolean;
+        collocatedText?: string;
+        userAsideId?: string;
+        setActiveAside?: boolean;
+        clearActiveAside?: boolean;
+    }, deps: TaskHandlerDeps): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+    /**
+     * Execute the orchestration plan.
+     * For known MCP skill servers (code-review, security-audit, researcher, etc.),
+     * we actually call the target tool. For other agents we record the assignment.
+     */
+    private executePlan;
+    private mapAgentToTool;
+    private extractTextFromMcpResult;
+    /**
+     * Format orchestration response
+     */
+    private formatOrchestrationResponse;
+}
+export {};