@yeaft/webchat-agent 0.1.604 → 0.1.606

package/package.json

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

package/unify/dream-v2/refresh.js

@@ -0,0 +1,109 @@
+/**
+ * dream-v2/refresh.js — DESIGN.md §9.14 refresh hook (Phase 8 PR-J).
+ *
+ * The PR-F wire-up plumbed `runDreamTick` into the scheduler with a v1
+ * no-op refresh placeholder. PR-J makes the refresh real but stays
+ * within the §8 v1 charter — "Thin: skip pruning/demotion; refresh-only
+ * in v1, no LLM".
+ *
+ * What "refresh" does today:
+ *   1. Read the scope's `index.md` rows (the entry catalog).
+ *   2. Select the top-N most recent rows by `updated` timestamp
+ *      (default 12 — enough to surface the active context without
+ *      exploding Layer A token cost).
+ *   3. Render a deterministic markdown synopsis (one bullet per row:
+ *      `- <title> [<kind>; tags] (<updated>)`).
+ *   4. Write to the scope's `summary.md` via `writeSummary` (atomic
+ *      rename — readers never see a partial write).
+ *
+ * If the index is empty (cold-start scope), we leave `summary.md`
+ * alone. Overwriting with an empty file would erase any human-written
+ * synopsis a future tool may have placed there.
+ *
+ * No LLM call. No pruning. No tombstones. The cursor is advanced by
+ * `runDreamTick` after this hook resolves, so a clean run of refresh
+ * counts as "scope handled" and we won't re-run until the diff-gate
+ * sees new content.
+ *
+ * Errors are propagated — `runDreamTick` already catches per-scope
+ * failures and records them under `errors[]` without aborting siblings.
+ */
+
+import { readIndex, writeSummary } from '../memory/scope-tree.js';
+
+/** Default number of recent entries surfaced on the synopsis. */
+export const DEFAULT_TOP_N = 12;
+
+/**
+ * Render a deterministic markdown synopsis for a scope from its index rows.
+ * Pure function — exported for unit tests.
+ *
+ * @param {{ kind: string, id?: string, scopeDir: string }} scope
+ * @param {Array<{ path: string, title?: string, tags?: string[]|string, kind?: string, updated?: string }>} rows
+ * @param {number} [topN]
+ * @returns {string}
+ */
+export function buildScopeSynopsis(scope, rows, topN = DEFAULT_TOP_N) {
+  if (!Array.isArray(rows) || rows.length === 0) return '';
+
+  // Sort by `updated` desc, then by path asc as a stable tiebreaker.
+  const sorted = [...rows].sort((a, b) => {
+    const u = (b.updated || '').localeCompare(a.updated || '');
+    return u !== 0 ? u : (a.path || '').localeCompare(b.path || '');
+  });
+  const top = sorted.slice(0, Math.max(1, topN | 0));
+
+  const header = `# ${scope.scopeDir} — recent context`;
+  const lines = top.map((r) => {
+    const title = (r.title || r.path || 'entry').trim();
+    const kind = r.kind ? `${r.kind}` : '';
+    const tagsRaw = Array.isArray(r.tags) ? r.tags : (typeof r.tags === 'string' ? r.tags.split(',') : []);
+    const tags = tagsRaw.map((t) => String(t).trim()).filter(Boolean);
+    const meta = [kind, ...tags].filter(Boolean).join('; ');
+    const metaPart = meta ? ` [${meta}]` : '';
+    const updated = r.updated ? ` (${r.updated})` : '';
+    return `- ${title}${metaPart}${updated}`;
+  });
+  return [header, '', ...lines, ''].join('\n');
+}
+
+/**
+ * Translate a `runDreamTick` ScopeRef ({ kind, id?, scopeDir }) into a
+ * `scope-tree.js` Scope ({ kind, id }). The two surfaces share the
+ * `kind` enum but `runDreamTick` carries `scopeDir` as the canonical
+ * identifier; scope-tree derives it from `kind`+`id`.
+ *
+ * @param {{ kind: string, id?: string, scopeDir: string }} ref
+ * @returns {{ kind: string, id?: string }}
+ */
+export function refToScope(ref) {
+  if (!ref || typeof ref !== 'object') {
+    throw new Error('refToScope: ref required');
+  }
+  if (ref.kind === 'user') return { kind: 'user' };
+  if (!ref.id) throw new Error(`refToScope: ${ref.kind} scope requires id`);
+  return { kind: ref.kind, id: ref.id };
+}
+
+/**
+ * Build a refresh hook bound to a specific memory root. The returned
+ * function is the `refresh` arg `runDreamTick` expects.
+ *
+ * @param {{ root: string, topN?: number }} args
+ * @returns {(scope: { kind: string, id?: string, scopeDir: string }) => Promise<void>}
+ */
+export function createScopeRefreshHook({ root, topN = DEFAULT_TOP_N } = {}) {
+  if (!root || typeof root !== 'string') {
+    throw new Error('createScopeRefreshHook: root required');
+  }
+  return async function refreshScopeSummary(scope) {
+    const target = refToScope(scope);
+    const rows = await readIndex(target, { root });
+    const body = buildScopeSynopsis(scope, rows, topN);
+    if (!body) {
+      // Cold-start scope: leave summary.md alone (see header docs).
+      return;
+    }
+    await writeSummary(target, body, { root });
+  };
+}

