agentic-orchestrator 0.1.0

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

@@ -0,0 +1,149 @@
+import type { AgentsConfigSnapshot } from '../core/kernel.js';
+
+export interface AppError extends Error {
+  code?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface SupervisorOptions {
+  max_active_features?: number;
+  max_parallel_gate_runs?: number;
+  max_iterations_per_phase?: number;
+  run_id?: string;
+  owner_instance_id?: string;
+  takeover_stale_run?: boolean;
+}
+
+export interface FeatureInput {
+  feature_id: string;
+}
+
+export interface WorkerSessions {
+  planner: string;
+  builder: string;
+  qa: string;
+}
+
+export type RuntimeRole = 'orchestrator' | 'planner' | 'builder' | 'qa';
+
+export interface FeatureStateFrontMatter {
+  version: number;
+  status: string;
+  cluster?: Record<string, string>;
+}
+
+export interface FeatureStatePayload {
+  front_matter: FeatureStateFrontMatter;
+  body?: string;
+}
+
+export interface FeatureContextPayload {
+  state: FeatureStatePayload;
+  spec?: string;
+  plan: Record<string, unknown> | null;
+  qa_test_index?: Record<string, unknown> | null;
+  latest_evidence?: Record<string, unknown> | null;
+}
+
+export interface PromptBundle {
+  planner: string | null;
+  builder: string | null;
+  qa: string | null;
+}
+
+export interface RuntimeSessionAssignment {
+  planner_session_id: string;
+  builder_session_id: string;
+  qa_session_id: string;
+}
+
+export interface RuntimeSessionsSnapshot {
+  run_id: string;
+  owner_instance_id: string;
+  orchestrator_session_id: string;
+  orchestrator_epoch?: number;
+  feature_sessions?: Record<string, RuntimeSessionAssignment>;
+}
+
+export interface AcquireRunLeaseInput {
+  run_id: string;
+  owner_instance_id: string;
+  provider: string;
+  model: string;
+  provider_config_ref_hash: string;
+  takeover_stale_run?: boolean;
+}
+
+export interface UpdateOrchestratorSessionInput {
+  run_id: string;
+  owner_instance_id: string;
+  orchestrator_session_id: string;
+  increment_epoch?: boolean;
+}
+
+export interface UpdateFeatureSessionAssignmentInput {
+  run_id: string;
+  owner_instance_id: string;
+  feature_id: string;
+  planner_session_id: string;
+  builder_session_id: string;
+  qa_session_id: string;
+}
+
+export interface PruneFeatureSessionAssignmentsInput {
+  run_id: string;
+  owner_instance_id: string;
+  active_feature_ids: string[];
+}
+
+export interface RuntimeStateReader {
+  getRuntimeSessions(): Promise<RuntimeSessionsSnapshot>;
+  getRepoRoot(): string;
+  getAgentsConfig(): AgentsConfigSnapshot;
+  getPolicySnapshot(): Record<string, unknown>;
+}
+
+export interface FeatureOrchestrationPort {
+  ensureLoaded(): Promise<void>;
+  recoverFromState(): Promise<{ data: Record<string, unknown> }>;
+  acquireRunLease(input: AcquireRunLeaseInput): Promise<{ data: { took_over_stale: boolean } }>;
+  updateOrchestratorSession(params: UpdateOrchestratorSessionInput): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot } }>;
+  updateFeatureSessionAssignment(params: UpdateFeatureSessionAssignmentInput): Promise<{ data: { updated: boolean } }>;
+  pruneFeatureSessionAssignments(params: PruneFeatureSessionAssignmentsInput): Promise<{ data: { removed: string[] } }>;
+  renewLeases(featureIds: string[]): Promise<void>;
+  renewRunLease(runId: string, ownerInstanceId: string): Promise<{ data: { lease_expires_at: string } }>;
+  repoDiff(featureId: string, options?: string[]): Promise<{ data: Record<string, unknown> }>;
+}
+
+export type SupervisorKernelPort = RuntimeStateReader & FeatureOrchestrationPort;
+
+export interface SupervisorToolCaller {
+  callTool<TData = Record<string, unknown>>(
+    role: RuntimeRole,
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<{ ok: true; data: TData }>;
+}
+
+export interface AgentPromptProvider {
+  loadRolePrompts(): Promise<PromptBundle>;
+}
+
+export interface FeatureClusterPatcher {
+  patchFeatureCluster(featureId: string, clusterPatch: Record<string, string>): Promise<void>;
+}
+
+export interface InitialPlanGenerator {
+  generateInitialPlan(featureId: string): Promise<Record<string, unknown>>;
+}
+
+export interface SupervisorRuntimeState {
+  runId: string;
+  ownerInstanceId: string;
+  orchestratorSessionId: string | null;
+  sessionsByFeature: Map<string, WorkerSessions>;
+  queue: FeatureInput[];
+  runMetadata: Record<string, unknown>;
+}
+
+export const UNASSIGNED_SESSION_ID = 'unassigned';

package/apps/control-plane/src/supervisor/worker-decision-loop.ts

@@ -0,0 +1,299 @@
+import { TOOLS } from '../core/constants.js';
+import type { WorkerProvider } from '../providers/providers.js';
+import type { RuntimeRole, SupervisorToolCaller } from './types.js';
+
+type AnyRecord = Record<string, unknown>;
+
+export interface WorkerDecisionInput {
+  role: RuntimeRole;
+  featureId: string;
+  contextBundle: AnyRecord;
+  instructions: string;
+  lastToolResults?: AnyRecord[];
+}
+
+export interface WorkerDecisionResult {
+  planSubmission: boolean;
+  patchApplied: boolean;
+  noteLogged: boolean;
+  requestHandled: boolean;
+  priorityOrder: string[];
+  toolResults: AnyRecord[];
+}
+
+export interface WorkerDecisionRunner {
+  execute(input: WorkerDecisionInput): Promise<WorkerDecisionResult>;
+}
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const normalized: string[] = [];
+  for (const item of value) {
+    const normalizedItem = asNonEmptyString(item);
+    if (normalizedItem) {
+      normalized.push(normalizedItem);
+    }
+  }
+  return normalized;
+}
+
+function readPlanVersion(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+    return null;
+  }
+  return Math.floor(value);
+}
+
+function asOutputs(result: Record<string, unknown>): AnyRecord[] {
+  const outputs = result.outputs;
+  if (Array.isArray(outputs)) {
+    return outputs
+      .map((item) => asRecord(item))
+      .filter((item) => Object.keys(item).length > 0);
+  }
+  return [asRecord(result)];
+}
+
+function makeEmptyResult(): WorkerDecisionResult {
+  return {
+    planSubmission: false,
+    patchApplied: false,
+    noteLogged: false,
+    requestHandled: false,
+    priorityOrder: [],
+    toolResults: []
+  };
+}
+
+export const NOOP_WORKER_DECISION_RUNNER: WorkerDecisionRunner = {
+  execute: () => Promise.resolve(makeEmptyResult())
+};
+
+interface WorkerDecisionLoopDependencies {
+  provider: WorkerProvider;
+  toolCaller: SupervisorToolCaller;
+}
+
+export class WorkerDecisionLoop implements WorkerDecisionRunner {
+  private readonly provider: WorkerProvider;
+  private readonly toolCaller: SupervisorToolCaller;
+
+  constructor(dependencies: WorkerDecisionLoopDependencies) {
+    this.provider = dependencies.provider;
+    this.toolCaller = dependencies.toolCaller;
+  }
+
+  async execute(input: WorkerDecisionInput): Promise<WorkerDecisionResult> {
+    const result = makeEmptyResult();
+    if (typeof this.provider.runWorker !== 'function') {
+      return result;
+    }
+
+    const workerOutput = await this.provider.runWorker({
+      role: input.role,
+      feature_id: input.featureId,
+      context_bundle: input.contextBundle,
+      instructions: input.instructions,
+      last_tool_results: input.lastToolResults ?? [],
+      runtime_selection: {
+        provider: this.provider.selection.provider,
+        model: this.provider.selection.model,
+        provider_config_ref: this.provider.selection.provider_config_ref
+      }
+    });
+
+    const outputs = asOutputs(workerOutput);
+    for (const output of outputs) {
+      const outputType = asNonEmptyString(output.type)?.toUpperCase();
+      if (!outputType) {
+        continue;
+      }
+
+      if (outputType === 'PLAN_SUBMISSION') {
+        await this.routePlanSubmission(input, output, result);
+        continue;
+      }
+      if (outputType === 'PATCH') {
+        await this.routePatch(input, output, result);
+        continue;
+      }
+      if (outputType === 'NOTE') {
+        await this.routeNote(input.featureId, output, result);
+        continue;
+      }
+      if (outputType === 'REQUEST') {
+        await this.routeRequest(input, output, result);
+      }
+    }
+
+    return result;
+  }
+
+  private async routePlanSubmission(
+    input: WorkerDecisionInput,
+    output: AnyRecord,
+    result: WorkerDecisionResult
+  ): Promise<void> {
+    if (input.role !== 'planner') {
+      return;
+    }
+
+    const planJson = asRecord(output.plan_json ?? output.plan);
+    if (Object.keys(planJson).length === 0) {
+      return;
+    }
+
+    const contextPlan = asRecord(input.contextBundle.plan);
+    const existingVersion = readPlanVersion(contextPlan.plan_version);
+    const requestedExpectedVersion = readPlanVersion(output.expected_plan_version);
+
+    if (existingVersion == null) {
+      const response = await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
+        feature_id: input.featureId,
+        plan_json: planJson
+      });
+      result.toolResults.push(asRecord(response.data));
+      result.planSubmission = true;
+      return;
+    }
+
+    const expectedPlanVersion = requestedExpectedVersion ?? existingVersion;
+    const response = await this.toolCaller.callTool('planner', TOOLS.PLAN_UPDATE, {
+      feature_id: input.featureId,
+      expected_plan_version: expectedPlanVersion,
+      plan_json: planJson
+    });
+    result.toolResults.push(asRecord(response.data));
+    result.planSubmission = true;
+  }
+
+  private async routePatch(input: WorkerDecisionInput, output: AnyRecord, result: WorkerDecisionResult): Promise<void> {
+    if (input.role !== 'builder' && input.role !== 'qa') {
+      return;
+    }
+
+    const unifiedDiff = asNonEmptyString(output.unified_diff ?? output.diff);
+    if (!unifiedDiff) {
+      return;
+    }
+
+    const response = await this.toolCaller.callTool(input.role, TOOLS.REPO_APPLY_PATCH, {
+      feature_id: input.featureId,
+      unified_diff: unifiedDiff
+    });
+    result.toolResults.push(asRecord(response.data));
+    result.patchApplied = true;
+  }
+
+  private async routeNote(featureId: string, output: AnyRecord, result: WorkerDecisionResult): Promise<void> {
+    const content = asNonEmptyString(output.content) ?? JSON.stringify(output);
+    try {
+      const response = await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+        feature_id: featureId,
+        note: content
+      });
+      result.toolResults.push(asRecord(response.data));
+      result.noteLogged = true;
+    } catch (_error) {
+      // Global logs are best-effort for parity with prior orphan-session logging.
+    }
+  }
+
+  private async routeRequest(input: WorkerDecisionInput, output: AnyRecord, result: WorkerDecisionResult): Promise<void> {
+    const request = asRecord(output.request ?? output);
+    const action = asNonEmptyString(request.action ?? request.request_type)?.toLowerCase();
+    if (!action) {
+      return;
+    }
+
+    if (action === 'prioritize') {
+      const featureOrder = asStringArray(request.feature_order);
+      if (featureOrder.length > 0) {
+        result.priorityOrder = featureOrder;
+        result.requestHandled = true;
+      }
+      return;
+    }
+
+    if (action === 'lock_acquire') {
+      const resources = asStringArray(request.resources);
+      if (resources.length === 0) {
+        return;
+      }
+      const response = await this.toolCaller.callTool('orchestrator', TOOLS.LOCKS_ACQUIRE, {
+        feature_id: input.featureId,
+        resources
+      });
+      result.toolResults.push(asRecord(response.data));
+      result.requestHandled = true;
+      return;
+    }
+
+    if (action === 'lock_release') {
+      const resources = asStringArray(request.resources);
+      if (resources.length === 0) {
+        return;
+      }
+      const response = await this.toolCaller.callTool('orchestrator', TOOLS.LOCKS_RELEASE, {
+        feature_id: input.featureId,
+        resources
+      });
+      result.toolResults.push(asRecord(response.data));
+      result.requestHandled = true;
+      return;
+    }
+
+    if (action === 'more_context' || action === 'context_refresh') {
+      const response = await this.toolCaller.callTool(input.role, TOOLS.FEATURE_GET_CONTEXT, {
+        feature_id: input.featureId
+      });
+      result.toolResults.push(asRecord(response.data));
+      result.requestHandled = true;
+      return;
+    }
+
+    if (action === 'amend_plan' && input.role === 'planner') {
+      const planJson = asRecord(request.plan_json);
+      if (Object.keys(planJson).length === 0) {
+        return;
+      }
+
+      const contextPlan = asRecord(input.contextBundle.plan);
+      const existingVersion = readPlanVersion(contextPlan.plan_version);
+      const requestedExpectedVersion = readPlanVersion(request.expected_plan_version);
+      if (existingVersion == null) {
+        const response = await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
+          feature_id: input.featureId,
+          plan_json: planJson
+        });
+        result.toolResults.push(asRecord(response.data));
+        result.requestHandled = true;
+        result.planSubmission = true;
+        return;
+      }
+
+      const response = await this.toolCaller.callTool('planner', TOOLS.PLAN_UPDATE, {
+        feature_id: input.featureId,
+        expected_plan_version: requestedExpectedVersion ?? existingVersion,
+        plan_json: planJson
+      });
+      result.toolResults.push(asRecord(response.data));
+      result.requestHandled = true;
+      result.planSubmission = true;
+    }
+  }
+}

