agentic-orchestrator 0.1.2 → 0.1.4

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

@@ -0,0 +1,120 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import { STATUS, TOOLS } from '../core/constants.js';
+import type { AppError, WorkerProvider } from '../providers/providers.js';
+import type { AopKernel } from '../core/kernel.js';
+import type { ToolClient } from '../mcp/tool-client.js';
+import type { CliOptions } from './types.js';
+import { callCliTool } from './tooling.js';
+
+interface FeatureStatePayload {
+  front_matter: {
+    status: 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 selectSessionRole(status: string): 'planner' | 'builder' | 'qa' {
+  if (status === STATUS.PLANNING) {
+    return 'planner';
+  }
+  if (status === STATUS.BUILDING) {
+    return 'builder';
+  }
+  return 'qa';
+}
+
+export class AttachCommandHandler {
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+  private readonly kernel: AopKernel;
+  private readonly provider: WorkerProvider;
+
+  constructor(toolClient: ToolClient, runId: string, kernel: AopKernel, provider: WorkerProvider) {
+    this.toolClient = toolClient;
+    this.runId = runId;
+    this.kernel = kernel;
+    this.provider = provider;
+  }
+
+  async execute(options: CliOptions): Promise<unknown> {
+    const featureId = options.feature_id;
+    if (!featureId) {
+      invalidCliArgs({
+        reason: '<feature_id> is required for attach',
+        expected: 'aop attach <feature_id>'
+      });
+    }
+    if (!isValidFeatureId(featureId)) {
+      invalidCliArgs({
+        reason: 'Invalid feature id',
+        provided: featureId,
+        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$'
+      });
+    }
+
+    const runtimeSessions = await this.kernel.getRuntimeSessions();
+    const featureSessions = runtimeSessions.feature_sessions?.[featureId];
+    if (!featureSessions) {
+      invalidCliArgs({
+        reason: `No active session cluster found for ${featureId}`,
+        feature_id: featureId
+      });
+    }
+
+    const rawState = await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_STATE_GET, {
+      feature_id: featureId
+    });
+    const state = rawState.data as unknown as FeatureStatePayload;
+    const status = state.front_matter.status;
+    const role = selectSessionRole(status);
+    const sessionByRole = {
+      planner: featureSessions.planner_session_id,
+      builder: featureSessions.builder_session_id,
+      qa: featureSessions.qa_session_id
+    };
+    const selectedSessionId = sessionByRole[role];
+    const sessionId =
+      selectedSessionId && selectedSessionId !== 'unassigned'
+        ? selectedSessionId
+        : runtimeSessions.orchestrator_session_id;
+
+    if (!sessionId || sessionId === 'unknown' || sessionId === 'unassigned') {
+      invalidCliArgs({
+        reason: `No attachable session found for ${featureId}`,
+        feature_id: featureId
+      });
+    }
+
+    if (typeof this.provider.attachToSession !== 'function') {
+      invalidCliArgs({
+        reason: `Provider ${this.provider.selection.provider} does not support interactive attach`,
+        feature_id: featureId,
+        provider: this.provider.selection.provider
+      });
+    }
+
+    await this.provider.attachToSession(sessionId);
+
+    return {
+      ok: true,
+      data: {
+        command: 'attach',
+        feature_id: featureId,
+        status,
+        role,
+        session_id: sessionId,
+        attached: true
+      }
+    };
+  }
+}

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

@@ -0,0 +1,190 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseFrontMatter } from '../core/frontmatter.js';
+import { TOOLS } from '../core/constants.js';
+import type { ToolClient } from '../mcp/tool-client.js';
+import type { CliOptions } from './types.js';
+import { callCliTool } from './tooling.js';
+
+const DEFAULT_GRACE_PERIOD_SECONDS = 3600;
+const TERMINAL_STATUSES = new Set(['merged', 'failed']);
+
+interface CleanupDetail {
+  feature_id: string;
+  reason: string;
+}
+
+interface FeatureIndex {
+  active?: string[];
+  blocked?: string[];
+  merged?: string[];
+}
+
+export class CleanupCommandHandler {
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+  private readonly repoRoot: string;
+  private readonly gracePeriodSeconds: number;
+  private readonly autoAfterMerge: boolean;
+
+  constructor(
+    toolClient: ToolClient,
+    runId: string,
+    repoRoot: string,
+    gracePeriodSeconds = DEFAULT_GRACE_PERIOD_SECONDS,
+    autoAfterMerge = false
+  ) {
+    this.toolClient = toolClient;
+    this.runId = runId;
+    this.repoRoot = repoRoot;
+    this.gracePeriodSeconds = gracePeriodSeconds;
+    this.autoAfterMerge = autoAfterMerge;
+  }
+
+  private async isRunLeaseInactive(): Promise<boolean> {
+    const runtimeRoot = path.join(this.repoRoot, '.aop', 'runtime');
+    const candidateLeasePaths = [
+      path.join(runtimeRoot, 'default', 'run-lease.json'),
+      path.join(runtimeRoot, 'run-lease.json')
+    ];
+
+    try {
+      const dirs = await fs.readdir(runtimeRoot, { withFileTypes: true });
+      for (const dir of dirs) {
+        if (dir.isDirectory()) {
+          candidateLeasePaths.push(path.join(runtimeRoot, dir.name, 'run-lease.json'));
+        }
+      }
+    } catch {
+      return true;
+    }
+
+    for (const leasePath of candidateLeasePaths) {
+      try {
+        const raw = await fs.readFile(leasePath, 'utf8');
+        const lease = JSON.parse(raw) as { run_id?: string; lease_expires_at?: string };
+        const runId = typeof lease.run_id === 'string' ? lease.run_id : 'none';
+        const leaseExpiresAt = typeof lease.lease_expires_at === 'string' ? lease.lease_expires_at : null;
+        const leaseExpiryMs = leaseExpiresAt ? new Date(leaseExpiresAt).getTime() : NaN;
+        if (runId !== 'none' && Number.isFinite(leaseExpiryMs) && leaseExpiryMs > Date.now()) {
+          return false;
+        }
+      } catch {
+        // Try next candidate lease file
+      }
+    }
+    return true;
+  }
+
+  async execute(options: CliOptions): Promise<unknown> {
+    const dryRun = options.dry_run ?? false;
+    const yes = options.yes ?? false;
+
+    const indexPath = path.join(this.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; nothing to clean
+    }
+
+    const allIndexedIds = new Set([
+      ...(indexData.active ?? []),
+      ...(indexData.blocked ?? []),
+      ...(indexData.merged ?? [])
+    ]);
+
+    const eligible: CleanupDetail[] = [];
+    const skipped: CleanupDetail[] = [];
+    const runLeaseInactive = await this.isRunLeaseInactive();
+
+    // Evaluate active + blocked (+ merged when auto_after_merge) for terminal status past grace period.
+    const candidateIds = [
+      ...(indexData.active ?? []),
+      ...(indexData.blocked ?? []),
+      ...(this.autoAfterMerge ? (indexData.merged ?? []) : [])
+    ];
+    for (const featureId of candidateIds) {
+      const statePath = path.join(this.repoRoot, '.aop', 'features', featureId, 'state.md');
+      try {
+        const raw = await fs.readFile(statePath, 'utf8');
+        const parsed = parseFrontMatter(raw);
+        const fm = parsed.frontMatter as { status?: string; last_updated?: string };
+        if (TERMINAL_STATUSES.has(fm.status ?? '') && fm.last_updated) {
+          const ageSeconds = (Date.now() - new Date(fm.last_updated).getTime()) / 1000;
+          if (ageSeconds > this.gracePeriodSeconds && runLeaseInactive) {
+            eligible.push({ feature_id: featureId, reason: `terminal status: ${fm.status}` });
+            continue;
+          }
+          if (!runLeaseInactive) {
+            skipped.push({ feature_id: featureId, reason: 'run lease still active' });
+            continue;
+          }
+        }
+        skipped.push({ feature_id: featureId, reason: 'not eligible' });
+      } catch {
+        if (this.autoAfterMerge && (indexData.merged ?? []).includes(featureId) && runLeaseInactive) {
+          eligible.push({ feature_id: featureId, reason: 'merged residue with missing state' });
+          continue;
+        }
+        skipped.push({ feature_id: featureId, reason: 'state unreadable' });
+      }
+    }
+
+    // Check for orphan worktrees (exist in .worktrees/ but not in index)
+    const worktreesRoot = path.join(this.repoRoot, '.worktrees');
+    try {
+      const entries = await fs.readdir(worktreesRoot, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) {
+          continue;
+        }
+        if (!allIndexedIds.has(entry.name)) {
+          eligible.push({ feature_id: entry.name, reason: 'orphan worktree' });
+        }
+      }
+    } catch {
+      // No worktrees directory; skip orphan check
+    }
+
+    if (dryRun || !yes) {
+      return {
+        ok: true,
+        data: {
+          would_clean: eligible,
+          cleaned: [],
+          skipped
+        }
+      };
+    }
+
+    // Perform actual deletion
+    const cleaned: CleanupDetail[] = [];
+    const failedToClean: CleanupDetail[] = [];
+
+    for (const item of eligible) {
+      try {
+        await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_DELETE, {
+          feature_id: item.feature_id,
+          dry_run: false,
+          confirm: true,
+          remove_worktree: true,
+          remove_branch: 'none'
+        });
+        cleaned.push(item);
+      } catch {
+        failedToClean.push(item);
+      }
+    }
+
+    return {
+      ok: true,
+      data: {
+        would_clean: eligible,
+        cleaned,
+        skipped: [...skipped, ...failedToClean]
+      }
+    };
+  }
+}

