agentic-orchestrator 0.1.28 → 0.2.1

package/dist/apps/control-plane/supervisor/runtime.js

@@ -1,5 +1,8 @@
 import crypto from 'node:crypto';
 import { stableHash } from '../core/fs.js';
+import { nowIso } from '../core/fs.js';
+import { STATUS, TOOLS } from '../core/constants.js';
+import { asPlanRecord, recoverStalePlanVersionConflict, isPlanVersionConflictError, } from '../core/plan-submit-recovery.js';
 import { createOperationId } from '../mcp/tool-client.js';
 import { withOperationIdIfRequired } from '../application/tools/tool-metadata.js';
 import { PromptBundleLoader } from './prompt-bundle-loader.js';
@@ -10,6 +13,13 @@ import { QaWaveExecutor } from './qa-wave-executor.js';
 import { LeaseHeartbeatService } from './lease-heartbeat-service.js';
 import { RunCoordinator } from './run-coordinator.js';
 import { WorkerDecisionLoop } from './worker-decision-loop.js';
+import { CapacityAwareEnrollmentScheduler, ExecutionEnrollmentService, } from './execution-enrollment-service.js';
+import { OrganizerAgentEnrollmentScheduler } from './organizer-enrollment-scheduler.js';
+import { OrganizerSidecarService } from './organizer-sidecar-service.js';
+import { AopPathLayout } from '../core/path-layout.js';
+import { ArtifactStager } from './artifact-stager.js';
+import Ajv2020Import from 'ajv/dist/2020.js';
+import { readFileSync } from 'node:fs';
 import { createNotifierService } from '../application/services/notifier-service.js';
 import { ReactionsService } from '../application/services/reactions-service.js';
 import { ActivityMonitorService } from '../application/services/activity-monitor-service.js';
@@ -66,9 +76,92 @@ function resolveAdapterName(slot, configuredValue, fallback) {
         }
     }
 }
+function isRunHistoryStatus(value) {
+    return (value === 'active' ||
+        value === 'completed' ||
+        value === 'failed' ||
+        value === 'timeout' ||
+        value === 'interrupted');
+}
+function asRunHistoryEntry(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    if (typeof record.run_id !== 'string' || typeof record.started_at !== 'string') {
+        return null;
+    }
+    const entry = {
+        run_id: record.run_id,
+        started_at: record.started_at,
+    };
+    const endedAt = record.ended_at;
+    if (typeof endedAt === 'string' || endedAt === null) {
+        entry.ended_at = endedAt;
+    }
+    if (isRunHistoryStatus(record.status)) {
+        entry.status = record.status;
+    }
+    return entry;
+}
+function normalizeRunHistory(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map(asRunHistoryEntry).filter((entry) => entry !== null);
+}
+function sortRunHistory(entries) {
+    return [...entries].sort((left, right) => {
+        const leftTs = Date.parse(left.started_at);
+        const rightTs = Date.parse(right.started_at);
+        const normalizedLeft = Number.isNaN(leftTs) ? 0 : leftTs;
+        const normalizedRight = Number.isNaN(rightTs) ? 0 : rightTs;
+        return normalizedRight - normalizedLeft;
+    });
+}
+function resolveRunStatus(frontMatter) {
+    const status = typeof frontMatter.status === 'string' ? frontMatter.status : '';
+    const reason = typeof frontMatter.status_reason === 'string' ? frontMatter.status_reason : '';
+    if (reason.toLowerCase().includes('timeout')) {
+        return 'timeout';
+    }
+    if (status === STATUS.MERGED || status === STATUS.READY_TO_MERGE) {
+        return 'completed';
+    }
+    if (status === STATUS.FAILED) {
+        return 'failed';
+    }
+    if (status === STATUS.BLOCKED || status === STATUS.PAUSED_BUDGET) {
+        return 'interrupted';
+    }
+    return 'interrupted';
+}
+function isVersionConflictError(error) {
+    return isPlanVersionConflictError(error);
+}
+class RunHistorySessionOrchestrator extends SessionOrchestrator {
+    runHistoryUpdater;
+    constructor(dependencies, runHistoryUpdater) {
+        super(dependencies);
+        this.runHistoryUpdater = runHistoryUpdater;
+    }
+    async initializeFeatureCluster(featureId) {
+        await super.initializeFeatureCluster(featureId);
+        await this.runHistoryUpdater.markRunStarted(featureId);
+    }
+    async closeFeatureCluster(featureId) {
+        await super.closeFeatureCluster(featureId);
+        await this.runHistoryUpdater.markRunEnded(featureId);
+    }
+}
 /**
  * @fileoverview Multi-agent supervisor runtime for orchestrating feature development.
  */
