@yeaft/webchat-agent 0.1.611 → 0.1.613

package/package.json

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

package/unify/engine.js

@@ -36,6 +36,20 @@ import { pickEffort, parseEffortPrefix } from './effort.js';
 import { normalizeEffort } from './models.js';
 import { attachRouterPlan, extractPriorPlan, stripMetaForWire } from './router/continuity.js';
 import { resolveThinking } from './router/thinking.js';
+import {
+  TOOL_BATCH_SIZE,
+  TURN_SUMMARY_THRESHOLD,
+  DUP_TOOL_THRESHOLD,
+  ExecLog,
+  buildEntry as buildExecLogEntry,
+  argsHashOf,
+  runT1Reflection,
+  runT2Reflection,
+  buildFallbackStub,
+  collapseRangeToReflection,
+  buildDuplicateReminder,
+  extractToolPairsFromRange,
+} from './tool-folding/index.js';
 
 /**
  * task-324 — Turn cap removed.
@@ -172,6 +186,26 @@ export class Engine {
    */
   #currentAbortCtrl = null;
 
+  /**
+   * PR-L — V7 Tool History Reflection state. Owned per Engine instance.
+   *
+   *   • `#execLog` — append-only log of every tool execution, used for
+   *     fallback-stub generation and duplicate-call detection. Persists
+   *     to <yeaftDir>/tool-log/<traceId>/<turnIdx>.jsonl when yeaftDir
+   *     is set; in-memory only otherwise.
+   *   • `#pendingT2` — Map<turnNumber, { promise, loopRange, count, ... }>
+   *     keyed by the turn number that triggered T2. The next query() call
+   *     non-blocking-checks this map; if the promise has resolved, the
+   *     prior turn's history is rewritten with the reflection. If still
+   *     pending, the engine falls back to the exec-log stub.
+   *   • `#reflectedTurns` — Set<turnNumber>; ensures T1 fires at most
+   *     once per turn (when toolCount crosses TOOL_BATCH_SIZE).
+   */
+  #execLog = null;
+  #pendingT2 = new Map();
+  #reflectedTurns = new Set();
+  #__queryCounter = 0;
+
   /** @type {string|null} */
   #abortReason = null;
 
@@ -202,6 +236,14 @@ export class Engine {
     this.#mcpManager = mcpManager || null;
     this.#yeaftDir = yeaftDir || null;
 
+    // PR-L: tool history reflection log. Keyed by traceId so distinct
+    // engine instances don't stomp on each other's jsonl files. When
+    // yeaftDir is null the ExecLog still works — purely in-memory.
+    this.#execLog = new ExecLog({
+      yeaftDir: this.#yeaftDir,
+      conversationId: this.#traceId,
+    });
+
     // Build fast config: uses fastModelId for internal tasks (recall, consolidation, dream)
     // Falls back to primary model if no fastModel configured
     const fastModelId = config.fastModelId || config.model;
@@ -846,6 +888,22 @@ export class Engine {
       { role: 'user', content: prompt },
     ];
 
+    // PR-L: T2 carry-forward. If a previous query()'s end-of-turn
+    // reflection has resolved, rewrite that turn's range in
+    // `conversationMessages` to a single assistant reflection message.
+    // If still pending, fall back to the exec-log stub — non-blocking,
+    // never wait. This runs BEFORE the first adapter.stream so the
+    // upcoming call sees the rewritten history.
+    yield* this.#applyPendingT2Reflections(conversationMessages, prompt);
+
+    // PR-L: track this query()'s tool-arc for reflection.
+    // `turnStartIdx` is where the current user message lives; the arc
+    // we may collapse spans (turnStartIdx + 1 .. last assistant/tool).
+    const turnStartIdx = conversationMessages.length - 1;
+    let queryToolCount = 0;
+    let t1Fired = false;
+    const queryNumber = (this.#__queryCounter = (this.#__queryCounter || 0) + 1);
+
     const toolDefs = this.#getToolDefs();
     let turnNumber = 0;
     let continueTurns = 0; // auto-continue counter
@@ -1196,6 +1254,56 @@ export class Engine {
           }
         }
 
