@swarmclawai/swarmclaw 1.3.4 → 1.3.6

package/src/lib/server/memory/dream-cycles.ts

@@ -0,0 +1,49 @@
+import fs from 'fs'
+import path from 'path'
+import { DATA_DIR } from '@/lib/server/data-dir'
+import { hmrSingleton, safeJsonParse } from '@/lib/shared-utils'
+import type { DreamCycle } from '@/types'
+
+const DREAM_CYCLES_PATH = path.join(DATA_DIR, 'dream-cycles.json')
+
+const state = hmrSingleton('__dream_cycles__', () => ({
+  cycles: null as DreamCycle[] | null,
+}))
+
+function ensureLoaded(): DreamCycle[] {
+  if (state.cycles !== null) return state.cycles
+  try {
+    const raw = fs.readFileSync(DREAM_CYCLES_PATH, { encoding: 'utf-8' })
+    state.cycles = safeJsonParse<DreamCycle[]>(raw, [])
+  } catch {
+    state.cycles = []
+  }
+  return state.cycles
+}
+
+function persist(): void {
+  fs.mkdirSync(path.dirname(DREAM_CYCLES_PATH), { recursive: true })
+  fs.writeFileSync(DREAM_CYCLES_PATH, JSON.stringify(ensureLoaded(), null, 2), { encoding: 'utf-8' })
+}
+
+export function saveDreamCycle(cycle: DreamCycle): void {
+  const cycles = ensureLoaded()
+  const idx = cycles.findIndex((c) => c.id === cycle.id)
+  if (idx >= 0) {
+    cycles[idx] = cycle
+  } else {
+    cycles.push(cycle)
+  }
+  persist()
+}
+
+export function listDreamCycles(agentId?: string, limit = 50): DreamCycle[] {
+  const cycles = ensureLoaded()
+  const filtered = agentId ? cycles.filter((c) => c.agentId === agentId) : [...cycles]
+  filtered.sort((a, b) => b.startedAt - a.startedAt)
+  return filtered.slice(0, limit)
+}
+
+export function getDreamCycle(id: string): DreamCycle | null {
+  return ensureLoaded().find((c) => c.id === id) ?? null
+}

package/src/lib/server/memory/dream-idle-callback.ts

@@ -0,0 +1,38 @@
+import { onNextIdleWindow } from '@/lib/server/runtime/idle-window'
+import { loadAgents } from '@/lib/server/storage'
+import { executeDreamCycle, resolveDreamConfig } from './dream-service'
+import { log } from '@/lib/server/logger'
+import { errorMessage } from '@/lib/shared-utils'
+
+const TAG = 'dream-idle'
+let dreamRegistered = false
+
+export function registerDreamIdleCallback(): void {
+  if (dreamRegistered) return
+  dreamRegistered = true
+  onNextIdleWindow(async () => {
+    dreamRegistered = false
+    await runDreamForEligibleAgents()
+    registerDreamIdleCallback()
+  })
+}
+
+async function runDreamForEligibleAgents(): Promise<void> {
+  const agents = loadAgents()
+  const now = Date.now()
+
+  for (const agent of Object.values(agents)) {
+    if (agent.trashedAt) continue
+    if (!agent.dreamEnabled) continue
+
+    const config = resolveDreamConfig(agent)
+    const lastDream = agent.lastDreamAt ?? 0
+    if (lastDream + config.cooldownMinutes * 60_000 >= now) continue
+
+    try {
+      await executeDreamCycle(agent.id, 'idle')
+    } catch (err: unknown) {
+      log.error(TAG, `Dream cycle failed for agent ${agent.id}: ${errorMessage(err)}`)
+    }
+  }
+}

package/src/lib/server/memory/dream-service.ts

