@swarmclawai/swarmclaw 0.8.4 → 0.8.7

package/src/lib/server/heartbeat-service.test.ts

@@ -0,0 +1,406 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { after, before, describe, it } from 'node:test'
+
+const originalEnv = {
+  DATA_DIR: process.env.DATA_DIR,
+  WORKSPACE_DIR: process.env.WORKSPACE_DIR,
+  SWARMCLAW_BUILD_MODE: process.env.SWARMCLAW_BUILD_MODE,
+}
+
+let tempDir = ''
+let workspaceDir = ''
+let mod: typeof import('./heartbeat-service')
+
+before(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-heartbeat-svc-'))
+  workspaceDir = path.join(tempDir, 'workspace')
+  fs.mkdirSync(workspaceDir, { recursive: true })
+  process.env.DATA_DIR = path.join(tempDir, 'data')
+  process.env.WORKSPACE_DIR = workspaceDir
+  process.env.SWARMCLAW_BUILD_MODE = '1'
+  mod = await import('./heartbeat-service')
+})
+
+after(() => {
+  // Stop the service in case any test started it
+  try { mod.stopHeartbeatService() } catch { /* ignore */ }
+  if (originalEnv.DATA_DIR === undefined) delete process.env.DATA_DIR
+  else process.env.DATA_DIR = originalEnv.DATA_DIR
+  if (originalEnv.WORKSPACE_DIR === undefined) delete process.env.WORKSPACE_DIR
+  else process.env.WORKSPACE_DIR = originalEnv.WORKSPACE_DIR
+  if (originalEnv.SWARMCLAW_BUILD_MODE === undefined) delete process.env.SWARMCLAW_BUILD_MODE
+  else process.env.SWARMCLAW_BUILD_MODE = originalEnv.SWARMCLAW_BUILD_MODE
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+// ── stripBlockedItems ───────────────────────────────────────────────────
+
+describe('stripBlockedItems', () => {
+  it('returns empty string for empty input', () => {
+    assert.equal(mod.stripBlockedItems(''), '')
+  })
+
+  it('removes list items with (blocked) marker', () => {
+    const input = '- Task A\n- Task B (blocked, no update)\n- Task C'
+    const result = mod.stripBlockedItems(input)
+    assert.ok(result.includes('Task A'))
+    assert.ok(!result.includes('Task B'))
+    assert.ok(result.includes('Task C'))
+  })
+
+  it('removes items with various blocked formats', () => {
+    const input = [
+      '- Normal item',
+      '* Blocked one (blocked: awaiting approval)',
+      '+ Another (blocked by dependency)',
+      '- Keep this',
+    ].join('\n')
+    const result = mod.stripBlockedItems(input)
+    assert.ok(!result.includes('Blocked one'))
+    assert.ok(!result.includes('Another (blocked'))
+    assert.ok(result.includes('Normal item'))
+    assert.ok(result.includes('Keep this'))
+  })
+
+  it('preserves headers even if they mention blocked', () => {
+    const input = '## Blocked Tasks\n- Item (blocked)'
+    const result = mod.stripBlockedItems(input)
+    assert.ok(result.includes('## Blocked Tasks'))
+    assert.ok(!result.includes('- Item'))
+  })
+
+  it('preserves non-list lines mentioning blocked', () => {
+    const input = 'Some blocked context text\n- Real blocked item (blocked)'
+    const result = mod.stripBlockedItems(input)
+    assert.ok(result.includes('Some blocked context'))
+    assert.ok(!result.includes('Real blocked'))
+  })
+})
+
+// ── isHeartbeatContentEffectivelyEmpty ───────────────────────────────────
+
+describe('isHeartbeatContentEffectivelyEmpty', () => {
+  it('returns true for null/undefined/empty', () => {
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty(null), true)
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty(undefined), true)
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty(''), true)
+  })
+
+  it('returns true for headers only', () => {
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty('# Title\n## Subtitle\n### H3'), true)
+  })
+
+  it('returns true for empty list items', () => {
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty('- \n* \n+ '), true)
+  })
+
+  it('returns true for empty checkboxes', () => {
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty('- [ ] \n- [x] '), true)
+  })
+
+  it('returns false for content with real text', () => {
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty('# Title\n- Do something useful'), false)
+  })
+
+  it('returns false for plain text', () => {
+    assert.equal(mod.isHeartbeatContentEffectivelyEmpty('Run the backup job'), false)
+  })
+})
+
+// ── buildIdentityContext ────────────────────────────────────────────────
+
+describe('buildIdentityContext', () => {
+  it('returns empty string when no identity fields', () => {
+    assert.equal(mod.buildIdentityContext({}, {}), '')
+  })
+
+  it('builds context from agent fields', () => {
+    const result = mod.buildIdentityContext(null, { name: 'Bot', emoji: '🤖' })
+    assert.ok(result.includes('## Your Identity'))
+    assert.ok(result.includes('Name: Bot'))
+  })
+
+  it('prefers file identity fields over agent fields', () => {
+    // Without an actual IDENTITY.md on disk, file fields will be empty,
+    // so agent fields should be used as fallback
+    const result = mod.buildIdentityContext({ cwd: workspaceDir }, { name: 'Agent', vibe: 'chill' })
+    assert.ok(result.includes('Name: Agent'))
+    assert.ok(result.includes('Vibe: chill'))
+  })
+
+  it('reads IDENTITY.md from session cwd when present', () => {
+    const identityPath = path.join(workspaceDir, 'IDENTITY.md')
+    fs.writeFileSync(identityPath, '- **Name**: FileBot\n- **Emoji**: 🐛\n')
+    try {
+      const result = mod.buildIdentityContext({ cwd: workspaceDir }, { name: 'Agent' })
+      assert.ok(result.includes('Name: FileBot'))
+    } finally {
+      fs.unlinkSync(identityPath)
+    }
+  })
+})
+
+// ── readHeartbeatFile ───────────────────────────────────────────────────
+
+describe('readHeartbeatFile', () => {
+  it('returns empty string when no HEARTBEAT.md', () => {
+    assert.equal(mod.readHeartbeatFile({ cwd: workspaceDir }), '')
+  })
+
+  it('reads HEARTBEAT.md from session cwd', () => {
+    const hbPath = path.join(workspaceDir, 'HEARTBEAT.md')
+    fs.writeFileSync(hbPath, '# Tasks\n- Check logs')
+    try {
+      const result = mod.readHeartbeatFile({ cwd: workspaceDir })
+      assert.ok(result.includes('Check logs'))
+    } finally {
+      fs.unlinkSync(hbPath)
+    }
+  })
+})
+
+// ── heartbeatConfigForSession ───────────────────────────────────────────
+
+describe('heartbeatConfigForSession', () => {
+  it('uses global defaults when no overrides', () => {
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1' },
+      { heartbeatIntervalSec: 60 },
+      {},
+    )
+    assert.equal(cfg.intervalSec, 60)
+    assert.equal(cfg.enabled, true)
+  })
+
+  it('disables when interval is 0', () => {
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1' },
+      { heartbeatIntervalSec: 0 },
+      {},
+    )
+    assert.equal(cfg.enabled, false)
+  })
+
+  it('agent layer overrides global settings', () => {
+    const agents: Record<string, Record<string, unknown>> = {
+      'a1': { heartbeatIntervalSec: 120, heartbeatEnabled: true, heartbeatPrompt: 'Custom agent prompt' },
+    }
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1', agentId: 'a1' },
+      { heartbeatIntervalSec: 60 },
+      agents,
+    )
+    assert.equal(cfg.intervalSec, 120)
+    assert.equal(cfg.prompt, 'Custom agent prompt')
+  })
+
+  it('agent can disable heartbeat', () => {
+    const agents: Record<string, Record<string, unknown>> = {
+      'a1': { heartbeatEnabled: false },
+    }
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1', agentId: 'a1' },
+      { heartbeatIntervalSec: 60 },
+      agents,
+    )
+    assert.equal(cfg.enabled, false)
+  })
+
+  it('session layer overrides agent settings', () => {
+    const agents: Record<string, Record<string, unknown>> = {
+      'a1': { heartbeatEnabled: true },
+    }
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1', agentId: 'a1', heartbeatEnabled: false },
+      { heartbeatIntervalSec: 60 },
+      agents,
+    )
+    assert.equal(cfg.enabled, false)
+  })
+
+  it('session interval overrides agent interval', () => {
+    const agents: Record<string, Record<string, unknown>> = {
+      'a1': { heartbeatIntervalSec: 120 },
+    }
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1', agentId: 'a1', heartbeatIntervalSec: 300 },
+      { heartbeatIntervalSec: 60 },
+      agents,
+    )
+    assert.equal(cfg.intervalSec, 300)
+  })
+
+  it('supports duration string format for interval', () => {
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1' },
+      { heartbeatInterval: '1h30m' },
+      {},
+    )
+    assert.equal(cfg.intervalSec, 5400) // 1h30m = 5400s
+  })
+
+  it('resolves model from settings and agent layers', () => {
+    const agents: Record<string, Record<string, unknown>> = {
+      'a1': { heartbeatModel: 'gpt-4' },
+    }
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1', agentId: 'a1' },
+      { heartbeatIntervalSec: 60, heartbeatModel: 'gpt-3.5' },
+      agents,
+    )
+    assert.equal(cfg.model, 'gpt-4')
+  })
+
+  it('returns showOk and showAlerts defaults', () => {
+    const cfg = mod.heartbeatConfigForSession(
+      { id: 's1' },
+      { heartbeatIntervalSec: 60 },
+      {},
+    )
+    assert.equal(cfg.showOk, false)
+    assert.equal(cfg.showAlerts, true)
+  })
+})
+
+// ── start/stop/status service lifecycle ─────────────────────────────────
+
+describe('heartbeat service lifecycle', () => {
+  it('reports not running initially', () => {
+    // Stop in case a previous test left it running
+    mod.stopHeartbeatService()
+    const status = mod.getHeartbeatServiceStatus()
+    assert.equal(status.running, false)
+  })
+
+  it('start sets running to true', () => {
+    mod.startHeartbeatService()
+    try {
+      const status = mod.getHeartbeatServiceStatus()
+      assert.equal(status.running, true)
+    } finally {
+      mod.stopHeartbeatService()
+    }
+  })
+
+  it('stop sets running to false', () => {
+    mod.startHeartbeatService()
+    mod.stopHeartbeatService()
+    const status = mod.getHeartbeatServiceStatus()
+    assert.equal(status.running, false)
+  })
+
+  it('restart clears tracked sessions and restarts', () => {
+    mod.startHeartbeatService()
+    mod.restartHeartbeatService()
+    try {
+      const status = mod.getHeartbeatServiceStatus()
+      assert.equal(status.running, true)
+      assert.equal(status.trackedSessions, 0)
+    } finally {
+      mod.stopHeartbeatService()
+    }
+  })
+
+  it('double start replaces the timer (no duplicate intervals)', () => {
+    mod.startHeartbeatService()
+    mod.startHeartbeatService()
+    try {
+      const status = mod.getHeartbeatServiceStatus()
+      assert.equal(status.running, true)
+    } finally {
+      mod.stopHeartbeatService()
+    }
+  })
+})
+
+// ── buildAgentHeartbeatPrompt ───────────────────────────────────────────
+
+describe('buildAgentHeartbeatPrompt', () => {
+  it('returns fallback prompt when agent is null', () => {
+    const result = mod.buildAgentHeartbeatPrompt({ id: 's1' }, null, 'fallback', '')
+    assert.equal(result, 'fallback')
+  })
+
+  it('includes AGENT_HEARTBEAT_TICK header', () => {
+    const result = mod.buildAgentHeartbeatPrompt(
+      { id: 's1', messages: [] },
+      { name: 'Bot' },
+      'Check status',
+      '',
+    )
+    assert.ok(result.includes('AGENT_HEARTBEAT_TICK'))
+  })
+
+  it('includes heartbeat file content when provided', () => {
+    const result = mod.buildAgentHeartbeatPrompt(
+      { id: 's1', messages: [] },
+      { name: 'Bot' },
+      'Check status',
+      '# Tasks\n- Do the thing',
+    )
+    assert.ok(result.includes('HEARTBEAT.md contents'))
+    assert.ok(result.includes('Do the thing'))
+  })
+
+  it('excludes HEARTBEAT.md section when content is effectively empty', () => {
+    const result = mod.buildAgentHeartbeatPrompt(
+      { id: 's1', messages: [] },
+      { name: 'Bot' },
+      'Check status',
+      '# Title\n- [ ] ',
+    )
+    assert.ok(!result.includes('HEARTBEAT.md contents'))
+  })
+
+  it('includes dynamic goal when set on agent', () => {
+    const result = mod.buildAgentHeartbeatPrompt(
+      { id: 's1', messages: [] },
+      { name: 'Bot', heartbeatGoal: 'Monitor CI pipeline' },
+      'Check status',
+      '',
+    )
+    assert.ok(result.includes('Monitor CI pipeline'))
+  })
+
+  it('includes recent conversation context', () => {
+    const result = mod.buildAgentHeartbeatPrompt(
+      {
+        id: 's1',
+        messages: [
+          { role: 'user', text: 'Check the logs', toolEvents: [] },
+          { role: 'assistant', text: 'Logs look clean', toolEvents: [] },
+        ],
+      },
+      { name: 'Bot' },
+      'Check status',
+      '',
+    )
+    assert.ok(result.includes('[user]: Check the logs'))
+    assert.ok(result.includes('[assistant]: Logs look clean'))
+  })
+
+  it('includes agent soul in prompt', () => {
+    const result = mod.buildAgentHeartbeatPrompt(
+      { id: 's1', messages: [] },
+      { name: 'Bot', soul: 'You are a cheerful monitoring assistant' },
+      'Check status',
+      '',
+    )
+    assert.ok(result.includes('Persona: You are a cheerful'))
+  })
+
+  it('strips blocked items from heartbeat file content', () => {
+    const result = mod.buildAgentHeartbeatPrompt(
+      { id: 's1', messages: [] },
+      { name: 'Bot' },
+      'Check status',
+      '- Active task\n- Blocked task (blocked, waiting)\n- Another active task',
+    )
+    assert.ok(result.includes('Active task'))
+    assert.ok(!result.includes('Blocked task'))
+    assert.ok(result.includes('Another active task'))
+  })
+})

