@swarmclawai/swarmclaw 0.6.7 → 0.7.0

package/src/lib/server/eval/scenarios.ts

@@ -0,0 +1,218 @@
+import type { EvalScenario } from './types'
+
+export const EVAL_SCENARIOS: EvalScenario[] = [
+  {
+    id: 'coding-prime',
+    name: 'Prime Number Function',
+    category: 'coding',
+    description: 'Create and test a function that checks if a number is prime',
+    userMessage: 'Create a function that checks if a number is prime and test it with a few examples including 2, 7, 10, and 97.',
+    expectedBehaviors: [
+      'Writes a correct isPrime function',
+      'Tests with the specified numbers',
+      'Returns correct results for each test case',
+    ],
+    scoringCriteria: [
+      { name: 'uses_shell', weight: 2, evaluator: 'tool_used', expected: 'shell' },
+      { name: 'uses_files', weight: 2, evaluator: 'tool_used', expected: 'files' },
+      { name: 'mentions_prime', weight: 1, evaluator: 'contains', expected: 'prime' },
+      { name: 'tests_number_2', weight: 1, evaluator: 'contains', expected: '2' },
+      { name: 'tests_number_97', weight: 1, evaluator: 'contains', expected: '97' },
+      { name: 'correctness', weight: 3, evaluator: 'llm_judge', expected: 'Did the response correctly implement an isPrime function and test it with 2, 7, 10, and 97, producing correct results (2=prime, 7=prime, 10=not prime, 97=prime)?' },
+    ],
+    timeoutMs: 60_000,
+    tools: ['shell', 'files'],
+  },
+  {
+    id: 'research-frameworks',
+    name: 'Node.js Framework Comparison',
+    category: 'research',
+    description: 'Research and compare top Node.js web frameworks by GitHub stars',
+    userMessage: 'Find the top 3 Node.js web frameworks by GitHub stars and compare them. Include star counts and key differences.',
+    expectedBehaviors: [
+      'Searches the web for framework information',
+      'Identifies at least 3 frameworks (e.g. Express, Next.js, Fastify)',
+      'Provides star counts and meaningful comparison',
+    ],
+    scoringCriteria: [
+      { name: 'uses_web_search', weight: 2, evaluator: 'tool_used', expected: 'web_search' },
+      { name: 'mentions_express', weight: 1, evaluator: 'regex', expected: 'express(\\.js)?' },
+      { name: 'mentions_next', weight: 1, evaluator: 'regex', expected: 'next(\\.js)?' },
+      { name: 'includes_stars', weight: 1, evaluator: 'regex', expected: '\\d+[kK,.]?\\d*\\s*(stars|\\*)' },
+      { name: 'quality', weight: 5, evaluator: 'llm_judge', expected: 'Did the response identify at least 3 Node.js web frameworks, include GitHub star counts, and provide a meaningful comparison of their key differences?' },
+    ],
+    timeoutMs: 90_000,
+    tools: ['web_search', 'web_fetch'],
+  },
+  {
+    id: 'companionship-overwhelmed',
+    name: 'Emotional Support - Overwhelmed',
+    category: 'companionship',
+    description: 'Provide empathetic support when user is overwhelmed with work',
+    userMessage: "I'm feeling overwhelmed with work deadlines. Everything is piling up and I don't know where to start.",
+    expectedBehaviors: [
+      'Acknowledges the feeling of being overwhelmed',
+      'Shows empathy without being dismissive',
+      'Offers actionable suggestions for managing workload',
+    ],
+    scoringCriteria: [
+      { name: 'empathy', weight: 4, evaluator: 'llm_judge', expected: 'Does the response show genuine empathy and acknowledge the user\'s feelings of being overwhelmed without being dismissive or jumping straight to advice?' },
+      { name: 'actionable_advice', weight: 3, evaluator: 'llm_judge', expected: 'Does the response offer practical, actionable suggestions for managing workload or reducing the feeling of being overwhelmed (e.g. prioritization, breaking tasks down, time management)?' },
+      { name: 'appropriate_tone', weight: 3, evaluator: 'llm_judge', expected: 'Is the tone warm, supportive, and human-like rather than clinical, robotic, or overly formal?' },
+    ],
+    timeoutMs: 30_000,
+    tools: [],
+  },
+  {
+    id: 'multi-step-project',
+    name: 'Project Directory Setup',
+    category: 'multi-step',
+    description: 'Create a project directory, write a README, and initialize git',
+    userMessage: "Create a project directory called 'demo-project' in /tmp, write a README.md with a title and description, and initialize a git repository in it.",
+    expectedBehaviors: [
+      'Creates the demo-project directory',
+      'Writes a README.md file with content',
+      'Initializes a git repository',
+    ],
+    scoringCriteria: [
+      { name: 'uses_shell', weight: 2, evaluator: 'tool_used', expected: 'shell' },
+      { name: 'uses_files', weight: 2, evaluator: 'tool_used', expected: 'files' },
+      { name: 'mentions_mkdir', weight: 1, evaluator: 'regex', expected: 'demo-project' },
+      { name: 'mentions_readme', weight: 1, evaluator: 'contains', expected: 'README' },
+      { name: 'mentions_git_init', weight: 1, evaluator: 'contains', expected: 'git init' },
+      { name: 'completeness', weight: 3, evaluator: 'llm_judge', expected: 'Did the response successfully complete all 3 steps: create the demo-project directory, write a README.md with meaningful content, and initialize a git repository?' },
+    ],
+    timeoutMs: 60_000,
+    tools: ['shell', 'files'],
+  },
+  {
+    id: 'memory-store-recall',
+    name: 'Memory Store and Recall',
+    category: 'memory',
+    description: 'Store a fact in memory and demonstrate recall capability',
+    userMessage: 'Remember that my favorite programming language is Rust and I prefer functional programming patterns. Then confirm what you just stored.',
+    expectedBehaviors: [
+      'Uses memory tool to store the information',
+      'Confirms what was stored',
+      'Accurately reflects the stored preferences',
+    ],
+    scoringCriteria: [
+      { name: 'uses_memory', weight: 3, evaluator: 'tool_used', expected: 'memory' },
+      { name: 'mentions_rust', weight: 2, evaluator: 'contains', expected: 'Rust' },
+      { name: 'mentions_functional', weight: 2, evaluator: 'contains', expected: 'functional' },
+      { name: 'confirmation', weight: 3, evaluator: 'llm_judge', expected: 'Did the response confirm storing the user\'s preference for Rust and functional programming, and accurately summarize what was stored?' },
+    ],
+    timeoutMs: 30_000,
+    tools: ['memory'],
+  },
+  {
+    id: 'planning-blog',
+    name: 'Blog Platform Planning',
+    category: 'planning',
+    description: 'Create a detailed plan for building a blog platform',
+    userMessage: 'Build me a detailed plan for a blog platform with posts, comments, and user authentication. Break it into tasks I can work through.',
+    expectedBehaviors: [
+      'Creates structured tasks or a plan',
+      'Covers posts, comments, and authentication',
+      'Breaks work into manageable pieces',
+    ],
+    scoringCriteria: [
+      { name: 'uses_tasks', weight: 2, evaluator: 'tool_used', expected: 'manage_tasks' },
+      { name: 'mentions_posts', weight: 1, evaluator: 'contains', expected: 'post' },
+      { name: 'mentions_comments', weight: 1, evaluator: 'contains', expected: 'comment' },
+      { name: 'mentions_auth', weight: 1, evaluator: 'regex', expected: 'auth(entication|orization)?' },
+      { name: 'plan_quality', weight: 5, evaluator: 'llm_judge', expected: 'Is the plan well-structured with clear, actionable tasks that cover the three main features (posts, comments, user auth)? Are tasks broken into manageable pieces with logical ordering?' },
+    ],
+    timeoutMs: 60_000,
+    tools: ['manage_tasks'],
+  },
+  {
+    id: 'tool-usage-weather',
+    name: 'Web Search - Weather',
+    category: 'tool-usage',
+    description: 'Search the web for current weather information',
+    userMessage: 'Search the web for today\'s weather in London and tell me the temperature and conditions.',
+    expectedBehaviors: [
+      'Uses web search tool',
+      'Reports temperature',
+      'Reports weather conditions',
+    ],
+    scoringCriteria: [
+      { name: 'uses_web_search', weight: 3, evaluator: 'tool_used', expected: 'web_search' },
+      { name: 'mentions_temperature', weight: 2, evaluator: 'regex', expected: '\\d+\\s*[°]?\\s*[CcFf]' },
+      { name: 'mentions_london', weight: 1, evaluator: 'contains', expected: 'London' },
+      { name: 'quality', weight: 4, evaluator: 'llm_judge', expected: 'Did the response provide specific, current weather information for London including temperature and conditions (e.g. sunny, cloudy, rain)?' },
+    ],
+    timeoutMs: 60_000,
+    tools: ['web_search'],
+  },
+  {
+    id: 'coding-fizzbuzz',
+    name: 'FizzBuzz Implementation',
+    category: 'coding',
+    description: 'Write and run a FizzBuzz implementation in Python',
+    userMessage: 'Write a FizzBuzz implementation in Python that prints numbers 1 to 30 and run it.',
+    expectedBehaviors: [
+      'Writes correct FizzBuzz logic',
+      'Runs the code successfully',
+      'Output contains Fizz, Buzz, and FizzBuzz',
+    ],
+    scoringCriteria: [
+      { name: 'uses_shell', weight: 2, evaluator: 'tool_used', expected: 'shell' },
+      { name: 'uses_files', weight: 2, evaluator: 'tool_used', expected: 'files' },
+      { name: 'contains_fizz', weight: 1, evaluator: 'contains', expected: 'Fizz' },
+      { name: 'contains_buzz', weight: 1, evaluator: 'contains', expected: 'Buzz' },
+      { name: 'contains_fizzbuzz', weight: 1, evaluator: 'contains', expected: 'FizzBuzz' },
+      { name: 'correctness', weight: 3, evaluator: 'llm_judge', expected: 'Did the response implement FizzBuzz correctly (multiples of 3 print Fizz, multiples of 5 print Buzz, multiples of both print FizzBuzz) and successfully execute it?' },
+    ],
+    timeoutMs: 60_000,
+    tools: ['shell', 'files'],
+  },
+  {
+    id: 'research-comparison',
+    name: 'LLM Pricing Comparison',
+    category: 'research',
+    description: 'Compare pricing of major LLM models',
+    userMessage: 'Compare the pricing of OpenAI GPT-4o and Anthropic Claude 3.5 Sonnet. Include input and output token costs.',
+    expectedBehaviors: [
+      'Searches for current pricing',
+      'Includes both models',
+      'Reports input and output token costs',
+    ],
+    scoringCriteria: [
+      { name: 'uses_web_search', weight: 2, evaluator: 'tool_used', expected: 'web_search' },
+      { name: 'mentions_gpt4o', weight: 1, evaluator: 'regex', expected: 'GPT-?4[oO]' },
+      { name: 'mentions_claude', weight: 1, evaluator: 'regex', expected: 'Claude\\s*3\\.?5' },
+      { name: 'mentions_pricing', weight: 1, evaluator: 'regex', expected: '\\$\\d+' },
+      { name: 'quality', weight: 5, evaluator: 'llm_judge', expected: 'Did the response provide accurate and specific pricing for both GPT-4o and Claude 3.5 Sonnet, including input and output token costs, with a clear comparison?' },
+    ],
+    timeoutMs: 90_000,
+    tools: ['web_search', 'web_fetch'],
+  },
+  {
+    id: 'multi-step-analyze',
+    name: 'Package.json Analysis',
+    category: 'multi-step',
+    description: 'Read and analyze the current project\'s package.json',
+    userMessage: 'Read the package.json in the current directory and list all dependencies. Group them into regular dependencies and dev dependencies.',
+    expectedBehaviors: [
+      'Reads package.json using shell or files tool',
+      'Lists regular dependencies',
+      'Lists dev dependencies',
+      'Groups them clearly',
+    ],
+    scoringCriteria: [
+      { name: 'uses_shell_or_files', weight: 2, evaluator: 'tool_used', expected: 'shell' },
+      { name: 'mentions_dependencies', weight: 1, evaluator: 'contains', expected: 'dependencies' },
+      { name: 'mentions_dev_deps', weight: 1, evaluator: 'regex', expected: 'dev[Dd]ependencies|dev dependencies' },
+      { name: 'mentions_package_json', weight: 1, evaluator: 'contains', expected: 'package.json' },
+      { name: 'quality', weight: 5, evaluator: 'llm_judge', expected: 'Did the response successfully read package.json, list the dependencies, and clearly group them into regular and dev dependencies?' },
+    ],
+    timeoutMs: 60_000,
+    tools: ['shell', 'files'],
+  },
+]
+
+export function getScenario(id: string): EvalScenario | undefined {
+  return EVAL_SCENARIOS.find(s => s.id === id)
+}

