@yeaft/webchat-agent 0.1.522 → 0.1.523

package/package.json

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

package/unify/vp/core-memory-recall.js

@@ -0,0 +1,75 @@
+/**
+ * core-memory-recall.js — single-dimension VP memory recall.
+ *
+ * Per R3 §Δ2.3: recall is scoped to the CURRENT VP only. The `scope`
+ * dimension from R2 was deleted; VP memory is a single store per VP and
+ * the recall filter is `{ vp: currentVpId, ... }` — no $or across local /
+ * global.
+ *
+ * This module is a thin shim over whatever memory store RoleInstance has
+ * (334f wraps 334o's shard-store). It duck-types the store so 334c does
+ * not hard-depend on 334f's final shape:
+ *
+ *   store.query({ vp, shard?, kind?, tags?, limit?, recency? })
+ *   store.search({ vp, query, limit? })    // optional
+ *
+ * Return shape: array of entries with at minimum `{ body, shard }`.
+ * Additional fields are passed through.
+ */
+
+const DEFAULT_LIMIT = 7;
+
+/**
+ * Recall top-K core memory for a VP.
+ *
+ * @param {object|null} store  — memoryStore (may be null)
+ * @param {{ vp: string, limit?: number, shard?: string, kind?: string,
+ *           tags?: string[] }} opts
+ * @returns {Promise<Array<{body:string, shard?:string, [k:string]:any}>>}
+ */
+export async function recallCoreMemory(store, opts = {}) {
+  if (!store || typeof store.query !== 'function') return [];
+  if (!opts.vp || typeof opts.vp !== 'string') {
+    throw new Error('recallCoreMemory: opts.vp (vpId) is required');
+  }
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0
+    ? opts.limit
+    : DEFAULT_LIMIT;
+
+  const filter = { vp: opts.vp, limit };
+  if (opts.shard) filter.shard = opts.shard;
+  if (opts.kind) filter.kind = opts.kind;
+  if (opts.tags && opts.tags.length) filter.tags = opts.tags;
+
+  // Support both sync and async stores.
+  const out = await Promise.resolve(store.query(filter));
+  if (!Array.isArray(out)) return [];
+  return out.slice(0, limit);
+}
+
+/**
+ * Optional keyword-search variant — used by the `memory_search` tool in
+ * 334d. Also VP-scoped.
+ *
+ * @param {object|null} store
+ * @param {{ vp: string, query: string, limit?: number }} opts
+ */
+export async function searchCoreMemory(store, opts = {}) {
+  if (!store) return [];
+  if (!opts.vp || !opts.query) return [];
+  const limit = opts.limit || DEFAULT_LIMIT;
+  if (typeof store.search === 'function') {
+    const out = await Promise.resolve(store.search({ vp: opts.vp, query: opts.query, limit }));
+    return Array.isArray(out) ? out.slice(0, limit) : [];
+  }
+  // Fallback: query + naive substring filter.
+  if (typeof store.query === 'function') {
+    const all = await Promise.resolve(store.query({ vp: opts.vp, limit: 200 }));
+    if (!Array.isArray(all)) return [];
+    const needle = opts.query.toLowerCase();
+    return all
+      .filter((e) => (e.body || '').toLowerCase().includes(needle))
+      .slice(0, limit);
+  }
+  return [];
+}

package/unify/vp/engine-binding.js