@@ -0,0 +1,315 @@
+import crypto from 'crypto'
+import type { DreamCycle, DreamCycleResult, DreamConfig, DreamTrigger, Agent } from '@/types'
+import { DEFAULT_DREAM_CONFIG } from '@/types/dream'
+import { getMemoryDb } from '@/lib/server/memory/memory-db'
+import { saveDreamCycle } from '@/lib/server/memory/dream-cycles'
+import { errorMessage, safeJsonParse } from '@/lib/shared-utils'
+import { log } from '@/lib/server/logger'
+
+const TAG = 'dream-service'
+
+const EXEMPT_CATEGORIES = new Set(['daily_digest', 'consolidated_insight', 'dream_reflection'])
+
+export function resolveDreamConfig(agent: Agent): DreamConfig {
+  return { ...DEFAULT_DREAM_CONFIG, ...agent.dreamConfig }
+}
+
+export async function runTier1Dream(
+  agentId: string,
+  config: DreamConfig,
+): Promise<Partial<DreamCycleResult>> {
+  const memDb = getMemoryDb()
+  const memories = memDb.getByAgent(agentId, 500)
+  const now = Date.now()
+  const decayAgeMs = config.decayAgeDays * 86_400_000
+  const pruneMs = config.pruneThresholdDays * 86_400_000
+
+  let decayed = 0
+  let pruned = 0
+  let promoted = 0
+  const errors: string[] = []
+
+  for (const mem of memories) {
+    // Skip exempt categories
+    if (EXEMPT_CATEGORIES.has(mem.category)) continue
+
+    const tier = (mem.metadata as Record<string, unknown> | undefined)?.tier
+    // Skip archived entries
+    if (tier === 'archive') continue
+
+    const age = now - (mem.createdAt || mem.updatedAt || 0)
+
+    // Decay & Prune: old entries with no engagement
+    if (age > decayAgeMs && (mem.accessCount || 0) === 0 && (mem.reinforcementCount || 0) === 0) {
+      if (tier === 'working' && age > pruneMs) {
+        memDb.delete(mem.id)
+        pruned++
+      } else {
+        memDb.update(mem.id, {
+          metadata: { ...(mem.metadata as Record<string, unknown>), decayedInDream: true },
+        })
+        decayed++
+      }
+      continue
+    }
+
+    // Promote: working-tier entries with high engagement
+    if (
+      (tier === 'working' || tier === '' || tier === undefined) &&
+      (mem.accessCount || 0) >= 3 &&
+      (mem.reinforcementCount || 0) >= 2
+    ) {
+      memDb.update(mem.id, {
+        metadata: { ...(mem.metadata as Record<string, unknown>), tier: 'durable' },
+      })
+      promoted++
+    }
+  }
+
+  // Dedup via maintain
+  let deduped = 0
+  try {
+    const maintenance = memDb.maintain({ dedupe: true, pruneWorking: false })
+    deduped = maintenance.deduped
+  } catch (err: unknown) {
+    const msg = `Dedup maintenance failed: ${errorMessage(err)}`
+    log.warn(TAG, msg)
+    errors.push(msg)
+  }
+
+  return { decayed, pruned, promoted, deduped, errors }
+}
+
+interface Tier2Consolidation {
+  sourceIds: string[]
+  title: string
+  content: string
+}
+
+interface Tier2Reflection {
+  title: string
+  content: string
+}
+
+interface Tier2Flagged {
+  memoryId: string
+  reason: string
+}
+
+interface Tier2Response {
+  consolidations?: Tier2Consolidation[]
+  reflections?: Tier2Reflection[]
+  flagged?: Tier2Flagged[]
+}
+
+export async function runTier2Dream(
+  agentId: string,
+  config: DreamConfig,
+): Promise<Partial<DreamCycleResult>> {
+  const memDb = getMemoryDb()
+  const allMemories = memDb.getByAgent(agentId, config.tier2MaxMemories)
+
+  // Filter to durable tier and non-exempt entries
+  const candidates = allMemories.filter((m) => {
+    if (EXEMPT_CATEGORIES.has(m.category)) return false
+    const tier = (m.metadata as Record<string, unknown> | undefined)?.tier
+    return tier === 'durable' || tier === 'working' || tier === '' || tier === undefined
+  })
+
+  if (candidates.length < 3) {
+    return { consolidated: 0, reflections: [], memoriesReviewed: 0, errors: [] }
+  }
+
+  const memoryLines = candidates.map((m) => {
+    const content = (m.content || '').slice(0, 300)
+    return `[${m.id}] [${m.category}] ${m.title}: ${content}`
+  })
+
+  const prompt = `You are reviewing your memories during a dream cycle to consolidate and reflect.
+
+Review the following memories and respond with a JSON object:
+{
+  "consolidations": [{ "sourceIds": ["id1", "id2"], "title": "...", "content": "..." }],
+  "reflections": [{ "title": "...", "content": "..." }],
+  "flagged": [{ "memoryId": "...", "reason": "..." }]
+}
+
+Rules:
+- Consolidate 2-5 groups of overlapping memories into single entries
+- Write 1-3 high-level reflections about patterns you notice
+- Flag any outdated or contradictory memories
+- Be concise. Each consolidation and reflection should be 1-3 sentences.
+
+MEMORIES:
+${memoryLines.join('\n')}`
+
+  const errors: string[] = []
+  let consolidated = 0
+  const reflectionTitles: string[] = []
+
+  try {
+    const { buildLLM } = await import('@/lib/server/build-llm')
+    const { llm } = await buildLLM({ agentId })
+    const { HumanMessage } = await import('@langchain/core/messages')
+
+    const response = await llm.invoke([new HumanMessage(prompt)])
+    const text = typeof response.content === 'string'
+      ? response.content
+      : Array.isArray(response.content)
+        ? response.content.map((b) => ('text' in b && typeof b.text === 'string' ? b.text : '')).join('')
+        : ''
+
+    // Extract JSON from response (handle markdown code blocks)
+    const jsonMatch = text.match(/\{[\s\S]*\}/)
+    const parsed = safeJsonParse<Tier2Response>(jsonMatch?.[0] ?? '', {})
+
+    // Process consolidations
+    if (Array.isArray(parsed.consolidations)) {
+      for (const c of parsed.consolidations) {
+        if (!c.title || !c.content || !Array.isArray(c.sourceIds)) continue
+        const validSourceIds = c.sourceIds.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)
+        memDb.add({
+          agentId,
+          sessionId: null,
+          category: 'consolidated_insight',
+          title: c.title,
+          content: c.content,
+          linkedMemoryIds: validSourceIds,
+          metadata: { tier: 'durable', origin: 'dream' },
+        })
+        consolidated++
+      }
+    }
+
+    // Process reflections
+    if (Array.isArray(parsed.reflections)) {
+      for (const r of parsed.reflections) {
+        if (!r.title || !r.content) continue
+        memDb.add({
+          agentId,
+          sessionId: null,
+          category: 'dream_reflection',
+          title: r.title,
+          content: r.content,
+          metadata: { tier: 'durable', origin: 'dream' },
+        })
+        reflectionTitles.push(r.title)
+      }
+    }
+
+    // Process flagged
+    if (Array.isArray(parsed.flagged)) {
+      for (const f of parsed.flagged) {
+        if (!f.memoryId || !f.reason) continue
+        const existing = memDb.get(f.memoryId)
+        if (existing) {
+          memDb.update(f.memoryId, {
+            metadata: {
+              ...(existing.metadata as Record<string, unknown>),
+              flaggedInDream: true,
+              flagReason: f.reason,
+            },
+          })
+        }
+      }
+    }
+  } catch (err: unknown) {
+    errors.push(errorMessage(err))
+  }
+
+  return {
+    consolidated,
+    reflections: reflectionTitles,
+    memoriesReviewed: candidates.length,
+    errors,
+  }
+}
+
+export async function executeDreamCycle(
+  agentId: string,
+  trigger: DreamTrigger,
+): Promise<DreamCycle> {
+  const { loadAgents, patchAgent, logActivity } = await import('@/lib/server/storage')
+  const agents = loadAgents()
+  const agent = agents[agentId]
+  if (!agent) throw new Error(`Agent ${agentId} not found`)
+
+  const config = resolveDreamConfig(agent)
+
+  // Check cooldown
+  if (agent.lastDreamAt && Date.now() - agent.lastDreamAt < config.cooldownMinutes * 60_000) {
+    throw new Error('Dream on cooldown')
+  }
+
+  const cycle: DreamCycle = {
+    id: crypto.randomUUID(),
+    agentId,
+    status: 'running',
+    trigger,
+    startedAt: Date.now(),
+  }
+  saveDreamCycle(cycle)
+
+  try {
+    // Tier 1: deterministic server-side operations
+    const tier1 = await runTier1Dream(agentId, config)
+
+    // Tier 2: LLM-driven reflection (optional)
+    let tier2: Partial<DreamCycleResult> = {}
+    if (config.tier2Enabled) {
+      tier2 = await runTier2Dream(agentId, config)
+    }
+
+    const result: DreamCycleResult = {
+      decayed: tier1.decayed ?? 0,
+      pruned: tier1.pruned ?? 0,
+      promoted: tier1.promoted ?? 0,
+      deduped: tier1.deduped ?? 0,
+      consolidated: tier2.consolidated ?? 0,
+      reflections: tier2.reflections ?? [],
+      memoriesReviewed: tier2.memoriesReviewed ?? 0,
+      durationMs: Date.now() - cycle.startedAt,
+      errors: [...(tier1.errors ?? []), ...(tier2.errors ?? [])],
+    }
+
+    cycle.status = 'completed'
+    cycle.completedAt = Date.now()
+    cycle.result = result
+    saveDreamCycle(cycle)
+
+    // Update agent
+    patchAgent(agentId, (current) => {
+      if (!current) return null
+      return {
+        ...current,
+        lastDreamAt: Date.now(),
+        dreamCycleCount: (current.dreamCycleCount || 0) + 1,
+      }
+    })
+
+    logActivity({
+      entityType: 'agent',
+      entityId: agentId,
+      action: 'dream_completed',
+      actor: 'system',
+      summary: `Dream cycle completed: ${result.decayed} decayed, ${result.pruned} pruned, ${result.consolidated} consolidated`,
+    })
+
+    log.info(TAG, `Dream cycle completed for agent ${agentId}`, {
+      trigger,
+      decayed: result.decayed,
+      pruned: result.pruned,
+      promoted: result.promoted,
+      consolidated: result.consolidated,
+    })
+
+    return cycle
+  } catch (err: unknown) {
+    cycle.status = 'failed'
+    cycle.completedAt = Date.now()
+    cycle.error = errorMessage(err)
+    saveDreamCycle(cycle)
+    log.error(TAG, `Dream cycle failed for agent ${agentId}: ${errorMessage(err)}`)
+    throw err
+  }
+}

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

