@yeaft/webchat-agent 0.1.526 → 0.1.528

package/connection/message-router.js

@@ -36,7 +36,7 @@ import { sendToServer, flushMessageBuffer } from './buffer.js';
 import { handleRestartAgent, handleUpgradeAgent } from './upgrade.js';
 import { loadMcpServers, updateMcpConfig } from '../mcp.js';
 import { getLlmConfig, updateLlmConfig, getUnifySettings, updateUnifySettings } from '../unify/config-api.js';
-import { handleUnifyChat, handleUnifyModeSwitch, handleUnifyModelSwitch, resetUnifySession, handleUnifyLoadHistory, handleUnifyMergeThread, handleUnifyForkThread, handleUnifyAbortThread, handleUnifyAbortAll, handleUnifyVpSubscribe } from '../unify/web-bridge.js';
+import { handleUnifyChat, handleUnifyModeSwitch, handleUnifyModelSwitch, resetUnifySession, handleUnifyLoadHistory, handleUnifyMergeThread, handleUnifyForkThread, handleUnifyAbortThread, handleUnifyAbortAll, handleUnifyVpSubscribe, handleUnifyVpCreate, handleUnifyVpUpdate, handleUnifyVpDelete, handleUnifyVpRead } from '../unify/web-bridge.js';
 
 export async function handleMessage(msg) {
   switch (msg.type) {
@@ -403,6 +403,23 @@ export async function handleMessage(msg) {
       handleUnifyVpSubscribe(msg);
       break;
 
+    // task-334-ui-g: VP CRUD (create / update / delete / read-single).
+    // All four reply via `vp_crud_result`; VpLoader's rescan emits the
+    // authoritative `vp_updated` / `vp_removed` events so the store stays
+    // in sync without a bespoke ack path.
+    case 'unify_vp_create':
+      handleUnifyVpCreate(msg);
+      break;
+    case 'unify_vp_update':
+      handleUnifyVpUpdate(msg);
+      break;
+    case 'unify_vp_delete':
+      handleUnifyVpDelete(msg);
+      break;
+    case 'unify_vp_read':
+      handleUnifyVpRead(msg);
+      break;
+
     // Expert roles definition (for ExpertPanel detail view)
     case 'get_expert_roles': {
       const { getExpertRolesDefinition } = await import('../expert-roles.js');

package/package.json

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

package/unify/routing/index.js

@@ -15,5 +15,7 @@ export {
   MAX_CHAIN_DEPTH,
   DEFAULT_WINDOW_MS,
   DEFAULT_MAX_HITS_PER_WINDOW,
+  DEFAULT_MAX_KEYS,
+  DEFAULT_TTL_MULTIPLIER,
 } from './loop-guard.js';
 export { createRouter } from './router.js';

package/unify/routing/loop-guard.js

@@ -18,6 +18,22 @@
  * The guard is a pure in-memory helper — no persistence — because the
  * threat model is one runaway turn storm within a single process tick.
  *
+ * Long-running process hygiene (N1, task-334d-followup):
+ *   The `hits` Map is keyed by "groupId::vpId" and would otherwise grow
+ *   unboundedly over a long session. Two complementary bounds:
+ *     - TTL sweep: on each NEW key insert, drop entries whose most
+ *       recent hit is older than `ttlMultiplier × windowMs` (default 2×).
+ *       Those entries can never throttle anyone regardless — their rate
+ *       window is already fully expired. Amortised O(n) but only on new
+ *       keys, so normal hot-path cost stays O(1).
+ *     - LRU cap: after the TTL sweep, if size > maxKeys (default 1000)
+ *       the Map's insertion-order head (oldest-used key) is evicted until
+ *       back under the cap. `check()` and `record()` both `touch()` a key
+ *       (delete+re-set) so recency is refreshed on every access.
+ *   Behavior invariants preserved: the `'all'` broadcast sentinel, the
+ *   `now()` injection seam, and the chain-depth check are untouched — only
+ *   the eviction path is new.
+ *
  * Integration contract (routing/router.js):
  *   - router stamps envelope.meta.causedBy = [...prevChain, currentMsgId]
  *   - router calls `guard.check({ groupId, targetVpId, chain })` BEFORE
@@ -30,6 +46,8 @@
 export const MAX_CHAIN_DEPTH = 10;
 export const DEFAULT_WINDOW_MS = 5_000;
 export const DEFAULT_MAX_HITS_PER_WINDOW = 8;
+export const DEFAULT_MAX_KEYS = 1_000;
+export const DEFAULT_TTL_MULTIPLIER = 2;
 
 /**
  * Build a new loop guard. Safe to share across a single web-bridge process.
@@ -38,17 +56,24 @@ export const DEFAULT_MAX_HITS_PER_WINDOW = 8;
  *   maxChainDepth?: number,
  *   windowMs?: number,
  *   maxHitsPerWindow?: number,
- *   now?: () => number,   // injectable for tests
+ *   maxKeys?: number,                  // N1: LRU cap (default 1000)
+ *   ttlMultiplier?: number,            // N1: evict keys idle > ttlMultiplier*windowMs
+ *   now?: () => number,                // injectable for tests
  * }} [options]
  */
 export function createLoopGuard(options = {}) {
   const maxChainDepth = options.maxChainDepth ?? MAX_CHAIN_DEPTH;
   const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
   const maxHits = options.maxHitsPerWindow ?? DEFAULT_MAX_HITS_PER_WINDOW;
+  const maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS;
+  const ttlMultiplier = options.ttlMultiplier ?? DEFAULT_TTL_MULTIPLIER;
   const now = typeof options.now === 'function' ? options.now : Date.now;
 
-  /** Map<"groupId::vpId", number[]> — sorted ascending timestamps. */
+  /** Map<"groupId::vpId", number[]> — sorted ascending timestamps.
+   * Map insertion order doubles as LRU recency: touching (delete+set) on
+   * every access keeps the oldest-used entry at the front for eviction. */
   const hits = new Map();
+  let evictions = 0;
 
   function key(groupId, vpId) { return `${groupId}::${vpId}`; }
 
@@ -58,6 +83,47 @@ export function createLoopGuard(options = {}) {
     if (i > 0) arr.splice(0, i);
   }
 
+  /**
+   * Touch a key → move to the Map's insertion tail (most-recently-used).
+   * Used on BOTH check() and record() paths so a blocked-but-checked
+   * target is kept warm as long as something keeps referencing it.
+   */
+  function touch(k, arr) {
+    hits.delete(k);
+    hits.set(k, arr);
+  }
+
+  /**
+   * Opportunistic TTL sweep: drop keys whose last hit is older than
+   * ttlMultiplier × windowMs (i.e. their rate window is fully expired and
+   * stale). Called on insert to amortise cleanup across normal traffic,
+   * so we never scan on the hot read path.
+   */
+  function sweepExpired() {
+    const ttlCutoff = now() - ttlMultiplier * windowMs;
+    for (const [k, arr] of hits) {
+      // arr is sorted ascending; the tail is the most-recent hit.
+      const last = arr.length > 0 ? arr[arr.length - 1] : -Infinity;
+      if (last < ttlCutoff) {
+        hits.delete(k);
+        evictions += 1;
+      }
+    }
+  }
+
+  /**
+   * Enforce the hard LRU cap. Called on insert AFTER sweepExpired so
+   * only genuinely hot but stale-enough entries get evicted.
+   */
+  function enforceCap() {
+    while (hits.size > maxKeys) {
+      const oldest = hits.keys().next().value;
+      if (oldest === undefined) break;
+      hits.delete(oldest);
+      evictions += 1;
+    }
+  }
+
   return {
     /**
      * Check whether a forward to (groupId, vpId) with the supplied causedBy
@@ -83,6 +149,9 @@ export function createLoopGuard(options = {}) {
       if (arr) {
         const cutoff = now() - windowMs;
         trim(arr, cutoff);
+        // Refresh LRU recency — a repeatedly-probed hot target should not
+        // be evicted just because it never crosses into record().
+        touch(k, arr);
         if (arr.length >= maxHits) {
           return {
             ok: false,
@@ -99,6 +168,7 @@ export function createLoopGuard(options = {}) {
       if (!groupId || !targetVpId) return;
       const k = key(groupId, targetVpId);
       let arr = hits.get(k);
+      const creating = !arr;
       if (!arr) {
         arr = [];
         hits.set(k, arr);
@@ -106,17 +176,36 @@ export function createLoopGuard(options = {}) {
       const cutoff = now() - windowMs;
       trim(arr, cutoff);
       arr.push(now());
+      // Refresh LRU recency for both existing and new keys.
+      touch(k, arr);
+      // On *new* key creation, opportunistically clean up: first drop
+      // fully-expired entries (cheap, bounds unbounded growth), then
+      // enforce the hard cap. Skip on the update path to keep hot-loop
+      // cost O(1).
+      if (creating) {
+        sweepExpired();
+        enforceCap();
+      }
     },
 
     /** Snapshot for tests / debug. */
     snapshot() {
       const out = {};
       for (const [k, arr] of hits) out[k] = arr.slice();
-      return { hits: out, maxChainDepth, windowMs, maxHits };
+      return {
+        hits: out,
+        maxChainDepth,
+        windowMs,
+        maxHits,
+        maxKeys,
+        ttlMultiplier,
+        size: hits.size,
+        evictions,
+      };
     },
 
     /** Wipe all counters (tests). */
-    reset() { hits.clear(); },
+    reset() { hits.clear(); evictions = 0; },
   };
 }
 

package/unify/vp/vp-crud.js

@@ -0,0 +1,201 @@
+/**
+ * vp-crud.js — filesystem CRUD for VP library (task-334-ui-g).
+ *
+ * Writes / updates / deletes `<lib>/<vpId>/role.md`. VpLoader's hot-reload
+ * picks up the change on its next debounced rescan and fans out
+ * vp_updated / vp_removed WS events to subscribers (334h).
+ *
+ * Hard constraints:
+ *   (a) zero touch on ids.js contract — we only *read* validateVpId;
+ *   (b) zero modification to registry.js / roster.js internals — the
+ *       entity layer sees changes only via VpLoader rescan;
+ *   (c) no Storage-Layer (334o) imports — stays on the entity side.
+ *
+ * Error codes returned to the caller (wire-visible):
+ *   'duplicate'      — vpId already exists (on create)
+ *   'not_found'      — vpId does not exist on disk (on update/delete)
+ *   <reason from validateVpId> — invalid shape
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { validateVpId } from '../groups/ids.js';
+import { DEFAULT_VP_LIB_DIR, parseRoleMd } from './vp-store.js';
+
+/**
+ * Error thrown by CRUD entry points. Has stable `.code` so callers can map
+ * to i18n / WS payload without string-parsing the message.
+ */
+export class VpCrudError extends Error {
+  constructor(code, vpId, message) {
+    super(message || `${code}: ${vpId}`);
+    this.name = 'VpCrudError';
+    this.code = code;
+    this.vpId = vpId;
+  }
+}
+
+function ensureLibDir(libDir) {
+  if (!existsSync(libDir)) mkdirSync(libDir, { recursive: true });
+}
+
+function vpDirFor(libDir, vpId) {
+  return join(libDir, vpId);
+}
+
+function vpRolePathFor(libDir, vpId) {
+  return join(vpDirFor(libDir, vpId), 'role.md');
+}
+
+/**
+ * Serialise a VP payload into role.md text with YAML frontmatter matching
+ * the parser in vp-store.js.
+ *
+ * @param {{vpId:string, displayName?:string, role?:string, traits?:string[], modelHint?:string, persona?:string}} p
+ * @returns {string}
+ */
+export function buildRoleMd(p) {
+  const id = String(p.vpId);
+  const name = p.displayName != null ? String(p.displayName) : id;
+  const role = p.role != null ? String(p.role) : '';
+  const traits = Array.isArray(p.traits) ? p.traits.map(t => String(t)).filter(Boolean) : [];
+  const modelHint = p.modelHint === 'primary' || p.modelHint === 'fast' ? p.modelHint : null;
+  const body = typeof p.persona === 'string' ? p.persona : '';
+
+  const lines = ['---', `id: ${id}`, `name: ${yamlScalar(name)}`, `role: ${yamlScalar(role)}`];
+  if (modelHint) lines.push(`modelHint: ${modelHint}`);
+  if (traits.length > 0) {
+    lines.push('traits:');
+    for (const t of traits) lines.push(`  - ${yamlScalar(t)}`);
+  }
+  lines.push('---', '', body.trim(), '');
+  return lines.join('\n');
+}
+
+function yamlScalar(v) {
+  const s = String(v);
+  // Quote anything that the minimal parser might mis-read: colons, leading
+  // dashes, or surrounding whitespace. Plain text passes through unquoted.
+  if (/^[\s]|[\s]$|^[-:]|[:#]/.test(s)) {
+    return `"${s.replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+/**
+ * Create a new VP. Writes `<lib>/<vpId>/role.md` and ensures `memory/` dir.
+ *
+ * @param {object} payload
+ * @param {string} payload.vpId
+ * @param {string} [payload.displayName]
+ * @param {string} [payload.role]
+ * @param {string[]} [payload.traits]
+ * @param {'primary'|'fast'} [payload.modelHint]
+ * @param {string} [payload.persona]
+ * @param {object} [options]
+ * @param {string} [options.libDir]
+ * @returns {{vpId:string, dir:string}}
+ */
+export function createVp(payload, options = {}) {
+  const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
+  const vpId = payload && payload.vpId;
+
+  const v = validateVpId(vpId);
+  if (!v.ok) throw new VpCrudError(v.reason, vpId);
+
+  ensureLibDir(libDir);
+  const dir = vpDirFor(libDir, vpId);
+  if (existsSync(dir)) {
+    // Directory already present. Treat as duplicate regardless of whether
+    // role.md is inside — prevents CRUD stomping on a half-created entry
+    // or a user-authored dir with no frontmatter yet.
+    throw new VpCrudError('duplicate', vpId);
+  }
+
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(join(dir, 'memory'), { recursive: true });
+  writeFileSync(vpRolePathFor(libDir, vpId), buildRoleMd({ ...payload, vpId }), 'utf-8');
+  return { vpId, dir };
+}
+
+/**
+ * Update an existing VP. vpId is immutable — the dir is keyed by it; if the
+ * user wants a rename they must delete + create.
+ *
+ * @param {object} payload  same shape as createVp, vpId must match existing dir
+ * @param {object} [options]
+ * @returns {{vpId:string, dir:string}}
+ */
+export function updateVp(payload, options = {}) {
+  const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
+  const vpId = payload && payload.vpId;
+
+  const v = validateVpId(vpId);
+  if (!v.ok) throw new VpCrudError(v.reason, vpId);
+
+  const dir = vpDirFor(libDir, vpId);
+  if (!existsSync(dir) || !existsSync(vpRolePathFor(libDir, vpId))) {
+    throw new VpCrudError('not_found', vpId);
+  }
+  writeFileSync(vpRolePathFor(libDir, vpId), buildRoleMd({ ...payload, vpId }), 'utf-8');
+  return { vpId, dir };
+}
+
+/**
+ * Delete a VP — removes the entire VP dir (role.md + memory/).
+ *
+ * Hard constraint: `memory/` contents are scoped to this VP; removing them
+ * with the role is the intended CRUD semantic (UX rule is the confirm
+ * dialog upstream, not here).
+ *
+ * @param {string} vpId
+ * @param {object} [options]
+ * @returns {{vpId:string}}
+ */
+export function deleteVp(vpId, options = {}) {
+  const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
+  // We do NOT run validateVpId here — deleting an already-legacy bad id is
+  // legitimate cleanup. But we DO refuse obviously unsafe inputs.
+  if (!vpId || typeof vpId !== 'string' || vpId.includes('/') || vpId.includes('\\') || vpId === '..' || vpId === '.') {
+    throw new VpCrudError('illegal_character', vpId);
+  }
+  const dir = vpDirFor(libDir, vpId);
+  if (!existsSync(dir)) {
+    throw new VpCrudError('not_found', vpId);
+  }
+  rmSync(dir, { recursive: true, force: true });
+  return { vpId };
+}
+
+/**
+ * Read the full editable shape of an existing VP (for populating the edit
+ * form). Parses role.md directly via the same parser vp-store uses, without
+ * dragging in the mtime / memoryDir side effects of loadVpFromDir.
+ *
+ * @param {string} vpId
+ * @param {object} [options]
+ * @returns {?{vpId:string, displayName:string, role:string, traits:string[], modelHint:?string, persona:string}}
+ */
+export function readVp(vpId, options = {}) {
+  const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
+  const rolePath = vpRolePathFor(libDir, vpId);
+  if (!existsSync(rolePath)) return null;
+  let source;
+  try {
+    source = readFileSync(rolePath, 'utf-8');
+  } catch {
+    return null;
+  }
+  const { meta, body } = parseRoleMd(source);
+  const id = String(meta.id || vpId).trim() || vpId;
+  const modelHintRaw = typeof meta.modelHint === 'string' ? meta.modelHint : null;
+  const modelHint = modelHintRaw === 'primary' || modelHintRaw === 'fast' ? modelHintRaw : null;
+  return {
+    vpId: id,
+    displayName: String(meta.name || id),
+    role: String(meta.role || ''),
+    traits: Array.isArray(meta.traits) ? meta.traits.map(String) : [],
+    modelHint,
+    persona: body,
+  };
+}

package/unify/web-bridge.js

@@ -27,6 +27,7 @@ import { sendToServer } from '../connection/buffer.js';
 import ctx from '../context.js';
 import { getThreadStore, MAIN_THREAD_ID } from './threads/store.js';
 import { handleVpSubscribe } from './vp/vp-bridge.js';
+import { createVp, updateVp, deleteVp, readVp, VpCrudError } from './vp/vp-crud.js';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -114,6 +115,105 @@ export function handleUnifyVpSubscribe(_msg) {
   handleVpSubscribe(sendUnifyEvent);
 }
 
+/**
+ * task-334-ui-g: VP CRUD from the web client.
+ *
+ * Thin dispatcher over agent/unify/vp/vp-crud.js. We never throw on the WS
+ * path — each op reports via `unify_output` with a structured payload so
+ * the UI can surface errors as i18n strings keyed by `error.code`. VpLoader
+ * picks up the on-disk change on its next debounced rescan (default 500ms)
+ * and fans out `vp_updated` / `vp_removed` events to every subscriber, so
+ * we do not need to emit an extra snapshot here.
+ *
+ * Message shapes (wire):
+ *   unify_vp_create  { payload: {vpId, displayName, role, traits, modelHint, persona}, requestId? }
+ *   unify_vp_update  { payload: {...}, requestId? }
+ *   unify_vp_delete  { vpId, requestId? }
+ *   unify_vp_read    { vpId, requestId? }
+ *
+ * Replies (all sent through sendUnifyEvent):
+ *   { type: 'vp_crud_result', op, requestId, ok, vpId?, vp?, error?: {code, vpId?} }
+ */
+function sendVpCrudResult(payload) {
+  sendUnifyEvent({ type: 'vp_crud_result', ...payload });
+}
+
+export function handleUnifyVpCreate(msg) {
+  const requestId = msg && msg.requestId;
+  const payload = msg && msg.payload;
+  try {
+    const { vpId } = createVp(payload || {});
+    sendVpCrudResult({ op: 'create', requestId, ok: true, vpId });
+  } catch (err) {
+    sendVpCrudResult({
+      op: 'create',
+      requestId,
+      ok: false,
+      error: {
+        code: err instanceof VpCrudError ? err.code : 'unknown',
+        vpId: err && err.vpId,
+        message: err && err.message,
+      },
+    });
+  }
+}
+
+export function handleUnifyVpUpdate(msg) {
+  const requestId = msg && msg.requestId;
+  const payload = msg && msg.payload;
+  try {
+    const { vpId } = updateVp(payload || {});
+    sendVpCrudResult({ op: 'update', requestId, ok: true, vpId });
+  } catch (err) {
+    sendVpCrudResult({
+      op: 'update',
+      requestId,
+      ok: false,
+      error: {
+        code: err instanceof VpCrudError ? err.code : 'unknown',
+        vpId: err && err.vpId,
+        message: err && err.message,
+      },
+    });
+  }
+}
+
+export function handleUnifyVpDelete(msg) {
+  const requestId = msg && msg.requestId;
+  const vpId = msg && msg.vpId;
+  try {
+    deleteVp(vpId);
+    sendVpCrudResult({ op: 'delete', requestId, ok: true, vpId });
+  } catch (err) {
+    sendVpCrudResult({
+      op: 'delete',
+      requestId,
+      ok: false,
+      error: {
+        code: err instanceof VpCrudError ? err.code : 'unknown',
+        vpId: err && err.vpId,
+        message: err && err.message,
+      },
+    });
+  }
+}
+
+export function handleUnifyVpRead(msg) {
+  const requestId = msg && msg.requestId;
+  const vpId = msg && msg.vpId;
+  const vp = readVp(vpId);
+  if (!vp) {
+    sendVpCrudResult({
+      op: 'read',
+      requestId,
+      ok: false,
+      error: { code: 'not_found', vpId },
+    });
+    return;
+  }
+  sendVpCrudResult({ op: 'read', requestId, ok: true, vpId, vp });
+}
+
 /**
  * task-318 rev-1 fix: install live-setter bridge between the session's
  * runtime handles (engineRegistry + threadStore) and `ctx.unifyRuntimeSettings`,