package/apps/control-plane/test/aop.spec.ts

@@ -0,0 +1,101 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { runCli } from '../src/interfaces/cli/bootstrap.js';
+
+vi.mock('../src/interfaces/cli/bootstrap.js', () => ({
+  runCli: vi.fn()
+}));
+
+const ORIGINAL_ARGV = [...process.argv];
+const ORIGINAL_EXIT_CODE = process.exitCode;
+
+function resetProcessState(): void {
+  process.argv = [...ORIGINAL_ARGV];
+  process.exitCode = ORIGINAL_EXIT_CODE;
+}
+
+describe('aop.ts entrypoint', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    resetProcessState();
+  });
+
+  afterEach(() => {
+    resetProcessState();
+  });
+
+  it('GIVEN_explicit_argv_and_runtime_WHEN_main_runs_THEN_delegates_to_runCli_and_returns_exit_code', async () => {
+    const { main } = await import('../src/cli/aop.js');
+    vi.mocked(runCli).mockResolvedValueOnce(7);
+
+    const runtime = {
+      cwd: '/tmp/custom-repo',
+      env: { NODE_ENV: 'test' } as NodeJS.ProcessEnv
+    };
+    const exitCode = await main(['status'], runtime);
+
+    expect(exitCode).toBe(7);
+    expect(runCli).toHaveBeenCalledWith(['status'], runtime);
+  });
+
+  it('GIVEN_no_arguments_WHEN_main_runs_THEN_uses_process_defaults', async () => {
+    const { main } = await import('../src/cli/aop.js');
+    vi.mocked(runCli).mockResolvedValueOnce(0);
+
+    process.argv = [ORIGINAL_ARGV[0], ORIGINAL_ARGV[1] ?? 'vitest', 'resume'];
+    const exitCode = await main();
+
+    expect(exitCode).toBe(0);
+    expect(runCli).toHaveBeenCalledWith(['resume'], {
+      cwd: process.cwd(),
+      env: process.env
+    });
+  });
+
+  it('GIVEN_direct_execution_check_WHEN_import_meta_and_argv_match_THEN_returns_true', async () => {
+    const { isDirectExecution } = await import('../src/cli/aop.js');
+    const modulePath = '/repo/apps/control-plane/src/cli/aop.ts';
+    expect(isDirectExecution(`file://${modulePath}`, modulePath)).toBe(true);
+    expect(isDirectExecution(`file://${modulePath}`, '/other/path.ts')).toBe(false);
+    expect(isDirectExecution(`file://${modulePath}`, undefined)).toBe(false);
+  });
+
+  it('GIVEN_not_direct_execution_WHEN_runAsEntrypoint_called_THEN_does_not_call_main_or_change_exit_code', async () => {
+    const { runAsEntrypoint } = await import('../src/cli/aop.js');
+    const executeMain = vi.fn(async () => 11);
+
+    const started = runAsEntrypoint('file:///repo/aop.ts', '/repo/other.ts', executeMain);
+
+    expect(started).toBe(false);
+    expect(executeMain).not.toHaveBeenCalled();
+    expect(process.exitCode).toBe(ORIGINAL_EXIT_CODE);
+  });
+
+  it('GIVEN_direct_execution_WHEN_runAsEntrypoint_called_THEN_calls_main_and_sets_process_exit_code', async () => {
+    const { runAsEntrypoint } = await import('../src/cli/aop.js');
+    const executeMain = vi.fn(async () => 13);
+    const modulePath = path.resolve(process.cwd(), 'apps/control-plane/src/cli/aop.ts');
+    const started = runAsEntrypoint(`file://${modulePath}`, modulePath, executeMain);
+
+    expect(started).toBe(true);
+    expect(executeMain).toHaveBeenCalledTimes(1);
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(process.exitCode).toBe(13);
+  });
+
+  it('GIVEN_module_executed_as_script_WHEN_imported_fresh_THEN_sets_process_exit_code_from_main', async () => {
+    vi.mocked(runCli).mockResolvedValueOnce(17);
+    const modulePath = path.resolve(process.cwd(), 'apps/control-plane/src/cli/aop.ts');
+    process.argv = [ORIGINAL_ARGV[0], modulePath, 'status'];
+
+    await import(`${pathToFileURL(modulePath).href}?entry=${Date.now()}`);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(process.exitCode).toBe(17);
+    expect(runCli).toHaveBeenCalledWith(['status'], {
+      cwd: process.cwd(),
+      env: process.env
+    });
+  });
+});

