@yeaft/webchat-agent 0.1.973 → 0.1.974

package/package.json

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

package/yeaft/sub-agent/liveness.js

@@ -99,3 +99,37 @@ export function snapshotLiveness(liveness, now = Date.now()) {
     recentTools: liveness.recentTools.slice(),
   };
 }
+
+export const DEFAULT_STALL_THRESHOLD_MS = 120000;
+
+/**
+ * Add a stable "is this likely stuck?" diagnostic to a liveness snapshot.
+ * If no event has ever arrived, fall back to createdAt / usage.startedAt so
+ * a silent running child can still become stale.
+ *
+ * @param {object} agent
+ * @param {{ now?: number, thresholdMs?: number }} [opts]
+ */
+export function diagnoseAgentLiveness(agent, opts = {}) {
+  const now = typeof opts.now === 'number' ? opts.now : Date.now();
+  const thresholdMs = typeof opts.thresholdMs === 'number' && opts.thresholdMs > 0
+    ? opts.thresholdMs
+    : DEFAULT_STALL_THRESHOLD_MS;
+  const liveness = snapshotLiveness(agent?.liveness, now);
+  const fallbackAt = agent?.createdAt || agent?.usage?.startedAt || null;
+  const activityAt = liveness.lastEventAt || fallbackAt;
+  const msSinceActivity = activityAt ? Math.max(0, now - activityAt) : null;
+  const stale = agent?.status === 'running'
+    && msSinceActivity !== null
+    && msSinceActivity >= thresholdMs;
+  return {
+    ...liveness,
+    msSinceLastEvent: liveness.msSinceLastEvent ?? msSinceActivity,
+    stale,
+    stalled: stale,
+    stallThresholdMs: thresholdMs,
+    diagnostic: stale
+      ? `No sub-agent activity for ${msSinceActivity}ms; treat it as stalled instead of waiting in a loop.`
+      : null,
+  };
+}

package/yeaft/sub-agent/notifications.js

@@ -4,11 +4,12 @@
  * Problem this solves:
  *   The original sub-agent protocol was purely pull-based — the parent had
  *   to keep calling WaitAgent to discover that its child had finished. If
- *   the parent forgot, the child's terminal state was never surfaced and
- *   the orchestration "hung" from the user's perspective. Modeled on
- *   claude-code's `<task-notification>` XML re-entry pattern: when a
- *   child reaches a terminal state we *push* a notification onto a queue
- *   that the parent will see the next time it talks to its engine.
+ *   the parent forgot, the child's progress or terminal state was never
+ *   surfaced and the orchestration "hung" from the user's perspective.
+ *   Modeled on claude-code's `<task-notification>` XML re-entry pattern:
+ *   when a child finishes a turn or reaches a terminal state we *push* a
+ *   notification onto a queue that the parent will see the next time it
+ *   talks to its engine.
  *
  *   This module is the queue. Two entry points consume it:
  *
@@ -16,11 +17,11 @@
  *        before returning).
  *     2. Engine.query() — when started with a user prompt, it asks
  *        `consumePendingNotifications({ sessionId, parentVpId })` for any queued
- *        terminal events from sub-agents that the parent hasn't yet
+ *        idle/terminal events from sub-agents that the parent hasn't yet
  *        acknowledged, and prepends a short XML block to the user
  *        message. The XML block is human-readable for the model and
- *        explicitly tells it "your sub-agent X finished while you were
- *        away; here's the result and what to do next".
+ *        explicitly tells it "your sub-agent X produced progress while you
+ *        were away; here's the result and what to do next".
  *
  *   The queue is in-memory only. We do NOT persist across process
  *   restarts because (a) sub-agents themselves don't survive restart,
