agentic-orchestrator 0.1.0

package/apps/control-plane/src/supervisor/runtime.ts

@@ -0,0 +1,347 @@
+import crypto from 'node:crypto';
+import { stableHash } from '../core/fs.js';
+import type { WorkerProvider } from '../providers/providers.js';
+import { createOperationId, type ToolClient } from '../mcp/tool-client.js';
+import { withOperationIdIfRequired } from '../application/tools/tool-metadata.js';
+import { PromptBundleLoader } from './prompt-bundle-loader.js';
+import { SessionOrchestrator } from './session-orchestrator.js';
+import { PlanningWaveExecutor } from './planning-wave-executor.js';
+import { BuildWaveExecutor } from './build-wave-executor.js';
+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 type {
+  AgentPromptProvider,
+  AppError,
+  FeatureClusterPatcher,
+  FeatureInput,
+  InitialPlanGenerator,
+  PromptBundle,
+  RuntimeRole,
+  SupervisorKernelPort,
+  SupervisorOptions,
+  SupervisorRuntimeState,
+  SupervisorToolCaller,
+  WorkerSessions
+} from './types.js';
+
+export class SupervisorRuntime
+  implements SupervisorToolCaller, AgentPromptProvider, InitialPlanGenerator, FeatureClusterPatcher
+{
+  kernel: SupervisorKernelPort;
+  provider: WorkerProvider;
+  toolClient: ToolClient;
+  maxActiveFeatures: number;
+  maxParallelGateRuns: number;
+  maxIterationsPerPhase: number;
+  takeoverStaleRun: boolean;
+
+  private readonly state: SupervisorRuntimeState;
+  private readonly promptBundleLoader: PromptBundleLoader;
+  private readonly sessionOrchestrator: SessionOrchestrator;
+  private readonly planningWaveExecutor: PlanningWaveExecutor;
+  private readonly buildWaveExecutor: BuildWaveExecutor;
+  private readonly qaWaveExecutor: QaWaveExecutor;
+  private readonly workerDecisionLoop: WorkerDecisionLoop;
+  private readonly leaseHeartbeatService: LeaseHeartbeatService;
+  private readonly runCoordinator: RunCoordinator;
+  private static readonly DEFAULT_MAX_ITERATIONS_PER_PHASE = 6;
+
+  constructor(
+    kernel: SupervisorKernelPort,
+    provider: WorkerProvider,
+    toolClient: ToolClient,
+    options: SupervisorOptions = {}
+  ) {
+    this.kernel = kernel;
+    this.provider = provider;
+    this.toolClient = toolClient;
+    this.maxActiveFeatures = options.max_active_features ?? 5;
+    this.maxParallelGateRuns = options.max_parallel_gate_runs ?? 2;
+    this.maxIterationsPerPhase = this.resolveMaxIterationsPerPhase(options.max_iterations_per_phase);
+    this.takeoverStaleRun = Boolean(options.takeover_stale_run);
+    const runId = options.run_id ?? `run:${Date.now()}`;
+    const ownerInstanceId = options.owner_instance_id ?? `supervisor:${process.pid}:${crypto.randomUUID()}`;
+
+    this.state = {
+      runId,
+      ownerInstanceId,
+      orchestratorSessionId: null,
+      sessionsByFeature: new Map(),
+      queue: [],
+      runMetadata: {
+        started_at: new Date().toISOString(),
+        owner_instance_id: ownerInstanceId,
+        takeover_stale_run: this.takeoverStaleRun,
+        resolved_provider: provider.selection
+      }
+    };
+
+    this.promptBundleLoader = new PromptBundleLoader(this.kernel);
+    this.sessionOrchestrator = new SessionOrchestrator({
+      kernel: this.kernel,
+      runtimeStateReader: this.kernel,
+      provider: this.provider,
+      promptProvider: this,
+      toolCaller: this,
+      state: this.state
+    });
+
+    this.workerDecisionLoop = new WorkerDecisionLoop({
+      provider: this.provider,
+      toolCaller: this
+    });
+
+    this.planningWaveExecutor = new PlanningWaveExecutor({
+      toolCaller: this,
+      planGenerator: this,
+      workerDecisionRunner: this.workerDecisionLoop
+    });
+
+    this.buildWaveExecutor = new BuildWaveExecutor({
+      toolCaller: this,
+      workerDecisionRunner: this.workerDecisionLoop
+    });
+
+    this.qaWaveExecutor = new QaWaveExecutor({
+      kernel: this.kernel,
+      provider: this.provider,
+      toolCaller: this,
+      promptProvider: this,
+      featureClusterPatcher: this,
+      state: this.state,
+      workerDecisionRunner: this.workerDecisionLoop
+    });
+
+    this.leaseHeartbeatService = new LeaseHeartbeatService({
+      kernel: this.kernel,
+      state: this.state
+    });
+
+    this.runCoordinator = new RunCoordinator({
+      kernel: this.kernel,
+      provider: this.provider,
+      toolCaller: this,
+      state: this.state,
+      sessionOrchestrator: this.sessionOrchestrator,
+      planningWaveExecutor: this.planningWaveExecutor,
+      buildWaveExecutor: this.buildWaveExecutor,
+      qaWaveExecutor: this.qaWaveExecutor,
+      leaseHeartbeatService: this.leaseHeartbeatService,
+      maxActiveFeatures: this.maxActiveFeatures,
+      maxParallelGateRuns: this.maxParallelGateRuns,
+      maxIterationsPerPhase: this.maxIterationsPerPhase,
+      takeoverStaleRun: this.takeoverStaleRun,
+      providerConfigRefHash: () => this.providerConfigRefHash(),
+      workerDecisionRunner: this.workerDecisionLoop
+    });
+  }
+
+  get runId(): string {
+    return this.state.runId;
+  }
+
+  set runId(value: string) {
+    this.state.runId = value;
+  }
+
+  get ownerInstanceId(): string {
+    return this.state.ownerInstanceId;
+  }
+
+  set ownerInstanceId(value: string) {
+    this.state.ownerInstanceId = value;
+  }
+
+  get orchestratorSessionId(): string | null {
+    return this.state.orchestratorSessionId;
+  }
+
+  set orchestratorSessionId(value: string | null) {
+    this.state.orchestratorSessionId = value;
+  }
+
+  get sessionsByFeature(): Map<string, WorkerSessions> {
+    return this.state.sessionsByFeature;
+  }
+
+  set sessionsByFeature(value: Map<string, WorkerSessions>) {
+    this.state.sessionsByFeature = value;
+  }
+
+  get queue(): FeatureInput[] {
+    return this.state.queue;
+  }
+
+  set queue(value: FeatureInput[]) {
+    this.state.queue = value;
+  }
+
+  get runMetadata(): Record<string, unknown> {
+    return this.state.runMetadata;
+  }
+
+  set runMetadata(value: Record<string, unknown>) {
+    this.state.runMetadata = value;
+  }
+
+  get promptsCache(): PromptBundle | null {
+    return this.promptBundleLoader.peekCache();
+  }
+
+  set promptsCache(value: PromptBundle | null) {
+    this.promptBundleLoader.setCache(value);
+  }
+
+  async start(features: FeatureInput[]): Promise<Record<string, unknown>> {
+    return await this.runCoordinator.start(features);
+  }
+
+  providerConfigRefHash(): string {
+    return stableHash(this.provider.selection.provider_config_ref ?? 'none');
+  }
+
+  private resolveMaxIterationsPerPhase(cliOverride: number | undefined): number {
+    if (typeof cliOverride === 'number' && Number.isFinite(cliOverride) && cliOverride >= 0) {
+      return Math.floor(cliOverride);
+    }
+
+    const policy = this.kernel.getPolicySnapshot();
+    const supervisor =
+      policy.supervisor && typeof policy.supervisor === 'object'
+        ? (policy.supervisor as Record<string, unknown>)
+        : null;
+    const configured = supervisor?.max_iterations_per_phase;
+    if (typeof configured === 'number' && Number.isFinite(configured) && configured >= 0) {
+      return Math.floor(configured);
+    }
+
+    return SupervisorRuntime.DEFAULT_MAX_ITERATIONS_PER_PHASE;
+  }
+
+  async ensureGlobalOrchestratorSession(): Promise<void> {
+    await this.sessionOrchestrator.ensureGlobalOrchestratorSession();
+  }
+
+  async cleanupOrphanWorkerSessions(activeFeatureIds: string[]): Promise<void> {
+    await this.sessionOrchestrator.cleanupOrphanWorkerSessions(activeFeatureIds);
+  }
+
+  async initializeFeatureCluster(featureId: string): Promise<void> {
+    await this.sessionOrchestrator.initializeFeatureCluster(featureId);
+  }
+
+  async reconcileQueuedFeatures(): Promise<void> {
+    await this.sessionOrchestrator.reconcileQueuedFeatures(this.state.queue);
+  }
+
+  async enforceActiveFeatureInvariant(activeFeatureIds: string[]): Promise<void> {
+    await this.sessionOrchestrator.enforceActiveFeatureInvariant(activeFeatureIds);
+  }
+
+  async patchFeatureCluster(featureId: string, clusterPatch: Record<string, string>): Promise<void> {
+    await this.sessionOrchestrator.patchFeatureCluster(featureId, clusterPatch);
+  }
+
+  async loadRolePrompts(): Promise<PromptBundle> {
+    return await this.promptBundleLoader.loadRolePrompts();
+  }
+
+  async runPlanningWave(featureIds: string[]): Promise<void> {
+    await this.planningWaveExecutor.run(featureIds);
+  }
+
+  async runPostQaReconciliationWave(featureIds: string[], iteration: number): Promise<void> {
+    await this.planningWaveExecutor.runPostQaReconciliation(featureIds, iteration);
+  }
+
+  async runBuildWave(featureIds: string[]): Promise<void> {
+    await this.buildWaveExecutor.run(featureIds, this.maxParallelGateRuns);
+  }
+
+  async runQaWave(featureIds: string[]): Promise<void> {
+    await this.qaWaveExecutor.run(featureIds, this.maxParallelGateRuns);
+  }
+
+  async renewLeaseHeartbeats(): Promise<void> {
+    await this.leaseHeartbeatService.renew();
+  }
+
+  async generateInitialPlan(featureId: string): Promise<Record<string, unknown>> {
+    const baseRef = await this.kernel.repoDiff(featureId, ['--stat']).then(() => 'HEAD').catch(() => 'HEAD');
+    return {
+      feature_id: featureId,
+      plan_version: 1,
+      summary: `Initial implementation plan for ${featureId}`,
+      allowed_areas: ['apps/control-plane', `.aop/features/${featureId}`],
+      forbidden_areas: [],
+      base_ref: baseRef,
+      files: {
+        create: [],
+        modify: [],
+        delete: []
+      },
+      contracts: {
+        openapi: 'none',
+        events: 'none',
+        db: 'none'
+      },
+      acceptance_criteria: ['Feature has deterministic plan and passes configured gate profile.'],
+      gate_profile: 'default'
+    };
+  }
+
+  private resolveRoleSessionId(role: RuntimeRole, payload: Record<string, unknown>): string | null {
+    if (role === 'orchestrator') {
+      return this.state.orchestratorSessionId;
+    }
+
+    const featureId = typeof payload.feature_id === 'string' ? payload.feature_id : null;
+    if (!featureId) {
+      return null;
+    }
+
+    const session = this.state.sessionsByFeature.get(featureId);
+    if (!session) {
+      return null;
+    }
+
+    switch (role) {
+      case 'planner':
+        return session.planner;
+      case 'builder':
+        return session.builder;
+      case 'qa':
+        return session.qa;
+      default:
+        return null;
+    }
+  }
+
+  async callTool<TData = Record<string, unknown>>(
+    role: RuntimeRole,
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<{ ok: true; data: TData }> {
+    const payload = withOperationIdIfRequired(toolName, args, createOperationId);
+    const roleSessionId = this.resolveRoleSessionId(role, payload);
+
+    const response = await this.toolClient.call(toolName, payload, {
+      run_id: this.state.runId,
+      session_id: roleSessionId ?? `bootstrap:${role}`,
+      actor_type: role,
+      actor_id: `supervisor:${role}`
+    });
+
+    if (response.ok === false) {
+      const normalized = (response).error;
+      const error = new Error(normalized.message) as AppError;
+      error.code = normalized.code;
+      error.details = normalized.details;
+      throw error;
+    }
+
+    return { ok: true, data: response.data as TData };
+  }
+}

package/apps/control-plane/src/supervisor/session-orchestrator.ts

@@ -0,0 +1,268 @@
+import { TOOLS } from '../core/constants.js';
+import type { WorkerProvider } from '../providers/providers.js';
+import type {
+  AgentPromptProvider,
+  FeatureInput,
+  FeatureStatePayload,
+  RuntimeStateReader,
+  SupervisorKernelPort,
+  SupervisorRuntimeState,
+  SupervisorToolCaller
+} from './types.js';
+import { UNASSIGNED_SESSION_ID } from './types.js';
+
+interface SessionOrchestratorDependencies {
+  kernel: SupervisorKernelPort;
+  runtimeStateReader: RuntimeStateReader;
+  provider: WorkerProvider;
+  promptProvider: AgentPromptProvider;
+  toolCaller: SupervisorToolCaller;
+  state: SupervisorRuntimeState;
+}
+
+export class SessionOrchestrator {
+  private readonly kernel: SupervisorKernelPort;
+  private readonly runtimeStateReader: RuntimeStateReader;
+  private readonly provider: WorkerProvider;
+  private readonly promptProvider: AgentPromptProvider;
+  private readonly toolCaller: SupervisorToolCaller;
+  private readonly state: SupervisorRuntimeState;
+
+  constructor(dependencies: SessionOrchestratorDependencies) {
+    this.kernel = dependencies.kernel;
+    this.runtimeStateReader = dependencies.runtimeStateReader;
+    this.provider = dependencies.provider;
+    this.promptProvider = dependencies.promptProvider;
+    this.toolCaller = dependencies.toolCaller;
+    this.state = dependencies.state;
+  }
+
+  async ensureGlobalOrchestratorSession(): Promise<void> {
+    const runtimeSessions = await this.runtimeStateReader.getRuntimeSessions();
+    const candidate = runtimeSessions.orchestrator_session_id;
+    const canReuse =
+      runtimeSessions.run_id === this.state.runId &&
+      runtimeSessions.owner_instance_id === this.state.ownerInstanceId &&
+      typeof candidate === 'string' &&
+      candidate.length > 0 &&
+      candidate !== 'unknown';
+
+    let reattachSucceeded = false;
+    if (canReuse) {
+      reattachSucceeded = await this.attemptReattach(candidate);
+    }
+
+    if (reattachSucceeded) {
+      this.state.orchestratorSessionId = candidate;
+      this.state.runMetadata.orchestrator_reattached = true;
+      return;
+    }
+
+    const orchestratorSession = await this.provider.createSession('orchestrator', 'global', null);
+    this.state.orchestratorSessionId = orchestratorSession.session_id;
+    this.state.runMetadata.orchestrator_reattached = false;
+    this.state.runMetadata.orchestrator_epoch_incremented = canReuse;
+
+    await this.kernel.updateOrchestratorSession({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      orchestrator_session_id: orchestratorSession.session_id,
+      increment_epoch: canReuse
+    });
+
+    if (canReuse && candidate) {
+      await this.markOrphanSession(candidate, Number(runtimeSessions.orchestrator_epoch ?? 0));
+    }
+  }
+
+  private async attemptReattach(sessionId: string): Promise<boolean> {
+    const policy = this.kernel.getPolicySnapshot();
+    const recovery =
+      policy.recovery && typeof policy.recovery === 'object'
+        ? (policy.recovery as Record<string, unknown>)
+        : {};
+    const timeoutMs =
+      typeof recovery.orchestrator_session_reattach_timeout_ms === 'number'
+        ? recovery.orchestrator_session_reattach_timeout_ms
+        : 5000;
+
+    try {
+      const reattachResult = await Promise.race([
+        this.provider.reattachSession(sessionId),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error('Reattach timeout')), timeoutMs)
+        )
+      ]);
+      return Boolean(reattachResult?.session_id === sessionId);
+    } catch (_error) {
+      return false;
+    }
+  }
+
+  private async markOrphanSession(sessionId: string, previousEpoch: number): Promise<void> {
+    const policy = this.kernel.getPolicySnapshot();
+    const recovery =
+      policy.recovery && typeof policy.recovery === 'object'
+        ? (policy.recovery as Record<string, unknown>)
+        : {};
+    if (recovery.orphan_session_cleanup_enabled !== true) {
+      return;
+    }
+
+    const orphanEvent = {
+      timestamp: new Date().toISOString(),
+      level: 'info',
+      message: `Marked orphan orchestrator session ${sessionId} from epoch ${previousEpoch} as replaced`,
+      metadata: {
+        orphan_session_id: sessionId,
+        previous_epoch: previousEpoch,
+        new_epoch: previousEpoch + 1
+      }
+    };
+
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+      feature_id: 'global',
+      note: JSON.stringify(orphanEvent)
+    }).catch(() => ({ ok: true, data: {} }));
+  }
+
+  async cleanupOrphanWorkerSessions(scopedFeatureIds: string[]): Promise<void> {
+    const runtimeSessions = await this.runtimeStateReader.getRuntimeSessions();
+    const assignments = runtimeSessions.feature_sessions ?? {};
+    const scopedSet = new Set(scopedFeatureIds);
+    const closeAllAssignedSessions = Boolean(this.state.runMetadata.orchestrator_epoch_incremented);
+
+    for (const featureId of Object.keys(assignments).sort((a, b) => a.localeCompare(b))) {
+      if (!closeAllAssignedSessions && !scopedSet.has(featureId)) {
+        continue;
+      }
+
+      const assignment = assignments[featureId];
+      for (const sessionId of [assignment.planner_session_id, assignment.builder_session_id, assignment.qa_session_id]) {
+        if (!sessionId || sessionId === UNASSIGNED_SESSION_ID) {
+          continue;
+        }
+
+        await this.provider.closeSession(sessionId).catch(() => ({ closed: true }));
+      }
+    }
+  }
+
+  async initializeFeatureCluster(featureId: string): Promise<void> {
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_INIT, { feature_id: featureId });
+
+    const prompts = await this.promptProvider.loadRolePrompts();
+    const plannerSession = await this.provider.createSession('planner', featureId, prompts.planner);
+    const builderSession = await this.provider.createSession('builder', featureId, prompts.builder);
+    const qaSession = await this.provider.createSession('qa', featureId, prompts.qa);
+
+    this.state.sessionsByFeature.set(featureId, {
+      planner: plannerSession.session_id,
+      builder: builderSession.session_id,
+      qa: qaSession.session_id
+    });
+
+    await this.kernel.updateFeatureSessionAssignment({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      feature_id: featureId,
+      planner_session_id: plannerSession.session_id,
+      builder_session_id: builderSession.session_id,
+      qa_session_id: qaSession.session_id
+    });
+
+    await this.patchFeatureCluster(featureId, {
+      orchestrator_session_id: this.state.orchestratorSessionId ?? 'unknown',
+      planner_session_id: plannerSession.session_id,
+      builder_session_id: builderSession.session_id,
+      qa_session_id: qaSession.session_id
+    });
+  }
+
+  async closeFeatureCluster(featureId: string): Promise<void> {
+    const sessions = this.state.sessionsByFeature.get(featureId);
+    if (!sessions) {
+      return;
+    }
+
+    for (const sessionId of [sessions.planner, sessions.builder, sessions.qa]) {
+      if (!sessionId || sessionId === UNASSIGNED_SESSION_ID) {
+        continue;
+      }
+
+      await this.provider.closeSession(sessionId).catch(() => ({ closed: true }));
+    }
+
+    this.state.sessionsByFeature.delete(featureId);
+  }
+
+  async reconcileQueuedFeatures(queue: FeatureInput[] = this.state.queue): Promise<void> {
+    for (const feature of queue) {
+      await this.kernel.updateFeatureSessionAssignment({
+        run_id: this.state.runId,
+        owner_instance_id: this.state.ownerInstanceId,
+        feature_id: feature.feature_id,
+        planner_session_id: UNASSIGNED_SESSION_ID,
+        builder_session_id: UNASSIGNED_SESSION_ID,
+        qa_session_id: UNASSIGNED_SESSION_ID
+      });
+
+      await this.patchFeatureCluster(feature.feature_id, {
+        orchestrator_session_id: this.state.orchestratorSessionId ?? 'unknown',
+        planner_session_id: UNASSIGNED_SESSION_ID,
+        builder_session_id: UNASSIGNED_SESSION_ID,
+        qa_session_id: UNASSIGNED_SESSION_ID
+      });
+    }
+  }
+
+  async enforceActiveFeatureInvariant(activeFeatureIds: string[]): Promise<void> {
+    const orchestratorSessionId = this.state.orchestratorSessionId;
+    if (!orchestratorSessionId) {
+      return;
+    }
+
+    for (const featureId of [...activeFeatureIds].sort((a, b) => a.localeCompare(b))) {
+      const state = await this.toolCaller.callTool<FeatureStatePayload>('orchestrator', TOOLS.FEATURE_STATE_GET, {
+        feature_id: featureId
+      });
+
+      const cluster = state.data.front_matter.cluster ?? {};
+      if (cluster.orchestrator_session_id === orchestratorSessionId) {
+        continue;
+      }
+
+      await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+        feature_id: featureId,
+        expected_version: state.data.front_matter.version,
+        patch: {
+          front_matter: {
+            cluster: {
+              ...cluster,
+              orchestrator_session_id: orchestratorSessionId
+            }
+          }
+        }
+      });
+    }
+  }
+
+  async patchFeatureCluster(featureId: string, clusterPatch: Record<string, string>): Promise<void> {
+    const state = await this.toolCaller.callTool<FeatureStatePayload>('orchestrator', TOOLS.FEATURE_STATE_GET, {
+      feature_id: featureId
+    });
+
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: featureId,
+      expected_version: state.data.front_matter.version,
+      patch: {
+        front_matter: {
+          cluster: {
+            ...(state.data.front_matter.cluster ?? {}),
+            ...clusterPatch
+          }
+        }
+      }
+    });
+  }
+}