agentic-orchestrator 0.1.13 → 0.1.15

package/apps/control-plane/src/providers/worker-provider-factory.ts

@@ -0,0 +1,198 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import { ApiWorkerProvider } from './api-worker-provider.js';
+import { CliWorkerProvider } from './cli-worker-provider.js';
+import type {
+  AppError,
+  ProviderCommandRunner,
+  ProviderSelection,
+  WorkerProvider,
+} from './providers.js';
+import { SUPPORTED_PROVIDERS, NullWorkerProvider } from './providers.js';
+import {
+  ClaudeOutputParser,
+  CodexOutputParser,
+  GeminiOutputParser,
+  GenericCliOutputParser,
+} from './output-parsers/index.js';
+
+export type WorkerProviderMode = 'live' | 'stub';
+export type ProviderCommandContext = 'run' | 'resume' | 'send' | 'attach';
+
+export type WorkerMalformedOutputAction = 'block_feature' | 'fail_run';
+export type WorkerNoProgressAction = 'block_feature' | 'fail_run';
+
+export interface WorkerProviderFactoryPolicy {
+  require_live_provider_for_run: boolean;
+}
+
+export interface WorkerProviderFactoryRuntime {
+  worker_response_timeout_ms: number;
+  max_consecutive_no_progress_iterations: number;
+}
+
+export interface CreateWorkerProviderInput {
+  selection: ProviderSelection;
+  mode: WorkerProviderMode;
+  context: ProviderCommandContext;
+  policy: WorkerProviderFactoryPolicy;
+  runtime: WorkerProviderFactoryRuntime;
+  commandRunner?: ProviderCommandRunner;
+}
+
+export interface WorkerProviderFactory {
+  create(input: CreateWorkerProviderInput): WorkerProvider;
+}
+
+interface RuntimeConfigInput {
+  worker_response_timeout_ms?: unknown;
+  max_consecutive_no_progress_iterations?: unknown;
+}
+
+interface PolicyConfigInput {
+  require_live_provider_for_run?: unknown;
+  malformed_worker_output_action?: unknown;
+  no_progress_action?: unknown;
+}
+
+function asPositiveInteger(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
+function toAppError(code: string, message: string, details: Record<string, unknown>): AppError {
+  const error = new Error(message) as AppError;
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+function normalizeMode(value: unknown): WorkerProviderMode | null {
+  if (value === 'live' || value === 'stub') {
+    return value;
+  }
+  return null;
+}
+
+export function resolveWorkerProviderMode(
+  cliMode: unknown,
+  configuredMode: unknown,
+  fallback: WorkerProviderMode,
+): WorkerProviderMode {
+  const explicitCliMode = normalizeMode(cliMode);
+  if (explicitCliMode) {
+    return explicitCliMode;
+  }
+
+  const explicitConfiguredMode = normalizeMode(configuredMode);
+  if (explicitConfiguredMode) {
+    return explicitConfiguredMode;
+  }
+
+  return fallback;
+}
+
+export function resolveWorkerProviderRuntime(
+  input: RuntimeConfigInput | null | undefined,
+): WorkerProviderFactoryRuntime {
+  return {
+    worker_response_timeout_ms: asPositiveInteger(input?.worker_response_timeout_ms, 120_000),
+    max_consecutive_no_progress_iterations: asPositiveInteger(
+      input?.max_consecutive_no_progress_iterations,
+      2,
+    ),
+  };
+}
+
+export function resolveWorkerProviderPolicy(
+  input: PolicyConfigInput | null | undefined,
+): WorkerProviderFactoryPolicy {
+  return {
+    require_live_provider_for_run: input?.require_live_provider_for_run !== false,
+  };
+}
+
+export function resolveMalformedWorkerOutputAction(
+  input: PolicyConfigInput | null | undefined,
+): WorkerMalformedOutputAction {
+  return input?.malformed_worker_output_action === 'fail_run' ? 'fail_run' : 'block_feature';
+}
+
+export function resolveNoProgressAction(
+  input: PolicyConfigInput | null | undefined,
+): WorkerNoProgressAction {
+  return input?.no_progress_action === 'fail_run' ? 'fail_run' : 'block_feature';
+}
+
+export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
+  create(input: CreateWorkerProviderInput): WorkerProvider {
+    const { selection, mode, context, policy, runtime, commandRunner } = input;
+
+    if (!SUPPORTED_PROVIDERS.has(selection.provider)) {
+      throw toAppError(ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER, 'Unsupported worker provider', {
+        provider: selection.provider,
+      });
+    }
+
+    if (mode === 'stub') {
+      if (
+        (context === 'run' || context === 'resume') &&
+        policy.require_live_provider_for_run === true
+      ) {
+        throw toAppError(
+          ERROR_CODES.PROVIDER_STUB_DISALLOWED,
+          'Stub worker provider is disallowed for run/resume',
+          {
+            provider: selection.provider,
+            context,
+          },
+        );
+      }
+      return new NullWorkerProvider(selection, { commandRunner });
+    }
+
+    if (selection.provider === 'gemini') {
+      return new ApiWorkerProvider(selection, {
+        outputParser: new GeminiOutputParser(),
+        workerResponseTimeoutMs: runtime.worker_response_timeout_ms,
+      });
+    }
+
+    if (selection.provider === 'codex') {
+      return new CliWorkerProvider(selection, {
+        outputParser: new CodexOutputParser(),
+        commandRunner,
+        workerResponseTimeoutMs: runtime.worker_response_timeout_ms,
+      });
+    }
+
+    if (selection.provider === 'claude') {
+      return new CliWorkerProvider(selection, {
+        outputParser: new ClaudeOutputParser(),
+        commandRunner,
+        workerResponseTimeoutMs: runtime.worker_response_timeout_ms,
+      });
+    }
+
+    if (
+      selection.provider === 'kiro-cli' ||
+      selection.provider === 'copilot' ||
+      selection.provider === 'custom'
+    ) {
+      return new CliWorkerProvider(selection, {
+        outputParser: new GenericCliOutputParser(),
+        commandRunner,
+        workerResponseTimeoutMs: runtime.worker_response_timeout_ms,
+      });
+    }
+
+    throw toAppError(
+      ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
+      'No live worker provider adapter is available for selection',
+      {
+        provider: selection.provider,
+      },
+    );
+  }
+}

package/apps/control-plane/src/supervisor/build-wave-executor.ts

@@ -1,10 +1,16 @@
 import { GATE_RESULT, STATUS, TOOLS } from '../core/constants.js';
+import { ERROR_CODES } from '../core/error-codes.js';
 import type { FeatureStatePayload, SupervisorToolCaller } from './types.js';
 import { NOOP_WORKER_DECISION_RUNNER, type WorkerDecisionRunner } from './worker-decision-loop.js';
 import type {
   GateRepairContext,
   ReactionsService,
 } from '../application/services/reactions-service.js';
+import type {
+  WorkerMalformedOutputAction,
+  WorkerNoProgressAction,
+  WorkerProviderMode,
+} from '../providers/worker-provider-factory.js';
 
 interface GatesRunData {
   overall?: string;
@@ -15,6 +21,10 @@ interface BuildWaveExecutorDependencies {
   toolCaller: SupervisorToolCaller;
   workerDecisionRunner?: WorkerDecisionRunner;
   reactionsService?: ReactionsService;
+  providerMode?: WorkerProviderMode;
+  noProgressLimit?: number;
+  noProgressAction?: WorkerNoProgressAction;
+  malformedOutputAction?: WorkerMalformedOutputAction;
 }
 
 function isRetryableToolError(error: unknown): boolean {
@@ -28,18 +38,39 @@ function isRetryableToolError(error: unknown): boolean {
   return (details as { retryable?: unknown }).retryable === true;
 }
 
+function asVersion(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return null;
+  }
+  return Math.floor(value);
+}
+
 export class BuildWaveExecutor {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly workerDecisionRunner: WorkerDecisionRunner;
   private readonly reactionsService: ReactionsService | undefined;
+  private readonly providerMode: WorkerProviderMode;
+  private readonly noProgressLimit: number;
+  private readonly noProgressAction: WorkerNoProgressAction;
+  private readonly malformedOutputAction: WorkerMalformedOutputAction;
+  private readonly noProgressByFeature = new Map<string, number>();
+  private readonly blockedForCurrentCycle = new Set<string>();
 
   constructor(dependencies: BuildWaveExecutorDependencies) {
     this.toolCaller = dependencies.toolCaller;
     this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
     this.reactionsService = dependencies.reactionsService;
+    this.providerMode = dependencies.providerMode ?? 'stub';
+    this.noProgressLimit =
+      typeof dependencies.noProgressLimit === 'number' && dependencies.noProgressLimit > 0
+        ? Math.floor(dependencies.noProgressLimit)
+        : 2;
+    this.noProgressAction = dependencies.noProgressAction ?? 'block_feature';
+    this.malformedOutputAction = dependencies.malformedOutputAction ?? 'block_feature';
   }
 
   async run(featureIds: string[], maxParallelGateRuns: number): Promise<void> {
+    this.blockedForCurrentCycle.clear();
     const batch: string[] = [];
     for (const featureId of featureIds) {
       const state = await this.toolCaller.callTool<FeatureStatePayload>(
@@ -60,16 +91,23 @@ export class BuildWaveExecutor {
       const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
         feature_id: featureId,
       });
-      await this.workerDecisionRunner.execute({
+      const decision = await this.workerDecisionRunner.execute({
         role: 'builder',
         featureId,
         contextBundle: context.data,
         instructions:
           'Emit PATCH outputs for code changes, NOTE outputs for progress context, and REQUEST outputs for lock/context needs.',
       });
+      const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision);
+      if (!shouldSkip) {
+        this.noProgressByFeature.delete(featureId);
+      }
     }
 
-    const executing = selected.map(async (featureId) => {
+    const gateCandidates = selected.filter(
+      (featureId) => !this.blockedForCurrentCycle.has(featureId),
+    );
+    const executing = gateCandidates.map(async (featureId) => {
       const stateForRetry = await this.toolCaller.callTool<FeatureStatePayload>(
         'builder',
         TOOLS.FEATURE_STATE_GET,
@@ -140,12 +178,17 @@ export class BuildWaveExecutor {
             failureHistory,
           };
           const repairPrompt = this.reactionsService.buildRepairPrompt(ctx);
-          await this.workerDecisionRunner.execute({
+          const repairDecision = await this.workerDecisionRunner.execute({
             role: 'builder',
             featureId,
             contextBundle: context.data,
             instructions: repairPrompt,
           });
+          const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, repairDecision);
+          if (shouldSkip) {
+            break;
+          }
+          this.noProgressByFeature.delete(featureId);
 
           try {
             const retryResult = await this.toolCaller.callTool<GatesRunData>(
@@ -209,4 +252,98 @@ export class BuildWaveExecutor {
 
     await Promise.allSettled(executing);
   }
+
+  private async enforceWorkerExecutionPolicy(
+    featureId: string,
+    decision: {
+      invalidOutput: boolean;
+      noProgress: boolean;
+    },
+  ): Promise<boolean> {
+    if (this.providerMode !== 'live') {
+      this.noProgressByFeature.delete(featureId);
+      return false;
+    }
+
+    if (decision.invalidOutput) {
+      await this.applyWorkerPolicyAction(
+        featureId,
+        this.malformedOutputAction,
+        ERROR_CODES.PROVIDER_OUTPUT_INVALID,
+        'Builder emitted malformed worker outputs',
+      );
+      this.blockedForCurrentCycle.add(featureId);
+      return true;
+    }
+
+    if (!decision.noProgress) {
+      this.noProgressByFeature.delete(featureId);
+      return false;
+    }
+
+    const currentCount = (this.noProgressByFeature.get(featureId) ?? 0) + 1;
+    this.noProgressByFeature.set(featureId, currentCount);
+    this.blockedForCurrentCycle.add(featureId);
+
+    if (currentCount < this.noProgressLimit) {
+      return true;
+    }
+
+    await this.applyWorkerPolicyAction(
+      featureId,
+      this.noProgressAction,
+      ERROR_CODES.PROVIDER_NO_PROGRESS,
+      `Builder made no actionable progress in ${currentCount} consecutive iterations`,
+    );
+    return true;
+  }
+
+  private async applyWorkerPolicyAction(
+    featureId: string,
+    action: WorkerNoProgressAction | WorkerMalformedOutputAction,
+    errorCode: string,
+    message: string,
+  ): Promise<void> {
+    if (action === 'fail_run') {
+      const error = new Error(message) as Error & {
+        code?: string;
+        details?: Record<string, unknown>;
+      };
+      error.code = errorCode;
+      error.details = {
+        feature_id: featureId,
+        retryable: false,
+        requires_human: true,
+      };
+      throw error;
+    }
+
+    const state = await this.toolCaller.callTool<FeatureStatePayload>(
+      'orchestrator',
+      TOOLS.FEATURE_STATE_GET,
+      {
+        feature_id: featureId,
+      },
+    );
+    const expectedVersion = asVersion(state.data.front_matter.version);
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: featureId,
+      expected_version: expectedVersion,
+      patch: {
+        front_matter: {
+          status: STATUS.BLOCKED,
+          status_reason: `${errorCode}: ${message}`,
+        },
+      },
+    });
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+      feature_id: featureId,
+      note: JSON.stringify({
+        phase: 'building',
+        decision: 'blocked',
+        error_code: errorCode,
+        reason: message,
+      }),
+    });
+  }
 }

package/apps/control-plane/src/supervisor/planning-wave-executor.ts

@@ -1,6 +1,12 @@
 import { STATUS, TOOLS } from '../core/constants.js';
+import { ERROR_CODES } from '../core/error-codes.js';
 import type { FeatureContextPayload, InitialPlanGenerator, SupervisorToolCaller } from './types.js';
 import { NOOP_WORKER_DECISION_RUNNER, type WorkerDecisionRunner } from './worker-decision-loop.js';
+import type {
+  WorkerMalformedOutputAction,
+  WorkerNoProgressAction,
+  WorkerProviderMode,
+} from '../providers/worker-provider-factory.js';
 
 type AnyRecord = Record<string, unknown>;
 
@@ -8,6 +14,10 @@ interface PlanningWaveExecutorDependencies {
   toolCaller: SupervisorToolCaller;
   planGenerator: InitialPlanGenerator;
   workerDecisionRunner?: WorkerDecisionRunner;
+  providerMode?: WorkerProviderMode;
+  noProgressLimit?: number;
+  noProgressAction?: WorkerNoProgressAction;
+  malformedOutputAction?: WorkerMalformedOutputAction;
 }
 
 interface ReconciliationDecision {
@@ -110,11 +120,23 @@ export class PlanningWaveExecutor {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly planGenerator: InitialPlanGenerator;
   private readonly workerDecisionRunner: WorkerDecisionRunner;
+  private readonly providerMode: WorkerProviderMode;
+  private readonly noProgressLimit: number;
+  private readonly noProgressAction: WorkerNoProgressAction;
+  private readonly malformedOutputAction: WorkerMalformedOutputAction;
+  private readonly noProgressByFeature = new Map<string, number>();
 
   constructor(dependencies: PlanningWaveExecutorDependencies) {
     this.toolCaller = dependencies.toolCaller;
     this.planGenerator = dependencies.planGenerator;
     this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
+    this.providerMode = dependencies.providerMode ?? 'stub';
+    this.noProgressLimit =
+      typeof dependencies.noProgressLimit === 'number' && dependencies.noProgressLimit > 0
+        ? Math.floor(dependencies.noProgressLimit)
+        : 2;
+    this.noProgressAction = dependencies.noProgressAction ?? 'block_feature';
+    this.malformedOutputAction = dependencies.malformedOutputAction ?? 'block_feature';
   }
 
   async run(featureIds: string[]): Promise<void> {
@@ -141,15 +163,22 @@ export class PlanningWaveExecutor {
           'Review feature context and emit PLAN_SUBMISSION/REQUEST/NOTE outputs to advance planning deterministically.',
       });
 
+      const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision);
+      if (shouldSkip) {
+        continue;
+      }
+
       if (decision.planSubmission || existingPlan) {
         continue;
       }
 
-      const plan = await this.planGenerator.generateInitialPlan(featureId);
-      await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
-        feature_id: featureId,
-        plan_json: plan,
-      });
+      if (this.providerMode === 'stub') {
+        const plan = await this.planGenerator.generateInitialPlan(featureId);
+        await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
+          feature_id: featureId,
+          plan_json: plan,
+        });
+      }
     }
   }
 
@@ -326,4 +355,95 @@ export class PlanningWaveExecutor {
       note: JSON.stringify(note),
     });
   }
+
+  private async enforceWorkerExecutionPolicy(
+    featureId: string,
+    decision: {
+      invalidOutput: boolean;
+      noProgress: boolean;
+    },
+  ): Promise<boolean> {
+    if (this.providerMode !== 'live') {
+      this.noProgressByFeature.delete(featureId);
+      return false;
+    }
+
+    if (decision.invalidOutput) {
+      await this.applyWorkerPolicyAction(
+        featureId,
+        this.malformedOutputAction,
+        ERROR_CODES.PROVIDER_OUTPUT_INVALID,
+        'Planner emitted malformed worker outputs',
+      );
+      return true;
+    }
+
+    if (!decision.noProgress) {
+      this.noProgressByFeature.delete(featureId);
+      return false;
+    }
+
+    const currentCount = (this.noProgressByFeature.get(featureId) ?? 0) + 1;
+    this.noProgressByFeature.set(featureId, currentCount);
+    if (currentCount < this.noProgressLimit) {
+      return true;
+    }
+
+    await this.applyWorkerPolicyAction(
+      featureId,
+      this.noProgressAction,
+      ERROR_CODES.PROVIDER_NO_PROGRESS,
+      `Planner made no actionable progress in ${currentCount} consecutive iterations`,
+    );
+    return true;
+  }
+
+  private async applyWorkerPolicyAction(
+    featureId: string,
+    action: WorkerNoProgressAction | WorkerMalformedOutputAction,
+    errorCode: string,
+    message: string,
+  ): Promise<void> {
+    if (action === 'fail_run') {
+      const error = new Error(message) as Error & {
+        code?: string;
+        details?: Record<string, unknown>;
+      };
+      error.code = errorCode;
+      error.details = {
+        feature_id: featureId,
+        retryable: false,
+        requires_human: true,
+      };
+      throw error;
+    }
+
+    const state = await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_GET, {
+      feature_id: featureId,
+    });
+    const frontMatter = asRecord(state.data.front_matter);
+    const expectedVersion =
+      typeof frontMatter.version === 'number' && Number.isFinite(frontMatter.version)
+        ? Math.floor(frontMatter.version)
+        : null;
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: featureId,
+      expected_version: expectedVersion,
+      patch: {
+        front_matter: {
+          status: STATUS.BLOCKED,
+          status_reason: `${errorCode}: ${message}`,
+        },
+      },
+    });
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+      feature_id: featureId,
+      note: JSON.stringify({
+        phase: 'planning',
+        decision: 'blocked',
+        error_code: errorCode,
+        reason: message,
+      }),
+    });
+  }
 }