@swarmclawai/swarmclaw 1.3.4 → 1.3.6

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,
   }
 }

package/src/lib/server/chat-execution/post-stream-finalization.ts

@@ -5,7 +5,7 @@
  * usage recording, forced external service summary, capability hooks,
  * and OpenClaw sync.
  */
-import type { Session, UsageRecord } from '@/types'
+import type { KnowledgeRetrievalTrace, Session, UsageRecord } from '@/types'
 import { log } from '@/lib/server/logger'
 import type { ChatTurnState } from '@/lib/server/chat-execution/chat-turn-state'
 
@@ -51,6 +51,7 @@ export interface PostStreamResult {
   fullText: string
   finalResponse: string
   toolEvents: import('@/types').MessageToolEvent[]
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 export interface FinalizeStreamResultOpts {
@@ -70,6 +71,7 @@ export interface FinalizeStreamResultOpts {
   cleanup: () => Promise<void>
   runId: string
   classification?: MessageClassification | null
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 export async function finalizeStreamResult(opts: FinalizeStreamResultOpts): Promise<PostStreamResult> {
@@ -138,7 +140,12 @@ export async function finalizeStreamResult(opts: FinalizeStreamResultOpts): Prom
     const finalResponse = await resolveAndSummarize()
     await emitLlmOutputHook(finalResponse)
     await cleanup()
-    return { fullText: state.fullText, finalResponse, toolEvents: state.streamedToolEvents }
+    return {
+      fullText: state.fullText,
+      finalResponse,
+      toolEvents: state.streamedToolEvents,
+      knowledgeRetrievalTrace: opts.knowledgeRetrievalTrace || null,
+    }
   }
 
   // Strip leaked classification JSON from model output (e.g. `{ "isDeliverableTask": true, ... }`)
@@ -212,5 +219,10 @@ export async function finalizeStreamResult(opts: FinalizeStreamResultOpts): Prom
 
   await cleanup()
 
-  return { fullText: state.fullText, finalResponse, toolEvents: state.streamedToolEvents }
+  return {
+    fullText: state.fullText,
+    finalResponse,
+    toolEvents: state.streamedToolEvents,
+    knowledgeRetrievalTrace: opts.knowledgeRetrievalTrace || null,
+  }
 }

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

@@ -8,7 +8,7 @@
 
 import fs from 'node:fs'
 import path from 'node:path'
-import type { Session, Agent } from '@/types'
+import type { KnowledgeRetrievalTrace, Session, Agent } from '@/types'
 import type { PromptMode } from '@/lib/server/chat-execution/prompt-mode'
 import type { MessageClassification } from '@/lib/server/chat-execution/message-classifier'
 import type { ActiveProjectContext } from '@/lib/server/project-context'
@@ -428,6 +428,7 @@ export function buildSuggestionsSection(
 export interface ProactiveMemoryResult {
   section: string | null
   injectedIds: Record<string, number>
+  knowledgeTrace?: KnowledgeRetrievalTrace | null
 }
 
 export async function buildProactiveMemorySection(
@@ -438,22 +439,28 @@ export async function buildProactiveMemorySection(
   isMinimalPrompt: boolean,
   currentThreadRecallRequest: boolean,
 ): Promise<ProactiveMemoryResult> {
-  const noResult: ProactiveMemoryResult = { section: null, injectedIds: {} }
+  const noResult: ProactiveMemoryResult = { section: null, injectedIds: {}, knowledgeTrace: null }
   if (isMinimalPrompt || !session.agentId || currentThreadRecallRequest || message.length <= 12) return noResult
   if (!agent?.proactiveMemory) return noResult
   try {
     const { getMemoryDb } = await import('@/lib/server/memory/memory-db')
     const { buildSessionMemoryScopeFilter } = await import('@/lib/server/memory/session-memory-scope')
+    const { buildKnowledgeRetrievalTrace } = await import('@/lib/server/knowledge-sources')
     const memDb = getMemoryDb()
     const recalled = memDb.search(message, session.agentId, {
       scope: buildSessionMemoryScopeFilter(session, agent.memoryScopeMode || null, activeProjectRoot),
     })
+    const knowledgeTrace = await buildKnowledgeRetrievalTrace({
+      query: message,
+      viewerAgentId: session.agentId,
+    })
 
     // Dedup: skip memories already injected 2+ times in this session
     const priorCounts = session.injectedMemoryIds || {}
     const filtered = recalled.filter((entry) => (priorCounts[entry.id] || 0) < 2)
 
     const topRecalled = filtered.slice(0, 3)
+    const sections: string[] = []
     if (topRecalled.length > 0) {
       // Track injection counts
       const updatedCounts: Record<string, number> = { ...priorCounts }
@@ -464,9 +471,28 @@ export async function buildProactiveMemorySection(
       const recalledLines = topRecalled.map((entry) =>
         `- ${entry.abstract || entry.content.slice(0, 300)}`,
       )
+      sections.push(`## Recalled Context\nRelevant memories from previous interactions:\n${recalledLines.join('\n')}`)
+      if (knowledgeTrace?.hits.length) {
+        const groundingLines = knowledgeTrace.hits.map((hit) =>
+          `- [${hit.chunkIndex + 1}/${hit.chunkCount}] ${hit.sourceTitle}: ${hit.snippet}`,
+        )
+        sections.push(`## Source Grounding\nSource-backed knowledge retrieved for this turn:\n${groundingLines.join('\n')}`)
+      }
       return {
-        section: `## Recalled Context\nRelevant memories from previous interactions:\n${recalledLines.join('\n')}`,
+        section: sections.join('\n\n'),
         injectedIds: updatedCounts,
+        knowledgeTrace,
+      }
+    }
+
+    if (knowledgeTrace?.hits.length) {
+      const groundingLines = knowledgeTrace.hits.map((hit) =>
+        `- [${hit.chunkIndex + 1}/${hit.chunkCount}] ${hit.sourceTitle}: ${hit.snippet}`,
+      )
+      return {
+        section: `## Source Grounding\nSource-backed knowledge retrieved for this turn:\n${groundingLines.join('\n')}`,
+        injectedIds: priorCounts,
+        knowledgeTrace,
       }
     }
   } catch { /* non-critical */ }

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

@@ -36,7 +36,7 @@ import { log } from '@/lib/server/logger'
 import { logExecution } from '@/lib/server/execution-log'
 import { buildCurrentDateTimePromptContext } from '@/lib/server/prompt-runtime-context'
 import { expandExtensionIds } from '@/lib/server/tool-aliases'
-import type { ExecutionBrief, Session, Message } from '@/types'
+import type { ExecutionBrief, KnowledgeRetrievalTrace, Session, Message } from '@/types'
 import { getEnabledCapabilityIds } from '@/lib/capability-selection'
 import { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
 import { resolveActiveProjectContext } from '@/lib/server/project-context'
@@ -199,6 +199,7 @@ export interface StreamAgentChatResult {
   finalResponse: string
   /** Tool events emitted during the streamed run. */
   toolEvents: import('@/types').MessageToolEvent[]
+  knowledgeRetrievalTrace?: KnowledgeRetrievalTrace | null
 }
 
 type LangChainContentPart =
@@ -267,6 +268,7 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
     preferMinimalPrompt: lightweightDirectChat,
   })
   const isMinimalPrompt = promptMode === 'minimal'
+  let knowledgeRetrievalTrace: KnowledgeRetrievalTrace | null = null
 
   // Resolve agent's thinking level for provider-native params
   let agentThinkingLevel: 'minimal' | 'low' | 'medium' | 'high' | undefined
@@ -309,6 +311,7 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
       fullText: requestedToolPreflightResponse,
       finalResponse: requestedToolPreflightResponse,
       toolEvents: [],
+      knowledgeRetrievalTrace: null,
     }
   }
   const runtime = loadRuntimeSettings()
@@ -490,6 +493,7 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
       isMinimalPrompt, currentThreadRecallRequest,
     )
     if (memoryResult.section) promptParts.push(memoryResult.section)
+    knowledgeRetrievalTrace = memoryResult.knowledgeTrace || null
     // Persist injection dedup counts so repeated memories are suppressed
     if (Object.keys(memoryResult.injectedIds).length > 0) {
       session.injectedMemoryIds = memoryResult.injectedIds
@@ -1269,5 +1273,6 @@ async function streamAgentChatCore(opts: StreamAgentChatOpts): Promise<StreamAge
     cleanup,
     runId,
     classification,
+    knowledgeRetrievalTrace,
   })
 }

