@yeaft/webchat-agent 0.1.951 → 0.1.953

package/yeaft/sub-agent/status.js

@@ -0,0 +1,81 @@
+/**
+ * status.js — Centralized status vocabulary for the sub-agent subsystem.
+ *
+ * The same string set used to be sprinkled across tools/agent.js,
+ * tools/wait-agent.js, tools/send-message.js, tools/close-agent.js,
+ * tools/list-agents.js and sub-agent/runner.js. Every time we added a
+ * status (e.g. 'abandoned' for the idle watchdog) we had to chase 5+
+ * files and update string lists. This module is the single source of
+ * truth.
+ *
+ * Status lifecycle:
+ *
+ *   created  → running ↔ idle (after each turn ends without queued prompt)
+ *            ↓        ↓
+ *            failed   completed
+ *            ↓        ↓
+ *            closed   abandoned (idle too long; reaped by watchdog)
+ *
+ * - 'created'   : registry record exists but the driver hasn't taken a
+ *                  step yet. Transient — flips to 'running' on first tick.
+ * - 'running'   : the sub-engine is processing a prompt.
+ * - 'idle'      : the previous turn ended cleanly and the queue is empty.
+ *                  The driver is parked in waitUntilResumed().
+ * - 'completed' : terminal success — typically set by tickAgent() when a
+ *                  budget cutoff is hit cleanly with a partial_output.
+ * - 'failed'    : terminal — driver/adapter/stream raised; agent.error set.
+ * - 'closed'    : terminal — CloseAgent called (or driver finally{} reaped
+ *                  a cleanly-finishing agent).
+ * - 'abandoned' : terminal — idle watchdog tripped (no prompt arrived in
+ *                  IDLE_ABANDON_MS). Distinct from 'closed' so the parent
+ *                  can tell "the parent forgot about me" from "the parent
+ *                  deliberately wrapped me up".
+ */
+
+export const STATUS = Object.freeze({
+  CREATED: 'created',
+  RUNNING: 'running',
+  IDLE: 'idle',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CLOSED: 'closed',
+  ABANDONED: 'abandoned',
+});
+
+const TERMINAL = new Set([STATUS.COMPLETED, STATUS.FAILED, STATUS.CLOSED, STATUS.ABANDONED]);
+const INTERACTIVE = new Set([STATUS.CREATED, STATUS.RUNNING, STATUS.IDLE]);
+
+/** Is this status a permanent terminal state? */
+export function isTerminalAgentStatus(status) {
+  return TERMINAL.has(status);
+}
+
+/** Is the agent still alive and interactable (not terminal)? */
+export function isInteractiveAgentStatus(status) {
+  return INTERACTIVE.has(status);
+}
+
+/** Can PromptAgent successfully queue a prompt at this status? */
+export function isPromptableAgentStatus(status) {
+  // Even 'created' is promptable — the mission is the implicit first prompt
+  // and a SendMessage racing the driver simply gets dequeued after the
+  // mission.
+  return status === STATUS.CREATED || status === STATUS.RUNNING || status === STATUS.IDLE;
+}
+
+/**
+ * Build the canonical human-facing label for a status. Used by UI nudges
+ * and `next_steps` strings so we don't drift between modules.
+ */
+export function describeAgentStatus(status) {
+  switch (status) {
+    case STATUS.CREATED:    return 'just spawned';
+    case STATUS.RUNNING:    return 'running a turn';
+    case STATUS.IDLE:       return 'idle (turn ended, queue empty)';
+    case STATUS.COMPLETED:  return 'completed (terminal)';
+    case STATUS.FAILED:     return 'failed (terminal)';
+    case STATUS.CLOSED:     return 'closed (terminal)';
+    case STATUS.ABANDONED:  return 'abandoned by idle watchdog (terminal)';
+    default:                return String(status || 'unknown');
+  }
+}

package/yeaft/tools/agent.js

@@ -24,6 +24,8 @@ import { defineTool } from './types.js';
 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';
 
 /** In-memory sub-agent registry. */
 const agents = new Map();
@@ -33,6 +35,44 @@ export function getAgentRegistry() {
   return agents;
 }
 
