@yeaft/webchat-agent 0.1.613 → 0.1.614

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.613",
+  "version": "0.1.614",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/engine.js

@@ -163,6 +163,9 @@ export class Engine {
   /** @type {object|null} — Config override for internal tasks (recall, consolidation, dream) using fastModel */
   #fastConfig;
 
+  /** @type {((agentId: string, evt: object) => void) | null} */
+  #subAgentEventSink = null;
+
   /**
    * task-325a — abort state.
    *
@@ -451,9 +454,39 @@ export class Engine {
       inboundEnvelope: vpCtx?.inboundEnvelope,
       taskId: vpCtx?.taskId,
       taskMembers: vpCtx?.taskMembers,
+      // Sub-agent plumbing — Agent tool needs these to spawn a child
+      // Engine that inherits the parent's adapter / stores / toolset.
+      parentEngineDeps: {
+        adapter: this.#adapter,
+        trace: this.#trace,
+        config: this.#config,
+        memoryStore: this.#memoryStore,
+        memoryShardStore: this.#memoryShardStore,
+        parentToolRegistry: this.#toolRegistry,
+        skillManager: this.#skillManager,
+        mcpManager: this.#mcpManager,
+        yeaftDir: this.#yeaftDir,
+        parentName: vpCtx?.senderVpId || 'parent',
+        parentVpId: vpCtx?.senderVpId || null,
+        parentVpPersona: vpCtx?.vpPersona || null,
+        onEvent: this.#subAgentEventSink || null,
+        language: this.#config?.language || 'en',
+      },
     };
   }
 
+  /**
+   * Set a sub-agent event sink. Called by web-bridge so every event
+   * yielded by a sub-engine gets surfaced to the frontend tagged with
+   * the parent's conversation/turn so the UI can render it inside the
+   * spawning sub-agent card.
+   *
+   * @param {(agentId: string, evt: object) => void} sink
+   */
+  setSubAgentEventSink(sink) {
+    this.#subAgentEventSink = typeof sink === 'function' ? sink : null;
+  }
+
   /**
    * Perform memory recall for a given prompt.
    * Uses recallR6 (R6 shard-based recall) when memoryShardStore is available,
@@ -1308,7 +1341,7 @@ export class Engine {
       }
 
       // Execute tool calls and feed results back
-      const toolCtx = this.#buildToolContext(signal, { router, senderVpId, inboundEnvelope, taskId, taskMembers });
+      const toolCtx = this.#buildToolContext(signal, { router, senderVpId, inboundEnvelope, taskId, taskMembers, vpPersona });
 
       // task-325a: track whether we aborted mid tool-loop so we can
       // break out of the outer while-loop cleanly once the current

package/unify/sub-agent/runner.js

@@ -0,0 +1,320 @@
+/**
+ * runner.js — Sub-agent execution driver.
+ *
+ * Lifecycle (per agent record in the global registry from `tools/agent.js`):
+ *
+ *   created → running → idle (mission turn finished, awaiting parent feedback)
+ *           ↘                ↘
+ *            failed          → running again (on SendMessage)
+ *           ↘                ↘
+ *            closed          completed (terminal — set by CloseAgent or last end_turn)
+ *
+ * Each sub-agent owns:
+ *   - its own Engine instance (shares parent adapter/trace/config/stores)
+ *   - its own ToolRegistry: parent's minus [Agent, SendMessage, WaitAgent,
+ *     CloseAgent, ListAgents, RouteForward, AskUser]
+ *   - its own messages buffer (`agent.engineMessages`) so a turn can resume
+ *     after SendMessage
+ *
+ * The runner is fire-and-forget: `startSubAgent(agent, deps)` schedules a
+ * microtask that drives the loop and returns immediately. Parents observe
+ * via `WaitAgent` (polls status) or via `deps.onEvent(agentId, evt)`
+ * which is invoked for every sub-engine event for live UI streaming.
+ *
+ * Errors are caught; the agent is marked `failed` with `error` set, and
+ * resolved through `WaitAgent` per the option-A protocol (parent decides
+ * how to react).
+ */
+
+import { Engine } from '../engine.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { buildSpawnedPreamble } from './spawned-prompt.js';
+
+const RESTRICTED_TOOLS = new Set([
+  'Agent',
+  'SendMessage',
+  'WaitAgent',
+  'CloseAgent',
+  'ListAgents',
+  'RouteForward',
+  'AskUser',
+]);
+
+/**
+ * Build a child ToolRegistry by copying every tool from the parent
+ * registry except those in RESTRICTED_TOOLS.
+ *
+ * @param {ToolRegistry|null} parentRegistry
+ * @returns {ToolRegistry}
+ */
+export function buildChildToolRegistry(parentRegistry) {
+  const child = new ToolRegistry();
+  if (!parentRegistry || typeof parentRegistry.getAllTools !== 'function') {
+    return child;
+  }
+  for (const t of parentRegistry.getAllTools()) {
+    if (RESTRICTED_TOOLS.has(t.name)) continue;
+    child.register(t);
+  }
+  return child;
+}
+
+/**
+ * Public read-only check — used by tests and callers that want to
+ * sanity-check the constraint without poking the registry.
+ */
+export function isRestrictedToolName(name) {
+  return RESTRICTED_TOOLS.has(name);
+}
+
+/**
+ * Fire-and-forget: kick off the sub-agent loop. Mutates `agent` in place
+ * (status, result, error, engineMessages, abortController).
+ *
+ * @param {object} agent — record from getAgentRegistry()
+ * @param {{
+ *   adapter: object,
+ *   trace: object,
+ *   config: object,
+ *   conversationStore?: object,
+ *   memoryStore?: object,
+ *   memoryShardStore?: object,
+ *   parentToolRegistry?: ToolRegistry,
+ *   skillManager?: object,
+ *   mcpManager?: object,
+ *   yeaftDir?: string,
+ *   parentName?: string,
+ *   parentVpId?: string,
+ *   parentVpPersona?: object,
+ *   onEvent?: (agentId: string, evt: object) => void,
+ *   language?: 'en'|'zh',
+ * }} deps
+ */
+export function startSubAgent(agent, deps = {}) {
+  if (!agent || typeof agent !== 'object') return;
+  if (agent.__driverStarted) return; // idempotent
+  agent.__driverStarted = true;
+
+  // Build sub-engine wired to the parent's adapter/stores/config but with
+  // a restricted toolset. We DO NOT pass a conversationStore: sub-agent
+  // turns must not pollute the user-facing conversation history. The
+  // memory stores are shared so memory recall still works for the
+  // sub-agent (matches parent VP persona memory).
+  const childRegistry = buildChildToolRegistry(deps.parentToolRegistry);
+  const subEngine = new Engine({
+    adapter: deps.adapter,
+    trace: deps.trace,
+    config: { ...deps.config, _readOnly: true },
+    conversationStore: null,
+    memoryStore: deps.memoryStore || null,
+    memoryShardStore: deps.memoryShardStore || null,
+    toolRegistry: childRegistry,
+    skillManager: deps.skillManager || null,
+    mcpManager: deps.mcpManager || null,
+    yeaftDir: deps.yeaftDir || null,
+  });
+
+  agent.subEngine = subEngine;
+  agent.engineMessages = agent.engineMessages || [];
+
+  // Compose the system-prompt-overlay we want injected. We piggyback on
+  // the existing `vpPersona` parameter that #buildSystemPrompt threads
+  // through to buildWorkerPrompt — appending our spawned-preamble at the
+  // end of the persona block guarantees it lands inside Layer A and is
+  // subject to the same persona caching guarantees.
+  const preamble = buildSpawnedPreamble({
+    parentName: deps.parentName || 'parent',
+    parentVpId: deps.parentVpId || null,
+    agentName: agent.name,
+    mission: agent.mission || agent.task || '',
+    language: deps.language || deps.config?.language || 'en',
+  });
+
+  const baseVpPersona =
+    deps.parentVpPersona && typeof deps.parentVpPersona === 'object'
+      ? { ...deps.parentVpPersona }
+      : {};
+  // Append the preamble onto whatever the parent persona body looked
+  // like. If the parent had no persona, we still hand the LLM a clean
+  // sub-agent identity block so it knows the scope.
+  baseVpPersona.persona =
+    [(baseVpPersona.persona || '').trim(), preamble.trim()]
+      .filter(Boolean)
+      .join('\n\n');
+  // renderVpPersona requires a displayName to emit the persona block.
+  // If the parent did not provide one, synthesize one from agent name
+  // so the spawned-preamble actually surfaces in the system prompt.
+  if (!baseVpPersona.displayName || !String(baseVpPersona.displayName).trim()) {
+    baseVpPersona.displayName = `${deps.parentName || 'Parent'}/${agent.name || 'sub-agent'}`;
+  }
+  baseVpPersona.subAgent = {
+    parentVpId: deps.parentVpId || null,
+    agentId: agent.id,
+    agentName: agent.name,
+  };
+
+  agent.subVpPersona = baseVpPersona;
+
+  // Background driver — pumps queued user messages through engine.query
+  // turn by turn until status flips to closed/completed/failed.
+  driveSubAgent(agent, subEngine, baseVpPersona, deps).catch((err) => {
+    if (agent.status === 'closed' || agent.status === 'completed') return;
+    agent.status = 'failed';
+    agent.error = err && err.message ? err.message : String(err);
+    agent.diagnostics.push({ type: 'driver_error', error: agent.error, at: Date.now() });
+    if (typeof deps.onEvent === 'function') {
+      try { deps.onEvent(agent.id, { type: 'sub_agent_status', agentId: agent.id, status: 'failed', error: agent.error }); } catch { /* ignore */ }
+    }
+  });
+}
+
+/**
+ * Drive one mission turn at a time. Each iteration:
+ *   1. Pull the next pending user message from the queue (or, on first
+ *      turn, the mission itself).
+ *   2. Run engine.query, forwarding every event to deps.onEvent (tagged
+ *      with agentId).
+ *   3. Capture the final assistant text → agent.lastResult, mark idle.
+ *   4. Wait for either a new SendMessage (status=='running' again) OR
+ *      CloseAgent (status=='closed') OR the mission to be marked
+ *      completed by parent.
+ */
+async function driveSubAgent(agent, subEngine, vpPersona, deps) {
+  const onEvent = typeof deps.onEvent === 'function' ? deps.onEvent : null;
+
+  // Helper: append a user message and either start or resume.
+  const dequeueNextUserPrompt = () => {
+    if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
+    return agent.pendingPrompts.shift() || null;
+  };
+
+  // Seed: mission becomes the first user prompt.
+  if (!agent.pendingPrompts) agent.pendingPrompts = [];
+  if (agent.mission && !agent.__missionSeeded) {
+    agent.pendingPrompts.push(agent.mission);
+    agent.__missionSeeded = true;
+  }
+
+  agent.status = 'running';
+  if (onEvent) {
+    try { onEvent(agent.id, { type: 'sub_agent_status', agentId: agent.id, agentName: agent.name, status: 'running' }); } catch { /* ignore */ }
+  }
+
+  while (agent.status !== 'closed' && agent.status !== 'completed' && agent.status !== 'failed') {
+    const prompt = dequeueNextUserPrompt();
+    if (!prompt) {
+      // Nothing to do — go idle and wait for SendMessage / CloseAgent.
+      agent.status = 'idle';
+      if (onEvent) {
+        try { onEvent(agent.id, { type: 'sub_agent_status', agentId: agent.id, status: 'idle' }); } catch { /* ignore */ }
+      }
+      await waitUntilResumed(agent);
+      // Either we have a new prompt now (back to running) or status is closed.
+      if (agent.status === 'closed') break;
+      agent.status = 'running';
+      continue;
+    }
+
+    let assistantText = '';
+    let endedNormally = false;
+    let streamError = null;
+    try {
+      const stream = subEngine.query({
+        prompt,
+        messages: agent.engineMessages,
+        signal: agent.abortController?.signal,
+        scenario: 'chat',
+        vpPersona,
+      });
+      for await (const evt of stream) {
+        // Forward every sub-engine event to the parent observer with
+        // the agent identity attached. Frontend renders these inside
+        // the sub-agent's collapsed card.
+        if (onEvent) {
+          try { onEvent(agent.id, { ...evt, agentId: agent.id, agentName: agent.name }); } catch { /* ignore listener errors */ }
+        }
+        if (evt && evt.type === 'text_delta' && typeof evt.text === 'string') {
+          assistantText += evt.text;
+        }
+        if (evt && evt.type === 'error' && evt.error) {
+          streamError = evt.error.message || String(evt.error);
+        }
+        if (evt && evt.type === 'stop') {
+          if (evt.stopReason === 'end_turn' || evt.stopReason === 'stop_sequence') {
+            endedNormally = true;
+          }
+        }
+      }
+    } catch (err) {
+      agent.status = 'failed';
+      agent.error = err && err.message ? err.message : String(err);
+      agent.diagnostics.push({ type: 'query_error', error: agent.error, at: Date.now() });
+      if (onEvent) {
+        try { onEvent(agent.id, { type: 'sub_agent_status', agentId: agent.id, status: 'failed', error: agent.error }); } catch { /* ignore */ }
+      }
+      return;
+    }
+
+    if (streamError) {
+      // Engine surfaced an error event (e.g. adapter failure) instead of
+      // throwing — treat the same as a thrown error.
+      agent.status = 'failed';
+      agent.error = streamError;
+      agent.diagnostics.push({ type: 'stream_error', error: streamError, at: Date.now() });
+      if (onEvent) {
+        try { onEvent(agent.id, { type: 'sub_agent_status', agentId: agent.id, status: 'failed', error: streamError }); } catch { /* ignore */ }
+      }
+      return;
+    }
+
+    // Persist the turn into the local message buffer so subsequent
+    // SendMessage continuations see context.
+    agent.engineMessages.push({ role: 'user', content: prompt });
+    if (assistantText) {
+      agent.engineMessages.push({ role: 'assistant', content: assistantText });
+    }
+    agent.lastResult = assistantText;
+    agent.usage.turns = (agent.usage.turns || 0) + 1;
+
+    if (!endedNormally) {
+      // Adapter aborted/errored without end_turn — mark failed.
+      agent.status = 'failed';
+      agent.error = agent.error || 'sub-agent stream ended without end_turn';
+      if (onEvent) {
+        try { onEvent(agent.id, { type: 'sub_agent_status', agentId: agent.id, status: 'failed', error: agent.error }); } catch { /* ignore */ }
+      }
+      return;
+    }
+
+    // Turn complete. Stash the result for WaitAgent and emit a turn-end
+    // event for the UI. Loop re-enters: if more pendingPrompts queued
+    // by SendMessage, run the next; else go idle.
+    agent.result = assistantText;
+    if (onEvent) {
+      try { onEvent(agent.id, { type: 'sub_agent_turn_end', agentId: agent.id, agentName: agent.name, content: assistantText }); } catch { /* ignore */ }
+    }
+  }
+}
+
+/**
+ * Resume signal — resolves when:
+ *   - a new prompt was pushed onto agent.pendingPrompts (SendMessage), OR
+ *   - the agent was closed (CloseAgent / abort)
+ *
+ * This is a tight poll because sub-agent I/O is interactive and there
+ * are at most a handful of these alive in a session.
+ */
+function waitUntilResumed(agent) {
+  return new Promise((resolve) => {
+    const tick = () => {
+      if (agent.status === 'closed' || agent.status === 'completed' || agent.status === 'failed') {
+        return resolve();
+      }
+      if (Array.isArray(agent.pendingPrompts) && agent.pendingPrompts.length > 0) {
+        return resolve();
+      }
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}

package/unify/sub-agent/spawned-prompt.js

@@ -0,0 +1,64 @@
+/**
+ * spawned-prompt.js — Build the spawned-sub-agent preamble.
+ *
+ * A sub-agent inherits its parent VP's full worker system prompt
+ * (so the persona/voice carries over) and gets ONE additional preamble
+ * block appended that tells it:
+ *   - it is a sub-agent of {parentName}
+ *   - its concrete mission (free markdown from the caller)
+ *   - it MUST NOT spawn further sub-agents, route to other VPs,
+ *     or interrupt the user (those tools are unregistered already
+ *     but the constraint is still spelled out for clarity)
+ *   - how to report back: free markdown, end_turn when mission complete
+ *
+ * This module is deliberately tiny — the heavy lifting (persona,
+ * Layer A summaries, etc.) is reused from `prompts.js` via the parent
+ * Engine's existing system-prompt build path.
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.parentName    — display name of spawning VP / Engine
+ * @param {string} args.parentVpId    — vpId if available (for traceability)
+ * @param {string} args.agentName     — sub-agent's own name (from Agent tool)
+ * @param {string} args.mission       — free markdown describing the task
+ * @param {'en'|'zh'} [args.language='en']
+ * @returns {string} preamble block (already ## headed, ready to concat)
+ */
+export function buildSpawnedPreamble({ parentName, parentVpId, agentName, mission, language = 'en' } = {}) {
+  const m = (mission || '').trim();
+  if (language === 'zh') {
+    const lines = [
+      '## 你是 sub-agent',
+      `- 派出方：${parentName || 'parent'}${parentVpId ? ` (${parentVpId})` : ''}`,
+      `- 你的名字：${agentName || 'sub-agent'}`,
+      '- 你继承了派出方的人格与风格，但你不是 ta。你只负责完成下面的子任务。',
+      '',
+      '## 你的子任务',
+      m || '(无具体任务说明)',
+      '',
+      '## 行为约束',
+      '- 不要再 spawn sub-agent（你已经没有 Agent / SendMessage / WaitAgent / CloseAgent 工具）。',
+      '- 不要 route_forward 给别的 VP，不要 ask_user。',
+      '- 完成时直接以 markdown 自由文本回复（end_turn）。建议结构："## 结果" / "## 关键发现" / "## 遗留问题"。',
+      '- 失败/不可行也要明确说出来，不要假装完成。父 VP 会读你的最终消息。',
+    ];
+    return lines.join('\n');
+  }
+  const lines = [
+    '## You are a sub-agent',
+    `- Spawned by: ${parentName || 'parent'}${parentVpId ? ` (${parentVpId})` : ''}`,
+    `- Your name: ${agentName || 'sub-agent'}`,
+    "- You inherit the spawner's persona and voice, but you are not them. You exist only to finish the sub-task below.",
+    '',
+    '## Your sub-task',
+    m || '(no mission body provided)',
+    '',
+    '## Constraints',
+    '- Do NOT spawn further sub-agents (Agent / SendMessage / WaitAgent / CloseAgent are not in your toolset).',
+    '- Do NOT use route_forward to other VPs. Do NOT ask_user.',
+    '- When done, reply in free markdown (end_turn). Suggested structure: "## Result" / "## Key findings" / "## Open questions".',
+    '- If the mission is infeasible or you fail, say so plainly. The parent will read your final message.',
+  ];
+  return lines.join('\n');
+}

package/unify/tools/agent.js

@@ -23,6 +23,7 @@
 import { defineTool } from './types.js';
 import { randomUUID } from 'crypto';
 import { getPersona, listPersonaIds } from '../personas.js';
+import { startSubAgent } from '../sub-agent/runner.js';
 
 /** In-memory sub-agent registry. */
 const agents = new Map();
@@ -273,13 +274,35 @@ Guidelines:
 
     agents.set(agentId, agent);
 
+    // PR-M1: actually spawn the sub-agent driver. This is fire-and-forget;
+    // it returns immediately. The parent observes via WaitAgent (poll) or
+    // via the engine's sub-agent event sink (live UI streaming).
+    const deps = ctx?.parentEngineDeps;
+    if (deps && deps.adapter) {
+      try {
+        startSubAgent(agent, deps);
+      } catch (err) {
+        agent.status = 'failed';
+        agent.error = err && err.message ? err.message : String(err);
+        agent.diagnostics.push({ type: 'spawn_error', error: agent.error, at: Date.now() });
+        return JSON.stringify({
+          error: `Failed to start sub-agent: ${agent.error}`,
+          agentId,
+        });
+      }
+    } else {
+      // No parent engine deps — caller is in a non-engine context (legacy
+      // tests). Leave the record in 'created' so existing tests still work.
+    }
+
     return JSON.stringify({
       success: true,
       agentId,
       name,
       persona: spec.persona || null,
       budget: spec.budget || null,
-      message: `Sub-agent "${name}" created (${agentId}). Use SendMessage to give it work.`,
+      status: agent.status,
+      message: `Sub-agent "${name}" spawned (${agentId}). Use WaitAgent to collect its first turn output, SendMessage to give it more work, CloseAgent to finish.`,
     });
   },
 });

package/unify/tools/close-agent.js

@@ -42,7 +42,15 @@ The agent's result (if any) is returned before closing.`,
       agent.result = result;
     }
 
