agentic-orchestrator 0.1.28 → 0.2.0

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

@@ -9,6 +9,7 @@ import type {
   SupervisorRuntimeState,
   SupervisorToolCaller,
 } from './types.js';
+import { resolvePlannerPhaseFromFrontMatter, type PlannerPromptPhase } from './planner-phase.js';
 import { UNASSIGNED_SESSION_ID } from './types.js';
 
 interface SessionOrchestratorDependencies {
@@ -24,6 +25,12 @@ interface SessionOrchestratorDependencies {
  * @fileoverview Session lifecycle management for agent clusters.
  */
 
+/**
+ * Manages provider session lifecycles for the orchestrator and per-feature agent clusters.
+ *
+ * Handles creation, reattachment, teardown, and prompt-phase synchronisation
+ * of orchestrator, reconciler, planner, builder, and QA sessions.
+ */
 export class SessionOrchestrator {
   private readonly kernel: SupervisorKernelPort;
   private readonly runtimeStateReader: RuntimeStateReader;
@@ -31,6 +38,7 @@ export class SessionOrchestrator {
   private readonly promptProvider: AgentPromptProvider;
   private readonly toolCaller: SupervisorToolCaller;
   private readonly state: SupervisorRuntimeState;
+  private readonly plannerPromptPhaseByFeature = new Map<string, PlannerPromptPhase>();
 
   constructor(dependencies: SessionOrchestratorDependencies) {
     this.kernel = dependencies.kernel;
@@ -41,12 +49,17 @@ export class SessionOrchestrator {
     this.state = dependencies.state;
   }
 
+  /**
+   * Ensure the global orchestrator session exists, reattaching to a previous
+   * session when the run/owner/provider match, or creating a fresh one otherwise.
+   */
   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 &&
+      runtimeSessions.provider === this.provider.selection.provider &&
       typeof candidate === 'string' &&
       candidate.length > 0 &&
       candidate !== 'unknown';
@@ -59,6 +72,8 @@ export class SessionOrchestrator {
     if (reattachSucceeded) {
       this.state.orchestratorSessionId = candidate;
       this.state.runMetadata.orchestrator_reattached = true;
+      await this.ensureGlobalReconcilerSession();
+      await this.ensureGlobalOrganizerSession();
       return;
     }
 
@@ -77,6 +92,89 @@ export class SessionOrchestrator {
     if (canReuse && candidate) {
       await this.markOrphanSession(candidate, Number(runtimeSessions.orchestrator_epoch ?? 0));
     }
+
+    await this.ensureGlobalReconcilerSession();
+    await this.ensureGlobalOrganizerSession();
+  }
+
+  private async ensureGlobalReconcilerSession(): Promise<void> {
+    const runtimeSessions = await this.runtimeStateReader.getRuntimeSessions();
+    const candidate = runtimeSessions.reconciler_session_id;
+    const canReuse =
+      runtimeSessions.run_id === this.state.runId &&
+      runtimeSessions.owner_instance_id === this.state.ownerInstanceId &&
+      runtimeSessions.provider === this.provider.selection.provider &&
+      typeof candidate === 'string' &&
+      candidate.length > 0 &&
+      candidate !== 'unknown';
+
+    if (canReuse) {
+      const reattachSucceeded = await this.attemptReattach(candidate);
+      if (reattachSucceeded) {
+        this.state.reconcilerSessionId = candidate;
+        this.state.runMetadata.reconciler_reattached = true;
+        return;
+      }
+    }
+
+    const prompts = await this.promptProvider.loadRolePrompts();
+    const reconcilerSession = await this.provider.createSession(
+      'reconciler',
+      'global',
+      prompts.reconciler ?? null,
+    );
+    this.state.reconcilerSessionId = reconcilerSession.session_id;
+    this.state.runMetadata.reconciler_reattached = false;
+
+    await this.kernel.updateReconcilerSession({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      reconciler_session_id: reconcilerSession.session_id,
+    });
+
+    if (canReuse && candidate) {
+      await this.provider.closeSession(candidate).catch(() => ({ closed: true }));
+    }
+  }
+
+  private async ensureGlobalOrganizerSession(): Promise<void> {
+    const runtimeSessions = await this.runtimeStateReader.getRuntimeSessions();
+    const candidate = runtimeSessions.organizer_session_id;
+    const canReuse =
+      runtimeSessions.run_id === this.state.runId &&
+      runtimeSessions.owner_instance_id === this.state.ownerInstanceId &&
+      runtimeSessions.provider === this.provider.selection.provider &&
+      typeof candidate === 'string' &&
+      candidate.length > 0 &&
+      candidate !== 'unknown';
+
+    if (canReuse) {
+      const reattachSucceeded = await this.attemptReattach(candidate);
+      if (reattachSucceeded) {
+        this.state.organizerSessionId = candidate;
+        this.state.runMetadata.organizer_reattached = true;
+        return;
+      }
+    }
+
+    const prompts = await this.promptProvider.loadRolePrompts();
+    const organizerSession = await this.provider.createSession(
+      'organizer',
+      'global',
+      prompts.organizer ?? null,
+    );
+    this.state.organizerSessionId = organizerSession.session_id;
+    this.state.runMetadata.organizer_reattached = false;
+
+    await this.kernel.updateOrganizerSession({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      organizer_session_id: organizerSession.session_id,
+    });
+
+    if (canReuse && candidate) {
+      await this.provider.closeSession(candidate).catch(() => ({ closed: true }));
+    }
   }
 
   private async attemptReattach(sessionId: string): Promise<boolean> {
@@ -132,6 +230,11 @@ export class SessionOrchestrator {
       .catch(() => ({ ok: true, data: {} }));
   }
 
+  /**
+   * Close stale worker sessions for the given features, or all assigned
+   * sessions when an orchestrator epoch increment has occurred.
+   * @param scopedFeatureIds Feature IDs whose worker sessions should be closed.
+   */
   async cleanupOrphanWorkerSessions(scopedFeatureIds: string[]): Promise<void> {
     const runtimeSessions = await this.runtimeStateReader.getRuntimeSessions();
     const assignments = runtimeSessions.feature_sessions ?? {};
@@ -158,11 +261,22 @@ export class SessionOrchestrator {
     }
   }
 
+  /**
+   * Initialise a full agent cluster (planner, builder, QA) for a feature,
+   * creating provider sessions, persisting session assignments, and patching
+   * the feature state with the new cluster metadata.
+   * @param featureId Feature to create the cluster for.
+   */
   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 plannerPromptPhase = await this.readPlannerPromptPhase(featureId);
+    const plannerSession = await this.provider.createSession(
+      'planner',
+      featureId,
+      this.resolvePlannerPrompt(prompts, plannerPromptPhase),
+    );
     const builderSession = await this.provider.createSession('builder', featureId, prompts.builder);
     const qaSession = await this.provider.createSession('qa', featureId, prompts.qa);
 
@@ -171,6 +285,7 @@ export class SessionOrchestrator {
       builder: builderSession.session_id,
       qa: qaSession.session_id,
     });
+    this.plannerPromptPhaseByFeature.set(featureId, plannerPromptPhase);
 
     await this.kernel.updateFeatureSessionAssignment({
       run_id: this.state.runId,
@@ -186,9 +301,15 @@ export class SessionOrchestrator {
       planner_session_id: plannerSession.session_id,
       builder_session_id: builderSession.session_id,
       qa_session_id: qaSession.session_id,
+      reconciler_session_id: this.state.reconcilerSessionId ?? 'unknown',
     });
   }
 
+  /**
+   * Tear down all provider sessions for a feature cluster and remove
+   * the in-memory session mapping.
+   * @param featureId Feature whose cluster sessions should be closed.
+   */
   async closeFeatureCluster(featureId: string): Promise<void> {
     const sessions = this.state.sessionsByFeature.get(featureId);
     if (!sessions) {
@@ -204,10 +325,28 @@ export class SessionOrchestrator {
     }
 
     this.state.sessionsByFeature.delete(featureId);
+    this.plannerPromptPhaseByFeature.delete(featureId);
   }
 
+  /**
+   * Re-evaluate and, if needed, rotate each feature's planner session to
+   * match the current planner prompt phase (e.g. intake vs. execution).
+   * @param featureIds Features whose planner sessions should be synchronised.
+   */
+  async syncPlannerSessions(featureIds: string[]): Promise<void> {
+    for (const featureId of [...featureIds].sort((a, b) => a.localeCompare(b))) {
+      await this.syncPlannerSession(featureId);
+    }
+  }
+
+  /**
+   * Mark queued (not-yet-active) features with unassigned session placeholders
+   * so they are tracked in the index without consuming real provider sessions.
+   * @param queue Features awaiting cluster initialisation; defaults to the runtime queue.
+   */
   async reconcileQueuedFeatures(queue: FeatureInput[] = this.state.queue): Promise<void> {
     for (const feature of queue) {
+      this.plannerPromptPhaseByFeature.delete(feature.feature_id);
       await this.kernel.updateFeatureSessionAssignment({
         run_id: this.state.runId,
         owner_instance_id: this.state.ownerInstanceId,
@@ -222,10 +361,85 @@ export class SessionOrchestrator {
         planner_session_id: UNASSIGNED_SESSION_ID,
         builder_session_id: UNASSIGNED_SESSION_ID,
         qa_session_id: UNASSIGNED_SESSION_ID,
+        reconciler_session_id: this.state.reconcilerSessionId ?? 'unknown',
       });
     }
   }
 
+  private async syncPlannerSession(featureId: string): Promise<void> {
+    const sessions = this.state.sessionsByFeature.get(featureId);
+    if (!sessions || !sessions.planner || sessions.planner === UNASSIGNED_SESSION_ID) {
+      return;
+    }
+
+    const desiredPhase = await this.readPlannerPromptPhase(featureId);
+    const currentPhase = this.plannerPromptPhaseByFeature.get(featureId) ?? null;
+    if (currentPhase === desiredPhase) {
+      return;
+    }
+
+    const prompts = await this.promptProvider.loadRolePrompts();
+    const nextPlannerSession = await this.provider.createSession(
+      'planner',
+      featureId,
+      this.resolvePlannerPrompt(prompts, desiredPhase),
+    );
+
+    const previousPlannerSessionId = sessions.planner;
+    this.state.sessionsByFeature.set(featureId, {
+      ...sessions,
+      planner: nextPlannerSession.session_id,
+    });
+    this.plannerPromptPhaseByFeature.set(featureId, desiredPhase);
+
+    await this.kernel.updateFeatureSessionAssignment({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      feature_id: featureId,
+      planner_session_id: nextPlannerSession.session_id,
+      builder_session_id: sessions.builder,
+      qa_session_id: sessions.qa,
+    });
+
+    await this.patchFeatureCluster(featureId, {
+      planner_session_id: nextPlannerSession.session_id,
+    });
+
+    await this.provider.closeSession(previousPlannerSessionId).catch(() => ({ closed: true }));
+  }
+
+  private async readPlannerPromptPhase(featureId: string): Promise<PlannerPromptPhase> {
+    const state = await this.kernel.readState(featureId).catch(() => ({ frontMatter: {} }));
+    const frontMatter =
+      typeof state === 'object' &&
+      state !== null &&
+      'frontMatter' in state &&
+      typeof state.frontMatter === 'object' &&
+      state.frontMatter !== null
+        ? (state.frontMatter as Record<string, unknown>)
+        : {};
+    return this.resolvePlannerPromptPhase(frontMatter);
+  }
+
+  private resolvePlannerPromptPhase(frontMatter: unknown): PlannerPromptPhase {
+    return resolvePlannerPhaseFromFrontMatter(frontMatter);
+  }
+
+  private resolvePlannerPrompt(
+    prompts: Awaited<ReturnType<AgentPromptProvider['loadRolePrompts']>>,
+    phase: PlannerPromptPhase,
+  ): string | null {
+    if (phase === 'intake') {
+      return prompts.plannerIntake ?? prompts.planner;
+    }
+    return prompts.planner;
+  }
+
+  /**
+   * Ensure every active feature's state records the current orchestrator
+   * session ID, patching any that have drifted (e.g. after a session rotation).
+   * @param activeFeatureIds Features to verify and patch if necessary.
+   */
   async enforceActiveFeatureInvariant(activeFeatureIds: string[]): Promise<void> {
     const orchestratorSessionId = this.state.orchestratorSessionId;
     if (!orchestratorSessionId) {
@@ -261,6 +475,11 @@ export class SessionOrchestrator {
     }
   }
 
+  /**
+   * Apply a partial update to a feature's cluster metadata in its persisted state.
+   * @param featureId Feature whose cluster metadata should be patched.
+   * @param clusterPatch Key-value pairs to merge into the existing cluster record.
+   */
   async patchFeatureCluster(
     featureId: string,
     clusterPatch: Record<string, string>,

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

@@ -1,8 +1,14 @@
 import type { AgentsConfigSnapshot } from '../core/kernel.js';
 import type { FeatureStatePayload } from '../core/tool-caller.js';
 import type { BudgetCheckResult } from '../application/services/cost-tracking-service.js';
-import type { ExecutionMode } from '../providers/providers.js';
+import type { ExecutionMode, ProviderSelection } from '../providers/providers.js';
 import type { PatchValidationResult } from '../application/services/patch-service.js';
+import type {
+  ExecutionRequestItem,
+  ExecutionRequestOutcome,
+  ExecutionRequestStatus,
+  PendingExecutionRequestProgress,
+} from '../core/execution-control.js';
 export type {
   FeatureStateFrontMatter,
   FeatureStatePayload,
@@ -24,6 +30,7 @@ export interface SupervisorOptions {
   owner_instance_id?: string;
   takeover_stale_run?: boolean;
   execution_mode?: ExecutionMode;
+  role_selections?: Record<string, ProviderSelection>;
 }
 
 export interface FeatureInput {
@@ -42,12 +49,27 @@ export interface FeatureContextPayload {
   plan: Record<string, unknown> | null;
   qa_test_index?: Record<string, unknown> | null;
   latest_evidence?: Record<string, unknown> | null;
+  gate_evidence_by_mode?: Record<string, Record<string, unknown> | null> | null;
+  decision_log?: string | null;
+  human_input?: {
+    open_questions: unknown[];
+    latest_answer: unknown | null;
+  } | null;
+  intake?: {
+    summary: Record<string, unknown>;
+    bootstrap_manifest: Record<string, unknown> | null;
+    verified_manifest: Record<string, unknown> | null;
+    review: Record<string, unknown> | null;
+  } | null;
 }
 
 export interface PromptBundle {
   planner: string | null;
+  plannerIntake?: string | null;
   builder: string | null;
   qa: string | null;
+  reconciler?: string | null;
+  organizer?: string | null;
 }
 
 export interface RuntimeSessionAssignment {
@@ -59,11 +81,49 @@ export interface RuntimeSessionAssignment {
 export interface RuntimeSessionsSnapshot {
   run_id: string;
   owner_instance_id: string;
+  provider?: string;
   orchestrator_session_id: string;
+  reconciler_session_id?: string;
+  organizer_session_id?: string;
+  reconciler_active_feature_id?: string | null;
+  reconciler_queue?: string[];
   orchestrator_epoch?: number;
   feature_sessions?: Record<string, RuntimeSessionAssignment>;
 }
 
+export interface OrganizerDependencyEntry {
+  depends_on: string[];
+  classification:
+    | 'explicit_dependency'
+    | 'inferred_dependency'
+    | 'no_dependency_found'
+    | 'ambiguous_dependency_requires_human';
+}
+
+export interface OrganizerDeferredEntry {
+  feature_id: string;
+  blocked_by: string[];
+  reason: string;
+}
+
+export interface OrganizerBlockedEntry {
+  feature_id: string;
+  reason: string;
+}
+
+export interface OrganizerOrderingArtifact {
+  version: 1;
+  generated_at: string;
+  expires_at: string;
+  completion_status: 'complete' | 'partial';
+  backlog_fingerprint: string;
+  analyzed_requests: string[];
+  dependency_graph: Record<string, OrganizerDependencyEntry>;
+  ready_set: string[];
+  deferred_set: OrganizerDeferredEntry[];
+  blocked_set: OrganizerBlockedEntry[];
+}
+
 export interface AcquireRunLeaseInput {
   run_id: string;
   owner_instance_id: string;
@@ -89,6 +149,18 @@ export interface UpdateFeatureSessionAssignmentInput {
   qa_session_id: string;
 }
 
+export interface UpdateReconcilerSessionInput {
+  run_id: string;
+  owner_instance_id: string;
+  reconciler_session_id: string;
+}
+
+export interface UpdateOrganizerSessionInput {
+  run_id: string;
+  owner_instance_id: string;
+  organizer_session_id: string;
+}
+
 export interface PruneFeatureSessionAssignmentsInput {
   run_id: string;
   owner_instance_id: string;
@@ -113,6 +185,12 @@ export interface FeatureOrchestrationPort {
   updateFeatureSessionAssignment(
     params: UpdateFeatureSessionAssignmentInput,
   ): Promise<{ data: { updated: boolean } }>;
+  updateReconcilerSession(
+    params: UpdateReconcilerSessionInput,
+  ): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot } }>;
+  updateOrganizerSession(
+    params: UpdateOrganizerSessionInput,
+  ): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot } }>;
   pruneFeatureSessionAssignments(
     params: PruneFeatureSessionAssignmentsInput,
   ): Promise<{ data: { removed: string[] } }>;
@@ -121,6 +199,30 @@ export interface FeatureOrchestrationPort {
     runId: string,
     ownerInstanceId: string,
   ): Promise<{ data: { lease_expires_at: string } }>;
+  releaseRunLease(runId: string, ownerInstanceId: string): Promise<{ data: { released: boolean } }>;
+  drainPendingExecutionRequests(
+    runId: string,
+    ownerInstanceId: string,
+  ): Promise<{ data: { items: ExecutionRequestItem[] } }>;
+  markExecutionRequestProcessed(
+    runId: string,
+    ownerInstanceId: string,
+    requestId: string,
+    status: Exclude<ExecutionRequestStatus, 'pending'>,
+    outcome: Exclude<ExecutionRequestOutcome, null>,
+  ): Promise<{ data: { updated: boolean } }>;
+  updateExecutionRequestProgress(
+    runId: string,
+    ownerInstanceId: string,
+    requestId: string,
+    patch: {
+      detected_at?: string | null;
+      last_evaluated_at?: string | null;
+      queued?: string[];
+      skipped?: Array<{ feature_id: string; reason: string }>;
+      deferred?: Array<{ feature_id: string; reason: string }>;
+    },
+  ): Promise<{ data: { updated: boolean; progress: PendingExecutionRequestProgress | null } }>;
   repoDiff(featureId: string, options?: string[]): Promise<{ data: Record<string, unknown> }>;
   worktreePath(featureId: string): string;
   featurePath(featureId: string): string;
@@ -137,10 +239,57 @@ export interface FeatureOrchestrationPort {
     ) => Promise<{ frontMatter?: Record<string, unknown>; body?: string }>,
   ): Promise<Record<string, unknown>>;
   checkBudget(featureId: string): Promise<BudgetCheckResult>;
+  redrivePreparedReconcilerConflict?(featureId: string): Promise<boolean>;
 }
 
 export type SupervisorKernelPort = RuntimeStateReader & FeatureOrchestrationPort;
 
+export type EnrollmentDecisionDisposition = 'queue_now' | 'defer' | 'reject';
+
+export interface EnrollmentDecision {
+  request_id: string;
+  feature_id: string;
+  disposition: EnrollmentDecisionDisposition;
+  reason: string;
+}
+
+export interface EnrollmentSchedulingFeature {
+  feature_id: string;
+  status: string | null;
+}
+
+export interface EnrollmentSchedulingInput {
+  activeFeatureIds: string[];
+  queuedFeatureIds: string[];
+  assignedFeatureIds: string[];
+  maxActiveFeatures: number;
+  request: ExecutionRequestItem;
+  features: EnrollmentSchedulingFeature[];
+}
+
+export interface EnrollmentSchedulingResult {
+  decisions: EnrollmentDecision[];
+}
+
+export interface EnrollmentScheduler {
+  schedule(input: EnrollmentSchedulingInput): Promise<EnrollmentSchedulingResult>;
+}
+
+export interface EnrollmentDecisionBatch {
+  request: ExecutionRequestItem;
+  decisions: EnrollmentDecision[];
+  progress: PendingExecutionRequestProgress;
+}
+
+export interface ExecutionEnrollmentServicePort {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  notifyNewRequestHint(): Promise<void>;
+  noteSafeCheckpoint(): Promise<void>;
+  drainReadyDecisions(): Promise<EnrollmentDecisionBatch[]>;
+  hasPendingWork(): boolean;
+}
+
 export interface AgentPromptProvider {
   loadRolePrompts(): Promise<PromptBundle>;
 }
@@ -157,6 +306,8 @@ export interface SupervisorRuntimeState {
   runId: string;
   ownerInstanceId: string;
   orchestratorSessionId: string | null;
+  reconcilerSessionId?: string | null;
+  organizerSessionId?: string | null;
   sessionsByFeature: Map<string, WorkerSessions>;
   queue: FeatureInput[];
   runMetadata: Record<string, unknown>;