@yeaft/webchat-agent 0.1.515 → 0.1.516

package/package.json

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

package/unify/vp/index.js

@@ -0,0 +1,8 @@
+/**
+ * index.js — Public barrel for agent/unify/vp.
+ */
+
+export { parseRoleMd, loadVpFromDir, scanVpLibrary, count, DEFAULT_VP_LIB_DIR } from './vp-store.js';
+export { RoleInstance } from './role-instance.js';
+export { Registry, defaultRegistry } from './registry.js';
+export { VpLoader } from './vp-loader.js';

package/unify/vp/registry.js

@@ -0,0 +1,169 @@
+/**
+ * registry.js — In-memory VP + RoleInstance registry.
+ *
+ * Two maps:
+ *   - vpMap:           vpId → VP
+ *   - instanceMap:     "<groupId>::<vpId>" → RoleInstance
+ *
+ * RoleInstance creation is idempotent: `getOrCreateRoleInstance(vpId, groupId)`
+ * returns the same instance for the same (vpId, groupId) pair.
+ *
+ * LRU eviction (per acceptance #3): when active instance count exceeds
+ * `softLimit.maxActiveRoleInstances` (default 40), the least-recently-used
+ * idle instance is evicted. Instances with `state !== 'idle'` are skipped
+ * over during eviction; if no idle candidate exists, the new instance is
+ * still created (soft limit — we do not hard-reject).
+ */
+
+import { RoleInstance } from './role-instance.js';
+
+const DEFAULT_MAX_ACTIVE_ROLE_INSTANCES = 40;
+
+export class Registry {
+  constructor(options = {}) {
+    /** @type {Map<string, import('./vp-store.js').VP>} */
+    this.vpMap = new Map();
+    /** @type {Map<string, RoleInstance>} */
+    this.instanceMap = new Map();
+    this.softLimit = {
+      maxActiveRoleInstances: options.maxActiveRoleInstances ?? DEFAULT_MAX_ACTIVE_ROLE_INSTANCES,
+    };
+    /** Listeners for eviction / persona-refresh (optional). */
+    this._evictListeners = new Set();
+  }
+
+  // ─── VP map ────────────────────────────────────────────────────
+
+  setVp(vp) {
+    if (!vp || !vp.id) return;
+    this.vpMap.set(vp.id, vp);
+  }
+
+  /**
+   * Replace a VP's persona fields in-place, preserving identity so any
+   * RoleInstance with `.vp === vp` keeps its reference stable across
+   * hot-reload. Fields copied: name, role, traits, modelHint, persona,
+   * mtimeMs.
+   */
+  updateVpInPlace(next) {
+    const cur = this.vpMap.get(next.id);
+    if (!cur) {
+      this.setVp(next);
+      return next;
+    }
+    cur.name = next.name;
+    cur.role = next.role;
+    cur.traits = next.traits;
+    cur.modelHint = next.modelHint;
+    cur.persona = next.persona;
+    cur.mtimeMs = next.mtimeMs;
+    // dir / memoryDir / id stable
+    return cur;
+  }
+
+  removeVp(vpId) {
+    this.vpMap.delete(vpId);
+    // Also drop any RoleInstances bound to a vanished VP.
+    for (const [key, ri] of this.instanceMap) {
+      if (ri.vpId === vpId) {
+        this.instanceMap.delete(key);
+      }
+    }
+  }
+
+  getVp(vpId) {
+    return this.vpMap.get(vpId);
+  }
+
+  listVps() {
+    return Array.from(this.vpMap.values());
+  }
+
+  vpCount() {
+    return this.vpMap.size;
+  }
+
+  // ─── RoleInstance map ─────────────────────────────────────────
+
+  _key(groupId, vpId) {
+    return `${groupId}::${vpId}`;
+  }
+
+  /**
+   * Idempotent create: same (vpId, groupId) returns same instance.
+   * Triggers LRU eviction when the soft limit is exceeded.
+   *
+   * @param {string} vpId
+   * @param {string} groupId
+   * @returns {RoleInstance}
+   */
+  getOrCreateRoleInstance(vpId, groupId) {
+    const vp = this.vpMap.get(vpId);
+    if (!vp) throw new Error(`unknown vpId: ${vpId}`);
+
+    const key = this._key(groupId, vpId);
+    const existing = this.instanceMap.get(key);
+    if (existing) {
+      existing.touch();
+      return existing;
+    }
+
+    const ri = new RoleInstance({ vp, groupId });
+    this.instanceMap.set(key, ri);
+    this._maybeEvict(ri);
+    return ri;
+  }
+
+  getRoleInstance(vpId, groupId) {
+    return this.instanceMap.get(this._key(groupId, vpId));
+  }
+
+  dropRoleInstance(vpId, groupId) {
+    const key = this._key(groupId, vpId);
+    const ri = this.instanceMap.get(key);
+    if (!ri) return false;
+    this.instanceMap.delete(key);
+    return true;
+  }
+
+  activeRoleInstanceCount() {
+    return this.instanceMap.size;
+  }
+
+  listRoleInstances() {
+    return Array.from(this.instanceMap.values());
+  }
+
+  onEvict(listener) {
+    this._evictListeners.add(listener);
+    return () => this._evictListeners.delete(listener);
+  }
+
+  _maybeEvict(exclude) {
+    const limit = this.softLimit.maxActiveRoleInstances;
+    if (this.instanceMap.size <= limit) return;
+
+    // Collect idle instances (excluding the just-created one), sort by
+    // lastActivityAt ascending.
+    const idle = [];
+    for (const ri of this.instanceMap.values()) {
+      if (ri === exclude) continue;
+      if (ri.state === 'idle') idle.push(ri);
+    }
+    idle.sort((a, b) => a.lastActivityAt - b.lastActivityAt);
+
+    while (this.instanceMap.size > limit && idle.length > 0) {
+      const victim = idle.shift();
+      const key = this._key(victim.groupId, victim.vpId);
+      this.instanceMap.delete(key);
+      for (const l of this._evictListeners) {
+        try { l(victim); } catch { /* ignore */ }
+      }
+    }
+    // If still over limit because no idle candidates exist, we accept the
+    // soft-limit breach — per spec, softLimit is a target, not a hard cap.
+  }
+}
+
+/** Module-level default registry (convenience). */
+export const defaultRegistry = new Registry();

