@yeaft/webchat-agent 1.0.446 → 1.0.448

package/yeaft/compact/compactor.js

@@ -1,283 +0,0 @@
-/**
- * compactor.js — per-group post-turn history compactor.
- *
- * Owns the orchestration that previously lived inline in
- * `agent/yeaft/web-bridge.js` as `getCompactState` /
- * `scheduleCompactAfterTurn` / `runCompactNow`. Bridge keeps WS knowledge
- * and history ownership; this class owns:
- *   - per-group single-flight + anti-starvation `pending` chain,
- *   - the precheck via `shouldCompactHistory`,
- *   - the call into `compactHistory` (which itself calls the supplied
- *     `summarize` injectable — bound to `Engine.summarizeForCompact` by
- *     `session.js`),
- *   - the race-guard that bails when the live history reference / length
- *     diverges from the snapshot we captured before awaiting the LLM.
- *
- * History is passed in PER CALL via a `historyHandle = { get, set }` so
- * Compactor never has to know about `sessionContexts`, `historyHydrated`,
- * or any other bridge-internal field. The WS event sink is wired
- * separately via `setOnCompacted`.
- *
- * Engine instances are per-VP-per-group (`vpEngines` keyed by
- * `${sessionId}::${vpId}`), so this orchestration cannot live on `Engine`
- * itself: a per-group single-flight slot pinned to a per-VP Engine is a
- * category error. Compactor is constructed once per session, beside the
- * `dreamScheduler`.
- */
-
-import { compactHistory, shouldCompactHistory } from '../history-compact.js';
-
-/**
- * Output cap for the summarizer call. The full compacted history is
- * built around the LLM-produced summary, so the summary itself must be
- * bounded — too long defeats the point of compacting, too short loses
- * context. 1024 tokens is the value that lived inline in the old
- * `runCompactNow` helper in `web-bridge.js` and matches the budget
- * `compactHistory` plans around.
- */
-const SUMMARIZER_MAX_TOKENS = 1024;
-
-/**
- * @typedef {object} CompactorHistoryHandle
- * @property {() => Array<object>} get  — return the current live history array
- * @property {(next: Array<object>) => void} set  — replace the array reference
- */
-
-/**
- * @typedef {object} CompactedResult
- * @property {string|null} reason
- * @property {number} beforeTurns
- * @property {number} afterTurns
- * @property {number} beforeTokens
- * @property {number} afterTokens
- * @property {number} archivedCount
- */
-
-export class Compactor {
-  /**
-   * @param {object} opts
-   * @param {(args: {system: string, prompt: string, maxTokens?: number}) => Promise<string>} opts.summarize
-   *        Bound to `engine.summarizeForCompact` by `session.js`. Returns
-   *        the trimmed summary text (or '' on failure — `compactHistory`
-   *        treats that as a soft failure).
-   * @param {() => number|undefined} [opts.getMaxContextTokens]
-   *        Returns the model-aware context window (preferred — provided
-   *        by `session.js` via `resolveContextWindow(model, config)`) or
-   *        a flat `config.maxContextTokens` fallback. The number is
-   *        threaded into `shouldCompactHistory` as `maxContextTokens`.
-   * @param {() => number|undefined} [opts.getTriggerRatio]
-   *        Returns the fraction-of-context threshold (e.g. `0.7` for the
-   *        user-stated "70% of model context"). The application-wide
-   *        default is 0.7, enforced by the injector in `session.js` — a
-   *        finite number in (0, 1) wins, anything else falls back to 0.7.
-   *
-   *        When NO injector is wired (typically test fixtures that omit
-   *        `getTriggerRatio` entirely), this falls through to
-   *        `shouldCompactHistory`'s library default (`DEFAULT_TOKEN_FRACTION`
-   *        = 0.5). That gap is intentional: the library default is the
-   *        documented unit-test contract, the application default is the
-   *        user-facing product contract, and the injector boundary is what
-   *        keeps them from drifting in production. Production callers MUST
-   *        wire `getTriggerRatio` (session.js does). Live-read so a config
-   *        edit takes effect without reboot.
-   * @param {() => string|undefined} [opts.getLanguage]
-   *        Returns the live `config.language`. Threaded into
-   *        `compactHistory` so the compactor's summary prompt + the
-   *        "session continued" wrapper render in the user's preferred
-   *        locale instead of always English.
-   * @param {(sessionId: string, result: CompactedResult) => void} [opts.onCompacted]
-   *        Optional sink. Bridge wires this to send the
-   *        `yeaft_history_compacted` WS event. Default: no-op. Can be
-   *        replaced post-construction via `setOnCompacted`.
-   */
-  constructor({ summarize, getMaxContextTokens, getTriggerRatio, getLanguage, onCompacted } = {}) {
-    if (typeof summarize !== 'function') {
-      throw new TypeError('Compactor: summarize is required');
-    }
-    this._summarize = summarize;
-    this._getMaxContextTokens = typeof getMaxContextTokens === 'function'
-      ? getMaxContextTokens
-      : () => undefined;
-    this._getTriggerRatio = typeof getTriggerRatio === 'function'
-      ? getTriggerRatio
-      : () => undefined;
-    this._getLanguage = typeof getLanguage === 'function'
-      ? getLanguage
-      : () => undefined;
-    this._onCompacted = typeof onCompacted === 'function' ? onCompacted : () => {};
-    /** @type {Map<string, { inFlight: Promise<void>|null, pending: boolean }>} */
-    this._states = new Map();
-  }
-
-  /**
-   * Replace the post-success sink. Bridge calls this from
-   * `installYeaftRuntimeBridge` once the bridge-local
-   * `sendToServer` + `yeaftConversationId` are available — keeps WS
-   * knowledge out of Compactor's constructor and avoids a circular
-   * import between `session.js` and `web-bridge.js`.
-   */
-  setOnCompacted(fn) {
-    this._onCompacted = typeof fn === 'function' ? fn : () => {};
-  }
-
-  /** Get-or-create the per-group state record. */
-  _state(sessionId) {
-    let s = this._states.get(sessionId);
-    if (!s) {
-      s = { inFlight: null, pending: false };
-      this._states.set(sessionId, s);
-    }
-    return s;
-  }
-
-  /**
-   * Entry-gate await. Bridge calls at the top of `handleYeaftGroupChat`
-   * so a brand-new turn never reads a half-mutated history mid-compact.
-   * Other groups' compacts never block this gate (per-group keying).
-   *
-   * @param {string} sessionId
-   */
-  async awaitInFlight(sessionId) {
-    if (!sessionId) return;
-    const s = this._states.get(sessionId);
-    if (s && s.inFlight) {
-      try { await s.inFlight; } catch { /* _runOnce already logs */ }
-    }
-  }
-
-  /**
-   * Post-turn fire-and-forget. Bridge calls after the per-VP fanout
-   * completes for a turn. The `historyHandle` MUST be a per-call value:
-   * its `get` / `set` close over the bridge's sessionId-scoped helpers
-   * (`getOrCreateSessionHistory` / `setGroupHistory`), not over a frozen
-   * snapshot, so a chained follow-up sees fresh state.
-   *
-   * Anti-starvation: while a compact is in flight, additional
-   * `scheduleAfterTurn` calls collapse to a single `pending=true`. Once
-   * the in-flight finishes, exactly one follow-up runs (no matter how
-   * many turns piled up during the await).
-   *
-   * @param {string} sessionId
-   * @param {CompactorHistoryHandle} historyHandle
-   */
-  scheduleAfterTurn(sessionId, historyHandle) {
-    if (!sessionId || !historyHandle) return;
-    const s = this._state(sessionId);
-    if (s.inFlight) {
-      // Anti-starvation: compact is already running. Mark a follow-up
-      // so when it finishes, it re-evaluates and runs again if still
-      // triggered.
-      s.pending = true;
-      return;
-    }
-    s.inFlight = this._runOnce(sessionId, historyHandle).finally(() => {
-      s.inFlight = null;
-      // If turns piled up while we were running and compaction is still
-      // needed, chain a follow-up. Use a microtask so the .finally
-      // chain settles cleanly before the next promise is created.
-      if (s.pending) {
-        s.pending = false;
-        queueMicrotask(() => this.scheduleAfterTurn(sessionId, historyHandle));
-      }
-    });
-  }
-
-  /**
-   * One compact pass. Captures snapshot reference + length, runs the
-   * precheck, calls `compactHistory`, race-guards, applies via
-   * `historyHandle.set`, then notifies `onCompacted`. All errors are
-   * swallowed (logged) so `inFlight` always clears.
-   *
-   * @param {string} sessionId
-   * @param {CompactorHistoryHandle} historyHandle
-   */
-  async _runOnce(sessionId, historyHandle) {
-    try {
-      // Capture reference AND length. If a different code path swaps the
-      // array (`consolidate` event, session reset, manual clear) the
-      // reference will differ. If a driver path push-mutates new
-      // messages in place (e.g. `route_forward` triggering a new VP
-      // turn during compact), the reference is the same but the length
-      // grew. Both cases mean our snapshot is no longer canonical.
-      const snapshot = historyHandle.get();
-      if (!Array.isArray(snapshot) || snapshot.length === 0) return;
-      const snapshotLen = snapshot.length;
-
-      const maxContextTokens = this._getMaxContextTokens();
-      const tokenFraction = this._getTriggerRatio();
-
-      // Cheap O(n) precheck so we don't bother engaging the LLM at all
-      // when the conversation is still small. `compactHistory` runs the
-      // same check internally, but only after building the summarizer
-      // input — this keeps small chats off the LLM altogether.
-      //
-      // `tokenFraction` is the user-configurable ratio knob — production
-      // wiring (session.js) ALWAYS returns a finite (0,1) number defaulting
-      // to 0.7. The `undefined` branch (helper falls back to its
-      // `DEFAULT_TOKEN_FRACTION = 0.5`) is reachable only when a caller
-      // skips `getTriggerRatio` entirely — see constructor JSDoc.
-      const triage = shouldCompactHistory(snapshot, { maxContextTokens, tokenFraction });
-      if (!triage.trigger) return;
-
-      const summarize = ({ system, prompt }) =>
-        this._summarize({ system, prompt, maxTokens: SUMMARIZER_MAX_TOKENS });
-
-      const result = await compactHistory(snapshot, {
-        summarize,
-        maxContextTokens,
-        tokenFraction,
-        language: this._getLanguage(),
-      });
-      if (!result || !result.compacted) {
-        if (result && result.error) {
-          console.warn(
-            `[Yeaft] history compact: summarizer failed (${result.error}); ` +
-            `keeping ${result.beforeTurns} turns / ~${result.beforeTokens} tokens`
-          );
-        }
-        return;
-      }
-
-      // Race guard: if the group's history was reassigned during the
-      // await (e.g. consolidate / reset), or push-mutated by a driver
-      // path, do NOT overwrite the fresh state with our stale compacted
-      // snapshot. These discards are EXPECTED during normal session
-      // resets / route_forward bursts — log at debug, not info.
-      const current = historyHandle.get();
-      if (current !== snapshot) {
-        console.debug('[Yeaft] history compact: history was reset during compact — discarding stale summary');
-        return;
-      }
-      if (current.length !== snapshotLen) {
-        console.debug('[Yeaft] history compact: history was appended-to during compact — discarding stale summary');
-        return;
-      }
-
-      historyHandle.set(result.messages);
-      console.log(
-        `[Yeaft] history compacted (reason=${result.reason}): ` +
-        `turns ${result.beforeTurns}→${result.afterTurns}, ` +
-        `tokens ~${result.beforeTokens}→${result.afterTokens}, ` +
-        `archived ${result.archivedCount} messages`
-      );
-
-      try {
-        this._onCompacted(sessionId, {
-          reason: result.reason,
-          beforeTurns: result.beforeTurns,
-          afterTurns: result.afterTurns,
-          beforeTokens: result.beforeTokens,
-          afterTokens: result.afterTokens,
-          archivedCount: result.archivedCount,
-        });
-      } catch { /* sink failure must not abort the orchestrator */ }
-    } catch (err) {
-      console.warn(`[Yeaft] history compact: unexpected failure (sessionId=${sessionId})`, err?.message || err);
-    }
-  }
-
-  /** Test-only: clear all per-group state. */
-  __testReset() {
-    this._states.clear();
-  }
-}

