@yeaft/webchat-agent 0.1.595 → 0.1.596

package/package.json

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

package/unify/dream-v2/diff-gate.js

@@ -0,0 +1,89 @@
+/**
+ * dream-v2/diff-gate.js — DESIGN.md §9.14.
+ *
+ * Hourly dream tick is cheap by default: read a per-scope cursor, check
+ * whether anything has changed since last pass, skip everything if not.
+ *
+ * The cursor is a tiny JSON file `<scopeDir>/.dream-cursor.json`:
+ *
+ *   { "lastTickAt": "<ISO>", "lastSeenSig": "<opaque>" }
+ *
+ * `lastSeenSig` is whatever the caller wants to put there — typically a
+ * hash of the entries dir mtime + index.md mtime. The diff-gate doesn't
+ * compute the signature; it just compares the supplied "current" against
+ * the stored "last". That keeps signatures pluggable (mtime today, content
+ * hash later, ETag on a remote scope etc.).
+ */
+
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+
+const FILE = '.dream-cursor.json';
+
+/**
+ * @param {string} root
+ * @param {string} scopeDir
+ * @returns {string}
+ */
+export function cursorPath(root, scopeDir) {
+  if (!root || !scopeDir) throw new Error('cursorPath: root + scopeDir required');
+  return join(root, scopeDir, FILE);
+}
+
+/**
+ * @param {{ root: string, scopeDir: string }} args
+ * @returns {Promise<{ lastTickAt: string|null, lastSeenSig: string|null }>}
+ */
+export async function readCursor({ root, scopeDir }) {
+  const path = cursorPath(root, scopeDir);
+  try {
+    const content = await fs.readFile(path, 'utf8');
+    const parsed = JSON.parse(content);
+    return {
+      lastTickAt: typeof parsed?.lastTickAt === 'string' ? parsed.lastTickAt : null,
+      lastSeenSig: typeof parsed?.lastSeenSig === 'string' ? parsed.lastSeenSig : null,
+    };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { lastTickAt: null, lastSeenSig: null };
+    if (err instanceof SyntaxError) return { lastTickAt: null, lastSeenSig: null };
+    throw err;
+  }
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   scopeDir: string,
+ *   sig: string,
+ *   tickAt?: string,
+ * }} args
+ */
+export async function writeCursor({ root, scopeDir, sig, tickAt }) {
+  if (typeof sig !== 'string') throw new Error('writeCursor: sig must be string');
+  const path = cursorPath(root, scopeDir);
+  await fs.mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  await fs.writeFile(tmp, JSON.stringify({
+    lastTickAt: tickAt || new Date().toISOString(),
+    lastSeenSig: sig,
+  }), 'utf8');
+  await fs.rename(tmp, path);
+}
+
+/**
+ * Diff-gate decision. Pure: takes (last, current) and returns whether
+ * dream should run. Caller decides what `currentSig` means.
+ *
+ * @param {{ lastSeenSig: string|null }} last
+ * @param {string} currentSig
+ * @returns {{ skip: boolean, reason: string }}
+ */
+export function shouldRunDream(last, currentSig) {
+  if (!last || last.lastSeenSig == null) {
+    return { skip: false, reason: 'no_cursor' };
+  }
+  if (last.lastSeenSig !== currentSig) {
+    return { skip: false, reason: 'diff' };
+  }
+  return { skip: true, reason: 'no_diff' };
+}

package/unify/dream-v2/scope-sig.js

@@ -0,0 +1,42 @@
+/**
+ * dream-v2/scope-sig.js — DESIGN.md §9.14.
+ *
+ * Default signature for a scope dir: combine the mtimes of `entries/`,
+ * `index.md`, `summary.md` into a stable opaque string. Cheap and
+ * dependency-free — we explicitly stay out of "compute SHA over all
+ * entry bodies" territory because the dream tick is meant to be
+ * fingertip-cheap when nothing changed.
+ *
+ * Missing files contribute `0` to the signature, so cold-start scopes
+ * have a stable "empty" signature until the first entry lands.
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+/**
+ * @param {{ root: string, scopeDir: string }} args
+ * @returns {Promise<string>}
+ */
+export async function computeScopeSig({ root, scopeDir }) {
+  if (!root || !scopeDir) throw new Error('computeScopeSig: root + scopeDir required');
+  const targets = [
+    join(root, scopeDir, 'entries'),
+    join(root, scopeDir, 'index.md'),
+    join(root, scopeDir, 'summary.md'),
+  ];
+  const stamps = [];
+  for (const p of targets) {
+    try {
+      const s = await fs.stat(p);
+      stamps.push(`${s.mtimeMs.toFixed(0)}:${s.size}`);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        stamps.push('0:0');
+      } else {
+        throw err;
+      }
+    }
+  }
+  return stamps.join('|');
+}

