agentic-orchestrator 0.1.26 → 0.1.28

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

@@ -0,0 +1,217 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ERROR_CODES } from '../core/error-codes.js';
+import { parseFrontMatter } from '../core/frontmatter.js';
+import { runGit } from '../core/git.js';
+import type { AppError } from '../providers/providers.js';
+import type { CliOptions } from './types.js';
+
+interface CheckpointRollbackRecord {
+  checkpoint_id: string;
+  diff_snapshot: string;
+  validation_status: 'valid' | 'invalid' | 'skipped';
+  timestamp: 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;
+}
+
+function asCheckpointRecord(value: unknown): CheckpointRollbackRecord | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const checkpointId =
+    typeof record['checkpoint_id'] === 'string' ? record['checkpoint_id'].trim() : '';
+  const diffSnapshot =
+    typeof record['diff_snapshot'] === 'string' ? record['diff_snapshot'].trim() : '';
+  const timestamp = typeof record['timestamp'] === 'string' ? record['timestamp'] : '';
+  const validationStatus =
+    record['validation_status'] === 'valid' ||
+    record['validation_status'] === 'invalid' ||
+    record['validation_status'] === 'skipped'
+      ? record['validation_status']
+      : null;
+
+  if (!checkpointId || !diffSnapshot || !timestamp || !validationStatus) {
+    return null;
+  }
+
+  return {
+    checkpoint_id: checkpointId,
+    diff_snapshot: diffSnapshot,
+    validation_status: validationStatus,
+    timestamp,
+  };
+}
+
+function throwFileNotFound(details: Record<string, unknown>): never {
+  const error = new Error(ERROR_CODES.FILE_NOT_FOUND) as AppError;
+  error.code = ERROR_CODES.FILE_NOT_FOUND;
+  error.details = details;
+  throw error;
+}
+
+function isPathInside(rootPath: string, targetPath: string): boolean {
+  const root = path.resolve(rootPath);
+  const target = path.resolve(targetPath);
+  if (target === root) {
+    return true;
+  }
+  return target.startsWith(`${root}${path.sep}`);
+}
+
+function normalizeWorktreePath(
+  frontMatter: Record<string, unknown>,
+  repoRoot: string,
+  featureId: string,
+): string {
+  const fromState =
+    typeof frontMatter['worktree_path'] === 'string' &&
+    frontMatter['worktree_path'].trim().length > 0
+      ? frontMatter['worktree_path'].trim()
+      : path.join(repoRoot, '.worktrees', featureId);
+  return path.resolve(fromState);
+}
+
+export class RollbackCommandHandler {
+  private readonly repoRoot: string;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+  }
+
+  async execute(options: CliOptions): Promise<unknown> {
+    const featureId = options.feature_id?.trim() ?? '';
+    if (!featureId) {
+      invalidCliArgs({
+        reason: '--feature-id is required for rollback',
+        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 checkpointId = options.checkpoint?.trim() ?? '';
+    if (!checkpointId) {
+      invalidCliArgs({
+        reason: '--checkpoint is required for rollback',
+        expected: '--checkpoint <checkpoint_id>',
+      });
+    }
+
+    const statePath = path.join(this.repoRoot, '.aop', 'features', featureId, 'state.md');
+    let stateRaw = '';
+    try {
+      stateRaw = await fs.readFile(statePath, 'utf8');
+    } catch {
+      throwFileNotFound({
+        reason: 'Feature state not found',
+        feature_id: featureId,
+        state_path: statePath,
+      });
+    }
+
+    const { frontMatter } = parseFrontMatter(stateRaw);
+    const checkpoints = Array.isArray(frontMatter['checkpoints'])
+      ? frontMatter['checkpoints']
+          .map((entry) => asCheckpointRecord(entry))
+          .filter((entry): entry is CheckpointRollbackRecord => entry != null)
+      : [];
+    const checkpoint = checkpoints.find((entry) => entry.checkpoint_id === checkpointId);
+
+    if (!checkpoint) {
+      invalidCliArgs({
+        reason: 'Checkpoint not found for feature',
+        feature_id: featureId,
+        checkpoint_id: checkpointId,
+      });
+    }
+
+    const checkpointPath = path.resolve(this.repoRoot, checkpoint.diff_snapshot);
+    if (!isPathInside(this.repoRoot, checkpointPath)) {
+      invalidCliArgs({
+        reason: 'Checkpoint diff snapshot resolved outside repository root',
+        checkpoint_path: checkpointPath,
+      });
+    }
+
+    try {
+      await fs.stat(checkpointPath);
+    } catch {
+      throwFileNotFound({
+        reason: 'Checkpoint diff snapshot file not found',
+        feature_id: featureId,
+        checkpoint_id: checkpointId,
+        checkpoint_path: checkpointPath,
+      });
+    }
+
+    const worktreePath = normalizeWorktreePath(frontMatter, this.repoRoot, featureId);
+
+    if (options.dry_run === true) {
+      return {
+        ok: true,
+        data: {
+          command: 'rollback',
+          feature_id: featureId,
+          checkpoint_id: checkpointId,
+          worktree_path: worktreePath,
+          checkpoint_path: checkpointPath,
+          dry_run: true,
+          applied: false,
+          validation_status: checkpoint.validation_status,
+          message: `Rollback preview ready for ${featureId} at ${checkpointId}`,
+        },
+      };
+    }
+
+    const applyResult = await runGit(
+      this.repoRoot,
+      ['apply', '-R', '--whitespace=nowarn', checkpointPath],
+      { cwd: worktreePath },
+    );
+
+    if (applyResult.code !== 0) {
+      const error = new Error(ERROR_CODES.GIT_FAILURE) as AppError;
+      error.code = ERROR_CODES.GIT_FAILURE;
+      error.details = {
+        feature_id: featureId,
+        checkpoint_id: checkpointId,
+        checkpoint_path: checkpointPath,
+        worktree_path: worktreePath,
+        stderr: applyResult.stderr,
+      };
+      throw error;
+    }
+
+    return {
+      ok: true,
+      data: {
+        command: 'rollback',
+        feature_id: featureId,
+        checkpoint_id: checkpointId,
+        worktree_path: worktreePath,
+        checkpoint_path: checkpointPath,
+        dry_run: false,
+        applied: true,
+        validation_status: checkpoint.validation_status,
+        timestamp: checkpoint.timestamp,
+        message: `Rolled back ${featureId} to checkpoint ${checkpointId}`,
+      },
+    };
+  }
+}

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

@@ -4,6 +4,7 @@ import { resolveProviderSelection } from '../providers/providers.js';
 import {
   DefaultWorkerProviderFactory,
   resolveWorkerProviderMode,
+  resolveWorkerProviderObservability,
   resolveWorkerProviderPolicy,
   resolveWorkerProviderRuntime,
   type WorkerProviderFactory,
@@ -88,6 +89,10 @@ export class RunCommandHandler {
       policySnapshot.execution && typeof policySnapshot.execution === 'object'
         ? (policySnapshot.execution as Record<string, unknown>)
         : null;
+    const observabilityPolicy =
+      policySnapshot.observability && typeof policySnapshot.observability === 'object'
+        ? (policySnapshot.observability as Record<string, unknown>)
+        : null;
     const provider = this.workerProviderFactory.create({
       selection,
       mode: resolveWorkerProviderMode(
@@ -97,7 +102,9 @@ export class RunCommandHandler {
       ),
       context: 'run',
       policy: resolveWorkerProviderPolicy(executionPolicy),
+      observability: resolveWorkerProviderObservability(observabilityPolicy),
       runtime: runtimeConfig,
+      repoRoot,
     });
     const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
       max_active_features: maxActiveFeatures ?? 5,
@@ -105,6 +112,7 @@ export class RunCommandHandler {
       run_id: runId,
       owner_instance_id: kernel.instanceId,
       takeover_stale_run: options.takeover_stale_run,
+      execution_mode: options.execution_mode,
     });
 
     const startResult = await supervisor.start(ingested as Array<{ feature_id: string }>);

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

@@ -5,6 +5,7 @@ export enum CliCommand {
   Stop = 'stop',
   Delete = 'delete',
   Cleanup = 'cleanup',
+  Rollback = 'rollback',
   Init = 'init',
   Dashboard = 'dashboard',
   Retry = 'retry',
@@ -19,6 +20,7 @@ export interface CliOptions {
   folder_input?: string;
   feature_id?: string;
   message?: string;
+  checkpoint?: string;
   dry_run?: boolean;
   yes?: boolean;
   remove_worktree?: boolean;
@@ -28,6 +30,7 @@ export interface CliOptions {
   agent_config?: string;
   provider_config_env?: string;
   worker_provider_mode?: 'live' | 'stub';
+  execution_mode?: 'deterministic' | 'interactive';
   transport?: string;
   takeover_stale_run?: boolean;
   batch?: boolean;

package/apps/control-plane/src/core/kernel-types.ts

@@ -0,0 +1,55 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyRecord = Record<string, any>;
+
+export interface KernelContext {
+  actor_type?: string;
+  actor_id?: string;
+}
+
+export interface KernelConfigOverrides {
+  policyPath?: string;
+  gatesPath?: string;
+  agentsPath?: string;
+  adaptersPath?: string;
+}
+
+export interface AgentsRoleConfig {
+  system_prompt_path?: string;
+}
+
+export interface AgentsRuntimeConfig {
+  execution_mode?: 'deterministic' | 'interactive' | string;
+  interactive?: {
+    watchdog_poll_interval_ms?: number;
+    checkpoint_interval_ms?: number;
+    max_uncommitted_changes?: number;
+    validation_on_checkpoint?: boolean;
+    revert_on_violation?: boolean;
+    violation_severity?: 'info' | 'warning' | 'error' | 'critical' | string;
+    shadow_workspace?: {
+      enabled?: boolean;
+      promotion_strategy?: 'atomic' | 'incremental' | string;
+      cleanup_on_failure?: boolean;
+      max_shadow_size_mb?: number;
+    };
+  };
+  default_provider?: string;
+  default_model?: string;
+  provider_config_env?: string;
+  default_agent_config?: Record<string, unknown>;
+  provider_configs?: Record<string, Record<string, unknown>>;
+  worker_provider_mode?: 'live' | 'stub' | string;
+  worker_response_timeout_ms?: number;
+  max_consecutive_no_progress_iterations?: number;
+}
+
+export interface AgentsConfigSnapshot {
+  version?: number;
+  roles?: Record<string, AgentsRoleConfig>;
+  missing_prompt_behavior?: 'ignore' | 'error' | string;
+  runtime?: AgentsRuntimeConfig;
+}
+
+export interface PolicyConfigSnapshot extends AnyRecord {
+  rbac?: Record<string, string[]>;
+}