agentic-orchestrator 0.1.0

package/apps/control-plane/test/worker-decision-loop.spec.ts

@@ -0,0 +1,587 @@
+import { describe, expect, it, vi } from 'vitest';
+import { TOOLS } from '../src/core/constants.js';
+import { NOOP_WORKER_DECISION_RUNNER, WorkerDecisionLoop } from '../src/supervisor/worker-decision-loop.js';
+
+describe('WorkerDecisionLoop', () => {
+  function makeProvider(runWorkerResult: Record<string, unknown>) {
+    return {
+      selection: {
+        provider: 'custom',
+        model: 'model-test',
+        provider_config_ref: null
+      },
+      runWorker: vi.fn(async () => runWorkerResult)
+    };
+  }
+
+  function makeToolCaller() {
+    return {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: { refreshed: true } };
+        }
+        return { ok: true, data: { accepted: true } };
+      })
+    };
+  }
+
+  it('GIVEN_noop_runner_WHEN_executed_THEN_returns_empty_decision_result', async () => {
+    const result = await NOOP_WORKER_DECISION_RUNNER.execute({
+      role: 'planner',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'noop'
+    });
+
+    expect(result).toEqual({
+      planSubmission: false,
+      patchApplied: false,
+      noteLogged: false,
+      requestHandled: false,
+      priorityOrder: [],
+      toolResults: []
+    });
+  });
+
+  it('GIVEN_provider_without_runWorker_WHEN_executed_THEN_returns_empty_result_without_tool_calls', async () => {
+    const provider = {
+      selection: {
+        provider: 'custom',
+        model: 'model-test',
+        provider_config_ref: null
+      }
+    };
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'builder',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'build'
+    });
+
+    expect(result.patchApplied).toBe(false);
+    expect(result.requestHandled).toBe(false);
+    expect(toolCaller.callTool).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_planner_submission_without_existing_plan_WHEN_executed_THEN_routes_to_plan_submit', async () => {
+    const provider = makeProvider({
+      type: 'PLAN_SUBMISSION',
+      plan_json: {
+        feature_id: 'feature_a',
+        plan_version: 1,
+        summary: 'Initial plan'
+      }
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'planner',
+      featureId: 'feature_a',
+      contextBundle: { plan: null },
+      instructions: 'plan'
+    });
+
+    expect(result.planSubmission).toBe(true);
+    expect(provider.runWorker).toHaveBeenCalledWith(
+      expect.objectContaining({
+        last_tool_results: [],
+        runtime_selection: {
+          provider: 'custom',
+          model: 'model-test',
+          provider_config_ref: null
+        }
+      })
+    );
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'planner',
+      TOOLS.PLAN_SUBMIT,
+      expect.objectContaining({
+        feature_id: 'feature_a'
+      })
+    );
+  });
+
+  it('GIVEN_planner_submission_with_existing_plan_WHEN_executed_THEN_routes_to_plan_update', async () => {
+    const provider = makeProvider({
+      type: 'PLAN_SUBMISSION',
+      plan_json: {
+        feature_id: 'feature_a',
+        plan_version: 3,
+        summary: 'Revised plan'
+      },
+      expected_plan_version: 2
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'planner',
+      featureId: 'feature_a',
+      contextBundle: { plan: { plan_version: 2 } },
+      instructions: 'plan',
+      lastToolResults: [{ tool: 'x' }]
+    });
+
+    expect(result.planSubmission).toBe(true);
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'planner',
+      TOOLS.PLAN_UPDATE,
+      expect.objectContaining({
+        feature_id: 'feature_a',
+        expected_plan_version: 2
+      })
+    );
+  });
+
+  it('GIVEN_non_planner_or_empty_plan_submission_WHEN_executed_THEN_ignores_submission', async () => {
+    const provider = makeProvider({
+      outputs: [
+        {
+          type: 'PLAN_SUBMISSION',
+          plan_json: {}
+        },
+        {
+          type: 'PLAN_SUBMISSION',
+          plan_json: {
+            feature_id: 'feature_a',
+            plan_version: 1
+          }
+        }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'builder',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'build'
+    });
+
+    expect(result.planSubmission).toBe(false);
+    expect(toolCaller.callTool).not.toHaveBeenCalledWith('planner', TOOLS.PLAN_SUBMIT, expect.any(Object));
+  });
+
+  it('GIVEN_builder_patch_output_WHEN_executed_THEN_routes_to_repo_apply_patch', async () => {
+    const provider = makeProvider({
+      outputs: [
+        {
+          type: 'PATCH',
+          diff: 'diff --git a/src/a.ts b/src/a.ts\n--- a/src/a.ts\n+++ b/src/a.ts\n@@ -1 +1 @@\n-a\n+b\n'
+        }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'qa',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'qa'
+    });
+
+    expect(result.patchApplied).toBe(true);
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'qa',
+      TOOLS.REPO_APPLY_PATCH,
+      expect.objectContaining({
+        feature_id: 'feature_a'
+      })
+    );
+  });
+
+  it('GIVEN_patch_without_diff_or_unsupported_role_WHEN_executed_THEN_skips_patch_routing', async () => {
+    const provider = makeProvider({
+      outputs: [
+        {
+          type: 'PATCH',
+          unified_diff: '   '
+        }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'planner',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'plan'
+    });
+
+    expect(result.patchApplied).toBe(false);
+    expect(toolCaller.callTool).not.toHaveBeenCalledWith('planner', TOOLS.REPO_APPLY_PATCH, expect.any(Object));
+  });
+
+  it('GIVEN_note_output_WHEN_log_append_succeeds_THEN_marks_note_logged', async () => {
+    const provider = makeProvider({
+      type: 'NOTE',
+      content: 'worker note'
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'builder',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'note'
+    });
+
+    expect(result.noteLogged).toBe(true);
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'orchestrator',
+      TOOLS.FEATURE_LOG_APPEND,
+      expect.objectContaining({
+        feature_id: 'feature_a',
+        note: 'worker note'
+      })
+    );
+  });
+
+  it('GIVEN_note_output_WHEN_log_append_fails_THEN_swallows_error_and_keeps_note_unset', async () => {
+    const provider = makeProvider({
+      type: 'NOTE',
+      metadata: { info: 'fallback-json' }
+    });
+    const toolCaller = {
+      callTool: vi.fn(async (role: string, toolName: string) => {
+        if (role === 'orchestrator' && toolName === TOOLS.FEATURE_LOG_APPEND) {
+          throw new Error('append_failed');
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'qa',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'note'
+    });
+
+    expect(result.noteLogged).toBe(false);
+    expect(result.toolResults).toEqual([]);
+  });
+
+  it('GIVEN_request_prioritize_with_empty_order_WHEN_executed_THEN_request_remains_unhandled', async () => {
+    const provider = makeProvider({
+      type: 'REQUEST',
+      request: {
+        action: 'prioritize',
+        feature_order: [null, '   ']
+      }
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'orchestrator',
+      featureId: 'global',
+      contextBundle: {},
+      instructions: 'prioritize'
+    });
+
+    expect(result.requestHandled).toBe(false);
+    expect(result.priorityOrder).toEqual([]);
+  });
+
+  it('GIVEN_request_lock_acquire_and_release_WHEN_executed_THEN_routes_lock_operations', async () => {
+    const provider = makeProvider({
+      outputs: [
+        {
+          type: 'REQUEST',
+          request: { action: 'lock_acquire', resources: ['openapi'] }
+        },
+        {
+          type: 'REQUEST',
+          request: { action: 'lock_release', resources: ['openapi'] }
+        }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'builder',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'locks'
+    });
+
+    expect(result.requestHandled).toBe(true);
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'orchestrator',
+      TOOLS.LOCKS_ACQUIRE,
+      expect.objectContaining({ feature_id: 'feature_a', resources: ['openapi'] })
+    );
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'orchestrator',
+      TOOLS.LOCKS_RELEASE,
+      expect.objectContaining({ feature_id: 'feature_a', resources: ['openapi'] })
+    );
+  });
+
+  it('GIVEN_lock_requests_with_missing_resources_WHEN_executed_THEN_skips_lock_tool_calls', async () => {
+    const provider = makeProvider({
+      outputs: [
+        {
+          type: 'REQUEST',
+          request: { action: 'lock_acquire', resources: [] }
+        },
+        {
+          type: 'REQUEST',
+          request: { action: 'lock_release', resources: [null] }
+        }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'planner',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'locks'
+    });
+
+    expect(result.requestHandled).toBe(false);
+    expect(toolCaller.callTool).not.toHaveBeenCalledWith('orchestrator', TOOLS.LOCKS_ACQUIRE, expect.any(Object));
+    expect(toolCaller.callTool).not.toHaveBeenCalledWith('orchestrator', TOOLS.LOCKS_RELEASE, expect.any(Object));
+  });
+
+  it('GIVEN_context_refresh_requests_WHEN_executed_THEN_requests_feature_context', async () => {
+    const provider = makeProvider({
+      outputs: [
+        {
+          type: 'REQUEST',
+          request: { action: 'more_context' }
+        },
+        {
+          type: 'REQUEST',
+          request: { request_type: 'context_refresh' }
+        }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'qa',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'context'
+    });
+
+    expect(result.requestHandled).toBe(true);
+    const contextCalls = toolCaller.callTool.mock.calls.filter((call) => call[1] === TOOLS.FEATURE_GET_CONTEXT);
+    expect(contextCalls).toHaveLength(2);
+  });
+
+  it('GIVEN_planner_amend_plan_request_WHEN_existing_version_missing_THEN_submits_new_plan', async () => {
+    const provider = makeProvider({
+      type: 'REQUEST',
+      request: {
+        action: 'amend_plan',
+        plan_json: {
+          feature_id: 'feature_a',
+          plan_version: 1
+        }
+      }
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'planner',
+      featureId: 'feature_a',
+      contextBundle: { plan: null },
+      instructions: 'amend'
+    });
+
+    expect(result.requestHandled).toBe(true);
+    expect(result.planSubmission).toBe(true);
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'planner',
+      TOOLS.PLAN_SUBMIT,
+      expect.objectContaining({ feature_id: 'feature_a' })
+    );
+  });
+
+  it('GIVEN_planner_amend_plan_request_WHEN_existing_version_present_THEN_updates_plan', async () => {
+    const provider = makeProvider({
+      type: 'REQUEST',
+      request: {
+        action: 'amend_plan',
+        expected_plan_version: 3,
+        plan_json: {
+          feature_id: 'feature_a',
+          plan_version: 4
+        }
+      }
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'planner',
+      featureId: 'feature_a',
+      contextBundle: { plan: { plan_version: 2 } },
+      instructions: 'amend'
+    });
+
+    expect(result.requestHandled).toBe(true);
+    expect(result.planSubmission).toBe(true);
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'planner',
+      TOOLS.PLAN_UPDATE,
+      expect.objectContaining({
+        feature_id: 'feature_a',
+        expected_plan_version: 3
+      })
+    );
+  });
+
+  it('GIVEN_amend_plan_without_payload_or_non_planner_role_WHEN_executed_THEN_ignores_request', async () => {
+    const provider = makeProvider({
+      outputs: [
+        {
+          type: 'REQUEST',
+          request: {
+            action: 'amend_plan',
+            plan_json: {}
+          }
+        },
+        {
+          type: 'REQUEST',
+          request: {
+            action: 'amend_plan',
+            plan_json: {
+              feature_id: 'feature_a'
+            }
+          }
+        }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'builder',
+      featureId: 'feature_a',
+      contextBundle: {},
+      instructions: 'amend'
+    });
+
+    expect(result.planSubmission).toBe(false);
+    expect(result.requestHandled).toBe(false);
+  });
+
+  it('GIVEN_unknown_or_malformed_outputs_WHEN_executed_THEN_ignores_them_without_crashing', async () => {
+    const provider = makeProvider({
+      outputs: [
+        null,
+        {},
+        { type: 'UNSUPPORTED' },
+        { type: 'REQUEST', request: {} },
+        { type: 'NOTE', content: 'x' }
+      ]
+    });
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'orchestrator',
+      featureId: 'global',
+      contextBundle: {},
+      instructions: 'noop'
+    });
+
+    expect(result.noteLogged).toBe(true);
+    expect(result.planSubmission).toBe(false);
+    expect(result.patchApplied).toBe(false);
+  });
+
+  it('extracts orchestrator prioritize requests into deterministic priority ordering', async () => {
+    const provider = makeProvider({
+      type: 'REQUEST',
+      request: {
+        action: 'prioritize',
+        feature_order: ['feature_c', 'feature_a']
+      }
+    });
+
+    const toolCaller = makeToolCaller();
+    const loop = new WorkerDecisionLoop({
+      provider: provider as never,
+      toolCaller: toolCaller as never
+    });
+
+    const result = await loop.execute({
+      role: 'orchestrator',
+      featureId: 'global',
+      contextBundle: {
+        active_feature_ids: ['feature_a', 'feature_b', 'feature_c']
+      },
+      instructions: 'prioritize'
+    });
+
+    expect(result.requestHandled).toBe(true);
+    expect(result.priorityOrder).toEqual(['feature_c', 'feature_a']);
+  });
+});

