agentic-orchestrator 0.1.0

package/apps/control-plane/src/core/schemas.ts

@@ -0,0 +1,125 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import Ajv2020Import from 'ajv/dist/2020.js';
+import type { AnySchema, ErrorObject, ValidateFunction } from 'ajv';
+
+export type SchemaId = string;
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ErrorObject[];
+}
+
+export interface SchemaValidator {
+  validate(name: SchemaId, payload: unknown): Promise<ValidationResult>;
+}
+
+type AjvLike = {
+  compile(schema: AnySchema): ValidateFunction;
+  addFormat?: (
+    name: string,
+    format:
+      | RegExp
+      | {
+          type?: string;
+          validate: (value: string) => boolean;
+        }
+  ) => AjvLike;
+};
+
+const RFC3339_DATE_TIME =
+  /^(\d{4})-(\d{2})-(\d{2})T([0-2]\d):([0-5]\d):([0-5]\d)(\.\d{1,9})?(Z|([+-])([0-2]\d):([0-5]\d))$/;
+
+function isStrictRfc3339DateTime(value: string): boolean {
+  if (typeof value !== 'string') {
+    return false;
+  }
+
+  const match = RFC3339_DATE_TIME.exec(value);
+  if (!match) {
+    return false;
+  }
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = Number(match[4]);
+  const minute = Number(match[5]);
+  const second = Number(match[6]);
+  const offsetHour = Number(match[10] ?? 0);
+  const offsetMinute = Number(match[11] ?? 0);
+
+  if (month < 1 || month > 12) {
+    return false;
+  }
+
+  const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+  if (day < 1 || day > daysInMonth) {
+    return false;
+  }
+
+  if (hour > 23 || minute > 59 || second > 59) {
+    return false;
+  }
+
+  if (offsetHour > 23 || offsetMinute > 59) {
+    return false;
+  }
+
+  return !Number.isNaN(Date.parse(value));
+}
+
+export class SchemaRegistry implements SchemaValidator {
+  readonly repoRoot: string;
+  private readonly ajv: AjvLike;
+  private readonly validators: Map<SchemaId, ValidateFunction>;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+    const Ajv2020Ctor = Ajv2020Import as unknown as new (options?: Record<string, unknown>) => AjvLike;
+    this.ajv = new Ajv2020Ctor({ allErrors: true, strict: false });
+    this.ajv.addFormat?.('date-time', {
+      type: 'string',
+      validate: isStrictRfc3339DateTime
+    });
+    this.validators = new Map();
+  }
+
+  schemaPath(name: SchemaId): string {
+    return path.join(this.repoRoot, 'agentic', 'orchestrator', 'schemas', name);
+  }
+
+  async loadSchema(name: SchemaId): Promise<ValidateFunction> {
+    const filePath = this.schemaPath(name);
+    const schemaText = await fs.readFile(filePath, 'utf8');
+    const schema = JSON.parse(schemaText) as AnySchema;
+    const validator = this.ajv.compile(schema);
+    this.validators.set(name, validator);
+    return validator;
+  }
+
+  async validate(name: SchemaId, payload: unknown): Promise<ValidationResult> {
+    const validator = this.validators.get(name) ?? (await this.loadSchema(name));
+    const valid = validator(payload);
+    return {
+      valid: Boolean(valid),
+      errors: valid ? [] : ((validator.errors ?? []))
+    };
+  }
+}
+
+export async function loadYamlFile<T = unknown>(filePath: string): Promise<T> {
+  const raw = await fs.readFile(filePath, 'utf8');
+  return YAML.parse(raw) as T;
+}
+
+export async function loadAndValidateYaml<T = unknown>(
+  schemaRegistry: SchemaValidator,
+  schemaName: SchemaId,
+  yamlPath: string
+): Promise<{ parsed: T; validation: ValidationResult }> {
+  const parsed = await loadYamlFile<T>(yamlPath);
+  const validation = await schemaRegistry.validate(schemaName, parsed);
+  return { parsed, validation };
+}

package/apps/control-plane/src/index.ts

