agentic-orchestrator 0.1.6 → 0.1.8

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

@@ -51,14 +51,14 @@ export class AttachCommandHandler {
     if (!featureId) {
       invalidCliArgs({
         reason: '<feature_id> is required for attach',
-        expected: 'aop attach <feature_id>'
+        expected: 'aop attach <feature_id>',
       });
     }
     if (!isValidFeatureId(featureId)) {
       invalidCliArgs({
         reason: 'Invalid feature id',
         provided: featureId,
-        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$'
+        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$',
       });
     }
 
@@ -67,12 +67,12 @@ export class AttachCommandHandler {
     if (!featureSessions) {
       invalidCliArgs({
         reason: `No active session cluster found for ${featureId}`,
-        feature_id: featureId
+        feature_id: featureId,
       });
     }
 
     const rawState = await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_STATE_GET, {
-      feature_id: featureId
+      feature_id: featureId,
     });
     const state = rawState.data as unknown as FeatureStatePayload;
     const status = state.front_matter.status;
@@ -80,7 +80,7 @@ export class AttachCommandHandler {
     const sessionByRole = {
       planner: featureSessions.planner_session_id,
       builder: featureSessions.builder_session_id,
-      qa: featureSessions.qa_session_id
+      qa: featureSessions.qa_session_id,
     };
     const selectedSessionId = sessionByRole[role];
     const sessionId =
@@ -91,7 +91,7 @@ export class AttachCommandHandler {
     if (!sessionId || sessionId === 'unknown' || sessionId === 'unassigned') {
       invalidCliArgs({
         reason: `No attachable session found for ${featureId}`,
-        feature_id: featureId
+        feature_id: featureId,
       });
     }
 
@@ -99,7 +99,7 @@ export class AttachCommandHandler {
       invalidCliArgs({
         reason: `Provider ${this.provider.selection.provider} does not support interactive attach`,
         feature_id: featureId,
-        provider: this.provider.selection.provider
+        provider: this.provider.selection.provider,
       });
     }
 
@@ -113,8 +113,8 @@ export class AttachCommandHandler {
         status,
         role,
         session_id: sessionId,
-        attached: true
-      }
+        attached: true,
+      },
     };
   }
 }

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

@@ -32,7 +32,7 @@ export class CleanupCommandHandler {
     runId: string,
     repoRoot: string,
     gracePeriodSeconds = DEFAULT_GRACE_PERIOD_SECONDS,
-    autoAfterMerge = false
+    autoAfterMerge = false,
   ) {
     this.toolClient = toolClient;
     this.runId = runId;
@@ -45,7 +45,7 @@ export class CleanupCommandHandler {
     const runtimeRoot = path.join(this.repoRoot, '.aop', 'runtime');
     const candidateLeasePaths = [
       path.join(runtimeRoot, 'default', 'run-lease.json'),
-      path.join(runtimeRoot, 'run-lease.json')
+      path.join(runtimeRoot, 'run-lease.json'),
     ];
 
     try {
@@ -64,7 +64,8 @@ export class CleanupCommandHandler {
         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 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;
@@ -92,7 +93,7 @@ export class CleanupCommandHandler {
     const allIndexedIds = new Set([
       ...(indexData.active ?? []),
       ...(indexData.blocked ?? []),
-      ...(indexData.merged ?? [])
+      ...(indexData.merged ?? []),
     ]);
 
     const eligible: CleanupDetail[] = [];
@@ -103,7 +104,7 @@ export class CleanupCommandHandler {
     const candidateIds = [
       ...(indexData.active ?? []),
       ...(indexData.blocked ?? []),
-      ...(this.autoAfterMerge ? (indexData.merged ?? []) : [])
+      ...(this.autoAfterMerge ? (indexData.merged ?? []) : []),
     ];
     for (const featureId of candidateIds) {
       const statePath = path.join(this.repoRoot, '.aop', 'features', featureId, 'state.md');
@@ -124,7 +125,11 @@ export class CleanupCommandHandler {
         }
         skipped.push({ feature_id: featureId, reason: 'not eligible' });
       } catch {
-        if (this.autoAfterMerge && (indexData.merged ?? []).includes(featureId) && runLeaseInactive) {
+        if (
+          this.autoAfterMerge &&
+          (indexData.merged ?? []).includes(featureId) &&
+          runLeaseInactive
+        ) {
           eligible.push({ feature_id: featureId, reason: 'merged residue with missing state' });
           continue;
         }
@@ -154,8 +159,8 @@ export class CleanupCommandHandler {
         data: {
           would_clean: eligible,
           cleaned: [],
-          skipped
-        }
+          skipped,
+        },
       };
     }
 
@@ -170,7 +175,7 @@ export class CleanupCommandHandler {
           dry_run: false,
           confirm: true,
           remove_worktree: true,
-          remove_branch: 'none'
+          remove_branch: 'none',
         });
         cleaned.push(item);
       } catch {
@@ -183,8 +188,8 @@ export class CleanupCommandHandler {
       data: {
         would_clean: eligible,
         cleaned,
-        skipped: [...skipped, ...failedToClean]
-      }
+        skipped: [...skipped, ...failedToClean],
+      },
     };
   }
 }

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

@@ -23,7 +23,7 @@ export class CliArgumentParser {
     const rawCommand = isHelpFlag ? CliCommand.Help : isKnownCommand ? first : CliCommand.Run;
     const tokens = isHelpFlag || isKnownCommand ? rest : argv;
     const options: CliOptions = {
-      command: rawCommand ?? CliCommand.Run
+      command: rawCommand ?? CliCommand.Run,
     };
 
     for (let index = 0; index < tokens.length; index += 1) {
@@ -159,7 +159,10 @@ export class CliArgumentParser {
       }
 
       if (!token.startsWith('-')) {
-        if ((options.command === CliCommand.Send || options.command === CliCommand.Attach) && !options.feature_id) {
+        if (
+          (options.command === CliCommand.Send || options.command === CliCommand.Attach) &&
+          !options.feature_id
+        ) {
           options.feature_id = token;
           continue;
         }
@@ -184,7 +187,7 @@ export class CliArgumentParser {
     error.details = {
       reason: 'Invalid --transport value',
       provided: option,
-      expected: ['inprocess', 'mcp']
+      expected: ['inprocess', 'mcp'],
     };
     throw error;
   }

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

@@ -7,17 +7,30 @@ 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>> {
+  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() };
+    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' });
+      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);
@@ -25,10 +38,17 @@ export class DashboardCommandHandler {
       return { ok: true, data: { message: 'Dashboard stopped', port, mode: 'dev' } };
     }
 
-    await execFileAsync('npm', ['run', '--workspace', dashboardWorkspace, 'build'], { cwd: repoRoot, env });
+    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' });
+      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);
@@ -40,7 +60,7 @@ export class DashboardCommandHandler {
       cwd: repoRoot,
       env,
       detached: true,
-      stdio: 'ignore'
+      stdio: 'ignore',
     });
     child.unref();
     return {
@@ -50,8 +70,8 @@ export class DashboardCommandHandler {
         port,
         background: true,
         built: true,
-        mode: 'production'
-      }
+        mode: 'production',
+      },
     };
   }
 }

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