package/src/lib/server/heartbeat-service.ts

@@ -15,6 +15,7 @@ import { buildIdentityContinuityContext } from './identity-continuity'
 import { buildMainLoopHeartbeatPrompt, isMainSession } from './main-agent-loop'
 import { ensureAgentThreadSession } from './agent-thread-session'
 import { isAgentDisabled } from './agent-availability'
+import { errorMessage, hmrSingleton } from '@/lib/shared-utils'
 
 const HEARTBEAT_TICK_MS = 60_000
 const MAX_CONCURRENT_HEARTBEATS = 5
@@ -33,14 +34,12 @@ interface HeartbeatState {
   failures: Map<string, FailureRecord>
 }
 
-const globalKey = '__swarmclaw_heartbeat_service__' as const
-const globalScope = globalThis as typeof globalThis & { [globalKey]?: HeartbeatState }
-const state: HeartbeatState = globalScope[globalKey] ?? (globalScope[globalKey] = {
+const state: HeartbeatState = hmrSingleton<HeartbeatState>('__swarmclaw_heartbeat_service__', () => ({
   timer: null,
   running: false,
   lastBySession: new Map<string, number>(),
   failures: new Map<string, FailureRecord>(),
-})
+}))
 
 function parseIntBounded(value: unknown, fallback: number, min: number, max: number): number {
   const parsed = typeof value === 'number'
@@ -194,6 +193,31 @@ export function buildIdentityContext(session: Record<string, unknown> | undefine
   return `## Your Identity\n${lines.join('\n')}`
 }
 
+// ── Blocked-item suppression ────────────────────────────────────────────
+// Ported from OpenClaw's duplicate-suppression pattern: instead of letting
+// the LLM see blocked tasks every tick (and parrot "still blocked"), we
+// strip those lines before they ever reach the prompt.  A line is
+// considered blocked if it contains "(blocked" anywhere (case-insensitive),
+// which covers "(blocked, no update)", "(blocked: awaiting …)", etc.
+const BLOCKED_MARKER_RE = /\(blocked\b/i
+
+/**
+ * Remove blocked checklist items from HEARTBEAT.md content so the LLM
+ * doesn't keep surfacing them.  Headers and non-list lines pass through
+ * unchanged.
+ */
+export function stripBlockedItems(content: string): string {
+  if (!content) return ''
+  const lines = content.split('\n')
+  const filtered = lines.filter((line) => {
+    const trimmed = line.trim()
+    // Only filter checklist / list items that are explicitly marked blocked
+    if (/^[-*+]\s/.test(trimmed) && BLOCKED_MARKER_RE.test(trimmed)) return false
+    return true
+  })
+  return filtered.join('\n')
+}
+
 /** Detect HEARTBEAT.md files that contain only skeleton structure (headers, empty list items) but no real content. */
 export function isHeartbeatContentEffectivelyEmpty(content: string | undefined | null): boolean {
   if (!content || typeof content !== 'string') return true
@@ -236,8 +260,9 @@ export function buildAgentHeartbeatPrompt(session: any, agent: any, fallbackProm
     })
     .join('\n')
 
-  // Don't inject effectively-empty HEARTBEAT.md content
-  const effectiveFileContent = isHeartbeatContentEffectivelyEmpty(heartbeatFileContent) ? '' : heartbeatFileContent
+  // Strip blocked items, then check if anything meaningful remains
+  const strippedContent = stripBlockedItems(heartbeatFileContent)
+  const effectiveFileContent = isHeartbeatContentEffectivelyEmpty(strippedContent) ? '' : strippedContent
 
   return [
     'AGENT_HEARTBEAT_TICK',
@@ -507,7 +532,7 @@ async function tickHeartbeats() {
         count: (prev?.count ?? 0) + 1,
         lastFailedAt: Date.now(),
       })
-      const msg = err instanceof Error ? err.message : String(err)
+      const msg = errorMessage(err)
       log.warn('heartbeat', `Heartbeat run failed for session ${sid}`, msg)
     })
   }
