@swarmclawai/swarmclaw 0.6.7 → 0.6.8

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

package/src/lib/server/langgraph-checkpoint.ts

@@ -266,6 +266,16 @@ export class SqliteCheckpointSaver extends BaseCheckpointSaver {
     this.db.prepare(`DELETE FROM langgraph_checkpoints WHERE thread_id = ?`).run(threadId)
     this.db.prepare(`DELETE FROM langgraph_writes WHERE thread_id = ?`).run(threadId)
   }
+
+  async deleteCheckpoint(threadId: string, checkpointId: string): Promise<void> {
+    this.db.prepare(`DELETE FROM langgraph_checkpoints WHERE thread_id = ? AND checkpoint_id = ?`).run(threadId, checkpointId)
+    this.db.prepare(`DELETE FROM langgraph_writes WHERE thread_id = ? AND checkpoint_id = ?`).run(threadId, checkpointId)
+  }
+
+  async deleteCheckpointsAfter(threadId: string, timestamp: number): Promise<void> {
+    this.db.prepare(`DELETE FROM langgraph_checkpoints WHERE thread_id = ? AND created_at > ?`).run(threadId, timestamp)
+    this.db.prepare(`DELETE FROM langgraph_writes WHERE thread_id = ? AND checkpoint_id NOT IN (SELECT checkpoint_id FROM langgraph_checkpoints WHERE thread_id = ?)`).run(threadId, threadId)
+  }
 }
 
 let _saver: SqliteCheckpointSaver | undefined

package/src/lib/server/link-understanding.ts

@@ -0,0 +1,55 @@
+import * as cheerio from 'cheerio'
+import { truncate } from './session-tools/context'
+
+const BARE_LINK_RE = /https?:\/\/\S+/gi
+
+/**
+ * Automatically fetch and summarize links found in user messages.
+ * This aligns SwarmClaw with OpenClaw's proactive link-understanding feature.
+ */
+export async function runLinkUnderstanding(message: string): Promise<string[]> {
+  const links = message.match(BARE_LINK_RE)
+  if (!links || links.length === 0) return []
+
+  const uniqueLinks = Array.from(new Set(links)).slice(0, 3) // Limit to first 3 links
+  const results: string[] = []
+
+  for (const url of uniqueLinks) {
+    try {
+      const res = await fetch(url, {
+        headers: { 'User-Agent': 'Mozilla/5.0 (compatible; SwarmClaw/1.0)' },
+        signal: AbortSignal.timeout(8000),
+      })
+      if (!res.ok) continue
+
+      const contentType = res.headers.get('content-type') || ''
+      if (contentType.includes('text/html')) {
+        const html = await res.text()
+        const $ = cheerio.load(html)
+        
+        // Handle YouTube specifically (OpenClaw favorite)
+        if (url.includes('youtube.com/') || url.includes('youtu.be/')) {
+          const title = $('meta[property="og:title"]').attr('content') || $('title').text()
+          const desc = $('meta[property="og:description"]').attr('content') || ''
+          results.push(`[Link Analysis: YouTube] ${url}\nTitle: ${title}\nDescription: ${desc}`)
+          continue
+        }
+
+        // General web page extraction
+        $('script, style, noscript, nav, footer, header').remove()
+        const title = $('title').text().trim()
+        const main = $('article, main, [role="main"]').first()
+        const bodyText = (main.length ? main.text() : $('body').text())
+          .replace(/\s+/g, ' ')
+          .trim()
+        
+        results.push(`[Link Analysis] ${url}\nTitle: ${title}\nContent: ${truncate(bodyText, 1000)}`)
+      }
+    } catch (err) {
+      // Fail silently for link understanding — don't block the main run
+      console.error(`Link understanding failed for ${url}:`, err)
+    }
+  }
+
+  return results
+}

package/src/lib/server/main-agent-loop.ts

@@ -1,22 +1,40 @@
 import { genId } from '@/lib/id'
 import { z } from 'zod'
 import type { GoalContract, MessageToolEvent } from '@/types'
-import { loadSessions, saveSessions, loadAgents, saveAgents, loadTasks, saveTasks } from './storage'
+import { loadSessions, saveSessions, loadAgents, saveAgents, loadTasks, saveTasks, loadSettings } from './storage'
 import { log } from './logger'
 import { getMemoryDb } from './memory-db'
 import { isProtectedMainSession } from './main-session'
