agentic-orchestrator 0.1.27 → 0.2.0

package/apps/control-plane/test/execution-enrollment-service.spec.ts

@@ -0,0 +1,648 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  CapacityAwareEnrollmentScheduler,
+  ExecutionEnrollmentService,
+} from '../src/supervisor/execution-enrollment-service.js';
+
+function makePendingRequest() {
+  return {
+    request_id: 'exec_req_001',
+    request_type: 'add_features' as const,
+    status: 'pending' as const,
+    requested_at: new Date(0).toISOString(),
+    processed_at: null,
+    requested_by: 'cli:add',
+    operation_id: 'op:add:feature_a',
+    features: [{ feature_id: 'feature_a', spec_path: '.aop/features/feature_a/spec.md' }],
+    progress: null,
+    outcome: null,
+  };
+}
+
+describe('ExecutionEnrollmentService', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('detects pending requests on the poll interval and drains a queue_now batch once', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: { items: [makePendingRequest()] },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      readState: vi.fn(async () => ({ frontMatter: { status: 'planning' }, body: '' })),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    await service.start();
+    await vi.advanceTimersByTimeAsync(2_000);
+
+    const batches = await service.drainReadyDecisions();
+    expect(batches).toHaveLength(1);
+    expect(batches[0].decisions).toEqual([
+      {
+        request_id: 'exec_req_001',
+        feature_id: 'feature_a',
+        disposition: 'queue_now',
+        reason: 'capacity_available',
+      },
+    ]);
+    expect(await service.drainReadyDecisions()).toEqual([]);
+    expect(kernel.updateExecutionRequestProgress).toHaveBeenCalledWith(
+      'run:test',
+      'owner:test',
+      'exec_req_001',
+      expect.objectContaining({
+        detected_at: expect.any(String),
+        last_evaluated_at: expect.any(String),
+        deferred: [],
+      }),
+    );
+
+    await service.stop();
+  });
+
+  it('reconciles immediately when a wake hint is delivered', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: { items: [makePendingRequest()] },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      readState: vi.fn(async () => ({ frontMatter: { status: 'planning' }, body: '' })),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    await service.start();
+    await service.notifyNewRequestHint();
+
+    expect(kernel.drainPendingExecutionRequests).toHaveBeenCalledTimes(1);
+    expect(await service.drainReadyDecisions()).toHaveLength(1);
+
+    await service.stop();
+  });
+
+  it('keeps deferred requests pending without producing a ready batch', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: { items: [makePendingRequest()] },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      readState: vi.fn(async () => ({ frontMatter: { status: 'planning' }, body: '' })),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>([
+        ['feature_live', { planner: 'p', builder: 'b', qa: 'q' }],
+      ]),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: new CapacityAwareEnrollmentScheduler({ allowQueueGrowth: false }),
+      maxActiveFeatures: 1,
+    });
+
+    await service.start();
+    await service.notifyNewRequestHint();
+
+    expect(await service.drainReadyDecisions()).toEqual([]);
+    expect(kernel.updateExecutionRequestProgress).toHaveBeenCalledWith(
+      'run:test',
+      'owner:test',
+      'exec_req_001',
+      expect.objectContaining({
+        deferred: [{ feature_id: 'feature_a', reason: 'capacity_full' }],
+      }),
+    );
+
+    await service.stop();
+  });
+
+  it('skips duplicate polls when the pending fingerprint has not changed', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: { items: [makePendingRequest()] },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      readState: vi.fn(async () => ({ frontMatter: { status: 'planning' }, body: '' })),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    await service.start();
+    await vi.advanceTimersByTimeAsync(2_000);
+    await vi.advanceTimersByTimeAsync(2_000);
+
+    expect(kernel.drainPendingExecutionRequests).toHaveBeenCalledTimes(2);
+    expect(kernel.updateExecutionRequestProgress).toHaveBeenCalledTimes(1);
+
+    await service.stop();
+  });
+
+  it('returns a completion batch when progress already handled every feature', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: {
+          items: [
+            {
+              ...makePendingRequest(),
+              progress: {
+                detected_at: '2026-03-16T00:00:00.000Z',
+                last_evaluated_at: '2026-03-16T00:00:01.000Z',
+                queued: ['feature_a'],
+                skipped: [],
+                deferred: [],
+              },
+            },
+          ],
+        },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      readState: vi.fn(async () => ({ frontMatter: { status: 'planning' }, body: '' })),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const scheduler = {
+      schedule: vi.fn(async () => ({ decisions: [] })),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: scheduler as never,
+      maxActiveFeatures: 1,
+    });
+
+    await service.notifyNewRequestHint();
+
+    const batches = await service.drainReadyDecisions();
+    expect(batches).toHaveLength(1);
+    expect(batches[0].decisions).toEqual([]);
+    expect(kernel.updateExecutionRequestProgress).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats missing feature state reads as unknown status and continues scheduling', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: { items: [makePendingRequest()] },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      readState: vi.fn(async () => {
+        throw new Error('missing state');
+      }),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    await service.notifyNewRequestHint();
+
+    const batches = await service.drainReadyDecisions();
+    expect(batches).toHaveLength(1);
+    expect(batches[0].decisions[0]).toMatchObject({
+      feature_id: 'feature_a',
+      disposition: 'queue_now',
+    });
+  });
+
+  it('starts only one poller and noteSafeCheckpoint triggers an immediate reconcile', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: { items: [makePendingRequest()] },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      readState: vi.fn(async () => ({ frontMatter: { status: 'planning' }, body: '' })),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    await service.start();
+    await service.start();
+    await vi.advanceTimersByTimeAsync(2_000);
+    await service.noteSafeCheckpoint();
+
+    expect(kernel.drainPendingExecutionRequests).toHaveBeenCalledTimes(2);
+
+    await service.stop();
+  });
+
+  it('sorts drained batches and reports pending work from internal state', async () => {
+    const service = new ExecutionEnrollmentService({
+      kernel: {} as never,
+      state: {
+        runId: 'run:test',
+        ownerInstanceId: 'owner:test',
+        orchestratorSessionId: 'orch:test',
+        sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+        queue: [] as Array<{ feature_id: string }>,
+        runMetadata: {},
+      } as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    expect(service.hasPendingWork()).toBe(false);
+    (service as any).wakeRequested = true;
+    expect(service.hasPendingWork()).toBe(true);
+    (service as any).wakeRequested = false;
+    (service as any).observedPendingRequestIds.add('exec_req_002');
+    expect(service.hasPendingWork()).toBe(true);
+    (service as any).observedPendingRequestIds.clear();
+
+    (service as any).readyBatches.set('exec_req_002', {
+      request: {
+        ...makePendingRequest(),
+        request_id: 'exec_req_002',
+        requested_at: '2026-03-16T00:00:02.000Z',
+      },
+      decisions: [],
+      progress: {
+        detected_at: null,
+        last_evaluated_at: null,
+        queued: [],
+        skipped: [],
+        deferred: [],
+      },
+    });
+    (service as any).readyBatches.set('exec_req_001', {
+      request: {
+        ...makePendingRequest(),
+        requested_at: '2026-03-16T00:00:01.000Z',
+      },
+      decisions: [],
+      progress: {
+        detected_at: null,
+        last_evaluated_at: null,
+        queued: [],
+        skipped: [],
+        deferred: [],
+      },
+    });
+
+    const drained = await service.drainReadyDecisions();
+    expect(drained.map((item) => item.request.request_id)).toEqual([
+      'exec_req_001',
+      'exec_req_002',
+    ]);
+    expect(service.hasPendingWork()).toBe(false);
+  });
+
+  it('waits for in-flight reconciles and logs non-Error reconcile failures', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    let releaseReconcile: (() => void) | null = null;
+    const inFlight = new Promise<void>((resolve) => {
+      releaseReconcile = resolve;
+    });
+    const service = new ExecutionEnrollmentService({
+      kernel: {
+        drainPendingExecutionRequests: vi.fn(async () => {
+          throw 'boom';
+        }),
+      } as never,
+      state: {
+        runId: 'run:test',
+        ownerInstanceId: 'owner:test',
+        orchestratorSessionId: 'orch:test',
+        sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+        queue: [] as Array<{ feature_id: string }>,
+        runMetadata: {},
+      } as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    (service as any).reconcileInFlight = inFlight;
+    const notifyPromise = service.notifyNewRequestHint();
+    expect(warnSpy).not.toHaveBeenCalled();
+    releaseReconcile?.();
+    await notifyPromise;
+
+    (service as any).reconcileInFlight = inFlight;
+    const stopPromise = service.stop();
+    await Promise.resolve();
+    expect(warnSpy).not.toHaveBeenCalled();
+    await stopPromise;
+
+    (service as any).reconcileInFlight = null;
+    await service.notifyNewRequestHint();
+    expect(warnSpy).toHaveBeenCalledWith('[enrollment] reconcile failed: boom');
+  });
+
+  it('serializes object-shaped reconcile failures into useful log messages', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const service = new ExecutionEnrollmentService({
+      kernel: {
+        drainPendingExecutionRequests: vi.fn(async () => {
+          throw { code: 'reconcile_failed', detail: 'boom' };
+        }),
+      } as never,
+      state: {
+        runId: 'run:test',
+        ownerInstanceId: 'owner:test',
+        orchestratorSessionId: 'orch:test',
+        sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+        queue: [] as Array<{ feature_id: string }>,
+        runMetadata: {},
+      } as never,
+      scheduler: new CapacityAwareEnrollmentScheduler(),
+      maxActiveFeatures: 1,
+    });
+
+    await service.notifyNewRequestHint();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[enrollment] reconcile failed: {"code":"reconcile_failed","detail":"boom"}',
+    );
+  });
+
+  it('normalizes scheduling inputs, deduplicates deferred reasons, and skips handled features', async () => {
+    const kernel = {
+      drainPendingExecutionRequests: vi.fn(async () => ({
+        data: {
+          items: [
+            {
+              ...makePendingRequest(),
+              features: [
+                { feature_id: 'feature_b', spec_path: '.aop/features/feature_b/spec.md' },
+                { feature_id: 'feature_a', spec_path: '.aop/features/feature_a/spec.md' },
+                { feature_id: 'feature_c', spec_path: '.aop/features/feature_c/spec.md' },
+              ],
+              progress: {
+                detected_at: '2026-03-16T00:00:00.000Z',
+                last_evaluated_at: '2026-03-16T00:00:01.000Z',
+                queued: [],
+                skipped: [{ feature_id: 'feature_c', reason: 'already_active' }],
+                deferred: [],
+              },
+            },
+          ],
+        },
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {
+          feature_c: {},
+          feature_a: {},
+        },
+      })),
+      readState: vi.fn(async () => ({ frontMatter: { status: 'planning' }, body: '' })),
+      updateExecutionRequestProgress: vi.fn(
+        async (_runId, _ownerInstanceId, _requestId, patch) => ({
+          data: { updated: true, progress: patch },
+        }),
+      ),
+    };
+    const scheduler = {
+      schedule: vi.fn(async (input) => {
+        expect(input.activeFeatureIds).toEqual(['feature_live']);
+        expect(input.queuedFeatureIds).toEqual(['feature_a', 'feature_b']);
+        expect(input.assignedFeatureIds).toEqual(['feature_a', 'feature_c']);
+        expect(input.features).toEqual([
+          { feature_id: 'feature_b', status: 'planning' },
+          { feature_id: 'feature_a', status: 'planning' },
+        ]);
+        return {
+          decisions: [
+            {
+              request_id: 'exec_req_001',
+              feature_id: 'feature_b',
+              disposition: 'defer',
+              reason: 'z_reason',
+            },
+            {
+              request_id: 'exec_req_001',
+              feature_id: '',
+              disposition: 'defer',
+              reason: 'ignored',
+            },
+            {
+              request_id: 'exec_req_001',
+              feature_id: 'feature_b',
+              disposition: 'defer',
+              reason: 'a_reason',
+            },
+            {
+              request_id: 'exec_req_001',
+              feature_id: 'feature_a',
+              disposition: 'defer',
+              reason: 'm_reason',
+            },
+          ],
+        };
+      }),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>([
+        ['feature_live', { planner: 'p', builder: 'b', qa: 'q' }],
+      ]),
+      queue: [
+        { feature_id: 'feature_b' },
+        { feature_id: 'feature_a' },
+        { feature_id: 'feature_b' },
+      ] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const service = new ExecutionEnrollmentService({
+      kernel: kernel as never,
+      state: state as never,
+      scheduler: scheduler as never,
+      maxActiveFeatures: 1,
+    });
+
+    await service.notifyNewRequestHint();
+
+    expect(kernel.updateExecutionRequestProgress).toHaveBeenCalledWith(
+      'run:test',
+      'owner:test',
+      'exec_req_001',
+      expect.objectContaining({
+        deferred: [
+          { feature_id: 'feature_a', reason: 'm_reason' },
+          { feature_id: 'feature_b', reason: 'a_reason' },
+          { feature_id: 'feature_b', reason: 'z_reason' },
+        ],
+      }),
+    );
+    expect(await service.drainReadyDecisions()).toEqual([]);
+  });
+});
+
+describe('CapacityAwareEnrollmentScheduler', () => {
+  it('rejects active, queued, assigned, and terminal features while allowing queue growth', async () => {
+    const scheduler = new CapacityAwareEnrollmentScheduler();
+
+    const result = await scheduler.schedule({
+      request: makePendingRequest(),
+      features: [
+        { feature_id: 'feature_active', status: null },
+        { feature_id: 'feature_queued', status: null },
+        { feature_id: 'feature_assigned', status: null },
+        { feature_id: 'feature_terminal', status: 'ready_to_merge' },
+        { feature_id: 'feature_growth', status: 'planning' },
+      ],
+      activeFeatureIds: ['feature_active'],
+      queuedFeatureIds: ['feature_queued'],
+      assignedFeatureIds: ['feature_assigned'],
+      maxActiveFeatures: 1,
+    });
+
+    expect(result.decisions).toEqual([
+      {
+        request_id: 'exec_req_001',
+        feature_id: 'feature_active',
+        disposition: 'reject',
+        reason: 'already_active',
+      },
+      {
+        request_id: 'exec_req_001',
+        feature_id: 'feature_queued',
+        disposition: 'reject',
+        reason: 'already_queued',
+      },
+      {
+        request_id: 'exec_req_001',
+        feature_id: 'feature_assigned',
+        disposition: 'reject',
+        reason: 'already_assigned_cluster',
+      },
+      {
+        request_id: 'exec_req_001',
+        feature_id: 'feature_terminal',
+        disposition: 'reject',
+        reason: 'terminal_status',
+      },
+      {
+        request_id: 'exec_req_001',
+        feature_id: 'feature_growth',
+        disposition: 'queue_now',
+        reason: 'queue_growth_allowed',
+      },
+    ]);
+  });
+});