agentic-orchestrator 0.1.0

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

@@ -0,0 +1,336 @@
+import { fail, type FailResponse, type ToolResponse } from '../core/response.js';
+import { ERROR_CODES } from '../core/error-codes.js';
+import { stableHash } from '../core/fs.js';
+import type { LoadedToolRegistry, ToolCatalogEntry, VerifiedActorClaims } from './runtime-types.js';
+import type { ToolDescriptor } from './transport-types.js';
+import { type ToolRegistryLoader } from './tool-registry-loader.js';
+import { type ToolContractValidator } from './tool-contract-validator.js';
+import { type ToolAuthorizer } from './tool-authorizer.js';
+import { type OperationLedger } from './operation-ledger.js';
+import { type KernelToolExecutor } from './kernel-tool-executor.js';
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item));
+  }
+
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(record).sort((a, b) => a.localeCompare(b))) {
+      out[key] = canonicalize(record[key]);
+    }
+    return out;
+  }
+
+  return value;
+}
+
+function hashRequest(toolName: string, args: Record<string, unknown>): string {
+  const normalized = canonicalize({ tool_name: toolName, args });
+  return stableHash(JSON.stringify(normalized));
+}
+
+function normalizeOperationId(args: Record<string, unknown>): string | null {
+  const operationId = args.operation_id;
+  return typeof operationId === 'string' && operationId.length >= 8 ? operationId : null;
+}
+
+function featureScopeAllows(claims: VerifiedActorClaims, args: Record<string, unknown>): boolean {
+  if (!claims.feature_scope || claims.feature_scope.length === 0) {
+    return true;
+  }
+
+  const requestedFeature = args.feature_id;
+  if (typeof requestedFeature !== 'string') {
+    return true;
+  }
+
+  return claims.feature_scope.includes(requestedFeature);
+}
+
+function emitToolLog(params: {
+  claims: VerifiedActorClaims;
+  toolName: string;
+  args: Record<string, unknown>;
+  latencyMs: number;
+  response: ToolResponse;
+}): void {
+  const operationId = typeof params.args.operation_id === 'string' ? params.args.operation_id : null;
+  const featureId = typeof params.args.feature_id === 'string' ? params.args.feature_id : null;
+  const errorCode = isFailResponse(params.response) ? params.response.error.code : null;
+  const payload = {
+    run_id: params.claims.run_id,
+    operation_id: operationId,
+    feature_id: featureId,
+    tool_name: params.toolName,
+    actor_type: params.claims.actor_type,
+    latency_ms: params.latencyMs,
+    result: params.response.ok ? 'ok' : 'error',
+    error_code: errorCode
+  };
+
+  process.stderr.write(`${JSON.stringify(payload)}\n`);
+}
+
+function isFailResponse(response: ToolResponse): response is FailResponse {
+  return response.ok === false;
+}
+
+export class ToolRuntime {
+  readonly registry: LoadedToolRegistry;
+  readonly loader: ToolRegistryLoader;
+  readonly validator: ToolContractValidator;
+  readonly authorizer: ToolAuthorizer;
+  readonly ledger: OperationLedger;
+  readonly executor: KernelToolExecutor;
+
+  constructor(params: {
+    registry: LoadedToolRegistry;
+    loader: ToolRegistryLoader;
+    validator: ToolContractValidator;
+    authorizer: ToolAuthorizer;
+    ledger: OperationLedger;
+    executor: KernelToolExecutor;
+  }) {
+    this.registry = params.registry;
+    this.loader = params.loader;
+    this.validator = params.validator;
+    this.authorizer = params.authorizer;
+    this.ledger = params.ledger;
+    this.executor = params.executor;
+  }
+
+  async listTools(): Promise<ToolDescriptor[]> {
+    const descriptors: ToolDescriptor[] = [];
+    const sorted = [...this.registry.toolsByName.values()].sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const tool of sorted) {
+      descriptors.push({
+        name: tool.name,
+        description: tool.description,
+        input_schema: await this.loader.readSchemaByRef(tool.input_schema_ref),
+        output_schema: await this.loader.readSchemaByRef(tool.output_schema_ref),
+        mutating: tool.mutating,
+        requires_operation_id: tool.requires_operation_id
+      });
+    }
+
+    return descriptors;
+  }
+
+  async callTool(toolName: string, args: Record<string, unknown>, claims: VerifiedActorClaims): Promise<ToolResponse> {
+    const started = Date.now();
+    const safeArgs = { ...(args ?? {}) };
+    const tool = this.lookupTool(toolName);
+    if (!tool) {
+      return this.finalize(started, claims, toolName, safeArgs, this.unknownToolResponse(toolName));
+    }
+
+    const scopeAuthorizationResult = this.authorizeFeatureScope(claims, safeArgs);
+    if (scopeAuthorizationResult) {
+      return this.finalize(started, claims, toolName, safeArgs, scopeAuthorizationResult);
+    }
+
+    const roleAuthorizationResult = this.authorizeRole(claims, toolName);
+    if (roleAuthorizationResult) {
+      return this.finalize(started, claims, toolName, safeArgs, roleAuthorizationResult);
+    }
+
+    const inputValidationResult = await this.validateInput(tool, toolName, safeArgs);
+    if (inputValidationResult) {
+      return this.finalize(started, claims, toolName, safeArgs, inputValidationResult);
+    }
+
+    const idempotencyResolution = await this.resolveIdempotency(tool, toolName, safeArgs, claims);
+    if (idempotencyResolution.result) {
+      return this.finalize(started, claims, toolName, safeArgs, idempotencyResolution.result);
+    }
+
+    const executionResponse = await this.executor.execute(tool, safeArgs, claims);
+    const outputValidationResult = await this.validateExecutionResponse(tool, toolName, executionResponse);
+    if (outputValidationResult) {
+      return this.finalize(started, claims, toolName, safeArgs, outputValidationResult);
+    }
+
+    if (idempotencyResolution.operationId && idempotencyResolution.requestHash) {
+      await this.ledger.recordOperation(
+        claims.run_id,
+        idempotencyResolution.operationId,
+        toolName,
+        idempotencyResolution.requestHash,
+        executionResponse
+      );
+    }
+
+    return this.finalize(started, claims, toolName, safeArgs, executionResponse);
+  }
+
+  private lookupTool(toolName: string): ToolCatalogEntry | null {
+    return this.registry.toolsByName.get(toolName) ?? null;
+  }
+
+  private unknownToolResponse(toolName: string): ToolResponse {
+    return fail(ERROR_CODES.INVALID_ARGUMENT, `Unknown tool ${toolName}`, {
+      retryable: false,
+      requires_human: true
+    });
+  }
+
+  private authorizeFeatureScope(
+    claims: VerifiedActorClaims,
+    args: Record<string, unknown>
+  ): ToolResponse | null {
+    if (featureScopeAllows(claims, args)) {
+      return null;
+    }
+    return fail(ERROR_CODES.FORBIDDEN_TOOL_FOR_ROLE, 'feature_scope_violation', {
+      retryable: false,
+      requires_human: true,
+      feature_scope: claims.feature_scope,
+      feature_id: args.feature_id
+    });
+  }
+
+  private authorizeRole(claims: VerifiedActorClaims, toolName: string): ToolResponse | null {
+    if (this.authorizer.isAuthorized(claims.actor_type, toolName)) {
+      return null;
+    }
+    return fail(ERROR_CODES.FORBIDDEN_TOOL_FOR_ROLE, `Tool ${toolName} is not allowed for role ${claims.actor_type}`, {
+      retryable: false,
+      requires_human: true,
+      actor_type: claims.actor_type,
+      tool_name: toolName
+    });
+  }
+
+  private async validateInput(
+    tool: ToolCatalogEntry,
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<ToolResponse | null> {
+    const inputValidation = await this.validator.validateInput(tool, args);
+    if (inputValidation.valid) {
+      return null;
+    }
+    return fail(ERROR_CODES.INVALID_ARGUMENT, 'tool_input_schema_validation_failed', {
+      retryable: false,
+      requires_human: true,
+      errors: inputValidation.errors,
+      tool_name: toolName
+    });
+  }
+
+  private async validateExecutionResponse(
+    tool: ToolCatalogEntry,
+    toolName: string,
+    response: ToolResponse
+  ): Promise<ToolResponse | null> {
+    if (response.ok) {
+      const outputValidation = await this.validator.validateOutput(tool, response.data);
+      if (outputValidation.valid) {
+        return null;
+      }
+      return fail(ERROR_CODES.INTERNAL_ERROR, 'tool_output_schema_validation_failed', {
+        retryable: false,
+        requires_human: true,
+        errors: outputValidation.errors,
+        tool_name: toolName
+      });
+    }
+
+    const envelope = this.validator.validateErrorEnvelope(response);
+    if (envelope.valid) {
+      return null;
+    }
+    return fail(ERROR_CODES.INTERNAL_ERROR, 'tool_error_envelope_validation_failed', {
+      retryable: false,
+      requires_human: true,
+      errors: envelope.errors,
+      tool_name: toolName
+    });
+  }
+
+  private finalize(
+    started: number,
+    claims: VerifiedActorClaims,
+    toolName: string,
+    args: Record<string, unknown>,
+    response: ToolResponse
+  ): ToolResponse {
+    emitToolLog({
+      claims,
+      toolName,
+      args,
+      latencyMs: Date.now() - started,
+      response
+    });
+    return response;
+  }
+
+  private async resolveIdempotency(
+    tool: ToolCatalogEntry,
+    toolName: string,
+    args: Record<string, unknown>,
+    claims: VerifiedActorClaims
+  ): Promise<{ operationId: string | null; requestHash: string | null; result: ToolResponse | null }> {
+    if (!tool.mutating) {
+      return { operationId: null, requestHash: null, result: null };
+    }
+
+    const operationId = normalizeOperationId(args);
+    if (tool.requires_operation_id && !operationId) {
+      return {
+        operationId: null,
+        requestHash: null,
+        result: fail(ERROR_CODES.OPERATION_ID_REQUIRED, 'operation_id is required for mutating tools', {
+          retryable: false,
+          requires_human: true,
+          tool_name: toolName
+        })
+      };
+    }
+    if (!operationId) {
+      return {
+        operationId: null,
+        requestHash: null,
+        result: fail(ERROR_CODES.OPERATION_ID_REQUIRED, 'operation_id is required for mutating tools', {
+          retryable: false,
+          requires_human: true,
+          tool_name: toolName
+        })
+      };
+    }
+
+    const requestHash = hashRequest(toolName, args);
+    const dedupe = await this.ledger.resolveOperation(claims.run_id, operationId, requestHash);
+    if (dedupe.status === 'replay') {
+      return {
+        operationId,
+        requestHash,
+        result: dedupe.response
+      };
+    }
+
+    if (dedupe.status === 'mismatch') {
+      return {
+        operationId,
+        requestHash,
+        result: fail(ERROR_CODES.OPERATION_ID_REUSE_MISMATCH, 'operation_id_reuse_mismatch', {
+          retryable: false,
+          requires_human: true,
+          operation_id: operationId,
+          request_hash: requestHash,
+          existing_hash: dedupe.existing_hash,
+          tool_name: toolName
+        })
+      };
+    }
+
+    return {
+      operationId,
+      requestHash,
+      result: null
+    };
+  }
+}

