@swarmclawai/swarmclaw 1.3.4 → 1.3.6

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/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-disabled.test.ts

@@ -1,40 +1,23 @@
 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'
+import { runWithTempDataDir as runWithSharedTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
 
-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-disabled-'))
-  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 })
-  }
+function runWithTempDataDir<T = unknown>(script: string): T {
+  return runWithSharedTempDataDir<T>(script, {
+    prefix: 'swarmclaw-chat-disabled-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
 }
 
 test('executeSessionChatTurn persists a visible error for disabled agents', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    error: string | null
+    text: string | null
+    persisted: boolean
+    lastRole: string | null
+    lastText: string | null
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const storage = storageMod.default || storageMod['module.exports'] || storageMod
     const threadMod = await import('@/lib/server/agents/agent-thread-session')

package/src/lib/server/chat-execution/chat-execution-eval-history.test.ts

@@ -1,40 +1,13 @@
 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-eval-history-'))
-  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 })
-  }
-}
+import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
 
 test('executeSessionChatTurn persists internal eval user turns for same-thread recall', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    recallText: string | null
+    roles: string[]
+    texts: string[]
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const storage = storageMod.default || storageMod['module.exports'] || storageMod
     const providersMod = await import('@/lib/providers/index')
@@ -103,7 +76,11 @@ test('executeSessionChatTurn persists internal eval user turns for same-thread r
       roles: storedSession.messages.map((entry) => entry.role),
       texts: storedSession.messages.map((entry) => entry.text),
     }))
-  `)
+  `, {
+    prefix: 'swarmclaw-chat-eval-history-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
 
   assert.match(String(output.recallText || ''), /Sunbird/)
   assert.deepEqual(output.roles, ['user', 'assistant', 'user', 'assistant'])

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

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
+
+test('executeSessionChatTurn persists citations and retrieval traces on grounded assistant messages', () => {
+  const output = runWithTempDataDir<{
+    persisted: boolean
+    resultCitationCount: number
+    resultSelectorStatus: string | null
+    messageCitationCount: number
+    messageTraceHitCount: number
+    messageSelectorStatus: string | null
+    messageSourceTitle: string | null
+  }>(`
+    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,
+    }))
+  `, {
+    prefix: 'swarmclaw-chat-grounding-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
+
+  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-session-sync.test.ts

@@ -1,40 +1,24 @@
 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-session-sync-'))
-  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 })
-  }
+import { runWithTempDataDir as runWithSharedTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
+
+function runWithTempDataDir<T = unknown>(script: string): T {
+  return runWithSharedTempDataDir<T>(script, {
+    prefix: 'swarmclaw-chat-session-sync-',
+    dataDir: 'data',
+    browserProfilesDir: 'browser-profiles',
+  })
 }
 
 test('executeSessionChatTurn syncs updated agent runtime fields onto its thread session', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    provider: string | null
+    model: string | null
+    extensions: string[]
+    heartbeatEnabled: boolean | null
+    heartbeatIntervalSec: number | null
+    connectorContext: Record<string, unknown> | null
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const storage = storageMod.default || storageMod['module.exports'] || storageMod
     const providersMod = await import('@/lib/providers/index')
@@ -126,7 +110,12 @@ test('executeSessionChatTurn syncs updated agent runtime fields onto its thread
 })
 
 test('executeSessionChatTurn keeps tool-only heartbeats off the visible main-thread history and clears stale connector state', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    connectorContext: Record<string, unknown> | null
+    messageCount: number
+    lastMessageText: string | null
+    heartbeatKinds: number
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const execMod = await import('@/lib/server/chat-execution/chat-execution')
@@ -232,7 +221,11 @@ test('executeSessionChatTurn keeps tool-only heartbeats off the visible main-thr
 })
 
 test('executeSessionChatTurn hides internal main-loop followup output from the visible transcript', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    messageCount: number
+    lastMessageText: string | null
+    hasStreamingArtifacts: boolean
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const execMod = await import('@/lib/server/chat-execution/chat-execution')
@@ -324,7 +317,10 @@ test('executeSessionChatTurn hides internal main-loop followup output from the v
 })
 
 test('executeSessionChatTurn forces external connector sessions onto session-scoped memory', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    memoryScopeMode: string | null
+    connectorContext: { isOwnerConversation?: boolean } | null
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const execMod = await import('@/lib/server/chat-execution/chat-execution')
@@ -418,7 +414,10 @@ test('executeSessionChatTurn forces external connector sessions onto session-sco
 })
 
 test('executeSessionChatTurn applies lifecycle hooks for model resolution and message persistence', () => {
-  const output = runWithTempDataDir(`
+  const output = runWithTempDataDir<{
+    lastMessageText: string
+    marks: string[]
+  }>(`
     const storageMod = await import('@/lib/server/storage')
     const providersMod = await import('@/lib/providers/index')
     const extMod = await import('@/lib/server/extensions')

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,11 @@
-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'
@@ -43,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'
@@ -154,6 +162,7 @@ export async function finalizeChatTurn(params: {
     received: boolean
   }
   durationMs: number
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
   emit: (event: SSEEvent) => void
 }): Promise<ExecuteChatTurnResult> {
   const {
@@ -164,6 +173,7 @@ export async function finalizeChatTurn(params: {
     responseCacheHit,
     directUsage,
     durationMs,
+    knowledgeRetrievalTrace,
     emit,
   } = params
   let { fullResponse, errorMessage } = params
@@ -313,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) {
@@ -413,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',
@@ -643,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,
   }
 }