agentic-orchestrator 0.1.0

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

@@ -0,0 +1,228 @@
+import { STATUS } from '../core/constants.js';
+import { resolveProviderSelection, NullWorkerProvider } from '../providers/providers.js';
+import { SupervisorRuntime } from '../supervisor/runtime.js';
+import type { AopKernel } from '../core/kernel.js';
+import type { ToolClient } from '../mcp/tool-client.js';
+import type { CliOptions, ToolTransport } from './types.js';
+
+type AnyRecord = Record<string, unknown>;
+
+interface ResumeFeature {
+  feature_id: string;
+  status: string;
+  resume_phase: string;
+  sources: string[];
+}
+
+export interface ResumeCommandContext {
+  repoRoot: string;
+  env: NodeJS.ProcessEnv;
+  runId: string;
+  transport: ToolTransport;
+  options: CliOptions;
+  kernel: AopKernel;
+  toolClient: ToolClient;
+}
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const normalized: string[] = [];
+  for (const item of value) {
+    if (typeof item !== 'string') {
+      continue;
+    }
+    const trimmed = item.trim();
+    if (trimmed.length > 0) {
+      normalized.push(trimmed);
+    }
+  }
+  return normalized;
+}
+
+function toResumePhase(status: string): string {
+  if (status === STATUS.BUILDING) {
+    return STATUS.BUILDING;
+  }
+  if (status === STATUS.QA) {
+    return STATUS.QA;
+  }
+  if (status === STATUS.READY_TO_MERGE) {
+    return STATUS.READY_TO_MERGE;
+  }
+  return STATUS.PLANNING;
+}
+
+function phaseRank(phase: string): number {
+  switch (phase) {
+    case STATUS.PLANNING:
+      return 0;
+    case STATUS.BUILDING:
+      return 1;
+    case STATUS.QA:
+      return 2;
+    case STATUS.READY_TO_MERGE:
+      return 3;
+    default:
+      return 99;
+  }
+}
+
+function isTerminalStatus(status: string): boolean {
+  return status === STATUS.MERGED || status === STATUS.FAILED;
+}
+
+interface ResumePlan {
+  run_id: string;
+  owner_instance_id: string;
+  features: ResumeFeature[];
+}
+
+export class ResumeCommandHandler {
+  async execute(context: ResumeCommandContext): Promise<unknown> {
+    const { env, runId, transport, options, kernel, toolClient } = context;
+    const recovery = await kernel.recoverFromState();
+    const resumePlan = await this.buildResumePlan(kernel, runId);
+
+    if (resumePlan.features.length === 0) {
+      return {
+        ok: true,
+        data: {
+          command: 'resume',
+          transport,
+          resumed: false,
+          recovery: recovery.data,
+          resume_plan: resumePlan
+        }
+      };
+    }
+
+    const selection = resolveProviderSelection({
+      cli: options as unknown as Record<string, string | undefined>,
+      env,
+      agentsConfig: kernel.getAgentsConfig()
+    });
+
+    const provider = new NullWorkerProvider(selection);
+    const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
+      max_active_features: 5,
+      max_parallel_gate_runs: 3,
+      run_id: resumePlan.run_id,
+      owner_instance_id: resumePlan.owner_instance_id,
+      takeover_stale_run: options.takeover_stale_run
+    });
+
+    const startResult = await supervisor.start(
+      resumePlan.features.map((feature) => ({
+        feature_id: feature.feature_id
+      }))
+    );
+
+    return {
+      ok: true,
+      data: {
+        command: 'resume',
+        transport,
+        resumed: true,
+        resumed_features: resumePlan.features,
+        queue_depth: startResult.queue_depth,
+        runtime_status: startResult.status,
+        run_metadata: startResult.run_metadata,
+        dashboard: startResult.dashboard,
+        recovery: recovery.data
+      }
+    };
+  }
+
+  private async buildResumePlan(kernel: AopKernel, fallbackRunId: string): Promise<ResumePlan> {
+    const index = await kernel.readIndex();
+    const runtimeSessions = await kernel.getRuntimeSessions();
+    const discovered = await kernel.featureDiscoverSpecs();
+
+    const sourcesByFeature = new Map<string, Set<string>>();
+    for (const featureId of asStringArray(index.active)) {
+      this.addSource(sourcesByFeature, featureId, 'index.active');
+    }
+    for (const featureId of asStringArray(index.blocked)) {
+      this.addSource(sourcesByFeature, featureId, 'index.blocked');
+    }
+    for (const [featureId] of Object.entries(asRecord(runtimeSessions.feature_sessions))) {
+      this.addSource(sourcesByFeature, featureId, 'runtime_sessions.feature_sessions');
+    }
+
+    const blockedQueue = Array.isArray(index.blocked_queue) ? index.blocked_queue : [];
+    for (const entry of blockedQueue) {
+      const featureId = asRecord(entry).feature_id;
+      if (typeof featureId === 'string' && featureId.length > 0) {
+        this.addSource(sourcesByFeature, featureId, 'index.blocked_queue');
+      }
+    }
+
+    const specs = Array.isArray(discovered.data?.specs) ? discovered.data.specs : [];
+    for (const item of specs) {
+      const featureId = asRecord(item).feature_id;
+      if (typeof featureId === 'string' && featureId.length > 0) {
+        this.addSource(sourcesByFeature, featureId, 'feature.discover_specs');
+      }
+    }
+
+    const resumable: ResumeFeature[] = [];
+    const sortedFeatureIds = [...sourcesByFeature.keys()].sort((a, b) => a.localeCompare(b));
+    for (const featureId of sortedFeatureIds) {
+      try {
+        const state = await kernel.featureStateGet(featureId);
+        const frontMatter = asRecord(state.data.front_matter);
+        const status = typeof frontMatter.status === 'string' ? frontMatter.status : STATUS.PLANNING;
+        if (isTerminalStatus(status)) {
+          continue;
+        }
+
+        resumable.push({
+          feature_id: featureId,
+          status,
+          resume_phase: toResumePhase(status),
+          sources: [...(sourcesByFeature.get(featureId) ?? new Set<string>())].sort((a, b) => a.localeCompare(b))
+        });
+      } catch (_error) {
+        continue;
+      }
+    }
+
+    resumable.sort((a, b) => {
+      const phaseDelta = phaseRank(a.resume_phase) - phaseRank(b.resume_phase);
+      if (phaseDelta !== 0) {
+        return phaseDelta;
+      }
+      return a.feature_id.localeCompare(b.feature_id);
+    });
+
+    const resolvedRunId = runtimeSessions.run_id !== 'none' ? runtimeSessions.run_id : fallbackRunId;
+    const resolvedOwnerInstanceId =
+      runtimeSessions.owner_instance_id !== 'none'
+        ? runtimeSessions.owner_instance_id
+        : `supervisor:${process.pid}:resume`;
+
+    return {
+      run_id: resolvedRunId,
+      owner_instance_id: resolvedOwnerInstanceId,
+      features: resumable
+    };
+  }
+
+  private addSource(sourcesByFeature: Map<string, Set<string>>, featureId: string, source: string): void {
+    if (!featureId) {
+      return;
+    }
+    const existing = sourcesByFeature.get(featureId);
+    if (existing) {
+      existing.add(source);
+      return;
+    }
+    sourcesByFeature.set(featureId, new Set([source]));
+  }
+}

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

