agentic-orchestrator 0.1.2 → 0.1.4

package/apps/control-plane/src/application/adapters/adapter-registry.ts

@@ -0,0 +1,169 @@
+import { ERROR_CODES } from '../../core/error-codes.js';
+
+export interface AdapterSlot<TContract> {
+  readonly name: string;
+  readonly _contract?: TContract; // phantom type — never at runtime
+}
+
+export interface AdapterManifest {
+  readonly slot: string;
+  readonly name: string;
+  readonly configSchema?: Record<string, unknown>;
+}
+
+export interface AdapterRegistry {
+  register<T>(slot: AdapterSlot<T>, manifest: AdapterManifest, factory: (config: unknown) => T): void;
+  resolve<T>(slot: AdapterSlot<T>, name: string, config: unknown): T;
+  list(slot: string): ReadonlyArray<AdapterManifest>;
+  has(slot: string, name: string): boolean;
+}
+
+interface AdapterEntry<T> {
+  manifest: AdapterManifest;
+  factory: (config: unknown) => T;
+}
+
+export interface AdapterRegistryError extends Error {
+  code: string;
+  details?: Record<string, unknown>;
+}
+
+function makeRegistryError(message: string, code: string, details?: Record<string, unknown>): AdapterRegistryError {
+  const error = new Error(message) as AdapterRegistryError;
+  error.code = code;
+  if (details !== undefined) {
+    error.details = details;
+  }
+  return error;
+}
+
+export class DefaultAdapterRegistry implements AdapterRegistry {
+  // slot name → adapter name → entry
+  private readonly _entries = new Map<string, Map<string, AdapterEntry<unknown>>>();
+
+  register<T>(slot: AdapterSlot<T>, manifest: AdapterManifest, factory: (config: unknown) => T): void {
+    let byName = this._entries.get(slot.name);
+    if (!byName) {
+      byName = new Map();
+      this._entries.set(slot.name, byName);
+    }    byName.set(manifest.name, { manifest, factory: factory as (config: unknown) => unknown });
+  }
+
+  resolve<T>(slot: AdapterSlot<T>, name: string, config: unknown): T {
+    const byName = this._entries.get(slot.name);
+    const entry = byName?.get(name) as AdapterEntry<T> | undefined;
+
+    if (!entry) {
+      throw makeRegistryError(
+        ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER,
+        ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER,
+        { slot: slot.name, name }
+      );
+    }
+
+    return entry.factory(config);
+  }
+
+  list(slot: string): ReadonlyArray<AdapterManifest> {
+    const byName = this._entries.get(slot);
+    if (!byName) {
+      return [];
+    }
+    return Array.from(byName.values()).map((e) => e.manifest);
+  }
+
+  has(slot: string, name: string): boolean {
+    return this._entries.get(slot)?.has(name) ?? false;
+  }
+}
+
+// ---- Built-in agent-provider slot ----
+
+export interface AgentProviderContract {
+  readonly name: string;
+}
+
+export const AGENT_PROVIDER_SLOT: AdapterSlot<AgentProviderContract> = {
+  name: 'agent-provider'
+};
+
+// ---- Activity detector slot ----
+
+export interface ActivityDetectorContract {
+  readonly name: string;
+}
+
+export const ACTIVITY_DETECTOR_SLOT: AdapterSlot<ActivityDetectorContract> = {
+  name: 'activity-detector'
+};
+
+// ---- Notification channel slot ----
+
+export interface NotificationChannelContract {
+  readonly name: string;
+}
+
+export const NOTIFICATION_CHANNEL_SLOT: AdapterSlot<NotificationChannelContract> = {
+  name: 'notification-channel'
+};
+
+// ---- SCM provider slot ----
+
+export interface ScmProviderContract {
+  readonly name: string;
+}
+
+export const SCM_PROVIDER_SLOT: AdapterSlot<ScmProviderContract> = {
+  name: 'scm-provider'
+};
+
+const BUILT_IN_PROVIDER_NAMES = ['codex', 'claude', 'gemini', 'kiro-cli', 'copilot', 'custom'] as const;
+const BUILT_IN_ACTIVITY_DETECTORS = ['claude-jsonl', 'codex-rpc', 'process-heuristic'] as const;
+const BUILT_IN_NOTIFICATION_CHANNELS = ['desktop', 'slack', 'webhook'] as const;
+const BUILT_IN_SCM_PROVIDERS = ['github'] as const;
+
+function makeProviderManifest(name: string): AdapterManifest {
+  return { slot: AGENT_PROVIDER_SLOT.name, name };
+}
+
+function makeProviderFactory(name: string): (config: unknown) => AgentProviderContract {
+  return (_config: unknown) => ({ name });
+}
+
+export const globalAdapterRegistry = new DefaultAdapterRegistry();
+
+for (const providerName of BUILT_IN_PROVIDER_NAMES) {
+  globalAdapterRegistry.register(
+    AGENT_PROVIDER_SLOT,
+    makeProviderManifest(providerName),
+    makeProviderFactory(providerName)
+  );
+}
+
+for (const detectorName of BUILT_IN_ACTIVITY_DETECTORS) {
+  globalAdapterRegistry.register(
+    ACTIVITY_DETECTOR_SLOT,
+    { slot: ACTIVITY_DETECTOR_SLOT.name, name: detectorName },
+    () => ({ name: detectorName })
+  );
+}
+
+for (const channelName of BUILT_IN_NOTIFICATION_CHANNELS) {
+  globalAdapterRegistry.register(
+    NOTIFICATION_CHANNEL_SLOT,
+    { slot: NOTIFICATION_CHANNEL_SLOT.name, name: channelName },
+    () => ({ name: channelName })
+  );
+}
+
+for (const scmProviderName of BUILT_IN_SCM_PROVIDERS) {
+  globalAdapterRegistry.register(
+    SCM_PROVIDER_SLOT,
+    { slot: SCM_PROVIDER_SLOT.name, name: scmProviderName },
+    () => ({ name: scmProviderName })
+  );
+}
+
+export const REGISTERED_PROVIDER_NAMES: ReadonlySet<string> = new Set(
+  globalAdapterRegistry.list(AGENT_PROVIDER_SLOT.name).map((m) => m.name)
+);

