@yeaft/webchat-agent 0.1.594 → 0.1.595

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.594",
+  "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;
+}