agentic-orchestrator 0.1.0

package/apps/control-plane/src/application/services/run-lease-service.ts

@@ -0,0 +1,340 @@
+import crypto from 'node:crypto';
+import { nowIso, stableHash } from '../../core/fs.js';
+import { fail } from '../../core/response.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import type { RuntimeSessionsSnapshot } from '../../core/runtime-sessions.js';
+
+export interface AcquireRunLeaseInput {
+  run_id: string;
+  owner_instance_id: string;
+  provider: string;
+  model: string;
+  provider_config_ref_hash: string;
+  takeover_stale_run?: boolean;
+}
+
+interface RuntimeFeatureSessionUpdateParams {
+  run_id: string;
+  owner_instance_id: string;
+  feature_id: string;
+  planner_session_id: string;
+  builder_session_id: string;
+  qa_session_id: string;
+}
+
+interface PruneFeatureSessionParams {
+  run_id: string;
+  owner_instance_id: string;
+  active_feature_ids: string[];
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type IndexSnapshot = Record<string, any>;
+
+export interface RunLeaseServicePort {
+  runLeaseTtlSeconds(): number;
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  readIndex(): Promise<IndexSnapshot>;
+  writeIndex(index: IndexSnapshot): Promise<void>;
+  normalizeRuntimeSessions(value: unknown, at?: string): RuntimeSessionsSnapshot;
+  isRunLeaseFresh(runtimeSessions: RuntimeSessionsSnapshot): boolean;
+  emptyRuntimeSessions(at?: string): RuntimeSessionsSnapshot;
+}
+
+export class RunLeaseService {
+  private readonly port: RunLeaseServicePort;
+
+  constructor(port: RunLeaseServicePort) {
+    this.port = port;
+  }
+
+  async acquireRunLease(input: AcquireRunLeaseInput): Promise<{
+    data: {
+      runtime_sessions: RuntimeSessionsSnapshot;
+      took_over_stale: boolean;
+      reused_existing_owner: boolean;
+    };
+  }> {
+    if (!input.run_id || !input.owner_instance_id) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'run_id and owner_instance_id are required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const ttlMs = this.port.runLeaseTtlSeconds() * 1000;
+    const normalizedProviderHash =
+      input.provider_config_ref_hash && input.provider_config_ref_hash.length > 0
+        ? input.provider_config_ref_hash
+        : stableHash('none');
+
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const current = this.port.normalizeRuntimeSessions(index.runtime_sessions);
+      const hasLease = current.run_id !== 'none' && current.owner_instance_id !== 'none';
+      const fresh = hasLease && this.port.isRunLeaseFresh(current);
+      const sameOwner = current.run_id === input.run_id && current.owner_instance_id === input.owner_instance_id;
+
+      if (fresh && !sameOwner) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.RUN_ALREADY_ACTIVE, 'Another active run already owns this repository', {
+            active_run_id: current.run_id,
+            owner_instance_id: current.owner_instance_id,
+            lease_expires_at: current.lease_expires_at,
+            stale: false,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      const staleOwnedByOther = hasLease && !fresh && !sameOwner;
+      if (staleOwnedByOther && !input.takeover_stale_run) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.RUN_ALREADY_ACTIVE, 'A stale run lease exists; explicit takeover is required', {
+            active_run_id: current.run_id,
+            owner_instance_id: current.owner_instance_id,
+            lease_expires_at: current.lease_expires_at,
+            stale: true,
+            requires_takeover: true,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      const now = nowIso();
+      const isInitialRun = !hasLease || current.run_id === 'none';
+      const claimed: RuntimeSessionsSnapshot = {
+        ...current,
+        run_id: input.run_id,
+        owner_instance_id: input.owner_instance_id,
+        lease_id: crypto.randomUUID(),
+        provider: input.provider,
+        model: input.model,
+        provider_config_ref_hash: normalizedProviderHash,
+        started_at: sameOwner && current.started_at ? current.started_at : now,
+        last_heartbeat_at: now,
+        lease_expires_at: new Date(Date.now() + ttlMs).toISOString(),
+        orchestrator_epoch: isInitialRun ? 0 : Number(current.orchestrator_epoch ?? 0)
+      };
+
+      if (!sameOwner) {
+        claimed.orchestrator_session_id = 'unknown';
+        claimed.feature_sessions = {};
+      }
+
+      index.runtime_sessions = claimed;
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+
+      return {
+        data: {
+          runtime_sessions: claimed,
+          took_over_stale: staleOwnedByOther,
+          reused_existing_owner: sameOwner
+        }
+      };
+    });
+  }
+
+  async renewRunLease(runId: string, ownerInstanceId: string): Promise<{ data: { lease_expires_at: string } }> {
+    if (!runId || !ownerInstanceId) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'runId and ownerInstanceId are required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const ttlMs = this.port.runLeaseTtlSeconds() * 1000;
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const current = this.port.normalizeRuntimeSessions(index.runtime_sessions);
+      if (current.run_id !== runId || current.owner_instance_id !== ownerInstanceId) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.RUN_LEASE_NOT_OWNED, 'Cannot renew a run lease not owned by this instance', {
+            run_id: runId,
+            owner_instance_id: ownerInstanceId,
+            active_run_id: current.run_id,
+            active_owner_instance_id: current.owner_instance_id,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      const updated: RuntimeSessionsSnapshot = {
+        ...current,
+        last_heartbeat_at: nowIso(),
+        lease_expires_at: new Date(Date.now() + ttlMs).toISOString()
+      };
+      index.runtime_sessions = updated;
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+
+      return {
+        data: {
+          lease_expires_at: updated.lease_expires_at
+        }
+      };
+    });
+  }
+
+  async releaseRunLease(runId: string, ownerInstanceId: string): Promise<{ data: { released: boolean } }> {
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const current = this.port.normalizeRuntimeSessions(index.runtime_sessions);
+      if (current.run_id !== runId || current.owner_instance_id !== ownerInstanceId) {
+        return { data: { released: false } };
+      }
+
+      index.runtime_sessions = this.port.emptyRuntimeSessions(nowIso());
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+      return { data: { released: true } };
+    });
+  }
+
+  async updateOrchestratorSession(params: {
+    run_id: string;
+    owner_instance_id: string;
+    orchestrator_session_id: string;
+    increment_epoch?: boolean;
+  }): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot } }> {
+    const { run_id, owner_instance_id, orchestrator_session_id, increment_epoch = false } = params;
+    if (!run_id || !owner_instance_id || !orchestrator_session_id) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'run_id, owner_instance_id, and orchestrator_session_id are required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const current = this.port.normalizeRuntimeSessions(index.runtime_sessions);
+      if (current.run_id !== run_id || current.owner_instance_id !== owner_instance_id) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.RUN_LEASE_NOT_OWNED, 'Cannot update orchestrator session without run ownership', {
+            run_id,
+            owner_instance_id,
+            active_run_id: current.run_id,
+            active_owner_instance_id: current.owner_instance_id,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      const nextEpoch = increment_epoch
+        ? Number(current.orchestrator_epoch ?? 0) + 1
+        : Number(current.orchestrator_epoch ?? 0);
+      const updated: RuntimeSessionsSnapshot = {
+        ...current,
+        orchestrator_session_id,
+        orchestrator_epoch: nextEpoch
+      };
+      index.runtime_sessions = updated;
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+
+      return {
+        data: {
+          runtime_sessions: updated
+        }
+      };
+    });
+  }
+
+  async updateFeatureSessionAssignment(params: RuntimeFeatureSessionUpdateParams): Promise<{ data: { updated: boolean } }> {
+    const { run_id, owner_instance_id, feature_id, planner_session_id, builder_session_id, qa_session_id } = params;
+
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const current = this.port.normalizeRuntimeSessions(index.runtime_sessions);
+      if (current.run_id !== run_id || current.owner_instance_id !== owner_instance_id) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.RUN_LEASE_NOT_OWNED, 'Cannot update feature sessions without run ownership', {
+            run_id,
+            owner_instance_id,
+            active_run_id: current.run_id,
+            active_owner_instance_id: current.owner_instance_id,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      const nextFeatureSessions = {
+        ...(current.feature_sessions ?? {}),
+        [feature_id]: {
+          planner_session_id,
+          builder_session_id,
+          qa_session_id
+        }
+      };
+
+      index.runtime_sessions = {
+        ...current,
+        feature_sessions: nextFeatureSessions
+      };
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+      return { data: { updated: true } };
+    });
+  }
+
+  async pruneFeatureSessionAssignments(params: PruneFeatureSessionParams): Promise<{ data: { removed: string[] } }> {
+    const active = new Set(params.active_feature_ids);
+    return await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const current = this.port.normalizeRuntimeSessions(index.runtime_sessions);
+      if (current.run_id !== params.run_id || current.owner_instance_id !== params.owner_instance_id) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.RUN_LEASE_NOT_OWNED, 'Cannot prune feature sessions without run ownership', {
+            run_id: params.run_id,
+            owner_instance_id: params.owner_instance_id,
+            active_run_id: current.run_id,
+            active_owner_instance_id: current.owner_instance_id,
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+
+      const existing = current.feature_sessions ?? {};
+      const kept: RuntimeSessionsSnapshot['feature_sessions'] = {};
+      const removed: string[] = [];
+      for (const [featureId, assignment] of Object.entries(existing)) {
+        if (active.has(featureId)) {
+          kept[featureId] = assignment;
+        } else {
+          removed.push(featureId);
+        }
+      }
+
+      if (removed.length > 0) {
+        index.runtime_sessions = {
+          ...current,
+          feature_sessions: kept
+        };
+        index.version += 1;
+        index.updated_at = nowIso();
+        await this.port.writeIndex(index);
+      }
+
+      removed.sort((a, b) => a.localeCompare(b));
+      return { data: { removed } };
+    });
+  }
+}

