agentic-orchestrator 0.1.2 → 0.1.4

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

@@ -0,0 +1,138 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import { TOOLS } from '../core/constants.js';
+import type { AppError } from '../providers/providers.js';
+import type { ToolClient } from '../mcp/tool-client.js';
+import type { CliOptions } from './types.js';
+import { callCliTool } from './tooling.js';
+
+interface RetryFeatureStatePayload {
+  front_matter: {
+    version: number;
+    status?: string;
+    status_reason?: string;
+    evidence?: {
+      last_gate_mode?: string;
+    };
+  };
+}
+
+function isValidFeatureId(value: string): boolean {
+  return /^[a-z0-9_][a-z0-9_-]*$/.test(value);
+}
+
+function invalidCliArgs(details: Record<string, unknown>): never {
+  const error = new Error(ERROR_CODES.INVALID_CLI_ARGS) as AppError;
+  error.code = ERROR_CODES.INVALID_CLI_ARGS;
+  error.details = details;
+  throw error;
+}
+
+export class RetryCommandHandler {
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+
+  constructor(toolClient: ToolClient, runId: string) {
+    this.toolClient = toolClient;
+    this.runId = runId;
+  }
+
+  async execute(options: CliOptions): Promise<unknown> {
+    const featureId = options.feature_id;
+    if (!featureId) {
+      invalidCliArgs({
+        reason: '--feature-id is required for retry',
+        expected: '--feature-id <feature_id>'
+      });
+    }
+    if (!isValidFeatureId(featureId)) {
+      invalidCliArgs({
+        reason: 'Invalid --feature-id value',
+        provided: featureId,
+        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$'
+      });
+    }
+
+    const force = options.force === true;
+    let retryCountReset = false;
+    let retryExecuted: boolean;
+    let forcedRetryExecuted = false;
+    let retryMode: string | null;
+    let retryOutcome: string | null;
+
+    const current = await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_STATE_GET, {
+      feature_id: featureId
+    });
+    const statePayload = current.data as unknown as RetryFeatureStatePayload;
+
+    const status = statePayload.front_matter.status ?? '';
+    const lastGateMode = statePayload.front_matter.evidence?.last_gate_mode;
+    const inferredMode =
+      typeof lastGateMode === 'string' && lastGateMode.length > 0
+        ? lastGateMode
+        : status === 'building'
+          ? 'fast'
+          : status === 'qa' || status === 'ready_to_merge'
+            ? 'full'
+            : status === 'blocked' && statePayload.front_matter.status_reason?.includes('forced_retry:fast')
+              ? 'fast'
+              : 'full';
+
+    if (!force && (status === 'merged' || status === 'failed')) {
+      invalidCliArgs({
+        reason: 'Cannot retry a terminal feature status without --force',
+        status,
+        expected_status: ['building', 'qa', 'ready_to_merge', 'blocked']
+      });
+    }
+
+    if (force) {
+      const frontMatterPatch: Record<string, unknown> = {
+        gate_retry_count: 0,
+        last_retry_at: null
+      };
+      if (status === 'blocked') {
+        frontMatterPatch.status =
+          inferredMode === 'fast'
+            ? 'building'
+            : inferredMode === 'full'
+              ? 'qa'
+              : inferredMode === 'merge'
+                ? 'ready_to_merge'
+                : 'qa';
+        frontMatterPatch.status_reason = `forced_retry:${inferredMode}`;
+      }
+
+      await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_STATE_PATCH, {
+        feature_id: featureId,
+        expected_version: statePayload.front_matter.version,
+        patch: {
+          front_matter: frontMatterPatch
+        }
+      });
+      retryCountReset = true;
+      forcedRetryExecuted = true;
+    }
+
+    const gate = await callCliTool(this.toolClient, this.runId, TOOLS.GATES_RUN, {
+      feature_id: featureId,
+      profile: null,
+      mode: inferredMode
+    });
+    retryMode = inferredMode;
+    const gateData = gate.data as { overall?: string };
+    retryOutcome = typeof gateData.overall === 'string' ? gateData.overall : null;
+    retryExecuted = true;
+
+    return {
+      ok: true,
+      data: {
+        feature_id: featureId,
+        retry_count_reset: retryCountReset,
+        retry_executed: retryExecuted,
+        forced_retry_executed: forcedRetryExecuted,
+        retry_mode: retryMode,
+        retry_outcome: retryOutcome
+      }
+    };
+  }
+}

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