package/unify/engine.js

@@ -713,7 +713,7 @@ export class Engine {
    *   SCENARIO_EFFORT. Unknown values fall through to 'high'.
    * @yields {EngineEvent}
    */
-  async *query({ prompt, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId } = {}) {
+  async *query({ prompt, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -764,7 +764,7 @@ export class Engine {
     const runSignal = abortCtrl.signal;
 
     try {
-      yield* this.#runQuery({ prompt: effectivePrompt, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId });
+      yield* this.#runQuery({ prompt: effectivePrompt, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan });
     } finally {
       if (signal) {
         try { signal.removeEventListener('abort', onExternalAbort); } catch { /* ignore */ }
@@ -782,7 +782,7 @@ export class Engine {
    * in a try/finally without indenting the whole loop.
    * @private
    */
-  async *#runQuery({ prompt, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId }) {
+  async *#runQuery({ prompt, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan }) {
 
     // ─── Pre-query: Memory Injection (task-287) + Compact Summary ──
     // Two-layer recall:
@@ -902,10 +902,19 @@ export class Engine {
         if (vpPersona && vpPersona.vpId) {
           const priorPlan = extractPriorPlan(conversationMessages, vpPersona.vpId);
           const thinkingCfg = (this.#config && this.#config.thinking) || {};
+          // PR-I: live routerPlan.thinking — when the dispatcher passes
+          // `vpPlan` for this turn (per-VP plan from the V2 router) and its
+          // `vpId` matches the active persona, surface its `thinking` field
+          // to resolveThinking. Mismatched vpId means the plan addresses a
+          // different VP — ignore it for this VP's thinking decision.
+          const liveRouterThinking = (vpPlan && typeof vpPlan === 'object'
+            && typeof vpPlan.vpId === 'string' && vpPlan.vpId === vpPersona.vpId
+            && (vpPlan.thinking === 'high' || vpPlan.thinking === 'max'))
+            ? vpPlan.thinking
+            : null;
           const resolved = resolveThinking({
             uiOverride: (userEffort === 'max' || userEffort === 'high') ? userEffort : null,
-            routerPlan: null, // PR-C scope: priorPlan continuity only;
-                              // live router-plan thinking is a follow-up.
+            routerPlan: liveRouterThinking,
             priorPlan: priorPlan && priorPlan.thinking ? priorPlan.thinking : null,
             vpDefault: typeof vpPersona.thinking === 'string' ? vpPersona.thinking : null,
             globalDefault: typeof thinkingCfg.default === 'string' ? thinkingCfg.default : null,
@@ -1106,12 +1115,29 @@ export class Engine {
       // assistant message that produced it. Stripped at the wire by
       // stripMetaForWire — pure bookkeeping for priorPlan continuity.
       if (vpPersona && vpPersona.vpId) {
+        // PR-I: when the dispatcher hands us a per-VP plan whose vpId matches
+        // the active persona, persist its `forwardQuery`, `preselect`, and
+        // `thinking` on the assistant message so the next turn's
+        // priorPlan continuity (DESIGN.md §9.15) sees the live router's
+        // decision — not a synthetic stub.
+        const planForThisVp = (vpPlan && typeof vpPlan === 'object'
+          && typeof vpPlan.vpId === 'string' && vpPlan.vpId === vpPersona.vpId)
+          ? vpPlan
+          : null;
         attachRouterPlan(assistantMsg, {
           vpId: vpPersona.vpId,
-          forwardQuery: { userOriginal: prompt || '', intent: '' },
-          preselect: undefined,
-          thinking: null,
-          thinkingReason: '',
+          forwardQuery: planForThisVp && planForThisVp.forwardQuery
+            ? planForThisVp.forwardQuery
+            : { userOriginal: prompt || '', intent: '' },
+          preselect: planForThisVp && planForThisVp.preselect
+            ? planForThisVp.preselect
+            : undefined,
+          thinking: planForThisVp && (planForThisVp.thinking === 'high' || planForThisVp.thinking === 'max')
+            ? planForThisVp.thinking
+            : null,
+          thinkingReason: planForThisVp && typeof planForThisVp.thinkingReason === 'string'
+            ? planForThisVp.thinkingReason
+            : '',
         });
       }
       conversationMessages.push(assistantMsg);

package/unify/memory/dream-scheduler.js

@@ -25,6 +25,7 @@ import { dreamShard } from './dream-shard.js';
 import { checkRecompression } from './recompression.js';
 import { runUserDreamJob } from './user-memory-store.js';
 import { runDreamTick } from '../dream-v2/tick.js';
+import { createScopeRefreshHook } from '../dream-v2/refresh.js';
 
 /** Default idle timeout before dream triggers (ms). */
 export const DREAM_IDLE_MS = 30 * 60 * 1000; // 30 min
@@ -169,16 +170,14 @@ export function createDreamScheduler(opts = {}) {
         try {
           const scopes = [{ kind: 'user', scopeDir: 'user' }];
           if (group?.id) scopes.push({ kind: 'group', id: group.id, scopeDir: `groups/${group.id}` });
+          // PR-J: real refresh hook — read each scope's `index.md`,
+          // render a deterministic top-N synopsis, atomically write
+          // `summary.md`. No LLM, refresh-only (DESIGN.md §8 line 395).
+          const refresh = createScopeRefreshHook({ root: memoryDir });
           const tickResult = await runDreamTick({
             root: memoryDir,
             scopes,
-            refresh: async (_scope) => {
-              // v1 refresh hook: no-op placeholder. The actual scope
-              // summary refresh continues to flow through the legacy
-              // shard / user-dream paths above; this tick only
-              // exercises the diff-gate + cursor write so future hook
-              // implementations can plug in without re-wiring.
-            },
+            refresh,
           });
           result.dreamV2Tick = {
             ran: tickResult.ran.length,

package/unify/threads/engine-instance.js

@@ -97,7 +97,7 @@ export class EngineInstance {
    * @param {AbortSignal} [params.signal]
    * @yields {object} EngineEvent with { ...event, threadId }
    */
-  async *query({ prompt, mode, signal, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId } = {}) {
+  async *query({ prompt, mode, signal, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan } = {}) {
     if (this.#terminated) {
       yield {
         type: 'error',
@@ -173,7 +173,7 @@ export class EngineInstance {
       curToolResults = [];
     }
 
-    for await (const event of this.#engine.query({ prompt, mode, messages: snapshot, signal, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId })) {
+    for await (const event of this.#engine.query({ prompt, mode, messages: snapshot, signal, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan })) {
       // Re-tag every event with the bound threadId. Non-object events
       // (shouldn't happen — all engine events are objects) are passed
       // through untouched.