+import { logExecution } from './execution-log'
 import {
   mergeGoalContracts,
   parseGoalContractFromText,
   parseMainLoopPlan,
   parseMainLoopReview,
 } from './autonomy-contract'
-const MAX_PENDING_EVENTS = 40
-const MAX_TIMELINE_EVENTS = 80
+import { buildIdentityContext } from './heartbeat-service'
+
+const MAX_PENDING_EVENTS = 60
+const MAX_TIMELINE_EVENTS = 120
 const EVENT_TTL_MS = 7 * 24 * 60 * 60 * 1000
-const MEMORY_NOTE_MIN_INTERVAL_MS = 90 * 60 * 1000
+const MEMORY_NOTE_MIN_INTERVAL_MS = 30 * 60 * 1000
 const DEFAULT_FOLLOWUP_DELAY_SEC = 45
-const MAX_FOLLOWUP_CHAIN = 6
+const DEFAULT_MAX_FOLLOWUP_CHAIN = 20
+function getMaxFollowupChain(agentId: string | undefined): number {
+  if (agentId) {
+    const agents = loadAgents()
+    const agent = agents[agentId]
+    if (typeof agent?.maxFollowupChain === 'number' && agent.maxFollowupChain > 0) {
+      return Math.min(agent.maxFollowupChain, 100)
+    }
+  }
+  const settings = loadSettings()
+  if (typeof settings?.maxFollowupChain === 'number' && settings.maxFollowupChain > 0) {
+    return Math.min(settings.maxFollowupChain, 100)
+  }
+  return DEFAULT_MAX_FOLLOWUP_CHAIN
+}
+
 const META_LINE_RE = /\[MAIN_LOOP_META\]\s*(\{[^\n]*\})/i
 const AGENT_HEARTBEAT_META_RE = /\[AGENT_HEARTBEAT_META\]\s*(\{[^\n]*\})/i
 const SCREENSHOT_GOAL_HINT = /\b(screenshot|screen shot|snapshot|capture)\b/i
@@ -25,6 +43,14 @@ const SCHEDULE_GOAL_HINT = /\b(schedule|scheduled|every\s+\w+|interval|cron|recu
 const UPLOAD_ARTIFACT_HINT = /(?:sandbox:)?\/api\/uploads\/[^\s)\]]+|https?:\/\/[^\s)\]]+\.(?:png|jpe?g|webp|gif|pdf)\b/i
 const SENT_ARTIFACT_HINT = /\b(sent|shared|uploaded|returned)\b[^.]*\b(screenshot|snapshot|image|file)\b/i
 
+const COMPANION_GOAL_PROMPT = `
+## Identity & Vibe
+You are a persistent companion.
+1. **Identity**: Embody your creature, theme, and vibe. Your emoji is your signature.
+2. **Workspace Context**: Respect the current workspace. Read IDENTITY.md and HEARTBEAT.md if they exist.
+3. **Continuity**: Maintain awareness of the user's long-term journey. Proactively help with open-ended goals without being asked for every step.
+`.trim()
+
 interface MainLoopSessionMessageLike {
   text?: string
 }
