@swarmclawai/swarmclaw 1.3.4 → 1.3.6

package/src/lib/server/protocols/protocol-step-helpers.ts

@@ -502,7 +502,12 @@ export function currentArtifact(run: ProtocolRun): ProtocolRunArtifact | null {
   return run.artifacts[run.artifacts.length - 1] || null
 }
 
-export function appendArtifact(run: ProtocolRun, artifact: ProtocolRunArtifact, deps?: ProtocolRunDeps): ProtocolRun {
+export function appendArtifact(
+  run: ProtocolRun,
+  artifact: ProtocolRunArtifact,
+  deps?: ProtocolRunDeps,
+  options?: { citations?: import('@/types').KnowledgeCitation[] },
+): ProtocolRun {
   const next = persistRun({
     ...run,
     artifacts: [...(run.artifacts || []), artifact],
@@ -518,6 +523,7 @@ export function appendArtifact(run: ProtocolRun, artifact: ProtocolRunArtifact,
     phaseId: artifact.phaseId || null,
     artifactId: artifact.id,
     summary: `Emitted ${artifact.kind.replace(/_/g, ' ')}: ${artifact.title}`,
+    citations: options?.citations,
   }, deps)
   return next
 }

package/src/lib/server/protocols/protocol-step-processors.ts

@@ -97,7 +97,12 @@ export async function collectResponses(
   for (const agentId of current.participantAgentIds) {
     if (responded.has(agentId)) continue
     renewProtocolLease(current.id)
-    let response: { text: string; toolEvents: import('@/types').MessageToolEvent[] }
+    let response: {
+      text: string
+      toolEvents: import('@/types').MessageToolEvent[]
+      citations?: import('@/types').KnowledgeCitation[]
+      retrievalTrace?: import('@/types').KnowledgeRetrievalTrace | null
+    }
     try {
       response = await executeAgentTurn({
         run: current,
@@ -116,7 +121,13 @@ export async function collectResponses(
       response = { text: `[Agent error: ${errMsg}]`, toolEvents: [] }
     }
     responded.add(agentId)
-    cachedResponses.push({ agentId, text: response.text, toolEvents: response.toolEvents })
+    cachedResponses.push({
+      agentId,
+      text: response.text,
+      toolEvents: response.toolEvents,
+      citations: response.citations,
+      retrievalTrace: response.retrievalTrace,
+    })
     current = persistRun({
       ...current,
       phaseState: {
@@ -143,6 +154,7 @@ export async function collectResponses(
         phaseId: phase.id,
         agentId,
         summary: `Captured a response from ${participantAgents[agentId]?.name || agentId}.`,
+        citations: response.citations,
       }, deps)
     }
   }
@@ -163,6 +175,7 @@ export async function collectResponses(
         phaseId: phase.id,
         agentId: response.agentId,
         summary: `Captured an independent response from ${participantAgents[response.agentId]?.name || response.agentId}.`,
+        citations: response.citations,
       }, deps)
     }
     current = persistRun({
@@ -210,7 +223,7 @@ export async function processFacilitatorArtifactPhase(
       ...(result.toolEvents.length > 0 ? { toolEvents: result.toolEvents } : {}),
     }, deps)
   }
-  const updated = appendArtifact(run, artifact, deps)
+  const updated = appendArtifact(run, artifact, deps, { citations: result.citations })
   return finishPhase(updated, phase, deps)
 }
 

package/src/lib/server/protocols/protocol-types.ts

@@ -5,6 +5,8 @@
 import type {
   BoardTask,
   Chatroom,
+  KnowledgeCitation,
+  KnowledgeRetrievalTrace,
   MessageToolEvent,
   ProtocolBranchCase,
   ProtocolPhaseDefinition,
@@ -72,6 +74,8 @@ export interface UpsertProtocolTemplateInput {
 export interface ProtocolAgentTurnResult {
   text: string
   toolEvents: MessageToolEvent[]
+  citations?: KnowledgeCitation[]
+  retrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 export interface ProtocolRunDeps {

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

@@ -1223,9 +1223,14 @@ function stopConnectorHealthMonitor() {
 
 function runConsolidationTick() {
   import('@/lib/server/memory/memory-consolidation').then(({ runDailyConsolidation, registerConsolidationIdleCallback, registerCompactionIdleCallback }) => {
-    // Wire idle-window callbacks so consolidation and compaction run during quiet periods
+    // Wire idle-window callbacks so consolidation, compaction, and dreaming run during quiet periods
     registerConsolidationIdleCallback()
     registerCompactionIdleCallback()
+    import('@/lib/server/memory/dream-idle-callback').then(({ registerDreamIdleCallback }) => {
+      registerDreamIdleCallback()
+    }).catch((err: unknown) => {
+      log.error(TAG, '[daemon] Dream idle callback registration failed:', errorMessage(err))
+    })
 
     return runDailyConsolidation().then((stats) => {
       if (stats.digests > 0 || stats.pruned > 0 || stats.deduped > 0) {

package/src/lib/server/runtime/run-ledger.test.ts

@@ -0,0 +1,120 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
+
+test('buildRetrievalSummary preserves citation count and dedupes source ids', () => {
+  const output = runWithTempDataDir<{
+    empty: unknown
+    summary: { citationCount: number; sourceIds: string[] } | null
+  }>(`
+    const ledgerMod = await import('./src/lib/server/runtime/run-ledger.ts')
+    const ledger = ledgerMod.default || ledgerMod
+
+    const summary = ledger.buildRetrievalSummary([
+      { sourceId: 'source-a' },
+      { sourceId: 'source-a' },
+      { sourceId: 'source-b' },
+    ])
+
+    console.log(JSON.stringify({
+      empty: ledger.buildRetrievalSummary([]),
+      summary,
+    }))
+  `, { prefix: 'swarmclaw-run-ledger-summary-' })
+
+  assert.equal(output.empty, null)
+  assert.deepEqual(output.summary, {
+    citationCount: 3,
+    sourceIds: ['source-a', 'source-b'],
+  })
+})
+
+test('appendPersistedRunEvent stores citations and retrieval traces', () => {
+  const output = runWithTempDataDir<{
+    eventCount: number
+    citationCount: number
+    selectorStatus: string | null
+    sourceIds: string[]
+  }>(`
+    const ledgerMod = await import('./src/lib/server/runtime/run-ledger.ts')
+    const storageMod = await import('./src/lib/server/storage.ts')
+    const ledger = ledgerMod.default || ledgerMod
+    const storage = storageMod.default || storageMod
+
+    ledger.persistRun({
+      id: 'run-grounded',
+      sessionId: 'session-1',
+      source: 'chat',
+      internal: false,
+      mode: 'followup',
+      status: 'completed',
+      messagePreview: 'grounded response',
+      queuedAt: 1,
+      retrievalSummary: null,
+    })
+
+    ledger.appendPersistedRunEvent({
+      runId: 'run-grounded',
+      sessionId: 'session-1',
+      phase: 'status',
+      status: 'completed',
+      citations: [{
+        sourceId: 'source-a',
+        sourceTitle: 'Gateway Runbook',
+        sourceKind: 'manual',
+        sourceUrl: null,
+        sourceLabel: null,
+        chunkId: 'chunk-1',
+        chunkIndex: 0,
+        chunkCount: 1,
+        charStart: 0,
+        charEnd: 42,
+        sectionLabel: null,
+        snippet: 'Use blue green deployment for gateway changes.',
+        whyMatched: 'Matched query terms: gateway, deployment',
+        score: 0.91,
+      }],
+      retrievalTrace: {
+        query: 'gateway deployment',
+        scope: 'source_knowledge',
+        hits: [{
+          sourceId: 'source-a',
+          sourceTitle: 'Gateway Runbook',
+          sourceKind: 'manual',
+          sourceUrl: null,
+          sourceLabel: null,
+          chunkId: 'chunk-1',
+          chunkIndex: 0,
+          chunkCount: 1,
+          charStart: 0,
+          charEnd: 42,
+          sectionLabel: null,
+          snippet: 'Use blue green deployment for gateway changes.',
+          whyMatched: 'Matched query terms: gateway, deployment',
+          score: 0.91,
+        }],
+        retrievedAt: 123,
+        selectorStatus: 'selected',
+      },
+      event: {
+        t: 'md',
+        text: '{"run":{"status":"completed"}}',
+      },
+    })
+
+    const events = Object.values(storage.loadRuntimeRunEvents())
+    const stored = events[0]
+
+    console.log(JSON.stringify({
+      eventCount: events.length,
+      citationCount: Array.isArray(stored?.citations) ? stored.citations.length : 0,
+      selectorStatus: stored?.retrievalTrace?.selectorStatus || null,
+      sourceIds: Array.isArray(stored?.citations) ? stored.citations.map((citation) => citation.sourceId) : [],
+    }))
+  `, { prefix: 'swarmclaw-run-ledger-events-' })
+
+  assert.equal(output.eventCount, 1)
+  assert.equal(output.citationCount, 1)
+  assert.equal(output.selectorStatus, 'selected')
+  assert.deepEqual(output.sourceIds, ['source-a'])
+})

package/src/lib/server/runtime/run-ledger.ts

@@ -1,5 +1,12 @@
 import { genId } from '@/lib/id'
-import type { RunEventRecord, SessionRunRecord, SessionRunStatus, SSEEvent } from '@/types'
+import type {
+  KnowledgeCitation,
+  KnowledgeRetrievalTrace,
+  RunEventRecord,
+  SessionRunRecord,
+  SessionRunStatus,
+  SSEEvent,
+} from '@/types'
 import {
   deleteRuntimeRun,
   deleteRuntimeRunEvent,
@@ -26,6 +33,21 @@ function now(): number {
   return Date.now()
 }
 
+export function buildRetrievalSummary(
+  citations?: KnowledgeCitation[] | null,
+): SessionRunRecord['retrievalSummary'] {
+  if (!Array.isArray(citations) || citations.length === 0) return null
+  const sourceIds = Array.from(new Set(
+    citations
+      .map((citation) => (typeof citation.sourceId === 'string' ? citation.sourceId.trim() : ''))
+      .filter(Boolean),
+  ))
+  return {
+    citationCount: citations.length,
+    sourceIds,
+  }
+}
+
 function summarizeEvent(event: SSEEvent): string | undefined {
   const raw = event.text || event.toolOutput || event.toolInput || event.toolName || ''
   if (!raw) return undefined
@@ -82,6 +104,8 @@ export function appendPersistedRunEvent(input: {
   event: SSEEvent
   timestamp?: number
   summary?: string
+  citations?: KnowledgeCitation[]
+  retrievalTrace?: KnowledgeRetrievalTrace | null
 }): RunEventRecord {
   const timestamp = typeof input.timestamp === 'number' && Number.isFinite(input.timestamp)
     ? Math.trunc(input.timestamp)
@@ -99,6 +123,8 @@ export function appendPersistedRunEvent(input: {
     status: input.status,
     summary: input.summary || summarizeEvent(input.event),
     event: input.event,
+    citations: input.citations,
+    retrievalTrace: input.retrievalTrace || undefined,
   }
   upsertRuntimeRunEvent(record.id, record)
   return record

package/src/lib/server/runtime/session-run-manager/drain.ts

@@ -4,6 +4,7 @@ import { isInternalHeartbeatRun } from '@/lib/server/runtime/heartbeat-source'
 import { notify } from '@/lib/server/ws-hub'
 import { errorMessage } from '@/lib/shared-utils'
 import { handleMainLoopRunResult } from '@/lib/server/agents/main-agent-loop'
+import { buildRetrievalSummary } from '@/lib/server/runtime/run-ledger'
 
 import {
   clearDeferredDrain,
@@ -119,6 +120,7 @@ export async function drainExecution(
       next.run.endedAt = next.run.endedAt || now()
       next.run.error = aborted ? (next.run.error || 'Cancelled') : result.error
       next.run.resultPreview = result.text?.slice(0, 280)
+      next.run.retrievalSummary = buildRetrievalSummary(result.citations)
       if (typeof result.inputTokens === 'number') next.run.totalInputTokens = result.inputTokens
       if (typeof result.outputTokens === 'number') next.run.totalOutputTokens = result.outputTokens
       if (typeof result.estimatedCost === 'number') next.run.estimatedCost = result.estimatedCost
@@ -127,6 +129,9 @@ export async function drainExecution(
         persisted: result.persisted,
         hasText: !!result.text,
         error: next.run.error || null,
+      }, {
+        citations: result.citations,
+        retrievalTrace: result.retrievalTrace,
       })
       log.info('session-run', `Run finished ${next.run.id}`, {
         sessionId: next.run.sessionId,

package/src/lib/server/runtime/session-run-manager/state.ts

@@ -113,6 +113,8 @@ export function persistEventForRun(entry: SessionRunQueueEntry, event: SSEEvent,
   phase?: RunEventRecord['phase']
   status?: SessionRunStatus
   summary?: string
+  citations?: import('@/types').KnowledgeCitation[]
+  retrievalTrace?: import('@/types').KnowledgeRetrievalTrace | null
 }): void {
   if (!shouldPersistRunEvent(event)) return
   appendPersistedRunEvent({
@@ -125,6 +127,8 @@ export function persistEventForRun(entry: SessionRunQueueEntry, event: SSEEvent,
     phase: opts?.phase || 'event',
     status: opts?.status,
     summary: opts?.summary,
+    citations: opts?.citations,
+    retrievalTrace: opts?.retrievalTrace || null,
     event,
   })
 }
@@ -149,7 +153,15 @@ export function emitToSubscribers(entry: SessionRunQueueEntry, event: SSEEvent)
   }
 }
 
-export function emitRunMeta(entry: SessionRunQueueEntry, status: SessionRunStatus, extra?: Record<string, unknown>) {
+export function emitRunMeta(
+  entry: SessionRunQueueEntry,
+  status: SessionRunStatus,
+  extra?: Record<string, unknown>,
+  persist?: {
+    citations?: import('@/types').KnowledgeCitation[]
+    retrievalTrace?: import('@/types').KnowledgeRetrievalTrace | null
+  },
+) {
   const event: SSEEvent = {
     t: 'md',
     text: JSON.stringify({
@@ -163,7 +175,12 @@ export function emitRunMeta(entry: SessionRunQueueEntry, status: SessionRunStatu
       },
     }),
   }
-  persistEventForRun(entry, event, { phase: 'status', status })
+  persistEventForRun(entry, event, {
+    phase: 'status',
+    status,
+    citations: persist?.citations,
+    retrievalTrace: persist?.retrievalTrace || null,
+  })
   for (const send of entry.onEvents) {
     try {
       send(event)

package/src/lib/server/storage-normalization.ts

@@ -507,6 +507,11 @@ function normalizeStoredRecordInner(
       agent.delegationEnabled = false
       agent.heartbeatEnabled = false
     }
+    // Dreaming defaults
+    if (agent.dreamEnabled === undefined) agent.dreamEnabled = false
+    if (agent.dreamConfig === undefined) agent.dreamConfig = null
+    if (agent.lastDreamAt === undefined) agent.lastDreamAt = null
+    if (typeof agent.dreamCycleCount !== 'number') agent.dreamCycleCount = 0
     // Persisted spend rollup defaults
     if (typeof agent.spentMonthlyCents !== 'number') agent.spentMonthlyCents = 0
     if (typeof agent.spentDailyCents !== 'number') agent.spentDailyCents = 0

package/src/lib/server/storage.ts

@@ -22,6 +22,7 @@ import type {
   ExternalAgentRuntime,
   GatewayProfile,
   GuardianCheckpoint,
+  KnowledgeSource,
   LearnedSkill,
   Message,
   ProtocolTemplate,
@@ -126,6 +127,7 @@ const COLLECTIONS = [
   'connectors',
   'documents',
   'document_revisions',
+  'knowledge_sources',
   'webhooks',
   'model_overrides',
   'mcp_servers',
@@ -1429,6 +1431,19 @@ const documentRevisionsStore = createCollectionStore('document_revisions')
 export const loadDocumentRevisions = documentRevisionsStore.load
 export const upsertDocumentRevision = documentRevisionsStore.upsert
 
+// --- Knowledge Sources ---
+const knowledgeSourcesStore = createCollectionStore('knowledge_sources')
+export const loadKnowledgeSources = knowledgeSourcesStore.load as () => Record<string, KnowledgeSource>
+export const saveKnowledgeSources = knowledgeSourcesStore.save as (data: Record<string, KnowledgeSource>) => void
+export const loadKnowledgeSource = knowledgeSourcesStore.loadItem as (id: string) => KnowledgeSource | null
+export const upsertKnowledgeSource = knowledgeSourcesStore.upsert as (id: string, value: KnowledgeSource) => void
+export const upsertKnowledgeSources = knowledgeSourcesStore.upsertMany
+export const patchKnowledgeSource = knowledgeSourcesStore.patch as (
+  id: string,
+  updater: (current: KnowledgeSource | null) => KnowledgeSource | null,
+) => KnowledgeSource | null
+export const deleteKnowledgeSource = knowledgeSourcesStore.deleteItem
+
 // --- Webhooks ---
 const webhooksStore = createCollectionStore('webhooks')
 export const loadWebhooks = webhooksStore.load

package/src/lib/server/test-utils/run-with-temp-data-dir.ts

@@ -10,19 +10,32 @@ export function runWithTempDataDir<T = unknown>(
   script: string,
   options: {
     prefix?: string
+    dataDir?: string
+    workspaceDir?: string
+    browserProfilesDir?: string
   } = {},
 ): T {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), options.prefix || 'swarmclaw-test-'))
-  const workspaceDir = path.join(tempDir, 'workspace')
+  const resolveTempPath = (value: string | undefined, fallback: string): string =>
+    path.isAbsolute(value || '') ? String(value) : path.join(tempDir, value || fallback)
+  const dataDir = resolveTempPath(options.dataDir, '')
+  const workspaceDir = resolveTempPath(options.workspaceDir, 'workspace')
+  const browserProfilesDir = options.browserProfilesDir
+    ? resolveTempPath(options.browserProfilesDir, 'browser-profiles')
+    : null
+
+  fs.mkdirSync(dataDir, { recursive: true })
   fs.mkdirSync(workspaceDir, { recursive: true })
+  if (browserProfilesDir) fs.mkdirSync(browserProfilesDir, { recursive: true })
 
   try {
     const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
       cwd: repoRoot,
       env: {
         ...process.env,
-        DATA_DIR: tempDir,
+        DATA_DIR: dataDir,
         WORKSPACE_DIR: workspaceDir,
+        ...(browserProfilesDir ? { BROWSER_PROFILES_DIR: browserProfilesDir } : {}),
       },
       encoding: 'utf-8',
     })

package/src/stores/slices/ui-slice.ts

@@ -71,6 +71,8 @@ export interface UiSlice {
   setKnowledgeSheetOpen: (open: boolean) => void
   editingKnowledgeId: string | null
   setEditingKnowledgeId: (id: string | null) => void
+  selectedKnowledgeSourceId: string | null
+  setSelectedKnowledgeSourceId: (id: string | null) => void
   knowledgeRefreshKey: number
   triggerKnowledgeRefresh: () => void
   extensionSheetOpen: boolean
@@ -169,6 +171,8 @@ export const createUiSlice: StateCreator<AppState, [], [], UiSlice> = (set, get)
   setKnowledgeSheetOpen: (open) => set({ knowledgeSheetOpen: open }),
   editingKnowledgeId: null,
   setEditingKnowledgeId: (id) => set({ editingKnowledgeId: id }),
+  selectedKnowledgeSourceId: null,
+  setSelectedKnowledgeSourceId: (id) => set({ selectedKnowledgeSourceId: id }),
   knowledgeRefreshKey: 0,
   triggerKnowledgeRefresh: () => set((s) => ({ knowledgeRefreshKey: s.knowledgeRefreshKey + 1 })),
   extensionSheetOpen: false,

package/src/types/agent.ts

@@ -1,6 +1,7 @@
 import type { ProviderId, ProviderType, OllamaMode } from './provider'
 import type { SessionResetMode, IdentityContinuityState } from './session'
 import type { SkillAllowlistMode } from './skill'
+import type { DreamConfig } from './dream'
 
 // --- Agent / Delegation ---
 
@@ -164,6 +165,12 @@ export interface Agent {
   lastSpendRollupAt?: number
   maxFollowupChain?: number
 
+  // Dreaming (idle-time memory consolidation)
+  dreamEnabled?: boolean
+  dreamConfig?: Partial<DreamConfig> | null
+  lastDreamAt?: number | null
+  dreamCycleCount?: number
+
   // Orchestrator Mode
   orchestratorEnabled?: boolean
   orchestratorMission?: string

package/src/types/dream.ts

@@ -0,0 +1,45 @@
+// --- Dreaming (idle-time memory consolidation) ---
+
+export type DreamStatus = 'pending' | 'running' | 'completed' | 'failed'
+export type DreamTrigger = 'idle' | 'manual'
+
+export interface DreamCycleResult {
+  decayed: number
+  pruned: number
+  promoted: number
+  deduped: number
+  consolidated: number
+  reflections: string[]
+  memoriesReviewed: number
+  durationMs: number
+  errors: string[]
+}
+
+export interface DreamCycle {
+  id: string
+  agentId: string
+  status: DreamStatus
+  trigger: DreamTrigger
+  startedAt: number
+  completedAt?: number | null
+  result?: DreamCycleResult | null
+  error?: string | null
+}
+
+export interface DreamConfig {
+  enabled: boolean
+  cooldownMinutes: number
+  decayAgeDays: number
+  pruneThresholdDays: number
+  tier2Enabled: boolean
+  tier2MaxMemories: number
+}
+
+export const DEFAULT_DREAM_CONFIG: DreamConfig = {
+  enabled: true,
+  cooldownMinutes: 360,
+  decayAgeDays: 30,
+  pruneThresholdDays: 90,
+  tier2Enabled: true,
+  tier2MaxMemories: 50,
+}

package/src/types/index.ts

@@ -15,3 +15,4 @@ export * from './approval'
 export * from './misc'
 export * from './goal'
 export * from './swarmdock'
+export * from './dream'

package/src/types/message.ts

@@ -1,4 +1,5 @@
 import type { MessageSource } from './connector'
+import type { KnowledgeCitation, KnowledgeRetrievalTrace } from './misc'
 
 export interface MessageToolEvent {
   name: string
@@ -53,4 +54,6 @@ export interface Message {
   runId?: string
   /** Cached turn semantics used for routing, delegation, and reflection. */
   semantics?: MessageSemanticsSummary
+  citations?: KnowledgeCitation[]
+  retrievalTrace?: KnowledgeRetrievalTrace | null
 }

package/src/types/misc.ts

@@ -469,6 +469,137 @@ export interface MemoryEntry {
   updatedAt: number
 }
 
+export type KnowledgeSourceKind = 'manual' | 'file' | 'url'
+export type KnowledgeSyncStatus = 'ready' | 'syncing' | 'error'
+export type KnowledgeHygieneActionKind = 'sync' | 'reindex' | 'archive' | 'restore' | 'supersede'
+export type KnowledgeHygieneFindingKind = 'stale' | 'duplicate' | 'overlap' | 'broken' | 'archived' | 'superseded'
+
+export interface KnowledgeCitation {
+  sourceId: string
+  sourceTitle: string
+  sourceKind: KnowledgeSourceKind
+  sourceUrl?: string | null
+  sourceLabel?: string | null
+  chunkId: string
+  chunkIndex: number
+  chunkCount: number
+  charStart: number
+  charEnd: number
+  sectionLabel?: string | null
+  snippet: string
+  whyMatched?: string | null
+  score: number
+}
+
+export interface KnowledgeRetrievalTrace {
+  query: string
+  scope: 'source_knowledge'
+  hits: KnowledgeCitation[]
+  retrievedAt: number
+  selectorStatus?: 'not_run' | 'selected' | 'no_match'
+}
+
+export interface KnowledgeSource {
+  id: string
+  kind: KnowledgeSourceKind
+  title: string
+  content?: string | null
+  sourceLabel?: string | null
+  sourceUrl?: string | null
+  sourcePath?: string | null
+  sourceHash?: string | null
+  scope: 'global' | 'agent'
+  agentIds: string[]
+  tags: string[]
+  syncStatus: KnowledgeSyncStatus
+  lastIndexedAt?: number | null
+  lastSyncedAt?: number | null
+  lastError?: string | null
+  archivedAt?: number | null
+  archivedReason?: string | null
+  duplicateOfSourceId?: string | null
+  supersededBySourceId?: string | null
+  maintenanceUpdatedAt?: number | null
+  maintenanceNotes?: string | null
+  nextSyncAt?: number | null
+  lastAutoSyncAt?: number | null
+  chunkCount: number
+  contentLength: number
+  createdAt: number
+  updatedAt: number
+  metadata?: Record<string, unknown>
+}
+
+export interface KnowledgeSearchHit {
+  id: string
+  sourceId: string
+  sourceTitle: string
+  sourceKind: KnowledgeSourceKind
+  sourceUrl?: string | null
+  sourceLabel?: string | null
+  scope: 'global' | 'agent'
+  agentIds: string[]
+  tags: string[]
+  syncStatus: KnowledgeSyncStatus
+  stale: boolean
+  title: string
+  snippet: string
+  content: string
+  chunkIndex: number
+  chunkCount: number
+  charStart: number
+  charEnd: number
+  sectionLabel?: string | null
+  score: number
+  whyMatched?: string | null
+  createdAt: number
+  updatedAt: number
+}
+
+export interface KnowledgeSourceSummary extends KnowledgeSource {
+  stale: boolean
+  topSnippet?: string | null
+  matchCount?: number
+  topScore?: number
+}
+
+export interface KnowledgeSourceDetail {
+  source: KnowledgeSourceSummary
+  chunks: MemoryEntry[]
+}
+
+export interface KnowledgeHygieneFinding {
+  kind: KnowledgeHygieneFindingKind
+  sourceId: string
+  sourceTitle: string
+  relatedSourceId?: string | null
+  relatedSourceTitle?: string | null
+  detail: string
+  createdAt: number
+}
+
+export interface KnowledgeHygieneAction {
+  kind: KnowledgeHygieneActionKind
+  sourceId: string
+  relatedSourceId?: string | null
+  summary: string
+  createdAt: number
+}
+
+export interface KnowledgeHygieneSummary {
+  scannedAt: number
+  counts: {
+    stale: number
+    duplicate: number
+    overlap: number
+    broken: number
+    archived: number
+    superseded: number
+  }
+  findings: KnowledgeHygieneFinding[]
+  recentActions: KnowledgeHygieneAction[]
+}
+
 // --- MCP Servers ---
 
 export type McpTransport = 'stdio' | 'sse' | 'streamable-http'