@yeaft/webchat-agent 0.1.666 → 0.1.669

package/connection/message-router.js

@@ -35,7 +35,7 @@ import {
 import { sendToServer, flushMessageBuffer } from './buffer.js';
 import { handleRestartAgent, handleUpgradeAgent } from './upgrade.js';
 import { loadMcpServers, updateMcpConfig } from '../mcp.js';
-import { getLlmConfig, updateLlmConfig, getUnifySettings, updateUnifySettings } from '../unify/config-api.js';
+import { getLlmConfig, updateLlmConfig, getUnifySettings, updateUnifySettings, getSearchSettings, updateSearchSettings, fetchTavilyUsage } from '../unify/config-api.js';
 import { handleUnifyChat, handleUnifyGroupChat, handleUnifyModeSwitch, handleUnifyModelSwitch, resetUnifySession, handleUnifyLoadHistory, handleUnifyAbortThread, handleUnifyAbortAll, handleUnifyVpSubscribe, handleUnifyVpCreate, handleUnifyVpUpdate, handleUnifyVpDelete, handleUnifyVpRead, handleUnifyFeatureMessage, handleUnifyFetchSummaryHistory, handleUnifyFeatureCrud, handleUnifyListGroups, handleUnifyCreateGroup, handleUnifyRenameGroup, handleUnifyArchiveGroup, handleUnifyDeleteGroup, handleUnifyAddMember, handleUnifyRemoveMember, handleUnifySetDefaultVp, handleUnifyDreamTrigger } from '../unify/web-bridge.js';
 
 export async function handleMessage(msg) {
@@ -355,6 +355,29 @@ export async function handleMessage(msg) {
       break;
     }
 
+    // Search settings (web-search backend + Tavily key) — read/write the
+    // `search` section of config.json. `get_tavily_usage` hits Tavily's
+    // /usage endpoint with the saved key and is fired from the UI only
+    // when the Search tab opens or the user clicks "Refresh" (no polling
+    // — the user explicitly asked for live read on open).
+    case 'get_search_settings': {
+      const settings = getSearchSettings(ctx.CONFIG?.yeaftDir);
+      sendToServer({ type: 'search_settings', ...settings });
+      break;
+    }
+
+    case 'update_search_settings': {
+      const result = updateSearchSettings(msg.settings || msg.config || {}, ctx.CONFIG?.yeaftDir);
+      sendToServer({ type: 'search_settings_updated', ...result });
+      break;
+    }
+
+    case 'get_tavily_usage': {
+      const usage = await fetchTavilyUsage(ctx.CONFIG?.yeaftDir);
+      sendToServer({ type: 'tavily_usage', ...usage });
+      break;
+    }
+
     // Unify — independent chat via Engine
     case 'unify_chat':
       await handleUnifyChat(msg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.666",
+  "version": "0.1.669",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",
@@ -10,7 +10,8 @@
   },
   "scripts": {
     "start": "node index.js",
-    "dev": "nodemon index.js"
+    "dev": "nodemon index.js",
+    "postinstall": "node scripts/check-pty.js"
   },
   "engines": {
     "node": ">=22.5.0"

package/scripts/check-pty.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * agent/scripts/check-pty.js — postinstall sanity check for node-pty.
+ *
+ * Why this exists:
+ *   `node-pty` is an optionalDependency. npm install swallows install
+ *   failures silently — when the native module fails to build (e.g.
+ *   Linux x64, where node-pty's tarball ships no prebuilds and the
+ *   host g++ is too old to compile C++20), the agent loses its
+ *   `terminal` capability with zero user-facing signal. The web UI's
+ *   Terminal tab silently disappears.
+ *
+ *   This postinstall script makes that failure visible: if we're on a
+ *   platform where node-pty was supposed to install but didn't, print
+ *   a clear warning with the recovery command. We never fail the
+ *   install — pty is genuinely optional, and required-feature mode
+ *   would block users who don't need a Terminal tab.
+ *
+ * Exit code is always 0 — we only print, never abort.
+ */
+
+import { existsSync } from 'fs';
+import { createRequire } from 'module';
+import { platform } from 'os';
+
+const require = createRequire(import.meta.url);
+
+function tryResolveNodePty() {
+  try {
+    return require.resolve('node-pty');
+  } catch {
+    return null;
+  }
+}
+
+function tryLoadBinary() {
+  // node-pty's lib/index.js does `require('../build/Release/pty.node')`
+  // — if the binary is missing or ABI-incompatible, that throws. We
+  // mimic the load eagerly so the warning fires at install time, not
+  // at agent startup.
+  try {
+    require('node-pty');
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+const resolved = tryResolveNodePty();
+if (!resolved) {
+  // node-pty was never installed at all — npm skipped it for the
+  // current platform/engine combination.
+  const plat = platform();
+  if (plat === 'linux' || plat === 'darwin' || plat === 'win32') {
+    console.warn('');
+    console.warn('  ⚠  node-pty was not installed on this host.');
+    console.warn('     The agent will run, but the web UI Terminal tab');
+    console.warn('     will be hidden (terminal capability missing).');
+    if (plat === 'linux') {
+      console.warn('');
+      console.warn('     Linux fix: install a C++20-capable compiler');
+      console.warn('     (g++-10 or newer) and rebuild:');
+      console.warn('');
+      console.warn('       sudo apt-get install -y g++-10');
+      console.warn('       CXX=g++-10 npm install node-pty --include=optional');
+    } else {
+      console.warn('');
+      console.warn('     Reinstall to retry:  npm install node-pty');
+    }
+    console.warn('');
+  }
+  process.exit(0);
+}
+
+const loaded = tryLoadBinary();
+if (!loaded.ok) {
+  console.warn('');
+  console.warn('  ⚠  node-pty resolved but failed to load native binary.');
+  console.warn(`     Error: ${loaded.error}`);
+  console.warn('     The agent will run without Terminal tab support.');
+  console.warn('     Recover: npm rebuild node-pty');
+  console.warn('');
+  process.exit(0);
+}
+
+// Silent on success — clean install output.
+process.exit(0);

package/unify/config-api.js

@@ -215,3 +215,154 @@ export function updateUnifySettings(update, dir) {
 
   return merged;
 }
+
+// ─── Search settings (web-search backend selection + Tavily key) ────
+
+/**
+ * Valid backend values. `playwright` is reserved for the upcoming
+ * playwright-service tool — its UI option is currently disabled, but we
+ * accept the literal so a hand-edited config doesn't trip validation.
+ * Anything else is rejected on write and normalized to `tavily` on read.
+ */
+const VALID_BACKENDS = ['tavily', 'playwright'];
+
+function maskKey(key) {
+  if (!key || typeof key !== 'string') return null;
+  if (key.length <= 10) return '***';
+  return `${key.slice(0, 6)}...${key.slice(-4)}`;
+}
+
+/**
+ * Read the `search` section of config.json. Tavily key is returned in
+ * masked form (`tvly-d...j3dgV`) — the raw key never leaves the agent.
+ * UI uses `tavilyKeyConfigured` to decide whether the input shows a
+ * "(unchanged)" placeholder vs an empty box.
+ *
+ * @param {string} [dir]
+ * @returns {{ backend: string, tavilyKeyConfigured: boolean, tavilyKeyMasked: string|null, disableHtmlFallback: boolean } | { error: string }}
+ */
+export function getSearchSettings(dir) {
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+  const defaults = {
+    backend: 'tavily',
+    tavilyKeyConfigured: false,
+    tavilyKeyMasked: null,
+    disableHtmlFallback: false,
+  };
+  if (!existsSync(configPath)) return defaults;
+  try {
+    const json = JSON.parse(readFileSync(configPath, 'utf8'));
+    const s = (json && typeof json.search === 'object' && json.search) || {};
+    const backend = VALID_BACKENDS.includes(s.backend) ? s.backend : 'tavily';
+    const key = typeof s.tavilyApiKey === 'string' ? s.tavilyApiKey : '';
+    return {
+      backend,
+      tavilyKeyConfigured: !!key,
+      tavilyKeyMasked: key ? maskKey(key) : null,
+      disableHtmlFallback: !!s.disableHtmlFallback,
+    };
+  } catch (e) {
+    return { error: `Failed to read config.json: ${e.message}` };
+  }
+}
+
+/**
+ * Update the `search` section of config.json. Update is shallow-merged:
+ * any field omitted from `update` keeps its previous value. Pass
+ * `tavilyApiKey: ''` explicitly to clear the key; pass `undefined` (or
+ * omit) to keep it unchanged — this is what the UI relies on so the
+ * "(unchanged)" placeholder doesn't accidentally wipe a saved key when
+ * the user only touches the backend radio.
+ *
+ * @param {{ backend?: string, tavilyApiKey?: string, disableHtmlFallback?: boolean }} update
+ * @param {string} [dir]
+ * @returns {ReturnType<typeof getSearchSettings>}
+ */
+export function updateSearchSettings(update, dir) {
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+
+  if (!update || typeof update !== 'object') {
+    return { error: 'update payload required' };
+  }
+  if (update.backend !== undefined && !VALID_BACKENDS.includes(update.backend)) {
+    return { error: `backend must be one of: ${VALID_BACKENDS.join(', ')}` };
+  }
+  if (update.tavilyApiKey !== undefined && typeof update.tavilyApiKey !== 'string') {
+    return { error: 'tavilyApiKey must be a string' };
+  }
+
+  let existing = {};
+  if (existsSync(configPath)) {
+    try {
+      existing = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      existing = {};
+    }
+  }
+  const prev = (existing && typeof existing.search === 'object' && existing.search) || {};
+  const merged = { ...prev };
+  if (update.backend !== undefined) merged.backend = update.backend;
+  if (update.tavilyApiKey !== undefined) merged.tavilyApiKey = update.tavilyApiKey;
+  if (update.disableHtmlFallback !== undefined) merged.disableHtmlFallback = !!update.disableHtmlFallback;
+  existing.search = merged;
+
+  try {
+    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+  } catch (e) {
+    return { error: `Failed to write config.json: ${e.message}` };
+  }
+  return getSearchSettings(root);
+}
+
+/**
+ * Probe Tavily's `/usage` endpoint with the currently-saved key. Returns
+ * the plan + usage fields the UI shows, or `{ error }` for any of:
+ *   - no key configured
+ *   - HTTP error from Tavily (401 = bad key, etc.)
+ *   - network failure
+ *
+ * Called only when the user opens the Search settings tab (the user
+ * explicitly asked for "open settings → live read, don't poll"). No
+ * caching here — a stale display is more confusing than a fresh probe.
+ *
+ * @param {string} [dir]
+ * @returns {Promise<{ plan: string, used: number, limit: number|null, paygoUsed: number, paygoLimit: number|null } | { error: string }>}
+ */
+export async function fetchTavilyUsage(dir) {
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+  if (!existsSync(configPath)) return { error: 'config.json not found' };
+  let key;
+  try {
+    const json = JSON.parse(readFileSync(configPath, 'utf8'));
+    key = json?.search?.tavilyApiKey;
+  } catch (e) {
+    return { error: `Failed to read config.json: ${e.message}` };
+  }
+  if (!key) return { error: 'Tavily API key not configured' };
+
+  try {
+    const res = await fetch('https://api.tavily.com/usage', {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${key}` },
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      return { error: `${res.status} ${res.statusText} ${text.slice(0, 200)}` };
+    }
+    const data = await res.json();
+    const account = data?.account || {};
+    return {
+      plan: account.current_plan || 'unknown',
+      used: Number(account.plan_usage) || 0,
+      limit: account.plan_limit ?? null,
+      paygoUsed: Number(account.paygo_usage) || 0,
+      paygoLimit: account.paygo_limit ?? null,
+    };
+  } catch (e) {
+    return { error: e.message || String(e) };
+  }
+}
+

package/unify/config.js

@@ -217,7 +217,7 @@ function loadLegacyConfig(dir, overrides) {
     maxContinueTurns: overrides.maxContinueTurns ?? fileConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
     // task-318: legacy path never had the `unify` section — defaults.
     unify: normaliseUnifySection(null),
-    // DESIGN-v2 feature flag. Default true (PR-E flipped). Override wins.
+    // H2-AMS feature flag. Default true. Override wins.
     memoryV2: overrides.memoryV2 !== undefined ? !!overrides.memoryV2 : true,
     providers: null,
     primaryModel: null,
@@ -315,7 +315,7 @@ export function loadConfig(overrides = {}) {
     // don't pollute the flat config namespace used by chat/crew code.
     unify: normaliseUnifySection(jsonConfig.unify),
 
-    // DESIGN-v2 feature flag. When true the session opens the FTS5
+    // H2-AMS feature flag. When true the session opens the FTS5
     // SegmentIndex (used by groups/pre-flow.js → memory/preflow.js
     // for pre-turn recall) and wires the v2 dream pipeline
     // (dream-v2/runner.js). When false both are skipped — no recall,

package/unify/dream-v2/apply.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/apply.js — DESIGN-v2 §16 + §17.2.
+ * dream-v2/apply.js.
  *
  * Execute one merged-target action: either UPDATE an existing scope's
  * memory.md/summary.md, or CREATE a new one (currently topic-only).

package/unify/dream-v2/limits.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/limits.js — DESIGN-v2 §18 constants.
+ * dream-v2/limits.js constants.
  *
  * Centralised so tests and runtime share one source of truth. Exposed
  * as both named exports and a `DEFAULT_LIMITS` object for `runDream()`

package/unify/dream-v2/merge.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/merge.js — DESIGN-v2 §15.
+ * dream-v2/merge.js.
  *
  * Pure-code stage between Triage and Apply.
  *

package/unify/dream-v2/runner.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/runner.js — DESIGN-v2 §13.
+ * dream-v2/runner.js.
  *
  * Orchestrates one full dream pass:
  *
@@ -29,7 +29,7 @@
  *
  *   onProgress emits dream_progress events that the web bridge forwards
  *   as `unify_output` messages so the debug panel can render live state
- *   (DESIGN-v2 §19.4). All events flow through the same channel; no new
+ *  . All events flow through the same channel; no new
  *   WebSocket message type is introduced.
  *
  * Everything that touches a shell of the system (LLM, message store,

package/unify/dream-v2/schedule.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/schedule.js — DESIGN-v2 §10.2.
+ * dream-v2/schedule.js.
  *
  * Two trigger paths:
  *
@@ -10,7 +10,7 @@
  *
  * The scheduler is a thin wrapper around `runDream()` that prevents
  * concurrent passes (a second tick while the previous is still running
- * is dropped, not queued — DESIGN-v2 §10.1: "slow is OK, doesn't
+ * is dropped, not queued: "slow is OK, doesn't
  * compete with user latency").
  */
 

package/unify/dream-v2/segment.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/segment.js — DESIGN-v2 §17.
+ * dream-v2/segment.js.
  *
  * Three independent length-control concerns, kept pure so they can be
  * unit-tested without touching disk or any LLM:

package/unify/dream-v2/session-wiring.js

@@ -1,13 +1,12 @@
 /**
- * dream-v2/session-wiring.js — DESIGN-v2 §13 wire-up for session.js.
+ * dream-v2/session-wiring.js wire-up for session.js.
  *
  * Bridges the framework-agnostic `runDream` orchestrator (dream-v2/runner.js)
  * to the live yeaft session: groups store, conversation log, LLM adapter,
  * and the engine's progress event sink.
  *
  * The dream pipeline only activates when `config.memoryV2 === true`. When
- * the flag is off, this module is a no-op — the legacy R6 dream-scheduler
- * keeps running as before (session.js still wires it).
+ * the flag is off, this module is a no-op.
  */
 
 import { join } from 'path';

package/unify/dream-v2/snapshot.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/snapshot.js — DESIGN-v2 §16.3 + §10.
+ * dream-v2/snapshot.js.
  *
  * Pre-Apply backup of memory.md + summary.md to
  * `~/.yeaft/memory/.dream-bak/<ts>/<scope-path>/`. The runner takes a

package/unify/dream-v2/state.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/state.js — DESIGN-v2 §11.
+ * dream-v2/state.js.
  *
  * Two pieces of state, tracked separately:
  *

package/unify/dream-v2/triage.js

@@ -1,5 +1,5 @@
 /**
- * dream-v2/triage.js — DESIGN-v2 §14.
+ * dream-v2/triage.js.
  *
  * Decide, for one group's diff, which scopes should be touched by Apply.
  * The decision is two-staged on purpose:

package/unify/engine.js

@@ -557,8 +557,8 @@ export class Engine {
    * @param {{ profile?: string, entries?: object[] }} [memory]
    * @param {string} [compactSummary]
    * @param {string} [prompt] — user prompt (for skill relevance matching)
-   * @param {string} [memoryInjection] — task-287: prebuilt memory block
-   * @param {string} [userProfile] — user profile from user-memory shard store
+   * @param {string} [memoryInjection] — prebuilt memory block from preflow
+   * @param {string} [userProfile] — user profile string
    * @param {object} [vpPersona]
    * @param {{user?:string, group?:string, vp?:string}} [summaries]
    * @returns {string}
@@ -936,12 +936,10 @@ export class Engine {
     //       memory/preflow.js) — per-turn scoped recall
     //   (b) AMS snapshot (resident summaries + onDemand FTS hits) appended
     //       below
-    // The legacy entries-aggregate `buildMemoryInjection` (index.md / by-project /
-    // by-topic / timeline) was retired in the H2-AMS rip.
     let memoryInjection = '';
     let recallEntryCount = 0;
 
-    // R6 recall: append shard-based recall results to memory injection
+    // FTS5 recall: append per-turn scoped hits to memory injection
     const recallResult = await this.#recallMemory(prompt, {
       groupId,
       vpId: vpPersona && typeof vpPersona === 'object' && typeof vpPersona.vpId === 'string'

package/unify/eval/cases/memory.js

@@ -1,134 +1,11 @@
 /**
  * eval/cases/memory.js — Memory recall eval cases
  *
- * Tests the memory recall pipeline:
- *   - Keyword extraction accuracy
- *   - Scope + tag filtering
- *   - LLM selection (when >7 candidates)
- *   - Fingerprint caching
- *   - Memory injection into system prompt
+ * Smoke-level evals for the H2-AMS memory pipeline. Detailed mocks live
+ * in unit tests; this file only declares the eval scenarios.
  */
 
-import {
-  noError,
-  containsText,
-  custom,
-} from '../runner.js';
-
-// ─── Memory Recall Test Helpers ──────────────────────────────
-
-/**
- * Create an engine with pre-loaded memory entries for eval.
- * Uses a mock MemoryStore that returns predefined entries.
- */
-function createMockMemoryStore(entries) {
-  return {
-    readProfile: () => 'User is a senior TypeScript developer who prefers functional programming.',
-    readEntry: (name) => entries.find(e => e.name === name) || null,
-    readSection: () => '',
-    listEntries: () => entries,
-    findByFilter: ({ scope, tags, limit = 15 }) => {
-      // Simple scoring: scope match + tag overlap
-      return entries
-        .map(e => {
-          let score = 0;
-          if (scope && e.scope === scope) score += 3;
-          if (scope && e.scope === 'global') score += 1;
-          if (tags) {
-            for (const t of tags) {
-              if (e.tags && e.tags.includes(t)) score += 1;
-            }
-          }
-          return { ...e, _score: score };
-        })
-        .filter(e => e._score > 0)
-        .sort((a, b) => b._score - a._score)
-        .slice(0, limit);
-    },
-    bumpFrequency: () => {},
-    search: (keyword) => entries.filter(e =>
-      e.content.toLowerCase().includes(keyword.toLowerCase()) ||
-      e.name.toLowerCase().includes(keyword.toLowerCase()),
-    ),
-    stats: () => ({ entryCount: entries.length, scopes: [], kinds: {} }),
-    writeEntry: () => 'test-entry',
-    writeEntries: () => [],
-    deleteEntry: () => true,
-    rebuildScopes: () => {},
-    addToSection: () => {},
-    writeProfile: () => {},
-    clear: () => {},
-  };
-}
-
-const sampleMemoryEntries = [
-  {
-    name: 'typescript-strict-mode',
-    kind: 'preference',
-    scope: 'global',
-    tags: ['typescript', 'config', 'strict'],
-    importance: 'high',
-    frequency: 5,
-    content: 'User always uses TypeScript strict mode with noImplicitAny enabled.',
-    created_at: '2026-03-01T00:00:00Z',
-    updated_at: '2026-04-01T00:00:00Z',
-  },
-  {
-    name: 'prefers-vitest',
-    kind: 'preference',
-    scope: 'work/claude-web-chat',
-    tags: ['testing', 'vitest', 'framework'],
-    importance: 'normal',
-    frequency: 3,
-    content: 'User prefers vitest over jest for testing. Uses vitest for all new projects.',
-    created_at: '2026-03-15T00:00:00Z',
-    updated_at: '2026-04-01T00:00:00Z',
-  },
-  {
-    name: 'error-handling-pattern',
-    kind: 'lesson',
-    scope: 'global',
-    tags: ['error-handling', 'typescript', 'patterns'],
-    importance: 'high',
-    frequency: 4,
-    content: 'Always use Result<T, E> pattern instead of throwing exceptions. Wrap external API calls in try-catch and return Result.',
-    created_at: '2026-02-01T00:00:00Z',
-    updated_at: '2026-04-01T00:00:00Z',
-  },
-  {
-    name: 'project-structure',
-    kind: 'context',
-    scope: 'work/claude-web-chat',
-    tags: ['architecture', 'project', 'monorepo'],
-    importance: 'normal',
-    frequency: 2,
-    content: 'Project uses monorepo with agent/, server/, web/ directories. Agent code is in agent/unify/.',
-    created_at: '2026-01-01T00:00:00Z',
-    updated_at: '2026-03-01T00:00:00Z',
-  },
-  {
-    name: 'functional-programming',
-    kind: 'preference',
-    scope: 'global',
-    tags: ['functional', 'programming', 'style'],
-    importance: 'normal',
-    frequency: 6,
-    content: 'User prefers functional programming: pure functions, immutable data, map/filter/reduce over loops.',
-    created_at: '2026-01-15T00:00:00Z',
-    updated_at: '2026-04-05T00:00:00Z',
-  },
-  {
-    name: 'api-design-rest',
-    kind: 'skill',
-    scope: 'global',
-    tags: ['api', 'rest', 'design'],
-    importance: 'normal',
-    frequency: 1,
-    content: 'REST API conventions: use plural nouns, HTTP methods for CRUD, 2xx success, 4xx client error, 5xx server error.',
-    created_at: '2026-02-15T00:00:00Z',
-    updated_at: '2026-02-15T00:00:00Z',
-  },
-];
+import { noError, custom } from '../runner.js';
 
 // ─── Eval Cases ──────────────────────────────────────────────
 
@@ -139,12 +16,8 @@ export const memoryCases = [
   {
     id: 'memory-profile-injection',
     suite: 'memory',
-    description: 'System prompt should include user profile from memory',
+    description: 'System prompt should include memory section after preflow',
     prompt: 'Help me with a coding task',
-    setupEngine: (engine) => {
-      // We can't directly inject memoryStore here since Engine uses private fields
-      // Instead, this eval verifies via the adapter call log that system prompt contains memory
-    },
     criteria: [
       noError,
       custom('has-response', 'Model produces a response', 5, (result) => ({
@@ -154,29 +27,23 @@ export const memoryCases = [
     ],
   },
 
-  // ─── Keyword Extraction (unit-level eval) ─────────────
+  // ─── Recall Event ──────────────────────────────────────
 
   {
     id: 'memory-keyword-extraction',
     suite: 'memory',
-    description: 'Keyword extraction produces relevant keywords',
+    description: 'Recall event emitted when preflow has hits',
     prompt: 'How should I handle TypeScript errors in my Express API?',
     criteria: [
       noError,
-      // This is tested at unit level but verifiable here via recall event
-      custom('recall-event', 'Recall event emitted (if memory store provided)', 3, (result) => {
-        // Without a real memory store this won't emit recall, so we check gracefully
+      custom('recall-event', 'Recall event emitted (if FTS index seeded)', 3, (result) => {
         const recallEvent = result.events.find(e => e.type === 'recall');
         return {
-          pass: true, // Always passes — it's informational
+          pass: true,
           score: recallEvent ? 1 : 0.5,
-          reason: recallEvent ? `Recalled ${recallEvent.entryCount} entries` : 'No memory store configured',
+          reason: recallEvent ? `Recalled ${recallEvent.entryCount} segments` : 'No FTS hits',
         };
       }),
     ],
   },
 ];
-
-// ─── Exported for direct import in unit tests ────────────────
-
-export { createMockMemoryStore, sampleMemoryEntries };

package/unify/memory/ams.js

@@ -11,7 +11,7 @@
  * truth is `<scope>/memory.md` + `<scope>/summary.md`. AMS itself
  * doesn't write to disk — that's Dream's job.
  *
- * Privacy (DESIGN-v2 §2.2): `vp/<other>` scopes are ALWAYS filtered out
+ * Privacy: `vp/<other>` scopes are ALWAYS filtered out
  * for any worker that isn't `<other>`. The owning code passes its own
  * vpId at construction.
  */

package/unify/memory/segment-store.js

@@ -5,7 +5,7 @@
  * segment blocks) and the SQLite segment index. This layer handles
  * scope <-> file path mapping; the index layer is scope-agnostic.
  *
- * Path conventions (DESIGN-v2 §5):
+ * Path conventions:
  *   ~/.yeaft/memory/user/memory.md
  *   ~/.yeaft/memory/vp/<id>/memory.md
  *   ~/.yeaft/memory/group/<id>/memory.md

package/unify/memory/store-v2.js

@@ -1,5 +1,5 @@
 /**
- * memory/store-v2.js — DESIGN-v2.md Part I: per-scope memory.md + summary.md.
+ * memory/store-v2.js — per-scope memory.md + summary.md (Layer-A storage).
  *
  * One pair of files per scope. No shards, no entries/, no index.md, no
  * index.json. The five scope kinds — user, vp, group, feature, topic — share
@@ -29,18 +29,15 @@
  * ACL:
  *   - This module enforces ONE ACL: `vp/<other>` paths are blocked when
  *     `currentVpId` is given and differs from `<other>`. Every other scope
- *     boundary is ACL-free in v2 (DESIGN-v2 §3.2).
+ *     boundary is ACL-free.
  *
  * What this module deliberately does NOT do:
  *   - No frontmatter parsing. memory.md and summary.md are pure markdown;
  *     the dream-state metadata block lives at the file's tail and is read
  *     by `dream-v2/state.js`, not here.
  *   - No LLM calls, no extraction, no summarisation. Pure I/O.
- *   - No legacy R6 fallback. The old MemoryStore (memory/store.js) and
- *     ScopeTree (memory/scope-tree.js) remain in service until PR-E swaps
- *     callers; this module is additive.
  *
- * Reference: agent/unify/memory/DESIGN-v2.md §2, §5, §9.
+ * Reference: agent/unify/memory/DESIGN-H2-AMS.md.
  */
 
 import {
@@ -228,8 +225,8 @@ export async function writeMemory(scope, content, opts = {}) {
 }
 
 /**
- * Append to a scope's memory.md. Used by the rare "direct write" path
- * (DESIGN-v2 §7.1); main flow is dream-driven rewrites.
+ * Append to a scope's memory.md. Used by the rare "direct write" path;
+ * main flow is dream-driven rewrites.
  *
  * Append is non-atomic with concurrent readers in the strict sense, but a
  * single appendFile of a small buffer is atomic at the kernel level on POSIX
@@ -316,7 +313,7 @@ export async function ensureScope(scope, opts = {}) {
 
 /**
  * Enumerate all scopes present on disk. Returns Scope shapes that round-trip
- * back through `scopeDir`. Used by Triage (DESIGN-v2 §14) to list candidate
+ * back through `scopeDir`. Used by Triage to list candidate
  * scopes for a group's diff.
  *
  * Walks shallowly:

package/unify/prompts.js

@@ -8,39 +8,13 @@
  * and used to enrich the system prompt beyond the hardcoded fallbacks.
  *
  * Phase 2 additions:
- *   - Memory section (user profile + recalled entries)
+ *   - Memory section (recalled segments via H2-AMS pre-flow)
  *   - Compact summary section (conversation history summary)
  *
- * task-287 refactor (tool-on-demand memory):
- *   - New `memoryInjection` param carries prebuilt "Memory Index + user
- *     preferences + project header" text (~1.5k tokens). Engine builds this
- *     via memory/layout.buildMemoryInjection() and passes it every turn.
- *   - Legacy `memory={profile,entries}` param still supported for callers
- *     (tests, CLI) that have not migrated.
- *
- * task-334e additions (R6 §Δ24.5 / §Δ27.3 / §Δ31.4 / §Δ29.3):
- *   - `taskCtx` param → renders a `## task_ctx` block with:
- *       * task-memory top-5 bodies with semantic shard prefix `[shard]`
- *         (no sourceRef — memory_trace opens the trail on demand)
- *       * `### related tasks` sub-section — `relatedTaskIds` top-3 (sorted
- *         by updatedAt desc) + per-task top-2 memory; ACL-gated by
- *         `target.members` ∋ currentVpId (§Δ31.4)
- *       * `### summary reminder` soft nudge — condition (§Δ27.3):
- *           non-summary msgs ≥ 3 AND since-lastSummary > 15min AND
- *           currentVpId == task.initiatorVpId → emits a DYNAMIC hint
- *   - `userProfile` param → renders a `## user_profile` block. Stub
- *     implementation: when not passed explicitly, we fall back to reading
- *     `~/.yeaft/user/profile.json` ({ "content": "…string…" }) if present
- *     (§Δ29.3 placeholder until 334l wires real user-memory recall).
- *   - `coreMemory` param → renders a `## core_memory` block with recall
- *     top-7 memory bodies (no sourceRef) and a trailing meta line pointing
- *     at `memory_trace` as the way to open the original message.
- *
- * Hard constraints (task-334e contract):
- *   - Does NOT modify engine.js turn loop.
- *   - Does NOT implement memory_trace / open_source_message (task-334f).
- *   - Does NOT implement task_summary_post (task-334n).
- *   - Changes limited to prompts.js + templates/.
+ * Memory injection (H2-AMS):
+ *   - `memoryInjection` carries prebuilt FTS-recall text from
+ *     `memory/preflow.js` over the relevant scopes (user/group/vp/feature/
+ *     global). Engine passes it every turn after preflow runs.
  *
  * Reference: yeaft-unify-system-prompt-budget.md — Static + Dynamic + Context layers
  */

package/unify/session.js

@@ -282,7 +282,7 @@ export async function loadSession(options = {}) {
     yeaftDir,
   });
 
-  // ─── 9a. Create dream scheduler (DESIGN-v2) ────────────
+  // ─── 9a. Create dream scheduler ────────────
   // The legacy R6 dream-scheduler was retired alongside recall-r6;
   // dream-v2 is the only active path. The `memoryV2: false` opt-out
   // no longer leaves a usable system, so we always wire v2 here.

package/unify/tools/web-search.js

@@ -60,6 +60,14 @@ Guidelines:
     const signal = ctx?.signal;
     const errors = [];
 
+    // Backend preference set in UnifySettings → Search tab. When the
+    // user picks `playwright` we'd normally call the playwright-service;
+    // that service is not yet shipped (next PR), so the preference is
+    // recorded for forward-compat and we transparently fall through to
+    // Tavily / HTML scrape. Once the service lands we'll insert a
+    // tryPlaywright backend here ahead of Tavily.
+    // Anything other than 'playwright' is treated as 'tavily'.
+
     // 1. Tavily — default, fast, structured.
     if (search.tavilyApiKey) {
       const r = await tryTavily(query, limit, search.tavilyApiKey, signal);