@yeaft/webchat-agent 0.1.591 → 0.1.593

package/package.json

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

package/unify/llm/chat-completions.js

@@ -45,6 +45,31 @@ function thinkingV1Enabled() {
   return process.env.UNIFY_THINKING_V1 === '1';
 }
 
+/**
+ * task-DESIGN-v4: Chat Completions adapter is deprecated in favour of
+ * `openai-responses.js` (Responses API) for OpenAI-protocol providers and
+ * `anthropic.js` for Anthropic. This warning fires once per process the
+ * first time the adapter is instantiated, unless UNIFY_SUPPRESS_DEPRECATION=1.
+ * Removal is scheduled for Phase 7 of the multi-VP redesign — see
+ * `agent/unify/DESIGN.md` § "Migration Plan".
+ */
+let _chatCompletionsDeprecationWarned = false;
+function warnChatCompletionsDeprecated() {
+  if (_chatCompletionsDeprecationWarned) return;
+  if (process.env.UNIFY_SUPPRESS_DEPRECATION === '1') {
+    _chatCompletionsDeprecationWarned = true;
+    return;
+  }
+  _chatCompletionsDeprecationWarned = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[unify] ChatCompletionsAdapter is deprecated. Migrate OpenAI-protocol '
+    + 'providers to the Responses API (set provider.protocol="openai-responses"). '
+    + 'This adapter will be removed in a future release. Set '
+    + 'UNIFY_SUPPRESS_DEPRECATION=1 to silence this warning.'
+  );
+}
+
 /**
  * Check if a model ID is an OpenAI model that supports max_completion_tokens.
  * OpenAI introduced max_completion_tokens with o1 and made it standard for
@@ -79,6 +104,7 @@ export class ChatCompletionsAdapter extends LLMAdapter {
     super({ apiKey, baseUrl });
     this.#apiKey = apiKey;
     this.#baseUrl = baseUrl.replace(/\/+$/, ''); // strip trailing slash
+    warnChatCompletionsDeprecated();
   }
 
   /** Expose baseUrl for testing. */

package/unify/llm/openai-responses.js

@@ -33,9 +33,34 @@ import {
   LLMServerError,
   LLMAbortError,
 } from './adapter.js';
+import {
+  normalizeEffort,
+  getThinkingCapability,
+} from '../models.js';
 
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 
+/**
+ * Feature-flag accessor mirroring anthropic.js. UNIFY_THINKING_V1 is OFF by
+ * default; set env to '1' to enable thinking-mode field translation. Read
+ * lazily so tests can flip the flag between calls.
+ */
+function thinkingV1Enabled() {
+  return process.env.UNIFY_THINKING_V1 === '1';
+}
+
+/**
+ * Translate a normalised effort ('low'|'medium'|'high'|'max') into the value
+ * accepted by the OpenAI Responses `reasoning.effort` field. Responses today
+ * accepts 'low'|'medium'|'high' — 'max' degrades to 'high' to match the
+ * registry's normaliseEffort downgrade rule.
+ */
+function effortForResponses(effort) {
+  if (!effort) return null;
+  if (effort === 'max') return 'high';
+  return effort;
+}
+
 export class OpenAIResponsesAdapter extends LLMAdapter {
   #apiKey;
   #baseUrl;
@@ -200,9 +225,9 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
   // ─── Streaming ──────────────────────────────────────────
 
   /**
-   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, extraBody?: object, signal?: AbortSignal }} params
+   * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, effort?: 'low'|'medium'|'high'|'max', extraBody?: object, signal?: AbortSignal }} params
    */
-  async *stream({ model, system, messages, tools, maxTokens = 16384, extraBody, signal }) {
+  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, extraBody, signal }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -214,6 +239,20 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
     if (system) body.instructions = system;
     const translatedTools = this.#translateTools(tools);
     if (translatedTools) body.tools = translatedTools;
+
+    // Inject Responses-API thinking-mode field. Mirrors anthropic.js gating:
+    // feature flag must be on, effort must be a known value, and the model's
+    // registry entry must declare thinkingProtocol === 'openai-reasoning'.
+    // Unknown / unsupported models silently drop the field.
+    const normEffort = normalizeEffort(effort);
+    if (thinkingV1Enabled() && normEffort) {
+      const cap = getThinkingCapability(model);
+      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning') {
+        const wireEffort = effortForResponses(normEffort);
+        if (wireEffort) body.reasoning = { effort: wireEffort };
+      }
+    }
+
     if (extraBody) Object.assign(body, extraBody);
 
     let response;
@@ -375,7 +414,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
 
   // ─── Non-streaming call() ───────────────────────────────
 