package/unify/vp/role-instance.js

@@ -0,0 +1,87 @@
+/**
+ * role-instance.js — RoleInstance class (per-group per-VP runtime handle).
+ *
+ * Per task-334 architecture §5: an Engine run targets one RoleInstance.
+ * This slice (334a) defines the object shape + basic lifecycle; the actual
+ * engine.run(roleInstance, opts) integration lives in 334c. Downstream
+ * stores (threadStore / subagentPool / memoryStore) are lazily attached by
+ * their respective slices — 334a only reserves the slots.
+ *
+ * Hard constraint (a) from slice spec: do NOT import 334o shard-store.
+ * `memoryStore` is a nullable placeholder here.
+ */
+
+/**
+ * @typedef {'idle'|'running'|'queued'|'error'} RoleInstanceState
+ */
+
+let _seq = 0;
+function nextInstanceId(vpId, groupId) {
+  _seq = (_seq + 1) >>> 0;
+  return `ri_${groupId}_${vpId}_${Date.now().toString(36)}_${_seq.toString(36)}`;
+}
+
+export class RoleInstance {
+  /**
+   * @param {{ vp: import('./vp-store.js').VP, groupId: string }} params
+   */
+  constructor({ vp, groupId }) {
+    if (!vp) throw new Error('RoleInstance requires a vp');
+    if (!groupId) throw new Error('RoleInstance requires a groupId');
+
+    this.id = nextInstanceId(vp.id, groupId);
+    this.vpId = vp.id;
+    this.groupId = groupId;
+    /** Live VP reference. Persona hot-reload mutates fields in place. */
+    this.vp = vp;
+
+    // ── Runtime state (preserved across persona hot-reload) ─────
+    /** @type {RoleInstanceState} */
+    this.state = 'idle';
+    /** Conversation messages appended by 334c. */
+    this.messages = [];
+    /** Pending input queue (334d). */
+    this.inputQueue = [];
+    /** Abort controller for in-flight engine.run (334c). */
+    this.abortController = null;
+
+    // ── Nullable sub-system handles (attached by later slices) ──
+    /** threadStore — 334h/334c bootstraps. */
+    this.threadStore = null;
+    /** subagentPool — 334c. */
+    this.subagentPool = null;
+    /** memoryStore — 334f wraps 334o; NOT created here. */
+    this.memoryStore = null;
+
+    // ── Telemetry ───────────────────────────────────────────────
+    this.createdAt = Date.now();
+    this.lastActivityAt = this.createdAt;
+  }
+
+  /** Update last-activity timestamp (used by LRU eviction). */
+  touch() {
+    this.lastActivityAt = Date.now();
+  }
+
+  /** Transition helper. */
+  setState(next) {
+    this.state = next;
+    this.touch();
+  }
+
+  /**
+   * Snapshot for debug / telemetry. Excludes bulky messages.
+   */
+  snapshot() {
+    return {
+      id: this.id,
+      vpId: this.vpId,
+      groupId: this.groupId,
+      state: this.state,
+      messageCount: this.messages.length,
+      queueDepth: this.inputQueue.length,
+      lastActivityAt: this.lastActivityAt,
+      createdAt: this.createdAt,
+    };
+  }
+}