@@ -0,0 +1,57 @@
+import { resolveProviderSelection, NullWorkerProvider } from '../providers/providers.js';
+import { SupervisorRuntime } from '../supervisor/runtime.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';
+
+export interface RunCommandContext {
+  repoRoot: string;
+  env: NodeJS.ProcessEnv;
+  runId: string;
+  transport: ToolTransport;
+  options: CliOptions;
+  kernel: AopKernel;
+  toolClient: ToolClient;
+}
+
+export class RunCommandHandler {
+  async execute(context: RunCommandContext): Promise<unknown> {
+    const { repoRoot, env, runId, transport, options, kernel, toolClient } = context;
+    const specResolver = new SpecInputResolver(repoRoot, toolClient, runId);
+    const ingestionService = new SpecIngestionService(repoRoot, toolClient, runId);
+
+    const resolvedPaths = await specResolver.resolve(options);
+    const ingested = await ingestionService.ingest(resolvedPaths);
+
+    const selection = resolveProviderSelection({
+      cli: options as unknown as Record<string, string | undefined>,
+      env,
+      agentsConfig: kernel.getAgentsConfig()
+    });
+
+    const provider = new NullWorkerProvider(selection);
+    const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
+      max_active_features: 5,
+      max_parallel_gate_runs: 3,
+      run_id: runId,
+      takeover_stale_run: options.takeover_stale_run
+    });
+
+    const startResult = await supervisor.start(ingested as Array<{ feature_id: string }>);
+
+    return {
+      ok: true,
+      data: {
+        command: 'run',
+        transport,
+        active_features: ingested,
+        queue_depth: startResult.queue_depth,
+        runtime_status: startResult.status,
+        run_metadata: startResult.run_metadata,
+        dashboard: startResult.dashboard
+      }
+    };
+  }
+}