@@ -1,10 +1,15 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { resolveProviderSelection, NullWorkerProvider } from '../providers/providers.js';
 import { SupervisorRuntime } from '../supervisor/runtime.js';
+import { TOOLS } from '../core/constants.js';
 import type { AopKernel } from '../core/kernel.js';
 import type { ToolClient } from '../mcp/tool-client.js';
 import type { CliOptions, ToolTransport } from './types.js';
 import { SpecInputResolver } from './spec-input-resolver.js';
 import { SpecIngestionService } from './spec-ingestion-service.js';
+import { isCanonicalSpecPath, canonicalFeatureIdFromPath } from './spec-utils.js';
+import { callCliTool } from './tooling.js';
 
 export interface RunCommandContext {
   repoRoot: string;
@@ -14,11 +19,45 @@ export interface RunCommandContext {
   options: CliOptions;
   kernel: AopKernel;
   toolClient: ToolClient;
+  maxActiveFeatures?: number;
+  maxParallelGateRuns?: number;
+}
+
+interface BatchDetail {
+  feature_id: string;
+  status: string;
+  reason?: string;
+}
+
+interface FeatureIndex {
+  active?: string[];
+  blocked?: string[];
 }
 
 export class RunCommandHandler {
+  private readonly spawnDelayMs: number;
+
+  constructor(spawnDelayMs = 500) {
+    this.spawnDelayMs = spawnDelayMs;
+  }
+
   async execute(context: RunCommandContext): Promise<unknown> {
-    const { repoRoot, env, runId, transport, options, kernel, toolClient } = context;
+    const {
+      repoRoot,
+      env,
+      runId,
+      transport,
+      options,
+      kernel,
+      toolClient,
+      maxActiveFeatures,
+      maxParallelGateRuns
+    } = context;
+
+    if (options.batch && options.folder_input) {
+      return await this.executeBatch(context);
+    }
+
     const specResolver = new SpecInputResolver(repoRoot, toolClient, runId);
     const ingestionService = new SpecIngestionService(repoRoot, toolClient, runId);
 
@@ -33,9 +72,10 @@ export class RunCommandHandler {
 
     const provider = new NullWorkerProvider(selection);
     const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
-      max_active_features: 5,
-      max_parallel_gate_runs: 3,
+      max_active_features: maxActiveFeatures ?? 5,
+      max_parallel_gate_runs: maxParallelGateRuns ?? 3,
       run_id: runId,
+      owner_instance_id: kernel.instanceId,
       takeover_stale_run: options.takeover_stale_run
     });
 
@@ -54,4 +94,76 @@ export class RunCommandHandler {
       }
     };
   }
+
+  private async executeBatch(context: RunCommandContext): Promise<unknown> {
+    const { repoRoot, runId, options, toolClient } = context;
+    const specResolver = new SpecInputResolver(repoRoot, toolClient, runId);
+
+    let allPaths: string[] = [];
+    try {
+      allPaths = await specResolver.resolve(options);
+    } catch {
+      // Empty folder is acceptable in batch mode
+    }
+
+    const indexPath = path.join(repoRoot, '.aop', 'features', 'index.json');
+    let indexData: FeatureIndex = {};
+    try {
+      const raw = await fs.readFile(indexPath, 'utf8');
+      indexData = JSON.parse(raw) as FeatureIndex;
+    } catch {
+      // No index yet; treat everything as new
+    }
+
+    const activeBlocked = new Set([...(indexData.active ?? []), ...(indexData.blocked ?? [])]);
+
+    const details: BatchDetail[] = [];
+    let created = 0;
+    let skipped = 0;
+    let failed = 0;
+    let isFirst = true;
+
+    for (const specPath of allPaths) {
+      const canonical = isCanonicalSpecPath(repoRoot, specPath);
+      let featureId: string;
+      try {
+        featureId = canonical ?? canonicalFeatureIdFromPath(specPath);
+      } catch {
+        failed++;
+        details.push({ feature_id: specPath, status: 'failed', reason: 'invalid feature id' });
+        continue;
+      }
+
+      if (activeBlocked.has(featureId)) {
+        skipped++;
+        details.push({ feature_id: featureId, status: 'skipped', reason: 'already active/blocked' });
+        continue;
+      }
+
+      if (!isFirst) {
+        await new Promise<void>((resolve) => setTimeout(resolve, this.spawnDelayMs));
+      }
+      isFirst = false;
+
+      try {
+        await callCliTool(toolClient, runId, TOOLS.FEATURE_INIT, { feature_id: featureId });
+        created++;
+        details.push({ feature_id: featureId, status: 'created' });
+      } catch {
+        failed++;
+        details.push({ feature_id: featureId, status: 'failed', reason: 'init failed' });
+      }
+    }
+
+    return {
+      ok: true,
+      data: {
+        command: 'batch-run',
+        created,
+        skipped,
+        failed,
+        details
+      }
+    };
+  }
 }

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