-  async call({ model, system, messages, maxTokens = 4096, extraBody, signal }) {
+  async call({ model, system, messages, maxTokens = 4096, effort, extraBody, signal }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -384,6 +423,17 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
       max_output_tokens: maxTokens,
     };
     if (system) body.instructions = system;
+
+    // Mirror stream()'s thinking injection for non-streaming side queries.
+    const normEffort = normalizeEffort(effort);
+    if (thinkingV1Enabled() && normEffort) {
+      const cap = getThinkingCapability(model);
+      if (cap.supportsThinking && cap.thinkingProtocol === 'openai-reasoning') {
+        const wireEffort = effortForResponses(normEffort);
+        if (wireEffort) body.reasoning = { effort: wireEffort };
+      }
+    }
+
     if (extraBody) Object.assign(body, extraBody);
 
     let response;

package/unify/memory/scope-tree.js

@@ -0,0 +1,520 @@
+/**
+ * memory/scope-tree.js — DESIGN.md Phase 2 (scoped memory tree).
+ *
+ * Implements the path-keyed scope tree described in DESIGN.md §2:
+ *
+ *   ~/.yeaft/memory/
+ *     user/
+ *       summary.md          — paragraph synopsis (Layer A)
+ *       index.md            — markdown table, path-keyed
+ *       entries/<yyyy-mm-dd>-<slug>.md
+ *     groups/<groupId>/    — same shape
+ *     vp/<vpId>/           — same shape
+ *     tasks/<taskId>/      — same shape, plus archive/
+ *
+ * This module is concerned ONLY with on-disk shape + atomic writes. It does
+ * NOT do any LLM work (extraction, summarisation, dream maintenance) — those
+ * are higher layers (compact-orchestrator, dream).
+ *
+ * Atomicity contract:
+ *   - Every write goes via `.tmp` + rename to avoid torn reads. A reader
+ *     mid-rename sees either the old or the new file, never half of either.
+ *   - `createEntry()` opens with `O_EXCL` so concurrent producers cannot
+ *     clobber a slug collision; the second writer surfaces `slug_exists`.
+ *   - `index.md` is rewritten in full (markdown table). Partial-row append
+ *     would leave a torn header on crash; the whole file is small enough
+ *     that full rewrite + atomic rename is fine.
+ *
+ * Concurrency rules (DESIGN.md §9.1):
+ *   - Two workers writing different entries to the same scope are safe —
+ *     they write to different files, then each updates index.md via the
+ *     atomic rename. Last writer wins for the index; both entries are
+ *     present on disk regardless.
+ *   - `summary.md` written via the same atomic rename. Workers reading it
+ *     mid-write see either the previous or the next paragraph.
+ *
+ * Path discipline:
+ *   - All scope paths returned by helpers are filesystem-relative paths
+ *     ROOTED at the memory dir, e.g. `groups/eng/entries/2026-04-21-foo.md`.
+ *     This matches DESIGN.md §1.2.1 — paths self-document.
+ */
+
+import {
+  promises as fsp,
+  existsSync,
+  mkdirSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+/** Default memory root. Tests override via `opts.root`. */
+export const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
+
+/** @typedef {'user'|'group'|'vp'|'task'} ScopeKind */
+/** @typedef {{kind: ScopeKind, id?: string}} Scope */
+
+/**
+ * Compute the scope's path segment relative to the memory root.
+ * `user/`, `groups/<id>/`, `vp/<id>/`, `tasks/<id>/`.
+ *
+ * @param {Scope} scope
+ * @returns {string}
+ */
+export function scopeDir(scope) {
+  if (!scope || typeof scope !== 'object') {
+    throw new Error('scopeDir: scope is required');
+  }
+  switch (scope.kind) {
+    case 'user':
+      return 'user';
+    case 'group':
+      if (!scope.id) throw new Error('scopeDir: group scope requires id');
+      return `groups/${scope.id}`;
+    case 'vp':
+      if (!scope.id) throw new Error('scopeDir: vp scope requires id');
+      return `vp/${scope.id}`;
+    case 'task':
+      if (!scope.id) throw new Error('scopeDir: task scope requires id');
+      return `tasks/${scope.id}`;
+    default:
+      throw new Error(`scopeDir: unknown kind ${JSON.stringify(scope.kind)}`);
+  }
+}
+
+/**
+ * Atomic write: temp-file + rename. Creates parent directories on demand.
+ * The rename is atomic on POSIX filesystems for paths on the same mount.
+ *
+ * @param {string} absPath
+ * @param {string} content
+ */
+async function atomicWrite(absPath, content) {
+  await fsp.mkdir(dirname(absPath), { recursive: true });
+  const tmp = `${absPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+  await fsp.writeFile(tmp, content, 'utf8');
+  await fsp.rename(tmp, absPath);
+}
+
+/**
+ * Slugify a free-form title for use in a filename. Lowercase, ASCII letters
+ * + digits + dash. Empty / pathological input returns `entry`.
+ *
+ * @param {string} title
+ * @returns {string}
+ */
+export function slugify(title) {
+  const raw = (title || '')
+    .toString()
+    .toLowerCase()
+    .normalize('NFKD')
+    // eslint-disable-next-line no-misleading-character-class
+    .replace(/[̀-ͯ]/g, '') // strip combining marks
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+  return raw || 'entry';
+}
+
+/**
+ * Format a Date as `yyyy-mm-dd` in UTC. Used in entry filenames.
+ *
+ * @param {Date} [d=new Date()]
+ * @returns {string}
+ */
+export function isoDate(d = new Date()) {
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * Compute the canonical entry path for a (scope, title, date) triple.
+ *
+ * @param {Scope} scope
+ * @param {string} title
+ * @param {Date} [date]
+ * @returns {string} relative to memory root
+ */
+export function entryPathFor(scope, title, date) {
+  return `${scopeDir(scope)}/entries/${isoDate(date)}-${slugify(title)}.md`;
+}
+
+// ─── frontmatter ───────────────────────────────────────────────
+
+/**
+ * Render YAML-ish frontmatter. Keys in deterministic order; string values
+ * are JSON-stringified to handle quotes / newlines safely; arrays render as
+ * `key: [a, b]`. Unknown values are skipped.
+ *
+ * @param {Record<string,*>} fm
+ * @returns {string}
+ */
+function renderFrontmatter(fm) {
+  if (!fm || typeof fm !== 'object') return '';
+  const order = ['title', 'kind', 'tags', 'source', 'createdAt', 'updatedAt'];
+  const seen = new Set();
+  const lines = ['---'];
+  for (const key of order) {
+    if (!(key in fm)) continue;
+    seen.add(key);
+    lines.push(renderFmLine(key, fm[key]));
+  }
+  for (const key of Object.keys(fm)) {
+    if (seen.has(key)) continue;
+    lines.push(renderFmLine(key, fm[key]));
+  }
+  lines.push('---');
+  return lines.filter(Boolean).join('\n');
+}
+
+function renderFmLine(key, value) {
+  if (value === null || value === undefined) return '';
+  if (Array.isArray(value)) {
+    const items = value.map(v => (typeof v === 'string' ? v : JSON.stringify(v)));
+    return `${key}: [${items.join(', ')}]`;
+  }
+  if (typeof value === 'string') {
+    // Quote when it contains anything non-trivial.
+    if (/^[\w\-./:]+$/.test(value)) return `${key}: ${value}`;
+    return `${key}: ${JSON.stringify(value)}`;
+  }
+  return `${key}: ${JSON.stringify(value)}`;
+}
+
+/**
+ * Parse the frontmatter block from a markdown body. Returns `{frontmatter,
+ * body}`; missing frontmatter ⇒ `frontmatter = {}` and `body` is the input.
+ * Best-effort parser — accepts the lines this module emits and a few common
+ * variants. Does NOT pull in a YAML dep.
+ *
+ * @param {string} content
+ * @returns {{ frontmatter: Record<string,*>, body: string }}
+ */
+export function parseEntry(content) {
+  if (typeof content !== 'string' || !content.startsWith('---')) {
+    return { frontmatter: {}, body: content || '' };
+  }
+  const end = content.indexOf('\n---', 4);
+  if (end === -1) return { frontmatter: {}, body: content };
+  const fmText = content.slice(4, end).trim();
+  const body = content.slice(end + 4).replace(/^\n+/, '');
+  const fm = {};
+  for (const rawLine of fmText.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const m = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (!m) continue;
+    const [, key, rest] = m;
+    fm[key] = parseFmValue(rest);
+  }
+  return { frontmatter: fm, body };
+}
+
+function parseFmValue(rest) {
+  if (rest === '') return '';
+  if (rest.startsWith('[') && rest.endsWith(']')) {
+    const inner = rest.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(',').map(s => {
+      const t = s.trim();
+      if (t.startsWith('"') && t.endsWith('"')) {
+        try { return JSON.parse(t); } catch { return t; }
+      }
+      return t;
+    });
+  }
+  if (rest.startsWith('"') && rest.endsWith('"')) {
+    try { return JSON.parse(rest); } catch { return rest.slice(1, -1); }
+  }
+  return rest;
+}
+
+// ─── entries ───────────────────────────────────────────────────
+
+/**
+ * Create a new entry under (scope, title). Fails with `slug_exists` if the
+ * computed path already exists. Returns the relative path written.
+ *
+ * @param {{
+ *   scope: Scope,
+ *   title: string,
+ *   body: string,
+ *   tags?: string[],
+ *   kind?: string,
+ *   source?: string,
+ *   date?: Date,
+ *   root?: string,
+ * }} args
+ * @returns {Promise<{ path: string, abs: string }>}
+ */
+export async function createEntry(args) {
+  const { scope, title, body, tags, kind, source, date, root = DEFAULT_MEMORY_ROOT } = args;
+  if (!title || typeof title !== 'string') throw new Error('createEntry: title required');
+  if (typeof body !== 'string') throw new Error('createEntry: body required (string)');
+  const rel = entryPathFor(scope, title, date);
+  const abs = join(root, rel);
+  await fsp.mkdir(dirname(abs), { recursive: true });
+  const fm = renderFrontmatter({
+    title,
+    kind: kind || 'note',
+    tags: Array.isArray(tags) && tags.length ? tags : undefined,
+    source: source || undefined,
+    createdAt: isoDate(date),
+    updatedAt: isoDate(date),
+  });
+  const content = `${fm}\n\n${body.trim()}\n`;
+  // O_EXCL — fail loudly on slug collision (DESIGN.md §9.1 atomicity).
+  let handle;
+  try {
+    handle = await fsp.open(abs, 'wx');
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      const e = new Error('slug_exists');
+      e.code = 'slug_exists';
+      e.path = rel;
+      throw e;
+    }
+    throw err;
+  }
+  try {
+    await handle.writeFile(content, 'utf8');
+  } finally {
+    await handle.close();
+  }
+  return { path: rel, abs };
+}
+
+/**
+ * Read an entry by its relative path; returns `null` if missing. Throws
+ * `acl_blocked` when the caller's `currentVpId` is given and the path is
+ * `vp/<other>/...` — the only hard ACL boundary.
+ *
+ * @param {string} relPath
+ * @param {{ root?: string, currentVpId?: string }} [opts]
+ * @returns {Promise<{ frontmatter: Record<string,*>, body: string, path: string } | null>}
+ */
+export async function readEntry(relPath, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT, currentVpId } = opts;
+  if (!relPath || typeof relPath !== 'string') throw new Error('readEntry: relPath required');
+  if (currentVpId && isVpForeign(relPath, currentVpId)) {
+    const e = new Error('acl_blocked');
+    e.code = 'acl_blocked';
+    e.path = relPath;
+    throw e;
+  }
+  const abs = join(root, relPath);
+  let raw;
+  try {
+    raw = await fsp.readFile(abs, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const { frontmatter, body } = parseEntry(raw);
+  return { frontmatter, body: body.replace(/\n+$/, ''), path: relPath };
+}
+
+/**
+ * @returns {boolean} true iff `relPath` is `vp/<other>/...` (other ≠ currentVpId).
+ */
+export function isVpForeign(relPath, currentVpId) {
+  if (!relPath || !currentVpId) return false;
+  const m = /^vp\/([^/]+)\//.exec(relPath);
+  if (!m) return false;
+  return m[1] !== currentVpId;
+}
+
+// ─── index.md ──────────────────────────────────────────────────
+
+/**
+ * Index row schema. `path` is the canonical, scope-rooted relative path.
+ * `updated` is YYYY-MM-DD UTC. `tags` is a comma-joined string for the
+ * markdown column; arrays are accepted as input and normalised.
+ *
+ * @typedef {{
+ *   path: string,
+ *   title: string,
+ *   tags?: string | string[],
+ *   kind?: string,
+ *   updated?: string,
+ * }} IndexRow
+ */
+
+/**
+ * Render the markdown table for `index.md` in a scope. Reverse-chronological
+ * — newest `updated` first — matching DESIGN.md §9.3 ("append on top").
+ *
+ * @param {Scope} scope
+ * @param {IndexRow[]} rows
+ * @returns {string}
+ */
+export function renderIndex(scope, rows) {
+  const dir = scopeDir(scope);
+  const sorted = [...(rows || [])].sort((a, b) => {
+    const ax = (b.updated || '').localeCompare(a.updated || '');
+    return ax !== 0 ? ax : (a.path || '').localeCompare(b.path || '');
+  });
+  const lines = [
+    `# index — ${dir}`,
+    '',
+    '| path | title | tags | kind | updated |',
+    '| ---- | ----- | ---- | ---- | ------- |',
+  ];
+  for (const r of sorted) {
+    const path = (r.path || '').replace(/\|/g, '\\|');
+    const title = (r.title || '').replace(/\|/g, '\\|');
+    const tags = Array.isArray(r.tags) ? r.tags.join(',') : (r.tags || '');
+    const kind = r.kind || '';
+    const updated = r.updated || '';
+    lines.push(`| ${path} | ${title} | ${tags} | ${kind} | ${updated} |`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Parse `index.md` markdown table back into an array of rows. Tolerates
+ * extra whitespace, missing optional columns, and the index header line.
+ * Unknown / malformed lines are skipped silently.
+ *
+ * @param {string} content
+ * @returns {IndexRow[]}
+ */
+export function parseIndex(content) {
+  if (typeof content !== 'string' || !content) return [];
+  const out = [];
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line.startsWith('|')) continue;
+    if (/^\|\s*-+/.test(line)) continue; // separator row
+    const cols = line.split('|').slice(1, -1).map(s => s.trim());
+    if (cols.length < 2) continue;
+    const [path, title, tags = '', kind = '', updated = ''] = cols;
+    if (!path || path === 'path') continue; // header row
+    out.push({
+      path,
+      title,
+      tags: tags ? tags.split(',').map(s => s.trim()).filter(Boolean) : [],
+      kind: kind || undefined,
+      updated: updated || undefined,
+    });
+  }
+  return out;
+}
+
+/**
+ * Read `index.md` for a scope and return the parsed rows. Missing index
+ * returns `[]` (cold-start scope).
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string }} [opts]
+ * @returns {Promise<IndexRow[]>}
+ */
+export async function readIndex(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'index.md');
+  let raw;
+  try { raw = await fsp.readFile(abs, 'utf8'); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return parseIndex(raw);
+}
+
+/**
+ * Atomically rewrite `index.md` for a scope.
+ *
+ * @param {Scope} scope
+ * @param {IndexRow[]} rows
+ * @param {{ root?: string }} [opts]
+ */
+export async function writeIndex(scope, rows, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'index.md');
+  await atomicWrite(abs, renderIndex(scope, rows));
+}
+
+/**
+ * Upsert a single row keyed by `path`. Existing row with the same path is
+ * replaced; otherwise the row is prepended (kept in reverse-chronological
+ * order via `renderIndex`'s sort). Returns the updated row list.
+ *
+ * @param {Scope} scope
+ * @param {IndexRow} row
+ * @param {{ root?: string }} [opts]
+ * @returns {Promise<IndexRow[]>}
+ */
+export async function upsertIndexRow(scope, row, opts = {}) {
+  if (!row || !row.path) throw new Error('upsertIndexRow: row.path required');
+  const rows = await readIndex(scope, opts);
+  const filtered = rows.filter(r => r.path !== row.path);
+  filtered.unshift(row);
+  await writeIndex(scope, filtered, opts);
+  return filtered;
+}
+
+/**
+ * Cap the rows surfaced to the router (DESIGN.md §9.3). Reverse-chrono;
+ * default K = 200. Caller passes the merged set; we trim and return.
+ *
+ * @param {IndexRow[]} rows
+ * @param {number} [k=200]
+ * @returns {IndexRow[]}
+ */
+export function capIndexRows(rows, k = 200) {
+  if (!Array.isArray(rows)) return [];
+  if (rows.length <= k) return rows.slice();
+  return rows.slice(0, k);
+}
+
+// ─── summary.md ────────────────────────────────────────────────
+
+/**
+ * Read the scope's `summary.md`. Empty / missing → ''.
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function readSummary(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'summary.md');
+  try { return (await fsp.readFile(abs, 'utf8')).trim(); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') return '';
+    throw err;
+  }
+}
+
+/**
+ * Atomically rewrite the scope's `summary.md`. The body is trimmed; empty
+ * input writes an empty file (callers that wanted "delete summary" can use
+ * `fs.unlink` directly — we don't surface that here).
+ *
+ * @param {Scope} scope
+ * @param {string} body
+ * @param {{ root?: string }} [opts]
+ */
+export async function writeSummary(scope, body, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const abs = join(root, scopeDir(scope), 'summary.md');
+  await atomicWrite(abs, `${(body || '').trim()}\n`);
+}
+
+// ─── ensure scope on disk ──────────────────────────────────────
+
+/**
+ * Best-effort: ensure the scope's directory and an empty `entries/` exist.
+ * Idempotent. Use at boot or on first write to avoid ENOENT cascades.
+ *
+ * @param {Scope} scope
+ * @param {{ root?: string }} [opts]
+ */
+export function ensureScopeSync(scope, opts = {}) {
+  const { root = DEFAULT_MEMORY_ROOT } = opts;
+  const dir = join(root, scopeDir(scope));
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const entries = join(dir, 'entries');
+  if (!existsSync(entries)) mkdirSync(entries, { recursive: true });
+}

package/unify/prompts.js

@@ -158,6 +158,11 @@ const RAW_TEMPLATES = {
   modeUnified: readTemplate('mode-unified.md'),
   modeDream: readTemplate('mode-dream.md'),
   toolGuidance: readTemplate('tool-guidance.md'),
+  // Phase 1 — DESIGN.md "Migration Plan" harness fragments. Optional so
+  // older deployments without the templates still boot; buildWorkerPrompt /
+  // buildRouterPrompt callers will simply omit the section.
+  harnessWorkerShape: readTemplate('harness/worker-shape.md', { required: false }),
+  harnessRouterShape: readTemplate('harness/router-shape.md', { required: false }),
 };
 
 /**
@@ -637,3 +642,164 @@ function renderCoreMemory(coreMemory, lang, memoryTraceAvailable) {
   }
   return lines.join('\n');
 }
+
+// ─── Phase 1: Worker / Router prompt splits ──────────────────────
+//
+// DESIGN.md (multi-VP redesign) describes two distinct prompt shapes:
+//
+//   • Worker prompt — what a VP sees when it executes a turn. Layered as
+//     A (identity + summaries) / B (router-preselected memory) / C (task
+//     scope) / D (turn scope).
+//   • Router prompt — what the per-VP Router sees before it decides
+//     plans[]. Identity-summary layer + recent group state, no task /
+//     turn-scope detail.
+//
+// To stay backwards-compatible with existing callers we KEEP
+// `buildSystemPrompt` and treat the two new entry points as thin wrappers
+// that:
+//   1) compose Layer-A summaries (user / group / vp) into the right
+//      headed sections, and
+//   2) prepend the matching harness/*-shape.md fragment when present.
+//
+// Subsequent phases will migrate engine.js / router.js to these entry
+// points and start filling Layers B / C with the new memory tree. For
+// now they exist primarily so tests can pin the contract.
+
+const LAYER_A_HEADERS = {
+  en: {
+    user: '## summary_user',
+    group: '## summary_group',
+    vp: '## summary_vp',
+  },
+  zh: {
+    user: '## 用户总结',
+    group: '## 群组总结',
+    vp: '## VP 总结',
+  },
+};
+
+/**
+ * Render Layer A's three rolling summaries (user / group / vp). Each is
+ * optional; missing or empty strings are skipped. Headers follow the
+ * `## summary_<scope>` convention so Layer-B/C/D headers don't collide.
+ *
+ * @param {{user?: string, group?: string, vp?: string}} summaries
+ * @param {'en'|'zh'} language
+ * @returns {string} concatenated block ('' when nothing to render)
+ */
+export function renderLayerASummaries(summaries, language = 'en') {
+  if (!summaries || typeof summaries !== 'object') return '';
+  const headers = LAYER_A_HEADERS[language] || LAYER_A_HEADERS.en;
+  const out = [];
+  for (const key of ['user', 'group', 'vp']) {
+    const body = typeof summaries[key] === 'string' ? summaries[key].trim() : '';
+    if (!body) continue;
+    out.push(`${headers[key]}\n${body}`);
+  }
+  return out.join('\n\n');
+}
+
+/**
+ * Worker prompt entry point (DESIGN.md Phase 1).
+ *
+ * Layered output:
+ *   harness/worker-shape   — what each layer means (optional fragment)
+ *   Layer A — buildSystemPrompt(...) output (identity + persona + Layer-A
+ *             summaries via `summaries`)
+ *   Layer B — `preselectedMemory` block (router-supplied)
+ *   Layer C — `taskScope` block (active task summary + related-task window)
+ *   Layer D — `turnScope` block (inbound envelope, in-flight turn notes)
+ *
+ * Layers B/C/D are passed in as already-rendered strings so this builder
+ * stays free of memory-store / task-store IO. Phase 2/3 will provide the
+ * real renderers; for now any caller can stub them.
+ *
+ * @param {{
+ *   language?: 'en'|'zh',
+ *   summaries?: {user?: string, group?: string, vp?: string},
+ *   preselectedMemory?: string,
+ *   taskScope?: string,
+ *   turnScope?: string,
+ *   includeShape?: boolean,
+ *   ...rest: import('./prompts.js').buildSystemPrompt
+ * }} params
+ * @returns {string}
+ */
+export function buildWorkerPrompt(params = {}) {
+  const {
+    language = 'en',
+    summaries,
+    preselectedMemory,
+    taskScope,
+    turnScope,
+    includeShape = true,
+    ...rest
+  } = params;
+
+  const parts = [];
+
+  // Optional harness — describes the layered shape.
+  if (includeShape) {
+    const shape = getTemplate('harnessWorkerShape', language);
+    if (shape) parts.push(shape);
+  }
+
+  // Layer A — base + persona + summaries.
+  const baseBlock = buildSystemPrompt({ ...rest, language });
+  if (baseBlock) parts.push(baseBlock);
+  const summaryBlock = renderLayerASummaries(summaries, language);
+  if (summaryBlock) parts.push(summaryBlock);
+
+  // Layer B — router-preselected memory entries (rendered upstream).
+  if (typeof preselectedMemory === 'string' && preselectedMemory.trim()) {
+    parts.push(preselectedMemory.trim());
+  }
+
+  // Layer C — task scope.
+  if (typeof taskScope === 'string' && taskScope.trim()) {
+    parts.push(taskScope.trim());
+  }
+
+  // Layer D — turn scope (inbound envelope, in-flight turn notes).
+  if (typeof turnScope === 'string' && turnScope.trim()) {
+    parts.push(turnScope.trim());
+  }
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Router prompt entry point (DESIGN.md Phase 1).
+ *
+ * The Router sees identity context (no persona — it speaks as a routing
+ * brain, not as any specific VP), the three Layer-A summaries, and a
+ * `routerContext` block prepared upstream (group roster, recent turns,
+ * pending tasks). Output schema is enforced by the harness fragment.
+ *
+ * @param {{
+ *   language?: 'en'|'zh',
+ *   summaries?: {user?: string, group?: string, vp?: string},
+ *   routerContext?: string,
+ *   includeShape?: boolean,
+ * }} params
+ * @returns {string}
+ */
+export function buildRouterPrompt(params = {}) {
+  const { language = 'en', summaries, routerContext, includeShape = true } = params;
+  const parts = [];
+
+  if (includeShape) {
+    const shape = getTemplate('harnessRouterShape', language);
+    if (shape) parts.push(shape);
+  }
+
+  const summaryBlock = renderLayerASummaries(summaries, language);
+  if (summaryBlock) parts.push(summaryBlock);
+
+  if (typeof routerContext === 'string' && routerContext.trim()) {
+    parts.push(routerContext.trim());
+  }
+
+  return parts.join('\n\n');
+}
+

package/unify/router/vp-planner.js

@@ -0,0 +1,282 @@
+/**
+ * router/vp-planner.js — DESIGN.md Phase 3a (router per-VP plans).
+ *
+ * The legacy `intent-classifier.js` decides "which thread continues this
+ * turn" — single-VP, single-plan. The multi-VP redesign (DESIGN.md §1.2.1)
+ * generalises that into a `plans[]` array: one plan per VP that should act
+ * this turn, in execution order. This module is the per-VP planner.
+ *
+ * Phase 3a scope: schema + validation + sequential fan-out runner. The LLM
+ * call itself is wired in Phase 3b along with `priorPlan` continuity. Until
+ * then, callers either (a) construct plans directly from override paths, or
+ * (b) wrap the legacy single-plan classifier and call `wrapLegacyDecision`.
+ *
+ * Non-goals here:
+ *   - parallel fan-out (Phase 3.5).
+ *   - thinking-mode resolution (handled at the dispatcher level alongside
+ *     the UI > Router > VP > Global precedence chain — DESIGN.md §9.16).
+ *   - `priorPlan` skip-router heuristic (Phase 3b).
+ *
+ * Shape contract (DESIGN.md §1.2.1):
+ *
+ *   {
+ *     action: 'continue' | 'switch_vp' | 'fork_task' | 'join_task' |
+ *             'broadcast' | 'noop',
+ *     targetTaskId: string | null,
+ *     plans: [
+ *       {
+ *         vpId: string,
+ *         forwardQuery: { userOriginal: string, intent: string },
+ *         preselect: { memoryPaths: string[], taskIds: string[] },
+ *         thinking: 'high' | 'max' | null,
+ *         thinkingReason: string,
+ *       }
+ *     ],
+ *     reason: string,
+ *   }
+ */
+
+import { isVpForeign } from '../memory/scope-tree.js';
+
+/** @typedef {{ userOriginal: string, intent: string }} ForwardQuery */
+/** @typedef {{ memoryPaths: string[], taskIds: string[] }} Preselect */
+/** @typedef {{
+ *    vpId: string,
+ *    forwardQuery: ForwardQuery,
+ *    preselect: Preselect,
+ *    thinking: 'high'|'max'|null,
+ *    thinkingReason: string,
+ *  }} VpPlan
+ */
+/** @typedef {{
+ *    action: 'continue'|'switch_vp'|'fork_task'|'join_task'|'broadcast'|'noop',
+ *    targetTaskId: string | null,
+ *    plans: VpPlan[],
+ *    reason: string,
+ *  }} RouterDecisionV2
+ */
+
+const ALLOWED_ACTIONS = new Set([
+  'continue', 'switch_vp', 'fork_task', 'join_task', 'broadcast', 'noop',
+]);
+
+const ALLOWED_THINKING = new Set([null, 'high', 'max']);
+
+/**
+ * Validate + canonicalise a router decision. Throws on truly malformed
+ * input (we want loud failures during Phase 3 wiring), but tolerates
+ * missing optional fields by filling defaults.
+ *
+ * @param {*} raw
+ * @returns {RouterDecisionV2}
+ */
+export function validateDecision(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('validateDecision: decision must be an object');
+  }
+  const action = ALLOWED_ACTIONS.has(raw.action) ? raw.action : 'continue';
+  const targetTaskId = (typeof raw.targetTaskId === 'string' && raw.targetTaskId)
+    ? raw.targetTaskId : null;
+  if (!Array.isArray(raw.plans)) {
+    throw new Error('validateDecision: plans must be an array');
+  }
+  const plans = raw.plans.map(validatePlan);
+  const reason = typeof raw.reason === 'string' ? raw.reason : '';
+  return { action, targetTaskId, plans, reason };
+}
+
+/**
+ * @param {*} raw
+ * @returns {VpPlan}
+ */
+export function validatePlan(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('validatePlan: plan must be an object');
+  }
+  if (typeof raw.vpId !== 'string' || !raw.vpId) {
+    throw new Error('validatePlan: vpId required');
+  }
+  const fq = raw.forwardQuery && typeof raw.forwardQuery === 'object'
+    ? raw.forwardQuery : {};
+  const userOriginal = typeof fq.userOriginal === 'string' ? fq.userOriginal : '';
+  const intent = typeof fq.intent === 'string' ? fq.intent : '';
+  const pre = raw.preselect && typeof raw.preselect === 'object'
+    ? raw.preselect : {};
+  const memoryPaths = Array.isArray(pre.memoryPaths)
+    ? pre.memoryPaths.filter(p => typeof p === 'string' && p)
+    : [];
+  const taskIds = Array.isArray(pre.taskIds)
+    ? pre.taskIds.filter(t => typeof t === 'string' && t)
+    : [];
+  const thinkingRaw = raw.thinking === undefined ? null : raw.thinking;
+  const thinking = ALLOWED_THINKING.has(thinkingRaw) ? thinkingRaw : null;
+  const thinkingReason = typeof raw.thinkingReason === 'string'
+    ? raw.thinkingReason : '';
+  return {
+    vpId: raw.vpId,
+    forwardQuery: { userOriginal, intent },
+    preselect: { memoryPaths, taskIds },
+    thinking,
+    thinkingReason,
+  };
+}
+
+/**
+ * Strip `vp/<other>/` paths from a plan's `preselect.memoryPaths`. The
+ * planner runs BEFORE the worker so this is the right place to enforce
+ * the cross-VP private-memory hard block (DESIGN.md §2.2). Returns a new
+ * plan; original is not mutated.
+ *
+ * @param {VpPlan} plan
+ * @returns {VpPlan}
+ */
+export function stripForeignVpPaths(plan) {
+  if (!plan) return plan;
+  const own = plan.vpId;
+  const filtered = plan.preselect.memoryPaths.filter(p => !isVpForeign(p, own));
+  if (filtered.length === plan.preselect.memoryPaths.length) return plan;
+  return {
+    ...plan,
+    preselect: { ...plan.preselect, memoryPaths: filtered },
+  };
+}
+
+/**
+ * Produce a default single-plan decision for "explicit @vp" or "no router
+ * needed" paths. The dispatcher uses this when it has decided not to call
+ * the LLM router (DESIGN.md §1.2.1 scenario A — explicit @vp; or §9.15
+ * priorPlan skip).
+ *
+ * @param {{
+ *   vpId: string,
+ *   userOriginal: string,
+ *   intent?: string,
+ *   memoryPaths?: string[],
+ *   taskIds?: string[],
+ *   targetTaskId?: string | null,
+ *   thinking?: 'high'|'max'|null,
+ *   thinkingReason?: string,
+ *   action?: RouterDecisionV2['action'],
+ *   reason?: string,
+ * }} args
+ * @returns {RouterDecisionV2}
+ */
+export function buildDirectDecision(args) {
+  const {
+    vpId, userOriginal, intent = '',
+    memoryPaths = [], taskIds = [],
+    targetTaskId = null,
+    thinking = null, thinkingReason = '',
+    action = 'continue', reason = 'direct',
+  } = args || {};
+  if (!vpId) throw new Error('buildDirectDecision: vpId required');
+  return validateDecision({
+    action,
+    targetTaskId,
+    plans: [{
+      vpId,
+      forwardQuery: { userOriginal, intent },
+      preselect: { memoryPaths, taskIds },
+      thinking,
+      thinkingReason,
+    }],
+    reason,
+  });
+}
+
+/**
+ * Translate a legacy `intent-classifier` single-thread decision (action +
+ * targetThreadId) into the V2 plans schema. We treat the old `targetThreadId`
+ * as the `vpId` because — in the multi-VP redesign — every "thread" is a VP
+ * (groups are sessions, see DESIGN.md §0.1). Callers that still produce
+ * legacy decisions can pipe them through this until Phase 3b.
+ *
+ * Mapping:
+ *   continue / switch → continue / switch_vp (single-VP plan)
+ *   fork              → fork_task   (single-VP plan)
+ *   anything else     → continue
+ *
+ * @param {{
+ *   action?: string,
+ *   targetThreadId?: string,
+ *   reason?: string,
+ *   source?: string,
+ * }} legacy
+ * @param {string} userOriginal
+ * @returns {RouterDecisionV2}
+ */
+export function wrapLegacyDecision(legacy, userOriginal = '') {
+  if (!legacy || typeof legacy !== 'object') {
+    return validateDecision({ action: 'noop', targetTaskId: null, plans: [], reason: '' });
+  }
+  const vpId = typeof legacy.targetThreadId === 'string' ? legacy.targetThreadId : '';
+  if (!vpId) {
+    return validateDecision({ action: 'noop', targetTaskId: null, plans: [], reason: legacy.reason || '' });
+  }
+  let action = 'continue';
+  if (legacy.action === 'switch') action = 'switch_vp';
+  else if (legacy.action === 'fork') action = 'fork_task';
+  else if (legacy.action === 'continue') action = 'continue';
+  return validateDecision({
+    action,
+    targetTaskId: null,
+    reason: legacy.reason || '',
+    plans: [{
+      vpId,
+      forwardQuery: { userOriginal, intent: '' },
+      preselect: { memoryPaths: [], taskIds: [] },
+      thinking: null,
+      thinkingReason: '',
+    }],
+  });
+}
+
+/**
+ * Sequential fan-out runner. Calls `runOne(plan, index, prior)` for each
+ * plan in order, awaiting each before starting the next. The previous
+ * plans' results are passed via `prior` so a later plan can read what an
+ * earlier plan emitted (DESIGN.md §1.2.1 — "ordering is load bearing").
+ *
+ * Plans whose `vpId` is missing from `groupMemberIds` (when the caller
+ * supplies that whitelist) are skipped with a logged `skipped:not_member`
+ * entry — never silently routed to a non-member.
+ *
+ * Errors from `runOne` are caught, recorded, and the loop continues; the
+ * report holds whatever each plan produced. The dispatcher decides whether
+ * to surface or retry.
+ *
+ * @param {VpPlan[]} plans
+ * @param {(plan: VpPlan, index: number, prior: any[]) => Promise<*>} runOne
+ * @param {{ groupMemberIds?: string[] }} [opts]
+ * @returns {Promise<{ results: any[], errors: Array<{ index: number, error: Error }> }>}
+ */
+export async function runPlansSequential(plans, runOne, opts = {}) {
+  if (!Array.isArray(plans)) throw new Error('runPlansSequential: plans array required');
+  if (typeof runOne !== 'function') throw new Error('runPlansSequential: runOne fn required');
+  const memberSet = Array.isArray(opts.groupMemberIds)
+    ? new Set(opts.groupMemberIds) : null;
+  const results = [];
+  const errors = [];
+  const prior = [];
+  for (let i = 0; i < plans.length; i += 1) {
+    const plan = plans[i];
+    if (memberSet && !memberSet.has(plan.vpId)) {
+      const skip = { index: i, vpId: plan.vpId, skipped: 'not_member' };
+      results.push(skip);
+      prior.push(skip);
+      continue;
+    }
+    try {
+      const out = await runOne(plan, i, prior);
+      results.push(out);
+      prior.push(out);
+    } catch (err) {
+      errors.push({ index: i, error: err });
+      // Insert a sentinel into prior so a later plan can see "the previous
+      // VP errored" rather than nothing — useful when a fallback VP is
+      // queued behind a primary.
+      prior.push({ index: i, vpId: plan.vpId, error: err });
+    }
+  }
+  return { results, errors };
+}

