@yeaft/webchat-agent 0.1.769 → 0.1.771

package/package.json

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

package/unify/vp-status-broker.js

@@ -0,0 +1,216 @@
+/**
+ * vp-status-broker.js — single source of truth for per-VP status,
+ * emitted to the frontend on every transition.
+ *
+ * Why: the browser used to reverse-infer VP status from assistant
+ * messages' `isStreaming` flag (web/stores/helpers/vp-timeline.js).
+ * That flag is a UI artifact, not a state machine — whenever the
+ * `result` event lands without flipping the flag (reconnect mid-turn,
+ * tool window where the flag is cosmetically dropped, persisted
+ * history that re-hydrates with the flag absent), the inferred
+ * status drifts and can stay stuck on "streaming" forever.
+ *
+ * This broker owns a tiny in-memory table keyed by `(groupId, vpId)`,
+ * and emits a `vp_status_changed` event each time the state really
+ * changes. `vp_status_snapshot` rebuilds the table on a fresh
+ * frontend (reconnect, refresh). The broker is in-memory only —
+ * agent restart starts everyone at `idle`, which is the right default
+ * because no turn is in flight on a fresh process either.
+ *
+ * State machine: see docs/notes/2026-05-15-vp-status-from-agent.md.
+ *
+ * Sink injection: the broker is constructed with a `send` callback so
+ * it doesn't depend on the WebSocket layer directly (and so tests can
+ * collect emitted events into an array without spinning up WS).
+ */
+
+/**
+ * Valid status values. `error` is a terminal/sticky state that the
+ * caller is expected to transition out of (the broker doesn't
+ * auto-decay — that policy belongs to the caller / web bridge).
+ * @type {ReadonlySet<string>}
+ */
+export const VALID_STATES = new Set([
+  'idle',
+  'typing',
+  'thinking',
+  'streaming',
+  'tool',
+  'error',
+]);
+
+/**
+ * @typedef {Object} VpStatusEntry
+ * @property {string} state    — one of VALID_STATES
+ * @property {number} since    — ms timestamp the state was entered
+ * @property {string|null} turnId
+ */
+
+/**
+ * Create a broker instance.
+ *
+ * @param {object} opts
+ * @param {(event: object) => void} opts.send  — emits events to the
+ *   wire (web bridge wraps `sendUnifyEvent`). Must be synchronous; the
+ *   broker calls it inline so transitions are flushed in order.
+ * @param {() => number} [opts.now]            — clock, defaults to
+ *   `Date.now`. Injected so tests can pin timestamps.
+ */
+export function createVpStatusBroker({ send, now = Date.now } = {}) {
+  if (typeof send !== 'function') {
+    throw new TypeError('createVpStatusBroker: `send` callback is required');
+  }
+
+  /**
+   * `${groupId}::${vpId}` → VpStatusEntry. Composite key because the
+   * same vpId can appear in multiple groups; we track them separately
+   * so the frontend's per-group timeline reads only its slice.
+   * @type {Map<string, VpStatusEntry & {groupId: string, vpId: string}>}
+   */
+  const table = new Map();
+
+  const keyOf = (groupId, vpId) => `${groupId || ''}::${vpId}`;
+
+  /**
+   * Apply a state transition. Idempotent: a no-op if the requested
+   * state is already current (no event emitted, no `since` rewrite).
+   * Validates the input state — unknown values throw, so a typo
+   * fails loudly in the agent log instead of silently breaking the
+   * UI's render.
+   *
+   * @param {object} args
+   * @param {string} args.groupId
+   * @param {string} args.vpId
+   * @param {string} args.state     — must be in VALID_STATES
+   * @param {string|null} [args.turnId]  — optional, for non-idle states
+   * @returns {boolean}             — true if a change was emitted
+   */
+  function transition({ groupId, vpId, state, turnId = null }) {
+    if (!vpId) return false;
+    if (!VALID_STATES.has(state)) {
+      throw new RangeError(`vp-status-broker: invalid state '${state}'`);
+    }
+    const key = keyOf(groupId, vpId);
+    const prev = table.get(key);
+    // Dedup: same state AND same turnId means no real transition.
+    // Allowing turnId to differ even at the same state lets a fresh
+    // turn re-stamp `since` without spamming events.
+    if (prev && prev.state === state && prev.turnId === turnId) {
+      return false;
+    }
+    const since = now();
+    const entry = { state, since, turnId, groupId: groupId || null, vpId };
+    table.set(key, entry);
+    send({
+      type: 'vp_status_changed',
+      groupId: entry.groupId,
+      vpId,
+      state,
+      since,
+      turnId,
+    });
+    return true;
+  }
+
+  /**
+   * Convenience: force `idle` regardless of current state. Used by
+   * the run-vp-turn `finally` block so a turn that ended via *any*
+   * path (normal, abort, error, watchdog escalation) always settles
+   * back to idle.
+   */
+  function settleIdle({ groupId, vpId }) {
+    return transition({ groupId, vpId, state: 'idle', turnId: null });
+  }
+
+  /**
+   * Build the snapshot payload. Optionally filtered by groupId.
+   *
+   * Filtering semantics:
+   *   - `groupId === undefined` → return every row across every group.
+   *     This is the all-groups broadcast used on `session_ready`.
+   *   - `groupId === null`      → same as undefined. Treated as "no
+   *     scope" because the wire envelope serializes `undefined` as
+   *     `null` over JSON, and we want both forms to behave the same.
+   *   - `groupId === '<id>'`    → only rows for that group.
+   *
+   * The store mirrors this semantic on the frontend (see
+   * `vp_status_snapshot` handler in chat.js): scoped snapshots
+   * replace just that group's slice, while null/undefined snapshots
+   * replace the whole table.
+   *
+   * @param {string} [groupId]
+   * @returns {Array<{vpId:string, state:string, since:number, turnId:string|null, groupId:string|null}>}
+   */
+  function snapshot(groupId) {
+    const out = [];
+    for (const entry of table.values()) {
+      if (groupId !== undefined && groupId !== null && entry.groupId !== groupId) continue;
+      out.push({
+        vpId: entry.vpId,
+        state: entry.state,
+        since: entry.since,
+        turnId: entry.turnId,
+        groupId: entry.groupId,
+      });
+    }
+    return out;
+  }
+
+  /**
+   * Emit a `vp_status_snapshot` to the wire. Pulls from `snapshot()`
+   * so the wire shape stays consistent with the in-memory table.
+   *
+   * Wire envelope: `{ type, groupId, statuses }` where `groupId` is
+   * `null` when unscoped (frontend uses null to mean "replace the
+   * whole table"). See `snapshot()` JSDoc for the scoping contract.
+   */
+  function broadcastSnapshot({ groupId } = {}) {
+    send({
+      type: 'vp_status_snapshot',
+      groupId: groupId === undefined ? null : groupId,
+      statuses: snapshot(groupId),
+    });
+  }
+
+  /**
+   * Drop an entry — e.g. when a VP is removed from a group. Without
+   * this, a deleted VP would stay in the snapshot forever and
+   * re-appear on the frontend at every reconnect.
+   */
+  function forget({ groupId, vpId }) {
+    table.delete(keyOf(groupId, vpId));
+  }
+
+  /**
+   * Wipe the in-memory table. Called from `resetUnifySession` on the
+   * agent side so a forced session reset doesn't leave the broker
+   * holding rows for VPs whose engines/inboxes have been cleared. The
+   * post-reset `broadcastSnapshot` then emits an empty table, and the
+   * frontend's mirror clears in lockstep.
+   *
+   * Distinct from `__testReset`: this is production code path, named
+   * accordingly. `__testReset` stays for tests that mutate broker
+   * state across describe-blocks.
+   */
+  function reset() {
+    table.clear();
+  }
+
+  /**
+   * Wipe everything (only used by tests; agent runtime keeps the
+   * broker alive for the whole process).
+   */
+  function __testReset() {
+    table.clear();
+  }
+
+  return {
+    transition,
+    settleIdle,
+    snapshot,
+    broadcastSnapshot,
+    forget,
+    reset,
+    __testReset,
+  };
+}