@@ -40,14 +40,14 @@ export class DeleteCommandHandler {
     if (!featureId) {
       invalidCliArgs({
         reason: '--feature-id is required for delete',
-        expected: '--feature-id <feature_id>'
+        expected: '--feature-id <feature_id>',
       });
     }
     if (!isValidFeatureId(featureId)) {
       invalidCliArgs({
         reason: 'Invalid --feature-id value',
         provided: featureId,
-        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$'
+        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$',
       });
     }
 
@@ -56,14 +56,14 @@ export class DeleteCommandHandler {
       invalidCliArgs({
         reason: 'Invalid --remove-branch value',
         provided: options.remove_branch,
-        expected: ['none', 'safe', 'force']
+        expected: ['none', 'safe', 'force'],
       });
     }
 
     if (options.yes !== true && options.dry_run === false) {
       invalidCliArgs({
         reason: 'Destructive delete requires --yes',
-        expected: 'Provide --yes or omit --dry-run=false'
+        expected: 'Provide --yes or omit --dry-run=false',
       });
     }
 
@@ -76,15 +76,15 @@ export class DeleteCommandHandler {
       dry_run: dryRun,
       confirm,
       remove_worktree: removeWorktree,
-      remove_branch: removeBranch
+      remove_branch: removeBranch,
     });
 
     return {
       ok: true,
       data: {
         command: 'delete',
-        ...(response.data ?? {})
-      }
+        ...(response.data ?? {}),
+      },
     };
   }
 }

