bloby-bot 0.20.0 → 0.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "releaseNotes": [
     "1. react router implemented",
     "2. new workspace design",
@@ -51,7 +51,7 @@
     "dev:docs": "cd ./docs && npx fumapress"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.50",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.97",
     "@clack/prompts": "^1.1.0",
     "@streamdown/code": "^1.1.1",
     "@tailwindcss/vite": "^4.2.0",

package/supervisor/agents/index.ts

@@ -0,0 +1,127 @@
+/**
+ * Agent Definitions — scalable sub-agent configuration.
+ *
+ * Each agent has:
+ * - A config entry in AGENT_CONFIGS (tools, maxTurns, model, etc.)
+ * - A prompt file in ./prompts/{name}.txt
+ *
+ * Adding a new agent: 1) create prompts/{name}.txt, 2) add config entry below.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { log } from '../../shared/logger.js';
+import { WORKSPACE_DIR } from '../../shared/paths.js';
+
+const PROMPTS_DIR = path.join(import.meta.dirname, 'prompts');
+
+/** Agent config without prompt (prompt is loaded from file) */
+interface AgentConfig {
+  description: string;
+  promptFile: string;
+  background: boolean;
+  maxTurns: number;
+  permissionMode?: string;
+  tools?: string[];
+  disallowedTools?: string[];
+  effort?: 'low' | 'medium' | 'high' | 'max';
+  model?: string;
+  memory?: 'user' | 'project' | 'local';
+}
+
+// ── Agent Configurations ──────────────────────────────────────────────────────
+// Add new agents here. Each needs a matching prompts/{promptFile}.
+
+const AGENT_CONFIGS: Record<string, AgentConfig> = {
+  coder: {
+    description: 'Handles all coding tasks: building features, fixing bugs, refactoring, full-stack development in the workspace. Use this for any task that requires reading, writing, or editing code files.',
+    promptFile: 'coder.txt',
+    background: true,
+    maxTurns: 50,
+    permissionMode: 'bypassPermissions',
+    effort: 'high',
+  },
+
+  // ── Future agents ──
+  // researcher: {
+  //   description: 'Researches topics on the web, gathers data, writes findings to files.',
+  //   promptFile: 'researcher.txt',
+  //   background: true,
+  //   maxTurns: 30,
+  //   disallowedTools: ['Write', 'Edit'],
+  //   effort: 'medium',
+  // },
+  //
+  // marketplace: {
+  //   description: 'Browses the Bloby Marketplace, installs and configures skills.',
+  //   promptFile: 'marketplace.txt',
+  //   background: true,
+  //   maxTurns: 20,
+  //   permissionMode: 'bypassPermissions',
+  //   effort: 'medium',
+  // },
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Read a workspace memory file, return '(empty)' if missing */
+function readMemoryFile(filename: string): string {
+  try {
+    const content = fs.readFileSync(path.join(WORKSPACE_DIR, filename), 'utf-8').trim();
+    return content || '(empty)';
+  } catch {
+    return '(empty)';
+  }
+}
+
+/** Read a prompt file from the prompts directory */
+function readPromptFile(filename: string): string {
+  const filePath = path.join(PROMPTS_DIR, filename);
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8').trim();
+    if (!content) {
+      log.warn(`[agents] Prompt file empty: ${filename}`);
+      return 'You are a background sub-agent. Complete the task described below.';
+    }
+    return content;
+  } catch (err) {
+    log.warn(`[agents] Could not read prompt file ${filename}: ${err}`);
+    return 'You are a background sub-agent. Complete the task described below.';
+  }
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the agents config for the SDK's query() options.
+ * Reads prompt files and injects project memory.
+ */
+export function buildAgents(): Record<string, any> {
+  const agents: Record<string, any> = {};
+  const memory = readMemoryFile('MEMORY.md');
+
+  for (const [name, config] of Object.entries(AGENT_CONFIGS)) {
+    let prompt = readPromptFile(config.promptFile);
+
+    // Inject project memory at the end of the prompt
+    prompt += `\n\n---\n\n# Project Memory\n\n## MEMORY.md\n${memory}`;
+
+    agents[name] = {
+      description: config.description,
+      prompt,
+      background: config.background,
+      maxTurns: config.maxTurns,
+      ...(config.permissionMode && { permissionMode: config.permissionMode }),
+      ...(config.tools && { tools: config.tools }),
+      ...(config.disallowedTools && { disallowedTools: config.disallowedTools }),
+      ...(config.effort && { effort: config.effort }),
+      ...(config.model && { model: config.model }),
+      ...(config.memory && { memory: config.memory }),
+    };
+
+    log.info(`[agents] Loaded agent "${name}" — prompt: ${prompt.length} chars, bg: ${config.background}, maxTurns: ${config.maxTurns}`);
+  }
+
+  log.info(`[agents] Built ${Object.keys(agents).length} agent definition(s): ${Object.keys(agents).join(', ')}`);
+  return agents;
+}

package/supervisor/agents/prompts/coder.txt

@@ -0,0 +1,120 @@
+# Sub-Agent: Coder
+
+You are a background coding agent. You have been delegated a specific task by the orchestrator — complete it fully and report what you did.
+
+## How to Work
+- Focus only on the task described in your prompt
+- Complete the full task before responding
+- Do not chat, greet, or explain what you will do — just do it
+- If something is ambiguous, make a reasonable choice and note it in your summary
+- When finished, write a concise summary of what you changed and why
+
+## Constraints
+- Do NOT edit: PULSE.json, CRONS.json, MYSELF.md, MYHUMAN.md — those are orchestrator-only
+- You MAY write to memory/daily notes if you learn something worth remembering
+- You MAY read any file in the workspace
+- You have full tool access: Read, Write, Edit, Bash, Glob, Grep
+
+---
+
+# Coding Excellence
+
+## Action Orientation
+Do things, don't describe them. When asked to build something, build it. When asked to fix something, fix it. Accept ambitious tasks — you're often the difference between "too complex" and "done."
+
+## Read Before Modify
+Always read code before changing it. Understand what exists. Never propose changes to code you haven't read.
+
+## Simplicity
+No over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.
+- Don't add features, refactoring, or "improvements" beyond what was asked
+- Don't add docstrings, comments, or type annotations to code you didn't change
+- Don't add error handling for scenarios that can't happen
+- Trust internal code and framework guarantees — validate only at system boundaries
+- Don't create helpers or abstractions for one-time operations
+- Three similar lines of code is better than a premature abstraction
+
+## Prefer Editing Over Creating
+Always prefer editing existing files over creating new ones. This prevents file bloat and builds on existing work. Don't create files unless absolutely necessary.
+
+## Careful Execution
+Consider the reversibility and blast radius of actions. Prefer `trash` over `rm` — recoverable beats gone forever. If something fails, pivot — don't retry the same thing blindly. Read error messages carefully and address root causes.
+
+## Parallel Operations
+Run independent tool calls in parallel. Don't serialize what can run concurrently.
+
+## Security
+Be aware of OWASP top 10 vulnerabilities. Sanitize user input at boundaries. Never hardcode secrets.
+
+## Error Philosophy
+Graceful failure. Read error messages carefully. Don't brute-force past errors.
+
+---
+
+# Workspace Architecture
+
+Your working directory is the `workspace/` folder. This is your full-stack workspace:
+
+- **Frontend**: `client/` (React + Vite + TailwindCSS). Edit files in `client/src/`
+- **Backend**: `backend/` (Node.js/Express). Entry point: `backend/index.ts`
+- **Database**: `app.db` (SQLite via `better-sqlite3`)
+- **Environment**: `.env` — managed through the chat UI. When you need environment variables, use this XML format so the UI renders an interactive form:
+
+```
+<EnvGroup title="Service Name Configuration">
+  <EnvInput name="ENV_VAR_NAME" label="Human-readable Label" placeholder="example_value..." />
+</EnvGroup>
+```
+
+## Backend Routing (Critical)
+
+A supervisor process sits in front of everything on port 3000. It strips the `/app` prefix before forwarding to the backend, preserving the `/api/` path.
+
+```
+Browser: GET /app/api/tasks → Supervisor strips /app → Backend receives: GET /api/tasks
+```
+
+**The rules:**
+- **Frontend** fetch calls: use `/app/api/...`
+- **Backend** Express routes: register as `/api/tasks`, `/api/health`
+- The `/app` prefix distinguishes workspace backend routes from system routes
+
+## Frontend Routing (React Router)
+
+Routes are defined in `client/src/App.tsx`. The sidebar uses `NavLink` for navigation.
+
+### Adding a New Full-Stack Page (Example)
+
+1. **Backend route** (`backend/index.ts`): register Express route at `/api/...`
+2. **Frontend page** (`client/src/components/Dashboard/`): create React component
+3. **Add route** (`client/src/App.tsx`): add `<Route>` inside `<Routes>`
+4. **Add sidebar link** (`client/src/components/Layout/Sidebar.tsx`): add `<NavItem>`
+
+## Build Rules
+NEVER run `npm run build`, `vite build`, or any build commands. Vite HMR handles frontend. Backend auto-restarts on file edit.
+
+## Installing Packages
+```bash
+npm install <package>        # run from your cwd (workspace root)
+```
+Packages are isolated to the workspace. Never modify the parent's package.json.
+
+## Backend Lifecycle (Critical)
+
+The supervisor manages the backend process:
+- Editing `.ts`, `.js`, or `.json` files in `backend/` → auto-restart
+- Editing `.env` → auto-restart
+- After your turn ends, if you used Write or Edit tools → auto-restart
+- The backend does NOT restart mid-turn — edits are batched
+
+**NEVER** kill processes, run `bloby start`, or run `npm start` directly.
+
+## Sacred Files — NEVER Modify
+- `supervisor/` — chat UI, proxy, process management
+- `worker/` — platform APIs and database
+- `shared/` — shared utilities
+- `bin/` — CLI entry point
+
+## Modular Philosophy
+
+Build **mini apps**: a new page component, a new React Router route, and a sidebar link. Each feature lives on its own page. Add a small dashboard widget when it makes sense.

package/supervisor/bloby-agent.ts

@@ -11,7 +11,7 @@ import { WORKSPACE_DIR } from '../shared/paths.js';
 import type { SavedFile } from './file-saver.js';
 import { getClaudeAccessToken } from '../worker/claude-auth.js';
 import { assembleSystemPrompt } from '../worker/prompts/prompt-assembler.js';
-import { formatTaskBoard } from './task-board.js';
+import { buildAgents } from './agents/index.js';
 
 export interface RecentMessage {
   role: 'user' | 'assistant';
@@ -20,6 +20,7 @@ export interface RecentMessage {
 
 interface ActiveQuery {
   abortController: AbortController;
+  queryHandle?: any; // SDK query handle for stopTask()
 }
 
 const activeQueries = new Map<string, ActiveQuery>();
@@ -144,20 +145,13 @@ export async function startBlobyAgentQuery(
       }
     } catch {}
 
-    // Inject task board (active + recently completed sub-agent tasks)
-    const taskBoard = formatTaskBoard();
-    if (taskBoard) {
-      log.info(`[bloby-agent] Injecting task board into system prompt (${taskBoard.length} chars)`);
-      enrichedPrompt += `\n\n---\n# Background Tasks\n${taskBoard}`;
-    }
+    // Task board is now managed natively by the SDK via background agents
   }
 
   if (recentMessages?.length) {
     enrichedPrompt += `\n\n---\n# Recent Conversation\n${formatConversationHistory(recentMessages)}`;
   }
 
-  activeQueries.set(conversationId, { abortController });
-
   let fullText = '';
   const usedTools = new Set<string>();
   let stderrBuf = '';
@@ -198,7 +192,15 @@ export async function startBlobyAgentQuery(
     } catch {}
 
     const effectiveMaxTurns = maxTurns ?? 50;
-    log.info(`[bloby-agent] Starting query: conv=${conversationId}, model=${model}, maxTurns=${effectiveMaxTurns}, promptLen=${enrichedPrompt.length}`);
+
+    // Build sub-agent definitions (only for orchestrator/admin, not customer support)
+    let agents: Record<string, any> | undefined;
+    if (!supportPrompt && effectiveMaxTurns <= 10) {
+      agents = buildAgents();
+      log.info(`[bloby-agent] Orchestrator mode — loaded ${Object.keys(agents).length} sub-agent(s): ${Object.keys(agents).join(', ')}`);
+    }
+
+    log.info(`[bloby-agent] Starting query: conv=${conversationId}, model=${model}, maxTurns=${effectiveMaxTurns}, agents=${agents ? Object.keys(agents).join(',') : 'none'}, promptLen=${enrichedPrompt.length}`);
 
     const claudeQuery = query({
       prompt: sdkPrompt,
@@ -211,6 +213,8 @@ export async function startBlobyAgentQuery(
         abortController,
         systemPrompt: enrichedPrompt,
         mcpServers,
+        ...(agents && { agents }),
+        ...(agents && { agentProgressSummaries: true }),
         stderr: (chunk: string) => { stderrBuf += chunk; },
         env: {
           ...process.env as Record<string, string>,
@@ -220,6 +224,9 @@ export async function startBlobyAgentQuery(
       },
     });
 
+    // Store query handle for stopTask() support
+    activeQueries.set(conversationId, { abortController, queryHandle: claudeQuery });
+
     onMessage('bot:typing', { conversationId });
 
     for await (const msg of claudeQuery) {
@@ -265,6 +272,51 @@ export async function startBlobyAgentQuery(
             status: 'running',
           });
           break;
+
+        // ── Background sub-agent events (SDK-managed) ──
+        case 'system': {
+          const sysMsg = msg as any;
+          if (sysMsg.subtype === 'task_started') {
+            log.info(`[bloby-agent] ──── SUB-AGENT STARTED ────`);
+            log.info(`[bloby-agent] Task ID: ${sysMsg.task_id}`);
+            log.info(`[bloby-agent] Description: ${sysMsg.description}`);
+            log.info(`[bloby-agent] Type: ${sysMsg.task_type || 'agent'}`);
+            onMessage('bot:task-created', {
+              conversationId,
+              taskId: sysMsg.task_id,
+              description: sysMsg.description,
+              type: sysMsg.task_type,
+            });
+          } else if (sysMsg.subtype === 'task_progress') {
+            const summary = sysMsg.summary || sysMsg.last_tool_name || 'working';
+            log.info(`[bloby-agent] Sub-agent ${sysMsg.task_id} | Progress: ${summary} | Tools: ${sysMsg.usage?.tool_uses || 0} | ${Math.round((sysMsg.usage?.duration_ms || 0) / 1000)}s`);
+            onMessage('bot:task-progress', {
+              conversationId,
+              taskId: sysMsg.task_id,
+              summary,
+              lastTool: sysMsg.last_tool_name,
+              usage: sysMsg.usage,
+            });
+          } else if (sysMsg.subtype === 'task_notification') {
+            log.info(`[bloby-agent] ──── SUB-AGENT ${sysMsg.status?.toUpperCase()} ────`);
+            log.info(`[bloby-agent] Task ID: ${sysMsg.task_id}`);
+            log.info(`[bloby-agent] Status: ${sysMsg.status}`);
+            log.info(`[bloby-agent] Summary: ${sysMsg.summary?.slice(0, 200)}`);
+            log.info(`[bloby-agent] Tokens: ${sysMsg.usage?.total_tokens || 0} | Tools: ${sysMsg.usage?.tool_uses || 0} | Duration: ${Math.round((sysMsg.usage?.duration_ms || 0) / 1000)}s`);
+            onMessage('bot:task-done', {
+              conversationId,
+              taskId: sysMsg.task_id,
+              status: sysMsg.status,
+              summary: sysMsg.summary,
+              usage: sysMsg.usage,
+            });
+            // If the sub-agent wrote files, flag it
+            if (sysMsg.status === 'completed') {
+              usedTools.add('Write'); // ensure backend restart
+            }
+          }
+          break;
+        }
       }
     }
 
@@ -295,3 +347,14 @@ export function stopBlobyAgentQuery(conversationId: string): void {
     activeQueries.delete(conversationId);
   }
 }
+
+/** Stop a specific background sub-agent task */
+export async function stopSubAgentTask(conversationId: string, taskId: string): Promise<void> {
+  const q = activeQueries.get(conversationId);
+  if (q?.queryHandle?.stopTask) {
+    log.info(`[bloby-agent] Stopping sub-agent task: ${taskId}`);
+    await q.queryHandle.stopTask(taskId);
+  } else {
+    log.warn(`[bloby-agent] Cannot stop task ${taskId} — no active query for ${conversationId}`);
+  }
+}

package/supervisor/channels/manager.ts

@@ -21,8 +21,6 @@ import { loadConfig } from '../../shared/config.js';
 import { WORKSPACE_DIR } from '../../shared/paths.js';
 import { log } from '../../shared/logger.js';
 import { startBlobyAgentQuery, type RecentMessage } from '../bloby-agent.js';
-import { parseDelegateBlocks } from '../delegate-parser.js';
-import { spawnSubAgent } from '../sub-agent.js';
 import { WhatsAppChannel } from './whatsapp.js';
 import type { ChannelConfig, ChannelProvider, ChannelStatus, ChannelType, InboundMessage, InboundMessageAttachment, SenderRole } from './types.js';
 import type { AgentAttachment } from '../bloby-agent.js';
@@ -416,29 +414,6 @@ export class ChannelManager {
         }
 
         if (type === 'bot:response' && eventData.content) {
-          // Parse <Delegate> blocks — spawn sub-agents, strip from visible text
-          log.info(`[channels] Admin response — parsing for <Delegate> blocks...`);
-          const { blocks, cleanText } = parseDelegateBlocks(eventData.content);
-
-          if (blocks.length) {
-            log.info(`[channels] Found ${blocks.length} delegation(s) from WhatsApp admin response`);
-          }
-
-          for (const block of blocks) {
-            log.info(`[channels] Spawning sub-agent from WhatsApp: type=${block.type}`);
-            spawnSubAgent({
-              type: block.type,
-              description: block.description,
-              conversationId: convId,
-              model,
-              names: { botName, humanName },
-              broadcastBloby,
-              restartBackend: () => this.opts.restartBackend(),
-            });
-          }
-
-          const displayContent = cleanText;
-
           // Send remaining text after the last tool use (or the full response if no tools were used)
           const remaining = waChunkBuf.trim();
           if (remaining) {
@@ -448,20 +423,16 @@ export class ChannelManager {
             waChunkBuf = '';
           }
 
-          // Save cleaned response to DB
+          // Save response to DB
           workerApi(`/api/conversations/${convId}/messages`, 'POST', {
             role: 'assistant',
-            content: displayContent,
+            content: eventData.content,
             meta: { model },
           }).catch(() => {});
-
-          // Mirror cleaned response to chat clients
-          broadcastBloby('bot:response', { ...eventData, content: displayContent });
-          return; // prevent double-broadcast below
         }
 
-        // Mirror streaming to chat clients
-        if (type === 'bot:token' || type === 'bot:typing' || type === 'bot:tool') {
+        // Mirror streaming + task events to chat clients
+        if (type === 'bot:token' || type === 'bot:response' || type === 'bot:typing' || type === 'bot:tool' || type.startsWith('bot:task-')) {
           broadcastBloby(type, eventData);
         }
 

package/supervisor/index.ts

@@ -13,10 +13,7 @@ import { createWorkerApp } from '../worker/index.js';
 import { closeDb, getSession, getSetting } from '../worker/db.js';
 import { spawnBackend, stopBackend, getBackendPort, isBackendAlive, isBackendStopping, resetBackendRestarts } from './backend.js';
 import { updateTunnelUrl, startHeartbeat, stopHeartbeat, disconnect } from '../shared/relay.js';
-import { startBlobyAgentQuery, stopBlobyAgentQuery, type RecentMessage } from './bloby-agent.js';
-import { parseDelegateBlocks } from './delegate-parser.js';
-import { spawnSubAgent } from './sub-agent.js';
-import { stopTask, stopAllTasks } from './task-board.js';
+import { startBlobyAgentQuery, stopBlobyAgentQuery, stopSubAgentTask, type RecentMessage } from './bloby-agent.js';
 import { ensureFileDirs, saveAttachment, type SavedFile } from './file-saver.js';
 import { startViteDevServers, stopViteDevServers } from './vite-dev.js';
 import { startScheduler, stopScheduler } from './scheduler.js';
@@ -1190,50 +1187,19 @@ ${!connected ? '<script>setTimeout(()=>location.reload(),4000)</script>' : ''}
                   waChunkBuf = '';
                 }
 
-                // Parse <Delegate> blocks — spawn sub-agents, strip from visible text
-                log.info(`[orchestrator] Parsing response for <Delegate> blocks...`);
-                const { blocks, cleanText } = parseDelegateBlocks(eventData.content || '');
-
-                if (blocks.length) {
-                  log.info(`[orchestrator] Found ${blocks.length} delegation(s) — spawning sub-agent(s)`);
-                } else {
-                  log.info(`[orchestrator] No delegations — direct response`);
-                }
-
-                for (const block of blocks) {
-                  log.info(`[orchestrator] Spawning sub-agent: type=${block.type}, task="${block.description.slice(0, 80)}..."`);
-                  spawnSubAgent({
-                    type: block.type,
-                    description: block.description,
-                    conversationId: convId,
-                    model: freshConfig.ai.model,
-                    names: { botName, humanName },
-                    broadcastBloby,
-                    restartBackend: () => {
-                      resetBackendRestarts();
-                      stopBackend().then(() => spawnBackend(backendPort));
-                    },
-                  });
-                }
-
-                const displayContent = cleanText;
-
                 (async () => {
                   try {
                     await workerApi(`/api/conversations/${convId}/messages`, 'POST', {
-                      role: 'assistant', content: displayContent, meta: { model: freshConfig.ai.model },
+                      role: 'assistant', content: eventData.content, meta: { model: freshConfig.ai.model },
                     });
                   } catch (err: any) {
                     log.warn(`[bloby] DB persist bot response error: ${err.message}`);
                   }
                 })();
-
-                // Broadcast cleaned text (without <Delegate> blocks)
-                broadcastBloby('bot:response', { ...eventData, content: displayContent });
-                return; // prevent double-broadcast below
               }
 
-              // Stream all other events to every connected client
+              // Stream all events to every connected client
+              // (includes bot:task-created, bot:task-progress, bot:task-done from SDK)
               broadcastBloby(type, eventData);
             }, data.attachments, savedFiles, { botName, humanName }, recentMessages,
             undefined, // no supportPrompt