@@ -577,3 +602,25 @@ export function getHeartbeatServiceStatus() {
     trackedSessions: state.lastBySession.size,
   }
 }
+
+/**
+ * Remove tracking entries for sessions that no longer exist.
+ * Called periodically by the daemon health sweep.
+ */
+export function pruneHeartbeatState(liveSessionIds: Set<string>): number {
+  let removed = 0
+  for (const id of state.lastBySession.keys()) {
+    if (!liveSessionIds.has(id)) {
+      state.lastBySession.delete(id)
+      state.failures.delete(id)
+      removed++
+    }
+  }
+  // Also clean up orphaned failure entries
+  for (const id of state.failures.keys()) {
+    if (!liveSessionIds.has(id)) {
+      state.failures.delete(id)
+    }
+  }
+  return removed
+}

package/src/lib/server/heartbeat-wake.test.ts

@@ -4,6 +4,7 @@ import { afterEach, describe, it } from 'node:test'
 import {
   buildHeartbeatWakePrompt,
   buildWakeTriggerContext,
+  deriveHeartbeatWakeDeliveryMode,
   hasPendingHeartbeatWake,
   mergeHeartbeatWakeRequest,
   requestHeartbeatNow,
@@ -109,4 +110,22 @@ describe('heartbeat-wake helpers', () => {
       ['connector-message', 'watch_job'],
     )
   })