@@ -0,0 +1,96 @@
+/**
+ * engine-binding.js — bind a single Engine instance to a VP.
+ *
+ * Per §5.1, Engine is a stateless library: `engine.query({prompt, messages,
+ * signal, ...})`. Per §5.2, each RoleInstance runs ITS VP's Engine. We keep
+ * one Engine per (vpId) — NOT per RoleInstance — because the Engine itself
+ * holds no conversation state; messages live on the RoleInstance. Sharing
+ * across groups for the same VP is correct and avoids adapter duplication.
+ *
+ * When a VP is hot-reloaded (persona body changed → personaHash changed),
+ * the cached Engine is still valid — the persona is injected via system
+ * prompt, not Engine constructor. We keep the cache stable unless the
+ * caller passes a new adapter (e.g. modelHint switched).
+ *
+ * Hard constraint: 334c does NOT import ../engine.js directly, because
+ * that pulls in adapter/config/tool machinery that's owned by the caller
+ * (web-bridge / eval runner). Instead this module takes a factory:
+ *
+ *   createEngine(vp) → Engine
+ *
+ * which the caller supplies when they wire up a Registry.
+ */
+
+const DEFAULT_SCOPE = Symbol.for('yeaft.334c.default-engine-scope');
+
+/**
+ * Build an engine binder. Stateless helper — state lives on the registry-
+ * like cache the caller provides (defaults to an internal WeakMap-style).
+ *
+ * @param {{
+ *   createEngine: (vp: import('./vp-store.js').VP) => object,
+ *   cache?: Map<string, object>,        // vpId → Engine
+ * }} deps
+ */
+export function createEngineBinder({ createEngine, cache } = {}) {
+  if (typeof createEngine !== 'function') {
+    throw new Error('createEngineBinder: createEngine(vp) factory is required');
+  }
+  const store = cache instanceof Map ? cache : new Map();
+  // Track personaHash at bind time so the caller can decide whether a
+  // later hot-reload warrants re-binding (MVP: we just stash it; engine
+  // itself is persona-agnostic).
+  const meta = new Map(); // vpId → { personaHash, modelHint }
+
+  return {
+    /**
+     * Resolve (or lazily create) the Engine for a RoleInstance's VP and
+     * attach it onto `ri.engine`. Idempotent.
+     *
+     * @param {import('./role-instance.js').RoleInstance} ri
+     * @returns {object} Engine
+     */
+    bind(ri) {
+      if (!ri || !ri.vp) throw new Error('bind: role instance required');
+      const vp = ri.vp;
+      let engine = store.get(vp.id);
+      if (!engine) {
+        engine = createEngine(vp);
+        if (!engine || typeof engine.query !== 'function') {
+          throw new Error(`bind: createEngine(${vp.id}) did not return an Engine-like object (missing query)`);
+        }
+        store.set(vp.id, engine);
+        meta.set(vp.id, { personaHash: vp.personaHash, modelHint: vp.modelHint });
+      }
+      ri.engine = engine;
+      return engine;
+    },
+
+    /**
+     * Mark a VP as "needs re-bind" — drop the cache entry. The next bind()
+     * call will invoke createEngine again. Useful when the caller knows
+     * the adapter or tool inventory has changed.
+     */
+    invalidate(vpId) {
+      const engine = store.get(vpId);
+      store.delete(vpId);
+      meta.delete(vpId);
+      // Best-effort: if the engine exposed a dispose, call it.
+      if (engine && typeof engine.dispose === 'function') {
+        try { engine.dispose(); } catch { /* ignore */ }
+      }
+    },
+
+    /** Drop every cached engine (e.g. on session teardown). */
+    clear() {
+      for (const vpId of Array.from(store.keys())) this.invalidate(vpId);
+    },
+
+    /** Diagnostics. */
+    size() { return store.size; },
+    has(vpId) { return store.has(vpId); },
+    getMeta(vpId) { return meta.get(vpId) || null; },
+  };
+
+  void DEFAULT_SCOPE; // reserved for cross-module sharing; not used in MVP
+}

package/unify/vp/index.js

@@ -6,3 +6,9 @@ export { parseRoleMd, loadVpFromDir, scanVpLibrary, count, DEFAULT_VP_LIB_DIR }
 export { RoleInstance } from './role-instance.js';
 export { Registry, defaultRegistry } from './registry.js';
 export { VpLoader } from './vp-loader.js';
+
+// task-334c
+export { buildSystemPrompt } from './system-prompt.js';
+export { recallCoreMemory, searchCoreMemory } from './core-memory-recall.js';
+export { createEngineBinder } from './engine-binding.js';
+export { createTurnRunner } from './run-turn.js';