package/unify/vp/vp-loader.js

@@ -0,0 +1,173 @@
+/**
+ * vp-loader.js — Hot-reload watcher for the VP library.
+ *
+ * Watches `~/.yeaft/virtual-persons/` for additions, removals, and role.md
+ * changes. Changes are debounced (default 500ms) and then applied:
+ *
+ *   - new dir with role.md  → registry.setVp(vp)
+ *   - removed dir           → registry.removeVp(vpId)
+ *   - role.md modified      → registry.updateVpInPlace(next)
+ *     (persona fields swap; RoleInstance.runtimeState preserved — the VP
+ *     object identity in registry is kept, so any RoleInstance holding
+ *     `.vp` sees the new persona without being rebuilt)
+ *
+ * Hard constraint (a): no 334o storage import.
+ */
+
+import { watch, existsSync } from 'fs';
+import { join } from 'path';
+import { scanVpLibrary, loadVpFromDir, DEFAULT_VP_LIB_DIR } from './vp-store.js';
+
+const DEFAULT_DEBOUNCE_MS = 500;
+
+export class VpLoader {
+  /**
+   * @param {{ dir?: string, registry: import('./registry.js').Registry, debounceMs?: number, onChange?: (summary) => void }} options
+   */
+  constructor(options) {
+    if (!options || !options.registry) {
+      throw new Error('VpLoader requires { registry }');
+    }
+    this.dir = options.dir || DEFAULT_VP_LIB_DIR;
+    this.registry = options.registry;
+    this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    this.onChange = typeof options.onChange === 'function' ? options.onChange : null;
+
+    /** @type {import('fs').FSWatcher|null} */
+    this._rootWatcher = null;
+    /** @type {Map<string, import('fs').FSWatcher>} */
+    this._dirWatchers = new Map();
+    /** @type {any} */
+    this._debounceTimer = null;
+    this._started = false;
+  }
+
+  /** Initial scan + install watchers. Returns the initial VP list. */
+  start() {
+    if (this._started) return this.registry.listVps();
+    this._started = true;
+
+    const vps = scanVpLibrary({ dir: this.dir });
+    for (const vp of vps) this.registry.setVp(vp);
+
+    if (existsSync(this.dir)) {
+      this._installRootWatcher();
+      for (const vp of vps) this._installDirWatcher(vp.dir);
+    }
+    return vps;
+  }
+
+  /** Stop watchers and clear timers. Safe to call multiple times. */
+  stop() {
+    this._started = false;
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+    if (this._rootWatcher) {
+      try { this._rootWatcher.close(); } catch { /* ignore */ }
+      this._rootWatcher = null;
+    }
+    for (const w of this._dirWatchers.values()) {
+      try { w.close(); } catch { /* ignore */ }
+    }
+    this._dirWatchers.clear();
+  }
+
+  _installRootWatcher() {
+    try {
+      this._rootWatcher = watch(this.dir, { persistent: false }, () => {
+        this._scheduleRescan();
+      });
+    } catch {
+      // watch may fail on some FS; hot-reload degrades to no-op
+    }
+  }
+
+  _installDirWatcher(dir) {
+    if (this._dirWatchers.has(dir)) return;
+    try {
+      const w = watch(dir, { persistent: false }, () => {
+        this._scheduleRescan();
+      });
+      this._dirWatchers.set(dir, w);
+    } catch {
+      // ignore
+    }
+  }
+
+  _scheduleRescan() {
+    if (this._debounceTimer) clearTimeout(this._debounceTimer);
+    this._debounceTimer = setTimeout(() => {
+      this._debounceTimer = null;
+      try {
+        this._rescan();
+      } catch {
+        // never crash the loader from a rescan error
+      }
+    }, this.debounceMs);
+  }
+
+  /**
+   * Force an immediate rescan (bypass debounce). Useful for tests.
+   * @returns {{ added: string[], removed: string[], updated: string[] }}
+   */
+  rescanNow() {
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+    return this._rescan();
+  }
+
+  _rescan() {
+    const fresh = scanVpLibrary({ dir: this.dir });
+    const freshById = new Map(fresh.map(v => [v.id, v]));
+    const oldById = new Map(this.registry.listVps().map(v => [v.id, v]));
+
+    const added = [];
+    const removed = [];
+    const updated = [];
+
+    // Added / updated
+    for (const [id, next] of freshById) {
+      const prev = oldById.get(id);
+      if (!prev) {
+        this.registry.setVp(next);
+        this._installDirWatcher(next.dir);
+        added.push(id);
+      } else if (
+        prev.mtimeMs !== next.mtimeMs ||
+        prev.persona !== next.persona ||
+        prev.name !== next.name ||
+        prev.role !== next.role
+      ) {
+        // In-place update preserves VP identity → RoleInstance.runtimeState
+        // is untouched; persona swap propagates on next read of vp.persona.
+        this.registry.updateVpInPlace(next);
+        updated.push(id);
+      }
+    }
+
+    // Removed
+    for (const [id, prev] of oldById) {
+      if (!freshById.has(id)) {
+        this.registry.removeVp(id);
+        const w = this._dirWatchers.get(prev.dir);
+        if (w) {
+          try { w.close(); } catch { /* ignore */ }
+          this._dirWatchers.delete(prev.dir);
+        }
+        removed.push(id);
+      }
+    }
+
+    const summary = { added, removed, updated };
+    if ((added.length || removed.length || updated.length) && this.onChange) {
+      try { this.onChange(summary); } catch { /* ignore */ }
+    }
+    return summary;
+  }
+}
+
+export { DEFAULT_VP_LIB_DIR };