package/apps/control-plane/src/cli/cli-argument-parser.ts

@@ -1,5 +1,6 @@
 import { ERROR_CODES } from '../core/error-codes.js';
 import type { AppError } from '../providers/providers.js';
+import { CliCommand } from './types.js';
 import type { CliOptions, ToolTransport } from './types.js';
 
 function parseOptionalBooleanToken(token: string | undefined): boolean | null {
@@ -15,10 +16,14 @@ function parseOptionalBooleanToken(token: string | undefined): boolean | null {
 export class CliArgumentParser {
   parse(argv: string[]): CliOptions {
     const [first, ...rest] = argv;
-    const command = first !== undefined && !first.startsWith('-') ? first : 'run';
-    const tokens = first !== undefined && !first.startsWith('-') ? rest : argv;
+
+    // Treat -h / --help anywhere as the help command
+    const isHelpFlag = first === '--help' || first === '-h';
+    const isKnownCommand = first !== undefined && !first.startsWith('-');
+    const rawCommand = isHelpFlag ? CliCommand.Help : isKnownCommand ? first : CliCommand.Run;
+    const tokens = isHelpFlag || isKnownCommand ? rest : argv;
     const options: CliOptions = {
-      command: command ?? 'run'
+      command: rawCommand ?? CliCommand.Run
     };
 
     for (let index = 0; index < tokens.length; index += 1) {
@@ -45,6 +50,11 @@ export class CliArgumentParser {
         index += 1;
         continue;
       }
+      if (token === '--message') {
+        options.message = next;
+        index += 1;
+        continue;
+      }
       if (token === '--dry-run') {
         const parsed = parseOptionalBooleanToken(next);
         if (parsed === null) {
@@ -96,7 +106,63 @@ export class CliArgumentParser {
       }
       if (token === '--takeover-stale-run') {
         options.takeover_stale_run = true;
+        continue;
+      }
+      if (token === '--batch') {
+        options.batch = true;
+        continue;
+      }
+      if (token === '--summary') {
+        options.summary = true;
+        continue;
+      }
+      if (token === '--auto') {
+        options.auto = true;
+        continue;
+      }
+      if (token === '--force') {
+        options.force = true;
+        continue;
+      }
+      if (token === '--project') {
+        options.project = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--all') {
+        options.all = true;
+        continue;
+      }
+      if (token === '--port') {
+        const parsed = Number(next);
+        if (!isNaN(parsed)) {
+          options.port = parsed;
+          index += 1;
+        }
+        continue;
+      }
+      if (token === '--foreground') {
+        options.foreground = true;
+        continue;
+      }
+      if (token === '--dev') {
+        options.dev = true;
+        continue;
+      }
+      if (token === '--help' || token === '-h') {
+        options.command = CliCommand.Help;
+        continue;
+      }
 
+      if (!token.startsWith('-')) {
+        if ((options.command === CliCommand.Send || options.command === CliCommand.Attach) && !options.feature_id) {
+          options.feature_id = token;
+          continue;
+        }
+        if (options.command === CliCommand.Send && !options.message) {
+          options.message = tokens.slice(index).join(' ');
+          break;
+        }
       }
     }
 

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

@@ -0,0 +1,57 @@
+import { execFile, spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const execFileAsync = promisify(execFile);
+
+export class DashboardCommandHandler {
+  async execute(options: { port?: number; foreground?: boolean; dev?: boolean }): Promise<Record<string, unknown>> {
+    const port = options.port ?? 3000;
+    const repoRoot = path.resolve(__dirname, '../../../../');
+    const dashboardWorkspace = '@aop/web-dashboard';
+    const devMode = options.dev === true;
+    const foreground = options.foreground === true || devMode;
+
+    const env = { ...process.env, PORT: String(port), HOSTNAME: '0.0.0.0', AOP_ROOT: process.cwd() };
+
+    if (devMode) {
+      const child = spawn('npm', ['run', '--workspace', dashboardWorkspace, 'dev'], { cwd: repoRoot, env, stdio: 'inherit' });
+      await new Promise<void>((resolve, reject) => {
+        child.on('close', resolve);
+        child.on('error', reject);
+      });
+      return { ok: true, data: { message: 'Dashboard stopped', port, mode: 'dev' } };
+    }
+
+    await execFileAsync('npm', ['run', '--workspace', dashboardWorkspace, 'build'], { cwd: repoRoot, env });
+
+    if (foreground) {
+      const child = spawn('npm', ['run', '--workspace', dashboardWorkspace, 'start'], { cwd: repoRoot, env, stdio: 'inherit' });
+      await new Promise<void>((resolve, reject) => {
+        child.on('close', resolve);
+        child.on('error', reject);
+      });
+      return { ok: true, data: { message: 'Dashboard stopped', port, mode: 'production' } };
+    }
+
+    const child = spawn('npm', ['run', '--workspace', dashboardWorkspace, 'start'], {
+      cwd: repoRoot,
+      env,
+      detached: true,
+      stdio: 'ignore'
+    });
+    child.unref();
+    return {
+      ok: true,
+      data: {
+        message: `Dashboard started on http://localhost:${port}`,
+        port,
+        background: true,
+        built: true,
+        mode: 'production'
+      }
+    };
+  }
+}

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

@@ -0,0 +1,163 @@
+import { CliCommand } from './types.js';
+
+interface CommandHelp {
+  usage: string;
+  description: string;
+  flags?: Array<{ flag: string; description: string }>;
+}
+
+const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
+  [CliCommand.Run]: {
+    usage: 'aop run [flags]',
+    description: 'Ingest spec files and start the agent supervisor.',
+    flags: [
+      { flag: '-fi <PATH>', description: 'Input spec file path' },
+      { flag: '-fl <PATH>', description: 'Input spec folder path' },
+      { flag: '--batch', description: 'Batch-ingest all specs in the folder (skip already-active features)' },
+      { flag: '--agent-provider <name>', description: 'Override agent provider (claude, codex, gemini, …)' },
+      { flag: '--agent-model <name>', description: 'Override agent model' },
+      { flag: '--agent-config <PATH>', description: 'Path to agent config file' },
+      { flag: '--provider-config-env <var>', description: 'Env var name that holds provider API key' },
+      { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' },
+      { flag: '--takeover-stale-run', description: 'Take over a stale run lease' },
+      { flag: '--project <name>', description: 'Select project from multi-project.yaml' }
+    ]
+  },
+  [CliCommand.Status]: {
+    usage: 'aop status [flags]',
+    description: 'Show live status of all tracked features.',
+    flags: [
+      { flag: '--summary', description: 'Print a condensed one-line-per-feature summary' },
+      { flag: '--all', description: 'Aggregate status across all projects in multi-project.yaml' },
+      { flag: '--project <name>', description: 'Scope to a specific project' }
+    ]
+  },
+  [CliCommand.Resume]: {
+    usage: 'aop resume [flags]',
+    description: 'Resume blocked or stalled features.',
+    flags: [
+      { flag: '--feature-id <id>', description: 'Resume a specific feature' },
+      { flag: '--force', description: 'Force-resume even if the feature is not blocked' },
+      { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' }
+    ]
+  },
+  [CliCommand.Stop]: {
+    usage: 'aop stop',
+    description: 'Signal the running supervisor to stop gracefully.'
+  },
+  [CliCommand.Delete]: {
+    usage: 'aop delete [flags]',
+    description: 'Delete one or all features from the index.',
+    flags: [
+      { flag: '--feature-id <id>', description: 'Feature to delete' },
+      { flag: '--all', description: 'Delete all features' },
+      { flag: '--dry-run', description: 'Preview what would be deleted without making changes' }
+    ]
+  },
+  [CliCommand.Cleanup]: {
+    usage: 'aop cleanup [flags]',
+    description: 'Clean up merged or stale feature state and worktrees.',
+    flags: [
+      { flag: '--feature-id <id>', description: 'Clean up a specific feature' },
+      { flag: '--all', description: 'Clean up all eligible features' },
+      { flag: '--remove-worktree', description: 'Remove the git worktree after cleanup' },
+      { flag: '--remove-branch <none|safe|force>', description: 'Branch removal mode after cleanup' },
+      { flag: '--dry-run', description: 'Preview what would be cleaned without making changes' },
+      { flag: '--yes', description: 'Skip confirmation prompts' }
+    ]
+  },
+  [CliCommand.Init]: {
+    usage: 'aop init [flags]',
+    description: 'Initialise agentic orchestrator configuration in the current directory.',
+    flags: [
+      { flag: '--auto', description: 'Run non-interactively with defaults' },
+      { flag: '--force', description: 'Overwrite existing configuration' }
+    ]
+  },
+  [CliCommand.Dashboard]: {
+    usage: 'aop dashboard [flags]',
+    description: 'Start the web dashboard server.',
+    flags: [
+      { flag: '--port <number>', description: 'Port to listen on (default: 3000)' },
+      { flag: '--foreground', description: 'Keep the server in the foreground' },
+      { flag: '--dev', description: 'Start in Next.js dev mode' }
+    ]
+  },
+  [CliCommand.Retry]: {
+    usage: 'aop retry [flags]',
+    description: 'Retry a failed gate or step for a feature.',
+    flags: [
+      { flag: '--feature-id <id>', description: 'Feature to retry' },
+      { flag: '--force', description: 'Force retry even if the feature is not in a failed state' }
+    ]
+  },
+  [CliCommand.Send]: {
+    usage: 'aop send <feature-id> <message>',
+    description: 'Send a message to an active agent for a feature.',
+    flags: [
+      { flag: '--feature-id <id>', description: 'Target feature (can also be the first positional argument)' },
+      { flag: '--message <text>', description: 'Message to deliver (can also be the remaining positional arguments)' }
+    ]
+  },
+  [CliCommand.Attach]: {
+    usage: 'aop attach <feature-id>',
+    description: 'Attach to the running agent session for a feature (interactive).',
+    flags: [
+      { flag: '--feature-id <id>', description: 'Feature to attach to (can also be the first positional argument)' }
+    ]
+  },
+  [CliCommand.Help]: {
+    usage: 'aop help [command]',
+    description: 'Show this help text, or detailed help for a specific command.',
+    flags: [{ flag: '--help, -h', description: 'Can also be used with any command' }]
+  }
+};
+
+function pad(str: string, width: number): string {
+  return str + ' '.repeat(Math.max(0, width - str.length));
+}
+
+function renderCommand(cmd: CliCommand, help: CommandHelp): string {
+  const lines: string[] = [`  ${pad(cmd, 12)}${help.description}`];
+  return lines.join('\n');
+}
+
+function renderCommandDetail(help: CommandHelp): string {
+  const lines: string[] = [`Usage: ${help.usage}`, '', `  ${help.description}`];
+  if (help.flags && help.flags.length > 0) {
+    lines.push('', 'Flags:');
+    const colWidth = Math.max(...help.flags.map((f) => f.flag.length)) + 4;
+    for (const { flag, description } of help.flags) {
+      lines.push(`  ${pad(flag, colWidth)}${description}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export class HelpCommandHandler {
+  execute(subcommand?: string): { ok: boolean; data: { help: string } } {
+    const target = subcommand as CliCommand | undefined;
+
+    if (target && target in COMMAND_HELP) {
+      const help = renderCommandDetail(COMMAND_HELP[target]);
+      return { ok: true, data: { help } };
+    }
+
+    const header = [
+      'aop — Agentic Orchestrator control plane',
+      '',
+      'Usage: aop <command> [flags]',
+      '',
+      'Commands:'
+    ];
+
+    const commandLines = (Object.entries(COMMAND_HELP) as Array<[CliCommand, CommandHelp]>).map(([cmd, help]) =>
+      renderCommand(cmd, help)
+    );
+
+    const footer = ['', 'Run `aop help <command>` for detailed help on any command.', 'Flags: --help, -h'];
+
+    const help = [...header, ...commandLines, ...footer].join('\n');
+    return { ok: true, data: { help } };
+  }
+}