package/apps/control-plane/tsconfig.build.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "../../dist/apps/control-plane",
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "test/**/*.ts",
+    "vitest.config.ts"
+  ]
+}

package/apps/control-plane/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node", "vitest/globals"]
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts",
+    "vitest.config.ts"
+  ]
+}

package/apps/control-plane/vitest.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['apps/control-plane/test/**/*.spec.ts'],
+    coverage: {
+      enabled: true,
+      provider: 'v8',
+      reporter: ['text', 'json-summary', 'lcov'],
+      reportsDirectory: 'coverage/control-plane',
+      include: ['apps/control-plane/src/**/*.{ts,tsx}'],
+      exclude: [
+        '**/*.d.ts',
+        '**/*.test.*',
+        '**/*.spec.*',
+        '**/__tests__/**',
+        'dist/**'
+      ],
+      thresholds: {
+        lines: 70,
+        branches: 70,
+        functions: 85,
+        statements: 70
+      }
+    }
+  }
+});

package/dist/apps/control-plane/application/services/collision-queue-service.d.ts

@@ -0,0 +1,69 @@
+type AnyRecord = Record<string, any>;
+type StateReadResult = {
+    frontMatter: AnyRecord;
+};
+type StateUpdater = (frontMatter: AnyRecord, body: string) => Promise<{
+    frontMatter?: AnyRecord;
+    body?: string;
+}>;
+interface QueueEntry {
+    feature_id: string;
+    plan_version: number;
+    detected_at: string;
+    collision_fingerprint: string;
+    required_resources: string[];
+    plan_snapshot?: AnyRecord;
+}
+export interface CollisionQueueServicePort {
+    getPolicySnapshot(): AnyRecord;
+    planPath(featureId: string): string;
+    statePath(featureId: string): string;
+    featureDiscoverSpecs(): Promise<{
+        data: {
+            specs: Array<{
+                feature_id: string;
+            }>;
+        };
+    }>;
+    readState(featureId: string): Promise<StateReadResult>;
+    withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+    withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+    readIndex(): Promise<AnyRecord>;
+    writeIndex(index: AnyRecord): Promise<void>;
+    updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
+    planSubmit(featureId: string, plan: AnyRecord, expectedVersion: number | null): Promise<{
+        data: {
+            feature_id: string;
+            accepted: boolean;
+            plan_version: number;
+        };
+    }>;
+}
+export declare class CollisionQueueService {
+    private readonly port;
+    constructor(port: CollisionQueueServicePort);
+    collectAcceptedPlans(excludeFeatureId?: string | null): Promise<AnyRecord[]>;
+    requiredResourcesForPlan(plan: AnyRecord): string[];
+    assertPlanLocksHeld(featureId: string, plan: AnyRecord): Promise<boolean>;
+    checkPlanCollision(featureId: string, plan: AnyRecord): Promise<{
+        hasCollisions: boolean;
+        fingerprint?: string;
+    }>;
+    processSingleQueueEntry(entry: QueueEntry): Promise<{
+        retried: boolean;
+        reason?: string;
+    }>;
+    reDriveBlockedQueue(): Promise<{
+        data: {
+            processed: number;
+            retried: number;
+            still_blocked: number;
+        };
+    }>;
+    clearQueueEntry(featureId: string): Promise<{
+        data: {
+            removed: boolean;
+        };
+    }>;
+}
+export {};