@desplega.ai/agent-swarm 1.55.0 → 1.56.2

package/src/http/agents.ts

@@ -100,6 +100,7 @@ const updateAgentProfileRoute = route({
     identityMd: z.string().max(65536).optional(),
     setupScript: z.string().max(65536).optional(),
     toolsMd: z.string().max(65536).optional(),
+    heartbeatMd: z.string().max(65536).optional(),
     changeSource: z.string().optional(),
     changedByAgentId: z.string().optional(),
     changeReason: z.string().optional(),
@@ -283,11 +284,12 @@ export async function handleAgentsRest(
       body.soulMd === undefined &&
       body.identityMd === undefined &&
       body.setupScript === undefined &&
-      body.toolsMd === undefined
+      body.toolsMd === undefined &&
+      body.heartbeatMd === undefined
     ) {
       jsonError(
         res,
-        "At least one field (role, description, capabilities, claudeMd, soulMd, identityMd, setupScript, or toolsMd) must be provided",
+        "At least one field (role, description, capabilities, claudeMd, soulMd, identityMd, setupScript, toolsMd, or heartbeatMd) must be provided",
         400,
       );
       return true;
@@ -317,6 +319,7 @@ export async function handleAgentsRest(
         identityMd: body.identityMd,
         setupScript: body.setupScript,
         toolsMd: body.toolsMd,
+        heartbeatMd: body.heartbeatMd,
       },
       versionMeta,
     );

package/src/http/heartbeat.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { runHeartbeatSweep } from "../heartbeat/heartbeat";
+import { checkHeartbeatChecklist, runHeartbeatSweep } from "../heartbeat/heartbeat";
 import { route } from "./route-def";
 import { json } from "./utils";
 
@@ -18,6 +18,19 @@ const triggerSweep = route({
   auth: { apiKey: true },
 });
 
+const triggerChecklist = route({
+  method: "post",
+  path: "/api/heartbeat/checklist",
+  pattern: ["api", "heartbeat", "checklist"],
+  summary: "Trigger an immediate heartbeat checklist check",
+  tags: ["Heartbeat"],
+  responses: {
+    200: { description: "Checklist check completed successfully" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleHeartbeat(
@@ -39,5 +52,20 @@ export async function handleHeartbeat(
     return true;
   }
 
+  if (triggerChecklist.match(req.method, pathSegments)) {
+    const parsed = await triggerChecklist.parse(req, res, pathSegments, new URLSearchParams());
+    if (!parsed) return true;
+
+    try {
+      await checkHeartbeatChecklist();
+      json(res, { success: true, message: "Heartbeat checklist check completed" });
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : "Unknown error during heartbeat checklist check";
+      json(res, { success: false, error: message }, 500);
+    }
+    return true;
+  }
+
   return false;
 }

package/src/tests/heartbeat-checklist.test.ts

@@ -0,0 +1,417 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  closeDb,
+  createAgent,
+  createTaskExtended,
+  getDb,
+  initDb,
+  startTask,
+  updateAgentProfile,
+} from "../be/db";
+import {
+  checkHeartbeatChecklist,
+  createBootTriageTask,
+  gatherSystemStatus,
+  isEffectivelyEmpty,
+} from "../heartbeat/heartbeat";
+
+// Side-effect import: register heartbeat templates (also done by heartbeat.ts,
+// but other test files may call clearTemplateDefinitions() in parallel)
+import "../heartbeat/templates";
+
+const TEST_DB_PATH = "./test-heartbeat-checklist.sqlite";
+
+describe("Heartbeat Checklist", () => {
+  beforeAll(async () => {
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    await unlink(TEST_DB_PATH).catch(() => {});
+    await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+    await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+  });
+
+  beforeEach(async () => {
+    getDb().run("DELETE FROM agent_tasks");
+    getDb().run("DELETE FROM agents");
+    // Re-register heartbeat templates — other test files (prompt-template-resolver,
+    // prompt-template-session) call clearTemplateDefinitions() in parallel
+    await import(`../heartbeat/templates?t=${Date.now()}`);
+  });
+
+  // ==========================================================================
+  // isEffectivelyEmpty()
+  // ==========================================================================
+
+  describe("isEffectivelyEmpty", () => {
+    test("returns true for empty string", () => {
+      expect(isEffectivelyEmpty("")).toBe(true);
+    });
+
+    test("returns true for whitespace-only", () => {
+      expect(isEffectivelyEmpty("   \n  \n  ")).toBe(true);
+    });
+
+    test("returns true for headers-only", () => {
+      expect(isEffectivelyEmpty("# Title\n## Subtitle")).toBe(true);
+    });
+
+    test("returns true for HTML comments only", () => {
+      expect(isEffectivelyEmpty("<!-- comment -->")).toBe(true);
+    });
+
+    test("returns true for multi-line HTML comments", () => {
+      expect(isEffectivelyEmpty("<!-- start\nsome content\nend -->")).toBe(true);
+    });
+
+    test("returns true for mix of headers + comments + empty items", () => {
+      const content = `# Heartbeat Checklist
+
+<!-- Keep this section empty -->
+## Section
+
+- [ ]
+-
+<!-- Another comment -->`;
+      expect(isEffectivelyEmpty(content)).toBe(true);
+    });
+
+    test("returns true for the default lead template", () => {
+      const content = `# Heartbeat Checklist
+
+<!-- Keep this section empty to skip periodic heartbeat checks (no LLM cost). -->
+<!-- Add actionable items below when you want periodic checks. -->
+<!-- The lead agent reads this every 30 minutes and acts on any items found. -->
+
+<!-- Examples (uncomment to activate):
+- Check Slack for unaddressed requests older than 1 hour
+- Review active tasks for any that seem stuck or blocked
+- If idle workers exist and unassigned tasks are available, investigate why auto-assignment didn't handle them
+- Post a daily summary to #agent-status at 5pm
+-->`;
+      expect(isEffectivelyEmpty(content)).toBe(true);
+    });
+
+    test("returns false for content with real list items", () => {
+      expect(isEffectivelyEmpty("- Check Slack for messages")).toBe(false);
+    });
+
+    test("returns false for content with plain text paragraphs", () => {
+      expect(isEffectivelyEmpty("Review the task queue every hour")).toBe(false);
+    });
+
+    test("returns false for headers + real content", () => {
+      const content = `# Heartbeat Checklist
+- Check if any tasks are stuck`;
+      expect(isEffectivelyEmpty(content)).toBe(false);
+    });
+  });
+
+  // ==========================================================================
+  // gatherSystemStatus()
+  // ==========================================================================
+
+  describe("gatherSystemStatus", () => {
+    test("returns markdown string", () => {
+      const status = gatherSystemStatus();
+      expect(typeof status).toBe("string");
+      expect(status.length).toBeGreaterThan(0);
+    });
+
+    test("includes task stats section with [auto-generated] label", () => {
+      const status = gatherSystemStatus();
+      expect(status).toContain("## Task Overview [auto-generated]");
+    });
+
+    test("includes agent status section with [auto-generated] label", () => {
+      const status = gatherSystemStatus();
+      expect(status).toContain("## Agent Status [auto-generated]");
+    });
+
+    test("handles empty DB gracefully", () => {
+      const status = gatherSystemStatus();
+      expect(status).toContain("In Progress: 0");
+      expect(status).toContain("Offline: 0");
+    });
+
+    test("reflects actual task and agent counts", () => {
+      const agent = createAgent({ name: "test-worker", isLead: false, status: "busy" });
+      createTaskExtended("Test task 1", { agentId: agent.id });
+      createTaskExtended("Test task 2");
+
+      const status = gatherSystemStatus();
+      // One task assigned (pending), one unassigned
+      expect(status).toContain("Pending: 1");
+      expect(status).toContain("Unassigned: 1");
+      expect(status).toContain("1 busy");
+    });
+
+    test("shows stalled tasks section when stalled tasks exist", () => {
+      const agent = createAgent({ name: "stall-worker", isLead: false, status: "busy" });
+      const task = createTaskExtended("Stalled task", { agentId: agent.id });
+      startTask(task.id);
+
+      // Make task stale (45 min)
+      const oldTime = new Date(Date.now() - 45 * 60 * 1000).toISOString();
+      getDb().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [oldTime, task.id]);
+
+      const status = gatherSystemStatus();
+      expect(status).toContain("## Stalled Tasks [auto-generated]");
+    });
+  });
+
+  // ==========================================================================
+  // checkHeartbeatChecklist()
+  // ==========================================================================
+
+  describe("checkHeartbeatChecklist", () => {
+    test("skips when no lead agent registered", async () => {
+      createAgent({ name: "worker", isLead: false, status: "idle" });
+
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all();
+      expect(tasks.length).toBe(0);
+    });
+
+    test("skips when heartbeatMd is NULL", async () => {
+      createAgent({ name: "lead", isLead: true, status: "idle" });
+
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all();
+      expect(tasks.length).toBe(0);
+    });
+
+    test("skips when heartbeatMd is effectively empty (all comments/headers)", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "# Heartbeat Checklist\n\n<!-- No items yet -->\n",
+      });
+
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all();
+      expect(tasks.length).toBe(0);
+    });
+
+    test("creates task when heartbeatMd has real content", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "# Heartbeat Checklist\n\n- Check if any tasks are stuck\n",
+      });
+
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all() as Array<{ id: string; task: string; agentId: string; priority: number }>;
+      expect(tasks.length).toBe(1);
+      expect(tasks[0]!.agentId).toBe(lead.id);
+      expect(tasks[0]!.priority).toBe(60);
+    });
+
+    test("dedup: skips when active heartbeat-checklist task exists for lead", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "- Check tasks\n",
+      });
+
+      // First call — creates task
+      await checkHeartbeatChecklist();
+
+      // Second call — should skip (dedup)
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all();
+      expect(tasks.length).toBe(1);
+    });
+
+    test("created task includes system status with [auto-generated] labels", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "- Review stalled tasks\n",
+      });
+
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT task FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all() as Array<{ task: string }>;
+      expect(tasks.length).toBe(1);
+      expect(tasks[0]!.task).toContain("[auto-generated]");
+      expect(tasks[0]!.task).toContain("Task Overview");
+    });
+
+    test("created task includes HEARTBEAT.md content", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "- Check Slack for unaddressed requests\n- Review blocked tasks\n",
+      });
+
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT task FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all() as Array<{ task: string }>;
+      expect(tasks.length).toBe(1);
+      expect(tasks[0]!.task).toContain("Check Slack for unaddressed requests");
+      expect(tasks[0]!.task).toContain("Review blocked tasks");
+    });
+
+    test("created task has correct tags", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "- Check tasks\n",
+      });
+
+      await checkHeartbeatChecklist();
+
+      const tasks = getDb()
+        .query("SELECT tags FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all() as Array<{ tags: string }>;
+      expect(tasks.length).toBe(1);
+      const tags = JSON.parse(tasks[0]!.tags);
+      expect(tags).toContain("checklist");
+      expect(tags).toContain("auto-generated");
+      // Must NOT contain "heartbeat" tag (would be filtered by default listing)
+      expect(tags).not.toContain("heartbeat");
+    });
+  });
+
+  // ==========================================================================
+  // createBootTriageTask()
+  // ==========================================================================
+
+  describe("createBootTriageTask", () => {
+    test("skips when no lead agent registered", async () => {
+      createAgent({ name: "worker", isLead: false, status: "idle" });
+
+      await createBootTriageTask();
+
+      const tasks = getDb().query("SELECT * FROM agent_tasks WHERE taskType = 'boot-triage'").all();
+      expect(tasks.length).toBe(0);
+    });
+
+    test("creates boot-triage task for lead", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+
+      await createBootTriageTask();
+
+      const tasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'boot-triage'")
+        .all() as Array<{ id: string; agentId: string; priority: number; task: string }>;
+      expect(tasks.length).toBe(1);
+      expect(tasks[0]!.agentId).toBe(lead.id);
+      expect(tasks[0]!.priority).toBe(70);
+    });
+
+    test("boot-triage task includes reboot context", async () => {
+      createAgent({ name: "lead", isLead: true, status: "idle" });
+
+      await createBootTriageTask();
+
+      const tasks = getDb()
+        .query("SELECT task FROM agent_tasks WHERE taskType = 'boot-triage'")
+        .all() as Array<{ task: string }>;
+      expect(tasks.length).toBe(1);
+      expect(tasks[0]!.task).toContain("Boot Triage");
+      expect(tasks[0]!.task).toContain("just restarted");
+      expect(tasks[0]!.task).toContain("Boot Event");
+    });
+
+    test("boot-triage task includes system status", async () => {
+      createAgent({ name: "lead", isLead: true, status: "idle" });
+
+      await createBootTriageTask();
+
+      const tasks = getDb()
+        .query("SELECT task FROM agent_tasks WHERE taskType = 'boot-triage'")
+        .all() as Array<{ task: string }>;
+      expect(tasks[0]!.task).toContain("Task Overview [auto-generated]");
+      expect(tasks[0]!.task).toContain("Agent Status [auto-generated]");
+    });
+
+    test("shows fallback text when heartbeatMd is empty", async () => {
+      createAgent({ name: "lead", isLead: true, status: "idle" });
+
+      await createBootTriageTask();
+
+      const tasks = getDb()
+        .query("SELECT task FROM agent_tasks WHERE taskType = 'boot-triage'")
+        .all() as Array<{ task: string }>;
+      expect(tasks[0]!.task).toContain("No standing orders configured");
+    });
+
+    test("includes heartbeatMd content when available", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "- Check Slack for unaddressed requests\n",
+      });
+
+      await createBootTriageTask();
+
+      const tasks = getDb()
+        .query("SELECT task FROM agent_tasks WHERE taskType = 'boot-triage'")
+        .all() as Array<{ task: string }>;
+      expect(tasks[0]!.task).toContain("Check Slack for unaddressed requests");
+    });
+
+    test("dedup: skips when active boot-triage task exists", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "- Check tasks\n",
+      });
+
+      await createBootTriageTask();
+      await createBootTriageTask();
+
+      const tasks = getDb().query("SELECT * FROM agent_tasks WHERE taskType = 'boot-triage'").all();
+      expect(tasks.length).toBe(1);
+    });
+
+    test("boot-triage has correct tags", async () => {
+      createAgent({ name: "lead", isLead: true, status: "idle" });
+
+      await createBootTriageTask();
+
+      const tasks = getDb()
+        .query("SELECT tags FROM agent_tasks WHERE taskType = 'boot-triage'")
+        .all() as Array<{ tags: string }>;
+      const tags = JSON.parse(tasks[0]!.tags);
+      expect(tags).toContain("boot");
+      expect(tags).toContain("triage");
+      expect(tags).toContain("auto-generated");
+    });
+
+    test("boot-triage and heartbeat-checklist are independent (different taskTypes)", async () => {
+      const lead = createAgent({ name: "lead", isLead: true, status: "idle" });
+      updateAgentProfile(lead.id, {
+        heartbeatMd: "- Check tasks\n",
+      });
+
+      await createBootTriageTask();
+      await checkHeartbeatChecklist();
+
+      const bootTasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'boot-triage'")
+        .all();
+      const checklistTasks = getDb()
+        .query("SELECT * FROM agent_tasks WHERE taskType = 'heartbeat-checklist'")
+        .all();
+      expect(bootTasks.length).toBe(1);
+      expect(checklistTasks.length).toBe(1);
+    });
+  });
+});