package/apps/control-plane/src/application/tools/tool-metadata.ts

@@ -0,0 +1,56 @@
+import { TOOLS } from '../../core/constants.js';
+
+export interface ToolBehaviorMetadata {
+  mutating: boolean;
+  requires_operation_id: boolean;
+}
+
+const MUTATING_TOOLS = [
+  TOOLS.FEATURE_INIT,
+  TOOLS.FEATURE_STATE_PATCH,
+  TOOLS.FEATURE_LOG_APPEND,
+  TOOLS.PLAN_SUBMIT,
+  TOOLS.PLAN_UPDATE,
+  TOOLS.REPO_ENSURE_WORKTREE,
+  TOOLS.REPO_APPLY_PATCH,
+  TOOLS.GATES_RUN,
+  TOOLS.QA_TEST_INDEX_UPDATE,
+  TOOLS.LOCKS_ACQUIRE,
+  TOOLS.LOCKS_RELEASE,
+  TOOLS.FEATURE_READY_TO_MERGE,
+  TOOLS.FEATURE_DELETE
+] as const;
+
+export const TOOL_BEHAVIOR_METADATA: Readonly<Record<string, ToolBehaviorMetadata>> = Object.freeze(
+  Object.fromEntries(
+    MUTATING_TOOLS.map((name) => [name, { mutating: true, requires_operation_id: true }])
+  )
+);
+
+export function isMutatingTool(toolName: string): boolean {
+  return TOOL_BEHAVIOR_METADATA[toolName]?.mutating ?? false;
+}
+
+export function toolRequiresOperationId(toolName: string): boolean {
+  return TOOL_BEHAVIOR_METADATA[toolName]?.requires_operation_id ?? false;
+}
+
+export function withOperationIdIfRequired(
+  toolName: string,
+  args: Record<string, unknown>,
+  createOperationId: (toolName: string, featureId?: string) => string
+): Record<string, unknown> {
+  if (!toolRequiresOperationId(toolName)) {
+    return { ...args };
+  }
+
+  if (typeof args.operation_id === 'string') {
+    return { ...args };
+  }
+
+  const featureId = typeof args.feature_id === 'string' ? args.feature_id : undefined;
+  return {
+    ...args,
+    operation_id: createOperationId(toolName, featureId)
+  };
+}

