agentic-orchestrator 0.1.2 → 0.1.4

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

@@ -4,10 +4,16 @@ 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 { TOOLS } from '../src/core/constants.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';
+import {
+  isMutatingTool,
+  toolRequiresOperationId,
+  withOperationIdIfRequired
+} from '../src/application/tools/tool-metadata.js';
 
 describe('McpServerAdapter helpers', () => {
   it('GIVEN_valid_token_and_empty_arguments_WHEN_calling_tool_THEN_forwards_claims', async () => {
@@ -192,4 +198,174 @@ describe('ToolContractValidator', () => {
     expect(invalidOutput.valid).toBe(false);
     expect(invalidOutput.errors.length).toBeGreaterThan(0);
   });
+
+  it('GIVEN_valid_input_and_output_WHEN_validating_THEN_returns_valid_with_no_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 never, registry as never);
+    // Call twice to exercise getOrCompile cache hit
+    const valid1 = await validator.validateInput(tool as never, { id: 'test' });
+    const valid2 = await validator.validateInput(tool as never, { id: 'test' });
+    const validOut = await validator.validateOutput(tool as never, { result: 'ok' });
+
+    expect(valid1.valid).toBe(true);
+    expect(valid1.errors).toEqual([]);
+    expect(valid2.valid).toBe(true); // cache hit
+    expect(validOut.valid).toBe(true);
+    expect(validOut.errors).toEqual([]);
+  });
+
+  it('GIVEN_valid_error_envelope_WHEN_validateErrorEnvelope_called_THEN_returns_valid', async () => {
+    const loader = {
+      readErrorsSchema: vi.fn(async () => ({
+        type: 'object',
+        required: ['ok'],
+        properties: { ok: { type: 'boolean' } }
+      })),
+      readSchemaByRef: vi.fn(async () => ({}))
+    };
+    const registry = { toolsRoot: '/tmp' };
+
+    const validator = await ToolContractValidator.create(loader as never, registry as never);
+    const result = validator.validateErrorEnvelope({ ok: false });
+    expect(result.valid).toBe(true);
+
+    const invalid = validator.validateErrorEnvelope({ bad: true });
+    expect(invalid.valid).toBe(false);
+  });
+
+  it('GIVEN_validator_returns_false_with_null_errors_WHEN_validateInput_called_THEN_returns_empty_errors_array', async () => {
+    const loader = {
+      readErrorsSchema: vi.fn(async () => ({
+        type: 'object',
+        required: ['ok'],
+        properties: { ok: { type: 'boolean' } }
+      })),
+      readSchemaByRef: vi.fn(async () => ({}))
+    };
+    const registry = { toolsRoot: '/tmp' };
+    const validator = await ToolContractValidator.create(loader as never, registry as never);
+
+    const mockFn = vi.fn(() => false) as ReturnType<typeof vi.fn> & { errors: null };
+    mockFn.errors = null;
+    validator.validators.set(path.resolve('/tmp', 'schemas/input/null-errors.json'), mockFn as never);
+
+    const tool = { input_schema_ref: 'schemas/input/null-errors.json' } as never;
+    const result = await validator.validateInput(tool, {});
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('GIVEN_validator_returns_false_with_null_errors_WHEN_validateOutput_called_THEN_returns_empty_errors_array', async () => {
+    const loader = {
+      readErrorsSchema: vi.fn(async () => ({
+        type: 'object',
+        required: ['ok'],
+        properties: { ok: { type: 'boolean' } }
+      })),
+      readSchemaByRef: vi.fn(async () => ({}))
+    };
+    const registry = { toolsRoot: '/tmp' };
+    const validator = await ToolContractValidator.create(loader as never, registry as never);
+
+    const mockFn = vi.fn(() => false) as ReturnType<typeof vi.fn> & { errors: null };
+    mockFn.errors = null;
+    validator.validators.set(path.resolve('/tmp', 'schemas/output/null-errors.json'), mockFn as never);
+
+    const tool = { output_schema_ref: 'schemas/output/null-errors.json' } as never;
+    const result = await validator.validateOutput(tool, {});
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('GIVEN_errorsValidator_returns_false_with_null_errors_WHEN_validateErrorEnvelope_called_THEN_returns_empty_errors', async () => {
+    const loader = {
+      readErrorsSchema: vi.fn(async () => ({
+        type: 'object',
+        required: ['ok'],
+        properties: { ok: { type: 'boolean' } }
+      })),
+      readSchemaByRef: vi.fn(async () => ({}))
+    };
+    const registry = { toolsRoot: '/tmp' };
+    const validator = await ToolContractValidator.create(loader as never, registry as never);
+
+    const nullErrorsFn = vi.fn(() => false) as ReturnType<typeof vi.fn> & { errors: null };
+    nullErrorsFn.errors = null;
+    (validator as never as { errorsValidator: unknown }).errorsValidator = nullErrorsFn;
+
+    const result = validator.validateErrorEnvelope({ bad: true });
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual([]);
+  });
+});
+
+describe('ToolMetadata helpers', () => {
+  const MUTATING = TOOLS.FEATURE_INIT;
+  const NON_MUTATING = TOOLS.FEATURE_STATE_GET;
+
+  it('GIVEN_mutating_tool_name_WHEN_isMutatingTool_called_THEN_returns_true', () => {
+    expect(isMutatingTool(MUTATING)).toBe(true);
+  });
+
+  it('GIVEN_non_mutating_tool_name_WHEN_isMutatingTool_called_THEN_returns_false', () => {
+    expect(isMutatingTool(NON_MUTATING)).toBe(false);
+  });
+
+  it('GIVEN_tool_requiring_operation_id_WHEN_toolRequiresOperationId_called_THEN_returns_true', () => {
+    expect(toolRequiresOperationId(MUTATING)).toBe(true);
+  });
+
+  it('GIVEN_tool_not_requiring_operation_id_WHEN_toolRequiresOperationId_called_THEN_returns_false', () => {
+    expect(toolRequiresOperationId(NON_MUTATING)).toBe(false);
+  });
+
+  it('GIVEN_mutating_tool_without_operation_id_WHEN_withOperationIdIfRequired_called_THEN_generates_operation_id', () => {
+    const args = { feature_id: 'my-feature' };
+    const createId = (_toolName: string, featureId?: string) => `gen-op:${featureId ?? 'global'}`;
+    const result = withOperationIdIfRequired(MUTATING, args, createId);
+    expect(result.operation_id).toBe('gen-op:my-feature');
+  });
+
+  it('GIVEN_mutating_tool_with_existing_operation_id_WHEN_withOperationIdIfRequired_called_THEN_preserves_existing', () => {
+    const args = { feature_id: 'my-feature', operation_id: 'existing-op-id' };
+    const createId = vi.fn(() => 'should-not-be-called');
+    const result = withOperationIdIfRequired(MUTATING, args, createId);
+    expect(result.operation_id).toBe('existing-op-id');
+    expect(createId).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_non_mutating_tool_WHEN_withOperationIdIfRequired_called_THEN_returns_args_unchanged', () => {
+    const args = { feature_id: 'my-feature' };
+    const createId = vi.fn(() => 'should-not-be-called');
+    const result = withOperationIdIfRequired(NON_MUTATING, args, createId);
+    expect(result).toEqual(args);
+    expect(result.operation_id).toBeUndefined();
+    expect(createId).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_cost_record_tool_WHEN_isMutatingTool_called_THEN_returns_true', () => {
+    expect(isMutatingTool(TOOLS.COST_RECORD)).toBe(true);
+  });
+
+  it('GIVEN_cost_record_tool_WHEN_toolRequiresOperationId_called_THEN_returns_true', () => {
+    expect(toolRequiresOperationId(TOOLS.COST_RECORD)).toBe(true);
+  });
 });

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

@@ -49,6 +49,17 @@ async function readIndex() {
   return JSON.parse(raw);
 }
 
+async function readRunLease() {
+  const leaseFile = path.join(repoRoot, '.aop', 'runtime', 'default', 'run-lease.json');
+  const raw = await fs.readFile(leaseFile, 'utf8');
+  return JSON.parse(raw);
+}
+
+async function writeRunLease(data: Record<string, unknown>) {
+  const leaseFile = path.join(repoRoot, '.aop', 'runtime', 'default', 'run-lease.json');
+  await fs.writeFile(leaseFile, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
 async function writeIndex(index: Record<string, unknown>) {
   await fs.writeFile(path.join(repoRoot, '.aop', 'features', 'index.json'), `${JSON.stringify(index, null, 2)}\n`, 'utf8');
 }
@@ -382,6 +393,32 @@ describe('MCP formalization', () => {
   });
 });
 
+describe('MCP utility functions', () => {
+  it('GIVEN_no_featureId_WHEN_createOperationId_called_THEN_returns_toolname_and_uuid', () => {
+    const id = createOperationId('feature.init');
+    expect(id).toMatch(/^feature_init__[0-9a-f-]{36}$/);
+  });
+
+  it('GIVEN_mcpClient_WHEN_listTools_called_THEN_returns_tool_list', async () => {
+    const { tooling } = await boot();
+    const tools = await tooling.mcpClient.listTools();
+    expect(Array.isArray(tools)).toBe(true);
+    expect(tools.length).toBeGreaterThan(0);
+  });
+
+  it('GIVEN_generateToolsMarkdown_false_WHEN_createToolingRuntime_called_THEN_succeeds', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    const { createToolingRuntime: ctRt, resolveToolClient: rtc } = await import('../src/mcp/runtime-factory.js');
+    const tooling = await ctRt(repoRoot, kernel, { generateToolsMarkdown: false });
+    expect(tooling.inProcessClient).toBeDefined();
+    const mcpClient = rtc('mcp', tooling);
+    expect(mcpClient).toBe(tooling.mcpClient);
+    const inpClient = rtc('inprocess', tooling);
+    expect(inpClient).toBe(tooling.inProcessClient);
+  });
+});
+
 async function runCriticalFlow(
   client: ToolClient,
   input: {
@@ -510,9 +547,7 @@ async function runCriticalFlow(
   );
   expect(merged.ok).toBe(true);
 
-  await expect(
-    fs.stat(path.join(repoRoot, '.aop', 'features', input.featureId))
-  ).rejects.toMatchObject({ code: 'ENOENT' });
+  await expect(fs.stat(path.join(repoRoot, '.aop', 'features', input.featureId))).resolves.toBeDefined();
 
   return {
     statusTimeline: [
@@ -735,9 +770,9 @@ async function runTakeoverAndRecoveryFlow(
   });
   await sourceRuntime.start([{ feature_id: featureId }]);
 
-  const staleIndex = await readIndex();
-  staleIndex.runtime_sessions.lease_expires_at = new Date(Date.now() - 60_000).toISOString();
-  await writeIndex(staleIndex);
+  const staleLease = await readRunLease();
+  staleLease.lease_expires_at = new Date(Date.now() - 60_000).toISOString();
+  await writeRunLease(staleLease);
 
   const noTakeoverRuntime = new SupervisorRuntime(kernel, provider, client, {
     run_id: `run:${label}:target:no-takeover`,
@@ -757,20 +792,20 @@ async function runTakeoverAndRecoveryFlow(
   });
   await takeoverRuntime.start([{ feature_id: featureId }]);
 
-  const postTakeover = await readIndex();
-  const takeoverSessionId = postTakeover.runtime_sessions.orchestrator_session_id;
-  const takeoverEpoch = Number(postTakeover.runtime_sessions.orchestrator_epoch ?? 0);
+  const postTakeover = await readRunLease();
+  const takeoverSessionId = postTakeover.orchestrator_session_id;
+  const takeoverEpoch = Number(postTakeover.orchestrator_epoch ?? 0);
 
-  postTakeover.runtime_sessions.lease_expires_at = new Date(Date.now() - 60_000).toISOString();
-  await writeIndex(postTakeover);
+  postTakeover.lease_expires_at = new Date(Date.now() - 60_000).toISOString();
+  await writeRunLease(postTakeover);
 
   await takeoverRuntime.start([{ feature_id: featureId }]);
-  const postRecovery = await readIndex();
+  const postRecovery = await readRunLease();
 
   return {
     noTakeoverCode,
-    takeoverSucceeded: postTakeover.runtime_sessions.run_id === `run:${label}:target:takeover`,
-    epochIncrementedOnRecovery: Number(postRecovery.runtime_sessions.orchestrator_epoch ?? 0) === takeoverEpoch + 1,
-    orchestratorSessionRotated: postRecovery.runtime_sessions.orchestrator_session_id !== takeoverSessionId
+    takeoverSucceeded: postTakeover.run_id === `run:${label}:target:takeover`,
+    epochIncrementedOnRecovery: Number(postRecovery.orchestrator_epoch ?? 0) === takeoverEpoch + 1,
+    orchestratorSessionRotated: postRecovery.orchestrator_session_id !== takeoverSessionId
   };
 }

package/apps/control-plane/test/merge-service.spec.ts

@@ -333,7 +333,8 @@ describe('MergeService', () => {
       feature_id: 'feature_merge',
       merge_sha: 'abc123',
       merge_strategy: 'rebase',
-      status: STATUS.MERGED
+      status: STATUS.MERGED,
+      retained_for_cleanup: true
     });
     expect(harness.state.frontMatter.status).toBe(STATUS.MERGED);
     expect((harness.state.frontMatter.evidence as AnyRecord).merge_strategy).toBe('rebase');
@@ -349,9 +350,71 @@ describe('MergeService', () => {
     expect(index.runtime_sessions.feature_sessions.other).toMatchObject({
       planner_session_id: 'planner-b'
     });
-    expect(rmMock).toHaveBeenCalledWith('/repo/.aop/features/feature_merge', {
-      recursive: true,
-      force: true
+    expect(rmMock).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_auto_cleanup_enabled_with_zero_grace_WHEN_merge_succeeds_THEN_removes_worktree_branch_and_feature_dir', async () => {
+    const harness = makeHarness({
+      policyOverrides: {
+        cleanup: {
+          auto_after_merge: true,
+          grace_period_seconds: 0
+        }
+      }
+    });
+
+    vi.mocked(runGit).mockImplementation(async (_repoRoot, args) => {
+      if (args[0] === 'rev-parse' && args[1] === 'HEAD') {
+        return commandResult({ stdout: 'abc123\n' });
+      }
+      return commandResult();
+    });
+
+    const result = await harness.service.featureReadyToMerge('feature_merge', 'merge', 'merge_commit', 'approved');
+
+    expect(result.data).toMatchObject({
+      retained_for_cleanup: false,
+      cleanup_grace_period_seconds: 0
     });
+    expect(runGit).toHaveBeenCalledWith('/repo', ['worktree', 'remove', '--force', '/repo/.worktrees/feature_merge']);
+    expect(runGit).toHaveBeenCalledWith('/repo', ['branch', '-D', 'feature_merge']);
+    expect(rmMock).toHaveBeenCalledWith('/repo/.aop/features/feature_merge', { recursive: true, force: true });
+  });
+
+  it('GIVEN_auto_cleanup_enabled_with_grace_WHEN_merge_succeeds_THEN_schedules_cleanup_after_delay', async () => {
+    vi.useFakeTimers();
+    try {
+      const harness = makeHarness({
+        policyOverrides: {
+          cleanup: {
+            auto_after_merge: true,
+            grace_period_seconds: 1
+          }
+        }
+      });
+
+      vi.mocked(runGit).mockImplementation(async (_repoRoot, args) => {
+        if (args[0] === 'rev-parse' && args[1] === 'HEAD') {
+          return commandResult({ stdout: 'abc123\n' });
+        }
+        return commandResult();
+      });
+
+      const result = await harness.service.featureReadyToMerge('feature_merge', 'merge', 'merge_commit', 'approved');
+
+      expect(result.data).toMatchObject({
+        retained_for_cleanup: true,
+        cleanup_grace_period_seconds: 1
+      });
+      expect(rmMock).not.toHaveBeenCalled();
+
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(runGit).toHaveBeenCalledWith('/repo', ['worktree', 'remove', '--force', '/repo/.worktrees/feature_merge']);
+      expect(runGit).toHaveBeenCalledWith('/repo', ['branch', '-D', 'feature_merge']);
+      expect(rmMock).toHaveBeenCalledWith('/repo/.aop/features/feature_merge', { recursive: true, force: true });
+    } finally {
+      vi.useRealTimers();
+    }
   });
 });