@@ -0,0 +1,21 @@
+export { AopKernel } from './core/kernel.js';
+export type { AgentsConfigSnapshot } from './core/kernel.js';
+export { SupervisorRuntime } from './supervisor/runtime.js';
+export {
+  resolveProviderSelection,
+  NullWorkerProvider
+} from './providers/providers.js';
+export type { WorkerProvider, ProviderSelectionResolver } from './providers/providers.js';
+export { createToolingRuntime, resolveToolClient } from './mcp/runtime-factory.js';
+export type {
+  ToolingKernelPort,
+  CreateToolingRuntimeOptions
+} from './mcp/runtime-factory.js';
+export { InProcessToolClient, McpToolClient, createOperationId } from './mcp/tool-client.js';
+export { TokenAuthVerifier } from './mcp/token-auth-verifier.js';
+export { McpServerAdapter } from './mcp/mcp-server-adapter.js';
+export {
+  TOOL_BEHAVIOR_METADATA,
+  isMutatingTool,
+  toolRequiresOperationId
+} from './application/tools/tool-metadata.js';

package/apps/control-plane/src/interfaces/cli/bootstrap.ts

@@ -0,0 +1,100 @@
+import crypto from 'node:crypto';
+import { AopKernel } from '../../core/kernel.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import type { AppError } from '../../providers/providers.js';
+import { createToolingRuntime, resolveToolClient } from '../../mcp/runtime-factory.js';
+import { CliArgumentParser } from '../../cli/cli-argument-parser.js';
+import { printError, printPayload } from '../../cli/io.js';
+import { StatusCommandHandler } from '../../cli/status-command-handler.js';
+import { ResumeCommandHandler } from '../../cli/resume-command-handler.js';
+import { StopCommandHandler } from '../../cli/stop-command-handler.js';
+import { DeleteCommandHandler } from '../../cli/delete-command-handler.js';
+import { RunCommandHandler } from '../../cli/run-command-handler.js';
+import type { RuntimeContext } from '../../cli/types.js';
+
+const SUPPORTED_COMMANDS = new Set(['run', 'status', 'resume', 'stop', 'delete']);
+
+export async function runCli(
+  argv: string[] = process.argv.slice(2),
+  runtime: RuntimeContext = { cwd: process.cwd(), env: process.env }
+): Promise<number> {
+  const parser = new CliArgumentParser();
+  const options = parser.parse(argv);
+  const repoRoot = runtime.cwd;
+
+  try {
+    if (!SUPPORTED_COMMANDS.has(options.command)) {
+      printError(ERROR_CODES.INVALID_CLI_ARGS, `Unknown command: ${options.command}`, {
+        command: options.command
+      });
+      return 1;
+    }
+
+    const transport = parser.resolveTransport(options.transport);
+    const runId = `run:${crypto.randomUUID()}`;
+
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+
+    const tooling = await createToolingRuntime(repoRoot, kernel);
+    const toolClient = resolveToolClient(transport, tooling);
+
+    if (options.command === 'status') {
+      const handler = new StatusCommandHandler(toolClient, runId);
+      const payload = await handler.execute();
+      printPayload(payload);
+      return 0;
+    }
+
+    if (options.command === 'resume') {
+      const handler = new ResumeCommandHandler();
+      const payload = await handler.execute({
+        repoRoot,
+        env: runtime.env,
+        runId,
+        transport,
+        options,
+        kernel,
+        toolClient
+      });
+      printPayload(payload);
+      return 0;
+    }
+
+    if (options.command === 'stop') {
+      const handler = new StopCommandHandler();
+      const payload = await handler.execute();
+      printPayload(payload);
+      return 0;
+    }
+
+    if (options.command === 'delete') {
+      const handler = new DeleteCommandHandler(toolClient, runId);
+      const payload = await handler.execute(options);
+      printPayload(payload);
+      return 0;
+    }
+
+    const handler = new RunCommandHandler();
+    const payload = await handler.execute({
+      repoRoot,
+      env: runtime.env,
+      runId,
+      transport,
+      options,
+      kernel,
+      toolClient
+    });
+    printPayload(payload);
+    return 0;
+  } catch (error: unknown) {
+    const typed = error as AppError;
+    const code = typed.code || ERROR_CODES.INTERNAL_ERROR;
+    printError(code, typed.message || 'Unhandled CLI error', {
+      ...(typed.details ?? {}),
+      retryable: false,
+      requires_human: true
+    });
+    return 1;
+  }
+}