@@ -45,13 +71,12 @@ export interface MainLoopTimelineEntry {
   at: number
   source: string
   note: string
-  status?: 'idle' | 'progress' | 'blocked' | 'ok'
+  status?: 'idle' | 'progress' | 'blocked' | 'ok' | 'reflection'
 }
 
 export interface MainLoopState {
   goal: string | null
   goalContract: GoalContract | null
-  status: 'idle' | 'progress' | 'blocked' | 'ok'
   summary: string | null
   nextAction: string | null
   planSteps: string[]
@@ -61,9 +86,12 @@ export interface MainLoopState {
   missionTaskId: string | null
   momentumScore: number
   paused: boolean
+  status: 'idle' | 'progress' | 'blocked' | 'ok'
   autonomyMode: 'assist' | 'autonomous'
   pendingEvents: MainLoopEvent[]
   timeline: MainLoopTimelineEntry[]
+  missionTokens: number
+  missionCostUsd: number
   followupChainCount: number
   metaMissCount: number
   workingMemoryNotes: string[]
@@ -104,6 +132,9 @@ export interface HandleMainLoopRunResultInput {
   resultText: string
   error?: string
   toolEvents?: MessageToolEvent[]
+  inputTokens?: number
+  outputTokens?: number
+  estimatedCost?: number
 }
 
 function toOneLine(value: string, max = 240): string {
@@ -143,7 +174,7 @@ function appendTimeline(
   source: string,
   note: string,
   now = Date.now(),
-  status?: 'idle' | 'progress' | 'blocked' | 'ok',
+  status?: 'idle' | 'progress' | 'blocked' | 'ok' | 'reflection',
 ) {
   const normalizedNote = toOneLine(note, 400)
   if (!normalizedNote) return
@@ -278,6 +309,8 @@ function normalizeState(raw: any, now = Date.now()): MainLoopState {
     autonomyMode: raw?.autonomyMode === 'assist' ? 'assist' : 'autonomous',
     pendingEvents,
     timeline,
+    missionTokens: typeof raw?.missionTokens === 'number' && Number.isFinite(raw.missionTokens) ? raw.missionTokens : 0,
+    missionCostUsd: typeof raw?.missionCostUsd === 'number' && Number.isFinite(raw.missionCostUsd) ? raw.missionCostUsd : 0,
     followupChainCount: clampInt(raw?.followupChainCount, 0, 0, 100),
     metaMissCount: clampInt(raw?.metaMissCount, 0, 0, 100),
     workingMemoryNotes: normalizeStringList(raw?.workingMemoryNotes, 24, 260),
@@ -489,6 +522,7 @@ function upsertMissionTask(session: any, state: MainLoopState, now: number): str
   const statusMap = {
     idle: 'backlog',
     progress: 'running',
+    reflection: 'running',
     blocked: 'failed',
     ok: 'completed',
   } as const
@@ -603,6 +637,9 @@ function maybeStoreMissionMemoryNote(
     state.reviewNote ? `review: ${state.reviewNote}` : '',
     typeof state.reviewConfidence === 'number' ? `review_confidence: ${state.reviewConfidence}` : '',
     state.missionTaskId ? `mission_task_id: ${state.missionTaskId}` : '',
+    typeof state.missionTokens === 'number' ? `mission_tokens: ${state.missionTokens}` : '',
+    typeof state.missionCostUsd === 'number' ? `mission_cost_usd: $${state.missionCostUsd.toFixed(4)}` : '',
+    state.workingMemoryNotes?.length ? `working_notes: ${state.workingMemoryNotes.slice(-5).join('; ')}` : '',
   ].filter(Boolean).join('\n')
 
   try {
@@ -622,20 +659,27 @@ function maybeStoreMissionMemoryNote(
       category: 'mission',
       title,
       content,
-    } as any)
+    })
     state.lastMemoryNoteAt = now
-  } catch (err: any) {
-    appendEvent(state, 'memory_note_error', `Failed to store mission memory note: ${toOneLine(err?.message || String(err), 240)}`, now)
+    logExecution(session.id, 'mission_checkpoint', `Checkpoint: ${toOneLine(state.goal || '', 120)}`, {
+      agentId: session.agentId,
+      detail: { momentumScore: state.momentumScore, followupChainCount: state.followupChainCount, missionTokens: state.missionTokens, missionCostUsd: state.missionCostUsd },
+    })
+  } catch (err: unknown) {
+    appendEvent(state, 'memory_note_error', `Failed to store mission memory note: ${toOneLine(err instanceof Error ? err.message : String(err), 240)}`, now)
   }
 }
 
-function buildFollowupPrompt(state: MainLoopState, opts?: { hasMemoryTool?: boolean }): string {
+function buildFollowupPrompt(state: MainLoopState, opts?: { hasMemoryTool?: boolean; agent?: Record<string, unknown> | null; session?: Record<string, unknown> | null }): string {
   const hasMemoryTool = opts?.hasMemoryTool === true
+  const identityContext = buildIdentityContext(opts?.session, opts?.agent)
   const goal = state.goal || 'No explicit goal yet. Continue with the strongest actionable objective from recent context.'
   const nextAction = state.nextAction || 'Determine the next highest-impact action and execute it.'
   const contractLines = buildGoalContractLines(state)
   return [
     'SWARM_MAIN_AUTO_FOLLOWUP',
+    identityContext,
+    COMPANION_GOAL_PROMPT,
     `Mission goal: ${goal}`,
     `Next action to execute now: ${nextAction}`,
     `Current status: ${state.status}`,
@@ -647,6 +691,9 @@ function buildFollowupPrompt(state: MainLoopState, opts?: { hasMemoryTool?: bool
     state.reviewNote ? `Last review: ${state.reviewNote}` : '',
     buildPendingEventLines(state),
     buildTimelineLines(state),
+    state.planSteps.length === 0 && state.followupChainCount === 0
+      ? 'Before executing, break the mission goal into 3-7 concrete subtasks. Output a [MAIN_LOOP_PLAN] JSON line with your plan, then execute the first step immediately.'
+      : '',
     'Act autonomously. Use available tools to execute work, verify results, and keep momentum.',
     state.autonomyMode === 'assist'
       ? 'Assist mode: execute safe internal analysis by default, and ask before irreversible external side effects (sending messages, purchases, account mutations).'
@@ -673,6 +720,9 @@ export function isMainSession(session: any): boolean {
 
 export function buildMainLoopHeartbeatPrompt(session: any, fallbackPrompt: string): string {
   const now = Date.now()
+  const agents = loadAgents()
+  const agent = session.agentId ? agents[session.agentId] : null
+  const identityContext = buildIdentityContext(session, agent)
   const state = normalizeState(session?.mainLoopState, now)
   const goal = state.goal || inferGoalFromSessionMessages(session) || null
   const hasMemoryTool = Array.isArray(session?.tools) && session.tools.includes('memory')
@@ -684,6 +734,8 @@ export function buildMainLoopHeartbeatPrompt(session: any, fallbackPrompt: strin
 
   return [
     'SWARM_MAIN_MISSION_TICK',
+    identityContext,
+    COMPANION_GOAL_PROMPT,
     `Time: ${new Date(now).toISOString()}`,
     `Mission goal: ${promptGoal}`,
     `Current status: ${state.status}`,
@@ -902,6 +954,10 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       appendTimeline(state, 'user_goal', `Goal updated: ${userGoal}`, now, state.status)
       appendWorkingMemoryNote(state, `goal:${userGoal}`)
       forceMemoryNote = true
+      logExecution(input.sessionId, 'mission_start', `New goal: ${toOneLine(userGoal, 200)}`, {
+        agentId: session.agentId,
+        detail: { goal: userGoal, planSteps: state.planSteps },
+      })
     } else if (userGoalContract?.objective) {
       state.goal = userGoalContract.objective
       state.goalContract = mergeGoalContracts(state.goalContract, userGoalContract)
@@ -909,8 +965,22 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       appendTimeline(state, 'user_goal_contract', `Goal contract updated: ${userGoalContract.objective}`, now, state.status)
       appendWorkingMemoryNote(state, `contract:${userGoalContract.objective}`)
       forceMemoryNote = true
+      logExecution(input.sessionId, 'mission_start', `New goal contract: ${toOneLine(userGoalContract.objective, 200)}`, {
+        agentId: session.agentId,
+        detail: { goal: userGoalContract.objective, contract: userGoalContract, planSteps: state.planSteps },
+      })
     }
     state.followupChainCount = 0
+    state.missionTokens = 0
+    state.missionCostUsd = 0
+  }
+
+  // Accumulate per-mission token/cost tracking
+  if (typeof input.inputTokens === 'number') {
+    state.missionTokens = (state.missionTokens || 0) + input.inputTokens + (input.outputTokens || 0)
+  }
+  if (typeof input.estimatedCost === 'number') {
+    state.missionCostUsd = (state.missionCostUsd || 0) + input.estimatedCost
   }
 
   if (state.paused && input.internal) {
@@ -958,7 +1028,7 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
 
   if (shouldAutoKickFromUserGoal) {
     followup = {
-      message: buildFollowupPrompt(state, { hasMemoryTool }),
+      message: buildFollowupPrompt(state, { hasMemoryTool, agent: session.agentId ? loadAgents()[session.agentId] : null, session }),
       delayMs: 1500,
       dedupeKey: `main-loop-user-kickoff:${input.sessionId}`,
     }
@@ -1020,11 +1090,33 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       )
       consumeEvents(state, meta.consume_event_ids)
 
-      if (meta.follow_up === true && !input.error && !isHeartbeatOk && !state.paused && state.followupChainCount < MAX_FOLLOWUP_CHAIN) {
+      // Budget enforcement: check mission cost against goalContract.budgetUsd
+      const budgetUsd = state.goalContract?.budgetUsd
+      if (typeof budgetUsd === 'number' && budgetUsd > 0 && typeof state.missionCostUsd === 'number') {
+        const usageRatio = state.missionCostUsd / budgetUsd
+        if (usageRatio >= 1.0 && !state.paused) {
+          state.paused = true
+          state.status = 'blocked'
+          appendTimeline(state, 'budget_exceeded', `Mission budget exceeded ($${state.missionCostUsd.toFixed(4)} / $${budgetUsd.toFixed(4)}). Mission paused.`, now, 'blocked')
+          appendEvent(state, 'budget_exceeded', `Budget limit reached: $${state.missionCostUsd.toFixed(4)} of $${budgetUsd.toFixed(4)}`, now)
+          logExecution(input.sessionId, 'budget_warning', `Budget exceeded: $${state.missionCostUsd.toFixed(4)} / $${budgetUsd.toFixed(4)}`, {
+            agentId: session.agentId,
+            detail: { missionCostUsd: state.missionCostUsd, budgetUsd, missionTokens: state.missionTokens },
+          })
+        } else if (usageRatio >= 0.8) {
+          appendEvent(state, 'budget_warning', `Mission approaching budget limit: $${state.missionCostUsd.toFixed(4)} of $${budgetUsd.toFixed(4)} (${Math.round(usageRatio * 100)}%)`, now)
+          logExecution(input.sessionId, 'budget_warning', `Budget at ${Math.round(usageRatio * 100)}%: $${state.missionCostUsd.toFixed(4)} / $${budgetUsd.toFixed(4)}`, {
+            agentId: session.agentId,
+            detail: { missionCostUsd: state.missionCostUsd, budgetUsd, usagePercent: Math.round(usageRatio * 100) },
+          })
+        }
+      }
+
+      if (meta.follow_up === true && !input.error && !isHeartbeatOk && !state.paused && state.followupChainCount < getMaxFollowupChain(session.agentId)) {
         state.followupChainCount += 1
         const delaySec = clampInt(meta.delay_sec, DEFAULT_FOLLOWUP_DELAY_SEC, 5, 900)
         followup = {
-          message: buildFollowupPrompt(state, { hasMemoryTool }),
+          message: buildFollowupPrompt(state, { hasMemoryTool, agent: session.agentId ? loadAgents()[session.agentId] : null, session }),
           delayMs: delaySec * 1000,
           dedupeKey: `main-loop-followup:${input.sessionId}`,
         }
@@ -1034,6 +1126,12 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
       }
       if (state.status === 'ok' || state.status === 'blocked') {
         forceMemoryNote = true
+        if (state.status === 'ok') {
+          logExecution(input.sessionId, 'mission_complete', `Mission completed: ${toOneLine(state.goal || 'unknown', 200)}`, {
+            agentId: session.agentId,
+            detail: { momentumScore: state.momentumScore, followupChainCount: state.followupChainCount, missionTokens: state.missionTokens, missionCostUsd: state.missionCostUsd },
+          })
+        }
       }
     } else if (!isHeartbeatOk && trimmedText) {
       state.metaMissCount = Math.min(100, state.metaMissCount + 1)
@@ -1064,6 +1162,7 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
   state.missionTaskId = upsertMissionTask(session, state, now)
   const shouldWritePeriodicMemory = !!state.summary && state.status === 'progress'
   maybeStoreMissionMemoryNote(session, state, now, input.source, forceMemoryNote || shouldWritePeriodicMemory)
+
   state.momentumScore = computeMomentumScore(state)
 
   state.updatedAt = now

package/src/lib/server/memory-db.ts

@@ -5,6 +5,7 @@ import { createHash } from 'crypto'
 import { genId } from '@/lib/id'
 import type { MemoryEntry, FileReference, MemoryImage, MemoryReference } from '@/types'
 import { getEmbedding, cosineSimilarity, serializeEmbedding, deserializeEmbedding } from './embeddings'
+import { applyMMR } from './mmr'
 import { loadSettings } from './storage'
 import {
   normalizeLinkedMemoryIds,
@@ -23,8 +24,8 @@ const MAX_IMAGE_INPUT_BYTES = 10 * 1024 * 1024 // 10MB
 const IMAGE_EXT_WHITELIST = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.tiff'])
 export const MAX_FTS_QUERY_TERMS = 6
 export const MAX_FTS_TERM_LENGTH = 48
-const MAX_FTS_RESULT_ROWS = 30
-const MAX_MERGED_RESULTS = 50
+const MAX_FTS_RESULT_ROWS = 50
+const MAX_MERGED_RESULTS = 80
 
 export const MEMORY_FTS_STOP_WORDS = new Set([
   'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from', 'how',
@@ -865,9 +866,12 @@ function initDb() {
 
       // Attempt vector search (synchronous — uses cached embedding if available)
       const vectorSimilarityScores = new Map<string, number>()
+      const rawEmbeddings = new Map<string, number[]>()
       let vectorResults: MemoryEntry[] = []
+      let queryEmbeddingResult: number[] | undefined
       try {
         const queryEmbedding = getEmbeddingSync(query)
+        queryEmbeddingResult = queryEmbedding || undefined
         if (queryEmbedding) {
           const rows = agentId
             ? getAllWithEmbeddingsByAgent.all(agentId) as any[]
@@ -877,7 +881,7 @@ function initDb() {
             .map((row) => {
               const emb = deserializeEmbedding(row.embedding)
               const score = cosineSimilarity(queryEmbedding, emb)
-              return { row, score }
+              return { row, score, emb }
             })
             .filter((s) => s.score > 0.3) // relevance threshold
             .sort((a, b) => b.score - a.score)
@@ -886,6 +890,7 @@ function initDb() {
           vectorResults = scored.map((s) => {
             const entry = rowToEntry(s.row)
             vectorSimilarityScores.set(entry.id, s.score)
+            rawEmbeddings.set(entry.id, s.emb)
             return entry
           })
         }
@@ -913,11 +918,17 @@ function initDb() {
         const reinforcement = Math.log((entry.reinforcementCount || 0) + 1) + 1
         const pinnedBoost = entry.pinned ? 1.5 : 1.0
         const salience = similarity * recencyDecay * reinforcement * pinnedBoost
-        return { entry, salience }
+        return { entry, salience, embedding: rawEmbeddings.get(entry.id) }
       })
-      salienceScored.sort((a, b) => b.salience - a.salience)
-
-      const out = salienceScored.slice(0, MAX_MERGED_RESULTS).map((s) => s.entry)
+      
+      // Apply MMR if we have a query embedding, otherwise standard sort
+      let out: MemoryEntry[] = []
+      if (queryEmbeddingResult) {
+        out = applyMMR(queryEmbeddingResult, salienceScored, MAX_MERGED_RESULTS, 0.6) // Lambda 0.6 = favor relevance slightly over diversity
+      } else {
+        salienceScored.sort((a, b) => b.salience - a.salience)
+        out = salienceScored.slice(0, MAX_MERGED_RESULTS).map((s) => s.entry)
+      }
 
       // Bump access counts for returned results (non-blocking)
       if (out.length) {

package/src/lib/server/mmr.ts

@@ -0,0 +1,73 @@
+import { cosineSimilarity } from './embeddings'
+import type { MemoryEntry } from '@/types'
+
+/**
+ * Applies Maximal Marginal Relevance (MMR) to diversify search results.
+ * It balances relevance to the query (salience/similarity) against novelty 
+ * compared to already-selected documents.
+ */
+export function applyMMR(
+  queryEmbedding: number[],
+  candidates: Array<{ entry: MemoryEntry; salience: number; embedding?: number[] }>,
+  limit: number,
+  lambda: number = 0.5
+): MemoryEntry[] {
+  if (candidates.length === 0) return []
+  
+  // Normalize salience to [0, 1] range
+  const maxSalience = Math.max(...candidates.map(c => c.salience))
+  const minSalience = Math.min(...candidates.map(c => c.salience))
+  const salienceRange = maxSalience - minSalience || 1
+
+  const candidatesWithNormalizedSalience = candidates.map(c => ({
+    ...c,
+    normSalience: (c.salience - minSalience) / salienceRange
+  }))
+
+  const selected: typeof candidatesWithNormalizedSalience = []
+  const remaining = [...candidatesWithNormalizedSalience]
+
+  // Debug: uncomment for troubleshooting
+  // console.log(`[mmr] Starting MMR for ${remaining.length} candidates, limit=${limit}, lambda=${lambda}`)
+
+  while (selected.length < limit && remaining.length > 0) {
+    let bestMmrScore = -Infinity
+    let bestIndex = -1
+
+    for (let i = 0; i < remaining.length; i++) {
+      const candidate = remaining[i]
+      
+      let maxSimToSelected = 0
+      if (selected.length > 0 && candidate.embedding) {
+        for (const sel of selected) {
+          if (sel.embedding) {
+            const sim = cosineSimilarity(candidate.embedding, sel.embedding)
+            if (sim > maxSimToSelected) maxSimToSelected = sim
+          }
+        }
+      }
+
+      // MMR Score = Lambda * Relevance - (1 - Lambda) * Diversity (max similarity to selected)
+      const mmrScore = (lambda * candidate.normSalience) - ((1 - lambda) * maxSimToSelected)
+      
+      // DEBUG LOG
+      // console.log(`  Candidate ${candidate.entry.id}: rel=${candidate.normSalience.toFixed(3)}, div_penalty=${maxSimToSelected.toFixed(3)}, mmr=${mmrScore.toFixed(3)}`)
+
+      if (mmrScore > bestMmrScore) {
+        bestMmrScore = mmrScore
+        bestIndex = i
+      }
+    }
+
+    if (bestIndex !== -1) {
+      const picked = remaining[bestIndex]
+      // console.log(`[mmr] Picked ${picked.entry.id} with score ${bestMmrScore.toFixed(3)}`)
+      selected.push(picked)
+      remaining.splice(bestIndex, 1)
+    } else {
+      break
+    }
+  }
+
+  return selected.map(s => s.entry)
+}

package/src/lib/server/orchestrator-lg.ts

@@ -12,6 +12,7 @@ import { getCheckpointSaver } from './langgraph-checkpoint'
 import { notify } from './ws-hub'
 import { pushMainLoopEventToMainSessions } from './main-agent-loop'
 import { buildCurrentDateTimePromptContext } from './prompt-runtime-context'
+import { getPluginManager } from './plugins'
 import { genId } from '@/lib/id'
 import { NON_LANGGRAPH_PROVIDER_IDS } from '@/lib/provider-sets'
 import type { Agent, TaskComment, MessageToolEvent } from '@/types'
@@ -176,6 +177,7 @@ export async function executeLangGraphOrchestrator(
         return `Agent "${agentName}" not found. Available: ${agents.map((a) => a.name).join(', ')}`
       }
       console.log(`[orchestrator-lg] Delegating to ${agent.name}: ${agentTask.slice(0, 80)}`)
+      getPluginManager().runHook('onAgentDelegation', { sourceAgentId: orchestrator.id, targetAgentId: agent.id, task: agentTask })
       const result = await executeSubTaskViaCli(agent, agentTask, sessionId)
       saveMessage(sessionId, 'assistant', `Delegated to ${agent.name}: ${agentTask.slice(0, 100)}`, [{
         name: 'delegate_to_agent',
@@ -623,6 +625,7 @@ export async function resumeLangGraphOrchestrator(
     async ({ agentName, task: agentTask }) => {
       const agent = agents.find((a) => a.name.toLowerCase() === agentName.toLowerCase())
       if (!agent) return `Agent "${agentName}" not found. Available: ${agents.map((a) => a.name).join(', ')}`
+      getPluginManager().runHook('onAgentDelegation', { sourceAgentId: orchestrator.id, targetAgentId: agent.id, task: agentTask })
       const result = await executeSubTaskViaCli(agent, agentTask, sessionId)
       saveMessage(sessionId, 'assistant', `Delegated to ${agent.name}: ${agentTask.slice(0, 100)}`, [{
         name: 'delegate_to_agent',