@yeaft/webchat-agent 0.1.723 → 0.1.725

package/package.json

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

package/unify/engine.js

@@ -28,6 +28,7 @@ import { archiveTurn } from './archive/turn-archive.js';
 import { archiveToolResults } from './archive/tool-results.js';
 import { readSummary as readScopeSummary } from './memory/store-v2.js';
 import { runAdjust } from './memory/adjust.js';
+import { isVpSeedBackfillStub } from './memory/seed-backfill.js';
 import { runStopHooks } from './stop-hooks.js';
 // H2.f.5: threads/ retired. Persisted messages still carry a `threadId`
 // field for back-compat with old conversation files; new writes always use
@@ -176,6 +177,45 @@ export function estimateMessagesTokens(system, messages) {
 
 // ─── Engine ──────────────────────────────────────────────────────
 
+/**
+ * buildResidentEntries — pure helper that builds the AMS Resident entry
+ * list from the per-turn Layer-A summaries.
+ *
+ * Encodes one non-trivial rule on top of "push if non-empty":
+ *
+ *   The `vp/<ownVpId>` summary is skipped when it carries the
+ *   seed-backfill stub marker. The persona body is already rendered as
+ *   Section 1 of the system prompt by `renderVpPersona`; surfacing the
+ *   stub's `# Name / Role` line as a Resident entry would re-label the
+ *   same identity in Section 6 ("Active Memory Set") with no added
+ *   information — the visible follow-up to the persona-dup bug fixed in
+ *   PR #722. Once Dream-v2 writes a real summary for this scope it
+ *   lacks the marker and is surfaced normally.
+ *
+ * Other-VP entries (group collaborators) are NOT considered here — only
+ * the local VP's summary is loaded into `summaries.vp` upstream by
+ * `#loadLayerASummaries`. Cross-VP context flows through onDemand recall.
+ *
+ * @param {{
+ *   groupId?: string|null,
+ *   ownVpId?: string|null,
+ *   summaries: { user?: string, group?: string, vp?: string }
+ * }} args
+ * @returns {Array<{scope: string, summary: string}>}
+ */
+export function buildResidentEntries(args) {
+  const summaries = (args && args.summaries) || {};
+  const out = [];
+  if (summaries.user) out.push({ scope: 'user', summary: summaries.user });
+  if (args.groupId && summaries.group) {
+    out.push({ scope: `group/${args.groupId}`, summary: summaries.group });
+  }
+  if (args.ownVpId && summaries.vp && !isVpSeedBackfillStub(summaries.vp)) {
+    out.push({ scope: `vp/${args.ownVpId}`, summary: summaries.vp });
+  }
+  return out;
+}
+
 export class Engine {
   /** @type {import('./llm/adapter.js').LLMAdapter} */
   #adapter;
@@ -505,14 +545,11 @@ export class Engine {
 
     // (a) Resident: rebuild from the same scope summaries the worker
     // prompt is already going to see.
-    const residentEntries = [];
-    if (args.summaries?.user)  residentEntries.push({ scope: 'user', summary: args.summaries.user });
-    if (args.groupId && args.summaries?.group) {
-      residentEntries.push({ scope: `group/${args.groupId}`, summary: args.summaries.group });
-    }
-    if (ownVpId && args.summaries?.vp) {
-      residentEntries.push({ scope: `vp/${ownVpId}`, summary: args.summaries.vp });
-    }
+    const residentEntries = buildResidentEntries({
+      groupId: args.groupId,
+      ownVpId,
+      summaries: args.summaries || {},
+    });
     ams.setResident(residentEntries);
 
     // (b) onDemand: replace with this turn's FTS hits.

package/unify/memory/seed-backfill.js

@@ -22,6 +22,42 @@ import { parseRoleMd } from '../vp/vp-store.js';
 
 const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
 
+/**
+ * Marker stamped into every VP summary written by this module.
+ *
+ * Two consumers care about it:
+ *   1. `engine.#prepareAms` uses `isVpSeedBackfillStub` to skip the
+ *      `vp/<ownVpId>` Resident entry when its summary is just our stub —
+ *      the real persona is already rendered as Section 1 of the system
+ *      prompt by `renderVpPersona`. Without the skip, AMS Resident dups
+ *      Section 1 with redundant `name + role` labels.
+ *   2. `migrateLegacyVpSummaries` uses absence-of-marker + presence of
+ *      `**Persona:**` to identify pre-fix summary.md files (which copied
+ *      up to 800 chars of `role.md` body) and rewrite them as stubs.
+ *
+ * Bump the version suffix when the stub format changes meaningfully so
+ * old stamps can be re-migrated if needed.
+ */
+export const VP_STUB_MARKER = '<!-- seed-backfill:vp-stub v1 -->';
+
+/**
+ * True iff the given summary text was produced by this module's VP stub
+ * writer (i.e. carries the marker comment). Whitespace-tolerant.
+ *
+ * Used by `engine.#prepareAms` to decide whether to surface the
+ * `vp/<ownVpId>` summary as a Resident AMS entry. Stubs are skipped so
+ * Section 1 (`renderVpPersona`) is the sole rendering of own-VP identity;
+ * Dream-v2's eventual real summary will lack the marker and be surfaced
+ * normally.
+ *
+ * @param {string|null|undefined} text
+ * @returns {boolean}
+ */
+export function isVpSeedBackfillStub(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  return text.includes(VP_STUB_MARKER);
+}
+
 function readIfPresent(path) {
   try {
     if (!existsSync(path)) return '';
@@ -39,10 +75,25 @@ function writeAtomicSync(path, body) {
 /**
  * Build a synthetic VP summary from the on-disk role.md.
  *
+ * IMPORTANT — this is a STUB that lives until Dream-v2 writes a real
+ * per-scope summary. Earlier versions copied up to 800 chars of the
+ * `role.md` body into `summary.md`. That body is *also* rendered as
+ * Section 1 of the system prompt (`renderVpPersona` in `prompts.js`),
+ * so the same persona text reappeared in `## Active Memory Set →
+ * Resident → vp/<id>` — the user-visible "Why is the persona defined
+ * twice?" bug.
+ *
+ * The summary.md placeholder is therefore deliberately minimal: just
+ * the VP's display name + role label. Layer-A AMS still sees a
+ * non-empty `vp/<id>` resident entry (so adjust/recall scope wiring
+ * stays unchanged), but the persona body is rendered exactly once,
+ * by Section 1.
+ *
+ * Once Dream-v2 produces a real summary for this scope it overwrites
+ * this stub — see `idempotency` note at the top of the file.
+ *
  * Delegates frontmatter parsing to `vp-store.js#parseRoleMd` so the
- * backfill stays in sync with the production loader. The earlier hand-
- * rolled regex parser silently dropped quoted multi-line scalars and
- * list-shaped fields — `parseRoleMd` covers both.
+ * backfill stays in sync with the production loader.
  *
  * @param {string} libDir
  * @param {string} vpId
@@ -54,17 +105,12 @@ function readVpRoleSummary(libDir, vpId) {
   let raw = '';
   try { raw = readFileSync(rolePath, 'utf-8'); } catch { return null; }
 
-  const { meta, body } = parseRoleMd(raw);
+  const { meta } = parseRoleMd(raw);
   const name = String(meta.name || vpId).trim() || vpId;
   const role = typeof meta.role === 'string' ? meta.role.trim() : '';
 
-  const persona = typeof body === 'string' ? body.trim() : '';
-  const lines = [`# ${name}`];
+  const lines = [VP_STUB_MARKER, '', `# ${name}`];
   if (role) lines.push('', `**Role:** ${role}`);
-  if (persona) {
-    const truncated = persona.length > 800 ? persona.slice(0, 800).trim() + '…' : persona;
-    lines.push('', '**Persona:**', '', truncated);
-  }
   return lines.join('\n').trim();
 }
 
@@ -123,6 +169,64 @@ function readGroupSummaryBody(groupDir) {
   return lines.join('\n').trim();
 }
 
+/**
+ * Detect the *legacy* (pre-stamp) VP summary shape: a body that lacks
+ * `VP_STUB_MARKER` AND contains the `**Persona:**` block written by the
+ * older stub. Tight signature on purpose — we don't want to clobber
+ * hand-edited or Dream-v2-produced summaries that happen to be missing
+ * the marker for unrelated reasons.
+ *
+ * @param {string} body
+ * @returns {boolean}
+ */
+function isLegacyVpSummary(body) {
+  if (typeof body !== 'string' || body.length === 0) return false;
+  if (body.includes(VP_STUB_MARKER)) return false;
+  return body.includes('**Persona:**');
+}
+
+/**
+ * One-shot migration: walk `<root>/vp/<id>/summary.md` and rewrite any
+ * file matching the legacy shape (`isLegacyVpSummary`) into the current
+ * stamped stub. Idempotent — a stamped or Dream-v2-produced file is left
+ * untouched. Safe to run on every session boot.
+ *
+ * Existing users whose `summary.md` was written by the pre-stamp stub
+ * carry the persona body forever, because `backfillVpSummaries` only
+ * writes when the file is empty/missing. This pass closes that gap.
+ *
+ * @param {{ libDir: string, root?: string }} opts
+ * @returns {{ scanned: number, migrated: number }}
+ */
+export function migrateLegacyVpSummaries({ libDir, root = DEFAULT_MEMORY_ROOT }) {
+  let scanned = 0;
+  let migrated = 0;
+  const vpRoot = join(root, 'vp');
+  if (!existsSync(vpRoot)) return { scanned, migrated };
+  let entries;
+  try { entries = readdirSync(vpRoot); } catch { return { scanned, migrated }; }
+  for (const name of entries) {
+    if (name.startsWith('.')) continue;
+    const summaryPath = join(vpRoot, name, 'summary.md');
+    let body = '';
+    try {
+      if (!existsSync(summaryPath)) continue;
+      body = readFileSync(summaryPath, 'utf-8');
+    } catch { continue; }
+    scanned++;
+    if (!isLegacyVpSummary(body)) continue;
+    const stub = readVpRoleSummary(libDir, name);
+    if (!stub) continue;
+    try {
+      writeAtomicSync(summaryPath, stub);
+      migrated++;
+    } catch (err) {
+      console.warn(`[seed-backfill] migrate vp ${name}: ${err?.message || err}`);
+    }
+  }
+  return { scanned, migrated };
+}
+
 /**
  * Walk groups/ and seed `summary.md` for every group without one.
  *
@@ -161,17 +265,30 @@ export function backfillGroupSummaries({ yeaftDir, root = DEFAULT_MEMORY_ROOT })
  * Run all backfills sequentially. Best-effort — any per-step error is
  * logged and the next step still runs.
  *
+ * Order:
+ *   1. Migrate legacy VP summaries (rewrite pre-stamp persona-body stubs
+ *      to current-format stamped stubs). Runs FIRST so that
+ *      `backfillVpSummaries` sees consistent on-disk state and any
+ *      future logic that distinguishes "stamped" vs "free-form" works
+ *      uniformly downstream.
+ *   2. Backfill missing VP summaries.
+ *   3. Backfill missing group summaries.
+ *
  * @param {{ yeaftDir: string, libDir: string, root?: string }} opts
- * @returns {{ vp: {scanned:number, seeded:number}, group: {scanned:number, seeded:number} }}
+ * @returns {{ migrate: {scanned:number, migrated:number}, vp: {scanned:number, seeded:number}, group: {scanned:number, seeded:number} }}
  */
 export function runSummaryBackfill({ yeaftDir, libDir, root = DEFAULT_MEMORY_ROOT }) {
+  let migrate = { scanned: 0, migrated: 0 };
   let vp = { scanned: 0, seeded: 0 };
   let group = { scanned: 0, seeded: 0 };
+  try { migrate = migrateLegacyVpSummaries({ libDir, root }); } catch (err) {
+    console.warn('[seed-backfill] vp migrate failed:', err?.message || err);
+  }
   try { vp = backfillVpSummaries({ libDir, root }); } catch (err) {
     console.warn('[seed-backfill] vp pass failed:', err?.message || err);
   }
   try { group = backfillGroupSummaries({ yeaftDir, root }); } catch (err) {
     console.warn('[seed-backfill] group pass failed:', err?.message || err);
   }
-  return { vp, group };
+  return { migrate, vp, group };
 }

package/unify/vp/vp-crud.js

@@ -23,6 +23,7 @@ import { homedir } from 'os';
 import { validateVpId } from '../groups/ids.js';
 import { DEFAULT_VP_LIB_DIR, parseRoleMd } from './vp-store.js';
 import { seedSummaryIfMissingSync, removeScopeDirSync } from '../memory/store-v2.js';
+import { VP_STUB_MARKER } from '../memory/seed-backfill.js';
 
 /**
  * Default memory root used when callers don't pass `options.memoryRoot`.
@@ -40,26 +41,36 @@ const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
  * @param {object} payload  same shape as createVp
  * @returns {string}
  */
+/**
+ * Build the seed body for a freshly-created VP's `<root>/vp/<id>/summary.md`.
+ *
+ * IMPORTANT — this is a STUB that mirrors `seed-backfill.js#readVpRoleSummary`.
+ * Earlier versions of both writers embedded up to 800 chars of `persona`
+ * here. That body is *also* rendered as Section 1 of the system prompt by
+ * `renderVpPersona`, so the same persona text reappeared in the AMS
+ * Resident block — the user-visible "persona defined twice" bug. PR #722
+ * fixed `seed-backfill.js`; this writer is the create-time twin.
+ *
+ * The seed is therefore deliberately minimal (name + role + traits) and
+ * stamped with `VP_STUB_MARKER` so `engine.buildResidentEntries` knows to
+ * skip the own-VP Resident push (Section 1 is already the source of truth
+ * for own-VP identity). Once Dream-v2 writes a real summary it overwrites
+ * this stub and lacks the marker, so it surfaces normally.
+ *
+ * @param {object} payload  same shape as createVp
+ * @returns {string}
+ */
 export function buildVpSeedSummary(payload) {
   const id = String(payload?.vpId || '').trim();
   const name = (payload?.displayName != null ? String(payload.displayName) : id).trim();
   const role = (payload?.role != null ? String(payload.role) : '').trim();
-  const persona = (typeof payload?.persona === 'string' ? payload.persona : '').trim();
   const traits = Array.isArray(payload?.traits)
     ? payload.traits.map(t => String(t)).filter(Boolean)
     : [];
 
-  const lines = [];
-  lines.push(`# ${name}`);
+  const lines = [VP_STUB_MARKER, '', `# ${name}`];
   if (role) lines.push('', `**Role:** ${role}`);
   if (traits.length > 0) lines.push('', `**Traits:** ${traits.join(', ')}`);
-  if (persona) {
-    // Keep the persona body terse — first 800 chars is plenty for an
-    // initial Layer-A resident summary; Dream-v2 will rewrite it as
-    // memory accumulates.
-    const truncated = persona.length > 800 ? persona.slice(0, 800).trim() + '…' : persona;
-    lines.push('', '**Persona:**', '', truncated);
-  }
   return lines.join('\n').trim();
 }