-    const finalResult = agent.result;
+    // PR-M1: abort any in-flight engine.query so the driver loop exits
+    // promptly. This is cooperative — if the driver is mid-stream the
+    // adapter receives the signal; if it's idle, status flip ends the
+    // wait loop on the next 50ms tick.
+    if (agent.abortController && !agent.abortController.signal.aborted) {
+      try { agent.abortController.abort('closed'); } catch { /* ignore */ }
+    }
+
+    const finalResult = agent.result || agent.lastResult || '';
     agent.status = 'closed';
 
     return JSON.stringify({
@@ -51,6 +59,7 @@ The agent's result (if any) is returned before closing.`,
       name: agent.name,
       result: finalResult,
       messages: agent.messages.length,
+      turns: agent.usage?.turns || 0,
       message: `Agent "${agent.name}" closed`,
     });
   },

package/unify/tools/send-message.js

@@ -42,20 +42,31 @@ The message is queued for the agent to process.`,
     if (agent.status === 'closed') {
       return JSON.stringify({ error: `Agent "${agent.name}" is closed` });
     }
+    if (agent.status === 'failed') {
+      return JSON.stringify({ error: `Agent "${agent.name}" has failed: ${agent.error || 'unknown error'}` });
+    }
 
+    // PR-M1: queue as a pending prompt the driver will pull. This wakes
+    // the driver out of its idle wait and starts a new turn. The 'active'
+    // status alias kept for backward-compat with code that polls for it.
+    if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
+    agent.pendingPrompts.push(message);
     agent.messages.push({
       role: 'user',
       content: message,
       timestamp: Date.now(),
     });
-    agent.status = 'active';
+    if (agent.status === 'idle' || agent.status === 'created') {
+      agent.status = 'running';
+    }
 
     return JSON.stringify({
       success: true,
       agentId: agent_id,
       name: agent.name,
       messageCount: agent.messages.length,
-      message: `Message sent to agent "${agent.name}"`,
+      pending: agent.pendingPrompts.length,
+      message: `Message sent to agent "${agent.name}". Use WaitAgent to collect its reply.`,
     });
   },
 });

package/unify/tools/wait-agent.js

@@ -38,37 +38,41 @@ Use after sending a task to an agent via SendMessage.`,
       return JSON.stringify({ error: `Agent not found: ${agent_id}` });
     }
 
