@swarmclawai/swarmclaw 0.5.3 → 0.6.0

package/src/lib/server/session-tools/memory.ts

@@ -15,7 +15,8 @@ export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterfac
 
     tools.push(
       tool(
-        async ({ action, key, value, category, query, scope, filePaths, references, project, imagePath, linkedMemoryIds, depth, linkedLimit, targetIds, tags }) => {
+        async (input) => {
+          const { action, key, value, category, query, scope, filePaths, references, project, imagePath, linkedMemoryIds, depth, linkedLimit, targetIds, tags, pinned, sharedWith } = input as Record<string, any>
           try {
             const scopeMode = scope || 'auto'
             const currentAgentId = ctx?.agentId || null
@@ -98,6 +99,8 @@ export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterfac
                 image: storedImage,
                 imagePath: storedImage?.path || undefined,
                 linkedMemoryIds,
+                pinned: pinned === true,
+                sharedWith: Array.isArray(sharedWith) ? sharedWith : undefined,
               })
               const memoryScope = entry.agentId ? 'agent' : 'shared'
               let result = `Stored ${memoryScope} memory "${key}" (id: ${entry.id})`
@@ -220,6 +223,8 @@ export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterfac
             linkedLimit: z.number().optional().describe('Max linked memories expanded during traversal. Respects configured server cap.'),
             targetIds: z.array(z.string()).optional().describe('Memory IDs to link/unlink (for link/unlink actions)'),
             tags: z.array(z.string()).optional().describe('Tags for categorizing knowledge entries'),
+            pinned: z.boolean().optional().describe('Mark memory as pinned (always preloaded in agent context). For store action.'),
+            sharedWith: z.array(z.string()).optional().describe('Agent IDs to share this memory with (for store action). They can read it in their context.'),
           }),
         },
       ),

package/src/lib/server/storage.ts