package/src/lib/server/eval/scorer.ts

@@ -0,0 +1,96 @@
+import type { ScoringCriterion, EvalCriterionResult } from './types'
+import type { MessageToolEvent } from '@/types'
+
+export async function scoreCriteria(
+  criteria: ScoringCriterion[],
+  responseText: string,
+  toolEvents: MessageToolEvent[],
+  judgeOpts?: { provider: string; model: string; apiKey: string | null; apiEndpoint?: string | null },
+): Promise<EvalCriterionResult[]> {
+  const results: EvalCriterionResult[] = []
+
+  for (const criterion of criteria) {
+    switch (criterion.evaluator) {
+      case 'contains': {
+        const found = responseText.toLowerCase().includes(criterion.expected.toLowerCase())
+        results.push({
+          criterion: criterion.name,
+          score: found ? criterion.weight : 0,
+          maxScore: criterion.weight,
+          evidence: found ? `Found "${criterion.expected}" in response` : `"${criterion.expected}" not found in response`,
+        })
+        break
+      }
+
+      case 'regex': {
+        const regex = new RegExp(criterion.expected, 'i')
+        const matched = regex.test(responseText)
+        results.push({
+          criterion: criterion.name,
+          score: matched ? criterion.weight : 0,
+          maxScore: criterion.weight,
+          evidence: matched ? `Pattern /${criterion.expected}/i matched` : `Pattern /${criterion.expected}/i did not match`,
+        })
+        break
+      }
+
+      case 'tool_used': {
+        const used = toolEvents.some(e => e.name === criterion.expected)
+        results.push({
+          criterion: criterion.name,
+          score: used ? criterion.weight : 0,
+          maxScore: criterion.weight,
+          evidence: used ? `Tool "${criterion.expected}" was used` : `Tool "${criterion.expected}" was not used`,
+        })
+        break
+      }
+
+      case 'llm_judge': {
+        if (!judgeOpts) {
+          results.push({
+            criterion: criterion.name,
+            score: 0,
+            maxScore: criterion.weight,
+            evidence: 'No judge provider configured; skipped',
+          })
+          break
+        }
+
+        try {
+          const { buildChatModel } = await import('../build-llm')
+          const { HumanMessage } = await import('@langchain/core/messages')
+
+          const llm = buildChatModel({
+            provider: judgeOpts.provider,
+            model: judgeOpts.model,
+            apiKey: judgeOpts.apiKey,
+            apiEndpoint: judgeOpts.apiEndpoint,
+          })
+
+          const judgePrompt = `Rate the following AI response on a scale of 0-10.\n\nCriterion: ${criterion.expected}\n\nResponse:\n${responseText}\n\nReply with ONLY a number 0-10.`
+          const result = await llm.invoke([new HumanMessage(judgePrompt)])
+          const scoreText = typeof result.content === 'string' ? result.content : ''
+          const parsed = parseInt(scoreText.trim(), 10)
+          const rawScore = Number.isFinite(parsed) ? Math.max(0, Math.min(10, parsed)) : 5
+
+          results.push({
+            criterion: criterion.name,
+            score: (rawScore / 10) * criterion.weight,
+            maxScore: criterion.weight,
+            evidence: `LLM judge: ${rawScore}/10`,
+          })
+        } catch (err: unknown) {
+          results.push({
+            criterion: criterion.name,
+            score: 0,
+            maxScore: criterion.weight,
+            evidence: `LLM judge error: ${err instanceof Error ? err.message : String(err)}`,
+          })
+        }
+        break
+      }
+    }
+  }
+
+  return results
+}

