agentic-orchestrator 0.1.0

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

@@ -0,0 +1,369 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AopKernel } from '../src/index.js';
+import { runGit } from '../src/core/git.js';
+import { makeTempRepo, writeFeatureSpec } from './helpers.js';
+
+let repoRoot: string;
+
+beforeEach(async () => {
+  repoRoot = await makeTempRepo(process.cwd());
+  await fs.mkdir(path.join(repoRoot, 'src'), { recursive: true });
+  await fs.writeFile(path.join(repoRoot, 'src', 'sample.txt'), 'hello\n', 'utf8');
+});
+
+describe('AopKernel', () => {
+  it('migrates legacy runtime artifacts from agentic into .aop when .aop is absent', async () => {
+    await fs.rm(path.join(repoRoot, '.aop'), { recursive: true, force: true });
+    await fs.mkdir(path.join(repoRoot, 'agentic', 'features'), { recursive: true });
+
+    const legacyIndexPath = path.join(repoRoot, 'agentic', 'features', 'index.json');
+    const legacySpecPath = path.join(repoRoot, 'agentic', 'features', 'legacy_feature', 'spec.md');
+    await fs.mkdir(path.dirname(legacySpecPath), { recursive: true });
+    await fs.writeFile(legacySpecPath, '# Legacy Spec\n', 'utf8');
+    await fs.writeFile(
+      legacyIndexPath,
+      `${JSON.stringify(
+        {
+          version: 1,
+          active: [],
+          blocked: [],
+          merged: [],
+          locks: {},
+          lock_leases: {},
+          blocked_queue: [],
+          updated_at: new Date().toISOString()
+        },
+        null,
+        2
+      )}\n`,
+      'utf8'
+    );
+
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+
+    const index = await (kernel as any).readIndex();
+    expect(await fs.readFile(path.join(repoRoot, '.aop', 'features', 'legacy_feature', 'spec.md'), 'utf8')).toContain('Legacy Spec');
+    expect(index.runtime_sessions).toBeTruthy();
+    expect(index.runtime_sessions.orchestrator_session_id).toBe('unknown');
+    expect(typeof index.runtime_sessions.lease_expires_at).toBe('string');
+  });
+
+  it('prefers existing .aop runtime artifacts over legacy agentic artifacts when both exist', async () => {
+    const legacySpecPath = path.join(repoRoot, 'agentic', 'features', 'priority_feature', 'spec.md');
+    await fs.mkdir(path.dirname(legacySpecPath), { recursive: true });
+    await fs.writeFile(legacySpecPath, '# Legacy Priority Spec\n', 'utf8');
+
+    const aopSpecPath = path.join(repoRoot, '.aop', 'features', 'priority_feature', 'spec.md');
+    await fs.mkdir(path.dirname(aopSpecPath), { recursive: true });
+    await fs.writeFile(aopSpecPath, '# AOP Priority Spec\n', 'utf8');
+
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await kernel.invoke('feature.init', { feature_id: 'priority_feature' }, { actor_type: 'orchestrator', actor_id: 't-priority' });
+
+    const context = await kernel.invoke(
+      'feature.get_context',
+      { feature_id: 'priority_feature' },
+      { actor_type: 'orchestrator', actor_id: 't-priority' }
+    );
+    expect(context.ok).toBe(true);
+    expect(context.data.spec).toContain('AOP Priority Spec');
+    expect(context.data.spec).not.toContain('Legacy Priority Spec');
+  });
+
+  it('initializes feature state and worktree', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_one');
+
+    const init = await kernel.invoke('feature.init', { feature_id: 'feature_one' }, { actor_type: 'orchestrator', actor_id: 't1' });
+    expect(init.ok).toBe(true);
+
+    const state = await kernel.invoke('feature.state_get', { feature_id: 'feature_one' }, { actor_type: 'orchestrator', actor_id: 't1' });
+    expect(state.ok).toBe(true);
+    expect(state.data.front_matter.status).toBe('planning');
+
+    const worktreePath = path.join(repoRoot, '.worktrees', 'feature_one');
+    await expect(fs.stat(worktreePath)).resolves.toBeTruthy();
+  });
+
+  it('enforces contract locks during plan submission', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_two');
+    await kernel.invoke('feature.init', { feature_id: 'feature_two' }, { actor_type: 'orchestrator', actor_id: 't2' });
+
+    const plan = {
+      feature_id: 'feature_two',
+      plan_version: 1,
+      summary: 'Add migration',
+      allowed_areas: ['src'],
+      forbidden_areas: [],
+      base_ref: 'HEAD',
+      files: { create: [], modify: ['src/sample.txt'], delete: [] },
+      contracts: { openapi: 'none', events: 'none', db: 'migration' },
+      acceptance_criteria: ['works'],
+      gate_profile: 'default'
+    };
+
+    const rejected = await kernel.invoke('plan.submit', { feature_id: 'feature_two', plan_json: plan }, { actor_type: 'orchestrator', actor_id: 't2' });
+    expect(rejected.ok).toBe(false);
+    expect(rejected.error.code).toBe('lock_not_held');
+
+    const lock = await kernel.invoke('locks.acquire', { resource: 'db_migrations', feature_id: 'feature_two' }, { actor_type: 'orchestrator', actor_id: 't2' });
+    expect(lock.ok).toBe(true);
+
+    const accepted = await kernel.invoke('plan.submit', { feature_id: 'feature_two', plan_json: plan }, { actor_type: 'orchestrator', actor_id: 't2' });
+    expect(accepted.ok).toBe(true);
+  });
+
+  it('rejects patch files outside planned file set', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_three');
+    await kernel.invoke('feature.init', { feature_id: 'feature_three' }, { actor_type: 'orchestrator', actor_id: 't3' });
+
+    const plan = {
+      feature_id: 'feature_three',
+      plan_version: 1,
+      summary: 'touch only sample file',
+      allowed_areas: ['src'],
+      forbidden_areas: [],
+      base_ref: 'HEAD',
+      files: { create: [], modify: ['src/sample.txt'], delete: [] },
+      contracts: { openapi: 'none', events: 'none', db: 'none' },
+      acceptance_criteria: ['works'],
+      gate_profile: 'default'
+    };
+
+    const planResult = await kernel.invoke('plan.submit', { feature_id: 'feature_three', plan_json: plan }, { actor_type: 'orchestrator', actor_id: 't3' });
+    expect(planResult.ok).toBe(true);
+
+    const diff = [
+      'diff --git a/src/other.txt b/src/other.txt',
+      'new file mode 100644',
+      '--- /dev/null',
+      '+++ b/src/other.txt',
+      '@@ -0,0 +1,1 @@',
+      '+x'
+    ].join('\n');
+
+    const patchResult = await kernel.invoke('repo.apply_patch', { feature_id: 'feature_three', unified_diff: diff }, { actor_type: 'builder', actor_id: 't3' });
+    expect(patchResult.ok).toBe(false);
+    expect(patchResult.error.code).toBe('patch_policy_violation');
+  });
+
+  it('updates QA index with optimistic concurrency', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_four');
+    await kernel.invoke('feature.init', { feature_id: 'feature_four' }, { actor_type: 'orchestrator', actor_id: 't4' });
+
+    const initial = await kernel.invoke('qa.test_index_get', { feature_id: 'feature_four' }, { actor_type: 'qa', actor_id: 't4' });
+    expect(initial.ok).toBe(true);
+
+    const conflict = await kernel.invoke(
+      'qa.test_index_update',
+      {
+        feature_id: 'feature_four',
+        expected_version: initial.data.index.version + 1,
+        updates: []
+      },
+      { actor_type: 'qa', actor_id: 't4' }
+    );
+
+    expect(conflict.ok).toBe(false);
+    expect(conflict.error.code).toBe('qa_index_version_conflict');
+  });
+
+  it('previews and applies deterministic feature deletion with residue cleanup', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_delete');
+    await kernel.invoke('feature.init', { feature_id: 'feature_delete' }, { actor_type: 'orchestrator', actor_id: 't-delete' });
+    await kernel.invoke(
+      'locks.acquire',
+      { resource: 'openapi', feature_id: 'feature_delete' },
+      { actor_type: 'orchestrator', actor_id: 't-delete' }
+    );
+
+    const indexPath = path.join(repoRoot, '.aop', 'features', 'index.json');
+    const index = JSON.parse(await fs.readFile(indexPath, 'utf8')) as Record<string, unknown>;
+    index.blocked_queue = [
+      {
+        feature_id: 'feature_delete',
+        plan_version: 1,
+        detected_at: '2026-03-01T00:00:00.000Z',
+        collision_fingerprint: 'fp:feature_delete',
+        required_resources: ['openapi']
+      },
+      {
+        feature_id: 'other_feature',
+        plan_version: 1,
+        detected_at: '2026-03-01T00:00:00.000Z',
+        collision_fingerprint: 'fp:other_feature',
+        required_resources: ['openapi']
+      }
+    ];
+    const runtimeSessions = index.runtime_sessions as { feature_sessions?: Record<string, unknown> };
+    runtimeSessions.feature_sessions = {
+      ...(runtimeSessions.feature_sessions ?? {}),
+      feature_delete: {
+        planner_session_id: 'planner:1',
+        builder_session_id: 'builder:1',
+        qa_session_id: 'qa:1'
+      }
+    };
+    index.runtime_sessions = runtimeSessions;
+    await fs.writeFile(indexPath, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+
+    const preview = await kernel.invoke(
+      'feature.delete',
+      {
+        feature_id: 'feature_delete',
+        dry_run: true,
+        confirm: false,
+        remove_worktree: true,
+        remove_branch: 'none'
+      },
+      { actor_type: 'system', actor_id: 'cleanup:preview' }
+    );
+    expect(preview.ok).toBe(true);
+    expect(preview.data.dry_run).toBe(true);
+    expect(preview.data.plan.blocked_queue_entries).toBe(1);
+    expect(preview.data.plan.runtime_session_assignment_exists).toBe(true);
+    expect(preview.data.summary.feature_dir_removed).toBe(false);
+
+    await expect(fs.stat(path.join(repoRoot, '.aop', 'features', 'feature_delete'))).resolves.toBeTruthy();
+    await expect(fs.stat(path.join(repoRoot, '.worktrees', 'feature_delete'))).resolves.toBeTruthy();
+
+    const applied = await kernel.invoke(
+      'feature.delete',
+      {
+        feature_id: 'feature_delete',
+        dry_run: false,
+        confirm: true,
+        remove_worktree: true,
+        remove_branch: 'none'
+      },
+      { actor_type: 'system', actor_id: 'cleanup:apply' }
+    );
+    expect(applied.ok).toBe(true);
+    expect(applied.data.summary.locks_released).toContain('openapi');
+    expect(applied.data.summary.blocked_queue_entries_removed).toBe(1);
+    expect(applied.data.summary.runtime_session_assignment_removed).toBe(true);
+    expect(applied.data.summary.feature_dir_removed).toBe(true);
+    expect(applied.data.summary.worktree_removed).toBe(true);
+
+    await expect(fs.stat(path.join(repoRoot, '.aop', 'features', 'feature_delete'))).rejects.toThrow();
+    await expect(fs.stat(path.join(repoRoot, '.worktrees', 'feature_delete'))).rejects.toThrow();
+
+    const postIndex = JSON.parse(await fs.readFile(indexPath, 'utf8')) as {
+      active: string[];
+      blocked_queue: Array<{ feature_id?: string }>;
+      locks: Record<string, string | null>;
+      runtime_sessions: { feature_sessions?: Record<string, unknown> };
+    };
+    expect(postIndex.active).not.toContain('feature_delete');
+    expect(postIndex.blocked_queue.map((entry) => entry.feature_id)).not.toContain('feature_delete');
+    expect(postIndex.locks.openapi).toBeNull();
+    expect(postIndex.runtime_sessions.feature_sessions?.feature_delete).toBeUndefined();
+
+    const rerun = await kernel.invoke(
+      'feature.delete',
+      {
+        feature_id: 'feature_delete',
+        dry_run: false,
+        confirm: true,
+        remove_worktree: true,
+        remove_branch: 'none'
+      },
+      { actor_type: 'system', actor_id: 'cleanup:rerun' }
+    );
+    expect(rerun.ok).toBe(true);
+    expect(rerun.data.summary.feature_dir_removed).toBe(false);
+    expect(rerun.data.summary.worktree_removed).toBe(false);
+    expect(rerun.data.summary.blocked_queue_entries_removed).toBe(0);
+  });
+
+  it('rejects feature.delete when a fresh run lease exists', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_guard');
+    await kernel.invoke('feature.init', { feature_id: 'feature_guard' }, { actor_type: 'orchestrator', actor_id: 't-guard' });
+
+    await kernel.acquireRunLease({
+      run_id: 'run:guard',
+      owner_instance_id: 'owner:guard',
+      provider: 'custom',
+      model: 'test',
+      provider_config_ref_hash: 'hash'
+    });
+
+    const blocked = await kernel.invoke(
+      'feature.delete',
+      {
+        feature_id: 'feature_guard',
+        dry_run: true,
+        confirm: false,
+        remove_worktree: true,
+        remove_branch: 'none'
+      },
+      { actor_type: 'system', actor_id: 'cleanup:guard' }
+    );
+
+    expect(blocked.ok).toBe(false);
+    expect(blocked.error.code).toBe('run_already_active');
+  });
+
+  it('enforces safe-vs-force branch deletion behavior for feature.delete', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_branch_cleanup');
+    await kernel.invoke(
+      'feature.init',
+      { feature_id: 'feature_branch_cleanup' },
+      { actor_type: 'orchestrator', actor_id: 't-branch' }
+    );
+
+    const worktree = path.join(repoRoot, '.worktrees', 'feature_branch_cleanup');
+    await fs.mkdir(path.join(worktree, 'src'), { recursive: true });
+    await fs.writeFile(path.join(worktree, 'src', 'branch-only.txt'), 'branch only\n', 'utf8');
+    await runGit(repoRoot, ['add', '-A'], { cwd: worktree });
+    await runGit(repoRoot, ['commit', '-m', 'branch-only commit'], { cwd: worktree });
+
+    const safeDelete = await kernel.invoke(
+      'feature.delete',
+      {
+        feature_id: 'feature_branch_cleanup',
+        dry_run: false,
+        confirm: true,
+        remove_worktree: true,
+        remove_branch: 'safe'
+      },
+      { actor_type: 'system', actor_id: 'cleanup:safe' }
+    );
+    expect(safeDelete.ok).toBe(false);
+    expect(safeDelete.error.code).toBe('git_failure');
+
+    const forceDelete = await kernel.invoke(
+      'feature.delete',
+      {
+        feature_id: 'feature_branch_cleanup',
+        dry_run: false,
+        confirm: true,
+        remove_worktree: true,
+        remove_branch: 'force'
+      },
+      { actor_type: 'system', actor_id: 'cleanup:force' }
+    );
+    expect(forceDelete.ok).toBe(true);
+    expect(forceDelete.data.summary.branch_removed).toBe(true);
+
+    const branchLookup = await runGit(repoRoot, ['show-ref', '--verify', 'refs/heads/feature_branch_cleanup']);
+    expect(branchLookup.code).not.toBe(0);
+  });
+});

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

