@yeaft/webchat-agent 0.1.593 → 0.1.595

package/package.json

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

package/unify/archive/tool-results.js

@@ -0,0 +1,158 @@
+/**
+ * archive/tool-results.js — DESIGN.md §4.3.
+ *
+ * Tool results balloon context (file dumps, web pages, grep output).
+ * When `turn_age > 5` AND content length > 2000 chars, archive the body
+ * to `…/archive/tool-results/<toolCallId>.md` and replace it in-place
+ * with a stub. The `[user, assistant(toolCalls), tool…]` pairing is
+ * preserved (the stub is still a `role:'tool'` message with the same
+ * `toolCallId`) so the engine never trips the OpenAI/Anthropic schema.
+ *
+ * This module is pure I/O + bookkeeping. It does NOT mutate the
+ * messages array directly; it returns a new array so callers can swap
+ * atomically.
+ */
+
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+
+const DEFAULT_TURN_AGE_MIN = 5;
+const DEFAULT_LENGTH_MIN = 2000;
+const STUB_PREVIEW_LEN = 200;
+
+/**
+ * Where a single archived body lives. The "scope" here is the directory
+ * containing the `archive/` folder — typically a group dir
+ * (`groups/<gid>`) but task-scoped tools archive under `tasks/<tid>/`.
+ *
+ * @param {{ root: string, scopeDir: string, toolCallId: string }} args
+ * @returns {string}
+ */
+export function toolArchivePath({ root, scopeDir, toolCallId }) {
+  if (!root || !scopeDir || !toolCallId) {
+    throw new Error('toolArchivePath: root + scopeDir + toolCallId required');
+  }
+  return join(root, scopeDir, 'archive', 'tool-results', `${toolCallId}.md`);
+}
+
+/**
+ * Compute the per-message `turn_age` for tool messages: how many
+ * `user` messages have appeared *after* the tool message (1-based — a
+ * tool message produced this turn has age 0).
+ *
+ * @param {object[]} messages
+ * @returns {number[]} same length as messages; age 0 for non-tool entries
+ */
+export function computeTurnAges(messages) {
+  if (!Array.isArray(messages)) return [];
+  const ages = new Array(messages.length).fill(0);
+  let userSeen = 0;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const m = messages[i];
+    if (m && m.role === 'user') {
+      userSeen += 1;
+      continue;
+    }
+    if (m && m.role === 'tool') ages[i] = userSeen;
+  }
+  return ages;
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   scopeDir: string,
+ *   message: object,
+ * }} args
+ * @returns {Promise<{ stub: object, archivedBytes: number, path: string }>}
+ */
+export async function archiveOne({ root, scopeDir, message }) {
+  if (!message || message.role !== 'tool') {
+    throw new Error('archiveOne: tool message required');
+  }
+  const toolCallId = message.toolCallId;
+  if (!toolCallId) throw new Error('archiveOne: toolCallId required');
+  const body = typeof message.content === 'string' ? message.content : JSON.stringify(message.content);
+  const path = toolArchivePath({ root, scopeDir, toolCallId });
+  await fs.mkdir(dirname(path), { recursive: true });
+  await fs.writeFile(path, body, 'utf8');
+  const sizeStr = formatSize(body.length);
+  const preview = body.slice(0, STUB_PREVIEW_LEN).replace(/\s+/g, ' ');
+  const stub = {
+    role: 'tool',
+    toolCallId,
+    content: `[archived: ${sizeStr}; preview: "${preview}"; retrieve via tool_trace("${toolCallId}")]`,
+    isError: !!message.isError,
+  };
+  return { stub, archivedBytes: body.length, path };
+}
+
+/**
+ * Read a previously-archived tool result body.
+ *
+ * @param {{ root: string, scopeDir: string, toolCallId: string }} args
+ * @returns {Promise<string|null>} body, or null if not found
+ */
+export async function readArchivedTool({ root, scopeDir, toolCallId }) {
+  const path = toolArchivePath({ root, scopeDir, toolCallId });
+  try {
+    return await fs.readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Sweep messages, archive every tool message that meets the age/length
+ * thresholds, return a new messages array with stubs swapped in. Untouched
+ * messages keep object identity.
+ *
+ * @param {{
+ *   root: string,
+ *   scopeDir: string,
+ *   messages: object[],
+ *   turnAgeMin?: number,
+ *   lengthMin?: number,
+ * }} args
+ * @returns {Promise<{
+ *   nextMessages: object[],
+ *   archivedCount: number,
+ *   archivedBytes: number,
+ * }>}
+ */
+export async function archiveToolResults({
+  root, scopeDir, messages,
+  turnAgeMin = DEFAULT_TURN_AGE_MIN, lengthMin = DEFAULT_LENGTH_MIN,
+}) {
+  if (!Array.isArray(messages)) throw new Error('archiveToolResults: messages array required');
+  const ages = computeTurnAges(messages);
+  let mutated = false;
+  let archivedCount = 0;
+  let archivedBytes = 0;
+  const out = messages.slice();
+  for (let i = 0; i < out.length; i += 1) {
+    const m = out[i];
+    if (!m || m.role !== 'tool' || !m.toolCallId) continue;
+    if (typeof m.content !== 'string') continue;
+    if (m.content.startsWith('[archived:')) continue;  // already a stub
+    if (ages[i] <= turnAgeMin) continue;
+    if (m.content.length <= lengthMin) continue;
+    const r = await archiveOne({ root, scopeDir, message: m });
+    out[i] = r.stub;
+    archivedCount += 1;
+    archivedBytes += r.archivedBytes;
+    mutated = true;
+  }
+  return {
+    nextMessages: mutated ? out : messages,
+    archivedCount,
+    archivedBytes,
+  };
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/unify/archive/trace.js

@@ -0,0 +1,70 @@
+/**
+ * archive/trace.js — DESIGN.md §4.4.
+ *
+ * Retrieval helpers backing the `tool_trace` / `message_trace` tools.
+ * The tool-registry wires these into the worker's toolset; this module
+ * is a thin wrapper around the archive readers with the ACL gate in
+ * place (only `vp/<other>/` is hard-blocked, per §1.2).
+ *
+ * Per design: the tools take a `toolCallId` / `turnId` plus the scope
+ * context (the worker passes its current scope dir). We never search
+ * across scopes — the caller knows which group/task/VP the lookup is
+ * for. Cross-VP lookups (`scopeDir = 'vp/<other>'`) throw `acl_blocked`.
+ */
+
+import { readArchivedTool } from './tool-results.js';
+import { readArchivedTurn } from './turn-archive.js';
+
+const VP_PREFIX = 'vp/';
+
+/**
+ * @param {string} scopeDir e.g. 'vp/grace' or 'groups/eng' or 'tasks/t_1'
+ * @param {string|null|undefined} currentVpId the VP making the call
+ */
+function aclCheck(scopeDir, currentVpId) {
+  if (typeof scopeDir !== 'string' || !scopeDir) {
+    throw new Error('trace: scopeDir required');
+  }
+  if (!scopeDir.startsWith(VP_PREFIX)) return;
+  const owner = scopeDir.slice(VP_PREFIX.length).split('/')[0];
+  if (!owner) return;
+  if (currentVpId && owner !== currentVpId) {
+    const e = new Error(`acl_blocked: ${scopeDir}`);
+    /** @type {any} */ (e).code = 'acl_blocked';
+    throw e;
+  }
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   scopeDir: string,
+ *   toolCallId: string,
+ *   currentVpId?: string,
+ * }} args
+ * @returns {Promise<{ ok: boolean, body?: string, error?: string }>}
+ */
+export async function toolTrace({ root, scopeDir, toolCallId, currentVpId }) {
+  aclCheck(scopeDir, currentVpId);
+  if (!toolCallId) return { ok: false, error: 'missing_toolCallId' };
+  const body = await readArchivedTool({ root, scopeDir, toolCallId });
+  if (body == null) return { ok: false, error: 'not_found' };
+  return { ok: true, body };
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   scopeDir: string,
+ *   turnId: string,
+ *   currentVpId?: string,
+ * }} args
+ * @returns {Promise<{ ok: boolean, header?: object, messages?: object[], error?: string }>}
+ */
+export async function messageTrace({ root, scopeDir, turnId, currentVpId }) {
+  aclCheck(scopeDir, currentVpId);
+  if (!turnId) return { ok: false, error: 'missing_turnId' };
+  const out = await readArchivedTurn({ root, scopeDir, turnId });
+  if (!out) return { ok: false, error: 'not_found' };
+  return { ok: true, header: out.header, messages: out.messages };
+}

package/unify/archive/turn-archive.js

@@ -0,0 +1,97 @@
+/**
+ * archive/turn-archive.js — DESIGN.md §4.2 + §4.4.
+ *
+ * When compact archives a cooling turn-group, the full content is
+ * written to `…/archive/<turnId>.md` so a worker can later replay it via
+ * `message_trace({turnId})`. Each archived turn is one markdown file
+ * with a YAML-ish header followed by JSON-encoded message bodies. We
+ * keep the format intentionally simple: any caller that can read JSON
+ * lines can replay it.
+ *
+ * Format:
+ *
+ *   ---
+ *   turnId: <id>
+ *   archivedAt: <ISO>
+ *   messageCount: <n>
+ *   ---
+ *   <line-delimited JSON, one message per line>
+ *
+ * We do NOT strip `_meta` here — DESIGN.md §9.15 says "Compact archive
+ * carries `_meta` into the archived turn — useful for `message_trace`
+ * replays".
+ */
+
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+
+/**
+ * @param {{ root: string, scopeDir: string, turnId: string }} args
+ */
+export function turnArchivePath({ root, scopeDir, turnId }) {
+  if (!root || !scopeDir || !turnId) {
+    throw new Error('turnArchivePath: root + scopeDir + turnId required');
+  }
+  return join(root, scopeDir, 'archive', `${turnId}.md`);
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   scopeDir: string,
+ *   turnId: string,
+ *   messages: object[],
+ *   archivedAt?: string,
+ * }} args
+ * @returns {Promise<{ path: string, byteLength: number }>}
+ */
+export async function archiveTurn({ root, scopeDir, turnId, messages, archivedAt }) {
+  if (!Array.isArray(messages)) throw new Error('archiveTurn: messages array required');
+  const path = turnArchivePath({ root, scopeDir, turnId });
+  await fs.mkdir(dirname(path), { recursive: true });
+  const header = [
+    '---',
+    `turnId: ${turnId}`,
+    `archivedAt: ${archivedAt || new Date().toISOString()}`,
+    `messageCount: ${messages.length}`,
+    '---',
+    '',
+  ].join('\n');
+  const body = messages.map(m => JSON.stringify(m)).join('\n');
+  const content = header + body + (messages.length ? '\n' : '');
+  await fs.writeFile(path, content, 'utf8');
+  return { path, byteLength: content.length };
+}
+
+/**
+ * @param {{ root: string, scopeDir: string, turnId: string }} args
+ * @returns {Promise<{ header: object, messages: object[] } | null>}
+ */
+export async function readArchivedTurn({ root, scopeDir, turnId }) {
+  const path = turnArchivePath({ root, scopeDir, turnId });
+  let content;
+  try {
+    content = await fs.readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const m = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return { header: {}, messages: [] };
+  const header = {};
+  for (const ln of m[1].split('\n')) {
+    const idx = ln.indexOf(':');
+    if (idx < 0) continue;
+    header[ln.slice(0, idx).trim()] = ln.slice(idx + 1).trim();
+  }
+  const messages = [];
+  for (const ln of m[2].split('\n')) {
+    if (!ln.trim()) continue;
+    try {
+      messages.push(JSON.parse(ln));
+    } catch {
+      // Skip torn line.
+    }
+  }
+  return { header, messages };
+}

package/unify/compact/decisions-log.js

@@ -0,0 +1,98 @@
+/**
+ * compact/decisions-log.js — DESIGN.md §9.1.
+ *
+ * Per-task append-only "decisions log". When two VPs run in parallel
+ * for the same `targetTaskId` (e.g. a router fan-out), both may want to
+ * write a decision. Atomic file create on `entries/*.md` solves the
+ * single-entry case; the decisions log is the sequencing layer that
+ * lets compact (track 2) read a chronological record and produce one
+ * canonical `tasks/<tid>/summary.md`.
+ *
+ * Format: line-delimited JSON (`decisions.jsonl`). Each line:
+ *
+ *   {"ts": "<ISO>", "vpId": "<id>", "kind": "<decision-kind>", "text": "<…>"}
+ *
+ * Append uses `fs.appendFile` which is atomic for small writes on
+ * POSIX. Readers tolerate partial last-line corruption (very unlikely
+ * but cheap to handle): unparseable lines are skipped with a warning.
+ */
+
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+
+const FILE = 'decisions.jsonl';
+
+/**
+ * @param {string} root
+ * @param {string} taskId
+ * @returns {string} absolute path
+ */
+export function decisionsLogPath(root, taskId) {
+  if (!root) throw new Error('decisionsLogPath: root required');
+  if (!taskId) throw new Error('decisionsLogPath: taskId required');
+  return join(root, 'tasks', taskId, FILE);
+}
+
+/**
+ * Append a decision row. Creates the parent directory on first write.
+ *
+ * @param {{
+ *   root: string,
+ *   taskId: string,
+ *   vpId: string,
+ *   kind: string,
+ *   text: string,
+ *   ts?: string,
+ * }} args
+ * @returns {Promise<{ path: string, line: string }>}
+ */
+export async function appendDecision({ root, taskId, vpId, kind, text, ts }) {
+  if (!vpId) throw new Error('appendDecision: vpId required');
+  if (!kind) throw new Error('appendDecision: kind required');
+  const path = decisionsLogPath(root, taskId);
+  await fs.mkdir(dirname(path), { recursive: true });
+  const row = {
+    ts: ts || new Date().toISOString(),
+    vpId,
+    kind,
+    text: typeof text === 'string' ? text : '',
+  };
+  const line = JSON.stringify(row) + '\n';
+  await fs.appendFile(path, line, 'utf8');
+  return { path, line };
+}
+
+/**
+ * Read the decisions log. Returns [] on missing file. Skips lines that
+ * fail JSON parse (logged via console.warn) so a torn write never
+ * blocks the reader.
+ *
+ * @param {{ root: string, taskId: string }} args
+ * @returns {Promise<Array<{ts: string, vpId: string, kind: string, text: string}>>}
+ */
+export async function readDecisions({ root, taskId }) {
+  const path = decisionsLogPath(root, taskId);
+  let content;
+  try {
+    content = await fs.readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  const lines = content.split('\n');
+  for (const ln of lines) {
+    if (!ln.trim()) continue;
+    try {
+      const row = JSON.parse(ln);
+      if (row && typeof row === 'object') out.push(row);
+    } catch {
+      // Tolerate the very last line being torn; warn but continue.
+      // (We could distinguish "torn last line" vs "corrupt mid-line"
+      // but the read path doesn't need to.)
+      // eslint-disable-next-line no-console
+      console.warn(`decisions-log: skipped unparseable line in ${path}`);
+    }
+  }
+  return out;
+}

package/unify/compact/orchestrator.js

@@ -0,0 +1,147 @@
+/**
+ * compact/orchestrator.js — DESIGN.md §4.2.
+ *
+ * One trigger, one pass, three tracks. The orchestrator owns the
+ * sequencing; the actual LLM-driven summarisation and extraction are
+ * supplied as injectables so this file stays small, deterministic, and
+ * testable without network.
+ *
+ * Track 1 — message compaction (always runs):
+ *   1. Find the cooling turn-groups (older than the hot window).
+ *   2. Generate a `compact_summary` of those groups.
+ *   3. Archive each cooling group atomically; replace it in the live
+ *      messages array with a single placeholder message.
+ *
+ * Track 2 — task summary refresh (when `taskId` is provided):
+ *   4. Refresh `tasks/<tid>/summary.md` from the cooling groups + the
+ *      prior summary. Atomic via the existing `writeSummary` helper.
+ *
+ * Track 3 — memory extraction (always runs):
+ *   5. Extract durable facts/lessons/preferences and write them as
+ *      scope entries through the supplied `extract` callback. The
+ *      callback owns scope routing and `index.md` upserts; this file
+ *      just hands it the cooling groups.
+ *
+ * Atomicity rule (§9.2): each cooling turn-group is archived as a
+ * unit. We never break a `[user, assistant(toolCalls), tool…]` triple.
+ * Track 1 is the only place that mutates `messages`.
+ */
+
+import { groupTurns, pickCoolingGroups, indicesFromGroups } from './turn-group.js';
+import { writeSummary } from '../memory/scope-tree.js';
+
+/**
+ * @typedef {{
+ *   summarise: (coolingMessages: object[]) => Promise<string>,
+ *   archive: (groupIndex: number, coolingMessages: object[]) => Promise<{ turnId: string }>,
+ *   extract?: (coolingMessages: object[]) => Promise<{ written: number }>,
+ *   refreshTaskSummary?: (coolingMessages: object[], priorSummary: string) => Promise<string>,
+ *   readPriorTaskSummary?: () => Promise<string>,
+ * }} CompactHooks
+ */
+
+/**
+ * @param {{
+ *   messages: object[],
+ *   keepHot?: number,
+ *   taskId?: string | null,
+ *   root?: string,
+ *   hooks: CompactHooks,
+ * }} args
+ * @returns {Promise<{
+ *   archivedGroups: number,
+ *   archivedMessages: number,
+ *   compactSummary: string,
+ *   extractedCount: number,
+ *   taskSummaryRefreshed: boolean,
+ *   nextMessages: object[],
+ * }>}
+ */
+export async function runCompact({ messages, keepHot = 10, taskId = null, root, hooks }) {
+  if (!Array.isArray(messages)) {
+    throw new Error('runCompact: messages array required');
+  }
+  if (!hooks || typeof hooks !== 'object') {
+    throw new Error('runCompact: hooks required');
+  }
+  if (typeof hooks.summarise !== 'function') {
+    throw new Error('runCompact: hooks.summarise required');
+  }
+  if (typeof hooks.archive !== 'function') {
+    throw new Error('runCompact: hooks.archive required');
+  }
+
+  const groups = groupTurns(messages);
+  const { hot, cooling } = pickCoolingGroups(groups, keepHot);
+
+  // Nothing to compact — return early. We still report `nextMessages` so
+  // callers can treat the result uniformly (no copy unless we changed
+  // anything).
+  if (cooling.length === 0) {
+    return {
+      archivedGroups: 0,
+      archivedMessages: 0,
+      compactSummary: '',
+      extractedCount: 0,
+      taskSummaryRefreshed: false,
+      nextMessages: messages,
+    };
+  }
+
+  // Slice out the cooling messages once for the summariser/extractor.
+  const coolingIdx = indicesFromGroups(cooling);
+  const coolingMessages = coolingIdx.map(i => messages[i]);
+
+  // Track 1.2 — summarise.
+  const compactSummary = await hooks.summarise(coolingMessages);
+
+  // Track 1.3 — archive each cooling group atomically.
+  const archiveResults = [];
+  for (let i = 0; i < cooling.length; i += 1) {
+    const g = cooling[i];
+    const groupMsgs = messages.slice(g.start, g.end);
+    const r = await hooks.archive(i, groupMsgs);
+    archiveResults.push({ ...g, turnId: r?.turnId });
+  }
+
+  // Track 2 — refresh task summary if applicable.
+  let taskSummaryRefreshed = false;
+  if (taskId && root && typeof hooks.refreshTaskSummary === 'function') {
+    const prior = typeof hooks.readPriorTaskSummary === 'function'
+      ? await hooks.readPriorTaskSummary() : '';
+    const next = await hooks.refreshTaskSummary(coolingMessages, prior);
+    if (typeof next === 'string' && next.trim()) {
+      await writeSummary({ kind: 'task', id: taskId }, next, { root });
+      taskSummaryRefreshed = true;
+    }
+  }
+
+  // Track 3 — memory extraction.
+  let extractedCount = 0;
+  if (typeof hooks.extract === 'function') {
+    const extractResult = await hooks.extract(coolingMessages);
+    if (extractResult && Number.isFinite(extractResult.written)) {
+      extractedCount = extractResult.written;
+    }
+  }
+
+  // Track 1.3 (cont.) — produce the new messages array with the cooling
+  // window replaced by a single `compact_summary` placeholder.
+  const placeholder = {
+    role: 'system',
+    kind: 'compact_summary',
+    content: compactSummary || '',
+  };
+  // Hot starts at the index right after the last cooling group.
+  const cutoff = cooling[cooling.length - 1].end;
+  const nextMessages = [placeholder, ...messages.slice(cutoff)];
+
+  return {
+    archivedGroups: cooling.length,
+    archivedMessages: coolingIdx.length,
+    compactSummary: compactSummary || '',
+    extractedCount,
+    taskSummaryRefreshed,
+    nextMessages,
+  };
+}

package/unify/compact/triggers.js

@@ -0,0 +1,54 @@
+/**
+ * compact/triggers.js — DESIGN.md §4.1.
+ *
+ * Pure functions: do I need to compact, and which triggers fired?
+ * Caller (orchestrator) decides what to do next; this module never
+ * touches disk or messages.
+ */
+
+const DEFAULT_MAX_MESSAGES = 50;
+const DEFAULT_TOKEN_RATIO = 0.9;
+const DEFAULT_IDLE_MS = 2 * 60 * 1000;
+
+/**
+ * @param {{
+ *   messages: object[],
+ *   tokenCount: number,
+ *   contextLimit: number,
+ *   lastActivityAt?: number,
+ *   now?: number,
+ *   explicit?: boolean,
+ *   maxMessages?: number,
+ *   tokenRatio?: number,
+ *   idleMs?: number,
+ * }} state
+ * @returns {{ trigger: boolean, reasons: string[] }}
+ */
+export function evaluateCompactTriggers(state = {}) {
+  const reasons = [];
+  const messages = Array.isArray(state.messages) ? state.messages : [];
+  const tokenCount = Number.isFinite(state.tokenCount) ? state.tokenCount : 0;
+  const contextLimit = Number.isFinite(state.contextLimit) && state.contextLimit > 0
+    ? state.contextLimit : 0;
+  const tokenRatio = Number.isFinite(state.tokenRatio) ? state.tokenRatio : DEFAULT_TOKEN_RATIO;
+  const maxMessages = Number.isFinite(state.maxMessages) ? state.maxMessages : DEFAULT_MAX_MESSAGES;
+  const idleMs = Number.isFinite(state.idleMs) ? state.idleMs : DEFAULT_IDLE_MS;
+
+  if (state.explicit) reasons.push('explicit');
+
+  if (contextLimit > 0 && tokenCount > tokenRatio * contextLimit) {
+    reasons.push('token_threshold');
+  }
+
+  if (messages.length > maxMessages) {
+    reasons.push('message_count');
+  }
+
+  if (Number.isFinite(state.lastActivityAt) && Number.isFinite(state.now)) {
+    if (state.now - state.lastActivityAt > idleMs) {
+      reasons.push('idle');
+    }
+  }
+
+  return { trigger: reasons.length > 0, reasons };
+}

package/unify/compact/turn-group.js

@@ -0,0 +1,85 @@
+/**
+ * compact/turn-group.js — DESIGN.md §9.2.
+ *
+ * Group messages into turns whose unit of archiving is "atomic": each
+ * group is either kept entirely live or archived entirely. Archiving
+ * an assistant message that contained `toolCalls` while leaving the
+ * tool results live (or vice versa) breaks the OpenAI invariant that
+ * `tool_call_id`s must be paired.
+ *
+ * A "turn group" starts on a `user` message and extends through every
+ * subsequent assistant + tool message until the next user message. The
+ * grouping function returns an array of `{ start, end, indices }` pairs
+ * where `[start, end)` is a half-open range over the input array.
+ *
+ * Edge cases:
+ *   - Leading non-user messages (e.g. a system or tool prelude written
+ *     by an init hook) form a group of their own at index 0.
+ *   - Trailing assistant/tool messages (incomplete turn) form the final
+ *     group — same rule.
+ *   - Empty input → empty result.
+ */
+
+/**
+ * @param {object[]} messages
+ * @returns {Array<{ start: number, end: number, role: string }>}
+ *   `role` reflects the group's anchor (the `user` message, if any;
+ *   otherwise the first message in the group).
+ */
+export function groupTurns(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return [];
+  const groups = [];
+  let cur = { start: 0, end: 0, role: messages[0]?.role || 'unknown' };
+  for (let i = 0; i < messages.length; i += 1) {
+    const m = messages[i];
+    if (!m || typeof m !== 'object') {
+      // Treat as belonging to the current group (don't break pairing).
+      cur.end = i + 1;
+      continue;
+    }
+    if (m.role === 'user' && cur.end > cur.start) {
+      groups.push(cur);
+      cur = { start: i, end: i + 1, role: 'user' };
+    } else {
+      cur.end = i + 1;
+      if (m.role === 'user') cur.role = 'user';
+    }
+  }
+  if (cur.end > cur.start) groups.push(cur);
+  return groups;
+}
+
+/**
+ * Pick the cut point: keep `keepHot` newest groups live, return the
+ * rest as "cooling" candidates for archive.
+ *
+ * Returns: `{ hot: groups[], cooling: groups[] }`. Both arrays use the
+ * same `{start, end, role}` shape from `groupTurns`.
+ *
+ * @param {Array<{start: number, end: number, role: string}>} groups
+ * @param {number} keepHot
+ */
+export function pickCoolingGroups(groups, keepHot = 10) {
+  if (!Array.isArray(groups)) return { hot: [], cooling: [] };
+  const k = Math.max(0, Math.floor(keepHot));
+  if (groups.length <= k) return { hot: groups.slice(), cooling: [] };
+  const cut = groups.length - k;
+  return {
+    hot: groups.slice(cut),
+    cooling: groups.slice(0, cut),
+  };
+}
+
+/**
+ * Flatten a list of groups back into the underlying message indices.
+ *
+ * @param {Array<{start: number, end: number}>} groups
+ * @returns {number[]}
+ */
+export function indicesFromGroups(groups) {
+  const out = [];
+  for (const g of groups) {
+    for (let i = g.start; i < g.end; i += 1) out.push(i);
+  }
+  return out;
+}

package/unify/prompts.js

@@ -163,6 +163,8 @@ const RAW_TEMPLATES = {
   // buildRouterPrompt callers will simply omit the section.
   harnessWorkerShape: readTemplate('harness/worker-shape.md', { required: false }),
   harnessRouterShape: readTemplate('harness/router-shape.md', { required: false }),
+  // Phase 3b — coordinator harness rule for inter-VP forwarding.
+  harnessRouterHandoff: readTemplate('harness/router-handoff.md', { required: false }),
 };
 
 /**
@@ -768,6 +770,39 @@ export function buildWorkerPrompt(params = {}) {
   return parts.join('\n\n');
 }
 
+/**
+ * Render the previous turn's router plan as a `## prior_plan` block, so
+ * the router can decide whether to extend it or start fresh
+ * (DESIGN.md §9.15). Returns '' when there is no prior plan to render.
+ *
+ * @param {object|null|undefined} priorPlan
+ * @param {'en'|'zh'} [language='en']
+ * @returns {string}
+ */
+export function renderPriorPlan(priorPlan, language = 'en') {
+  if (!priorPlan || typeof priorPlan !== 'object') return '';
+  const header = language === 'zh' ? '## 上一轮 plan' : '## prior_plan';
+  const lines = [];
+  if (priorPlan.vpId) lines.push(`vpId: ${priorPlan.vpId}`);
+  const fq = priorPlan.forwardQuery;
+  if (fq && (fq.userOriginal || fq.intent)) {
+    if (fq.intent) lines.push(`intent: ${fq.intent}`);
+    if (fq.userOriginal) lines.push(`userOriginal: ${fq.userOriginal}`);
+  }
+  const pre = priorPlan.preselect;
+  if (pre) {
+    if (Array.isArray(pre.memoryPaths) && pre.memoryPaths.length) {
+      lines.push(`memoryPaths: ${pre.memoryPaths.join(', ')}`);
+    }
+    if (Array.isArray(pre.taskIds) && pre.taskIds.length) {
+      lines.push(`taskIds: ${pre.taskIds.join(', ')}`);
+    }
+  }
+  if (priorPlan.thinking) lines.push(`thinking: ${priorPlan.thinking}`);
+  if (!lines.length) return '';
+  return `${header}\n${lines.join('\n')}`;
+}
+
 /**
  * Router prompt entry point (DESIGN.md Phase 1).
  *
@@ -780,12 +815,13 @@ export function buildWorkerPrompt(params = {}) {
  *   language?: 'en'|'zh',
  *   summaries?: {user?: string, group?: string, vp?: string},
  *   routerContext?: string,
+ *   priorPlan?: object|null,
  *   includeShape?: boolean,
  * }} params
  * @returns {string}
  */
 export function buildRouterPrompt(params = {}) {
-  const { language = 'en', summaries, routerContext, includeShape = true } = params;
+  const { language = 'en', summaries, routerContext, priorPlan, includeShape = true } = params;
   const parts = [];
 
   if (includeShape) {
@@ -796,6 +832,9 @@ export function buildRouterPrompt(params = {}) {
   const summaryBlock = renderLayerASummaries(summaries, language);
   if (summaryBlock) parts.push(summaryBlock);
 
+  const priorBlock = renderPriorPlan(priorPlan, language);
+  if (priorBlock) parts.push(priorBlock);
+
   if (typeof routerContext === 'string' && routerContext.trim()) {
     parts.push(routerContext.trim());
   }

package/unify/router/continuity.js

@@ -0,0 +1,108 @@
+/**
+ * router/continuity.js — DESIGN.md §9.15 priorPlan carry-back.
+ *
+ * Phase 3b scope:
+ *   - `attachRouterPlan(message, plan)` — write the plan as `_meta.routerPlan`
+ *     on the assistant message that produced it.
+ *   - `extractPriorPlan(messages, vpId)` — find the most recent assistant
+ *     message belonging to the given VP and return its `_meta.routerPlan`.
+ *   - `stripMetaForWire(messages)` — drop `_meta` before sending to the LLM
+ *     (it's bookkeeping, never model-visible).
+ *
+ * The skip-router heuristic (§9.15 #1) is intentionally NOT implemented in
+ * Phase 3b — DESIGN.md §8 line 391 says "do NOT ship the skip-router
+ * heuristic yet". We just plumb the metadata; the dispatcher can decide.
+ *
+ * Per-VP attribution: an assistant message belongs to a VP when its
+ * `_meta.routerPlan.vpId` matches; we never guess from content. First turn
+ * of a fresh group has no priorPlan — that is the expected cold-start.
+ */
+
+/** @typedef {{
+ *   vpId: string,
+ *   forwardQuery?: { userOriginal?: string, intent?: string },
+ *   preselect?: { memoryPaths?: string[], taskIds?: string[] },
+ *   thinking?: 'high'|'max'|null,
+ *   thinkingReason?: string,
+ * }} RouterPlanLike
+ */
+
+/**
+ * Attach a router plan to an assistant message. Mutates `message` in place
+ * and returns it. We mutate (rather than clone) because the caller is the
+ * engine appending to its own `conversationMessages` array — cloning would
+ * just discard the work.
+ *
+ * Tool messages do not carry plans (no plan attached to a tool result).
+ *
+ * @param {object} message
+ * @param {RouterPlanLike|null|undefined} plan
+ * @returns {object}
+ */
+export function attachRouterPlan(message, plan) {
+  if (!message || typeof message !== 'object') return message;
+  if (message.role !== 'assistant') return message;
+  if (!plan || typeof plan !== 'object' || !plan.vpId) return message;
+  message._meta = message._meta || {};
+  message._meta.routerPlan = {
+    vpId: plan.vpId,
+    forwardQuery: plan.forwardQuery
+      ? {
+        userOriginal: plan.forwardQuery.userOriginal || '',
+        intent: plan.forwardQuery.intent || '',
+      } : undefined,
+    preselect: plan.preselect
+      ? {
+        memoryPaths: Array.isArray(plan.preselect.memoryPaths)
+          ? [...plan.preselect.memoryPaths] : [],
+        taskIds: Array.isArray(plan.preselect.taskIds)
+          ? [...plan.preselect.taskIds] : [],
+      } : undefined,
+    thinking: plan.thinking ?? null,
+    thinkingReason: plan.thinkingReason || '',
+  };
+  return message;
+}
+
+/**
+ * Walk `messages` from the end, return the most recent assistant message's
+ * `_meta.routerPlan` whose `vpId` matches. Returns null if none found —
+ * that's a cold start, not an error.
+ *
+ * @param {object[]} messages
+ * @param {string} vpId
+ * @returns {RouterPlanLike | null}
+ */
+export function extractPriorPlan(messages, vpId) {
+  if (!Array.isArray(messages) || !vpId) return null;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const m = messages[i];
+    if (!m || m.role !== 'assistant') continue;
+    const plan = m._meta && m._meta.routerPlan;
+    if (plan && plan.vpId === vpId) return plan;
+  }
+  return null;
+}
+
+/**
+ * Return a copy of the messages array with `_meta` stripped from every
+ * message. The serialisers (anthropic/openai-responses) read this; it is
+ * NEVER part of the wire payload. Cheap because we only shallow-clone the
+ * messages that actually have `_meta`.
+ *
+ * @param {object[]} messages
+ * @returns {object[]}
+ */
+export function stripMetaForWire(messages) {
+  if (!Array.isArray(messages)) return messages;
+  let mutated = false;
+  const out = messages.map(m => {
+    if (m && typeof m === 'object' && '_meta' in m) {
+      mutated = true;
+      const { _meta, ...rest } = m;
+      return rest;
+    }
+    return m;
+  });
+  return mutated ? out : messages;
+}

package/unify/router/thinking.js

@@ -0,0 +1,78 @@
+/**
+ * router/thinking.js — DESIGN.md §9.16 thinking-mode precedence chain.
+ *
+ * Resolves the final `thinking` value the engine should pass to the
+ * adapter, given the four signal sources:
+ *
+ *   1. UI override     (highest)  — submitOptions / topbar selector
+ *   2. Router plan     —           — per-plan thinking field
+ *   3. VP default      —           — vp/<id>/role.md frontmatter
+ *   4. Global default  (lowest)    — config.thinking.default
+ *
+ * Allowed values: `'high' | 'max' | null`. (`null` ⇒ adapter drops the
+ * field; provider-specific normalisation happens at the adapter via
+ * `models.js#normalizeEffort`.)
+ *
+ * Continuity rule (§9.16): when no UI override is in force AND the router
+ * did not change its recommendation versus the prior plan, keep the prior
+ * plan's value. Anthropic prompt cache keys include the thinking field;
+ * unstable values cause prefix re-encoding every turn.
+ *
+ * The `allowRouterEscalate: false` config gate hard-blocks the router
+ * from bumping below→`max`. UI overrides bypass that gate (they're the
+ * user's direct intent, not a heuristic).
+ */
+
+const ALLOWED = new Set([null, 'high', 'max']);
+
+/**
+ * @param {*} v
+ * @returns {'high'|'max'|null}
+ */
+function clean(v) {
+  if (v === undefined) return null;
+  return ALLOWED.has(v) ? v : null;
+}
+
+/**
+ * @param {{
+ *   uiOverride?: 'high'|'max'|null,
+ *   routerPlan?: 'high'|'max'|null,
+ *   priorPlan?: 'high'|'max'|null,
+ *   vpDefault?: 'high'|'max'|null,
+ *   globalDefault?: 'high'|'max'|null,
+ *   allowRouterEscalate?: boolean,
+ * }} signals
+ * @returns {{ value: 'high'|'max'|null, source: 'ui'|'router'|'prior'|'vp'|'global'|'default' }}
+ */
+export function resolveThinking(signals = {}) {
+  const ui = clean(signals.uiOverride);
+  if (ui) return { value: ui, source: 'ui' };
+
+  const router = clean(signals.routerPlan);
+  const prior = clean(signals.priorPlan);
+  const vp = clean(signals.vpDefault);
+  const global_ = clean(signals.globalDefault);
+  const escalateOk = signals.allowRouterEscalate !== false;
+
+  // Continuity: if router agrees with prior or is silent, prefer prior to
+  // keep the cache key stable.
+  if (router && prior && router === prior) {
+    return { value: prior, source: 'prior' };
+  }
+
+  if (router) {
+    // allowRouterEscalate=false hard-blocks router from emitting 'max'
+    // when the baseline is 'high'.
+    const baseline = prior || vp || global_ || 'high';
+    if (!escalateOk && router === 'max' && baseline !== 'max') {
+      return { value: baseline, source: prior ? 'prior' : (vp ? 'vp' : 'global') };
+    }
+    return { value: router, source: 'router' };
+  }
+
+  if (prior) return { value: prior, source: 'prior' };
+  if (vp) return { value: vp, source: 'vp' };
+  if (global_) return { value: global_, source: 'global' };
+  return { value: 'high', source: 'default' };
+}

package/unify/router/vp-planner.js

@@ -280,3 +280,62 @@ export async function runPlansSequential(plans, runOne, opts = {}) {
   }
   return { results, errors };
 }
+
+/**
+ * Parallel fan-out runner (Phase 3.5). Calls `runOne(plan, index)` for each
+ * plan concurrently, with optional `concurrency` cap. Results are returned
+ * in input order regardless of completion order. Errors from `runOne` are
+ * caught per-plan and DO NOT abort siblings (DESIGN.md §9.1 — concurrent
+ * VP turns must be independent).
+ *
+ * NOTE: parallel mode loses the `prior[]` channel that the sequential
+ * runner provides. Callers that need plan N to read plan N-1's output must
+ * use `runPlansSequential`. The dispatcher chooses based on whether the
+ * plans share a `targetTaskId` (parallel-safe) or pipeline data
+ * (sequential-only).
+ *
+ * @param {VpPlan[]} plans
+ * @param {(plan: VpPlan, index: number) => Promise<*>} runOne
+ * @param {{ groupMemberIds?: string[], concurrency?: number }} [opts]
+ * @returns {Promise<{ results: any[], errors: Array<{ index: number, error: Error }> }>}
+ */
+export async function runPlansParallel(plans, runOne, opts = {}) {
+  if (!Array.isArray(plans)) throw new Error('runPlansParallel: plans array required');
+  if (typeof runOne !== 'function') throw new Error('runPlansParallel: runOne fn required');
+  const memberSet = Array.isArray(opts.groupMemberIds)
+    ? new Set(opts.groupMemberIds) : null;
+  const concurrency = Number.isFinite(opts.concurrency) && opts.concurrency > 0
+    ? Math.floor(opts.concurrency) : Infinity;
+
+  const results = new Array(plans.length);
+  const errors = [];
+  let nextIdx = 0;
+
+  const runSlot = async () => {
+    // Workers pull tasks from a shared queue index — preserves backpressure
+    // when concurrency < plans.length without per-task scheduling overhead.
+    while (true) {
+      const i = nextIdx;
+      nextIdx += 1;
+      if (i >= plans.length) return;
+      const plan = plans[i];
+      if (memberSet && !memberSet.has(plan.vpId)) {
+        results[i] = { index: i, vpId: plan.vpId, skipped: 'not_member' };
+        continue;
+      }
+      try {
+        results[i] = await runOne(plan, i);
+      } catch (err) {
+        errors.push({ index: i, error: err });
+        results[i] = { index: i, vpId: plan.vpId, error: err };
+      }
+    }
+  };
+
+  const workerCount = Math.min(plans.length, concurrency);
+  const workers = [];
+  for (let w = 0; w < workerCount; w += 1) workers.push(runSlot());
+  await Promise.all(workers);
+
+  return { results, errors };
+}

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

@@ -0,0 +1,34 @@
+<!-- lang:en -->
+# Harness — Router Handoff
+
+If, while drafting your reply, you realise you are the wrong VP for this
+turn, hand off instead of guessing. Call `route_forward(targetVpId, reason)`
+with a short, actionable reason. The next turn becomes the receiving VP's
+turn with your reason as the inbound envelope — they act with no other
+context from you.
+
+Use this when:
+
+- The user's question is outside your expertise and another VP in the
+  group clearly owns it.
+- Your read of the situation is "this is comms not kernel" / "this is
+  legal not engineering" — name the boundary.
+
+Do NOT use this to dodge hard questions you legitimately own. The router
+already picked you; only forward when the topic genuinely belongs to
+someone else.
+<!-- lang:zh -->
+# Harness — Router 转交
+
+如果你在起草回复时发现本轮应该由其他 VP 来回答，请直接转交，而不是
+强答。调用 `route_forward(targetVpId, reason)` 并给出简短可操作的原因。
+下一轮变为目标 VP 的回合，你给的 reason 即为他们看到的入站信封——他
+们不会读到你的其他上下文。
+
+适用场景：
+
+- 用户的问题超出你的专业范围，群里另一个 VP 显然更合适。
+- 你判断「这是沟通不是内核」/「这是法务不是工程」——说出边界。
+
+不要用它来回避你确实该回答的问题。Router 既然选了你，只有当话题
+确实属于他人时才转交。