@yeaft/webchat-agent 0.1.524 → 0.1.525

package/package.json

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

package/unify/vp/vp-bridge.js

@@ -1,9 +1,5 @@
 /**
- * vp-bridge.js — task-334-ui-a snapshot-only WS adapter.
- *
- * Per ruling .crew/context/task-334-ui-a-ruling.md §3 (D3 = mixed):
- *   • snapshot path lives here (this slice, in-scope)
- *   • live diff (vp_updated / vp_removed) deferred to 334h — see TODO below
+ * vp-bridge.js — task-334-ui-a snapshot + task-334h live-diff WS adapter.
  *
  * This module is the SOLE serialiser for the wire-format VP shape.
  * Per ruling §1 (D1 = (b) web-bridge boundary rename), the entity layer
@@ -12,10 +8,17 @@
  *
  * Per ruling §2 (D2):
  *   • subtitle  → agent emits `vp.role` directly
- *   • personaHash → agent emits `vp.personaHash` (added by dev-1's
- *     334a-followup patch). Until that lands, this serialiser falls back
- *     to undefined and the web layer simply omits the field.
+ *   • personaHash → agent emits `vp.personaHash`
  *   • color / avatar → web-derived, NOT emitted here
+ *
+ * task-334h — live diff:
+ *   • subscribers (Set of sendUnifyEvent fns) receive per-vp `vp_updated`
+ *     and `vp_removed` events as VpLoader's debounced rescan commits
+ *     added / updated / removed vpIds.
+ *   • Event shape: `{ type, vpId, vp?, reason? }` where `reason` ∈
+ *     { 'persona.edit', 'traits.edit', 'manual.reload', 'file.removed' }.
+ *   • Back-compat: `vp_snapshot` shape unchanged; `reason` is purely
+ *     additive so older web clients ignore it.
  */
 
 import { defaultRegistry } from './registry.js';
@@ -25,12 +28,132 @@ import { VpLoader } from './vp-loader.js';
 let _loaderStarted = false;
 let _loader = null;
 
