agentic-orchestrator 0.1.27 → 0.2.0

package/apps/control-plane/src/cli/command-catalog.ts

@@ -0,0 +1,479 @@
+import { CliCommand } from './types.js';
+
+export type CompletionValueSource =
+  | 'execution_mode'
+  | 'feature_id'
+  | 'merge_strategy'
+  | 'project'
+  | 'remove_branch'
+  | 'shell'
+  | 'sync_remote'
+  | 'transport'
+  | 'worker_provider_mode';
+
+export interface FlagDef {
+  aliases: string[];
+  description: string;
+  takesValue: boolean;
+  valueHint?: string;
+  valueSource?: CompletionValueSource;
+  repeatable?: boolean;
+}
+
+export interface CommandDef {
+  usage: string;
+  description: string;
+  flags: FlagDef[];
+  hidden?: boolean;
+}
+
+function flag(
+  aliases: string[],
+  description: string,
+  options: {
+    takesValue?: boolean;
+    valueHint?: string;
+    valueSource?: CompletionValueSource;
+    repeatable?: boolean;
+  } = {},
+): FlagDef {
+  return {
+    aliases,
+    description,
+    takesValue: options.takesValue ?? false,
+    valueHint: options.valueHint,
+    valueSource: options.valueSource,
+    repeatable: options.repeatable ?? false,
+  };
+}
+
+export function formatFlagUsage(definition: FlagDef): string {
+  const flagText = definition.aliases.join(', ');
+  return definition.takesValue && definition.valueHint
+    ? `${flagText} <${definition.valueHint}>`
+    : flagText;
+}
+
+export const COMMAND_CATALOG: Record<CliCommand, CommandDef> = {
+  [CliCommand.Run]: {
+    usage: 'aop run [flags]',
+    description: 'Ingest spec files and start the agent supervisor.',
+    flags: [
+      flag(['-fi', '--fi'], 'Input spec file path', { takesValue: true, valueHint: 'PATH' }),
+      flag(['-fl', '--fl'], 'Input spec folder path', { takesValue: true, valueHint: 'PATH' }),
+      flag(['--batch'], 'Batch-ingest all specs in the folder (skip already-active features)'),
+      flag(['--agent-provider'], 'Override agent provider (claude, codex, gemini, ...)', {
+        takesValue: true,
+        valueHint: 'name',
+      }),
+      flag(['--agent-model'], 'Override agent model', {
+        takesValue: true,
+        valueHint: 'name',
+      }),
+      flag(['--agent-config'], 'Path to agent config file', {
+        takesValue: true,
+        valueHint: 'PATH',
+      }),
+      flag(['--provider-config-env'], 'Env var name used for API-backed provider auth/config', {
+        takesValue: true,
+        valueHint: 'var',
+      }),
+      flag(
+        ['--worker-provider-mode'],
+        'Worker execution mode override (default: live for run/resume)',
+        {
+          takesValue: true,
+          valueHint: 'live|stub',
+          valueSource: 'worker_provider_mode',
+        },
+      ),
+      flag(
+        ['--execution-mode'],
+        'Execution mode override for worker decision flow (default: deterministic)',
+        {
+          takesValue: true,
+          valueHint: 'deterministic|interactive',
+          valueSource: 'execution_mode',
+        },
+      ),
+      flag(['--transport'], 'Tool transport layer (default: mcp)', {
+        takesValue: true,
+        valueHint: 'inprocess|mcp',
+        valueSource: 'transport',
+      }),
+      flag(['--takeover-stale-run'], 'Take over a stale run lease'),
+      flag(['--project'], 'Select project from multi-project.yaml', {
+        takesValue: true,
+        valueHint: 'name',
+        valueSource: 'project',
+      }),
+    ],
+  },
+  [CliCommand.Add]: {
+    usage: 'aop add [flags]',
+    description: 'Enroll new specs or resume an existing feature in the active execution.',
+    flags: [
+      flag(['-fi', '--fi'], 'Input spec file path', { takesValue: true, valueHint: 'PATH' }),
+      flag(['-fl', '--fl'], 'Input spec folder path', { takesValue: true, valueHint: 'PATH' }),
+      flag(['--resume'], 'Resume an existing feature in the active execution', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--transport'], 'Tool transport layer (default: mcp)', {
+        takesValue: true,
+        valueHint: 'inprocess|mcp',
+        valueSource: 'transport',
+      }),
+      flag(['--project'], 'Select project from multi-project.yaml', {
+        takesValue: true,
+        valueHint: 'name',
+        valueSource: 'project',
+      }),
+    ],
+  },
+  [CliCommand.Status]: {
+    usage: 'aop status [flags]',
+    description: 'Show live status of all tracked features.',
+    flags: [
+      flag(['--summary'], 'Print a condensed one-line-per-feature summary'),
+      flag(['--all'], 'Aggregate status across all projects in multi-project.yaml'),
+      flag(['--project'], 'Scope to a specific project', {
+        takesValue: true,
+        valueHint: 'name',
+        valueSource: 'project',
+      }),
+    ],
+  },
+  [CliCommand.Questions]: {
+    usage: 'aop questions [flags]',
+    description: 'List persisted human-input questions for a feature.',
+    flags: [
+      flag(['--feature-id'], 'Feature whose questions should be listed', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--status'], 'Filter question status (default: open)', {
+        takesValue: true,
+        valueHint: 'open|answered|expired|withdrawn|all',
+      }),
+      flag(['--project'], 'Scope to a specific project', {
+        takesValue: true,
+        valueHint: 'name',
+        valueSource: 'project',
+      }),
+    ],
+  },
+  [CliCommand.Answer]: {
+    usage: 'aop answer [flags]',
+    description: 'Answer a persisted blocking question and resume the feature.',
+    flags: [
+      flag(['--feature-id'], 'Feature that owns the question', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--question-id'], 'Question id to answer', {
+        takesValue: true,
+        valueHint: 'id',
+      }),
+      flag(['--answer'], 'Answer value (plain text or JSON object string)', {
+        takesValue: true,
+        valueHint: 'value',
+      }),
+      flag(['--answered-by'], 'Operator identity recorded on the answer', {
+        takesValue: true,
+        valueHint: 'id',
+      }),
+      flag(['--project'], 'Scope to a specific project', {
+        takesValue: true,
+        valueHint: 'name',
+        valueSource: 'project',
+      }),
+    ],
+  },
+  [CliCommand.Resume]: {
+    usage: 'aop resume [flags]',
+    description: 'Resume blocked or stalled features.',
+    flags: [
+      flag(['--feature-id'], 'Resume a specific feature', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--force'], 'Force-resume even if the feature is not blocked'),
+      flag(['--worker-provider-mode'], 'Worker execution mode override (default: live)', {
+        takesValue: true,
+        valueHint: 'live|stub',
+        valueSource: 'worker_provider_mode',
+      }),
+      flag(
+        ['--execution-mode'],
+        'Execution mode override for worker decision flow (default: deterministic)',
+        {
+          takesValue: true,
+          valueHint: 'deterministic|interactive',
+          valueSource: 'execution_mode',
+        },
+      ),
+      flag(['--transport'], 'Tool transport layer (default: mcp)', {
+        takesValue: true,
+        valueHint: 'inprocess|mcp',
+        valueSource: 'transport',
+      }),
+    ],
+  },
+  [CliCommand.Stop]: {
+    usage: 'aop stop [flags]',
+    description: 'Stop the dashboard server by terminating listeners on a target port.',
+    flags: [
+      flag(['--port'], 'Port to stop (default: 3000)', {
+        takesValue: true,
+        valueHint: 'number',
+      }),
+      flag(['--project'], 'Use the project default dashboard port', {
+        takesValue: true,
+        valueHint: 'name',
+        valueSource: 'project',
+      }),
+    ],
+  },
+  [CliCommand.Delete]: {
+    usage: 'aop delete [flags]',
+    description: 'Delete one or all features from the index (preview-only unless --yes is set).',
+    flags: [
+      flag(['--feature-id'], 'Feature to delete', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--all'], 'Delete all features'),
+      flag(['--dry-run'], 'Preview what would be deleted without making changes'),
+      flag(['--yes'], 'Required to apply destructive deletion'),
+    ],
+  },
+  [CliCommand.Cleanup]: {
+    usage: 'aop cleanup [flags]',
+    description: 'Clean up merged or stale feature state and worktrees.',
+    flags: [
+      flag(['--feature-id'], 'Clean up a specific feature', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--all'], 'Clean up all eligible features'),
+      flag(['--remove-worktree'], 'Remove the git worktree after cleanup'),
+      flag(['--remove-branch'], 'Branch removal mode after cleanup', {
+        takesValue: true,
+        valueHint: 'none|safe|force',
+        valueSource: 'remove_branch',
+      }),
+      flag(['--dry-run'], 'Preview what would be cleaned without making changes'),
+      flag(['--yes'], 'Skip confirmation prompts'),
+      flag(
+        ['--force'],
+        'Force cleanup of features with expired leases regardless of status (e.g. after a timeout)',
+      ),
+    ],
+  },
+  [CliCommand.Rollback]: {
+    usage: 'aop rollback [flags]',
+    description: 'Rollback a feature worktree by applying the inverse of a checkpoint snapshot.',
+    flags: [
+      flag(['--feature-id'], 'Feature to roll back', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--checkpoint'], 'Checkpoint id to reverse-apply', {
+        takesValue: true,
+        valueHint: 'id',
+      }),
+      flag(['--dry-run'], 'Preview rollback inputs without applying git changes'),
+    ],
+  },
+  [CliCommand.Init]: {
+    usage: 'aop init [flags]',
+    description: 'Initialise agentic orchestrator configuration in the current directory.',
+    flags: [
+      flag(['--auto'], 'Run non-interactively with defaults'),
+      flag(['--force'], 'Overwrite existing configuration'),
+      flag(
+        ['--advanced-policy'],
+        'Generate full explicit policy.yaml with all advanced controls (default: lean policy)',
+      ),
+    ],
+  },
+  [CliCommand.Dashboard]: {
+    usage: 'aop dashboard [flags]',
+    description: 'Start the web dashboard server.',
+    flags: [
+      flag(['--port'], 'Port to listen on (default: 3000)', {
+        takesValue: true,
+        valueHint: 'number',
+      }),
+      flag(['--foreground'], 'Keep the server in the foreground'),
+      flag(['--dev'], 'Start in Next.js dev mode'),
+    ],
+  },
+  [CliCommand.Collision]: {
+    usage: 'aop collision (--allow | --list | --revoke) [flags]',
+    description: 'Approve, inspect, or revoke intentional plan collisions.',
+    flags: [
+      flag(['--allow'], 'Create or reuse an override for the latest unresolved collision record'),
+      flag(['--list'], 'List collision overrides, optionally scoped to a feature'),
+      flag(['--revoke'], 'Revoke an existing collision override by id'),
+      flag(['--feature-id'], 'Primary feature id for allow/list operations', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--with-feature-id'], 'Counterpart feature id for allow operations', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--reason'], 'Operator rationale for approving the overlap', {
+        takesValue: true,
+        valueHint: 'text',
+      }),
+      flag(['--override-id'], 'Override id for revoke operations', {
+        takesValue: true,
+        valueHint: 'id',
+      }),
+      flag(['--resume'], 'Immediately retry the recorded colliding plan after approval'),
+    ],
+  },
+  [CliCommand.Retry]: {
+    usage: 'aop retry [flags]',
+    description: 'Retry a failed gate or step for a feature.',
+    flags: [
+      flag(['--feature-id'], 'Feature to retry', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--force'], 'Force retry even if the feature is not in a failed state'),
+    ],
+  },
+  [CliCommand.Merge]: {
+    usage: 'aop merge [flags]',
+    description: 'Merge a ready_to_merge feature branch into the base branch.',
+    flags: [
+      flag(['--feature-id'], 'Feature to merge (required)', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--strategy', '--merge-strategy'], 'Merge strategy (default: merge_commit)', {
+        takesValue: true,
+        valueHint: 'merge_commit|squash|rebase',
+        valueSource: 'merge_strategy',
+      }),
+      flag(['--commit-message'], 'Commit message (default: "Merge feature <id>")', {
+        takesValue: true,
+        valueHint: 'msg',
+      }),
+      flag(['--approval-token'], 'Approval token (required if policy enforces user approval)', {
+        takesValue: true,
+        valueHint: 'token',
+      }),
+      flag(
+        ['--sync-remote'],
+        'How to handle local/remote mainline divergence. Defaults to "auto", which syncs origin/<base> into local before feature reconciliation. Use "skip" to proceed with local as-is.',
+        {
+          takesValue: true,
+          valueHint: 'auto|skip',
+          valueSource: 'sync_remote',
+        },
+      ),
+    ],
+  },
+  [CliCommand.Send]: {
+    usage: 'aop send <feature-id> <message>',
+    description: 'Send a message to an active agent for a feature.',
+    flags: [
+      flag(['--feature-id'], 'Target feature (can also be the first positional argument)', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--message'], 'Message to deliver (can also be the remaining positional arguments)', {
+        takesValue: true,
+        valueHint: 'text',
+      }),
+    ],
+  },
+  [CliCommand.Attach]: {
+    usage: 'aop attach <feature-id>',
+    description: 'Attach to the running agent session for a feature (interactive).',
+    flags: [
+      flag(['--feature-id'], 'Feature to attach to (can also be the first positional argument)', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+    ],
+  },
+  [CliCommand.Help]: {
+    usage: 'aop help [command]',
+    description: 'Show this help text, or detailed help for a specific command.',
+    flags: [flag(['--help', '-h'], 'Can also be used with any command')],
+  },
+  [CliCommand.Replay]: {
+    usage: 'aop replay [flags]',
+    description: 'Query the deterministic replay timeline for a run.',
+    flags: [
+      flag(['--run-id'], 'Run ID to query (required)', {
+        takesValue: true,
+        valueHint: 'id',
+      }),
+      flag(['--from-sequence'], 'Return entries with sequence >= N', {
+        takesValue: true,
+        valueHint: 'N',
+      }),
+      flag(['--limit'], 'Maximum number of entries to return', {
+        takesValue: true,
+        valueHint: 'N',
+      }),
+      flag(['--feature-id'], 'Filter entries to a specific feature_id', {
+        takesValue: true,
+        valueHint: 'id',
+        valueSource: 'feature_id',
+      }),
+      flag(['--tool'], 'Filter entries to a specific tool_name', {
+        takesValue: true,
+        valueHint: 'name',
+      }),
+      flag(['--json'], 'Emit raw JSON response from replay.timeline_get'),
+    ],
+  },
+  [CliCommand.Completion]: {
+    usage: 'aop completion <bash|zsh|fish>',
+    description: 'Print shell completion registration script for the given shell.',
+    flags: [],
+  },
+  [CliCommand.InternalComplete]: {
+    usage: 'aop __complete <shell> <cword> [tokens...]',
+    description: 'Internal tab-completion backend (not intended for direct use).',
+    flags: [],
+    hidden: true,
+  },
+};
+
+export function getPublicCommands(): string[] {
+  return (Object.entries(COMMAND_CATALOG) as Array<[CliCommand, CommandDef]>)
+    .filter(([, definition]) => !definition.hidden)
+    .map(([command]) => command);
+}
+
+export function getCommandFlags(command: string): FlagDef[] {
+  const definition = COMMAND_CATALOG[command as CliCommand];
+  return definition?.flags ?? [];
+}
+
+export function isPublicCommand(command: string): command is CliCommand {
+  const definition = COMMAND_CATALOG[command as CliCommand];
+  return Boolean(definition && !definition.hidden);
+}

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