package/unify/web-bridge.js

@@ -50,6 +50,7 @@ import {
 } from './history-compact.js';
 import { persistUnifyAttachments, attachmentsForPersistence } from './attachments.js';
 import { parseSeqFromId } from './conversation/persist.js';
+import { createVpStatusBroker } from './vp-status-broker.js';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -78,6 +79,43 @@ let currentAbortCtrl = null;
  */
 const turnAbortCtrls = new Map();
 
+/**
+ * Per-VP status broker — the agent-side authority for VP timeline
+ * status. Lazy-initialized on first use because `sendUnifyEvent` is
+ * declared below; trying to call it at module top-level would crash
+ * with a TDZ error during agent boot.
+ *
+ * Every transition (typing → thinking → streaming → tool → idle) is
+ * pushed through `vpStatusBroker.transition(...)`. The broker also
+ * owns the `vp_status_snapshot` payload for reconnect.
+ *
+ * @type {ReturnType<typeof createVpStatusBroker> | null}
+ */
+let vpStatusBroker = null;
+function getVpStatusBroker() {
+  if (!vpStatusBroker) {
+    vpStatusBroker = createVpStatusBroker({
+      send: (event) => {
+        // The broker emits both `vp_status_changed` and
+        // `vp_status_snapshot`. Both ride the standard sendUnifyEvent
+        // envelope so the frontend's existing unify_output dispatcher
+        // sees them. We stamp groupId/vpId on the envelope for
+        // events that target a specific VP so the server's per-client
+        // routing (groupId scoping, etc.) works the same way as
+        // typing events.
+        const env = {};
+        if (event && typeof event === 'object') {
+          if (event.groupId) env.groupId = event.groupId;
+          if (event.vpId) env.vpId = event.vpId;
+          if (event.turnId) env.turnId = event.turnId;
+        }
+        sendUnifyEvent(event, env);
+      },
+    });
+  }
+  return vpStatusBroker;
+}
+
 /**
  * Per-VP inbox + driver + engine pool (group multi-VP delivery).
  *
@@ -573,6 +611,15 @@ function enqueueForVp(groupId, vpId, envelope) {
     }, { groupId, vpId, turnId });
   } catch { /* never crash WS pipeline */ }
 