+        // PR-L: T2 end-of-turn (asynchronous) reflection. Fires when the
+        // total tool count for this query() exceeds TURN_SUMMARY_THRESHOLD
+        // (5) AND T1 didn't already collapse the arc. Kicks off the
+        // primary-model call without await; the next query()'s
+        // `#applyPendingT2Reflections` carries the result forward.
+        if (queryToolCount > TURN_SUMMARY_THRESHOLD && !t1Fired) {
+          const arcStart = turnStartIdx + 1;
+          const arcEnd = conversationMessages.length - 1;
+          if (arcEnd > arcStart) {
+            const { pairs, assistantText } = extractToolPairsFromRange(
+              conversationMessages, arcStart, arcEnd,
+            );
+            yield {
+              type: 'reflection',
+              trigger: 't2',
+              status: 'pending',
+              loopRange: [arcStart, arcEnd],
+              toolCount: pairs.length,
+            };
+            const promise = runT2Reflection({
+              adapter: this.#adapter,
+              model: this.#config.model,
+              originalUserMsg: prompt,
+              toolPairs: pairs,
+              assistantText,
+              signal,
+            });
+            // Detach: never await. The promise outlives this query() and
+            // the next call will pick it up (or use the fallback stub if
+            // it hasn't resolved by then).
+            // PR-L follow-up: latch a synchronously-readable ready flag
+            // and result on the info record so `#applyPendingT2Reflections`
+            // can decide ready-vs-pending without racing microtasks.
+            const info = {
+              promise,
+              loopRange: [arcStart, arcEnd],
+              count: pairs.length,
+              originalUserMsg: prompt,
+              ready: false,
+              result: null,
+              error: null,
+            };
+            promise.then(
+              (v) => { info.ready = true; info.result = v; },
+              (err) => { info.ready = true; info.error = err; },
+            );
+            this.#pendingT2.set(queryNumber, info);
+          }
+        }
+
         break;
       }
 
@@ -1206,6 +1314,8 @@ export class Engine {
       // break out of the outer while-loop cleanly once the current
       // tool batch finishes reporting.
       let abortedDuringTools = false;
+      /** @type {string[]} */
+      const pendingDupReminders = [];
 
       for (const tc of toolCalls) {
         // task-325a: honour abort between tools. We don't cancel a tool
@@ -1219,6 +1329,35 @@ export class Engine {
 
         const toolStartTime = Date.now();
 
+        // PR-L: duplicate-call detection. If this exact (toolName,
+        // argsHash) pair has already been executed DUP_TOOL_THRESHOLD
+        // (3) times within the current turn + last 2 turns, queue a
+        // system reminder. We push the reminder AFTER the tool batch
+        // completes (not now) so the
+        // assistant(tool_use) → user(tool_result, …) pairing demanded
+        // by the Anthropic / OpenAI Responses APIs stays intact. We
+        // don't block the call — the LLM still decides.
+        const dupHash = argsHashOf(tc.input);
+        // PR-L follow-up: lookback is by user-conversation turn
+        // (`queryNumber`), NOT by inner adapter loop iteration. Each call
+        // to query() bumps queryNumber once, so "last 2 turns" means the
+        // current user turn + the previous two user turns — the natural
+        // semantic for "the model is stuck in a loop across the
+        // conversation."
+        const dupInfo = this.#execLog.dupInfo({
+          toolName: tc.name,
+          argsHash: dupHash,
+          currentTurn: queryNumber,
+          lookbackTurns: 2,
+        });
+        if (dupInfo.count + 1 >= DUP_TOOL_THRESHOLD) {
+          pendingDupReminders.push(buildDuplicateReminder({
+            toolName: tc.name,
+            count: dupInfo.count + 1,
+            lastResultBrief: dupInfo.lastResultBrief,
+          }));
+        }
+
         let output;
         let isError = false;
 
@@ -1266,6 +1405,92 @@ export class Engine {
           content: output,
           isError,
         });