package/unify/vp/vp-store.js

@@ -0,0 +1,183 @@
+/**
+ * vp-store.js — Virtual Person (VP) store.
+ *
+ * Scans `~/.yeaft/virtual-persons/<vp-name>/role.md` and produces VP records.
+ * role.md is a Markdown file with YAML frontmatter:
+ *
+ *   ---
+ *   id: alice
+ *   name: Alice
+ *   role: Product Manager
+ *   modelHint: primary
+ *   traits:
+ *     - curious
+ *     - pragmatic
+ *   ---
+ *   (body = VP persona / system-prompt-shaped description)
+ *
+ * Per task-334a spec hard constraint (a): this module does NOT import the
+ * 334o storage layer. Memory bootstrap is `mkdir -p` only — no shard-store
+ * touches.
+ */
+
+import { readFileSync, readdirSync, statSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+/**
+ * @typedef {Object} VP
+ * @property {string} id              — VP id (default: dir name)
+ * @property {string} name
+ * @property {string} role
+ * @property {string[]} traits
+ * @property {'fast'|'primary'|undefined} modelHint
+ * @property {string} persona         — markdown body (persona / system prompt seed)
+ * @property {string} dir             — absolute path to VP dir
+ * @property {string} memoryDir       — absolute path to VP memory dir
+ * @property {number} mtimeMs         — role.md mtime (for hot-reload)
+ */
+
+export const DEFAULT_VP_LIB_DIR = join(homedir(), '.yeaft', 'virtual-persons');
+
+/**
+ * Parse YAML frontmatter + body from role.md.
+ * Minimal parser (scalars + bullet lists), same shape as personas.js.
+ *
+ * @param {string} source
+ * @returns {{ meta: Record<string, any>, body: string }}
+ */
+export function parseRoleMd(source) {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: source };
+
+  const [, yaml, body] = match;
+  /** @type {Record<string, any>} */
+  const meta = {};
+  const lines = yaml.split(/\r?\n/);
+  let currentList = null;
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const listMatch = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (listMatch && currentList) {
+      currentList.push(listMatch[1].replace(/^['"]|['"]$/g, ''));
+      continue;
+    }
+    const kvMatch = line.match(/^([\w-]+):\s*(.*)$/);
+    if (kvMatch) {
+      const [, key, raw] = kvMatch;
+      const value = raw.trim();
+      if (!value) {
+        currentList = [];
+        meta[key] = currentList;
+      } else {
+        meta[key] = value.replace(/^['"]|['"]$/g, '');
+        currentList = null;
+      }
+    }
+  }
+
+  return { meta, body: body.trim() };
+}
+
+/**
+ * Load a single VP from an absolute VP directory.
+ * Returns null if role.md is missing or has no usable id.
+ *
+ * Side effect: ensures `<dir>/memory/` exists (mkdir -p only — per hard
+ * constraint (a), we do not touch shard-store).
+ *
+ * @param {string} dir
+ * @returns {VP|null}
+ */
+export function loadVpFromDir(dir) {
+  const rolePath = join(dir, 'role.md');
+  let source;
+  let st;
+  try {
+    source = readFileSync(rolePath, 'utf-8');
+    st = statSync(rolePath);
+  } catch {
+    return null;
+  }
+
+  const { meta, body } = parseRoleMd(source);
+  const dirName = dir.split(/[\\/]/).filter(Boolean).pop() || '';
+  const id = String(meta.id || dirName).trim();
+  if (!id) return null;
+
+  const memoryDir = join(dir, 'memory');
+  try {
+    mkdirSync(memoryDir, { recursive: true });
+  } catch {
+    // best-effort; do not fail load on mkdir error
+  }
+
+  const modelHintRaw = typeof meta.modelHint === 'string' ? meta.modelHint : undefined;
+  const modelHint = modelHintRaw === 'primary' || modelHintRaw === 'fast' ? modelHintRaw : undefined;
+
+  /** @type {VP} */
+  return {
+    id,
+    name: String(meta.name || id),
+    role: String(meta.role || ''),
+    traits: Array.isArray(meta.traits) ? meta.traits.map(String) : [],
+    modelHint,
+    persona: body,
+    dir,
+    memoryDir,
+    mtimeMs: st.mtimeMs,
+  };
+}
+
+/**
+ * Scan a VP library root (default `~/.yeaft/virtual-persons`).
+ *
+ * @param {{ dir?: string }} [options]
+ * @returns {VP[]}
+ */
+export function scanVpLibrary(options = {}) {
+  const { dir = DEFAULT_VP_LIB_DIR } = options;
+  if (!existsSync(dir)) return [];
+
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const vps = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+    const vp = loadVpFromDir(join(dir, entry.name));
+    if (vp) vps.push(vp);
+  }
+  return vps;
+}
+
+/**
+ * Count VPs in the library without loading full records.
+ * Cheap API for G1 empty-library fallback (acceptance #4).
+ *
+ * @param {{ dir?: string }} [options]
+ * @returns {number}
+ */
+export function count(options = {}) {
+  const { dir = DEFAULT_VP_LIB_DIR } = options;
+  if (!existsSync(dir)) return 0;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let n = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const rolePath = join(dir, entry.name, 'role.md');
+    if (existsSync(rolePath)) n++;
+  }
+  return n;
+}