+
+  it('forces connector-triggered wakes into tool-only delivery mode', () => {
+    const connectorWake = mergeHeartbeatWakeRequest(undefined, {
+      sessionId: 'sess-3',
+      reason: 'connector-message',
+      source: 'connector:whatsapp',
+      requestedAt: 1,
+    })
+    const scheduleWake = mergeHeartbeatWakeRequest(undefined, {
+      sessionId: 'sess-4',
+      reason: 'schedule',
+      source: 'schedule:daily',
+      requestedAt: 1,
+    })
+
+    assert.equal(deriveHeartbeatWakeDeliveryMode(connectorWake.events), 'tool_only')
+    assert.equal(deriveHeartbeatWakeDeliveryMode(scheduleWake.events), 'default')
+  })
 })

package/src/lib/server/heartbeat-wake.ts

@@ -16,6 +16,7 @@ import { loadSessions, loadAgents, loadSettings } from './storage'
 import { enqueueSessionRun, getSessionExecutionState } from './session-run-manager'
 import { log } from './logger'
 import { isAgentDisabled } from './agent-availability'
+import { errorMessage, hmrSingleton } from '@/lib/shared-utils'
 
 export interface WakeRequestInput {
   eventId?: string
@@ -56,21 +57,12 @@ const MAX_RESUME_CHARS = 280
 const MAX_DETAIL_CHARS = 800
 type WakeTimerKind = 'normal' | 'retry'
 
-const globalKey = '__swarmclaw_heartbeat_wake__' as const
-const globalScope = globalThis as typeof globalThis & {
-  [globalKey]?: {
-    pending: Map<string, WakeRequest>
-    timer: ReturnType<typeof setTimeout> | null
-    timerDueAt: number | null
-    timerKind: WakeTimerKind | null
-  }
-}
-const state = globalScope[globalKey] ?? (globalScope[globalKey] = {
-  pending: new Map(),
-  timer: null,
-  timerDueAt: null,
-  timerKind: null,
-})
+const state = hmrSingleton('__swarmclaw_heartbeat_wake__', () => ({
+  pending: new Map<string, WakeRequest>(),
+  timer: null as ReturnType<typeof setTimeout> | null,
+  timerDueAt: null as number | null,
+  timerKind: null as WakeTimerKind | null,
+}))
 
 function trimText(value: unknown, maxChars: number): string | undefined {
   if (typeof value !== 'string') return undefined
@@ -235,6 +227,14 @@ export function buildWakeTriggerContext(events: WakeEvent[], nowIso?: string): s
   return lines.join('\n')
 }
 
+export function deriveHeartbeatWakeDeliveryMode(
+  events: WakeEvent[],
+): 'default' | 'tool_only' {
+  return events.some((event) => event.reason.toLowerCase() === 'connector-message')
+    ? 'tool_only'
+    : 'default'
+}
+
 export function buildHeartbeatWakePrompt(input: {
   wake: WakeRequest
   basePrompt?: string
@@ -347,6 +347,7 @@ function flushWakes(): void {
           showOk: cfg.showOk,
           showAlerts: cfg.showAlerts,
           target: cfg.target,
+          deliveryMode: deriveHeartbeatWakeDeliveryMode(wake.events),
         },
       })
 
@@ -360,7 +361,7 @@ function flushWakes(): void {
         retryCount: wake.retryCount + 1,
       })
       delayedForRetry = true
-      log.warn('heartbeat-wake', `Wake failed: ${err instanceof Error ? err.message : String(err)}`)
+      log.warn('heartbeat-wake', `Wake failed: ${errorMessage(err)}`)
     }
   }