@swarmclawai/swarmclaw 1.3.4 → 1.3.5

package/src/app/api/memory/dream/route.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from 'next/server'
+import { log } from '@/lib/server/logger'
+
+const TAG = 'api-dream'
+
+export async function GET(req: Request) {
+  try {
+    const { searchParams } = new URL(req.url)
+    const agentId = searchParams.get('agentId') ?? undefined
+    const limit = Math.max(1, Math.min(500, Number(searchParams.get('limit')) || 50))
+    const { listDreamCycles } = await import('@/lib/server/memory/dream-cycles')
+    const cycles = listDreamCycles(agentId, limit)
+    return NextResponse.json({ ok: true, cycles })
+  } catch (err: unknown) {
+    log.error(TAG, 'GET failed:', err)
+    return NextResponse.json({ ok: false, error: String((err as Error)?.message || err) }, { status: 500 })
+  }
+}
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json().catch(() => ({})) as Record<string, unknown>
+    const agentId = typeof body.agentId === 'string' ? body.agentId : undefined
+    if (!agentId) {
+      return NextResponse.json({ ok: false, error: 'agentId is required' }, { status: 400 })
+    }
+    const { executeDreamCycle } = await import('@/lib/server/memory/dream-service')
+    const cycle = await executeDreamCycle(agentId, 'manual')
+    return NextResponse.json({ ok: true, cycle })
+  } catch (err: unknown) {
+    log.error(TAG, 'POST failed:', err)
+    return NextResponse.json({ ok: false, error: String((err as Error)?.message || err) }, { status: 500 })
+  }
+}

package/src/app/knowledge/layout.tsx