@@ -75,9 +76,9 @@ function bucketKey(scope, sessionId) {
 }
 
 /**
- * Enqueue a terminal notification for an agent. Idempotent per agent —
- * a second call with the same agentId is a no-op (we only emit one
- * terminal notice per child).
+ * Enqueue a progress/terminal notification for an agent. Idempotent per
+ * agent while queued — a second call with the same agentId is a no-op
+ * until the previous notice is replaced or consumed.
  *
  * @param {{ agentId: string, agentName: string, status: string, result?: string, error?: string|null, outputFile?: string|null, turns?: number, parentVpId?: string|null, parentSessionId?: string|null, sessionId?: string|null, budgetExceeded?: boolean, budgetReason?: string|null, budgetUsage?: object|null }} input
  * @returns {SubAgentNotification|null} the queued record (null if a dup)
@@ -210,10 +211,10 @@ export function formatNotificationsForPrompt(notifs) {
   const parts = [];
   parts.push('<sub-agent-notifications>');
   parts.push(
-    'The following sub-agent(s) reached a terminal state while you were ' +
-    'away. The user has NOT seen any of this — only you have. You MUST ' +
-    'either (a) relay the result(s) to the user in your reply, or (b) act ' +
-    'on the result(s) before replying. Do NOT ignore these.',
+    'The following sub-agent(s) produced progress or reached a terminal ' +
+    'state while you were away. The user has NOT seen any of this — only ' +
+    'you have. You MUST either (a) relay the result(s) to the user in your ' +
+    'reply, or (b) act on the result(s) before replying. Do NOT ignore these.',
   );
   for (const n of notifs) {
     parts.push('');

package/yeaft/sub-agent/runner.js

@@ -41,7 +41,7 @@ import { buildSpawnedPreamble } from './spawned-prompt.js';
 import { STATUS, isTerminalAgentStatus } from './status.js';
 import { createOutputLog } from './output-log.js';
 import { makeLiveness, bumpLivenessFromEvent } from './liveness.js';
-import { enqueueTerminalNotification } from './notifications.js';
+import { consumeNotificationForAgent, enqueueTerminalNotification } from './notifications.js';
 // NOTE: tickAgent lives in `../tools/agent.js`, which itself imports this
 // module (startSubAgent). To avoid the ES-module circular-import gotcha
 // where one side sees an undefined export at module-init time, we import
@@ -223,8 +223,43 @@ export function startSubAgent(agent, deps = {}) {
  *      CloseAgent (status=='closed') OR the idle watchdog firing
  *      (status=='abandoned').
  */
