@swarmclawai/swarmclaw 0.4.5 → 0.5.0

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

@@ -135,14 +135,14 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
                   await inst.pinMessage(targetChannel, targetMessageId)
                   return JSON.stringify({ status: 'pinned', connectorId, messageId: targetMessageId })
                 }
-              } catch (err: any) {
-                return `Error: ${err.message || String(err)}`
+              } catch (err: unknown) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`
               }
             }
 
             return 'Unknown action. Use list_running, list_targets, or send.'
-          } catch (err: any) {
-            return `Error: ${err.message || String(err)}`
+          } catch (err: unknown) {
+            return `Error: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {

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

@@ -199,6 +199,21 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
                   return
                 }
 
+                // If resume failed because the session no longer exists, clear the stale ID
+                // and return a targeted error so the agent retries without resume
+                if (resumeIdToUse && /No conversation found/i.test(stdout + stderr)) {
+                  persistDelegateResumeId('claudeCode', null)
+                  log.warn('session-tools', 'delegate_to_claude_code stale resume ID cleared', {
+                    sessionId: ctx?.sessionId || null,
+                    staleResumeId: resumeIdToUse,
+                  })
+                  finish(
+                    `Error: The previous Claude Code session (${resumeIdToUse}) has expired and was cleared. ` +
+                    'Retry the task with resume=false to start a fresh session.',
+                  )
+                  return
+                }
+
                 const successText = assistantText.trim() || stdout.trim() || stderr.trim()
                 if (code === 0 && successText) {
                   const out = discoveredSessionId
@@ -230,7 +245,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
         },
         {
           name: 'delegate_to_claude_code',
-          description: 'Delegate a complex task to Claude Code CLI. Use for tasks that need deep code understanding, multi-file refactoring, or running tests. The task runs in the session working directory.',
+          description: 'Delegate a complex multi-file coding task to Claude Code CLI. ONLY for deep code understanding, multi-file refactoring, or large code generation. NEVER use this to run servers, dev servers, install dependencies, or execute commands — use execute_command for those (this tool\'s session ends and kills any running processes).',
           schema: z.object({
             task: z.string().describe('Detailed description of the task for Claude Code'),
             resume: z.boolean().optional().describe('If true, try to resume the last saved Claude delegation session for this SwarmClaw session'),
@@ -442,7 +457,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
         },
         {
           name: 'delegate_to_codex_cli',
-          description: 'Delegate a complex task to Codex CLI. Use for deep coding/refactor tasks and shell-driven implementation work.',
+          description: 'Delegate a complex multi-file coding task to Codex CLI. ONLY for deep code understanding, multi-file refactoring, or large code generation. NEVER use this to run servers, dev servers, install dependencies, or execute commands — use execute_command for those (this tool\'s session ends and kills any running processes).',
           schema: z.object({
             task: z.string().describe('Detailed description of the task for Codex CLI'),
             resume: z.boolean().optional().describe('If true, try to resume the last saved Codex delegation thread for this SwarmClaw session'),
@@ -607,7 +622,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
         },
         {
           name: 'delegate_to_opencode_cli',
-          description: 'Delegate a complex task to OpenCode CLI. Use for deep coding/refactor tasks and shell-driven implementation work.',
+          description: 'Delegate a complex multi-file coding task to OpenCode CLI. ONLY for deep code understanding, multi-file refactoring, or large code generation. NEVER use this to run servers, dev servers, install dependencies, or execute commands — use execute_command for those (this tool\'s session ends and kills any running processes).',
           schema: z.object({
             task: z.string().describe('Detailed description of the task for OpenCode CLI'),
             resume: z.boolean().optional().describe('If true, try to resume the last saved OpenCode delegation session for this SwarmClaw session'),
@@ -648,6 +663,7 @@ export function buildDelegateTools(bctx: ToolBuildContext): StructuredToolInterf
               description: taskDesc || taskPrompt,
               status: 'todo',
               agentId: resolvedId,
+              cwd,
               sourceType: 'delegation' as const,
               delegatedByAgentId: ctx.agentId!,
               createdAt: now,

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

@@ -26,8 +26,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             const resolved = safePath(bctx.cwd, filePath)
             const content = fs.readFileSync(resolved, 'utf-8')
             return truncate(content, MAX_FILE)
-          } catch (err: any) {
-            return `Error reading file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error reading file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -55,8 +55,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             }
             fs.writeFileSync(resolved, content, 'utf-8')
             return `File written: ${filePath} (${content.length} bytes)`
-          } catch (err: any) {
-            return `Error writing file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error writing file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -80,8 +80,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             const resolved = safePath(bctx.cwd, dirPath || '.')
             const tree = listDirRecursive(resolved, 0, 3)
             return tree.length ? tree.join('\n') : '(empty directory)'
-          } catch (err: any) {
-            return `Error listing files: ${err.message}`
+          } catch (err: unknown) {
+            return `Error listing files: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -109,8 +109,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             fs.mkdirSync(path.dirname(destination), { recursive: true })
             fs.copyFileSync(source, destination)
             return `File copied: ${sourcePath} -> ${destinationPath}`
-          } catch (err: any) {
-            return `Error copying file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error copying file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -141,8 +141,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             if (fs.existsSync(destination) && overwrite) fs.unlinkSync(destination)
             fs.renameSync(source, destination)
             return `File moved: ${sourcePath} -> ${destinationPath}`
-          } catch (err: any) {
-            return `Error moving file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error moving file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -175,8 +175,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             }
             fs.rmSync(resolved, { recursive: !!recursive, force: !!force })
             return `Deleted: ${filePath}`
-          } catch (err: any) {
-            return `Error deleting file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error deleting file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -220,8 +220,8 @@ export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[
             } else {
               return `[Download ${basename}](/api/uploads/${filename})`
             }
-          } catch (err: any) {
-            return `Error sending file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error sending file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -297,8 +297,8 @@ img{max-width:100%}
             } finally {
               await browser.close()
             }
-          } catch (err: any) {
-            return `Error creating document: ${err.message}`
+          } catch (err: unknown) {
+            return `Error creating document: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -383,8 +383,8 @@ img{max-width:100%}
             await workbook.xlsx.writeFile(resolved)
             const size = fs.statSync(resolved).size
             return `Excel spreadsheet created: ${outName} (${rows.length} rows, ${cols.length} columns, ${(size / 1024).toFixed(1)} KB)`
-          } catch (err: any) {
-            return `Error creating spreadsheet: ${err.message}`
+          } catch (err: unknown) {
+            return `Error creating spreadsheet: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -416,8 +416,8 @@ img{max-width:100%}
             const updated = content.replace(oldText, newText)
             fs.writeFileSync(resolved, updated, 'utf-8')
             return `Successfully edited ${filePath}`
-          } catch (err: any) {
-            return `Error editing file: ${err.message}`
+          } catch (err: unknown) {
+            return `Error editing file: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {

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

@@ -143,12 +143,12 @@ export async function buildSessionTools(cwd: string, enabledTools: string[], ctx
           type: 'tool_request',
           toolId,
           reason,
-          message: `Tool access request sent to user for "${toolId}". Wait for the user to grant access before trying to use it.`,
+          message: `Tool access request sent to user for "${toolId}". The user will be prompted to grant access — once granted, a follow-up message will arrive and you should immediately proceed with the original task using the newly available tool.`,
         })
       },
       {
         name: 'request_tool_access',
-        description: 'Request access to a tool that is currently disabled. The user will be prompted to grant access. Use this when you need a tool from the disabled tools list.',
+        description: 'Request access to a tool that is currently disabled. The user will be prompted to grant access, and a follow-up "Continue" message will be sent automatically once granted. End your current response after calling this — do NOT tell the user to "let you know" or ask them to confirm; the continuation is automatic.',
         schema: z.object({
           toolId: z.string().describe('The tool ID to request access for (e.g. manage_tasks, shell, claude_code)'),
           reason: z.string().describe('Brief explanation of why you need this tool'),

package/src/lib/server/session-tools/openclaw-nodes.ts

@@ -28,8 +28,8 @@ export function buildOpenClawNodeTools(bctx: ToolBuildContext): StructuredToolIn
             connectorId: openclawConnectors[0].id,
             note: 'This feature requires the OpenClaw gateway to support nodes.* RPCs.',
           })
-        } catch (err: any) {
-          return JSON.stringify({ error: err.message })
+        } catch (err: unknown) {
+          return JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
         }
       },
       {
@@ -59,8 +59,8 @@ export function buildOpenClawNodeTools(bctx: ToolBuildContext): StructuredToolIn
             params: params || null,
             connectorId: openclawConnectors[0].id,
           })
-        } catch (err: any) {
-          return JSON.stringify({ error: err.message })
+        } catch (err: unknown) {
+          return JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
         }
       },
       {
@@ -93,8 +93,8 @@ export function buildOpenClawNodeTools(bctx: ToolBuildContext): StructuredToolIn
             message,
             connectorId: openclawConnectors[0].id,
           })
-        } catch (err: any) {
-          return JSON.stringify({ error: err.message })
+        } catch (err: unknown) {
+          return JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
         }
       },
       {

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

@@ -177,8 +177,8 @@ export function buildSandboxTools(bctx: ToolBuildContext): StructuredToolInterfa
             const stdout = truncate((result.stdout || '').trim(), MAX_OUTPUT)
             const stderr = truncate((result.stderr || '').trim(), MAX_OUTPUT)
             return JSON.stringify({ exitCode: result.status ?? 0, stdout, stderr })
-          } catch (err: any) {
-            return JSON.stringify({ error: err.message })
+          } catch (err: unknown) {
+            return JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
           }
         },
         {

package/src/lib/server/session-tools/search-providers.ts

@@ -13,6 +13,13 @@ export interface WebSearchProvider {
   search(query: string, maxResults: number): Promise<SearchResult[]>
 }
 
+interface RawSearchResult {
+  title?: string
+  url?: string
+  content?: string
+  description?: string
+}
+
 const UA = 'Mozilla/5.0 (compatible; SwarmClaw/1.0)'
 
 // ---------------------------------------------------------------------------
@@ -162,8 +169,8 @@ class SearXNGProvider implements WebSearchProvider {
     })
     if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`)
     const data = await res.json()
-    const rawResults = Array.isArray(data.results) ? data.results : []
-    return rawResults.slice(0, maxResults).map((r: any) => ({
+    const rawResults: RawSearchResult[] = Array.isArray(data.results) ? data.results : []
+    return rawResults.slice(0, maxResults).map((r) => ({
       title: r.title || '',
       url: r.url || '',
       snippet: r.content || '',
@@ -194,8 +201,8 @@ class TavilyProvider implements WebSearchProvider {
     })
     if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`)
     const data = await res.json()
