forgeagent 3.0.0-alpha.12

package/dist/execution/pm/coordination-engine.js

@@ -0,0 +1,961 @@
+/**
+ * Coordination Engine
+ *
+ * Manages DAG-based parallel execution of agent tasks:
+ * - Builds dependency graph from task requirements
+ * - Topological sort into parallel batches
+ * - Injects context between dependent agents via HandoffPackage
+ * - Tracks execution state and enables resume
+ * - VCC verification gate with circuit breaker (Agent Harness Pattern)
+ */
+import { BlueprintGateRunner } from '../blueprint/gate-runner.js';
+import { DEFAULT_VALIDATION_BLUEPRINT } from '../blueprint/types.js';
+import { SessionState } from '../types/session-state.js';
+import logger from '../../utils/logger.js';
+import { hasBlockingVccMustFailure } from '../../contracts/vcc/runtime-metadata.js';
+import { VCC_CRITIC_MAX_TOKENS } from '../../config/engine-defaults.js';
+const DEFAULT_VCC_GATE_CONFIG = {
+    enabled: false,
+    maxRetries: 3,
+    softGateMode: true, // Start soft, promote to hard after stability
+    testTimeoutMs: 60000 // 1 minute
+};
+const DEFAULT_CONFIG = {
+    maxParallelTasks: 3,
+    enableParallelExecution: true,
+    handoffSummaryMaxTokens: 2000,
+    estimateTokensPerTask: VCC_CRITIC_MAX_TOKENS,
+    estimateMsPerTask: 60000, // 1 minute
+    vccGate: DEFAULT_VCC_GATE_CONFIG
+};
+/**
+ * Coordination Engine - DAG-based parallel task execution
+ */
+export class CoordinationEngine {
+    config;
+    taskNodes = new Map();
+    executionPlan = null;
+    completedTasks = new Set();
+    taskResults = new Map();
+    handoffs = new Map(); // target task -> handoffs
+    // VCC Gate state
+    vccRetryCount = 0;
+    lastVCCGateResult = null;
+    sessionState = SessionState.RUNNING;
+    stateChangeHandlers = [];
+    interventionHandlers = [];
+    // Completed features for VCC testing (populated by recordCompletion)
+    completedFeatures = [];
+    blueprintRunner;
+    constructor(config = {}) {
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            vccGate: { ...DEFAULT_VCC_GATE_CONFIG, ...config.vccGate }
+        };
+        this.blueprintRunner = new BlueprintGateRunner(config.blueprintGate ?? { enabled: true });
+        logger.debug('[CoordinationEngine] Initialized', { config: this.config, blueprintEnabled: this.blueprintRunner.isEnabled() });
+    }
+    /**
+     * Subscribe to session state changes
+     */
+    onStateChange(handler) {
+        this.stateChangeHandlers.push(handler);
+    }
+    /**
+     * Subscribe to human intervention events
+     */
+    onHumanInterventionRequired(handler) {
+        this.interventionHandlers.push(handler);
+    }
+    /**
+     * Get current session state
+     */
+    getSessionState() {
+        return this.sessionState;
+    }
+    /**
+     * Get last VCC gate result
+     */
+    getLastVCCGateResult() {
+        return this.lastVCCGateResult;
+    }
+    /**
+     * Run VCC verification gate before batch execution
+     *
+     * @param testRunner - Function that runs VCC test suite and returns results
+     * @returns VCCGateResult with pass/fail status
+     */
+    async runVCCGate(testRunner) {
+        if (!this.config.vccGate.enabled || (this.completedFeatures.length === 0 && this.taskResults.size === 0)) {
+            return {
+                passed: true,
+                passCount: 0,
+                failCount: 0,
+                failures: [],
+                executionTimeMs: 0,
+                retryCount: 0,
+                circuitBreakerTriggered: false
+            };
+        }
+        logger.info('[CoordinationEngine] Running VCC verification gate', {
+            completedFeatures: this.completedFeatures.length,
+            retryCount: this.vccRetryCount
+        });
+        const startTime = Date.now();
+        let testResults;
+        try {
+            testResults = await Promise.race([
+                testRunner(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('VCC test timeout')), this.config.vccGate.testTimeoutMs))
+            ]);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            testResults = {
+                passed: 0,
+                failed: 1,
+                failures: [{
+                        testFile: 'vcc-gate',
+                        testName: 'execution',
+                        errorMessage: `VCC test execution failed: ${errorMessage}`,
+                        stackTrace: error instanceof Error ? error.stack : undefined
+                    }],
+                executionTimeMs: Date.now() - startTime
+            };
+        }
+        const result = {
+            passed: testResults.failed === 0,
+            passCount: testResults.passed,
+            failCount: testResults.failed,
+            failures: testResults.failures,
+            executionTimeMs: testResults.executionTimeMs,
+            retryCount: this.vccRetryCount,
+            circuitBreakerTriggered: false
+        };
+        if (!result.passed) {
+            this.vccRetryCount++;
+            if (this.vccRetryCount > this.config.vccGate.maxRetries) {
+                // Circuit breaker triggered
+                result.circuitBreakerTriggered = true;
+                this.sessionState = SessionState.HUMAN_INTERVENTION;
+                const interventionEvent = {
+                    reason: 'VCC_GATE_MAX_RETRIES',
+                    failedTests: result.failures,
+                    attempts: this.vccRetryCount,
+                    suggestedActions: [
+                        'Review failed VCC tests for potential flaws in test generation',
+                        'Check if the failing criteria are achievable with current implementation',
+                        'Consider waiving specific criteria if justified',
+                        'Manually fix the underlying issues and mark as FIXED_BY_HUMAN'
+                    ]
+                };
+                logger.warn('[CoordinationEngine] VCC gate circuit breaker triggered', {
+                    attempts: this.vccRetryCount,
+                    failedTests: result.failures.length
+                });
+                // Emit events
+                this.emitStateChange(SessionState.RUNNING, SessionState.HUMAN_INTERVENTION, 'vcc_gate_max_retries', {
+                    intervention: {
+                        reason: 'VCC verification gate failed after maximum retries',
+                        vccRetryCount: this.vccRetryCount,
+                        failedTests: result.failures,
+                        suggestedActions: interventionEvent.suggestedActions
+                    }
+                });
+                for (const handler of this.interventionHandlers) {
+                    try {
+                        handler(interventionEvent);
+                    }
+                    catch (e) {
+                        logger.error('[CoordinationEngine] Intervention handler error', { error: e });
+                    }
+                }
+            }
+            else if (!this.config.vccGate.softGateMode) {
+                // Hard gate mode - log warning but allow retry
+                logger.warn('[CoordinationEngine] VCC gate failed, will retry', {
+                    attempt: this.vccRetryCount,
+                    maxRetries: this.config.vccGate.maxRetries,
+                    failures: result.failures.map(f => f.testName)
+                });
+            }
+            else {
+                // Soft gate mode - advisory only
+                logger.info('[CoordinationEngine] VCC gate soft failure (advisory)', {
+                    failures: result.failures.map(f => f.testName)
+                });
+            }
+        }
+        else {
+            // Reset retry count on success
+            this.vccRetryCount = 0;
+            logger.info('[CoordinationEngine] VCC gate passed', {
+                passCount: result.passCount
+            });
+        }
+        this.lastVCCGateResult = result;
+        return result;
+    }
+    /**
+     * Check if execution should proceed based on VCC gate status
+     */
+    shouldProceedWithExecution() {
+        if (this.sessionState === SessionState.HUMAN_INTERVENTION) {
+            return false;
+        }
+        if (!this.config.vccGate.enabled) {
+            return true;
+        }
+        if (!this.lastVCCGateResult) {
+            return true; // No gate result yet
+        }
+        // VCC MUST failures always block execution, even in soft mode.
+        if (this.hasBlockingMustFailures(this.lastVCCGateResult)) {
+            return false;
+        }
+        // In soft mode, proceed for non-MUST failures (advisory only)
+        if (this.config.vccGate.softGateMode) {
+            return true;
+        }
+        // In hard mode, only proceed when the most recent gate explicitly passed.
+        return this.lastVCCGateResult.passed;
+    }
+    /**
+     * Create a regression fix task definition when VCC gate fails
+     *
+     * Returns a partial task definition that the caller must complete
+     * by adding agent and projectContext before execution.
+     *
+     * @param failures - VCC test failures to fix
+     * @param context - Additional context (error output, stack trace)
+     * @returns Task definition to be completed, or null if no failures
+     */
+    createRegressionFixTaskDef(failures, context) {
+        if (failures.length === 0) {
+            return null;
+        }
+        const fixTaskId = `fix-vcc-regression-${Date.now()}`;
+        const failureDescriptions = failures.map(f => `- ${f.testFile}::${f.testName}: ${f.errorMessage}`).join('\n');
+        const taskDef = {
+            id: fixTaskId,
+            description: 'Fix VCC regression failures detected by verification gate',
+            prompt: `The VCC verification gate detected the following test failures that must be fixed before proceeding:
+
+${failureDescriptions}
+
+${context?.errorOutput ? `## Error Output\n\`\`\`\n${context.errorOutput}\n\`\`\`\n` : ''}
+${context?.stackTrace ? `## Stack Trace\n\`\`\`\n${context.stackTrace}\n\`\`\`\n` : ''}
+
+Please analyze the failures and fix the underlying issues. The tests are generated from VCC (Verifiable Completion Contract) specifications and represent completion criteria that must be satisfied.
+
+Focus on:
+1. Understanding what each test is validating
+2. Identifying the root cause of the failure
+3. Making minimal, targeted fixes to pass the tests
+4. Not breaking other functionality in the process`,
+            dependencies: [] // No dependencies - should run immediately
+        };
+        logger.info('[CoordinationEngine] Created regression fix task definition', {
+            taskId: fixTaskId,
+            failureCount: failures.length
+        });
+        return taskDef;
+    }
+    /**
+     * Resume execution after human intervention
+     */
+    resumeAfterIntervention() {
+        if (this.sessionState !== SessionState.HUMAN_INTERVENTION) {
+            logger.warn('[CoordinationEngine] Cannot resume - not in HUMAN_INTERVENTION state');
+            return;
+        }
+        this.vccRetryCount = 0; // Reset retry count
+        this.sessionState = SessionState.RUNNING;
+        this.emitStateChange(SessionState.HUMAN_INTERVENTION, SessionState.RUNNING, 'human_resolved');
+        logger.info('[CoordinationEngine] Resumed after human intervention');
+    }
+    /**
+     * Emit session state change event
+     */
+    emitStateChange(from, to, reason, extra) {
+        const event = {
+            from,
+            to,
+            timestamp: new Date().toISOString(),
+            reason,
+            ...extra
+        };
+        for (const handler of this.stateChangeHandlers) {
+            try {
+                handler(event);
+            }
+            catch (e) {
+                logger.error('[CoordinationEngine] State change handler error', { error: e });
+            }
+        }
+    }
+    /**
+     * Build execution plan from tasks
+     */
+    buildPlan(tasks) {
+        logger.info('[CoordinationEngine] Building execution plan', {
+            taskCount: tasks.length
+        });
+        // Reset state
+        this.taskNodes.clear();
+        this.completedTasks.clear();
+        this.taskResults.clear();
+        this.handoffs.clear();
+        // Build task nodes with dependency info
+        for (const task of tasks) {
+            this.taskNodes.set(task.id, this.buildTaskNode(task));
+        }
+        // Single-Writer enforcement: reviewer agents depend on the writer agent.
+        // This forces writer into batch 1, reviewers into batch 2 — preventing
+        // parallel overwrite race condition (Council verdict Feb 11, 4/4 unanimous).
+        this.enforceWriterReviewerOrder();
+        // Validate dependency references before scheduling to avoid silently
+        // treating missing prerequisites as circular dependencies.
+        this.validateDependencyReferences();
+        // Resolve dependents (reverse lookup)
+        this.resolveDependents();
+        // Build parallel batches via topological sort
+        const batches = this.buildBatches();
+        // Calculate critical path
+        const criticalPath = this.findCriticalPath();
+        // Build plan
+        this.executionPlan = {
+            batches,
+            totalTasks: tasks.length,
+            parallelizable: this.countParallelizable(batches),
+            criticalPath,
+            estimatedTotalTokens: batches.reduce((sum, b) => sum + b.estimatedTokens, 0),
+            estimatedDurationMs: this.estimateTotalDuration(batches)
+        };
+        logger.info('[CoordinationEngine] Execution plan built', {
+            batches: batches.length,
+            parallelizable: this.executionPlan.parallelizable,
+            criticalPathLength: criticalPath.length
+        });
+        return this.executionPlan;
+    }
+    /**
+     * Build task node from task definition
+     */
+    buildTaskNode(task) {
+        // Extract dependencies from task metadata or explicit dependencies
+        const dependencies = task.dependencies || [];
+        // Extract context requirements from task description/metadata
+        const requires = this.extractRequirements(task);
+        const provides = this.extractProvides(task);
+        return {
+            taskId: task.id,
+            task,
+            dependencies,
+            dependents: [], // Filled in resolveDependents()
+            provides,
+            requires
+        };
+    }
+    /**
+     * Classify agent role as 'writer' or 'reviewer'.
+     * Writers generate code (backend, frontend, implementation, architect).
+     * Reviewers validate code (QA, DevOps, test).
+     */
+    classifyAgentRole(agentType) {
+        const lower = agentType.toLowerCase();
+        // Reviewer patterns: QA, DevOps, test-focused agents
+        if (lower.includes('qa') || lower.includes('devops') || lower.includes('test')
+            || lower.includes('review') || lower.includes('security')) {
+            return 'reviewer';
+        }
+        // Everything else is a writer (backend, frontend, architect, etc.)
+        return 'writer';
+    }
+    /**
+     * Enforce single-writer pattern: reviewer tasks depend on the writer task.
+     * This ensures the writer runs in batch 1 and reviewers in batch 2,
+     * preventing parallel overwrite of generated files.
+     *
+     * Council verdict (Feb 11, 4/4 unanimous): Single Writer + Multi-Critic.
+     * Anthropic harness design (Mar 2026): Separate evaluator from generator.
+     */
+    enforceWriterReviewerOrder() {
+        const writerTaskIds = [];
+        const reviewerTaskIds = [];
+        for (const [taskId, node] of this.taskNodes) {
+            const agentType = node.task.agent?.config?.type || '';
+            const role = this.classifyAgentRole(agentType);
+            if (role === 'writer') {
+                writerTaskIds.push(taskId);
+            }
+            else {
+                reviewerTaskIds.push(taskId);
+            }
+        }
+        // Only enforce if we have both writers and reviewers
+        if (writerTaskIds.length === 0 || reviewerTaskIds.length === 0) {
+            return;
+        }
+        // Mark reviewer tasks as depending on ALL writer tasks
+        for (const reviewerId of reviewerTaskIds) {
+            const node = this.taskNodes.get(reviewerId);
+            for (const writerId of writerTaskIds) {
+                if (!node.dependencies.includes(writerId)) {
+                    node.dependencies.push(writerId);
+                }
+            }
+        }
+        logger.info('[CoordinationEngine] Single-writer enforcement applied', {
+            writers: writerTaskIds.length,
+            reviewers: reviewerTaskIds.length,
+            writerTypes: writerTaskIds.map(id => this.taskNodes.get(id).task.agent?.config?.type),
+            reviewerTypes: reviewerTaskIds.map(id => this.taskNodes.get(id).task.agent?.config?.type),
+        });
+    }
+    /**
+     * Extract what context a task requires
+     */
+    extractRequirements(task) {
+        const requires = [];
+        const agentType = task.agent?.config?.type || '';
+        // Common requirement patterns based on agent type
+        if (agentType.includes('architect')) {
+            requires.push('requirements', 'constraints');
+        }
+        if (agentType.includes('qa')) {
+            requires.push('requirements', 'architecture');
+        }
+        if (agentType.includes('implement')) {
+            requires.push('architecture', 'requirements');
+        }
+        if (agentType.includes('test')) {
+            requires.push('implementation', 'qa_plan');
+        }
+        return requires;
+    }
+    /**
+     * Extract what context a task provides
+     */
+    extractProvides(task) {
+        const provides = [];
+        const agentType = task.agent?.config?.type || '';
+        if (agentType.includes('analyst') || agentType.includes('requirements')) {
+            provides.push('requirements', 'constraints');
+        }
+        if (agentType.includes('architect')) {
+            provides.push('architecture', 'design_decisions');
+        }
+        if (agentType.includes('qa')) {
+            provides.push('qa_plan', 'test_strategy');
+        }
+        if (agentType.includes('implement')) {
+            provides.push('implementation', 'code_structure');
+        }
+        return provides;
+    }
+    /**
+     * Resolve dependents (reverse of dependencies)
+     */
+    resolveDependents() {
+        for (const [taskId, node] of this.taskNodes) {
+            for (const depId of node.dependencies) {
+                const depNode = this.taskNodes.get(depId);
+                if (depNode) {
+                    depNode.dependents.push(taskId);
+                }
+            }
+        }
+    }
+    /**
+     * Build parallel execution batches via topological sort
+     */
+    buildBatches() {
+        const batches = [];
+        const completed = new Set();
+        const remaining = new Set(this.taskNodes.keys());
+        let batchNumber = 0;
+        while (remaining.size > 0) {
+            // Find all tasks whose dependencies are satisfied
+            const ready = [];
+            for (const taskId of remaining) {
+                const node = this.taskNodes.get(taskId);
+                const depsReady = node.dependencies.every(d => completed.has(d));
+                if (depsReady) {
+                    ready.push(node.task);
+                }
+            }
+            if (ready.length === 0 && remaining.size > 0) {
+                // Circular dependency detected - break by taking first remaining
+                logger.warn('[CoordinationEngine] Circular dependency detected, breaking cycle');
+                const firstRemaining = remaining.values().next().value;
+                const node = this.taskNodes.get(firstRemaining);
+                ready.push(node.task);
+            }
+            // Limit batch size
+            const batchTasks = this.config.enableParallelExecution
+                ? ready.slice(0, this.config.maxParallelTasks)
+                : [ready[0]];
+            // Create batch
+            const batch = {
+                batchNumber: batchNumber++,
+                tasks: batchTasks,
+                canParallelize: batchTasks.length > 1,
+                estimatedTokens: batchTasks.length * this.config.estimateTokensPerTask,
+                estimatedDurationMs: this.config.estimateMsPerTask // Parallel = same duration
+            };
+            batches.push(batch);
+            // Mark as completed for next iteration
+            for (const task of batchTasks) {
+                completed.add(task.id);
+                remaining.delete(task.id);
+            }
+        }
+        return batches;
+    }
+    /**
+     * Validate that all dependency references point to known tasks.
+     * Throws immediately if any are missing.
+     */
+    validateDependencyReferences() {
+        const missing = [];
+        for (const [taskId, node] of this.taskNodes) {
+            for (const depId of node.dependencies) {
+                if (!this.taskNodes.has(depId)) {
+                    missing.push({ taskId, dependencyId: depId });
+                }
+            }
+        }
+        if (missing.length > 0) {
+            const preview = missing
+                .slice(0, 5)
+                .map(m => `${m.taskId} -> ${m.dependencyId}`)
+                .join(', ');
+            throw new Error(`[CoordinationEngine] Missing task dependencies detected (${missing.length}): ${preview}`);
+        }
+    }
+    /**
+     * Find critical path (longest dependency chain)
+     */
+    findCriticalPath() {
+        const memo = new Map();
+        const longestPath = (taskId) => {
+            if (memo.has(taskId)) {
+                return memo.get(taskId);
+            }
+            const node = this.taskNodes.get(taskId);
+            if (!node || node.dependencies.length === 0) {
+                const path = [taskId];
+                memo.set(taskId, path);
+                return path;
+            }
+            // Find longest path among dependencies
+            let longest = [];
+            for (const depId of node.dependencies) {
+                const path = longestPath(depId);
+                if (path.length > longest.length) {
+                    longest = path;
+                }
+            }
+            const result = [...longest, taskId];
+            memo.set(taskId, result);
+            return result;
+        };
+        // Find overall longest path
+        let criticalPath = [];
+        for (const taskId of this.taskNodes.keys()) {
+            const path = longestPath(taskId);
+            if (path.length > criticalPath.length) {
+                criticalPath = path;
+            }
+        }
+        return criticalPath;
+    }
+    /**
+     * Count parallelizable tasks
+     */
+    countParallelizable(batches) {
+        return batches.reduce((sum, batch) => {
+            return sum + (batch.canParallelize ? batch.tasks.length : 0);
+        }, 0);
+    }
+    /**
+     * Estimate total duration considering parallelism
+     */
+    estimateTotalDuration(batches) {
+        // With parallelism, duration is sum of batch durations (not task durations)
+        return batches.reduce((sum, batch) => sum + batch.estimatedDurationMs, 0);
+    }
+    /**
+     * Get coordination engine configuration (for RuntimeAdapter PMConfigSnapshot)
+     */
+    getConfig() {
+        return {
+            maxParallelTasks: this.config.maxParallelTasks,
+            enableParallelExecution: this.config.enableParallelExecution,
+            handoffSummaryMaxTokens: this.config.handoffSummaryMaxTokens,
+            vccGate: {
+                enabled: this.config.vccGate.enabled,
+                mode: this.config.vccGate.softGateMode ? 'soft' : 'hard',
+                maxRetries: this.config.vccGate.maxRetries,
+            },
+        };
+    }
+    /**
+     * Get current execution plan
+     */
+    getPlan() {
+        return this.executionPlan;
+    }
+    /**
+     * Get next batch of tasks to execute
+     */
+    getNextBatch() {
+        if (!this.executionPlan) {
+            return null;
+        }
+        // Find first batch with uncompleted tasks
+        for (const batch of this.executionPlan.batches) {
+            const pendingTasks = batch.tasks.filter(t => !this.completedTasks.has(t.id));
+            if (pendingTasks.length > 0) {
+                return {
+                    ...batch,
+                    tasks: pendingTasks
+                };
+            }
+        }
+        return null; // All done
+    }
+    /**
+     * Record task completion with result
+     */
+    recordCompletion(taskId, result) {
+        this.completedTasks.add(taskId);
+        this.taskResults.set(taskId, result);
+        const hasBlockingMustFailure = this.hasResultBlockingMustFailure(result);
+        // Track completed features for VCC gate
+        if (result.success && !hasBlockingMustFailure) {
+            this.completedFeatures.push(taskId);
+        }
+        // Generate handoffs for dependent tasks
+        const node = this.taskNodes.get(taskId);
+        if (node && result.success && !hasBlockingMustFailure) {
+            this.generateHandoffs(node, result);
+        }
+        logger.debug('[CoordinationEngine] Task completed', {
+            taskId,
+            success: result.success,
+            hasBlockingMustFailure,
+            dependents: node?.dependents.length || 0,
+            completedFeatures: this.completedFeatures.length
+        });
+    }
+    hasBlockingMustFailures(gateResult) {
+        if (!gateResult || gateResult.failures.length === 0)
+            return false;
+        return gateResult.failures.some((failure) => failure.testFile === 'vcc-must' || /vcc must/i.test(failure.errorMessage));
+    }
+    hasResultBlockingMustFailure(result) {
+        return hasBlockingVccMustFailure(result.metadata);
+    }
+    /**
+     * Get list of completed features for VCC testing
+     */
+    getCompletedFeatures() {
+        return [...this.completedFeatures];
+    }
+    /**
+     * Generate handoff packages for dependent tasks
+     */
+    generateHandoffs(node, result) {
+        const handoff = this.createHandoffPackage(node, result);
+        for (const dependentId of node.dependents) {
+            if (!this.handoffs.has(dependentId)) {
+                this.handoffs.set(dependentId, []);
+            }
+            this.handoffs.get(dependentId).push(handoff);
+        }
+    }
+    /**
+     * Create handoff package from task result
+     */
+    createHandoffPackage(node, result) {
+        const output = result.output || '';
+        const agentType = node.task.agent?.config?.type || 'unknown';
+        return {
+            fromAgent: agentType,
+            toAgent: 'pending', // Will be filled when consumed
+            summary: this.extractSummary(output),
+            requirements: this.extractSection(output, 'requirements'),
+            constraints: this.extractSection(output, 'constraints'),
+            assumptions: this.extractSection(output, 'assumptions'),
+            openQuestions: this.extractSection(output, 'questions'),
+            artifactRefs: this.extractArtifactRefs(result),
+            relevanceScore: 1.0 // Will be adjusted when consumed
+        };
+    }
+    /**
+     * Extract summary from output
+     */
+    extractSummary(output) {
+        // Look for summary section or use first paragraph
+        const summaryMatch = output.match(/#+\s*Summary[:\s]*\n([\s\S]*?)(?=\n#+|$)/i);
+        if (summaryMatch) {
+            return summaryMatch[1].trim().slice(0, this.config.handoffSummaryMaxTokens * 4);
+        }
+        // Fall back to first 500 chars
+        return output.slice(0, 500).trim();
+    }
+    /**
+     * Extract section from output
+     */
+    extractSection(output, sectionName) {
+        const regex = new RegExp(`#+\\s*${sectionName}[:\\s]*\\n([\\s\\S]*?)(?=\\n#+|$)`, 'i');
+        const match = output.match(regex);
+        if (!match) {
+            return [];
+        }
+        // Parse as bullet points or lines
+        const content = match[1];
+        return content
+            .split('\n')
+            .map(line => line.replace(/^[\s*-]+/, '').trim())
+            .filter(line => line.length > 0);
+    }
+    /**
+     * Extract artifact references from result
+     */
+    extractArtifactRefs(result) {
+        const refs = [];
+        if (result.artifacts) {
+            for (const artifact of result.artifacts) {
+                if (typeof artifact === 'string') {
+                    refs.push(artifact);
+                }
+                else if (artifact && typeof artifact === 'object' && 'id' in artifact) {
+                    refs.push(artifact.id);
+                }
+            }
+        }
+        return refs;
+    }
+    /**
+     * Get context for a task (handoffs from dependencies)
+     */
+    getContextForTask(taskId) {
+        const node = this.taskNodes.get(taskId);
+        const agentType = node ? node.task.agent?.config?.type || 'unknown' : 'unknown';
+        const handoffs = this.handoffs.get(taskId) || [];
+        // Update toAgent in handoffs
+        for (const handoff of handoffs) {
+            handoff.toAgent = agentType;
+        }
+        // Get results from dependencies
+        const previousResults = new Map();
+        if (node) {
+            for (const depId of node.dependencies) {
+                const result = this.taskResults.get(depId);
+                if (result) {
+                    previousResults.set(depId, result);
+                }
+            }
+        }
+        return {
+            taskId,
+            agentType,
+            handoffs,
+            summaryChunks: [], // Filled by RunningSummary
+            previousResults
+        };
+    }
+    /**
+     * Inject context into task prompt
+     */
+    injectContext(task, context) {
+        if (context.handoffs.length === 0 && context.summaryChunks.length === 0) {
+            return task; // No context to inject
+        }
+        // Build context section
+        const contextParts = [];
+        if (context.handoffs.length > 0) {
+            contextParts.push('\n\n---\n## Context from Previous Agents\n');
+            for (const handoff of context.handoffs) {
+                contextParts.push(`\n### From ${handoff.fromAgent}\n`);
+                contextParts.push(`**Summary**: ${handoff.summary}\n`);
+                if (handoff.requirements.length > 0) {
+                    contextParts.push(`\n**Key Requirements**:\n${handoff.requirements.map(r => `- ${r}`).join('\n')}\n`);
+                }
+                if (handoff.constraints.length > 0) {
+                    contextParts.push(`\n**Constraints**:\n${handoff.constraints.map(c => `- ${c}`).join('\n')}\n`);
+                }
+                if (handoff.openQuestions.length > 0) {
+                    contextParts.push(`\n**Open Questions**:\n${handoff.openQuestions.map(q => `- ${q}`).join('\n')}\n`);
+                }
+            }
+        }
+        if (context.summaryChunks.length > 0) {
+            contextParts.push('\n\n---\n## Workflow Summary\n');
+            for (const chunk of context.summaryChunks) {
+                contextParts.push(`\n### ${chunk.taskType}\n${chunk.content}\n`);
+            }
+        }
+        // Append context to prompt
+        return {
+            ...task,
+            prompt: task.prompt + contextParts.join('')
+        };
+    }
+    /**
+     * Get completion status
+     */
+    getStatus() {
+        if (!this.executionPlan) {
+            return {
+                totalTasks: 0,
+                completed: 0,
+                remaining: 0,
+                currentBatch: 0,
+                totalBatches: 0
+            };
+        }
+        // Find current batch
+        let currentBatch = 0;
+        for (let i = 0; i < this.executionPlan.batches.length; i++) {
+            const batch = this.executionPlan.batches[i];
+            const allComplete = batch.tasks.every(t => this.completedTasks.has(t.id));
+            if (!allComplete) {
+                currentBatch = i;
+                break;
+            }
+            currentBatch = i + 1;
+        }
+        return {
+            totalTasks: this.executionPlan.totalTasks,
+            completed: this.completedTasks.size,
+            remaining: this.executionPlan.totalTasks - this.completedTasks.size,
+            currentBatch,
+            totalBatches: this.executionPlan.batches.length
+        };
+    }
+    /**
+     * Check if all tasks are complete
+     */
+    isComplete() {
+        return this.executionPlan !== null &&
+            this.completedTasks.size >= this.executionPlan.totalTasks;
+    }
+    /**
+     * Get all task results
+     */
+    getAllResults() {
+        return new Map(this.taskResults);
+    }
+    /**
+     * Run the default validation blueprint (lint → format → typecheck) between phases.
+     * Returns node results from the deterministic gates.
+     */
+    async runBlueprintGates(cwd) {
+        if (!this.blueprintRunner.isEnabled())
+            return [];
+        const result = await this.blueprintRunner.runGates(DEFAULT_VALIDATION_BLUEPRINT.nodes.filter((n) => n.type === 'deterministic'), cwd);
+        return result;
+    }
+    /** Get the blueprint executor instance. */
+    getBlueprintRunner() {
+        return this.blueprintRunner;
+    }
+    /**
+     * Reset for new execution
+     */
+    reset() {
+        this.taskNodes.clear();
+        this.executionPlan = null;
+        this.completedTasks.clear();
+        this.taskResults.clear();
+        this.handoffs.clear();
+        // Reset VCC gate state
+        this.vccRetryCount = 0;
+        this.lastVCCGateResult = null;
+        this.sessionState = SessionState.RUNNING;
+        this.completedFeatures = [];
+        logger.info('[CoordinationEngine] Reset');
+    }
+    /**
+     * Get checkpoint data for persistence
+     */
+    getCheckpoint() {
+        const taskResultsObj = {};
+        for (const [k, v] of this.taskResults) {
+            taskResultsObj[k] = v;
+        }
+        const handoffsObj = {};
+        for (const [k, v] of this.handoffs) {
+            handoffsObj[k] = v;
+        }
+        return {
+            completedTasks: Array.from(this.completedTasks),
+            taskResults: taskResultsObj,
+            handoffs: handoffsObj,
+            vccState: {
+                retryCount: this.vccRetryCount,
+                lastResult: this.lastVCCGateResult,
+                sessionState: this.sessionState,
+                completedFeatures: this.completedFeatures
+            }
+        };
+    }
+    /**
+     * Restore from checkpoint
+     */
+    restoreFromCheckpoint(checkpoint) {
+        this.completedTasks = new Set(checkpoint.completedTasks);
+        this.taskResults.clear();
+        for (const [k, v] of Object.entries(checkpoint.taskResults)) {
+            this.taskResults.set(k, v);
+        }
+        this.handoffs.clear();
+        for (const [k, v] of Object.entries(checkpoint.handoffs)) {
+            this.handoffs.set(k, v);
+        }
+        // Restore VCC state if available
+        if (checkpoint.vccState) {
+            this.vccRetryCount = checkpoint.vccState.retryCount;
+            this.lastVCCGateResult = checkpoint.vccState.lastResult;
+            this.sessionState = checkpoint.vccState.sessionState;
+            this.completedFeatures = checkpoint.vccState.completedFeatures;
+        }
+        logger.info('[CoordinationEngine] Restored from checkpoint', {
+            completedTasks: this.completedTasks.size,
+            vccRetryCount: this.vccRetryCount,
+            sessionState: this.sessionState
+        });
+    }
+    /**
+     * Check if all tasks are complete and VCC passed
+     */
+    isFullyComplete() {
+        if (!this.isComplete()) {
+            return false;
+        }
+        // If VCC gate is enabled, check that it passed
+        if (this.config.vccGate.enabled && this.lastVCCGateResult) {
+            return this.lastVCCGateResult.passed;
+        }
+        return true;
+    }
+    /**
+     * Enable or update VCC gate configuration
+     */
+    setVCCGateConfig(config) {
+        this.config.vccGate = { ...this.config.vccGate, ...config };
+        logger.info('[CoordinationEngine] VCC gate config updated', { vccGate: this.config.vccGate });
+    }
+    /**
+     * Get current VCC gate configuration
+     */
+    getVCCGateConfig() {
+        return { ...this.config.vccGate };
+    }
+}
+//# sourceMappingURL=coordination-engine.js.map