@yeaft/webchat-agent 0.1.543 → 0.1.545

package/package.json

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

package/unify/memory/user-memory-store.js

@@ -0,0 +1,222 @@
+/**
+ * user-memory-store.js — R6 §Δ29 User-memory store + dream + profile builder.
+ *
+ * Wraps the R6 shard-store (task-334f) with user-specific semantics:
+ *   - 5 shards: profile / preferences / projects / goals / relations
+ *   - Storage path: ~/.yeaft/user/memory/
+ *   - UserDreamJob: reuses dream-shard.js compact framework
+ *   - buildUserProfile(): top-N recall for SEMI-DYNAMIC injection
+ *
+ * Hard constraints:
+ *   - No VP/task memory imports (user memory is orthogonal)
+ *   - Never throws from public API — best-effort with console.warn fallback
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { existsSync } from 'fs';
+import { openMemoryShardStore } from './shard-store.js';
+import { USER_SHARDS } from './schema.js';
+import { scanShards, runCompactJob } from './dream-shard.js';
+
+/** Default storage root for user memory. */
+export const USER_MEMORY_DIR = join(homedir(), '.yeaft', 'user', 'memory');
+
+/** Maximum entries to include in the user_profile prompt segment. */
+const PROFILE_TOP_N = 5;
+
+/** Shard priority for profile builder recall (most → least relevant). */
+const PROFILE_RECALL_SHARDS = ['profile', 'preferences', 'goals'];
+
+// ─── Lazy singleton ───────────────────────────────────────────
+
+/** @type {ReturnType<typeof openMemoryShardStore> | null} */
+let _store = null;
+
+/**
+ * Get (or lazily create) the process-singleton user-memory shard store.
+ * Returns null on failure (missing dir, permissions, etc.) — caller must
+ * handle null gracefully.
+ *
+ * @param {{ dir?: string }} [opts]
+ * @returns {ReturnType<typeof openMemoryShardStore> | null}
+ */
+export function getUserMemoryStore(opts = {}) {
+  if (_store) return _store;
+  try {
+    const dir = opts.dir || USER_MEMORY_DIR;
+    _store = openMemoryShardStore(dir, 'user');
+    return _store;
+  } catch (err) {
+    console.warn('[user-memory-store] failed to open store:', err.message);
+    return null;
+  }
+}
+
+/**
+ * Close and reset the singleton. Used by tests.
+ */
+export function _resetUserMemoryStoreForTest() {
+  if (_store) {
+    try { _store.close(); } catch { /* ignore */ }
+  }
+  _store = null;
+}
+
+/**
+ * Open a fresh (non-singleton) user-memory store at an arbitrary dir.
+ * Useful for tests that want isolation.
+ */
+export function openUserMemoryStore(dir) {
+  return openMemoryShardStore(dir, 'user');
+}
+
+// ─── Write / Remove ──────────────────────────────────────────
+
+/**
+ * Classify user-memory text into a shard based on simple heuristics.
+ * Falls back to 'profile' when uncertain.
+ *
+ * @param {string} text
+ * @param {string[]} [tags]
+ * @returns {string}
+ */
+export function classifyUserMemoryShard(text, tags) {
+  const lower = (text || '').toLowerCase();
+  const tagSet = new Set((tags || []).map(t => t.toLowerCase()));
+
+  // Explicit tag hints
+  if (tagSet.has('goal') || tagSet.has('goals')) return 'goals';
+  if (tagSet.has('project') || tagSet.has('projects')) return 'projects';
+  if (tagSet.has('preference') || tagSet.has('preferences')) return 'preferences';
+  if (tagSet.has('relation') || tagSet.has('relations')) return 'relations';
+  if (tagSet.has('profile')) return 'profile';
+
+  // Keyword heuristics
+  if (/\b(goal|objective|target|aim|aspir|want to|plan to|hope to)\b/i.test(lower)) return 'goals';
+  if (/\b(project|repo|codebase|app|application|product)\b/i.test(lower)) return 'projects';
+  if (/\b(prefer|like|dislike|style|format|tone|language|dark mode|theme)\b/i.test(lower)) return 'preferences';
+  if (/\b(colleague|friend|team|manager|report|partner|contact|person)\b/i.test(lower)) return 'relations';
+
+  return 'profile';
+}
+
+/**
+ * Ingest a user-memory write. Returns the entryId on success, null on failure.
+ *
+ * @param {object} store — user-memory shard store
+ * @param {{ text: string, tags?: string[], sourceRef?: object }} params
+ * @returns {string|null} entryId
+ */
+export function writeUserMemory(store, { text, tags, sourceRef }) {
+  if (!store || !text || typeof text !== 'string' || !text.trim()) return null;
+  try {
+    const shard = classifyUserMemoryShard(text, tags);
+    const id = `um-${randomUUID().slice(0, 12)}`;
+    const entry = {
+      id,
+      shard,
+      kind: 'preference', // user-memory entries are preference-kind (no sourceRef required)
+      body: text.trim(),
+      tags: Array.isArray(tags) ? tags.slice() : [],
+      authoredBy: 'user:self',
+    };
+    store.put(entry);
+    return id;
+  } catch (err) {
+    console.warn('[user-memory-store] write failed:', err.message);
+    return null;
+  }
+}
+
+/**
+ * Remove a user-memory entry by id. Returns true on success.
+ *
+ * @param {object} store
+ * @param {string} entryId
+ * @returns {boolean}
+ */
+export function removeUserMemory(store, entryId) {
+  if (!store || !entryId) return false;
+  try {
+    store.remove(entryId);
+    return true;
+  } catch (err) {
+    console.warn('[user-memory-store] remove failed:', err.message);
+    return false;
+  }
+}
+
+// ─── Profile Builder ─────────────────────────────────────────
+
+/**
+ * Build the `user_profile` text segment for SEMI-DYNAMIC prompt injection.
+ * Reads top-N entries from profile/preferences/goals shards and formats
+ * them as a compact bullet list.
+ *
+ * @param {object} [store] — user-memory shard store (uses singleton if omitted)
+ * @param {{ maxEntries?: number }} [opts]
+ * @returns {string} — empty string if no user-memory exists
+ */
+export function buildUserProfile(store, opts = {}) {
+  const s = store || getUserMemoryStore();
+  if (!s) return '';
+
+  const max = opts.maxEntries || PROFILE_TOP_N;
+  const lines = [];
+
+  try {
+    for (const shardName of PROFILE_RECALL_SHARDS) {
+      if (lines.length >= max) break;
+      const { results } = s.query({ shard: shardName });
+      // Filter out superseded entries
+      const live = results.filter(r => !r.supersededBy);
+      // Take most recent first (results are already ordered by storage)
+      for (const rec of live) {
+        if (lines.length >= max) break;
+        const full = s.get(rec.id);
+        if (!full || !full.body) continue;
+        const body = full.body.trim();
+        if (!body) continue;
+        lines.push(`- ${body}`);
+      }
+    }
+  } catch (err) {
+    console.warn('[user-memory-store] buildUserProfile failed:', err.message);
+    return '';
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Dream Job ───────────────────────────────────────────────
+
+/**
+ * Run user-memory dream maintenance (compact low-utilization shards).
+ * Reuses dream-shard.js compact framework — no LLM calls needed for
+ * user-memory (user-authored entries don't need merge/prune by an LLM;
+ * we only compact to reclaim superseded/removed tombstones).
+ *
+ * @param {{ store?: object, onPhase?: (phase:string, data:any) => void }} [opts]
+ * @returns {{ scan: object, compact: object } | null}
+ */
+export function runUserDreamJob(opts = {}) {
+  const store = 'store' in opts ? opts.store : getUserMemoryStore();
+  if (!store) return null;
+
+  try {
+    const scan = scanShards(store);
+    const compact = runCompactJob({
+      shardStore: store,
+      shardNames: scan.needsCompaction,
+      onCompact: opts.onPhase
+        ? (shard, r) => opts.onPhase('compact', { shard, ...r })
+        : undefined,
+    });
+    return { scan: { totalEntries: scan.totalEntries, totalBytes: scan.totalBytes }, compact };
+  } catch (err) {
+    console.warn('[user-memory-store] dream job failed:', err.message);
+    return null;
+  }
+}

package/unify/user-memory.js

@@ -1,10 +1,9 @@
 /**
- * user-memory.js — R6 §Δ29 user-memory WS event skeleton.
+ * user-memory.js — R6 §Δ29 user-memory WS event handlers.
  *
- * PLACEHOLDER ONLY. Actual ingestion / shard write / cross-task recall
- * is owned by task-334l. This file reserves three event names on the
- * wire + acknowledges the request so the web client can ship its
- * emitter code without a dependency-cycle on 334l's storage layer.
+ * Replaces the stub (task-334h) with real ingestion backed by the R6
+ * shard-store. Writes land immediately in `~/.yeaft/user/memory/` with
+ * a real entryId; the ack carries `reason: 'accepted'`.
  *
  * Wire shapes (frozen by R6 §Δ31.6 table; additive fields only):
  *
@@ -12,23 +11,19 @@
  *     { type, text, tags?, sourceRef?, requestId? }
  *
  *   outbound (agent → web):  `user_memory_updated`
- *     { type, entryId?, reason: 'accepted'|'deferred'|'noop',
+ *     { type, entryId?, reason: 'accepted'|'noop',
  *       requestId?, pending?: boolean }
  *
  *   outbound (agent → web):  `user_memory_removed`
  *     { type, entryId, requestId? }
- *
- * Current behaviour: every write is replied with `user_memory_updated`
- * carrying `reason: 'deferred'` and `pending: true` — the frontend
- * treats this as "queued but not yet persisted" and keeps the toast in
- * a muted state. 334l will flip the reason to `'accepted'` with a
- * concrete `entryId` once the ingestion pipeline lands.
- *
- * No removal path is offered yet (would require the storage layer to
- * have produced entryIds first); the handler is exported as a named
- * stub so the router can wire it without a second edit when 334l ships.
  */
 
+import {
+  getUserMemoryStore,
+  writeUserMemory,
+  removeUserMemory,
+} from './memory/user-memory-store.js';
+
 /** @type {(event:object)=>void | null} */
 let _sendUnifyEvent = null;
 
@@ -43,12 +38,12 @@ export function setUserMemorySender(fn) {
 /**
  * WS handler: `unify_user_memory_write`.
  *
- * Validates the minimum shape (non-empty string `text`) and replies with
- * a `user_memory_updated` ack carrying `pending: true`. Never throws.
+ * Validates the minimum shape (non-empty string `text`), writes to the
+ * user-memory shard store, and replies with a `user_memory_updated` ack
+ * carrying the real entryId. Never throws.
  *
  * @param {any} msg
  * @param {(event:object)=>void} [sendUnifyEvent] — optional override
- *   (falls back to the module-level sender installed via setUserMemorySender)
  */
 export function handleUnifyUserMemoryWrite(msg, sendUnifyEvent) {
   const send = sendUnifyEvent || _sendUnifyEvent;
@@ -69,22 +64,27 @@ export function handleUnifyUserMemoryWrite(msg, sendUnifyEvent) {
     return;
   }
 
-  // Placeholder — 334l replaces this with real ingestion.
+  // Real ingestion via shard store.
+  const store = getUserMemoryStore();
+  const tags = Array.isArray(msg.tags) ? msg.tags : [];
+  const sourceRef = msg.sourceRef && typeof msg.sourceRef === 'object' ? msg.sourceRef : undefined;
+  const entryId = store ? writeUserMemory(store, { text, tags, sourceRef }) : null;
+
   try {
     send({
       type: 'user_memory_updated',
-      reason: 'deferred',
-      pending: true,
+      reason: entryId ? 'accepted' : 'deferred',
+      pending: !entryId,
+      entryId: entryId || undefined,
       ...(requestId ? { requestId } : {}),
     });
   } catch { /* best-effort */ }
 }
 
 /**
- * WS handler: `unify_user_memory_remove` (skeleton).
+ * WS handler: `unify_user_memory_remove`.
  *
- * Until 334l lands we have no entries to remove; reply with a noop
- * `user_memory_updated` so the UI can clear its toast.
+ * Removes the entry from the user-memory shard store and acks.
  */
 export function handleUnifyUserMemoryRemove(msg, sendUnifyEvent) {
   const send = sendUnifyEvent || _sendUnifyEvent;
@@ -93,11 +93,14 @@ export function handleUnifyUserMemoryRemove(msg, sendUnifyEvent) {
   const requestId = msg && typeof msg.requestId === 'string' ? msg.requestId : undefined;
   const entryId = msg && typeof msg.entryId === 'string' ? msg.entryId : null;
 
+  const store = getUserMemoryStore();
+  const removed = entryId && store ? removeUserMemory(store, entryId) : false;
+
   try {
     send({
       type: 'user_memory_removed',
       entryId,
-      pending: true, // 334l will flip once real removal lands
+      pending: !removed,
       ...(requestId ? { requestId } : {}),
     });
   } catch { /* best-effort */ }