package/apps/control-plane/src/mcp/tools-markdown-generator.ts

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { atomicWriteFile } from '../core/fs.js';
+import type { ToolCatalog } from './runtime-types.js';
+
+export class ToolsMarkdownGenerator {
+  readonly repoRoot: string;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+  }
+
+  renderFromCatalog(catalog: ToolCatalog): string {
+    const names = [...catalog.tools].map((tool) => tool.name).sort((a, b) => a.localeCompare(b));
+    const lines = ['# AOP MCP Tool Surface', '', 'Generated from `agentic/orchestrator/tools/catalog.json`.', ''];
+    for (const name of names) {
+      lines.push(`- ${name}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  async writeFromCatalog(catalog: ToolCatalog): Promise<void> {
+    const outPath = path.join(this.repoRoot, 'agentic', 'orchestrator', 'tools.md');
+    await atomicWriteFile(outPath, this.renderFromCatalog(catalog));
+  }
+}

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

@@ -0,0 +1,16 @@
+import type { VerifiedActorClaims } from './runtime-types.js';
+
+export interface ToolDescriptor {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+  output_schema: Record<string, unknown>;
+  mutating: boolean;
+  requires_operation_id: boolean;
+}
+
+export interface ToolCallRequest {
+  tool_name: string;
+  args: Record<string, unknown>;
+  claims: VerifiedActorClaims;
+}

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

@@ -0,0 +1,2 @@
+export * from './runtime-types.js';
+export * from './transport-types.js';

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

@@ -0,0 +1,177 @@
+import crypto from 'node:crypto';
+import { ERROR_CODES } from '../core/error-codes.js';
+
+export interface AppError extends Error {
+  code?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface ProviderSelection {
+  provider: 'codex' | 'claude' | 'gemini' | 'custom';
+  model: string;
+  provider_config_env: string | null;
+  provider_config_ref: string | null;
+}
+
+interface ResolveSelectionInput {
+  cli: Record<string, string | undefined>;
+  env: NodeJS.ProcessEnv;
+  agentsConfig?: {
+    runtime?: {
+      default_provider?: string;
+      default_model?: string;
+      provider_config_env?: string;
+    };
+  };
+}
+
+export const SUPPORTED_PROVIDERS = new Set<ProviderSelection['provider']>(['codex', 'claude', 'gemini', 'custom']);
+export type ProviderSelectionResolver = (input: ResolveSelectionInput) => ProviderSelection;
+
+export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env, agentsConfig }) => {
+  const provider =
+    cli.agent_provider ||
+    env.AOP_AGENT_PROVIDER ||
+    agentsConfig?.runtime?.default_provider ||
+    null;
+
+  const model =
+    cli.agent_model ||
+    env.AOP_AGENT_MODEL ||
+    agentsConfig?.runtime?.default_model ||
+    null;
+
+  const providerConfigEnv =
+    cli.provider_config_env ||
+    env.AOP_PROVIDER_CONFIG_ENV ||
+    agentsConfig?.runtime?.provider_config_env ||
+    null;
+
+  if (!provider) {
+    const error = new Error(ERROR_CODES.AGENT_PROVIDER_NOT_CONFIGURED) as AppError;
+    error.code = ERROR_CODES.AGENT_PROVIDER_NOT_CONFIGURED;
+    throw error;
+  }
+
+  if (!SUPPORTED_PROVIDERS.has(provider as ProviderSelection['provider'])) {
+    const error = new Error(ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER) as AppError;
+    error.code = ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER;
+    error.details = { provider };
+    throw error;
+  }
+
+  if (provider !== 'custom' && (!providerConfigEnv || !env[providerConfigEnv])) {
+    const error = new Error(ERROR_CODES.PROVIDER_AUTH_MISSING) as AppError;
+    error.code = ERROR_CODES.PROVIDER_AUTH_MISSING;
+    error.details = {
+      provider,
+      provider_config_env: providerConfigEnv
+    };
+    throw error;
+  }
+
+  return {
+    provider: provider as ProviderSelection['provider'],
+    model: model ?? `${provider}-default`,
+    provider_config_env: providerConfigEnv,
+    provider_config_ref: providerConfigEnv ? env[providerConfigEnv] ?? null : null
+  };
+};
+
+export interface WorkerSession {
+  session_id: string;
+  role: string;
+  feature_id: string;
+  system_prompt_loaded: boolean;
+}
+
+export interface WorkerProvider {
+  selection: ProviderSelection;
+  createSession(role: string, featureId: string, systemPrompt: string | null): Promise<WorkerSession>;
+  reattachSession(sessionId: string): Promise<WorkerSession | null>;
+  closeSession(sessionId: string): Promise<{ closed: true }>;
+  runWorker(input: {
+    role: string;
+    feature_id: string;
+    context_bundle?: Record<string, unknown>;
+    instructions?: string;
+    last_tool_results?: Array<Record<string, unknown>>;
+    runtime_selection?: {
+      provider: string;
+      model: string;
+      provider_config_ref: string | null;
+    };
+  }): Promise<Record<string, unknown>>;
+}
+
+export class NullWorkerProvider implements WorkerProvider {
+  selection: ProviderSelection;
+
+  constructor(selection: ProviderSelection) {
+    this.selection = selection;
+  }
+
+  createSession(role: string, featureId: string, systemPrompt: string | null): Promise<WorkerSession> {
+    return Promise.resolve({
+      session_id: `${role}-${featureId}-${crypto.randomUUID()}`,
+      role,
+      feature_id: featureId,
+      system_prompt_loaded: Boolean(systemPrompt)
+    });
+  }
+  reattachSession(sessionId: string): Promise<WorkerSession | null> {
+    if (!sessionId || sessionId === 'unknown') {
+      return Promise.resolve(null);
+    }
+    return Promise.resolve({
+      session_id: sessionId,
+      role: 'orchestrator',
+      feature_id: 'global',
+      system_prompt_loaded: false
+    });
+  }
+  closeSession(_sessionId: string): Promise<{ closed: true }> {
+    return Promise.resolve({ closed: true });
+  }
+
+  runWorker({
+    role,
+    feature_id,
+    context_bundle
+  }: {
+    role: string;
+    feature_id: string;
+    context_bundle?: Record<string, unknown>;
+    instructions?: string;
+    last_tool_results?: Array<Record<string, unknown>>;
+    runtime_selection?: {
+      provider: string;
+      model: string;
+      provider_config_ref: string | null;
+    };
+  }): Promise<Record<string, unknown>> {
+    if (role === 'planner') {
+      const state = context_bundle?.state;
+      const frontMatter =
+        state && typeof state === 'object'
+          ? (state as Record<string, unknown>).front_matter
+          : null;
+      const status =
+        frontMatter && typeof frontMatter === 'object'
+          ? (frontMatter as Record<string, unknown>).status
+          : null;
+      return Promise.resolve({
+        type: 'NOTE',
+        content: `Planner session active for ${feature_id}.`,
+        context_snapshot: {
+          status: typeof status === 'string' ? status : 'unknown'
+        }
+      });
+    }
+
+    return Promise.resolve({
+      type: 'NOTE',
+      content: `${role} session active for ${feature_id}.`
+    });
+  }
+}

package/apps/control-plane/src/supervisor/build-wave-executor.ts

@@ -0,0 +1,55 @@
+import { STATUS, TOOLS } from '../core/constants.js';
+import type { FeatureStatePayload, SupervisorToolCaller } from './types.js';
+import { NOOP_WORKER_DECISION_RUNNER, type WorkerDecisionRunner } from './worker-decision-loop.js';
+
+interface BuildWaveExecutorDependencies {
+  toolCaller: SupervisorToolCaller;
+  workerDecisionRunner?: WorkerDecisionRunner;
+}
+
+export class BuildWaveExecutor {
+  private readonly toolCaller: SupervisorToolCaller;
+  private readonly workerDecisionRunner: WorkerDecisionRunner;
+
+  constructor(dependencies: BuildWaveExecutorDependencies) {
+    this.toolCaller = dependencies.toolCaller;
+    this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
+  }
+
+  async run(featureIds: string[], maxParallelGateRuns: number): Promise<void> {
+    const batch: string[] = [];
+    for (const featureId of featureIds) {
+      const state = await this.toolCaller.callTool<FeatureStatePayload>('builder', TOOLS.FEATURE_STATE_GET, {
+        feature_id: featureId
+      });
+
+      if (state.data.front_matter.status === STATUS.BUILDING) {
+        batch.push(featureId);
+      }
+    }
+
+    const selected = batch.slice(0, maxParallelGateRuns);
+    for (const featureId of selected) {
+      const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
+        feature_id: featureId
+      });
+      await this.workerDecisionRunner.execute({
+        role: 'builder',
+        featureId,
+        contextBundle: context.data,
+        instructions:
+          'Emit PATCH outputs for code changes, NOTE outputs for progress context, and REQUEST outputs for lock/context needs.'
+      });
+    }
+
+    const executing = selected.map((featureId) =>
+      this.toolCaller.callTool('builder', TOOLS.GATES_RUN, {
+        feature_id: featureId,
+        profile: null,
+        mode: 'fast'
+      })
+    );
+
+    await Promise.allSettled(executing);
+  }
+}

package/apps/control-plane/src/supervisor/lease-heartbeat-service.ts

@@ -0,0 +1,22 @@
+import type { FeatureOrchestrationPort, SupervisorRuntimeState } from './types.js';
+
+interface LeaseHeartbeatServiceDependencies {
+  kernel: FeatureOrchestrationPort;
+  state: SupervisorRuntimeState;
+}
+
+export class LeaseHeartbeatService {
+  private readonly kernel: FeatureOrchestrationPort;
+  private readonly state: SupervisorRuntimeState;
+
+  constructor(dependencies: LeaseHeartbeatServiceDependencies) {
+    this.kernel = dependencies.kernel;
+    this.state = dependencies.state;
+  }
+
+  async renew(): Promise<void> {
+    const featureIds = [...this.state.sessionsByFeature.keys()];
+    await this.kernel.renewLeases(featureIds);
+    await this.kernel.renewRunLease(this.state.runId, this.state.ownerInstanceId);
+  }
+}