package/apps/control-plane/src/mcp/kernel-tool-executor.ts

@@ -0,0 +1,39 @@
+import { ok, type ToolResponse } from '../core/response.js';
+import type { ToolCatalogEntry, VerifiedActorClaims } from './runtime-types.js';
+
+export interface ToolExecutionRouterPort {
+  dispatchTool(
+    toolName: string,
+    args: Record<string, unknown>,
+    context: { actorType: string; actorId: string }
+  ): Promise<unknown>;
+  normalizeError(error: unknown): ToolResponse;
+}
+
+export class KernelToolExecutor {
+  readonly router: ToolExecutionRouterPort;
+
+  constructor(router: ToolExecutionRouterPort) {
+    this.router = router;
+  }
+
+  async execute(tool: ToolCatalogEntry, args: Record<string, unknown>, claims: VerifiedActorClaims): Promise<ToolResponse> {
+    try {
+      const result = (await this.router.dispatchTool(tool.name, args, {
+        actorType: claims.actor_type,
+        actorId: claims.actor_id
+      })) as Record<string, unknown>;
+      const payload =
+        result.data && typeof result.data === 'object'
+          ? (result.data as Record<string, unknown>)
+          : result;
+      const evidence =
+        result.evidence && typeof result.evidence === 'object'
+          ? (result.evidence as Record<string, unknown>)
+          : undefined;
+      return ok(payload, evidence);
+    } catch (error: unknown) {
+      return this.router.normalizeError(error);
+    }
+  }
+}

package/apps/control-plane/src/mcp/mcp-server-adapter.ts

@@ -0,0 +1,74 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import { fail } from '../core/response.js';
+import type { ToolResponse } from '../core/response.js';
+import type { ToolDescriptor } from './transport-types.js';
+import { type TokenAuthVerifier } from './token-auth-verifier.js';
+import { type ToolRuntime } from './tool-runtime.js';
+
+interface McpCallRequest {
+  name: string;
+  arguments?: Record<string, unknown>;
+  session_token?: string;
+}
+
+function extractActorClaimsFromArgs(args: Record<string, unknown>): { actor_type?: string; actor_id?: string } {
+  const actor_type = typeof args.actor_type === 'string' ? args.actor_type : undefined;
+  const actor_id = typeof args.actor_id === 'string' ? args.actor_id : undefined;
+  return { actor_type, actor_id };
+}
+
+export class McpServerAdapter {
+  readonly authVerifier: TokenAuthVerifier;
+  readonly runtime: ToolRuntime;
+
+  constructor(runtime: ToolRuntime, authVerifier: TokenAuthVerifier) {
+    this.runtime = runtime;
+    this.authVerifier = authVerifier;
+  }
+
+  async toolsList(): Promise<{ tools: ToolDescriptor[] }> {
+    const tools = await this.runtime.listTools();
+    return { tools };
+  }
+
+  async toolsCall(request: McpCallRequest): Promise<ToolResponse> {
+    const args = { ...(request.arguments ?? {}) };
+
+    try {
+      const claims = this.authVerifier.verifyToken(request.session_token ?? '');
+      const supplied = extractActorClaimsFromArgs(args);
+      if ((supplied.actor_type && supplied.actor_type !== claims.actor_type) || (supplied.actor_id && supplied.actor_id !== claims.actor_id)) {
+        return fail(ERROR_CODES.INVALID_ACTOR_CLAIM, 'actor claim does not match signed token', {
+          retryable: false,
+          requires_human: true,
+          supplied,
+          token_claims: {
+            actor_type: claims.actor_type,
+            actor_id: claims.actor_id
+          }
+        });
+      }
+
+      delete args.actor_type;
+      delete args.actor_id;
+
+      return this.runtime.callTool(request.name, args, claims);
+    } catch (error: unknown) {
+      if (
+        typeof error === 'object' &&
+        error !== null &&
+        'normalizedResponse' in error
+      ) {
+        return (error as { normalizedResponse: ToolResponse }).normalizedResponse;
+      }
+      const message =
+        typeof error === 'object' && error !== null && 'message' in error
+          ? (error as { message?: unknown }).message
+          : undefined;
+      return fail(ERROR_CODES.UNAUTHENTICATED, String(message ?? error), {
+        retryable: false,
+        requires_human: true
+      });
+    }
+  }
+}