package/apps/control-plane/src/application/tools/tool-router.ts

@@ -0,0 +1,43 @@
+export interface ToolHandlerContext {
+  actorType: string;
+  actorId: string;
+}
+
+export type ToolHandler = (
+  args: Record<string, unknown>,
+  context: ToolHandlerContext
+) => Promise<unknown>;
+
+export class ToolHandlerRegistry {
+  private readonly handlers = new Map<string, ToolHandler>();
+
+  register(toolName: string, handler: ToolHandler): void {
+    this.handlers.set(toolName, handler);
+  }
+
+  lookup(toolName: string): ToolHandler | undefined {
+    return this.handlers.get(toolName);
+  }
+}
+
+export class ToolRouter {
+  private readonly registry: ToolHandlerRegistry;
+  private readonly unknownToolHandler: (toolName: string) => Promise<unknown>;
+
+  constructor(registry: ToolHandlerRegistry, unknownToolHandler: (toolName: string) => Promise<unknown>) {
+    this.registry = registry;
+    this.unknownToolHandler = unknownToolHandler;
+  }
+
+  async route(
+    toolName: string,
+    args: Record<string, unknown>,
+    context: ToolHandlerContext
+  ): Promise<unknown> {
+    const handler = this.registry.lookup(toolName);
+    if (!handler) {
+      return await this.unknownToolHandler(toolName);
+    }
+    return await handler(args, context);
+  }
+}