package/apps/control-plane/src/cli/spec-ingestion-service.ts

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { stableHash, ensureDir } from '../core/fs.js';
+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 { FeatureStatePayload } from './types.js';
+import { callCliTool } from './tooling.js';
+import { canonicalFeatureIdFromPath, isCanonicalSpecPath, isLegacyCanonicalSpecPath } from './spec-utils.js';
+
+export class SpecIngestionService {
+  private readonly repoRoot: string;
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+
+  constructor(repoRoot: string, toolClient: ToolClient, runId: string) {
+    this.repoRoot = repoRoot;
+    this.toolClient = toolClient;
+    this.runId = runId;
+  }
+
+  async ingest(resolvedPaths: string[]): Promise<Array<Record<string, string>>> {
+    const featureIds = new Set<string>();
+    const items: Array<Record<string, string>> = [];
+
+    for (const sourcePath of resolvedPaths) {
+      const canonical = isCanonicalSpecPath(this.repoRoot, sourcePath);
+      const legacyCanonical = canonical ? null : isLegacyCanonicalSpecPath(this.repoRoot, sourcePath);
+      let featureId: string;
+      let targetPath: string;
+      if (canonical) {
+        featureId = canonical;
+        targetPath = sourcePath;
+      } else if (legacyCanonical) {
+        featureId = legacyCanonical;
+        targetPath = path.join(this.repoRoot, '.aop', 'features', featureId, 'spec.md');
+      } else {
+        featureId = canonicalFeatureIdFromPath(sourcePath);
+        targetPath = path.join(this.repoRoot, '.aop', 'features', featureId, 'spec.md');
+      }
+
+      if (featureIds.has(featureId)) {
+        const error = new Error(ERROR_CODES.FEATURE_SLUG_COLLISION) as AppError;
+        error.code = ERROR_CODES.FEATURE_SLUG_COLLISION;
+        error.details = { feature_id: featureId };
+        throw error;
+      }
+      featureIds.add(featureId);
+
+      if (!canonical) {
+        await ensureDir(path.dirname(targetPath));
+        const sourceContent = await fs.readFile(sourcePath, 'utf8');
+        await fs.writeFile(targetPath, sourceContent, 'utf8');
+      }
+
+      await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_INIT, { feature_id: featureId });
+
+      const sourceContent = await fs.readFile(sourcePath, 'utf8');
+      const sourceHash = stableHash(sourceContent);
+      const state = await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_STATE_GET, {
+        feature_id: featureId
+      });
+      const typedState = state.data as unknown as FeatureStatePayload;
+
+      await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_STATE_PATCH, {
+        feature_id: featureId,
+        expected_version: typedState.front_matter.version,
+        patch: {
+          front_matter: {
+            source: {
+              path: path.relative(this.repoRoot, sourcePath).replaceAll('\\\\', '/'),
+              hash: sourceHash
+            }
+          }
+        }
+      });
+
+      items.push({
+        feature_id: featureId,
+        source_path: path.relative(this.repoRoot, sourcePath).replaceAll('\\\\', '/'),
+        canonical_spec_path: path.relative(this.repoRoot, targetPath).replaceAll('\\\\', '/')
+      });
+    }
+
+    return items;
+  }
+}

