agentic-orchestrator 0.1.3 → 0.1.4

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

@@ -0,0 +1,295 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export type NotificationPriority = 'critical' | 'warning' | 'info';
+type CanonicalPriority = NotificationPriority;
+export type NotificationEvent =
+  | 'gate_failed'
+  | 'collision_detected'
+  | 'feature_blocked'
+  | 'ready_to_merge'
+  | 'feature_merged'
+  | 'stale_lease'
+  | 'agent_stuck'
+  | 'changes_requested'
+  | 'budget_exceeded'
+  | 'budget_alert';
+
+export interface NotificationPayload {
+  event: NotificationEvent;
+  priority: NotificationPriority;
+  feature_id?: string;
+  message: string;
+  details?: Record<string, unknown>;
+  timestamp: string;
+}
+
+export interface NotifierChannel {
+  name: string;
+  send(payload: NotificationPayload): Promise<void>;
+}
+
+export interface NotificationChannelConfig {
+  desktop?: { enabled?: boolean };
+  slack?: { enabled?: boolean; webhook?: string; channel?: string };
+  webhook?: { enabled?: boolean; url?: string };
+}
+
+export interface NotificationRoutingConfig {
+  critical?: string[];
+  warning?: string[];
+  info?: string[];
+  urgent?: string[];
+  action?: string[];
+}
+
+export interface NotificationConfig {
+  enabled: boolean;
+  channels?: NotificationChannelConfig;
+  routing?: NotificationRoutingConfig;
+}
+
+const DEFAULT_ROUTING: Record<NotificationPriority, string[]> = {
+  critical: ['desktop', 'slack'],
+  warning: ['slack', 'desktop'],
+  info: ['slack']
+};
+
+const EVENT_PRIORITY: Record<NotificationEvent, CanonicalPriority> = {
+  gate_failed: 'critical',
+  collision_detected: 'critical',
+  feature_blocked: 'warning',
+  ready_to_merge: 'info',
+  feature_merged: 'info',
+  stale_lease: 'warning',
+  agent_stuck: 'warning',
+  changes_requested: 'warning',
+  budget_exceeded: 'critical',
+  budget_alert: 'warning'
+};
+
+const THROTTLE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+
+export class DesktopNotifierChannel implements NotifierChannel {
+  readonly name = 'desktop';
+
+  async send(payload: NotificationPayload): Promise<void> {
+    const title = `AOP [${payload.priority}]`;
+    const body = payload.feature_id
+      ? `[${payload.feature_id}] ${payload.message}`
+      : payload.message;
+
+    const platform = process.platform;
+    try {
+      if (platform === 'linux') {
+        await execFileAsync('notify-send', [title, body], { timeout: 3000 });
+      } else if (platform === 'darwin') {
+        const script = `display notification "${body.replaceAll('"', '\\"')}" with title "${title.replaceAll('"', '\\"')}"`;
+        await execFileAsync('osascript', ['-e', script], { timeout: 3000 });
+      }
+      // Other platforms: silently skip
+    } catch {
+      // Notification tool not available — silently skip
+    }
+  }
+}
+
+export class SlackNotifierChannel implements NotifierChannel {
+  readonly name = 'slack';
+  private readonly webhookUrl: string;
+  private readonly channel: string;
+
+  constructor(webhookUrl: string, channel: string) {
+    this.webhookUrl = webhookUrl;
+    this.channel = channel;
+  }
+
+  async send(payload: NotificationPayload): Promise<void> {
+    const details = payload.details ?? {};
+    const dashboardFeatureUrl =
+      typeof details.dashboard_feature_url === 'string' && details.dashboard_feature_url.length > 0
+        ? details.dashboard_feature_url
+        : typeof details.dashboard_url === 'string' && details.dashboard_url.length > 0
+          ? details.dashboard_url
+          : null;
+    const detailsJson = JSON.stringify(details);
+    const detailsSuffix =
+      detailsJson !== '{}' ? `\nContext: \`${detailsJson.length > 800 ? `${detailsJson.slice(0, 800)}…` : detailsJson}\`` : '';
+    const dashboardSuffix = dashboardFeatureUrl ? `\nDashboard: ${dashboardFeatureUrl}` : '';
+    const text = payload.feature_id
+      ? `*[${payload.priority.toUpperCase()}]* \`${payload.feature_id}\`: ${payload.message}`
+      : `*[${payload.priority.toUpperCase()}]* ${payload.message}`;
+
+    const body = JSON.stringify({ channel: this.channel, text: `${text}${dashboardSuffix}${detailsSuffix}` });
+    const response = await fetch(this.webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body
+    });
+    if (!response.ok) {
+      throw new Error(`Slack webhook returned ${response.status}`);
+    }
+  }
+}
+
+export class WebhookNotifierChannel implements NotifierChannel {
+  readonly name = 'webhook';
+  private readonly url: string;
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  async send(payload: NotificationPayload): Promise<void> {
+    const response = await fetch(this.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      throw new Error(`Webhook returned ${response.status}`);
+    }
+  }
+}
+
+export class NotifierService {
+  private readonly config: NotificationConfig;
+  private readonly channels: Map<string, NotifierChannel>;
+  private readonly routing: Record<CanonicalPriority, string[]>;
+  private readonly throttleCache: Map<string, number>;
+  private readonly dashboardUrl: string | null;
+
+  constructor(config: NotificationConfig, dashboardUrl: string | null = null) {
+    this.config = config;
+    this.throttleCache = new Map();
+    this.routing = this.buildRouting(config.routing);
+    this.channels = this.buildChannels(config.channels);
+    this.dashboardUrl = dashboardUrl;
+  }
+
+  private buildRouting(routing: NotificationRoutingConfig | undefined): Record<CanonicalPriority, string[]> {
+    const critical = routing?.critical ?? routing?.urgent ?? routing?.action ?? DEFAULT_ROUTING.critical;
+    return {
+      critical,
+      warning: routing?.warning ?? DEFAULT_ROUTING.warning,
+      info: routing?.info ?? DEFAULT_ROUTING.info
+    };
+  }
+
+  private buildChannels(channelsConfig: NotificationChannelConfig | undefined): Map<string, NotifierChannel> {
+    const map = new Map<string, NotifierChannel>();
+    if (!channelsConfig) {
+      return map;
+    }
+
+    if (channelsConfig.desktop?.enabled === true) {
+      map.set('desktop', new DesktopNotifierChannel());
+    }
+
+    const slack = channelsConfig.slack;
+    if (slack?.enabled === true && slack.webhook) {
+      map.set('slack', new SlackNotifierChannel(slack.webhook, slack.channel ?? '#aop-alerts'));
+    }
+
+    const webhook = channelsConfig.webhook;
+    if (webhook?.enabled === true && webhook.url) {
+      map.set('webhook', new WebhookNotifierChannel(webhook.url));
+    }
+
+    return map;
+  }
+
+  private isThrottled(featureId: string | undefined, event: NotificationEvent): boolean {
+    const key = `${featureId ?? '__global__'}:${event}`;
+    const last = this.throttleCache.get(key);
+    const now = Date.now();
+    if (last !== undefined && now - last < THROTTLE_WINDOW_MS) {
+      return true;
+    }
+    this.throttleCache.set(key, now);
+    return false;
+  }
+
+  async notify(
+    event: NotificationEvent,
+    context: { feature_id?: string; message: string; details?: Record<string, unknown> }
+  ): Promise<void> {
+    if (!this.config.enabled) {
+      return;
+    }
+    if (this.isThrottled(context.feature_id, event)) {
+      return;
+    }
+
+    const priority = EVENT_PRIORITY[event];
+    const details: Record<string, unknown> = {
+      ...(context.details ?? {})
+    };
+    if (this.dashboardUrl) {
+      details.dashboard_url = this.dashboardUrl;
+      if (context.feature_id) {
+        details.dashboard_feature_url = `${this.dashboardUrl}?feature=${encodeURIComponent(context.feature_id)}`;
+      }
+    }
+    const payload: NotificationPayload = {
+      event,
+      priority,
+      feature_id: context.feature_id,
+      message: context.message,
+      details,
+      timestamp: new Date().toISOString()
+    };
+
+    const targetChannelNames = this.routing[priority] ?? [];
+
+    for (const channelName of targetChannelNames) {
+      const channel = this.channels.get(channelName);
+      if (!channel) {
+        continue;
+      }
+      try {
+        await channel.send(payload);
+      } catch (err) {
+        process.stderr.write(`[NotifierService] Channel "${channelName}" failed: ${String(err)}\n`);
+      }
+    }
+  }
+}
+
+export function createNotifierService(
+  policySnapshot: Record<string, unknown>,
+  preferredChannel: string | null = null
+): NotifierService {
+  const raw = policySnapshot.notifications;
+  if (!raw || typeof raw !== 'object') {
+    return new NotifierService({ enabled: false });
+  }
+  const n = raw as Record<string, unknown>;
+  const config: NotificationConfig = {
+    enabled: n.enabled === true,
+    channels: (n.channels as NotificationChannelConfig | undefined) ?? {},
+    routing: (n.routing as NotificationRoutingConfig | undefined) ?? {}
+  };
+  if (preferredChannel) {
+    const channels = config.channels ?? {};
+    const forceEnabled = { enabled: true };
+    config.channels = {
+      desktop: preferredChannel === 'desktop' ? { ...(channels.desktop ?? {}), ...forceEnabled } : { enabled: false },
+      slack: preferredChannel === 'slack' ? { ...(channels.slack ?? {}), ...forceEnabled } : { enabled: false },
+      webhook: preferredChannel === 'webhook' ? { ...(channels.webhook ?? {}), ...forceEnabled } : { enabled: false }
+    };
+  }
+  const dashboardRaw =
+    policySnapshot.dashboard && typeof policySnapshot.dashboard === 'object'
+      ? (policySnapshot.dashboard as Record<string, unknown>)
+      : {};
+  const dashboardPort =
+    typeof dashboardRaw.port === 'number' && Number.isFinite(dashboardRaw.port) ? Math.floor(dashboardRaw.port) : 3000;
+  const dashboardUrl =
+    typeof process.env.AOP_DASHBOARD_URL === 'string' && process.env.AOP_DASHBOARD_URL.trim().length > 0
+      ? process.env.AOP_DASHBOARD_URL.trim()
+      : `http://localhost:${dashboardPort}`;
+  return new NotifierService(config, dashboardUrl);
+}