package/src/lib/server/eval/store.ts

@@ -0,0 +1,37 @@
+import Database from 'better-sqlite3'
+import path from 'path'
+import type { EvalRun } from './types'
+
+const DB_PATH = path.join(process.cwd(), 'data', 'eval-runs.db')
+
+let db: Database.Database | null = null
+
+function getDb(): Database.Database {
+  if (!db) {
+    db = new Database(DB_PATH)
+    db.pragma('journal_mode = WAL')
+    db.exec(`CREATE TABLE IF NOT EXISTS eval_runs (
+      id TEXT PRIMARY KEY,
+      data TEXT NOT NULL
+    )`)
+  }
+  return db
+}
+
+export function saveEvalRun(run: EvalRun): void {
+  getDb().prepare('INSERT OR REPLACE INTO eval_runs (id, data) VALUES (?, ?)').run(run.id, JSON.stringify(run))
+}
+
+export function getEvalRun(id: string): EvalRun | null {
+  const row = getDb().prepare('SELECT data FROM eval_runs WHERE id = ?').get(id) as { data: string } | undefined
+  return row ? JSON.parse(row.data) as EvalRun : null
+}
+
+export function listEvalRuns(limit = 50): EvalRun[] {
+  const rows = getDb().prepare('SELECT data FROM eval_runs ORDER BY rowid DESC LIMIT ?').all(limit) as { data: string }[]
+  return rows.map(r => JSON.parse(r.data) as EvalRun)
+}
+
+export function listEvalRunsByAgent(agentId: string, limit = 50): EvalRun[] {
+  return listEvalRuns(limit * 2).filter(r => r.agentId === agentId).slice(0, limit)
+}