+
+        // PR-L: persist this execution to the exec-log for fallback-stub
+        // and duplicate-call detection. Best-effort — disk failures are
+        // swallowed inside ExecLog.append.
+        // PR-L follow-up: persist under `queryNumber` (one entry-key per
+        // user-conversation turn), not the inner loop's turnNumber.
+        // Aligns exec-log layout with dup detection lookback and the
+        // T2 fallback-stub readTurn() call below.
+        this.#execLog.append(queryNumber, buildExecLogEntry({
+          loopIdx: queryToolCount,
+          toolName: tc.name,
+          args: tc.input,
+          output,
+          isError,
+        }));
+        queryToolCount += 1;
+      }
+
+      // PR-L: flush any duplicate-call reminders queued during the batch.
+      // Pushed AFTER the for-loop so the tool_use → tool_result pairing
+      // is intact; the next adapter.stream() will see the reminder as a
+      // user message immediately after the last tool result.
+      for (const reminder of pendingDupReminders) {
+        conversationMessages.push({ role: 'user', content: reminder });
+      }
+
+      // PR-L: T1 in-turn (synchronous) reflection. Fires exactly once per
+      // query() lifetime, the moment queryToolCount crosses
+      // TOOL_BATCH_SIZE (13). Generates a markdown reflection over the
+      // assistant+tool arc since the user prompt and rewrites the history
+      // in place — collapsing it to a SINGLE assistant message — before
+      // the next adapter.stream() runs.
+      if (!t1Fired
+          && queryToolCount >= TOOL_BATCH_SIZE
+          && !this.#reflectedTurns.has(`${queryNumber}:t1`)
+          && !abortedDuringTools && !signal?.aborted) {
+        t1Fired = true;
+        this.#reflectedTurns.add(`${queryNumber}:t1`);
+        try {
+          const arcStart = turnStartIdx + 1;
+          const arcEnd = conversationMessages.length - 1;
+          const { pairs, assistantText } = extractToolPairsFromRange(
+            conversationMessages, arcStart, arcEnd,
+          );
+          yield {
+            type: 'reflection',
+            trigger: 't1',
+            status: 'pending',
+            loopRange: [arcStart, arcEnd],
+            toolCount: pairs.length,
+          };
+          const { content, durationMs } = await runT1Reflection({
+            adapter: this.#adapter,
+            model: this.#config.model,
+            originalUserMsg: prompt,
+            toolPairs: pairs,
+            assistantText,
+            signal,
+          });
+          const next = collapseRangeToReflection(
+            conversationMessages, arcStart, arcEnd, content,
+          );
+          conversationMessages.length = 0;
+          for (const m of next) conversationMessages.push(m);
+          yield {
+            type: 'reflection',
+            trigger: 't1',
+            // PR-L bug fix: keep the same loopRange as the `pending` event
+            // so the frontend key stays stable across pending → ready and
+            // the spinner card is replaced in place (no orphan).
+            status: 'ready',
+            loopRange: [arcStart, arcEnd],
+            toolCount: pairs.length,
+            content,
+            durationMs,
+          };
+        } catch (err) {
+          // Best-effort. On failure leave history unchanged so the loop
+          // continues normally — never block the turn.
+          yield {
+            type: 'reflection',
+            trigger: 't1',
+            status: 'error',
+            error: err && err.message || String(err),
+          };
+        }
       }
 
       // task-325a: if abort fired between tools, converge now — emit