package/apps/control-plane/src/application/services/performance-analytics-service.ts

@@ -0,0 +1,122 @@
+import { atomicWriteJson, ensureDir, nowIso, readJson } from '../../core/fs.js';
+import path from 'node:path';
+
+export interface FeatureOutcome {
+  feature_id: string;
+  provider: string;
+  model: string;
+  status: string;
+  gate_pass: boolean;
+  retry_count: number;
+  duration_ms: number;
+  cost_usd: number;
+  recorded_at: string;
+}
+
+export interface ProviderModelStats {
+  provider: string;
+  model: string;
+  total_features: number;
+  success_count: number;
+  success_rate: number;
+  avg_retry_count: number;
+  avg_duration_ms: number;
+  avg_cost_usd: number;
+  last_updated: string;
+}
+
+export interface AnalyticsSnapshot {
+  outcomes: FeatureOutcome[];
+  aggregates: ProviderModelStats[];
+  generated_at: string;
+}
+
+export interface PerformanceAnalyticsServicePort {
+  analyticsPath(): string;
+  getPolicySnapshot(): Record<string, unknown>;
+}
+
+function computeAggregates(outcomes: FeatureOutcome[]): ProviderModelStats[] {
+  const groups = new Map<string, FeatureOutcome[]>();
+  for (const o of outcomes) {
+    const key = `${o.provider}::${o.model}`;
+    const list = groups.get(key);
+    if (list) {
+      list.push(o);
+    } else {
+      groups.set(key, [o]);
+    }
+  }
+
+  const aggregates: ProviderModelStats[] = [];
+  for (const [, group] of groups) {
+    const first = group[0];
+    const total = group.length;
+    const successCount = group.filter((o) => o.gate_pass).length;
+    const sumRetry = group.reduce((s, o) => s + o.retry_count, 0);
+    const sumDuration = group.reduce((s, o) => s + o.duration_ms, 0);
+    const sumCost = group.reduce((s, o) => s + o.cost_usd, 0);
+
+    aggregates.push({
+      provider: first.provider,
+      model: first.model,
+      total_features: total,
+      success_count: successCount,
+      success_rate: total > 0 ? successCount / total : 0,
+      avg_retry_count: total > 0 ? sumRetry / total : 0,
+      avg_duration_ms: total > 0 ? sumDuration / total : 0,
+      avg_cost_usd: total > 0 ? sumCost / total : 0,
+      last_updated: nowIso()
+    });
+  }
+
+  return aggregates;
+}
+
+export class PerformanceAnalyticsService {
+  private readonly port: PerformanceAnalyticsServicePort;
+
+  constructor(port: PerformanceAnalyticsServicePort) {
+    this.port = port;
+  }
+
+  async recordOutcome(outcome: FeatureOutcome): Promise<AnalyticsSnapshot> {
+    const filePath = this.port.analyticsPath();
+    await ensureDir(path.dirname(filePath));
+
+    const current = await this.readSnapshot();
+    current.outcomes.push(outcome);
+    current.aggregates = computeAggregates(current.outcomes);
+    current.generated_at = nowIso();
+
+    await atomicWriteJson(filePath, current);
+    return current;
+  }
+
+  async getAnalytics(): Promise<AnalyticsSnapshot> {
+    return await this.readSnapshot();
+  }
+
+  async getProviderStats(provider?: string, model?: string): Promise<ProviderModelStats[]> {
+    const snapshot = await this.readSnapshot();
+    let stats = snapshot.aggregates;
+
+    if (provider) {
+      stats = stats.filter((s) => s.provider === provider);
+    }
+    if (model) {
+      stats = stats.filter((s) => s.model === model);
+    }
+
+    return stats;
+  }
+
+  private async readSnapshot(): Promise<AnalyticsSnapshot> {
+    const existing = await readJson<AnalyticsSnapshot>(this.port.analyticsPath(), null);
+    return existing ?? {
+      outcomes: [],
+      aggregates: [],
+      generated_at: nowIso()
+    };
+  }
+}

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

