@swarmclawai/swarmclaw 0.3.1 → 0.4.5

package/src/lib/server/connectors/pairing.test.ts

@@ -0,0 +1,99 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { test } from 'node:test'
+import {
+  addAllowedSender,
+  approvePairingCode,
+  clearConnectorPairingState,
+  createOrTouchPairingRequest,
+  isSenderAllowed,
+  listPendingPairingRequests,
+  listStoredAllowedSenders,
+  parseAllowFromCsv,
+  parsePairingPolicy,
+} from './pairing.ts'
+
+function withTempDataDir<T>(fn: (dir: string) => T): T {
+  const original = process.env.DATA_DIR
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-pairing-test-'))
+  process.env.DATA_DIR = tempDir
+  try {
+    return fn(tempDir)
+  } finally {
+    if (typeof original === 'string') process.env.DATA_DIR = original
+    else delete process.env.DATA_DIR
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+test('pairing store creates request, approves code, and persists allowlist', () => {
+  withTempDataDir(() => {
+    const connectorId = 'pair-test-1'
+
+    const first = createOrTouchPairingRequest({
+      connectorId,
+      senderId: '+15551234567',
+      senderName: 'Alice',
+      channelId: 'chat:1',
+    })
+    assert.equal(first.created, true)
+    assert.equal(first.code.length, 8)
+
+    const second = createOrTouchPairingRequest({
+      connectorId,
+      senderId: '+15551234567',
+      senderName: 'Alice',
+      channelId: 'chat:1',
+    })
+    assert.equal(second.created, false)
+    assert.equal(second.code, first.code)
+
+    const pendingBefore = listPendingPairingRequests(connectorId)
+    assert.equal(pendingBefore.length, 1)
+    assert.equal(pendingBefore[0].senderId, '+15551234567')
+
+    const bad = approvePairingCode(connectorId, 'INVALID')
+    assert.equal(bad.ok, false)
+
+    const approved = approvePairingCode(connectorId, first.code)
+    assert.equal(approved.ok, true)
+    assert.equal(approved.senderId, '+15551234567')
+
+    const pendingAfter = listPendingPairingRequests(connectorId)
+    assert.equal(pendingAfter.length, 0)
+
+    const stored = listStoredAllowedSenders(connectorId)
+    assert.deepEqual(stored, ['+15551234567'])
+
+    assert.equal(isSenderAllowed({ connectorId, senderId: '+15551234567' }), true)
+    assert.equal(isSenderAllowed({ connectorId, senderId: '+16667778888' }), false)
+
+    clearConnectorPairingState(connectorId)
+    assert.deepEqual(listStoredAllowedSenders(connectorId), [])
+  })
+})
+
+test('pairing helpers normalize policy and allowFrom csv entries', () => {
+  assert.equal(parsePairingPolicy('PAIRING'), 'pairing')
+  assert.equal(parsePairingPolicy('allowlist'), 'allowlist')
+  assert.equal(parsePairingPolicy('unknown', 'open'), 'open')
+
+  const list = parseAllowFromCsv('  +1555,TEST@example.com,+1555  ,   ')
+  assert.deepEqual(list, ['+1555', 'test@example.com'])
+})
+
+test('addAllowedSender deduplicates and normalizes sender ids', () => {
+  withTempDataDir(() => {
+    const connectorId = 'pair-test-2'
+    const first = addAllowedSender(connectorId, '  TEST@Example.com  ')
+    assert.equal(first.added, true)
+    assert.equal(first.normalized, 'test@example.com')
+
+    const second = addAllowedSender(connectorId, 'test@example.com')
+    assert.equal(second.added, false)
+
+    assert.deepEqual(listStoredAllowedSenders(connectorId), ['test@example.com'])
+  })
+})

package/src/lib/server/connectors/pairing.ts

@@ -0,0 +1,256 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const DEFAULT_DATA_DIR = path.join(process.cwd(), 'data')
+const STORE_VERSION = 1
+const PENDING_TTL_MS = 24 * 60 * 60 * 1000
+const MAX_PENDING_PER_CONNECTOR = 100
+const PAIR_CODE_LENGTH = 8
+const PAIR_CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
+
+function resolveStorePath(): string {
+  const dataDir = process.env.DATA_DIR || DEFAULT_DATA_DIR
+  return path.join(dataDir, 'connectors', 'pairing-store.json')
+}
+
+export type PairingPolicy = 'open' | 'allowlist' | 'pairing' | 'disabled'
+
+export interface PairingRequest {
+  code: string
+  senderId: string
+  senderName?: string
+  channelId?: string
+  createdAt: number
+  updatedAt: number
+}
+
+interface ConnectorPairingState {
+  allowedSenderIds: string[]
+  pending: PairingRequest[]
+}
+
+interface PairingStore {
+  version: number
+  connectors: Record<string, ConnectorPairingState>
+}
+
+function normalizeSenderId(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+function dedupe(items: string[]): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const item of items) {
+    const normalized = normalizeSenderId(item)
+    if (!normalized || seen.has(normalized)) continue
+    seen.add(normalized)
+    out.push(normalized)
+  }
+  return out
+}
+
+function prunePending(entries: PairingRequest[]): PairingRequest[] {
+  const now = Date.now()
+  return entries.filter((entry) => {
+    if (!entry?.code || !entry?.senderId) return false
+    if (!Number.isFinite(entry.createdAt) || !Number.isFinite(entry.updatedAt)) return false
+    return (now - entry.updatedAt) <= PENDING_TTL_MS
+  }).slice(-MAX_PENDING_PER_CONNECTOR)
+}
+
+function emptyStore(): PairingStore {
+  return { version: STORE_VERSION, connectors: {} }
+}
+
+function loadStore(): PairingStore {
+  const storePath = resolveStorePath()
+  try {
+    if (!fs.existsSync(storePath)) return emptyStore()
+    const raw = fs.readFileSync(storePath, 'utf8')
+    const parsed = JSON.parse(raw) as PairingStore
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.connectors !== 'object') {
+      return emptyStore()
+    }
+
+    const normalized: PairingStore = emptyStore()
+    for (const [connectorId, value] of Object.entries(parsed.connectors || {})) {
+      const state = value as Partial<ConnectorPairingState>
+      const allowedSenderIds = dedupe(Array.isArray(state.allowedSenderIds) ? state.allowedSenderIds.map(String) : [])
+      const pending = prunePending(Array.isArray(state.pending) ? state.pending as PairingRequest[] : [])
+      normalized.connectors[connectorId] = { allowedSenderIds, pending }
+    }
+    return normalized
+  } catch {
+    return emptyStore()
+  }
+}
+
+function saveStore(store: PairingStore): void {
+  const storePath = resolveStorePath()
+  fs.mkdirSync(path.dirname(storePath), { recursive: true })
+  fs.writeFileSync(storePath, `${JSON.stringify(store, null, 2)}\n`)
+}
+
+function ensureConnectorState(store: PairingStore, connectorId: string): ConnectorPairingState {
+  const existing = store.connectors[connectorId]
+  if (existing) {
+    existing.allowedSenderIds = dedupe(existing.allowedSenderIds || [])
+    existing.pending = prunePending(existing.pending || [])
+    return existing
+  }
+  const created: ConnectorPairingState = {
+    allowedSenderIds: [],
+    pending: [],
+  }
+  store.connectors[connectorId] = created
+  return created
+}
+
+function randomPairCode(existing: Set<string>): string {
+  for (let i = 0; i < 256; i++) {
+    const bytes = crypto.randomBytes(PAIR_CODE_LENGTH)
+    let out = ''
+    for (let j = 0; j < PAIR_CODE_LENGTH; j++) {
+      out += PAIR_CODE_ALPHABET[bytes[j] % PAIR_CODE_ALPHABET.length]
+    }
+    if (!existing.has(out)) return out
+  }
+  throw new Error('Unable to generate unique pairing code')
+}
+
+export function parsePairingPolicy(value: unknown, fallback: PairingPolicy = 'open'): PairingPolicy {
+  if (typeof value !== 'string') return fallback
+  const normalized = value.trim().toLowerCase()
+  if (normalized === 'open' || normalized === 'allowlist' || normalized === 'pairing' || normalized === 'disabled') {
+    return normalized
+  }
+  return fallback
+}
+
+export function parseAllowFromCsv(value: unknown): string[] {
+  if (typeof value !== 'string') return []
+  return dedupe(value.split(',').map((item) => item.trim()).filter(Boolean))
+}
+
+export function listStoredAllowedSenders(connectorId: string): string[] {
+  const store = loadStore()
+  const state = ensureConnectorState(store, connectorId)
+  return state.allowedSenderIds.slice()
+}
+
+export function listPendingPairingRequests(connectorId: string): PairingRequest[] {
+  const store = loadStore()
+  const state = ensureConnectorState(store, connectorId)
+  return state.pending.slice().sort((a, b) => b.updatedAt - a.updatedAt)
+}
+
+export function addAllowedSender(connectorId: string, senderId: string): { added: boolean; normalized: string } {
+  const normalized = normalizeSenderId(senderId)
+  if (!normalized) return { added: false, normalized }
+
+  const store = loadStore()
+  const state = ensureConnectorState(store, connectorId)
+  const hasExisting = state.allowedSenderIds.includes(normalized)
+  if (!hasExisting) {
+    state.allowedSenderIds.push(normalized)
+  }
+
+  // Remove any pending requests for the same sender after approval.
+  state.pending = state.pending.filter((entry) => normalizeSenderId(entry.senderId) !== normalized)
+
+  saveStore(store)
+  return { added: !hasExisting, normalized }
+}
+
+export function createOrTouchPairingRequest(params: {
+  connectorId: string
+  senderId: string
+  senderName?: string
+  channelId?: string
+}): { code: string; created: boolean } {
+  const normalized = normalizeSenderId(params.senderId)
+  if (!normalized) throw new Error('senderId is required')
+
+  const store = loadStore()
+  const state = ensureConnectorState(store, params.connectorId)
+  const now = Date.now()
+
+  const existing = state.pending.find((entry) => normalizeSenderId(entry.senderId) === normalized)
+  if (existing) {
+    existing.updatedAt = now
+    existing.senderName = params.senderName || existing.senderName
+    existing.channelId = params.channelId || existing.channelId
+    saveStore(store)
+    return { code: existing.code, created: false }
+  }
+
+  const existingCodes = new Set(state.pending.map((entry) => entry.code.toUpperCase()))
+  const code = randomPairCode(existingCodes)
+  state.pending.push({
+    code,
+    senderId: normalized,
+    senderName: params.senderName,
+    channelId: params.channelId,
+    createdAt: now,
+    updatedAt: now,
+  })
+  state.pending = prunePending(state.pending)
+  saveStore(store)
+  return { code, created: true }
+}
+
+export function approvePairingCode(connectorId: string, codeRaw: string): {
+  ok: boolean
+  senderId?: string
+  senderName?: string
+  reason?: string
+} {
+  const code = codeRaw.trim().toUpperCase()
+  if (!code) return { ok: false, reason: 'Missing code' }
+
+  const store = loadStore()
+  const state = ensureConnectorState(store, connectorId)
+  const idx = state.pending.findIndex((entry) => entry.code.toUpperCase() === code)
+  if (idx < 0) return { ok: false, reason: 'Code not found or expired' }
+
+  const pending = state.pending[idx]
+  state.pending.splice(idx, 1)
+
+  const normalizedSender = normalizeSenderId(pending.senderId)
+  if (!state.allowedSenderIds.includes(normalizedSender)) {
+    state.allowedSenderIds.push(normalizedSender)
+    state.allowedSenderIds = dedupe(state.allowedSenderIds)
+  }
+
+  saveStore(store)
+  return {
+    ok: true,
+    senderId: normalizedSender,
+    senderName: pending.senderName,
+  }
+}
+
+export function isSenderAllowed(params: {
+  connectorId: string
+  senderId: string
+  configAllowFrom?: string[]
+}): boolean {
+  const normalized = normalizeSenderId(params.senderId)
+  if (!normalized) return false
+
+  const configSet = new Set((params.configAllowFrom || []).map((item) => normalizeSenderId(item)).filter(Boolean))
+  if (configSet.has(normalized)) return true
+
+  const store = loadStore()
+  const state = ensureConnectorState(store, params.connectorId)
+  return state.allowedSenderIds.includes(normalized)
+}
+
+export function clearConnectorPairingState(connectorId: string): void {
+  const store = loadStore()
+  if (!store.connectors[connectorId]) return
+  delete store.connectors[connectorId]
+  saveStore(store)
+}