package/apps/control-plane/src/cli/env-file.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs/promises';
+
+export type EnvFileValues = Record<string, string>;
+
+const SAFE_UNQUOTED_ENV_VALUE = /^[A-Za-z0-9_./:@+=-]+$/;
+
+function unquoteValue(raw: string): string {
+  const trimmed = raw.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function parseEnvLine(line: string): { key: string; value: string } | null {
+  const trimmed = line.trim();
+  if (trimmed.length === 0 || trimmed.startsWith('#')) {
+    return null;
+  }
+
+  const normalized = trimmed.startsWith('export ') ? trimmed.slice('export '.length) : trimmed;
+  const separatorIndex = normalized.indexOf('=');
+  if (separatorIndex <= 0) {
+    return null;
+  }
+
+  const key = normalized.slice(0, separatorIndex).trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    return null;
+  }
+
+  const value = normalized.slice(separatorIndex + 1);
+  return { key, value: unquoteValue(value) };
+}
+
+function formatEnvValue(value: string): string {
+  if (SAFE_UNQUOTED_ENV_VALUE.test(value)) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+export async function readEnvFileValues(envPath: string): Promise<EnvFileValues> {
+  let content: string;
+  try {
+    content = await fs.readFile(envPath, 'utf8');
+  } catch {
+    return {};
+  }
+
+  const values: EnvFileValues = {};
+  for (const line of content.split(/\r?\n/)) {
+    const parsed = parseEnvLine(line);
+    if (!parsed) {
+      continue;
+    }
+    values[parsed.key] = parsed.value;
+  }
+  return values;
+}
+
+export function readNonEmptyEnvValue(
+  key: string,
+  runtimeEnv: NodeJS.ProcessEnv,
+  envFileValues: EnvFileValues,
+): string | null {
+  const runtimeValue = runtimeEnv[key];
+  if (typeof runtimeValue === 'string' && runtimeValue.trim().length > 0) {
+    return runtimeValue;
+  }
+
+  const fileValue = envFileValues[key];
+  if (typeof fileValue === 'string' && fileValue.trim().length > 0) {
+    return fileValue;
+  }
+
+  return null;
+}
+
+export async function upsertEnvFileValue(
+  envPath: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  let content = '';
+  try {
+    content = await fs.readFile(envPath, 'utf8');
+  } catch {
+    // create file from scratch
+  }
+
+  const lines = content.length > 0 ? content.split(/\r?\n/) : [];
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const matcher = new RegExp(`^\\s*(?:export\\s+)?${escapedKey}\\s*=`);
+  const nextLine = `${key}=${formatEnvValue(value)}`;
+
+  let replaced = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (matcher.test(lines[index])) {
+      lines[index] = nextLine;
+      replaced = true;
+      break;
+    }
+  }
+
+  if (!replaced) {
+    lines.push(nextLine);
+  }
+
+  const normalized = `${lines.join('\n').replace(/\n*$/, '')}\n`;
+  await fs.writeFile(envPath, normalized, 'utf8');
+}

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

@@ -13,15 +13,24 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     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: '--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: '--provider-config-env <var>',
+        description: 'Env var name used for API-backed provider auth/config',
+      },
       { 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' }
-    ]
+      { flag: '--project <name>', description: 'Select project from multi-project.yaml' },
+    ],
   },
   [CliCommand.Status]: {
     usage: 'aop status [flags]',
@@ -29,8 +38,8 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     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' }
-    ]
+      { flag: '--project <name>', description: 'Scope to a specific project' },
+    ],
   },
   [CliCommand.Resume]: {
     usage: 'aop resume [flags]',
@@ -38,12 +47,12 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     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)' }
-    ]
+      { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' },
+    ],
   },
   [CliCommand.Stop]: {
     usage: 'aop stop',
-    description: 'Signal the running supervisor to stop gracefully.'
+    description: 'Signal the running supervisor to stop gracefully.',
   },
   [CliCommand.Delete]: {
     usage: 'aop delete [flags]',
@@ -51,8 +60,8 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     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' }
-    ]
+      { flag: '--dry-run', description: 'Preview what would be deleted without making changes' },
+    ],
   },
   [CliCommand.Cleanup]: {
     usage: 'aop cleanup [flags]',
@@ -61,10 +70,13 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
       { 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: '--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' }
-    ]
+      { flag: '--yes', description: 'Skip confirmation prompts' },
+    ],
   },
   [CliCommand.Init]: {
     usage: 'aop init [flags]',
@@ -72,8 +84,12 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     flags: [
       { flag: '--auto', description: 'Run non-interactively with defaults' },
       { flag: '--force', description: 'Overwrite existing configuration' },
-      { flag: '--advanced-policy', description: 'Generate full explicit policy.yaml with all advanced controls (default: lean policy)' }
-    ]
+      {
+        flag: '--advanced-policy',
+        description:
+          'Generate full explicit policy.yaml with all advanced controls (default: lean policy)',
+      },
+    ],
   },
   [CliCommand.Dashboard]: {
     usage: 'aop dashboard [flags]',
@@ -81,37 +97,46 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     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' }
-    ]
+      { 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' }
-    ]
+      { 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)' }
-    ]
+      {
+        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)' }
-    ]
+      {
+        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' }]
-  }
+    flags: [{ flag: '--help, -h', description: 'Can also be used with any command' }],
+  },
 };
 
 function pad(str: string, width: number): string {
@@ -149,14 +174,18 @@ export class HelpCommandHandler {
       '',
       'Usage: aop <command> [flags]',
       '',
-      'Commands:'
+      'Commands:',
     ];
 
-    const commandLines = (Object.entries(COMMAND_HELP) as Array<[CliCommand, CommandHelp]>).map(([cmd, help]) =>
-      renderCommand(cmd, help)
+    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 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 } };