@yeaft/webchat-agent 0.1.930 → 0.1.931

package/package.json

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

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,