@yeaft/webchat-agent 0.1.684 → 0.1.686

package/package.json

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

package/unify/engine.js

@@ -1028,6 +1028,43 @@ export class Engine {
     let t1Fired = false;
     const queryNumber = (this.#__queryCounter = (this.#__queryCounter || 0) + 1);
 
+    // feat-6af5f9f1 PR B: a Turn = one user prompt + all AI responses.
+    // `queryTurnId` is the wire-level turn identifier; every event emitted
+    // during this query() carries it as `turnId`. Each LLM call inside
+    // the loop is a `loopNumber` (was wire field `turnNumber`).
+    const queryTurnId = randomUUID();
+    const queryStartedAt = Date.now();
+    const userQuestionPreview = String(prompt || '').slice(0, 200);
+    const queryVpId = vpPersona && typeof vpPersona === 'object'
+      && typeof vpPersona.vpId === 'string'
+      ? vpPersona.vpId
+      : (typeof senderVpId === 'string' ? senderVpId : null);
+
+    yield {
+      type: 'turn_open',
+      turnId: queryTurnId,
+      userPrompt: userQuestionPreview,
+      vpId: queryVpId,
+      groupId: groupId || null,
+      at: queryStartedAt,
+    };
+
+    // Surface memory recall to the debug panel right after turn_open.
+    // recallResult was loaded above; emit a structured `memory_used`
+    // event so the UI can show "loaded N segments" without parsing
+    // the legacy `recall` event (which only carried entryCount).
+    if (recallResult && Array.isArray(recallResult.entries) && recallResult.entries.length > 0) {
+      yield {
+        type: 'memory_used',
+        turnId: queryTurnId,
+        loaded: recallResult.entries.map(e => ({
+          id: e && e.id || null,
+          score: e && typeof e.score === 'number' ? e.score : null,
+          kind: e && e.kind || null,
+        })),
+      };
+    }
+
     const toolDefs = this.#getToolDefs();
     let turnNumber = 0;
     let continueTurns = 0; // auto-continue counter
@@ -1196,16 +1233,23 @@ export class Engine {
           responseText,
         });
 
-        // Emit debug_turn for error path too
+        // Emit `loop` event for error path too (was `debug_turn`).
+        const errLoopInputTokens = totalUsage.inputTokens || 0;
+        const errLoopOutputTokens = totalUsage.outputTokens || 0;
         yield {
-          type: 'debug_turn',
-          turnNumber,
+          type: 'loop',
+          turnId: queryTurnId,
+          loopNumber: turnNumber,
           model: currentModel,
           systemPrompt,
           messages: conversationMessages.map(mapDebugMessage),
           response: responseText || `Error: ${err.message}`,
           toolCalls: toolCalls.map(tc => ({ id: tc.id, name: tc.name, input: tc.input })),
-          usage: { inputTokens: totalUsage.inputTokens, outputTokens: totalUsage.outputTokens },
+          usage: {
+            inputTokens: errLoopInputTokens,
+            outputTokens: errLoopOutputTokens,
+            totalTokens: errLoopInputTokens + errLoopOutputTokens,
+          },
           latencyMs,
           ttfbMs,
           stopReason: 'error',
@@ -1270,20 +1314,31 @@ export class Engine {
         responseText,
       });
 
-      // Emit debug_turn event for web UI debug panel
-      // (conversationMessages does NOT yet include the assistant response at this point)
-      // task-331: preserve toolCalls / toolCallId / isError on each message so
-      // the Debug panel can render function_call requests and their paired
-      // tool_result responses across turns.
+      // Emit `loop` event for the debug panel.
+      // feat-6af5f9f1 PR B: a Loop is one LLM call inside a Turn. The wire
+      // event was historically named `debug_turn` and carried `turnNumber`,
+      // which is misleading — it's per-LLM-call, not per-user-prompt.
+      // We emit the new shape (turnId + loopNumber) and keep totalTokens
+      // pre-computed so the UI doesn't have to.
+      // task-331: preserve toolCalls / toolCallId / isError on each message
+      // so the panel can render function_call requests and their paired
+      // tool_result responses across loops.
+      const loopInputTokens = totalUsage.inputTokens || 0;
+      const loopOutputTokens = totalUsage.outputTokens || 0;
       yield {
-        type: 'debug_turn',
-        turnNumber,
+        type: 'loop',
+        turnId: queryTurnId,
+        loopNumber: turnNumber,
         model: currentModel,
         systemPrompt,
         messages: conversationMessages.map(mapDebugMessage),
         response: responseText,
         toolCalls: toolCalls.map(tc => ({ id: tc.id, name: tc.name, input: tc.input })),
-        usage: { inputTokens: totalUsage.inputTokens, outputTokens: totalUsage.outputTokens },
+        usage: {
+          inputTokens: loopInputTokens,
+          outputTokens: loopOutputTokens,
+          totalTokens: loopInputTokens + loopOutputTokens,
+        },
         latencyMs,
         ttfbMs,
         stopReason,
@@ -1390,10 +1445,12 @@ export class Engine {
           });
           if (adjustResult && adjustResult.ran) {
             yield {
-              type: 'ams_adjust',
+              type: 'memory_adjust',
+              turnId: queryTurnId,
               groupKey: amsContext.groupKey,
               added: adjustResult.added,
               evicted: adjustResult.evicted,
+              skipped: adjustResult.skipped || 0,
               reason: adjustResult.reason,
             };
           }
@@ -1413,6 +1470,8 @@ export class Engine {
             );
             yield {
               type: 'reflection',
+              turnId: queryTurnId,
+              loopNumber: turnNumber,
               trigger: 't2',
               status: 'pending',
               loopRange: [arcStart, arcEnd],
@@ -1437,6 +1496,7 @@ export class Engine {
               loopRange: [arcStart, arcEnd],
               count: pairs.length,
               originalUserMsg: prompt,
+              originatingTurnId: queryTurnId,
               ready: false,
               result: null,
               error: null,
@@ -1534,6 +1594,20 @@ export class Engine {
 
         const toolDurationMs = Date.now() - toolStartTime;
 
+        // feat-6af5f9f1 PR B: emit a structured `tool_exec` event for the
+        // debug panel. Args/output are already in `conversationMessages`
+        // and will be visible in the next loop's snapshot, so we don't
+        // duplicate them here — only the per-tool timing + status.
+        yield {
+          type: 'tool_exec',
+          turnId: queryTurnId,
+          loopNumber: turnNumber,
+          callId: tc.id,
+          name: tc.name,
+          durationMs: toolDurationMs,
+          isError,
+        };
+
         // Log tool to debug trace
         this.#trace.logTool(turnId, {
           toolName: tc.name,
@@ -1596,6 +1670,8 @@ export class Engine {
           );
           yield {
             type: 'reflection',
+            turnId: queryTurnId,
+            loopNumber: turnNumber,
             trigger: 't1',
             status: 'pending',
             loopRange: [arcStart, arcEnd],
@@ -1616,6 +1692,8 @@ export class Engine {
           for (const m of next) conversationMessages.push(m);
           yield {
             type: 'reflection',
+            turnId: queryTurnId,
+            loopNumber: turnNumber,
             trigger: 't1',
             // PR-L bug fix: keep the same loopRange as the `pending` event
             // so the frontend key stays stable across pending → ready and
@@ -1631,6 +1709,8 @@ export class Engine {
           // continues normally — never block the turn.
           yield {
             type: 'reflection',
+            turnId: queryTurnId,
+            loopNumber: turnNumber,
             trigger: 't1',
             status: 'error',
             error: err && err.message || String(err),
@@ -1656,6 +1736,18 @@ export class Engine {
 
       // Loop back to call adapter again with tool results
     }
+
+    // feat-6af5f9f1 PR B: turn closed. Emits final totals so the debug
+    // panel can show "Turn done · 4 loops · 12.4s · 5.0k tok" without
+    // having to reduce the loops itself. Always fires (every break path
+    // above falls through here).
+    yield {
+      type: 'turn_close',
+      turnId: queryTurnId,
+      totalMs: Date.now() - queryStartedAt,
+      totalTokens: cumulativeInputTokens + cumulativeOutputTokens,
+      loopCount: turnNumber,
+    };
   }
 
   /**
@@ -1753,6 +1845,7 @@ export class Engine {
 
       yield {
         type: 'reflection',
+        turnId: info.originatingTurnId || null,
         trigger,
         status: 'ready',
         loopRange: [startIdx, endIdx],
@@ -1782,4 +1875,29 @@ export class Engine {
 
   /** @returns {object} — Config with fastModel as model (for internal tasks) */
   get fastConfig() { return this.#fastConfig; }
+
+  /**
+   * Run a one-shot fast-model call to produce a compact summary.
+   * Used by the web bridge's in-memory history compactor
+   * (`agent/unify/history-compact.js`) — kept on the engine so callers
+   * don't reach into the private adapter field.
+   *
+   * @param {{system: string, prompt: string, maxTokens?: number}} args
+   * @returns {Promise<string>} — summary text (trimmed); '' on failure
+   */
+  async summarizeForCompact({ system, prompt, maxTokens = 1024 } = {}) {
+    if (!system || !prompt) return '';
+    try {
+      const out = await this.#adapter.call({
+        model: this.#fastConfig.model,
+        system,
+        messages: [{ role: 'user', content: prompt }],
+        maxTokens,
+      });
+      return (out?.text || '').trim();
+    } catch (err) {
+      console.warn('[Engine] summarizeForCompact failed:', err?.message || err);
+      return '';
+    }
+  }
 }

package/unify/history-compact.js

@@ -0,0 +1,461 @@
+/**
+ * history-compact.js — In-memory conversation history compaction for the
+ * Unify group-chat fan-out path.
+ *
+ * Problem this solves:
+ *   `agent/unify/web-bridge.js` keeps a flat module-level array
+ *   `conversationMessages` that grows unbounded across the lifetime of the
+ *   agent process. Every fan-out turn snapshots the whole thing into
+ *   `baseSnapshot` and feeds it to `engine.query` for every VP. Without a
+ *   cap, prompt size and token cost grow linearly with conversation length.
+ *
+ * Existing infrastructure (`agent/unify/compact/orchestrator.js`,
+ * `engine.js#runOrchestratorCompact`) compacts the on-disk
+ * `conversationStore` — a different surface. This helper compacts the
+ * in-memory array that actually gets passed to the LLM.
+ *
+ * Approach (Claude-Code-style compact):
+ *   1. Skip tool messages and the synthetic `_reflection`/`_compactSummary`
+ *      wrappers when feeding the summarizer (tool result bodies are noise;
+ *      reflection wrappers are already a summary).
+ *   2. Ask the fast model to produce a short structured summary of the
+ *      conversation up to a cut-point.
+ *   3. Replace `messages[0..cutIdx]` with ONE synthetic user message
+ *      carrying that summary, wrapped with the canonical recovery prompt
+ *      ("This session is being continued from a previous conversation...").
+ *   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
+ *
+ * Defaults match the user-stated requirement; both 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
+ *   ("messages must end with user before next assistant turn"). Wrapping
+ *   as user mirrors what Claude Code does for compact summaries — and
+ *   what `tool-folding/index.js#collapseRangeToReflection` already does
+ *   for tool-arc reflections in this codebase. The opening sentence
+ *   ("This session is being continued ...") makes the model treat it
+ *   as a recovery directive rather than a fresh user prompt.
+ */
+
+import { estimateTokens } from './conversation/persist.js';
+
+/**
+ * Default trigger thresholds — match the user's stated policy:
+ *   "如果 turn 超过 20 或者 message 上下文超过 80K，那么就 compact"
+ */
+export const DEFAULT_TURN_LIMIT = 20;
+export const DEFAULT_TOKEN_LIMIT = 80_000;
+
+/**
+ * How many user→assistant pairs to leave intact at the tail. The summary
+ * replaces everything before this window. 2 keeps "what we were just
+ * talking about" lossless.
+ */
+export const DEFAULT_KEEP_RECENT_TURNS = 2;
+
+/**
+ * Estimate the token weight of a single message including role overhead
+ * and any tool-call structure. Mirrors `dream-v2/segment.js` approach: a
+ * couple of tokens per message for role/wrapping plus the body.
+ *
+ * @param {{role:string, content?:string, toolCalls?:Array, toolCallId?:string}} m
+ * @returns {number}
+ */
+export function estimateMessageTokens(m) {
+  if (!m || typeof m !== 'object') return 0;
+  let n = 2; // role + framing
+  if (typeof m.content === 'string') n += estimateTokens(m.content);
+  if (Array.isArray(m.toolCalls)) {
+    for (const tc of m.toolCalls) {
+      n += 4; // call framing
+      try {
+        const inputJson = typeof tc.input === 'string' ? tc.input : JSON.stringify(tc.input || {});
+        n += estimateTokens(inputJson);
+      } catch { /* ignore — JSON.stringify failure on circular input */ }
+      if (tc.name) n += estimateTokens(tc.name);
+    }
+  }
+  if (m.toolCallId) n += 2;
+  return n;
+}
+
+/**
+ * Sum estimated tokens across all messages.
+ * @param {Array<object>} messages
+ * @returns {number}
+ */
+export function estimateMessagesTokens(messages) {
+  if (!Array.isArray(messages)) return 0;
+  let total = 0;
+  for (const m of messages) total += estimateMessageTokens(m);
+  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.
+ *
+ * @param {Array<object>} messages
+ * @param {{turnLimit?: number, tokenLimit?: number}} [opts]
+ * @returns {{trigger: boolean, reason: 'turn_count'|'token_threshold'|null,
+ *            turnCount: number, tokenCount: number,
+ *            turnLimit: number, tokenLimit: number}}
+ */
+export function shouldCompactHistory(messages, opts = {}) {
+  const turnLimit = opts.turnLimit ?? DEFAULT_TURN_LIMIT;
+  const tokenLimit = opts.tokenLimit ?? DEFAULT_TOKEN_LIMIT;
+  const turnCount = countTurns(messages);
+  const tokenCount = estimateMessagesTokens(messages);
+
+  let reason = null;
+  if (turnCount > turnLimit) reason = 'turn_count';
+  else if (tokenCount > tokenLimit) reason = 'token_threshold';
+
+  return {
+    trigger: reason !== null,
+    reason,
+    turnCount,
+    tokenCount,
+    turnLimit,
+    tokenLimit,
+  };
+}
+
+/**
+ * Strip noise from a message list before sending it to the summarizer:
+ *   - drop `role: 'tool'` (raw tool results — too verbose, mostly redundant)
+ *   - drop messages already tagged `_compactSummary` (avoid summarising
+ *     a summary)
+ *   - keep `_reflection` messages as-is (they're already a fold-summary
+ *     of an earlier tool arc and contain real information)
+ *   - elide `toolCalls` from assistant messages: replace each with a tag
+ *     line like "[called tool: bash with input ...]" so the summarizer
+ *     knows a tool ran without spending tokens on the full input
+ *
+ * @param {Array<object>} messages
+ * @returns {Array<{role:string, content:string}>}
+ */
+export function buildSummarizerInput(messages) {
+  if (!Array.isArray(messages)) return [];
+  const out = [];
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue;
+    if (m.role === 'tool') continue;
+    if (m._compactSummary) continue;
+    let content = typeof m.content === 'string' ? m.content : '';
+    if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+      const callTags = m.toolCalls.map(tc => {
+        const name = tc.name || 'unknown';
+        let inputBrief = '';
+        try {
+          const json = typeof tc.input === 'string' ? tc.input : JSON.stringify(tc.input || {});
+          inputBrief = json.length > 120 ? json.slice(0, 120) + '…' : json;
+        } catch { inputBrief = '<input>'; }
+        return `[tool ${name}: ${inputBrief}]`;
+      }).join(' ');
+      content = content ? `${content}\n${callTags}` : callTags;
+    }
+    if (!content) continue;
+    out.push({ role: m.role, content });
+  }
+  return out;
+}
+
+/**
+ * Find the cut index: keep the last `keepRecent` user→assistant arcs
+ * 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).
+ *
+ * @param {Array<object>} messages
+ * @param {number} keepRecent
+ * @returns {number}
+ */
+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;
+}
+
+/**
+ * Wrap a summary string into the canonical "session continued" recovery
+ * message. The wording is deliberately close to Claude Code's compact
+ * marker so frontend filters (already in `web/stores/helpers/claudeOutput.js`,
+ * `server/db/message-db.js`) recognise it.
+ *
+ * @param {string} summary
+ * @returns {{role:'user', content:string, _compactSummary: true}}
+ */
+export function wrapSummaryAsUserMessage(summary) {
+  const body = (summary || '').trim() || '(no summary produced)';
+  const content =
+    'This session is being continued from a previous conversation. ' +
+    'The earlier context has been summarized for efficiency.\n\n' +
+    'Summary of conversation so far:\n' +
+    body +
+    '\n\nContinue the conversation from where it left off without asking the user any further questions.';
+  return {
+    role: 'user',
+    content,
+    _compactSummary: true,
+  };
+}
+
+/**
+ * Build the prompt fed to the fast-model summarizer. Kept in code (not in
+ * a template file) because it's small and lives alongside the call site.
+ *
+ * @param {Array<{role:string, content:string}>} cleanedMessages
+ * @returns {{system: string, prompt: string}}
+ */
+export function buildSummaryPrompt(cleanedMessages) {
+  const transcript = cleanedMessages
+    .map(m => `[${m.role}]\n${m.content}`)
+    .join('\n\n---\n\n');
+  const system =
+    'You are a conversation summarizer for a multi-agent group chat. ' +
+    'Produce a concise (4–8 short bullet points) summary of the conversation ' +
+    'so far. Preserve: (1) decisions made, (2) facts learned, (3) the user\'s ' +
+    'current goal, (4) any open questions or pending actions, (5) which VPs ' +
+    'are participating and what each contributed. Do NOT include raw tool ' +
+    'output. Do NOT speculate. Be specific.';
+  const prompt =
+    'Summarize the following conversation. Output ONLY the summary, no ' +
+    'preamble.\n\n' +
+    transcript;
+  return { system, prompt };
+}
+
+/**
+ * Apply compaction to a messages array. Pure transform once `summarize`
+ * has produced text. Returns a new array — does not mutate the input.
+ *
+ * @param {Array<object>} messages
+ * @param {{
+ *   summarize: (args: {system: string, prompt: string}) => Promise<string>,
+ *   keepRecent?: number,
+ *   turnLimit?: number,
+ *   tokenLimit?: number,
+ * }} options
+ * @returns {Promise<{
+ *   messages: Array<object>,
+ *   compacted: boolean,
+ *   reason: string|null,
+ *   summary: string|null,
+ *   archivedCount: number,
+ *   beforeTurns: number,
+ *   beforeTokens: number,
+ *   afterTurns: number,
+ *   afterTokens: number,
+ * }>}
+ */
+export async function compactHistory(messages, options) {
+  const {
+    summarize,
+    keepRecent = DEFAULT_KEEP_RECENT_TURNS,
+    turnLimit = DEFAULT_TURN_LIMIT,
+    tokenLimit = DEFAULT_TOKEN_LIMIT,
+  } = options || {};
+
+  if (typeof summarize !== 'function') {
+    throw new TypeError('compactHistory: options.summarize must be a function');
+  }
+
+  const before = shouldCompactHistory(messages, { turnLimit, tokenLimit });
+  if (!before.trigger) {
+    return {
+      messages,
+      compacted: false,
+      reason: null,
+      summary: null,
+      archivedCount: 0,
+      beforeTurns: before.turnCount,
+      beforeTokens: before.tokenCount,
+      afterTurns: before.turnCount,
+      afterTokens: before.tokenCount,
+    };
+  }
+
+  const cutIdx = findCutIndex(messages, keepRecent);
+  if (cutIdx <= 0) {
+    // Not enough history to fold while preserving the recent window.
+    return {
+      messages,
+      compacted: false,
+      reason: before.reason,
+      summary: null,
+      archivedCount: 0,
+      beforeTurns: before.turnCount,
+      beforeTokens: before.tokenCount,
+      afterTurns: before.turnCount,
+      afterTokens: before.tokenCount,
+    };
+  }
+
+  const archived = messages.slice(0, cutIdx);
+  const tail = messages.slice(cutIdx);
+  const cleaned = buildSummarizerInput(archived);
+
+  let summaryText = '';
+  if (cleaned.length > 0) {
+    const { system, prompt } = buildSummaryPrompt(cleaned);
+    try {
+      summaryText = (await summarize({ system, prompt })) || '';
+    } catch (err) {
+      // Summarizer failure → return original messages, signal failure.
+      return {
+        messages,
+        compacted: false,
+        reason: before.reason,
+        summary: null,
+        archivedCount: 0,
+        beforeTurns: before.turnCount,
+        beforeTokens: before.tokenCount,
+        afterTurns: before.turnCount,
+        afterTokens: before.tokenCount,
+        error: err && err.message ? err.message : String(err),
+      };
+    }
+    // Treat an empty / whitespace-only summary as a soft failure rather
+    // than a successful compact. Otherwise we'd archive real history
+    // behind a "(no summary produced)" placeholder and the next turn
+    // would start from useless context.
+    if (!summaryText.trim()) {
+      return {
+        messages,
+        compacted: false,
+        reason: before.reason,
+        summary: null,
+        archivedCount: 0,
+        beforeTurns: before.turnCount,
+        beforeTokens: before.tokenCount,
+        afterTurns: before.turnCount,
+        afterTokens: before.tokenCount,
+        error: 'empty summary',
+      };
+    }
+  }
+
+  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);
+
+  const newMessages = [summaryMsg, ...safeTail];
+  const after = shouldCompactHistory(newMessages, { turnLimit, tokenLimit });
+
+  return {
+    messages: newMessages,
+    compacted: true,
+    reason: before.reason,
+    summary: summaryText,
+    archivedCount: archived.length,
+    beforeTurns: before.turnCount,
+    beforeTokens: before.tokenCount,
+    afterTurns: after.turnCount,
+    afterTokens: after.tokenCount,
+  };
+}

package/unify/web-bridge.js

@@ -44,6 +44,10 @@ import {
 import { openGroup, loadGroupMeta } from './groups/group-store.js';
 import { createCoordinator } from './groups/coordinator.js';
 import { seedDefaultGroup } from './groups/seed-default.js';
+import {
+  shouldCompactHistory,
+  compactHistory,
+} from './history-compact.js';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -535,6 +539,10 @@ function handleEngineEvent(event, hctx) {
     case 'reflection':
       sendUnifyEvent({
         type: 'reflection',
+        // feat-6af5f9f1 PR B: stamp turnId/loopNumber so the debug panel
+        // can attach reflection cards to the matching loop.
+        turnId: event.turnId || null,
+        loopNumber: event.loopNumber || null,
         trigger: event.trigger,
         status: event.status,
         loopRange: event.loopRange,
@@ -545,10 +553,66 @@ function handleEngineEvent(event, hctx) {
       }, envelope);
       break;
 
-    case 'debug_turn':
+    case 'turn_open':
+      sendUnifyEvent({
+        type: 'turn_open',
+        turnId: event.turnId,
+        userPrompt: event.userPrompt,
+        vpId: event.vpId,
+        groupId: event.groupId,
+        at: event.at,
+      }, envelope);
+      break;
+
+    case 'turn_close':
+      sendUnifyEvent({
+        type: 'turn_close',
+        turnId: event.turnId,
+        totalMs: event.totalMs,
+        totalTokens: event.totalTokens,
+        loopCount: event.loopCount,
+      }, envelope);
+      break;
+
+    case 'memory_used':
+      sendUnifyEvent({
+        type: 'memory_used',
+        turnId: event.turnId,
+        loaded: event.loaded || [],
+      }, envelope);
+      break;
+
+    case 'memory_adjust':
+      sendUnifyEvent({
+        type: 'memory_adjust',
+        turnId: event.turnId,
+        groupKey: event.groupKey,
+        added: event.added,
+        evicted: event.evicted,
+        skipped: event.skipped,
+        reason: event.reason,
+      }, envelope);
+      break;
+
+    case 'tool_exec':
       sendUnifyEvent({
-        type: 'debug_turn',
-        turnNumber: event.turnNumber,
+        type: 'tool_exec',
+        turnId: event.turnId,
+        loopNumber: event.loopNumber,
+        callId: event.callId,
+        name: event.name,
+        durationMs: event.durationMs,
+        isError: event.isError,
+      }, envelope);
+      break;
+
+    case 'loop':
+      // feat-6af5f9f1 PR B: replaces the old `debug_turn` event. Same
+      // payload shape plus turnId + loopNumber + usage.totalTokens.
+      sendUnifyEvent({
+        type: 'loop',
+        turnId: event.turnId,
+        loopNumber: event.loopNumber,
         model: event.model,
         systemPrompt: event.systemPrompt,
         messages: event.messages,
@@ -621,6 +685,15 @@ export async function handleUnifyGroupChat(msg) {
     ? msg.groupId.trim()
     : 'grp_default';
 
+  // Entry gate: if a compact is in flight from the previous turn,
+  // wait for it to finish before reading conversationMessages. Compact
+  // runs at turn END (post-fanout) so it does not block the user's
+  // current message latency, but a fast double-send from the user must
+  // not race with the swap.
+  if (_compactInFlight) {
+    try { await _compactInFlight; } catch { /* first caller logs */ }
+  }
+
   // yeaftDir is a hard prerequisite for both session boot and group seeding;
   // validate BEFORE booting so a misconfigured agent doesn't leave a zombie
   // session lying around.
@@ -825,6 +898,14 @@ export async function handleUnifyGroupChat(msg) {
       } catch { /* never crash WS pipeline */ }
     }
   }));
+
+  // Post-turn compaction. Triggers when the JUST-APPENDED turn pushed
+  // history past 20 turns / 80K tokens. Runs in the background — does
+  // not block the response to this message. The next user message
+  // awaits `_compactInFlight` at the entry gate (handleUnifyGroupChat
+  // top), so the swap is guaranteed to be observed before the next
+  // baseSnapshot capture. Errors are swallowed; next turn retries.
+  scheduleCompactAfterTurn(groupId);
 }
 
 /**
@@ -1091,6 +1172,145 @@ function appendTurnToHistory(prompt, assistantTextParts, toolCallsAccum, toolRes
   }
 }
 
+/**
+ * In-flight compact promise. Set by `scheduleCompactAfterTurn` when a
+ * turn ends and triggers compaction; awaited by the next
+ * `handleUnifyGroupChat` invocation at its entry gate so the next
+ * baseSnapshot reflects the compacted history.
+ *
+ * Compact runs at turn END (not before fan-out), so it does not add
+ * latency to the user's current message. The trade-off: the next user
+ * message may have to wait briefly for the compact to finish — but
+ * compact uses the fast model and typically completes in 1–3s.
+ *
+ * @type {Promise<void>|null}
+ */
+let _compactInFlight = null;
+
+/**
+ * Re-trigger flag. If `scheduleCompactAfterTurn` is called while a
+ * compact is already in flight, set this so the in-flight one chains
+ * a follow-up immediately on completion. Without this, a sustained
+ * burst of turns could starve compaction: turn N triggers compact,
+ * turns N+1 / N+2 / … each find `_compactInFlight` set and skip,
+ * leaving history above threshold until the burst ends.
+ */
+let _compactPending = false;
+
+/**
+ * Fire-and-forget post-turn compaction. Called once at the end of each
+ * `handleUnifyGroupChat` after `Promise.all(runVpTurn)` resolves. If a
+ * compaction is still in flight from an earlier turn, we set
+ * `_compactPending` so the running compact chains a follow-up on
+ * completion (anti-starvation).
+ *
+ * The promise is stored in `_compactInFlight` so the next user message
+ * can await it before reading `conversationMessages`.
+ *
+ * @param {string} groupId — for envelope tagging on the emitted event
+ */
+function scheduleCompactAfterTurn(groupId) {
+  if (_compactInFlight) {
+    // A compact is already running. Mark a follow-up so when it
+    // finishes, it re-evaluates and runs again if still triggered.
+    _compactPending = true;
+    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);
+  if (!triage.trigger) return;
+  if (!session?.engine || typeof session.engine.summarizeForCompact !== 'function') {
+    console.warn('[Unify] history compact: engine.summarizeForCompact unavailable — skipping');
+    return;
+  }
+
+  _compactInFlight = runCompactNow(groupId).finally(() => {
+    _compactInFlight = 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 (_compactPending) {
+      _compactPending = false;
+      queueMicrotask(() => scheduleCompactAfterTurn(groupId));
+    }
+  });
+}
+
+/**
+ * Run the in-memory history compactor. Replaces the older prefix of
+ * `conversationMessages` with a single user-role summary message,
+ * preserving the recent tail verbatim. Mutates the module-level
+ * variable in place via reassignment.
+ *
+ * Behaviour:
+ *   - If summarization fails, leaves history untouched.
+ *   - On success, emits a `unify_history_compacted` event so dev tools
+ *     can show what happened (frontend currently ignores it).
+ *
+ * Race safety:
+ *   - Single-flight via `_compactInFlight` (only one runs at a time).
+ *   - Reads the array reference once into `snapshot`. If anything else
+ *     reassigns `conversationMessages` during the await (`consolidate`
+ *     event from the engine, `clearUnifyMessages`, `resetUnifySession`),
+ *     we detect the swap by reference comparison and bail without
+ *     overwriting their fresh state.
+ *
+ * @param {string} groupId
+ * @returns {Promise<void>}
+ */
+async function runCompactNow(groupId) {
+  const summarize = ({ system, prompt }) =>
+    session.engine.summarizeForCompact({ system, prompt, maxTokens: 1024 });
+
+  // Capture the current array reference. If anyone reassigns
+  // `conversationMessages` while we're summarizing (engine consolidate
+  // event, session reset, manual clear), the reference will differ
+  // and we abandon the swap.
+  const snapshot = conversationMessages;
+
+  try {
+    const result = await compactHistory(snapshot, { summarize });
+    if (!result.compacted) {
+      if (result.error) {
+        console.warn(
+          `[Unify] history compact: summarizer failed (${result.error}); ` +
+          `keeping ${result.beforeTurns} turns / ~${result.beforeTokens} tokens`
+        );
+      }
+      return;
+    }
+    // Race guard: if `conversationMessages` was reassigned during the
+    // await (e.g. consolidate / reset), do NOT overwrite the fresh
+    // state with our stale compacted snapshot.
+    if (conversationMessages !== snapshot) {
+      console.log('[Unify] history compact: history was reset during compact — discarding stale summary');
+      return;
+    }
+    conversationMessages = result.messages;
+    console.log(
+      `[Unify] history compacted (reason=${result.reason}): ` +
+      `turns ${result.beforeTurns}→${result.afterTurns}, ` +
+      `tokens ~${result.beforeTokens}→${result.afterTokens}, ` +
+      `archived ${result.archivedCount} messages`
+    );
+    try {
+      sendUnifyEvent({
+        type: 'unify_history_compacted',
+        reason: result.reason,
+        beforeTurns: result.beforeTurns,
+        afterTurns: result.afterTurns,
+        beforeTokens: result.beforeTokens,
+        afterTokens: result.afterTokens,
+        archivedCount: result.archivedCount,
+        ts: Date.now(),
+      }, { groupId });
+    } catch { /* WS pipeline failure must not crash compact */ }
+  } catch (err) {
+    console.warn('[Unify] history compact: unexpected failure', err?.message || err);
+  }
+}
+
 /**
  * H2.f.2: user-initiated abort. The pre-H2 multi-thread version took a
  * `threadId` parameter; the new version aborts the single in-flight