+function buildWallTimeBudgetResult(agent, reason) {
+  return {
+    status: 'budget_exceeded',
+    partial_output: agent.partial_output || agent.lastResult || agent.result || '',
+    reason,
+    usage: { ...(agent.usage || {}) },
+  };
+}
+
+function armWallTimeWatchdog(agent, deps) {
+  const wallTimeMs = agent?.budget?.wall_time_ms;
+  if (typeof wallTimeMs !== 'number' || !Number.isFinite(wallTimeMs) || wallTimeMs <= 0) {
+    return null;
+  }
+  const startedAt = agent.usage?.startedAt || Date.now();
+  const remainingMs = Math.max(0, startedAt + wallTimeMs - Date.now());
+  const timer = setTimeout(() => {
+    if (isTerminalAgentStatus(agent.status)) return;
+    const reason = `wall_time_ms (${wallTimeMs}) exceeded`;
+    agent.result = buildWallTimeBudgetResult(agent, reason);
+    agent.partial_output = agent.result.partial_output || '';
+    if (agent.abortController && !agent.abortController.signal.aborted) {
+      try { agent.abortController.abort(reason); } catch { /* ignore */ }
+    }
+    transitionTerminal(agent, STATUS.COMPLETED, {
+      error: reason,
+      diagnostic: 'wall_time_watchdog',
+      deps,
+    });
+  }, remainingMs);
+  timer.unref?.();
+  return timer;
+}
+
 async function driveSubAgent(agent, subEngine, vpPersona, deps) {
   const onEvent = typeof deps.onEvent === 'function' ? deps.onEvent : null;
+  const wallTimeWatchdog = armWallTimeWatchdog(agent, deps);
   const idleAbandonMs = typeof deps.idleAbandonMs === 'number' && deps.idleAbandonMs > 0
     ? deps.idleAbandonMs : IDLE_ABANDON_MS;
 
@@ -262,6 +297,21 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
         agent.status = STATUS.IDLE;
         agent.idleSince = Date.now();
         emit({ type: 'sub_agent_status', status: STATUS.IDLE });
+        if (agent.result || agent.lastResult) {
+          try {
+            enqueueTerminalNotification({
+              agentId: agent.id,
+              agentName: agent.name,
+              status: STATUS.IDLE,
+              result: typeof agent.result === 'string' ? agent.result : (agent.lastResult || ''),
+              error: null,
+              outputFile: agent.outputFile || null,
+              turns: agent.usage?.turns || 0,
+              parentVpId: agent.parentVpId || deps.parentVpId || null,
+              parentSessionId: agent.parentSessionId || deps.parentSessionId || null,
+            });
+          } catch { /* best-effort notification */ }
+        }
 
         const reason = await waitUntilResumed(agent, idleAbandonMs);
         if (reason === 'abandoned') {
@@ -398,6 +448,7 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
       emit({ type: 'sub_agent_turn_end', content: assistantText });
     }
   } finally {
+    if (wallTimeWatchdog) clearTimeout(wallTimeWatchdog);
     // Always clean up driver-owned resources. We intentionally do NOT
     // unset agent.result / agent.lastResult / agent.liveness / agent.
     // outputFile — those are observable by the parent after termination.
@@ -451,7 +502,10 @@ function finalizeTerminal(agent, status, { error, deps } = {}) {
   }
 
   // Push the re-entry notification so the parent learns about this
-  // even if it forgot to call WaitAgent.
+  // even if it forgot to call WaitAgent. A prior idle notification may
+  // still be indexed by agentId after the parent consumed the queue; remove
+  // it so terminal state can replace that non-terminal progress notice.
+  try { consumeNotificationForAgent(agent.id); } catch { /* ignore */ }
   try {
     const budgetResult = agent.result && typeof agent.result === 'object'
       && agent.result.status === 'budget_exceeded'

package/yeaft/tools/agent.js

@@ -25,7 +25,7 @@ import { randomUUID } from 'crypto';
 import { getPersona, listPersonaIds } from '../personas.js';
 import { startSubAgent } from '../sub-agent/runner.js';
 import { STATUS, isTerminalAgentStatus } from '../sub-agent/status.js';
-import { makeLiveness } from '../sub-agent/liveness.js';
+import { diagnoseAgentLiveness, makeLiveness } from '../sub-agent/liveness.js';
 
 /** In-memory sub-agent registry. */
 const agents = new Map();
@@ -232,18 +232,16 @@ Guidelines:
 - Use expected_output when the return shape matters
 - Add a budget only when you need an explicit safety cutoff
 
-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.
+Async orchestration:
+  1. SpawnAgent  — starts the sub-agent as a background task and returns immediately.
+  2. Continue    — keep working in the parent VP; do not block just to poll.
+  3. ListAgents  — non-blocking status check when you need progress/liveness.
+  4. PromptAgent — optional follow-up if the sub-agent is idle and needs guidance.
+  5. CloseAgent  — stop or finalize a sub-agent when it is no longer needed.
 
-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.`,
+Completion/failure is delivered through sub-agent notifications on later parent
+turns. WaitAgent remains available only as a short compatibility poll; do not
+use it as the default workflow or call it repeatedly in a loop.`,
   parameters: {
     type: 'object',
     properties: {
@@ -381,11 +379,13 @@ you just kicked off.`,
       // tests). Leave the record in 'created' so existing tests still work.
     }
 
+    const liveness = diagnoseAgentLiveness(agent);
     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.',
+        'Sub-agent is running in the background. Continue the parent task; ' +
+        'use ListAgents for a non-blocking status check, PromptAgent only ' +
+        'when the sub-agent is idle and needs more input, and rely on ' +
+        'completion notifications on later turns. Do not call WaitAgent in a loop.',
       success: true,
       agentId,
       name,
@@ -393,7 +393,10 @@ you just kicked off.`,
       budget: spec.budget || null,
       status: agent.status,
       outputFile: agent.outputFile || null,
-      message: `Sub-agent "${name}" spawned (${agentId}). Use WaitAgent to collect its first turn output, PromptAgent to give it more work, CloseAgent to finish. Read \`outputFile\` for the durable event log at any time.`,
+      liveness,
+      stale: liveness.stale,
+      stalled: liveness.stalled,
+      message: `Sub-agent "${name}" spawned (${agentId}) as an async background task. Use ListAgents to monitor it without blocking. Read \`outputFile\` for the durable event log at any time.`,
     });
   },
 });