-    // If already completed, return result immediately
-    if (agent.status === 'completed' || agent.status === 'closed') {
+    // PR-M1: terminal states return immediately.
+    if (agent.status === 'completed' || agent.status === 'closed' || agent.status === 'failed') {
       return JSON.stringify({
         agentId: agent_id,
         name: agent.name,
         status: agent.status,
-        result: agent.result,
+        result: agent.result || agent.lastResult || '',
+        error: agent.error || null,
         messages: agent.messages.length,
+        turns: agent.usage?.turns || 0,
       });
     }
 
-    // Wait for completion with timeout
+    // PR-M1: 'idle' means the sub-agent finished its current turn and is
+    // waiting for the next SendMessage. That IS a useful return point for
+    // the parent — surface lastResult and let parent decide what's next.
     const deadline = Date.now() + timeout_ms;
     while (Date.now() < deadline) {
-      if (agent.status === 'completed' || agent.status === 'closed') {
+      if (agent.status === 'idle' || agent.status === 'completed' || agent.status === 'closed' || agent.status === 'failed') {
         return JSON.stringify({
           agentId: agent_id,
           name: agent.name,
           status: agent.status,
-          result: agent.result,
+          result: agent.result || agent.lastResult || '',
+          error: agent.error || null,
           messages: agent.messages.length,
+          turns: agent.usage?.turns || 0,
         });
       }
 
-      // Check abort signal
       if (ctx?.signal?.aborted) {
         return JSON.stringify({ error: 'Wait cancelled', agentId: agent_id });
       }
 
-      // Poll every 500ms
-      await new Promise(r => setTimeout(r, 500));
+      await new Promise(r => setTimeout(r, 200));
     }
 
     return JSON.stringify({
@@ -77,7 +81,9 @@ Use after sending a task to an agent via SendMessage.`,
       status: agent.status,
       timedOut: true,
       message: `Agent "${agent.name}" is still running after ${timeout_ms}ms`,
+      result: agent.lastResult || '',
       messages: agent.messages.length,
+      turns: agent.usage?.turns || 0,
     });
   },
 });

package/unify/vp/system-prompt.js

@@ -120,7 +120,18 @@ function buildStatic(vp, capabilitiesLine) {
     : `(no persona body for ${vp.id})`;
 
   const caps = (capabilitiesLine && capabilitiesLine.trim())
-    || 'Tools: route_forward, memory_search, memory_trace, task_summary_post (if initiator).';
+    || [
+      'Tools: route_forward, memory_search, memory_trace, task_summary_post (if initiator).',
+      'Sub-agent fan-out: when a single user task is large enough to benefit from parallel execution,',
+      'you MAY spawn sub-agents using the `Agent` tool. Each sub-agent inherits your persona +',
+      'voice, gets its own ToolRegistry (without Agent / RouteForward / AskUser to prevent recursion),',
+      'and runs the same Engine flow. Use `Agent` to spawn (returns agentId), `WaitAgent` to collect',
+      'each turn output, `SendMessage` for follow-ups, `CloseAgent` when done. You can fire multiple',
+      '`Agent` tool_calls in one assistant turn to launch them in parallel. Pass a self-contained,',
+      'markdown mission ("## Goal / ## Context / ## Deliverable / ## Constraints") — the sub-agent',
+      'cannot see your conversation history. Only spawn when work is genuinely parallelisable; for',
+      'small or strictly-sequential tasks, do it yourself.',
+    ].join('\n');
 
   // personaHash travels in the static block so downstream (334h live-diff)
   // can detect changes without re-hashing.

package/unify/web-bridge.js

@@ -1402,6 +1402,22 @@ export async function handleUnifyChat(msg) {
       // code — the config file was updated on disk but the running
       // session continued with the old caps until next restart.
       installUnifyRuntimeBridge(session);
+
+      // PR-M1: install a sub-agent event sink so events emitted by sub-
+      // agent Engines surface to the web client. Frontend filters by the
+      // `agentId` field and renders them inside the sub-agent card.
+      try {
+        if (session.engine && typeof session.engine.setSubAgentEventSink === 'function') {
+          session.engine.setSubAgentEventSink((agentId, evt) => {
+            try {
+              sendUnifyEvent({ type: 'sub_agent_event', agentId, payload: evt });
+            } catch { /* ignore */ }
+          });
+        }
+      } catch (err) {
+        console.warn('[Unify] setSubAgentEventSink wiring failed:', err?.message || err);
+      }
+
       // task-317: run one idle-archive sweep at bootstrap, then schedule
       // the hourly tick bound to this session.
       runAutoArchiveSweep(session);