package/src/lib/server/execution-engine/task-attempt.ts

@@ -3,7 +3,7 @@ import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { log } from '@/lib/server/logger'
 import { loadSettings } from '@/lib/server/settings/settings-repository'
 import { loadSessions } from '@/lib/server/sessions/session-repository'
-import { appendPersistedRunEvent, persistRun } from '@/lib/server/runtime/run-ledger'
+import { appendPersistedRunEvent, buildRetrievalSummary, persistRun } from '@/lib/server/runtime/run-ledger'
 import { notify } from '@/lib/server/ws-hub'
 import { captureGuardianCheckpoint } from '@/lib/server/agents/guardian'
 import {
@@ -68,6 +68,7 @@ function notifyExecutionState(sessionId: string): void {
 }
 
 function emitStatus(run: SessionRunRecord, status: SessionRunStatus, extra?: Record<string, unknown>): void {
+  const { citations, retrievalTrace, ...eventExtra } = extra || {}
   appendPersistedRunEvent({
     runId: run.id,
     sessionId: run.sessionId,
@@ -78,6 +79,8 @@ function emitStatus(run: SessionRunRecord, status: SessionRunStatus, extra?: Rec
     phase: 'status',
     status,
     summary: run.resultPreview || run.error || undefined,
+    citations: citations as import('@/types').KnowledgeCitation[] | undefined,
+    retrievalTrace: (retrievalTrace as import('@/types').KnowledgeRetrievalTrace | undefined) || undefined,
     event: {
       t: 'md',
       text: JSON.stringify({
@@ -90,7 +93,7 @@ function emitStatus(run: SessionRunRecord, status: SessionRunStatus, extra?: Rec
           status,
           source: run.source,
           internal: run.internal,
-          ...extra,
+          ...eventExtra,
         },
       }),
     },
@@ -268,6 +271,7 @@ export function enqueueTaskAttemptExecution(
       run.endedAt = Date.now()
       run.error = controller.signal.aborted ? (run.error || 'Cancelled') : result.error
       run.resultPreview = result.text?.slice(0, 280)
+      run.retrievalSummary = buildRetrievalSummary(result.citations)
       if (typeof result.inputTokens === 'number') run.totalInputTokens = result.inputTokens
       if (typeof result.outputTokens === 'number') run.totalOutputTokens = result.outputTokens
       if (typeof result.estimatedCost === 'number') run.estimatedCost = result.estimatedCost
@@ -275,6 +279,8 @@ export function enqueueTaskAttemptExecution(
       emitStatus(run, run.status, {
         hasText: !!result.text,
         error: run.error || null,
+        citations: result.citations,
+        retrievalTrace: result.retrievalTrace,
       })
       return result
     } catch (err: unknown) {

package/src/lib/server/knowledge-import.ts

@@ -0,0 +1,159 @@
+import fs from 'fs'
+import path from 'path'
+import * as cheerio from 'cheerio'
+
+const TEXT_EXTS = new Set([
+  '.txt', '.md', '.markdown', '.csv', '.tsv', '.json', '.jsonl',
+  '.html', '.htm', '.xml', '.yaml', '.yml', '.toml', '.ini', '.cfg',
+  '.js', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.c', '.cpp', '.h',
+  '.rb', '.php', '.sh', '.bash', '.zsh', '.sql', '.r', '.swift', '.kt',
+  '.env', '.log', '.conf', '.properties', '.gitignore', '.dockerignore',
+])
+
+export const MAX_KNOWLEDGE_IMPORT_BYTES = 10 * 1024 * 1024
+export const MAX_KNOWLEDGE_CONTENT_CHARS = 500_000
+
+export function isKnowledgeTextFile(filename: string): boolean {
+  const ext = path.extname(filename).toLowerCase()
+  return TEXT_EXTS.has(ext) || ext === ''
+}
+
+export function deriveKnowledgeTitle(filename: string): string {
+  const name = path.basename(filename, path.extname(filename))
+  return name
+    .replace(/[-_]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+    .trim() || 'Knowledge Source'
+}
+
+function normalizeKnowledgeContent(content: string): string {
+  const normalized = String(content || '')
+    .replace(/^\uFEFF/, '')
+    .replace(/\r\n/g, '\n')
+    .trim()
+
+  if (normalized.length <= MAX_KNOWLEDGE_CONTENT_CHARS) return normalized
+  return `${normalized.slice(0, MAX_KNOWLEDGE_CONTENT_CHARS)}\n\n[... truncated at 500k characters]`
+}
+
+async function extractPdfText(buffer: Buffer, filePathHint?: string): Promise<string> {
+  try {
+    const pdfParseModule = await import('pdf-parse') as unknown as {
+      default?: (input: Buffer) => Promise<{ text?: string }>
+    }
+    const pdfParse = pdfParseModule.default
+    if (typeof pdfParse !== 'function') throw new Error('pdf-parse loader unavailable')
+    const result = await pdfParse(buffer)
+    return normalizeKnowledgeContent(result.text || '')
+  } catch {
+    return normalizeKnowledgeContent(
+      `[PDF document]\n\nUnable to extract text automatically.${filePathHint ? `\n\nSaved at: ${filePathHint}` : ''}`,
+    )
+  }
+}
+
+function htmlToReadableText(html: string): { title: string | null; content: string } {
+  const $ = cheerio.load(html)
+  $('script, style, noscript, svg, nav, footer, header').remove()
+
+  const title = $('title').first().text().trim() || null
+  const root = $('main').first().length
+    ? $('main').first()
+    : $('article').first().length
+      ? $('article').first()
+      : $('body').first().length
+        ? $('body').first()
+        : $('html').first()
+
+  const text = root
+    .text()
+    .replace(/\u00a0/g, ' ')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join('\n\n')
+
+  return {
+    title,
+    content: normalizeKnowledgeContent(text),
+  }
+}
+
+export async function extractKnowledgeTextFromBuffer(
+  buffer: Buffer,
+  filename: string,
+  filePathHint?: string,
+): Promise<string> {
+  if (buffer.length === 0) return ''
+  if (buffer.length > MAX_KNOWLEDGE_IMPORT_BYTES) {
+    throw new Error('File too large. Maximum 10MB.')
+  }
+
+  const ext = path.extname(filename).toLowerCase()
+  if (ext === '.pdf') {
+    return extractPdfText(buffer, filePathHint)
+  }
+
+  if (isKnowledgeTextFile(filename)) {
+    return normalizeKnowledgeContent(buffer.toString('utf-8'))
+  }
+
+  return normalizeKnowledgeContent(
+    `[Binary file: ${filename}]${filePathHint ? `\n\nSaved at: ${filePathHint}` : ''}`,
+  )
+}
+
+export async function extractKnowledgeTextFromFile(filePath: string, filename?: string): Promise<string> {
+  const buffer = await fs.promises.readFile(filePath)
+  return extractKnowledgeTextFromBuffer(buffer, filename || path.basename(filePath), filePath)
+}
+
+export async function extractKnowledgeTextFromUrl(sourceUrl: string): Promise<{
+  title: string | null
+  content: string
+  contentType: string | null
+}> {
+  const response = await fetch(sourceUrl, {
+    headers: {
+      'user-agent': 'SwarmClaw/knowledge-import',
+      accept: 'text/html, text/plain, application/json, application/pdf, */*',
+    },
+  })
+
+  if (!response.ok) {
+    throw new Error(`URL fetch failed (${response.status})`)
+  }
+
+  const contentType = response.headers.get('content-type')
+  const contentLength = Number.parseInt(response.headers.get('content-length') || '', 10)
+  if (Number.isFinite(contentLength) && contentLength > MAX_KNOWLEDGE_IMPORT_BYTES) {
+    throw new Error('Remote document is too large. Maximum 10MB.')
+  }
+
+  if ((contentType || '').includes('application/pdf') || sourceUrl.toLowerCase().endsWith('.pdf')) {
+    const buffer = Buffer.from(await response.arrayBuffer())
+    return {
+      title: null,
+      content: await extractPdfText(buffer, sourceUrl),
+      contentType,
+    }
+  }
+
+  const text = await response.text()
+  const looksLikeHtml = (contentType || '').includes('text/html') || /<html[\s>]|<body[\s>]/i.test(text)
+  if (looksLikeHtml) {
+    const parsed = htmlToReadableText(text)
+    return {
+      title: parsed.title,
+      content: parsed.content,
+      contentType,
+    }
+  }
+
+  return {
+    title: null,
+    content: normalizeKnowledgeContent(text),
+    contentType,
+  }
+}