@yeaft/webchat-agent 0.1.688 → 0.1.689

package/package.json

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

package/unify/cli.js

@@ -212,8 +212,11 @@ async function runREPL(config, args) {
 
   const { engine, conversationStore, trace, skillManager, mcpManager, toolRegistry } = session;
 
-  // Load persisted conversation as initial messages
-  let conversationMessages = conversationStore.loadRecent(50).map(m => ({
+  // Load persisted conversation as initial messages. `loadRecent` is now
+  // turn-based (one user round-trip = one turn; multi-VP fan-out collapses
+  // into one turn). 20 turns is the bootstrap window — the engine-level
+  // compactor in `history-compact.js` is the authoritative size limiter.
+  let conversationMessages = conversationStore.loadRecent().map(m => ({
     role: m.role,
     content: m.content,
     ...(m.toolCallId && { toolCallId: m.toolCallId }),

package/unify/conversation/persist.js

@@ -21,6 +21,25 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, renameSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
 import { isPermissionError } from '../init.js';
+import { pairSanitize } from '../pair-sanitize.js';
+import { sliceLastNTurns } from '../turn-utils.js';
+
+/**
+ * Default cold-start "recent window" size, expressed in TURNS (not raw
+ * messages). One turn = one user prompt round-trip; multi-VP fan-out
+ * collapses N `@vp-X` variants of the same canonical prompt into ONE turn.
+ *
+ * Why turns and not messages: message-count slicing can cut mid-arc and
+ * orphan a `[assistant(toolCalls), tool…]` pair, which 400s the Anthropic /
+ * Chat-Completions adapter. Turn-based slicing always cuts at a user-
+ * message boundary, which is pair-safe by construction.
+ *
+ * 20 turns is the bootstrap window the user signed off on (2026-05-01).
+ * The session-level compactor in `history-compact.js` is the authoritative
+ * size limiter once the engine is running; this is just the cold-start
+ * replay window after a fresh boot or reconnect.
+ */
+export const DEFAULT_RECENT_TURNS = 20;
 
 // ─── Token estimation ────────────────────────────────────────
 
@@ -424,13 +443,29 @@ export class ConversationStore {
   // ─── Read API ───────────────────────────────────────────
 
   /**
-   * Load recent hot messages, sorted by id (chronological).
+   * Load recent hot messages, sliced to the last `turnsLimit` TURNS and
+   * sorted chronologically.
+   *
+   * Turn-based (not message-based) slicing is the contract here. A "turn"
+   * is one user-prompt round-trip — multi-VP fan-out emits N user
+   * messages for the same prompt, all of which collapse into ONE turn.
+   * `sliceLastNTurns` cuts at a user-message boundary, so an
+   * `[assistant(toolCalls), tool…]` arc is never split across the cut.
    *
-   * @param {number} [limit=50] — max messages to load
+   * `pairSanitize` runs as a defensive secondary pass — turn-boundary
+   * cuts are already pair-safe, but historical / hand-edited stores may
+   * contain orphans, and `pairSanitize` is idempotent.
+   *
+   * Back-compat: callers that pass `Infinity` (or a negative number) get
+   * the full hot history. `0` returns `[]`.
+   *
+   * @param {number} [turnsLimit=DEFAULT_RECENT_TURNS] — max turns to load
    * @returns {object[]} — parsed message objects
    */
-  loadRecent(limit = 50) {
-    return this.#loadFromDir(this.#msgDir, limit);
+  loadRecent(turnsLimit = DEFAULT_RECENT_TURNS) {
+    const all = this.#loadFromDir(this.#msgDir, Infinity);
+    if (turnsLimit === Infinity || turnsLimit < 0) return pairSanitize(all);
+    return pairSanitize(sliceLastNTurns(all, turnsLimit));
   }
 
   /**
@@ -443,29 +478,43 @@ export class ConversationStore {
   }
 
   /**
-   * Load recent hot messages stamped with `groupId`, sorted chronologically.
-   * Group-history-isolation (Bug 7): a message lives in exactly one group.
-   * Messages without a `groupId` frontmatter (legacy / pre-grouping) are
-   * NOT returned — they would otherwise leak into every group's stream.
+   * Load recent hot messages stamped with `groupId`, sliced to the last
+   * `turnsLimit` TURNS and sorted chronologically.
+   *
+   * Group-history-isolation (Bug 7): a message lives in exactly one
+   * group. Messages without a `groupId` frontmatter (legacy / pre-
+   * grouping) are NOT returned — they would otherwise leak into every
+   * group's stream.
+   *
+   * Turn-based slicing (2026-05-01): we used to take the last N
+   * messages, which can land mid-arc and orphan a tool_use/tool_result
+   * pair (the Anthropic / Chat-Completions adapter then 400s on the
+   * orphan). Switching to `sliceLastNTurns` always cuts at a user-
+   * message boundary — multi-VP `@vp-X` variants of the same canonical
+   * prompt collapse into ONE turn, so a fan-out turn is kept whole.
+   *
+   * `pairSanitize` runs as a belt-and-suspenders second pass: turn-
+   * boundary cuts are pair-safe by construction, but if a hand-edited
+   * store somehow contains pre-existing orphans we drop them anyway.
    *
-   * Implementation note: filters AFTER reading the most recent N files
+   * Implementation note: filters AFTER reading the most recent files
    * because the on-disk order is global by sequence id. We over-read by
-   * loading all hot files and slicing the tail of the filtered set so
-   * `limit` reflects "N most recent messages in this group", not "N most
-   * recent messages on disk that happen to be in this group". For typical
-   * inboxes (≤ a few thousand hot messages) this is cheap; if it ever
-   * becomes a hot path we add a per-group on-disk index.
+   * loading every hot file and slicing the tail of the FILTERED set so
+   * `turnsLimit` reflects "N most recent turns in this group", not "N
+   * most recent messages on disk that happen to be in this group". For
+   * typical inboxes (≤ a few thousand hot messages) this is cheap; if
+   * it ever becomes a hot path we add a per-group on-disk index.
    *
    * @param {string} groupId — required; null/empty returns []
-   * @param {number} [limit=50]
+   * @param {number} [turnsLimit=DEFAULT_RECENT_TURNS]
    * @returns {object[]}
    */
-  loadRecentByGroup(groupId, limit = 50) {
+  loadRecentByGroup(groupId, turnsLimit = DEFAULT_RECENT_TURNS) {
     if (!groupId) return [];
     const all = this.#loadFromDir(this.#msgDir, Infinity);
     const filtered = all.filter(m => m && m.groupId === groupId);
-    if (limit === Infinity || limit < 0) return filtered;
-    return filtered.slice(-limit);
+    if (turnsLimit === Infinity || turnsLimit < 0) return pairSanitize(filtered);
+    return pairSanitize(sliceLastNTurns(filtered, turnsLimit));
   }
 
   /**

package/unify/history-compact.js

@@ -26,12 +26,19 @@
  *   4. Keep the last `keepRecent` user→assistant turns intact so the model
  *      has fresh, untransformed context for whatever the user just said.
  *
- * Triggers (either fires):
- *   - turn count > 20  (each user message in `conversationMessages` is a turn)
- *   - estimated tokens > 80,000
+ * Triggers (any fires, but only above a 30K token soft floor):
+ *   - tokens < 30_000 → never compact (cheap chat, no point paying
+ *     the summarizer)
+ *   - tokens > 40 % of `maxContextTokens` (defaults to 200K → 80K)
+ *   - tokens > 200,000 hard ceiling
  *
- * Defaults match the user-stated requirement; both are overridable via the
- * options bag for tests / future config plumbing.
+ * The "turn > 20" trigger that an earlier revision used was dropped:
+ * under a 30K token floor it's effectively dead code — the fractional
+ * threshold fires first in any conversation big enough to matter.
+ *
+ * Defaults are derived from `maxContextTokens` so the policy auto-adjusts
+ * when the user widens or narrows their context budget. All knobs are
+ * overridable via the options bag for tests / future config plumbing.
  *
  * Why role='user' for the summary message:
  *   The Anthropic Messages API rejects assistant prefill at the tail
@@ -44,13 +51,53 @@
  */
 
 import { estimateTokens } from './conversation/persist.js';
+import { pairSanitize } from './pair-sanitize.js';
+import {
+  countTurns as countTurnsImpl,
+  indexOfNthTurnFromEnd,
+} from './turn-utils.js';
+
+/**
+ * Re-export `countTurns` so existing callers / tests that import it
+ * from this module continue to work. Implementation now lives in
+ * `turn-utils.js` and is shared with `ConversationStore`.
+ */
+export const countTurns = countTurnsImpl;
 
 /**
- * Default trigger thresholds — match the user's stated policy:
- *   "如果 turn 超过 20 或者 message 上下文超过 80K，那么就 compact"
+ * Default trigger thresholds (2026-05-01 policy update):
+ *   - never compact while total tokens < 30K (soft floor — most
+ *     conversations under that aren't worth paying the summarizer
+ *     cost; the LLM hasn't started feeling the context yet either),
+ *   - otherwise compact if ANY of:
+ *       tokens > 40 % of `maxContextTokens` (default 200K → 80K)
+ *       tokens > 200K hard ceiling
+ *
+ * The earlier "turn count > 20" trigger was DROPPED because under
+ * the new floor it's effectively dead code — by the time you've sent
+ * 20 user prompts that exceed 30K tokens, the fractional threshold
+ * has already fired. `turnLimit` and the `turn_count` reason code
+ * are still accepted as overrides so tests / future config can re-
+ * enable a turn-based trigger if needed; with `turnLimit: Infinity`
+ * (the new default) the check is simply skipped.
+ *
+ * Token thresholds are derived from `maxContextTokens` at evaluation
+ * time so the policy auto-adjusts to the user's configured context.
+ */
+export const DEFAULT_TURN_LIMIT = Infinity;
+export const DEFAULT_MIN_TOKEN_FLOOR = 30_000;
+export const DEFAULT_MAX_CONTEXT_TOKENS = 200_000;
+export const DEFAULT_TOKEN_FRACTION = 0.4;
+export const DEFAULT_HARD_TOKEN_CEILING = 200_000;
+/**
+ * Effective default token trigger when no `maxContextTokens` is provided:
+ *   min(40% of 200K, 200K) = 80K. Preserved as `DEFAULT_TOKEN_LIMIT` for
+ *   back-compat with existing tests that import this name.
  */
-export const DEFAULT_TURN_LIMIT = 20;
-export const DEFAULT_TOKEN_LIMIT = 80_000;
+export const DEFAULT_TOKEN_LIMIT = Math.min(
+  Math.floor(DEFAULT_MAX_CONTEXT_TOKENS * DEFAULT_TOKEN_FRACTION),
+  DEFAULT_HARD_TOKEN_CEILING
+);
 
 /**
  * How many user→assistant pairs to leave intact at the tail. The summary
@@ -97,71 +144,67 @@ export function estimateMessagesTokens(messages) {
   return total;
 }
 
-/**
- * Strip a leading `@vp-<id> ` mention prefix from a user prompt. The
- * web bridge prefixes each VP's per-turn prompt with `@vp-<id> ` so
- * the engine knows which VP is replying. When counting "turns" we
- * want the user-facing notion of a turn (one round-trip), not one per
- * VP — so we strip the prefix before deduping consecutive identical
- * user messages.
- *
- * Format mirrors `web-bridge.js#runVpTurn`:
- *   `@vp-${vpId} ${text}`
- *
- * @param {string} content
- * @returns {string}
- */
-function stripVpMentionPrefix(content) {
-  if (typeof content !== 'string') return '';
-  return content.replace(/^@vp-[^\s]+\s+/, '');
-}
-
-/**
- * Count "turns" — defined as a user-side round-trip, NOT one per
- * user-role message. Multi-VP fan-out appends one user message per VP
- * (each with an `@vp-<id>` prefix) for the same underlying user prompt;
- * those collapse into a single turn here.
- *
- * Algorithm: walk user-role messages, strip the `@vp-` prefix, count
- * a turn whenever the canonical text changes from the previous user
- * message (or it's the first one).
- *
- * @param {Array<object>} messages
- * @returns {number}
- */
-export function countTurns(messages) {
-  if (!Array.isArray(messages)) return 0;
-  let n = 0;
-  let prev = null;
-  for (const m of messages) {
-    if (!m || m.role !== 'user') continue;
-    const canonical = stripVpMentionPrefix(m.content || '');
-    if (canonical !== prev) {
-      n++;
-      prev = canonical;
-    }
-  }
-  return n;
-}
-
 /**
  * Pure trigger evaluator. Decides whether the in-memory history needs
  * compaction. No I/O, no LLM call.
  *
+ * Policy (2026-05-01):
+ *   1. tokens < `minTokenFloor` (default 30K) → trigger=false (always).
+ *   2. otherwise trigger if ANY of:
+ *        turnCount > turnLimit (default Infinity → effectively off;
+ *           callers can pin a number to re-enable a turn-count trigger)
+ *        tokenCount > maxContextTokens*fraction (reason='token_threshold')
+ *        tokenCount > hardTokenCeiling          (reason='token_ceiling')
+ *
+ * `tokenLimit` is preserved as a back-compat override for callers /
+ * tests that pin a specific number; when set, it overrides the
+ * fraction-of-context calculation.
+ *
  * @param {Array<object>} messages
- * @param {{turnLimit?: number, tokenLimit?: number}} [opts]
- * @returns {{trigger: boolean, reason: 'turn_count'|'token_threshold'|null,
+ * @param {{
+ *   turnLimit?: number,
+ *   tokenLimit?: number,
+ *   minTokenFloor?: number,
+ *   maxContextTokens?: number,
+ *   tokenFraction?: number,
+ *   hardTokenCeiling?: number,
+ * }} [opts]
+ * @returns {{trigger: boolean, reason: 'turn_count'|'token_threshold'|'token_ceiling'|null,
  *            turnCount: number, tokenCount: number,
- *            turnLimit: number, tokenLimit: number}}
+ *            turnLimit: number, tokenLimit: number,
+ *            minTokenFloor: number, hardTokenCeiling: number}}
  */
 export function shouldCompactHistory(messages, opts = {}) {
   const turnLimit = opts.turnLimit ?? DEFAULT_TURN_LIMIT;
-  const tokenLimit = opts.tokenLimit ?? DEFAULT_TOKEN_LIMIT;
+  const minTokenFloor = opts.minTokenFloor ?? DEFAULT_MIN_TOKEN_FLOOR;
+  const hardTokenCeiling = opts.hardTokenCeiling ?? DEFAULT_HARD_TOKEN_CEILING;
+  const maxContextTokens = opts.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
+  const tokenFraction = opts.tokenFraction ?? DEFAULT_TOKEN_FRACTION;
+  // tokenLimit override wins; otherwise compute fractional threshold.
+  const tokenLimit =
+    opts.tokenLimit
+    ?? Math.min(Math.floor(maxContextTokens * tokenFraction), hardTokenCeiling);
+
   const turnCount = countTurns(messages);
   const tokenCount = estimateMessagesTokens(messages);
 
   let reason = null;
-  if (turnCount > turnLimit) reason = 'turn_count';
+  // (1) Soft floor: never compact small conversations.
+  if (tokenCount < minTokenFloor) {
+    return {
+      trigger: false,
+      reason: null,
+      turnCount,
+      tokenCount,
+      turnLimit,
+      tokenLimit,
+      minTokenFloor,
+      hardTokenCeiling,
+    };
+  }
+  // (2) Trigger evaluation. Turn check is opt-in (Infinity by default).
+  if (Number.isFinite(turnLimit) && turnCount > turnLimit) reason = 'turn_count';
+  else if (tokenCount > hardTokenCeiling) reason = 'token_ceiling';
   else if (tokenCount > tokenLimit) reason = 'token_threshold';
 
   return {
@@ -171,6 +214,8 @@ export function shouldCompactHistory(messages, opts = {}) {
     tokenCount,
     turnLimit,
     tokenLimit,
+    minTokenFloor,
+    hardTokenCeiling,
   };
 }
 
@@ -219,13 +264,14 @@ export function buildSummarizerInput(messages) {
  * intact, fold everything before. Returns the index that the cut starts
  * AT, i.e. messages[0..cutIdx) gets summarised, messages[cutIdx..] stays.
  *
- * Strategy: walks user-role messages from the END backwards, counting
- * DISTINCT turns by canonical text (after stripping `@vp-<id>` prefix
- * via `stripVpMentionPrefix`). Multi-VP fan-out variants of the same
- * underlying turn collapse into one turn — and the candidate cut index
- * is extended backwards through them so all `@vp-X` variants of the
- * kept turn stay together. If there aren't enough turns to fold (history
- * shorter than keepRecent), returns -1 (caller treats as no-op).
+ * Thin wrapper around `turn-utils.indexOfNthTurnFromEnd` with the
+ * historical contract preserved:
+ *   - empty input returns -1,
+ *   - `keepRecent <= 0` folds everything (returns messages.length),
+ *   - "fewer turns than keepRecent" maps to -1 (caller treats as no-op).
+ *
+ * Multi-VP fan-out: `@vp-X` variants of the same underlying turn count
+ * as ONE turn and the boundary extends backwards through them all.
  *
  * @param {Array<object>} messages
  * @param {number} keepRecent
@@ -234,42 +280,10 @@ export function buildSummarizerInput(messages) {
 export function findCutIndex(messages, keepRecent) {
   if (!Array.isArray(messages) || messages.length === 0) return -1;
   if (keepRecent <= 0) return messages.length; // fold everything
-
-  // Walk from the end, counting DISTINCT turns (multiple consecutive
-  // user messages with the same canonical text — i.e. one fan-out's
-  // @vp-X variants — collapse into a single turn). Stop when we've
-  // started the (keepRecent)-th turn from the end; everything before
-  // its first user-message gets folded.
-  let turnsFromEnd = 0;
-  let nextCanonical = null; // canonical text of the turn we just opened
-  let candidateIdx = -1;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    if (!messages[i] || messages[i].role !== 'user') continue;
-    const canonical = stripVpMentionPrefix(messages[i].content || '');
-    if (canonical !== nextCanonical) {
-      // New (older) turn boundary.
-      turnsFromEnd++;
-      nextCanonical = canonical;
-      if (turnsFromEnd === keepRecent) {
-        candidateIdx = i;
-        // Keep walking — the same turn might extend further back via
-        // earlier @vp variants of the same canonical text.
-        continue;
-      }
-      if (turnsFromEnd > keepRecent) {
-        // We've stepped into the (keepRecent+1)-th turn — stop. The
-        // last recorded `candidateIdx` is the start of the LAST
-        // keepRecent block.
-        break;
-      }
-    } else if (turnsFromEnd === keepRecent) {
-      // Same canonical text as the keepRecent-th-from-end turn — this
-      // is an earlier @vp-variant of that same turn. Extend candidate
-      // backwards to include it.
-      candidateIdx = i;
-    }
-  }
-  return candidateIdx;
+  const idx = indexOfNthTurnFromEnd(messages, keepRecent);
+  // `indexOfNthTurnFromEnd` returns -1 when there are fewer turns than
+  // requested — historical contract is the same. Pass through.
+  return idx;
 }
 
 /**
@@ -331,6 +345,10 @@ export function buildSummaryPrompt(cleanedMessages) {
  *   keepRecent?: number,
  *   turnLimit?: number,
  *   tokenLimit?: number,
+ *   minTokenFloor?: number,
+ *   maxContextTokens?: number,
+ *   tokenFraction?: number,
+ *   hardTokenCeiling?: number,
  * }} options
  * @returns {Promise<{
  *   messages: Array<object>,
@@ -348,15 +366,29 @@ export async function compactHistory(messages, options) {
   const {
     summarize,
     keepRecent = DEFAULT_KEEP_RECENT_TURNS,
-    turnLimit = DEFAULT_TURN_LIMIT,
-    tokenLimit = DEFAULT_TOKEN_LIMIT,
+    turnLimit,
+    tokenLimit,
+    minTokenFloor,
+    maxContextTokens,
+    tokenFraction,
+    hardTokenCeiling,
   } = options || {};
 
   if (typeof summarize !== 'function') {
     throw new TypeError('compactHistory: options.summarize must be a function');
   }
 
-  const before = shouldCompactHistory(messages, { turnLimit, tokenLimit });
+  // Pass thresholds through to shouldCompactHistory so a single options
+  // bag controls the policy. Undefined keys fall back to module defaults.
+  const triggerOpts = {
+    turnLimit,
+    tokenLimit,
+    minTokenFloor,
+    maxContextTokens,
+    tokenFraction,
+    hardTokenCeiling,
+  };
+  const before = shouldCompactHistory(messages, triggerOpts);
   if (!before.trigger) {
     return {
       messages,
@@ -433,19 +465,17 @@ export async function compactHistory(messages, options) {
 
   const summaryMsg = wrapSummaryAsUserMessage(summaryText);
 
-  // Defensive: if the tail starts with a `role: 'tool'` message, the
-  // adapter will reject it (tool messages must follow an assistant with
-  // a matching tool_call). Drop leading tool messages from the tail —
-  // their preceding assistant has been folded into the summary, so the
-  // tool result is orphaned anyway.
-  let tailStart = 0;
-  while (tailStart < tail.length && tail[tailStart] && tail[tailStart].role === 'tool') {
-    tailStart++;
-  }
-  const safeTail = tail.slice(tailStart);
+  // Defensive pair-sanitize: the cut at `cutIdx` lands at a user-message
+  // boundary so an `[assistant(toolCalls), tool…]` arc is not split, but
+  // we still run `pairSanitize` over the tail as belt-and-suspenders —
+  // it idempotently drops any orphan tool messages, and any assistant
+  // whose tool_use IDs aren't fully matched in the tail. This is what
+  // keeps the next adapter call from 400-ing on tool_use/tool_result
+  // mismatch when the storage / fan-out layer reorders messages.
+  const safeTail = pairSanitize(tail);
 
   const newMessages = [summaryMsg, ...safeTail];
-  const after = shouldCompactHistory(newMessages, { turnLimit, tokenLimit });
+  const after = shouldCompactHistory(newMessages, triggerOpts);
 
   return {
     messages: newMessages,

package/unify/pair-sanitize.js

@@ -0,0 +1,143 @@
+/**
+ * pair-sanitize.js — Drop tool_use / tool_result orphans from a message
+ * slice so it can be safely fed to the LLM adapter.
+ *
+ * Why this exists:
+ *   `agent/unify/conversation/persist.js#loadRecentByGroup` and
+ *   `agent/unify/history-compact.js#compactHistory` both produce
+ *   sub-slices of a longer message stream. Both paths can — depending on
+ *   where the cut lands — produce one of two illegal shapes:
+ *     1. A `role: 'tool'` message whose owning assistant `tool_use` is
+ *        no longer in the slice.
+ *     2. An `assistant` message whose `toolCalls[i].id` has no matching
+ *        `role: 'tool'` follow-up inside the slice.
+ *   The Anthropic Messages API and the Chat-Completions adapter both
+ *   400 on either shape ("`tool_use` blocks must be paired with
+ *   `tool_result` blocks").
+ *
+ * Strategy (Strategy B from the design doc):
+ *   Drop orphans rather than extending the slice backwards. Concretely:
+ *
+ *     - Walk forward. For each `role: 'assistant'` message with
+ *       `toolCalls`, look ahead at the contiguous run of `role: 'tool'`
+ *       messages (or, in this codebase's flat array form, all `tool`
+ *       messages between this assistant and the next assistant/user)
+ *       and collect the set of `toolCallId`s that are present.
+ *     - Filter the assistant's `toolCalls` to that set. If the result
+ *       is empty AND the assistant has no text content, drop the
+ *       assistant. Otherwise keep it with the surviving subset (which
+ *       may be empty `toolCalls: []` if it had text).
+ *     - Drop any `role: 'tool'` whose `toolCallId` is not in the
+ *       surviving set of any preceding assistant in the slice.
+ *
+ * The transform is idempotent: running it twice produces the same
+ * result as running it once. It does not mutate the input.
+ *
+ * It's deliberately tolerant of "weird" inputs — null entries, missing
+ * fields, leading orphan tools (which become outright drops) — because
+ * the call sites already see all of those.
+ */
+
+/**
+ * @typedef {Object} UnifiedMessage
+ * @property {string} role           - 'user' | 'assistant' | 'tool' | 'system'
+ * @property {string} [content]
+ * @property {Array<{id: string, name?: string, input?: any}>} [toolCalls]
+ * @property {string} [toolCallId]   - present on role:'tool'
+ * @property {boolean} [isError]
+ */
+
+/**
+ * Sanitize a message slice so every `tool_use` is paired with its
+ * `tool_result` and vice versa. Returns a new array; never mutates input.
+ *
+ * @param {UnifiedMessage[]} messages
+ * @returns {UnifiedMessage[]}
+ */
+export function pairSanitize(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return [];
+
+  // Pass 1: collect every toolCallId that has a matching `role:'tool'`
+  // message somewhere in the slice. (Pairing is positional, but for
+  // the orphan-drop policy a global presence check is sufficient — and
+  // it tolerates reorderings that the storage layer occasionally does
+  // when sequence ids cross seconds-boundaries.)
+  const toolResultIds = new Set();
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue;
+    if (m.role === 'tool' && typeof m.toolCallId === 'string' && m.toolCallId) {
+      toolResultIds.add(m.toolCallId);
+    }
+  }
+
+  // Pass 2: walk messages, filter assistant.toolCalls down to those
+  // whose result is in the slice, and track which call-ids survived.
+  // A `role:'tool'` is kept iff its toolCallId is in survivingCallIds.
+  const survivingCallIds = new Set();
+  const out = [];
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') {
+      // Pass through non-object junk so callers that intentionally
+      // include sentinels don't lose them. (Practically never happens.)
+      out.push(m);
+      continue;
+    }
+    if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+      const keptCalls = m.toolCalls.filter(tc =>
+        tc && typeof tc.id === 'string' && toolResultIds.has(tc.id)
+      );
+      const text = typeof m.content === 'string' ? m.content : '';
+      const hasText = text.trim().length > 0;
+      if (keptCalls.length === 0 && !hasText) {
+        // No text, all tool_uses orphaned → drop the message entirely.
+        // Anthropic / OpenAI both reject empty assistant turns anyway.
+        continue;
+      }
+      // Record surviving call ids so we keep their tool_result counterparts.
+      for (const tc of keptCalls) survivingCallIds.add(tc.id);
+      // Replace toolCalls with the filtered subset. Preserve other fields.
+      out.push({ ...m, toolCalls: keptCalls });
+      continue;
+    }
+    if (m.role === 'tool') {
+      if (typeof m.toolCallId !== 'string' || !m.toolCallId) {
+        // Tool message with no id — can't pair, drop it.
+        continue;
+      }
+      if (!survivingCallIds.has(m.toolCallId)) {
+        // Orphan tool_result: the assistant that called it isn't in the
+        // slice (or its tool_use was filtered out above).
+        continue;
+      }
+      out.push(m);
+      continue;
+    }
+    // user / system / assistant-without-toolCalls / unknown — keep as-is.
+    out.push(m);
+  }
+
+  return out;
+}
+
+/**
+ * Quick predicate: does this slice contain at least one orphan?
+ * Useful for tests and diagnostics. Pure function over `pairSanitize`.
+ *
+ * @param {UnifiedMessage[]} messages
+ * @returns {boolean}
+ */
+export function hasOrphanPairs(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return false;
+  const sanitized = pairSanitize(messages);
+  if (sanitized.length !== messages.length) return true;
+  // Same length but maybe an assistant's toolCalls shrank.
+  for (let i = 0; i < messages.length; i++) {
+    const a = messages[i];
+    const b = sanitized[i];
+    if (!a || !b) continue;
+    const aCalls = Array.isArray(a.toolCalls) ? a.toolCalls.length : 0;
+    const bCalls = Array.isArray(b.toolCalls) ? b.toolCalls.length : 0;
+    if (aCalls !== bCalls) return true;
+  }
+  return false;
+}

package/unify/turn-utils.js

@@ -0,0 +1,154 @@
+/**
+ * turn-utils.js — Turn-based slicing primitives for the Unify history.
+ *
+ * "Turn" = one user-side round-trip, NOT one user-role message.
+ * Multi-VP fan-out emits N user messages (each `@vp-<id> <text>`) for
+ * the SAME underlying prompt. They collapse into ONE turn here.
+ *
+ * Two concerns this module unifies:
+ *
+ *   1. `compact/turn-group.js` already does atomicity grouping —
+ *      `[user, assistant, tool…]` triples that must move as a unit
+ *      so we don't split tool_use/tool_result pairs. That's storage-
+ *      invariant work.
+ *
+ *   2. THIS module does turn IDENTITY — "is the next user-role message
+ *      the start of a new conversational turn, or is it just another
+ *      `@vp-X` variant of the previous one?" That's a higher-level
+ *      semantic concern.
+ *
+ * Both are needed. `sliceLastNTurns` cuts at a turn boundary AND walks
+ * forward to include all `@vp-X` variants of that turn so the result
+ * is always a pair-safe, semantically-aligned slice.
+ */
+
+/**
+ * Strip a leading `@vp-<id> ` mention prefix from a user prompt. The
+ * web bridge prefixes each VP's per-turn prompt with `@vp-<id> ` so
+ * the engine knows which VP is replying. When asking "are these the
+ * same turn?" we want the user-facing notion of a turn (one prompt
+ * fanned out to multiple VPs is one turn) — so we strip the prefix
+ * before comparing.
+ *
+ * Format mirrors `web-bridge.js#runVpTurn` (`@vp-${vpId} ${text}`)
+ * and the canonical vpId charset from `groups/ids.js#VP_ID_RE`
+ * (`[A-Za-z0-9_-]`). The regex here is intentionally constrained to
+ * that charset so a literal `@vp-` substring in a *user-typed* message
+ * (e.g. `"@vp-, fooled you"`, `"@vp-😀 hi"`) is NOT mistaken for a
+ * fan-out prefix and over-stripped.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stripVpMentionPrefix(content) {
+  if (typeof content !== 'string') return '';
+  return content.replace(/^@vp-[A-Za-z0-9_-]+\s+/, '');
+}
+
+/**
+ * Count "turns" — distinct user prompts after `@vp-X` collapsing.
+ *
+ * A turn is opened when we hit a user-role message whose canonical
+ * text differs from the previous user-role message. Two consecutive
+ * user-role messages with the same canonical text (i.e. `@vp-a foo`
+ * followed by `@vp-b foo`) count as ONE turn.
+ *
+ * @param {Array<object>} messages
+ * @returns {number}
+ */
+export function countTurns(messages) {
+  if (!Array.isArray(messages)) return 0;
+  let n = 0;
+  let prev = null;
+  for (const m of messages) {
+    if (!m || m.role !== 'user') continue;
+    const canonical = stripVpMentionPrefix(m.content || '');
+    if (canonical !== prev) {
+      n++;
+      prev = canonical;
+    }
+  }
+  return n;
+}
+
+/**
+ * Find the index of the message that opens the (n)-th-from-end turn.
+ * Returns -1 if there aren't n turns in the history.
+ *
+ * Algorithm (mirrors `history-compact.js#findCutIndex`):
+ *   - Walk user-role messages from END backwards, counting DISTINCT
+ *     turns by canonical text.
+ *   - When `turnsFromEnd === n`, record the index. Keep walking — the
+ *     same turn might extend further back through earlier `@vp-X`
+ *     variants. Stop on the FIRST user-role message whose canonical
+ *     text differs (i.e. the (n+1)-th-from-end turn).
+ *
+ * The returned index always points at a user-role message — the
+ * natural turn boundary — which means messages[idx..] is a clean
+ * `[user, ..., user, ...]` slice with no orphan tool_use / tool_result
+ * pairs (provided the input was clean).
+ *
+ * @param {Array<object>} messages
+ * @param {number} n  — 1 = "open the most recent turn"
+ * @returns {number}
+ */
+export function indexOfNthTurnFromEnd(messages, n) {
+  if (!Array.isArray(messages) || messages.length === 0) return -1;
+  if (n <= 0) return messages.length; // "0 turns from end" = past everything
+
+  let turnsFromEnd = 0;
+  let openCanonical = null;
+  let candidate = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (!messages[i] || messages[i].role !== 'user') continue;
+    const canonical = stripVpMentionPrefix(messages[i].content || '');
+    if (canonical !== openCanonical) {
+      // Boundary: a new (older) turn starts here.
+      turnsFromEnd++;
+      openCanonical = canonical;
+      if (turnsFromEnd === n) {
+        candidate = i;
+        // Don't break — earlier `@vp-X` variants of THIS turn may
+        // extend the boundary further back. We'll catch them via the
+        // `else if` branch below until we hit a different canonical.
+        continue;
+      }
+      if (turnsFromEnd > n) {
+        // We've stepped one turn past the kept window — done.
+        break;
+      }
+    } else if (turnsFromEnd === n) {
+      // Same canonical text as the kept boundary — this is an earlier
+      // `@vp-X` variant of the same turn. Pull `candidate` back to it.
+      candidate = i;
+    }
+  }
+  return candidate;
+}
+
+/**
+ * Return the suffix of `messages` containing the last `n` turns.
+ *
+ * Always cuts at a user-message boundary (the start of the (n)-th-from-
+ * end turn), so the returned slice is pair-safe with respect to
+ * `[assistant(toolCalls), tool…]` arcs that LIVE inside one of the
+ * kept turns. Anything before the boundary — including any leading
+ * non-user messages from a prior turn — is dropped.
+ *
+ * If the history has fewer than `n` turns, returns the whole array
+ * (caller can decide whether that's a no-op).
+ *
+ * @param {Array<object>} messages
+ * @param {number} n
+ * @returns {Array<object>}
+ */
+export function sliceLastNTurns(messages, n) {
+  if (!Array.isArray(messages) || messages.length === 0) return [];
+  if (n <= 0) return [];
+  const idx = indexOfNthTurnFromEnd(messages, n);
+  if (idx === -1) {
+    // Fewer than n turns — keep everything.
+    return messages.slice();
+  }
+  return messages.slice(idx);
+}

package/unify/web-bridge.js

@@ -1007,7 +1007,7 @@ async function ensureSessionLoaded() {
 
   unifyConversationId = `unify-${Date.now()}`;
 
-  restoreHistoryFromRecent(session.conversationStore.loadRecent(50));
+  restoreHistoryFromRecent(session.conversationStore.loadRecent());
 
   sendUnifyEvent({
     type: 'session_ready',
@@ -1217,8 +1217,16 @@ function scheduleCompactAfterTurn(groupId) {
     return;
   }
   // Cheap O(n) precheck so we don't bother engaging the LLM at all
-  // when the conversation is still small.
-  const triage = shouldCompactHistory(conversationMessages);
+  // when the conversation is still small. Mirrors the policy that
+  // `runCompactNow` will apply: 30K soft floor / 40 % of configured
+  // context / 200K hard ceiling. (The turn-count trigger is off by
+  // default — DEFAULT_TURN_LIMIT=Infinity — pin `turnLimit` via opts
+  // to re-enable it.)
+  const maxContextTokens =
+    typeof session?.config?.maxContextTokens === 'number'
+      ? session.config.maxContextTokens
+      : undefined;
+  const triage = shouldCompactHistory(conversationMessages, { maxContextTokens });
   if (!triage.trigger) return;
   if (!session?.engine || typeof session.engine.summarizeForCompact !== 'function') {
     console.warn('[Unify] history compact: engine.summarizeForCompact unavailable — skipping');
@@ -1269,8 +1277,16 @@ async function runCompactNow(groupId) {
   // and we abandon the swap.
   const snapshot = conversationMessages;
 
+  // Pull the user-configured context width so the 40 %-of-context
+  // threshold auto-adjusts to whatever model they're on. Falls back to
+  // the module default when missing.
+  const maxContextTokens =
+    typeof session?.config?.maxContextTokens === 'number'
+      ? session.config.maxContextTokens
+      : undefined;
+
   try {
-    const result = await compactHistory(snapshot, { summarize });
+    const result = await compactHistory(snapshot, { summarize, maxContextTokens });
     if (!result.compacted) {
       if (result.error) {
         console.warn(
@@ -1613,6 +1629,10 @@ export function handleUnifyModelSwitch(msg) {
  */
 export async function handleUnifyLoadHistory(msg) {
   const groupId = (msg && typeof msg.groupId === 'string' && msg.groupId) || null;
+  // `lim` is now expressed in TURNS, not raw messages. `loadRecent` and
+  // `loadRecentByGroup` use turn-based slicing so the cut never lands
+  // mid-tool-arc. Pass `undefined` to use the persistence-layer default
+  // (DEFAULT_RECENT_TURNS = 20 turns).
   const pickRecent = (store, lim) =>
     groupId ? store.loadRecentByGroup(groupId, lim) : store.loadRecent(lim);
 
@@ -1627,12 +1647,12 @@ export async function handleUnifyLoadHistory(msg) {
 
     unifyConversationId = `unify-${Date.now()}`;
 
-    restoreHistoryFromRecent(pickRecent(session.conversationStore, 50));
+    restoreHistoryFromRecent(pickRecent(session.conversationStore, undefined));
   } else if (groupId) {
     // Re-entering an existing session with a (possibly new) group filter:
     // re-seed the engine's flat history so it doesn't carry messages from
     // another group into the next turn's context.
-    restoreHistoryFromRecent(pickRecent(session.conversationStore, 50));
+    restoreHistoryFromRecent(pickRecent(session.conversationStore, undefined));
   }
 
   // Always replay session_ready so refresh / reconnect rebuilds UI state.
@@ -1647,6 +1667,11 @@ export async function handleUnifyLoadHistory(msg) {
   });
   sendGroupSnapshotBroadcast();
 
+  // `msg.limit` is the replay-scrollback request from the frontend (UI
+  // history pane, not engine context). Semantics changed (2026-05-01):
+  // now expressed in TURNS. The previous default (50 messages) maps to
+  // ~20–25 turns; in the turn-count world 50 turns of UI scrollback is
+  // still cheap and matches what the frontend already passes through.
   const limit = (typeof msg.limit === 'number') ? msg.limit : 50;
   const messages = limit > 0 ? pickRecent(session.conversationStore, limit) : [];
   const compactSummary = session.conversationStore.readCompactSummary();
@@ -1704,7 +1729,7 @@ export async function resetUnifySession() {
 
     unifyConversationId = `unify-${Date.now()}`;
 
-    restoreHistoryFromRecent(session.conversationStore.loadRecent(50));
+    restoreHistoryFromRecent(session.conversationStore.loadRecent());
 
     sendUnifyEvent({
       type: 'session_ready',