@@ -4,6 +4,7 @@ import { sortResourcesDeterministically } from '../../core/path-rules.js';
 import { ERROR_CODES } from '../../core/error-codes.js';
 import { fail } from '../../core/response.js';
 import { GATE_RESULT, STATUS } from '../../core/constants.js';
+import { getUnresolvedDeps, detectCircularDependency, addToDepBlocked } from './dependency-scheduler-service.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyRecord = Record<string, any>;
@@ -227,6 +228,53 @@ export class PlanService {
     };
   }
 
+  async checkDependencies(featureId: string | null): Promise<void> {
+    if (!featureId) {return;}
+    const state = await this.port.readState(featureId);
+    const dependsOn: string[] = Array.isArray(state.frontMatter.depends_on)
+      ? (state.frontMatter.depends_on as string[]).filter((d): d is string => typeof d === 'string')
+      : [];
+    if (dependsOn.length === 0) {return;}
+
+    // Circular detection: traverse the dependency chain
+    const depsCache = new Map<string, string[]>([[featureId, dependsOn]]);
+    const getDirectDeps = (id: string): string[] => {
+      if (depsCache.has(id)) {return depsCache.get(id);}
+      return [];
+    };
+    const cycle = detectCircularDependency(featureId, getDirectDeps);
+    if (cycle) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.DEPENDENCY_CIRCULAR, `Circular dependency detected: ${cycle}`, {
+          feature_id: featureId,
+          cycle,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const index = await this.port.readIndex();
+    const mergedFeatures: string[] = Array.isArray(index.merged) ? (index.merged as string[]) : [];
+    const unresolved = getUnresolvedDeps(dependsOn, mergedFeatures);
+    if (unresolved.length > 0) {
+      await this.port.withIndexLock(async () => {
+        const idx = await this.port.readIndex();
+        addToDepBlocked(idx, featureId, unresolved);
+        idx.updated_at = nowIso();
+        await this.port.writeIndex(idx);
+      });
+      throw {
+        normalizedResponse: fail(ERROR_CODES.DEPENDENCY_UNRESOLVED, 'Plan deferred: dependencies not yet merged', {
+          feature_id: featureId,
+          depends_on_unresolved: unresolved,
+          retryable: true,
+          requires_human: false
+        })
+      };
+    }
+  }
+
   async planSubmit(
     featureId: string | null,
     plan: AnyRecord | null,
@@ -255,6 +303,9 @@ export class PlanService {
     await this.validatePlanSchema(plan);
     await this.assertPlanLocksHeld(featureId, plan);
 
+    // N4: Dependency-aware scheduling — check depends_on before accepting plan
+    await this.checkDependencies(featureId);
+
     const existing = await readJson(this.port.planPath(featureId), null);
     this.validatePlanRevisionRules(existing, plan, expectedVersion);