package/unify/dream-v2/tick.js

@@ -0,0 +1,99 @@
+/**
+ * dream-v2/tick.js — DESIGN.md §9.14 dream cadence.
+ *
+ * Hourly tick:
+ *   1. For each registered scope, compute current signature.
+ *   2. Read the scope cursor; if no diff, skip.
+ *   3. On diff (or `force`), call the supplied `refresh(scope)` hook,
+ *      which is responsible for rewriting `summary.md` / `index.md`.
+ *      Any errors per scope are captured; other scopes still run.
+ *   4. Write the new cursor.
+ *
+ * Phase 6 is intentionally refresh-only (DESIGN.md §8 line 395:
+ * "Thin: skip pruning/demotion; refresh-only in v1"). The `refresh`
+ * hook gets to decide what "refresh" means; this file just sequences
+ * the diff-gated calls.
+ */
+
+import { computeScopeSig } from './scope-sig.js';
+import { readCursor, writeCursor, shouldRunDream } from './diff-gate.js';
+
+/**
+ * @typedef {{ kind: 'user'|'group'|'vp'|'task', id?: string, scopeDir: string }} ScopeRef
+ */
+
+/**
+ * @param {{
+ *   root: string,
+ *   scopes: ScopeRef[],
+ *   refresh: (scope: ScopeRef) => Promise<void>,
+ *   force?: boolean,
+ *   computeSig?: (scope: ScopeRef) => Promise<string>,
+ *   now?: () => string,
+ * }} args
+ * @returns {Promise<{
+ *   ran: Array<{ scopeDir: string, reason: string }>,
+ *   skipped: Array<{ scopeDir: string, reason: string }>,
+ *   errors: Array<{ scopeDir: string, error: Error }>,
+ * }>}
+ */
+export async function runDreamTick({
+  root, scopes, refresh, force = false,
+  computeSig, now,
+}) {
+  if (!root) throw new Error('runDreamTick: root required');
+  if (!Array.isArray(scopes)) throw new Error('runDreamTick: scopes array required');
+  if (typeof refresh !== 'function') throw new Error('runDreamTick: refresh fn required');
+
+  const sigOf = typeof computeSig === 'function'
+    ? computeSig
+    : (s) => computeScopeSig({ root, scopeDir: s.scopeDir });
+  const stamp = typeof now === 'function' ? now : () => new Date().toISOString();
+
+  const ran = [];
+  const skipped = [];
+  const errors = [];
+
+  for (const scope of scopes) {
+    if (!scope || !scope.scopeDir) continue;
+    let sig;
+    try {
+      sig = await sigOf(scope);
+    } catch (err) {
+      errors.push({ scopeDir: scope.scopeDir, error: err });
+      continue;
+    }
+    const last = await readCursor({ root, scopeDir: scope.scopeDir });
+    const decision = force
+      ? { skip: false, reason: 'forced' }
+      : shouldRunDream(last, sig);
+
+    if (decision.skip) {
+      skipped.push({ scopeDir: scope.scopeDir, reason: decision.reason });
+      continue;
+    }
+
+    try {
+      await refresh(scope);
+      ran.push({ scopeDir: scope.scopeDir, reason: decision.reason });
+    } catch (err) {
+      errors.push({ scopeDir: scope.scopeDir, error: err });
+      // Do NOT advance the cursor on failure — next tick should retry.
+      continue;
+    }
+
+    // Recompute the sig AFTER refresh in case the refresh hook itself
+    // wrote files; this is the value we want to compare against next tick.
+    let postSig;
+    try {
+      postSig = await sigOf(scope);
+    } catch {
+      postSig = sig;
+    }
+    await writeCursor({
+      root, scopeDir: scope.scopeDir, sig: postSig, tickAt: stamp(),
+    });
+  }
+
+  return { ran, skipped, errors };
+}