-function ensureLoader() {
+/**
+ * Broadcast fan-out. VpLoader.onChange fires once per debounce batch for the
+ * whole process, so every active subscriber must receive each live-diff event.
+ * @type {Set<(event:object)=>void>}
+ */
+const _subscribers = new Set();
+
+/**
+ * Last-seen persona snapshot per vpId, used to classify `reason` when an
+ * `updated` entry arrives from VpLoader. We cache only the minimal fields we
+ * compare against, never the VP reference (identity is stable via
+ * registry.updateVpInPlace, so by the time onChange fires the registry
+ * already holds the new values — we must remember the *previous* values).
+ *
+ * Shape: vpId → { persona: string, traits: string[] }
+ * @type {Map<string, {persona:string, traits:string[]}>}
+ */
+const _prevState = new Map();
+
+function tsnap(vp) {
+  return {
+    persona: vp && typeof vp.persona === 'string' ? vp.persona : '',
+    traits: Array.isArray(vp && vp.traits) ? vp.traits.slice() : [],
+  };
+}
+
+function traitsEqual(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return a === b;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * Pure reason classifier. Exposed for unit tests.
+ *
+ * @param {{persona:string, traits:string[]}|undefined} prev
+ * @param {{persona?:string, traits?:string[]}|undefined} next
+ * @returns {'persona.edit'|'traits.edit'|'manual.reload'}
+ */
+export function classifyUpdateReason(prev, next) {
+  if (!prev || !next) return 'manual.reload';
+  const prevPersona = prev.persona || '';
+  const nextPersona = typeof next.persona === 'string' ? next.persona : '';
+  if (prevPersona !== nextPersona) return 'persona.edit';
+  if (!traitsEqual(prev.traits || [], next.traits || [])) return 'traits.edit';
+  return 'manual.reload';
+}
+
+/** Seed / refresh `_prevState` for a given registry. */
+function captureState(registry) {
+  _prevState.clear();
+  for (const vp of registry.listVps()) {
+    _prevState.set(vp.id, tsnap(vp));
+  }
+}
+
+/**
+ * onChange callback bound to the process-singleton VpLoader. Translates the
+ * `{added, updated, removed}` summary into per-vpId wire events and
+ * broadcasts them to every active subscriber.
+ *
+ * @param {{added:string[],updated:string[],removed:string[]}} summary
+ * @param {import('./registry.js').Registry} registry
+ */
+function broadcastChange(summary, registry) {
+  if (!summary || _subscribers.size === 0) {
+    // Still must refresh state so a later subscriber doesn't mis-classify.
+    captureState(registry);
+    return;
+  }
+
+  // Removed → vp_removed
+  for (const vpId of summary.removed || []) {
+    const evt = { type: 'vp_removed', vpId, reason: 'file.removed' };
+    _fanout(evt);
+    _prevState.delete(vpId);
+  }
+
+  // Added → vp_updated (no prev state yet, so reason = 'manual.reload').
+  for (const vpId of summary.added || []) {
+    const vp = registry.getVp(vpId);
+    if (!vp) continue;
+    const evt = {
+      type: 'vp_updated',
+      vpId,
+      vp: serializeVpForWire(vp),
+      reason: 'manual.reload',
+    };
+    _fanout(evt);
+    _prevState.set(vpId, tsnap(vp));
+  }
+
+  // Updated → classify against cached prev state.
+  for (const vpId of summary.updated || []) {
+    const vp = registry.getVp(vpId);
+    if (!vp) continue;
+    const prev = _prevState.get(vpId);
+    const reason = classifyUpdateReason(prev, vp);
+    const evt = {
+      type: 'vp_updated',
+      vpId,
+      vp: serializeVpForWire(vp),
+      reason,
+    };
+    _fanout(evt);
+    _prevState.set(vpId, tsnap(vp));
+  }
+}
+
+function _fanout(evt) {
+  for (const fn of _subscribers) {
+    try { fn(evt); } catch { /* never crash the loader from a subscriber */ }
+  }
+}
+
+function ensureLoader(registry = defaultRegistry) {
   if (_loaderStarted) return _loader;
   _loaderStarted = true;
   try {
-    _loader = new VpLoader({ registry: defaultRegistry });
+    _loader = new VpLoader({
+      registry,
+      onChange: (summary) => broadcastChange(summary, registry),
+    });
     _loader.start();
+    captureState(registry);
   } catch {
     // Hot-reload optional; subscribe still returns whatever scan loaded.
     _loader = null;
@@ -73,25 +196,31 @@ export function buildVpSnapshot(registry = defaultRegistry) {
 
 /**
  * Handle an `unify_vp_subscribe` request from the web client.
- * Lazily starts the VpLoader on first call (debounced rescan watchers).
  *
- * @param {(event: object) => void} sendUnifyEvent — emit fn (web-bridge wires this)
+ * Registers `sendUnifyEvent` as a live-diff subscriber, emits an initial
+ * `vp_snapshot`, and (on first call process-wide) starts the VpLoader
+ * whose debounced rescan fans out `vp_updated` / `vp_removed` events.
+ *
+ * Returns an unsubscribe fn the caller MAY invoke on WS close to prevent
+ * sending to a dead socket. Web-bridge is expected to manage this.
+ *
+ * @param {(event: object) => void} sendUnifyEvent
  * @param {import('./registry.js').Registry} [registry]
+ * @returns {() => void} unsubscribe fn
  */
 export function handleVpSubscribe(sendUnifyEvent, registry = defaultRegistry) {
-  ensureLoader();
+  ensureLoader(registry);
+  _subscribers.add(sendUnifyEvent);
   try {
     sendUnifyEvent(buildVpSnapshot(registry));
   } catch {
     // Never crash the WS pipeline from snapshot serialisation.
   }
-  // TODO(334h): vp_updated / vp_removed live broadcast.
-  // Wire VpLoader.onChange → emit per-vp `vp_updated` and `vp_removed`
-  // events using serializeVpForWire(). Out of scope for 334-ui-a.
+  return () => { _subscribers.delete(sendUnifyEvent); };
 }
 
 /**
- * Test seam: reset the lazy loader (for vitest).
+ * Test seam: reset the lazy loader + subscriber set + state cache.
  */
 export function _resetVpBridgeForTest() {
   if (_loader) {
@@ -99,4 +228,22 @@ export function _resetVpBridgeForTest() {
   }
   _loader = null;
   _loaderStarted = false;
+  _subscribers.clear();
+  _prevState.clear();
+}
+
+/**
+ * Test seam: manually drive broadcast (bypasses VpLoader so tests don't need
+ * a real filesystem). Used by the live-diff unit test.
+ */
+export function _broadcastChangeForTest(summary, registry = defaultRegistry) {
+  broadcastChange(summary, registry);
+}
+
+/**
+ * Test seam: pre-seed `_prevState` so classifyUpdateReason has something to
+ * compare against when a test drives `_broadcastChangeForTest` directly.
+ */
+export function _seedPrevStateForTest(registry = defaultRegistry) {
+  captureState(registry);
 }

package/unify/web-bridge.js

@@ -105,9 +105,10 @@ function sendUnifyEvent(event) {
 }
 
 /**
- * task-334-ui-a: respond to `unify_vp_subscribe` from the web client by
- * pushing a one-shot `vp_snapshot` event. Live diff (vp_updated /
- * vp_removed) is intentionally deferred to 334h per ruling §3.
+ * task-334-ui-a + task-334h: respond to `unify_vp_subscribe` from the web
+ * client by pushing a one-shot `vp_snapshot` event AND registering this
+ * socket as a live-diff subscriber. VpLoader's debounced rescan fans out
+ * `vp_updated` / `vp_removed` events to every active subscriber.
  */
 export function handleUnifyVpSubscribe(_msg) {
   handleVpSubscribe(sendUnifyEvent);