package/apps/control-plane/src/cli/aop.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env -S tsx
+import { runCli } from '../interfaces/cli/bootstrap.js';
+import type { RuntimeContext } from './types.js';
+
+export async function main(
+  argv: string[] = process.argv.slice(2),
+  runtime: RuntimeContext = { cwd: process.cwd(), env: process.env }
+): Promise<number> {
+  return await runCli(argv, runtime);
+}
+
+export function isDirectExecution(importMetaUrl: string, argv1: string | undefined): boolean {
+  return importMetaUrl === `file://${argv1 ?? ''}`;
+}
+
+export function runAsEntrypoint(
+  importMetaUrl: string,
+  argv1: string | undefined,
+  executeMain: () => Promise<number> = () => main()
+): boolean {
+  if (!isDirectExecution(importMetaUrl, argv1)) {
+    return false;
+  }
+
+  void executeMain().then((exitCode) => {
+    process.exitCode = exitCode;
+  });
+  return true;
+}
+
+runAsEntrypoint(import.meta.url, process.argv[1]);

package/apps/control-plane/src/cli/cli-argument-parser.ts

@@ -0,0 +1,116 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { AppError } from '../providers/providers.js';
+import type { CliOptions, ToolTransport } from './types.js';
+
+function parseOptionalBooleanToken(token: string | undefined): boolean | null {
+  if (token === 'true') {
+    return true;
+  }
+  if (token === 'false') {
+    return false;
+  }
+  return null;
+}
+
+export class CliArgumentParser {
+  parse(argv: string[]): CliOptions {
+    const [first, ...rest] = argv;
+    const command = first !== undefined && !first.startsWith('-') ? first : 'run';
+    const tokens = first !== undefined && !first.startsWith('-') ? rest : argv;
+    const options: CliOptions = {
+      command: command ?? 'run'
+    };
+
+    for (let index = 0; index < tokens.length; index += 1) {
+      const token = tokens[index];
+      const next = tokens[index + 1];
+
+      if (token === '-fi') {
+        options.file_input = next;
+        index += 1;
+        continue;
+      }
+      if (token === '-fl') {
+        options.folder_input = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--agent-provider') {
+        options.agent_provider = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--feature-id') {
+        options.feature_id = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--dry-run') {
+        const parsed = parseOptionalBooleanToken(next);
+        if (parsed === null) {
+          options.dry_run = true;
+        } else {
+          options.dry_run = parsed;
+          index += 1;
+        }
+        continue;
+      }
+      if (token === '--yes') {
+        options.yes = true;
+        continue;
+      }
+      if (token === '--remove-worktree') {
+        const parsed = parseOptionalBooleanToken(next);
+        if (parsed === null) {
+          options.remove_worktree = true;
+        } else {
+          options.remove_worktree = parsed;
+          index += 1;
+        }
+        continue;
+      }
+      if (token === '--remove-branch') {
+        options.remove_branch = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--agent-model') {
+        options.agent_model = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--provider-config-env') {
+        options.provider_config_env = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--transport') {
+        options.transport = next;
+        index += 1;
+        continue;
+      }
+      if (token === '--takeover-stale-run') {
+        options.takeover_stale_run = true;
+
+      }
+    }
+
+    return options;
+  }
+
+  resolveTransport(option: string | undefined): ToolTransport {
+    const raw = (option ?? 'mcp').toLowerCase();
+    if (raw === 'inprocess' || raw === 'mcp') {
+      return raw;
+    }
+
+    const error = new Error(ERROR_CODES.INVALID_CLI_ARGS) as AppError;
+    error.code = ERROR_CODES.INVALID_CLI_ARGS;
+    error.details = {
+      reason: 'Invalid --transport value',
+      provided: option,
+      expected: ['inprocess', 'mcp']
+    };
+    throw error;
+  }
+}