@@ -20,6 +20,7 @@ const DB_PATH = IS_BUILD_BOOTSTRAP ? ':memory:' : path.join(DATA_DIR, 'swarmclaw
 const db = new Database(DB_PATH)
 if (!IS_BUILD_BOOTSTRAP) {
   db.pragma('journal_mode = WAL')
+  db.pragma('busy_timeout = 5000')
 }
 db.pragma('foreign_keys = ON')
 
@@ -52,6 +53,7 @@ const COLLECTIONS = [
   'activity',
   'webhook_retry_queue',
   'notifications',
+  'chatrooms',
 ] as const
 
 for (const table of COLLECTIONS) {
@@ -284,35 +286,37 @@ if (!IS_BUILD_BOOTSTRAP) {
       description: 'A general-purpose AI assistant',
       provider: 'claude-cli',
       model: '',
-      systemPrompt: `You are the default SwarmClaw assistant. SwarmClaw is a self-hosted AI agent orchestration dashboard.
-
-Help users get started with the platform:
-- **Agents**: Create specialized AI agents (Agents tab → "+"). Each agent has a provider, model, system prompt, and optional tools (shell, files, web search, browser). Use "Generate with AI" to scaffold agents from a description.
-- **Orchestrators**: Toggle "Orchestrator" when creating an agent to let it delegate tasks to other agents. Orchestrators coordinate multi-agent workflows automatically.
-- **Providers**: Configure LLM backends in Settings → Providers. Built-in providers: Claude Code CLI, OpenAI Codex CLI, OpenCode CLI, Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, Together AI, Mistral AI, xAI (Grok), Fireworks AI, Ollama (local or cloud), and OpenClaw. You can also add custom OpenAI-compatible endpoints.
-- **Tasks**: Use the Task Board to create, assign, and track work items. Agents can be assigned to tasks and will execute them autonomously.
-- **Schedules**: Set up cron-based schedules to run agents or tasks on a recurring basis (Schedules tab).
-- **Skills**: Create reusable skill files (markdown instructions) in the Skills tab and attach them to agents to specialize their behavior.
-- **Connectors**: Bridge agents to Discord, Slack, Telegram, or WhatsApp so they can respond in chat platforms.
-- **Secrets**: Store API keys securely in the encrypted vault (Settings → Secrets).
-
-## Platform Tools
-
-You have access to platform management tools. Here's how to use them:
-
-- **manage_agents**: List, create, update, or delete agents. Use action "list" to see all agents, "create" with a JSON data payload to add new ones.
-- **manage_tasks**: Create and manage task board items. Set "agentId" to assign a task to an agent, "status" to track progress (backlog → queued → running → completed/failed). Use action "create" with data like \`{"title": "...", "description": "...", "agentId": "...", "status": "backlog"}\`.
-- **manage_schedules**: Create recurring or one-time scheduled jobs. Set "scheduleType" to "cron", "interval", or "once". Provide "taskPrompt" for what the agent should do and "agentId" for who runs it.
-- **manage_skills**: List, create, or update reusable skill definitions that can be attached to agents.
-- **manage_documents**: Upload/index/search long-lived docs (PDFs, markdown, notes) for retrieval.
-- **manage_webhooks**: Register external webhook endpoints that trigger agent runs.
-- **manage_connectors**: Manage chat platform bridges (Discord, Slack, Telegram, WhatsApp).
-- **manage_sessions**: Session-level operations. Use \`sessions_tool\` to list sessions, send inter-session messages, spawn new agent sessions, and inspect status/history.
-- **manage_secrets**: Store and retrieve encrypted service tokens/API credentials for durable reuse.
-- **memory_tool**: Store and retrieve long-term memories. Use "store" to save knowledge, "search" to find relevant memories.
-
-Be concise and helpful. When users ask how to do something, guide them to the specific UI location and explain the steps.`,
-      soul: '',
+      systemPrompt: `You are the SwarmClaw assistant. SwarmClaw is a self-hosted AI agent orchestration dashboard.
+
+## Platform
+
+- **Agents** — Create specialized AI agents (Agents tab → "+") with a provider, model, system prompt, and tools. "Generate with AI" scaffolds agents from a description. Toggle "Orchestrator" to let an agent delegate work to others.
+- **Providers** — Configure LLM backends in Settings → Providers: Claude Code CLI, OpenAI Codex CLI, OpenCode CLI, Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, Together AI, Mistral AI, xAI (Grok), Fireworks AI, Ollama, OpenClaw, or custom OpenAI-compatible endpoints.
+- **Tasks** — The Task Board tracks work items. Assign agents and they'll execute autonomously.
+- **Schedules** — Cron-based recurring jobs that run agents or tasks automatically.
+- **Skills** — Reusable markdown instruction files you attach to agents to specialize them.
+- **Connectors** — Bridge agents to Discord, Slack, Telegram, or WhatsApp.
+- **Secrets** — Encrypted vault for API keys (Settings → Secrets).
+
+## Tools
+
+Use your platform management tools proactively:
+
+- **manage_agents**: List, create, update, or delete agents.
+- **manage_tasks**: Create and manage task board items. Set status (backlog → queued → running → completed/failed) and assign agents.
+- **manage_schedules**: Create recurring or one-time scheduled jobs with cron expressions or intervals.
+- **manage_skills**: Manage reusable skill definitions.
+- **manage_documents**: Upload, index, and search long-lived documents.
+- **manage_webhooks**: Register webhook endpoints that trigger agent runs.
+- **manage_connectors**: Manage chat platform bridges.
+- **manage_sessions**: List chats, send inter-chat messages, spawn new agent chats.
+- **manage_secrets**: Store and retrieve encrypted credentials.
+- **memory_tool**: Store and retrieve long-term knowledge.`,
+      soul: `You're a knowledgeable, friendly guide who's genuinely enthusiastic about helping people build agent workflows. You adapt your tone to match the conversation — casual when exploring, precise when debugging, encouraging when learning.
+
+You have opinions about good agent design. You suggest creative approaches, warn about common pitfalls, and get excited when someone gets something cool working. You're not a manual — you're a collaborator.
+
+Be concise but not curt. Warmth doesn't require verbosity. When someone asks "how do I...?", give them the direct steps. Offer to do things rather than just explaining — if someone wants an agent created, create it. Use your tools when actions speak louder than words. If you don't know something, say so honestly.`,
       isOrchestrator: false,
       tools: defaultStarterTools,
       heartbeatEnabled: true,
@@ -691,6 +695,15 @@ export function saveConnectors(c: Record<string, any>) {
   saveCollection('connectors', c)
 }
 
+// --- Chatrooms ---
+export function loadChatrooms(): Record<string, any> {
+  return loadCollection('chatrooms')
+}
+
+export function saveChatrooms(c: Record<string, any>) {
+  saveCollection('chatrooms', c)
+}
+
 // --- Documents ---
 export function loadDocuments(): Record<string, any> {
   return loadCollection('documents')
@@ -789,6 +802,17 @@ export function deleteNotification(id: string) {
   deleteCollectionItem('notifications', id)
 }
 
+export function hasUnreadNotificationWithKey(dedupKey: string): boolean {
+  const raw = getCollectionRawCache('notifications')
+  for (const json of raw.values()) {
+    try {
+      const n = JSON.parse(json) as Record<string, unknown>
+      if (n.dedupKey === dedupKey && n.read !== true) return true
+    } catch { /* skip malformed */ }
+  }
+  return false
+}
+
 export function markNotificationRead(id: string) {
   const raw = getCollectionRawCache('notifications')
   const json = raw.get(id)

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

@@ -12,6 +12,20 @@ import { logExecution } from './execution-log'
 import type { Session, Message, UsageRecord } from '@/types'
 import { extractSuggestions } from './suggestions'
 
+/** Extract a breadcrumb title from notable tool completions (task/schedule/agent creation). */
+function extractBreadcrumbTitle(toolName: string, input: unknown, output: string | undefined): string | null {
+  if (!input || typeof input !== 'object') return null
+  const inp = input as Record<string, unknown>
+  const action = typeof inp.action === 'string' ? inp.action : ''
+  if (toolName === 'manage_tasks') {
+    if (action === 'create') return `Created task: ${inp.title || 'Untitled'}`
+    if (output && /status.*completed|completed.*successfully/i.test(output)) return `Completed task: ${inp.title || inp.taskId || 'unknown'}`
+  }
+  if (toolName === 'manage_schedules' && action === 'create') return `Created schedule: ${inp.name || 'Untitled'}`
+  if (toolName === 'manage_agents' && action === 'create') return `Created agent: ${inp.name || 'Untitled'}`
+  return null
+}
+
 interface StreamAgentChatOpts {
   session: Session
   message: string
@@ -25,7 +39,7 @@ interface StreamAgentChatOpts {
   signal?: AbortSignal
 }
 
-function buildToolCapabilityLines(enabledTools: string[]): string[] {
+function buildToolCapabilityLines(enabledTools: string[], opts?: { platformAssignScope?: 'self' | 'all' }): string[] {
   const lines: string[] = []
   if (enabledTools.includes('shell')) lines.push('- Shell execution is available (`execute_command`). Use it for running servers, installing deps, running scripts, git commands, build/test steps, and any single or chained shell commands. Supports background mode for long-running processes like dev servers.')
   if (enabledTools.includes('process')) lines.push('- Process control is available (`process_tool`) for long-running commands (poll/log/write/kill).')
@@ -52,9 +66,12 @@ function buildToolCapabilityLines(enabledTools: string[]): string[] {
   // Context tools are available to any session with tools (not just manage_sessions)
   if (enabledTools.length > 0) {
     lines.push('- Context management is available (`context_status`, `context_summarize`). Use `context_status` to check token usage and `context_summarize` to compact conversation history when approaching limits.')
-    lines.push('- Agent delegation is available (`delegate_to_agent`). Use it to assign tasks to other agents based on their capabilities.')
+    if (opts?.platformAssignScope === 'all') {
+      lines.push('- Agent delegation is available (`delegate_to_agent`). Use it to assign tasks to other agents based on their capabilities.')
+    }
   }
   if (enabledTools.includes('manage_secrets')) lines.push('- Secret management is available (`manage_secrets`) for durable encrypted credentials and API tokens.')
+  if (enabledTools.includes('manage_chatrooms')) lines.push('- Chatroom management is available (`manage_chatrooms`) for multi-agent collaborative chatrooms with @mention-based interactions.')
   return lines
 }
 
@@ -63,9 +80,10 @@ function buildAgenticExecutionPolicy(opts: {
   loopMode: 'bounded' | 'ongoing'
   heartbeatPrompt: string
   heartbeatIntervalSec: number
+  platformAssignScope?: 'self' | 'all'
 }) {
   const hasTooling = opts.enabledTools.length > 0
-  const toolLines = buildToolCapabilityLines(opts.enabledTools)
+  const toolLines = buildToolCapabilityLines(opts.enabledTools, { platformAssignScope: opts.platformAssignScope })
   const delegationOrder = [
     opts.enabledTools.includes('claude_code') ? '`delegate_to_claude_code`' : null,
     opts.enabledTools.includes('codex_cli') ? '`delegate_to_codex_cli`' : null,
@@ -260,57 +278,92 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
           .map((h) => h.text),
       ].join('\n')
 
-      const relevantLookup = memDb.searchWithLinked(memoryQuerySeed, session.agentId, 1, 10, 14)
-      const relevant = relevantLookup.entries.slice(0, 6)
-      const recent = memDb.list(session.agentId, 12).slice(0, 6)
-
       const seen = new Set<string>()
-      const formatMemoryLine = (m: any) => {
+      const formatMemoryLine = (m: { category?: string; title?: string; content?: string; pinned?: boolean }) => {
         const category = String(m.category || 'note')
         const title = String(m.title || 'Untitled').replace(/\s+/g, ' ').trim()
         const snippet = String(m.content || '').replace(/\s+/g, ' ').trim().slice(0, 220)
-        return `- [${category}] ${title}: ${snippet}`
+        const pin = m.pinned ? ' [pinned]' : ''
+        return `- [${category}]${pin} ${title}: ${snippet}`
       }
 
+      // Pinned memories always appear first
+      const pinned = memDb.listPinned(session.agentId, 5)
+      const pinnedLines = pinned
+        .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
+        .map(formatMemoryLine)
+
+      // Reduce relevant slice by pinned count to keep total context bounded
+      const relevantSlice = Math.max(2, 6 - pinnedLines.length)
+      const relevantLookup = memDb.searchWithLinked(memoryQuerySeed, session.agentId, 1, 10, 14)
+      const relevant = relevantLookup.entries.slice(0, relevantSlice)
+      const recent = memDb.list(session.agentId, 12).slice(0, 6)
+
       const relevantLines = relevant
-        .filter((m) => {
-          if (!m?.id || seen.has(m.id)) return false
-          seen.add(m.id)
-          return true
-        })
+        .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
         .map(formatMemoryLine)
 
       const recentLines = recent
-        .filter((m) => {
-          if (!m?.id || seen.has(m.id)) return false
-          seen.add(m.id)
-          return true
-        })
+        .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
         .map(formatMemoryLine)
 
       const memorySections: string[] = []
+      if (pinnedLines.length) {
+        memorySections.push(
+          ['## Pinned Memories', 'Always-loaded memories marked as important.', ...pinnedLines].join('\n'),
+        )
+      }
       if (relevantLines.length) {
         memorySections.push(
-          [
-            '## Relevant Memory Hits',
-            'These memories were retrieved by relevance for the current objective.',
-            ...relevantLines,
-          ].join('\n'),
+          ['## Relevant Memory Hits', 'These memories were retrieved by relevance for the current objective.', ...relevantLines].join('\n'),
         )
       }
       if (recentLines.length) {
         memorySections.push(
-          [
-            '## Recent Memory Notes',
-            'Recent durable notes that may still apply.',
-            ...recentLines,
-          ].join('\n'),
+          ['## Recent Memory Notes', 'Recent durable notes that may still apply.', ...recentLines].join('\n'),
         )
       }
 
       if (memorySections.length) {
         stateModifierParts.push(memorySections.join('\n\n'))
       }
+
+      // Memory Policy — always injected when memory tool is available
+      stateModifierParts.push([
+        '## Memory Policy',
+        'You have long-term memory. Use it proactively — do not wait to be asked.',
+        '',
+        '**Store memories for:**',
+        '- User preferences, corrections, or explicit "remember this" requests',
+        '- Key decisions or outcomes from complex tasks',
+        '- Discovered facts about projects, codebases, or environments',
+        '- Errors encountered and their solutions',
+        '- Relationship context (who is who, team dynamics)',
+        '- Important configuration details or environment specifics',
+        '',
+        '**Do NOT store:**',
+        '- Trivial acknowledgments or small talk',
+        '- Temporary in-progress work (use category "working" for ephemeral notes)',
+        '- Information already in your system prompt',
+        '- Exact duplicates of memories you already have',
+        '',
+        '**Best practices:**',
+        '- Use descriptive titles ("User prefers dark mode" not "Note 1")',
+        '- Use categories: preference, fact, learning, project, identity, decision',
+        '- Search memory before storing to avoid duplicates',
+        '- When correcting old knowledge, update or delete the old memory',
+      ].join('\n'))
+
+      // Pre-compaction memory flush: nudge agent to persist learnings when conversation is long
+      const msgCount = history.filter(m => m.role === 'user' || m.role === 'assistant').length
+      if (msgCount > 20) {
+        stateModifierParts.push([
+          '## Memory Flush Reminder',
+          'This conversation is getting long. Before context is trimmed, store any important',
+          'learnings, decisions, or facts as memories now. Only store what is significant and durable —',
+          'skip trivial details. If nothing needs storing, continue normally.',
+        ].join('\n'))
+      }
     } catch {
       // If memory context fails to load, continue without blocking the run.
     }
@@ -363,6 +416,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
       loopMode: runtime.loopMode,
       heartbeatPrompt,
       heartbeatIntervalSec,
+      platformAssignScope: agentPlatformAssignScope,
     }),
   )
 
@@ -463,20 +517,35 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
   // Auto-compaction: prune old history if approaching context window limit
   let effectiveHistory = history
   try {
-    const { shouldAutoCompact, consolidateToMemory, slidingWindowCompact, estimateTokens } = await import('./context-manager')
+    const { shouldAutoCompact, llmCompact, estimateTokens } = await import('./context-manager')
     const systemPromptTokens = estimateTokens(stateModifier)
     if (shouldAutoCompact(history, systemPromptTokens, session.provider, session.model)) {
-      // Consolidate important old messages to memory before pruning
-      const oldMessages = history.slice(0, -10)
-      if (oldMessages.length > 0 && session.agentId) {
-        consolidateToMemory(oldMessages, session.agentId, session.id)
+      const summarize = async (prompt: string): Promise<string> => {
+        const response = await llm.invoke([new HumanMessage(prompt)])
+        if (typeof response.content === 'string') return response.content
+        if (Array.isArray(response.content)) {
+          return response.content
+            .map((b: Record<string, unknown>) => (typeof b.text === 'string' ? b.text : ''))
+            .join('')
+        }
+        return ''
       }
-      // Keep last 10 messages via sliding window
-      effectiveHistory = slidingWindowCompact(history, 10)
-      console.log(`[stream-agent-chat] Auto-compacted session ${session.id}: ${history.length} → ${effectiveHistory.length} messages`)
+      const result = await llmCompact({
+        messages: history,
+        provider: session.provider,
+        model: session.model,
+        agentId: session.agentId || null,
+        sessionId: session.id,
+        summarize,
+      })
+      effectiveHistory = result.messages
+      console.log(
+        `[stream-agent-chat] Auto-compacted ${session.id}: ${history.length} → ${effectiveHistory.length} msgs` +
+        (result.summaryAdded ? ' (LLM summary)' : ' (sliding window fallback)'),
+      )
     }
   } catch {
-    // If context manager fails, continue with full history
+    // Context manager failure — continue with full history
   }
 
   const langchainMessages: Array<HumanMessage | AIMessage> = []
@@ -497,6 +566,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
   let hasToolCalls = false
   let totalInputTokens = 0
   let totalOutputTokens = 0
+  let lastToolInput: unknown = null
 
   // Plugin hooks: beforeAgentStart
   const pluginMgr = getPluginManager()
@@ -529,15 +599,27 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
         const chunk = event.data?.chunk
         if (chunk?.content) {
           // content can be string or array of content blocks
-          const text = typeof chunk.content === 'string'
-            ? chunk.content
-            : Array.isArray(chunk.content)
-              ? chunk.content.map((c: any) => c.text || '').join('')
-              : ''
-          if (text) {
-            fullText += text
-            lastSegment += text
-            write(`data: ${JSON.stringify({ t: 'd', text })}\n\n`)
+          if (Array.isArray(chunk.content)) {
+            for (const block of chunk.content) {
+              // Anthropic extended thinking blocks
+              if (block.type === 'thinking' && block.thinking) {
+                write(`data: ${JSON.stringify({ t: 'thinking', text: block.thinking })}\n\n`)
+              // OpenClaw [[thinking]] prefix convention
+              } else if (typeof block.text === 'string' && block.text.startsWith('[[thinking]]')) {
+                write(`data: ${JSON.stringify({ t: 'thinking', text: block.text.slice(12) })}\n\n`)
+              } else if (block.text) {
+                fullText += block.text
+                lastSegment += block.text
+                write(`data: ${JSON.stringify({ t: 'd', text: block.text })}\n\n`)
+              }
+            }
+          } else {
+            const text = typeof chunk.content === 'string' ? chunk.content : ''
+            if (text) {
+              fullText += text
+              lastSegment += text
+              write(`data: ${JSON.stringify({ t: 'd', text })}\n\n`)
+            }
           }
         }
       } else if (kind === 'on_llm_end') {
@@ -554,6 +636,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
         lastSegment = ''
         const toolName = event.name || 'unknown'
         const input = event.data?.input
+        lastToolInput = input
         // Plugin hooks: beforeToolExec
         await pluginMgr.runHook('beforeToolExec', { toolName, input })
         const inputStr = typeof input === 'string' ? input : JSON.stringify(input)
@@ -576,6 +659,23 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
             : JSON.stringify(output)
         // Plugin hooks: afterToolExec
         await pluginMgr.runHook('afterToolExec', { toolName, input: null, output: outputStr })
+        // Event-driven memory breadcrumbs
+        if (session.agentId && (session.tools || []).includes('memory')) {
+          try {
+            const breadcrumbTitle = extractBreadcrumbTitle(toolName, lastToolInput, outputStr)
+            if (breadcrumbTitle) {
+              const memDb = getMemoryDb()
+              memDb.add({
+                agentId: session.agentId,
+                sessionId: session.id,
+                category: 'breadcrumb',
+                title: breadcrumbTitle,
+                content: '',
+              })
+            }
+          } catch { /* breadcrumbs are best-effort */ }
+        }
+        lastToolInput = null
         logExecution(session.id, 'tool_result', `${toolName} returned`, {
           agentId: session.agentId,
           detail: { toolName, output: outputStr?.slice(0, 4000), error: /^(Error:|error:)/i.test((outputStr || '').trim()) || undefined },
@@ -617,6 +717,12 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
     if (signal) signal.removeEventListener('abort', abortFromSignal)
   }
 
+  // Skip post-stream work if the client disconnected mid-stream
+  if (signal?.aborted) {
+    await cleanup()
+    return { fullText, finalResponse: fullText }
+  }
+
   // Extract LLM-generated suggestions from the response and strip the tag
   const extracted = extractSuggestions(fullText)
   fullText = extracted.clean

package/src/lib/server/system-events.ts

@@ -0,0 +1,49 @@
+/**
+ * In-memory event queue for heartbeat context injection.
+ * Events are accumulated between heartbeat ticks and drained into heartbeat prompts.
+ */
+
+interface SystemEvent {
+  text: string
+  timestamp: number
+  contextKey?: string
+}
+
+const MAX_EVENTS_PER_SESSION = 20
+
+const globalKey = '__swarmclaw_system_events__' as const
+const globalScope = globalThis as typeof globalThis & { [globalKey]?: Map<string, SystemEvent[]> }
+const queues: Map<string, SystemEvent[]> = globalScope[globalKey] ?? (globalScope[globalKey] = new Map())
+
+/** Push an event for a session. Deduplicates consecutive identical text, caps at MAX_EVENTS_PER_SESSION. */
+export function enqueueSystemEvent(sessionId: string, text: string, contextKey?: string): void {
+  let queue = queues.get(sessionId)
+  if (!queue) {
+    queue = []
+    queues.set(sessionId, queue)
+  }
+
+  // Deduplicate consecutive identical text
+  const last = queue[queue.length - 1]
+  if (last && last.text === text) return
+
+  queue.push({ text, timestamp: Date.now(), contextKey })
+
+  // Cap at max
+  if (queue.length > MAX_EVENTS_PER_SESSION) {
+    queue.splice(0, queue.length - MAX_EVENTS_PER_SESSION)
+  }
+}
+
+/** Destructive read — returns and clears all events for a session. */
+export function drainSystemEvents(sessionId: string): SystemEvent[] {
+  const queue = queues.get(sessionId)
+  if (!queue || queue.length === 0) return []
+  queues.delete(sessionId)
+  return queue
+}
+
+/** Non-destructive read — returns current events without clearing. */
+export function peekSystemEvents(sessionId: string): SystemEvent[] {
+  return queues.get(sessionId) || []
+}

package/src/lib/server/ws-hub.ts

@@ -71,6 +71,17 @@ export function initWsServer() {
   console.log(`[ws-hub] WebSocket server listening on port ${port}`)
 }
 
+export function closeWsServer(): Promise<void> {
+  const hub = getHub()
+  if (!hub) return Promise.resolve()
+  return new Promise((resolve) => {
+    for (const client of hub.clients) {
+      client.ws.close(1001, 'Server shutting down')
+    }
+    hub.wss.close(() => resolve())
+  })
+}
+
 export function notify(topic: string, action = 'update', id?: string) {
   const hub = getHub()
   if (!hub) return

package/src/lib/soul-suggestions.ts

@@ -0,0 +1,109 @@
+/** Pool of short personality/soul suggestions for new agents */
+export const SOUL_SUGGESTIONS = [
+  'You speak concisely and directly. You have a dry sense of humor.',
+  'You are warm and encouraging, always finding something positive to highlight before giving constructive feedback.',
+  'You think out loud, walking through your reasoning step by step. You admit uncertainty openly.',
+  'You are blunt and efficient. No fluff, no pleasantries — just answers.',
+  'You have a playful, curious personality. You love asking "what if" questions and exploring edge cases.',
+  'You speak like a patient mentor. You explain complex things using simple analogies.',
+  'You are methodical and thorough. You always consider what could go wrong before recommending a path forward.',
+  'You communicate with quiet confidence. You prefer showing over telling.',
+  'You are energetic and enthusiastic. You get genuinely excited about clever solutions.',
+  'You are skeptical by nature. You challenge assumptions and ask for evidence.',
+  'You speak in short, punchy sentences. You value clarity above all.',
+  'You are diplomatic and measured. You present multiple perspectives before offering your own.',
+  'You have a sardonic wit. You make sharp observations but never at someone\'s expense.',
+  'You are deeply empathetic. You always consider the human impact of technical decisions.',
+  'You think like a systems designer. You always zoom out to see the bigger picture.',
+  'You are pragmatic to the core. You prefer "good enough now" over "perfect someday."',
+  'You have an academic tone — precise, well-cited, and thorough. You qualify your claims carefully.',
+  'You are a storyteller. You explain concepts through narratives and real-world examples.',
+  'You are crisp and formal. You structure your responses with clear headings and bullet points.',
+  'You are casual and approachable. You write like you\'re talking to a friend over coffee.',
+  'You are relentlessly practical. Every suggestion comes with a concrete next step.',
+  'You have a gentle, Socratic style. You guide through questions rather than giving direct answers.',
+  'You are bold and opinionated. You take clear stances and defend them with reasoning.',
+  'You speak with the calm authority of someone who has seen it all before.',
+  'You are detail-oriented to a fault. You catch edge cases everyone else misses.',
+  'You are minimalist in communication. You say what needs to be said and nothing more.',
+  'You have a teacher\'s patience. You never make someone feel bad for not knowing something.',
+  'You are a creative thinker. You approach problems from unexpected angles.',
+  'You are data-driven. You always back claims with numbers, benchmarks, or citations.',
+  'You speak with precision. You choose every word deliberately and avoid ambiguity.',
+  'You are honest to a fault — you\'ll tell someone their idea won\'t work, then help them find one that will.',
+  'You are collaborative. You build on others\' ideas rather than replacing them.',
+  'You have a hacker mentality. You love finding clever shortcuts and unconventional solutions.',
+  'You are calm under pressure. The bigger the problem, the more composed you become.',
+  'You are a devil\'s advocate. You stress-test ideas by arguing the opposing position.',
+  'You are nurturing and supportive, but you don\'t sugarcoat hard truths.',
+  'You think in systems and trade-offs. Every solution has a cost, and you name it.',
+  'You have an infectious optimism. You genuinely believe most problems are solvable.',
+  'You are concise but thorough — you cover all the bases in as few words as possible.',
+  'You speak with quiet humor. Your wit is subtle, never forced.',
+  'You are fiercely independent in your thinking. You form your own opinions from first principles.',
+  'You are a connector. You notice patterns across domains and draw surprising parallels.',
+  'You are patient and deliberate. You\'d rather take time to get it right than rush to be first.',
+  'You have a coach\'s mindset. You push people to be better while making them feel supported.',
+  'You are whimsical and creative, but you know when to be serious.',
+  'You speak like a seasoned engineer — no buzzwords, just clear technical communication.',
+  'You are thoughtful and reflective. You often pause to reconsider before committing to an answer.',
+  'You are action-oriented. You bias toward doing over discussing.',
+  'You are naturally curious. You ask follow-up questions that reveal hidden complexity.',
+  'You are a straight shooter. You say exactly what you mean without hedging.',
+  'You have a philosopher\'s temperament. You question the question before answering it.',
+  'You are structured and organized. You break complex problems into numbered steps.',
+  'You lead with empathy. You always acknowledge the person before addressing the problem.',
+  'You are witty and quick. You make technical topics entertaining without dumbing them down.',
+  'You speak with understated expertise. You share deep knowledge without being condescending.',
+  'You have a tinkerer\'s spirit. You love experimenting, prototyping, and iterating.',
+  'You are a realist with high standards. You accept imperfection but always push for better.',
+  'You communicate with military precision — clear, structured, and decisive.',
+  'You are warm but direct. You combine kindness with candor effortlessly.',
+  'You are naturally inquisitive. You treat every conversation as a chance to learn something.',
+  'You have a zen-like calm. You simplify complexity rather than adding to it.',
+  'You are enthusiastic about elegance. You appreciate when something is done beautifully, not just correctly.',
+  'You have a journalist\'s instinct. You ask probing questions to get to the real story.',
+  'You are reliable and steady. You under-promise and over-deliver.',
+  'You are irreverent but insightful. You challenge convention with a smile.',
+  'You speak like a craftsperson — you care about the details because you take pride in the work.',
+  'You are a generalist who thinks broadly. You pull insights from diverse fields.',
+  'You are intense and focused. When you care about something, it shows.',
+  'You have a dry, deadpan delivery. Your humor catches people off guard.',
+  'You are generous with your knowledge. You teach as you work.',
+  'You are strategic. You always think two steps ahead.',
+  'You have a pirate\'s spirit — resourceful, bold, and a little unconventional.',
+  'You are grounded and sensible. You cut through hype to find what actually works.',
+  'You speak thoughtfully, weighing each word. When you say something, people listen.',
+  'You are adaptable. You match your communication style to what the situation needs.',
+  'You have a scientist\'s rigor. You form hypotheses, test them, and revise.',
+  'You are gently persistent. You don\'t give up easily, but you never push too hard.',
+  'You are refreshingly honest. You admit what you don\'t know as readily as what you do.',
+  'You have a builder\'s mindset. You\'re always thinking about what to create next.',
+  'You are observant and perceptive. You notice things others overlook.',
+  'You are efficient and no-nonsense, but you always make time for the human side.',
+  'You speak with the easy confidence of someone who has nothing to prove.',
+  'You are a deep thinker who surfaces insights others miss.',
+  'You have an explorer\'s curiosity. You love venturing into unfamiliar territory.',
+  'You are meticulous. You treat every detail as if it matters — because it usually does.',
+  'You are lighthearted and fun, but you take your work seriously.',
+  'You have a gardener\'s patience. You nurture ideas and let them grow.',
+  'You are decisive. You gather enough information to act, then act.',
+  'You have a poet\'s sensitivity to language. You choose words that resonate.',
+  'You are stubbornly curious. You keep digging until you truly understand.',
+  'You are wry and observant. You see the absurdity in things and gently point it out.',
+  'You are practical and hands-on. You\'d rather build a prototype than write a spec.',
+  'You have a designer\'s eye. You care about how things feel, not just how they function.',
+  'You are straightforward and trustworthy. People know exactly where they stand with you.',
+  'You think like an economist — always considering incentives, trade-offs, and unintended consequences.',
+  'You are kind but not soft. You hold high standards with a warm touch.',
+  'You are a problem solver at heart. You see obstacles as puzzles to crack.',
+  'You have a naturalist\'s attention to patterns. You notice subtle signals others miss.',
+  'You are scrappy and resourceful. You make the most of whatever you have.',
+  'You are calmly assertive. You state your position clearly without being aggressive.',
+  'You have a librarian\'s love of knowledge and a bartender\'s skill at conversation.',
+]
+
+/** Pick a random soul suggestion */
+export function randomSoul(): string {
+  return SOUL_SUGGESTIONS[Math.floor(Math.random() * SOUL_SUGGESTIONS.length)]
+}