-    const rawResults = Array.isArray(data.results) ? data.results : []
-    return rawResults.slice(0, maxResults).map((r: any) => ({
+    const rawResults: RawSearchResult[] = Array.isArray(data.results) ? data.results : []
+    return rawResults.slice(0, maxResults).map((r) => ({
       title: r.title || '',
       url: r.url || '',
       snippet: r.content || '',
@@ -227,8 +234,8 @@ class BraveProvider implements WebSearchProvider {
     )
     if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`)
     const data = await res.json()
-    const rawResults = Array.isArray(data.web?.results) ? data.web.results : []
-    return rawResults.slice(0, maxResults).map((r: any) => ({
+    const rawResults: RawSearchResult[] = Array.isArray(data.web?.results) ? data.web.results : []
+    return rawResults.slice(0, maxResults).map((r) => ({
       title: r.title || '',
       url: r.url || '',
       snippet: r.description || '',

package/src/lib/server/session-tools/session-tools-wiring.test.ts

@@ -131,8 +131,8 @@ describe('MCP tool block type wiring', () => {
       'utf-8',
     )
     assert.ok(src.includes('mcpServerIds'), 'index.ts should reference mcpServerIds')
-    assert.ok(src.includes('mcp_list_tools'), 'index.ts should define mcp_list_tools tool')
-    assert.ok(src.includes('mcp_call'), 'index.ts should define mcp_call tool')
+    assert.ok(src.includes('connectMcpServer'), 'index.ts should connect configured MCP servers')
+    assert.ok(src.includes('mcpToolsToLangChain'), 'index.ts should inject MCP tools dynamically')
   })
 })
 

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

@@ -49,7 +49,7 @@ export function buildShellTools(bctx: ToolBuildContext): StructuredToolInterface
         },
         {
           name: 'execute_command',
-          description: 'Execute a shell command in the session working directory. Supports background mode and timeout/yield controls.',
+          description: 'Execute a shell command in the session working directory. This is the PRIMARY tool for running servers, dev servers, installing packages, running scripts, git operations, and any command the user wants to run or test. Use background=true for long-running processes like servers. Supports timeout/yield controls.',
           schema: z.object({
             command: z.string().describe('The shell command to execute'),
             background: z.boolean().optional().describe('If true, start command in background immediately'),

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

@@ -73,8 +73,8 @@ export function buildWebTools(bctx: ToolBuildContext): StructuredToolInterface[]
             return results.length > 0
               ? JSON.stringify(results, null, 2)
               : 'No results found.'
-          } catch (err: any) {
-            return `Error searching web: ${err.message}`
+          } catch (err: unknown) {
+            return `Error searching web: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -111,8 +111,8 @@ export function buildWebTools(bctx: ToolBuildContext): StructuredToolInterface[]
               .replace(/\s+/g, ' ')
               .trim()
             return truncate(text, MAX_OUTPUT)
-          } catch (err: any) {
-            return `Error fetching URL: ${err.message}`
+          } catch (err: unknown) {
+            return `Error fetching URL: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -316,8 +316,8 @@ export function buildWebTools(bctx: ToolBuildContext): StructuredToolInterface[]
               ? params.saveTo.trim()
               : undefined
             return await callMcpTool(mcpTool, args, { saveTo })
-          } catch (err: any) {
-            return `Error: ${err.message}`
+          } catch (err: unknown) {
+            return `Error: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
@@ -368,8 +368,8 @@ export function buildWebTools(bctx: ToolBuildContext): StructuredToolInterface[]
                 return `Error (exit ${result.status}): ${stderr || stdout || 'unknown error'}`
               }
               return truncate(stdout || '(no output)', MAX_OUTPUT)
-            } catch (err: any) {
-              return `Error: ${err.message}`
+            } catch (err: unknown) {
+              return `Error: ${err instanceof Error ? err.message : String(err)}`
             }
           },
           {

package/src/lib/server/storage.ts

@@ -5,6 +5,8 @@ import os from 'os'
 import Database from 'better-sqlite3'
 
 import { DATA_DIR, WORKSPACE_DIR } from './data-dir'
+import type { Message } from '@/types'
+import { ensureMainSessionFlag } from './main-session'
 export const UPLOAD_DIR = path.join(DATA_DIR, 'uploads')
 
 // Ensure directories exist
@@ -13,9 +15,12 @@ for (const dir of [DATA_DIR, UPLOAD_DIR, WORKSPACE_DIR]) {
 }
 
 // --- SQLite Database ---
-const DB_PATH = path.join(DATA_DIR, 'swarmclaw.db')
+const IS_BUILD_BOOTSTRAP = process.env.SWARMCLAW_BUILD_MODE === '1'
+const DB_PATH = IS_BUILD_BOOTSTRAP ? ':memory:' : path.join(DATA_DIR, 'swarmclaw.db')
 const db = new Database(DB_PATH)
-db.pragma('journal_mode = WAL')
+if (!IS_BUILD_BOOTSTRAP) {
+  db.pragma('journal_mode = WAL')
+}
 db.pragma('foreign_keys = ON')
 
 const collectionCacheKey = '__swarmclaw_storage_collection_cache__' as const
@@ -243,10 +248,12 @@ function migrateFromJson() {
   console.log('[storage] Migration complete. JSON files preserved as backup.')
 }
 
-migrateFromJson()
+if (!IS_BUILD_BOOTSTRAP) {
+  migrateFromJson()
+}
 
 // Seed default agent if agents table is empty
-{
+if (!IS_BUILD_BOOTSTRAP) {
   const defaultStarterTools = [
     'memory',
     'files',
@@ -305,6 +312,7 @@ Be concise and helpful. When users ask how to do something, guide them to the sp
       soul: '',
       isOrchestrator: false,
       tools: defaultStarterTools,
+      heartbeatEnabled: true,
       platformAssignScope: 'all',
       skillIds: [],
       subAgentIds: [],
@@ -341,10 +349,12 @@ function loadEnv() {
     })
   }
 }
-loadEnv()
+if (!IS_BUILD_BOOTSTRAP) {
+  loadEnv()
+}
 
 // Auto-generate CREDENTIAL_SECRET if missing
-if (!process.env.CREDENTIAL_SECRET) {
+if (!IS_BUILD_BOOTSTRAP && !process.env.CREDENTIAL_SECRET) {
   const secret = crypto.randomBytes(32).toString('hex')
   const envPath = path.join(process.cwd(), '.env.local')
   fs.appendFileSync(envPath, `\nCREDENTIAL_SECRET=${secret}\n`)
@@ -354,7 +364,7 @@ if (!process.env.CREDENTIAL_SECRET) {
 
 // Auto-generate ACCESS_KEY if missing (used for simple auth)
 const SETUP_FLAG = path.join(DATA_DIR, '.setup_pending')
-if (!process.env.ACCESS_KEY) {
+if (!IS_BUILD_BOOTSTRAP && !process.env.ACCESS_KEY) {
   const key = crypto.randomBytes(16).toString('hex')
   const envPath = path.join(process.cwd(), '.env.local')
   fs.appendFileSync(envPath, `\nACCESS_KEY=${key}\n`)
@@ -384,7 +394,31 @@ export function markSetupComplete(): void {
 
 // --- Sessions ---
 export function loadSessions(): Record<string, any> {
-  return loadCollection('sessions')
+  const sessions = loadCollection('sessions')
+  const agents = loadCollection('agents')
+  let changed = false
+
+  for (const [id, session] of Object.entries(sessions)) {
+    if (!session || typeof session !== 'object') continue
+
+    if (typeof session.id !== 'string' || !session.id.trim()) {
+      session.id = id
+      changed = true
+    }
+
+    const beforeMainFlag = session.mainSession === true
+    ensureMainSessionFlag(session)
+    if (!beforeMainFlag && session.mainSession === true) changed = true
+
+    const agentId = typeof session.agentId === 'string' ? session.agentId.trim() : ''
+    if (agentId && !Object.prototype.hasOwnProperty.call(agents, agentId)) {
+      session.agentId = null
+      changed = true
+    }
+  }
+
+  if (changed) saveCollection('sessions', sessions)
+  return sessions
 }
 
 export function saveSessions(s: Record<string, any>) {
@@ -452,8 +486,23 @@ export function decryptKey(encrypted: string): string {
 }
 
 // --- Agents ---
-export function loadAgents(): Record<string, any> {
-  return loadCollection('agents')
+export function loadAgents(opts?: { includeTrashed?: boolean }): Record<string, any> {
+  const all = loadCollection('agents')
+  if (opts?.includeTrashed) return all
+  const result: Record<string, any> = {}
+  for (const [id, agent] of Object.entries(all)) {
+    if (!agent.trashedAt) result[id] = agent
+  }
+  return result
+}
+
+export function loadTrashedAgents(): Record<string, any> {
+  const all = loadCollection('agents')
+  const result: Record<string, any> = {}
+  for (const [id, agent] of Object.entries(all)) {
+    if (agent.trashedAt) result[id] = agent
+  }
+  return result
 }
 
 export function saveAgents(p: Record<string, any>) {
@@ -527,12 +576,14 @@ export async function getSecret(key: string): Promise<{
   if (!needle) return null
 
   const secrets = loadSecrets()
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const matches = Object.values(secrets).find((secret: any) => {
     if (!secret || typeof secret !== 'object') return false
     const id = typeof secret.id === 'string' ? secret.id.toLowerCase() : ''
     const name = typeof secret.name === 'string' ? secret.name.toLowerCase() : ''
     const service = typeof secret.service === 'string' ? secret.service.toLowerCase() : ''
     return id === needle || name === needle || service === needle
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
   }) as any | undefined
 
   if (!matches) return null
@@ -690,7 +741,7 @@ export function appendWebhookLog(id: string, entry: any) {
   upsertCollectionItem('webhook_logs', id, entry)
 }
 
-export function getSessionMessages(sessionId: string): any[] {
+export function getSessionMessages(sessionId: string): Message[] {
   const stmt = db.prepare('SELECT data FROM sessions WHERE id = ?')
   const row = stmt.get(sessionId) as { data: string } | undefined
   if (!row) return []

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

@@ -10,6 +10,7 @@ import { loadRuntimeSettings, getAgentLoopRecursionLimit } from './runtime-setti
 import { getMemoryDb } from './memory-db'
 import { logExecution } from './execution-log'
 import type { Session, Message, UsageRecord } from '@/types'
+import { extractSuggestions } from './suggestions'
 
 interface StreamAgentChatOpts {
   session: Session
@@ -26,7 +27,7 @@ interface StreamAgentChatOpts {
 
 function buildToolCapabilityLines(enabledTools: string[]): string[] {
   const lines: string[] = []
-  if (enabledTools.includes('shell')) lines.push('- Shell execution is available (`execute_command`). Use it for real checks/build/test steps.')
+  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).')
   if (enabledTools.includes('files') || enabledTools.includes('copy_file') || enabledTools.includes('move_file') || enabledTools.includes('delete_file')) {
     lines.push('- File operations are available (`read_file`, `write_file`, `list_files`, `copy_file`, `move_file`, `send_file`). `delete_file` is destructive and may be disabled unless explicitly enabled.')
@@ -111,10 +112,10 @@ function buildAgenticExecutionPolicy(opts: {
       ? 'When coordinating platform work, inspect existing sessions and avoid duplicating active efforts.'
       : '',
     hasDelegationTool
-      ? `For substantial coding/build/refactor/test requests, prefer CLI delegation first using this order: ${delegationOrder.join(' -> ')}.`
+      ? 'CRITICAL — tool selection: ALWAYS use `execute_command` for running servers, dev servers, HTTP servers, installing dependencies, running scripts, git operations, process management, starting/stopping services, or any command the user wants to "run". Delegation tools (Claude/Codex/OpenCode) CANNOT keep a server running — their session ends and the process dies. `execute_command` with background=true is the ONLY way to run persistent processes.'
       : '',
     hasDelegationTool
-      ? 'Use direct shell/file tool loops yourself mainly for small edits, quick verification, or when delegation tools are unavailable/failing.'
+      ? `Only use CLI delegation (${delegationOrder.join(' -> ')}) for tasks that need deep code understanding across multiple files: large refactors, complex debugging, multi-file code generation, or test suites. Never delegate when the user says "run", "start", "serve", "execute", or "test it locally".`
       : '',
     opts.enabledTools.includes('memory')
       ? 'Memory is active and required for long-horizon work: before major tasks, run memory_tool search/list for relevant prior work; after each meaningful step, store concise reusable notes (what changed, where it lives, constraints, next step). Treat memory as shared context plus your own agent notes, not as user-owned personal profile data.'
@@ -346,6 +347,16 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
     }
   }
 
+  stateModifierParts.push(
+    [
+      '## Follow-up Suggestions',
+      'At the end of every response, include a <suggestions> block with exactly 3 short',
+      'follow-up prompts the user might want to send next, as a JSON array. Keep each under 60 chars.',
+      'Make them contextual to what you just said. Example:',
+      '<suggestions>["Set up a Discord connector", "Create a research agent", "Show the task board"]</suggestions>',
+    ].join('\n'),
+  )
+
   stateModifierParts.push(
     buildAgenticExecutionPolicy({
       enabledTools: session.tools || [],
@@ -606,6 +617,13 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
     if (signal) signal.removeEventListener('abort', abortFromSignal)
   }
 
+  // Extract LLM-generated suggestions from the response and strip the tag
+  const extracted = extractSuggestions(fullText)
+  fullText = extracted.clean
+  if (extracted.suggestions) {
+    write(`data: ${JSON.stringify({ t: 'md', text: JSON.stringify({ suggestions: extracted.suggestions }) })}\n\n`)
+  }
+
   // Track cost
   const totalTokens = totalInputTokens + totalOutputTokens
   if (totalTokens > 0) {
@@ -647,8 +665,10 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
   // If tools were called, finalResponse is the text from the last LLM turn only.
   // Fall back to fullText if the last segment is empty (e.g. agent ended on a tool call
   // with no summary text).
+  // Strip suggestions tag from lastSegment too (connector delivery)
+  const cleanLastSegment = extractSuggestions(lastSegment).clean
   const finalResponse = hasToolCalls
-    ? (lastSegment.trim() || fullText)
+    ? (cleanLastSegment.trim() || fullText)
     : fullText
 
   return { fullText, finalResponse }

package/src/lib/server/suggestions.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod'
+
+const suggestionsSchema = z.array(z.string().min(1).max(80)).length(3)
+
+const SUGGESTIONS_RE = /<suggestions>\s*([\s\S]*?)\s*<\/suggestions>\s*$/
+
+export function extractSuggestions(text: string): { clean: string; suggestions: string[] | null } {
+  const match = text.match(SUGGESTIONS_RE)
+  if (!match) return { clean: text, suggestions: null }
+
+  const clean = text.slice(0, match.index).trimEnd()
+
+  try {
+    const parsed = JSON.parse(match[1])
+    const validated = suggestionsSchema.parse(parsed)
+    return { clean, suggestions: validated }
+  } catch {
+    return { clean, suggestions: null }
+  }
+}

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

@@ -83,3 +83,17 @@ export function notify(topic: string, action = 'update', id?: string) {
     }
   }
 }
+
+/** Send an event with a data payload to subscribed browser clients. */
+export function notifyWithPayload(topic: string, data: unknown) {
+  const hub = getHub()
+  if (!hub) return
+
+  const payload = JSON.stringify({ topic, action: 'event', data })
+
+  for (const client of hub.clients) {
+    if (client.topics.has(topic) && client.ws.readyState === WebSocket.OPEN) {
+      client.ws.send(payload)
+    }
+  }
+}