@kmmao/happy-agent 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -18,7 +18,7 @@ var path = require('path');
 var fs = require('fs');
 var os = require('os');
 
-var version = "0.4.0";
+var version = "0.5.0";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://happyserve.xycloud.info").replace(/\/+$/, "");
@@ -1846,9 +1846,24 @@ function untrackSession(pid) {
   pidToSession.delete(pid);
   return session;
 }
+function getTrackedSession(pid) {
+  return pidToSession.get(pid);
+}
 function getAllTrackedSessions() {
   return [...pidToSession.values()];
 }
+function getTrackedSessionCount() {
+  return pidToSession.size;
+}
+
+var trackedSessions = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  getAllTrackedSessions: getAllTrackedSessions,
+  getTrackedSession: getTrackedSession,
+  getTrackedSessionCount: getTrackedSessionCount,
+  trackSession: trackSession,
+  untrackSession: untrackSession
+});
 
 const execFileAsync = util.promisify(child_process.execFile);
 const SERVER_INTERNAL_SECRETS = /* @__PURE__ */ new Set([
@@ -2010,11 +2025,11 @@ function stopSession(pid) {
   }
 }
 
-const PROMPT_DIR = path.join(os.tmpdir(), "happy", "agent-prompts");
+const PROMPT_DIR$1 = path.join(os.tmpdir(), "happy", "agent-prompts");
 async function writePromptFile(prefix, content) {
-  await promises.mkdir(PROMPT_DIR, { recursive: true });
+  await promises.mkdir(PROMPT_DIR$1, { recursive: true });
   const filename = `${prefix}-${Date.now()}.md`;
-  const filepath = path.join(PROMPT_DIR, filename);
+  const filepath = path.join(PROMPT_DIR$1, filename);
   await promises.writeFile(filepath, content, "utf-8");
   return filepath;
 }
@@ -2044,130 +2059,139 @@ function buildSupervisorPrompt(data) {
   if (data.customRules) parts.push("", "## Custom Rules", data.customRules);
   return parts.join("\n");
 }
-async function handleWebhookTrigger(data, client, serverUrl, authToken) {
+function mapTaskPriority(priority) {
+  if (priority === "urgent" || priority === "high") return "urgent";
+  if (priority === "background" || priority === "low") return "background";
+  return "user";
+}
+function handleWebhookTrigger(data, client, serverUrl, authToken, scheduler) {
   logger.debug(`[TRIGGER] Webhook: issue #${data.issueNumber} in ${data.repoPath}`);
-  client.emitWebhookStatus({
-    webhookEventId: data.webhookEventId,
-    status: "dispatched"
-  });
-  try {
-    const promptFile = await writePromptFile("webhook", buildWebhookPrompt(data));
-    const result = await spawnSession({
-      directory: data.repoPath,
-      approvedNewDirectoryCreation: false,
-      automationContext: {
-        kind: "webhook",
-        trigger: `issue#${data.issueNumber}`
-      },
-      environmentVariables: {
-        HAPPY_INITIAL_PROMPT_FILE: promptFile,
-        HAPPY_WEBHOOK_EVENT_ID: data.webhookEventId,
-        HAPPY_WEBHOOK_ISSUE_URL: data.issueUrl,
-        HAPPY_SERVER_URL: serverUrl,
-        HAPPY_AUTH_TOKEN: authToken
-      }
-    });
-    if (result.type === "success") {
-      logger.debug(`[TRIGGER] Webhook session spawned: PID ${result.pid}`);
-    } else {
-      logger.debug(`[TRIGGER] Webhook spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
-      client.emitWebhookStatus({
-        webhookEventId: data.webhookEventId,
-        status: "failed",
-        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+  const { deduped } = scheduler.enqueue({
+    kind: "webhook",
+    dedupeKey: `webhook:${data.webhookEventId}`,
+    priority: "background",
+    run: async (jobId) => {
+      client.emitWebhookStatus({ webhookEventId: data.webhookEventId, status: "dispatched" });
+      const promptFile = await writePromptFile("webhook", buildWebhookPrompt(data));
+      const result = await spawnSession({
+        directory: data.repoPath,
+        approvedNewDirectoryCreation: false,
+        automationContext: { kind: "webhook", trigger: `issue#${data.issueNumber}` },
+        environmentVariables: {
+          HAPPY_INITIAL_PROMPT_FILE: promptFile,
+          HAPPY_WEBHOOK_EVENT_ID: data.webhookEventId,
+          HAPPY_WEBHOOK_ISSUE_URL: data.issueUrl,
+          HAPPY_SERVER_URL: serverUrl,
+          HAPPY_AUTH_TOKEN: authToken
+        }
       });
+      if (result.type !== "success") {
+        const msg = result.type === "error" ? result.errorMessage : "Directory creation not approved";
+        client.emitWebhookStatus({ webhookEventId: data.webhookEventId, status: "failed", errorMessage: msg });
+        throw new Error(msg);
+      }
+      const tracked = (await Promise.resolve().then(function () { return trackedSessions; })).getTrackedSession(result.pid);
+      if (tracked?.childProcess) {
+        tracked.childProcess.on("exit", (code) => {
+          if (code === 0) scheduler.markCompleted(jobId);
+          else scheduler.markFailed(jobId, `exit code ${code}`);
+          client.emitWebhookStatus({ webhookEventId: data.webhookEventId, status: code === 0 ? "completed" : "failed" });
+        });
+      }
+      return { pid: result.pid };
     }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    logger.debug(`[TRIGGER] Webhook error: ${msg}`);
-    client.emitWebhookStatus({
-      webhookEventId: data.webhookEventId,
-      status: "failed",
-      errorMessage: msg
-    });
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Webhook deduped: ${data.webhookEventId}`);
   }
 }
-async function handleSupervisorTrigger(data, client, serverUrl, authToken) {
+function handleSupervisorTrigger(data, client, serverUrl, authToken, scheduler) {
   logger.debug(`[TRIGGER] Supervisor: run ${data.runId} in ${data.repoPath}`);
-  client.emitSupervisorRunStatus({
-    runId: data.runId,
-    projectId: data.projectId,
-    status: "running"
-  });
-  try {
-    const promptFile = await writePromptFile("supervisor", buildSupervisorPrompt(data));
-    const result = await spawnSession({
-      directory: data.repoPath,
-      approvedNewDirectoryCreation: false,
-      automationContext: {
-        kind: "supervisor",
-        trigger: data.trigger,
-        projectId: data.projectId,
-        runId: data.runId
-      },
-      environmentVariables: {
-        HAPPY_INITIAL_PROMPT_FILE: promptFile,
-        HAPPY_SUPERVISOR_RUN_ID: data.runId,
-        HAPPY_SUPERVISOR_PROJECT_ID: data.projectId,
-        HAPPY_SUPERVISOR_SERVER_URL: serverUrl,
-        HAPPY_SUPERVISOR_AUTH_TOKEN: authToken
-      }
-    });
-    if (result.type !== "success") {
-      client.emitSupervisorRunStatus({
-        runId: data.runId,
-        projectId: data.projectId,
-        status: "failed",
-        errorMessage: result.type === "error" ? result.errorMessage : "Directory creation not approved"
+  const { deduped } = scheduler.enqueue({
+    kind: "supervisor",
+    dedupeKey: `supervisor:${data.runId}`,
+    priority: "background",
+    run: async (jobId) => {
+      client.emitSupervisorRunStatus({ runId: data.runId, projectId: data.projectId, status: "running" });
+      const promptFile = await writePromptFile("supervisor", buildSupervisorPrompt(data));
+      const result = await spawnSession({
+        directory: data.repoPath,
+        approvedNewDirectoryCreation: false,
+        automationContext: { kind: "supervisor", trigger: data.trigger, projectId: data.projectId, runId: data.runId },
+        environmentVariables: {
+          HAPPY_INITIAL_PROMPT_FILE: promptFile,
+          HAPPY_SUPERVISOR_RUN_ID: data.runId,
+          HAPPY_SUPERVISOR_PROJECT_ID: data.projectId,
+          HAPPY_SUPERVISOR_SERVER_URL: serverUrl,
+          HAPPY_SUPERVISOR_AUTH_TOKEN: authToken
+        }
       });
+      if (result.type !== "success") {
+        const msg = result.type === "error" ? result.errorMessage : "Directory creation not approved";
+        client.emitSupervisorRunStatus({ runId: data.runId, projectId: data.projectId, status: "failed", errorMessage: msg });
+        throw new Error(msg);
+      }
+      const tracked = (await Promise.resolve().then(function () { return trackedSessions; })).getTrackedSession(result.pid);
+      if (tracked?.childProcess) {
+        tracked.childProcess.on("exit", (code) => {
+          const status = code === 0 ? "completed" : "failed";
+          if (code === 0) scheduler.markCompleted(jobId);
+          else scheduler.markFailed(jobId, `exit code ${code}`);
+          client.emitSupervisorRunStatus({ runId: data.runId, projectId: data.projectId, status });
+        });
+      }
+      return { pid: result.pid };
     }
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    logger.debug(`[TRIGGER] Supervisor error: ${msg}`);
-    client.emitSupervisorRunStatus({
-      runId: data.runId,
-      projectId: data.projectId,
-      status: "failed",
-      errorMessage: msg
-    });
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Supervisor deduped: ${data.runId}`);
   }
 }