@@ -0,0 +1,65 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import { TOOLS } from '../core/constants.js';
+import type { AppError } from '../providers/providers.js';
+import type { ToolClient } from '../mcp/tool-client.js';
+import type { CliOptions } from './types.js';
+import { callCliTool } from './tooling.js';
+
+function isValidFeatureId(value: string): boolean {
+  return /^[a-z0-9_][a-z0-9_-]*$/.test(value);
+}
+
+function invalidCliArgs(details: Record<string, unknown>): never {
+  const error = new Error(ERROR_CODES.INVALID_CLI_ARGS) as AppError;
+  error.code = ERROR_CODES.INVALID_CLI_ARGS;
+  error.details = details;
+  throw error;
+}
+
+export class SendCommandHandler {
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+
+  constructor(toolClient: ToolClient, runId: string) {
+    this.toolClient = toolClient;
+    this.runId = runId;
+  }
+
+  async execute(options: CliOptions): Promise<unknown> {
+    const featureId = options.feature_id;
+    if (!featureId) {
+      invalidCliArgs({
+        reason: '--feature-id is required for send',
+        expected: '--feature-id <feature_id>'
+      });
+    }
+    if (!isValidFeatureId(featureId)) {
+      invalidCliArgs({
+        reason: 'Invalid --feature-id value',
+        provided: featureId,
+        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$'
+      });
+    }
+
+    const message = options.message;
+    if (!message || message.trim().length === 0) {
+      invalidCliArgs({
+        reason: '--message is required for send',
+        expected: '--message <message>'
+      });
+    }
+
+    const response = await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_SEND_MESSAGE, {
+      feature_id: featureId,
+      message
+    });
+
+    return {
+      ok: true,
+      data: {
+        command: 'send',
+        ...(response.data ?? {})
+      }
+    };
+  }
+}

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

@@ -2,6 +2,67 @@ import {TOOLS} from '../core/constants.js';
 import type {ToolClient} from '../mcp/tool-client.js';
 import {callCliTool} from './tooling.js';
 