@@ -1279,20 +1245,14 @@ ${!connected ? '<script>setTimeout(()=>location.reload(),4000)</script>' : ''}
       if (msg.type === 'user:stop-task') {
         const taskId = (msg as any).data?.taskId;
         if (taskId) {
-          log.info(`[orchestrator] Stopping task: ${taskId}`);
-          stopTask(taskId);
-          broadcastBloby('bot:task-stopped', { taskId });
+          log.info(`[orchestrator] Stopping sub-agent task: ${taskId}`);
+          stopSubAgentTask(convId, taskId).catch((err) => {
+            log.warn(`[orchestrator] Failed to stop task ${taskId}: ${err.message}`);
+          });
         }
         return;
       }
 
-      if (msg.type === 'user:stop-all-tasks') {
-        log.info(`[orchestrator] Stopping all background tasks`);
-        stopAllTasks();
-        broadcastBloby('bot:tasks-cleared', {});
-        return;
-      }
-
       if (msg.type === 'user:clear-context') {
         (async () => {
           try {

package/worker/prompts/bloby-system-prompt.txt

@@ -206,65 +206,37 @@ Complex cron tasks can have detailed instruction files in `tasks/{cron-id}.md`.
 
 # Delegation
 
-You can delegate heavy work to background sub-agents. This lets you respond quickly while work happens in parallel. The user keeps chatting with you while sub-agents build, research, or process in the background.
+You have background sub-agents available via the Agent tool. **Always delegate work — never do coding or heavy tasks yourself.** You are the conversational orchestrator. Your sub-agents do the actual work.
 
-## When to Delegate
+## How It Works
 
-**Delegate to a sub-agent** (takes many tool calls, runs in background):
-- Building new features (pages, APIs, components)
-- Multi-file refactoring or code changes
-- Complex bug fixes requiring investigation
-- Any coding task that would take more than 2-3 tool calls
+You have an Agent tool with background agents available. When you invoke one, it runs in the background — you respond immediately to your human while the agent works. You'll receive progress updates and completion notifications automatically.
 
-**Handle directly** (quick, do it yourself):
-- Conversational responses, chitchat, questions
-- Memory file writes (MEMORY.md, MYSELF.md, MYHUMAN.md, daily notes)
-- Config edits (PULSE.json, CRONS.json, MCP.json)
-- Channel configuration (mode, admins)
-- Simple file reads or status checks
-- Setting up reminders or crons
-
-## How to Delegate
-
-Include a `<Delegate>` block in your response. The supervisor strips it from your visible message, spawns a background coding agent, and your human never sees the XML — they just see your conversational response.
-
-```
-<Delegate type="coder">
-Build a contacts page with search and tag filtering.
-- Backend: Express API at /api/contacts (GET, POST, DELETE) using SQLite
-- Frontend: React page at client/src/components/Dashboard/ContactsPage.tsx
-- Add sidebar link and route in App.tsx
-</Delegate>
-```
-
-You can include multiple `<Delegate>` blocks in one response for parallel work. Always write a natural conversational message alongside the delegation — your human should know what you're doing.
-
-**Good example:**
-> "On it! I'll build that contacts page with search and tags. Give me a few minutes."
-> `<Delegate type="coder">...</Delegate>`
+## CRITICAL: Always Delegate
 
-## Available Sub-Agent Types
+**You MUST delegate** (use your sub-agents):
+- ALL coding tasks — building features, fixing bugs, refactoring, any file editing
+- ALL workspace modifications — creating pages, APIs, components
+- Complex research or data gathering
+- Any task that requires tool use (Read, Write, Edit, Bash)
 
-| Type | Use For |
-|------|---------|
-| `coder` | All coding tasks — features, fixes, refactoring, full-stack development |
-
-## Task Board
+**You respond directly** (NO delegation needed):
+- Conversational responses, chitchat, questions
+- Answering questions from memory/context already in your prompt
+- Acknowledging requests and telling your human what you're doing
 
-A "Background Tasks" section appears in your context showing active and recently completed sub-agent tasks. Use it to:
+**You NEVER use tools directly.** No Read, Write, Edit, Bash, Glob, Grep. If you need to do any of those things, delegate to a sub-agent. You are the friendly conversational layer — your sub-agents are the workers.
 
-- **Report results naturally** when tasks complete: "That contacts page is ready — I added search and tag filtering."
-- **Give progress updates** if the user asks: "Still working on it — currently editing the API routes."
-- **Avoid duplicates** — check if a similar task is already running before delegating again.
+## When a sub-agent completes
 
-When a task completes, report the results to your human in your next response. Be specific about what was built or changed.
+You'll be notified with a summary of what was done. Report the results naturally to your human: "Done! I built the contacts page with search and tags. Check it out!"
 
 ## Rules
 
-- **Max 3 concurrent sub-agents.** If all slots are busy, tasks queue automatically (up to 5 queued).
-- **Keep task descriptions specific and actionable.** Include file paths, technologies, and acceptance criteria when relevant.
-- **Never delegate memory or config edits** — MYSELF.md, MYHUMAN.md, MEMORY.md, PULSE.json, CRONS.json are yours to manage directly.
-- **Always respond conversationally alongside delegation.** Don't just silently delegate — tell your human what you're doing.
+- **Keep task descriptions specific and actionable.** Include what to build, which files, acceptance criteria.
+- **Always respond conversationally alongside delegation.** Don't go silent — tell your human what you're doing.
+- **Report results** when sub-agents finish. Be specific about what changed.
+- **You can run multiple agents** in parallel if the user asks for several things at once.
 
 ---
 

package/supervisor/delegate-parser.ts

@@ -1,44 +0,0 @@
-/**
- * Parse <Delegate> blocks from agent responses.
- * Same pattern as <Message> parsing in scheduler.ts.
- */
-
-import { log } from '../shared/logger.js';
-import type { SubAgentType } from './task-board.js';
-
-export interface DelegateBlock {
-  type: SubAgentType;
-  description: string;
-}
-
-const DELEGATE_REGEX = /<Delegate\s+type="(\w+)">([\s\S]*?)<\/Delegate>/g;
-
-/**
- * Extract <Delegate> blocks from response text.
- * Returns the parsed blocks and the cleaned text with blocks stripped.
- */
-export function parseDelegateBlocks(text: string): { blocks: DelegateBlock[]; cleanText: string } {
-  const blocks: DelegateBlock[] = [];
-
-  let match;
-  // Reset lastIndex since we reuse the regex
-  DELEGATE_REGEX.lastIndex = 0;
-  while ((match = DELEGATE_REGEX.exec(text)) !== null) {
-    const type = match[1] as SubAgentType;
-    const description = match[2].trim();
-    log.info(`[delegate-parser] Found <Delegate type="${type}"> — "${description.slice(0, 80)}..."`);
-    blocks.push({ type, description });
-  }
-
-  // Strip delegate blocks from visible text
-  let cleanText = text.replace(DELEGATE_REGEX, '').trim();
-
-  // Clean up excessive newlines left by stripping
-  cleanText = cleanText.replace(/\n{3,}/g, '\n\n');
-
-  if (blocks.length) {
-    log.info(`[delegate-parser] Parsed ${blocks.length} delegate block(s), cleaned text: "${cleanText.slice(0, 80)}..."`);
-  }
-
-  return { blocks, cleanText };
-}

package/supervisor/sub-agent.ts

@@ -1,175 +0,0 @@
-/**
- * Sub-Agent Spawner — creates and manages background agent queries.
- * Sub-agents run independently from the orchestrator, handling
- * heavy work (coding, research) while the user keeps chatting.
- */
-
-import { log } from '../shared/logger.js';
-import { startBlobyAgentQuery } from './bloby-agent.js';
-import { createTask, completeTask, failTask, setOnTaskPromoted, type SubAgentTask, type SubAgentType } from './task-board.js';
-import { assembleSubAgentPrompt } from '../worker/prompts/sub-agent-prompts.js';
-
-export interface SpawnOpts {
-  type: SubAgentType;
-  description: string;
-  conversationId: string;
-  model: string;
-  names: { botName: string; humanName: string };
-  broadcastBloby: (type: string, data: any) => void;
-  restartBackend: () => void;
-}
-
-/** Pending spawn options for queued tasks, keyed by task ID */
-const pendingOpts = new Map<string, SpawnOpts>();
-
-// Register the global promotion handler once (handles all queued tasks)
-setOnTaskPromoted((task: SubAgentTask) => {
-  const opts = pendingOpts.get(task.id);
-  if (opts) {
-    pendingOpts.delete(task.id);
-    log.info(`[sub-agent] Queued task ${task.id} promoted — starting agent`);
-    opts.broadcastBloby('bot:task-progress', {
-      taskId: task.id,
-      tool: 'starting',
-    });
-    runSubAgent(task, opts);
-  }
-});
-
-/**
- * Spawn a background sub-agent for a delegated task.
- * Returns the created task, or null if the queue is full.
- */
-export function spawnSubAgent(opts: SpawnOpts): SubAgentTask | null {
-  log.info(`[sub-agent] ──── SPAWN REQUEST ────`);
-  log.info(`[sub-agent] Type: ${opts.type}`);
-  log.info(`[sub-agent] Description: "${opts.description.slice(0, 120)}..."`);
-  log.info(`[sub-agent] Model: ${opts.model}`);
-  log.info(`[sub-agent] Conversation: ${opts.conversationId}`);
-
-  const task = createTask(opts.type, opts.description, opts.conversationId);
-  if (!task) {
-    log.warn(`[sub-agent] Could not create task — queue full`);
-    opts.broadcastBloby('bot:task-error', {
-      error: 'Too many background tasks. Try again in a moment.',
-    });
-    return null;
-  }
-
-  // Broadcast task creation
-  opts.broadcastBloby('bot:task-created', {
-    taskId: task.id,
-    type: task.type,
-    description: task.description,
-    status: task.status,
-  });
-
-  if (task.status === 'queued') {
-    // Store opts so we can start the agent when promoted
-    pendingOpts.set(task.id, opts);
-    log.info(`[sub-agent] Task ${task.id} queued — will start when a slot opens`);
-    return task;
-  }
-
-  // Task is immediately running
-  log.info(`[sub-agent] Task ${task.id} starting immediately (slot available)`);
-  runSubAgent(task, opts);
-  return task;
-}
-
-/** Actually start the agent query for a task */
-function runSubAgent(task: SubAgentTask, opts: SpawnOpts): void {
-  const systemPrompt = assembleSubAgentPrompt(opts.type, opts.names);
-  const convId = `subagent-${task.id}`;
-
-  log.info(`[sub-agent] ──── STARTING AGENT ────`);
-  log.info(`[sub-agent] Task ID: ${task.id}`);
-  log.info(`[sub-agent] Type: ${task.type}`);
-  log.info(`[sub-agent] Conv ID: ${convId}`);
-  log.info(`[sub-agent] Prompt length: ${systemPrompt.length} chars`);
-  log.info(`[sub-agent] Task description: "${task.description.slice(0, 120)}..."`);
-
-  let fullText = '';
-  let toolCount = 0;
-
-  startBlobyAgentQuery(
-    convId,
-    task.description,
-    opts.model,
-    (type, eventData) => {
-      // Track tool usage for progress
-      if (type === 'bot:tool') {
-        toolCount++;
-        const toolName = eventData.name || 'working';
-        task.progress.push(toolName);
-        if (toolName === 'Write' || toolName === 'Edit') {
-          task.usedFileTools = true;
-        }
-        log.info(`[sub-agent] Task ${task.id} | Tool #${toolCount}: ${toolName}${eventData.input?.file_path ? ` → ${eventData.input.file_path}` : ''}`);
-        opts.broadcastBloby('bot:task-progress', {
-          taskId: task.id,
-          tool: toolName,
-          input: eventData.input,
-        });
-      }
-
-      // Accumulate response text
-      if (type === 'bot:token' && eventData.token) {
-        fullText += eventData.token;
-      }
-
-      // Store final response
-      if (type === 'bot:response') {
-        fullText = eventData.content || fullText;
-        log.info(`[sub-agent] Task ${task.id} | Response received (${fullText.length} chars)`);
-      }
-
-      // Handle completion
-      if (type === 'bot:done') {
-        const usedFiles = task.usedFileTools || eventData.usedFileTools;
-        const elapsed = Math.round((Date.now() - task.createdAt) / 1000);
-        completeTask(task.id, fullText || '(completed)', usedFiles);
-
-        log.info(`[sub-agent] ──── TASK COMPLETED ────`);
-        log.info(`[sub-agent] Task ID: ${task.id}`);
-        log.info(`[sub-agent] Duration: ${elapsed}s`);
-        log.info(`[sub-agent] Tools used: ${toolCount}`);
-        log.info(`[sub-agent] File tools: ${usedFiles}`);
-        log.info(`[sub-agent] Result preview: "${(fullText || '').slice(0, 200)}..."`);
-
-        opts.broadcastBloby('bot:task-done', {
-          taskId: task.id,
-          type: task.type,
-          description: task.description,
-          result: fullText?.slice(0, 500) || '(completed)',
-          usedFileTools: usedFiles,
-        });
-
-        // Restart backend if file tools were used
-        if (usedFiles) {
-          log.info(`[sub-agent] Task ${task.id} used file tools — restarting backend`);
-          opts.restartBackend();
-        }
-      }
-
-      // Handle errors
-      if (type === 'bot:error') {
-        const errorMsg = eventData.error || 'Unknown error';
-        failTask(task.id, errorMsg);
-        opts.broadcastBloby('bot:task-error', {
-          taskId: task.id,
-          error: errorMsg,
-        });
-        log.warn(`[sub-agent] ──── TASK FAILED ────`);
-        log.warn(`[sub-agent] Task ID: ${task.id}`);
-        log.warn(`[sub-agent] Error: ${errorMsg}`);
-      }
-    },
-    undefined, // no attachments
-    undefined, // no savedFiles
-    opts.names,
-    undefined, // no recentMessages — sub-agents don't need chat history
-    systemPrompt, // passed as supportPrompt to bypass main prompt assembly
-    50, // maxTurns — full power for sub-agents
-  );
-}

package/supervisor/task-board.ts

@@ -1,231 +0,0 @@
-/**
- * Task Board — tracks background sub-agent tasks.
- * In-memory only (no DB persistence). Tasks are ephemeral — they exist
- * for the duration of the work and a short window after for reporting.
- */
-
-import { log } from '../shared/logger.js';
-
-export type SubAgentType = 'coder' | 'researcher';
-
-export interface SubAgentTask {
-  id: string;
-  type: SubAgentType;
-  description: string;
-  status: 'queued' | 'running' | 'done' | 'error';
-  progress: string[];
-  result?: string;
-  error?: string;
-  usedFileTools: boolean;
-  createdAt: number;
-  completedAt?: number;
-  conversationId: string;
-  abortController: AbortController;
-}
-
-const tasks = new Map<string, SubAgentTask>();
-const taskQueue: SubAgentTask[] = [];
-const MAX_CONCURRENT = 3;
-const MAX_QUEUED = 5;
-/** Keep completed tasks for 5 minutes before cleanup */
-const COMPLETED_TTL = 5 * 60 * 1000;
-
-/** Callback invoked when a queued task gets promoted to running */
-let onTaskPromoted: ((task: SubAgentTask) => void) | null = null;
-
-/** Register a callback for when queued tasks are promoted */
-export function setOnTaskPromoted(cb: (task: SubAgentTask) => void) {
-  onTaskPromoted = cb;
-}
-
-function generateId(): string {
-  return 'task-' + Math.random().toString(36).slice(2, 8) + Date.now().toString(36).slice(-4);
-}
-
-function getRunningCount(): number {
-  let count = 0;
-  for (const t of tasks.values()) {
-    if (t.status === 'running') count++;
-  }
-  return count;
-}
-
-/** Create a task. Returns the task (queued or running), or null if queue is full. */
-export function createTask(
-  type: SubAgentType,
-  description: string,
-  conversationId: string,
-): SubAgentTask | null {
-  const task: SubAgentTask = {
-    id: generateId(),
-    type,
-    description,
-    status: 'queued',
-    progress: [],
-    usedFileTools: false,
-    createdAt: Date.now(),
-    conversationId,
-    abortController: new AbortController(),
-  };
-
-  if (getRunningCount() < MAX_CONCURRENT) {
-    task.status = 'running';
-    tasks.set(task.id, task);
-    log.info(`[task-board] Created task ${task.id} (${type}) — running`);
-    return task;
-  }
-
-  if (taskQueue.length >= MAX_QUEUED) {
-    log.warn(`[task-board] Queue full (${MAX_QUEUED}) — rejecting task`);
-    return null;
-  }
-
-  tasks.set(task.id, task);
-  taskQueue.push(task);
-  log.info(`[task-board] Created task ${task.id} (${type}) — queued (position ${taskQueue.length})`);
-  return task;
-}
-
-/** Mark a task as completed */
-export function completeTask(id: string, result: string, usedFileTools: boolean): void {
-  const task = tasks.get(id);
-  if (!task) return;
-  task.status = 'done';
-  task.result = result;
-  task.usedFileTools = usedFileTools;
-  task.completedAt = Date.now();
-  log.info(`[task-board] Task ${id} completed`);
-  promoteNext();
-  scheduleCleanup(id);
-}
-
-/** Mark a task as failed */
-export function failTask(id: string, error: string): void {
-  const task = tasks.get(id);
-  if (!task) return;
-  task.status = 'error';
-  task.error = error;
-  task.completedAt = Date.now();
-  log.warn(`[task-board] Task ${id} failed: ${error}`);
-  promoteNext();
-  scheduleCleanup(id);
-}
-
-/** Stop a task by aborting its controller */
-export function stopTask(id: string): boolean {
-  const task = tasks.get(id);
-  if (!task) return false;
-
-  // If queued, just remove from queue
-  if (task.status === 'queued') {
-    const idx = taskQueue.indexOf(task);
-    if (idx !== -1) taskQueue.splice(idx, 1);
-    tasks.delete(id);
-    log.info(`[task-board] Removed queued task ${id}`);
-    return true;
-  }
-
-  if (task.status === 'running') {
-    task.abortController.abort();
-    task.status = 'error';
-    task.error = 'Stopped by user';
-    task.completedAt = Date.now();
-    log.info(`[task-board] Stopped task ${id}`);
-    promoteNext();
-    scheduleCleanup(id);
-    return true;
-  }
-
-  return false;
-}
-
-/** Stop all active tasks */
-export function stopAllTasks(): void {
-  for (const task of tasks.values()) {
-    if (task.status === 'running') {
-      task.abortController.abort();
-      task.status = 'error';
-      task.error = 'Stopped by user';
-      task.completedAt = Date.now();
-    }
-  }
-  // Clear queue
-  while (taskQueue.length) {
-    const t = taskQueue.pop()!;
-    tasks.delete(t.id);
-  }
-  log.info('[task-board] All tasks stopped');
-}
-
-/** Get all active (running + queued) tasks */
-export function getActiveTasks(): SubAgentTask[] {
-  return Array.from(tasks.values()).filter(
-    (t) => t.status === 'running' || t.status === 'queued',
-  );
-}
-
-/** Get recently completed/failed tasks (within TTL window) */
-export function getRecentCompletedTasks(): SubAgentTask[] {
-  const cutoff = Date.now() - COMPLETED_TTL;
-  return Array.from(tasks.values()).filter(
-    (t) => (t.status === 'done' || t.status === 'error') && (t.completedAt || 0) > cutoff,
-  );
-}
-
-/** Format the task board as markdown for system prompt injection */
-export function formatTaskBoard(): string {
-  const active = getActiveTasks();
-  const completed = getRecentCompletedTasks();
-
-  if (!active.length && !completed.length) return '';
-
-  const lines: string[] = [];
-
-  if (active.length) {
-    lines.push('## Active Tasks');
-    for (const t of active) {
-      const elapsed = Math.round((Date.now() - t.createdAt) / 1000);
-      const time = elapsed < 60 ? `${elapsed}s ago` : `${Math.round(elapsed / 60)}m ago`;
-      const lastTool = t.progress.length ? t.progress[t.progress.length - 1] : 'starting';
-      lines.push(`- **${t.id}** (${t.type}, ${t.status}): "${t.description.slice(0, 100)}"`);
-      lines.push(`  Started ${time} | Last: ${lastTool}`);
-    }
-  }
-
-  if (completed.length) {
-    lines.push('');
-    lines.push('## Recently Completed Tasks');
-    for (const t of completed) {
-      const statusLabel = t.status === 'done' ? 'DONE' : `ERROR: ${t.error}`;
-      lines.push(`- **${t.id}** (${t.type}, ${statusLabel}): "${t.description.slice(0, 100)}"`);
-      if (t.result) {
-        lines.push(`  Result: ${t.result.slice(0, 300)}`);
-      }
-    }
-  }
-
-  return lines.join('\n');
-}
-
-// ── Internal ──
-
-function promoteNext() {
-  if (!taskQueue.length || getRunningCount() >= MAX_CONCURRENT) return;
-
-  const next = taskQueue.shift()!;
-  next.status = 'running';
-  log.info(`[task-board] Promoted queued task ${next.id} to running`);
-
-  if (onTaskPromoted) {
-    onTaskPromoted(next);
-  }
-}
-
-function scheduleCleanup(id: string) {
-  setTimeout(() => {
-    const task = tasks.get(id);
-    if (task && (task.status === 'done' || task.status === 'error')) {
-      tasks.delete(id);
-    }
-  }, COMPLETED_TTL);
-}

package/worker/prompts/sub-agent-prompts.ts

@@ -1,111 +0,0 @@
-/**
- * Sub-agent System Prompt Builder
- *
- * Builds task-specific system prompts for background sub-agents.
- * Extracts relevant sections from the main bloby-system-prompt.txt.
- */
-
-import fs from 'fs';
-import path from 'path';
-import { WORKSPACE_DIR } from '../../shared/paths.js';
-import { log } from '../../shared/logger.js';
-
-const PROMPT_FILE = path.join(import.meta.dirname, 'bloby-system-prompt.txt');
-
-/** Read a workspace memory file, return '(empty)' if missing */
-function readMemoryFile(filename: string): string {
-  try {
-    const content = fs.readFileSync(path.join(WORKSPACE_DIR, filename), 'utf-8').trim();
-    return content || '(empty)';
-  } catch {
-    return '(empty)';
-  }
-}
-
-/** Extract a section from the base prompt between two H1 headers */
-function extractSection(prompt: string, startHeader: string, endHeader: string): string {
-  const startIdx = prompt.indexOf(startHeader);
-  if (startIdx === -1) return '';
-
-  const endIdx = endHeader ? prompt.indexOf(endHeader, startIdx + startHeader.length) : -1;
-  if (endIdx === -1) return prompt.slice(startIdx);
-
-  return prompt.slice(startIdx, endIdx).trim();
-}
-
-/** Build the system prompt for a sub-agent based on type */
-export function assembleSubAgentPrompt(
-  type: 'coder' | 'researcher',
-  names: { botName: string; humanName: string },
-): string {
-  log.info(`[sub-agent-prompts] Building ${type} prompt for ${names.botName}`);
-  if (type === 'coder') {
-    const prompt = buildCoderPrompt(names);
-    log.info(`[sub-agent-prompts] Coder prompt assembled (${prompt.length} chars)`);
-    return prompt;
-  }
-  // Future: researcher, marketplace
-  const prompt = buildCoderPrompt(names);
-  log.info(`[sub-agent-prompts] Fallback prompt assembled (${prompt.length} chars)`);
-  return prompt;
-}
-
-function buildCoderPrompt(names: { botName: string; humanName: string }): string {
-  const memory = readMemoryFile('MEMORY.md');
-
-  // Read base prompt and extract coding-relevant sections
-  let codingSection = '';
-  let workspaceSection = '';
-  try {
-    const raw = fs.readFileSync(PROMPT_FILE, 'utf-8')
-      .replace(/\$BOT/g, names.botName)
-      .replace(/\$HUMAN/g, names.humanName);
-
-    codingSection = extractSection(raw, '# Coding Excellence', '# Personality and Conduct');
-    workspaceSection = extractSection(raw, '# Workspace Architecture', '# Personality and Conduct');
-
-    log.info(`[sub-agent-prompts] Extracted coding section: ${codingSection.length} chars`);
-    log.info(`[sub-agent-prompts] Extracted workspace section: ${workspaceSection.length} chars`);
-
-    // If workspace was already included in coding section, avoid duplication
-    if (codingSection.includes('# Workspace Architecture')) {
-      log.info(`[sub-agent-prompts] Workspace already in coding section — skipping duplicate`);
-      workspaceSection = '';
-    }
-  } catch (err) {
-    log.warn(`[sub-agent-prompts] Could not read base prompt: ${err}`);
-  }
-
-  return `# Sub-Agent: Coder
-
-You are a background coding agent working for ${names.botName}. Your human is ${names.humanName}.
-
-You have been delegated a specific coding task by the orchestrator agent. Your job is to complete it fully and report what you did.
-
-## How to Work
-- Focus only on the task described below
-- Complete the full task before responding
-- Do not chat, greet, or explain what you will do — just do it
-- If something is ambiguous, make a reasonable choice and note it in your summary
-- When finished, write a concise summary of what you changed and why
-
-## Constraints
-- Do NOT edit: PULSE.json, CRONS.json, MYSELF.md, MYHUMAN.md — those are orchestrator-only
-- You MAY write to memory/daily notes if you learn something worth remembering
-- You MAY read any file in the workspace
-- You have full tool access: Read, Write, Edit, Bash, Glob, Grep
-
----
-
-${codingSection}
-
-${workspaceSection}
-
----
-
-# Project Context
-
-## MEMORY.md
-${memory}
-`;
-}