package/src/lib/server/eval/types.ts

@@ -0,0 +1,48 @@
+export interface ScoringCriterion {
+  name: string
+  weight: number
+  evaluator: 'contains' | 'regex' | 'tool_used' | 'llm_judge'
+  expected: string
+}
+
+export interface EvalScenario {
+  id: string
+  name: string
+  category: 'coding' | 'research' | 'companionship' | 'multi-step' | 'memory' | 'planning' | 'tool-usage' | 'long-lived'
+  description: string
+  userMessage: string
+  expectedBehaviors: string[]
+  scoringCriteria: ScoringCriterion[]
+  timeoutMs: number
+  tools: string[]
+}
+
+export interface EvalRun {
+  id: string
+  scenarioId: string
+  agentId: string
+  status: 'pending' | 'running' | 'completed' | 'failed'
+  startedAt: number
+  endedAt?: number
+  score: number
+  maxScore: number
+  details: EvalCriterionResult[]
+  sessionId?: string
+  error?: string
+}
+
+export interface EvalCriterionResult {
+  criterion: string
+  score: number
+  maxScore: number
+  evidence?: string
+}
+
+export interface EvalSuiteResult {
+  agentId: string
+  totalScore: number
+  maxScore: number
+  percentage: number
+  runs: EvalRun[]
+  completedAt: number
+}