package/apps/control-plane/src/mcp/operation-ledger.ts

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import { atomicWriteJson, ensureDir, readJson, withFileLock, nowIso } from '../core/fs.js';
+import { AopPathLayout } from '../core/path-layout.js';
+import type { ToolResponse } from '../core/response.js';
+
+interface LedgerEntry {
+  operation_id: string;
+  tool_name: string;
+  request_hash: string;
+  response: ToolResponse;
+  created_at: string;
+  updated_at: string;
+}
+
+interface LedgerFile {
+  run_id: string;
+  updated_at: string;
+  operations: Record<string, LedgerEntry>;
+}
+
+export class OperationLedger {
+  readonly repoRoot: string;
+  readonly pathLayout: AopPathLayout;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+    this.pathLayout = new AopPathLayout(repoRoot);
+  }
+
+  get ledgerRoot(): string {
+    return this.pathLayout.operationLedgerRoot;
+  }
+
+  ledgerPath(runId: string): string {
+    return path.join(this.ledgerRoot, `${runId}.json`);
+  }
+
+  lockPath(runId: string): string {
+    return path.join(this.ledgerRoot, `${runId}.lock`);
+  }
+
+  async ensureRunLedger(runId: string): Promise<void> {
+    await ensureDir(this.ledgerRoot);
+    const existing = await readJson<LedgerFile>(this.ledgerPath(runId), null);
+    if (!existing) {
+      await atomicWriteJson(this.ledgerPath(runId), {
+        run_id: runId,
+        updated_at: nowIso(),
+        operations: {}
+      } as LedgerFile);
+    }
+  }
+
+  async resolveOperation(
+    runId: string,
+    operationId: string,
+    requestHash: string
+  ): Promise<{ status: 'new' } | { status: 'replay'; response: ToolResponse } | { status: 'mismatch'; existing_hash: string }> {
+    await this.ensureRunLedger(runId);
+
+    return await withFileLock(this.lockPath(runId), async () => {
+      const ledger = await readJson<LedgerFile>(this.ledgerPath(runId), null);
+      const operations = ledger?.operations ?? {};
+      const existing = operations[operationId];
+      if (!existing) {
+        return { status: 'new' };
+      }
+
+      if (existing.request_hash !== requestHash) {
+        return {
+          status: 'mismatch',
+          existing_hash: existing.request_hash
+        };
+      }
+
+      return {
+        status: 'replay',
+        response: existing.response
+      };
+    });
+  }
+
+  async recordOperation(runId: string, operationId: string, toolName: string, requestHash: string, response: ToolResponse): Promise<void> {
+    await this.ensureRunLedger(runId);
+
+    await withFileLock(this.lockPath(runId), async () => {
+      const ledger = (await readJson<LedgerFile>(this.ledgerPath(runId), null)) ?? {
+        run_id: runId,
+        updated_at: nowIso(),
+        operations: {}
+      };
+
+      const now = nowIso();
+      const existing = ledger.operations[operationId];
+      ledger.operations[operationId] = {
+        operation_id: operationId,
+        tool_name: toolName,
+        request_hash: requestHash,
+        response,
+        created_at: existing?.created_at ?? now,
+        updated_at: now
+      };
+      ledger.updated_at = now;
+
+      await atomicWriteJson(this.ledgerPath(runId), ledger);
+    });
+  }
+}

package/apps/control-plane/src/mcp/protocol-contract.ts