-async function handleTaskTrigger(data, serverUrl, _authToken) {
+function handleTaskTrigger(data, serverUrl, _authToken, scheduler) {
   logger.debug(`[TRIGGER] Task: ${data.taskId} in ${data.directory}`);
-  try {
-    const promptFile = await writePromptFile("task", data.prompt);
-    const skillEnv = {};
-    if (data.skillContents?.length) {
-      skillEnv.HAPPY_TASK_SKILL_COUNT = String(data.skillContents.length);
-      for (let i = 0; i < data.skillContents.length; i++) {
-        skillEnv[`HAPPY_TASK_SKILL_${i}_NAME`] = data.skillContents[i].name;
-        skillEnv[`HAPPY_TASK_SKILL_${i}_CONTENT`] = data.skillContents[i].content;
+  const { deduped } = scheduler.enqueue({
+    kind: "task",
+    dedupeKey: `task:${data.taskId}`,
+    priority: mapTaskPriority(data.priority),
+    run: async (jobId) => {
+      const promptFile = await writePromptFile("task", data.prompt);
+      const skillEnv = {};
+      if (data.skillContents?.length) {
+        skillEnv.HAPPY_TASK_SKILL_COUNT = String(data.skillContents.length);
+        for (let i = 0; i < data.skillContents.length; i++) {
+          skillEnv[`HAPPY_TASK_SKILL_${i}_NAME`] = data.skillContents[i].name;
+          skillEnv[`HAPPY_TASK_SKILL_${i}_CONTENT`] = data.skillContents[i].content;
+        }
       }
-    }
-    const result = await spawnSession({
-      directory: data.directory,
-      approvedNewDirectoryCreation: true,
-      // Tasks always auto-approve directory
-      automationContext: {
-        kind: "task",
-        trigger: "task-dispatch",
-        projectId: data.projectId
-      },
-      environmentVariables: {
-        HAPPY_INITIAL_PROMPT_FILE: promptFile,
-        HAPPY_TASK_ID: data.taskId,
-        HAPPY_TASK_PRIORITY: data.priority,
-        HAPPY_TASK_SERVER_URL: serverUrl,
-        HAPPY_TASK_RESULT_TOKEN: data.resultToken ?? "",
-        HAPPY_TASK_REPORT_URL: `${serverUrl}/v1/tasks/${data.taskId}/result`,
-        ...skillEnv
+      const result = await spawnSession({
+        directory: data.directory,
+        approvedNewDirectoryCreation: true,
+        automationContext: { kind: "task", trigger: "task-dispatch", projectId: data.projectId },
+        environmentVariables: {
+          HAPPY_INITIAL_PROMPT_FILE: promptFile,
+          HAPPY_TASK_ID: data.taskId,
+          HAPPY_TASK_PRIORITY: data.priority,
+          HAPPY_TASK_SERVER_URL: serverUrl,
+          HAPPY_TASK_RESULT_TOKEN: data.resultToken ?? "",
+          HAPPY_TASK_REPORT_URL: `${serverUrl}/v1/tasks/${data.taskId}/result`,
+          ...skillEnv
+        }
+      });
+      if (result.type !== "success") {
+        throw new Error(result.type === "error" ? result.errorMessage : "Directory creation not approved");
       }
-    });
-    if (result.type !== "success") {
-      logger.debug(`[TRIGGER] Task spawn failed: ${result.type === "error" ? result.errorMessage : "needs approval"}`);
+      const tracked = (await Promise.resolve().then(function () { return trackedSessions; })).getTrackedSession(result.pid);
+      if (tracked?.childProcess) {
+        tracked.childProcess.on("exit", (code) => {
+          if (code === 0) scheduler.markCompleted(jobId);
+          else scheduler.markFailed(jobId, `exit code ${code}`);
+        });
+      }
+      return { pid: result.pid };
     }
-  } catch (error) {
-    logger.debug(`[TRIGGER] Task error: ${error instanceof Error ? error.message : String(error)}`);
+  });
+  if (deduped) {
+    logger.debug(`[TRIGGER] Task deduped: ${data.taskId}`);
   }
 }
 
@@ -2188,6 +2212,9 @@ class MachineClient {
   automationEnabled = false;
   automationServerUrl = "";
   automationAuthToken = "";
+  scheduler = null;
+  loopCoordinator = null;
+  auditStore = null;
   constructor(opts) {
     this.token = opts.token;
     this.machine = opts.machine;
@@ -2229,6 +2256,34 @@ class MachineClient {
       return { sessions };
     });
   }
+  registerLoopHandlers() {
+    const coord = this.loopCoordinator;
+    this.rpcHandlerManager.registerHandler("create-loop", async (data) => {
+      const loop = coord.createLoop(data);
+      return { loop: { id: loop.id, name: loop.name, state: loop.state } };
+    });
+    this.rpcHandlerManager.registerHandler("list-loops", async () => {
+      return { loops: coord.listLoops() };
+    });
+    this.rpcHandlerManager.registerHandler("pause-loop", async (data) => {
+      return { success: coord.pauseLoop(data.loopId) };
+    });
+    this.rpcHandlerManager.registerHandler("resume-loop", async (data) => {
+      return { success: coord.resumeLoop(data.loopId) };
+    });
+    this.rpcHandlerManager.registerHandler("delete-loop", async (data) => {
+      return { success: coord.deleteLoop(data.loopId) };
+    });
+  }
+  registerAuditHandlers() {
+    const audit = this.auditStore;
+    this.rpcHandlerManager.registerHandler("query-audit-log", async (data) => {
+      return { events: audit.query(data) };
+    });
+    this.rpcHandlerManager.registerHandler("audit-summary", async () => {
+      return { summary: audit.summarize() };
+    });
+  }
   // -----------------------------------------------------------------------
   // Connection
   // -----------------------------------------------------------------------
@@ -2410,37 +2465,49 @@ class MachineClient {
    * Enable automation handling — agent will process webhook, supervisor,
    * and task triggers from the server by spawning Happy CLI sessions.
    */
-  enableAutomation(serverUrl, authToken) {
+  enableAutomation(serverUrl, authToken, scheduler, loopCoordinator, auditStore) {
     this.automationEnabled = true;
     this.automationServerUrl = serverUrl;
     this.automationAuthToken = authToken;
+    this.scheduler = scheduler;
+    this.loopCoordinator = loopCoordinator ?? null;
+    this.auditStore = auditStore ?? null;
+    if (this.loopCoordinator) {
+      this.registerLoopHandlers();
+    }
+    if (this.auditStore) {
+      this.registerAuditHandlers();
+    }
     logger.debug("[MACHINE] Automation enabled");
   }
   /** Internal dispatch for ephemeral events that need automation handling. */
   handleAutomationEvent(event) {
-    if (!this.automationEnabled) return;
+    if (!this.automationEnabled || !this.scheduler) return;
     switch (event.type) {
       case "webhook-trigger":
-        void handleWebhookTrigger(
+        handleWebhookTrigger(
           event,
           this,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
       case "supervisor-trigger":
-        void handleSupervisorTrigger(
+        handleSupervisorTrigger(
           event,
           this,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
       case "task-trigger":
-        void handleTaskTrigger(
+        handleTaskTrigger(
           event,
           this.automationServerUrl,
-          this.automationAuthToken
+          this.automationAuthToken,
+          this.scheduler
         );
         break;
     }
@@ -2520,6 +2587,544 @@ function tailscaleChanged(prev, next) {
   return prev.status !== next.status || prev.ipv4 !== next.ipv4 || prev.ipv6 !== next.ipv6 || prev.hostname !== next.hostname || JSON.stringify(prev.serves) !== JSON.stringify(next.serves);
 }
 
+const PRIORITY_ORDER = {
+  urgent: 0,
+  user: 1,
+  background: 2
+};
+const ACTIVE_STATUSES = /* @__PURE__ */ new Set(["queued", "dispatching", "running"]);
+class AutomationScheduler {
+  maxConcurrentJobs;
+  retryDelayMs;
+  defaultMaxAttempts;
+  maxRecentCompletions;
+  onAudit;
+  /** Active jobs indexed by id. */
+  jobs = /* @__PURE__ */ new Map();
+  /** dedupeKey → jobId for fast dedup lookups. */
+  dedupeIndex = /* @__PURE__ */ new Map();
+  /** Ring buffer for completed/failed jobs. */
+  recentCompletions = [];
+  pumpTimer = null;
+  pumping = false;
+  constructor(options) {
+    this.maxConcurrentJobs = options?.maxConcurrentJobs ?? 2;
+    this.retryDelayMs = options?.retryDelayMs ?? 5e3;
+    this.defaultMaxAttempts = options?.maxAttempts ?? 3;
+    this.maxRecentCompletions = options?.maxRecentCompletions ?? 50;
+    this.onAudit = options?.onAudit ?? null;
+    this.pumpTimer = setInterval(() => this.pump(), 1e3);
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  enqueue(opts) {
+    const existingId = this.dedupeIndex.get(opts.dedupeKey);
+    if (existingId) {
+      const existing = this.jobs.get(existingId);
+      if (existing && ACTIVE_STATUSES.has(existing.status)) {
+        logger.debug(`[SCHEDULER] Deduped: ${opts.dedupeKey} (job ${existingId} is ${existing.status})`);
+        return { job: existing, deduped: true };
+      }
+    }
+    const job = {
+      id: crypto.randomUUID(),
+      kind: opts.kind,
+      dedupeKey: opts.dedupeKey,
+      priority: opts.priority,
+      status: "queued",
+      attempt: 0,
+      maxAttempts: this.defaultMaxAttempts,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      nextRunAt: Date.now(),
+      run: opts.run
+    };
+    this.jobs.set(job.id, job);
+    this.dedupeIndex.set(job.dedupeKey, job.id);
+    logger.debug(`[SCHEDULER] Enqueued: ${job.kind} ${job.dedupeKey} (${job.priority}) id=${job.id}`);
+    this.onAudit?.({ kind: "job_enqueued", jobId: job.id, dedupeKey: job.dedupeKey, message: `${job.kind}:${job.priority}` });
+    this.pump();
+    return { job, deduped: false };
+  }
+  markCompleted(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job || job.status === "completed" || job.status === "failed") return;
+    job.status = "completed";
+    job.updatedAt = Date.now();
+    logger.debug(`[SCHEDULER] Completed: ${job.kind} ${job.dedupeKey} id=${jobId}`);
+    this.onAudit?.({ kind: "job_completed", jobId, dedupeKey: job.dedupeKey });
+    this.finalize(job);
+  }
+  markFailed(jobId, error) {
+    const job = this.jobs.get(jobId);
+    if (!job || job.status === "completed" || job.status === "failed") return;
+    job.errorMessage = error;
+    job.updatedAt = Date.now();
+    if (job.attempt < job.maxAttempts) {
+      job.status = "queued";
+      job.nextRunAt = Date.now() + job.attempt * this.retryDelayMs;
+      logger.debug(`[SCHEDULER] Retry queued: ${job.dedupeKey} attempt=${job.attempt}/${job.maxAttempts} nextRunAt=+${job.attempt * this.retryDelayMs}ms`);
+      this.onAudit?.({ kind: "job_retried", jobId, dedupeKey: job.dedupeKey, errorMessage: error, message: `attempt ${job.attempt}/${job.maxAttempts}` });
+      this.pump();
+      return;
+    }
+    job.status = "failed";
+    logger.debug(`[SCHEDULER] Failed (exhausted): ${job.kind} ${job.dedupeKey} id=${jobId}: ${error}`);
+    this.onAudit?.({ kind: "job_failed", jobId, dedupeKey: job.dedupeKey, errorMessage: error });
+    this.finalize(job);
+  }
+  getStatus() {
+    let queueLength = 0;
+    let runningCount = 0;
+    for (const job of this.jobs.values()) {
+      if (job.status === "queued") queueLength++;
+      else if (job.status === "dispatching" || job.status === "running") runningCount++;
+    }
+    return {
+      queueLength,
+      runningCount,
+      recentCompletions: [...this.recentCompletions]
+    };
+  }
+  shutdown() {
+    if (this.pumpTimer) {
+      clearInterval(this.pumpTimer);
+      this.pumpTimer = null;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  pump() {
+    if (this.pumping) return;
+    this.pumping = true;
+    try {
+      const now = Date.now();
+      let runningCount = 0;
+      for (const job of this.jobs.values()) {
+        if (job.status === "dispatching" || job.status === "running") runningCount++;
+      }
+      if (runningCount >= this.maxConcurrentJobs) return;
+      const ready = [];
+      for (const job of this.jobs.values()) {
+        if (job.status === "queued" && job.nextRunAt <= now) {
+          ready.push(job);
+        }
+      }
+      ready.sort((a, b) => {
+        const pDiff = PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority];
+        if (pDiff !== 0) return pDiff;
+        return a.createdAt - b.createdAt;
+      });
+      const slotsAvailable = this.maxConcurrentJobs - runningCount;
+      const toDispatch = ready.slice(0, slotsAvailable);
+      for (const job of toDispatch) {
+        this.dispatch(job);
+      }
+    } finally {
+      this.pumping = false;
+    }
+  }
+  dispatch(job) {
+    job.status = "dispatching";
+    job.attempt++;
+    job.updatedAt = Date.now();
+    logger.debug(`[SCHEDULER] Dispatching: ${job.kind} ${job.dedupeKey} attempt=${job.attempt}`);
+    this.onAudit?.({ kind: "job_dispatched", jobId: job.id, dedupeKey: job.dedupeKey, message: `attempt ${job.attempt}` });
+    job.run(job.id).then(({ pid }) => {
+      if (job.status === "dispatching") {
+        job.status = "running";
+        job.pid = pid;
+        job.updatedAt = Date.now();
+        logger.debug(`[SCHEDULER] Running: ${job.dedupeKey} pid=${pid}`);
+      }
+    }).catch((error) => {
+      const msg = error instanceof Error ? error.message : String(error);
+      logger.debug(`[SCHEDULER] Dispatch failed: ${job.dedupeKey}: ${msg}`);
+      if (job.status === "dispatching") {
+        this.markFailed(job.id, msg);
+      }
+    });
+  }
+  finalize(job) {
+    this.jobs.delete(job.id);
+    if (this.dedupeIndex.get(job.dedupeKey) === job.id) {
+      this.dedupeIndex.delete(job.dedupeKey);
+    }
+    this.recentCompletions.push({
+      id: job.id,
+      kind: job.kind,
+      dedupeKey: job.dedupeKey,
+      status: job.status,
+      completedAt: job.updatedAt,
+      errorMessage: job.errorMessage
+    });
+    while (this.recentCompletions.length > this.maxRecentCompletions) {
+      this.recentCompletions.shift();
+    }
+    this.pump();
+  }
+}
+
+const PROMPT_DIR = path.join(os.tmpdir(), "happy", "agent-loop-prompts");
+const DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
+const DEFAULT_MAX_ITERATIONS = 0;
+class AgentLoopCoordinator {
+  loops = /* @__PURE__ */ new Map();
+  scheduler;
+  serverUrl;
+  authToken;
+  guardian;
+  tickTimer = null;
+  constructor(scheduler, serverUrl, authToken, guardian) {
+    this.scheduler = scheduler;
+    this.serverUrl = serverUrl;
+    this.authToken = authToken;
+    this.guardian = guardian ?? null;
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  start() {
+    if (this.tickTimer) return;
+    this.tickTimer = setInterval(() => this.tick(), 1e3);
+    logger.debug("[LOOP] Coordinator started");
+  }
+  shutdown() {
+    if (this.tickTimer) {
+      clearInterval(this.tickTimer);
+      this.tickTimer = null;
+    }
+    logger.debug("[LOOP] Coordinator shutdown");
+  }
+  // -----------------------------------------------------------------------
+  // CRUD
+  // -----------------------------------------------------------------------
+  createLoop(input) {
+    const loop = {
+      id: crypto.randomUUID(),
+      name: input.name,
+      prompt: input.prompt,
+      directory: input.directory,
+      intervalMs: Math.max(input.intervalMs, 1e4),
+      // min 10s
+      createdAt: Date.now(),
+      state: "idle",
+      iteration: 0,
+      nextRunAt: Date.now() + Math.max(input.intervalMs, 1e4),
+      consecutiveFailures: 0,
+      maxConsecutiveFailures: input.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES,
+      maxIterations: input.maxIterations ?? DEFAULT_MAX_ITERATIONS
+    };
+    this.loops.set(loop.id, loop);
+    logger.debug(`[LOOP] Created: ${loop.name} (${loop.id}) interval=${loop.intervalMs}ms`);
+    return loop;
+  }
+  getLoop(id) {
+    return this.loops.get(id);
+  }
+  listLoops() {
+    return [...this.loops.values()].map((l) => ({
+      id: l.id,
+      name: l.name,
+      state: l.state,
+      iteration: l.iteration,
+      intervalMs: l.intervalMs,
+      nextRunAt: l.nextRunAt,
+      lastCompletedAt: l.lastCompletedAt
+    }));
+  }
+  pauseLoop(id) {
+    const loop = this.loops.get(id);
+    if (!loop || loop.state === "paused") return false;
+    loop.state = "paused";
+    logger.debug(`[LOOP] Paused: ${loop.name} (${id})`);
+    return true;
+  }
+  resumeLoop(id) {
+    const loop = this.loops.get(id);
+    if (!loop || loop.state !== "paused") return false;
+    loop.state = "idle";
+    loop.nextRunAt = Date.now() + loop.intervalMs;
+    loop.consecutiveFailures = 0;
+    loop.errorMessage = void 0;
+    logger.debug(`[LOOP] Resumed: ${loop.name} (${id})`);
+    return true;
+  }
+  deleteLoop(id) {
+    const deleted = this.loops.delete(id);
+    if (deleted) logger.debug(`[LOOP] Deleted: ${id}`);
+    return deleted;
+  }
+  // -----------------------------------------------------------------------
+  // Scheduler callback
+  // -----------------------------------------------------------------------
+  onJobTerminal(loopId, status, errorMessage) {
+    const loop = this.loops.get(loopId);
+    if (!loop) return;
+    loop.activeJobId = void 0;
+    loop.lastCompletedAt = Date.now();
+    if (status === "completed") {
+      loop.consecutiveFailures = 0;
+      loop.state = "idle";
+      loop.nextRunAt = Date.now() + loop.intervalMs;
+      logger.debug(`[LOOP] Iteration ${loop.iteration} completed: ${loop.name}`);
+    } else {
+      loop.consecutiveFailures++;
+      loop.errorMessage = errorMessage;
+      if (loop.consecutiveFailures >= loop.maxConsecutiveFailures) {
+        loop.state = "blocked";
+        logger.debug(`[LOOP] Blocked after ${loop.consecutiveFailures} failures: ${loop.name}`);
+      } else {
+        loop.state = "idle";
+        loop.nextRunAt = Date.now() + loop.intervalMs;
+        logger.debug(`[LOOP] Iteration ${loop.iteration} failed (${loop.consecutiveFailures}/${loop.maxConsecutiveFailures}): ${loop.name}`);
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Tick
+  // -----------------------------------------------------------------------
+  tick() {
+    const now = Date.now();
+    for (const loop of this.loops.values()) {
+      if (loop.state !== "idle") continue;
+      if (loop.nextRunAt > now) continue;
+      if (loop.maxIterations > 0 && loop.iteration >= loop.maxIterations) {
+        loop.state = "paused";
+        logger.debug(`[LOOP] Max iterations reached (${loop.maxIterations}): ${loop.name}`);
+        continue;
+      }
+      this.enqueueLoop(loop);
+    }
+  }
+  enqueueLoop(loop) {
+    loop.iteration++;
+    loop.state = "active";
+    loop.lastStartedAt = Date.now();
+    const iterationNum = loop.iteration;
+    const loopId = loop.id;
+    const coordinator = this;
+    const guardianSessionId = this.guardian?.resolve({ loopId: loop.id }) ?? void 0;
+    const { job, deduped } = this.scheduler.enqueue({
+      kind: "task",
+      dedupeKey: `agent-loop:${loop.id}:${loop.iteration}`,
+      priority: "background",
+      run: async (jobId) => {
+        const promptFile = await writeLoopPromptFile(loop.name, loop.prompt, iterationNum);
+        const result = await spawnSession({
+          directory: loop.directory,
+          approvedNewDirectoryCreation: false,
+          happySessionId: guardianSessionId,
+          automationContext: {
+            kind: "agent_loop",
+            trigger: `loop:${loop.name}:iteration-${iterationNum}`
+          },
+          environmentVariables: {
+            HAPPY_INITIAL_PROMPT_FILE: promptFile,
+            HAPPY_LOOP_ID: loopId,
+            HAPPY_LOOP_NAME: loop.name,
+            HAPPY_LOOP_ITERATION: String(iterationNum),
+            HAPPY_SERVER_URL: coordinator.serverUrl,
+            HAPPY_AUTH_TOKEN: coordinator.authToken
+          }
+        });
+        if (result.type !== "success") {
+          throw new Error(result.type === "error" ? result.errorMessage : "Directory not approved");
+        }
+        const tracked = (await Promise.resolve().then(function () { return trackedSessions; })).getTrackedSession(result.pid);
+        if (tracked?.childProcess) {
+          tracked.childProcess.on("exit", (code) => {
+            const status = code === 0 ? "completed" : "failed";
+            coordinator.onJobTerminal(loopId, status, code !== 0 ? `exit code ${code}` : void 0);
+            if (code === 0) coordinator.scheduler.markCompleted(jobId);
+            else coordinator.scheduler.markFailed(jobId, `exit code ${code}`);
+          });
+        }
+        return { pid: result.pid };
+      }
+    });
+    if (deduped) {
+      loop.iteration--;
+      loop.state = "idle";
+      logger.debug(`[LOOP] Enqueue deduped: ${loop.name} iteration ${iterationNum}`);
+    } else {
+      loop.activeJobId = job.id;
+      logger.debug(`[LOOP] Enqueued: ${loop.name} iteration ${iterationNum} job=${job.id}`);
+    }
+  }
+}
+async function writeLoopPromptFile(name, prompt, iteration) {
+  await promises.mkdir(PROMPT_DIR, { recursive: true });
+  const filename = `loop-${name.replace(/[^a-zA-Z0-9-]/g, "_")}-${iteration}-${Date.now()}.md`;
+  const filepath = path.join(PROMPT_DIR, filename);
+  const content = [
+    `# Agent Loop: ${name}`,
+    `Iteration: ${iteration}`,
+    "",
+    prompt
+  ].join("\n");
+  await promises.writeFile(filepath, content, "utf-8");
+  return filepath;
+}
+
+class GuardianSessionRegistry {
+  entries = /* @__PURE__ */ new Map();
+  /**
+   * Find an existing session to reuse.
+   * Tries loop key first, then project key.
+   */
+  resolve(input) {
+    if (input.loopId) {
+      const entry = this.entries.get(`loop:${input.loopId}`);
+      if (entry) {
+        logger.debug(`[GUARDIAN] Resolved session ${entry.sessionId} for loop:${input.loopId}`);
+        return entry.sessionId;
+      }
+    }
+    if (input.projectId) {
+      const entry = this.entries.get(`project:${input.projectId}`);
+      if (entry) {
+        logger.debug(`[GUARDIAN] Resolved session ${entry.sessionId} for project:${input.projectId}`);
+        return entry.sessionId;
+      }
+    }
+    return null;
+  }
+  /**
+   * Remember a session for future reuse.
+   * Stores under both loop and project keys if available.
+   */
+  remember(sessionId, input) {
+    const now = Date.now();
+    if (input.loopId) {
+      const key = `loop:${input.loopId}`;
+      this.entries.set(key, {
+        key,
+        sessionId,
+        loopId: input.loopId,
+        projectId: input.projectId,
+        updatedAt: now
+      });
+      logger.debug(`[GUARDIAN] Remembered ${sessionId} for ${key}`);
+    }
+    if (input.projectId) {
+      const key = `project:${input.projectId}`;
+      if (!this.entries.has(key)) {
+        this.entries.set(key, {
+          key,
+          sessionId,
+          projectId: input.projectId,
+          updatedAt: now
+        });
+        logger.debug(`[GUARDIAN] Remembered ${sessionId} for ${key}`);
+      }
+    }
+  }
+  /**
+   * Forget a specific session (e.g., after it exits).
+   */
+  forgetSession(sessionId) {
+    let removed = 0;
+    for (const [key, entry] of this.entries) {
+      if (entry.sessionId === sessionId) {
+        this.entries.delete(key);
+        removed++;
+      }
+    }
+    if (removed > 0) {
+      logger.debug(`[GUARDIAN] Forgot session ${sessionId} (${removed} entries)`);
+    }
+    return removed;
+  }
+  /**
+   * Forget all entries for a loop.
+   */
+  forgetLoop(loopId) {
+    return this.entries.delete(`loop:${loopId}`);
+  }
+  /**
+   * Get all entries (for observability).
+   */
+  getSnapshot() {
+    return [...this.entries.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+  }
+  /**
+   * Number of tracked guardian entries.
+   */
+  get size() {
+    return this.entries.size;
+  }
+}
+
+class AutomationAuditStore {
+  maxEntries;
+  events = [];
+  nextId = 1;
+  constructor(options) {
+    this.maxEntries = options?.maxEntries ?? 500;
+  }
+  /**
+   * Record an audit event.
+   */
+  record(event) {
+    const entry = {
+      ...event,
+      id: this.nextId++,
+      timestamp: Date.now()
+    };
+    this.events.push(entry);
+    while (this.events.length > this.maxEntries) {
+      this.events.shift();
+    }
+    logger.debug(`[AUDIT] ${entry.kind}: ${entry.message ?? entry.dedupeKey ?? entry.jobId ?? ""}`);
+    return entry;
+  }
+  /**
+   * Query events with optional filters.
+   */
+  query(filter) {
+    const limit = filter?.limit ?? 50;
+    let results = this.events;
+    if (filter?.kind) {
+      results = results.filter((e) => e.kind === filter.kind);
+    }
+    if (filter?.loopId) {
+      results = results.filter((e) => e.loopId === filter.loopId);
+    }
+    if (filter?.since) {
+      results = results.filter((e) => e.timestamp >= filter.since);
+    }
+    return results.slice(-limit).reverse();
+  }
+  /**
+   * Summary counts by kind.
+   */
+  summarize() {
+    const counts = {
+      job_enqueued: 0,
+      job_dispatched: 0,
+      job_completed: 0,
+      job_failed: 0,
+      job_retried: 0,
+      loop_started: 0,
+      loop_blocked: 0,
+      loop_paused: 0
+    };
+    for (const event of this.events) {
+      counts[event.kind]++;
+    }
+    return counts;
+  }
+  /**
+   * Total number of stored events.
+   */
+  get size() {
+    return this.events.length;
+  }
+}
+
 function pidFilePath(homeDir) {
   return node_path.join(homeDir, "agent-daemon.pid");
 }
@@ -2587,8 +3192,16 @@ async function startDaemon(options) {
     agentVersion: version,
     workingDirectory: workDir
   });
+  const auditStore = new AutomationAuditStore();
+  const scheduler = new AutomationScheduler({
+    maxConcurrentJobs: 2,
+    onAudit: (event) => auditStore.record(event)
+  });
+  const guardian = new GuardianSessionRegistry();
+  const loopCoordinator = new AgentLoopCoordinator(scheduler, config.serverUrl, creds.token, guardian);
   client.setTailscaleInfo(fullTailscale);
-  client.enableAutomation(config.serverUrl, creds.token);
+  client.enableAutomation(config.serverUrl, creds.token, scheduler, loopCoordinator, auditStore);
+  loopCoordinator.start();
   client.connect();
   writePidFile(config.homeDir, process.pid);
   console.log(`Daemon started (PID ${process.pid})`);
@@ -2599,6 +3212,8 @@ async function startDaemon(options) {
     logger.debug(`[DAEMON] Received ${signal}, shutting down...`);
     console.log(`
 Received ${signal}, shutting down...`);
+    loopCoordinator.shutdown();
+    scheduler.shutdown();
     client.shutdown();
     removePidFile(config.homeDir);
     process.exit(0);