@yeaft/webchat-agent 0.1.930 → 0.1.932

package/package.json

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

package/yeaft/dream/output-snapshot.js

@@ -0,0 +1,59 @@
+/**
+ * dream/output-snapshot.js.
+ *
+ * Read-only projection of Dream-owned output files for UI observability.
+ * The Dream write path remains `runner -> apply -> memory/store`; callers use
+ * this module to load the current `memory.md` / `summary.md` contents for a
+ * single Yeaft session when emitting status or restoring a switched session.
+ */
+
+import { join } from 'node:path';
+
+import { readMemory, readSummary } from '../memory/store.js';
+import { readGroupState } from './state.js';
+
+export const DREAM_SNAPSHOT_TEXT_LIMIT = 6000;
+
+export function truncateDreamText(value, limit = DREAM_SNAPSHOT_TEXT_LIMIT) {
+  const text = typeof value === 'string' ? value : '';
+  if (text.length <= limit) return { text, truncated: false };
+  return { text: text.slice(0, limit), truncated: true };
+}
+
+/**
+ * Build the loadable Dream output for one Yeaft session.
+ *
+ * @param {{ yeaftDir?: string|null }} sessionLike
+ * @param {string} sessionId
+ * @returns {Promise<object|null>}
+ */
+export async function buildDreamOutputSnapshot(sessionLike, sessionId) {
+  if (!sessionId || !sessionLike?.yeaftDir) return null;
+  const scope = `group/${sessionId}`;
+  const memoryScope = { kind: 'group', id: sessionId };
+  const root = join(sessionLike.yeaftDir, 'memory');
+  const [memoryRaw, summaryRaw, state] = await Promise.all([
+    readMemory(memoryScope, { root }).catch(() => ''),
+    readSummary(memoryScope, { root }).catch(() => ''),
+    readGroupState(root, sessionId).catch(() => ({
+      lastDreamMessageId: null,
+      lastDreamAt: null,
+      messageCount: 0,
+    })),
+  ]);
+  const memory = truncateDreamText(memoryRaw);
+  const summary = truncateDreamText(summaryRaw);
+  return {
+    scope,
+    sessionId,
+    loadedAt: new Date().toISOString(),
+    lastDreamAt: state?.lastDreamAt || null,
+    lastDreamMessageId: state?.lastDreamMessageId || null,
+    messageCount: Number.isFinite(state?.messageCount) ? state.messageCount : 0,
+    hasOutput: !!(memoryRaw || summaryRaw),
+    memoryText: memory.text,
+    memoryTruncated: memory.truncated,
+    summaryText: summary.text,
+    summaryTruncated: summary.truncated,
+  };
+}

package/yeaft/dream/session-wiring.js

@@ -338,7 +338,7 @@ export function createV2DreamScheduler(session) {
       ...buildRunDreamOpts(session, onProgress),
       manual: !!opts.manual,
       scopeFilter: Array.isArray(opts.scopeFilter) ? opts.scopeFilter : undefined,
-    }).then((result) => {
+    }).then(async (result) => {
       // Bug 2: emit turn_close when the dream pass completes.
       result.trigger = opts.manual ? 'manual' : 'auto';
       if (session._dreamActiveGroupId && !result.sessionId) result.sessionId = session._dreamActiveGroupId;
@@ -370,6 +370,11 @@ export function createV2DreamScheduler(session) {
       if (typeof session._dreamProgressSink === 'function') {
         session._dreamProgressSink(turnClose);
       }
+      if (typeof session._dreamResultSink === 'function') {
+        try {
+          await session._dreamResultSink(result);
+        } catch { /* dream result visibility must never fail the scheduler */ }
+      }
       return result;
     });
   };

package/yeaft/tools/agent.js

@@ -191,7 +191,19 @@ Guidelines:
 - Give a clear, focused mission — what "done" looks like
 - Use expected_output when the return shape matters
 - Add a budget only when you need an explicit safety cutoff