package/apps/control-plane/test/cli-helpers.spec.ts

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+import { CliArgumentParser } from '../src/cli/cli-argument-parser.js';
+import { assertOkResponse, callCliTool } from '../src/cli/tooling.js';
+import { canonicalFeatureIdFromPath, isCanonicalSpecPath, isLegacyCanonicalSpecPath } from '../src/cli/spec-utils.js';
+
+describe('cli helper modules', () => {
+  it('GIVEN_empty_argv_or_extended_flags_WHEN_parsing_THEN_handles_defaults_and_all_supported_tokens', () => {
+    const parser = new CliArgumentParser();
+    expect(parser.parse([])).toEqual({ command: 'run' });
+    expect(parser.parse(['-fi', '.aop/features/feature_x/spec.md'])).toMatchObject({
+      command: 'run',
+      file_input: '.aop/features/feature_x/spec.md'
+    });
+
+    const parsed = parser.parse([
+      'run',
+      '--agent-model',
+      'gpt-5',
+      '--provider-config-env',
+      'AOP_PROVIDER_CFG',
+      '--transport',
+      'mcp'
+    ]);
+
+    expect(parsed).toMatchObject({
+      command: 'run',
+      agent_model: 'gpt-5',
+      provider_config_env: 'AOP_PROVIDER_CFG',
+      transport: 'mcp'
+    });
+    const deleteParsed = parser.parse([
+      'delete',
+      '--feature-id',
+      'feature_x',
+      '--yes',
+      '--dry-run',
+      'false',
+      '--remove-worktree',
+      'false',
+      '--remove-branch',
+      'force'
+    ]);
+    expect(deleteParsed).toMatchObject({
+      command: 'delete',
+      feature_id: 'feature_x',
+      yes: true,
+      dry_run: false,
+      remove_worktree: false,
+      remove_branch: 'force'
+    });
+    expect(parser.resolveTransport('InProcess')).toBe('inprocess');
+    expect(parser.resolveTransport(undefined)).toBe('mcp');
+  });
+
+  it('GIVEN_noncanonical_paths_WHEN_deriving_feature_id_or_canonical_spec_THEN_throws_or_returns_null', () => {
+    expect(canonicalFeatureIdFromPath('feature_x.spec.md')).toBe('feature_x');
+    expect(canonicalFeatureIdFromPath('feature_x-spec.md')).toBe('feature_x');
+    expect(() => canonicalFeatureIdFromPath('INVALID Feature.md')).toThrow(ERROR_CODES.INVALID_FEATURE_SLUG);
+
+    expect(
+      isCanonicalSpecPath('/repo', path.join('/repo', '.aop', 'features', 'feature_a', 'spec.md'))
+    ).toBe('feature_a');
+    expect(
+      isLegacyCanonicalSpecPath('/repo', path.join('/repo', 'agentic', 'features', 'feature_a', 'spec.md'))
+    ).toBe('feature_a');
+    expect(
+      isCanonicalSpecPath('/repo', path.join('/repo', 'agentic', 'features', 'feature_a', 'spec.md'))
+    ).toBeNull();
+    expect(isCanonicalSpecPath('/repo', '/repo/spec-files/feature_a.md')).toBeNull();
+  });
+
+  it('GIVEN_failed_tool_response_without_details_WHEN_asserting_ok_THEN_uses_internal_error_defaults', () => {
+    expect(() =>
+      assertOkResponse({
+        ok: false,
+        error: {}
+      } as any)
+    ).toThrow(ERROR_CODES.INTERNAL_ERROR);
+  });
+
+  it('GIVEN_tool_client_response_WHEN_calling_cli_tool_THEN_uses_system_identity_and_returns_ok_payload', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: { accepted: true } }))
+    };
+
+    const response = await callCliTool(toolClient as any, 'run:cli', 'report.dashboard', { sample: true });
+
+    expect(response).toMatchObject({ ok: true, data: { accepted: true } });
+    expect(toolClient.call).toHaveBeenCalledWith(
+      'report.dashboard',
+      expect.any(Object),
+      expect.objectContaining({
+        run_id: 'run:cli',
+        session_id: 'bootstrap:cli',
+        actor_type: 'system',
+        actor_id: 'cli:system'
+      })
+    );
+  });
+});

package/apps/control-plane/test/cli.spec.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest';
+import { main } from '../src/cli/aop.js';
+
+describe('aop CLI', () => {
+  it('returns non-zero for invalid mutual exclusion', async () => {
+    const exitCode = await main(['run', '-fi', 'a.md', '-fl', 'specs'], {
+      cwd: process.cwd(),
+      env: process.env
+    });
+    expect(exitCode).toBe(1);
+  });
+});