package/unify/templates/harness/router-shape.md

@@ -0,0 +1,49 @@
+<!-- lang:en -->
+# Prompt Shape (Router)
+
+You are the per-VP Router. You see the group's roster, summaries, recent
+turns, and the latest user message. You return a JSON `plans[]` array — one
+plan per VP that should act this turn, in execution order.
+
+Each plan contains:
+
+- `vpId` — which VP runs.
+- `forwardQuery` — `{ userOriginal, intent }`. `userOriginal` is the
+  verbatim user text; `intent` is a one-line gloss in third person. Do not
+  rewrite the user's words; the worker will read both.
+- `preselect` — `{ memoryPaths[], taskIds[] }`. Memory paths are
+  scope-prefixed (`user/`, `groups/<id>/`, `vp/<id>/`, `tasks/<id>/`).
+- `thinking` — `null | "high" | "max"`. Set when the turn warrants
+  deeper reasoning; leave `null` to use the VP / global default.
+- `thinkingReason` — short justification when `thinking` is non-null.
+
+Hard rules:
+- Never include `vp/<other>/` paths in `preselect.memoryPaths`. Cross-VP
+  private memory is hard-blocked.
+- Plans run sequentially in the order returned. Treat ordering as load
+  bearing; the second plan can read the first plan's output.
+- If no VP needs to act, return `{"plans": []}`.
+<!-- lang:zh -->
+# Prompt 结构（Router）
+
+你是当前群组的 Router。你能看到群成员、总结、最近的回合，以及最新的用户
+消息。你返回一个 JSON `plans[]` 数组——每个需要发言的 VP 一个 plan，按
+执行顺序排列。
+
+每个 plan 包含：
+
+- `vpId`：要执行的 VP。
+- `forwardQuery`：`{ userOriginal, intent }`。`userOriginal` 是用户的
+  原话；`intent` 是用第三人称写的一行意图说明。不要改写用户原话，Worker
+  会同时看到两者。
+- `preselect`：`{ memoryPaths[], taskIds[] }`。memoryPaths 必须带 scope
+  前缀（`user/`、`groups/<id>/`、`vp/<id>/`、`tasks/<id>/`）。
+- `thinking`：`null | "high" | "max"`。需要深度推理时设置，否则保持 null
+  使用 VP / 全局默认。
+- `thinkingReason`：当 `thinking` 非空时的简短理由。
+
+硬规则：
+- `preselect.memoryPaths` 不允许包含 `vp/<其他 VP>/`。跨 VP 私有记忆硬
+  屏蔽。
+- plans 按返回顺序串行执行；后一个 plan 可以读到前一个 plan 的输出。
+- 如果本轮无需任何 VP 发言，返回 `{"plans": []}`。

