@desplega.ai/agent-swarm 1.55.0 → 1.56.3

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.55.0",
+    "version": "1.56.3",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -509,6 +509,10 @@
                     "type": "string",
                     "maxLength": 65536
                   },
+                  "heartbeatMd": {
+                    "type": "string",
+                    "maxLength": 65536
+                  },
                   "changeSource": {
                     "type": "string"
                   },
@@ -1911,6 +1915,27 @@
         }
       }
     },
+    "/api/heartbeat/checklist": {
+      "post": {
+        "summary": "Trigger an immediate heartbeat checklist check",
+        "tags": [
+          "Heartbeat"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Checklist check completed successfully"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/memory/index": {
       "post": {
         "summary": "Ingest content into memory system (async embedding)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.55.0",
+  "version": "1.56.3",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/be/db.ts

@@ -229,6 +229,7 @@ const VERSIONABLE_FIELDS: VersionableField[] = [
   "toolsMd",
   "claudeMd",
   "setupScript",
+  "heartbeatMd",
 ];
 
 function ensureAgentProfileColumns(database: Database): void {
@@ -399,9 +400,10 @@ function seedContextVersions(): void {
         toolsMd: string | null;
         claudeMd: string | null;
         setupScript: string | null;
+        heartbeatMd: string | null;
       },
       []
-    >(`SELECT id, soulMd, identityMd, toolsMd, claudeMd, setupScript FROM agents`)
+    >(`SELECT id, soulMd, identityMd, toolsMd, claudeMd, setupScript, heartbeatMd FROM agents`)
     .all();
 
   for (const agent of agents) {
@@ -450,6 +452,7 @@ type AgentRow = {
   identityMd: string | null;
   setupScript: string | null;
   toolsMd: string | null;
+  heartbeatMd: string | null;
   lastActivityAt: string | null;
   createdAt: string;
   lastUpdatedAt: string;
@@ -471,6 +474,7 @@ function rowToAgent(row: AgentRow): Agent {
     identityMd: row.identityMd ?? undefined,
     setupScript: row.setupScript ?? undefined,
     toolsMd: row.toolsMd ?? undefined,
+    heartbeatMd: row.heartbeatMd ?? undefined,
     lastActivityAt: row.lastActivityAt ?? undefined,
     createdAt: row.createdAt,
     lastUpdatedAt: row.lastUpdatedAt,
@@ -2259,6 +2263,7 @@ export function updateAgentProfile(
     identityMd?: string;
     setupScript?: string;
     toolsMd?: string;
+    heartbeatMd?: string;
   },
   meta?: VersionMeta,
 ): Agent | null {
@@ -2312,6 +2317,7 @@ export function updateAgentProfile(
           string | null,
           string | null,
           string | null,
+          string | null,
           string,
           string,
         ]
@@ -2325,6 +2331,7 @@ export function updateAgentProfile(
           identityMd = COALESCE(?, identityMd),
           setupScript = COALESCE(?, setupScript),
           toolsMd = COALESCE(?, toolsMd),
+          heartbeatMd = COALESCE(?, heartbeatMd),
           lastUpdatedAt = ?
          WHERE id = ? RETURNING *`,
       )
@@ -2337,6 +2344,7 @@ export function updateAgentProfile(
         updates.identityMd ?? null,
         updates.setupScript ?? null,
         updates.toolsMd ?? null,
+        updates.heartbeatMd ?? null,
         now,
         id,
       );

package/src/be/migrations/025_workflow_run_cancelled_status.sql

@@ -1,5 +1,3 @@
-PRAGMA defer_foreign_keys = ON;
-
 -- Add 'cancelled' as a valid status for workflow runs.
 -- SQLite does not support ALTER CHECK constraints, so we recreate the table.
 

package/src/be/migrations/027_heartbeat_md.sql

@@ -0,0 +1 @@
+ALTER TABLE agents ADD COLUMN heartbeatMd TEXT DEFAULT NULL;

package/src/be/migrations/runner.ts

@@ -152,6 +152,12 @@ export function runMigrations(db: Database): void {
   }
 
   // 5. Run pending migrations
+  // Disable FK checks for the entire migration pass. Individual migrations
+  // (008, 025, 026) need to DROP + recreate tables, which can violate FKs
+  // mid-transaction. PRAGMA foreign_keys cannot be changed inside a transaction,
+  // so we disable it here, outside any transaction, and re-enable after.
+  db.run("PRAGMA foreign_keys = OFF");
+
   for (const migration of migrations) {
     const existing = applied.get(migration.version);
 
@@ -184,4 +190,6 @@ export function runMigrations(db: Database): void {
     const elapsed = (performance.now() - start).toFixed(1);
     console.debug(`[migrations] Applied: ${migration.name} (${elapsed}ms)`);
   }
+
+  db.run("PRAGMA foreign_keys = ON");
 }

package/src/commands/runner.ts

@@ -1991,6 +1991,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   let agentSetupScript: string | undefined;
   let agentToolsMd: string | undefined;
   let agentClaudeMd: string | undefined;
+  let agentHeartbeatMd: string | undefined;
   let agentProfileName: string | undefined;
   let agentDescription: string | undefined;
   let agentSkillsSummary: { name: string; description: string }[] | undefined;
@@ -2170,6 +2171,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           claudeMd?: string;
           setupScript?: string;
           toolsMd?: string;
+          heartbeatMd?: string;
           name?: string;
           description?: string;
         };
@@ -2178,12 +2180,19 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         agentSetupScript = profile.setupScript;
         agentToolsMd = profile.toolsMd;
         agentClaudeMd = profile.claudeMd;
+        agentHeartbeatMd = profile.heartbeatMd;
         agentProfileName = profile.name;
         agentDescription = profile.description;
 
         // Generate default templates if missing (runner registers via POST /api/agents
         // which doesn't generate templates like join-swarm does)
-        if (!agentSoulMd || !agentIdentityMd || !agentToolsMd || !agentClaudeMd) {
+        if (
+          !agentSoulMd ||
+          !agentIdentityMd ||
+          !agentToolsMd ||
+          !agentClaudeMd ||
+          !agentHeartbeatMd
+        ) {
           // Use already-fetched template (from pre-registration step)
           if (cachedTemplate) {
             const ctx = {
@@ -2202,6 +2211,8 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               agentClaudeMd = interpolate(cachedTemplate.files.claudeMd, ctx).result;
             if (!agentSetupScript)
               agentSetupScript = interpolate(cachedTemplate.files.setupScript, ctx).result;
+            if (!agentHeartbeatMd)
+              agentHeartbeatMd = interpolate(cachedTemplate.files.heartbeatMd, ctx).result;
             console.log(`[${role}] Applied template: ${templateId}`);
           }
 
@@ -2226,6 +2237,8 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
             if (!profile.claudeMd && agentClaudeMd) profileUpdate.claudeMd = agentClaudeMd;
             if (!profile.setupScript && agentSetupScript)
               profileUpdate.setupScript = agentSetupScript;
+            if (!profile.heartbeatMd && agentHeartbeatMd)
+              profileUpdate.heartbeatMd = agentHeartbeatMd;
 
             await fetch(`${apiUrl}/api/agents/${agentId}/profile`, {
               method: "PUT",
@@ -2364,6 +2377,16 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
       }
     }
 
+    // Write HEARTBEAT.md to workspace (lead's periodic checklist)
+    if (agentHeartbeatMd) {
+      try {
+        await Bun.write("/workspace/HEARTBEAT.md", agentHeartbeatMd);
+        console.log(`[${role}] Wrote HEARTBEAT.md to workspace`);
+      } catch (err) {
+        console.warn(`[${role}] Could not write HEARTBEAT.md: ${(err as Error).message}`);
+      }
+    }
+
     // Write CLAUDE.md to workspace (agent-level instructions)
     if (agentClaudeMd) {
       try {