@@ -146,6 +146,20 @@ function metadataNumber(entry: MemoryEntry, key: string): number | null {
   return typeof value === 'number' && Number.isFinite(value) ? value : null
 }
 
+function knowledgeChunkHashScope(category: string, metadata: unknown): string {
+  if (category !== 'knowledge' || !metadata || typeof metadata !== 'object') return category
+  const sourceIdValue = (metadata as Record<string, unknown>).sourceId
+  const sourceId = typeof sourceIdValue === 'string'
+    ? sourceIdValue.trim()
+    : ''
+  if (!sourceId) return category
+  const chunkIndexValue = (metadata as Record<string, unknown>).chunkIndex
+  const chunkIndex = typeof chunkIndexValue === 'number'
+    ? chunkIndexValue
+    : null
+  return `${category}:${sourceId}:${chunkIndex ?? 'legacy'}`
+}
+
 function followUpSalienceMultiplier(entry: MemoryEntry, nowTs: number): number {
   if (entry.category !== 'reflection/open_loop') return 1
   const resolvedAt = metadataNumber(entry, 'resolvedAt')
@@ -664,7 +678,7 @@ function initDb() {
     update: db.prepare(`
       UPDATE memories
       SET agentId=?, sessionId=?, category=?, title=?, content=?, metadata=?, embedding=?,
-          "references"=?, filePaths=?, image=?, imagePath=?, linkedMemoryIds=?, pinned=?, sharedWith=?, updatedAt=?
+          "references"=?, filePaths=?, image=?, imagePath=?, linkedMemoryIds=?, pinned=?, sharedWith=?, contentHash=?, updatedAt=?
       WHERE id=?
     `),
     delete: db.prepare(`DELETE FROM memories WHERE id=?`),
@@ -677,6 +691,13 @@ function initDb() {
     listAll: db.prepare(`SELECT * FROM memories ORDER BY updatedAt DESC LIMIT ?`),
     listByAgent: db.prepare(`SELECT * FROM memories WHERE agentId=? ORDER BY updatedAt DESC LIMIT ?`),
     listByAgentOrShared: db.prepare(`SELECT * FROM memories WHERE agentId=? OR sharedWith LIKE ? ORDER BY updatedAt DESC LIMIT ?`),
+    listByCategoryAll: db.prepare(`SELECT * FROM memories WHERE category=? ORDER BY updatedAt DESC LIMIT ?`),
+    listByCategoryAgentOrShared: db.prepare(`SELECT * FROM memories WHERE category=? AND (agentId=? OR sharedWith LIKE ?) ORDER BY updatedAt DESC LIMIT ?`),
+    listKnowledgeSourceChunks: db.prepare(`
+      SELECT * FROM memories
+      WHERE category='knowledge' AND json_extract(metadata, '$.sourceId') = ?
+      ORDER BY COALESCE(json_extract(metadata, '$.chunkIndex'), 0) ASC, createdAt ASC
+    `),
     listPinnedByAgent: db.prepare(`SELECT * FROM memories WHERE pinned = 1 AND agentId = ? ORDER BY updatedAt DESC LIMIT ?`),
     listPinnedAll: db.prepare(`SELECT * FROM memories WHERE pinned = 1 ORDER BY updatedAt DESC LIMIT ?`),
     search: db.prepare(`
@@ -803,7 +824,7 @@ function initDb() {
       const category = data.category || 'note'
       const title = data.title || 'Untitled'
       const content = data.content || ''
-      const contentHash = computeContentHash(category, content)
+      const contentHash = computeContentHash(knowledgeChunkHashScope(category, data.metadata), content)
 
       // Content-hash dedup: if same content already exists for this agent, reinforce instead of duplicating
       const agentId = data.agentId || null
@@ -896,6 +917,7 @@ function initDb() {
       const now = Date.now()
       const pinnedVal = merged.pinned ? 1 : 0
       const sharedWithVal = Array.isArray(merged.sharedWith) && merged.sharedWith.length ? JSON.stringify(merged.sharedWith) : null
+      const nextContentHash = computeContentHash(knowledgeChunkHashScope(merged.category, merged.metadata), merged.content)
       stmts.update.run(
         merged.agentId || null, merged.sessionId || null,
         merged.category, merged.title, merged.content,
@@ -908,6 +930,7 @@ function initDb() {
         nextLinked.length ? JSON.stringify(nextLinked) : null,
         pinnedVal,
         sharedWithVal,
+        nextContentHash,
         now, id,
       )
 
@@ -1215,6 +1238,18 @@ function initDb() {
       return rows.map(rowToEntry)
     },
 
+    listByCategory(category: string, agentId?: string, limit = 500): MemoryEntry[] {
+      const safeLimit = Math.max(1, Math.min(10_000, Math.trunc(limit)))
+      const rows = agentId
+        ? stmts.listByCategoryAgentOrShared.all(category, agentId, `%"${agentId}"%`, safeLimit) as Record<string, unknown>[]
+        : stmts.listByCategoryAll.all(category, safeLimit) as Record<string, unknown>[]
+      return rows.map(rowToEntry)
+    },
+
+    listKnowledgeSourceChunks(sourceId: string): MemoryEntry[] {
+      return (stmts.listKnowledgeSourceChunks.all(sourceId) as Record<string, unknown>[]).map(rowToEntry)
+    },
+
     listPinned(agentId?: string, limit = 20): MemoryEntry[] {
       const safeLimit = Math.max(1, Math.min(100, Math.trunc(limit)))
       const rows = agentId

package/src/lib/server/protocols/protocol-agent-turn.ts

@@ -48,6 +48,7 @@ import { AGENT_TURN_TIMEOUT_MS, cleanText, now } from '@/lib/server/protocols/pr
 import type { ProtocolAgentTurnResult, ProtocolRunDeps } from '@/lib/server/protocols/protocol-types'
 import { normalizeProtocolRun } from '@/lib/server/protocols/protocol-normalization'
 import { persistChatroomInteractionMemory } from '@/lib/server/chatrooms/chatroom-memory-bridge'
+import { selectKnowledgeCitations } from '@/lib/server/knowledge-sources'
 
 // ---- Zod schema ----
 
@@ -262,6 +263,10 @@ export async function defaultExecuteAgentTurn(params: {
       ])
       const rawText = result.finalResponse || result.fullText || ''
       const text = stripHiddenControlTokens(rawText)
+      const grounding = selectKnowledgeCitations({
+        responseText: text,
+        retrievalTrace: result.knowledgeRetrievalTrace || null,
+      })
       if (text.trim() && !shouldSuppressHiddenControlText(rawText)) {
         appendSyntheticSessionMessage(syntheticSession.id, 'assistant', text)
         // Persist interaction to agent memory (fire-and-forget)
@@ -278,6 +283,8 @@ export async function defaultExecuteAgentTurn(params: {
       return {
         text: cleanText(text, 6_000),
         toolEvents: result.toolEvents || [],
+        citations: grounding.citations,
+        retrievalTrace: grounding.retrievalTrace,
       }
     } catch (err: unknown) {
       lastError = err

package/src/lib/server/protocols/protocol-run-lifecycle.ts

@@ -47,6 +47,13 @@ const protocolExecutionState = hmrSingleton('__swarmclaw_protocol_engine_executi
   pendingRunIds: new Set<string>(),
 }))
 
+function shouldYieldBetweenProtocolSteps(deps?: ProtocolRunDeps): boolean {
+  // Dependency-injected runs are used for deterministic tests and nested orchestration.
+  // Keep the production scheduler cooperative, but let injected executions drain
+  // their step loop without requiring multiple timer turns.
+  return !deps
+}
+
 // ---- Scheduling/Recovery (G10) ----
 
 export function requestProtocolRunExecution(runId: string, deps?: ProtocolRunDeps): boolean {
@@ -54,7 +61,7 @@ export function requestProtocolRunExecution(runId: string, deps?: ProtocolRunDep
   if (!normalizedId) return false
   if (protocolExecutionState.pendingRunIds.has(normalizedId)) return false
   protocolExecutionState.pendingRunIds.add(normalizedId)
-  setTimeout(() => {
+  const invoke = () => {
     void runProtocolRun(normalizedId, deps)
       .catch((err: unknown) => {
         log.warn(TAG, `execution failed for ${normalizedId}: ${errorMessage(err)}`)
@@ -62,7 +69,9 @@ export function requestProtocolRunExecution(runId: string, deps?: ProtocolRunDep
       .finally(() => {
         protocolExecutionState.pendingRunIds.delete(normalizedId)
       })
-  }, 0)
+  }
+  if (deps) queueMicrotask(invoke)
+  else setTimeout(invoke, 0)
   return true
 }
 
@@ -115,8 +124,9 @@ export function wakeProtocolRunFromTaskCompletion(taskId: string, deps?: Protoco
 }
 
 export function ensureProtocolEngineRecovered(deps?: ProtocolRunDeps): void {
-  if (protocolRecoveryState.completed) return
-  protocolRecoveryState.completed = true
+  const bypassCompletedGuard = Boolean(deps)
+  if (!bypassCompletedGuard && protocolRecoveryState.completed) return
+  if (!bypassCompletedGuard) protocolRecoveryState.completed = true
   const runs = Object.values(loadProtocolRuns()).map((entry) => normalizeProtocolRun(entry))
   for (const run of runs) {
     if (run.parentRunId) {
@@ -321,8 +331,11 @@ export async function runProtocolRun(runId: string, deps?: ProtocolRunDeps): Pro
         appendProtocolEvent(run.id, { type: 'failed', summary: `Exceeded maximum step iterations (${MAX_STEP_ITERATIONS}).` }, deps)
         break
       }
-      // Yield between steps so I/O, HTTP responses, and timers can run.
-      await new Promise(r => setTimeout(r, 0))
+      if (shouldYieldBetweenProtocolSteps(deps)) {
+        // Yield between steps in the fire-and-forget runtime so I/O, HTTP responses,
+        // and timers can run.
+        await new Promise(r => setTimeout(r, 0))
+      }
       const latest = loadProtocolRunById(run.id)
       if (!latest) return null
       if (latest.status === 'paused' || latest.status === 'cancelled' || latest.status === 'archived' || latest.status === 'completed') {

package/src/lib/server/protocols/protocol-service.test.ts

@@ -96,6 +96,105 @@ test('protocol-service creates a hidden transcript run and completes a structure
   assert.equal(output.eventTypes.filter((type) => type === 'phase_completed').length, 5)
 })
 
+test('protocol-service persists citations on participant and artifact events when grounded responses are provided', () => {
+  const output = runWithTempDataDir<{
+    participantCitationCounts: number[]
+    artifactCitationCounts: number[]
+    selectorStatuses: string[]
+  }>(`
+    const storageMod = await import('./src/lib/server/storage')
+    const protocolsMod = await import('./src/lib/server/protocols/protocol-service')
+    const storage = storageMod.default || storageMod
+    const protocols = protocolsMod.default || protocolsMod
+
+    storage.upsertStoredItem('agents', 'agentA', {
+      id: 'agentA',
+      name: 'Agent A',
+      provider: 'ollama',
+      model: 'test-model',
+      systemPrompt: 'test',
+      createdAt: 1,
+      updatedAt: 1,
+    })
+
+    const groundedCitation = {
+      sourceId: 'source-1',
+      sourceTitle: 'Gateway Runbook',
+      sourceKind: 'manual',
+      sourceUrl: null,
+      sourceLabel: null,
+      chunkId: 'chunk-1',
+      chunkIndex: 0,
+      chunkCount: 1,
+      charStart: 0,
+      charEnd: 48,
+      sectionLabel: null,
+      snippet: 'Use blue green deployment for gateway changes.',
+      whyMatched: 'Matched query terms: gateway, deployment',
+      score: 0.92,
+    }
+
+    const run = protocols.createProtocolRun({
+      title: 'Grounded structured run',
+      templateId: 'single_agent_structured_run',
+      participantAgentIds: ['agentA'],
+      facilitatorAgentId: 'agentA',
+      autoStart: false,
+    }, { now: () => 1000 })
+
+    await protocols.runProtocolRun(run.id, {
+      now: () => 2000,
+      executeAgentTurn: async ({ phase }) => {
+        if (phase.kind === 'summarize') {
+          return {
+            text: 'Blue green deployment keeps the rollback path simple.',
+            toolEvents: [],
+            citations: [groundedCitation],
+            retrievalTrace: {
+              query: 'gateway deployment',
+              scope: 'source_knowledge',
+              hits: [groundedCitation],
+              retrievedAt: 2000,
+              selectorStatus: 'selected',
+            },
+          }
+        }
+        if (phase.kind === 'round_robin') {
+          return {
+            text: 'Use blue green deployment for the gateway rollout.',
+            toolEvents: [],
+            citations: [groundedCitation],
+            retrievalTrace: {
+              query: 'gateway rollout',
+              scope: 'source_knowledge',
+              hits: [groundedCitation],
+              retrievedAt: 2000,
+              selectorStatus: 'selected',
+            },
+          }
+        }
+        return { text: 'Opened the session.', toolEvents: [] }
+      },
+    })
+
+    const detail = protocols.getProtocolRunDetail(run.id)
+    const participantEvents = (detail?.events || []).filter((event) => event.type === 'participant_response')
+    const artifactEvents = (detail?.events || []).filter((event) => event.type === 'artifact_emitted')
+
+    console.log(JSON.stringify({
+      participantCitationCounts: participantEvents.map((event) => event.citations?.length || 0),
+      artifactCitationCounts: artifactEvents.map((event) => event.citations?.length || 0),
+      selectorStatuses: participantEvents
+        .map((event) => event.retrievalTrace?.selectorStatus)
+        .filter((value) => typeof value === 'string'),
+    }))
+  `, { prefix: 'swarmclaw-protocol-grounding-' })
+
+  assert.deepEqual(output.participantCitationCounts, [1])
+  assert.deepEqual(output.artifactCitationCounts, [1])
+  assert.deepEqual(output.selectorStatuses, [])
+})
+
 test('protocol-service supports custom template CRUD and operator actions', () => {
   const output = runWithTempDataDir<{
     createdTemplateId: string | null