@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/engine/approvals.ts

@@ -69,19 +69,158 @@ export interface ApprovalPolicy {
   enabled: boolean;
 }
 
+// ─── Escalation Chains ────────────────────────────────
+
+export interface EscalationLevel {
+  order: number;
+  approvers: {
+    userIds: string[];
+    roles: string[];
+  };
+  timeoutMinutes: number;
+  notifyChannels: ('email' | 'slack' | 'webhook')[];
+}
+
+export interface EscalationChain {
+  id: string;
+  orgId: string;
+  name: string;
+  description?: string;
+  levels: EscalationLevel[];
+  fallbackAction: 'deny' | 'allow' | 'escalate_admin';
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface EscalationState {
+  chainId: string;
+  currentLevel: number;
+  history: { level: number; notifiedAt: string; escalatedAt?: string }[];
+}
+
 // ─── Engine ─────────────────────────────────────────────
 
+import type { EngineDatabase } from './db-adapter.js';
+
 export class ApprovalEngine {
   private requests = new Map<string, ApprovalRequest>();
   private policies: ApprovalPolicy[] = [];
+  private escalationChains = new Map<string, EscalationChain>();
+  private escalationTimers = new Map<string, NodeJS.Timeout>();
   private listeners: ((req: ApprovalRequest) => void)[] = [];
+  private engineDb?: EngineDatabase;
 
-  addPolicy(policy: ApprovalPolicy) {
+  /**
+   * Set the database adapter and load existing data from DB
+   */
+  async setDb(db: EngineDatabase): Promise<void> {
+    this.engineDb = db;
+    await this.loadFromDb();
+  }
+
+  /**
+   * Load pending requests and policies from DB
+   */
+  private async loadFromDb(): Promise<void> {
+    if (!this.engineDb) return;
+    try {
+      // Load pending approval requests and recreate expiry timers
+      const pending = await this.engineDb.getApprovalRequests({ status: 'pending' });
+      for (const req of pending) {
+        this.requests.set(req.id, req);
+        this.recreateExpiryTimer(req);
+      }
+
+      // Load all approval policies
+      const policies = await this.engineDb.getAllApprovalPolicies();
+      for (const policy of policies) {
+        if (!this.policies.find(p => p.id === policy.id)) {
+          this.policies.push(policy);
+        }
+      }
+
+      // Load escalation chains
+      try {
+        const chains = await this.engineDb.query<any>('SELECT * FROM escalation_chains WHERE enabled = 1');
+        for (const r of chains) {
+          this.escalationChains.set(r.id, {
+            id: r.id, orgId: r.org_id, name: r.name, description: r.description,
+            levels: JSON.parse(r.levels), fallbackAction: r.fallback_action,
+            enabled: !!r.enabled, createdAt: r.created_at, updatedAt: r.updated_at,
+          });
+        }
+      } catch { /* escalation_chains table may not exist yet */ }
+    } catch {
+      // Table may not exist yet
+    }
+  }
+
+  private recreateExpiryTimer(req: ApprovalRequest): void {
+    const expiresAt = new Date(req.expiresAt).getTime();
+    const remaining = expiresAt - Date.now();
+
+    if (remaining <= 0) {
+      // Already expired — expire it now
+      const policy = this.findMatchingPolicy(req.toolId, req.riskLevel, req.sideEffects);
+      if (policy?.timeout.defaultAction === 'allow') {
+        req.status = 'approved';
+        req.decision = {
+          by: 'system',
+          action: 'approve',
+          reason: 'Auto-approved: approval timeout expired',
+          timestamp: new Date().toISOString(),
+        };
+      } else {
+        req.status = 'expired';
+      }
+      this.engineDb?.updateApprovalRequest(req.id, req.status, req.decision).catch((err) => {
+        console.error(`[approvals] Failed to expire request ${req.id}:`, err);
+      });
+      this.notifyListeners(req);
+      return;
+    }
+
+    // Set timer for remaining time
+    const policy = this.findMatchingPolicy(req.toolId, req.riskLevel, req.sideEffects);
+    setTimeout(() => {
+      const current = this.requests.get(req.id);
+      if (current && current.status === 'pending') {
+        if (policy?.timeout.defaultAction === 'allow') {
+          current.status = 'approved';
+          current.decision = {
+            by: 'system',
+            action: 'approve',
+            reason: 'Auto-approved: approval timeout expired',
+            timestamp: new Date().toISOString(),
+          };
+        } else {
+          current.status = 'expired';
+        }
+        this.engineDb?.updateApprovalRequest(current.id, current.status, current.decision).catch((err) => {
+          console.error(`[approvals] Failed to update expired request ${current.id}:`, err);
+        });
+        this.notifyListeners(current);
+      }
+    }, remaining);
+  }
+
+  async addPolicy(policy: ApprovalPolicy, orgId?: string): Promise<void> {
     this.policies.push(policy);
+    if (this.engineDb && orgId) {
+      try {
+        await this.engineDb.upsertApprovalPolicy(orgId, policy);
+      } catch (err) {
+        console.error(`[approvals] Failed to persist policy ${policy.id}:`, err);
+      }
+    }
   }
 
   removePolicy(id: string) {
     this.policies = this.policies.filter(p => p.id !== id);
+    this.engineDb?.deleteApprovalPolicy(id).catch((err) => {
+      console.error(`[approvals] Failed to delete policy ${id}:`, err);
+    });
   }
 
   getPolicies(): ApprovalPolicy[] {
@@ -100,6 +239,7 @@ export class ApprovalEngine {
     sideEffects: string[];
     parameters?: Record<string, any>;
     context?: string;
+    orgId?: string;
   }): Promise<ApprovalRequest | null> {
     // Find matching policy
     const policy = this.findMatchingPolicy(opts.toolId, opts.riskLevel, opts.sideEffects);
@@ -123,6 +263,13 @@ export class ApprovalEngine {
 
     this.requests.set(request.id, request);
 
+    // Persist to DB
+    try {
+      await this.engineDb?.insertApprovalRequest(request, opts.orgId || '');
+    } catch (err) {
+      console.error(`[approvals] Failed to persist approval request ${request.id}:`, err);
+    }
+
     // Notify approvers
     await this.notifyApprovers(request, policy);
 
@@ -153,13 +300,20 @@ export class ApprovalEngine {
   /**
    * Approve or deny a pending request
    */
-  decide(requestId: string, decision: Omit<ApprovalDecision, 'timestamp'>): ApprovalRequest | null {
+  async decide(requestId: string, decision: Omit<ApprovalDecision, 'timestamp'>): Promise<ApprovalRequest | null> {
     const request = this.requests.get(requestId);
     if (!request || request.status !== 'pending') return null;
 
     request.status = decision.action === 'approve' ? 'approved' : 'denied';
     request.decision = { ...decision, timestamp: new Date().toISOString() };
 
+    // Persist to DB
+    try {
+      await this.engineDb?.updateApprovalRequest(request.id, request.status, request.decision);
+    } catch (err) {
+      console.error(`[approvals] Failed to persist decision for ${request.id}:`, err);
+    }
+
     this.notifyListeners(request);
     return request;
   }
@@ -228,6 +382,159 @@ export class ApprovalEngine {
     return () => { this.listeners = this.listeners.filter(l => l !== listener); };
   }
 
+  // ─── Escalation Chains ──────────────────────────────────
+
+  async addEscalationChain(chain: EscalationChain): Promise<void> {
+    this.escalationChains.set(chain.id, chain);
+    this.engineDb?.execute(
+      `INSERT INTO escalation_chains (id, org_id, name, description, levels, fallback_action, enabled, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET name=excluded.name, description=excluded.description, levels=excluded.levels, fallback_action=excluded.fallback_action, enabled=excluded.enabled, updated_at=excluded.updated_at`,
+      [chain.id, chain.orgId, chain.name, chain.description || null, JSON.stringify(chain.levels), chain.fallbackAction, chain.enabled ? 1 : 0, chain.createdAt, chain.updatedAt]
+    ).catch((err) => { console.error(`[approvals] Failed to persist escalation chain ${chain.id}:`, err); });
+  }
+
+  removeEscalationChain(id: string): void {
+    this.escalationChains.delete(id);
+    this.engineDb?.execute('DELETE FROM escalation_chains WHERE id = ?', [id])
+      .catch((err) => { console.error(`[approvals] Failed to delete escalation chain ${id}:`, err); });
+  }
+
+  getEscalationChains(orgId?: string): EscalationChain[] {
+    const all = Array.from(this.escalationChains.values());
+    return orgId ? all.filter(c => c.orgId === orgId) : all;
+  }
+
+  getEscalationChain(id: string): EscalationChain | undefined {
+    return this.escalationChains.get(id);
+  }
+
+  /**
+   * Manually escalate a pending approval request to the next level
+   */
+  async escalateRequest(requestId: string): Promise<ApprovalRequest | null> {
+    const request = this.requests.get(requestId);
+    if (!request || request.status !== 'pending') return null;
+
+    const escalation = (request as any)._escalation as EscalationState | undefined;
+    if (!escalation) return null;
+
+    const chain = this.escalationChains.get(escalation.chainId);
+    if (!chain) return null;
+
+    const nextLevel = escalation.currentLevel + 1;
+    const nextLevelDef = chain.levels.find(l => l.order === nextLevel);
+
+    if (!nextLevelDef) {
+      // No more levels — apply fallback
+      if (chain.fallbackAction === 'allow') {
+        request.status = 'approved';
+        request.decision = { by: 'system', action: 'approve', reason: 'Escalation chain exhausted — auto-approved', timestamp: new Date().toISOString() };
+      } else {
+        request.status = 'expired';
+      }
+      this.engineDb?.updateApprovalRequest(request.id, request.status, request.decision).catch(() => {});
+      this.notifyListeners(request);
+      return request;
+    }
+
+    // Move to next level
+    escalation.history.push({ level: escalation.currentLevel, notifiedAt: new Date().toISOString(), escalatedAt: new Date().toISOString() });
+    escalation.currentLevel = nextLevel;
+
+    // Update expiry based on new level's timeout
+    request.expiresAt = new Date(Date.now() + nextLevelDef.timeoutMinutes * 60_000).toISOString();
+
+    // Set new escalation timer
+    this.clearEscalationTimer(requestId);
+    this.setEscalationTimer(request, chain, nextLevel);
+
+    // Persist escalation state
+    this.engineDb?.execute(
+      'UPDATE approval_requests SET escalation_level = ?, escalation_history = ?, expires_at = ? WHERE id = ?',
+      [nextLevel, JSON.stringify(escalation.history), request.expiresAt, requestId]
+    ).catch(() => {});
+
+    this.notifyListeners(request);
+    return request;
+  }
+
+  /**
+   * Create an approval request with escalation chain support
+   */
+  async requestApprovalWithEscalation(opts: {
+    agentId: string; agentName: string; toolId: string; toolName: string;
+    riskLevel: string; sideEffects: string[]; parameters?: Record<string, any>;
+    context?: string; orgId?: string; escalationChainId: string;
+  }): Promise<ApprovalRequest | null> {
+    const chain = this.escalationChains.get(opts.escalationChainId);
+    if (!chain || !chain.enabled || chain.levels.length === 0) {
+      return this.requestApproval(opts); // Fallback to standard approval
+    }
+
+    const firstLevel = chain.levels.find(l => l.order === 1) || chain.levels[0];
+
+    const request: ApprovalRequest = {
+      id: crypto.randomUUID(),
+      agentId: opts.agentId, agentName: opts.agentName,
+      toolId: opts.toolId, toolName: opts.toolName,
+      reason: `Escalation chain "${chain.name}" — Level 1`,
+      riskLevel: opts.riskLevel, sideEffects: opts.sideEffects,
+      parameters: this.sanitizeParams(opts.parameters),
+      context: opts.context, status: 'pending',
+      createdAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + firstLevel.timeoutMinutes * 60_000).toISOString(),
+    };
+
+    // Store escalation state as a hidden property
+    const escalation: EscalationState = {
+      chainId: chain.id, currentLevel: 1,
+      history: [{ level: 1, notifiedAt: new Date().toISOString() }],
+    };
+    (request as any)._escalation = escalation;
+
+    this.requests.set(request.id, request);
+
+    // Persist with escalation columns
+    try {
+      await this.engineDb?.insertApprovalRequest(request, opts.orgId || '');
+      await this.engineDb?.execute(
+        'UPDATE approval_requests SET escalation_chain_id = ?, escalation_level = ?, escalation_history = ? WHERE id = ?',
+        [chain.id, 1, JSON.stringify(escalation.history), request.id]
+      );
+    } catch (err) {
+      console.error(`[approvals] Failed to persist escalated approval:`, err);
+    }
+
+    // Set escalation timer
+    this.setEscalationTimer(request, chain, 1);
+
+    this.notifyListeners(request);
+    return request;
+  }
+
+  private setEscalationTimer(request: ApprovalRequest, chain: EscalationChain, currentLevel: number): void {
+    const levelDef = chain.levels.find(l => l.order === currentLevel);
+    if (!levelDef) return;
+
+    const timer = setTimeout(() => {
+      const req = this.requests.get(request.id);
+      if (req && req.status === 'pending') {
+        this.escalateRequest(request.id).catch(() => {});
+      }
+    }, levelDef.timeoutMinutes * 60_000);
+
+    this.escalationTimers.set(request.id, timer);
+  }
+
+  private clearEscalationTimer(requestId: string): void {
+    const timer = this.escalationTimers.get(requestId);
+    if (timer) {
+      clearTimeout(timer);
+      this.escalationTimers.delete(requestId);
+    }
+  }
+
   // ─── Private ──────────────────────────────────────────
 
   private findMatchingPolicy(toolId: string, riskLevel: string, sideEffects: string[]): ApprovalPolicy | undefined {

package/src/engine/catalog-routes.ts

@@ -0,0 +1,155 @@
+/**
+ * Catalog Routes — Skills + Souls + Permission Profiles + Config Generation
+ * Mounted at / on the engine sub-app (routes define /skills/*, /souls/*, /profiles/*, /permissions/*, /config/*).
+ */
+
+import { Hono } from 'hono';
+import type { PermissionEngine, SkillSuite } from './skills.js';
+import type { SkillDefinition } from './skills.js';
+import type { AgentConfigGenerator, AgentConfig } from './agent-config.js';
+
+interface PresetProfile {
+  name: string;
+  [key: string]: any;
+}
+
+interface SoulLibrary {
+  getSoulTemplates: () => any[];
+  getSoulTemplatesByCategory: () => Record<string, any[]>;
+  getSoulTemplate: (id: string) => any | undefined;
+  searchSoulTemplates: (query: string) => any[];
+  SOUL_CATEGORIES: Record<string, any>;
+}
+
+export function createCatalogRoutes(opts: {
+  skills: Omit<SkillDefinition, 'tools'>[];
+  presets: readonly PresetProfile[];
+  permissions: PermissionEngine;
+  configGen: AgentConfigGenerator;
+  soulLib: SoulLibrary;
+  suites?: SkillSuite[];
+}) {
+  const { skills, presets, permissions, configGen, soulLib, suites = [] } = opts;
+  const router = new Hono();
+
+  // ─── Skills Catalog ─────────────────────────────────────
+
+  router.get('/skills', (c) => {
+    return c.json({ skills, categories: [...new Set(skills.map(s => s.category))], total: skills.length });
+  });
+
+  router.get('/skills/by-category', (c) => {
+    const grouped: Record<string, typeof skills> = {};
+    for (const skill of skills) {
+      if (!grouped[skill.category]) grouped[skill.category] = [];
+      grouped[skill.category].push(skill);
+    }
+    return c.json({ categories: grouped });
+  });
+
+  router.get('/skills/suites', (c) => {
+    return c.json({ suites, total: suites.length });
+  });
+
+  router.get('/skills/:id', (c) => {
+    const skill = skills.find(s => s.id === c.req.param('id'));
+    if (!skill) return c.json({ error: 'Skill not found' }, 404);
+    return c.json({ skill });
+  });
+
+  // ─── Soul Library (Pre-built Role Templates) ────────────
+
+  router.get('/souls', (c) => {
+    const templates = soulLib.getSoulTemplates();
+    return c.json({ templates, categories: soulLib.SOUL_CATEGORIES, total: templates.length });
+  });
+
+  router.get('/souls/by-category', (c) => {
+    return c.json({ categories: soulLib.getSoulTemplatesByCategory(), categoryMeta: soulLib.SOUL_CATEGORIES });
+  });
+
+  router.get('/souls/search', (c) => {
+    const q = c.req.query('q') || '';
+    const results = soulLib.searchSoulTemplates(q);
+    return c.json({ templates: results, total: results.length });
+  });
+
+  router.get('/souls/:id', (c) => {
+    const template = soulLib.getSoulTemplate(c.req.param('id'));
+    if (!template) return c.json({ error: 'Soul template not found' }, 404);
+    return c.json({ template });
+  });
+
+  // ─── Permission Profiles ────────────────────────────────
+
+  router.get('/profiles/presets', (c) => c.json({ presets }));
+
+  router.get('/profiles/:agentId', (c) => {
+    const profile = permissions.getProfile(c.req.param('agentId'));
+    if (!profile) return c.json({ error: 'No profile assigned' }, 404);
+    return c.json({ profile });
+  });
+
+  router.put('/profiles/:agentId', async (c) => {
+    const agentId = c.req.param('agentId');
+    const profile = await c.req.json();
+    profile.id = profile.id || agentId;
+    profile.updatedAt = new Date().toISOString();
+    if (!profile.createdAt) profile.createdAt = profile.updatedAt;
+    permissions.setProfile(agentId, profile);
+    return c.json({ success: true, profile });
+  });
+
+  router.post('/profiles/:agentId/apply-preset', async (c) => {
+    const agentId = c.req.param('agentId');
+    const { presetName } = await c.req.json();
+    const preset = presets.find(p => p.name === presetName);
+    if (!preset) return c.json({ error: 'Preset not found' }, 404);
+    const profile = { ...preset, id: agentId, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
+    permissions.setProfile(agentId, profile as any);
+    return c.json({ success: true, profile });
+  });
+
+  router.post('/permissions/check', async (c) => {
+    const { agentId, toolId } = await c.req.json();
+    return c.json(permissions.checkPermission(agentId, toolId));
+  });
+
+  router.get('/permissions/:agentId/tools', (c) => {
+    const tools = permissions.getAvailableTools(c.req.param('agentId'));
+    return c.json({ tools, total: tools.length });
+  });
+
+  router.get('/permissions/:agentId/policy', (c) => {
+    return c.json(permissions.generateToolPolicy(c.req.param('agentId')));
+  });
+
+  // ─── Config Generation ──────────────────────────────────
+
+  router.post('/config/workspace', async (c) => {
+    const config: AgentConfig = await c.req.json();
+    return c.json({ files: configGen.generateWorkspace(config) });
+  });
+
+  router.post('/config/gateway', async (c) => {
+    const config: AgentConfig = await c.req.json();
+    return c.json({ config: configGen.generateGatewayConfig(config) });
+  });
+
+  router.post('/config/docker-compose', async (c) => {
+    const config: AgentConfig = await c.req.json();
+    return c.json({ compose: configGen.generateDockerCompose(config) });
+  });
+
+  router.post('/config/systemd', async (c) => {
+    const config: AgentConfig = await c.req.json();
+    return c.json({ unit: configGen.generateSystemdUnit(config) });
+  });
+
+  router.post('/config/deploy-script', async (c) => {
+    const config: AgentConfig = await c.req.json();
+    return c.json({ script: configGen.generateVPSDeployScript(config) });
+  });
+
+  return router;
+}