package/src/tests/heartbeat.test.ts

@@ -18,7 +18,6 @@ import {
 import {
   codeLevelTriage,
   preflightGate,
-  resetEscalationCooldowns,
   runHeartbeatSweep,
   startHeartbeat,
   stopHeartbeat,
@@ -53,7 +52,6 @@ describe("Heartbeat Triage", () => {
     getDb().run("DELETE FROM agent_tasks");
     getDb().run("DELETE FROM agents");
     getDb().run("DELETE FROM active_sessions");
-    resetEscalationCooldowns();
   });
 
   // ==========================================================================
@@ -285,8 +283,6 @@ describe("Heartbeat Triage", () => {
       expect(findings.autoFailedTasks.length).toBe(0);
       expect(findings.stalledTasks.length).toBe(1);
       expect(findings.stalledTasks[0]!.id).toBe(task.id);
-      expect(findings.escalationNeeded).toBe(true);
-
       // Task should NOT be failed
       const updated = getTaskById(task.id);
       expect(updated?.status).toBe("in_progress");
@@ -356,11 +352,11 @@ describe("Heartbeat Triage", () => {
       ).toBe(true);
     });
 
-    test("no escalation when no stalled tasks", async () => {
+    test("no stalled tasks when workers are healthy", async () => {
       createAgent({ name: "healthy-worker", isLead: false, status: "idle" });
 
       const findings = await codeLevelTriage();
-      expect(findings.escalationNeeded).toBe(false);
+      expect(findings.stalledTasks.length).toBe(0);
     });
 
     test("sets agent to idle after auto-failing its only task", async () => {
@@ -406,57 +402,6 @@ describe("Heartbeat Triage", () => {
       expect(tasks.length).toBe(1);
     });
 
-    test("creates triage task for lead when stalled tasks found with fresh session", async () => {
-      const lead = createAgent({ name: "triage-lead", isLead: true, status: "idle" });
-      const worker = createAgent({ name: "stall-worker", isLead: false, status: "busy" });
-      const task = createTaskExtended("Stalled task", { agentId: worker.id });
-      startTask(task.id);
-
-      // Create fresh active session (worker alive but task stale)
-      insertActiveSession({
-        agentId: worker.id,
-        taskId: task.id,
-        triggerType: "task_assigned",
-      });
-
-      // Make task stale (45 min)
-      const oldTime = new Date(Date.now() - 45 * 60 * 1000).toISOString();
-      getDb().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [oldTime, task.id]);
-
-      await runHeartbeatSweep();
-
-      // Verify triage task was created for lead
-      const triageTasks = getDb()
-        .query("SELECT * FROM agent_tasks WHERE taskType = 'heartbeat' AND agentId = ?")
-        .all(lead.id) as Array<{ id: string; task: string }>;
-      expect(triageTasks.length).toBe(1);
-      expect(triageTasks[0]!.task).toContain("Stalled Tasks");
-    });
-
-    test("does not create duplicate triage tasks due to escalation cooldown", async () => {
-      const lead = createAgent({ name: "triage-lead", isLead: true, status: "idle" });
-      const worker = createAgent({ name: "stall-worker", isLead: false, status: "busy" });
-      const task = createTaskExtended("Stalled task", { agentId: worker.id });
-      startTask(task.id);
-
-      insertActiveSession({
-        agentId: worker.id,
-        taskId: task.id,
-        triggerType: "task_assigned",
-      });
-
-      const oldTime = new Date(Date.now() - 45 * 60 * 1000).toISOString();
-      getDb().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [oldTime, task.id]);
-
-      await runHeartbeatSweep();
-      await runHeartbeatSweep();
-
-      const triageTasks = getDb()
-        .query("SELECT id FROM agent_tasks WHERE taskType = 'heartbeat' AND agentId = ?")
-        .all(lead.id) as Array<{ id: string }>;
-      expect(triageTasks.length).toBe(1);
-    });
-
     test("auto-fails stalled task with no session during sweep", async () => {
       const worker = createAgent({ name: "dead-worker", isLead: false, status: "busy" });
       const task = createTaskExtended("Stalled no-session", { agentId: worker.id });

package/src/tests/prompt-template-remaining.test.ts

@@ -99,7 +99,7 @@ describe("template registration — all sources", () => {
   test("Heartbeat template is registered (1 event)", () => {
     const all = getAllTemplateDefinitions();
     const eventTypes = all.map((d) => d.eventType);
-    expect(eventTypes).toContain("heartbeat.escalation.stalled");
+    expect(eventTypes).toContain("heartbeat.checklist");
   });
 
   test("Task lifecycle templates are registered (2 task_lifecycle)", () => {

package/src/tools/update-profile.ts

@@ -67,6 +67,13 @@ export const registerUpdateProfileTool = (server: McpServer) => {
           .describe(
             "Environment-specific operational knowledge. Repos, services, SSH hosts, APIs, device names — anything specific to your setup. Synced to /workspace/TOOLS.md.",
           ),
+        heartbeatMd: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Heartbeat checklist content (HEARTBEAT.md). Checked periodically — add standing orders for the lead to review. Synced to /workspace/HEARTBEAT.md.",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -87,6 +94,7 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         identityMd,
         setupScript,
         toolsMd,
+        heartbeatMd,
       },
       requestInfo,
       _meta,
@@ -159,20 +167,21 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         soulMd === undefined &&
         identityMd === undefined &&
         setupScript === undefined &&
-        toolsMd === undefined
+        toolsMd === undefined &&
+        heartbeatMd === undefined
       ) {
         return {
           content: [
             {
               type: "text",
-              text: "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, or toolsMd) must be provided.",
+              text: "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, toolsMd, or heartbeatMd) must be provided.",
             },
           ],
           structuredContent: {
             yourAgentId: requestInfo.agentId,
             success: false,
             message:
-              "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, or toolsMd) must be provided.",
+              "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, toolsMd, or heartbeatMd) must be provided.",
           },
         };
       }
@@ -207,6 +216,7 @@ export const registerUpdateProfileTool = (server: McpServer) => {
             identityMd,
             setupScript,
             toolsMd,
+            heartbeatMd,
           },
           {
             changeSource: isUpdatingSelf ? "self_edit" : "lead_coaching",
@@ -245,6 +255,13 @@ export const registerUpdateProfileTool = (server: McpServer) => {
               /* ignore */
             }
           }
+          if (heartbeatMd !== undefined) {
+            try {
+              await Bun.write("/workspace/HEARTBEAT.md", heartbeatMd);
+            } catch {
+              /* ignore */
+            }
+          }
         }
 
         if (!agent) {
@@ -268,6 +285,7 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         if (identityMd !== undefined) updatedFields.push("identityMd");
         if (setupScript !== undefined) updatedFields.push("setupScript");
         if (toolsMd !== undefined) updatedFields.push("toolsMd");
+        if (heartbeatMd !== undefined) updatedFields.push("heartbeatMd");
 
         const targetLabel = isUpdatingSelf ? "own" : `agent ${targetAgentId}`;
         return {