package/unify/templates/harness/worker-shape.md

@@ -0,0 +1,35 @@
+<!-- lang:en -->
+# Prompt Shape (Worker)
+
+You are a Worker VP turn. Your prompt is built from four layers, in order:
+
+- **Layer A — Identity & Context**: who you are (VP persona) plus the three
+  rolling summaries (user / group / vp). Slow-changing; updated by the
+  hourly Dream pass.
+- **Layer B — Pre-selected Memory**: a small set of memory entries the
+  Router decided are relevant for this turn. Treat these as authoritative
+  context; do not re-fetch unless something is missing.
+- **Layer C — Task Scope**: the active task summary and a short window of
+  related task threads. Empty when the turn has no task binding.
+- **Layer D — Turn Scope**: the in-flight messages, tool traces, and any
+  inbound envelope (a forwarded handoff from another VP).
+
+When information is missing, prefer to ask via tools rather than fabricating
+it. When in doubt about scope, the order of trust is: turn → task →
+preselected memory → identity summary.
+<!-- lang:zh -->
+# Prompt 结构（Worker）
+
+你是一个 Worker VP 的回合。Prompt 由四层组成，自上而下：
+
+- **A 层 · 身份与背景**：你的 VP 人设，以及三段缓慢更新的总结（用户 /
+  群组 / VP）。由每小时一次的 Dream 维护。
+- **B 层 · 路由预选记忆**：Router 判定与本轮相关的少量记忆条目，视为权威
+  上下文，缺失时再去取。
+- **C 层 · 任务范围**：当前任务的 summary，以及最近的相关任务窗口。无
+  任务绑定时该层为空。
+- **D 层 · 当前回合**：本轮的消息、工具调用 trace，以及（如有）从其他
+  VP 转交而来的 inbound envelope。
+
+信息缺失时优先用工具询问，不要编造。判定信息可信度的顺序：当前回合 >
+任务范围 > 预选记忆 > 身份总结。