package/apps/control-plane/src/cli/spec-input-resolver.ts

@@ -0,0 +1,95 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+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, DiscoveredSpecsPayload } from './types.js';
+import { callCliTool } from './tooling.js';
+
+async function readMarkdownFilesRecursive(folder: string): Promise<string[]> {
+  const results: string[] = [];
+
+  async function walk(current: string): Promise<void> {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const entry of entries) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absolute);
+        continue;
+      }
+      if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+        results.push(absolute);
+      }
+    }
+  }
+
+  await walk(folder);
+  results.sort((a, b) => a.localeCompare(b));
+  return results;
+}
+
+export class SpecInputResolver {
+  private readonly repoRoot: string;
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+
+  constructor(repoRoot: string, toolClient: ToolClient, runId: string) {
+    this.repoRoot = repoRoot;
+    this.toolClient = toolClient;
+    this.runId = runId;
+  }
+
+  async resolve(options: CliOptions): Promise<string[]> {
+    if (options.file_input && options.folder_input) {
+      const error = new Error(ERROR_CODES.INVALID_CLI_ARGS) as AppError;
+      error.code = ERROR_CODES.INVALID_CLI_ARGS;
+      error.details = { reason: '-fi and -fl are mutually exclusive' };
+      throw error;
+    }
+
+    if (options.file_input) {
+      const absolute = path.resolve(this.repoRoot, options.file_input);
+      const stat = await fs.stat(absolute).catch(() => null);
+      if (!stat || !stat.isFile()) {
+        const error = new Error(ERROR_CODES.INPUT_PATH_NOT_FOUND) as AppError;
+        error.code = ERROR_CODES.INPUT_PATH_NOT_FOUND;
+        error.details = { path: options.file_input };
+        throw error;
+      }
+      return [absolute];
+    }
+
+    if (options.folder_input) {
+      const absolute = path.resolve(this.repoRoot, options.folder_input);
+      const stat = await fs.stat(absolute).catch(() => null);
+      if (!stat || !stat.isDirectory()) {
+        const error = new Error(ERROR_CODES.INPUT_PATH_NOT_FOUND) as AppError;
+        error.code = ERROR_CODES.INPUT_PATH_NOT_FOUND;
+        error.details = { path: options.folder_input };
+        throw error;
+      }
+
+      const markdownFiles = await readMarkdownFilesRecursive(absolute);
+      if (markdownFiles.length === 0) {
+        const error = new Error(ERROR_CODES.NO_SPECS_FOUND) as AppError;
+        error.code = ERROR_CODES.NO_SPECS_FOUND;
+        error.details = { folder: options.folder_input };
+        throw error;
+      }
+      return markdownFiles;
+    }
+
+    const discovered = await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_DISCOVER_SPECS, {});
+    const specs = (discovered.data as unknown as DiscoveredSpecsPayload).specs ?? [];
+    if (specs.length === 0) {
+      const error = new Error(ERROR_CODES.NO_SPECS_FOUND) as AppError;
+      error.code = ERROR_CODES.NO_SPECS_FOUND;
+      throw error;
+    }
+
+    return specs.map((item: { spec_path: string }) => path.join(this.repoRoot, item.spec_path));
+  }
+}