@@ -0,0 +1,195 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ok } from '../src/core/response.js';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+import { McpServerAdapter } from '../src/index.js';
+import { OperationLedger } from '../src/mcp/operation-ledger.js';
+import { ToolAuthorizer } from '../src/mcp/tool-authorizer.js';
+import { ToolContractValidator } from '../src/mcp/tool-contract-validator.js';
+
+describe('McpServerAdapter helpers', () => {
+  it('GIVEN_valid_token_and_empty_arguments_WHEN_calling_tool_THEN_forwards_claims', async () => {
+    const runtime = {
+      listTools: vi.fn(async () => [{ name: 'report.dashboard' }]),
+      callTool: vi.fn(async () => ok({ accepted: true }))
+    };
+    const auth = {
+      verifyToken: vi.fn(() => ({
+        run_id: 'run-1',
+        session_id: 'session-1',
+        actor_type: 'orchestrator',
+        actor_id: 'actor-1',
+        issued_at: new Date().toISOString(),
+        expires_at: new Date(Date.now() + 60_000).toISOString()
+      }))
+    };
+    const adapter = new McpServerAdapter(runtime as any, auth as any);
+
+    await expect(adapter.toolsList()).resolves.toEqual({ tools: [{ name: 'report.dashboard' }] });
+    const response = await adapter.toolsCall({ name: 'report.dashboard' });
+
+    expect(response).toMatchObject({ ok: true, data: { accepted: true } });
+    expect(runtime.callTool).toHaveBeenCalledWith(
+      'report.dashboard',
+      {},
+      expect.objectContaining({ actor_type: 'orchestrator', actor_id: 'actor-1' })
+    );
+  });
+
+  it('GIVEN_mismatched_actor_claim_or_normalized_error_WHEN_calling_tool_THEN_returns_expected_failure', async () => {
+    const runtime = {
+      callTool: vi.fn()
+    };
+    const auth = {
+      verifyToken: vi.fn(() => ({
+        run_id: 'run-1',
+        session_id: 'session-1',
+        actor_type: 'orchestrator',
+        actor_id: 'actor-1',
+        issued_at: new Date().toISOString(),
+        expires_at: new Date(Date.now() + 60_000).toISOString()
+      }))
+    };
+    const adapter = new McpServerAdapter(runtime as any, auth as any);
+
+    const mismatch = await adapter.toolsCall({
+      name: 'report.dashboard',
+      arguments: { actor_id: 'other-actor' }
+    });
+    expect(mismatch).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.INVALID_ACTOR_CLAIM }
+    });
+
+    auth.verifyToken = vi.fn(() => {
+      throw {
+        normalizedResponse: {
+          ok: false,
+          error: { code: 'normalized_error' }
+        }
+      };
+    });
+    const normalized = await adapter.toolsCall({ name: 'report.dashboard', arguments: {} });
+    expect(normalized).toMatchObject({
+      ok: false,
+      error: { code: 'normalized_error' }
+    });
+
+    auth.verifyToken = vi.fn(() => {
+      throw new Error('invalid signature');
+    });
+    const unauthenticated = await adapter.toolsCall({ name: 'report.dashboard', arguments: {} });
+    expect(unauthenticated).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.UNAUTHENTICATED }
+    });
+  });
+});
+
+describe('OperationLedger', () => {
+  let repoRoot = '';
+
+  afterEach(async () => {
+    if (repoRoot) {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+      repoRoot = '';
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('GIVEN_missing_ledger_file_WHEN_resolving_or_recording_THEN_uses_null-safe_fallbacks', async () => {
+    repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-op-ledger-'));
+    const ledger = new OperationLedger(repoRoot);
+    vi.spyOn(ledger, 'ensureRunLedger').mockResolvedValue(undefined);
+
+    await expect(ledger.resolveOperation('run-x', 'op-x', 'hash-x')).resolves.toEqual({ status: 'new' });
+    await ledger.recordOperation('run-x', 'op-x', 'feature.init', 'hash-x', ok({ initialized: true }));
+
+    const stored = JSON.parse(await fs.readFile(ledger.ledgerPath('run-x'), 'utf8'));
+    expect(stored.operations['op-x']).toMatchObject({
+      operation_id: 'op-x',
+      tool_name: 'feature.init',
+      request_hash: 'hash-x'
+    });
+  });
+
+  it('GIVEN_existing_operation_record_WHEN_recording_same_operation_THEN_preserves_created_at', async () => {
+    repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-op-ledger-'));
+    const ledger = new OperationLedger(repoRoot);
+
+    await ledger.recordOperation('run-y', 'op-y', 'feature.init', 'hash-1', ok({ first: true }));
+    const first = JSON.parse(await fs.readFile(ledger.ledgerPath('run-y'), 'utf8'));
+    const createdAt = first.operations['op-y'].created_at;
+
+    await ledger.recordOperation('run-y', 'op-y', 'feature.init', 'hash-2', ok({ second: true }));
+    const second = JSON.parse(await fs.readFile(ledger.ledgerPath('run-y'), 'utf8'));
+
+    expect(second.operations['op-y'].created_at).toBe(createdAt);
+    expect(second.operations['op-y'].request_hash).toBe('hash-2');
+  });
+});
+
+describe('ToolAuthorizer', () => {
+  const registry = {
+    toolsByName: new Map([
+      ['report.dashboard', { supported_roles: ['orchestrator'] }],
+      ['feature.init', { supported_roles: ['orchestrator', 'system'] }]
+    ])
+  };
+
+  it('GIVEN_missing_tool_or_role_allowlist_WHEN_authorizing_THEN_returns_false', () => {
+    const authorizer = new ToolAuthorizer({}, registry as any);
+    expect(authorizer.isAuthorized('orchestrator', 'missing.tool')).toBe(false);
+    expect(authorizer.isAuthorized('qa', 'report.dashboard')).toBe(false);
+  });
+
+  it('GIVEN_policy_references_unknown_tool_WHEN_constructing_THEN_throws', () => {
+    expect(() => new ToolAuthorizer({ orchestrator: ['missing.tool'] }, registry as any)).toThrow(
+      'policy_references_unknown_tool:orchestrator:missing.tool'
+    );
+  });
+});
+
+describe('ToolContractValidator', () => {
+  it('GIVEN_invalid_input_or_output_payload_WHEN_validating_THEN_returns_errors', async () => {
+    const loader = {
+      readErrorsSchema: vi.fn(async () => ({
+        type: 'object',
+        required: ['ok'],
+        properties: { ok: { type: 'boolean' } }
+      })),
+      readSchemaByRef: vi.fn(async (schemaRef: string) => {
+        if (schemaRef.includes('input')) {
+          return {
+            type: 'object',
+            required: ['id'],
+            properties: { id: { type: 'string' } }
+          };
+        }
+        return {
+          type: 'object',
+          required: ['result'],
+          properties: { result: { type: 'string' } }
+        };
+      })
+    };
+    const registry = {
+      toolsRoot: '/tmp'
+    };
+    const tool = {
+      input_schema_ref: 'schemas/input/tool.schema.json',
+      output_schema_ref: 'schemas/output/tool.schema.json'
+    };
+
+    const validator = await ToolContractValidator.create(loader as any, registry as any);
+    const invalidInput = await validator.validateInput(tool as any, {});
+    const invalidOutput = await validator.validateOutput(tool as any, {});
+
+    expect(invalidInput.valid).toBe(false);
+    expect(invalidInput.errors.length).toBeGreaterThan(0);
+    expect(invalidOutput.valid).toBe(false);
+    expect(invalidOutput.errors.length).toBeGreaterThan(0);
+  });
+});