@yeaft/webchat-agent 0.1.952 → 0.1.953

package/package.json

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

package/yeaft/engine.js

@@ -43,6 +43,7 @@ import { attachRouterPlan, extractPriorPlan, stripMetaForWire } from './router/c
 import { resolveThinking } from './router/thinking.js';
 import { approxTokens } from './memory/budget.js';
 import { COLLAB_TOOL_POLICY, truncateToolResultIfNeeded } from './tools/registry.js';
+import { acknowledgePendingNotifications, formatNotificationsForPrompt, peekPendingNotifications } from './sub-agent/notifications.js';
 import {
   TOOL_BATCH_SIZE,
   TURN_SUMMARY_THRESHOLD,
@@ -958,6 +959,8 @@ export class Engine {
         parentName: vpCtx?.senderVpId || 'parent',
         parentVpId: vpCtx?.senderVpId || null,
         parentVpPersona: vpCtx?.vpPersona || null,
+        parentSessionId: vpCtx?.sessionId || null,
+        parentThreadId: vpCtx?.threadId || MAIN_THREAD_ID,
         onEvent: this.#subAgentEventSink || null,
         language: this.#config?.language || 'en',
         // Forward the session-shared ToolUsageStats so sub-agent
@@ -1424,6 +1427,12 @@ export class Engine {
     const effectiveCollabToolPolicy = collabToolPolicy === COLLAB_TOOL_POLICY.SINGLE_VP || collabToolPolicy === COLLAB_TOOL_POLICY.MULTI_VP
       ? collabToolPolicy
       : null;
+    const runtimeSessionId = (typeof sessionId === 'string' && sessionId.trim())
+      ? sessionId.trim()
+      : this.#sessionId;
+    const runtimeThreadId = (typeof threadId === 'string' && threadId.trim())
+      ? threadId.trim()
+      : MAIN_THREAD_ID;
 
     // ─── Pre-query: FTS5 Memory Recall + AMS snapshot ─────
     // Memory has a SINGLE render outlet now (DESIGN-PROMPT §3 ③):
@@ -1574,9 +1583,37 @@ export class Engine {
     // If `promptParts` was supplied (image/file attachments), use the array form
     // so the adapter sees image content blocks alongside the text. Otherwise the
     // legacy string form keeps prompt-cache behavior identical.
-    const finalUserContent = (Array.isArray(promptParts) && promptParts.length > 0)
-      ? promptParts
-      : prompt;
+    //
+    // Sub-agent re-entry: before constructing the user message, drain any
+    // terminal sub-agent notifications that landed for this parent VP
+    // while it was idle. If any are present we prepend an XML-tagged
+    // block to the user prompt so the parent model sees the sub-agent
+    // result(s) even if it forgot to call WaitAgent. See
+    // sub-agent/notifications.js for the bucketing + format.
+    const parentVpIdForNotif = (vpPersona && typeof vpPersona === 'object' && typeof vpPersona.vpId === 'string')
+      ? vpPersona.vpId
+      : (typeof senderVpId === 'string' ? senderVpId : null);
+    const isSubAgentTurn = !!(vpPersona && typeof vpPersona === 'object' && vpPersona.subAgent);
+    const notifScope = {
+      sessionId: runtimeSessionId,
+      parentVpId: parentVpIdForNotif,
+      threadId: runtimeThreadId,
+    };
+    const pendingSubAgentNotifs = isSubAgentTurn ? [] : peekPendingNotifications(notifScope);
+    const subAgentNotifBlock = formatNotificationsForPrompt(pendingSubAgentNotifs);
+
+    let finalUserContent;
+    if (Array.isArray(promptParts) && promptParts.length > 0) {
+      // Multimodal prompt — prepend the notification block as a leading
+      // text part so the adapter still sees image content blocks intact.
+      finalUserContent = subAgentNotifBlock
+        ? [{ type: 'text', text: subAgentNotifBlock + '\n\n' }, ...promptParts]
+        : promptParts;
+    } else {
+      finalUserContent = subAgentNotifBlock
+        ? `${subAgentNotifBlock}\n\n${prompt || ''}`
+        : prompt;
+    }
     const conversationMessages = [
       ...compactMessages,
       ...messages,
@@ -2191,6 +2228,9 @@ export class Engine {
 
       // If no tool calls, we're done
       if (stopReason !== 'tool_use' || toolCalls.length === 0) {
+        if (pendingSubAgentNotifs.length > 0) {
+          acknowledgePendingNotifications(notifScope, pendingSubAgentNotifs.map(n => n.id));
+        }
         yield { type: 'turn_end', turnNumber, stopReason, threadId };
 
         // ─── Post-query: StopHooks or Legacy ─────────────
@@ -2340,6 +2380,8 @@ export class Engine {
       const toolCtx = this.#buildToolContext(signal, {
         router,
         senderVpId,
+        sessionId: runtimeSessionId,
+        threadId: runtimeThreadId,
         inboundEnvelope,
         taskId,
         taskMembers,
@@ -2536,6 +2578,9 @@ export class Engine {
       // multi-iteration tool loops) and BEFORE the abortedDuringTools
       // check (so a clean handoff doesn't get reported as 'aborted').
       if (endTurnRequested) {
+        if (pendingSubAgentNotifs.length > 0) {
+          acknowledgePendingNotifications(notifScope, pendingSubAgentNotifs.map(n => n.id));
+        }
         const handoffDetail = typeof endTurnRequested === 'object'
           ? endTurnRequested
           : { kind: 'tool_handoff', reason: String(endTurnRequested) };

package/yeaft/sub-agent/liveness.js

@@ -0,0 +1,101 @@
+/**
+ * liveness.js — "Is this sub-agent alive or hung?" helpers.
+ *
+ * Yeaft's original wait_agent payload told the parent essentially nothing
+ * mid-flight: just `{ status, result: '' }`. The model couldn't tell
+ * "still thinking" from "stuck on a slow tool" from "actually wedged".
+ *
+ * Liveness is a tiny counter struct we update from the runner whenever a
+ * sub-engine event passes through. wait_agent and list_agents include
+ * it in their JSON payloads so the parent gets a clear visible signal
+ * that the child is doing work, plus a timestamp it can compare against
+ * Date.now() to compute "seconds since last activity".
+ *
+ * The struct lives on the agent record as `agent.liveness`. We never
+ * delete the field — even on terminal status the last snapshot is
+ * preserved so the parent can see "you ran 7 tools and last spoke 3
+ * seconds before completing".
+ */
+
+/**
+ * Create a fresh liveness record.
+ *
+ * @returns {{
+ *   toolUseCount: number,
+ *   tokenCount: number,
+ *   eventCount: number,
+ *   lastEventAt: number,
+ *   lastEventType: string|null,
+ *   recentTools: string[],
+ * }}
+ */
+export function makeLiveness() {
+  return {
+    toolUseCount: 0,
+    tokenCount: 0,
+    eventCount: 0,
+    lastEventAt: 0,
+    lastEventType: null,
+    recentTools: [],
+  };
+}
+
+const RECENT_TOOLS_MAX = 5;
+
+/**
+ * Update a liveness record from a sub-engine event.
+ *
+ * @param {ReturnType<typeof makeLiveness>} liveness
+ * @param {object} evt
+ */
+export function bumpLivenessFromEvent(liveness, evt) {
+  if (!liveness || !evt || typeof evt !== 'object') return;
+  liveness.eventCount += 1;
+  liveness.lastEventAt = Date.now();
+  liveness.lastEventType = evt.type || liveness.lastEventType;
+  if (evt.type === 'text_delta' && typeof evt.text === 'string') {
+    // Coarse "have we produced output" signal. Token count is not exact —
+    // it's character-based — but it lets the parent see "yes, the model
+    // is generating".
+    liveness.tokenCount += evt.text.length;
+  } else if (evt.type === 'tool_start' || evt.type === 'tool_call') {
+    liveness.toolUseCount += 1;
+    const name = evt.toolName || evt.name || (evt.tool && evt.tool.name) || null;
+    if (name) {
+      liveness.recentTools.push(name);
+      if (liveness.recentTools.length > RECENT_TOOLS_MAX) {
+        liveness.recentTools.splice(0, liveness.recentTools.length - RECENT_TOOLS_MAX);
+      }
+    }
+  }
+}
+
+/**
+ * Render a small JSON object suitable for embedding inside a wait_agent /
+ * list_agents reply. Keeps the public field names stable and bounded.
+ *
+ * @param {ReturnType<typeof makeLiveness>|null|undefined} liveness
+ * @param {number} [now=Date.now()]
+ */
+export function snapshotLiveness(liveness, now = Date.now()) {
+  if (!liveness) {
+    return {
+      toolUseCount: 0,
+      tokenCount: 0,
+      eventCount: 0,
+      lastEventAt: null,
+      msSinceLastEvent: null,
+      lastEventType: null,
+      recentTools: [],
+    };
+  }
+  return {
+    toolUseCount: liveness.toolUseCount,
+    tokenCount: liveness.tokenCount,
+    eventCount: liveness.eventCount,
+    lastEventAt: liveness.lastEventAt || null,
+    msSinceLastEvent: liveness.lastEventAt ? Math.max(0, now - liveness.lastEventAt) : null,
+    lastEventType: liveness.lastEventType,
+    recentTools: liveness.recentTools.slice(),
+  };
+}

package/yeaft/sub-agent/notifications.js

@@ -0,0 +1,257 @@
+/**
+ * notifications.js — Sub-agent → parent re-entry queue.
+ *
+ * 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.
+ *
+ *   This module is the queue. Two entry points consume it:
+ *
+ *     1. WaitAgent (drains anything queued for this agent on terminal,
+ *        before returning).
+ *     2. Engine.query() — when started with a user prompt, it asks
+ *        `consumePendingNotifications({ sessionId, parentVpId, threadId })` for any queued
+ *        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".
+ *
+ *   The queue is in-memory only. We do NOT persist across process
+ *   restarts because (a) sub-agents themselves don't survive restart,
+ *   and (b) the durable per-agent outputFile (see output-log.js) is the
+ *   long-term record.
+ *
+ * Keying:
+ *   Notifications are bucketed by `(sessionId, parentVpId, threadId)` when
+ *   the parent runs inside a Yeaft Session. Legacy / test callers that
+ *   don't provide a sessionId still bucket by `parentVpId` (or
+ *   `'__no_vp__'`) so older in-process callers keep working. WaitAgent
+ *   always drains via agentId regardless of bucket, so the bucket only
+ *   matters for the engine pre-prompt drain.
+ *
+ * Dedup:
+ *   Each notification carries a unique id (agentId + status + ts). The
+ *   `markNotified()` flag on the agent record (set by drainers) prevents
+ *   us from emitting more than one terminal notification per agent.
+ */
+
+/** @typedef {{ id: string, agentId: string, agentName: string, status: string, result: string, error: string|null, outputFile: string|null, turns: number, parentVpId: string|null, parentSessionId: string|null, parentThreadId: string|null, budgetExceeded: boolean, budgetReason: string|null, budgetUsage: object|null, createdAt: number }} SubAgentNotification */
+
+/** Map<bucketKey, SubAgentNotification[]> */
+const byParent = new Map();
+/** Map<agentId, SubAgentNotification> — for WaitAgent agentId drains. */
+const byAgent = new Map();
+
+const FALLBACK_BUCKET = '__no_vp__';
+const MAIN_THREAD_ID = 'main';
+
+function cleanString(value) {
+  return (typeof value === 'string' && value.trim()) ? value.trim() : null;
+}
+
+function normalizeScope(input, sessionId, threadId) {
+  if (input && typeof input === 'object') {
+    return {
+      parentVpId: cleanString(input.parentVpId),
+      sessionId: cleanString(input.sessionId ?? input.parentSessionId),
+      threadId: cleanString(input.threadId ?? input.parentThreadId) || MAIN_THREAD_ID,
+    };
+  }
+  return {
+    parentVpId: cleanString(input),
+    sessionId: cleanString(sessionId),
+    threadId: cleanString(threadId) || MAIN_THREAD_ID,
+  };
+}
+
+function bucketKey(scope, sessionId, threadId) {
+  const s = normalizeScope(scope, sessionId, threadId);
+  const vp = s.parentVpId || FALLBACK_BUCKET;
+  if (!s.sessionId) return vp;
+  return `${s.sessionId}::${vp}::${s.threadId || MAIN_THREAD_ID}`;
+}
+
+/**
+ * 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).
+ *
+ * @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, parentThreadId?: string|null, threadId?: string|null, budgetExceeded?: boolean, budgetReason?: string|null, budgetUsage?: object|null }} input
+ * @returns {SubAgentNotification|null} the queued record (null if a dup)
+ */
+export function enqueueTerminalNotification(input) {
+  if (!input || !input.agentId || !input.status) return null;
+  if (byAgent.has(input.agentId)) return null; // already queued
+  const scope = normalizeScope({
+    parentVpId: input.parentVpId,
+    parentSessionId: input.parentSessionId ?? input.sessionId,
+    parentThreadId: input.parentThreadId ?? input.threadId,
+  });
+  const rec = {
+    id: `${input.agentId}:${input.status}:${Date.now()}`,
+    agentId: input.agentId,
+    agentName: input.agentName || input.agentId,
+    status: input.status,
+    result: input.result || '',
+    error: input.error || null,
+    outputFile: input.outputFile || null,
+    turns: typeof input.turns === 'number' ? input.turns : 0,
+    parentVpId: scope.parentVpId,
+    parentSessionId: scope.sessionId,
+    parentThreadId: scope.threadId,
+    budgetExceeded: Boolean(input.budgetExceeded),
+    budgetReason: input.budgetReason || null,
+    budgetUsage: input.budgetUsage || null,
+    createdAt: Date.now(),
+  };
+  const key = bucketKey(scope);
+  if (!byParent.has(key)) byParent.set(key, []);
+  byParent.get(key).push(rec);
+  byAgent.set(rec.agentId, rec);
+  return rec;
+}
+
+/**
+ * Drain and return pending notifications for a parent VP. Pass null to
+ * drain the fallback bucket. Returns [] when nothing pending.
+ *
+ * Engine calls this at the start of every user-driven turn so the
+ * parent model sees terminal events that arrived while it was idle.
+ *
+ * @param {string|{parentVpId?: string|null, sessionId?: string|null, parentSessionId?: string|null, threadId?: string|null, parentThreadId?: string|null}|null} scope
+ * @returns {SubAgentNotification[]}
+ */
+export function consumePendingNotifications(scope) {
+  const key = bucketKey(scope);
+  const list = byParent.get(key) || [];
+  byParent.set(key, []);
+  // Don't drop from byAgent yet — WaitAgent may still query by agentId
+  // and we want it to be a no-op on already-drained records (the
+  // `notified` flag on the agent itself is the real dedup gate).
+  return list.slice();
+}
+
+/**
+ * Return pending notifications without acknowledging them. Engine uses this
+ * while constructing a prompt; it acknowledges only after the parent turn
+ * completes successfully so abort/error paths don't lose the notification.
+ *
+ * @param {string|{parentVpId?: string|null, sessionId?: string|null, parentSessionId?: string|null, threadId?: string|null, parentThreadId?: string|null}|null} scope
+ * @returns {SubAgentNotification[]}
+ */
+export function peekPendingNotifications(scope) {
+  const key = bucketKey(scope);
+  const list = byParent.get(key) || [];
+  return list.slice();
+}
+
+/**
+ * Acknowledge notifications previously returned by peekPendingNotifications.
+ * Removes them from both parent and per-agent maps.
+ *
+ * @param {string|{parentVpId?: string|null, sessionId?: string|null, parentSessionId?: string|null, threadId?: string|null, parentThreadId?: string|null}|null} scope
+ * @param {string[]} ids
+ */
+export function acknowledgePendingNotifications(scope, ids = []) {
+  const idSet = new Set(Array.isArray(ids) ? ids.filter(Boolean) : []);
+  if (idSet.size === 0) return;
+  const key = bucketKey(scope);
+  const list = byParent.get(key) || [];
+  const kept = [];
+  for (const rec of list) {
+    if (idSet.has(rec.id)) {
+      byAgent.delete(rec.agentId);
+    } else {
+      kept.push(rec);
+    }
+  }
+  byParent.set(key, kept);
+}
+
+/**
+ * Drain and return the pending notification for a single agent, or null.
+ * Used by WaitAgent on terminal so the same notification isn't also
+ * re-prepended to the next user turn.
+ *
+ * @param {string} agentId
+ * @returns {SubAgentNotification|null}
+ */
+export function consumeNotificationForAgent(agentId) {
+  if (!agentId) return null;
+  const rec = byAgent.get(agentId);
+  if (!rec) return null;
+  byAgent.delete(agentId);
+  // Also remove from the parent bucket so the engine drain doesn't
+  // re-emit it.
+  const key = bucketKey({
+    parentVpId: rec.parentVpId,
+    sessionId: rec.parentSessionId,
+    threadId: rec.parentThreadId,
+  });
+  const list = byParent.get(key);
+  if (Array.isArray(list)) {
+    const idx = list.findIndex(r => r.id === rec.id);
+    if (idx >= 0) list.splice(idx, 1);
+  }
+  return rec;
+}
+
+/**
+ * Format a notification batch as a single XML-tagged block to prepend
+ * to the user's next prompt. The model sees this as system-emitted
+ * out-of-band context (we wrap with a literal tag so it's visually
+ * obvious in transcripts).
+ *
+ * @param {SubAgentNotification[]} notifs
+ * @returns {string} '' when notifs is empty
+ */
+export function formatNotificationsForPrompt(notifs) {
+  if (!Array.isArray(notifs) || notifs.length === 0) return '';
+  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.',
+  );
+  for (const n of notifs) {
+    parts.push('');
+    parts.push(`<notification agent="${n.agentName}" id="${n.agentId}" status="${n.status}" turns="${n.turns}">`);
+    if (n.error) parts.push(`  error: ${n.error}`);
+    if (n.budgetExceeded) {
+      parts.push('  budgetExceeded: true');
+      if (n.budgetReason) parts.push(`  budgetReason: ${n.budgetReason}`);
+      if (n.budgetUsage) parts.push(`  budgetUsage: ${JSON.stringify(n.budgetUsage)}`);
+    }
+    if (n.outputFile) parts.push(`  outputFile: ${n.outputFile}`);
+    if (n.result) {
+      const r = n.result.length > 1500 ? n.result.slice(0, 1500) + '…(truncated)' : n.result;
+      parts.push('  result:');
+      parts.push(`    ${r.split('\n').join('\n    ')}`);
+    }
+    parts.push('</notification>');
+  }
+  parts.push('</sub-agent-notifications>');
+  return parts.join('\n');
+}
+
+/** Reset both maps. Tests only. */
+export function _resetNotifications() {
+  byParent.clear();
+  byAgent.clear();
+}
+
+/** Inspect the queue. Tests only. */
+export function _peekAll() {
+  return {
+    byParent: Object.fromEntries([...byParent.entries()].map(([k, v]) => [k, v.slice()])),
+    byAgent: Object.fromEntries(byAgent.entries()),
+  };
+}