+interface ProjectStatusEntry {
+  name: string;
+  path: string;
+  status: unknown;
+}
+
+export interface StatusOptions {
+  summary?: boolean;
+  all?: boolean;
+  projectStatuses?: ProjectStatusEntry[];
+}
+
+type ActivityState = 'active' | 'idle' | 'unknown';
+type ExtendedActivityState = ActivityState | 'waiting_input' | 'blocked' | 'exited';
+
+const ACTIVITY_IDLE_THRESHOLD_MS = 300_000;
+
+interface DashboardFeature {
+  feature_id: string;
+  status?: string;
+  last_heartbeat_at?: string;
+  last_run_at?: string;
+  activity_state?: ExtendedActivityState;
+  activity_last_event_at?: string;
+  activity_detected_via?: 'jsonl' | 'ledger' | 'process' | 'unknown';
+  pr?: {
+    number: number;
+    url: string;
+    ci_status: string;
+    review_decision: string;
+    merge_ready: boolean;
+    pending_review_threads: number;
+    has_conflicts: boolean;
+    merge_score: number;
+  };
+}
+
+interface DashboardData {
+  features?: DashboardFeature[];
+}
+
+function computeFeatureActivity(feature: DashboardFeature): ExtendedActivityState {
+  if (
+    feature.activity_state === 'active' ||
+    feature.activity_state === 'idle' ||
+    feature.activity_state === 'waiting_input' ||
+    feature.activity_state === 'blocked' ||
+    feature.activity_state === 'exited' ||
+    feature.activity_state === 'unknown'
+  ) {
+    return feature.activity_state;
+  }
+
+  const timestamp = feature.activity_last_event_at ?? feature.last_heartbeat_at ?? feature.last_run_at;
+  if (!timestamp) {
+    return 'unknown';
+  }
+  const elapsed = Date.now() - new Date(timestamp).getTime();
+  return elapsed <= ACTIVITY_IDLE_THRESHOLD_MS ? 'active' : 'idle';
+}
+
 export class StatusCommandHandler {
   private readonly toolClient: ToolClient;
   private readonly runId: string;
@@ -11,7 +72,46 @@ export class StatusCommandHandler {
     this.runId = runId;
   }
 
-  async execute(): Promise<unknown> {
-    return await callCliTool(this.toolClient, this.runId, TOOLS.REPORT_DASHBOARD, {});
+  async execute(options?: StatusOptions): Promise<unknown> {
+    // If --all with pre-fetched project statuses, return aggregate result
+    if (options?.all && options.projectStatuses) {
+      return {
+        ok: true,
+        data: {
+          projects: options.projectStatuses
+        }
+      };
+    }
+
+    const result = await callCliTool(this.toolClient, this.runId, TOOLS.REPORT_DASHBOARD, {});
+
+    if (options?.summary) {
+      const data = result.data as unknown as DashboardData;
+      const features = data?.features ?? [];
+      return {
+        ok: true,
+        data: {
+          summary: features.map((f) => ({
+            feature_id: f.feature_id,
+            status: f.status ?? 'unknown',
+            activity: computeFeatureActivity(f)
+          }))
+        }
+      };
+    }
+
+    const dashboardData = result.data as unknown as DashboardData;
+    const rawFeatures = dashboardData?.features ?? [];
+    return {
+      ok: true,
+      data: {
+        ...result.data,
+        features: rawFeatures.map((f) => ({
+          ...f,
+          activity: computeFeatureActivity(f),
+          ...(f.pr !== undefined ? { pr_info: f.pr } : {})
+        }))
+      }
+    };
   }
 }

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

@@ -1,8 +1,24 @@
+export enum CliCommand {
+  Run = 'run',
+  Status = 'status',
+  Resume = 'resume',
+  Stop = 'stop',
+  Delete = 'delete',
+  Cleanup = 'cleanup',
+  Init = 'init',
+  Dashboard = 'dashboard',
+  Retry = 'retry',
+  Send = 'send',
+  Attach = 'attach',
+  Help = 'help'
+}
+
 export interface CliOptions {
-  command: string;
+  command: CliCommand | string;
   file_input?: string;
   folder_input?: string;
   feature_id?: string;
+  message?: string;
   dry_run?: boolean;
   yes?: boolean;
   remove_worktree?: boolean;
@@ -13,6 +29,15 @@ export interface CliOptions {
   provider_config_env?: string;
   transport?: string;
   takeover_stale_run?: boolean;
+  batch?: boolean;
+  summary?: boolean;
+  auto?: boolean;
+  force?: boolean;
+  project?: string;
+  all?: boolean;
+  port?: number;
+  foreground?: boolean;
+  dev?: boolean;
 }
 
 export type RemoveBranchMode = 'none' | 'safe' | 'force';

package/apps/control-plane/src/core/constants.ts

@@ -7,7 +7,8 @@ export const STATUS = {
   BLOCKED: 'blocked',
   READY_TO_MERGE: 'ready_to_merge',
   MERGED: 'merged',
-  FAILED: 'failed'
+  FAILED: 'failed',
+  PAUSED_BUDGET: 'paused_budget'
 } as const;
 
 export type FeatureStatus = (typeof STATUS)[keyof typeof STATUS];
@@ -47,7 +48,12 @@ export const TOOLS = {
   LOCKS_RELEASE: 'locks.release',
   COLLISIONS_SCAN: 'collisions.scan',
   REPORT_DASHBOARD: 'report.dashboard',
-  REPORT_FEATURE_SUMMARY: 'report.feature_summary'
+  REPORT_FEATURE_SUMMARY: 'report.feature_summary',
+  FEATURE_SEND_MESSAGE: 'feature.send_message',
+  COST_RECORD: 'cost.record',
+  COST_GET: 'cost.get',
+  PERFORMANCE_RECORD_OUTCOME: 'performance.record_outcome',
+  PERFORMANCE_GET_ANALYTICS: 'performance.get_analytics'
 } as const;
 
 export const DEFAULT_CLUSTER = {

package/apps/control-plane/src/core/error-codes.ts

@@ -44,7 +44,9 @@ export const ERROR_CODES = {
   PATCH_POLICY_VIOLATION: 'patch_policy_violation',
   FILE_NOT_FOUND: 'file_not_found',
   INVALID_ARGUMENT: 'invalid_argument',
-  INTERNAL_ERROR: 'internal_error'
+  INTERNAL_ERROR: 'internal_error',
+  DEPENDENCY_UNRESOLVED: 'dependency_unresolved',
+  DEPENDENCY_CIRCULAR: 'dependency_circular'
 } as const;
 
 export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];