+const MAIN_THREAD_ID = 'main';
+
+function cleanString(value) {
+  return (typeof value === 'string' && value.trim()) ? value.trim() : null;
+}
+
+export function getCallerAgentScope(ctx = {}) {
+  const deps = ctx?.parentEngineDeps || {};
+  return {
+    sessionId: cleanString(deps.parentSessionId ?? ctx?.sessionId),
+    parentVpId: cleanString(deps.parentVpId ?? ctx?.senderVpId),
+    parentThreadId: cleanString(deps.parentThreadId ?? ctx?.threadId),
+  };
+}
+
+export function agentBelongsToCaller(agent, ctx = {}) {
+  if (!agent) return false;
+  const scope = getCallerAgentScope(ctx);
+  return agentBelongsToScope(agent, scope);
+}
+
+export function agentBelongsToScope(agent, scope = {}) {
+  if (!agent) return false;
+  const agentSessionId = cleanString(agent.parentSessionId);
+  const scopeSessionId = cleanString(scope.sessionId);
+  const agentVpId = cleanString(agent.parentVpId);
+  const scopeVpId = cleanString(scope.parentVpId);
+  const agentThreadId = cleanString(agent.parentThreadId);
+  const scopeThreadId = cleanString(scope.parentThreadId);
+  if (!scopeSessionId && !scopeVpId && !scopeThreadId) {
+    return !agentSessionId && !agentVpId;
+  }
+  if ((agentSessionId || scopeSessionId) && agentSessionId !== scopeSessionId) return false;
+  if ((agentVpId || scopeVpId) && agentVpId !== scopeVpId) return false;
+  if (!agentThreadId && !scopeThreadId) return true;
+  return (agentThreadId || MAIN_THREAD_ID) === (scopeThreadId || MAIN_THREAD_ID);
+}
+
 /** Reset registry (for tests). */
 export function _resetAgentRegistry() {
   agents.clear();
@@ -138,7 +178,7 @@ export function budgetExceededResult(agent, reason) {
 export function tickAgent(agentId, delta = {}, now = Date.now()) {
   const agent = agents.get(agentId);
   if (!agent) return null;
-  if (agent.status === 'completed' || agent.status === 'closed') return null;
+  if (isTerminalAgentStatus(agent.status)) return null;
 
   if (typeof delta.tokens === 'number' && delta.tokens > 0) {
     agent.usage.tokens += delta.tokens;
@@ -155,7 +195,7 @@ export function tickAgent(agentId, delta = {}, now = Date.now()) {
 
   const envelope = budgetExceededResult(agent, check.reason);
   agent.result = envelope;
-  agent.status = 'completed';
+  agent.status = STATUS.COMPLETED;
   agent.diagnostics.push({
     type: 'budget_exceeded',
     limit: check.limit,
@@ -262,10 +302,15 @@ you just kicked off.`,
     }
     const spec = validation.spec;
     const { name, cwd } = input;
+    const callerScope = getCallerAgentScope(ctx);
 
-    // Check for name collision
+    // Check for name collision — any non-terminal agent with the same
+    // name blocks the new spawn. Terminal agents (closed/failed/abandoned/
+    // completed) free the name up for reuse. Scope this to the caller's
+    // Session/VP/thread so independent sessions can reuse natural names.
     for (const [, agent] of agents) {
-      if (agent.name === name && agent.status !== 'closed') {
+      if (agent.name === name && !isTerminalAgentStatus(agent.status)
+        && agentBelongsToScope(agent, callerScope)) {
         return JSON.stringify({
           next_steps: ERROR_NEXT_STEPS,
           error: `Agent "${name}" already exists. Close it first or use a different name.`,
@@ -287,28 +332,42 @@ you just kicked off.`,
       personaData: persona || null,
       budget: spec.budget,
       cwd: cwd || ctx?.cwd || process.cwd(),
-      status: 'created',
+      status: STATUS.CREATED,
       messages: [],
       result: null,
+      lastResult: '',
       partial_output: '',
       diagnostics: [],
       usage: { tokens: 0, turns: 0, startedAt: now },
       createdAt: now,
       trace: [],
+      // Liveness counters — kept fresh by the runner from each sub-engine
+      // event so WaitAgent/ListAgents can show real-time progress.
+      liveness: makeLiveness(),
+      // Path to the durable JSONL event log. Populated by the runner
+      // when startSubAgent attaches createOutputLog(); we initialize to
+      // null so the field always exists on the record shape.
+      outputFile: null,
+      // ParentVpId is mirrored from deps when the driver starts so the
+      // notification queue can bucket by parent Session/VP/thread.
+      parentVpId: callerScope.parentVpId,
+      parentSessionId: callerScope.sessionId,
+      parentThreadId: callerScope.parentThreadId,
       abortController: new AbortController(),
     };
 
     agents.set(agentId, agent);
 
-    // PR-M1: actually spawn the sub-agent driver. This is fire-and-forget;
-    // it returns immediately. The parent observes via WaitAgent (poll) or
-    // via the engine's sub-agent event sink (live UI streaming).
+    // Actually spawn the sub-agent driver. This is fire-and-forget;
+    // it returns immediately. The parent observes via WaitAgent (which
+    // surfaces status + liveness + outputFile) or via the engine's
+    // sub-agent event sink (live UI streaming).
     const deps = ctx?.parentEngineDeps;
     if (deps && deps.adapter) {
       try {
         startSubAgent(agent, deps);
       } catch (err) {
-        agent.status = 'failed';
+        agent.status = STATUS.FAILED;
         agent.error = err && err.message ? err.message : String(err);
         agent.diagnostics.push({ type: 'spawn_error', error: agent.error, at: Date.now() });
         return JSON.stringify({
@@ -333,7 +392,8 @@ you just kicked off.`,
       persona: spec.persona || null,
       budget: spec.budget || null,
       status: agent.status,
-      message: `Sub-agent "${name}" spawned (${agentId}). Use WaitAgent to collect its first turn output, PromptAgent to give it more work, CloseAgent to finish.`,
+      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.`,
     });
   },
 });

package/yeaft/tools/close-agent.js

@@ -1,9 +1,17 @@
 /**
  * close-agent.js — Close a sub-agent and clean up.
+ *
+ * Marks status='closed' (terminal), aborts the abort controller so any
+ * in-flight engine.query stops promptly, and drains any pending re-entry
+ * notification for the agent so the engine doesn't redeliver it on the
+ * next user turn.
  */
 
 import { defineTool } from './types.js';
-import { getAgentRegistry } from './agent.js';
+import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
+import { isTerminalAgentStatus, STATUS } from '../sub-agent/status.js';
+import { consumeNotificationForAgent, enqueueTerminalNotification } from '../sub-agent/notifications.js';
+import { snapshotLiveness } from '../sub-agent/liveness.js';
 
 export default defineTool({
   name: 'CloseAgent',
@@ -33,8 +41,6 @@ Do NOT end your turn silently right after CloseAgent.`,
   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 ' +
@@ -49,21 +55,58 @@ Do NOT end your turn silently right after CloseAgent.`,
     if (!agent) {
       return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent not found: ${agent_id}` });
     }
+    if (!agentBelongsToCaller(agent, ctx)) {
+      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent not found: ${agent_id}` });
+    }
 
     if (result) {
       agent.result = result;
     }
 
-    // PR-M1: abort any in-flight engine.query so the driver loop exits
-    // promptly. This is cooperative — if the driver is mid-stream the
-    // adapter receives the signal; if it's idle, status flip ends the
-    // wait loop on the next 50ms tick.
+    // Abort any in-flight engine.query so the driver loop exits promptly.
+    // Cooperative — if the driver is mid-stream the adapter receives the
+    // signal; if it's idle, status flip ends the wait loop on the next tick.
     if (agent.abortController && !agent.abortController.signal.aborted) {
       try { agent.abortController.abort('closed'); } catch { /* ignore */ }
     }
 
-    const finalResult = agent.result || agent.lastResult || '';
-    agent.status = 'closed';
+    const finalResult = (typeof agent.result === 'string' && agent.result)
+      ? agent.result
+      : (agent.lastResult || '');
+
+    // If the agent had already gone terminal (e.g. failed) before we got
+    // here, preserve that status; otherwise mark closed. Either way drain
+    // any pending re-entry notification — the parent is explicitly
+    // wrapping up so it doesn't need another nudge.
+    const wasTerminal = isTerminalAgentStatus(agent.status);
+    if (!wasTerminal) {
+      agent.status = STATUS.CLOSED;
+      // The driver may not yet have observed the abort / status flip; push
+      // a notification so the queue stays consistent (idempotent inside
+      // the notifications module). The driver's own finalizeTerminal()
+      // would also try to enqueue but the __terminalNotified guard makes
+      // that a no-op.
+      try {
+        enqueueTerminalNotification({
+          agentId: agent.id,
+          agentName: agent.name,
+          status: STATUS.CLOSED,
+          result: finalResult,
+          error: agent.error || null,
+          outputFile: agent.outputFile || null,
+          turns: agent.usage?.turns || 0,
+          parentVpId: agent.parentVpId || null,
+          parentSessionId: agent.parentSessionId || null,
+          parentThreadId: agent.parentThreadId || 'main',
+        });
+      } catch { /* never block close on notification queue */ }
+      agent.__terminalNotified = true;
+    }
+
+    // The parent is acknowledging the agent right now via this tool
+    // call; drop the queued notification so the engine doesn't
+    // double-deliver on its next user turn.
+    consumeNotificationForAgent(agent.id);
 
     return JSON.stringify({
       next_steps:
@@ -73,7 +116,10 @@ Do NOT end your turn silently right after CloseAgent.`,
       success: true,
       agentId: agent_id,
       name: agent.name,
+      status: agent.status,
       result: finalResult,
+      outputFile: agent.outputFile || null,
+      liveness: snapshotLiveness(agent.liveness),
       messages: agent.messages.length,
       turns: agent.usage?.turns || 0,
       message: `Agent "${agent.name}" closed`,

package/yeaft/tools/list-agents.js

@@ -1,41 +1,68 @@
 /**
- * list-agents.js — List all active sub-agents.
+ * list-agents.js — List all active (and optionally terminal) sub-agents.
+ *
+ * Returns: { agents: [{ id, name, status, task, outputFile, liveness,
+ * lastEventAt, msSinceLastEvent, error, hasResult, createdAt }, …] }.
+ *
+ * The default filter drops `closed` agents to stay tidy; pass
+ * include_closed=true (or include_terminal=true) to see them all. The
+ * include_closed alias is kept for backward-compat with the old shape.
  */
 
 import { defineTool } from './types.js';
-import { getAgentRegistry } from './agent.js';
+import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
+import { isTerminalAgentStatus } from '../sub-agent/status.js';
+import { snapshotLiveness } from '../sub-agent/liveness.js';
 
 export default defineTool({
   name: 'ListAgents',
   description: `List all sub-agents and their current status.
 
-Shows agent IDs, names, tasks, status (created/active/completed/closed),
-and message counts. Use to monitor parallel task progress.`,
+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.
+
+By default only non-closed agents are returned. Pass include_closed=true
+to also list closed/failed/abandoned/completed agents.`,
   parameters: {
     type: 'object',
     properties: {
       include_closed: {
         type: 'boolean',
-        description: 'Include closed agents in the list (default: false)',
+        description: 'Include closed/failed/abandoned/completed agents in the list (default: false)',
+      },
+      include_terminal: {
+        type: 'boolean',
+        description: 'Alias for include_closed — include all terminal-status agents in the list',
       },
     },
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   async execute(input, ctx) {
-    const { include_closed = false } = input;
+    const includeTerminal = Boolean(input?.include_closed || input?.include_terminal);
     const agents = getAgentRegistry();
+    const now = Date.now();
 
     const agentList = [];
     for (const [id, agent] of agents) {
-      if (!include_closed && agent.status === 'closed') continue;
+      if (!agentBelongsToCaller(agent, ctx)) continue;
+      if (!includeTerminal && isTerminalAgentStatus(agent.status)) continue;
+      const liveness = snapshotLiveness(agent.liveness, now);
       agentList.push({
         id,
         name: agent.name,
         status: agent.status,
-        task: agent.task?.slice(0, 200),
-        messages: agent.messages.length,
-        hasResult: !!agent.result,
+        task: typeof agent.task === 'string' ? agent.task.slice(0, 200) : null,
+        outputFile: agent.outputFile || null,
+        liveness,
+        lastEventAt: liveness.lastEventAt,
+        msSinceLastEvent: liveness.msSinceLastEvent,
+        error: agent.error || null,
+        hasResult: Boolean(agent.result || agent.lastResult),
+        messages: Array.isArray(agent.messages) ? agent.messages.length : 0,
+        turns: agent.usage?.turns || 0,
         createdAt: agent.createdAt,
       });
     }
@@ -43,7 +70,9 @@ and message counts. Use to monitor parallel task progress.`,
     if (agentList.length === 0) {
       return JSON.stringify({
         agents: [],
-        message: 'No active sub-agents',
+        message: includeTerminal
+          ? 'No sub-agents in the registry'
+          : 'No active sub-agents (pass include_closed=true to see terminal ones)',
       });
     }
 

package/yeaft/tools/send-message.js

@@ -6,7 +6,8 @@
  */
 
 import { defineTool } from './types.js';
-import { getAgentRegistry } from './agent.js';
+import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
+import { isTerminalAgentStatus, isPromptableAgentStatus, STATUS, describeAgentStatus } from '../sub-agent/status.js';
 
 export default defineTool({
   name: 'PromptAgent',
@@ -21,7 +22,10 @@ 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.`,
+SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.
+
+PromptAgent is rejected if the sub-agent is in a terminal state
+(completed/failed/closed/abandoned). Use SpawnAgent to start a fresh one.`,
   parameters: {
     type: 'object',
     properties: {
@@ -56,17 +60,38 @@ SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to us
     if (!agent) {
       return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent not found: ${agent_id}` });
     }
+    if (!agentBelongsToCaller(agent, ctx)) {
+      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent not found: ${agent_id}` });
+    }
 
-    if (agent.status === 'closed') {
-      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent "${agent.name}" is closed` });
+    if (isTerminalAgentStatus(agent.status)) {
+      // Build a specific error message per status. Telling the model
+      // "agent is closed" vs "agent failed: <error>" vs "agent was
+      // abandoned (idle too long)" gives it a clear next action.
+      const desc = describeAgentStatus(agent.status);
+      const detail = agent.status === STATUS.FAILED && agent.error
+        ? `: ${agent.error}`
+        : '';
+      return JSON.stringify({
+        next_steps: ERROR_NEXT_STEPS,
+        error: `Agent "${agent.name}" is ${desc}${detail}. Spawn a new agent if you need more work.`,
+        agentId: agent_id,
+        status: agent.status,
+      });
     }
-    if (agent.status === 'failed') {
-      return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: `Agent "${agent.name}" has failed: ${agent.error || 'unknown error'}` });
+
+    if (!isPromptableAgentStatus(agent.status)) {
+      // Defensive — covers any future status that isn't terminal but
+      // also isn't ready for prompts.
+      return JSON.stringify({
+        next_steps: ERROR_NEXT_STEPS,
+        error: `Agent "${agent.name}" is in status "${agent.status}", which does not accept new prompts.`,
+        agentId: agent_id,
+      });
     }
 
-    // PR-M1: queue as a pending prompt the driver will pull. This wakes
-    // the driver out of its idle wait and starts a new turn. The 'active'
-    // status alias kept for backward-compat with code that polls for it.
+    // Queue as a pending prompt the driver will pull. This wakes the
+    // driver out of its idle wait and starts a new turn.
     if (!Array.isArray(agent.pendingPrompts)) agent.pendingPrompts = [];
     agent.pendingPrompts.push(message);
     agent.messages.push({
@@ -74,8 +99,8 @@ SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to us
       content: message,
       timestamp: Date.now(),
     });
-    if (agent.status === 'idle' || agent.status === 'created') {
-      agent.status = 'running';
+    if (agent.status === STATUS.IDLE || agent.status === STATUS.CREATED) {
+      agent.status = STATUS.RUNNING;
     }
 
     return JSON.stringify({