@yeaft/webchat-agent 0.1.929 → 0.1.931

package/history.js

@@ -1,5 +1,5 @@
 import { homedir } from 'os';
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync, fstatSync } from 'fs';
 import { join } from 'path';
 import ctx from './context.js';
 import { getProvider, DEFAULT_PROVIDER } from './providers/index.js';
@@ -146,6 +146,116 @@ export async function getHistorySessions(workDir) {
   return sessions;
 }
 
+// feat-chat-load-perf: tail-read helper used by loadSessionHistory.
+// Reads the last `limit` user/assistant rows from a JSONL without slurping
+// the whole file. Strategy: open the file, fstat to get size, then read
+// fixed-size chunks from the end backwards into a Buffer. We split on the
+// `\n` *byte* (0x0A) — NOT on a decoded string — because Buffer→string
+// substitutes U+FFFD for any partial multi-byte sequence at chunk
+// boundaries, and that corruption is undetectable downstream (JSON.parse
+// happily accepts U+FFFD as valid string content). Splitting on the
+// newline byte and carrying raw bytes between iterations means every
+// complete line is decoded as a whole and the agent never feeds the LLM
+// mangled history. A 42 MB / 100k-message JSONL with limit=500 reads
+// roughly 1–4 MB instead of the entire file.
+//
+// Tradeoffs:
+// - Falls back to full readFileSync if anything throws (defensive — a 200ms
+//   slow path beats a broken history load).
+// - The TAIL_CHUNK_SIZE constant (256 KB) is sized so a single chunk almost
+//   always contains many complete lines from Claude CLI's per-message
+//   write pattern.
+// - The carry Buffer is capped at TAIL_MAX_CARRY_BYTES — a pathological
+//   JSONL line longer than that triggers the fallback path rather than
+//   letting the agent OOM.
+const TAIL_CHUNK_SIZE = 256 * 1024; // 256 KB
+const TAIL_MAX_CARRY_BYTES = 4 * 1024 * 1024; // 4 MB — safety valve, see above
+const NEWLINE_BYTE = 0x0a;
+
+// Exported for tests so the UTF-8-boundary regression can splice a
+// multi-byte character exactly at the chunk seam.
+export const _TAIL_CHUNK_SIZE_FOR_TESTS = TAIL_CHUNK_SIZE;
+
+function readTailMessages(filePath, limit) {
+  const fd = openSync(filePath, 'r');
+  try {
+    const { size } = fstatSync(fd);
+    if (size === 0) return [];
+
+    const collected = []; // newest-first while we build it; reverse before return
+    let carry = Buffer.alloc(0); // raw-byte tail from the previous (deeper-into-file) chunk
+    let position = size;
+    const chunkBuf = Buffer.alloc(TAIL_CHUNK_SIZE);
+
+    while (position > 0 && collected.length < limit) {
+      const readSize = Math.min(TAIL_CHUNK_SIZE, position);
+      const offset = position - readSize;
+      readSync(fd, chunkBuf, 0, readSize, offset);
+      position = offset;
+      const atHead = position === 0;
+
+      // Concatenate raw bytes — never decode partials, never split UTF-8.
+      const buf = Buffer.concat([chunkBuf.slice(0, readSize), carry]);
+
+      // If we're not yet at the head of the file, the first segment up to
+      // (but not including) the first newline is a potentially-partial
+      // line — stash its bytes for the next iteration. If there's no
+      // newline at all, the whole chunk is one partial line and we carry
+      // it forward.
+      let tailStart = 0;
+      if (!atHead) {
+        const firstNl = buf.indexOf(NEWLINE_BYTE);
+        if (firstNl === -1) {
+          if (buf.length > TAIL_MAX_CARRY_BYTES) {
+            // Refuse to grow the carry unbounded — propagate to fallback.
+            throw new Error(`tail-read carry exceeded ${TAIL_MAX_CARRY_BYTES} bytes`);
+          }
+          carry = buf;
+          continue;
+        }
+        carry = buf.slice(0, firstNl);
+        tailStart = firstNl + 1;
+      }
+
+      // Everything from tailStart to end is complete UTF-8 lines — decode
+      // safely as one block.
+      const text = buf.slice(tailStart).toString('utf-8');
+      const lines = text.split('\n');
+
+      // Walk lines newest-first (end to start).
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line || !line.trim()) continue;
+        try {
+          const data = JSON.parse(line);
+          if (data.type === 'user' || data.type === 'assistant') {
+            collected.push(data);
+            if (collected.length >= limit) break;
+          }
+        } catch {}
+      }
+    }
+
+    // If we ran out of file with leftover carry, try it as the head line.
+    if (collected.length < limit && carry.length > 0) {
+      const headLine = carry.toString('utf-8').trim();
+      if (headLine) {
+        try {
+          const data = JSON.parse(headLine);
+          if (data.type === 'user' || data.type === 'assistant') {
+            collected.push(data);
+          }
+        } catch {}
+      }
+    }
+
+    // collected is newest-first; flip to chronological order for callers.
+    return collected.reverse();
+  } finally {
+    closeSync(fd);
+  }
+}
+
 // 读取 session 文件中的历史消息
 export function loadSessionHistory(workDir, claudeSessionId, limit = 500) {
   const projectsDir = getClaudeProjectsDir();
@@ -159,6 +269,17 @@ export function loadSessionHistory(workDir, claudeSessionId, limit = 500) {
     return [];
   }
 
+  // Fast path: tail-read only the last `limit` user/assistant rows. Avoids
+  // slurping ~42 MB into memory + ~100k JSON.parse calls when we only need
+  // the last 500 entries on every chat resume.
+  if (limit && limit > 0) {
+    try {
+      return readTailMessages(sessionFile, limit);
+    } catch (e) {
+      console.error(`Tail-read failed (${e.message}), falling back to full read for: ${sessionFile}`);
+    }
+  }
+
   const messages = [];
   try {
     const content = readFileSync(sessionFile, 'utf-8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.929",
+  "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,