package/unify/vp/registry.js

@@ -56,6 +56,11 @@ export class Registry {
     cur.traits = next.traits;
     cur.modelHint = next.modelHint;
     cur.persona = next.persona;
+    // task-334c: personaHash must track persona body. 334a-followup added
+    // the field; this is the in-place update mirror. (Originally recorded
+    // as a 334h nit, but 334c's system-prompt block names the hash in
+    // STATIC — carrying a stale hash would bleed into the prompt.)
+    cur.personaHash = next.personaHash;
     cur.mtimeMs = next.mtimeMs;
     // dir / memoryDir / id stable
     return cur;

package/unify/vp/role-instance.js

@@ -1,18 +1,32 @@
 /**
  * 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.
+ * task-334 §5 RoleInstance. 334a defined the shape; task-334c adds the
+ * lifecycle surface:
+ *   - state machine:   idle → queued → running → (idle | error) + standby
+ *   - inputQueue:      enqueue(envelope) + drain(runner) loop
+ *   - abort:           per-instance AbortController, exposed via abort()
  *
- * Hard constraint (a) from slice spec: do NOT import 334o shard-store.
- * `memoryStore` is a nullable placeholder here.
+ * Hard constraints (inherited from 334a):
+ *   - does NOT import 334o shard-store directly (memoryStore stays nullable)
+ *   - does NOT import 334d routing (inputQueue accepts whatever coordinator
+ *     hands it; runner is the sole consumer)
+ *
+ * Hard constraint (334c-specific):
+ *   - the runner callback is injected — RoleInstance does not know about
+ *     Engine internals. See run-turn.js for the canonical runner.
  */
 
 /**
- * @typedef {'idle'|'running'|'queued'|'error'} RoleInstanceState
+ * @typedef {'idle'|'queued'|'running'|'standby'|'error'} RoleInstanceState
+ *
+ *   - idle:     no work, ready to accept
+ *   - queued:   inputQueue has items, drain scheduled/running but this
+ *               iteration is not yet inside the runner (brief transition)
+ *   - running:  inside runner for one envelope
+ *   - standby:  explicit pause via setState('standby'); enqueue is allowed
+ *               (buffers) but drain is gated until setState('idle')
+ *   - error:    last turn threw; next enqueue re-enters drain and clears
  */
 
 let _seq = 0;
@@ -38,24 +52,40 @@ export class RoleInstance {
     // ── Runtime state (preserved across persona hot-reload) ─────
     /** @type {RoleInstanceState} */
     this.state = 'idle';
-    /** Conversation messages appended by 334c. */
+    /** Conversation messages appended by run-turn (user + assistant pairs). */
     this.messages = [];
-    /** Pending input queue (334d). */
+    /** Pending input queue (envelopes from coordinator). */
     this.inputQueue = [];
-    /** Abort controller for in-flight engine.run (334c). */
+    /** Abort controller for in-flight run. Created per-turn. */
     this.abortController = null;
 
     // ── Nullable sub-system handles (attached by later slices) ──
-    /** threadStore — 334h/334c bootstraps. */
+    /** threadStore — optional (334h). */
     this.threadStore = null;
-    /** subagentPool — 334c. */
+    /** subagentPool — optional. */
     this.subagentPool = null;
     /** memoryStore — 334f wraps 334o; NOT created here. */
     this.memoryStore = null;
+    /** Cached Engine for this VP; bound lazily by engine-binding.js. */
+    this.engine = null;
+    /** Cached systemPrompt string; rebuilt when vp.mtimeMs changes. */
+    this.systemPrompt = null;
+    /** mtimeMs seen when systemPrompt was last built — invalidation key. */
+    this._promptBuiltForMtime = null;
 
     // ── Telemetry ───────────────────────────────────────────────
     this.createdAt = Date.now();
     this.lastActivityAt = this.createdAt;
+    /** Total turns executed via drain (error turns included). */
+    this.turnCount = 0;
+    /** Last error thrown by runner; cleared on next successful turn. */
+    this.lastError = null;
+
+    // ── Drain internals ────────────────────────────────────────
+    /** Set while a drain loop is active. Prevents re-entry. */
+    this._draining = false;
+    /** Promise that resolves when the current drain loop exits. */
+    this._drainPromise = null;
   }
 
   /** Update last-activity timestamp (used by LRU eviction). */
@@ -63,12 +93,109 @@ export class RoleInstance {
     this.lastActivityAt = Date.now();
   }
 
-  /** Transition helper. */
+  /** Transition helper. Emits a state change to optional listeners. */
   setState(next) {
     this.state = next;
     this.touch();
   }
 
+  /**
+   * Enqueue an envelope for processing. Triggers a drain if one isn't
+   * already running.
+   *
+   * Envelope shape (from coordinator.js makeEnvelope): { groupId, taskId,
+   * msg, trigger }. Opaque to RoleInstance — handed verbatim to runner.
+   *
+   * @param {object} envelope
+   * @returns {number} new inputQueue length
+   */
+  enqueue(envelope) {
+    if (!envelope) throw new Error('enqueue: envelope required');
+    this.inputQueue.push(envelope);
+    this.touch();
+    if (this.state === 'idle') this.setState('queued');
+    return this.inputQueue.length;
+  }
+
+  /**
+   * Abort the in-flight run (if any) and clear the pending queue's
+   * ability to advance further by signalling abort. The queue is NOT
+   * cleared — that's policy left to the caller (e.g. GroupCoordinator
+   * may reshedule on next user message).
+   *
+   * @param {string} [reason]
+   */
+  abort(reason = 'user') {
+    if (this.abortController && !this.abortController.signal.aborted) {
+      try { this.abortController.abort(reason); } catch { /* ignore */ }
+    }
+    this.touch();
+  }
+
+  /**
+   * Drain the inputQueue by invoking `runner(envelope)` for each. One
+   * envelope at a time, FIFO. Re-entry safe: if a drain is already in
+   * progress, return the in-flight promise instead of starting a second
+   * loop. Standby gates the loop (standby → no runner calls until a
+   * subsequent `setState('idle')` + enqueue).
+   *
+   * The runner owns state transitions into 'running' and back to 'idle'
+   * for the iteration it's handling; drain only sets the initial queued
+   * / final idle around the whole loop.
+   *
+   * @param {(envelope: object, ri: RoleInstance) => Promise<void>} runner
+   * @returns {Promise<{turns:number, errors:number}>}
+   */
+  drain(runner) {
+    if (typeof runner !== 'function') {
+      return Promise.reject(new Error('drain: runner must be a function'));
+    }
+    if (this._draining) return this._drainPromise;
+
+    this._draining = true;
+    this._drainPromise = (async () => {
+      let turns = 0;
+      let errors = 0;
+      try {
+        while (this.inputQueue.length > 0) {
+          // Standby blocks the drain — buffer until caller reactivates.
+          if (this.state === 'standby') break;
+          const envelope = this.inputQueue.shift();
+          this.turnCount += 1;
+          turns += 1;
+          // Fresh controller per turn so abort(reason) only kills one iter
+          // and the next envelope starts with a clean signal.
+          this.abortController = new AbortController();
+          try {
+            this.setState('running');
+            await runner(envelope, this);
+            this.lastError = null;
+          } catch (err) {
+            errors += 1;
+            this.lastError = err;
+            this.setState('error');
+            // Propagate abort — don't swallow it; but do stop draining so
+            // the caller can decide to requeue / resume.
+            if (err && err.name === 'AbortError') break;
+            // Non-abort errors: continue draining. The next turn gets a
+            // fresh state via setState('running') at the top of the loop.
+          }
+        }
+        // Settle terminal state only if we didn't bail in 'error' or
+        // 'standby'. Keep 'standby' sticky so caller must reactivate.
+        if (this.state !== 'standby' && this.state !== 'error') {
+          this.setState('idle');
+        }
+      } finally {
+        this._draining = false;
+        this._drainPromise = null;
+        this.abortController = null;
+      }
+      return { turns, errors };
+    })();
+    return this._drainPromise;
+  }
+
   /**
    * Snapshot for debug / telemetry. Excludes bulky messages.
    */
@@ -80,6 +207,8 @@ export class RoleInstance {
       state: this.state,
       messageCount: this.messages.length,
       queueDepth: this.inputQueue.length,
+      turnCount: this.turnCount,
+      hasError: Boolean(this.lastError),
       lastActivityAt: this.lastActivityAt,
       createdAt: this.createdAt,
     };

package/unify/vp/run-turn.js

@@ -0,0 +1,197 @@
+/**
+ * run-turn.js — execute one turn for a RoleInstance.
+ *
+ * A "turn" = consume one envelope from RoleInstance.inputQueue, build a
+ * fresh system prompt (§8), call `engine.query({prompt, messages, signal})`,
+ * accumulate the streamed text, and append the resulting assistant
+ * message both to `ri.messages` (for next-turn context) and — if the
+ * caller provides a GroupHandle — to the group's jsonl log via its
+ * `appendMessage` API (§334b public surface; hard constraint c: we never
+ * hand-write bytes).
+ *
+ * This is the canonical runner passed to `RoleInstance.drain(runner)`.
+ * Tests substitute a fake engine via createEngineBinder to exercise the
+ * drain loop / state machine without a live adapter.
+ *
+ * Streaming contract — event types handled (all optional; Engine.query is
+ * the source of truth):
+ *   { type: 'text',        text: string }          — accumulate
+ *   { type: 'text_chunk',  text: string }          — accumulate
+ *   { type: 'tool_call',   ... }                   — pass to onEvent
+ *   { type: 'tool_end',    ... }                   — pass to onEvent
+ *   { type: 'aborted',     reason }                — exit loop, throw AbortError
+ *   { type: 'error',       error }                 — throw
+ *   { type: 'turn_end',    ... }                   — exit loop
+ *
+ * Unknown event types are forwarded to `onEvent(evt)` if provided.
+ */
+
+import { buildSystemPrompt } from './system-prompt.js';
+
+/**
+ * Build a runner suitable for RoleInstance.drain().
+ *
+ * @param {{
+ *   binder: import('./engine-binding.js').createEngineBinder extends (...args:any)=>infer R ? R : never,
+ *   registry?: import('./registry.js').Registry,
+ *   group?: import('../groups/group-store.js').GroupHandle,  // optional persistence
+ *   rosterMembers?: string[],
+ *   capabilitiesLine?: string,
+ *   onEvent?: (evt:any, ri:any) => void,
+ *   buildPromptOverride?: typeof buildSystemPrompt,
+ * }} deps
+ */
+export function createTurnRunner(deps = {}) {
+  const {
+    binder,
+    registry,
+    group,
+    rosterMembers,
+    capabilitiesLine,
+    onEvent,
+    buildPromptOverride,
+  } = deps;
+
+  if (!binder || typeof binder.bind !== 'function') {
+    throw new Error('createTurnRunner: binder (from createEngineBinder) is required');
+  }
+
+  const buildPrompt = buildPromptOverride || buildSystemPrompt;
+
+  /**
+   * The actual runner. Called once per envelope by drain().
+   *
+   * @param {object} envelope   — { groupId, taskId, msg, trigger }
+   * @param {import('./role-instance.js').RoleInstance} ri
+   */
+  return async function runOneTurn(envelope, ri) {
+    if (!envelope || !envelope.msg) {
+      throw new Error('runOneTurn: envelope.msg missing');
+    }
+
+    const engine = binder.bind(ri);
+
+    // Fresh system prompt per turn — DYNAMIC section changes every turn.
+    const systemPrompt = await buildPrompt(ri, {
+      registry,
+      rosterMembers,
+      capabilitiesLine,
+      runtimeCtx: {
+        taskId: envelope.taskId || null,
+        isDream: false,
+      },
+    });
+
+    // Prompt text = inbound message body. Engine.query spec:
+    //   { prompt, messages, signal, ... }
+    // It prepends the system prompt via adapter-level wiring; we pass
+    // `systemPrompt` as an explicit first message if the engine supports
+    // it, else rely on the engine's own system injection. For §334c MVP
+    // we pass systemPrompt as metadata on messages[0] and let the engine
+    // decide — tests supply a fake engine that echoes back.
+    const prompt = String(envelope.msg.text || '').trim();
+    if (!prompt) {
+      // No-op envelope (empty msg): record a stub and return.
+      ri.messages.push({ role: 'user', text: '', ts: new Date().toISOString(), meta: envelope });
+      return;
+    }
+
+    ri.messages.push({
+      role: 'user',
+      text: prompt,
+      ts: envelope.msg.ts || new Date().toISOString(),
+      from: envelope.msg.from || 'user',
+      msgId: envelope.msg.id || null,
+      trigger: envelope.trigger || null,
+    });
+
+    const signal = ri.abortController ? ri.abortController.signal : undefined;
+
+    // Build prior-messages window for the engine — MVP: the last 20.
+    const priorMessages = ri.messages.slice(-20);
+
+    let accumulated = '';
+    let aborted = false;
+    let errored = null;
+
+    const iterator = engine.query({
+      prompt,
+      messages: priorMessages,
+      signal,
+      systemPrompt,
+      metadata: {
+        vpId: ri.vpId,
+        groupId: ri.groupId,
+        taskId: envelope.taskId || null,
+        turnId: `${ri.id}:${ri.turnCount}`,
+      },
+    });
+
+    try {
+      for await (const evt of iterator) {
+        if (!evt || typeof evt !== 'object') continue;
+        switch (evt.type) {
+          case 'text':
+          case 'text_chunk':
+          case 'message':
+            if (typeof evt.text === 'string') accumulated += evt.text;
+            if (onEvent) try { onEvent(evt, ri); } catch { /* ignore */ }
+            break;
+          case 'aborted':
+            aborted = true;
+            if (onEvent) try { onEvent(evt, ri); } catch { /* ignore */ }
+            break;
+          case 'error':
+            errored = evt.error instanceof Error ? evt.error : new Error(String(evt.error || 'engine error'));
+            if (onEvent) try { onEvent(evt, ri); } catch { /* ignore */ }
+            break;
+          case 'turn_end':
+            if (onEvent) try { onEvent(evt, ri); } catch { /* ignore */ }
+            break;
+          default:
+            if (onEvent) try { onEvent(evt, ri); } catch { /* ignore */ }
+        }
+        if (aborted || errored) break;
+      }
+    } catch (err) {
+      if (err && err.name === 'AbortError') {
+        aborted = true;
+      } else {
+        errored = err;
+      }
+    }
+
+    if (aborted) {
+      const e = new Error('aborted');
+      e.name = 'AbortError';
+      throw e;
+    }
+    if (errored) throw errored;
+
+    // Record assistant reply (even if empty — the turn still counted).
+    const assistantMsg = {
+      role: 'assistant',
+      text: accumulated,
+      ts: new Date().toISOString(),
+      from: ri.vpId,
+      taskId: envelope.taskId || null,
+    };
+    ri.messages.push(assistantMsg);
+
+    // Hard constraint (c): persistence goes through 334b's appendMessage.
+    if (group && typeof group.appendMessage === 'function' && accumulated.trim()) {
+      try {
+        group.appendMessage({
+          from: ri.vpId,
+          role: 'assistant',
+          text: accumulated,
+          taskId: envelope.taskId || null,
+          meta: { trigger: envelope.trigger || null, replyTo: envelope.msg.id || null },
+        });
+      } catch (err) {
+        // Non-fatal: the in-memory message is still recorded on ri.messages.
+        if (onEvent) try { onEvent({ type: 'persist_error', error: err }, ri); } catch { /* ignore */ }
+      }
+    }
+  };
+}

package/unify/vp/system-prompt.js

@@ -0,0 +1,191 @@
+/**
+ * system-prompt.js — assemble a VP's system prompt per architecture §8.
+ *
+ * Three sections:
+ *   § STATIC
+ *     - identity (yeaft base — short)
+ *     - vp_persona (role.md persona body)
+ *     - capabilities (tools) — 334d owns the real list; this slice leaves
+ *       a stub that names the MVP tool surface ("route_forward" ...).
+ *
+ *   § SEMI-DYNAMIC
+ *     - group_roster (name + on-line status via Registry.activeCount)
+ *     - (skills / mcp / user_profile — owned by other slices; 334c emits
+ *       placeholder only if the caller provides them)
+ *
+ *   § DYNAMIC
+ *     - runtime_ctx  { vpId, groupId, taskId?, isDream=false }
+ *     - core_memory  (recall top-K; vp single-dim per R3 §Δ2.3)
+ *
+ * Caching: the STATIC persona section is cached per RoleInstance via
+ * `ri._promptBuiltForMtime === vp.mtimeMs`. DYNAMIC is always rebuilt.
+ *
+ * Hard constraint (334c): this module does not touch 334f/334g memory
+ * internals. It calls `memoryStore.query({vp})` (duck-typed) and falls
+ * back to an empty top-K if the store is null.
+ */
+
+import { recallCoreMemory } from './core-memory-recall.js';
+
+const CORE_MEMORY_TOP_K = 7;          // §8
+const ROSTER_STATUS_ONLINE = 'online';
+const ROSTER_STATUS_BUSY = 'busy';
+
+/**
+ * Build one complete system prompt string.
+ *
+ * @param {import('./role-instance.js').RoleInstance} ri
+ * @param {{
+ *   registry?: import('./registry.js').Registry,
+ *   rosterMembers?: string[],           // explicit override (334b GroupHandle.roster)
+ *   runtimeCtx?: { taskId?: string|null, isDream?: boolean, recentChatSummary?: string },
+ *   capabilitiesLine?: string,          // 334d injects tool inventory
+ *   userProfile?: string,               // 334l injects top-5 user-memory
+ *   recentGroupChat?: string,           // 334h injects N recent msgs
+ * }} opts
+ * @returns {string}
+ */
+export async function buildSystemPrompt(ri, opts = {}) {
+  if (!ri || !ri.vp) throw new Error('buildSystemPrompt: role instance required');
+  const vp = ri.vp;
+
+  // ─── § STATIC (cached per mtime) ────────────────────────────
+  let staticBlock = ri.systemPrompt;
+  if (!staticBlock || ri._promptBuiltForMtime !== vp.mtimeMs) {
+    staticBlock = buildStatic(vp, opts.capabilitiesLine);
+    ri.systemPrompt = staticBlock;
+    ri._promptBuiltForMtime = vp.mtimeMs;
+  }
+
+  // ─── § SEMI-DYNAMIC ─────────────────────────────────────────
+  const roster = buildRoster(ri, opts.registry, opts.rosterMembers);
+  const userProfile = opts.userProfile ? `\n## user_profile\n${opts.userProfile.trim()}\n` : '';
+
+  // ─── § DYNAMIC ──────────────────────────────────────────────
+  const ctx = opts.runtimeCtx || {};
+  const runtime = buildRuntimeCtx(ri, ctx);
+  const recent = opts.recentGroupChat
+    ? `\n## recent_group_chat\n${opts.recentGroupChat.trim()}\n`
+    : '';
+  const coreMem = await buildCoreMemoryBlock(ri, ctx);
+
+  return [
+    '# § STATIC',
+    staticBlock,
+    '',
+    '# § SEMI-DYNAMIC',
+    roster,
+    userProfile.trim() ? userProfile : '',
+    '',
+    '# § DYNAMIC',
+    runtime,
+    recent.trim() ? recent : '',
+    coreMem,
+  ]
+    .filter(Boolean)
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+// ──────────────────────────────────────────────────────────────
+// STATIC
+// ──────────────────────────────────────────────────────────────
+
+function buildStatic(vp, capabilitiesLine) {
+  const identity =
+    'You are a Virtual Person (VP) in a yeaft multi-agent group.\n' +
+    'Respect §6 triggers: text @-mentions do NOT route. Use the `route_forward` tool for explicit dispatch.';
+
+  const persona = vp.persona && vp.persona.trim()
+    ? vp.persona.trim()
+    : `(no persona body for ${vp.id})`;
+
+  const caps = (capabilitiesLine && capabilitiesLine.trim())
+    || 'Tools: route_forward, memory_search, memory_trace, task_summary_post (if initiator).';
+
+  // personaHash travels in the static block so downstream (334h live-diff)
+  // can detect changes without re-hashing.
+  return [
+    '## identity',
+    identity,
+    '',
+    `## vp_persona (id=${vp.id}, hash=${vp.personaHash || '-'})`,
+    `Name: ${vp.name}`,
+    vp.role ? `Role: ${vp.role}` : '',
+    vp.traits && vp.traits.length ? `Traits: ${vp.traits.join(', ')}` : '',
+    '',
+    persona,
+    '',
+    '## capabilities',
+    caps,
+  ].filter(Boolean).join('\n');
+}
+
+// ──────────────────────────────────────────────────────────────
+// SEMI-DYNAMIC — Roster
+// ──────────────────────────────────────────────────────────────
+
+function buildRoster(ri, registry, rosterMembers) {
+  const members = Array.isArray(rosterMembers) && rosterMembers.length > 0
+    ? rosterMembers
+    : registry
+      ? Array.from(new Set(registry.listRoleInstances()
+          .filter((r) => r.groupId === ri.groupId)
+          .map((r) => r.vpId)))
+      : [ri.vpId];
+
+  const lines = [`## 群成员 (${members.length})`];
+  for (const vpId of members) {
+    if (vpId === ri.vpId) {
+      lines.push(`- 你自己：${vpId}`);
+      continue;
+    }
+    const status = memberStatus(vpId, registry);
+    const name = registry?.getVp?.(vpId)?.name || vpId;
+    lines.push(`- ${name} (${vpId}) · ${status}`);
+  }
+  return lines.join('\n');
+}
+
+function memberStatus(vpId, registry) {
+  if (!registry) return ROSTER_STATUS_ONLINE;
+  // §8.2: busy if any RoleInstance for this VP has state==='running' in any group.
+  // MVP: also 'running' while 'queued'? — spec says "running RoleInstance 数 > 0".
+  const ris = registry.listRoleInstances?.() || [];
+  const busy = ris.some((r) => r.vpId === vpId && r.state === 'running');
+  return busy ? ROSTER_STATUS_BUSY : ROSTER_STATUS_ONLINE;
+}
+
+// ──────────────────────────────────────────────────────────────
+// DYNAMIC
+// ──────────────────────────────────────────────────────────────
+
+function buildRuntimeCtx(ri, ctx) {
+  return [
+    '## runtime_ctx',
+    `vpId: ${ri.vpId}`,
+    `groupId: ${ri.groupId}`,
+    ctx.taskId ? `taskId: ${ctx.taskId}` : null,
+    `isDream: ${Boolean(ctx.isDream)}`,
+  ].filter(Boolean).join('\n');
+}
+
+async function buildCoreMemoryBlock(ri, ctx) {
+  if (!ri.memoryStore) return '';
+  const entries = await recallCoreMemory(ri.memoryStore, {
+    vp: ri.vpId,
+    limit: CORE_MEMORY_TOP_K,
+  });
+  if (!entries || entries.length === 0) return '';
+  void ctx; // task_ctx injection is 334n's scope; reserved param.
+  const lines = ['## core_memory'];
+  for (const e of entries) {
+    const shard = e.shard || 'general';
+    const body = (e.body || '').trim();
+    if (!body) continue;
+    lines.push(`- [mem:${shard}] ${body}`);
+  }
+  if (lines.length === 1) return '';
+  return lines.join('\n');
+}