package/src/lib/server/execution-log.ts

@@ -8,14 +8,18 @@ import { genId } from '@/lib/id'
 // ---------------------------------------------------------------------------
 
 export type LogCategory =
-  | 'trigger'       // what kicked off the action
-  | 'decision'      // reasoning / model choice
-  | 'tool_call'     // tool invocation with input
-  | 'tool_result'   // tool output
-  | 'outbound'      // messages sent to users/platforms
-  | 'file_op'       // file read/write/delete with checksums
-  | 'commit'        // git commit activity
-  | 'error'         // errors during execution
+  | 'trigger'            // what kicked off the action
+  | 'decision'           // reasoning / model choice
+  | 'tool_call'          // tool invocation with input
+  | 'tool_result'        // tool output
+  | 'outbound'           // messages sent to users/platforms
+  | 'file_op'            // file read/write/delete with checksums
+  | 'commit'             // git commit activity
+  | 'error'              // errors during execution
+  | 'mission_start'      // new mission/goal started
+  | 'mission_checkpoint' // periodic mission state snapshot
+  | 'mission_complete'   // mission reached ok status
+  | 'budget_warning'     // mission approaching or exceeding budget
 
 export interface ExecutionLogEntry {
   id: string

package/src/lib/server/guardian.ts

@@ -0,0 +1,34 @@
+import { execSync } from 'child_process'
+import path from 'path'
+import fs from 'fs'
+
+/**
+ * OpenClaw Guardian — Auto-Rollback capability.
+ * If an agent fails a task critically and has autoRecovery enabled,
+ * we attempt to roll back the workspace to the last known good state.
+ */
+export function performGuardianRollback(cwd: string): { ok: boolean; reason?: string } {
+  try {
+    const gitDir = path.join(cwd, '.git')
+    if (!fs.existsSync(gitDir)) {
+      return { ok: false, reason: 'Workspace is not a git repository. Cannot rollback.' }
+    }
+
+    // Check if dirty
+    const status = execSync('git status --porcelain', { cwd, encoding: 'utf8' })
+    if (!status.trim()) {
+      return { ok: false, reason: 'Workspace is clean. Nothing to rollback.' }
+    }
+
+    console.log(`[guardian] Auto-recovery triggered in ${cwd}. Rolling back changes...`)
+    
+    // Perform rollback
+    execSync('git reset --hard HEAD', { cwd, encoding: 'utf8' })
+    execSync('git clean -fd', { cwd, encoding: 'utf8' })
+
+    return { ok: true }
+  } catch (err: unknown) {
+    console.error('[guardian] Auto-rollback failed:', err)
+    return { ok: false, reason: `Git operation failed: ${err instanceof Error ? err.message : String(err)}` }
+  }
+}

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

@@ -132,6 +132,45 @@ function readHeartbeatFile(session: any): string {
   return ''
 }
 
+function readIdentityFile(session: Record<string, unknown>): Record<string, string> {
+  try {
+    const filePath = path.join(typeof session.cwd === 'string' ? session.cwd : WORKSPACE_DIR, 'IDENTITY.md')
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf-8')
+      const identity: Record<string, string> = {}
+      for (const line of content.split('\n')) {
+        const cleaned = line.trim().replace(/^\s*-\s*/, '')
+        const colonIndex = cleaned.indexOf(':')
+        if (colonIndex === -1) continue
+        const label = cleaned.slice(0, colonIndex).replace(/[*_]/g, '').trim().toLowerCase()
+        const value = cleaned.slice(colonIndex + 1).replace(/^[*_]+|[*_]+$/g, '').trim()
+        if (value) identity[label] = value
+      }
+      return identity
+    }
+  } catch { /* ignore */ }
+  return {}
+}
+
+export function buildIdentityContext(session: Record<string, unknown> | undefined | null, agent: Record<string, unknown> | undefined | null): string {
+  const fileId = session ? readIdentityFile(session) : {}
+  const name = fileId.name || agent?.name || ''
+  const emoji = fileId.emoji || agent?.emoji || ''
+  const creature = fileId.creature || agent?.creature || ''
+  const vibe = fileId.vibe || agent?.vibe || ''
+  const theme = fileId.theme || agent?.theme || ''
+
+  const lines = []
+  if (name) lines.push(`Name: ${name}`)
+  if (emoji) lines.push(`Emoji: ${emoji}`)
+  if (creature) lines.push(`Creature: ${creature}`)
+  if (vibe) lines.push(`Vibe: ${vibe}`)
+  if (theme) lines.push(`Theme: ${theme}`)
+
+  if (lines.length === 0) return ''
+  return `## Your Identity\n${lines.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
@@ -148,6 +187,7 @@ export function isHeartbeatContentEffectivelyEmpty(content: string | undefined |
 function buildAgentHeartbeatPrompt(session: any, agent: any, fallbackPrompt: string, heartbeatFileContent: string): string {
   if (!agent) return fallbackPrompt
 
+  const identityContext = buildIdentityContext(session, agent)
   // Drain system events accumulated since last heartbeat
   const events = drainSystemEvents(session.id)
   const eventBlock = events.length > 0
@@ -178,7 +218,7 @@ function buildAgentHeartbeatPrompt(session: any, agent: any, fallbackPrompt: str
   return [
     'AGENT_HEARTBEAT_TICK',
     `Time: ${new Date().toISOString()}`,
-    `Agent: ${agent.name}`,
+    identityContext,
     description ? `Description: ${description}` : '',
     eventBlock ? `Events since last heartbeat:\n${eventBlock}` : '',
     dynamicGoal
@@ -202,6 +242,14 @@ function buildAgentHeartbeatPrompt(session: any, agent: any, fallbackPrompt: str
   ].filter(Boolean).join('\n')
 }
 
+function applyMomentumMultiplier(intervalSec: number, momentumScore: number): number {
+  let multiplier = 1.0
+  if (momentumScore >= 80) multiplier = 0.5
+  else if (momentumScore < 40) multiplier = 2.0
+  const adjusted = Math.round(intervalSec * multiplier)
+  return Math.max(30, Math.min(7200, adjusted))
+}
+
 function resolveInterval(obj: Record<string, any>, currentSec: number): number {
   // Prefer heartbeatInterval (duration string) over heartbeatIntervalSec (raw number)
   if (obj.heartbeatInterval !== undefined && obj.heartbeatInterval !== null) {
@@ -347,6 +395,10 @@ async function tickHeartbeats() {
     const cfg = heartbeatConfigForSession(session, settings, agents)
     if (!cfg.enabled) continue
 
+    // Apply momentum-based multiplier to heartbeat interval
+    const momentumScore = session.mainLoopState?.momentumScore ?? 40
+    cfg.intervalSec = applyMomentumMultiplier(cfg.intervalSec, momentumScore)
+
     // For sessions with explicit opt-in, use a shorter idle threshold (just intervalSec * 2).
     // For inherited/global heartbeats, keep the 180s minimum to avoid noisy auto-fire.
     const defaultIdleSec = explicitOptIn