agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/src/cli/replay-command-handler.ts

@@ -0,0 +1,98 @@
+import type { ToolClient } from '../mcp/tool-client.js';
+import { TOOLS } from '../core/constants.js';
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { AppError } from '../providers/providers.js';
+import { callCliTool } from './tooling.js';
+
+export interface ReplayOptions {
+  runId?: string;
+  fromSequence?: number;
+  limit?: number;
+  featureId?: string;
+  toolFilter?: string;
+  jsonOutput?: boolean;
+}
+
+interface TimelineEntry {
+  ts: string;
+  sequence: number;
+  run_id: string;
+  session_id: string;
+  actor_type: string;
+  feature_id: string | null;
+  tool_name: string;
+  mutating: boolean;
+  operation_id: string | null;
+  idempotency_status: string;
+  request_hash: string | null;
+  result: string;
+  error_code: string | null;
+  latency_ms: number;
+}
+
+function formatEntry(entry: TimelineEntry): string {
+  const idempotencyBadge =
+    entry.idempotency_status !== 'none' ? ` [${entry.idempotency_status}]` : '';
+  const errorPart = entry.error_code ? ` (${entry.error_code})` : '';
+  const featurePart = entry.feature_id ? ` feature=${entry.feature_id}` : '';
+  const mutatingBadge = entry.mutating ? ' M' : '';
+  return `  #${String(entry.sequence).padStart(4, '0')} ${entry.ts} ${entry.result.toUpperCase()}${mutatingBadge}${idempotencyBadge}${errorPart} ${entry.tool_name}${featurePart} ${entry.latency_ms}ms`;
+}
+
+export class ReplayCommandHandler {
+  readonly toolClient: ToolClient;
+  readonly runId: string;
+
+  constructor(toolClient: ToolClient, runId: string) {
+    this.toolClient = toolClient;
+    this.runId = runId;
+  }
+
+  async execute(options: ReplayOptions): Promise<void> {
+    if (!options.runId) {
+      const err = new Error('--run-id is required for aop replay') as AppError;
+      err.code = ERROR_CODES.INVALID_CLI_ARGS;
+      err.details = { hint: 'Usage: aop replay --run-id <id>' };
+      throw err;
+    }
+
+    const args: Record<string, unknown> = { run_id: options.runId };
+    if (options.fromSequence !== undefined) {
+      args.from_sequence = options.fromSequence;
+    }
+    if (options.limit !== undefined) {
+      args.limit = options.limit;
+    }
+    if (options.featureId !== undefined) {
+      args.feature_id = options.featureId;
+    }
+    if (options.toolFilter !== undefined) {
+      args.tool_name = options.toolFilter;
+    }
+
+    const response = await callCliTool(
+      this.toolClient,
+      this.runId,
+      TOOLS.REPLAY_TIMELINE_GET,
+      args,
+    );
+
+    if (options.jsonOutput) {
+      process.stdout.write(JSON.stringify(response.data) + '\n');
+      return;
+    }
+
+    const data = response.data as { run_id: string; entries: TimelineEntry[]; total: number };
+    process.stdout.write(`Replay timeline for run: ${data.run_id}\n`);
+    process.stdout.write(`Entries: ${data.total}\n\n`);
+
+    if (data.entries.length === 0) {
+      process.stdout.write('  (no entries found)\n');
+      return;
+    }
+
+    for (const entry of data.entries) {
+      process.stdout.write(formatEntry(entry) + '\n');
+    }
+  }
+}

package/apps/control-plane/src/cli/resume-command-handler.ts