@@ -0,0 +1,23 @@
+import { resolveCompletionCandidates } from './completion-resolver.js';
+
+/**
+ * Handles the hidden `aop __complete -- <words>` backend.
+ *
+ * Always succeeds (exit 0) and returns an empty candidate list on any error,
+ * so that tab-completion degrades gracefully without breaking the shell.
+ */
+export class CompleteCommandHandler {
+  constructor(private readonly cwd: string = process.cwd()) {}
+
+  /**
+   * @param shellArgs - The raw argv passed to the hidden `aop __complete` backend.
+   * @returns Newline-delimited completion candidates.
+   */
+  resolve(shellArgs: string[]): string[] {
+    try {
+      return resolveCompletionCandidates(shellArgs, this.cwd);
+    } catch {
+      return [];
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { AppError } from '../providers/providers.js';
+import { SUPPORTED_SHELLS, renderShellCompletion } from './completion-shell-renderer.js';
+import type { SupportedShell } from './completion-shell-renderer.js';
+
+export class CompletionCommandHandler {
+  execute(shell: string | undefined): { ok: true; data: { script: string } } {
+    if (!shell || !(SUPPORTED_SHELLS as string[]).includes(shell)) {
+      const error = new Error(
+        `Unsupported shell: ${shell ?? '(none)'}. Supported: ${SUPPORTED_SHELLS.join(', ')}`,
+      ) as AppError;
+      error.code = ERROR_CODES.INVALID_CLI_ARGS;
+      error.details = {
+        provided: shell,
+        supported: SUPPORTED_SHELLS,
+      };
+      throw error;
+    }
+
+    return {
+      ok: true,
+      data: { script: renderShellCompletion(shell as SupportedShell) },
+    };
+  }
+}