agentic-orchestrator 0.1.2 → 0.1.4

package/apps/control-plane/src/supervisor/run-coordinator.ts

@@ -14,6 +14,9 @@ import { type BuildWaveExecutor } from './build-wave-executor.js';
 import { type QaWaveExecutor } from './qa-wave-executor.js';
 import { type LeaseHeartbeatService } from './lease-heartbeat-service.js';
 import { NOOP_WORKER_DECISION_RUNNER, type WorkerDecisionRunner } from './worker-decision-loop.js';
+import type { NotifierService } from '../application/services/notifier-service.js';
+import type { PrMonitorService } from '../application/services/pr-monitor-service.js';
+import type { IssueTracker } from '../application/services/issue-tracker-service.js';
 
 interface RunCoordinatorDependencies {
   kernel: FeatureOrchestrationPort & RuntimeStateReader;
@@ -31,6 +34,9 @@ interface RunCoordinatorDependencies {
   takeoverStaleRun: boolean;
   providerConfigRefHash: () => string;
   workerDecisionRunner?: WorkerDecisionRunner;
+  notifier?: NotifierService;
+  prMonitor?: PrMonitorService;
+  issueTracker?: IssueTracker;
 }
 
 export class RunCoordinator {
@@ -49,7 +55,11 @@ export class RunCoordinator {
   private readonly takeoverStaleRun: boolean;
   private readonly providerConfigRefHash: () => string;
   private readonly workerDecisionRunner: WorkerDecisionRunner;
-  private static readonly TERMINAL_STATUSES = new Set<string>([STATUS.MERGED, STATUS.FAILED]);
+  private readonly notifier: NotifierService | undefined;
+  private readonly prMonitor: PrMonitorService | undefined;
+  private readonly issueTracker: IssueTracker | undefined;
+  private readonly statusCache: Map<string, string>;
+  private static readonly TERMINAL_STATUSES = new Set<string>([STATUS.MERGED, STATUS.FAILED, STATUS.PAUSED_BUDGET]);
 
   constructor(dependencies: RunCoordinatorDependencies) {
     this.kernel = dependencies.kernel;
@@ -67,6 +77,10 @@ export class RunCoordinator {
     this.takeoverStaleRun = dependencies.takeoverStaleRun;
     this.providerConfigRefHash = dependencies.providerConfigRefHash;
     this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
+    this.notifier = dependencies.notifier;
+    this.prMonitor = dependencies.prMonitor;
+    this.issueTracker = dependencies.issueTracker;
+    this.statusCache = new Map();
   }
 
   async start(features: FeatureInput[]): Promise<Record<string, unknown>> {
@@ -106,10 +120,13 @@ export class RunCoordinator {
       }
       await this.leaseHeartbeatService.renew();
       activeFeatureIds = await this.applyOrchestratorPrioritization(activeFeatureIds, iteration + 1);
+      // N3: Check budget before waves; pause over-budget features
+      activeFeatureIds = await this.pauseOverBudgetFeatures(activeFeatureIds);
       await this.planningWaveExecutor.run(activeFeatureIds);
       await this.buildWaveExecutor.run(activeFeatureIds, this.maxParallelGateRuns);
       await this.qaWaveExecutor.run(activeFeatureIds, this.maxParallelGateRuns);
       await this.planningWaveExecutor.runPostQaReconciliation(activeFeatureIds, iteration + 1);
+      await this.notifyStatusTransitions(activeFeatureIds);
       activeFeatureIds = await this.rebalanceActiveFeatures(activeFeatureIds);
     }
 
@@ -127,6 +144,39 @@ export class RunCoordinator {
     };
   }
 
+  private async pauseOverBudgetFeatures(activeFeatureIds: string[]): Promise<string[]> {
+    const remaining: string[] = [];
+    for (const featureId of activeFeatureIds) {
+      const budgetCheck = await this.kernel.checkBudget(featureId);
+      if (budgetCheck.over_budget) {
+        await this.kernel.updateState(featureId, null, (_fm) => Promise.resolve({
+          frontMatter: {
+            status: STATUS.PAUSED_BUDGET,
+            status_reason: `Feature paused: estimated cost $${budgetCheck.current_cost_usd.toFixed(4)} exceeds budget limit $${budgetCheck.limit_usd.toFixed(2)}`
+          }
+        }));
+        if (this.notifier) {
+          await this.notifier.notify('budget_exceeded', {
+            feature_id: featureId,
+            message: `Budget exceeded for ${featureId}: $${budgetCheck.current_cost_usd.toFixed(4)} >= $${budgetCheck.limit_usd.toFixed(2)}`,
+            details: { current_cost_usd: budgetCheck.current_cost_usd, limit_usd: budgetCheck.limit_usd }
+          });
+        }
+        await this.sessionOrchestrator.closeFeatureCluster(featureId);
+      } else {
+        remaining.push(featureId);
+        if (budgetCheck.alert_threshold_reached && this.notifier) {
+          await this.notifier.notify('budget_alert', {
+            feature_id: featureId,
+            message: `Budget alert for ${featureId}: $${budgetCheck.current_cost_usd.toFixed(4)} (${Math.round(budgetCheck.alert_threshold * 100)}% of $${budgetCheck.limit_usd.toFixed(2)})`,
+            details: { current_cost_usd: budgetCheck.current_cost_usd, limit_usd: budgetCheck.limit_usd, alert_threshold: budgetCheck.alert_threshold }
+          });
+        }
+      }
+    }
+    return remaining;
+  }
+
   private async rebalanceActiveFeatures(currentActiveFeatureIds: string[]): Promise<string[]> {
     const survivingActiveFeatureIds: string[] = [];
     const sortedCurrent = [...currentActiveFeatureIds].sort((a, b) => a.localeCompare(b));
@@ -172,16 +222,103 @@ export class RunCoordinator {
     return activeFeatureIds;
   }
 
-  private async readFeatureStatus(featureId: string): Promise<string | null> {
+  private static asRecord(value: unknown): Record<string, unknown> {
+    return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+  }
+
+  private async readFeatureStateSnapshot(
+    featureId: string
+  ): Promise<{ status: string | null; branch: string; hasPr: boolean }> {
     try {
       const state = await this.toolCaller.callTool<FeatureStatePayload>('orchestrator', TOOLS.FEATURE_STATE_GET, {
         feature_id: featureId
       });
-      const status = state.data.front_matter.status;
-      return typeof status === 'string' ? status : null;
-    } catch (_error) {
-      return null;
+      const frontMatter = RunCoordinator.asRecord(state.data.front_matter);
+      const status = typeof frontMatter.status === 'string' ? frontMatter.status : null;
+      const prValue = frontMatter.pr;
+      const hasPr = prValue !== null && typeof prValue === 'object';
+      const branch =
+        typeof frontMatter.worktree_branch === 'string'
+          ? frontMatter.worktree_branch
+          : typeof frontMatter.branch === 'string'
+            ? frontMatter.branch
+            : featureId;
+      return { status, branch, hasPr };
+    } catch {
+      return { status: null, branch: featureId, hasPr: false };
+    }
+  }
+
+  private async readFeatureStatus(featureId: string): Promise<string | null> {
+    const snapshot = await this.readFeatureStateSnapshot(featureId);
+    return snapshot.status;
+  }
+
+  private async notifyStatusTransitions(featureIds: string[]): Promise<void> {
+    for (const featureId of featureIds) {
+      const snapshot = await this.readFeatureStateSnapshot(featureId);
+      const newStatus = snapshot.status;
+      if (newStatus === null) {
+        continue;
+      }
+      const prevStatus = this.statusCache.get(featureId);
+      const shouldPollPr = this.prMonitor && (newStatus === STATUS.READY_TO_MERGE || snapshot.hasPr);
+      if (prevStatus === newStatus && shouldPollPr) {
+        await this.prMonitor.checkAndUpdate(featureId, snapshot.branch);
+      }
+      if (prevStatus === newStatus) {
+        continue;
+      }
+      this.statusCache.set(featureId, newStatus);
+      if (this.notifier) {
+        if (newStatus === STATUS.BLOCKED) {
+          const event = prevStatus === STATUS.PLANNING ? 'collision_detected' : 'gate_failed';
+          await this.notifier.notify(event, {
+            feature_id: featureId,
+            message: `Feature ${featureId} blocked (event: ${event})`
+          });
+        } else if (newStatus === STATUS.READY_TO_MERGE) {
+          await this.notifier.notify('ready_to_merge', {
+            feature_id: featureId,
+            message: `Feature ${featureId} is ready to merge`
+          });
+          if (shouldPollPr) {
+            await this.prMonitor.checkAndUpdate(featureId, snapshot.branch);
+          }
+        } else if (newStatus === STATUS.MERGED) {
+          await this.notifier.notify('feature_merged', {
+            feature_id: featureId,
+            message: `Feature ${featureId} was merged`
+          });
+        }
+      }
+      if (this.issueTracker) {
+        await this.syncIssueTrackerStatus(featureId, newStatus, prevStatus);
+      }
+    }
+  }
+
+  private async syncIssueTrackerStatus(featureId: string, status: string, prevStatus: string | undefined): Promise<void> {
+    if (!this.issueTracker) {return;}
+    const issueId = featureId.replace(/^feature[/_]/, '');
+    if (status === STATUS.PLANNING && prevStatus === undefined) {
+      // Spec enrichment: fetch issue context when planning starts, store in frontmatter
+      const issue = await this.issueTracker.getIssue(issueId).catch(() => null);
+      if (issue && issue.title) {
+        const issueCtx = {
+          id: issue.id,
+          title: issue.title,
+          body: issue.body,
+          status: issue.status,
+          url: issue.url
+        };
+        await this.kernel.updateState(featureId, null, (fm) =>
+          Promise.resolve({ frontMatter: { ...fm, issue_context: issueCtx } })
+        );
+      }
     }
+    await this.issueTracker.addComment(issueId, `AOP: feature status changed to \`${status}\``).catch(() => undefined);
+    await this.issueTracker.updateIssueStatus(issueId, status).catch(() => undefined);
   }
 
   private async applyOrchestratorPrioritization(

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

@@ -11,6 +11,19 @@ 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 { createNotifierService } from '../application/services/notifier-service.js';
+import { ReactionsService } from '../application/services/reactions-service.js';
+import { ActivityMonitorService } from '../application/services/activity-monitor-service.js';
+import { PrMonitorService, createGhRunner } from '../application/services/pr-monitor-service.js';
+import { createIssueTracker } from '../application/services/issue-tracker-service.js';
+import {
+  globalAdapterRegistry,
+  NOTIFICATION_CHANNEL_SLOT,
+  ACTIVITY_DETECTOR_SLOT,
+  SCM_PROVIDER_SLOT,
+  type AdapterSlot
+} from '../application/adapters/adapter-registry.js';
+import type { ReactionsPolicy } from '../application/services/reactions-service.js';
 import type {
   AgentPromptProvider,
   AppError,
@@ -26,6 +39,32 @@ import type {
   WorkerSessions
 } from './types.js';
 
+type NamedContract = { name: string };
+
+function resolveAdapterName(
+  slot: AdapterSlot<NamedContract>,
+  configuredValue: unknown,
+  fallback: string | null
+): string | null {
+  const configured = typeof configuredValue === 'string' && configuredValue.length > 0 ? configuredValue : null;
+  const candidate = configured ?? fallback;
+  if (!candidate) {
+    return null;
+  }
+  try {
+    return globalAdapterRegistry.resolve(slot, candidate, {}).name;
+  } catch {
+    if (!fallback || candidate === fallback) {
+      return null;
+    }
+    try {
+      return globalAdapterRegistry.resolve(slot, fallback, {}).name;
+    } catch {
+      return null;
+    }
+  }
+}
+
 export class SupervisorRuntime
   implements SupervisorToolCaller, AgentPromptProvider, InitialPlanGenerator, FeatureClusterPatcher
 {
@@ -58,11 +97,18 @@ export class SupervisorRuntime
     this.provider = provider;
     this.toolClient = toolClient;
     this.maxActiveFeatures = options.max_active_features ?? 5;
-    this.maxParallelGateRuns = options.max_parallel_gate_runs ?? 2;
+    this.maxParallelGateRuns = this.resolveMaxParallelGateRuns(options.max_parallel_gate_runs);
     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()}`;
+    const adaptersConfig =
+      typeof (this.kernel as { getAdaptersConfig?: () => Record<string, unknown> }).getAdaptersConfig === 'function'
+        ? this.kernel.getAdaptersConfig()
+        : {};
+    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');
 
     this.state = {
       runId,
@@ -74,7 +120,12 @@ export class SupervisorRuntime
         started_at: new Date().toISOString(),
         owner_instance_id: ownerInstanceId,
         takeover_stale_run: this.takeoverStaleRun,
-        resolved_provider: provider.selection
+        resolved_provider: provider.selection,
+        adapters: {
+          notification_channel: notificationChannel,
+          activity_detector: activityDetector,
+          scm_provider: scmProvider
+        }
       }
     };
 
@@ -88,9 +139,43 @@ export class SupervisorRuntime
       state: this.state
     });
 
+    const notifier = createNotifierService(this.kernel.getPolicySnapshot(), notificationChannel);
+    const reactionsPolicy = this.resolveReactionsPolicy();
+    const reactionsService = new ReactionsService({
+      toolCaller: this,
+      notifier,
+      policy: reactionsPolicy
+    });
+
+    const activityMonitor = new ActivityMonitorService({
+      toolCaller: this,
+      notifier,
+      reactionsPolicy,
+      idleThresholdMs: this.resolveActivityIdleThresholdMs(),
+      detectorName: activityDetector ?? 'claude-jsonl'
+    });
+
+    const prMonitor =
+      scmProvider === 'github'
+        ? new PrMonitorService({
+            toolCaller: this,
+            notifier,
+            reactionsPolicy,
+            ghRunner: createGhRunner()
+          })
+        : undefined;
+
+    const policy = this.kernel.getPolicySnapshot();
+    const rawIssueTrackerConfig = policy['issue_tracker'];
+    const issueTrackerConfig = typeof rawIssueTrackerConfig === 'object' && rawIssueTrackerConfig !== null
+      ? (rawIssueTrackerConfig as { type: string; config?: Record<string, string> })
+      : undefined;
+    const issueTracker = createIssueTracker(issueTrackerConfig);
+
     this.workerDecisionLoop = new WorkerDecisionLoop({
       provider: this.provider,
-      toolCaller: this
+      toolCaller: this,
+      activityMonitor
     });
 
     this.planningWaveExecutor = new PlanningWaveExecutor({
@@ -101,7 +186,8 @@ export class SupervisorRuntime
 
     this.buildWaveExecutor = new BuildWaveExecutor({
       toolCaller: this,
-      workerDecisionRunner: this.workerDecisionLoop
+      workerDecisionRunner: this.workerDecisionLoop,
+      reactionsService
     });
 
     this.qaWaveExecutor = new QaWaveExecutor({
@@ -111,7 +197,8 @@ export class SupervisorRuntime
       promptProvider: this,
       featureClusterPatcher: this,
       state: this.state,
-      workerDecisionRunner: this.workerDecisionLoop
+      workerDecisionRunner: this.workerDecisionLoop,
+      reactionsService
     });
 
     this.leaseHeartbeatService = new LeaseHeartbeatService({
@@ -134,7 +221,10 @@ export class SupervisorRuntime
       maxIterationsPerPhase: this.maxIterationsPerPhase,
       takeoverStaleRun: this.takeoverStaleRun,
       providerConfigRefHash: () => this.providerConfigRefHash(),
-      workerDecisionRunner: this.workerDecisionLoop
+      workerDecisionRunner: this.workerDecisionLoop,
+      notifier,
+      prMonitor,
+      issueTracker
     });
   }
 
@@ -220,6 +310,45 @@ export class SupervisorRuntime
     return SupervisorRuntime.DEFAULT_MAX_ITERATIONS_PER_PHASE;
   }
 
+  private resolveMaxParallelGateRuns(cliOverride: number | undefined): number {
+    if (typeof cliOverride === 'number' && Number.isFinite(cliOverride) && cliOverride >= 1) {
+      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_parallel_gate_runs;
+    if (typeof configured === 'number' && Number.isFinite(configured) && configured >= 1) {
+      return Math.floor(configured);
+    }
+
+    return 2;
+  }
+
+  private resolveReactionsPolicy(): ReactionsPolicy | undefined {
+    const policy = this.kernel.getPolicySnapshot();
+    if (policy.reactions && typeof policy.reactions === 'object') {
+      return policy.reactions as ReactionsPolicy;
+    }
+    return undefined;
+  }
+
+  private resolveActivityIdleThresholdMs(): number {
+    const policy = this.kernel.getPolicySnapshot();
+    const supervisor =
+      policy.supervisor && typeof policy.supervisor === 'object'
+        ? (policy.supervisor as Record<string, unknown>)
+        : null;
+    const configured = supervisor?.agent_idle_threshold_ms;
+    if (typeof configured === 'number' && Number.isFinite(configured) && configured > 0) {
+      return Math.floor(configured);
+    }
+    return 300_000;
+  }
+
   async ensureGlobalOrchestratorSession(): Promise<void> {
     await this.sessionOrchestrator.ensureGlobalOrchestratorSession();
   }

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

@@ -1,4 +1,12 @@
 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';
+export type {
+  FeatureStateFrontMatter,
+  FeatureStatePayload,
+  RuntimeRole,
+  ToolCaller as SupervisorToolCaller
+} from '../core/tool-caller.js';
 
 export interface AppError extends Error {
   code?: string;
@@ -24,19 +32,6 @@ export interface WorkerSessions {
   qa: string;
 }
 
-export type RuntimeRole = 'orchestrator' | 'planner' | 'builder' | 'qa';
-
-export interface FeatureStateFrontMatter {
-  version: number;
-  status: string;
-  cluster?: Record<string, string>;
-}
-
-export interface FeatureStatePayload {
-  front_matter: FeatureStateFrontMatter;
-  body?: string;
-}
-
 export interface FeatureContextPayload {
   state: FeatureStatePayload;
   spec?: string;
@@ -101,6 +96,7 @@ export interface RuntimeStateReader {
   getRepoRoot(): string;
   getAgentsConfig(): AgentsConfigSnapshot;
   getPolicySnapshot(): Record<string, unknown>;
+  getAdaptersConfig(): Record<string, unknown>;
 }
 
 export interface FeatureOrchestrationPort {
@@ -113,18 +109,13 @@ export interface FeatureOrchestrationPort {
   renewLeases(featureIds: string[]): Promise<void>;
   renewRunLease(runId: string, ownerInstanceId: string): Promise<{ data: { lease_expires_at: string } }>;
   repoDiff(featureId: string, options?: string[]): Promise<{ data: Record<string, unknown> }>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  updateState(featureId: string, expectedVersion: number | null, updater: (fm: Record<string, any>, body: string) => Promise<{ frontMatter?: Record<string, any>; body?: string }>): Promise<Record<string, unknown>>;
+  checkBudget(featureId: string): Promise<BudgetCheckResult>;
 }
 
 export type SupervisorKernelPort = RuntimeStateReader & FeatureOrchestrationPort;
 
-export interface SupervisorToolCaller {
-  callTool<TData = Record<string, unknown>>(
-    role: RuntimeRole,
-    toolName: string,
-    args: Record<string, unknown>
-  ): Promise<{ ok: true; data: TData }>;
-}
-
 export interface AgentPromptProvider {
   loadRolePrompts(): Promise<PromptBundle>;
 }

package/apps/control-plane/src/supervisor/worker-decision-loop.ts

@@ -1,6 +1,7 @@
 import { TOOLS } from '../core/constants.js';
 import type { WorkerProvider } from '../providers/providers.js';
 import type { RuntimeRole, SupervisorToolCaller } from './types.js';
+import type { ActivityMonitorService } from '../application/services/activity-monitor-service.js';
 
 type AnyRecord = Record<string, unknown>;
 
@@ -86,15 +87,18 @@ export const NOOP_WORKER_DECISION_RUNNER: WorkerDecisionRunner = {
 interface WorkerDecisionLoopDependencies {
   provider: WorkerProvider;
   toolCaller: SupervisorToolCaller;
+  activityMonitor?: ActivityMonitorService;
 }
 
 export class WorkerDecisionLoop implements WorkerDecisionRunner {
   private readonly provider: WorkerProvider;
   private readonly toolCaller: SupervisorToolCaller;
+  private readonly activityMonitor: ActivityMonitorService | undefined;
 
   constructor(dependencies: WorkerDecisionLoopDependencies) {
     this.provider = dependencies.provider;
     this.toolCaller = dependencies.toolCaller;
+    this.activityMonitor = dependencies.activityMonitor;
   }
 
   async execute(input: WorkerDecisionInput): Promise<WorkerDecisionResult> {
@@ -140,6 +144,10 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       }
     }
 
+    if (this.activityMonitor) {
+      await this.activityMonitor.checkAndNotifyStuck(input.featureId);
+    }
+
     return result;
   }