@yeaft/webchat-agent 0.1.812 → 0.1.814

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.812",
+  "version": "0.1.814",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",
@@ -35,7 +35,8 @@
   },
   "files": [
     "**/*.js",
-    "unify/templates/**/*.md"
+    "unify/templates/**/*.md",
+    "unify/dream-v2/prompts/**/*.md"
   ],
   "license": "MIT",
   "author": "Yeaft",

package/unify/dream-v2/prompts/create.md

@@ -0,0 +1,14 @@
+You are creating a new memory scope from scratch.
+
+Scope path: {{target}}   (must be ≤2 levels)
+
+Source conversations:
+{{sources}}
+
+{{siblingsBlock}}
+Task:
+1. Write memory.md from scratch with reasonable section structure.
+2. Write summary.md (1–3 sentences).
+
+Reply with strict JSON of the shape:
+{ "memory_md": "...", "summary_md": "..." }

package/unify/dream-v2/prompts/extract-group.md

@@ -0,0 +1,57 @@
+# Dream Extract — Group Scope
+
+You are extracting **memory segments** from a conversation between the
+user and a Yeaft AI companion. This pass focuses on a specific
+**`group/<id>` scope**: long-lived facts about one collaboration group
+(a project team, a study cohort, a working set of people/agents).
+
+The target group id is provided as `{{groupId}}`.
+
+## What to extract for `group/<id>` scope
+
+- **purpose** — what this group exists to do, its charter / mission
+- **members** — people, VPs, and roles in the group, and what each is
+  responsible for
+- **conventions** — how the group works (rituals, cadences, naming,
+  channels, languages used)
+- **shared decisions** — durable agreements ("we ship on Fridays",
+  "all PRs need two reviewers")
+- **shared context** — domain knowledge the whole group relies on
+- **relations** — other groups, features, or topics this group owns or
+  depends on
+- **lessons** — collective takeaways ("we tried X in Q1, it didn't
+  scale, switched to Y")
+
+## What NOT to extract here
+
+- Personal preferences of the user — those go to `user` scope.
+- Single-VP traits — those go to that VP's `vp/<id>` scope.
+- Feature-specific implementation detail — those go to
+  `feature/<id>` scope.
+- Transient status updates — only durable group facts.
+
+## Segment shape
+
+Each segment is **self-contained** and **about one thing**. Detail is
+OK; one-line summaries are NOT — preserve specifics.
+
+## Output format
+
+Reply with a JSON array of segment objects:
+
+```json
+[
+  {
+    "kind": "decision",
+    "tags": ["process", "review"],
+    "sourceMessages": ["m_201"],
+    "body": "Group {{groupId}} decided every PR touching the payments
+    module needs sign-off from both the security VP and the payments
+    feature owner before merge. Rationale: a near-miss in March."
+  }
+]
+```
+
+`kind` ∈ {`fact`, `preference`, `decision`, `lesson`, `relation`,
+`goal`, `context`}. `scope` is filled in by the runner — do not include
+it. If nothing group-scope is in this batch, return `[]`.

package/unify/dream-v2/prompts/extract-topic.md

@@ -0,0 +1,59 @@
+# Dream Extract — Topic Scope
+
+You are extracting **memory segments** from a conversation between the
+user and a Yeaft AI companion. This pass focuses on a specific
+**`topic/<id>` scope**: long-lived facts and viewpoints about a domain
+topic that recurs across conversations (e.g. `topic/lang/rust`,
+`topic/auth/jwt`, `topic/ml/transformers`).
+
+The target topic id is provided as `{{topicId}}`.
+
+## What to extract for `topic/<id>` scope
+
+- **core facts** — durable knowledge about the topic (how it works,
+  key terms, gotchas) that the user has either taught the assistant
+  or confirmed
+- **viewpoints / opinions** — formed views the user holds on this
+  topic ("I think GraphQL is overkill for internal tools")
+- **canonical references** — sources the user trusts on this topic
+  (specific docs, papers, people)
+- **patterns** — how the user typically applies this topic
+  ("when using JWT, always set short access-token TTL + refresh")
+- **lessons** — things that bit them, things that worked
+- **relations** — features, projects, or other topics tied to this one
+
+## What NOT to extract here
+
+- Facts about the user as a person — `user` scope.
+- Facts specific to one feature implementation — `feature/<id>`.
+- Group conventions — `group/<id>`.
+- Generic encyclopedia facts the assistant already knows — only the
+  user's *durable views and confirmed knowledge* about the topic.
+
+## Segment shape
+
+Each segment is **self-contained** and **about one thing**. Detail is
+OK; one-line summaries are NOT — capture rationale and specifics so
+the segment is useful next time without rehydrating the conversation.
+
+## Output format
+
+Reply with a JSON array of segment objects:
+
+```json
+[
+  {
+    "kind": "lesson",
+    "tags": ["jwt", "auth"],
+    "sourceMessages": ["m_330", "m_331"],
+    "body": "On topic {{topicId}}: user always pairs short-lived JWT
+    access tokens (≤15 min) with rotating refresh tokens stored as
+    HttpOnly cookies. Got burned by a 24h-token leak in 2024 — single
+    long-lived token is treated as a non-starter."
+  }
+]
+```
+
+`kind` ∈ {`fact`, `preference`, `decision`, `lesson`, `relation`,
+`goal`, `context`}. `scope` is filled in by the runner — do not include
+it. If nothing topic-scope is in this batch, return `[]`.

package/unify/dream-v2/prompts/extract-user.md

@@ -0,0 +1,56 @@
+# Dream Extract — User Scope
+
+You are extracting **memory segments** from a conversation between the
+user and a Yeaft AI companion. This pass focuses on the **`user`
+scope**: long-lived facts about the user themselves.
+
+## What to extract for `user` scope
+
+Extract segments that describe the user as a person:
+
+- **identity** — name, role, location, languages spoken, time zone
+- **preferences** — tools they use (zsh, vim, JS over TS, …), code style,
+  communication style, what they value
+- **habits / workflow** — how they work, when they work, recurring
+  patterns
+- **goals (long-term)** — what they're building, where they want to go
+- **relations** — people / projects / orgs they regularly mention
+- **lessons / opinions** — formed views ("I don't trust X", "Y is the
+  right tool for Z")
+
+## What NOT to extract here
+
+- Anything specific to a single feature, project, or VP — those go to
+  `feature/*`, `vp/*`, or `topic/*` scopes (handled by other passes).
+- Transient state ("I'm tired today") — only durable facts.
+- Verbatim message copies — segments are *secondary processing*, not
+  transcripts.
+
+## Segment shape
+
+Each segment is **self-contained** and **about one thing**. A 30-turn
+conversation typically yields 1–3 user-scope segments, not 30. Detail
+is OK; one-line summaries are NOT — preserve the specifics that make
+the memory useful next time (e.g. "uses zsh with starship prompt" beats
+"uses a shell").
+
+## Output format
+
+Reply with a JSON array of segment objects:
+
+```json
+[
+  {
+    "kind": "preference",
+    "tags": ["shell", "terminal"],
+    "sourceMessages": ["m_142", "m_143"],
+    "body": "User uses zsh with the starship prompt and prefers
+    keyboard-only workflows. Wants suggestions to assume zsh + vim
+    keybindings unless told otherwise."
+  }
+]
+```
+
+`kind` ∈ {`fact`, `preference`, `decision`, `lesson`, `relation`,
+`goal`, `context`}. `scope` is filled in by the runner — do not include
+it. If nothing user-scope is in this batch, return `[]`.

package/unify/dream-v2/prompts/extract-vp.md

@@ -0,0 +1,55 @@
+# Dream Extract — VP Scope
+
+You are extracting **memory segments** from a conversation between the
+user and a Yeaft AI companion. This pass focuses on a specific
+**`vp/<id>` scope**: long-lived facts about one Virtual Person (a
+persona / sub-agent / role the user works with).
+
+The target VP id is provided as `{{vpId}}`. Only extract facts about
+*this* VP, not other VPs.
+
+## What to extract for `vp/<id>` scope
+
+- **identity** — who this VP is, role, persona name, charter
+- **voice / style** — how they speak, tone, formatting habits, language
+- **expertise** — what they know well, what they should defer on
+- **interaction patterns** — how the user and this VP work together,
+  what kinds of questions go to this VP, expected response shape
+- **boundaries** — what this VP will NOT do, or things to avoid
+- **relations** — other VPs, projects, or topics this VP is tied to
+- **decisions made by/about this VP** — durable choices ("VP X always
+  reviews schema migrations"), not single-turn outcomes
+
+## What NOT to extract here
+
+- Facts about the user themselves — those go to `user` scope.
+- Facts about other VPs — those go to *their* `vp/<other>` scope.
+- Single-turn task state — only durable persona facts.
+- Verbatim message copies — segments are *secondary processing*.
+
+## Segment shape
+
+Each segment is **self-contained** and **about one thing**. Detail is
+OK; one-line summaries are NOT — preserve specifics that make the
+memory useful next time.
+
+## Output format
+
+Reply with a JSON array of segment objects:
+
+```json
+[
+  {
+    "kind": "preference",
+    "tags": ["voice", "style"],
+    "sourceMessages": ["m_88"],
+    "body": "VP {{vpId}} writes in concise bullet form, never uses
+    emoji, and always cites file paths with line numbers. Switches to
+    Chinese when the user does."
+  }
+]
+```
+
+`kind` ∈ {`fact`, `preference`, `decision`, `lesson`, `relation`,
+`goal`, `context`}. `scope` is filled in by the runner — do not include
+it. If nothing about this VP is in this batch, return `[]`.

package/unify/dream-v2/prompts/summarize-scope.md

@@ -0,0 +1,40 @@
+# Dream Summarize — Per-Scope Compression
+
+You are summarizing the **memory segments** of a single scope into a
+short, dense prose summary. This is NOT extraction — the segments
+already exist. Your job is to compress them into a paragraph the
+session can keep resident in working memory.
+
+The target scope is `{{scope}}` and contains `{{segmentCount}}`
+segments listed below.
+
+## Goals
+
+- A reader (the assistant in a future turn) should grasp **the gist of
+  this scope** from your summary alone, without reading the segments.
+- Detail is OK — but compress. Drop redundancy, keep specifics that
+  matter (names, numbers, decisions, durable views).
+- Stay faithful: do not invent facts that are not in the segments. Do
+  not "soften" decisions or opinions.
+- Bilingual: write in the same language the segments are mostly in.
+
+## Length
+
+- Target **≤ {{tokenBudget}} tokens**.
+- One paragraph for small scopes; two or three short paragraphs grouped
+  by theme for larger scopes. No bullet lists, no headings.
+
+## What NOT to do
+
+- Don't list every segment one by one — that defeats compression.
+- Don't quote verbatim chunks of segment bodies.
+- Don't add meta-commentary ("the segments show that..."). Speak
+  directly about the subject.
+
+## Segments
+
+{{segments}}
+
+## Output
+
+Reply with the prose summary only. No preamble, no JSON, no fences.

package/unify/dream-v2/prompts/triage-pass1.md

@@ -0,0 +1,20 @@
+You are deciding whether a recent group conversation carries:
+  - signals that should update the USER profile, and/or
+  - signals that should update one or more TOPIC scopes.
+
+Do NOT mention vp/, group/, or feature/ scopes — those are handled by hard rules.
+
+Group: {{groupId}}
+
+Existing topic scopes (path — summary):
+{{topicSummaries}}
+
+Conversation:
+{{conversation}}
+
+Respond with strict JSON of the shape:
+{
+  "user_profile_signals": boolean,
+  "topics": [ "<short category description>", ... ],
+  "trivial_only": boolean
+}

package/unify/dream-v2/prompts/triage-pass2.md

@@ -0,0 +1,15 @@
+Bind a free-form topic description to an exact path under topic/.
+Rules:
+  - At most TWO path segments. Reject any third level.
+  - Segments may contain letters, digits, dashes, underscores, dots, CJK.
+  - Prefer matching an existing path if the description fits.
+
+Description: {{description}}
+
+Existing topics:
+{{existingTopics}}
+
+Reply with strict JSON, exactly one of:
+  { "decision": "match", "path": "<existing path>" }
+  { "decision": "new",   "path": "<new ≤2-segment path>" }
+  { "decision": "none" }

package/unify/dream-v2/prompts/update.md

@@ -0,0 +1,33 @@
+You are updating an existing memory scope.
+
+Scope: {{target}}
+{{batchHeader}}
+Current memory.md:
+"""
+{{memoryMd}}
+"""
+
+Current summary.md:
+"""
+{{summaryMd}}
+"""
+
+Recent conversations:
+{{sources}}
+
+Task:
+- Extract from these conversations what is relevant to THIS scope.
+- Integrate it into memory.md (reorganize sections if needed).
+- Drop stale or contradicted entries.
+- Rewrite summary.md (1–3 sentences).
+- The same conversations are being processed for OTHER scopes too.
+  Only handle what is relevant here. Ignore the rest.
+
+Hard rules:
+- Never read or reference any other scope's files.
+- Never modify VP system-prompt, group charter, or user preferences.
+- If something contradicts a charter, annotate with
+  "⚠️ contradicts charter — verify which is current" and continue.
+
+Reply with strict JSON of the shape:
+{ "memory_md": "...", "summary_md": "..." }

package/unify/vp/vp-bridge.js

@@ -28,6 +28,7 @@ import { STOCK_VP_IDS } from './stock-ids.js';
 /** Process-singleton VpLoader; lazily started on first subscribe. */
 let _loaderStarted = false;
 let _loader = null;
+let _loaderDir = null;
 
 /**
  * Broadcast fan-out. VpLoader.onChange fires once per debounce batch for the
@@ -145,21 +146,33 @@ function _fanout(evt) {
   }
 }
 
-function ensureLoader(registry = defaultRegistry) {
-  if (_loaderStarted) return { loader: _loader, fresh: false };
+function ensureLoader(registry = defaultRegistry, options = {}) {
+  const desiredDir = registry === defaultRegistry && typeof options.dir === 'string' && options.dir.trim()
+    ? options.dir.trim()
+    : null;
+  if (_loaderStarted && _loaderDir === desiredDir) return { loader: _loader, fresh: false };
+
+  if (_loader) {
+    try { _loader.stop(); } catch { /* ignore */ }
+  }
   _loaderStarted = true;
+  _loader = null;
+  _loaderDir = desiredDir;
+  if (registry === defaultRegistry && registry.vpMap && typeof registry.vpMap.clear === 'function') {
+    registry.vpMap.clear();
+  }
   // For NON-default registries (unit tests seeding VPs manually) we MUST NOT
-  // start VpLoader — its .start() scans DEFAULT_VP_LIB_DIR and push-imports
-  // every on-disk VP into the test registry, overwriting/augmenting the
-  // fixture. Tests don't need hot-reload anyway; `_broadcastChangeForTest`
-  // drives the diff path directly.
+  // start VpLoader — its .start() scans the configured/default VP library and
+  // push-imports every on-disk VP into the test registry, overwriting or
+  // augmenting the fixture. Tests don't need hot-reload anyway;
+  // `_broadcastChangeForTest` drives the diff path directly.
   if (registry !== defaultRegistry) {
-    _loader = null;
     captureState(registry);
     return { loader: null, fresh: true };
   }
   try {
     _loader = new VpLoader({
+      ...(desiredDir ? { dir: desiredDir } : {}),
       registry,
       onChange: (summary) => broadcastChange(summary, registry),
     });
@@ -228,10 +241,11 @@ export function buildVpSnapshot(registry = defaultRegistry) {
  *
  * @param {(event: object) => void} sendUnifyEvent
  * @param {import('./registry.js').Registry} [registry]
+ * @param {{dir?: string}} [options]
  * @returns {() => void} unsubscribe fn
  */
-export function handleVpSubscribe(sendUnifyEvent, registry = defaultRegistry) {
-  const { loader, fresh } = ensureLoader(registry);
+export function handleVpSubscribe(sendUnifyEvent, registry = defaultRegistry, options = {}) {
+  const { loader, fresh } = ensureLoader(registry, options);
   // task-338-F2 + task-339-followup: replay semantics.
   //
   // The loader's own start() already scans on first creation, so on a
@@ -245,9 +259,9 @@ export function handleVpSubscribe(sendUnifyEvent, registry = defaultRegistry) {
   // production path so the first snapshot always reflects current disk.
   //
   // For NON-default registries (unit tests that seed VPs manually), we
-  // MUST skip the rescan: rescan against DEFAULT_VP_LIB_DIR would call
-  // registry.removeVp() for seeded ids that don't exist on disk, wiping
-  // the test fixture. See vp-bridge-live-diff.test.js and
+  // MUST skip the rescan: rescan against the configured/default VP library
+  // would call registry.removeVp() for seeded ids that don't exist on disk,
+  // wiping the test fixture. See vp-bridge-live-diff.test.js and
   // vp-bridge-first-subscribe-replay.test.js (test-seed preservation).
   //
   // On subsequent subscribes (page reload, reconnect, second web client)
@@ -277,6 +291,7 @@ export function _resetVpBridgeForTest() {
   }
   _loader = null;
   _loaderStarted = false;
+  _loaderDir = null;
   _subscribers.clear();
   _prevState.clear();
 }

package/unify/web-bridge.js

@@ -1188,12 +1188,27 @@ function sendUnifyEvent(event, { groupId, vpId, turnId, threadId } = {}) {
   });
 }
 
+function configuredVpPaths() {
+  const yeaftDir = ctx.CONFIG?.yeaftDir;
+  if (typeof yeaftDir !== 'string' || !yeaftDir.trim()) return {};
+  const root = yeaftDir.trim();
+  return {
+    libDir: join(root, 'virtual-persons'),
+    memoryRoot: join(root, 'memory'),
+  };
+}
+
 export function handleUnifyVpSubscribe(_msg) {
   if (_vpUnsubscribe) {
     try { _vpUnsubscribe(); } catch { /* ignore */ }
     _vpUnsubscribe = null;
   }
-  _vpUnsubscribe = handleVpSubscribe(sendUnifyEvent);
+  const { libDir } = configuredVpPaths();
+  _vpUnsubscribe = handleVpSubscribe(
+    sendUnifyEvent,
+    undefined,
+    libDir ? { dir: libDir } : {},
+  );
 }
 
 /**
@@ -1207,9 +1222,12 @@ export function handleUnifyVpCreate(msg) {
   const requestId = msg && msg.requestId;
   const payload = msg && msg.payload;
   try {
-    const yeaftDir = ctx.CONFIG?.yeaftDir;
-    const memoryRoot = yeaftDir ? join(yeaftDir, 'memory') : undefined;
-    const { vpId } = createVp(payload || {}, memoryRoot ? { memoryRoot } : {});
+    const { libDir, memoryRoot } = configuredVpPaths();
+    const options = {
+      ...(libDir ? { libDir } : {}),
+      ...(memoryRoot ? { memoryRoot } : {}),
+    };
+    const { vpId } = createVp(payload || {}, options);
     sendVpCrudResult({ op: 'create', requestId, ok: true, vpId });
   } catch (err) {
     sendVpCrudResult({
@@ -1229,7 +1247,8 @@ export function handleUnifyVpUpdate(msg) {
   const requestId = msg && msg.requestId;
   const payload = msg && msg.payload;
   try {
-    const { vpId } = updateVp(payload || {});
+    const { libDir } = configuredVpPaths();
+    const { vpId } = updateVp(payload || {}, libDir ? { libDir } : {});
     sendVpCrudResult({ op: 'update', requestId, ok: true, vpId });
   } catch (err) {
     sendVpCrudResult({
@@ -1249,9 +1268,12 @@ export function handleUnifyVpDelete(msg) {
   const requestId = msg && msg.requestId;
   const vpId = msg && msg.vpId;
   try {
-    const yeaftDir = ctx.CONFIG?.yeaftDir;
-    const memoryRoot = yeaftDir ? join(yeaftDir, 'memory') : undefined;
-    deleteVp(vpId, memoryRoot ? { memoryRoot } : {});
+    const { libDir, memoryRoot } = configuredVpPaths();
+    const options = {
+      ...(libDir ? { libDir } : {}),
+      ...(memoryRoot ? { memoryRoot } : {}),
+    };
+    deleteVp(vpId, options);
     // vp-status: a deleted VP must not haunt the snapshot. We don't
     // know up front which groups the VP appeared in (the registry's
     // delete already detached it from every group), so sweep every
@@ -1282,7 +1304,8 @@ export function handleUnifyVpDelete(msg) {
 export function handleUnifyVpRead(msg) {
   const requestId = msg && msg.requestId;
   const vpId = msg && msg.vpId;
-  const vp = readVp(vpId);
+  const { libDir } = configuredVpPaths();
+  const vp = readVp(vpId, libDir ? { libDir } : {});
   if (!vp) {
     sendVpCrudResult({
       op: 'read',