@@ -1,17 +1,27 @@
-import { STATUS } from '../core/constants.js';
-import { resolveProviderSelection } from '../providers/providers.js';
+import path from 'node:path';
+import { STATUS, TOOLS } from '../core/constants.js';
+import { ERROR_CODES } from '../core/error-codes.js';
+import { deriveFeatureResumePhase } from '../core/feature-resume-phase.js';
+import {
+  resolveProviderSelection,
+  resolveProviderSelectionsByRole,
+  validateRoleProviderCompatibility,
+  type AppError,
+} from '../providers/providers.js';
 import {
   DefaultWorkerProviderFactory,
   resolveWorkerProviderMode,
   resolveWorkerProviderObservability,
   resolveWorkerProviderPolicy,
   resolveWorkerProviderRuntime,
+  resolvePromptOverlayDir,
   type WorkerProviderFactory,
 } from '../providers/worker-provider-factory.js';
 import { SupervisorRuntime } from '../supervisor/runtime.js';
 import type { AopKernel } from '../core/kernel.js';
 import type { ToolClient } from '../mcp/tool-client.js';
 import type { CliOptions, ToolTransport } from './types.js';
+import { callCliTool } from './tooling.js';
 
 type AnyRecord = Record<string, unknown>;
 
@@ -61,21 +71,23 @@ function asFeatureId(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
-function toResumePhase(status: string): string {
-  if (status === STATUS.BUILDING) {
-    return STATUS.BUILDING;
-  }
-  if (status === STATUS.QA) {
-    return STATUS.QA;
-  }
-  if (status === STATUS.READY_TO_MERGE) {
-    return STATUS.READY_TO_MERGE;
-  }
-  return STATUS.PLANNING;
+function readOpenQuestionCount(frontMatter: AnyRecord): number {
+  const humanInput = asRecord(frontMatter.human_input);
+  const value = humanInput.open_question_count;
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+
+function readResumeStatus(frontMatter: AnyRecord): string | null {
+  const humanInput = asRecord(frontMatter.human_input);
+  return typeof humanInput.resume_status === 'string' && humanInput.resume_status.length > 0
+    ? humanInput.resume_status
+    : null;
 }
 
 function phaseRank(phase: string): number {
   switch (phase) {
+    case STATUS.INTAKE:
+      return -1;
     case STATUS.PLANNING:
       return 0;
     case STATUS.BUILDING:
@@ -93,12 +105,24 @@ function isTerminalStatus(status: string): boolean {
   return status === STATUS.MERGED || status === STATUS.FAILED;
 }
 
+function isGenericResumeBlockedStatus(status: string): boolean {
+  return status === STATUS.READY_TO_MERGE;
+}
+
 interface ResumePlan {
   run_id: string;
   owner_instance_id: string;
   features: ResumeFeature[];
 }
 
+interface ActiveRunEnrollmentResult {
+  mode: 'submitted' | 'already_enrolled';
+  request_id: string | null;
+  request_status: string | null;
+  enrolled_features: string[];
+  already_enrolled_features: string[];
+}
+
 export class ResumeCommandHandler {
   private readonly workerProviderFactory: WorkerProviderFactory;
 
@@ -112,6 +136,37 @@ export class ResumeCommandHandler {
     const requestedFeatureId = asFeatureId(options.feature_id);
     const resumePlan = await this.buildResumePlan(kernel, runId, requestedFeatureId);
 
+    if (requestedFeatureId && resumePlan.features.length === 0) {
+      try {
+        const state = await kernel.featureStateGet(requestedFeatureId);
+        const frontMatter = asRecord(state.data.front_matter);
+        const rawStatus =
+          typeof frontMatter.status === 'string' ? frontMatter.status : STATUS.PLANNING;
+        const status =
+          rawStatus === STATUS.AWAITING_INPUT || readOpenQuestionCount(frontMatter) > 0
+            ? STATUS.AWAITING_INPUT
+            : rawStatus;
+        if (isGenericResumeBlockedStatus(status)) {
+          return {
+            ok: false,
+            error: {
+              code: ERROR_CODES.INVALID_STATUS_TRANSITION,
+              message: `Feature ${requestedFeatureId} is already ready_to_merge and cannot be resumed`,
+              details: {
+                feature_id: requestedFeatureId,
+                status,
+                retryable: false,
+                requires_human: false,
+                suggested_action: 'Use review/merge flow or merge-repair actions instead of resume',
+              },
+            },
+          };
+        }
+      } catch {
+        // Fall through to the existing resumed:false response.
+      }
+    }
+
     if (resumePlan.features.length === 0) {
       return {
         ok: true,
@@ -125,11 +180,69 @@ export class ResumeCommandHandler {
       };
     }
 
+    const runtimeSessions = await kernel.getRuntimeSessions();
+    const hasFreshActiveRun =
+      runtimeSessions.run_id !== 'none' &&
+      runtimeSessions.owner_instance_id !== 'none' &&
+      kernel.isRunLeaseFresh(runtimeSessions);
+    if (hasFreshActiveRun) {
+      const enrollment = await this.enrollIntoActiveRun({
+        repoRoot,
+        runId,
+        toolClient,
+        runtimeSessions,
+        features: resumePlan.features,
+      });
+      return {
+        ok: true,
+        data: {
+          command: 'resume',
+          transport,
+          resumed: true,
+          resumed_features: resumePlan.features,
+          resume_mode:
+            enrollment.mode === 'submitted' ? 'active_run_enrollment' : 'already_enrolled',
+          resume_plan: resumePlan,
+          recovery: recovery.data,
+          active_run: {
+            run_id: runtimeSessions.run_id,
+            owner_instance_id: runtimeSessions.owner_instance_id,
+          },
+          request_id: enrollment.request_id,
+          request_status: enrollment.request_status,
+          enrolled_features: enrollment.enrolled_features,
+          already_enrolled_features: enrollment.already_enrolled_features,
+        },
+      };
+    }
+
     const selection = resolveProviderSelection({
       cli: options as unknown as Record<string, string | undefined>,
       env,
       agentsConfig: kernel.getAgentsConfig(),
     });
+    const roleSelections = resolveProviderSelectionsByRole({
+      cli: options as unknown as Record<string, string | undefined>,
+      env,
+      agentsConfig: kernel.getAgentsConfig(),
+    });
+    const executionModeValue = options.execution_mode;
+    const compatExecutionMode =
+      executionModeValue === 'deterministic' || executionModeValue === 'interactive'
+        ? executionModeValue
+        : null;
+    const compatibility = validateRoleProviderCompatibility(roleSelections, compatExecutionMode);
+    if (!compatibility.valid) {
+      const first = compatibility.errors[0];
+      const error = new Error(first.message) as AppError;
+      error.code = first.code;
+      error.details = {
+        ...first.details,
+        role: first.role,
+        all_errors: compatibility.errors,
+      };
+      throw error;
+    }
 
     const runtimeConfig = resolveWorkerProviderRuntime(kernel.getAgentsConfig().runtime);
     const policySnapshot = kernel.getPolicySnapshot();
@@ -141,6 +254,10 @@ export class ResumeCommandHandler {
       policySnapshot.observability && typeof policySnapshot.observability === 'object'
         ? (policySnapshot.observability as Record<string, unknown>)
         : null;
+    const overlayDir = resolvePromptOverlayDir(
+      repoRoot,
+      kernel.getAgentsConfig().runtime?.prompt_overlay_dir,
+    );
     const provider = this.workerProviderFactory.create({
       selection,
       mode: resolveWorkerProviderMode(
@@ -153,6 +270,7 @@ export class ResumeCommandHandler {
       observability: resolveWorkerProviderObservability(observabilityPolicy),
       runtime: runtimeConfig,
       repoRoot,
+      overlayDir,
     });
     const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
       max_active_features: 5,
@@ -161,6 +279,7 @@ export class ResumeCommandHandler {
       owner_instance_id: resumePlan.owner_instance_id,
       takeover_stale_run: options.takeover_stale_run,
       execution_mode: options.execution_mode,
+      role_selections: roleSelections,
     });
 
     const startResult = await supervisor.start(
@@ -233,16 +352,31 @@ export class ResumeCommandHandler {
       try {
         const state = await kernel.featureStateGet(featureId);
         const frontMatter = asRecord(state.data.front_matter);
-        const status =
+        const rawStatus =
           typeof frontMatter.status === 'string' ? frontMatter.status : STATUS.PLANNING;
-        if (isTerminalStatus(status)) {
+        const status =
+          rawStatus === STATUS.AWAITING_INPUT || readOpenQuestionCount(frontMatter) > 0
+            ? STATUS.AWAITING_INPUT
+            : rawStatus;
+        if (isTerminalStatus(status) || isGenericResumeBlockedStatus(status)) {
           continue;
         }
+        const resumeStatus = readResumeStatus(frontMatter);
 
         resumable.push({
           feature_id: featureId,
           status,
-          resume_phase: toResumePhase(status),
+          resume_phase:
+            status === STATUS.AWAITING_INPUT && resumeStatus !== null
+              ? deriveFeatureResumePhase({
+                  ...frontMatter,
+                  status: STATUS.AWAITING_INPUT,
+                  human_input: {
+                    ...asRecord(frontMatter.human_input),
+                    resume_status: resumeStatus,
+                  },
+                })
+              : deriveFeatureResumePhase(frontMatter),
           sources: [...(sourcesByFeature.get(featureId) ?? new Set<string>())].sort((a, b) =>
             a.localeCompare(b),
           ),
@@ -274,6 +408,87 @@ export class ResumeCommandHandler {
     };
   }
 
+  private canonicalSpecPath(repoRoot: string, featureId: string): string {
+    return path.relative(repoRoot, path.join(repoRoot, '.aop', 'features', featureId, 'spec.md'));
+  }
+
+  private async enrollIntoActiveRun(input: {
+    repoRoot: string;
+    runId: string;
+    toolClient: ToolClient;
+    runtimeSessions: {
+      run_id?: string;
+      owner_instance_id?: string;
+      feature_sessions?: Record<string, unknown>;
+    };
+    features: ResumeFeature[];
+  }): Promise<ActiveRunEnrollmentResult> {
+    const assignedSessions =
+      input.runtimeSessions.feature_sessions &&
+      typeof input.runtimeSessions.feature_sessions === 'object'
+        ? input.runtimeSessions.feature_sessions
+        : {};
+    const alreadyEnrolled = input.features
+      .filter((feature) => Boolean(assignedSessions[feature.feature_id]))
+      .map((feature) => feature.feature_id)
+      .sort((left, right) => left.localeCompare(right));
+    const toEnroll = input.features
+      .filter((feature) => !assignedSessions[feature.feature_id])
+      .sort((left, right) => left.feature_id.localeCompare(right.feature_id));
+
+    if (toEnroll.length === 0) {
+      return {
+        mode: 'already_enrolled',
+        request_id: null,
+        request_status: null,
+        enrolled_features: [],
+        already_enrolled_features: alreadyEnrolled,
+      };
+    }
+
+    try {
+      const submitted = await callCliTool(
+        input.toolClient,
+        input.runId,
+        TOOLS.RUNTIME_EXECUTION_REQUEST_SUBMIT,
+        {
+          run_id: input.runtimeSessions.run_id,
+          owner_instance_id: input.runtimeSessions.owner_instance_id,
+          request_type: 'add_features',
+          features: toEnroll.map((feature) => ({
+            feature_id: feature.feature_id,
+            spec_path: this.canonicalSpecPath(input.repoRoot, feature.feature_id).replaceAll(
+              '\\',
+              '/',
+            ),
+          })),
+        },
+      );
+
+      return {
+        mode: 'submitted',
+        request_id:
+          typeof submitted.data.request_id === 'string' ? submitted.data.request_id : null,
+        request_status:
+          typeof submitted.data.request_status === 'string' ? submitted.data.request_status : null,
+        enrolled_features: toEnroll.map((feature) => feature.feature_id),
+        already_enrolled_features: alreadyEnrolled,
+      };
+    } catch (error) {
+      const appError = error as AppError;
+      if (appError.code !== ERROR_CODES.DUPLICATE_EXECUTION_REQUEST) {
+        throw error;
+      }
+      return {
+        mode: 'submitted',
+        request_id: null,
+        request_status: 'pending',
+        enrolled_features: toEnroll.map((feature) => feature.feature_id),
+        already_enrolled_features: alreadyEnrolled,
+      };
+    }
+  }
+
   private addSource(
     sourcesByFeature: Map<string, Set<string>>,
     featureId: string,