package/src/lib/server/connectors/signal.ts

@@ -147,6 +147,7 @@ export async function handleSignalEvent(
     senderId: sender,
     senderName: envelope.sourceName || sender,
     text,
+    isGroup: !!groupId,
   }
 
   try {

package/src/lib/server/connectors/teams.ts

@@ -22,11 +22,11 @@ const teams: PlatformConnector = {
     const conversationReferences = new Map<string, any>()
     let stopped = false
 
-    // Process incoming activities — called from the webhook endpoint
-    // POST /api/connectors/[id]/webhook should pipe req/res through this
-    const processActivity = async (req: any, res: any) => {
+    // Process incoming activities — called from the webhook endpoint.
+    // We use processActivityDirect so this works from Next.js route handlers.
+    const processActivity = async (activity: any) => {
       if (stopped) return
-      await adapter.processActivity(req, res, async (context: any) => {
+      await adapter.processActivityDirect(activity, async (context: any) => {
         if (context.activity.type !== 'message') return
         if (!context.activity.text) return
 
@@ -57,7 +57,7 @@ const teams: PlatformConnector = {
       })
     }
 
-    // Store processActivity on globalThis so the webhook route can access it
+    // Store processActivity on globalThis so the webhook route can access it.
     const handlerKey = `__swarmclaw_teams_handler_${connector.id}__`
     ;(globalThis as any)[handlerKey] = processActivity
 

package/src/lib/server/connectors/types.ts

@@ -21,9 +21,11 @@ export interface InboundMessage {
   senderId: string         // platform-specific user ID
   senderName: string       // display name
   text: string
+  isGroup?: boolean
   imageUrl?: string
   media?: InboundMedia[]
   replyToMessageId?: string
+  agentIdOverride?: string
 }
 
 /** A running connector instance */
@@ -50,6 +52,14 @@ export interface ConnectorInstance {
   authenticated?: boolean
   /** Whether the connector has existing saved credentials (WhatsApp only) */
   hasCredentials?: boolean
+  /** Rich messaging: send a reaction emoji to a message */
+  sendReaction?: (channelId: string, messageId: string, emoji: string) => Promise<void>
+  /** Rich messaging: edit a previously sent message */
+  editMessage?: (channelId: string, messageId: string, newText: string) => Promise<void>
+  /** Rich messaging: delete a message */
+  deleteMessage?: (channelId: string, messageId: string) => Promise<void>
+  /** Rich messaging: pin a message */
+  pinMessage?: (channelId: string, messageId: string) => Promise<void>
 }
 
 /** Platform-specific connector implementation */

package/src/lib/server/context-manager.ts

@@ -56,7 +56,7 @@ const PROVIDER_DEFAULT_WINDOWS: Record<string, number> = {
   mistral: 128_000,
   xai: 131_072,
   fireworks: 32_768,
-  ollama: 8_192,
+  ollama: 32_768,
   openclaw: 128_000,
 }
 

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

@@ -1,4 +1,5 @@
 import { loadQueue, loadSchedules, loadSessions, saveSessions, loadConnectors } from './storage'
+import { notify } from './ws-hub'
 import { processNext, cleanupFinishedTaskSessions, validateCompletedTasksQueue, recoverStalledRunningTasks } from './queue'
 import { startScheduler, stopScheduler } from './scheduler'
 import { sweepOrphanedBrowsers, getActiveBrowserCount } from './session-tools'
@@ -114,6 +115,7 @@ export function startDaemon(options?: { source?: string; manualStart?: boolean }
     return
   }
   ds.running = true
+  notify('daemon')
   console.log(`[daemon] Starting daemon (source=${source}, scheduler + queue processor + heartbeat)`)
 
   validateCompletedTasksQueue()
@@ -135,6 +137,7 @@ export function stopDaemon(options?: { source?: string; manualStop?: boolean })
   if (options?.manualStop === true) ds.manualStopRequested = true
   if (!ds.running) return
   ds.running = false
+  notify('daemon')
   console.log(`[daemon] Stopping daemon (source=${source})`)
 
   stopScheduler()

package/src/lib/server/data-dir.ts

@@ -1,3 +1,4 @@
 import path from 'path'
 
 export const DATA_DIR = process.env.DATA_DIR || path.join(process.cwd(), 'data')
+export const WORKSPACE_DIR = path.join(DATA_DIR, 'workspace')

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

@@ -1,7 +1,7 @@
 import fs from 'fs'
 import path from 'path'
-import crypto from 'crypto'
 import Database from 'better-sqlite3'
+import { genId } from '@/lib/id'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -94,7 +94,7 @@ export function logExecution(
     detail?: Record<string, unknown>
   },
 ): string {
-  const id = crypto.randomBytes(8).toString('hex')
+  const id = genId(8)
   const ts = Date.now()
   try {
     insertStmt().run(
@@ -133,7 +133,7 @@ export function logExecutionBatch(
   const tx = db.transaction(() => {
     for (const e of entries) {
       stmt.run(
-        crypto.randomBytes(8).toString('hex'),
+        genId(8),
         e.sessionId,
         e.runId ?? null,
         e.agentId ?? null,

package/src/lib/server/heartbeat-service.ts

@@ -1,7 +1,10 @@
+import fs from 'fs'
+import path from 'path'
 import { loadAgents, loadSessions, loadSettings } from './storage'
 import { enqueueSessionRun, getSessionRunState } from './session-run-manager'
 import { log } from './logger'
 import { buildMainLoopHeartbeatPrompt, getMainLoopStateForSession, isMainSession } from './main-agent-loop'
+import { WORKSPACE_DIR } from './data-dir'
 
 const HEARTBEAT_TICK_MS = 5_000
 
@@ -118,6 +121,56 @@ export interface HeartbeatConfig {
 
 const DEFAULT_HEARTBEAT_PROMPT = 'Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.'
 
+function readHeartbeatFile(session: any): string {
+  try {
+    const filePath = path.join(session.cwd || WORKSPACE_DIR, 'HEARTBEAT.md')
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf-8').trim()
+    }
+  } catch { /* ignore */ }
+  return ''
+}
+
+function buildAgentHeartbeatPrompt(session: any, agent: any, fallbackPrompt: string, heartbeatFileContent: string): string {
+  if (!agent) return fallbackPrompt
+
+  // Dynamic goal (agent-set) takes priority over static system prompt
+  const dynamicGoal = agent.heartbeatGoal || ''
+  const dynamicNextAction = agent.heartbeatNextAction || ''
+  const description = agent.description || ''
+  const systemPrompt = agent.systemPrompt || ''
+  const soul = agent.soul || ''
+  const goalSummary = systemPrompt.slice(0, 500)
+  const recentMessages = (session.messages || []).slice(-5)
+  const recentContext = recentMessages
+    .map((m: any) => `[${m.role}]: ${(m.text || '').slice(0, 200)}`)
+    .join('\n')
+
+  return [
+    'AGENT_HEARTBEAT_TICK',
+    `Time: ${new Date().toISOString()}`,
+    `Agent: ${agent.name}`,
+    description ? `Description: ${description}` : '',
+    dynamicGoal
+      ? `Current goal (self-set): ${dynamicGoal}`
+      : goalSummary ? `System prompt (initial goal):\n${goalSummary}` : '',
+    dynamicNextAction ? `Planned next action: ${dynamicNextAction}` : '',
+    soul ? `Persona: ${soul.slice(0, 300)}` : '',
+    heartbeatFileContent ? `\nHEARTBEAT.md contents:\n${heartbeatFileContent.slice(0, 2000)}` : '',
+    recentContext ? `Recent conversation:\n${recentContext}` : '',
+    fallbackPrompt !== DEFAULT_HEARTBEAT_PROMPT ? `\nAgent instructions:\n${fallbackPrompt}` : '',
+    '',
+    'You are running an autonomous heartbeat tick. Review your goal and recent context.',
+    'If there is meaningful work to do toward your goal, use your tools and take action.',
+    'If nothing needs attention right now, reply exactly HEARTBEAT_OK.',
+    'Do not ask clarifying questions. Take the most reasonable next action.',
+    '',
+    'To update your goal or plan, include this line in your response:',
+    '[AGENT_HEARTBEAT_META]{"goal": "your evolved goal", "status": "progress", "next_action": "what you plan to do next"}',
+    'You can evolve your goal as you learn more. Set status to "progress" while working, "ok" when done, "idle" when waiting.',
+  ].filter(Boolean).join('\n')
+}
+
 function resolveInterval(obj: Record<string, any>, currentSec: number): number {
   // Prefer heartbeatInterval (duration string) over heartbeatIntervalSec (raw number)
   if (obj.heartbeatInterval !== undefined && obj.heartbeatInterval !== null) {
@@ -288,9 +341,20 @@ async function tickHeartbeats() {
     const runState = getSessionRunState(session.id)
     if (runState.runningRunId) continue
 
-    const heartbeatMessage = isMainSession(session)
-      ? buildMainLoopHeartbeatPrompt(session, cfg.prompt)
-      : cfg.prompt
+    let heartbeatMessage: string
+    if (isMainSession(session)) {
+      heartbeatMessage = buildMainLoopHeartbeatPrompt(session, cfg.prompt)
+    } else {
+      const heartbeatFileContent = readHeartbeatFile(session)
+      const hasGoal = !!(agent?.heartbeatGoal || agent?.description || agent?.systemPrompt || agent?.soul)
+      const hasCustomPrompt = cfg.prompt !== DEFAULT_HEARTBEAT_PROMPT
+      // Skip heartbeat only if there's truly nothing to drive it:
+      // no agent goal, no HEARTBEAT.md content, AND no custom prompt configured
+      if (!hasGoal && !heartbeatFileContent && !hasCustomPrompt) {
+        continue
+      }
+      heartbeatMessage = buildAgentHeartbeatPrompt(session, agent, cfg.prompt, heartbeatFileContent)
+    }
 
     const enqueue = enqueueSessionRun({
       sessionId: session.id,

package/src/lib/server/knowledge-db.test.ts

@@ -104,39 +104,8 @@ function rowToEntry(row: Record<string, unknown>): MemoryEntry {
   }
 }
 
-// ---- Knowledge helpers (mirrors memory-db.ts exported functions) ----
-
-const MEMORY_FTS_STOP_WORDS = new Set([
-  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from', 'how',
-  'i', 'if', 'in', 'is', 'it', 'of', 'on', 'or', 'that', 'the', 'this',
-  'to', 'was', 'we', 'were', 'what', 'when', 'where', 'which', 'who', 'with',
-  'you', 'your',
-])
-const MAX_FTS_QUERY_TERMS = 6
-const MAX_FTS_TERM_LENGTH = 48
-
-function buildFtsQuery(input: string): string {
-  const tokens = String(input || '')
-    .toLowerCase()
-    .match(/[a-z0-9][a-z0-9._:/-]*/g) || []
-  if (!tokens.length) return ''
-  const unique: string[] = []
-  const seen = new Set<string>()
-  for (const token of tokens) {
-    const term = token.slice(0, MAX_FTS_TERM_LENGTH)
-    if (term.length < 3) continue
-    if (MEMORY_FTS_STOP_WORDS.has(term)) continue
-    if (seen.has(term)) continue
-    seen.add(term)
-    unique.push(term)
-    if (unique.length >= MAX_FTS_QUERY_TERMS) break
-  }
-  if (unique.length === 1) {
-    return unique[0].length >= 5 ? `"${unique[0].replace(/"/g, '')}"` : ''
-  }
-  const selected = unique.slice(0, Math.min(4, MAX_FTS_QUERY_TERMS))
-  return selected.map((term) => `"${term.replace(/"/g, '')}"`).join(' AND ')
-}
+// ---- Knowledge helpers (re-exported from memory-db.ts) ----
+import { buildFtsQuery } from './memory-db'
 
 function addRawMemory(data: {
   agentId?: string | null