@@ -10,7 +10,7 @@ export default function KnowledgeLayout({ children }: { children: React.ReactNod
     <>
       <SidebarPanelShell
         title="Knowledge"
-        createLabel="Knowledge Entry"
+        createLabel="New Source"
         onNew={() => useAppStore.getState().setKnowledgeSheetOpen(true)}
       >
         <KnowledgeList />

package/src/app/knowledge/page.tsx

@@ -1,27 +1,7 @@
 'use client'
 
-import { useAppStore } from '@/stores/use-app-store'
-import { KnowledgeList } from '@/components/knowledge/knowledge-list'
+import { KnowledgeDetail } from '@/components/knowledge/knowledge-detail'
 
 export default function KnowledgePage() {
-  return (
-    <div className="flex-1 flex flex-col h-full">
-      <div className="flex items-center px-6 pt-5 pb-3 shrink-0">
-        <h2 className="font-display text-[14px] font-600 text-text-2 tracking-[-0.01em] capitalize flex-1">
-          Knowledge
-        </h2>
-        <button
-          onClick={() => useAppStore.getState().setKnowledgeSheetOpen(true)}
-          className="flex items-center gap-1.5 px-2.5 py-1.5 rounded-[8px] text-[11px] font-600 text-accent-bright bg-accent-soft hover:bg-accent-bright/15 transition-all cursor-pointer"
-          style={{ fontFamily: 'inherit' }}
-        >
-          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round">
-            <line x1="12" y1="5" x2="12" y2="19" /><line x1="5" y1="12" x2="19" y2="12" />
-          </svg>
-          Knowledge Entry
-        </button>
-      </div>
-      <KnowledgeList />
-    </div>
-  )
+  return <KnowledgeDetail />
 }

package/src/app/protocols/page.tsx

@@ -16,6 +16,7 @@ import {
 import { useTasksQuery } from '@/features/tasks/queries'
 import { MainContent } from '@/components/layout/main-content'
 import { StructuredSessionLauncher } from '@/components/protocols/structured-session-launcher'
+import { GroundingPanel } from '@/components/knowledge/grounding-panel'
 import { timeAgo } from '@/lib/time-format'
 import type {
   BoardTask,
@@ -164,8 +165,8 @@ export default function ProtocolsPage() {
   const runActionMutation = useProtocolRunActionMutation()
   const upsertTemplateMutation = useUpsertProtocolTemplateMutation()
   const deleteTemplateMutation = useDeleteProtocolTemplateMutation()
-  const templates = templatesQuery.data ?? []
-  const runs = runsQuery.data ?? []
+  const templates = useMemo(() => templatesQuery.data ?? [], [templatesQuery.data])
+  const runs = useMemo(() => runsQuery.data ?? [], [runsQuery.data])
   const detail = detailQuery.data ?? null
   const agents = agentsQuery.data ?? {}
   const chatrooms = chatroomsQuery.data ?? {}
@@ -203,6 +204,14 @@ export default function ProtocolsPage() {
   const selectedTemplate = useMemo(() => templates.find((template) => template.id === form.templateId) || null, [form.templateId, templates])
   const customTemplates = useMemo(() => templates.filter((template) => !template.builtIn), [templates])
   const builtInTemplates = useMemo(() => templates.filter((template) => template.builtIn), [templates])
+  const artifactCitationMap = useMemo(() => {
+    const map = new Map<string, ProtocolRunEvent['citations']>()
+    for (const event of detail?.events || []) {
+      if (!event.artifactId || !event.citations?.length) continue
+      map.set(event.artifactId, event.citations)
+    }
+    return map
+  }, [detail?.events])
   const filteredRuns = useMemo(() => {
     const search = runSearch.trim().toLowerCase()
     return runs.filter((run) => {
@@ -1167,6 +1176,11 @@ export default function ProtocolsPage() {
                                 <span className="text-[11px] text-text-3/60">{artifact.kind.replace(/_/g, ' ')}</span>
                               </div>
                               <div className="mt-2 whitespace-pre-wrap text-[13px] leading-relaxed text-text-2">{artifact.content}</div>
+                              {artifactCitationMap.get(artifact.id)?.length ? (
+                                <div className="mt-3">
+                                  <GroundingPanel citations={artifactCitationMap.get(artifact.id)} compact />
+                                </div>
+                              ) : null}
                             </div>
                           ))}
                         </div>
@@ -1220,6 +1234,11 @@ export default function ProtocolsPage() {
                                 <div className="text-[11px] text-text-3/55">{timeAgo(event.createdAt)}</div>
                               </div>
                               <div className="mt-2 text-[13px] leading-relaxed text-text-2">{event.summary}</div>
+                              {event.citations?.length ? (
+                                <div className="mt-3">
+                                  <GroundingPanel citations={event.citations} compact />
+                                </div>
+                              ) : null}
                             </div>
                           ))}
                         </div>

package/src/cli/index.js

@@ -26,6 +26,8 @@ const COMMAND_GROUPS = [
       cmd('clone', 'POST', '/agents/:id/clone', 'Clone an agent'),
       cmd('bulk-update', 'PATCH', '/agents/bulk', 'Bulk update agents', { expectsJsonBody: true }),
       cmd('status', 'GET', '/agents/:id/status', 'Get live status for an agent'),
+      cmd('dream', 'GET', '/agents/:id/dream', 'Get agent dream config and recent cycles'),
+      cmd('dream-update', 'PATCH', '/agents/:id/dream', 'Update agent dream config', { expectsJsonBody: true }),
     ],
   },
   {
@@ -268,6 +270,17 @@ const COMMAND_GROUPS = [
         requestType: 'upload',
         inputPositional: 'filePath',
       }),
+      cmd('hygiene', 'GET', '/knowledge/hygiene', 'Get knowledge hygiene summary'),
+      cmd('hygiene-run', 'POST', '/knowledge/hygiene', 'Run knowledge hygiene maintenance'),
+      cmd('sources', 'GET', '/knowledge/sources', 'List knowledge sources'),
+      cmd('source-create', 'POST', '/knowledge/sources', 'Create knowledge source', { expectsJsonBody: true }),
+      cmd('source-get', 'GET', '/knowledge/sources/:id', 'Get knowledge source detail'),
+      cmd('source-update', 'PUT', '/knowledge/sources/:id', 'Update knowledge source', { expectsJsonBody: true }),
+      cmd('source-delete', 'DELETE', '/knowledge/sources/:id', 'Delete knowledge source'),
+      cmd('source-archive', 'POST', '/knowledge/sources/:id/archive', 'Archive knowledge source', { expectsJsonBody: true }),
+      cmd('source-restore', 'POST', '/knowledge/sources/:id/restore', 'Restore archived knowledge source'),
+      cmd('source-supersede', 'POST', '/knowledge/sources/:id/supersede', 'Mark source as superseded', { expectsJsonBody: true }),
+      cmd('source-sync', 'POST', '/knowledge/sources/:id/sync', 'Re-sync file/URL knowledge source'),
     ],
   },
   {
@@ -290,6 +303,9 @@ const COMMAND_GROUPS = [
       cmd('maintenance', 'GET', '/memory/maintenance', 'Analyze memory dedupe/prune candidates'),
       cmd('maintenance-run', 'POST', '/memory/maintenance', 'Run memory dedupe/prune maintenance', { expectsJsonBody: true }),
       cmd('graph', 'GET', '/memory/graph', 'Get memory graph (nodes and links) for visualization'),
+      cmd('dream', 'GET', '/memory/dream', 'List dream cycles'),
+      cmd('dream-trigger', 'POST', '/memory/dream', 'Trigger a dream cycle', { expectsJsonBody: true }),
+      cmd('dream-get', 'GET', '/memory/dream/:id', 'Get dream cycle by id'),
     ],
   },
   {

package/src/cli/spec.js

@@ -12,6 +12,8 @@ const COMMAND_GROUPS = {
       restore: { description: 'Restore a trashed agent', method: 'POST', path: '/agents/trash' },
       purge: { description: 'Permanently delete a trashed agent', method: 'DELETE', path: '/agents/trash' },
       status: { description: 'Get live status for an agent', method: 'GET', path: '/agents/:id/status', params: ['id'] },
+      dream: { description: 'Get agent dream config and recent cycles', method: 'GET', path: '/agents/:id/dream', params: ['id'] },
+      'dream-update': { description: 'Update agent dream config', method: 'PATCH', path: '/agents/:id/dream', params: ['id'] },
     },
   },
   activity: {
@@ -218,6 +220,9 @@ const COMMAND_GROUPS = {
       delete: { description: 'Delete memory entry', method: 'DELETE', path: '/memory/:id', params: ['id'] },
       maintenance: { description: 'Analyze memory dedupe/prune candidates', method: 'GET', path: '/memory/maintenance' },
       'maintenance-run': { description: 'Run memory dedupe/prune maintenance', method: 'POST', path: '/memory/maintenance' },
+      dream: { description: 'List dream cycles', method: 'GET', path: '/memory/dream' },
+      'dream-trigger': { description: 'Trigger a dream cycle', method: 'POST', path: '/memory/dream' },
+      'dream-get': { description: 'Get dream cycle by id', method: 'GET', path: '/memory/dream/:id', params: ['id'] },
     },
   },
   'memory-images': {

package/src/components/agents/agent-sheet.tsx

@@ -236,6 +236,9 @@ export function AgentSheet() {
   const [heartbeatIntervalSec, setHeartbeatIntervalSec] = useState('')  // '' = default (30m)
   const [heartbeatModel, setHeartbeatModel] = useState('')
   const [heartbeatPrompt, setHeartbeatPrompt] = useState('')
+  const [dreamEnabled, setDreamEnabled] = useState(false)
+  const [dreamCooldownMinutes, setDreamCooldownMinutes] = useState('360')
+  const [dreamTier2Enabled, setDreamTier2Enabled] = useState(true)
   const [orchestratorEnabled, setOrchestratorEnabled] = useState(false)
   const [orchestratorMission, setOrchestratorMission] = useState('')
   const [orchestratorWakeInterval, setOrchestratorWakeInterval] = useState('5m')
@@ -437,6 +440,9 @@ export function AgentSheet() {
         setHeartbeatIntervalSec(parseDurationToSec(editing.heartbeatInterval, editing.heartbeatIntervalSec))
         setHeartbeatModel(editing.heartbeatModel || '')
         setHeartbeatPrompt(editing.heartbeatPrompt || '')
+        setDreamEnabled(editing.dreamEnabled || false)
+        setDreamCooldownMinutes(editing.dreamConfig?.cooldownMinutes != null ? String(editing.dreamConfig.cooldownMinutes) : '360')
+        setDreamTier2Enabled(editing.dreamConfig?.tier2Enabled !== false)
         setOrchestratorEnabled(editing.orchestratorEnabled || false)
         setOrchestratorMission(editing.orchestratorMission || '')
         setOrchestratorWakeInterval(typeof editing.orchestratorWakeInterval === 'string' ? editing.orchestratorWakeInterval : typeof editing.orchestratorWakeInterval === 'number' ? `${editing.orchestratorWakeInterval}s` : '5m')
@@ -516,6 +522,9 @@ export function AgentSheet() {
         setHeartbeatIntervalSec(parseDurationToSec(src.heartbeatInterval, src.heartbeatIntervalSec))
         setHeartbeatModel(src.heartbeatModel || '')
         setHeartbeatPrompt(src.heartbeatPrompt || '')
+        setDreamEnabled(src.dreamEnabled || false)
+        setDreamCooldownMinutes(src.dreamConfig?.cooldownMinutes != null ? String(src.dreamConfig.cooldownMinutes) : '360')
+        setDreamTier2Enabled(src.dreamConfig?.tier2Enabled !== false)
         setOrchestratorEnabled(src.orchestratorEnabled || false)
         setOrchestratorMission(src.orchestratorMission || '')
         setOrchestratorWakeInterval(typeof src.orchestratorWakeInterval === 'string' ? src.orchestratorWakeInterval : typeof src.orchestratorWakeInterval === 'number' ? `${src.orchestratorWakeInterval}s` : '5m')
@@ -794,6 +803,10 @@ export function AgentSheet() {
       heartbeatIntervalSec: heartbeatIntervalSec ? Number(heartbeatIntervalSec) : null,
       heartbeatModel: heartbeatModel.trim() || null,
       heartbeatPrompt: heartbeatPrompt.trim() || null,
+      dreamEnabled,
+      dreamConfig: dreamEnabled
+        ? { cooldownMinutes: Number(dreamCooldownMinutes) || 360, tier2Enabled: dreamTier2Enabled }
+        : null,
       orchestratorEnabled,
       orchestratorMission: orchestratorMission.trim() || undefined,
       orchestratorWakeInterval: orchestratorWakeInterval.trim() || null,
@@ -818,6 +831,8 @@ export function AgentSheet() {
       data.heartbeatIntervalSec = null
       data.heartbeatModel = null
       data.heartbeatPrompt = null
+      data.dreamEnabled = false
+      data.dreamConfig = null
     }
     const savedAgent = editing
       ? await updateAgent(editing.id, data)
@@ -1007,6 +1022,7 @@ export function AgentSheet() {
     if (skills.length > 0 || skillIds.length > 0 || mcpServerIds.length > 0 || mcpDisabledTools.length > 0) badges.push('Skills & MCP')
     if (toolsDifferFromDefault || filesystemScope === 'machine') badges.push('Tools')
     if (budgetEnabled) badges.push('Budget')
+    if (dreamEnabled) badges.push('Dreaming')
     if (disabled) badges.push('Disabled')
     if (autoRecovery) badges.push('Recovery')
     if (projectId) badges.push('Project')
@@ -1018,6 +1034,7 @@ export function AgentSheet() {
     autoRecovery,
     budgetEnabled,
     disabled,
+    dreamEnabled,
     fallbackCredentialIds.length,
     filesystemScope,
     identityPersonaLabel,
@@ -1905,6 +1922,54 @@ export function AgentSheet() {
             <span className={`absolute top-0.5 left-0.5 h-5 w-5 rounded-full bg-white transition-transform duration-200 ${heartbeatEnabled ? 'translate-x-5' : 'translate-x-0'}`} />
           </button>
         </div>
+        <div className="flex items-center justify-between gap-4 rounded-[14px] border border-white/[0.06] bg-white/[0.02] px-4 py-4 mt-3">
+          <div className="min-w-0">
+            <div className="flex items-center gap-2">
+              <p className="text-[14px] font-600 text-text">Dreaming</p>
+              <HintTip text="When enabled, this agent consolidates and optimizes its memories during idle periods" />
+            </div>
+            <p className="mt-1 text-[12px] leading-[1.6] text-text-3/75">
+              Consolidate, decay, and reflect on memories when the agent is idle.
+            </p>
+          </div>
+          <button
+            type="button"
+            onClick={() => setDreamEnabled((current) => !current)}
+            className={`relative h-6 w-11 shrink-0 rounded-full border-none transition-colors duration-200 ${dreamEnabled ? 'bg-accent-bright' : 'bg-white/[0.12]'}`}
+            aria-pressed={dreamEnabled}
+          >
+            <span className={`absolute top-0.5 left-0.5 h-5 w-5 rounded-full bg-white transition-transform duration-200 ${dreamEnabled ? 'translate-x-5' : 'translate-x-0'}`} />
+          </button>
+        </div>
+        {dreamEnabled && (
+          <div className="mt-3 rounded-[14px] border border-white/[0.04] bg-white/[0.01] px-4 py-4 space-y-3">
+            <div>
+              <label className="flex items-center gap-2 text-[12px] font-600 text-text-2 mb-1.5">
+                Cooldown (minutes) <HintTip text="Minimum minutes between dream cycles" />
+              </label>
+              <input
+                type="number"
+                value={dreamCooldownMinutes}
+                onChange={(e) => setDreamCooldownMinutes(e.target.value)}
+                min={1}
+                placeholder="360"
+                className={inputClass}
+                style={{ fontFamily: 'inherit' }}
+              />
+            </div>
+            <label className="flex items-center gap-3 cursor-pointer">
+              <div
+                onClick={() => setDreamTier2Enabled((current) => !current)}
+                className={`w-11 h-6 rounded-full transition-all duration-200 relative cursor-pointer shrink-0 ${dreamTier2Enabled ? 'bg-accent-bright' : 'bg-white/[0.08]'}`}
+              >
+                <div className={`absolute top-0.5 w-5 h-5 rounded-full bg-white transition-all duration-200 ${dreamTier2Enabled ? 'left-[22px]' : 'left-0.5'}`} />
+              </div>
+              <span className="flex items-center gap-2 text-[13px] text-text-2">
+                Tier 2 Reflection <HintTip text="Use the agent's LLM to reflect on memories and produce consolidated insights" />
+              </span>
+            </label>
+          </div>
+        )}
       </SectionCard>
       )}
 

package/src/components/chat/message-bubble.tsx

@@ -25,6 +25,7 @@ import { ConnectorPlatformIcon, getConnectorPlatformLabel } from '@/components/s
 import { copyTextToClipboard } from '@/lib/clipboard'
 import { formatMessageTimestamp } from '@/lib/chat/chat-display'
 import { stripAllInternalMetadata } from '@/lib/strip-internal-metadata'
+import { GroundingPanel } from '@/components/knowledge/grounding-panel'
 
 /** Parse delegation-source metadata prefix from system messages */
 const DELEGATION_SOURCE_RE = /^\[delegation-source:([^:]*):([^:]*):([^\]]*)\]/
@@ -974,6 +975,15 @@ export const MessageBubble = memo(function MessageBubble({ message, assistantNam
         </div>
       ) : null}
 
+      {!isUser && (message.citations?.length || message.retrievalTrace?.hits?.length) ? (
+        <div className="mt-2 max-w-[85%] md:max-w-[72%]">
+          <GroundingPanel
+            citations={message.citations}
+            retrievalTrace={message.retrievalTrace}
+          />
+        </div>
+      ) : null}
+
       {/* Bookmark indicator */}
       {message.bookmarked && (
         <div className={`flex items-center gap-1 mt-1 px-1 ${isUser ? 'justify-end' : ''}`}>

package/src/components/knowledge/grounding-panel.tsx

@@ -0,0 +1,99 @@
+'use client'
+
+import type { KnowledgeCitation, KnowledgeRetrievalTrace } from '@/types'
+
+function dedupeCitations(citations: KnowledgeCitation[]): KnowledgeCitation[] {
+  const seen = new Set<string>()
+  const out: KnowledgeCitation[] = []
+  for (const citation of citations) {
+    const key = `${citation.sourceId}:${citation.chunkId}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(citation)
+  }
+  return out
+}
+
+export function GroundingPanel(props: {
+  citations?: KnowledgeCitation[]
+  retrievalTrace?: KnowledgeRetrievalTrace | null
+  title?: string
+  compact?: boolean
+  className?: string
+}) {
+  const explicit = Array.isArray(props.citations) ? dedupeCitations(props.citations) : []
+  const fallback = props.retrievalTrace?.hits ? dedupeCitations(props.retrievalTrace.hits) : []
+  const items = explicit.length > 0 ? explicit : fallback
+  if (items.length === 0) return null
+
+  const title = props.title || 'Grounding'
+  const compact = props.compact === true
+  const selected = explicit.length > 0
+
+  return (
+    <details className={`group rounded-[12px] border border-sky-400/15 bg-sky-400/[0.04] ${props.className || ''}`}>
+      <summary className="flex cursor-pointer list-none items-center gap-2 px-3.5 py-2.5 select-none [&::-webkit-details-marker]:hidden">
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" className="shrink-0 text-sky-300/70 transition-transform group-open:rotate-90">
+          <polyline points="9 18 15 12 9 6" />
+        </svg>
+        <span className="text-[11px] font-600 uppercase tracking-[0.05em] text-sky-200/80">{title}</span>
+        <span className="text-[10px] font-mono text-text-3/50">
+          {selected ? `${explicit.length} citation${explicit.length === 1 ? '' : 's'}` : `${fallback.length} retrieved`}
+        </span>
+        {props.retrievalTrace?.selectorStatus && (
+          <span className="ml-auto text-[10px] text-text-3/45">
+            {props.retrievalTrace.selectorStatus === 'selected'
+              ? 'selected'
+              : props.retrievalTrace.selectorStatus === 'no_match'
+                ? 'candidates'
+                : 'retrieved'}
+          </span>
+        )}
+      </summary>
+
+      <div className="space-y-2 px-3.5 pb-3 pt-1">
+        {props.retrievalTrace?.query && (
+          <div className="rounded-[10px] border border-white/[0.06] bg-black/20 px-3 py-2 text-[11px] text-text-3/75">
+            Query: <span className="text-text-2">{props.retrievalTrace.query}</span>
+          </div>
+        )}
+
+        {items.map((citation) => (
+          <div key={`${citation.sourceId}:${citation.chunkId}`} className="rounded-[10px] border border-white/[0.06] bg-black/15 px-3 py-2.5">
+            <div className="flex items-start justify-between gap-3">
+              <div className="min-w-0">
+                <div className="text-[12px] font-600 text-text-2">{citation.sourceTitle}</div>
+                <div className="mt-0.5 text-[10px] text-text-3/60">
+                  Chunk {citation.chunkIndex + 1} of {citation.chunkCount}
+                  {citation.sectionLabel ? ` • ${citation.sectionLabel}` : ''}
+                </div>
+              </div>
+              <div className="shrink-0 text-[10px] font-mono text-text-3/55">
+                {citation.score.toFixed(2)}
+              </div>
+            </div>
+
+            {citation.whyMatched && (
+              <div className="mt-2 text-[11px] text-sky-100/78">{citation.whyMatched}</div>
+            )}
+
+            <div className={`mt-2 whitespace-pre-wrap break-words text-text-2/85 ${compact ? 'text-[11px]' : 'text-[12px]'}`}>
+              {citation.snippet}
+            </div>
+
+            {(citation.sourceLabel || citation.sourceUrl) && (
+              <div className="mt-2 flex flex-wrap items-center gap-2 text-[10px] text-text-3/55">
+                {citation.sourceLabel && <span>{citation.sourceLabel}</span>}
+                {citation.sourceUrl && (
+                  <a href={citation.sourceUrl} target="_blank" rel="noreferrer" className="text-sky-300 hover:underline">
+                    open source
+                  </a>
+                )}
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+    </details>
+  )
+}