package/apps/control-plane/src/cli/spec-utils.ts

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import {ERROR_CODES} from '../core/error-codes.js';
+import type {AppError} from '../providers/providers.js';
+
+export function canonicalFeatureIdFromPath(inputPath: string): string {
+  const basename = path.basename(inputPath);
+  let candidate = basename.replace(/\.[^.]+$/, '');
+  if (candidate.endsWith('.spec')) {
+    candidate = candidate.slice(0, -'.spec'.length);
+  } else if (candidate.endsWith('-spec')) {
+    candidate = candidate.slice(0, -'-spec'.length);
+  }
+
+  if (!candidate || !/^[a-z0-9_][a-z0-9_-]*$/.test(candidate)) {
+    const error = new Error(ERROR_CODES.INVALID_FEATURE_SLUG) as AppError;
+    error.code = ERROR_CODES.INVALID_FEATURE_SLUG;
+    error.details = { input_path: inputPath, derived_feature_id: candidate };
+    throw error;
+  }
+
+  return candidate;
+}
+
+export function isCanonicalSpecPath(repoRoot: string, candidate: string): string | null {
+  const relative = path.relative(repoRoot, candidate).replaceAll('\\\\', '/');
+  const match = relative.match(/^\.aop\/features\/([a-z0-9_][a-z0-9_-]*)\/spec\.md$/);
+  if (!match) {
+    return null;
+  }
+  return match[1];
+}
+
+export function isLegacyCanonicalSpecPath(repoRoot: string, candidate: string): string | null {
+  const relative = path.relative(repoRoot, candidate).replaceAll('\\\\', '/');
+  const match = relative.match(/^agentic\/features\/([a-z0-9_][a-z0-9_-]*)\/spec\.md$/);
+  if (!match) {
+    return null;
+  }
+  return match[1];
+}

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

@@ -0,0 +1,17 @@
+import {TOOLS} from '../core/constants.js';
+import type {ToolClient} from '../mcp/tool-client.js';
+import {callCliTool} from './tooling.js';
+
+export class StatusCommandHandler {
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+
+  constructor(toolClient: ToolClient, runId: string) {
+    this.toolClient = toolClient;
+    this.runId = runId;
+  }
+
+  async execute(): Promise<unknown> {
+    return await callCliTool(this.toolClient, this.runId, TOOLS.REPORT_DASHBOARD, {});
+  }
+}

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

@@ -0,0 +1,5 @@
+export class StopCommandHandler {
+  execute(): Promise<unknown> {
+    return Promise.resolve({ ok: true, data: { status: 'stop_not_implemented_yet' } });
+  }
+}

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

@@ -0,0 +1,36 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { FailResponse, OkResponse, ToolResponse } from '../core/response.js';
+import type { AppError } from '../providers/providers.js';
+import { createOperationId, type ToolClient } from '../mcp/tool-client.js';
+import { withOperationIdIfRequired } from '../application/tools/tool-metadata.js';
+
+export function assertOkResponse<TData extends Record<string, unknown>>(
+  response: ToolResponse<TData>
+): OkResponse<TData> {
+  if (!response.ok) {
+    const failed = response as FailResponse;
+    const error = new Error(failed.error.message ?? ERROR_CODES.INTERNAL_ERROR) as AppError;
+    error.code = failed.error.code ?? ERROR_CODES.INTERNAL_ERROR;
+    error.details = failed.error.details ?? {};
+    throw error;
+  }
+  return response;
+}
+
+export async function callCliTool(
+  toolClient: ToolClient,
+  runId: string,
+  toolName: string,
+  args: Record<string, unknown>
+): Promise<OkResponse<Record<string, unknown>>> {
+  const payload = withOperationIdIfRequired(toolName, args, createOperationId);
+
+  const response = await toolClient.call(toolName, payload, {
+    run_id: runId,
+    session_id: 'bootstrap:cli',
+    actor_type: 'system',
+    actor_id: 'cli:system'
+  });
+
+  return assertOkResponse(response);
+}

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

@@ -0,0 +1,34 @@
+export interface CliOptions {
+  command: string;
+  file_input?: string;
+  folder_input?: string;
+  feature_id?: string;
+  dry_run?: boolean;
+  yes?: boolean;
+  remove_worktree?: boolean;
+  remove_branch?: string;
+  agent_provider?: string;
+  agent_model?: string;
+  provider_config_env?: string;
+  transport?: string;
+  takeover_stale_run?: boolean;
+}
+
+export type RemoveBranchMode = 'none' | 'safe' | 'force';
+
+export interface RuntimeContext {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+}
+
+export type ToolTransport = 'inprocess' | 'mcp';
+
+export interface FeatureStatePayload {
+  front_matter: {
+    version: number;
+  };
+}
+
+export interface DiscoveredSpecsPayload {
+  specs: Array<{ spec_path: string }>;
+}