@hamp10/agentforge 0.1.0

package/src/OpenClawCLI.js

@@ -0,0 +1,1520 @@
+import { spawn } from 'child_process';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'fs';
+import { EventEmitter } from 'events';
+import { homedir } from 'os';
+import path from 'path';
+import treeKill from 'tree-kill';
+
+// Canary configuration
+const CANARY_ENDPOINT = process.env.CANARY_ENDPOINT || 'https://canary.bot';
+const CANARY_PARENT_API_KEY = process.env.CANARY_PARENT_API_KEY; // Optional: inherit ownership
+
+/**
+ * Controls OpenClaw agents via CLI instead of WebSocket Gateway
+ */
+export class OpenClawCLI extends EventEmitter {
+  static _findBin() {
+    const home = process.env.HOME || homedir();
+    const candidates = [
+      path.join(home, '.npm-global/bin/openclaw'),
+      '/usr/local/bin/openclaw',
+      '/opt/homebrew/bin/openclaw',
+    ];
+    for (const c of candidates) if (existsSync(c)) return c;
+    return null;
+  }
+
+  static isAvailable() {
+    return !!OpenClawCLI._findBin();
+  }
+
+  constructor() {
+    super();
+    this.activeAgents = new Map();
+    // Full absolute path to the openclaw script
+    this.bin = OpenClawCLI._findBin() || '/usr/local/bin/openclaw';
+    // Read valid Anthropic API key from local auth-profiles at startup
+    // This is passed as ANTHROPIC_API_KEY to every openclaw spawn, bypassing
+    // any broken auth-profiles.json on this machine (e.g. invalid default key)
+    this.anthropicApiKey = this._readAnthropicKey();
+    // OpenClaw Gateway streaming config — populated by worker.js on init
+    this.gatewayPort = null;
+    this.gatewayToken = null;
+  }
+
+  /**
+   * Run an agent task via the OpenClaw Gateway's OpenAI-compatible streaming endpoint.
+   * Returns the full response text, emitting agent_output events in real-time for each token.
+   * Falls back to null if the gateway is not configured or the request fails.
+   */
+  async _runAgentTaskStreaming(agentId, task, sessionId) {
+    if (!this.gatewayPort || !this.gatewayToken) return null;
+    const url = `http://127.0.0.1:${this.gatewayPort}/v1/chat/completions`;
+    const sessionKey = `agent:${agentId}:main`;
+    let fullText = '';
+
+    // Friendly names for tool calls shown as live messages to the user
+    const toolLabels = {
+      read: '📄 Reading file', write: '✏️ Writing file', edit: '✏️ Editing file',
+      bash: '⚡ Running command', exec: '⚡ Running command', process: '⚡ Running process',
+      web_search: '🔍 Searching the web', web_fetch: '🌐 Fetching page',
+      browser: '🌐 Browsing', image: '🖼️ Analyzing image',
+      memory_search: '🧠 Searching memory', memory_get: '🧠 Reading memory',
+      sessions_spawn: '🤖 Spawning sub-agent', sessions_send: '📤 Sending to agent',
+      tts: '🔊 Generating speech', canvas: '🎨 Updating canvas',
+    };
+
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.gatewayToken}`,
+          'Content-Type': 'application/json',
+          // Target the agent's main session so history is preserved
+          'x-openclaw-agent-id': agentId,
+          'x-openclaw-session-key': sessionKey,
+        },
+        body: JSON.stringify({
+          model: `openclaw:${agentId}`,
+          messages: [{ role: 'user', content: task }],
+          stream: true,
+        }),
+        signal: AbortSignal.timeout(600_000), // 10 min max
+      });
+      if (!res.ok) {
+        console.warn(`[${agentId}] ⚠️ Streaming HTTP ${res.status} — falling back to subprocess`);
+        return null;
+      }
+
+      // Parse SSE stream — emit text tokens AND tool call activity
+      const decoder = new TextDecoder();
+      let buffer = '';
+      const seenToolCallIds = new Set(); // avoid duplicate tool_activity for same call_id
+      const pendingToolCalls = new Map(); // index -> { id, name, args }
+
+      for await (const rawChunk of res.body) {
+        buffer += decoder.decode(rawChunk, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? ''; // keep incomplete line
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith('data:')) continue;
+          const json = trimmed.slice(5).trim();
+          if (json === '[DONE]') break;
+          try {
+            const chunk = JSON.parse(json);
+            const choice = chunk?.choices?.[0];
+            if (!choice) continue;
+
+            // Text token — stream to dashboard
+            const delta = choice.delta?.content;
+            if (delta) {
+              fullText += delta;
+              this.emit('agent_output', { agentId, output: delta });
+            }
+
+            // Tool call delta — detect new tool calls and emit activity events
+            const toolCallDeltas = choice.delta?.tool_calls;
+            if (toolCallDeltas) {
+              for (const tc of toolCallDeltas) {
+                const idx = tc.index ?? 0;
+                if (!pendingToolCalls.has(idx)) {
+                  pendingToolCalls.set(idx, { id: tc.id || '', name: tc.function?.name || '', args: '' });
+                } else {
+                  const pending = pendingToolCalls.get(idx);
+                  if (tc.function?.name && !pending.name) pending.name = tc.function.name;
+                  if (tc.id && !pending.id) pending.id = tc.id;
+                  if (tc.function?.arguments) pending.args += tc.function.arguments;
+                }
+
+                // Emit tool_activity as soon as we have a name and haven't emitted for this call yet
+                const pending = pendingToolCalls.get(idx);
+                const callKey = pending.id || `${idx}-${pending.name}`;
+                if (pending.name && !seenToolCallIds.has(callKey)) {
+                  seenToolCallIds.add(callKey);
+                  const label = toolLabels[pending.name] || `🔧 ${pending.name}`;
+                  console.log(`[${agentId}] 🛠️  Tool call: ${pending.name}`);
+
+                  // Emit tool_activity so the typing indicator + thinking log update
+                  this.emit('tool_activity', {
+                    agentId,
+                    event: 'tool_start',
+                    tool: pending.name,
+                    description: label,
+                  });
+                }
+              }
+            }
+
+            // Tool calls finishing — emit complete events
+            if (choice.finish_reason === 'tool_calls') {
+              for (const [, tc] of pendingToolCalls) {
+                if (tc.name) {
+                  this.emit('tool_activity', { agentId, event: 'tool_end', tool: tc.name, description: `✓ ${tc.name}` });
+                }
+              }
+              pendingToolCalls.clear();
+            }
+          } catch { /* malformed chunk — skip */ }
+        }
+      }
+      // Return an object so callers can distinguish "success with no text" from "request failed"
+      return { text: fullText, succeeded: true };
+    } catch (err) {
+      console.warn(`[${agentId}] ⚠️ Streaming HTTP error: ${err.message} — falling back to subprocess`);
+      return null; // null = request failed, subprocess fallback needed
+    }
+  }
+
+  /** Read the first valid Anthropic API key from local auth-profiles (skips :default) */
+  _readAnthropicKey() {
+    // 1. Env var override
+    if (process.env.ANTHROPIC_API_KEY) {
+      console.log('🔑 Anthropic key loaded from ANTHROPIC_API_KEY env');
+      return process.env.ANTHROPIC_API_KEY;
+    }
+    // 2. ~/.agentforge/config.json anthropicToken field
+    try {
+      const cfg = path.join(homedir(), '.agentforge', 'config.json');
+      if (existsSync(cfg)) {
+        const d = JSON.parse(readFileSync(cfg, 'utf-8'));
+        if (d.anthropicToken) {
+          console.log('🔑 Anthropic key loaded from agentforge config');
+          return d.anthropicToken;
+        }
+      }
+    } catch {}
+    // 3. Scan agent auth-profiles
+    try {
+      const agentsDir = path.join(homedir(), '.openclaw', 'agents');
+      if (!existsSync(agentsDir)) return null;
+      for (const dir of readdirSync(agentsDir)) {
+        const authPath = path.join(agentsDir, dir, 'agent', 'auth-profiles.json');
+        if (!existsSync(authPath)) continue;
+        try {
+          const data = JSON.parse(readFileSync(authPath, 'utf-8'));
+          for (const [name, profile] of Object.entries(data?.profiles || {})) {
+            if (name !== 'anthropic:default' && profile?.provider === 'anthropic' && profile?.token) {
+              console.log(`🔑 Anthropic key loaded from profile: ${name}`);
+              return profile.token;
+            }
+          }
+        } catch {}
+      }
+    } catch (e) {
+      console.warn('⚠️ Could not read auth-profiles:', e.message);
+    }
+    return null;
+  }
+
+  /**
+   * Extract toolInput JSON from a verbose openclaw line.
+   * Handles brace-balanced extraction so nested objects parse correctly.
+   * Returns parsed object or null.
+   */
+  extractToolInput(line) {
+    const idx = line.indexOf('toolInput=');
+    if (idx === -1) return null;
+    const rest = line.slice(idx + 10);
+
+    // Object input: toolInput={...}
+    if (rest.startsWith('{')) {
+      let depth = 0, end = 0;
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '{') depth++;
+        else if (rest[i] === '}') {
+          depth--;
+          if (depth === 0) { end = i + 1; break; }
+        }
+      }
+      if (end === 0) return null;
+      try {
+        return JSON.parse(rest.slice(0, end));
+      } catch (e) {
+        return null;
+      }
+    }
+
+    // String input: toolInput="some text" — wrap in {text:} so extractSpeechText can find it
+    if (rest.startsWith('"')) {
+      let end = 1;
+      while (end < rest.length) {
+        if (rest[end] === '"' && rest[end - 1] !== '\\') { end++; break; }
+        end++;
+      }
+      try {
+        const str = JSON.parse(rest.slice(0, end));
+        return { text: str };
+      } catch (e) {
+        return null;
+      }
+    }
+
+    // Unquoted text: toolInput=Hello world (no braces or quotes)
+    // Take everything up to the next key=value pattern or end of line
+    const unquotedMatch = rest.match(/^([^{"\s][^\n]*?)(?:\s+\w+=[^\s]|$)/);
+    if (unquotedMatch && unquotedMatch[1].trim()) {
+      return { text: unquotedMatch[1].trim() };
+    }
+
+    return null;
+  }
+
+  /**
+   * Try to extract tts speech text from a raw log line using multiple patterns.
+   * Fallback for when extractToolInput returns null (openclaw format varies).
+   */
+  extractTtsTextFromRaw(line) {
+    if (!line) return null;
+    // input="...", text="...", content="...", message="..."
+    const quoted = line.match(/(?:^|\s)(?:input|text|content|message|speech|utterance)\s*=\s*"((?:[^"\\]|\\.)*)"/i);
+    if (quoted) return quoted[1];
+    // input={text:"..."} or input={"text":"..."}
+    const jsonMatch = line.match(/(?:^|\s)(?:input|args)\s*=\s*(\{[^}]+\})/i);
+    if (jsonMatch) {
+      try {
+        const obj = JSON.parse(jsonMatch[1]);
+        if (obj.text) return obj.text;
+        if (obj.input) return obj.input;
+      } catch {}
+    }
+    return null;
+  }
+
+  /**
+   * Build a specific, readable description from a tool name + its parsed input.
+   * Returns a rich string like "📄 Read dashboard.js (L1-200)" or null if no useful info.
+   */
+  buildRichDescription(toolName, toolInput) {
+    if (!toolInput) return null;
+    switch (toolName) {
+      case 'read': {
+        const fp = toolInput.file_path || toolInput.path || '';
+        const base = fp ? path.basename(fp) : '';
+        if (!base) return null;
+        return `Reviewing ${base}`;
+      }
+      case 'write': {
+        const fp = toolInput.file_path || toolInput.path || '';
+        return fp ? `Writing ${path.basename(fp)}` : null;
+      }
+      case 'edit': {
+        const fp = toolInput.file_path || toolInput.path || '';
+        return fp ? `Updating ${path.basename(fp)}` : null;
+      }
+      case 'multiedit': {
+        const fp = toolInput.file_path || toolInput.path || '';
+        return fp ? `Updating ${path.basename(fp)}` : null;
+      }
+      case 'exec':
+      case 'bash': {
+        const cmd = (toolInput.command || toolInput.cmd || '').trim();
+        if (!cmd) return null;
+        // Interpret common commands naturally
+        if (/screencapture/.test(cmd)) return `Taking a screenshot`;
+        if (/^open\s/.test(cmd)) return `Opening in browser`;
+        if (/^npm\s+install/.test(cmd)) return `Installing dependencies`;
+        if (/^npm\s+run\s+(\S+)/.test(cmd)) return `Running ${cmd.match(/^npm\s+run\s+(\S+)/)[1]}`;
+        if (/^npm\s/.test(cmd)) return `Running npm`;
+        if (/^npx\s/.test(cmd)) return `Running npx`;
+        if (/^git\s+clone/.test(cmd)) return `Cloning repository`;
+        if (/^git\s+/.test(cmd)) return `Running git`;
+        if (/^curl\s/.test(cmd)) return `Making a request`;
+        if (/^python/.test(cmd)) return `Running Python script`;
+        if (/^node\s/.test(cmd)) return `Running Node.js`;
+        if (/^ls\s?/.test(cmd)) return `Listing files`;
+        if (/^mkdir/.test(cmd)) return `Creating directory`;
+        if (/^cp\s/.test(cmd)) return `Copying file`;
+        if (/^mv\s/.test(cmd)) return `Moving file`;
+        if (/^rm\s/.test(cmd)) return `Removing file`;
+        if (/^cat\s/.test(cmd)) return `Reading file`;
+        // Fallback: show trimmed command but no more than 60 chars
+        return cmd.length > 60 ? cmd.slice(0, 60) + '…' : cmd;
+      }
+      case 'web_search': {
+        const q = toolInput.query || '';
+        if (!q) return null;
+        return `Searching for "${q.length > 60 ? q.slice(0, 60) + '…' : q}"`;
+      }
+      case 'web_fetch':
+      case 'webfetch': {
+        const url = toolInput.url || '';
+        if (!url) return null;
+        try {
+          const u = new URL(url);
+          return `Reading ${u.hostname}`;
+        } catch {
+          return `Reading page`;
+        }
+      }
+      case 'glob': {
+        const pattern = toolInput.pattern || '';
+        return pattern ? `Finding files` : null;
+      }
+      case 'grep': {
+        const pat = toolInput.pattern || '';
+        if (!pat) return null;
+        return `Searching codebase`;
+      }
+      case 'browser': {
+        const action = (toolInput.action || '').toLowerCase();
+        if (action === 'navigate' || action === 'goto' || action === 'open') {
+          const url = toolInput.url || toolInput.targetUrl || '';
+          try { const u = new URL(url); return `Opening ${u.hostname}`; }
+          catch { return `Opening page`; }
+        }
+        if (action === 'click') return `Clicking on the page`;
+        if (action === 'screenshot' || action === 'snapshot') return `Taking a screenshot`;
+        if (action === 'type') return `Entering text`;
+        if (action === 'scroll') return `Scrolling`;
+        if (action === 'act') return `Interacting with page`;
+        return `Browsing`;
+      }
+      case 'todocreate':
+      case 'todowrite':
+      case 'todo_write':
+        return `Updating task list`;
+      case 'memory_search': {
+        const q = toolInput.query || '';
+        return q ? `Recalling "${q.slice(0, 45)}"` : `Searching memory`;
+      }
+      case 'sessions_spawn': {
+        return `Starting a sub-agent`;
+      }
+      case 'sessions_send': {
+        return `Sending message to agent`;
+      }
+      default: {
+        const firstStr = Object.values(toolInput).find(v => typeof v === 'string' && v.length > 0);
+        if (firstStr) return `${firstStr.slice(0, 60)}`;
+        return null;
+      }
+    }
+  }
+
+  /**
+   * Parse tool activity from OpenClaw output
+   * Detects patterns like: "embedded run tool start: ... tool=read toolCallId=..."
+   * Also detects API calls, streaming, retries, and other lifecycle events
+   */
+  parseToolActivity(line) {
+    const trimmed = line.trim();
+
+    // Map tool names to friendly descriptions (fallback when toolInput is absent)
+    const toolDescriptions = {
+      'read': 'Reviewing file',
+      'write': 'Writing file',
+      'edit': 'Updating file',
+      'exec': 'Running command',
+      'bash': 'Running command',
+      'process': 'Running process',
+      'web_search': 'Searching the web',
+      'web_fetch': 'Reading page',
+      'browser': 'Browsing',
+      'image': 'Analyzing image',
+      'memory_search': 'Searching memory',
+      'memory_get': 'Reading memory',
+      'message': 'Sending message',
+      'cron': 'Scheduling task',
+      'tts': 'Generating speech',
+      'canvas': 'Updating canvas',
+      'nodes': 'Checking nodes',
+      'gateway': 'Gateway operation',
+      'sessions_spawn': 'Starting a sub-agent',
+      'sessions_send': 'Sending message to agent',
+      'sessions_list': 'Checking active agents',
+      'sessions_history': 'Reading conversation history',
+      'session_status': 'Checking status',
+      'agents_list': 'Listing agents',
+    };
+
+    // Match OpenClaw embedded tool start pattern: "tool start: ... tool=read"
+    const toolStartMatch = trimmed.match(/tool start:.*tool=(\w+)/i);
+    if (toolStartMatch) {
+      const toolName = toolStartMatch[1].toLowerCase();
+      const toolInput = this.extractToolInput(trimmed);
+      const richDesc = toolInput ? this.buildRichDescription(toolName, toolInput) : null;
+      return {
+        event: 'tool_start',
+        tool: toolName,
+        toolInput,
+        description: richDesc || toolDescriptions[toolName] || `Running ${toolName}...`,
+        raw: trimmed
+      };
+    }
+
+    // Match tool end pattern: "tool end: ... tool=read"
+    const toolEndMatch = trimmed.match(/tool end:.*tool=(\w+)/i);
+    if (toolEndMatch) {
+      const toolName = toolEndMatch[1].toLowerCase();
+      const durationMatch = trimmed.match(/durationMs=(\d+)/);
+      const durationMs = durationMatch ? parseInt(durationMatch[1]) : null;
+      return {
+        event: 'tool_end',
+        tool: toolName,
+        durationMs,
+        description: durationMs && durationMs > 2000
+          ? `✓ ${toolName} (${(durationMs / 1000).toFixed(1)}s)`
+          : `✓ ${toolName}`,
+        raw: trimmed
+      };
+    }
+
+    // Match toolResult in output (tool completed)
+    if (trimmed.includes('toolResult') || trimmed.includes('tool result')) {
+      return {
+        event: 'tool_result',
+        tool: null,
+        description: 'Processing tool result',
+        raw: trimmed
+      };
+    }
+
+    // === API/Model lifecycle events ===
+    // OpenClaw format: "embedded run <event>: runId=... key=value ..."
+    
+    // Prompt start = calling the model API (format: "embedded run prompt start:")
+    if (trimmed.includes('run prompt start:') || trimmed.includes('prompt start:')) {
+      return {
+        event: 'api_call_start',
+        tool: null,
+        description: '🌐 Calling model API...',
+        raw: trimmed
+      };
+    }
+
+    // Prompt end = model response received (format: "embedded run prompt end: ... durationMs=N")
+    const promptEndMatch = trimmed.match(/(?:run )?prompt end:.*durationMs=(\d+)/i);
+    if (promptEndMatch) {
+      const durationMs = parseInt(promptEndMatch[1]);
+      return {
+        event: 'api_call_end',
+        tool: null,
+        description: `✅ Model responded (${(durationMs/1000).toFixed(1)}s)`,
+        durationMs,
+        raw: trimmed
+      };
+    }
+
+    // Run start (format: "embedded run start: runId=... provider=... model=...")
+    if (trimmed.includes('embedded run start:') || trimmed.includes('run start:')) {
+      const modelMatch = trimmed.match(/model=([^\s]+)/);
+      const providerMatch = trimmed.match(/provider=([^\s]+)/);
+      return {
+        event: 'run_start',
+        tool: null,
+        description: `🚀 Starting run (${providerMatch?.[1] || 'unknown'}/${modelMatch?.[1] || 'unknown'})`,
+        raw: trimmed
+      };
+    }
+
+    // Run done (format: "embedded run done: ... durationMs=N aborted=...")
+    if (trimmed.includes('embedded run done:') || trimmed.includes('run done:')) {
+      const durationMatch = trimmed.match(/durationMs=(\d+)/);
+      const abortedMatch = trimmed.match(/aborted=(true|false)/);
+      const durationMs = durationMatch ? parseInt(durationMatch[1]) : null;
+      const wasAborted = abortedMatch?.[1] === 'true';
+      return {
+        event: 'run_done',
+        tool: null,
+        description: durationMs 
+          ? `🏁 Run ${wasAborted ? 'aborted' : 'complete'} (${(durationMs/1000).toFixed(1)}s total)` 
+          : '🏁 Run complete',
+        durationMs,
+        aborted: wasAborted,
+        raw: trimmed
+      };
+    }
+
+    // Compaction (format: "embedded run compaction start:")
+    if (trimmed.includes('compaction start:')) {
+      return {
+        event: 'compaction_start',
+        tool: null,
+        description: '🗜️ Compacting context...',
+        raw: trimmed
+      };
+    }
+
+    // Compaction retry
+    if (trimmed.includes('compaction retry:')) {
+      return {
+        event: 'compaction_retry',
+        tool: null,
+        description: '🗜️ Retrying compaction...',
+        raw: trimmed
+      };
+    }
+
+    // Timeout (format: "embedded run timeout:")
+    if (trimmed.includes('run timeout:')) {
+      return {
+        event: 'timeout',
+        tool: null,
+        description: '⏰ Run timed out',
+        raw: trimmed
+      };
+    }
+
+    // Abort still streaming warning
+    if (trimmed.includes('abort still streaming:')) {
+      return {
+        event: 'abort_streaming',
+        tool: null,
+        description: '⚠️ Aborting while still streaming',
+        raw: trimmed
+      };
+    }
+
+    // Rate limits / retries (various patterns)
+    if (trimmed.includes('rate limit') || trimmed.includes('429') || 
+        trimmed.includes('retrying') || trimmed.includes('retry:')) {
+      return {
+        event: 'rate_limit',
+        tool: null,
+        description: '⏳ Rate limited, retrying...',
+        raw: trimmed
+      };
+    }
+
+    // Agent lifecycle (format: "embedded run agent start:" / "embedded run agent end:")
+    if (trimmed.includes('run agent start:') || trimmed.includes('agent start:')) {
+      return {
+        event: 'agent_start',
+        tool: null,
+        description: '🤖 Agent starting...',
+        raw: trimmed
+      };
+    }
+
+    if (trimmed.includes('run agent end:') || trimmed.includes('agent end:')) {
+      return {
+        event: 'agent_end',
+        tool: null,
+        description: '🤖 Agent finished',
+        raw: trimmed
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Strip ANSI escape codes from a string
+   */
+  stripAnsi(str) {
+    // Matches ESC[ sequences (colors, cursor movement, etc.)
+    return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')
+              .replace(/\x1b\][^\x07]*\x07/g, '') // OSC sequences
+              .replace(/\x1b[^[]/g, '');           // Other ESC sequences
+  }
+
+  /**
+   * Check if a line is a diagnostic/verbose log that should be hidden from chat
+   */
+  isDiagnosticLog(line) {
+    const trimmed = this.stripAnsi(line).trim();
+    return trimmed.includes('[agent/embedded]') ||
+           trimmed.includes('[diagnostic]') ||
+           trimmed.includes('lane enqueue:') ||
+           trimmed.includes('lane dequeue:') ||
+           trimmed.includes('lane task done:') ||
+           trimmed.includes('session state:') ||
+           trimmed.includes('run registered:') ||
+           trimmed.includes('run cleared:') ||
+           trimmed.includes('embedded run') ||
+           trimmed.includes('Registered plugin command:') ||
+           trimmed.includes('(plugin:') ||
+           // Filter out error messages - users shouldn't see technical errors
+           trimmed.startsWith('Error:') ||
+           trimmed.includes('Agent failed:') ||
+           trimmed.includes('[openclaw]') ||
+           trimmed.includes('Unhandled promise rejection') ||
+           trimmed.includes('shared_storage_worklet') ||
+           trimmed.includes('playwright-core') ||
+           trimmed.includes('ECONNREFUSED') ||
+           trimmed.includes('ETIMEDOUT') ||
+           trimmed.includes('Command exited with code') ||
+           trimmed.includes('targetInfo') ||
+           trimmed.includes('crBrowser') ||
+           trimmed.includes('crConnection') ||
+           // Image processing / tool internals
+           trimmed.startsWith('Optimized PNG') ||
+           trimmed.startsWith('Optimized JPEG') ||
+           trimmed.startsWith('Optimized image') ||
+           trimmed.includes('preserving alpha') ||
+           trimmed.includes('side≤') ||
+           trimmed.match(/^\d+x\d+px [\d.]+(KB|MB)/) ||
+           trimmed.includes('Image resized to fit') ||
+           trimmed.includes('→') && trimmed.includes('KB') && trimmed.includes('->') ||
+           trimmed.includes('(side≤');
+  }
+
+  /**
+   * Register an agent with Canary and get its API key
+   * Each agent gets its own identity in Canary for proper tracking
+   */
+  async registerWithCanary(agentId, workDir) {
+    try {
+      const response = await fetch(`${CANARY_ENDPOINT}/api/agents/register`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: `AgentForge: ${agentId}`,
+          description: `Auto-registered agent working on ${path.basename(workDir)}`,
+          platform: 'openclaw',
+          owner_hint: 'AgentForge spawned agent',
+          // If parent API key is set, sub-agents auto-inherit ownership
+          ...(CANARY_PARENT_API_KEY ? { parent_agent_api_key: CANARY_PARENT_API_KEY } : {})
+        })
+      });
+
+      if (!response.ok) {
+        console.log(`⚠️  Canary registration failed: ${response.status}`);
+        return null;
+      }
+
+      const data = await response.json();
+      console.log(`🐤 Registered with Canary: ${data.agent?.id || 'unknown'}`);
+      
+      if (data.agent?.claim_url) {
+        console.log(`   Claim URL: ${data.agent.claim_url}`);
+      }
+      
+      return data.agent?.api_key || null;
+    } catch (error) {
+      console.log(`⚠️  Could not reach Canary: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Create a new isolated agent
+   */
+  async createAgent(agentId, workDir) {
+    // Ensure workspace directory exists before openclaw tries to use it
+    mkdirSync(workDir, { recursive: true });
+
+    // Register with Canary to get agent-specific API key
+    const canaryApiKey = await this.registerWithCanary(agentId, workDir);
+    
+    // Store Canary API key in agent's workspace for persistence
+    if (canaryApiKey) {
+      const canaryConfigPath = path.join(workDir, '.canary');
+      writeFileSync(canaryConfigPath, JSON.stringify({ 
+        apiKey: canaryApiKey,
+        agentId,
+        registeredAt: new Date().toISOString()
+      }, null, 2));
+    }
+
+    return new Promise((resolve, reject) => {
+      console.log(`Creating OpenClaw agent: ${agentId}`);
+      console.log(`  Working directory: ${workDir}\n`);
+
+      const proc = spawn(process.execPath, [this.bin,
+        'agents', 'add', agentId, '--workspace', workDir, '--non-interactive'
+      ], { env: { ...process.env } });
+
+      let output = '';
+      let error = '';
+
+      proc.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+
+      proc.stderr.on('data', (data) => {
+        error += data.toString();
+      });
+
+      proc.on('error', (err) => {
+        console.error(`⚠️  Failed to spawn openclaw for createAgent: ${err.message}`);
+        resolve({ agentId, workDir }); // Don't crash - agent may already exist
+      });
+
+      proc.on('close', async (code) => {
+        if (code === 0) {
+          console.log(`✓ Agent created: ${agentId}`);
+        } else {
+          // Agent might already exist, which is fine
+          console.log(`⚠️  Agent creation failed or already exists: ${agentId}`);
+          if (error) {
+            console.error(`  Error: ${error.trim()}`);
+          }
+        }
+
+        // Copy AgentForge template files AFTER openclaw creates the agent
+        // This ensures MEMORY.md and memory/ dir exist for memory persistence
+        // Use bundled templates (packaged with worker) as primary source,
+        // fall back to /tmp if somehow missing
+        const bundledTemplateDir = path.join(path.dirname(new URL(import.meta.url).pathname), '../../templates/agent');
+        const templateDir = existsSync(bundledTemplateDir) ? bundledTemplateDir : '/tmp/agentforge/templates/agent';
+        console.log(`📁 Using templates from: ${templateDir}`);
+        try {
+          if (existsSync(templateDir)) {
+            const { execSync } = await import('child_process');
+            
+            // Copy MEMORY.md if it doesn't exist
+            const memoryMdSrc = path.join(templateDir, 'MEMORY.md');
+            const memoryMdDst = path.join(workDir, 'MEMORY.md');
+            if (existsSync(memoryMdSrc) && !existsSync(memoryMdDst)) {
+              execSync(`cp "${memoryMdSrc}" "${memoryMdDst}"`, { stdio: 'ignore' });
+              console.log(`📁 Added MEMORY.md template`);
+            }
+
+            // Create memory/ directory if it doesn't exist
+            const memoryDir = path.join(workDir, 'memory');
+            if (!existsSync(memoryDir)) {
+              mkdirSync(memoryDir, { recursive: true });
+              console.log(`📁 Created memory/ directory`);
+            }
+
+            // Copy core identity/personality files — always overwrite so all machines stay in sync
+            for (const fname of ['AGENTS.md', 'SOUL.md', 'TOOLS.md']) {
+              const src = path.join(templateDir, fname);
+              const dst = path.join(workDir, fname);
+              if (existsSync(src)) {
+                execSync(`cp "${src}" "${dst}"`, { stdio: 'ignore' });
+                console.log(`📁 Applied ${fname} template`);
+              }
+            }
+
+            // Copy AGENTFORGE.md (platform guide with projects path)
+            const agentforgeMdSrc = path.join(templateDir, 'AGENTFORGE.md');
+            const agentforgeMdDst = path.join(workDir, 'AGENTFORGE.md');
+            if (existsSync(agentforgeMdSrc)) {
+              execSync(`cp "${agentforgeMdSrc}" "${agentforgeMdDst}"`, { stdio: 'ignore' });
+              console.log(`📁 Added AGENTFORGE.md platform guide`);
+            }
+          }
+        } catch (err) {
+          console.warn(`⚠️  Template setup failed: ${err.message}`);
+        }
+
+        resolve({ agentId, workDir });
+      });
+    });
+  }
+
+  /**
+   * Run an agent task
+   * Images are saved to workspace and referenced in message for vision model analysis
+   */
+  async runAgentTask(agentId, task, workDir, sessionId = null, image = null, browserProfile = null, imageWorkDir = null) {
+    // ── Gateway path disabled — subprocess shows live tool activity ──────────
+    // Gateway path: SSE token streaming — tokens arrive live as the model generates.
+    // Dashboard buffers tokens into sentences before showing each as a complete bubble.
+    if (!image && this.gatewayPort && this.gatewayToken) {
+      console.log(`\n🤖 Running agent (streaming): ${agentId}`);
+      console.log(`   Task: ${task.slice(0, 120)}${task.length > 120 ? '…' : ''}`);
+      try {
+        const streamResult = await this._runAgentTaskStreaming(agentId, task, sessionId);
+        if (streamResult !== null) {
+          // Gateway request succeeded (streamResult.succeeded === true).
+          // Use the text response if any; if the agent only did tool work with no
+          // text output, return empty string — do NOT fall back to subprocess (which
+          // would re-run the same task a second time and corrupt the session state).
+          const responseText = streamResult.text || '';
+          if (!responseText) {
+            console.log(`[${agentId}] ✅ Gateway task completed with no text output (tool-only task)`);
+          }
+          let identity = { identityName: agentId, identityEmoji: '🤖' };
+          try { identity = await this.getAgentIdentity(agentId); } catch { /* ignore */ }
+          this.emit('agent_completed', { agentId, duration: 0, result: { output: responseText }, identity });
+          return { success: true, agentId, duration: 0, result: { output: responseText }, identity };
+        }
+        console.warn(`[${agentId}] ⚠️ Streaming request failed — falling back to subprocess`);
+      } catch (err) {
+        console.warn(`[${agentId}] ⚠️ Streaming failed (${err.message}) — falling back to subprocess`);
+      }
+    }
+    // ── Subprocess fallback ────────────────────────────────────────────────────
+    return new Promise(async (resolve, reject) => {
+      console.log(`\n🤖 Running agent: ${agentId}`);
+      console.log(`   Task: ${task}`);
+      console.log(`   Working dir: ${workDir}`);
+      if (sessionId) {
+        console.log(`   Session: ${sessionId}`);
+      }
+      if (browserProfile) {
+        console.log(`   Browser profile: ${browserProfile}`);
+      }
+
+      let imagePath = null;
+      let modifiedTask = task;
+
+      // Handle image by saving to workspace
+      if (image) {
+        try {
+          const fs = await import('fs/promises');
+          const path = await import('path');
+
+          // Use imageWorkDir (agent's actual workspace) if provided, otherwise fall back to workDir
+          const imageDir = imageWorkDir || workDir;
+          
+          // Ensure workspace directory exists before saving image
+          await fs.mkdir(imageDir, { recursive: true });
+
+          // Extract base64 data (remove data:image/png;base64, prefix if present)
+          const base64Data = image.replace(/^data:image\/\w+;base64,/, '');
+          const buffer = Buffer.from(base64Data, 'base64');
+
+          // Save to workspace with timestamp to avoid conflicts
+          const timestamp = Date.now();
+          const imageFileName = `uploaded_image_${timestamp}.png`;
+          imagePath = path.join(imageDir, imageFileName);
+
+          await fs.writeFile(imagePath, buffer);
+          console.log(`   📷 Image saved to: ${imagePath}`);
+
+          // Modify task to reference the image
+          modifiedTask = `${task}\n\n[There is an image file in the workspace: ${imageFileName}]`;
+        } catch (error) {
+          console.error(`   ⚠️  Failed to save image: ${error.message}`);
+        }
+      }
+
+      console.log('\n');
+
+      const startTime = Date.now();
+      let runCompleted = false;
+      let completionTimer = null;
+      let promiseSettled = false;
+      let agentEndSeen = false; // true once "agent end: isError=false" fires
+
+      // Build command arguments with potentially modified task
+      // --local is required since openclaw 2026.3.8 to run embedded instead of via Gateway
+      const args = [
+        'agent',
+        '--local',
+        '--agent', agentId,
+        '--message', modifiedTask,
+        '--verbose', 'on'  // Enable tool call output
+      ];
+
+      // Add session ID for conversation persistence
+      if (sessionId) {
+        args.push('--session-id', sessionId);
+      }
+
+      // Browser profile selection (cdp-url flag removed - not supported by openclaw agent)
+
+      // Ensure working directory exists before spawning
+      mkdirSync(workDir, { recursive: true });
+
+      // Load agent-specific Canary API key if available
+      let canaryApiKey = null;
+      try {
+        const canaryConfigPath = path.join(workDir, '.canary');
+        if (existsSync(canaryConfigPath)) {
+          const canaryConfig = JSON.parse(readFileSync(canaryConfigPath, 'utf-8'));
+          canaryApiKey = canaryConfig.apiKey;
+        }
+      } catch {
+        // No Canary config, that's fine
+      }
+
+      // Build environment with agent-specific Canary key + valid Anthropic API key
+      const agentEnv = { ...process.env };
+      if (canaryApiKey) {
+        agentEnv.CANARY_API_KEY = canaryApiKey;
+        console.log(`   🐤 Canary tracking: enabled (agent-specific key)`);
+      }
+      // Inject valid Anthropic key directly — bypasses broken auth-profiles.json on any machine.
+      // Prefer the locally cached key, but fall back to process.env which may be set later by the server.
+      const resolvedAnthropicKey = this.anthropicApiKey || process.env.ANTHROPIC_API_KEY || null;
+      if (resolvedAnthropicKey) {
+        agentEnv.ANTHROPIC_API_KEY = resolvedAnthropicKey;
+        // Keep the instance cache updated so subsequent spawns reuse the injected key without re-reading env
+        if (!this.anthropicApiKey) {
+          this.anthropicApiKey = resolvedAnthropicKey;
+        }
+      }
+
+      // Auto-fix auth-profiles.json before spawning: remove invalid anthropic:default key
+      // This self-heals any machine where the default key returns 401
+      try {
+        const authPath = path.join(homedir(), '.openclaw', 'agents', agentId, 'agent', 'auth-profiles.json');
+        if (existsSync(authPath)) {
+          const authData = JSON.parse(readFileSync(authPath, 'utf-8'));
+          if (authData?.profiles?.['anthropic:default']) {
+            delete authData.profiles['anthropic:default'];
+            if (!authData.lastGood) authData.lastGood = {};
+            authData.lastGood['anthropic'] = 'anthropic:manual';
+            writeFileSync(authPath, JSON.stringify(authData, null, 2));
+            console.log(`[${agentId}] 🔑 Auto-fixed auth: removed invalid anthropic:default key`);
+          }
+        }
+      } catch (authFixErr) {
+        // Non-fatal - openclaw will fail with 401 if key is bad, which is catchable
+        console.warn(`[${agentId}] ⚠️ Auth fix skipped: ${authFixErr.message}`);
+      }
+
+      // Kill any existing process for this agent before spawning — prevents race condition
+      // where task 1 resolves via runCompleted but its process is still alive for 5s,
+      // task 2 spawns a new process, both fight over session files, task 2 hangs.
+      const existingAgent = this.activeAgents.get(agentId);
+      if (existingAgent && existingAgent.proc && !existingAgent.proc.killed) {
+        console.log(`[${agentId}] 🔪 Killing lingering process (pid ${existingAgent.proc.pid}) before spawning new one`);
+        try { treeKill(existingAgent.proc.pid, 'SIGKILL'); } catch (e) { /* already dead */ }
+        this.activeAgents.delete(agentId);
+        // Wait for process to fully exit and release file locks before spawning
+        await new Promise(r => setTimeout(r, 800));
+      }
+
+      // Change to working directory and run agent
+      // Use process.execPath (node) directly to avoid shell metacharacter issues
+      // with user message content (quotes, apostrophes, etc.)
+      const proc = spawn(process.execPath, [this.bin, ...args], {
+        cwd: workDir,
+        env: agentEnv
+      });
+
+      let output = '';
+      let filteredOutput = ''; // user-facing output only — no diagnostic/system logs
+      let error = '';
+      let recentLines = []; // rolling buffer for TTS context debugging
+      let firstOutputSeen = false;
+
+      // Kill if openclaw produces zero output for 90s — means it's hung on API call
+      const firstOutputTimer = setTimeout(() => {
+        if (!firstOutputSeen && !promiseSettled) {
+          console.warn(`[${agentId}] ⚠️ No output in 90s — openclaw hung, killing`);
+          try { proc.kill('SIGKILL'); } catch (e) { /* already dead */ }
+          if (!promiseSettled) {
+            promiseSettled = true;
+            this.activeAgents.delete(agentId);
+            reject(new Error('openclaw produced no output within 90s — possible API hang'));
+          }
+        }
+      }, 90000);
+
+      proc.stdout.on('data', (data) => {
+        firstOutputSeen = true;
+        clearTimeout(firstOutputTimer);
+        const text = data.toString();
+        output += text;
+
+        // Process line by line to filter technical logs
+        const lines = text.split('\n');
+        const filteredLines = [];
+
+        for (const line of lines) {
+          const trimmed = this.stripAnsi(line).trim();
+
+          // Detect "agent end: isError=false" — the agent's actual work is done.
+          // After this, openclaw may do compaction (LLM call) and then hang without
+          // ever emitting "embedded run done". Start a 30s grace timer so if the
+          // process doesn't exit cleanly we force-resolve and unblock the queue.
+          if (!agentEndSeen && trimmed.includes('run agent end:') && trimmed.includes('isError=false')) {
+            agentEndSeen = true;
+            console.log(`[${agentId}] ✅ Agent task finished (agent end isError=false), starting 30s grace timer`);
+            if (!completionTimer) {
+              completionTimer = setTimeout(async () => {
+                if (runCompleted || promiseSettled) return; // already handled
+                console.log(`[${agentId}] ⚠️ Process still running 30s after agent end — force killing (compaction hung?)`);
+                runCompleted = true;
+                try { proc.kill('SIGTERM'); } catch (e) { /* already dead */ }
+                setTimeout(() => { try { proc.kill('SIGKILL'); } catch (e) {} }, 1000);
+                if (!promiseSettled) {
+                  promiseSettled = true;
+                  const duration = Date.now() - startTime;
+                  let identity = { identityName: agentId, identityEmoji: '🤖' };
+                  try {
+                    identity = await Promise.race([
+                      this.getAgentIdentity(agentId),
+                      new Promise(r => setTimeout(() => r(identity), 5000))
+                    ]);
+                  } catch (e) { /* use default */ }
+                  this.activeAgents.delete(agentId);
+                  let result;
+                  try { result = JSON.parse(output); } catch (e) { result = { output: filteredOutput }; }
+                  console.log(`\n✅ Agent ${agentId} (${identity.identityName}) completed in ${(duration / 1000).toFixed(2)}s (force-resolved after compaction hang)\n`);
+                  this.emit('agent_completed', { agentId, duration, result, identity });
+                  resolve({ success: true, agentId, duration, result, identity });
+                }
+              }, 30000);
+            }
+          }
+
+          // Detect when OpenClaw run completes - process should exit soon after
+          // Pattern: "embedded run done" or "run_completed"
+          if (trimmed.includes('embedded run done') || trimmed.includes('run_completed')) {
+            if (!runCompleted) {
+              runCompleted = true;
+              // Cancel the agentEnd grace timer — clean exit happened
+              if (completionTimer) { clearTimeout(completionTimer); completionTimer = null; }
+              console.log(`[${agentId}] 🏁 Run completed, waiting for process exit...`);
+
+              // Give process 5 seconds to exit gracefully, then force kill and resolve
+              completionTimer = setTimeout(async () => {
+                if (proc && !proc.killed) {
+                  console.log(`[${agentId}] ⚠️ Process didn't exit after run completed, force killing`);
+                  try {
+                    proc.kill('SIGTERM');
+                    setTimeout(() => {
+                      if (!proc.killed) {
+                        proc.kill('SIGKILL');
+                      }
+                    }, 1000);
+                  } catch (e) {
+                    // Process might already be dead
+                  }
+                }
+                // Task completed successfully — resolve now instead of waiting for close event.
+                // The close event can hang indefinitely if openclaw's child subprocesses keep
+                // stdio pipes open after the parent is killed.
+                if (!promiseSettled) {
+                  promiseSettled = true;
+                  const duration = Date.now() - startTime;
+                  let identity = { identityName: agentId, identityEmoji: '🤖' };
+                  try {
+                    identity = await Promise.race([
+                      this.getAgentIdentity(agentId),
+                      new Promise(r => setTimeout(() => r(identity), 5000))
+                    ]);
+                  } catch (e) { /* use default */ }
+                  this.activeAgents.delete(agentId);
+                  let result;
+                  try { result = JSON.parse(output); } catch (e) { result = { output: filteredOutput }; }
+                  console.log(`\n✅ Agent ${agentId} (${identity.identityName}) completed in ${(duration / 1000).toFixed(2)}s (force-resolved after kill)\n`);
+                  this.emit('agent_completed', { agentId, duration, result, identity });
+                  resolve({ success: true, agentId, duration, result, identity });
+                }
+              }, 5000);
+            }
+          }
+
+          // Rolling buffer of last 15 raw lines for TTS context debugging
+          if (!recentLines) recentLines = [];
+          recentLines.push(line);
+          if (recentLines.length > 15) recentLines.shift();
+
+          // Only filter out EXACT system message patterns (starts with these)
+          const isSystemLog = trimmed.startsWith('[Canary]') ||
+                             trimmed.startsWith('[agents/') ||
+                             trimmed.includes('Plugin registered') ||
+                             trimmed.includes('Registered plugin command:') ||
+                             trimmed.includes('inherited auth-profiles') ||
+                             trimmed.includes('gateway tool:') ||
+                             trimmed.includes('Debugger listening') ||
+                             trimmed.includes('[diagnostic]') ||
+                             trimmed.includes('[agent/embedded]') ||
+                             trimmed.includes('browser/service') ||
+                             trimmed.includes('Browser control service') ||
+                             trimmed.includes('profiles=');
+
+          // Detect AGENTFORGE_IMAGE:/path — agent wants to send a screenshot to the user's chat
+          if (trimmed.startsWith('AGENTFORGE_IMAGE:')) {
+            const imagePath = trimmed.slice('AGENTFORGE_IMAGE:'.length).trim();
+            try {
+              const imageData = readFileSync(imagePath);
+              const ext = imagePath.split('.').pop().toLowerCase();
+              const mime = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : ext === 'gif' ? 'image/gif' : 'image/png';
+              const base64 = `data:${mime};base64,${imageData.toString('base64')}`;
+              this.emit('agent_image', { agentId, image: base64 });
+              console.log(`[${agentId}] 📸 Sending screenshot to chat (${Math.round(imageData.length / 1024)}KB)`);
+            } catch (e) {
+              console.warn(`[${agentId}] ⚠️ Could not read image ${imagePath}:`, e.message);
+            }
+            continue; // Don't show the marker line in chat
+          }
+
+          // Always emit agent_alive + parse tool activity for ANY stdout line —
+          // [agent/embedded] lines are system logs but still carry tool start/end events
+          if (trimmed.length > 0) {
+            this.emit('agent_alive', { agentId });
+            const toolActivityAny = this.parseToolActivity(line);
+            if (toolActivityAny) {
+              if (toolActivityAny.tool === 'tts' && toolActivityAny.event === 'tool_start' && !toolActivityAny.toolInput) {
+                this.emit('tts_context', { agentId, lines: [...recentLines] });
+              }
+              this.emit('tool_activity', { agentId, ...toolActivityAny });
+            }
+          }
+
+          if (!isSystemLog && trimmed.length > 0) {
+            // Drop OpenClaw placeholder responses that confuse the UI
+            if (/^no reply from agent\.?$/i.test(trimmed)) {
+              continue;
+            }
+            // tool activity already emitted above for all lines
+            const toolActivity = this.parseToolActivity(line);
+
+            // Filter out diagnostic/verbose logs from chat
+            if (!this.isDiagnosticLog(line) && !toolActivity) {
+              // Always push ANSI-stripped version so raw escape codes never reach the UI
+              filteredLines.push(trimmed);
+            }
+          }
+
+          // Detect tool calls and emit current action
+          const currentAction = this.parseCurrentAction(trimmed);
+          if (currentAction) {
+            this.emit('current_action', {
+              agentId,
+              action: currentAction
+            });
+          }
+
+          if (trimmed.length > 0) {
+            console.log(`[${agentId}] ${trimmed}`);
+          }
+        }
+
+        // Emit filtered output and accumulate for task_complete response
+        if (filteredLines.length > 0) {
+          const filteredChunk = filteredLines.join('\n') + '\n';
+          filteredOutput += (filteredOutput ? '\n' : '') + filteredChunk;
+          this.emit('agent_output', {
+            agentId,
+            output: filteredChunk
+          });
+        }
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(firstOutputTimer);
+        console.error(`❌ Failed to spawn openclaw for runAgentTask: ${err.message}`);
+        this.activeAgents.delete(agentId);
+        if (!promiseSettled) {
+          promiseSettled = true;
+          reject(new Error(`Failed to spawn openclaw: ${err.message}`));
+        }
+      });
+
+      proc.stderr.on('data', (data) => {
+        const text = data.toString();
+        error += text;
+
+        this.emit('agent_error', {
+          agentId,
+          error: text
+        });
+
+        // Print stderr in real-time
+        console.error(`[${agentId}] [stderr] ${text.trim()}`);
+      });
+
+      proc.on('close', async (code) => {
+        const duration = Date.now() - startTime;
+        clearTimeout(firstOutputTimer);
+
+        // Clear the completion timer if it's still running
+        if (completionTimer) {
+          clearTimeout(completionTimer);
+          completionTimer = null;
+        }
+
+        // If promise already settled by force-resolve after kill, skip
+        // IMPORTANT: only delete from activeAgents if this is still OUR process —
+        // a newer task may have already replaced the entry with a new process
+        if (promiseSettled) {
+          const tracked = this.activeAgents.get(agentId);
+          if (tracked && tracked.proc === proc) {
+            this.activeAgents.delete(agentId);
+          }
+          return;
+        }
+        promiseSettled = true;
+
+        // Cleanup image file if it was created
+        if (imagePath) {
+          try {
+            const fs = await import('fs/promises');
+            await fs.unlink(imagePath);
+            console.log(`   🗑️  Cleaned up image file`);
+          } catch (error) {
+            // Ignore cleanup errors
+          }
+        }
+
+        // Get agent identity info
+        const identity = await this.getAgentIdentity(agentId);
+
+        // Clean up activeAgents so stale processes don't confuse future tasks
+        this.activeAgents.delete(agentId);
+
+        if (code === 0) {
+          console.log(`\n✅ Agent ${agentId} (${identity.identityName}) completed in ${(duration / 1000).toFixed(2)}s\n`);
+
+          let result;
+          try {
+            // Try to parse JSON output
+            result = JSON.parse(output);
+          } catch (e) {
+            // Use filteredOutput (user-facing only) — raw `output` contains diagnostic logs
+            result = { output: filteredOutput || output };
+          }
+
+          this.emit('agent_completed', {
+            agentId,
+            duration,
+            result,
+            identity
+          });
+
+          resolve({
+            success: true,
+            agentId,
+            duration,
+            result,
+            identity
+          });
+        } else {
+          console.error(`\n❌ Agent ${agentId} failed (exit code ${code})`);
+          if (error) {
+            console.error(`Error output:\n${error}`);
+          }
+          console.error('');
+
+          this.emit('agent_failed', {
+            agentId,
+            error,
+            code
+          });
+
+          reject(new Error(`Agent failed: ${error || 'Unknown error'}`));
+        }
+      });
+
+      // Track active agent
+      this.activeAgents.set(agentId, {
+        proc,
+        startTime,
+        task,
+        workDir
+      });
+    });
+  }
+
+  /**
+   * Spawn and run multiple agents in parallel
+   */
+  async runMultipleAgents(agentConfigs) {
+    console.log(`\n${'='.repeat(80)}`);
+    console.log(`🚀 Spawning ${agentConfigs.length} OpenClaw agents in parallel`);
+    console.log(`${'='.repeat(80)}\n`);
+
+    // First, ensure all agents exist
+    const createPromises = agentConfigs.map(config =>
+      this.createAgent(config.agentId, config.workDir)
+    );
+
+    await Promise.allSettled(createPromises);
+
+    // Then run all agent tasks in parallel
+    const runPromises = agentConfigs.map(config =>
+      this.runAgentTask(config.agentId, config.task, config.workDir)
+    );
+
+    const results = await Promise.allSettled(runPromises);
+
+    const successful = results.filter(r => r.status === 'fulfilled').length;
+    const failed = results.filter(r => r.status === 'rejected').length;
+
+    console.log(`\n${'='.repeat(80)}`);
+    console.log(`📊 Results: ${successful} succeeded, ${failed} failed`);
+    console.log(`${'='.repeat(80)}\n`);
+
+    return results;
+  }
+
+  /**
+   * List all agents (with timeout to prevent hanging)
+   */
+  async listAgents() {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(process.execPath, [this.bin, 'agents', 'list', '--json']);
+      let output = '';
+      let resolved = false;
+      
+      // 10 second timeout - if this hangs, don't block forever
+      const timeout = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          console.log('⚠️ listAgents timed out after 10s');
+          try { proc.kill('SIGKILL'); } catch (e) {}
+          resolve([]);
+        }
+      }, 10000);
+
+      proc.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+      
+      proc.on('error', (err) => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          console.error('⚠️ listAgents error:', err.message);
+          resolve([]);
+        }
+      });
+
+      proc.on('close', (code) => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          if (code === 0) {
+            try {
+              const agents = JSON.parse(output);
+              resolve(agents);
+            } catch (e) {
+              resolve([]);
+            }
+          } else {
+            resolve([]);
+          }
+        }
+      });
+    });
+  }
+
+  /**
+   * Get agent identity info (name, emoji) from OpenClaw
+   * Has a 15s total timeout to prevent blocking
+   */
+  async getAgentIdentity(agentId) {
+    try {
+      // Race against a timeout
+      const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => resolve(null), 15000);
+      });
+      
+      const agents = await Promise.race([this.listAgents(), timeoutPromise]);
+      
+      if (agents) {
+        const agent = agents.find(a => a.id === agentId);
+        if (agent) {
+          return {
+            identityName: agent.identityName || agent.name || agentId,
+            identityEmoji: agent.identityEmoji || '🤖'
+          };
+        }
+      }
+    } catch (e) {
+      console.error('Failed to get agent identity:', e);
+    }
+    return { identityName: agentId, identityEmoji: '🤖' };
+  }
+
+  /**
+   * Get active agents
+   */
+  getActiveAgents() {
+    return Array.from(this.activeAgents.values());
+  }
+
+  /**
+   * Parse output line to detect current action/tool being used
+   * Returns a human-readable action string or null
+   */
+  parseCurrentAction(line) {
+    if (!line) return null;
+    
+    // Tool call patterns - OpenClaw outputs these when calling tools
+    const toolPatterns = [
+      // Direct tool invocations
+      { pattern: /\[tools?\]\s*(\w+)/i, format: (m) => this.formatToolName(m[1]) },
+      { pattern: /calling\s+(\w+)/i, format: (m) => this.formatToolName(m[1]) },
+      { pattern: /tool:\s*(\w+)/i, format: (m) => this.formatToolName(m[1]) },
+      
+      // Browser actions
+      { pattern: /browser.*?(snapshot|click|navigate|open|type|screenshot)/i, format: () => '🌐 Using browser' },
+      { pattern: /opening.*?url/i, format: () => '🌐 Opening URL' },
+      { pattern: /taking.*?screenshot/i, format: () => '📸 Taking screenshot' },
+      
+      // File operations
+      { pattern: /\bread\b.*?file|reading\s+\w+\.(js|ts|py|md|json|txt|html|css)/i, format: () => '📄 Reading file' },
+      { pattern: /\bwrite\b.*?file|writing\s+to/i, format: () => '✏️ Writing file' },
+      { pattern: /\bedit\b.*?file|editing/i, format: () => '✏️ Editing file' },
+      
+      // Command execution
+      { pattern: /\bexec\b|executing|running\s+command|spawn/i, format: () => '⚡ Running command' },
+      { pattern: /\$\s*\w+|bash|shell/i, format: () => '⚡ Running command' },
+      
+      // Search/web
+      { pattern: /web_search|searching.*?web/i, format: () => '🔍 Searching web' },
+      { pattern: /web_fetch|fetching.*?url/i, format: () => '🌐 Fetching URL' },
+      
+      // Memory
+      { pattern: /memory_search/i, format: () => '🧠 Searching memory' },
+      
+      // Messages
+      { pattern: /\bmessage\b.*?send|sending.*?message/i, format: () => '💬 Sending message' },
+      
+      // Thinking indicator (Claude's extended thinking)
+      { pattern: /thinking|reasoning/i, format: () => '🤔 Thinking' },
+    ];
+    
+    for (const { pattern, format } of toolPatterns) {
+      const match = line.match(pattern);
+      if (match) {
+        return format(match);
+      }
+    }
+    
+    return null;
+  }
+
+  /**
+   * Format tool name into human-readable action
+   */
+  formatToolName(toolName) {
+    const toolLabels = {
+      'read': '📄 Reading file',
+      'write': '✏️ Writing file',
+      'edit': '✏️ Editing file',
+      'exec': '⚡ Running command',
+      'browser': '🌐 Using browser',
+      'web_search': '🔍 Searching web',
+      'web_fetch': '🌐 Fetching URL',
+      'memory_search': '🧠 Searching memory',
+      'memory_get': '🧠 Reading memory',
+      'message': '💬 Messaging',
+      'image': '🖼️ Analyzing image',
+      'tts': '🔊 Text to speech',
+      'cron': '⏰ Managing schedule',
+      'nodes': '📱 Using devices',
+      'canvas': '🎨 Using canvas',
+      'sessions_spawn': '🤖 Spawning agent',
+      'sessions_send': '💬 Messaging agent',
+    };
+    
+    const lower = toolName.toLowerCase();
+    return toolLabels[lower] || `🔧 ${toolName}`;
+  }
+
+  /**
+   * Cancel a running agent task by killing the process tree immediately
+   */
+  cancelAgent(agentId) {
+    const agentInfo = this.activeAgents.get(agentId);
+    if (!agentInfo || !agentInfo.proc) {
+      console.log(`⚠️  No running process found for agent ${agentId}`);
+      return false;
+    }
+
+    const { proc } = agentInfo;
+    const pid = proc.pid;
+    
+    console.log(`🛑 Killing process tree for agent ${agentId} (PID: ${pid})`);
+    
+    // Clean up tracking immediately
+    this.activeAgents.delete(agentId);
+    
+    // Use tree-kill to kill the entire process tree with SIGKILL (immediate, no grace period)
+    treeKill(pid, 'SIGKILL', (err) => {
+      if (err) {
+        console.log(`⚠️  tree-kill error (process may already be dead): ${err.message}`);
+      } else {
+        console.log(`✅ Process tree ${pid} killed successfully`);
+      }
+    });
+    
+    this.emit('agent_cancelled', { agentId });
+    
+    return true;
+  }
+}