@swarmclawai/swarmclaw 0.7.6 → 0.7.8

package/src/lib/server/connectors/manager.ts

@@ -332,6 +332,7 @@ export interface ConnectorReconnectState {
   nextRetryAt: number
   backoffMs: number
   error: string
+  exhausted: boolean
 }
 
 const reconnectStateKey = '__swarmclaw_connector_reconnect_state__' as const
@@ -342,6 +343,55 @@ const RECONNECT_INITIAL_BACKOFF_MS = 1_000
 const RECONNECT_MAX_BACKOFF_MS = 5 * 60 * 1_000
 const RECONNECT_MAX_ATTEMPTS = 10
 
+interface ConnectorReconnectPolicy {
+  initialBackoffMs?: number
+  maxBackoffMs?: number
+  maxAttempts?: number
+}
+
+export function createConnectorReconnectState(
+  init: Partial<ConnectorReconnectState> = {},
+  policy: ConnectorReconnectPolicy = {},
+): ConnectorReconnectState {
+  return {
+    attempts: init.attempts ?? 0,
+    lastAttemptAt: init.lastAttemptAt ?? 0,
+    nextRetryAt: init.nextRetryAt ?? 0,
+    backoffMs: init.backoffMs ?? policy.initialBackoffMs ?? RECONNECT_INITIAL_BACKOFF_MS,
+    error: init.error ?? '',
+    exhausted: init.exhausted ?? false,
+  }
+}
+
+export function advanceConnectorReconnectState(
+  previous: ConnectorReconnectState,
+  error: string,
+  now = Date.now(),
+  policy: ConnectorReconnectPolicy = {},
+): ConnectorReconnectState {
+  const initialBackoffMs = policy.initialBackoffMs ?? RECONNECT_INITIAL_BACKOFF_MS
+  const maxBackoffMs = policy.maxBackoffMs ?? RECONNECT_MAX_BACKOFF_MS
+  const maxAttempts = policy.maxAttempts ?? RECONNECT_MAX_ATTEMPTS
+  const attempts = previous.attempts + 1
+  const backoffMs = Math.min(maxBackoffMs, initialBackoffMs * (2 ** Math.max(0, attempts - 1)))
+  return {
+    attempts,
+    lastAttemptAt: now,
+    nextRetryAt: now + backoffMs,
+    backoffMs,
+    error,
+    exhausted: attempts >= maxAttempts,
+  }
+}
+
+export function clearReconnectState(connectorId: string): void {
+  reconnectState.delete(connectorId)
+}
+
+export function setReconnectState(connectorId: string, state: ConnectorReconnectState): void {
+  reconnectState.set(connectorId, state)
+}
+
 /** Record a health event for a connector (persisted to connector_health collection) */
 function recordHealthEvent(connectorId: string, event: ConnectorHealthEventType, message?: string): void {
   const id = genId()
@@ -2008,33 +2058,43 @@ async function _startConnectorImpl(connectorId: string): Promise<void> {
   const connector = connectors[connectorId] as Connector | undefined
   if (!connector) throw new Error('Connector not found')
 
-  // Resolve bot token from credential
-  let botToken = ''
-  if (connector.credentialId) {
-    const creds = loadCredentials()
-    const cred = creds[connector.credentialId]
-    if (cred?.encryptedKey) {
-      try { botToken = decryptKey(cred.encryptedKey) } catch { /* ignore */ }
-    }
-  }
-  // Also check config for inline token (some platforms)
-  if (!botToken && connector.config.botToken) {
-    botToken = connector.config.botToken
-  }
-  if (!botToken && connector.platform === 'bluebubbles' && connector.config.password) {
-    botToken = connector.config.password
+  // Starting a connector expresses durable intent: keep it enabled across
+  // transient failures so daemon recovery and server restarts can retry it.
+  if (connector.isEnabled !== true) {
+    connector.isEnabled = true
+    connector.updatedAt = Date.now()
+    connectors[connectorId] = connector
+    saveConnectors(connectors)
+    notify('connectors')
   }
 
-  if (!botToken && connector.platform !== 'whatsapp' && connector.platform !== 'openclaw' && connector.platform !== 'signal' && connector.platform !== 'email') {
-    throw new Error('No bot token configured')
-  }
+  try {
+    // Resolve bot token from credential
+    let botToken = ''
+    if (connector.credentialId) {
+      const creds = loadCredentials()
+      const cred = creds[connector.credentialId]
+      if (cred?.encryptedKey) {
+        try { botToken = decryptKey(cred.encryptedKey) } catch { /* ignore */ }
+      }
+    }
+    // Also check config for inline token (some platforms)
+    if (!botToken && connector.config.botToken) {
+      botToken = connector.config.botToken
+    }
+    if (!botToken && connector.platform === 'bluebubbles' && connector.config.password) {
+      botToken = connector.config.password
+    }
 
-  const platform = await getPlatform(connector.platform)
+    if (!botToken && connector.platform !== 'whatsapp' && connector.platform !== 'openclaw' && connector.platform !== 'signal' && connector.platform !== 'email') {
+      throw new Error('No bot token configured')
+    }
 
-  // Bump generation counter so stale events from previous instances are ignored
-  generationCounter.set(connectorId, (generationCounter.get(connectorId) ?? 0) + 1)
+    const platform = await getPlatform(connector.platform)
+
+    // Bump generation counter so stale events from previous instances are ignored
+    generationCounter.set(connectorId, (generationCounter.get(connectorId) ?? 0) + 1)
 
-  try {
     const instance = await platform.start(
       connector,
       botToken,
@@ -2049,6 +2109,7 @@ async function _startConnectorImpl(connectorId: string): Promise<void> {
     connector.updatedAt = Date.now()
     connectors[connectorId] = connector
     saveConnectors(connectors)
+    clearReconnectState(connectorId)
     notify('connectors')
 
     console.log(`[connector] Started ${connector.platform} connector: ${connector.name}`)
@@ -2056,7 +2117,7 @@ async function _startConnectorImpl(connectorId: string): Promise<void> {
   } catch (err: unknown) {
     const errMsg = err instanceof Error ? err.message : String(err)
     connector.status = 'error'
-    connector.isEnabled = false
+    connector.isEnabled = true
     connector.lastError = errMsg
     connector.updatedAt = Date.now()
     connectors[connectorId] = connector
@@ -2074,6 +2135,7 @@ export async function stopConnector(connectorId: string): Promise<void> {
     await instance.stop()
     running.delete(connectorId)
   }
+  clearReconnectState(connectorId)
 
   for (const [debounceKey, entry] of pendingInboundDebounce.entries()) {
     if (entry.connector.id !== connectorId) continue
@@ -2141,6 +2203,7 @@ export async function repairConnector(connectorId: string): Promise<void> {
     await instance.stop()
     running.delete(connectorId)
   }
+  clearReconnectState(connectorId)
 
   // Clear auth directory
   const { clearAuthDir } = await import('./whatsapp')
@@ -2609,7 +2672,7 @@ export async function checkConnectorHealth(): Promise<void> {
       // Connector is healthy — clear any reconnect state
       if (reconnectState.has(id)) {
         console.log(`[connector-health] Connector "${instance.connector.name}" recovered`)
-        reconnectState.delete(id)
+        clearReconnectState(id)
       }
       continue
     }
@@ -2627,68 +2690,30 @@ export async function checkConnectorHealth(): Promise<void> {
 
     // If the connector is not enabled, don't attempt reconnect
     if (!connector.isEnabled) {
-      reconnectState.delete(id)
+      clearReconnectState(id)
       continue
     }
 
-    // Attempt reconnect with backoff
-    const state = reconnectState.get(id) ?? {
-      attempts: 0,
-      lastAttemptAt: 0,
-      nextRetryAt: 0,
-      backoffMs: RECONNECT_INITIAL_BACKOFF_MS,
-      error: '',
-    }
-
-    // Check if we've exceeded max attempts
-    if (state.attempts >= RECONNECT_MAX_ATTEMPTS) {
-      console.warn(`[connector-health] Connector "${connector.name}" exceeded ${RECONNECT_MAX_ATTEMPTS} reconnect attempts — marking as error`)
-      connector.status = 'error'
-      connector.lastError = `Auto-reconnect gave up after ${RECONNECT_MAX_ATTEMPTS} attempts: ${state.error}`
-      connector.updatedAt = Date.now()
-      connectors[id] = connector
-      connectorsDirty = true
-      reconnectState.delete(id)
-      notify('connectors')
-      continue
-    }
-
-    const now = Date.now()
-
-    // Check if enough time has passed for the next retry
-    if (now < state.nextRetryAt) {
-      // Not yet time to retry — keep state and skip
-      continue
-    }
-
-    state.attempts += 1
-    state.lastAttemptAt = now
-    reconnectState.set(id, state)
-
-    try {
-      console.log(`[connector-health] Reconnecting "${connector.name}" (attempt ${state.attempts}/${RECONNECT_MAX_ATTEMPTS})`)
-      await startConnector(id)
-      // Success — clear reconnect state
-      reconnectState.delete(id)
-      console.log(`[connector-health] Connector "${connector.name}" reconnected successfully`)
-      recordHealthEvent(id, 'reconnected', `Connector "${connector.name}" reconnected after ${state.attempts} attempt(s)`)
-    } catch (err: unknown) {
-      const errorMsg = err instanceof Error ? err.message : String(err)
-      state.error = errorMsg
-      state.backoffMs = Math.min(RECONNECT_MAX_BACKOFF_MS, RECONNECT_INITIAL_BACKOFF_MS * (2 ** state.attempts))
-      state.nextRetryAt = now + state.backoffMs
-      reconnectState.set(id, state)
-      console.warn(`[connector-health] Reconnect failed for "${connector.name}" (attempt ${state.attempts}/${RECONNECT_MAX_ATTEMPTS}): ${errorMsg}. Next retry at ${new Date(state.nextRetryAt).toISOString()}`)
+    connector.status = 'error'
+    connector.lastError = connector.lastError || 'Connection lost'
+    connector.updatedAt = Date.now()
+    connectors[id] = connector
+    connectorsDirty = true
+    if (!reconnectState.has(id)) {
+      setReconnectState(id, createConnectorReconnectState({
+        error: connector.lastError || 'Connection lost',
+      }))
     }
   }
 
   if (connectorsDirty) {
     saveConnectors(connectors)
+    notify('connectors')
   }
 
   // Purge reconnect state for connectors that no longer exist
   for (const id of reconnectState.keys()) {
-    if (!connectors[id]) reconnectState.delete(id)
+    if (!connectors[id] || connectors[id]?.isEnabled !== true || running.has(id)) clearReconnectState(id)
   }
 }
 

package/src/lib/server/daemon-state.ts

@@ -11,6 +11,12 @@ import {
   startConnector,
   getConnectorStatus,
   checkConnectorHealth,
+  createConnectorReconnectState,
+  advanceConnectorReconnectState,
+  clearReconnectState,
+  getAllReconnectStates,
+  getReconnectState,
+  setReconnectState,
 } from './connectors/manager'
 import { startHeartbeatService, stopHeartbeatService, getHeartbeatServiceStatus } from './heartbeat-service'
 import { hasOpenClawAgents, ensureGatewayConnected, disconnectGateway, getGateway } from './openclaw-gateway'
@@ -34,6 +40,7 @@ const QUEUE_CHECK_INTERVAL = 30_000 // 30 seconds
 const BROWSER_SWEEP_INTERVAL = 60_000 // 60 seconds
 const BROWSER_MAX_AGE = 10 * 60 * 1000 // 10 minutes idle = orphaned
 const HEALTH_CHECK_INTERVAL = 120_000 // 2 minutes
+const CONNECTOR_HEALTH_CHECK_INTERVAL = 5_000 // 5 seconds
 const MEMORY_CONSOLIDATION_INTERVAL = 6 * 3600_000 // 6 hours
 const MEMORY_CONSOLIDATION_INITIAL_DELAY = 60_000 // 1 minute after daemon start
 const STALE_MULTIPLIER = 4 // session is stale after N × heartbeat interval
@@ -87,12 +94,12 @@ const ds: {
   queueIntervalId: ReturnType<typeof setInterval> | null
   browserSweepId: ReturnType<typeof setInterval> | null
   healthIntervalId: ReturnType<typeof setInterval> | null
+  connectorHealthIntervalId: ReturnType<typeof setInterval> | null
   memoryConsolidationTimeoutId: ReturnType<typeof setTimeout> | null
   memoryConsolidationIntervalId: ReturnType<typeof setInterval> | null
   evalSchedulerIntervalId: ReturnType<typeof setInterval> | null
   /** Session IDs we've already alerted as stale (alert-once semantics). */
   staleSessionIds: Set<string>
-  connectorRestartState: Map<string, { lastAttemptAt: number; failCount: number; wakeAttempts: number }>
   /** OpenClaw gateway agent IDs currently considered down. */
   openclawDownAgentIds: Set<string>
   /** Per-agent auto-repair state for OpenClaw gateways. */
@@ -107,11 +114,11 @@ const ds: {
   queueIntervalId: null,
   browserSweepId: null,
   healthIntervalId: null,
+  connectorHealthIntervalId: null,
   memoryConsolidationTimeoutId: null,
   memoryConsolidationIntervalId: null,
   evalSchedulerIntervalId: null,
   staleSessionIds: new Set<string>(),
-  connectorRestartState: new Map<string, { lastAttemptAt: number; failCount: number; wakeAttempts: number }>(),
   openclawDownAgentIds: new Set<string>(),
   openclawRepairState: new Map<string, { attempts: number; lastAttemptAt: number; cooldownUntil: number }>(),
   lastIntegrityCheckAt: null,
@@ -123,7 +130,6 @@ const ds: {
 
 // Backfill fields for hot-reloaded daemon state objects from older code versions.
 if (!ds.staleSessionIds) ds.staleSessionIds = new Set<string>()
-if (!ds.connectorRestartState) ds.connectorRestartState = new Map<string, { lastAttemptAt: number; failCount: number; wakeAttempts: number }>()
 if (!ds.openclawDownAgentIds) ds.openclawDownAgentIds = new Set<string>()
 if (!ds.openclawRepairState) ds.openclawRepairState = new Map<string, { attempts: number; lastAttemptAt: number; cooldownUntil: number }>()
 if (ds.lastIntegrityCheckAt === undefined) ds.lastIntegrityCheckAt = null
@@ -132,6 +138,7 @@ if (ds.lastIntegrityDriftCount === undefined) ds.lastIntegrityDriftCount = 0
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 if ((ds as any).issueLastAlertAt) delete (ds as any).issueLastAlertAt
 if (ds.healthIntervalId === undefined) ds.healthIntervalId = null
+if (ds.connectorHealthIntervalId === undefined) ds.connectorHealthIntervalId = null
 if (ds.manualStopRequested === undefined) ds.manualStopRequested = false
 if (ds.memoryConsolidationTimeoutId === undefined) ds.memoryConsolidationTimeoutId = null
 if (ds.memoryConsolidationIntervalId === undefined) ds.memoryConsolidationIntervalId = null
@@ -156,6 +163,7 @@ export function startDaemon(options?: { source?: string; manualStart?: boolean }
     startQueueProcessor()
     startBrowserSweep()
     startHealthMonitor()
+    startConnectorHealthMonitor()
     startHeartbeatService()
     startMemoryConsolidation()
     startEvalScheduler()
@@ -173,6 +181,7 @@ export function startDaemon(options?: { source?: string; manualStart?: boolean }
     startQueueProcessor()
     startBrowserSweep()
     startHealthMonitor()
+    startConnectorHealthMonitor()
     startHeartbeatService()
     startMemoryConsolidation()
     startEvalScheduler()
@@ -201,6 +210,7 @@ export function stopDaemon(options?: { source?: string; manualStop?: boolean })
   stopQueueProcessor()
   stopBrowserSweep()
   stopHealthMonitor()
+  stopConnectorHealthMonitor()
   stopHeartbeatService()
   stopMemoryConsolidation()
   stopEvalScheduler()
@@ -278,7 +288,8 @@ async function sendHealthAlert(text: string) {
 }
 
 async function runConnectorHealthChecks(now: number) {
-  // First, check isAlive() on running instances and attempt reconnection for dead ones
+  // First, collapse dead runtime instances into persisted error state so the
+  // daemon can own the restart cadence and backoff policy.
   try {
     await checkConnectorHealth()
   } catch (err: unknown) {
@@ -289,48 +300,30 @@ async function runConnectorHealthChecks(now: number) {
   for (const connector of Object.values(connectors) as Record<string, unknown>[]) {
     if (!connector?.id || typeof connector.id !== 'string') continue
     if (connector.isEnabled !== true) {
-      ds.connectorRestartState.delete(connector.id)
+      clearReconnectState(connector.id)
       continue
     }
 
     const runtimeStatus = getConnectorStatus(connector.id)
     if (runtimeStatus === 'running') {
-      ds.connectorRestartState.delete(connector.id)
+      clearReconnectState(connector.id)
       continue
     }
 
-    const current = ds.connectorRestartState.get(connector.id) || { lastAttemptAt: 0, failCount: 0, wakeAttempts: 0 }
-    // Backfill wakeAttempts for state objects created before this field existed
-    if (typeof current.wakeAttempts !== 'number') current.wakeAttempts = 0
-
-    // Cap wake attempts — stop retrying after MAX_WAKE_ATTEMPTS consecutive failures
-    if (current.wakeAttempts >= MAX_WAKE_ATTEMPTS) {
-      console.warn(`[health] Connector "${connector.name}" exceeded ${MAX_WAKE_ATTEMPTS} wake attempts — giving up`)
-      connector.status = 'error'
-      connector.lastError = `Auto-restart gave up after ${MAX_WAKE_ATTEMPTS} consecutive failures`
-      connector.updatedAt = Date.now()
-      connectors[connector.id] = connector
-      saveConnectors(connectors)
-      ds.connectorRestartState.delete(connector.id)
-      createNotification({
-        type: 'error',
-        title: `Connector "${connector.name}" failed`,
-        message: `Auto-restart gave up after ${MAX_WAKE_ATTEMPTS} consecutive failures.`,
-        dedupKey: `connector-gave-up:${connector.id}`,
-        entityType: 'connector',
-        entityId: connector.id,
-      })
+    const current = getReconnectState(connector.id)
+      ?? createConnectorReconnectState(
+        { error: typeof connector.lastError === 'string' ? connector.lastError : '' },
+        { initialBackoffMs: CONNECTOR_RESTART_BASE_MS },
+      )
+
+    if (current.exhausted) {
       continue
     }
 
-    const backoffMs = Math.min(
-      CONNECTOR_RESTART_MAX_MS,
-      CONNECTOR_RESTART_BASE_MS * (2 ** Math.min(6, current.failCount)),
-    )
-    if ((now - current.lastAttemptAt) < backoffMs) continue
+    if (current.nextRetryAt > now) continue
 
     // Notify on first detection of a down connector
-    if (current.wakeAttempts === 0) {
+    if (current.attempts === 0) {
       createNotification({
         type: 'warning',
         title: `Connector "${connector.name}" is down`,
@@ -341,24 +334,43 @@ async function runConnectorHealthChecks(now: number) {
       })
     }
 
-    current.lastAttemptAt = now
-    ds.connectorRestartState.set(connector.id, current)
     try {
       await startConnector(connector.id)
-      ds.connectorRestartState.delete(connector.id)
+      clearReconnectState(connector.id)
       await sendHealthAlert(`Connector "${connector.name}" (${connector.platform}) was down and has been auto-restarted.`)
     } catch (err: unknown) {
-      current.failCount += 1
-      current.wakeAttempts += 1
-      ds.connectorRestartState.set(connector.id, current)
       const message = err instanceof Error ? err.message : String(err)
-      console.warn(`[health] Connector auto-restart failed for ${connector.name} (attempt ${current.wakeAttempts}/${MAX_WAKE_ATTEMPTS}): ${message}`)
+      const next = advanceConnectorReconnectState(current, message, now, {
+        initialBackoffMs: CONNECTOR_RESTART_BASE_MS,
+        maxBackoffMs: CONNECTOR_RESTART_MAX_MS,
+        maxAttempts: MAX_WAKE_ATTEMPTS,
+      })
+      setReconnectState(connector.id, next)
+      if (next.exhausted) {
+        console.warn(`[health] Connector "${connector.name}" exceeded ${MAX_WAKE_ATTEMPTS} auto-restart attempts — giving up until the server restarts or the user retries manually`)
+        connector.status = 'error'
+        connector.lastError = `Auto-restart gave up after ${MAX_WAKE_ATTEMPTS} attempts: ${message}`
+        connector.updatedAt = Date.now()
+        connectors[connector.id] = connector
+        saveConnectors(connectors)
+        notify('connectors')
+        createNotification({
+          type: 'error',
+          title: `Connector "${connector.name}" failed`,
+          message: `Auto-restart gave up after ${MAX_WAKE_ATTEMPTS} attempts.`,
+          dedupKey: `connector-gave-up:${connector.id}`,
+          entityType: 'connector',
+          entityId: connector.id,
+        })
+      } else {
+        console.warn(`[health] Connector auto-restart failed for ${connector.name} (attempt ${next.attempts}/${MAX_WAKE_ATTEMPTS}): ${message}`)
+      }
     }
   }
 
   // Purge restart state for connectors that no longer exist in storage
-  for (const id of ds.connectorRestartState.keys()) {
-    if (!connectors[id]) ds.connectorRestartState.delete(id)
+  for (const id of Object.keys(getAllReconnectStates())) {
+    if (!connectors[id] || connectors[id]?.isEnabled !== true) clearReconnectState(id)
   }
 }
 
@@ -776,8 +788,6 @@ async function runHealthChecks() {
 
   if (sessionsDirty) saveSessions(sessions)
 
-  await runConnectorHealthChecks(now)
-
   // Provider reachability checks
   try {
     await runProviderHealthChecks()
@@ -851,6 +861,26 @@ function stopHealthMonitor() {
   }
 }
 
+function startConnectorHealthMonitor() {
+  if (ds.connectorHealthIntervalId) return
+
+  const tick = () => {
+    runConnectorHealthChecks(Date.now()).catch((err) => {
+      console.error('[daemon] Connector health tick failed:', err instanceof Error ? err.message : String(err))
+    })
+  }
+
+  tick()
+  ds.connectorHealthIntervalId = setInterval(tick, CONNECTOR_HEALTH_CHECK_INTERVAL)
+}
+
+function stopConnectorHealthMonitor() {
+  if (ds.connectorHealthIntervalId) {
+    clearInterval(ds.connectorHealthIntervalId)
+    ds.connectorHealthIntervalId = null
+  }
+}
+
 function runConsolidationTick() {
   import('./memory-consolidation').then(({ runDailyConsolidation }) =>
     runDailyConsolidation().then((stats) => {
@@ -951,12 +981,16 @@ function stopEvalScheduler() {
 }
 
 export async function runDaemonHealthCheckNow() {
-  await runHealthChecks()
+  await Promise.all([
+    runHealthChecks(),
+    runConnectorHealthChecks(Date.now()),
+  ])
 }
 
 export function getDaemonStatus() {
   const queue = loadQueue()
   const schedules = loadSchedules()
+  const reconnectStates = Object.values(getAllReconnectStates())
 
   // Find next scheduled task
   let nextScheduled: number | null = null
@@ -985,9 +1019,12 @@ export function getDaemonStatus() {
     heartbeat: getHeartbeatServiceStatus(),
     health: {
       monitorActive: !!ds.healthIntervalId,
+      connectorMonitorActive: !!ds.connectorHealthIntervalId,
       staleSessions: ds.staleSessionIds.size,
-      connectorsInBackoff: ds.connectorRestartState.size,
+      connectorsInBackoff: reconnectStates.filter((state) => !state.exhausted).length,
+      connectorsExhausted: reconnectStates.filter((state) => state.exhausted).length,
       checkIntervalSec: Math.trunc(HEALTH_CHECK_INTERVAL / 1000),
+      connectorCheckIntervalSec: Math.trunc(CONNECTOR_HEALTH_CHECK_INTERVAL / 1000),
       integrity: {
         enabled: loadSettings().integrityMonitorEnabled !== false,
         lastCheckedAt: ds.lastIntegrityCheckAt,

package/src/lib/server/elevenlabs.test.ts

@@ -1,12 +1,61 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
-import { requestElevenLabsMp3Stream, synthesizeElevenLabsMp3 } from './elevenlabs'
+import { requestElevenLabsMp3Stream, resolveElevenLabsConfig, synthesizeElevenLabsMp3 } from './elevenlabs'
+import { loadSettings, saveSettings } from './storage'
 
 describe('elevenlabs helpers', () => {
+  it('prefers agent override first, then settings default, then env fallback', () => {
+    const originalSettings = loadSettings()
+    const originalKey = process.env.ELEVENLABS_API_KEY
+    const originalVoice = process.env.ELEVENLABS_VOICE
+
+    try {
+      saveSettings({
+        ...originalSettings,
+        elevenLabsApiKey: 'settings-key',
+        elevenLabsVoiceId: 'settings-voice',
+      })
+      process.env.ELEVENLABS_API_KEY = 'env-key'
+      process.env.ELEVENLABS_VOICE = 'env-voice'
+
+      assert.deepEqual(resolveElevenLabsConfig('agent-voice'), {
+        apiKey: 'settings-key',
+        voiceId: 'agent-voice',
+      })
+      assert.deepEqual(resolveElevenLabsConfig(null), {
+        apiKey: 'settings-key',
+        voiceId: 'settings-voice',
+      })
+
+      saveSettings({
+        ...originalSettings,
+        elevenLabsApiKey: 'settings-key',
+        elevenLabsVoiceId: null,
+      })
+
+      assert.deepEqual(resolveElevenLabsConfig(undefined), {
+        apiKey: 'settings-key',
+        voiceId: 'env-voice',
+      })
+    } finally {
+      saveSettings(originalSettings)
+      if (originalKey === undefined) delete process.env.ELEVENLABS_API_KEY
+      else process.env.ELEVENLABS_API_KEY = originalKey
+      if (originalVoice === undefined) delete process.env.ELEVENLABS_VOICE
+      else process.env.ELEVENLABS_VOICE = originalVoice
+    }
+  })
+
   it('synthesizeElevenLabsMp3 posts TTS request and returns audio bytes', async () => {
     const originalFetch = global.fetch
+    const originalSettings = loadSettings()
     const originalKey = process.env.ELEVENLABS_API_KEY
     const originalVoice = process.env.ELEVENLABS_VOICE
+    saveSettings({
+      ...originalSettings,
+      elevenLabsApiKey: null,
+      elevenLabsVoiceId: null,
+    })
     process.env.ELEVENLABS_API_KEY = 'test-key'
     process.env.ELEVENLABS_VOICE = 'voice-123'
 
@@ -25,6 +74,7 @@ describe('elevenlabs helpers', () => {
       assert.equal(out.toString('utf8'), 'abc')
     } finally {
       global.fetch = originalFetch
+      saveSettings(originalSettings)
       if (originalKey === undefined) delete process.env.ELEVENLABS_API_KEY
       else process.env.ELEVENLABS_API_KEY = originalKey
       if (originalVoice === undefined) delete process.env.ELEVENLABS_VOICE
@@ -34,14 +84,21 @@ describe('elevenlabs helpers', () => {
 
   it('requestElevenLabsMp3Stream calls streaming endpoint', async () => {
     const originalFetch = global.fetch
+    const originalSettings = loadSettings()
     const originalKey = process.env.ELEVENLABS_API_KEY
     const originalVoice = process.env.ELEVENLABS_VOICE
+    saveSettings({
+      ...originalSettings,
+      elevenLabsApiKey: null,
+      elevenLabsVoiceId: null,
+    })
     process.env.ELEVENLABS_API_KEY = 'test-key'
     process.env.ELEVENLABS_VOICE = 'voice-xyz'
 
     global.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
       assert.equal(String(input), 'https://api.elevenlabs.io/v1/text-to-speech/voice-xyz/stream')
       assert.equal(init?.method, 'POST')
+      assert.equal((init?.headers as Record<string, string>)['xi-api-key'], 'test-key')
       return new Response('stream', { status: 200, headers: { 'Content-Type': 'audio/mpeg' } })
     }) as typeof fetch
 
@@ -51,6 +108,7 @@ describe('elevenlabs helpers', () => {
       assert.equal(await res.text(), 'stream')
     } finally {
       global.fetch = originalFetch
+      saveSettings(originalSettings)
       if (originalKey === undefined) delete process.env.ELEVENLABS_API_KEY
       else process.env.ELEVENLABS_API_KEY = originalKey
       if (originalVoice === undefined) delete process.env.ELEVENLABS_VOICE

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

@@ -12,6 +12,7 @@ import { log } from './logger'
 import { WORKSPACE_DIR } from './data-dir'
 import { drainSystemEvents } from './system-events'
 import { buildIdentityContinuityContext } from './identity-continuity'
+import { buildMainLoopHeartbeatPrompt, isMainSession } from './main-agent-loop'
 import { ensureAgentThreadSession } from './agent-thread-session'
 
 const HEARTBEAT_TICK_MS = 5_000
@@ -434,7 +435,10 @@ async function tickHeartbeats() {
     if (!hasGoal && !heartbeatFileContent && !hasCustomPrompt) {
       continue
     }
-    const heartbeatMessage = buildAgentHeartbeatPrompt(session, agent, cfg.prompt, heartbeatFileContent)
+    const baseHeartbeatMessage = buildAgentHeartbeatPrompt(session, agent, cfg.prompt, heartbeatFileContent)
+    const heartbeatMessage = isMainSession(session)
+      ? buildMainLoopHeartbeatPrompt(session, baseHeartbeatMessage)
+      : baseHeartbeatMessage
 
     const enqueue = enqueueSessionRun({
       sessionId: session.id,