@swarmclawai/swarmclaw 1.3.3 → 1.3.5

package/src/components/memory/memory-card.tsx

@@ -19,6 +19,8 @@ export function MemoryCard({ entry, active, agentName, agentAvatarSeed, agentAva
   const [now] = useState(() => Date.now())
   const scope = deriveMemoryScope(entry)
   const tier = getMemoryTier(entry)
+  const isDreamOrigin = entry.category === 'dream_reflection'
+    || (entry.metadata as Record<string, unknown> | undefined)?.origin === 'dream'
 
   return (
     <div
@@ -36,6 +38,11 @@ export function MemoryCard({ entry, active, agentName, agentAvatarSeed, agentAva
         <span className="shrink-0 text-[9px] font-700 uppercase tracking-wider text-accent-bright/70 bg-accent-soft px-1.5 py-0.5 rounded-[5px]">
           {entry.category || 'note'}
         </span>
+        {isDreamOrigin && (
+          <span className="shrink-0 text-[9px] font-700 uppercase tracking-wider text-violet-300/70 bg-violet-400/10 px-1.5 py-0.5 rounded-[5px]">
+            dream
+          </span>
+        )}
         {entry.pinned && (
           <svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor" className="shrink-0 text-amber-400/80">
             <path d="M16 2l-4 4-4-4-2 2 4 4-5 5v1h1l5-5 4 4 2-2-4-4 4-4z" transform="rotate(45 12 12)" />

package/src/components/memory/memory-detail.tsx

@@ -175,6 +175,19 @@ export function MemoryDetail() {
   const inputClass = "w-full px-4 py-3 rounded-[12px] border border-white/[0.06] bg-white/[0.02] text-text outline-none transition-all duration-200 placeholder:text-text-3/70 focus:border-accent-bright/20 focus:bg-white/[0.03]"
   const refs = entry.references || []
   const showRefsCollapse = refs.length > 3
+  const entryMeta = entry.metadata && typeof entry.metadata === 'object'
+    ? entry.metadata as Record<string, unknown>
+    : {}
+  const knowledgeSourceId = typeof entryMeta.sourceId === 'string' ? entryMeta.sourceId : null
+  const knowledgeSourceTitle = typeof entryMeta.sourceTitle === 'string' ? entryMeta.sourceTitle : null
+  const knowledgeSourceKind = typeof entryMeta.sourceKind === 'string' ? entryMeta.sourceKind : null
+  const knowledgeSourceLabel = typeof entryMeta.sourceLabel === 'string' ? entryMeta.sourceLabel : null
+  const knowledgeSourceUrl = typeof entryMeta.sourceUrl === 'string' ? entryMeta.sourceUrl : null
+  const knowledgeChunkIndex = typeof entryMeta.chunkIndex === 'number' ? entryMeta.chunkIndex : null
+  const knowledgeChunkCount = typeof entryMeta.chunkCount === 'number' ? entryMeta.chunkCount : null
+  const knowledgeSectionLabel = typeof entryMeta.sectionLabel === 'string' ? entryMeta.sectionLabel : null
+  const knowledgeCharStart = typeof entryMeta.charStart === 'number' ? entryMeta.charStart : null
+  const knowledgeCharEnd = typeof entryMeta.charEnd === 'number' ? entryMeta.charEnd : null
 
   return (
     <div className="flex-1 flex flex-col h-full min-h-0">
@@ -438,6 +451,33 @@ export function MemoryDetail() {
                 {entry.content || '(empty)'}
               </div>
 
+              {knowledgeSourceId && (
+                <div className="rounded-[14px] border border-white/[0.06] bg-white/[0.02] px-4 py-3">
+                  <label className="block text-[11px] font-600 text-text-3/60 uppercase tracking-[0.06em] mb-2">Source</label>
+                  <div className="space-y-1.5">
+                    <p className="text-[13px] text-text-2">
+                      {knowledgeSourceTitle || entry.title}
+                      {knowledgeSourceKind ? ` • ${knowledgeSourceKind}` : ''}
+                    </p>
+                    {knowledgeSourceLabel && (
+                      <p className="text-[12px] text-text-3/65">{knowledgeSourceLabel}</p>
+                    )}
+                    {knowledgeSourceUrl && (
+                      <a href={knowledgeSourceUrl} target="_blank" rel="noreferrer" className="text-[12px] text-accent-bright hover:underline break-all">
+                        {knowledgeSourceUrl}
+                      </a>
+                    )}
+                    <p className="text-[11px] text-text-3/55">
+                      {knowledgeChunkIndex != null && knowledgeChunkCount != null
+                        ? `Chunk ${knowledgeChunkIndex + 1} of ${knowledgeChunkCount}`
+                        : 'Source-backed knowledge'}
+                      {knowledgeSectionLabel ? ` • ${knowledgeSectionLabel}` : ''}
+                      {knowledgeCharStart != null && knowledgeCharEnd != null ? ` • chars ${knowledgeCharStart}-${knowledgeCharEnd}` : ''}
+                    </p>
+                  </div>
+                </div>
+              )}
+
               {/* Shared with (read mode) */}
               {entry.sharedWith && entry.sharedWith.length > 0 && (
                 <div>
@@ -575,6 +615,12 @@ export function MemoryDetail() {
                     <span className="text-text-3/70 block mb-1">Tier</span>
                     <span className="text-text-3/60 font-mono">{tier}</span>
                   </div>
+                  {knowledgeSourceId && (
+                    <div>
+                      <span className="text-text-3/70 block mb-1">Knowledge Source</span>
+                      <span className="text-text-3/60 font-mono">{knowledgeSourceId}</span>
+                    </div>
+                  )}
                   {entry.sessionId && (
                     <div>
                       <span className="text-text-3/70 block mb-1">Chat</span>

package/src/components/runs/run-list.tsx

@@ -8,6 +8,7 @@ import { BottomSheet } from '@/components/shared/bottom-sheet'
 import type { RunEventRecord, SessionRunRecord, SessionRunStatus } from '@/types'
 import { PageLoader } from '@/components/ui/page-loader'
 import { formatElapsed } from '@/lib/format-display'
+import { GroundingPanel } from '@/components/knowledge/grounding-panel'
 
 const STATUS_COLORS: Record<SessionRunStatus, { bg: string; text: string }> = {
   queued: { bg: 'bg-yellow-500/10', text: 'text-yellow-400' },
@@ -84,6 +85,10 @@ export function RunList() {
   }, [])
 
   const filtered = statusFilter ? runs.filter((r) => r.status === statusFilter) : runs
+  const selectedResultGrounding = selectedEvents
+    .slice()
+    .reverse()
+    .find((event) => event.phase === 'status' && ((event.citations?.length || 0) > 0 || event.retrievalTrace?.hits?.length))
 
   if (loading) {
     return <PageLoader label="Loading runs..." />
@@ -240,6 +245,15 @@ export function RunList() {
                 <pre className="text-[11px] text-text-3/80 font-mono whitespace-pre-wrap break-all bg-white/[0.02] rounded-[12px] p-4 max-h-[200px] overflow-auto border border-white/[0.04]">
                   {selected.resultPreview}
                 </pre>
+                {selectedResultGrounding && (
+                  <div className="mt-3">
+                    <GroundingPanel
+                      citations={selectedResultGrounding.citations}
+                      retrievalTrace={selectedResultGrounding.retrievalTrace}
+                      compact
+                    />
+                  </div>
+                )}
               </div>
             )}
 
@@ -262,6 +276,15 @@ export function RunList() {
                         <div className="text-[11px] text-text-2 whitespace-pre-wrap break-words">
                           {event.summary || event.event.text || event.event.toolOutput || event.event.toolName || event.event.t}
                         </div>
+                        {(event.citations?.length || event.retrievalTrace?.hits?.length) ? (
+                          <div className="mt-2">
+                            <GroundingPanel
+                              citations={event.citations}
+                              retrievalTrace={event.retrievalTrace}
+                              compact
+                            />
+                          </div>
+                        ) : null}
                       </div>
                     ))}
                   </div>

package/src/lib/providers/cli-utils.ts

@@ -8,6 +8,7 @@
 
 import fs from 'fs'
 import os from 'os'
+import { findBinaryOnPath } from '../server/session-tools/context'
 import path from 'path'
 import { spawnSync, type ChildProcess } from 'child_process'
 import { log } from '../server/logger'
@@ -63,10 +64,8 @@ function getNvmBinaryPaths(name: string): string[] {
  * then falls back to known paths + nvm paths.
  */
 export function resolveCliBinary(name: string, extraPaths?: string[]): string | null {
-  // Lazy import to avoid circular dependency at module load
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { findBinaryOnPath } = require('../server/session-tools/context')
-  const fromPath = findBinaryOnPath(name) as string | null
+  const fromPath = findBinaryOnPath(name)
+
   if (fromPath) return fromPath
 
   const paths = [

package/src/lib/providers/index.ts

@@ -11,6 +11,8 @@ import { errorMessage, sleep, jitteredBackoff } from '@/lib/shared-utils'
 import { classifyProviderError } from './error-classification'
 import { log } from '@/lib/server/logger'
 import type { ProviderInfo, ProviderConfig as CustomProviderConfig, ProviderType, ProviderId } from '../../types'
+import { loadProviderConfigs, loadModelOverrides, loadStoredItem, loadCredentials, decryptKey } from '@/lib/server/storage'
+import { getExtensionManager } from '@/lib/server/extensions'
 
 const TAG = 'providers'
 
@@ -289,8 +291,6 @@ export const PROVIDERS: Record<string, BuiltinProviderConfig> = {
 /** Merge built-in providers with custom providers from storage */
 function getCustomProviders(): Record<string, CustomProviderConfig> {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { loadProviderConfigs } = require('../server/storage') as typeof import('@/lib/server/storage')
     const configs = loadProviderConfigs() as Record<string, CustomProviderConfig>
     return Object.fromEntries(
       Object.entries(configs).filter(([, config]) => config?.type === 'custom'),
@@ -303,8 +303,6 @@ function getCustomProviders(): Record<string, CustomProviderConfig> {
 
 function getModelOverrides(): Record<string, string[]> {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { loadModelOverrides } = require('../server/storage') as typeof import('@/lib/server/storage')
     return loadModelOverrides()
   } catch {
     return {}
@@ -342,17 +340,15 @@ export function getProviderList(): ProviderInfo[] {
 
   let extensionProviders: ProviderInfo[] = []
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { getExtensionManager } = require('../server/extensions')
-    extensionProviders = getExtensionManager().getProviders().map((p: Record<string, unknown>) => ({
-      id: String(p.id) as ProviderId,
-      name: String(p.name),
-      models: p.models as string[],
-      defaultModels: p.models as string[],
-      supportsModelDiscovery: Boolean(p.supportsModelDiscovery),
-      requiresApiKey: Boolean(p.requiresApiKey),
-      requiresEndpoint: Boolean(p.requiresEndpoint),
-      defaultEndpoint: p.defaultEndpoint as string | undefined,
+    extensionProviders = getExtensionManager().getProviders().map((p) => ({
+      id: p.id as ProviderId,
+      name: p.name,
+      models: p.models,
+      defaultModels: p.models,
+      supportsModelDiscovery: false,
+      requiresApiKey: p.requiresApiKey,
+      requiresEndpoint: p.requiresEndpoint,
+      defaultEndpoint: p.defaultEndpoint,
     }))
   } catch { /* ignore if running somewhere extensions aren't available */ }
 
@@ -391,8 +387,6 @@ export function getProvider(id: string): BuiltinProviderConfig | null {
   // Fallback: direct single-item DB lookup for custom-* providers
   if (id.startsWith('custom-') && !custom) {
     try {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      const { loadStoredItem } = require('../server/storage') as typeof import('@/lib/server/storage')
       const directConfig = loadStoredItem('provider_configs', id) as CustomProviderConfig | null
       if (directConfig?.type === 'custom' && directConfig.isEnabled) {
         log.info(TAG, `Resolved custom provider '${id}' via direct DB lookup (batch load missed it)`)
@@ -405,10 +399,8 @@ export function getProvider(id: string): BuiltinProviderConfig | null {
 
   // Check Extension Providers
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { getExtensionManager } = require('../server/extensions')
     const extensionProviders = getExtensionManager().getProviders()
-    const found = extensionProviders.find((p: Record<string, unknown>) => p.id === id)
+    const found = extensionProviders.find((p) => p.id === id)
     if (found) {
       return {
         id: found.id as ProviderId,
@@ -455,8 +447,6 @@ export async function streamChatWithFailover(
       let apiKey: string | null = opts.apiKey || null
       if (credId && i > 0) {
         // Need to decrypt fallback credential
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { loadCredentials, decryptKey } = require('../server/storage') as typeof import('@/lib/server/storage')
         const creds = loadCredentials()
         const cred = creds[credId]
         if (cred?.encryptedKey) {

package/src/lib/providers/openclaw.ts

@@ -8,6 +8,7 @@ import type { Agent } from '@/types'
 import { deriveOpenClawWsUrl } from '@/lib/openclaw/openclaw-endpoint'
 import { normalizeOpenClawAgentId } from '@/lib/openclaw/openclaw-agent-id'
 import { loadAgents } from '../server/storage'
+import { getSharedDeviceToken } from '../server/openclaw/sync'
 import {
   resolveOpenClawGatewayAgentIdFromList,
   type OpenClawGatewayAgentSummary,
@@ -74,8 +75,6 @@ function tryLoadIdentityFile(filePath: string): DeviceIdentity | null {
 function loadOrCreateDeviceIdentity(): DeviceIdentity {
   // 0. Check shared device token for cross-synced identity
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { getSharedDeviceToken } = require('../server/openclaw/sync')
     const sharedToken = getSharedDeviceToken()
     if (sharedToken) {
       // Shared token exists — the connector has already paired.

package/src/lib/server/agents/subagent-swarm.ts

@@ -17,6 +17,7 @@ import { logActivity } from '@/lib/server/activity/activity-log'
 import { createNotification } from '@/lib/server/create-notification'
 import { notify } from '@/lib/server/ws-hub'
 import { loadAgents } from '@/lib/server/agents/agent-repository'
+import { upsertStoredItem, loadStoredItem, loadCollection } from '../storage'
 import {
   spawnSubagent,
   type SubagentContext,
@@ -159,8 +160,6 @@ function notifySwarmChanged() {
 
 function persistSwarmSnapshot(swarm: SwarmHandle): void {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { upsertStoredItem } = require('../storage')
     upsertStoredItem('swarm_snapshots', swarm.swarmId, {
       swarmId: swarm.swarmId,
       parentSessionId: swarm.parentSessionId,
@@ -549,8 +548,6 @@ export function getSwarmSnapshot(swarmId: string): SwarmSnapshot | null {
   if (swarm) return buildSwarmSnapshot(swarm)
   // Fallback to persisted store for swarms from previous process lifetimes
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { loadStoredItem } = require('../storage')
     const persisted = loadStoredItem('swarm_snapshots', swarmId)
     return persisted ? (persisted as SwarmSnapshot) : null
   } catch { return null }
@@ -640,9 +637,7 @@ function buildSwarmSnapshot(swarm: SwarmHandle): SwarmSnapshot {
  */
 export function restoreSwarmRegistry(): number {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { loadCollection, upsertStoredItem } = require('../storage')
-    const persisted = loadCollection('swarm_snapshots') as Record<string, SwarmSnapshot>
+    const persisted = loadCollection('swarm_snapshots') as unknown as Record<string, SwarmSnapshot>
     let lost = 0
     for (const [id, record] of Object.entries(persisted)) {
       if (swarmRegistry.has(id)) continue

package/src/lib/server/api-routes.test.ts

@@ -78,9 +78,16 @@ function parseKnowledgeQueryParams(url: string) {
   const q = searchParams.get('q')
   const tagsParam = searchParams.get('tags')
   const limitParam = searchParams.get('limit')
+  const includeArchivedParam = searchParams.get('includeArchived')
   const tags = tagsParam ? tagsParam.split(',').map((t) => t.trim()).filter(Boolean) : undefined
   const limit = limitParam ? Math.max(1, Math.min(500, Number.parseInt(limitParam, 10) || 50)) : undefined
-  return { q, tags, limit }
+  const normalizedIncludeArchived = typeof includeArchivedParam === 'string'
+    ? includeArchivedParam.trim().toLowerCase()
+    : ''
+  const includeArchived = normalizedIncludeArchived === '1'
+    || normalizedIncludeArchived === 'true'
+    || normalizedIncludeArchived === 'yes'
+  return { q, tags, limit, includeArchived }
 }
 
 // ---------------------------------------------------------------------------
@@ -91,7 +98,12 @@ const thisFile = new URL(import.meta.url).pathname
 const routeDir = path.resolve(path.dirname(thisFile), '../../app/api')
 
 function readRoute(...segments: string[]): string {
-  return fs.readFileSync(path.join(routeDir, ...segments), 'utf-8')
+  const direct = path.join(routeDir, ...segments)
+  if (fs.existsSync(direct)) {
+    return fs.readFileSync(direct, 'utf-8')
+  }
+  const withTs = direct.endsWith('.ts') ? direct : `${direct}.ts`
+  return fs.readFileSync(withTs, 'utf-8')
 }
 
 // ===========================================================================
@@ -225,6 +237,12 @@ describe('Knowledge API contract', () => {
     it('returns undefined limit when param is absent', () => {
       assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge').limit, undefined)
     })
+
+    it('parses includeArchived as a boolean flag', () => {
+      assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge?includeArchived=true').includeArchived, true)
+      assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge?includeArchived=1').includeArchived, true)
+      assert.equal(parseKnowledgeQueryParams('http://localhost/api/knowledge?includeArchived=no').includeArchived, false)
+    })
   })
 
   // --- Route file structure -----------------------------------------------
@@ -241,6 +259,29 @@ describe('Knowledge API contract', () => {
       assert.match(src, /export\s+async\s+function\s+PUT/)
       assert.match(src, /export\s+async\s+function\s+DELETE/)
     })
+
+    it('knowledge/hygiene/route.ts exports GET and POST', () => {
+      const src = readRoute('knowledge', 'hygiene', 'route.ts')
+      assert.match(src, /export\s+async\s+function\s+GET/)
+      assert.match(src, /export\s+async\s+function\s+POST/)
+    })
+
+    it('knowledge/sources/route.ts re-exports GET and POST', () => {
+      const src = readRoute('knowledge', 'sources', 'route.ts')
+      assert.match(src, /export\s+\{\s*GET,\s*POST\s*\}/)
+    })
+
+    it('knowledge/sources/[id]/route.ts re-exports GET, PUT, DELETE', () => {
+      const src = readRoute('knowledge', 'sources', '[id]', 'route.ts')
+      assert.match(src, /export\s+\{\s*GET,\s*PUT,\s*DELETE\s*\}/)
+    })
+
+    it('knowledge source action routes export POST', () => {
+      for (const route of ['archive', 'restore', 'supersede', 'sync']) {
+        const src = readRoute('knowledge', 'sources', '[id]', route, 'route.ts')
+        assert.match(src, /export\s+async\s+function\s+POST/)
+      }
+    })
   })
 })
 

package/src/lib/server/chat-execution/chat-execution-grounding.test.ts

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import test from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
+
+function runWithTempDataDir(script: string) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-chat-grounding-'))
+  try {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DATA_DIR: path.join(tempDir, 'data'),
+        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
+        BROWSER_PROFILES_DIR: path.join(tempDir, 'browser-profiles'),
+      },
+      encoding: 'utf-8',
+    })
+    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+    const lines = (result.stdout || '')
+      .trim()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+    return JSON.parse(jsonLine || '{}')
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+test('executeSessionChatTurn persists citations and retrieval traces on grounded assistant messages', () => {
+  const output = runWithTempDataDir(`
+    const storageMod = await import('@/lib/server/storage')
+    const providersMod = await import('@/lib/providers/index')
+    const threadMod = await import('@/lib/server/agents/agent-thread-session')
+    const execMod = await import('@/lib/server/chat-execution/chat-execution')
+    const messageRepoMod = await import('@/lib/server/messages/message-repository')
+    const knowledgeMod = await import('@/lib/server/knowledge-sources')
+
+    const storage = storageMod.default || storageMod['module.exports'] || storageMod
+    const ensureAgentThreadSession = threadMod.ensureAgentThreadSession
+      || threadMod.default?.ensureAgentThreadSession
+      || threadMod['module.exports']?.ensureAgentThreadSession
+    const executeSessionChatTurn = execMod.executeSessionChatTurn
+      || execMod.default?.executeSessionChatTurn
+      || execMod['module.exports']?.executeSessionChatTurn
+    const getMessages = messageRepoMod.getMessages
+      || messageRepoMod.default?.getMessages
+      || messageRepoMod['module.exports']?.getMessages
+    const knowledge = knowledgeMod.default || knowledgeMod
+    const providers = providersMod.PROVIDERS
+      || providersMod.default?.PROVIDERS
+      || providersMod['module.exports']?.PROVIDERS
+
+    providers['test-provider'] = {
+      id: 'test-provider',
+      name: 'Test Provider',
+      models: ['unit'],
+      requiresApiKey: false,
+      requiresEndpoint: false,
+      handler: {
+        async streamChat() {
+          return 'Use blue green deployment for the gateway migration so rollback stays simple.'
+        },
+      },
+    }
+
+    const now = Date.now()
+    storage.saveAgents({
+      molly: {
+        id: 'molly',
+        name: 'Molly',
+        description: 'Grounding test',
+        provider: 'test-provider',
+        model: 'unit',
+        credentialId: null,
+        apiEndpoint: null,
+        fallbackCredentialIds: [],
+        disabled: false,
+        proactiveMemory: true,
+        extensions: ['memory'],
+        createdAt: now,
+        updatedAt: now,
+      },
+    })
+
+    await knowledge.createKnowledgeSource({
+      kind: 'manual',
+      title: 'Gateway Migration Runbook',
+      content: 'Use blue green deployment for gateway migrations so rollback stays simple and downtime stays low.',
+      tags: ['deploy'],
+    })
+
+    const session = ensureAgentThreadSession('molly')
+    const result = await executeSessionChatTurn({
+      sessionId: session.id,
+      message: 'gateway blue green rollback',
+      runId: 'run-grounding-chat',
+    })
+
+    const messages = getMessages(session.id)
+    const lastMessage = messages[messages.length - 1]
+
+    console.log(JSON.stringify({
+      persisted: result.persisted || false,
+      resultCitationCount: Array.isArray(result.citations) ? result.citations.length : 0,
+      resultSelectorStatus: result.retrievalTrace?.selectorStatus || null,
+      messageCitationCount: Array.isArray(lastMessage?.citations) ? lastMessage.citations.length : 0,
+      messageTraceHitCount: Array.isArray(lastMessage?.retrievalTrace?.hits) ? lastMessage.retrievalTrace.hits.length : 0,
+      messageSelectorStatus: lastMessage?.retrievalTrace?.selectorStatus || null,
+      messageSourceTitle: lastMessage?.citations?.[0]?.sourceTitle || null,
+    }))
+  `)
+
+  assert.equal(output.persisted, true)
+  assert.equal(output.resultCitationCount >= 1, true)
+  assert.equal(output.resultSelectorStatus, 'selected')
+  assert.equal(output.messageCitationCount >= 1, true)
+  assert.equal(output.messageTraceHitCount >= 1, true)
+  assert.equal(output.messageSelectorStatus, 'selected')
+  assert.equal(output.messageSourceTitle, 'Gateway Migration Runbook')
+})

package/src/lib/server/chat-execution/chat-execution-types.ts

@@ -1,4 +1,9 @@
-import type { MessageToolEvent, SSEEvent } from '@/types'
+import type {
+  KnowledgeCitation,
+  KnowledgeRetrievalTrace,
+  MessageToolEvent,
+  SSEEvent,
+} from '@/types'
 
 export interface ExecuteChatTurnInput {
   sessionId: string
@@ -33,4 +38,6 @@ export interface ExecuteChatTurnResult {
   inputTokens?: number
   outputTokens?: number
   estimatedCost?: number
+  citations?: KnowledgeCitation[]
+  retrievalTrace?: KnowledgeRetrievalTrace | null
 }

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

@@ -112,6 +112,7 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
     responseCacheHit: streamResult.responseCacheHit,
     directUsage: streamResult.directUsage,
     durationMs: streamResult.durationMs,
+    knowledgeRetrievalTrace: streamResult.knowledgeRetrievalTrace || null,
     emit: partialPersistence.emit,
   })
 

package/src/lib/server/chat-execution/chat-turn-finalization.ts

@@ -1,4 +1,12 @@
-import type { Message, MessageToolEvent, SSEEvent, Session, UsageRecord } from '@/types'
+import type {
+  KnowledgeRetrievalTrace,
+  Message,
+  MessageToolEvent,
+  SSEEvent,
+  Session,
+  UsageRecord,
+} from '@/types'
+import { sendConnectorMessage } from '../connectors/manager'
 import { applyExactOutputContract, classifyExactOutputContract, type ExactOutputContract } from '@/lib/server/chat-execution/exact-output-contract'
 import { stripMainLoopMetaForPersistence } from '@/lib/server/agents/main-agent-loop'
 import { shouldSuppressHiddenControlText, stripHiddenControlTokens } from '@/lib/server/agents/assistant-control'
@@ -42,6 +50,7 @@ import {
 import { appendUsage } from '@/lib/server/usage/usage-repository'
 import { synchronizeWorkingStateForTurn } from '@/lib/server/working-state/service'
 import { notify } from '@/lib/server/ws-hub'
+import { selectKnowledgeCitations } from '@/lib/server/knowledge-sources'
 
 import type { ExecuteChatTurnInput, ExecuteChatTurnResult } from './chat-execution-types'
 import type { PartialAssistantPersistence } from '@/lib/server/chat-execution/chat-turn-partial-persistence'
@@ -153,6 +162,7 @@ export async function finalizeChatTurn(params: {
     received: boolean
   }
   durationMs: number
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
   emit: (event: SSEEvent) => void
 }): Promise<ExecuteChatTurnResult> {
   const {
@@ -163,6 +173,7 @@ export async function finalizeChatTurn(params: {
     responseCacheHit,
     directUsage,
     durationMs,
+    knowledgeRetrievalTrace,
     emit,
   } = params
   let { fullResponse, errorMessage } = params
@@ -312,6 +323,12 @@ export async function finalizeChatTurn(params: {
   const hiddenControlOnly = shouldSuppressHiddenControlText(rawTextForPersistence)
   const textForPersistence = stripHiddenControlTokens(rawTextForPersistence)
   const persistedText = getPersistedAssistantText(textForPersistence, persistedToolEvents)
+  const grounding = hiddenControlOnly
+    ? { citations: [], retrievalTrace: knowledgeRetrievalTrace || null }
+    : selectKnowledgeCitations({
+        responseText: persistedText,
+        retrievalTrace: knowledgeRetrievalTrace || null,
+      })
   let persistedResponseForHooks = textForPersistence
 
   if (isHeartbeatRun && rawTextForPersistence) {
@@ -412,6 +429,8 @@ export async function finalizeChatTurn(params: {
           thinking: thinkingText || undefined,
           toolEvents: persistedToolEvents.length ? persistedToolEvents : undefined,
           kind: persistedKind,
+          citations: grounding.citations.length > 0 ? grounding.citations : undefined,
+          retrievalTrace: grounding.retrievalTrace || undefined,
         },
         enabledIds: extensionsForRun,
         phase: isHeartbeatRun ? 'heartbeat' : 'assistant_final',
@@ -478,8 +497,6 @@ export async function finalizeChatTurn(params: {
           && heartbeatConfig.target !== 'none'
         ) {
           try {
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            const { sendConnectorMessage } = require('../connectors/manager')
             let connectorId: string | undefined
             let channelId: string | undefined
             if (heartbeatConfig.target === 'last') {
@@ -527,9 +544,7 @@ export async function finalizeChatTurn(params: {
             : ''
           if (!recentInbound && channelId) {
             try {
-              // eslint-disable-next-line @typescript-eslint/no-require-imports
-              const { sendConnectorMessage: sendMsg } = require('../connectors/manager')
-              sendMsg({ connectorId: connectorId || undefined, channelId, text: nextAssistantMessage.text }).catch((err: unknown) => {
+              sendConnectorMessage({ connectorId: connectorId || undefined, channelId, text: nextAssistantMessage.text }).catch((err: unknown) => {
                 log.warn('connector', 'Auto-route connector delivery failed', {
                   connectorId,
                   channelId,
@@ -646,5 +661,7 @@ export async function finalizeChatTurn(params: {
     inputTokens: accumulatedUsage.inputTokens || undefined,
     outputTokens: accumulatedUsage.outputTokens || undefined,
     estimatedCost: accumulatedUsage.estimatedCost || undefined,
+    citations: grounding.citations.length > 0 ? grounding.citations : undefined,
+    retrievalTrace: grounding.retrievalTrace || undefined,
   }
 }

package/src/lib/server/chat-execution/chat-turn-stream-execution.ts

@@ -1,5 +1,5 @@
 import { CONTEXT_OVERFLOW_RE } from '@/lib/providers/error-classification'
-import type { ProviderType } from '@/types'
+import type { KnowledgeRetrievalTrace, ProviderType } from '@/types'
 import { getEnabledCapabilityIds } from '@/lib/capability-selection'
 import { isLocalOpenClawEndpoint } from '@/lib/openclaw/openclaw-endpoint'
 import { streamAgentChat } from '@/lib/server/chat-execution/stream-agent-chat'
@@ -42,6 +42,7 @@ export interface ExecutedPreparedChatTurn {
     outputTokens: number
     received: boolean
   }
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 export async function executePreparedChatTurn(params: {
@@ -90,6 +91,7 @@ export async function executePreparedChatTurn(params: {
   let responseCacheHit = false
   let responseCacheInput: LlmResponseCacheKeyInput | null = null
   let durationMs = 0
+  let knowledgeRetrievalTrace: KnowledgeRetrievalTrace | null = null
   const startTs = Date.now()
   const endLlmPerf = perf.start('chat-execution', 'llm-round-trip', {
     sessionId,
@@ -111,6 +113,7 @@ export async function executePreparedChatTurn(params: {
       responseCacheHit,
       durationMs,
       directUsage,
+      knowledgeRetrievalTrace: null,
     }
   }
 
@@ -157,6 +160,7 @@ export async function executePreparedChatTurn(params: {
         promptMode,
       })
       fullResponse = result.finalResponse || result.fullText
+      knowledgeRetrievalTrace = result.knowledgeRetrievalTrace || null
     } else {
       let directHistorySnapshot = isAutoRunNoHistory
         ? (heartbeatLightContext ? [] : getSessionMessages(sessionId).slice(-6))
@@ -298,5 +302,6 @@ export async function executePreparedChatTurn(params: {
     responseCacheHit,
     durationMs,
     directUsage,
+    knowledgeRetrievalTrace,
   }
 }