@@ -0,0 +1,9 @@
+export const MCP_PROTOCOL_PIN = {
+  mcp_protocol_version: '2025-11-05',
+  sdk: {
+    package: '@modelcontextprotocol/sdk',
+    version: '1.18.0'
+  }
+} as const;
+
+export const REQUIRED_MCP_TRANSPORTS = ['stdio'] as const;

package/apps/control-plane/src/mcp/runtime-factory.ts

@@ -0,0 +1,105 @@
+import { OperationLedger } from './operation-ledger.js';
+import { KernelToolExecutor, type ToolExecutionRouterPort } from './kernel-tool-executor.js';
+import { McpServerAdapter } from './mcp-server-adapter.js';
+import { TokenAuthVerifier } from './token-auth-verifier.js';
+import { ToolAuthorizer } from './tool-authorizer.js';
+import { ToolContractValidator } from './tool-contract-validator.js';
+import { InProcessToolClient, McpToolClient, type ToolClient } from './tool-client.js';
+import { ToolRegistryLoader } from './tool-registry-loader.js';
+import { ToolRuntime } from './tool-runtime.js';
+import { ToolsMarkdownGenerator } from './tools-markdown-generator.js';
+
+export interface ToolingKernelPort extends ToolExecutionRouterPort {
+  getRbacPolicy(): Record<string, string[]>;
+}
+
+export interface CreateToolingRuntimeOptions {
+  generateToolsMarkdown?: boolean;
+}
+
+export interface ToolingRuntime {
+  loader: ToolRegistryLoader;
+  registry: Awaited<ReturnType<ToolRegistryLoader['load']>>;
+  validator: ToolContractValidator;
+  authorizer: ToolAuthorizer;
+  ledger: OperationLedger;
+  executor: KernelToolExecutor;
+  runtime: ToolRuntime;
+  authVerifier: TokenAuthVerifier;
+  mcpAdapter: McpServerAdapter;
+  inProcessClient: InProcessToolClient;
+  mcpClient: McpToolClient;
+}
+
+export class ToolingRuntimeComposer {
+  private readonly repoRoot: string;
+  private readonly kernel: ToolingKernelPort;
+  private readonly options: CreateToolingRuntimeOptions;
+
+  constructor(repoRoot: string, kernel: ToolingKernelPort, options: CreateToolingRuntimeOptions = {}) {
+    this.repoRoot = repoRoot;
+    this.kernel = kernel;
+    this.options = options;
+  }
+
+  async compose(): Promise<ToolingRuntime> {
+    const loader = new ToolRegistryLoader(this.repoRoot);
+    const registry = await loader.load();
+
+    await this.generateToolsMarkdownIfEnabled(registry.catalog);
+
+    const validator = await ToolContractValidator.create(loader, registry);
+    const authorizer = new ToolAuthorizer(this.kernel.getRbacPolicy(), registry);
+    const ledger = new OperationLedger(this.repoRoot);
+    const executor = new KernelToolExecutor(this.kernel);
+    const runtime = new ToolRuntime({
+      registry,
+      loader,
+      validator,
+      authorizer,
+      ledger,
+      executor
+    });
+    const authVerifier = new TokenAuthVerifier();
+    const mcpAdapter = new McpServerAdapter(runtime, authVerifier);
+
+    return {
+      loader,
+      registry,
+      validator,
+      authorizer,
+      ledger,
+      executor,
+      runtime,
+      authVerifier,
+      mcpAdapter,
+      inProcessClient: new InProcessToolClient(runtime),
+      mcpClient: new McpToolClient(mcpAdapter, authVerifier)
+    };
+  }
+
+  private async generateToolsMarkdownIfEnabled(catalog: Awaited<ReturnType<ToolRegistryLoader['load']>>['catalog']): Promise<void> {
+    const shouldGenerateDocs = this.options.generateToolsMarkdown ?? true;
+    if (!shouldGenerateDocs) {
+      return;
+    }
+    const markdownGenerator = new ToolsMarkdownGenerator(this.repoRoot);
+    await markdownGenerator.writeFromCatalog(catalog);
+  }
+}
+
+export async function createToolingRuntime(
+  repoRoot: string,
+  kernel: ToolingKernelPort,
+  options: CreateToolingRuntimeOptions = {}
+): Promise<ToolingRuntime> {
+  const composer = new ToolingRuntimeComposer(repoRoot, kernel, options);
+  return await composer.compose();
+}
+
+export function resolveToolClient(transport: 'inprocess' | 'mcp', tooling: ToolingRuntime): ToolClient {
+  if (transport === 'mcp') {
+    return tooling.mcpClient;
+  }
+  return tooling.inProcessClient;
+}