+  // vp-status: queued, driver not running yet → 'typing'. Emitted
+  // alongside `vp_typing_start` so the timeline pane lights up on the
+  // same edge as the per-message typing dot.
+  try {
+    getVpStatusBroker().transition({ groupId, vpId, state: 'typing', turnId });
+  } catch (err) {
+    console.warn('[Unify] vp-status typing transition failed:', err?.message || err);
+  }
+
   ensureDriverRunning(groupId, vpId);
 }
 
@@ -864,6 +911,18 @@ export function handleUnifyVpDelete(msg) {
     const yeaftDir = ctx.CONFIG?.yeaftDir;
     const memoryRoot = yeaftDir ? join(yeaftDir, 'memory') : undefined;
     deleteVp(vpId, memoryRoot ? { memoryRoot } : {});
+    // vp-status: a deleted VP must not haunt the snapshot. We don't
+    // know up front which groups the VP appeared in (the registry's
+    // delete already detached it from every group), so sweep every
+    // matching entry from the broker table.
+    try {
+      const broker = getVpStatusBroker();
+      for (const row of broker.snapshot()) {
+        if (row.vpId === vpId) broker.forget({ groupId: row.groupId, vpId });
+      }
+    } catch (err) {
+      console.warn('[Unify] vp-status forget on delete failed:', err?.message || err);
+    }
     sendVpCrudResult({ op: 'delete', requestId, ok: true, vpId });
   } catch (err) {
     sendVpCrudResult({
@@ -1165,6 +1224,29 @@ export function installUnifyRuntimeBridge(s) {
   };
 }
 
+/**
+ * Mid-turn vp-status transitions (text_delta / tool_call / tool_end).
+ * Tolerates `hctx` missing groupId/vpId — pre-707 1:1 chat paths don't
+ * have either; they're tracked as the default broker key but the
+ * frontend ignores rows it doesn't recognize.
+ *
+ * @param {object} hctx
+ * @param {string} state
+ */
+function maybeTransitionVpStatus(hctx, state) {
+  if (!hctx || !hctx.vpId) return;
+  try {
+    getVpStatusBroker().transition({
+      groupId: hctx.groupId || null,
+      vpId: hctx.vpId,
+      state,
+      turnId: hctx.turnId || null,
+    });
+  } catch (err) {
+    console.warn(`[Unify] vp-status ${state} transition failed:`, err?.message || err);
+  }
+}
+
 /**
  * Handle a single engine event unwrapped from an `engine_event` envelope.
  * H2.f.2: no longer stamps a threadId on outgoing claude_output frames.
@@ -1187,6 +1269,10 @@ function handleEngineEvent(event, hctx) {
         type: 'assistant',
         message: { content: [{ type: 'text', text: event.text }] },
       }, envelope);
+      // vp-status: first text-delta of a (thinking|tool) phase flips
+      // the row to 'streaming'. transition() is a no-op when already
+      // streaming, so subsequent deltas are cheap.
+      maybeTransitionVpStatus(hctx, 'streaming');
       break;
 
     case 'thinking_delta':
@@ -1220,6 +1306,7 @@ function handleEngineEvent(event, hctx) {
           }],
         },
       }, envelope);
+      maybeTransitionVpStatus(hctx, 'tool');
       break;
 
     case 'tool_start':
@@ -1248,6 +1335,12 @@ function handleEngineEvent(event, hctx) {
           is_error: event.isError || false,
         }],
       }, envelope);
+      // Tool finished. The engine may either (a) emit more text-deltas
+      // before end_turn, or (b) go straight to end_turn. Settle the
+      // row back to 'thinking' — if (a), the next text_delta will flip
+      // it to 'streaming'; if (b), runVpTurn's finally will flip it to
+      // 'idle'. Either way we never strand the row in 'tool'.
+      maybeTransitionVpStatus(hctx, 'thinking');
       break;
 
     case 'turn_start':
@@ -1964,6 +2057,15 @@ async function ensureSessionLoaded() {
     tools: session.status.tools,
   });
   sendGroupSnapshotBroadcast();
+  // vp-status: rebuild frontend status table from authoritative agent
+  // memory. Sent unconditionally so reconnect/refresh paths get the same
+  // bootstrap as first-load (the broker dedup logic makes a redundant
+  // snapshot harmless).
+  try {
+    getVpStatusBroker().broadcastSnapshot();
+  } catch (err) {
+    console.warn('[Unify] vp-status snapshot broadcast failed:', err?.message || err);
+  }
 }
 
 /**
@@ -2008,6 +2110,19 @@ async function runVpTurnWithEscalation(args) {
           { groupId, vpId, turnId },
         );
       } catch { /* never crash WS pipeline */ }
+      // vp-status: when the watchdog escalates, `runVpTurn`'s inner
+      // promise is still dangling (the adapter is ignoring `signal`)
+      // and its outer `finally` won't run until the adapter eventually
+      // returns — which may be never. Settle the broker here so the
+      // row drops to idle in lockstep with the synthetic stop frame.
+      // This is the exact failure mode the watchdog exists for; not
+      // settling here would re-introduce the "stuck on streaming" bug
+      // the whole PR is meant to fix.
+      try {
+        getVpStatusBroker().settleIdle({ groupId, vpId });
+      } catch (err) {
+        console.warn('[Unify] vp-status settleIdle (escalation) failed:', err?.message || err);
+      }
     },
   });
 }