package/yeaft/tools/list-agents.js

@@ -12,16 +12,17 @@
 import { defineTool } from './types.js';
 import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
 import { isTerminalAgentStatus } from '../sub-agent/status.js';
-import { snapshotLiveness } from '../sub-agent/liveness.js';
+import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
 
 export default defineTool({
   name: 'ListAgents',
   description: `List all sub-agents and their current status.
 
 Returns id, name, status, mission/task summary, durable outputFile path,
-liveness counters (toolUseCount, tokenCount, msSinceLastEvent, recentTools)
-and message count for each agent. Use to monitor parallel work in flight,
-and Read \`outputFile\` for any single agent if you need its full timeline.
+liveness counters (toolUseCount, tokenCount, msSinceLastEvent, recentTools),
+stale/stalled diagnostics, result tail, and message count for each agent. Use
+this as the primary non-blocking monitor for async sub-agent work, and Read
+\`outputFile\` for any single agent if you need its full timeline.
 
 By default only non-closed agents are returned. Pass include_closed=true
 to also list closed/failed/abandoned/completed agents.`,
@@ -49,7 +50,10 @@ to also list closed/failed/abandoned/completed agents.`,
     for (const [id, agent] of agents) {
       if (!agentBelongsToCaller(agent, ctx)) continue;
       if (!includeTerminal && isTerminalAgentStatus(agent.status)) continue;
-      const liveness = snapshotLiveness(agent.liveness, now);
+      const liveness = diagnoseAgentLiveness(agent, { now });
+      const resultText = (typeof agent.result === 'string' && agent.result)
+        ? agent.result
+        : (agent.lastResult || '');
       agentList.push({
         id,
         name: agent.name,
@@ -59,8 +63,13 @@ to also list closed/failed/abandoned/completed agents.`,
         liveness,
         lastEventAt: liveness.lastEventAt,
         msSinceLastEvent: liveness.msSinceLastEvent,
+        lastEventType: liveness.lastEventType,
+        stale: liveness.stale,
+        stalled: liveness.stalled,
+        diagnostic: liveness.diagnostic,
         error: agent.error || null,
         hasResult: Boolean(agent.result || agent.lastResult),
+        resultTail: resultText ? resultText.slice(-1000) : '',
         messages: Array.isArray(agent.messages) ? agent.messages.length : 0,
         turns: agent.usage?.turns || 0,
         createdAt: agent.createdAt,

package/yeaft/tools/wait-agent.js

@@ -33,7 +33,7 @@
 import { defineTool } from './types.js';
 import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
 import { isTerminalAgentStatus, STATUS } from '../sub-agent/status.js';
-import { snapshotLiveness } from '../sub-agent/liveness.js';
+import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
 import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
 
 /**
@@ -43,7 +43,7 @@ import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
  * tail-positioned nudges when `result` is long).
  *
  * @param {string} status
- * @param {{ timedOut?: boolean, runningInBackground?: boolean, budgetExceeded?: boolean }} [opts]
+ * @param {{ timedOut?: boolean, runningInBackground?: boolean, budgetExceeded?: boolean, stale?: boolean }} [opts]
  */
 function nextStepsFor(status, opts = {}) {
   if (opts.budgetExceeded) {
@@ -55,15 +55,20 @@ function nextStepsFor(status, opts = {}) {
       'as an ordinary successful completion.'
     );
   }
+  if (opts.timedOut && opts.stale) {
+    return (
+      'Sub-agent still has a running record but appears stalled. Do NOT keep ' +
+      'calling WaitAgent in a loop. Use ListAgents/outputFile to inspect it, ' +
+      'CloseAgent if you want to stop it, or report the stalled background ' +
+      'task and start a fresh agent if needed.'
+    );
+  }
   if (opts.timedOut) {
     return (
-      'Sub-agent is STILL RUNNING in the background — it does NOT need ' +
-      'another PromptAgent to keep going. Decide: (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) tell the ' +
-      'user the agent is still working and ask whether to keep waiting. ' +
-      'Read `outputFile` for the full event timeline. Do NOT end your turn ' +
-      'silently.'
+      'Sub-agent is running in the background; it does not need another ' +
+      'PromptAgent to keep going. Continue the main task or tell the user it ' +
+      'is still running. Use ListAgents later for a non-blocking status check; ' +
+      'only call WaitAgent again if the user explicitly wants to wait.'
     );
   }
   switch (status) {
@@ -124,6 +129,7 @@ function errorNextSteps() {
  */
 function buildEnvelope(agent, { timedOut = false } = {}) {
   const status = agent.status;
+  const liveness = diagnoseAgentLiveness(agent);
   const budgetResult = agent.result && typeof agent.result === 'object'
     && agent.result.status === 'budget_exceeded'
     ? agent.result
@@ -134,13 +140,18 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
         ? agent.result
         : (agent.lastResult || ''));
   const env = {
-    next_steps: nextStepsFor(status, { timedOut, budgetExceeded: !!budgetResult }),
+    next_steps: nextStepsFor(status, { timedOut, budgetExceeded: !!budgetResult, stale: liveness.stale }),
     agentId: agent.id,
     name: agent.name,
     status,
     error: agent.error || null,
     outputFile: agent.outputFile || null,
-    liveness: snapshotLiveness(agent.liveness),
+    liveness,
+    stale: liveness.stale,
+    stalled: liveness.stalled,
+    msSinceLastEvent: liveness.msSinceLastEvent,
+    lastEventType: liveness.lastEventType,
+    diagnostic: liveness.diagnostic,
     messages: Array.isArray(agent.messages) ? agent.messages.length : 0,
     turns: agent.usage?.turns || 0,
   };
@@ -188,7 +199,7 @@ 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).`,
+Compatibility tool. The default wait is a short 5000ms poll. Callers may request up to 300000ms (5 minutes), but this is no longer the primary sub-agent workflow; prefer SpawnAgent + ListAgents + completion notifications for async background work.`,
   parameters: {
     type: 'object',
     properties: {
@@ -200,7 +211,7 @@ The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
         type: 'number',
         minimum: 0,
         maximum: 300000,
-        description: 'Maximum time to wait in milliseconds (default: 30000, max: 300000 / 5 minutes)',
+        description: 'Maximum time to wait in milliseconds (default: 5000 short poll, max: 300000 / 5 minutes)',
       },
     },
     required: ['agent_id'],
@@ -209,7 +220,7 @@ The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   async execute(input, ctx) {
-    const { agent_id, timeout_ms = 30000 } = input;
+    const { agent_id, timeout_ms = 5000 } = input;
     if (!agent_id) {
       return JSON.stringify({ next_steps: errorNextSteps(), error: 'agent_id is required' });
     }
@@ -234,6 +245,7 @@ The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
       return JSON.stringify(buildEnvelope(agent));
     }
     if (agent.status === STATUS.IDLE) {
+      consumeNotificationForAgent(agent.id);
       return JSON.stringify(buildEnvelope(agent));
     }
     if (ctx?.signal?.aborted) {
@@ -248,6 +260,7 @@ The default wait is 30000ms. Callers may request up to 300000ms (5 minutes).`,
         return JSON.stringify(buildEnvelope(agent));
       }
       if (agent.status === STATUS.IDLE) {
+        consumeNotificationForAgent(agent.id);
         return JSON.stringify(buildEnvelope(agent));
       }
       if (ctx?.signal?.aborted) {