package/apps/control-plane/src/application/multi-project-loader.ts

@@ -0,0 +1,119 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import YAML from 'yaml';
+import { SchemaRegistry } from '../core/schemas.js';
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { AppError } from '../providers/providers.js';
+
+export interface ProjectConfig {
+  name: string;
+  path: string;
+  repo?: string;
+  branch?: string;
+  policy?: string;
+  gates?: string;
+  dashboard_port?: number;
+}
+
+export interface MultiProjectConfig {
+  version: string;
+  defaults?: {
+    max_active_features?: number;
+    max_parallel_gate_runs?: number;
+    dashboard_port?: number;
+    default_project?: string;
+    policy?: string;
+    gates?: string;
+    notifications?: { enabled?: boolean };
+  };
+  projects: ProjectConfig[];
+}
+
+const MULTI_PROJECT_YAML = 'multi-project.yaml';
+const SCHEMA_NAME = 'multi-project.schema.json';
+
+function resolveHomePath(rawPath: string): string {
+  if (rawPath.startsWith('~/') || rawPath === '~') {
+    return path.join(os.homedir(), rawPath.slice(1));
+  }
+  return rawPath;
+}
+
+function resolveConfiguredPath(rawPath: string, baseDir: string): string {
+  const expanded = resolveHomePath(rawPath);
+  if (path.isAbsolute(expanded)) {
+    return expanded;
+  }
+  return path.resolve(baseDir, expanded);
+}
+
+export class MultiProjectLoader {
+  async load(baseDir: string): Promise<MultiProjectConfig | null> {
+    const yamlPath = path.join(baseDir, 'agentic', 'orchestrator', MULTI_PROJECT_YAML);
+
+    let raw: string;
+    try {
+      raw = await fs.readFile(yamlPath, 'utf8');
+    } catch {
+      return null;
+    }
+
+    const parsed = YAML.parse(raw) as MultiProjectConfig;
+
+    const schemaRegistry = new SchemaRegistry(baseDir);
+    const result = await schemaRegistry.validate(SCHEMA_NAME, parsed);
+    if (!result.valid) {
+      const error = new Error(
+        `multi-project.yaml validation failed: ${result.errors.map((e) => e.message).join(', ')}`
+      ) as AppError;
+      error.code = ERROR_CODES.INVALID_ARGUMENT;
+      error.details = {
+        retryable: false,
+        requires_human: true,
+        validation_errors: result.errors
+      };
+      throw error;
+    }
+
+    // Resolve project paths and per-project override paths to absolute paths.
+    const projects: ProjectConfig[] = parsed.projects.map((p) => ({
+      ...p,
+      path: resolveConfiguredPath(p.path, baseDir),
+      policy: typeof p.policy === 'string' ? resolveConfiguredPath(p.policy, resolveConfiguredPath(p.path, baseDir)) : undefined,
+      gates: typeof p.gates === 'string' ? resolveConfiguredPath(p.gates, resolveConfiguredPath(p.path, baseDir)) : undefined
+    }));
+
+    return { ...parsed, projects };
+  }
+
+  getProject(config: MultiProjectConfig, name: string): ProjectConfig | null {
+    return config.projects.find((p) => p.name === name) ?? null;
+  }
+
+  resolveProjectPolicyPath(config: MultiProjectConfig, project: ProjectConfig): string | undefined {
+    const override = project.policy ?? config.defaults?.policy;
+    if (typeof override !== 'string' || override.length === 0) {
+      return undefined;
+    }
+    return resolveConfiguredPath(override, project.path);
+  }
+
+  resolveProjectGatesPath(config: MultiProjectConfig, project: ProjectConfig): string | undefined {
+    const override = project.gates ?? config.defaults?.gates;
+    if (typeof override !== 'string' || override.length === 0) {
+      return undefined;
+    }
+    return resolveConfiguredPath(override, project.path);
+  }
+
+  async exists(baseDir: string): Promise<boolean> {
+    const yamlPath = path.join(baseDir, 'agentic', 'orchestrator', MULTI_PROJECT_YAML);
+    try {
+      await fs.access(yamlPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/apps/control-plane/src/application/services/activity-monitor-service.ts

@@ -0,0 +1,199 @@
+import { TOOLS } from '../../core/constants.js';
+import type { FeatureStateFrontMatter, FeatureStatePayload, ToolCaller as SupervisorToolCaller } from '../../core/tool-caller.js';
+import type { NotifierService } from './notifier-service.js';
+
+export type ActivityState = 'active' | 'idle' | 'waiting_input' | 'blocked' | 'exited' | 'unknown';
+
+export interface ActivitySnapshot {
+  featureId: string;
+  state: ActivityState;
+  lastEventAt: string | null; // ISO8601
+  detectedVia: 'jsonl' | 'ledger' | 'process' | 'unknown';
+}
+
+export interface AgentStuckReaction {
+  enabled: boolean;
+  action: string;
+  idle_threshold_ms: number;
+  escalate_after: number;
+}
+
+export interface ActivityMonitorServiceDependencies {
+  toolCaller: SupervisorToolCaller;
+  operationLedger?: { getLastOperationAt(featureId: string): string | null };
+  idleThresholdMs?: number;
+  notifier?: NotifierService;
+  reactionsPolicy?: { agent_stuck?: AgentStuckReaction };
+  detectorName?: string;
+}
+
+type ActivityFrontMatter = FeatureStateFrontMatter & {
+  status_reason?: string;
+  last_heartbeat_at?: string;
+  last_run_at?: string;
+  activity_state?: string;
+  activity_last_event_at?: string | null;
+  activity_detected_via?: string;
+};
+
+const DEFAULT_IDLE_THRESHOLD_MS = 300_000;
+
+export class ActivityMonitorService {
+  private readonly toolCaller: SupervisorToolCaller;
+  private readonly operationLedger: { getLastOperationAt(featureId: string): string | null } | undefined;
+  private readonly idleThresholdMs: number;
+  private readonly notifier: NotifierService | undefined;
+  private readonly reactionsPolicy: { agent_stuck?: AgentStuckReaction } | undefined;
+  private readonly detectorName: string;
+
+  constructor(dependencies: ActivityMonitorServiceDependencies) {
+    this.toolCaller = dependencies.toolCaller;
+    this.operationLedger = dependencies.operationLedger;
+    this.idleThresholdMs = dependencies.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
+    this.notifier = dependencies.notifier;
+    this.reactionsPolicy = dependencies.reactionsPolicy;
+    this.detectorName = dependencies.detectorName ?? 'claude-jsonl';
+  }
+
+  private detectedVia(featureId: string): ActivitySnapshot['detectedVia'] {
+    if (this.detectorName === 'codex-rpc' && this.operationLedger?.getLastOperationAt(featureId)) {
+      return 'ledger';
+    }
+    if (this.detectorName === 'codex-rpc' || this.detectorName === 'process-heuristic') {
+      return 'process';
+    }
+    return this.detectorName === 'claude-jsonl' ? 'jsonl' : 'unknown';
+  }
+
+  private resolveLastEvent(featureId: string, frontMatter: ActivityFrontMatter): string | null {
+    const statusReason = typeof frontMatter.status_reason === 'string' ? frontMatter.status_reason.toLowerCase() : '';
+    if (statusReason.includes('waiting_input') || statusReason.includes('awaiting_input')) {
+      return frontMatter.last_heartbeat_at ?? frontMatter.last_run_at ?? null;
+    }
+
+    if (this.detectorName === 'codex-rpc') {
+      const ledgerTs = this.operationLedger?.getLastOperationAt(featureId) ?? null;
+      return ledgerTs ?? frontMatter.last_run_at ?? frontMatter.last_heartbeat_at ?? null;
+    }
+
+    if (this.detectorName === 'process-heuristic') {
+      return frontMatter.last_run_at ?? frontMatter.last_heartbeat_at ?? null;
+    }
+
+    return frontMatter.last_heartbeat_at ?? frontMatter.last_run_at ?? null;
+  }
+
+  private deriveState(frontMatter: ActivityFrontMatter, lastEventAt: string | null): ActivityState {
+    const status = frontMatter.status;
+    const statusReason = typeof frontMatter.status_reason === 'string' ? frontMatter.status_reason.toLowerCase() : '';
+
+    if (status === 'failed' || status === 'merged') {
+      return 'exited';
+    }
+    if (status === 'blocked') {
+      return 'blocked';
+    }
+    if (statusReason.includes('waiting_input') || statusReason.includes('awaiting_input')) {
+      return 'waiting_input';
+    }
+    if (!lastEventAt) {
+      return 'unknown';
+    }
+
+    const elapsed = Date.now() - new Date(lastEventAt).getTime();
+    return elapsed <= this.idleThresholdMs ? 'active' : 'idle';
+  }
+
+  private async persistSnapshot(featureId: string, snapshot: ActivitySnapshot): Promise<void> {
+    try {
+      const current = await this.toolCaller.callTool<FeatureStatePayload>('orchestrator', TOOLS.FEATURE_STATE_GET, {
+        feature_id: featureId
+      });
+      const frontMatter = current.data.front_matter as ActivityFrontMatter & {
+        version: number;
+        activity_state?: string;
+        activity_last_event_at?: string | null;
+        activity_detected_via?: string;
+      };
+      const unchanged =
+        frontMatter.activity_state === snapshot.state &&
+        (frontMatter.activity_last_event_at ?? null) === snapshot.lastEventAt &&
+        frontMatter.activity_detected_via === snapshot.detectedVia;
+      if (unchanged) {
+        return;
+      }
+
+      await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+        feature_id: featureId,
+        expected_version: frontMatter.version,
+        patch: {
+          front_matter: {
+            activity_state: snapshot.state,
+            activity_last_event_at: snapshot.lastEventAt,
+            activity_detected_via: snapshot.detectedVia,
+            activity_detector: this.detectorName
+          }
+        }
+      });
+    } catch {
+      // Activity persistence is best-effort and should not block orchestration.
+    }
+  }
+
+  async getActivityState(featureId: string): Promise<ActivitySnapshot> {
+    const response = await this.toolCaller.callTool<FeatureStatePayload>(
+      'orchestrator',
+      TOOLS.FEATURE_STATE_GET,
+      { feature_id: featureId }
+    );
+
+    const frontMatter = response.data.front_matter as ActivityFrontMatter;
+    const lastEventAt = this.resolveLastEvent(featureId, frontMatter);
+    return {
+      featureId,
+      state: this.deriveState(frontMatter, lastEventAt),
+      lastEventAt,
+      detectedVia: this.detectedVia(featureId)
+    };
+  }
+
+  async checkAndNotifyStuck(featureId: string): Promise<boolean> {
+    const snapshot = await this.getActivityState(featureId);
+    await this.persistSnapshot(featureId, snapshot);
+
+    if (snapshot.state !== 'idle') {
+      return false;
+    }
+
+    const reaction = this.reactionsPolicy?.agent_stuck;
+    if (!reaction?.enabled) {
+      return true;
+    }
+
+    if (reaction.action.includes('notify') && this.notifier) {
+      await this.notifier.notify('agent_stuck', {
+        feature_id: featureId,
+        message: `Agent for feature '${featureId}' appears stuck (idle since ${snapshot.lastEventAt ?? 'unknown'}).`,
+        details: {
+          state: snapshot.state,
+          last_event_at: snapshot.lastEventAt,
+          idle_threshold_ms: this.idleThresholdMs
+        }
+      });
+    }
+
+    return true;
+  }
+
+  formatForStatus(snapshot: ActivitySnapshot): string {
+    if (!snapshot.lastEventAt) {
+      return snapshot.state;
+    }
+
+    const elapsed = Date.now() - new Date(snapshot.lastEventAt).getTime();
+    const minutes = Math.floor(elapsed / 60_000);
+    const timeStr = minutes < 1 ? 'just now' : `${minutes}m ago`;
+
+    return `${snapshot.state} (${timeStr})`;
+  }
+}

package/apps/control-plane/src/application/services/cost-tracking-service.ts

@@ -0,0 +1,82 @@
+import { atomicWriteJson, nowIso, readJson } from '../../core/fs.js';
+
+export interface FeatureCost {
+  feature_id: string;
+  tokens_used: number;
+  estimated_cost_usd: number;
+  last_updated: string;
+}
+
+export interface BudgetPolicy {
+  per_feature_limit_usd?: number;
+  alert_threshold?: number;
+}
+
+export interface BudgetCheckResult {
+  over_budget: boolean;
+  alert_threshold_reached: boolean;
+  current_cost_usd: number;
+  limit_usd: number;
+  alert_threshold: number;
+}
+
+export interface CostTrackingServicePort {
+  featureCostPath(featureId: string): string;
+  getPolicySnapshot(): Record<string, unknown>;
+}
+
+export class CostTrackingService {
+  private readonly port: CostTrackingServicePort;
+
+  constructor(port: CostTrackingServicePort) {
+    this.port = port;
+  }
+
+  async getFeatureCost(featureId: string): Promise<FeatureCost> {
+    const existing = await readJson<FeatureCost>(this.port.featureCostPath(featureId), null);
+    return existing ?? {
+      feature_id: featureId,
+      tokens_used: 0,
+      estimated_cost_usd: 0.0,
+      last_updated: nowIso()
+    };
+  }
+
+  async recordCost(featureId: string, tokensDelta: number, costUsdDelta: number): Promise<FeatureCost> {
+    const current = await this.getFeatureCost(featureId);
+    const updated: FeatureCost = {
+      feature_id: featureId,
+      tokens_used: current.tokens_used + tokensDelta,
+      estimated_cost_usd: current.estimated_cost_usd + costUsdDelta,
+      last_updated: nowIso()
+    };
+    await atomicWriteJson(this.port.featureCostPath(featureId), updated);
+    return updated;
+  }
+
+  async checkBudget(featureId: string): Promise<BudgetCheckResult> {
+    const policy = this.port.getPolicySnapshot();
+    const budgetPolicy = (
+      policy.budget && typeof policy.budget === 'object' ? policy.budget : {}
+    ) as BudgetPolicy;
+
+    const limitUsd = typeof budgetPolicy.per_feature_limit_usd === 'number'
+      ? budgetPolicy.per_feature_limit_usd
+      : Infinity;
+    const alertThreshold = typeof budgetPolicy.alert_threshold === 'number'
+      ? budgetPolicy.alert_threshold
+      : 0.8;
+
+    const cost = await this.getFeatureCost(featureId);
+    const overBudget = Number.isFinite(limitUsd) && cost.estimated_cost_usd >= limitUsd;
+    const alertThresholdReached = Number.isFinite(limitUsd) && cost.estimated_cost_usd >= limitUsd * alertThreshold;
+
+    return {
+      over_budget: overBudget,
+      alert_threshold_reached: alertThresholdReached,
+      current_cost_usd: cost.estimated_cost_usd,
+      limit_usd: Number.isFinite(limitUsd) ? limitUsd : -1,
+      alert_threshold: alertThreshold
+    };
+  }
+}

package/apps/control-plane/src/application/services/dependency-scheduler-service.ts

@@ -0,0 +1,86 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+export interface DepBlockedEntry {
+  feature_id: string;
+  depends_on_unresolved: string[];
+}
+
+/**
+ * Returns the subset of `dependsOn` IDs not present in `mergedFeatures`.
+ */
+export function getUnresolvedDeps(dependsOn: string[], mergedFeatures: string[]): string[] {
+  const mergedSet = new Set(mergedFeatures);
+  return dependsOn.filter((dep) => !mergedSet.has(dep));
+}
+
+/**
+ * DFS cycle detection starting from `startId`.
+ * `getDirectDeps` returns the direct `depends_on` list for a given feature ID.
+ * Returns a cycle description string if a cycle is found, or `null` if none.
+ */
+export function detectCircularDependency(
+  startId: string,
+  getDirectDeps: (id: string) => string[]
+): string | null {
+  const visited = new Set<string>();
+  const stack: string[] = [];
+
+  function dfs(id: string): boolean {
+    if (stack.includes(id)) {
+      return true; // cycle found
+    }
+    if (visited.has(id)) {return false;}
+    visited.add(id);
+    stack.push(id);
+    for (const dep of getDirectDeps(id)) {
+      if (dfs(dep)) {return true;}
+    }
+    stack.pop();
+    return false;
+  }
+
+  if (dfs(startId)) {
+    const cycleStart = stack.indexOf(startId) === -1 ? 0 : stack.indexOf(startId);
+    return [...stack.slice(cycleStart), startId].join(' → ');
+  }
+  return null;
+}
+
+/**
+ * Adds (or updates) a feature's entry in `index.dep_blocked`.
+ */
+export function addToDepBlocked(index: AnyRecord, featureId: string, unresolvedDeps: string[]): void {
+  const depBlocked: DepBlockedEntry[] = Array.isArray(index.dep_blocked) ? index.dep_blocked : [];
+  const existing = depBlocked.findIndex((e) => e.feature_id === featureId);
+  const entry: DepBlockedEntry = { feature_id: featureId, depends_on_unresolved: unresolvedDeps };
+  if (existing >= 0) {
+    depBlocked[existing] = entry;
+  } else {
+    depBlocked.push(entry);
+  }
+  index.dep_blocked = depBlocked;
+}
+
+/**
+ * After `mergedFeatureId` is merged, remove it from each entry's `depends_on_unresolved`.
+ * If an entry's `depends_on_unresolved` becomes empty, the entry is removed (feature is unblocked).
+ * Returns the list of feature IDs that are now fully unblocked.
+ */
+export function resolveDepBlocked(index: AnyRecord, mergedFeatureId: string): string[] {
+  const depBlocked: DepBlockedEntry[] = Array.isArray(index.dep_blocked) ? index.dep_blocked : [];
+  const promoted: string[] = [];
+  const remaining: DepBlockedEntry[] = [];
+
+  for (const entry of depBlocked) {
+    const stillUnresolved = entry.depends_on_unresolved.filter((dep) => dep !== mergedFeatureId);
+    if (stillUnresolved.length === 0) {
+      promoted.push(entry.feature_id);
+    } else {
+      remaining.push({ ...entry, depends_on_unresolved: stillUnresolved });
+    }
+  }
+
+  index.dep_blocked = remaining;
+  return promoted;
+}