package/apps/control-plane/src/cli/delete-command-handler.ts

@@ -0,0 +1,90 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import { TOOLS } from '../core/constants.js';
+import type { AppError } from '../providers/providers.js';
+import type { ToolClient } from '../mcp/tool-client.js';
+import type { CliOptions, RemoveBranchMode } from './types.js';
+import { callCliTool } from './tooling.js';
+
+function isValidFeatureId(value: string): boolean {
+  return /^[a-z0-9_][a-z0-9_-]*$/.test(value);
+}
+
+function asRemoveBranchMode(value: string | undefined): RemoveBranchMode | null {
+  if (value === undefined) {
+    return 'none';
+  }
+  if (value === 'none' || value === 'safe' || value === 'force') {
+    return value;
+  }
+  return null;
+}
+
+function invalidCliArgs(details: Record<string, unknown>): never {
+  const error = new Error(ERROR_CODES.INVALID_CLI_ARGS) as AppError;
+  error.code = ERROR_CODES.INVALID_CLI_ARGS;
+  error.details = details;
+  throw error;
+}
+
+export class DeleteCommandHandler {
+  private readonly toolClient: ToolClient;
+  private readonly runId: string;
+
+  constructor(toolClient: ToolClient, runId: string) {
+    this.toolClient = toolClient;
+    this.runId = runId;
+  }
+
+  async execute(options: CliOptions): Promise<unknown> {
+    const featureId = options.feature_id;
+    if (!featureId) {
+      invalidCliArgs({
+        reason: '--feature-id is required for delete',
+        expected: '--feature-id <feature_id>'
+      });
+    }
+    if (!isValidFeatureId(featureId)) {
+      invalidCliArgs({
+        reason: 'Invalid --feature-id value',
+        provided: featureId,
+        expected_pattern: '^[a-z0-9_][a-z0-9_-]*$'
+      });
+    }
+
+    const removeBranch = asRemoveBranchMode(options.remove_branch);
+    if (removeBranch === null) {
+      invalidCliArgs({
+        reason: 'Invalid --remove-branch value',
+        provided: options.remove_branch,
+        expected: ['none', 'safe', 'force']
+      });
+    }
+
+    if (options.yes !== true && options.dry_run === false) {
+      invalidCliArgs({
+        reason: 'Destructive delete requires --yes',
+        expected: 'Provide --yes or omit --dry-run=false'
+      });
+    }
+
+    const dryRun = options.yes === true ? (options.dry_run ?? false) : true;
+    const confirm = options.yes === true;
+    const removeWorktree = options.remove_worktree ?? true;
+
+    const response = await callCliTool(this.toolClient, this.runId, TOOLS.FEATURE_DELETE, {
+      feature_id: featureId,
+      dry_run: dryRun,
+      confirm,
+      remove_worktree: removeWorktree,
+      remove_branch: removeBranch
+    });
+
+    return {
+      ok: true,
+      data: {
+        command: 'delete',
+        ...(response.data ?? {})
+      }
+    };
+  }
+}

package/apps/control-plane/src/cli/io.ts

@@ -0,0 +1,14 @@
+export function printPayload(payload: unknown): void {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+export function printError(code: string, message: string, details: Record<string, unknown> = {}): void {
+  printPayload({
+    ok: false,
+    error: {
+      code,
+      message,
+      details
+    }
+  });
+}