@agenticmail/enterprise 0.5.136 → 0.5.138

package/dist/chunk-DNYMU2RT.js

@@ -0,0 +1,1912 @@
+import {
+  withRetry
+} from "./chunk-JLSQOQ5L.js";
+import {
+  PermissionEngine
+} from "./chunk-T6FM7KNN.js";
+
+// src/engine/agent-config.ts
+var AgentConfigGenerator = class _AgentConfigGenerator {
+  /**
+   * Generate the complete workspace files for an agent
+   */
+  generateWorkspace(config) {
+    return {
+      "SOUL.md": this.generateSoul(config),
+      "USER.md": this.generateUser(config),
+      "AGENTS.md": this.generateAgents(config),
+      "IDENTITY.md": this.generateIdentity(config),
+      "HEARTBEAT.md": this.generateHeartbeat(config),
+      "TOOLS.md": this.generateTools(config),
+      "MEMORY.md": `# MEMORY.md \u2014 ${config.displayName}'s Long-Term Memory
+
+_Created ${(/* @__PURE__ */ new Date()).toISOString()}_
+`
+    };
+  }
+  /**
+   * Generate the gateway config for this agent
+   */
+  generateGatewayConfig(config) {
+    const channels = {};
+    for (const ch of config.channels?.enabled || []) {
+      if (!ch.enabled) continue;
+      channels[ch.type] = ch.config;
+    }
+    return {
+      model: `${config.model.provider}/${config.model.modelId}`,
+      thinking: config.model.thinkingLevel,
+      temperature: config.model.temperature,
+      maxTokens: config.model.maxTokens,
+      channels,
+      heartbeat: config.heartbeat?.enabled ? {
+        intervalMinutes: config.heartbeat.intervalMinutes
+      } : void 0,
+      workspace: config.workspace?.workingDirectory
+    };
+  }
+  /**
+   * Generate a docker-compose.yml for this agent
+   */
+  generateDockerCompose(config) {
+    const dc = config.deployment.config.docker;
+    if (!dc) throw new Error("No Docker config");
+    const env = { ...dc.env };
+    env["AGENTICMAIL_MODEL"] = `${config.model.provider}/${config.model.modelId}`;
+    env["AGENTICMAIL_THINKING"] = config.model.thinkingLevel;
+    if (config.email?.enabled && config.email.address) {
+      env["AGENTICMAIL_EMAIL"] = config.email.address;
+    }
+    const envLines = Object.entries(env).map(([k, v]) => `      ${k}: "${v}"`).join("\n");
+    const volumes = dc.volumes.map((v) => `      - ${v}`).join("\n");
+    const ports = dc.ports.map((p) => `      - "${p}:${p}"`).join("\n");
+    return `version: "3.8"
+
+services:
+  ${config.name}:
+    image: ${dc.image}:${dc.tag}
+    container_name: agenticmail-${config.name}
+    restart: ${dc.restart}
+    ports:
+${ports}
+    volumes:
+${volumes}
+    environment:
+${envLines}
+    deploy:
+      resources:
+        limits:
+          cpus: "${dc.resources.cpuLimit}"
+          memory: ${dc.resources.memoryLimit}
+${dc.network ? `    networks:
+      - ${dc.network}
+
+networks:
+  ${dc.network}:
+    external: true` : ""}
+`;
+  }
+  /**
+   * Generate a systemd service file for VPS deployment
+   */
+  generateSystemdUnit(config) {
+    const vps = config.deployment.config.vps;
+    if (!vps) throw new Error("No VPS config");
+    return `[Unit]
+Description=AgenticMail Agent: ${config.displayName}
+After=network.target
+
+[Service]
+Type=simple
+User=${vps.user}
+WorkingDirectory=${vps.installPath}
+ExecStart=/usr/bin/env node ${vps.installPath}/node_modules/.bin/agenticmail-enterprise start
+Restart=always
+RestartSec=10
+Environment=NODE_ENV=production
+Environment=AGENTICMAIL_MODEL=${config.model.provider}/${config.model.modelId}
+Environment=AGENTICMAIL_THINKING=${config.model.thinkingLevel}
+
+# Security hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=${vps.installPath}
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+`;
+  }
+  /**
+   * Generate a deployment script for VPS
+   */
+  generateVPSDeployScript(config) {
+    const vps = config.deployment.config.vps;
+    if (!vps) throw new Error("No VPS config");
+    return `#!/bin/bash
+set -euo pipefail
+
+# AgenticMail Agent Deployment Script
+# Agent: ${config.displayName}
+# Target: ${vps.host}
+
+echo "\u{1F680} Deploying ${config.displayName} to ${vps.host}..."
+
+INSTALL_PATH="${vps.installPath}"
+${vps.sudo ? 'SUDO="sudo"' : 'SUDO=""'}
+
+# 1. Install Node.js if needed
+if ! command -v node &> /dev/null; then
+  echo "\u{1F4E6} Installing Node.js..."
+  curl -fsSL https://deb.nodesource.com/setup_22.x | $SUDO bash -
+  $SUDO apt-get install -y nodejs
+fi
+
+# 2. Create workspace
+mkdir -p "$INSTALL_PATH/workspace"
+cd "$INSTALL_PATH"
+
+# 3. Install AgenticMail Enterprise
+echo "\u{1F4E6} Installing packages..."
+npm init -y 2>/dev/null || true
+npm install @agenticmail/enterprise @agenticmail/core agenticmail
+
+# 4. Write workspace files
+echo "\u{1F4DD} Writing agent configuration..."
+${Object.entries(this.generateWorkspace(config)).map(
+      ([file, content]) => `cat > "$INSTALL_PATH/workspace/${file}" << 'WORKSPACE_EOF'
+${content}
+WORKSPACE_EOF`
+    ).join("\n\n")}
+
+# 5. Write gateway config
+cat > "$INSTALL_PATH/config.yaml" << 'CONFIG_EOF'
+${JSON.stringify(this.generateGatewayConfig(config), null, 2)}
+CONFIG_EOF
+
+# 6. Install systemd service
+echo "\u2699\uFE0F Installing systemd service..."
+$SUDO tee /etc/systemd/system/agenticmail-${config.name}.service > /dev/null << 'SERVICE_EOF'
+${this.generateSystemdUnit(config)}
+SERVICE_EOF
+
+$SUDO systemctl daemon-reload
+$SUDO systemctl enable agenticmail-${config.name}
+$SUDO systemctl start agenticmail-${config.name}
+
+echo "\u2705 ${config.displayName} deployed and running!"
+echo "   Status: systemctl status agenticmail-${config.name}"
+echo "   Logs:   journalctl -u agenticmail-${config.name} -f"
+`;
+  }
+  // ─── Private Generators ─────────────────────────────
+  generateSoul(config) {
+    const id = config.identity;
+    if (id.personality && id.personality.length > 200) {
+      const personaBlock = this.buildPersonaBlock(config);
+      return personaBlock ? id.personality + "\n\n" + personaBlock : id.personality;
+    }
+    const toneMap = {
+      formal: "Be professional and precise. Use proper grammar. Avoid slang or casual language.",
+      casual: "Be relaxed and conversational. Use contractions. Feel free to be informal.",
+      professional: "Be competent and clear. Direct communication without being stiff.",
+      friendly: "Be warm and approachable. Show genuine interest. Use a positive tone.",
+      custom: id.customTone || ""
+    };
+    const personaSection = this.buildPersonaBlock(config);
+    return `# SOUL.md \u2014 Who You Are
+
+## Role
+You are **${config.displayName}**, a ${id.role}.
+
+## Communication Style
+${toneMap[id.tone] || toneMap["professional"]}
+
+## Language
+Primary language: ${id.language}
+${personaSection ? "\n" + personaSection + "\n" : ""}
+## Core Principles
+- Be genuinely helpful, not performatively helpful
+- Be resourceful \u2014 try to figure things out before asking
+- Earn trust through competence
+- Keep private information private
+
+## Boundaries
+- Never share confidential company information
+- Ask before taking irreversible actions
+- Stay within your assigned role and permissions
+`;
+  }
+  /** Calculate current age from a date-of-birth string */
+  static deriveAge(dateOfBirth) {
+    const dob = new Date(dateOfBirth);
+    const today = /* @__PURE__ */ new Date();
+    let age = today.getFullYear() - dob.getFullYear();
+    const monthDiff = today.getMonth() - dob.getMonth();
+    if (monthDiff < 0 || monthDiff === 0 && today.getDate() < dob.getDate()) age--;
+    return age;
+  }
+  buildPersonaBlock(config) {
+    const id = config.identity;
+    const lines = [];
+    const liveAge = id.dateOfBirth ? _AgentConfigGenerator.deriveAge(id.dateOfBirth) : id.age;
+    if (id.gender || liveAge || id.ageRange || id.maritalStatus || id.culturalBackground || id.traits) {
+      lines.push("## Persona");
+      lines.push(`Your name is **${config.displayName}**. This is your real identity \u2014 introduce yourself by this name and respond to it naturally. You embody the following personal characteristics. These are core to who you are \u2014 reflect them naturally in your communication style, references, perspectives, and behavior.
+`);
+    }
+    if (id.gender) {
+      const genderMap = {
+        male: "You present as male. Use he/him pronouns when referring to yourself in the third person.",
+        female: "You present as female. Use she/her pronouns when referring to yourself in the third person.",
+        "non-binary": "You present as non-binary. Use they/them pronouns when referring to yourself in the third person."
+      };
+      if (genderMap[id.gender]) lines.push(genderMap[id.gender]);
+    }
+    if (id.dateOfBirth) {
+      const dob = new Date(id.dateOfBirth);
+      const monthNames = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+      lines.push(`You were born on ${monthNames[dob.getMonth()]} ${dob.getDate()}, ${dob.getFullYear()}. You are currently ${liveAge} years old. This is your real birthday and age \u2014 let it naturally inform your frame of reference, cultural touchstones, energy level, and life experience.`);
+    } else if (liveAge) {
+      lines.push(`You are ${liveAge} years old. This is your actual age \u2014 let it naturally inform your frame of reference, cultural touchstones, energy level, and life experience that you draw from.`);
+    } else if (id.ageRange) {
+      const ageMap = {
+        young: "You are a young professional in your 20s-30s. You bring fresh perspectives, are comfortable with modern technology and trends, and communicate with energy and adaptability. Your references and examples tend to be contemporary.",
+        "mid-career": "You are a mid-career professional in your 30s-40s. You balance youthful energy with substantial experience. You have seen enough to know what works, and you bring both confidence and openness to your interactions.",
+        senior: "You are a senior veteran professional in your 50s+. You draw on decades of experience and wisdom. You communicate with gravitas, patience, and deep institutional knowledge. You mentor naturally and reference time-tested principles."
+      };
+      if (ageMap[id.ageRange]) lines.push(ageMap[id.ageRange]);
+    }
+    if (id.maritalStatus) {
+      const maritalMap = {
+        single: "You are single. This shapes your availability mindset \u2014 you are flexible with your time and can relate to independent lifestyles.",
+        married: "You are married. You understand partnership, compromise, and family-oriented priorities. You naturally reference teamwork and shared responsibility.",
+        divorced: "You have been through a divorce. This gives you resilience, empathy for difficult transitions, and a pragmatic outlook on change.",
+        widowed: "You are widowed. You carry deep empathy, emotional maturity, and an appreciation for what matters most.",
+        "in-a-relationship": "You are in a relationship. You bring warmth and relational awareness to your interactions."
+      };
+      if (maritalMap[id.maritalStatus]) lines.push(maritalMap[id.maritalStatus]);
+    }
+    if (id.culturalBackground) {
+      const cultureMap = {
+        "north-american": "Your cultural background is North American. You communicate directly, value efficiency and individual initiative, use informal greetings, and are comfortable with straightforward feedback.",
+        "british-european": "Your cultural background is British/European. You communicate with polite understatement, appreciate structured formality, use measured and precise language, and value diplomatic phrasing.",
+        "latin-american": "Your cultural background is Latin American. You communicate with warmth, prioritize building personal relationships before business, are expressive and personable, and value hospitality in interactions.",
+        "middle-eastern": "Your cultural background is Middle Eastern. You communicate with respect and hospitality, are context-aware in formality, value honor and trust-building, and show generous courtesy in your interactions.",
+        "east-asian": "Your cultural background is East Asian. You communicate with indirect harmony, show respect for hierarchy and seniority, exercise thoughtful precision in your words, and value group consensus over individual assertion.",
+        "south-asian": "Your cultural background is South Asian. You communicate with adaptable formality, are relationship-aware and respectful of elders and authority, blend traditional values with modern pragmatism, and show warmth through attentiveness.",
+        "southeast-asian": "Your cultural background is Southeast Asian. You communicate gently and diplomatically, seek consensus in group settings, show deference and politeness, and value harmony over confrontation.",
+        "african": "Your cultural background is African. You communicate with community orientation, warmth, and storytelling richness. You value collective wisdom, show respect for elders and tradition, and bring vibrant energy to interactions.",
+        "caribbean": "Your cultural background is Caribbean. You communicate with friendly warmth, approachable energy, and resilient optimism. You value community, bring vibrant personality to interactions, and balance professionalism with genuine connection.",
+        "australian-pacific": "Your cultural background is Australian/Pacific. You communicate casually and straightforwardly, value egalitarianism, use humor naturally, and keep interactions grounded and unpretentious."
+      };
+      if (cultureMap[id.culturalBackground]) lines.push(cultureMap[id.culturalBackground]);
+    }
+    if (id.traits) {
+      const traitLines = [];
+      if (id.traits.communication === "direct") traitLines.push("You are direct and straightforward \u2014 you say what you mean clearly without excessive hedging.");
+      if (id.traits.communication === "diplomatic") traitLines.push("You are diplomatic \u2014 you frame feedback constructively, soften disagreements, and prioritize preserving relationships.");
+      if (id.traits.detail === "big-picture") traitLines.push("You focus on the big picture \u2014 you lead with strategy, outcomes, and high-level thinking before diving into specifics.");
+      if (id.traits.detail === "detail-oriented") traitLines.push("You are detail-oriented \u2014 you are thorough, precise, and ensure nothing falls through the cracks.");
+      if (id.traits.energy === "enthusiastic") traitLines.push("You are enthusiastic \u2014 you bring visible energy, optimism, and momentum to every interaction.");
+      if (id.traits.energy === "calm") traitLines.push("You are calm and measured \u2014 you project steadiness, think before responding, and bring a grounding presence.");
+      if (id.traits.humor === "witty") traitLines.push("You have a witty sense of humor \u2014 you use clever wordplay, quick observations, and well-timed remarks to keep interactions engaging.");
+      if (id.traits.humor === "dry") traitLines.push("You have a dry sense of humor \u2014 you deliver deadpan observations and understated irony that reward attentive listeners.");
+      if (id.traits.humor === "warm") traitLines.push("You have a warm sense of humor \u2014 you use gentle, inclusive humor that puts people at ease and builds rapport.");
+      if (id.traits.humor === "none") traitLines.push("You keep things strictly professional \u2014 you avoid humor and focus entirely on substance and clarity.");
+      if (id.traits.formality === "formal") traitLines.push("You maintain a formal communication style \u2014 you use proper titles, structured language, and professional conventions.");
+      if (id.traits.formality === "casual") traitLines.push("You are casual and approachable \u2014 you use conversational language, contractions, and a friendly, relaxed tone.");
+      if (id.traits.formality === "adaptive") traitLines.push("You adapt your formality to context \u2014 you match the tone of whoever you are speaking with, formal when needed, relaxed when appropriate.");
+      if (id.traits.empathy === "high") traitLines.push("You are highly empathetic \u2014 you actively acknowledge emotions, validate feelings, and prioritize emotional connection alongside the task at hand.");
+      if (id.traits.empathy === "moderate") traitLines.push("You show moderate empathy \u2014 you are aware of and responsive to emotions without letting them overshadow practical outcomes.");
+      if (id.traits.empathy === "reserved") traitLines.push("You are emotionally reserved \u2014 you focus on facts and logic, offering support through competence rather than emotional expression.");
+      if (id.traits.patience === "patient") traitLines.push("You are exceptionally patient \u2014 you take time to explain, repeat when needed, and never rush or show frustration.");
+      if (id.traits.patience === "efficient") traitLines.push("You prioritize efficiency \u2014 you get to the point quickly, value brevity, and keep interactions focused and productive.");
+      if (id.traits.creativity === "creative") traitLines.push("You are creative and inventive \u2014 you suggest novel approaches, think outside the box, and bring fresh perspectives to problems.");
+      if (id.traits.creativity === "conventional") traitLines.push("You favor proven approaches \u2014 you rely on established best practices, standard methods, and time-tested solutions.");
+      if (traitLines.length) lines.push(traitLines.join(" "));
+    }
+    return lines.length > 1 ? lines.join("\n") : "";
+  }
+  generateUser(config) {
+    return config.context?.userInfo || `# USER.md \u2014 About Your Organization
+
+_Configure this from the admin dashboard._
+`;
+  }
+  generateAgents(config) {
+    const customInstructions = config.context?.customInstructions || "";
+    return `# AGENTS.md \u2014 Your Workspace
+
+## Every Session
+1. Read SOUL.md \u2014 this is who you are
+2. Read USER.md \u2014 this is who you're helping
+3. Check memory/ for recent context
+
+## Memory
+- Daily notes: memory/YYYY-MM-DD.md
+- Long-term: MEMORY.md
+
+## Safety
+- Don't exfiltrate private data
+- Don't run destructive commands without asking
+- When in doubt, ask
+
+${customInstructions}
+`;
+  }
+  generateIdentity(config) {
+    const id = config.identity;
+    const lines = [
+      "# IDENTITY.md\n",
+      `- **Name:** ${config.displayName}`,
+      `- **Role:** ${id.role}`,
+      `- **Tone:** ${id.tone}`,
+      `- **Language:** ${id.language || "en"}`
+    ];
+    if (id.gender) lines.push(`- **Gender:** ${id.gender}`);
+    if (id.dateOfBirth) {
+      const age = _AgentConfigGenerator.deriveAge(id.dateOfBirth);
+      lines.push(`- **Date of Birth:** ${id.dateOfBirth}`);
+      lines.push(`- **Age:** ${age}`);
+    } else if (id.age) {
+      lines.push(`- **Age:** ${id.age}`);
+    }
+    if (id.ageRange) lines.push(`- **Age Range:** ${{ young: "Young Professional (20s-30s)", "mid-career": "Mid-Career (30s-40s)", senior: "Senior / Veteran (50s+)" }[id.ageRange] || id.ageRange}`);
+    if (id.maritalStatus) lines.push(`- **Marital Status:** ${id.maritalStatus.replace(/-/g, " ")}`);
+    if (id.culturalBackground) lines.push(`- **Cultural Background:** ${id.culturalBackground.replace(/-/g, " ")}`);
+    if (id.traits) {
+      if (id.traits.communication) lines.push(`- **Communication Style:** ${id.traits.communication}`);
+      if (id.traits.detail) lines.push(`- **Focus:** ${id.traits.detail}`);
+      if (id.traits.energy) lines.push(`- **Energy:** ${id.traits.energy}`);
+      if (id.traits.humor) lines.push(`- **Humor:** ${id.traits.humor}`);
+      if (id.traits.formality) lines.push(`- **Formality:** ${id.traits.formality}`);
+      if (id.traits.empathy) lines.push(`- **Empathy:** ${id.traits.empathy}`);
+      if (id.traits.patience) lines.push(`- **Patience:** ${id.traits.patience}`);
+      if (id.traits.creativity) lines.push(`- **Creativity:** ${id.traits.creativity}`);
+    }
+    return lines.join("\n") + "\n";
+  }
+  generateHeartbeat(config) {
+    if (!config.heartbeat?.enabled) return "# HEARTBEAT.md\n# Heartbeat disabled\n";
+    const checks = (config.heartbeat.checks || []).map((c) => `- Check ${c}`).join("\n");
+    return `# HEARTBEAT.md
+
+## Periodic Checks
+${checks}
+
+## Schedule
+Check every ${config.heartbeat.intervalMinutes} minutes during active hours.
+`;
+  }
+  generateTools(config) {
+    return `# TOOLS.md \u2014 Local Notes
+
+_Add environment-specific notes here (camera names, SSH hosts, etc.)_
+`;
+  }
+};
+
+// src/engine/deployer.ts
+var DeploymentEngine = class {
+  configGen = new AgentConfigGenerator();
+  deployments = /* @__PURE__ */ new Map();
+  liveStatus = /* @__PURE__ */ new Map();
+  /**
+   * Deploy an agent to its configured target
+   */
+  async deploy(config, onEvent) {
+    const events = [];
+    const emit = (phase, status, message, details) => {
+      const event = { timestamp: (/* @__PURE__ */ new Date()).toISOString(), phase, status, message, details };
+      events.push(event);
+      onEvent?.(event);
+    };
+    try {
+      emit("validate", "started", "Validating agent configuration...");
+      this.validateConfig(config);
+      emit("validate", "completed", "Configuration valid");
+      let result;
+      switch (config.deployment.target) {
+        case "docker":
+          result = await this.deployDocker(config, emit);
+          break;
+        case "vps":
+          result = await this.deployVPS(config, emit);
+          break;
+        case "fly":
+          result = await this.deployFly(config, emit);
+          break;
+        case "railway":
+          result = await this.deployRailway(config, emit);
+          break;
+        case "local":
+          result = await this.deployLocal(config, emit);
+          break;
+        default:
+          throw new Error(`Unsupported deployment target: ${config.deployment.target}`);
+      }
+      result.events = events;
+      this.deployments.set(config.id, result);
+      return result;
+    } catch (error) {
+      emit("complete", "failed", `Deployment failed: ${error.message}`);
+      const result = { success: false, events, error: error.message };
+      this.deployments.set(config.id, result);
+      return result;
+    }
+  }
+  /**
+   * Stop a running agent
+   */
+  async stop(config) {
+    switch (config.deployment.target) {
+      case "docker":
+        return this.execCommand(`docker stop agenticmail-${config.name} && docker rm agenticmail-${config.name}`);
+      case "vps":
+        return this.execSSH(config, `sudo systemctl stop agenticmail-${config.name}`);
+      case "fly":
+        return this.flyMachineAction(config, "stop");
+      case "local":
+        return { success: true, message: "Local agent stopped" };
+      default:
+        return { success: false, message: `Cannot stop: unsupported target ${config.deployment.target}` };
+    }
+  }
+  /**
+   * Restart a running agent
+   */
+  async restart(config) {
+    switch (config.deployment.target) {
+      case "docker":
+        return this.execCommand(`docker restart agenticmail-${config.name}`);
+      case "vps":
+        return this.execSSH(config, `sudo systemctl restart agenticmail-${config.name}`);
+      case "fly":
+        return this.flyMachineAction(config, "restart");
+      case "local":
+        return { success: true, message: "Local agent restarted" };
+      default:
+        return { success: false, message: `Cannot restart: unsupported target ${config.deployment.target}` };
+    }
+  }
+  /**
+   * Get live status of a deployed agent
+   */
+  async getStatus(config) {
+    const base = {
+      agentId: config.id,
+      name: config.displayName,
+      status: "not-deployed",
+      healthStatus: "unknown"
+    };
+    try {
+      switch (config.deployment.target) {
+        case "docker":
+          return await this.getDockerStatus(config, base);
+        case "vps":
+          return await this.getVPSStatus(config, base);
+        case "fly":
+          return await this.getCloudStatus(config, base);
+        case "local":
+          return { ...base, status: "running", healthStatus: "healthy", uptime: Math.floor((Date.now() - new Date(config.deployment?.config?.deployedAt || Date.now()).getTime()) / 1e3) };
+        default:
+          return base;
+      }
+    } catch {
+      return { ...base, status: "error", healthStatus: "unhealthy" };
+    }
+  }
+  /**
+   * Stream logs from a deployed agent
+   */
+  async getLogs(config, lines = 100) {
+    switch (config.deployment.target) {
+      case "docker":
+        return (await this.execCommand(`docker logs --tail ${lines} agenticmail-${config.name}`)).message;
+      case "vps":
+        return (await this.execSSH(config, `journalctl -u agenticmail-${config.name} --no-pager -n ${lines}`)).message;
+      case "fly":
+        return `Logs available at: https://fly.io/apps/${config.deployment.config.cloud?.appName || "unknown"}/monitoring`;
+      default:
+        return "Log streaming not supported for this target";
+    }
+  }
+  /**
+   * Update a deployed agent's configuration without full redeployment
+   */
+  async updateConfig(config) {
+    const workspace = this.configGen.generateWorkspace(config);
+    const gatewayConfig = this.configGen.generateGatewayConfig(config);
+    switch (config.deployment.target) {
+      case "docker": {
+        for (const [file, content] of Object.entries(workspace)) {
+          const escaped = content.replace(/'/g, "'\\''");
+          await this.execCommand(`docker exec agenticmail-${config.name} sh -c 'echo "${Buffer.from(content).toString("base64")}" | base64 -d > /workspace/${file}'`);
+        }
+        await this.execCommand(`docker exec agenticmail-${config.name} agenticmail-enterprise restart`);
+        return { success: true, message: "Configuration updated and gateway restarted" };
+      }
+      case "vps": {
+        const vps = config.deployment.config.vps;
+        for (const [file, content] of Object.entries(workspace)) {
+          await this.execSSH(config, `cat > ${vps.installPath}/workspace/${file} << 'EOF'
+${content}
+EOF`);
+        }
+        await this.execSSH(config, `sudo systemctl restart agenticmail-${config.name}`);
+        return { success: true, message: "Configuration updated and service restarted" };
+      }
+      default:
+        return { success: false, message: "Hot config update not supported for this target" };
+    }
+  }
+  // ─── Docker Deployment ────────────────────────────────
+  async deployDocker(config, emit) {
+    const dc = config.deployment.config.docker;
+    if (!dc) throw new Error("Docker config missing");
+    emit("provision", "started", "Generating Docker configuration...");
+    const compose = this.configGen.generateDockerCompose(config);
+    emit("provision", "completed", "Docker Compose generated");
+    emit("configure", "started", "Generating agent workspace...");
+    const workspace = this.configGen.generateWorkspace(config);
+    emit("configure", "completed", `Generated ${Object.keys(workspace).length} workspace files`);
+    emit("install", "started", `Pulling image ${dc.image}:${dc.tag}...`);
+    await this.execCommand(`docker pull ${dc.image}:${dc.tag}`);
+    emit("install", "completed", "Image pulled");
+    emit("start", "started", "Starting container...");
+    const envArgs = Object.entries(dc.env).map(([k, v]) => `-e ${k}="${v}"`).join(" ");
+    const volumeArgs = dc.volumes.map((v) => `-v ${v}`).join(" ");
+    const portArgs = dc.ports.map((p) => `-p ${p}:${p}`).join(" ");
+    const runCmd = `docker run -d --name agenticmail-${config.name} --restart ${dc.restart} ${portArgs} ${volumeArgs} ${envArgs} ${dc.resources ? `--cpus="${dc.resources.cpuLimit}" --memory="${dc.resources.memoryLimit}"` : ""} ${dc.image}:${dc.tag}`;
+    const runResult = await this.execCommand(runCmd);
+    if (!runResult.success) {
+      throw new Error(`Container failed to start: ${runResult.message}`);
+    }
+    const containerId = runResult.message.trim().substring(0, 12);
+    emit("start", "completed", `Container ${containerId} running`);
+    emit("upload", "started", "Writing workspace files...");
+    for (const [file, content] of Object.entries(workspace)) {
+      await this.execCommand(`docker exec agenticmail-${config.name} sh -c 'echo "${Buffer.from(content).toString("base64")}" | base64 -d > /workspace/${file}'`);
+    }
+    emit("upload", "completed", "Workspace configured");
+    emit("healthcheck", "started", "Checking agent health...");
+    let healthy = false;
+    for (let i = 0; i < 10; i++) {
+      await new Promise((r) => setTimeout(r, 3e3));
+      const check = await this.execCommand(`docker exec agenticmail-${config.name} agenticmail-enterprise status 2>/dev/null || echo "not ready"`);
+      if (check.success && !check.message.includes("not ready")) {
+        healthy = true;
+        break;
+      }
+    }
+    if (healthy) {
+      emit("healthcheck", "completed", "Agent is healthy");
+      emit("complete", "completed", `Agent "${config.displayName}" deployed successfully`);
+    } else {
+      emit("healthcheck", "failed", "Agent did not become healthy within 30s");
+    }
+    return {
+      success: healthy,
+      containerId,
+      url: `http://localhost:${dc.ports[0]}`,
+      events: []
+    };
+  }
+  // ─── VPS Deployment ───────────────────────────────────
+  async deployVPS(config, emit) {
+    const vps = config.deployment.config.vps;
+    if (!vps) throw new Error("VPS config missing");
+    emit("provision", "started", `Connecting to ${vps.host}...`);
+    const script = this.configGen.generateVPSDeployScript(config);
+    emit("provision", "completed", "Deploy script generated");
+    emit("configure", "started", "Testing SSH connection...");
+    const sshTest = await this.execSSH(config, 'echo "ok"');
+    if (!sshTest.success) {
+      throw new Error(`SSH connection failed: ${sshTest.message}`);
+    }
+    emit("configure", "completed", "SSH connection verified");
+    emit("upload", "started", "Uploading deployment script...");
+    const scriptB64 = Buffer.from(script).toString("base64");
+    await this.execSSH(config, `echo "${scriptB64}" | base64 -d > /tmp/deploy-agenticmail.sh && chmod +x /tmp/deploy-agenticmail.sh`);
+    emit("upload", "completed", "Script uploaded");
+    emit("install", "started", "Running deployment (this may take a few minutes)...");
+    const deployResult = await this.execSSH(config, "bash /tmp/deploy-agenticmail.sh");
+    if (!deployResult.success) {
+      throw new Error(`Deployment script failed: ${deployResult.message}`);
+    }
+    emit("install", "completed", "Installation complete");
+    emit("healthcheck", "started", "Verifying service status...");
+    await new Promise((r) => setTimeout(r, 5e3));
+    const statusCheck = await this.execSSH(config, `systemctl is-active agenticmail-${config.name}`);
+    const isActive = statusCheck.success && statusCheck.message.trim() === "active";
+    if (isActive) {
+      emit("healthcheck", "completed", "Service is active");
+      emit("complete", "completed", `Agent deployed to ${vps.host}`);
+    } else {
+      emit("healthcheck", "failed", "Service not active");
+    }
+    return {
+      success: isActive,
+      sshCommand: `ssh ${vps.user}@${vps.host}${vps.port !== 22 ? ` -p ${vps.port}` : ""}`,
+      events: []
+    };
+  }
+  // ─── Fly.io Deployment ────────────────────────────────
+  /**
+   * Local/in-process deployment — agent runs within the same enterprise server.
+   * No container or VM needed. Just mark as running.
+   */
+  async deployLocal(config, emit) {
+    emit("provision", "started", "Preparing local agent runtime...");
+    emit("provision", "completed", "Local runtime ready");
+    emit("configure", "started", "Applying agent configuration...");
+    emit("configure", "completed", "Configuration applied");
+    emit("start", "started", "Starting agent...");
+    emit("start", "completed", "Agent started in local runtime");
+    emit("healthcheck", "started", "Running health check...");
+    emit("healthcheck", "completed", "Agent is healthy");
+    emit("complete", "completed", "Local deployment successful");
+    return {
+      success: true,
+      url: void 0,
+      events: []
+    };
+  }
+  /**
+   * Deploy agent to Fly.io using the Machines API (HTTP).
+   * No flyctl CLI needed — works from inside containers.
+   *
+   * Flow:
+   * 1. Create app (if it doesn't exist)
+   * 2. Create a Machine with the @agenticmail/enterprise Docker image
+   * 3. Set secrets (API keys, DB URL, etc.)
+   * 4. Wait for machine to start
+   */
+  async deployFly(config, emit) {
+    const cloud = config.deployment.config.cloud;
+    if (!cloud) throw new Error("Fly.io config missing");
+    const apiToken = cloud.apiToken;
+    if (!apiToken) throw new Error("Fly.io API token is required");
+    const appName = cloud.appName || config.deployment.config.flyAppName || `am-agent-${config.name.toLowerCase().replace(/[^a-z0-9-]/g, "-").slice(0, 30)}`;
+    const region = cloud.region || "iad";
+    const size = cloud.size || "shared-cpu-1x";
+    const FLY_API = "https://api.machines.dev/v1";
+    const authHeader = apiToken.startsWith("FlyV1 ") || apiToken.startsWith("fm2_") ? apiToken.startsWith("FlyV1 ") ? apiToken : `FlyV1 ${apiToken}` : `Bearer ${apiToken}`;
+    const flyFetch = async (path, method = "GET", body) => {
+      const res = await fetch(`${FLY_API}${path}`, {
+        method,
+        headers: {
+          "Authorization": authHeader,
+          "Content-Type": "application/json"
+        },
+        body: body ? JSON.stringify(body) : void 0
+      });
+      const text = await res.text();
+      let data;
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = { raw: text };
+      }
+      if (!res.ok) throw new Error(`Fly API ${method} ${path}: ${res.status} \u2014 ${data.error || text}`);
+      return data;
+    };
+    emit("provision", "started", `Creating Fly.io app "${appName}"...`);
+    try {
+      let flyOrg = cloud.org && cloud.org.length < 40 && /^[a-z0-9-]+$/.test(cloud.org) ? cloud.org : "";
+      if (!flyOrg) {
+        try {
+          const orgsRes = await flyFetch("/apps?org_slug=personal");
+          if (orgsRes?.apps?.length > 0 && orgsRes.apps[0].organization?.slug) {
+            flyOrg = orgsRes.apps[0].organization.slug;
+          }
+        } catch {
+        }
+        if (!flyOrg) flyOrg = "personal";
+      }
+      await flyFetch("/apps", "POST", {
+        app_name: appName,
+        org_slug: flyOrg
+      });
+      emit("provision", "completed", `App "${appName}" created`);
+    } catch (e) {
+      if (e.message.includes("already exists") || e.message.includes("already been taken")) {
+        emit("provision", "completed", `App "${appName}" already exists, reusing`);
+      } else {
+        throw e;
+      }
+    }
+    emit("configure", "started", "Preparing agent configuration...");
+    const env = {
+      NODE_ENV: "production",
+      AGENTICMAIL_AGENT_ID: config.id,
+      AGENTICMAIL_AGENT_NAME: config.displayName || config.name,
+      AGENTICMAIL_MODEL: `${config.model?.provider || "anthropic"}/${config.model?.modelId || "claude-sonnet-4-20250514"}`,
+      PORT: "3000"
+    };
+    if (config.model?.thinkingLevel) env.AGENTICMAIL_THINKING = config.model.thinkingLevel;
+    if (process.env.DATABASE_URL) env.DATABASE_URL = process.env.DATABASE_URL;
+    if (process.env.JWT_SECRET) env.JWT_SECRET = process.env.JWT_SECRET;
+    emit("configure", "completed", "Configuration ready");
+    emit("install", "started", "Deploying machine...");
+    const existingMachines = await flyFetch(`/apps/${appName}/machines`);
+    const machineConfig = {
+      image: "node:22-slim",
+      env,
+      services: [{
+        ports: [
+          { port: 443, handlers: ["tls", "http"] },
+          { port: 80, handlers: ["http"], force_https: true }
+        ],
+        protocol: "tcp",
+        internal_port: 3e3
+      }],
+      guest: {
+        cpu_kind: size.includes("performance") ? "performance" : "shared",
+        cpus: size.includes("2x") ? 2 : 1,
+        memory_mb: size.includes("2x") ? 1024 : 512
+      },
+      init: {
+        cmd: ["sh", "-c", "rm -rf /root/.npm && mkdir -p /tmp/agent && cd /tmp/agent && npm init -y > /dev/null 2>&1 && npm install --no-save @agenticmail/enterprise pg && npx @agenticmail/enterprise agent"]
+      },
+      auto_destroy: false,
+      restart: { policy: "always" }
+    };
+    let machineId;
+    const liveMachines = (existingMachines || []).filter((m) => m.state !== "destroyed");
+    if (liveMachines.length > 0) {
+      const existing = liveMachines[0];
+      machineId = existing.id;
+      emit("install", "started", `Reusing existing machine ${machineId} (state: ${existing.state})...`);
+      if (existing.state === "started" || existing.state === "running") {
+        try {
+          await flyFetch(`/apps/${appName}/machines/${machineId}/stop`, "POST");
+          await flyFetch(`/apps/${appName}/machines/${machineId}/wait?state=stopped&timeout=30`);
+        } catch {
+        }
+      }
+      await flyFetch(`/apps/${appName}/machines/${machineId}`, "POST", {
+        config: machineConfig,
+        region
+      });
+      emit("install", "completed", `Machine ${machineId} updated and restarting`);
+    } else {
+      const machine = await flyFetch(`/apps/${appName}/machines`, "POST", {
+        name: `agent-${config.name.toLowerCase().replace(/[^a-z0-9-]/g, "-").slice(0, 20)}`,
+        region,
+        config: machineConfig
+      });
+      machineId = machine.id;
+      emit("install", "completed", `Machine ${machineId} created in ${region}`);
+    }
+    emit("start", "started", "Waiting for machine to start...");
+    try {
+      await flyFetch(`/apps/${appName}/machines/${machineId}/wait?state=started&timeout=60`);
+      emit("start", "completed", "Machine is running");
+    } catch {
+      emit("start", "completed", "Machine starting (health check pending)");
+    }
+    config.deployment.config.cloud = {
+      ...cloud,
+      provider: "fly",
+      appName,
+      region,
+      size
+    };
+    config.deployment.config.flyAppName = appName;
+    config.deployment.config.flyMachineId = machineId;
+    config.deployment.config.deployedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const url = cloud.customDomain || `https://${appName}.fly.dev`;
+    emit("complete", "completed", `Agent live at ${url}`);
+    return {
+      success: true,
+      url,
+      appId: appName,
+      events: []
+    };
+  }
+  // ─── Railway Deployment ───────────────────────────────
+  async deployRailway(config, emit) {
+    const cloud = config.deployment.config.cloud;
+    if (!cloud || cloud.provider !== "railway") throw new Error("Railway config missing");
+    emit("provision", "started", "Creating Railway project...");
+    const appName = cloud.appName || `agenticmail-${config.name}`;
+    const result = await this.execCommand(`railway init --name ${appName}`, { RAILWAY_TOKEN: cloud.apiToken });
+    emit("provision", result.success ? "completed" : "failed", result.message);
+    return {
+      success: result.success,
+      url: `https://${appName}.up.railway.app`,
+      appId: appName,
+      events: []
+    };
+  }
+  // ─── Status Checkers ──────────────────────────────────
+  async getDockerStatus(config, base) {
+    const inspect = await this.execCommand(`docker inspect agenticmail-${config.name} --format '{{.State.Status}} {{.State.StartedAt}}'`);
+    if (!inspect.success) return { ...base, status: "not-deployed" };
+    const [status, startedAt] = inspect.message.trim().split(" ");
+    const running = status === "running";
+    const uptime = running ? Math.floor((Date.now() - new Date(startedAt).getTime()) / 1e3) : 0;
+    let metrics = void 0;
+    if (running) {
+      const stats = await this.execCommand(`docker stats agenticmail-${config.name} --no-stream --format '{{.CPUPerc}} {{.MemUsage}}'`);
+      if (stats.success) {
+        const parts = stats.message.trim().split(" ");
+        metrics = {
+          cpuPercent: parseFloat(parts[0]) || 0,
+          memoryMb: parseFloat(parts[1]) || 0,
+          toolCallsToday: 0,
+          activeSessionCount: 0,
+          errorRate: 0
+        };
+      }
+    }
+    return {
+      ...base,
+      status: running ? "running" : "stopped",
+      uptime,
+      healthStatus: running ? "healthy" : "unhealthy",
+      lastHealthCheck: (/* @__PURE__ */ new Date()).toISOString(),
+      metrics
+    };
+  }
+  async getVPSStatus(config, base) {
+    const result = await this.execSSH(config, `systemctl is-active agenticmail-${config.name}`);
+    const active = result.success && result.message.trim() === "active";
+    let uptime = 0;
+    if (active) {
+      const uptimeResult = await this.execSSH(config, `systemctl show agenticmail-${config.name} --property=ActiveEnterTimestamp --value`);
+      if (uptimeResult.success) {
+        uptime = Math.floor((Date.now() - new Date(uptimeResult.message.trim()).getTime()) / 1e3);
+      }
+    }
+    return {
+      ...base,
+      status: active ? "running" : "stopped",
+      uptime,
+      healthStatus: active ? "healthy" : "unhealthy",
+      lastHealthCheck: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  async getCloudStatus(config, base) {
+    const cloud = config.deployment.config.cloud;
+    if (!cloud || !cloud.apiToken) return base;
+    const appName = cloud.appName || `am-agent-${config.name.toLowerCase().replace(/[^a-z0-9-]/g, "-").slice(0, 30)}`;
+    const FLY_API = "https://api.machines.dev/v1";
+    const t = cloud.apiToken;
+    const auth = t.startsWith("FlyV1 ") ? t : t.startsWith("fm2_") ? `FlyV1 ${t}` : `Bearer ${t}`;
+    try {
+      const res = await fetch(`${FLY_API}/apps/${appName}/machines`, {
+        headers: { "Authorization": auth }
+      });
+      if (!res.ok) return { ...base, status: "error", healthStatus: "unhealthy" };
+      const machines = await res.json();
+      if (machines.length === 0) return { ...base, status: "stopped" };
+      const machine = machines[0];
+      const state = machine.state;
+      const isRunning = state === "started" || state === "replacing";
+      return {
+        ...base,
+        status: isRunning ? "running" : state === "stopped" ? "stopped" : "error",
+        healthStatus: isRunning ? "healthy" : "unhealthy",
+        endpoint: `https://${appName}.fly.dev`,
+        version: machine.image_ref?.tag,
+        uptime: machine.created_at ? Math.floor((Date.now() - new Date(machine.created_at).getTime()) / 1e3) : void 0
+      };
+    } catch {
+      return { ...base, status: "error", healthStatus: "unhealthy" };
+    }
+  }
+  // ─── Helpers ──────────────────────────────────────────
+  /** Stop or restart a Fly.io machine via the Machines API */
+  async flyMachineAction(config, action) {
+    const cloud = config.deployment.config.cloud;
+    if (!cloud || !cloud.apiToken) return { success: false, message: "Fly.io config missing" };
+    const appName = cloud.appName || `am-agent-${config.name.toLowerCase().replace(/[^a-z0-9-]/g, "-").slice(0, 30)}`;
+    const FLY_API = "https://api.machines.dev/v1";
+    const t = cloud.apiToken;
+    const auth = t.startsWith("FlyV1 ") ? t : t.startsWith("fm2_") ? `FlyV1 ${t}` : `Bearer ${t}`;
+    try {
+      const res = await fetch(`${FLY_API}/apps/${appName}/machines`, {
+        headers: { "Authorization": auth }
+      });
+      if (!res.ok) return { success: false, message: `Failed to list machines: ${res.status}` };
+      const machines = await res.json();
+      if (machines.length === 0) return { success: false, message: "No machines found" };
+      const machineId = machines[0].id;
+      const actionRes = await fetch(`${FLY_API}/apps/${appName}/machines/${machineId}/${action}`, {
+        method: "POST",
+        headers: { "Authorization": auth }
+      });
+      if (!actionRes.ok) {
+        const err = await actionRes.text();
+        return { success: false, message: `${action} failed: ${err}` };
+      }
+      return { success: true, message: `Machine ${machineId} ${action}ed` };
+    } catch (e) {
+      return { success: false, message: e.message };
+    }
+  }
+  validateConfig(config) {
+    if (!config.name) throw new Error("Agent name is required");
+    if (!config.identity.role) throw new Error("Agent role is required");
+    if (!config.model.modelId) throw new Error("Model ID is required");
+    if (!config.deployment.target) throw new Error("Deployment target is required");
+    switch (config.deployment.target) {
+      case "docker":
+        if (!config.deployment.config.docker) throw new Error("Docker configuration missing");
+        break;
+      case "vps":
+        if (!config.deployment.config.vps?.host) throw new Error("VPS host is required");
+        break;
+      case "fly":
+      case "railway":
+        if (!config.deployment.config.cloud?.apiToken) throw new Error("Cloud API token is required");
+        break;
+    }
+  }
+  generateDockerfile(config) {
+    return `FROM node:22-slim
+
+WORKDIR /app
+
+RUN npm install -g @agenticmail/enterprise @agenticmail/core agenticmail
+
+COPY workspace/ /workspace/
+
+ENV NODE_ENV=production
+ENV AGENTICMAIL_MODEL=${config.model.provider}/${config.model.modelId}
+ENV AGENTICMAIL_THINKING=${config.model.thinkingLevel}
+
+EXPOSE 3000
+
+CMD ["agenticmail-enterprise", "start"]
+`;
+  }
+  async execCommand(cmd, env) {
+    const { exec } = await import("child_process");
+    const { promisify } = await import("util");
+    const execAsync = promisify(exec);
+    try {
+      const { stdout, stderr } = await execAsync(cmd, {
+        timeout: 3e5,
+        // 5 min max
+        env: { ...process.env, ...env }
+      });
+      return { success: true, message: stdout || stderr };
+    } catch (error) {
+      return { success: false, message: error.stderr || error.message };
+    }
+  }
+  async execSSH(config, command) {
+    const vps = config.deployment.config.vps;
+    if (!vps) return { success: false, message: "No VPS config" };
+    const sshArgs = [
+      "-o StrictHostKeyChecking=no",
+      `-p ${vps.port || 22}`,
+      vps.sshKeyPath ? `-i ${vps.sshKeyPath}` : "",
+      `${vps.user}@${vps.host}`,
+      `"${command.replace(/"/g, '\\"')}"`
+    ].filter(Boolean).join(" ");
+    return this.execCommand(`ssh ${sshArgs}`);
+  }
+  async writeFile(path, content) {
+    const { writeFile } = await import("fs/promises");
+    const { dirname } = await import("path");
+    const { mkdir } = await import("fs/promises");
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf-8");
+  }
+};
+
+// src/engine/lifecycle.ts
+var AgentLifecycleManager = class {
+  agents = /* @__PURE__ */ new Map();
+  healthCheckIntervals = /* @__PURE__ */ new Map();
+  deployer = new DeploymentEngine();
+  configGen = new AgentConfigGenerator();
+  permissions;
+  engineDb;
+  eventListeners = [];
+  dirtyAgents = /* @__PURE__ */ new Set();
+  flushTimer = null;
+  /** Track which budget alert thresholds have already fired per agent per day to avoid duplicates */
+  firedAlerts = /* @__PURE__ */ new Map();
+  budgetAlerts = [];
+  birthdayTimer = null;
+  lastBirthdayCheck = "";
+  /** External callback for sending birthday messages (set via setBirthdaySender) */
+  birthdaySender = null;
+  /** Vault for decrypting deploy credentials */
+  vault;
+  constructor(opts) {
+    this.engineDb = opts?.db;
+    this.permissions = opts?.permissions || new PermissionEngine();
+  }
+  /**
+   * Set the database adapter and load existing agents from DB
+   */
+  async setDb(db) {
+    this.engineDb = db;
+    await this.loadFromDb();
+  }
+  setVault(vault) {
+    this.vault = vault;
+  }
+  /**
+   * Load all agents from DB into memory
+   */
+  async loadFromDb() {
+    if (!this.engineDb) return;
+    try {
+      const agents = await this.engineDb.getAllManagedAgents();
+      for (const agent of agents) {
+        this.agents.set(agent.id, agent);
+        if (agent.state === "running" || agent.state === "degraded") {
+          this.startHealthCheckLoop(agent);
+        }
+      }
+    } catch {
+    }
+  }
+  // ─── Agent CRUD ─────────────────────────────────────
+  /**
+   * Create a new managed agent (starts in 'draft' state)
+   */
+  async createAgent(orgId, config, createdBy) {
+    const agent = {
+      id: config.id || crypto.randomUUID(),
+      orgId,
+      config,
+      state: "draft",
+      stateHistory: [],
+      health: {
+        status: "unknown",
+        lastCheck: (/* @__PURE__ */ new Date()).toISOString(),
+        uptime: 0,
+        consecutiveFailures: 0,
+        checks: []
+      },
+      usage: this.emptyUsage(),
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      version: 1
+    };
+    this.agents.set(agent.id, agent);
+    await this.persistAgent(agent);
+    this.emitEvent(agent, "created", { createdBy });
+    return agent;
+  }
+  /**
+   * Update agent configuration (must be in draft, ready, stopped, or error state)
+   */
+  async updateConfig(agentId, updates, updatedBy) {
+    const agent = this.getAgent(agentId);
+    if (!agent) throw new Error(`Agent ${agentId} not found`);
+    const mutableStates = ["draft", "ready", "stopped", "error"];
+    if (!mutableStates.includes(agent.state)) {
+      throw new Error(`Cannot update config in state "${agent.state}". Stop the agent first.`);
+    }
+    const merged = { ...agent.config, ...updates, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    if (updates.identity && agent.config.identity) {
+      merged.identity = { ...agent.config.identity, ...updates.identity };
+    }
+    if (updates.model && agent.config.model) {
+      merged.model = { ...agent.config.model, ...updates.model };
+    }
+    if (updates.deployment && agent.config.deployment) {
+      merged.deployment = { ...agent.config.deployment, ...updates.deployment };
+    }
+    agent.config = merged;
+    agent.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    agent.version++;
+    if (agent.state === "draft" && this.isConfigComplete(agent.config)) {
+      this.transition(agent, "ready", "Configuration complete", updatedBy);
+    } else if (agent.state !== "draft") {
+      this.transition(agent, "ready", "Configuration updated", updatedBy);
+    }
+    await this.persistAgent(agent);
+    this.emitEvent(agent, "configured", { updatedBy, changes: Object.keys(updates) });
+    return agent;
+  }
+  /**
+   * Deploy an agent to its target environment
+   */
+  async deploy(agentId, deployedBy) {
+    const agent = this.getAgent(agentId);
+    if (!agent) throw new Error(`Agent ${agentId} not found`);
+    if (!["ready", "stopped", "error"].includes(agent.state)) {
+      throw new Error(`Cannot deploy from state "${agent.state}"`);
+    }
+    if (!this.isConfigComplete(agent.config)) {
+      throw new Error("Agent configuration is incomplete");
+    }
+    this.transition(agent, "provisioning", "Deployment initiated", deployedBy);
+    await this.persistAgent(agent);
+    try {
+      await this.resolveDeployCredentials(agent);
+      this.transition(agent, "deploying", "Pushing configuration", "system");
+      const result = await this.deployer.deploy(agent.config, (event) => {
+        this.emitEvent(agent, "deployed", { phase: event.phase, status: event.status, message: event.message });
+      });
+      if (result.success) {
+        this.transition(agent, "starting", "Deployment successful, agent starting", "system");
+        agent.lastDeployedAt = (/* @__PURE__ */ new Date()).toISOString();
+        const healthy = await this.waitForHealthy(agent, 6e4);
+        if (healthy) {
+          this.transition(agent, "running", "Agent is healthy and running", "system");
+          this.emitEvent(agent, "started", { deployedBy });
+          this.emitEvent(agent, "onboarding_required", { message: "Agent should complete onboarding: read org policies, acknowledge each, and internalize knowledge." });
+          this.startHealthCheckLoop(agent);
+        } else {
+          this.transition(agent, "degraded", "Agent started but health check failed", "system");
+          this.startHealthCheckLoop(agent);
+        }
+      } else {
+        this.transition(agent, "error", `Deployment failed: ${result.error}`, "system");
+      }
+      await this.persistAgent(agent);
+      return agent;
+    } catch (error) {
+      this.transition(agent, "error", `Deployment error: ${error.message}`, "system");
+      await this.persistAgent(agent);
+      throw error;
+    }
+  }
+  /**
+   * Stop a running agent
+   */
+  async stop(agentId, stoppedBy, reason) {
+    const agent = this.getAgent(agentId);
+    if (!agent) throw new Error(`Agent ${agentId} not found`);
+    if (!["running", "degraded", "starting", "error"].includes(agent.state)) {
+      throw new Error(`Cannot stop from state "${agent.state}"`);
+    }
+    this.stopHealthCheckLoop(agentId);
+    try {
+      await this.deployer.stop(agent.config);
+      this.transition(agent, "stopped", reason || "Stopped by user", stoppedBy);
+    } catch (error) {
+      this.transition(agent, "stopped", `Stopped with error: ${error.message}`, stoppedBy);
+    }
+    await this.persistAgent(agent);
+    this.emitEvent(agent, "stopped", { stoppedBy, reason });
+    return agent;
+  }
+  /**
+   * Restart a running agent
+   */
+  async restart(agentId, restartedBy) {
+    const agent = this.getAgent(agentId);
+    if (!agent) throw new Error(`Agent ${agentId} not found`);
+    this.transition(agent, "updating", "Restarting", restartedBy);
+    try {
+      await this.deployer.restart(agent.config);
+      const healthy = await this.waitForHealthy(agent, 3e4);
+      this.transition(agent, healthy ? "running" : "degraded", "Restarted", "system");
+    } catch (error) {
+      this.transition(agent, "error", `Restart failed: ${error.message}`, "system");
+    }
+    await this.persistAgent(agent);
+    this.emitEvent(agent, "restarted", { restartedBy });
+    return agent;
+  }
+  /**
+   * Hot-update config on a running agent (no full redeploy)
+   */
+  async hotUpdate(agentId, updates, updatedBy) {
+    const agent = this.getAgent(agentId);
+    if (!agent) throw new Error(`Agent ${agentId} not found`);
+    if (agent.state !== "running" && agent.state !== "degraded") {
+      throw new Error(`Hot update only works on running agents (current: "${agent.state}")`);
+    }
+    const prevState = agent.state;
+    this.transition(agent, "updating", "Hot config update", updatedBy);
+    const merged = { ...agent.config, ...updates, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    if (updates.identity && agent.config.identity) {
+      merged.identity = { ...agent.config.identity, ...updates.identity };
+    }
+    if (updates.model && agent.config.model) {
+      merged.model = { ...agent.config.model, ...updates.model };
+    }
+    if (updates.deployment && agent.config.deployment) {
+      merged.deployment = { ...agent.config.deployment, ...updates.deployment };
+    }
+    agent.config = merged;
+    agent.version++;
+    try {
+      await this.deployer.updateConfig(agent.config);
+      this.transition(agent, prevState, "Config updated successfully", "system");
+    } catch (error) {
+      this.transition(agent, "degraded", `Config update failed: ${error.message}`, "system");
+    }
+    await this.persistAgent(agent);
+    this.emitEvent(agent, "updated", { updatedBy, hotUpdate: true });
+    return agent;
+  }
+  /**
+   * Destroy an agent completely (stop + delete all resources)
+   */
+  async destroy(agentId, destroyedBy) {
+    const agent = this.getAgent(agentId);
+    if (!agent) throw new Error(`Agent ${agentId} not found`);
+    this.transition(agent, "destroying", "Agent being destroyed", destroyedBy);
+    this.stopHealthCheckLoop(agentId);
+    if (["running", "degraded", "starting"].includes(agent.state)) {
+      try {
+        await this.deployer.stop(agent.config);
+      } catch {
+      }
+    }
+    this.emitEvent(agent, "destroyed", { destroyedBy });
+    this.agents.delete(agentId);
+    try {
+      await this.engineDb?.deleteManagedAgent(agentId);
+    } catch (err) {
+      console.error(`[lifecycle] Failed to delete agent ${agentId} from DB:`, err);
+    }
+  }
+  // ─── Monitoring ─────────────────────────────────────
+  /**
+   * Record LLM usage (tokens + cost) from an agent session turn.
+   */
+  recordLLMUsage(agentId, opts) {
+    const agent = this.agents.get(agentId);
+    if (!agent) return;
+    const totalTokens = (opts.inputTokens || 0) + (opts.outputTokens || 0);
+    const usage = agent.usage;
+    if (totalTokens > 0) {
+      usage.tokensToday += totalTokens;
+      usage.tokensThisWeek += totalTokens;
+      usage.tokensThisMonth += totalTokens;
+      usage.tokensThisYear += totalTokens;
+    }
+    if (opts.costUsd) {
+      usage.costToday += opts.costUsd;
+      usage.costThisWeek += opts.costUsd;
+      usage.costThisMonth += opts.costUsd;
+      usage.costThisYear += opts.costUsd;
+    }
+    usage.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
+    this.dirtyAgents.add(agentId);
+    this.scheduleUsageFlush();
+    const budget = agent.budgetConfig;
+    if (budget) {
+      if (budget.dailyCostCap > 0 && usage.costToday >= budget.dailyCostCap) {
+        this.fireBudgetAlert(agent, "daily_exceeded", "cost", usage.costToday, budget.dailyCostCap);
+        this.stop(agentId, "system", "Daily cost budget exceeded").catch(() => {
+        });
+      }
+    }
+  }
+  /**
+   * Record a tool call for usage tracking with per-agent budget controls
+   */
+  recordToolCall(agentId, toolId, opts) {
+    const agent = this.agents.get(agentId);
+    if (!agent) return;
+    const usage = agent.usage;
+    usage.toolCallsToday++;
+    usage.toolCallsThisMonth++;
+    if (opts?.tokensUsed) {
+      usage.tokensToday += opts.tokensUsed;
+      usage.tokensThisWeek += opts.tokensUsed;
+      usage.tokensThisMonth += opts.tokensUsed;
+      usage.tokensThisYear += opts.tokensUsed;
+    }
+    if (opts?.costUsd) {
+      usage.costToday += opts.costUsd;
+      usage.costThisWeek += opts.costUsd;
+      usage.costThisMonth += opts.costUsd;
+      usage.costThisYear += opts.costUsd;
+    }
+    if (opts?.isExternalAction) {
+      usage.externalActionsToday++;
+      usage.externalActionsThisMonth++;
+    }
+    if (opts?.error) {
+      usage.errorsToday++;
+    }
+    usage.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
+    const budget = agent.budgetConfig;
+    if (budget) {
+      if (budget.dailyCostCap > 0 && usage.costToday >= budget.dailyCostCap) {
+        this.fireBudgetAlert(agent, "daily_exceeded", "cost", usage.costToday, budget.dailyCostCap);
+        this.stop(agentId, "system", "Daily cost budget exceeded").catch(() => {
+        });
+      }
+      if (budget.monthlyCostCap > 0 && usage.costThisMonth >= budget.monthlyCostCap) {
+        this.fireBudgetAlert(agent, "exceeded", "cost", usage.costThisMonth, budget.monthlyCostCap);
+        this.stop(agentId, "system", "Monthly cost budget exceeded").catch(() => {
+        });
+      }
+      if (budget.dailyTokenCap > 0 && usage.tokensToday >= budget.dailyTokenCap) {
+        this.fireBudgetAlert(agent, "daily_exceeded", "tokens", usage.tokensToday, budget.dailyTokenCap);
+        this.stop(agentId, "system", "Daily token budget exceeded").catch(() => {
+        });
+      }
+      if (budget.monthlyTokenCap > 0 && usage.tokensThisMonth >= budget.monthlyTokenCap) {
+        this.fireBudgetAlert(agent, "exceeded", "tokens", usage.tokensThisMonth, budget.monthlyTokenCap);
+        this.stop(agentId, "system", "Monthly token budget exceeded").catch(() => {
+        });
+      }
+      if (budget.weeklyCostCap > 0 && usage.costThisWeek >= budget.weeklyCostCap) {
+        this.fireBudgetAlert(agent, "weekly_exceeded", "cost", usage.costThisWeek, budget.weeklyCostCap);
+        this.stop(agentId, "system", "Weekly cost budget exceeded").catch(() => {
+        });
+      }
+      if (budget.weeklyTokenCap > 0 && usage.tokensThisWeek >= budget.weeklyTokenCap) {
+        this.fireBudgetAlert(agent, "weekly_exceeded", "tokens", usage.tokensThisWeek, budget.weeklyTokenCap);
+        this.stop(agentId, "system", "Weekly token budget exceeded").catch(() => {
+        });
+      }
+      if (budget.annualCostCap > 0 && usage.costThisYear >= budget.annualCostCap) {
+        this.fireBudgetAlert(agent, "annual_exceeded", "cost", usage.costThisYear, budget.annualCostCap);
+        this.stop(agentId, "system", "Annual cost budget exceeded").catch(() => {
+        });
+      }
+      if (budget.annualTokenCap > 0 && usage.tokensThisYear >= budget.annualTokenCap) {
+        this.fireBudgetAlert(agent, "annual_exceeded", "tokens", usage.tokensThisYear, budget.annualTokenCap);
+        this.stop(agentId, "system", "Annual token budget exceeded").catch(() => {
+        });
+      }
+      const thresholds = budget.warningThresholds || [50, 80, 95];
+      for (const pct of thresholds) {
+        if (budget.monthlyCostCap > 0) {
+          const ratio = usage.costThisMonth / budget.monthlyCostCap * 100;
+          if (ratio >= pct) {
+            this.fireBudgetAlert(agent, `warning_${pct}`, "cost", usage.costThisMonth, budget.monthlyCostCap);
+          }
+        }
+        if (budget.monthlyTokenCap > 0) {
+          const ratio = usage.tokensThisMonth / budget.monthlyTokenCap * 100;
+          if (ratio >= pct) {
+            this.fireBudgetAlert(agent, `warning_${pct}`, "tokens", usage.tokensThisMonth, budget.monthlyTokenCap);
+          }
+        }
+        if (budget.weeklyCostCap > 0) {
+          const ratio = usage.costThisWeek / budget.weeklyCostCap * 100;
+          if (ratio >= pct) {
+            this.fireBudgetAlert(agent, `weekly_warning_${pct}`, "cost", usage.costThisWeek, budget.weeklyCostCap);
+          }
+        }
+        if (budget.weeklyTokenCap > 0) {
+          const ratio = usage.tokensThisWeek / budget.weeklyTokenCap * 100;
+          if (ratio >= pct) {
+            this.fireBudgetAlert(agent, `weekly_warning_${pct}`, "tokens", usage.tokensThisWeek, budget.weeklyTokenCap);
+          }
+        }
+        if (budget.annualCostCap > 0) {
+          const ratio = usage.costThisYear / budget.annualCostCap * 100;
+          if (ratio >= pct) {
+            this.fireBudgetAlert(agent, `annual_warning_${pct}`, "cost", usage.costThisYear, budget.annualCostCap);
+          }
+        }
+        if (budget.annualTokenCap > 0) {
+          const ratio = usage.tokensThisYear / budget.annualTokenCap * 100;
+          if (ratio >= pct) {
+            this.fireBudgetAlert(agent, `annual_warning_${pct}`, "tokens", usage.tokensThisYear, budget.annualTokenCap);
+          }
+        }
+      }
+    } else {
+      if (usage.tokenBudgetMonthly > 0 && usage.tokensThisMonth >= usage.tokenBudgetMonthly) {
+        this.emitEvent(agent, "budget_exceeded", { type: "tokens", used: usage.tokensThisMonth, budget: usage.tokenBudgetMonthly });
+        this.stop(agentId, "system", "Monthly token budget exceeded").catch(() => {
+        });
+      } else if (usage.tokenBudgetMonthly > 0 && usage.tokensThisMonth >= usage.tokenBudgetMonthly * 0.8) {
+        this.emitEvent(agent, "budget_warning", { type: "tokens", used: usage.tokensThisMonth, budget: usage.tokenBudgetMonthly, percent: 80 });
+      }
+      if (usage.costBudgetMonthly > 0 && usage.costThisMonth >= usage.costBudgetMonthly) {
+        this.emitEvent(agent, "budget_exceeded", { type: "cost", used: usage.costThisMonth, budget: usage.costBudgetMonthly });
+        this.stop(agentId, "system", "Monthly cost budget exceeded").catch(() => {
+        });
+      }
+    }
+    this.emitEvent(agent, "tool_call", { toolId, ...opts });
+    this.dirtyAgents.add(agentId);
+    this.scheduleUsageFlush();
+  }
+  /**
+   * Get all agents for an org
+   */
+  getAgentsByOrg(orgId) {
+    return Array.from(this.agents.values()).filter((a) => a.orgId === orgId);
+  }
+  /**
+   * Get a single agent
+   */
+  getAgent(agentId) {
+    return this.agents.get(agentId);
+  }
+  /**
+   * Get org-wide usage summary
+   */
+  getOrgUsage(orgId) {
+    const agents = this.getAgentsByOrg(orgId);
+    return {
+      totalAgents: agents.length,
+      runningAgents: agents.filter((a) => a.state === "running").length,
+      totalTokensToday: agents.reduce((sum, a) => sum + a.usage.tokensToday, 0),
+      totalCostToday: agents.reduce((sum, a) => sum + a.usage.costToday, 0),
+      totalToolCallsToday: agents.reduce((sum, a) => sum + a.usage.toolCallsToday, 0),
+      totalErrorsToday: agents.reduce((sum, a) => sum + a.usage.errorsToday, 0),
+      agents: agents.map((a) => ({ id: a.id, name: a.config.displayName, state: a.state, usage: a.usage }))
+    };
+  }
+  /**
+   * Subscribe to lifecycle events (for dashboard real-time updates)
+   */
+  onEvent(listener) {
+    this.eventListeners.push(listener);
+    return () => {
+      this.eventListeners = this.eventListeners.filter((l) => l !== listener);
+    };
+  }
+  /**
+   * Reset daily counters (call at midnight via cron)
+   */
+  resetDailyCounters() {
+    for (const agent of this.agents.values()) {
+      agent.usage.tokensToday = 0;
+      agent.usage.toolCallsToday = 0;
+      agent.usage.externalActionsToday = 0;
+      agent.usage.costToday = 0;
+      agent.usage.errorsToday = 0;
+      agent.usage.totalSessionsToday = 0;
+      this.dirtyAgents.add(agent.id);
+    }
+    this.firedAlerts.clear();
+    this.scheduleUsageFlush();
+  }
+  /**
+   * Reset monthly counters (call on 1st of month)
+   */
+  resetMonthlyCounters() {
+    for (const agent of this.agents.values()) {
+      agent.usage.tokensThisMonth = 0;
+      agent.usage.toolCallsThisMonth = 0;
+      agent.usage.externalActionsThisMonth = 0;
+      agent.usage.costThisMonth = 0;
+      this.dirtyAgents.add(agent.id);
+    }
+    this.scheduleUsageFlush();
+  }
+  /**
+   * Reset weekly counters (call on Monday via workforce scheduler)
+   */
+  resetWeeklyCounters() {
+    for (const agent of this.agents.values()) {
+      agent.usage.tokensThisWeek = 0;
+      agent.usage.costThisWeek = 0;
+      this.dirtyAgents.add(agent.id);
+    }
+    this.scheduleUsageFlush();
+  }
+  /**
+   * Reset annual counters (call on Jan 1 via workforce scheduler)
+   */
+  resetAnnualCounters() {
+    for (const agent of this.agents.values()) {
+      agent.usage.tokensThisYear = 0;
+      agent.usage.costThisYear = 0;
+      this.dirtyAgents.add(agent.id);
+    }
+    this.scheduleUsageFlush();
+  }
+  // ─── Budget Management ─────────────────────────────────
+  /**
+   * Set per-agent budget configuration
+   */
+  async setBudgetConfig(agentId, config) {
+    const agent = this.agents.get(agentId);
+    if (!agent) throw new Error(`Agent ${agentId} not found`);
+    agent.budgetConfig = config;
+    if (!agent.config) agent.config = {};
+    agent.config.budgetConfig = config;
+    agent.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.persistAgent(agent);
+  }
+  /**
+   * Get per-agent budget configuration
+   */
+  getBudgetConfig(agentId) {
+    const agent = this.agents.get(agentId);
+    if (!agent) return void 0;
+    if (!agent.budgetConfig && agent.config?.budgetConfig) {
+      agent.budgetConfig = agent.config.budgetConfig;
+    }
+    return agent.budgetConfig;
+  }
+  /**
+   * Get budget alerts (optionally filtered)
+   */
+  getBudgetAlerts(opts) {
+    let alerts = [...this.budgetAlerts];
+    if (opts?.orgId) alerts = alerts.filter((a) => a.orgId === opts.orgId);
+    if (opts?.agentId) alerts = alerts.filter((a) => a.agentId === opts.agentId);
+    if (opts?.acknowledged !== void 0) alerts = alerts.filter((a) => a.acknowledged === opts.acknowledged);
+    return alerts.slice(0, opts?.limit || 100);
+  }
+  /**
+   * Acknowledge a budget alert
+   */
+  async acknowledgeBudgetAlert(alertId) {
+    const alert = this.budgetAlerts.find((a) => a.id === alertId);
+    if (alert) {
+      alert.acknowledged = true;
+      this.engineDb?.execute(
+        "UPDATE budget_alerts SET acknowledged = 1 WHERE id = ?",
+        [alertId]
+      ).catch((err) => {
+        console.error(`[lifecycle] Failed to acknowledge alert ${alertId}:`, err);
+      });
+    }
+  }
+  /**
+   * Get org-wide budget summary
+   */
+  getBudgetSummary(orgId) {
+    const agents = this.getAgentsByOrg(orgId);
+    return {
+      totalDailyCost: agents.reduce((s, a) => s + a.usage.costToday, 0),
+      totalWeeklyCost: agents.reduce((s, a) => s + a.usage.costThisWeek, 0),
+      totalMonthlyCost: agents.reduce((s, a) => s + a.usage.costThisMonth, 0),
+      totalAnnualCost: agents.reduce((s, a) => s + a.usage.costThisYear, 0),
+      totalDailyTokens: agents.reduce((s, a) => s + a.usage.tokensToday, 0),
+      totalWeeklyTokens: agents.reduce((s, a) => s + a.usage.tokensThisWeek, 0),
+      totalMonthlyTokens: agents.reduce((s, a) => s + a.usage.tokensThisMonth, 0),
+      totalAnnualTokens: agents.reduce((s, a) => s + a.usage.tokensThisYear, 0),
+      agentBudgets: agents.map((a) => ({
+        id: a.id,
+        name: a.config.displayName,
+        budget: a.budgetConfig,
+        usage: {
+          costToday: a.usage.costToday,
+          costThisWeek: a.usage.costThisWeek,
+          costThisMonth: a.usage.costThisMonth,
+          costThisYear: a.usage.costThisYear,
+          tokensToday: a.usage.tokensToday,
+          tokensThisWeek: a.usage.tokensThisWeek,
+          tokensThisMonth: a.usage.tokensThisMonth,
+          tokensThisYear: a.usage.tokensThisYear
+        }
+      })),
+      recentAlerts: this.budgetAlerts.filter((a) => a.orgId === orgId).slice(0, 20)
+    };
+  }
+  fireBudgetAlert(agent, alertType, budgetType, currentValue, limitValue) {
+    const key = `${agent.id}:${alertType}:${budgetType}`;
+    if (!this.firedAlerts.has(agent.id)) this.firedAlerts.set(agent.id, /* @__PURE__ */ new Set());
+    const fired = this.firedAlerts.get(agent.id);
+    if (fired.has(key)) return;
+    fired.add(key);
+    const alert = {
+      id: crypto.randomUUID(),
+      orgId: agent.orgId,
+      agentId: agent.id,
+      alertType,
+      budgetType,
+      currentValue,
+      limitValue,
+      acknowledged: false,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.budgetAlerts.push(alert);
+    if (this.budgetAlerts.length > 500) this.budgetAlerts = this.budgetAlerts.slice(-500);
+    this.engineDb?.execute(
+      "INSERT INTO budget_alerts (id, org_id, agent_id, alert_type, budget_type, current_value, limit_value, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+      [alert.id, alert.orgId, alert.agentId, alert.alertType, alert.budgetType, alert.currentValue, alert.limitValue, alert.createdAt]
+    ).catch((err) => {
+      console.error(`[lifecycle] Failed to persist budget alert:`, err);
+    });
+    const eventType = alertType.startsWith("warning") ? "budget_warning" : "budget_exceeded";
+    this.emitEvent(agent, eventType, { alertType, budgetType, currentValue, limitValue, percent: Math.round(currentValue / limitValue * 100) });
+  }
+  // ─── Health Check Loop ────────────────────────────────
+  startHealthCheckLoop(agent) {
+    this.stopHealthCheckLoop(agent.id);
+    const interval = setInterval(async () => {
+      try {
+        const status = await this.deployer.getStatus(agent.config);
+        agent.lastHealthCheckAt = (/* @__PURE__ */ new Date()).toISOString();
+        const check = {
+          name: "deployment_status",
+          status: status.status === "running" ? "pass" : "fail",
+          message: `Status: ${status.status}, Health: ${status.healthStatus}`,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          durationMs: 0
+        };
+        agent.health.checks = [check, ...agent.health.checks].slice(0, 10);
+        if (status.status === "running" && status.healthStatus === "healthy") {
+          agent.health.status = "healthy";
+          agent.health.consecutiveFailures = 0;
+          if (status.uptime) agent.health.uptime = status.uptime;
+          if (status.metrics) {
+            agent.usage.activeSessionCount = status.metrics.activeSessionCount;
+          }
+          if (agent.state === "degraded") {
+            this.transition(agent, "running", "Health restored", "system");
+            this.emitEvent(agent, "auto_recovered", {});
+          }
+        } else {
+          agent.health.consecutiveFailures++;
+          agent.health.status = agent.health.consecutiveFailures >= 3 ? "unhealthy" : "degraded";
+          if (agent.state === "running" && agent.health.consecutiveFailures >= 2) {
+            this.transition(agent, "degraded", `Health degraded: ${agent.health.consecutiveFailures} consecutive failures`, "system");
+          }
+          if (agent.health.consecutiveFailures >= 5 && agent.state !== "error") {
+            this.emitEvent(agent, "auto_recovered", { action: "restart", failures: agent.health.consecutiveFailures });
+            agent.health.consecutiveFailures = 0;
+            try {
+              await this.deployer.restart(agent.config);
+              this.transition(agent, "starting", "Auto-restarted after health failures", "system");
+            } catch {
+              this.transition(agent, "error", "Auto-restart failed", "system");
+            }
+          }
+        }
+        agent.health.lastCheck = (/* @__PURE__ */ new Date()).toISOString();
+        await this.persistAgent(agent);
+      } catch (error) {
+        agent.health.consecutiveFailures++;
+        agent.health.status = "unhealthy";
+      }
+    }, 3e4);
+    this.healthCheckIntervals.set(agent.id, interval);
+  }
+  stopHealthCheckLoop(agentId) {
+    const interval = this.healthCheckIntervals.get(agentId);
+    if (interval) {
+      clearInterval(interval);
+      this.healthCheckIntervals.delete(agentId);
+    }
+  }
+  // ─── Private Helpers ──────────────────────────────────
+  transition(agent, to, reason, triggeredBy) {
+    const from = agent.state;
+    const transition = {
+      from,
+      to,
+      reason,
+      triggeredBy,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    agent.stateHistory.push(transition);
+    if (agent.stateHistory.length > 50) agent.stateHistory = agent.stateHistory.slice(-50);
+    agent.state = to;
+    agent.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.engineDb?.addStateTransition(agent.id, transition).catch((err) => {
+      console.error(`[lifecycle] Failed to persist state transition for ${agent.id}:`, err);
+    });
+  }
+  /**
+   * Resolve org-level deploy credentials and merge into agent config.
+   * If the agent's deployment config is missing an API token, look up
+   * the org's deploy_credentials table for a matching target type.
+   * Also sanitizes app names to be valid for the target platform.
+   */
+  async resolveDeployCredentials(agent) {
+    const target = agent.config?.deployment?.target;
+    if (!target) return;
+    if (!agent.config.deployment.config) agent.config.deployment.config = {};
+    if (target === "fly" || target === "railway") {
+      if (!agent.config.deployment.config.cloud) agent.config.deployment.config.cloud = {};
+      const cloud = agent.config.deployment.config.cloud;
+      if (cloud.appName) {
+        cloud.appName = cloud.appName.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
+      }
+      if (!cloud.provider) cloud.provider = target;
+      if (cloud.apiToken) return;
+      if (this.engineDb) {
+        try {
+          const orgId = agent.orgId || "default";
+          const creds = await this.engineDb.getDeployCredentialsByType(orgId, target);
+          if (creds.length > 0) {
+            let credConfig = creds[0].config;
+            if (credConfig?._encrypted && this.vault) {
+              try {
+                credConfig = JSON.parse(this.vault.decrypt(credConfig._encrypted));
+              } catch (decErr) {
+                console.error("[lifecycle] Failed to decrypt deploy credential:", decErr);
+              }
+            }
+            if (credConfig?.apiToken || credConfig?.token) {
+              cloud.apiToken = credConfig.apiToken || credConfig.token;
+              if (credConfig.region && !cloud.region) cloud.region = credConfig.region;
+            }
+          }
+        } catch (err) {
+          console.error("[lifecycle] Failed to resolve deploy credentials:", err);
+        }
+      }
+    }
+  }
+  isConfigComplete(config) {
+    return !!(config.name && config.displayName && config.identity?.role && config.model?.modelId && config.deployment?.target && config.permissionProfileId);
+  }
+  async waitForHealthy(agent, timeoutMs) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const status = await this.deployer.getStatus(agent.config);
+        if (status.status === "running") return true;
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, 3e3));
+    }
+    return false;
+  }
+  /** Public persist — for use by routes that mutate agent config directly (e.g. email config) */
+  async saveAgent(agentId) {
+    const agent = this.agents.get(agentId);
+    if (agent) await this.persistAgent(agent);
+  }
+  async persistAgent(agent) {
+    if (!agent.name) agent.name = agent.id;
+    this.agents.set(agent.id, agent);
+    if (!this.engineDb) return;
+    try {
+      await withRetry(
+        () => this.engineDb.upsertManagedAgent(agent),
+        { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 2e3 }
+      );
+    } catch (err) {
+      console.error(`[lifecycle] Failed to persist agent ${agent.id}:`, err);
+    }
+  }
+  scheduleUsageFlush() {
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(async () => {
+      this.flushTimer = null;
+      const agentIds = [...this.dirtyAgents];
+      this.dirtyAgents.clear();
+      for (const id of agentIds) {
+        const agent = this.agents.get(id);
+        if (agent) {
+          await this.persistAgent(agent);
+        }
+      }
+    }, 5e3);
+  }
+  emitEvent(agent, type, data) {
+    const event = {
+      id: crypto.randomUUID(),
+      agentId: agent.id,
+      orgId: agent.orgId,
+      type,
+      data,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    for (const listener of this.eventListeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  emptyUsage() {
+    return {
+      tokensToday: 0,
+      tokensThisWeek: 0,
+      tokensThisMonth: 0,
+      tokensThisYear: 0,
+      tokenBudgetMonthly: 0,
+      toolCallsToday: 0,
+      toolCallsThisMonth: 0,
+      externalActionsToday: 0,
+      externalActionsThisMonth: 0,
+      costToday: 0,
+      costThisWeek: 0,
+      costThisMonth: 0,
+      costThisYear: 0,
+      costBudgetMonthly: 0,
+      activeSessionCount: 0,
+      totalSessionsToday: 0,
+      errorsToday: 0,
+      errorRate1h: 0,
+      lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  // ─── Birthday Automation ────────────────────────────
+  /**
+   * Register a callback to send birthday messages to agents.
+   * Called once during server startup with access to the communication bus.
+   */
+  setBirthdaySender(sender) {
+    this.birthdaySender = sender;
+  }
+  /**
+   * Start the daily birthday check loop.
+   * Runs every hour, but only triggers once per calendar day.
+   */
+  startBirthdayScheduler() {
+    this.checkBirthdays();
+    this.birthdayTimer = setInterval(() => this.checkBirthdays(), 60 * 60 * 1e3);
+  }
+  /**
+   * Check all agents for birthdays and send greetings.
+   * Only fires once per calendar day.
+   */
+  async checkBirthdays() {
+    const today = /* @__PURE__ */ new Date();
+    const dateKey = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, "0")}-${String(today.getDate()).padStart(2, "0")}`;
+    if (this.lastBirthdayCheck === dateKey) return;
+    this.lastBirthdayCheck = dateKey;
+    const todayMonth = today.getMonth() + 1;
+    const todayDay = today.getDate();
+    for (const agent of this.agents.values()) {
+      const dob = agent.config?.identity?.dateOfBirth;
+      if (!dob) continue;
+      const dobDate = new Date(dob);
+      if (dobDate.getMonth() + 1 === todayMonth && dobDate.getDate() === todayDay) {
+        const age = AgentConfigGenerator.deriveAge(dob);
+        this.emitEvent(agent, "birthday", { dateOfBirth: dob, age, name: agent.config.displayName });
+        if (this.birthdaySender) {
+          try {
+            await this.birthdaySender(agent);
+          } catch (err) {
+            console.error(`[lifecycle] Failed to send birthday message to ${agent.config.displayName}:`, err);
+          }
+        }
+      }
+    }
+  }
+  /** Get agents with upcoming birthdays (next N days) */
+  getUpcomingBirthdays(days = 30) {
+    const today = /* @__PURE__ */ new Date();
+    const results = [];
+    for (const agent of this.agents.values()) {
+      const dob = agent.config?.identity?.dateOfBirth;
+      if (!dob) continue;
+      const dobDate = new Date(dob);
+      const thisYearBday = new Date(today.getFullYear(), dobDate.getMonth(), dobDate.getDate());
+      if (thisYearBday < today) {
+        thisYearBday.setFullYear(today.getFullYear() + 1);
+      }
+      const diffMs = thisYearBday.getTime() - today.getTime();
+      const daysUntil = Math.ceil(diffMs / (1e3 * 60 * 60 * 24));
+      if (daysUntil <= days) {
+        results.push({
+          agent,
+          dateOfBirth: dob,
+          age: AgentConfigGenerator.deriveAge(dob) + (daysUntil > 0 ? 1 : 0),
+          daysUntil
+        });
+      }
+    }
+    return results.sort((a, b) => a.daysUntil - b.daysUntil);
+  }
+  /**
+   * Cleanup: stop all health check loops
+   */
+  shutdown() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.birthdayTimer) {
+      clearInterval(this.birthdayTimer);
+      this.birthdayTimer = null;
+    }
+    for (const id of this.dirtyAgents) {
+      const agent = this.agents.get(id);
+      if (agent) {
+        this.engineDb?.upsertManagedAgent(agent).catch(() => {
+        });
+      }
+    }
+    this.dirtyAgents.clear();
+    for (const [id] of this.healthCheckIntervals) {
+      this.stopHealthCheckLoop(id);
+    }
+  }
+};
+
+export {
+  AgentConfigGenerator,
+  DeploymentEngine,
+  AgentLifecycleManager
+};