@@ -2099,6 +2214,12 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
 
     // Emit turn_start so frontend can create the message block.
     sendUnifyEvent({ type: 'vp_turn_start', vpId, turnId, groupId }, envelope);
+    // vp-status: LLM call about to start, no text/tool yet → 'thinking'.
+    try {
+      getVpStatusBroker().transition({ groupId, vpId, state: 'thinking', turnId });
+    } catch (err) {
+      console.warn('[Unify] vp-status thinking transition failed:', err?.message || err);
+    }
 
     try {
       const assistantTextParts = [];
@@ -2184,6 +2305,17 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
 
     console.error('[Unify] query error:', err);
 
+    // vp-status: surface a transient `error` state so the row's status
+    // label flips red for the brief window before the outer finally
+    // settles it to idle. Without this, an LLM/tool failure would look
+    // identical to a normal turn end in the timeline — the user has
+    // no way to tell from the row that something went wrong.
+    try {
+      getVpStatusBroker().transition({ groupId, vpId, state: 'error', turnId });
+    } catch (brokerErr) {
+      console.warn('[Unify] vp-status error transition failed:', brokerErr?.message || brokerErr);
+    }
+
     if (isPermissionErrorMsg(err.message)) {
       if (!_permissionDiagnosticSent) {
         _permissionDiagnosticSent = true;
@@ -2212,6 +2344,16 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
       type: 'result',
       result_text: '',
     }, envelope);
+  } finally {
+    // vp-status: guaranteed-settle. Regardless of how the turn exited
+    // (normal completion, AbortError early-return, caught exception),
+    // the row must drop back to 'idle'. Wrapped in its own try so a
+    // broker bug can't mask the original error.
+    try {
+      getVpStatusBroker().settleIdle({ groupId, vpId });
+    } catch (err) {
+      console.warn('[Unify] vp-status settleIdle failed:', err?.message || err);
+    }
   }
 }
 