package/yeaft/compact/orchestrator.js

@@ -1,141 +0,0 @@
-/**
- * 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';
-
-/**
- * @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, 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 — task summary refresh: removed. The legacy `feature/<id>` root
-  // scope was dropped along with the Feature system (2026-05-13); under the
-  // group-isolated layout feature summaries would live at
-  // `group/<g>/feature/<id>/` and are written by dream, not by post-turn
-  // compact. Engine no longer passes `taskId`/`root` to this orchestrator.
-  const taskSummaryRefreshed = false;
-
-  // 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/yeaft/compact/partition.js

@@ -1,94 +0,0 @@
-/**
- * compact/partition.js — Hot-window budget partitioning utilities.
- *
- * (Renamed from `agent/yeaft/memory/consolidate.js` on 2026-06-09.) The
- * legacy "consolidate" name and the `memory/` location both pointed at
- * a single concept — Layer-A memory consolidation — that has since been
- * cleanly split:
- *
- *   - Memory consolidation / system-prompt maintenance is owned by
- *     Dream V2 (per-group diff -> triage -> merge by target scope ->
- *     apply via segment-store + summary-store). NONE of that lives here.
- *
- *   - Conversation history compaction (the thing this file ACTUALLY
- *     serves) is owned by `compact/orchestrator.js`. The two functions
- *     below — `shouldCompact` (the "hot window over budget?" predicate
- *     that gates `compact/orchestrator.js`) and `partitionMessages`
- *     (hot/cold split by token budget) are pure helpers for that
- *     orchestrator.
- *
- * Why the move matters: keeping these under `memory/` invited the next
- * person to think "this is part of the memory subsystem" and reach for
- * it during a Dream-v2 patch — the exact category error
- * `DESIGN-COMPACT-VS-DREAM.md` (sibling doc) warns against. Putting
- * them next to `compact/orchestrator.js` makes the ownership obvious
- * from the file tree.
- */
-
-// ─── Constants ──────────────────────────────────────────────────
-
-/** Default MESSAGE_TOKEN_BUDGET for hot message compaction. */
-export const DEFAULT_MESSAGE_TOKEN_BUDGET = 32768;
-
-/** After compact, keep this fraction of the budget. */
-export const COMPACT_KEEP_RATIO = 0.4;
-
-/** Minimum messages to keep hot (newest). */
-const MIN_KEEP_MESSAGES = 3;
-
-/**
- * Check if a compact pass should be triggered.
- *
- * Semantically: "is the hot window over budget?" — the predicate that
- * gates `compact/orchestrator.js`. Renamed from `shouldConsolidate` on
- * 2026-06-09; the old name leaked Dream V2's vocabulary into a file
- * that exclusively serves Compact.
- *
- * @param {import('../conversation/persist.js').ConversationStore} conversationStore
- * @param {number} [budget] — MESSAGE_TOKEN_BUDGET
- * @returns {boolean}
- */
-export function shouldCompact(conversationStore, budget = DEFAULT_MESSAGE_TOKEN_BUDGET) {
-  const hotTokens = conversationStore.hotTokens();
-  return hotTokens > budget;
-}
-
-/**
- * Determine which messages to archive (move to cold).
- * Strategy: from oldest, accumulate tokens until remaining ≤ budget * 40%.
- * Always keep at least MIN_KEEP_MESSAGES.
- *
- * @param {object[]} messages — all hot messages, sorted chronologically
- * @param {number} budget — MESSAGE_TOKEN_BUDGET
- * @returns {{ toArchive: object[], toKeep: object[] }}
- */
-export function partitionMessages(messages, budget = DEFAULT_MESSAGE_TOKEN_BUDGET) {
-  if (messages.length <= MIN_KEEP_MESSAGES) {
-    return { toArchive: [], toKeep: messages };
-  }
-
-  const keepBudget = Math.floor(budget * COMPACT_KEEP_RATIO);
-
-  // Work backwards from newest: accumulate tokens until we hit keepBudget
-  let keepTokens = 0;
-  let keepStart = messages.length;
-
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msgTokens = messages[i].tokens_est || 0;
-    if (keepTokens + msgTokens > keepBudget && (messages.length - i) >= MIN_KEEP_MESSAGES) {
-      keepStart = i + 1;
-      break;
-    }
-    keepTokens += msgTokens;
-    if (i === 0) keepStart = 0;
-  }
-
-  // Ensure at least MIN_KEEP_MESSAGES are kept
-  keepStart = Math.min(keepStart, messages.length - MIN_KEEP_MESSAGES);
-  keepStart = Math.max(keepStart, 0);
-
-  return {
-    toArchive: messages.slice(0, keepStart),
-    toKeep: messages.slice(keepStart),
-  };
-}

package/yeaft/compact/triggers.js

@@ -1,54 +0,0 @@
-/**
- * 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/yeaft/compact/turn-group.js

@@ -1,85 +0,0 @@
-/**
- * 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;
-}