package/apps/control-plane/src/mcp/runtime-types.ts

@@ -0,0 +1,44 @@
+export interface ToolCatalogEntry {
+  name: string;
+  description: string;
+  input_schema_ref: string;
+  output_schema_ref: string;
+  supported_roles: string[];
+  handler_id: string;
+  mutating: boolean;
+  requires_operation_id: boolean;
+}
+
+export interface ToolCatalog {
+  version: number;
+  tools: ToolCatalogEntry[];
+}
+
+export interface ProtocolContract {
+  mcp_protocol_version: string;
+  sdk: {
+    package: string;
+    version: string;
+  };
+  enabled_transports: string[];
+}
+
+export interface LoadedToolRegistry {
+  toolsRoot: string;
+  catalogPath: string;
+  protocolPath: string;
+  catalog: ToolCatalog;
+  protocol: ProtocolContract;
+  toolsByName: Map<string, ToolCatalogEntry>;
+  toolsByHandlerId: Map<string, ToolCatalogEntry>;
+}
+
+export interface VerifiedActorClaims {
+  run_id: string;
+  session_id: string;
+  actor_type: string;
+  actor_id: string;
+  issued_at: string;
+  expires_at: string;
+  feature_scope?: string[];
+}

package/apps/control-plane/src/mcp/token-auth-verifier.ts

@@ -0,0 +1,63 @@
+import type { VerifiedActorClaims } from './runtime-types.js';
+import { SessionTokenCodec } from './token-codec.js';
+import { TokenClaimsValidator } from './token-claims-validator.js';
+
+interface TokenAuthOptions {
+  secret?: string;
+  ttl_seconds?: number;
+  now?: () => Date;
+}
+
+export class TokenAuthVerifier {
+  readonly secret: string;
+  readonly ttlSeconds: number;
+  readonly now: () => Date;
+  private readonly tokenCodec: SessionTokenCodec;
+  private readonly claimsValidator: TokenClaimsValidator;
+
+  constructor(options: TokenAuthOptions = {}) {
+    this.secret = options.secret ?? process.env.AOP_MCP_HMAC_SECRET ?? 'aop-dev-secret';
+    this.ttlSeconds = options.ttl_seconds ?? 900;
+    this.now = options.now ?? (() => new Date());
+    this.tokenCodec = new SessionTokenCodec(this.secret);
+    this.claimsValidator = new TokenClaimsValidator(this.now);
+  }
+
+  issueToken(input: {
+    run_id: string;
+    session_id: string;
+    actor_type: string;
+    actor_id: string;
+    feature_scope?: string[];
+    expires_at?: string;
+  }): string {
+    const issuedAt = this.now().toISOString();
+    const expiresAt = input.expires_at ?? new Date(this.now().getTime() + this.ttlSeconds * 1000).toISOString();
+
+    const claims: VerifiedActorClaims = {
+      run_id: input.run_id,
+      session_id: input.session_id,
+      actor_type: input.actor_type,
+      actor_id: input.actor_id,
+      feature_scope: input.feature_scope,
+      issued_at: issuedAt,
+      expires_at: expiresAt
+    };
+
+    this.claimsValidator.validate(claims, { checkExpiry: false });
+    return this.tokenCodec.issue(claims);
+  }
+
+  verifyToken(token: string): VerifiedActorClaims {
+    try {
+      const claims = this.tokenCodec.decodeAndVerify(token);
+      this.claimsValidator.validate(claims);
+      return claims;
+    } catch (error: unknown) {
+      if ((error as { normalizedResponse?: unknown })?.normalizedResponse) {
+        throw error;
+      }
+      this.claimsValidator.wrapCodecError(error);
+    }
+  }
+}