@@ -2693,6 +2835,14 @@ export async function handleUnifyLoadHistory(msg) {
     tools: session.status.tools,
   });
   sendGroupSnapshotBroadcast();
+  // vp-status: replay the authoritative table on reconnect so a refreshed
+  // frontend doesn't have to wait for the next transition to learn each
+  // VP's current state.
+  try {
+    getVpStatusBroker().broadcastSnapshot();
+  } catch (err) {
+    console.warn('[Unify] vp-status snapshot broadcast (replay) failed:', err?.message || err);
+  }
 
   // `msg.limit` is the replay-scrollback request from the frontend (UI
   // history pane, not engine context). Semantics changed (2026-05-01):
@@ -2865,6 +3015,16 @@ export async function resetUnifySession() {
   // History-dedup cache is keyed by per-session coordinator msg ids;
   // a fresh session resets the id space, so clear the cache too.
   _persistedUserMsgIds.clear();
+  // vp-status: nuke the broker table too. Drivers above have just
+  // been aborted, so any in-flight `settleIdle` from their outer
+  // `finally` blocks is racing this reset. Clearing here makes the
+  // post-reset `broadcastSnapshot` (further down) emit an empty
+  // table, and the frontend mirror clears in lockstep.
+  try {
+    getVpStatusBroker().reset();
+  } catch (err) {
+    console.warn('[Unify] vp-status broker reset failed:', err?.message || err);
+  }
 
   try {
     const yeaftDir = ctx.CONFIG?.yeaftDir;
@@ -2890,6 +3050,14 @@ export async function resetUnifySession() {
       mcpServers: session.status.mcpServers,
       tools: session.status.tools,
     });
+    // vp-status: after a forced reset the broker table is still live in
+    // memory; broadcast so the frontend can rebuild its mirror without
+    // waiting for the first per-VP transition.
+    try {
+      getVpStatusBroker().broadcastSnapshot();
+    } catch (err) {
+      console.warn('[Unify] vp-status snapshot broadcast (reset) failed:', err?.message || err);
+    }
   } catch (err) {
     console.error('[Unify] Failed to re-initialize session after reset:', err.message);
   }