@@ -1335,6 +1560,82 @@ export class Engine {
   /** @returns {import('./mcp.js').MCPManager|null} */
   get mcpManager() { return this.#mcpManager; }
 
+  /**
+   * PR-L — V7 Tool History Reflection helpers.
+   *
+   * `#applyPendingT2Reflections` is called at the start of every
+   * `#runQuery` to carry forward any prior turn's async reflection. It is
+   * a generator so it can yield reflection events to the engine consumer.
+   * Non-blocking: never awaits a pending promise.
+   *
+   * @param {Array} conversationMessages
+   * @param {string} originalUserMsg
+   */
+  async *#applyPendingT2Reflections(conversationMessages, originalUserMsg) {
+    if (this.#pendingT2.size === 0) return;
+    // Drain in insertion order (Map preserves it). We process all entries
+    // because the user could send multiple prompts back-to-back before
+    // the engine resumes — each historical turn gets its rewrite.
+    const drained = [...this.#pendingT2.entries()];
+    this.#pendingT2.clear();
+
+    for (const [turnNumber, info] of drained) {
+      const range = info.loopRange;
+      if (!Array.isArray(range) || range.length !== 2) continue;
+      const [startIdx, endIdx] = range;
+      if (startIdx < 0 || endIdx < startIdx || endIdx >= conversationMessages.length) {
+        continue;
+      }
+
+      // PR-L follow-up: deterministic readiness check. The info record
+      // carries `ready / result / error` flags that are flipped from the
+      // promise's then/catch handler; reading them here is purely
+      // synchronous bookkeeping — no microtask race.
+      let content;
+      let trigger;
+      let durationMs = 0;
+      if (!info.ready) {
+        // Still in flight — fall back to the exec-log stub. Detach the
+        // unresolved promise so we don't leak it (handlers above already
+        // swallow rejection by routing into info.error).
+        const entries = this.#execLog ? this.#execLog.readTurn(turnNumber) : [];
+        content = buildFallbackStub({ execLogEntries: entries, originalUserMsg: info.originalUserMsg || originalUserMsg });
+        trigger = 't2-fallback';
+      } else if (info.error) {
+        // Promise rejected — leave history unchanged, no event.
+        continue;
+      } else if (info.result && typeof info.result.content === 'string' && info.result.content) {
+        content = info.result.content;
+        trigger = 't2';
+        durationMs = info.result.durationMs || 0;
+      } else {
+        // Resolved but with no usable content — defensively skip.
+        continue;
+      }
+
+      // Rewrite history.
+      const next = collapseRangeToReflection(conversationMessages, startIdx, endIdx, content);
+      // Mutate in place so caller's reference stays valid.
+      conversationMessages.length = 0;
+      for (const m of next) conversationMessages.push(m);
+
+      yield {
+        type: 'reflection',
+        trigger,
+        status: 'ready',
+        loopRange: [startIdx, endIdx],
+        toolCount: info.count || 0,
+        content,
+        durationMs,
+      };
+    }
+  }
+
+  /**
+   * PR-L — read-only accessor for tests.
+   */
+  get _execLog() { return this.#execLog; }
+
   /**
    * task-299 Phase 1: the engine's current thread marker.
    * Defaults to 'main' if the thread store is unreachable for any reason.

package/unify/tool-folding/exec-log.js

@@ -0,0 +1,188 @@
+/**
+ * exec-log.js — Persistent tool execution log used by the reflection
+ * subsystem (PR-L).
+ *
+ * Two purposes:
+ *   1. Source of fallback-stub when T2 reflection isn't ready in time.
+ *   2. Duplicate-call detection — count how many times the SAME
+ *      (toolName, argsHash) pair has been executed in the current turn
+ *      plus the last two turns, so the engine can inject a reminder when
+ *      the model is stuck in a loop.
+ *
+ * Storage layout (only when yeaftDir is configured):
+ *   <yeaftDir>/tool-log/<conversationId>/<turnIdx>.jsonl
+ *
+ * One JSON object per line:
+ *   { loopIdx, toolName, argsHash, argsBrief, resultBrief,
+ *     resultBytes, resultStatus, timestamp }
+ *
+ * If yeaftDir is absent, the log is held in memory only.
+ */
+
+import { createHash } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+const ARGS_BRIEF_CAP = 200;
+const RESULT_BRIEF_CAP = 500;
+
+/**
+ * Canonical-JSON-stringify and hash. Stable across key ordering so identical
+ * args produce identical hashes regardless of how the LLM serialised them.
+ *
+ * @param {any} args
+ * @returns {string} 16 hex chars
+ */
+export function argsHashOf(args) {
+  let canon;
+  try {
+    canon = canonicalStringify(args);
+  } catch {
+    canon = String(args);
+  }
+  return createHash('sha256').update(canon).digest('hex').slice(0, 16);
+}
+
+function canonicalStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalStringify).join(',') + ']';
+  }
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(value[k])).join(',') + '}';
+}
+
+function brief(value, cap) {
+  let s;
+  if (typeof value === 'string') s = value;
+  else {
+    try { s = JSON.stringify(value); } catch { s = String(value); }
+  }
+  if (s == null) s = '';
+  if (s.length <= cap) return s;
+  return s.slice(0, cap) + '…';
+}
+
+/**
+ * Build a single exec-log entry from a tool execution result.
+ *
+ * @param {{ loopIdx: number, toolName: string, args: any, output: any, isError: boolean }} p
+ * @returns {object}
+ */
+export function buildEntry({ loopIdx, toolName, args, output, isError }) {
+  const argsBrief = brief(args, ARGS_BRIEF_CAP);
+  const resultBrief = brief(output, RESULT_BRIEF_CAP);
+  const resultBytes = typeof output === 'string'
+    ? Buffer.byteLength(output, 'utf8')
+    : Buffer.byteLength(brief(output, 1_000_000), 'utf8');
+  return {
+    loopIdx,
+    toolName,
+    argsHash: argsHashOf(args),
+    argsBrief,
+    resultBrief,
+    resultBytes,
+    resultStatus: isError ? 'error' : 'ok',
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * ExecLog — manages append + read for one Engine instance. Tracks turns in
+ * memory and (if yeaftDir is configured) mirrors them to disk as JSONL.
+ */
+export class ExecLog {
+  /**
+   * @param {{ yeaftDir?: string|null, conversationId?: string|null }} opts
+   */
+  constructor({ yeaftDir = null, conversationId = null } = {}) {
+    this.yeaftDir = yeaftDir || null;
+    this.conversationId = conversationId || 'default';
+    /** @type {Map<number, object[]>} */
+    this.turns = new Map();
+  }
+
+  /** Path for a turn's jsonl file (or null if persistence is disabled). */
+  pathFor(turnIdx) {
+    if (!this.yeaftDir) return null;
+    return path.join(this.yeaftDir, 'tool-log', this.conversationId, `${turnIdx}.jsonl`);
+  }
+
+  /** Append an entry to a given turn's log. */
+  append(turnIdx, entry) {
+    let arr = this.turns.get(turnIdx);
+    if (!arr) { arr = []; this.turns.set(turnIdx, arr); }
+    arr.push(entry);
+    const p = this.pathFor(turnIdx);
+    if (p) {
+      try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf8');
+      } catch {
+        // Best-effort persistence — never break the engine on disk failure.
+      }
+    }
+  }
+
+  /** Read all entries for a turn (memory first; disk on cold-start). */
+  readTurn(turnIdx) {
+    const mem = this.turns.get(turnIdx);
+    if (mem) return mem.slice();
+    const p = this.pathFor(turnIdx);
+    if (!p) return [];
+    try {
+      const txt = fs.readFileSync(p, 'utf8');
+      const out = [];
+      for (const line of txt.split('\n')) {
+        const t = line.trim();
+        if (!t) continue;
+        try { out.push(JSON.parse(t)); } catch { /* skip bad line */ }
+      }
+      this.turns.set(turnIdx, out.slice());
+      return out;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Count exact duplicates of (toolName, argsHash) across the current turn
+   * plus the previous N turns.
+   *
+   * @param {{ toolName: string, argsHash: string, currentTurn: number, lookbackTurns?: number }} q
+   * @returns {number}
+   */
+  dupCount({ toolName, argsHash, currentTurn, lookbackTurns = 2 }) {
+    let count = 0;
+    let lastBrief = '';
+    for (let t = Math.max(0, currentTurn - lookbackTurns); t <= currentTurn; t += 1) {
+      for (const e of this.readTurn(t)) {
+        if (e.toolName === toolName && e.argsHash === argsHash) {
+          count += 1;
+          lastBrief = e.resultBrief || lastBrief;
+        }
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Like dupCount but also returns the most-recent matching resultBrief
+   * (used to compose the duplicate reminder).
+   *
+   * @returns {{ count: number, lastResultBrief: string }}
+   */
+  dupInfo({ toolName, argsHash, currentTurn, lookbackTurns = 2 }) {
+    let count = 0;
+    let lastBrief = '';
+    for (let t = Math.max(0, currentTurn - lookbackTurns); t <= currentTurn; t += 1) {
+      for (const e of this.readTurn(t)) {
+        if (e.toolName === toolName && e.argsHash === argsHash) {
+          count += 1;
+          lastBrief = e.resultBrief || lastBrief;
+        }
+      }
+    }
+    return { count, lastResultBrief: lastBrief };
+  }
+}

package/unify/tool-folding/fallback-stub.js

@@ -0,0 +1,47 @@
+/**
+ * fallback-stub.js — Generated when T2 reflection isn't ready in time
+ * (PR-L). Built synchronously from exec-log entries — no LLM call.
+ */
+
+/**
+ * @param {{ execLogEntries: Array<object>, originalUserMsg?: string }} p
+ * @returns {string}
+ */
+export function buildFallbackStub({ execLogEntries, originalUserMsg }) {
+  const entries = Array.isArray(execLogEntries) ? execLogEntries : [];
+  const N = entries.length;
+  const counts = new Map();
+  for (const e of entries) {
+    counts.set(e.toolName, (counts.get(e.toolName) || 0) + 1);
+  }
+  const tally = [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([name, n]) => `- ${name} × ${n}`)
+    .join('\n');
+
+  const errors = entries.filter(e => e.resultStatus === 'error');
+  const findings = entries
+    .slice(0, 10)
+    .map(e => `- \`${e.toolName}(${e.argsBrief})\` → ${e.resultStatus}: ${e.resultBrief}`)
+    .join('\n');
+
+  const head = originalUserMsg
+    ? `_(Original request: ${String(originalUserMsg).slice(0, 200)})_\n\n`
+    : '';
+
+  return `${head}## What was attempted
+A previous turn executed ${N} tool call${N === 1 ? '' : 's'}; reflection wasn't generated in time, so this is a mechanical summary.
+
+## Key findings
+${findings || '_(no entries)_'}
+
+## Direction check
+- ${errors.length} tool call${errors.length === 1 ? '' : 's'} failed.
+- This is a fallback stub; no semantic analysis was performed.
+
+## Suggested next direction
+Continue per the user's original request; do not assume the previous turn made progress beyond the raw findings above.
+
+## Tool execution log
+${tally || '_(empty)_'}`;
+}

package/unify/tool-folding/index.js

@@ -0,0 +1,123 @@
+/**
+ * tool-folding/index.js — V7 reflection subsystem entry (PR-L).
+ *
+ * Exposes:
+ *   - Constants TOOL_BATCH_SIZE, TURN_SUMMARY_THRESHOLD, DUP_TOOL_THRESHOLD
+ *   - Reflector helpers (T1 sync, T2 async, fallback stub)
+ *   - Helpers for collapsing message ranges into a single assistant
+ *     reflection message
+ *   - Duplicate-reminder text formatter
+ *
+ * The constants are NOT config-driven — V7 design freezes them in code.
+ */
+
+export const TOOL_BATCH_SIZE = 13;
+export const TURN_SUMMARY_THRESHOLD = 5;
+export const DUP_TOOL_THRESHOLD = 3;
+
+export { ExecLog, buildEntry, argsHashOf } from './exec-log.js';
+export { buildReflectionPrompt, REFLECTION_TEMPLATE } from './reflection-prompt.js';
+export { runT1Reflection } from './t1-reflector.js';
+export { runT2Reflection } from './t2-reflector.js';
+export { buildFallbackStub } from './fallback-stub.js';
+
+/**
+ * Collapse messages[startIdx..endIdx] (inclusive) into a single
+ * `{ role: 'assistant', content }` message. Returns a NEW array; does not
+ * mutate the input.
+ *
+ * The original assistant+tool sequence (the action arc) is replaced by the
+ * reflection; user messages within that range stay put (defensive — the
+ * caller normally passes a range that contains only assistant+tool).
+ *
+ * @param {Array} messages
+ * @param {number} startIdx
+ * @param {number} endIdx
+ * @param {string} reflectionContent
+ * @returns {Array}
+ */
+export function collapseRangeToReflection(messages, startIdx, endIdx, reflectionContent) {
+  if (!Array.isArray(messages)) return messages;
+  if (startIdx < 0 || endIdx < startIdx || endIdx >= messages.length) return messages;
+  const before = messages.slice(0, startIdx);
+  const collapsed = messages.slice(startIdx, endIdx + 1);
+  const after = messages.slice(endIdx + 1);
+
+  // Preserve any user messages that happened to appear inside the range
+  // (not expected per V7 spec, but defensive). Everything else (assistant +
+  // tool) is replaced by ONE assistant reflection message.
+  const preservedUsers = collapsed.filter(m => m && m.role === 'user');
+  const reflectionMsg = {
+    role: 'assistant',
+    content: reflectionContent,
+    _reflection: true,
+  };
+  return [...before, ...preservedUsers, reflectionMsg, ...after];
+}
+
+/**
+ * Build the (toolName, argsHash) → 3rd-time reminder text used by the
+ * duplicate-call detector.
+ *
+ * @param {{ toolName: string, count: number, lastResultBrief: string }} p
+ * @returns {string}
+ */
+export function buildDuplicateReminder({ toolName, count, lastResultBrief }) {
+  return `[system note] You have called ${toolName} with the same arguments ${count} times. `
+    + `Previous result: ${(lastResultBrief || '').trim()}. `
+    + `Consider whether re-running this tool is necessary or if you should try a different approach.`;
+}
+
+/**
+ * Convert assistant.toolCalls + matching tool results into the
+ * { name, input, output, isError } pairs the reflector prompt expects.
+ *
+ * Walks `messages[startIdx..endIdx]` and pairs each tool_use with its
+ * tool_result by toolCallId. Unpaired tool_use entries are dropped.
+ *
+ * @param {Array} messages
+ * @param {number} startIdx
+ * @param {number} endIdx
+ * @returns {{ pairs: Array, assistantText: string }}
+ */
+export function extractToolPairsFromRange(messages, startIdx, endIdx) {
+  const pairs = [];
+  const byId = new Map();
+  let assistantText = '';
+  const lo = Math.max(0, startIdx);
+  const hi = Math.min(messages.length - 1, endIdx);
+  for (let i = lo; i <= hi; i += 1) {
+    const m = messages[i];
+    if (!m) continue;
+    if (m.role === 'assistant') {
+      if (typeof m.content === 'string' && m.content) {
+        assistantText += (assistantText ? '\n' : '') + m.content;
+      }
+      const calls = Array.isArray(m.toolCalls) ? m.toolCalls : [];
+      for (const tc of calls) {
+        const ent = { name: tc.name, input: tc.input, output: '', isError: false, _id: tc.id };
+        pairs.push(ent);
+        if (tc.id) byId.set(tc.id, ent);
+      }
+    } else if (m.role === 'tool') {
+      const ent = m.toolCallId ? byId.get(m.toolCallId) : null;
+      if (ent) {
+        ent.output = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        ent.isError = !!m.isError;
+      } else {
+        // Orphan tool result — still include for completeness.
+        pairs.push({
+          name: '(orphan)',
+          input: {},
+          output: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+          isError: !!m.isError,
+        });
+      }
+    }
+  }
+  // Strip internal _id field before returning.
+  return {
+    pairs: pairs.map(({ name, input, output, isError }) => ({ name, input, output, isError })),
+    assistantText,
+  };
+}

package/unify/tool-folding/reflection-prompt.js

@@ -0,0 +1,74 @@
+/**
+ * reflection-prompt.js — V7 reflection prompt builder (PR-L).
+ *
+ * One template, used by both T1 (in-turn) and T2 (end-of-turn) reflectors.
+ * The primary model is asked to REFLECT on a sequence of tool calls — not
+ * just summarise. The output is markdown with five fixed sections so the
+ * frontend ReflectionCard can render each independently.
+ */
+
+const TEMPLATE = `You are reviewing a sequence of {N} tool calls executed by an AI agent.
+Your job is NOT just to summarize, but to REFLECT.
+
+Output as markdown with these exact sections:
+
+## What was attempted
+2-3 sentences on the goal and action arc.
+
+## Key findings
+Concrete facts: paths, line numbers, IDs, error codes (preserve verbatim).
+
+## Direction check
+- Is the trajectory still aligned with the user's original request?
+- Any drift / scope creep?
+- Any tool calls that look redundant?
+- Any signs of unproductive loops?
+
+## Suggested next direction
+What should the next loop focus on? What should it AVOID?
+
+## Tool execution log
+Compact list: <tool_name> × <count> (with notable args).
+
+CRITICAL: Preserve all identifiers, paths, URLs, line numbers, and error
+messages literally. Do NOT paraphrase data values.
+
+User original request:
+{originalUserMessage}
+
+Tool execution sequence:
+{toolCallsAndResults}`;
+
+/**
+ * Render the prompt.
+ *
+ * @param {{ originalUserMsg: string, toolPairs: Array<{ name: string, input: any, output: string, isError: boolean }>, assistantText?: string }} p
+ * @returns {string}
+ */
+export function buildReflectionPrompt({ originalUserMsg, toolPairs, assistantText }) {
+  const N = toolPairs.length;
+  const seq = toolPairs.map((p, i) => formatPair(i + 1, p)).join('\n\n');
+  const head = assistantText && assistantText.trim()
+    ? `Assistant text emitted during this batch:\n${assistantText.trim()}\n\n`
+    : '';
+  return TEMPLATE
+    .replace('{N}', String(N))
+    .replace('{originalUserMessage}', String(originalUserMsg || '').slice(0, 4000))
+    .replace('{toolCallsAndResults}', head + seq);
+}
+
+function formatPair(idx, p) {
+  let inputStr;
+  try { inputStr = JSON.stringify(p.input); } catch { inputStr = String(p.input); }
+  if (typeof inputStr === 'string' && inputStr.length > 1000) {
+    inputStr = inputStr.slice(0, 1000) + '…';
+  }
+  let outputStr = typeof p.output === 'string' ? p.output : (() => {
+    try { return JSON.stringify(p.output); } catch { return String(p.output); }
+  })();
+  if (outputStr.length > 2000) outputStr = outputStr.slice(0, 2000) + '…';
+  const status = p.isError ? ' [ERROR]' : '';
+  return `[${idx}] ${p.name}${status}\n  args: ${inputStr}\n  result: ${outputStr}`;
+}
+
+export const REFLECTION_TEMPLATE = TEMPLATE;

package/unify/tool-folding/t1-reflector.js

@@ -0,0 +1,41 @@
+/**
+ * t1-reflector.js — V7 in-turn (synchronous) reflection (PR-L).
+ *
+ * Triggered when the current turn has accumulated TOOL_BATCH_SIZE (13) tool
+ * results and the engine is about to loop back into adapter.stream(). Calls
+ * the PRIMARY model — never the fast model — to generate a markdown
+ * reflection over the batch.
+ *
+ * On success: returns { content, durationMs }.
+ * On failure: throws (engine catches and leaves history unchanged).
+ */
+
+import { buildReflectionPrompt } from './reflection-prompt.js';
+
+/**
+ * @param {{
+ *   adapter: { call: Function },
+ *   model: string,
+ *   originalUserMsg: string,
+ *   toolPairs: Array<{ name: string, input: any, output: string, isError: boolean }>,
+ *   assistantText?: string,
+ *   signal?: AbortSignal,
+ * }} p
+ * @returns {Promise<{ content: string, durationMs: number }>}
+ */
+export async function runT1Reflection({ adapter, model, originalUserMsg, toolPairs, assistantText, signal }) {
+  const t0 = Date.now();
+  const prompt = buildReflectionPrompt({ originalUserMsg, toolPairs, assistantText });
+  const result = await adapter.call({
+    model,
+    system: prompt,
+    messages: [{ role: 'user', content: 'Produce the reflection now.' }],
+    maxTokens: 2048,
+    signal,
+  });
+  const content = (result && typeof result.text === 'string') ? result.text.trim() : '';
+  if (!content) {
+    throw new Error('T1 reflection returned empty content');
+  }
+  return { content, durationMs: Date.now() - t0 };
+}

package/unify/tool-folding/t2-reflector.js

@@ -0,0 +1,39 @@
+/**
+ * t2-reflector.js — V7 end-of-turn (asynchronous) reflection (PR-L).
+ *
+ * Same prompt and primary-model call as T1, but kicked off without await.
+ * The engine stores the resulting promise on the instance; on the next
+ * query() it checks (non-blocking) whether the promise has resolved and
+ * either rewrites history with the reflection or falls back to the
+ * exec-log stub.
+ */
+
+import { buildReflectionPrompt } from './reflection-prompt.js';
+
+/**
+ * @param {{
+ *   adapter: { call: Function },
+ *   model: string,
+ *   originalUserMsg: string,
+ *   toolPairs: Array<{ name: string, input: any, output: string, isError: boolean }>,
+ *   assistantText?: string,
+ *   signal?: AbortSignal,
+ * }} p
+ * @returns {Promise<{ content: string, durationMs: number }>}
+ */
+export async function runT2Reflection({ adapter, model, originalUserMsg, toolPairs, assistantText, signal }) {
+  const t0 = Date.now();
+  const prompt = buildReflectionPrompt({ originalUserMsg, toolPairs, assistantText });
+  const result = await adapter.call({
+    model,
+    system: prompt,
+    messages: [{ role: 'user', content: 'Produce the reflection now.' }],
+    maxTokens: 2048,
+    signal,
+  });
+  const content = (result && typeof result.text === 'string') ? result.text.trim() : '';
+  if (!content) {
+    throw new Error('T2 reflection returned empty content');
+  }
+  return { content, durationMs: Date.now() - t0 };
+}

package/unify/web-bridge.js

@@ -1006,6 +1006,24 @@ function handleEngineEvent(event, threadId, hctx) {
       }, gid);
       break;
 
+    case 'reflection':
+      // PR-L: V7 tool-history reflection event. Two phases per occurrence:
+      //   status: 'pending' — generation kicked off
+      //   status: 'ready'   — markdown content + durationMs
+      //   status: 'error'   — generation failed (history left unchanged)
+      sendUnifyEvent({
+        type: 'reflection',
+        trigger: event.trigger,
+        status: event.status,
+        loopRange: event.loopRange,
+        toolCount: event.toolCount,
+        content: event.content,
+        durationMs: event.durationMs,
+        error: event.error,
+        threadId,
+      }, gid);
+      break;
+
     case 'debug_turn':
       sendUnifyEvent({
         type: 'debug_turn',