-- Use PromptAgent to communicate, WaitAgent to collect results, CloseAgent to finalize`,
+
+Orchestration loop you MUST follow:
+  1. SpawnAgent     — fire-and-forget; the sub-agent is now running.
+  2. WaitAgent      — blocks until the sub-agent goes idle / completes /
+                      fails / closes (or times out). Returns the reply.
+  3. PromptAgent    — optional: queue a follow-up; then WaitAgent again.
+  4. CloseAgent     — finalize when done.
+  5. Reply to user  — relay what the sub-agent found in your own words.
+
+CRITICAL — SpawnAgent only KICKS OFF the sub-agent. It has NOT produced any
+result yet. You MUST call WaitAgent next to collect the reply. Do NOT end your
+turn right after SpawnAgent without calling WaitAgent or telling the user what
+you just kicked off.`,
   parameters: {
     type: 'object',
     properties: {
@@ -235,8 +247,19 @@ Guidelines:
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
   async execute(input, ctx) {
+    // NB: every envelope below puts `next_steps` (or `error_next_steps`) at
+    // the FIRST position because `agent/yeaft/tools/registry.js` caps tool
+    // output at 1 KiB by chopping the tail. Tail-positioned nudges get
+    // truncated when the rest of the envelope is large.
+    const ERROR_NEXT_STEPS =
+      'That call failed — see `error`. Either correct the arguments and ' +
+      'retry, or tell the user what went wrong. Do NOT end your turn ' +
+      'silently after an error envelope.';
+
     const validation = validateSpec(input);
-    if (!validation.ok) return JSON.stringify({ error: validation.error });
+    if (!validation.ok) {
+      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: validation.error });
+    }
     const spec = validation.spec;
     const { name, cwd } = input;
 
@@ -244,6 +267,7 @@ Guidelines:
     for (const [, agent] of agents) {
       if (agent.name === name && agent.status !== 'closed') {
         return JSON.stringify({
+          next_steps: ERROR_NEXT_STEPS,
           error: `Agent "${name}" already exists. Close it first or use a different name.`,
           agentId: agent.id,
         });
@@ -288,6 +312,7 @@ Guidelines:
         agent.error = err && err.message ? err.message : String(err);
         agent.diagnostics.push({ type: 'spawn_error', error: agent.error, at: Date.now() });
         return JSON.stringify({
+          next_steps: ERROR_NEXT_STEPS,
           error: `Failed to start sub-agent: ${agent.error}`,
           agentId,
         });
@@ -298,6 +323,10 @@ Guidelines:
     }
 
     return JSON.stringify({
+      next_steps:
+        'Sub-agent is now running — no reply yet. Call WaitAgent next to ' +
+        'collect its first turn. Do NOT end your turn here without either ' +
+        'waiting for the reply or telling the user what you just spawned.',
       success: true,
       agentId,
       name,

package/yeaft/tools/close-agent.js

@@ -10,7 +10,12 @@ export default defineTool({
   description: `Close a sub-agent and release its resources.
 
 Use when a sub-agent's task is complete or no longer needed.
-The agent's result (if any) is returned before closing.`,
+The agent's final \`result\` (if any) is returned in the envelope before closing.
+
+CRITICAL — closing the sub-agent is NOT the end of YOUR turn. After CloseAgent
+you MUST relay the \`result\` to the user in your own reply (or summarize what
+was accomplished). The user has not seen the sub-agent's reply — only you have.
+Do NOT end your turn silently right after CloseAgent.`,
   parameters: {
     type: 'object',
     properties: {
@@ -28,14 +33,21 @@ The agent's result (if any) is returned before closing.`,
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
   async execute(input, ctx) {
+    // NB: next_steps is the FIRST envelope field — the registry's 1 KiB
+    // tail-truncation would eat it if it lived at the end.
+    const ERROR_NEXT_STEPS =
+      'That call failed — see `error`. Either correct the arguments and ' +
+      'retry, or tell the user what went wrong. Do NOT end your turn ' +
+      'silently after an error envelope.';
+
     const { agent_id, result } = input;
-    if (!agent_id) return JSON.stringify({ error: 'agent_id is required' });
+    if (!agent_id) return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: 'agent_id is required' });
 
     const agents = getAgentRegistry();
     const agent = agents.get(agent_id);
 
     if (!agent) {
-      return JSON.stringify({ error: `Agent not found: ${agent_id}` });
+      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent not found: ${agent_id}` });
     }
 
     if (result) {
@@ -54,6 +66,10 @@ The agent's result (if any) is returned before closing.`,
     agent.status = 'closed';
 
     return JSON.stringify({
+      next_steps:
+        'Sub-agent is closed. Now reply to the user — summarize what was ' +
+        'accomplished and surface the `result` text. Do NOT end your turn ' +
+        'without telling the user what happened.',
       success: true,
       agentId: agent_id,
       name: agent.name,

package/yeaft/tools/send-message.js

@@ -14,7 +14,14 @@ export default defineTool({
   description: `Send a follow-up prompt to a sub-agent you previously spawned.
 
 Use this to give the sub-agent more work, additional instructions, or relay
-information. The prompt is queued for the agent to process on its next turn.`,
+information. The prompt is queued for the agent to process on its next turn.
+
+IMPORTANT — PromptAgent only QUEUES the message; it does NOT block. After this
+returns you almost always want to call WaitAgent next to collect the reply.
+Do NOT end your turn after PromptAgent without either (a) calling WaitAgent,
+(b) explaining to the user what you just asked the sub-agent, or (c) calling
+CloseAgent. The orchestration loop is
+SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.`,
   parameters: {
     type: 'object',
     properties: {
@@ -32,22 +39,29 @@ information. The prompt is queued for the agent to process on its next turn.`,
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
   async execute(input, ctx) {
+    // NB: next_steps is the FIRST envelope field — the registry's 1 KiB
+    // tail-truncation would eat it if it lived at the end.
+    const ERROR_NEXT_STEPS =
+      'That call failed — see `error`. Either correct the arguments and ' +
+      'retry, or tell the user what went wrong. Do NOT end your turn ' +
+      'silently after an error envelope.';
+
     const { agent_id, message } = input;
-    if (!agent_id) return JSON.stringify({ error: 'agent_id is required' });
-    if (!message) return JSON.stringify({ error: 'message is required' });
+    if (!agent_id) return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: 'agent_id is required' });
+    if (!message) return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: 'message is required' });
 
     const agents = getAgentRegistry();
     const agent = agents.get(agent_id);
 
     if (!agent) {
-      return JSON.stringify({ error: `Agent not found: ${agent_id}` });
+      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent not found: ${agent_id}` });
     }
 
     if (agent.status === 'closed') {
-      return JSON.stringify({ error: `Agent "${agent.name}" is closed` });
+      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent "${agent.name}" is closed` });
     }
     if (agent.status === 'failed') {
-      return JSON.stringify({ error: `Agent "${agent.name}" has failed: ${agent.error || 'unknown error'}` });
+      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent "${agent.name}" has failed: ${agent.error || 'unknown error'}` });
     }
 
     // PR-M1: queue as a pending prompt the driver will pull. This wakes
@@ -65,6 +79,11 @@ information. The prompt is queued for the agent to process on its next turn.`,
     }
 
     return JSON.stringify({
+      next_steps:
+        'Message is queued — the sub-agent has NOT replied yet. Call WaitAgent ' +
+        'next to collect the reply, then relay it to the user. Do NOT end your ' +
+        'turn here without either waiting for the reply or telling the user ' +
+        'what you just asked.',
       success: true,
       agentId: agent_id,
       name: agent.name,

package/yeaft/tools/wait-agent.js

@@ -1,16 +1,114 @@
 /**
  * wait-agent.js — Wait for a sub-agent to complete and get its result.
+ *
+ * Loop-stall fix (2026-06-11):
+ *
+ * Symptom — when the LLM called WaitAgent inside a sub-agent orchestration,
+ * the assistant turn ended silently right after the tool returned. The user
+ * saw a stuck "tool ran" panel and no follow-up text or further tool calls.
+ *
+ * Cause — the engine loop is correct (it appends the tool result and re-enters
+ * `adapter.stream()`), but the LLM was reading the bare JSON envelope (status +
+ * result + turns…) as a "complete answer" and emitting `end_turn` with no
+ * text. The previous description ("Returns the agent's final result or current
+ * status") gave it zero guidance about what to do next.
+ *
+ * Fix — every WaitAgent response now carries an explicit, status-dependent
+ * `next_steps` field that names the exact tool to call next, and the tool
+ * description spells out the full SpawnAgent → PromptAgent → WaitAgent →
+ * CloseAgent loop. The same nudge pattern lives on the companion tools.
  */
 
 import { defineTool } from './types.js';
 import { getAgentRegistry } from './agent.js';
 
+/**
+ * Build the status-specific next-step guidance the LLM reads after a wait.
+ *
+ * The wording is imperative and names actual tools so the model has a clear
+ * action to take — leaving it implicit was the bug.
+ *
+ * @param {string} status
+ * @param {boolean} [timedOut]
+ */
+function nextStepsFor(status, timedOut = false) {
+  if (timedOut) {
+    return (
+      'Sub-agent is still running. Either (a) call WaitAgent again with a ' +
+      'larger timeout_ms to keep waiting, (b) call CloseAgent if you want to ' +
+      'cut it short and use partial output, or (c) explain to the user that ' +
+      'the agent is still working and ask whether to keep waiting. Do NOT ' +
+      'end your turn silently.'
+    );
+  }
+  switch (status) {
+    case 'idle':
+      return (
+        'Sub-agent finished one turn and is idle. The `result` above is its ' +
+        'reply — relay it to the user in your own words, or send a follow-up ' +
+        'via PromptAgent, or finalize via CloseAgent. Do NOT end your turn ' +
+        'silently without telling the user what the sub-agent said.'
+      );
+    case 'completed':
+      return (
+        'Sub-agent finished successfully (terminal). Summarize the `result` ' +
+        'for the user in your own reply. Do NOT end your turn with no text.'
+      );
+    case 'closed':
+      return (
+        'Sub-agent was closed (terminal). Report the final `result` to the ' +
+        'user in your reply. Do NOT end your turn silently.'
+      );
+    case 'failed':
+      return (
+        'Sub-agent failed — see `error`. Decide whether to retry with a fresh ' +
+        'SpawnAgent, adjust the mission, or report the failure to the user. ' +
+        'Do NOT end your turn silently.'
+      );
+    default:
+      return (
+        'Decide what to do next: PromptAgent to send follow-up work, ' +
+        'CloseAgent to finalize, or WaitAgent again. Always tell the user ' +
+        'what just happened — do NOT end your turn silently.'
+      );
+  }
+}
+
+/**
+ * Nudge for the `{error: ...}` error envelopes. The error path used to ship a
+ * naked `{error}` blob — same shape that caused the silent-end_turn bug on the
+ * happy path. Tell the LLM what to do about an error (correct the call, or
+ * report the failure to the user) so it does not end its turn silently after a
+ * fat-finger like a wrong agent_id.
+ */
+function errorNextSteps() {
+  return (
+    'That call failed — see `error`. Either correct the arguments and retry, ' +
+    'or tell the user what went wrong. Do NOT end your turn silently after an ' +
+    'error envelope; the user has not seen the error, only you have.'
+  );
+}
+
 export default defineTool({
   name: 'WaitAgent',
-  description: `Wait for a sub-agent to complete its task and retrieve the result.
+  description: `Wait for a sub-agent to complete its current turn and retrieve its reply.
+
+Returns a JSON envelope with the sub-agent's status, latest \`result\` text, and
+an explicit \`next_steps\` field telling you what to do next. Read \`next_steps\`
+every time — the wait is part of an orchestration loop, not a terminal answer.
 
-Returns the agent's final result or current status if still running.
-Use after sending a task to an agent via PromptAgent.
+CRITICAL — after WaitAgent returns you MUST take one of these actions:
+  • status='idle' / 'completed' / 'closed': RELAY the \`result\` to the user
+    in your own words (or send follow-up work via PromptAgent, or finalize
+    via CloseAgent).
+  • status='failed': report the failure to the user OR retry with a fresh
+    SpawnAgent.
+  • timedOut=true: call WaitAgent again with a larger timeout, OR CloseAgent
+    to cut it short, OR tell the user the agent is still working.
+
+NEVER end your turn silently right after WaitAgent — the user has not seen the
+sub-agent's reply yet; only you have. The orchestration loop is
+SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.
 
 The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
   parameters: {
@@ -34,21 +132,29 @@ The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
   isReadOnly: () => true,
   async execute(input, ctx) {
     const { agent_id, timeout_ms = 30000 } = input;
-    if (!agent_id) return JSON.stringify({ error: 'agent_id is required' });
+    // NB: `next_steps` is intentionally the FIRST field in every envelope
+    // below. `agent/yeaft/tools/registry.js` caps each tool result at
+    // TOOL_RESULT_MAX_BYTES (1 KiB) by truncating the tail — if `next_steps`
+    // were last, a long `result` would push the directive off the end and the
+    // LLM would never see the very nudge this PR delivers.
+    if (!agent_id) {
+      return JSON.stringify({ next_steps: errorNextSteps(), error: 'agent_id is required' });
+    }
     if (typeof timeout_ms !== 'number' || !Number.isFinite(timeout_ms) || timeout_ms < 0 || timeout_ms > 300000) {
-      return JSON.stringify({ error: 'timeout_ms must be a number between 0 and 300000' });
+      return JSON.stringify({ next_steps: errorNextSteps(), error: 'timeout_ms must be a number between 0 and 300000' });
     }
 
     const agents = getAgentRegistry();
     const agent = agents.get(agent_id);
 
     if (!agent) {
-      return JSON.stringify({ error: `Agent not found: ${agent_id}` });
+      return JSON.stringify({ next_steps: errorNextSteps(), error: `Agent not found: ${agent_id}` });
     }
 
-    // PR-M1: terminal states return immediately.
+    // Terminal states return immediately.
     if (agent.status === 'completed' || agent.status === 'closed' || agent.status === 'failed') {
       return JSON.stringify({
+        next_steps: nextStepsFor(agent.status),
         agentId: agent_id,
         name: agent.name,
         status: agent.status,
@@ -59,13 +165,14 @@ The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
       });
     }
 
-    // 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.
+    // '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 === 'idle' || agent.status === 'completed' || agent.status === 'closed' || agent.status === 'failed') {
         return JSON.stringify({
+          next_steps: nextStepsFor(agent.status),
           agentId: agent_id,
           name: agent.name,
           status: agent.status,
@@ -77,13 +184,14 @@ The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
       }
 
       if (ctx?.signal?.aborted) {
-        return JSON.stringify({ error: 'Wait cancelled', agentId: agent_id });
+        return JSON.stringify({ next_steps: errorNextSteps(), error: 'Wait cancelled', agentId: agent_id });
       }
 
       await new Promise(r => setTimeout(r, 200));
     }
 
     return JSON.stringify({
+      next_steps: nextStepsFor(agent.status, true),
       agentId: agent_id,
       name: agent.name,
       status: agent.status,

package/yeaft/web-bridge.js

@@ -21,6 +21,7 @@
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
+import { buildDreamOutputSnapshot } from './dream/output-snapshot.js';
 import { Engine } from './engine.js';
 import { loadSession } from './session.js';
 import { loadConfig } from './config.js';
@@ -112,6 +113,14 @@ export function __testSetThreadClassifier(fn) {
  */
 const inflightScopedDreamGroups = new Set();
 
+async function sendDreamSnapshotForSession(sessionId, extra = {}) {
+  const snapshot = await buildDreamOutputSnapshot(session, sessionId);
+  if (!snapshot) return null;
+  sendYeaftEvent({ type: 'yeaft_dream_snapshot', ...extra, snapshot }, { sessionId });
+  return snapshot;
+}
+
+
 /**
  * Single in-flight AbortController for legacy 1:1 chat. A new 1:1 user message
  * cancels the prior round (if any).
@@ -1865,6 +1874,30 @@ export function installYeaftRuntimeBridge(s) {
     } catch { /* never let event delivery throw */ }
   };
 
+  // Auto dream runs are triggered by the scheduler / nudges, not by the
+  // manual `handleYeaftDreamTrigger` path. Without this terminal sink the UI
+  // only saw progress debug events and could not restore the final dream
+  // output after switching sessions. Manual runs keep using their explicit
+  // handler below to avoid duplicate terminal events.
+  s._dreamResultSink = async (result = {}) => {
+    if (result?.trigger !== 'auto') return;
+    const normalized = normalizeDreamResult(result);
+    const processed = Array.isArray(result.groups)
+      ? result.groups.filter(g => g && g.status === 'processed' && g.sessionId)
+      : [];
+    for (const group of processed) {
+      const sessionId = group.sessionId;
+      const snapshot = await buildDreamOutputSnapshot(session, sessionId).catch(() => null);
+      sendToServer({
+        type: 'yeaft_dream_result',
+        sessionId,
+        ...result,
+        ...normalized,
+        snapshot,
+      });
+    }
+  };
+
   // Wire the post-compact WS sink. Compactor is constructed in
   // session.js with a no-op sink; bridge owns `sendYeaftEvent` /
   // `yeaftConversationId`, so the sink is wired here once a session is
@@ -3594,6 +3627,9 @@ export async function handleYeaftDreamTrigger(msg = {}) {
       : await session.dreamScheduler.triggerDreamNow();
 
     const normalized = normalizeDreamResult(result);
+    const snapshot = sessionId
+      ? await buildDreamOutputSnapshot(session, sessionId).catch(() => null)
+      : null;
 
     // Spread `result` FIRST so normalized fields (success, skipped,
     // skippedReason, groupsProcessed, groupsSkipped, targetsApplied,
@@ -3616,6 +3652,7 @@ export async function handleYeaftDreamTrigger(msg = {}) {
       ...tag,
       ...result,
       ...normalized,
+      ...(snapshot ? { snapshot } : {}),
     });
   } catch (err) {
     const error = err?.message || String(err);
@@ -3829,6 +3866,9 @@ export async function handleYeaftLoadHistory(msg) {
     yeaftDir: ctx.CONFIG?.yeaftDir || null,
   });
   sendSessionSnapshotBroadcast();
+  if (sessionId) {
+    await sendDreamSnapshotForSession(sessionId, { trigger: 'load_history' }).catch(() => null);
+  }
   // vp-status: replay the authoritative table on reconnect so a refreshed
   // frontend doesn't have to wait for the next transition to learn each
   // VP's current state.