+/**
+ * Multi-agent supervisor runtime that coordinates planning, build, and QA waves
+ * across concurrent feature clusters. Implements tool calling, prompt loading,
+ * plan generation, and session lifecycle management.
+ */
 export class SupervisorRuntime {
     kernel;
     provider;
@@ -86,6 +179,8 @@ export class SupervisorRuntime {
     workerDecisionLoop;
     leaseHeartbeatService;
     runCoordinator;
+    executionEnrollmentService;
+    organizerSidecar;
     cliExecutionMode;
     interactiveConfig;
     worktreeWatchdogService;
@@ -122,10 +217,12 @@ export class SupervisorRuntime {
         const notificationChannel = resolveAdapterName(NOTIFICATION_CHANNEL_SLOT, adaptersConfig['notification-channel'], null);
         const activityDetector = resolveAdapterName(ACTIVITY_DETECTOR_SLOT, adaptersConfig['activity-detector'], 'claude-jsonl');
         const scmProvider = resolveAdapterName(SCM_PROVIDER_SLOT, adaptersConfig['scm-provider'], 'github');
+        const roleSelections = options.role_selections ?? null;
         this.state = {
             runId,
             ownerInstanceId,
             orchestratorSessionId: null,
+            reconcilerSessionId: null,
             sessionsByFeature: new Map(),
             queue: [],
             runMetadata: {
@@ -133,6 +230,7 @@ export class SupervisorRuntime {
                 owner_instance_id: ownerInstanceId,
                 takeover_stale_run: this.takeoverStaleRun,
                 resolved_provider: provider.selection,
+                resolved_role_providers: roleSelections,
                 adapters: {
                     notification_channel: notificationChannel,
                     activity_detector: activityDetector,
@@ -141,14 +239,22 @@ export class SupervisorRuntime {
             },
         };
         this.promptBundleLoader = new PromptBundleLoader(this.kernel);
-        this.sessionOrchestrator = new SessionOrchestrator({
+        const runHistoryUpdater = {
+            markRunStarted: async (featureId) => {
+                await this.markRunHistoryStarted(featureId);
+            },
+            markRunEnded: async (featureId) => {
+                await this.markRunHistoryEnded(featureId);
+            },
+        };
+        this.sessionOrchestrator = new RunHistorySessionOrchestrator({
             kernel: this.kernel,
             runtimeStateReader: this.kernel,
             provider: this.provider,
             promptProvider: this,
             toolCaller: this,
             state: this.state,
-        });
+        }, runHistoryUpdater);
         const notifier = createNotifierService(this.kernel.getPolicySnapshot(), notificationChannel);
         const reactionsPolicy = this.resolveReactionsPolicy();
         const reactionsService = new ReactionsService({
@@ -204,9 +310,16 @@ export class SupervisorRuntime {
             resolveWorktreePath: (featureId) => this.kernel.worktreePath(featureId),
             resolveRoleSessionId: (role, featureId) => this.resolveRoleSessionIdByFeature(role, featureId),
         });
+        let coordinatorRef = null;
+        const safeCheckpointHook = async () => {
+            if (coordinatorRef !== null) {
+                await coordinatorRef.handleSafeCheckpoint();
+            }
+        };
         this.planningWaveExecutor = new PlanningWaveExecutor({
             toolCaller: this,
             planGenerator: this,
+            plannerSessionSync: this.sessionOrchestrator,
             workerDecisionRunner: this.workerDecisionLoop,
             providerMode: this.provider.mode,
             outputLoopDetector,
@@ -221,7 +334,10 @@ export class SupervisorRuntime {
             runId: () => this.state.runId,
             providerName: this.provider.selection.provider,
             modelName: this.provider.selection.model,
+            safeCheckpointHook,
+            getPolicySnapshot: () => this.kernel.getPolicySnapshot(),
         });
+        const artifactStager = new ArtifactStager(this.kernel.getRepoRoot());
         this.buildWaveExecutor = new BuildWaveExecutor({
             toolCaller: this,
             workerDecisionRunner: this.workerDecisionLoop,
@@ -241,6 +357,8 @@ export class SupervisorRuntime {
             runId: () => this.state.runId,
             providerName: this.provider.selection.provider,
             modelName: this.provider.selection.model,
+            safeCheckpointHook,
+            artifactStager,
         });
         this.qaWaveExecutor = new QaWaveExecutor({
             kernel: this.kernel,
@@ -266,11 +384,41 @@ export class SupervisorRuntime {
             runId: () => this.state.runId,
             providerName: this.provider.selection.provider,
             modelName: this.provider.selection.model,
+            safeCheckpointHook,
         });
         this.leaseHeartbeatService = new LeaseHeartbeatService({
             kernel: this.kernel,
             state: this.state,
         });
+        const capacityScheduler = new CapacityAwareEnrollmentScheduler();
+        const organizerEnabled = this.kernel.getAgentsConfig().roles?.organizer != null;
+        const pathLayout = new AopPathLayout(this.kernel.getRepoRoot());
+        const scheduler = organizerEnabled
+            ? new OrganizerAgentEnrollmentScheduler({
+                orderingArtifactPath: pathLayout.organizerOrderingPath(this.state.ownerInstanceId),
+                fallback: capacityScheduler,
+            })
+            : capacityScheduler;
+        this.executionEnrollmentService = new ExecutionEnrollmentService({
+            kernel: this.kernel,
+            state: this.state,
+            scheduler,
+            maxActiveFeatures: this.maxActiveFeatures,
+        });
+        if (organizerEnabled) {
+            const sidecarValidator = this.compileOrganizerSchema(pathLayout.organizerOrderingSchemaPath());
+            this.organizerSidecar = new OrganizerSidecarService({
+                provider: this.provider,
+                organizerSessionId: () => this.state.organizerSessionId ?? null,
+                kernel: this.kernel,
+                state: this.state,
+                artifactPath: pathLayout.organizerOrderingPath(this.state.ownerInstanceId),
+                schemaValidator: sidecarValidator,
+            });
+        }
+        else {
+            this.organizerSidecar = null;
+        }
         this.runCoordinator = new RunCoordinator({
             kernel: this.kernel,
             provider: this.provider,
@@ -290,53 +438,83 @@ export class SupervisorRuntime {
             notifier,
             prMonitor,
             issueTracker,
+            executionEnrollmentService: this.executionEnrollmentService,
         });
+        coordinatorRef = this.runCoordinator;
     }
+    /** Unique identifier for the current supervisor run. */
     get runId() {
         return this.state.runId;
     }
     set runId(value) {
         this.state.runId = value;
     }
+    /** Unique identifier for the supervisor process instance that owns this run. */
     get ownerInstanceId() {
         return this.state.ownerInstanceId;
     }
     set ownerInstanceId(value) {
         this.state.ownerInstanceId = value;
     }
+    /** Session ID for the global orchestrator agent. */
     get orchestratorSessionId() {
         return this.state.orchestratorSessionId;
     }
     set orchestratorSessionId(value) {
         this.state.orchestratorSessionId = value;
     }
+    /** Session ID for the post-QA reconciliation agent. */
+    get reconcilerSessionId() {
+        return this.state.reconcilerSessionId;
+    }
+    set reconcilerSessionId(value) {
+        this.state.reconcilerSessionId = value;
+    }
+    /** Map of feature IDs to their per-role worker session identifiers. */
     get sessionsByFeature() {
         return this.state.sessionsByFeature;
     }
     set sessionsByFeature(value) {
         this.state.sessionsByFeature = value;
     }
+    /** Pending feature inputs waiting to be enrolled into active execution. */
     get queue() {
         return this.state.queue;
     }
     set queue(value) {
         this.state.queue = value;
     }
+    /** Metadata snapshot for the current run (timestamps, provider info, adapter config). */
     get runMetadata() {
         return this.state.runMetadata;
     }
     set runMetadata(value) {
         this.state.runMetadata = value;
     }
+    /** Cached role prompt bundle, or null if not yet loaded. */
     get promptsCache() {
         return this.promptBundleLoader.peekCache();
     }
     set promptsCache(value) {
         this.promptBundleLoader.setCache(value);
     }
+    /**
+     * Starts the supervisor run, enrolling features and delegating to the run coordinator.
+     * @param features - Feature inputs to process in this run.
+     * @returns Run summary with per-feature outcomes.
+     */
     async start(features) {
-        return await this.runCoordinator.start(features);
+        await this.executionEnrollmentService.start();
+        this.organizerSidecar?.start();
+        try {
+            return await this.runCoordinator.start(features);
+        }
+        finally {
+            await this.organizerSidecar?.stop();
+            await this.executionEnrollmentService.stop();
+        }
     }
+    /** Returns a stable hash of the current provider configuration reference. */
     providerConfigRefHash() {
         return stableHash(this.provider.selection.provider_config_ref ?? 'none');
     }
@@ -386,42 +564,182 @@ export class SupervisorRuntime {
         }
         return 300_000;
     }
+    /** Creates the global orchestrator session if one does not already exist. */
     async ensureGlobalOrchestratorSession() {
         await this.sessionOrchestrator.ensureGlobalOrchestratorSession();
     }
+    /**
+     * Removes worker sessions that are no longer associated with any active feature.
+     * @param activeFeatureIds - Feature IDs that should retain their sessions.
+     */
     async cleanupOrphanWorkerSessions(activeFeatureIds) {
         await this.sessionOrchestrator.cleanupOrphanWorkerSessions(activeFeatureIds);
     }
+    /**
+     * Initializes a feature cluster by creating per-role worker sessions and recording run history.
+     * @param featureId - The feature to initialize.
+     */
     async initializeFeatureCluster(featureId) {
         await this.sessionOrchestrator.initializeFeatureCluster(featureId);
     }
+    /** Reconciles queued features by enrolling them into active execution slots. */
     async reconcileQueuedFeatures() {
         await this.sessionOrchestrator.reconcileQueuedFeatures(this.state.queue);
     }
+    async markRunHistoryStarted(featureId) {
+        try {
+            const state = await this.kernel.readState(featureId);
+            const frontMatter = state.frontMatter;
+            const runHistory = normalizeRunHistory(frontMatter.run_history);
+            const now = nowIso();
+            const currentRunId = this.state.runId;
+            const existing = runHistory.find((entry) => entry.run_id === currentRunId) ?? null;
+            const latest = runHistory[0] ?? null;
+            const latestIsActive = latest && latest.run_id !== currentRunId
+                ? latest.status === 'active' || latest.ended_at === null
+                : false;
+            const nextHistory = runHistory.filter((entry) => entry.run_id !== currentRunId);
+            if (latest && latest.run_id !== currentRunId && latestIsActive) {
+                nextHistory[0] = {
+                    ...latest,
+                    status: 'interrupted',
+                    ended_at: now,
+                };
+            }
+            nextHistory.unshift({
+                run_id: currentRunId,
+                started_at: existing?.started_at ?? now,
+                ended_at: null,
+                status: 'active',
+            });
+            const expectedVersion = typeof frontMatter.version === 'number' && Number.isFinite(frontMatter.version)
+                ? frontMatter.version
+                : null;
+            await this.kernel
+                .updateState(featureId, expectedVersion, (fm, body) => Promise.resolve({
+                frontMatter: {
+                    ...fm,
+                    run_history: sortRunHistory(nextHistory),
+                },
+                body,
+            }))
+                .catch((error) => {
+                if (!isVersionConflictError(error)) {
+                    throw error;
+                }
+            });
+        }
+        catch {
+            // Best-effort update: do not interrupt supervisor flow.
+        }
+    }
+    async markRunHistoryEnded(featureId) {
+        try {
+            const state = await this.kernel.readState(featureId);
+            const frontMatter = state.frontMatter;
+            const runHistory = normalizeRunHistory(frontMatter.run_history);
+            const now = nowIso();
+            const currentRunId = this.state.runId;
+            const status = resolveRunStatus(frontMatter);
+            let found = false;
+            const nextHistory = runHistory.map((entry) => {
+                if (entry.run_id !== currentRunId) {
+                    return entry;
+                }
+                found = true;
+                return {
+                    ...entry,
+                    ended_at: now,
+                    status,
+                };
+            });
+            if (!found) {
+                nextHistory.unshift({
+                    run_id: currentRunId,
+                    started_at: typeof frontMatter.phase_entered_at === 'string' ? frontMatter.phase_entered_at : now,
+                    ended_at: now,
+                    status,
+                });
+            }
+            const expectedVersion = typeof frontMatter.version === 'number' && Number.isFinite(frontMatter.version)
+                ? frontMatter.version
+                : null;
+            await this.kernel
+                .updateState(featureId, expectedVersion, (fm, body) => Promise.resolve({
+                frontMatter: {
+                    ...fm,
+                    run_history: sortRunHistory(nextHistory),
+                },
+                body,
+            }))
+                .catch((error) => {
+                if (!isVersionConflictError(error)) {
+                    throw error;
+                }
+            });
+        }
+        catch {
+            // Best-effort update: do not interrupt supervisor flow.
+        }
+    }
+    /**
+     * Ensures session state is consistent with the set of active features,
+     * closing clusters for features that are no longer active.
+     * @param activeFeatureIds - Currently active feature IDs.
+     */
     async enforceActiveFeatureInvariant(activeFeatureIds) {
         await this.sessionOrchestrator.enforceActiveFeatureInvariant(activeFeatureIds);
     }
+    /**
+     * Applies a partial update to a feature cluster's worker session mappings.
+     * @param featureId - The feature whose cluster to patch.
+     * @param clusterPatch - Key-value pairs to merge into the cluster record.
+     */
     async patchFeatureCluster(featureId, clusterPatch) {
         await this.sessionOrchestrator.patchFeatureCluster(featureId, clusterPatch);
     }
+    /** Loads and caches the role-specific system prompts for planner, builder, and QA agents. */
     async loadRolePrompts() {
         return await this.promptBundleLoader.loadRolePrompts();
     }
+    /**
+     * Executes the planning wave for the given features, generating or refining plans.
+     * @param featureIds - Features to include in this planning wave.
+     */
     async runPlanningWave(featureIds) {
         await this.planningWaveExecutor.run(featureIds);
     }
+    /**
+     * Runs a post-QA reconciliation wave to address QA findings via plan adjustments.
+     * @param featureIds - Features requiring reconciliation.
+     * @param iteration - Current reconciliation iteration (used for convergence tracking).
+     */
     async runPostQaReconciliationWave(featureIds, iteration) {
         await this.planningWaveExecutor.runPostQaReconciliation(featureIds, iteration);
     }
+    /**
+     * Executes the build wave, running builder agents with gate validation.
+     * @param featureIds - Features to build in this wave.
+     */
     async runBuildWave(featureIds) {
         await this.buildWaveExecutor.run(featureIds, this.maxParallelGateRuns);
     }
+    /**
+     * Executes the QA wave, running QA agents with gate validation.
+     * @param featureIds - Features to validate in this wave.
+     */
     async runQaWave(featureIds) {
         await this.qaWaveExecutor.run(featureIds, this.maxParallelGateRuns);
     }
+    /** Renews lease heartbeats for all active feature sessions to prevent stale-run takeover. */
     async renewLeaseHeartbeats() {
         await this.leaseHeartbeatService.renew();
     }
+    /**
+     * Generates a scaffold initial plan for a feature before the planner agent refines it.
+     * @param featureId - The feature to generate a plan for.
+     * @returns A plan record with default allowed areas, empty file lists, and placeholder criteria.
+     */
     async generateInitialPlan(featureId) {
         const baseRef = await this.kernel
             .repoDiff(featureId, ['--stat'])
@@ -447,10 +765,26 @@ export class SupervisorRuntime {
             acceptance_criteria: ['Feature has deterministic plan and passes configured gate profile.'],
         };
     }
+    compileOrganizerSchema(schemaPath) {
+        const Ajv2020Ctor = Ajv2020Import;
+        const ajv = new Ajv2020Ctor({ allErrors: true, strict: false });
+        ajv.addFormat('date-time', {
+            type: 'string',
+            validate: (v) => !Number.isNaN(Date.parse(v)),
+        });
+        const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+        return ajv.compile(schema);
+    }
     resolveRoleSessionId(role, payload) {
         if (role === 'orchestrator') {
             return this.state.orchestratorSessionId;
         }
+        if (role === 'reconciler') {
+            return this.state.reconcilerSessionId;
+        }
+        if (role === 'organizer') {
+            return this.state.organizerSessionId ?? null;
+        }
         const featureId = typeof payload.feature_id === 'string' ? payload.feature_id : null;
         if (!featureId) {
             return null;
@@ -490,6 +824,11 @@ export class SupervisorRuntime {
             violationSeverity: asSeverity(interactive['violation_severity'], 'warning'),
         };
     }
+    /**
+     * Resolves the execution mode for a feature using the precedence chain:
+     * CLI override > feature state > agents.yaml runtime config > deterministic default.
+     * @param featureId - The feature whose execution mode to resolve.
+     */
     async resolveExecutionMode(featureId) {
         if (this.cliExecutionMode) {
             return this.cliExecutionMode;
@@ -510,6 +849,14 @@ export class SupervisorRuntime {
         }
         return 'deterministic';
     }
+    /**
+     * Invokes an MCP tool on behalf of a supervisor agent role, attaching session
+     * context and operation IDs. Automatically recovers plan version conflicts.
+     * @param role - The agent role making the tool call (e.g. planner, builder, qa).
+     * @param toolName - Name of the MCP tool to invoke.
+     * @param args - Tool-specific input arguments.
+     * @returns The tool response data on success.
+     */
     async callTool(role, toolName, args) {
         const payload = withOperationIdIfRequired(toolName, args, createOperationId);
         const roleSessionId = this.resolveRoleSessionId(role, payload);
@@ -520,6 +867,10 @@ export class SupervisorRuntime {
             actor_id: `supervisor:${role}`,
         });
         if (response.ok === false) {
+            const recovered = await this.tryRecoverPlanVersionConflict(role, toolName, payload, response.error);
+            if (recovered) {
+                return recovered;
+            }
             const normalized = response.error;
             const error = new Error(normalized.message);
             error.code = normalized.code;
@@ -528,5 +879,44 @@ export class SupervisorRuntime {
         }
         return { ok: true, data: response.data };
     }
+    async tryRecoverPlanVersionConflict(role, toolName, args, error) {
+        if (toolName !== TOOLS.PLAN_SUBMIT && toolName !== TOOLS.PLAN_UPDATE) {
+            return null;
+        }
+        const featureId = typeof args.feature_id === 'string' ? args.feature_id : null;
+        const submittedPlan = asPlanRecord(args.plan_json);
+        if (!featureId || Object.keys(submittedPlan).length === 0) {
+            return null;
+        }
+        const recovered = await recoverStalePlanVersionConflict({
+            error,
+            featureId,
+            submittedPlan,
+            readAcceptedPlan: async (nextFeatureId) => {
+                const currentPlanResponse = await this.callTool(role, TOOLS.PLAN_GET, {
+                    feature_id: nextFeatureId,
+                });
+                return currentPlanResponse.data.plan;
+            },
+            submitPlanUpdate: async (nextFeatureId, expectedPlanVersion, plan) => {
+                return await this.callTool(role, TOOLS.PLAN_UPDATE, {
+                    feature_id: nextFeatureId,
+                    expected_plan_version: expectedPlanVersion,
+                    plan_json: plan,
+                });
+            },
+            buildEquivalentSuccess: (nextFeatureId, currentPlanVersion) => ({
+                ok: true,
+                data: {
+                    feature_id: nextFeatureId,
+                    accepted: true,
+                    plan_version: currentPlanVersion,
+                    recovered: true,
+                    recovery_strategy: 'reuse_existing_plan_version',
+                },
+            }),
+        });
+        return recovered;
+    }
 }
 //# sourceMappingURL=runtime.js.map