@yeaft/webchat-agent 1.0.504 → 1.0.506

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.504",
+  "version": "1.0.506",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/cli.js

@@ -388,6 +388,7 @@ async function runREPL(config, args) {
     content: m.content,
     ...(m.toolCallId && { toolCallId: m.toolCallId }),
     ...(m.toolCalls && { toolCalls: m.toolCalls }),
+    ...(m.providerState && { providerState: m.providerState }),
     ...(Array.isArray(m.thinkingBlocks) && m.thinkingBlocks.length > 0
       ? { thinkingBlocks: m.thinkingBlocks.map(block => ({ ...block })) }
       : {}),
@@ -908,6 +909,7 @@ async function runStreamJson(config, args) {
     content: message.content,
     ...(message.toolCallId && { toolCallId: message.toolCallId }),
     ...(message.toolCalls && { toolCalls: message.toolCalls }),
+    ...(message.providerState && { providerState: message.providerState }),
     ...(Array.isArray(message.thinkingBlocks) && message.thinkingBlocks.length > 0
       ? { thinkingBlocks: message.thinkingBlocks.map(block => ({ ...block })) }
       : {}),
@@ -1263,6 +1265,7 @@ async function runOnce(config, args) {
       content: m.content,
       ...(m.toolCallId && { toolCallId: m.toolCallId }),
       ...(m.toolCalls && { toolCalls: m.toolCalls }),
+      ...(m.providerState && { providerState: m.providerState }),
       ...(Array.isArray(m.thinkingBlocks) && m.thinkingBlocks.length > 0
         ? { thinkingBlocks: m.thinkingBlocks.map(block => ({ ...block })) }
         : {}),

package/yeaft/config-api.js

@@ -12,7 +12,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { DEFAULT_YEAFT_DIR } from './init.js';
 import { normalizeProviderModels, parseModelRef, serializeModelForPersistence } from './models.js';
-import { normaliseTelemetrySection, normaliseYeaftSection } from './config.js';
+import { clampYeaftField, normaliseTelemetrySection, normaliseYeaftSection } from './config.js';
 import { normaliseBrowserRuntimeSection, validateBrowserRuntimeUpdate } from '../browser-runtime/config.js';
 import { normalizePluginConfig } from './plugins.js';
 import { mutateAgentConfig, readAgentConfigForWrite } from './config-store.js';
@@ -196,7 +196,7 @@ export function updateLlmConfig(update, dir) {
  * stable shape — `normaliseYeaftSection` guarantees that.
  *
  * @param {string} [dir] — Yeaft data directory
- * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number, recentTurnsLimit: number, dream: object } | { error: string }}
+ * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number, recentTurnsLimit: number, relatedTurnsLimit: number, dream: object } | { error: string }}
  */
 export function getYeaftSettings(dir) {
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
@@ -215,15 +215,16 @@ export function getYeaftSettings(dir) {
  * Update the Yeaft-section of config.json. Merges into existing config
  * (LLM provider / model fields are untouched) and validates each field:
  * `maxConcurrentThreads` must be 1..50, `autoArchiveIdleDays` must be
- * 1..3650, `recentTurnsLimit` must be 1..500. Dream limits are read-only
+ * 1..3650, `recentTurnsLimit` must be 1..500, `relatedTurnsLimit` must be
+ * 0..10 (0 disables related recall). Dream limits are read-only
  * runtime defaults here; invalid values are rejected
  * outright so the UI sees an error rather than silently reverting — a
  * silent revert would make "I set it to 100 and nothing happened"
  * impossible to debug.
  *
- * @param {{ maxConcurrentThreads?: number, autoArchiveIdleDays?: number, recentTurnsLimit?: number }} update
+ * @param {{ maxConcurrentThreads?: number, autoArchiveIdleDays?: number, recentTurnsLimit?: number, relatedTurnsLimit?: number }} update
  * @param {string} [dir]
- * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number, recentTurnsLimit: number, dream: object } | { error: string }}
+ * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number, recentTurnsLimit: number, relatedTurnsLimit: number, dream: object } | { error: string }}
  */
 export function updateYeaftSettings(update, dir) {
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
@@ -252,6 +253,13 @@ export function updateYeaftSettings(update, dir) {
       return { error: 'recentTurnsLimit must be between 1 and 500' };
     }
   }
+  if (update.relatedTurnsLimit !== undefined) {
+    const value = clampYeaftField(update.relatedTurnsLimit, 'relatedTurnsLimit');
+    const n = Number(update.relatedTurnsLimit);
+    if (value === null || n < 0 || n > 10) {
+      return { error: 'relatedTurnsLimit must be between 0 and 10' };
+    }
+  }
 
   try {
     return mutateAgentConfig(root, existing => {
@@ -266,6 +274,9 @@ export function updateYeaftSettings(update, dir) {
         recentTurnsLimit: update.recentTurnsLimit !== undefined
           ? Math.floor(Number(update.recentTurnsLimit))
           : prev.recentTurnsLimit,
+        relatedTurnsLimit: update.relatedTurnsLimit !== undefined
+          ? clampYeaftField(update.relatedTurnsLimit, 'relatedTurnsLimit')
+          : prev.relatedTurnsLimit,
       };
       if (existing.yeaft?.dream && typeof existing.yeaft.dream === 'object') {
         merged.dream = existing.yeaft.dream;

package/yeaft/config.js

@@ -54,6 +54,9 @@ const DEFAULTS = {
   // bring back after boot or reconnect. Older transcript remains available
   // through history pagination/search. Range: 1–500.
   yeaftRecentTurnsLimit: 20,
+  // Same-Session related Q&A turns, selected by deterministic full-text rules.
+  // Range: 0–10; 0 disables related recall without changing recent history.
+  yeaftRelatedTurnsLimit: 8,
   // CLAUDE.md / AGENTS.md project-doc cap, in bytes. Mirrors Codex's
   // `project_doc_max_bytes`. 0 disables the feature (no project-doc
   // block is injected). Hand-edited values are NOT clamped — we let
@@ -254,13 +257,14 @@ function isTruthy(val) {
  * bounds via `clampYeaftField`.
  *
  * @param {any} raw — jsonConfig.yeaft (may be undefined / malformed)
- * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number, recentTurnsLimit: number, dream: object }}
+ * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number, recentTurnsLimit: number, relatedTurnsLimit: number, dream: object }}
  */
 export function normaliseYeaftSection(raw) {
   const out = {
     maxConcurrentThreads: DEFAULTS.yeaftMaxConcurrentThreads,
     autoArchiveIdleDays: DEFAULTS.yeaftAutoArchiveIdleDays,
     recentTurnsLimit: DEFAULTS.yeaftRecentTurnsLimit,
+    relatedTurnsLimit: DEFAULTS.yeaftRelatedTurnsLimit,
     dream: { ...DEFAULT_LIMITS },
   };
   if (!raw || typeof raw !== 'object') return out;
@@ -270,6 +274,8 @@ export function normaliseYeaftSection(raw) {
   if (ad !== null) out.autoArchiveIdleDays = ad;
   const rt = clampYeaftField(raw.recentTurnsLimit, 'recentTurnsLimit');
   if (rt !== null) out.recentTurnsLimit = rt;
+  const related = clampYeaftField(raw.relatedTurnsLimit, 'relatedTurnsLimit');
+  if (related !== null) out.relatedTurnsLimit = related;
   const dream = raw.dream;
   if (dream && typeof dream === 'object' && !Array.isArray(dream)) {
     for (const key of Object.keys(DEFAULT_LIMITS)) {
@@ -287,17 +293,20 @@ export function normaliseYeaftSection(raw) {
  * (`normaliseYeaftSection`) and write (`updateYeaftSettings` validation).
  *
  * @param {unknown} v
- * @param {'maxConcurrentThreads'|'autoArchiveIdleDays'|'recentTurnsLimit'} field
+ * @param {'maxConcurrentThreads'|'autoArchiveIdleDays'|'recentTurnsLimit'|'relatedTurnsLimit'} field
  * @returns {number | null}
  */
 export function clampYeaftField(v, field) {
   if (v === null || v === undefined) return null;
+  if (field === 'relatedTurnsLimit' &&
+      (typeof v !== 'number' && typeof v !== 'string' || typeof v === 'string' && !v.trim())) return null;
   const n = Number(v);
   if (!Number.isFinite(n)) return null;
   let lo;
   let hi;
   if (field === 'maxConcurrentThreads') { lo = 1; hi = 50; }
   else if (field === 'recentTurnsLimit') { lo = 1; hi = 500; }
+  else if (field === 'relatedTurnsLimit') { lo = 0; hi = 10; }
   else { lo = 1; hi = 3650; } // autoArchiveIdleDays
   return Math.min(hi, Math.max(lo, Math.floor(n)));
 }

package/yeaft/conversation/history-index-worker.js

@@ -10,6 +10,7 @@ import {
   normalizeLiteralSearch,
 } from './visible-entry.js';
 import { fingerprintConversationSources } from './history-index-state.js';
+import { extractRecallTerms, scoreRecallTurn, RECALL_LIMITS } from './recall-relevance.js';
 
 const INDEX_SCHEMA_VERSION = 2;
 const SHORT_BLOOM_BYTES = 256;
@@ -423,6 +424,155 @@ function queryIndex(request) {
   }
 }
 
+// Candidate discovery and complete-turn reads share one worker operation and
+// immutable index generation. Only bounded metadata is read before byte checks.
+function recallTurns(request) {
+  const db = openDatabase(workerData.databasePath);
+  try {
+    const indexMeta = readMeta(db);
+    const generation = Number(indexMeta.generation) || 0;
+    const terms = extractRecallTerms(request.prompt);
+    const cap = (value, fallback) => Math.min(fallback, Math.max(1, Math.floor(Number(value) || fallback)));
+    const limit = cap(request.limit, 10);
+    const maxTurnRows = cap(request.maxTurnRows, RECALL_LIMITS.maxTurnRows);
+    const maxTurnBytes = cap(request.maxTurnBytes, RECALL_LIMITS.maxTurnBytes);
+    const maxReadBytes = cap(request.maxReadBytes, RECALL_LIMITS.maxReadBytes);
+    const beforeSeq = Number.isFinite(request.beforeSeq) ? request.beforeSeq : Number.MAX_SAFE_INTEGER;
+    const meta = {
+      status: 'ready', reason: 'no_match', terms, indexGeneration: generation,
+      candidateRowsRead: 0, boundaryRowsRead: 0, turnRowsRead: 0, readBytes: 0,
+      skippedOversizedTurns: 0, skippedFencedTurns: 0, candidateCapped: false,
+      limits: { ...RECALL_LIMITS, maxTurnRows, maxTurnBytes, maxReadBytes, limit },
+      ...indexStats(indexMeta),
+    };
+    const sourceBefore = currentSourceToken();
+    if (sourceBefore.fingerprint !== indexMeta.raw_source_fingerprint) {
+      return { turns: [], meta: { ...meta, status: 'not_ready', reason: 'stale_result' } };
+    }
+    const candidates = new Map();
+    const candidateById = db.prepare(`SELECT entry_id,entry_start_seq,entry_end_seq,role
+      FROM entries WHERE rowid=? AND session_id=? AND role IN ('user','assistant') AND entry_end_seq<?`);
+    const addCandidate = row => {
+      if (!row) return;
+      if (candidates.size < RECALL_LIMITS.maxCandidates) candidates.set(row.entry_id, row);
+      else meta.candidateCapped = true;
+    };
+    const shortTerms = terms.filter(term => codePoints(term).length < 3);
+    for (const term of terms.filter(term => codePoints(term).length >= 3)) {
+      const chars = codePoints(normalizeLiteralSearch(term));
+      const grams = [...new Set([chars.slice(0, 3).join(''), chars.slice(-3).join('')])];
+      const match = grams.map(gram => `"${gram.replaceAll('"', '""')}"`).join(' AND ');
+      // Fixed trigram prefix, not exhaustive term search: false positives or
+      // rows rejected by the seq fence can consume all 32 slots. Do not scan
+      // additional postings to fill the result; candidateCapped reports this.
+      const ids = db.prepare('SELECT rowid FROM entry_fts WHERE entry_fts MATCH ? ORDER BY rowid ASC LIMIT ?')
+        .all(match, RECALL_LIMITS.candidatesPerTerm + 1);
+      if (ids.length > RECALL_LIMITS.candidatesPerTerm) meta.candidateCapped = true;
+      for (const { rowid } of ids.slice(0, RECALL_LIMITS.candidatesPerTerm)) {
+        meta.candidateRowsRead += 1;
+        addCandidate(candidateById.get(rowid, workerData.sessionId, beforeSeq));
+      }
+    }
+    // Two-character Chinese words cannot use trigram FTS. Scan only a fixed
+    // newest metadata/bloom prefix, never unbounded text or the source JSONL.
+    if (shortTerms.length) {
+      const rows = db.prepare(`SELECT entry_id,entry_start_seq,entry_end_seq,role,short_bloom
+        FROM entries WHERE session_id=? AND entry_end_seq<?
+        ORDER BY entry_end_seq DESC,entry_id DESC LIMIT ?`)
+        .all(workerData.sessionId, beforeSeq, RECALL_LIMITS.shortTermRows);
+      meta.candidateRowsRead += rows.length;
+      if (rows.length === RECALL_LIMITS.shortTermRows) meta.candidateCapped = true;
+      for (const row of rows) {
+        if (shortTerms.some(term => bloomMayContain(row.short_bloom, normalizeLiteralSearch(term)))) addCandidate(row);
+      }
+    }
+    const previousRows = db.prepare(`SELECT entry_id,entry_start_seq,entry_end_seq,role
+      FROM entries WHERE session_id=? AND entry_end_seq<=?
+      ORDER BY entry_end_seq DESC,entry_id DESC LIMIT ?`);
+    const followingRows = db.prepare(`SELECT entry_id,entry_start_seq,entry_end_seq,role,
+        length(CAST(text_body AS BLOB))+length(CAST(source_message_ids AS BLOB)) AS bytes
+      FROM entries WHERE session_id=? AND entry_end_seq>=?
+      ORDER BY entry_end_seq ASC,entry_id ASC LIMIT ?`);
+    const readEntry = db.prepare('SELECT * FROM entries WHERE session_id=? AND entry_id=?');
+    const seenUsers = new Set();
+    const turns = [];
+    for (const candidate of [...candidates.values()].sort((a, b) => b.entry_end_seq - a.entry_end_seq)) {
+      let user = candidate.role === 'user' ? candidate : null;
+      if (!user) {
+        const remaining = RECALL_LIMITS.maxBoundaryRows - meta.boundaryRowsRead;
+        if (remaining <= 0) { meta.candidateCapped = true; break; }
+        for (const row of previousRows.iterate(workerData.sessionId, candidate.entry_start_seq, remaining)) {
+          meta.boundaryRowsRead += 1;
+          if (row.role === 'user') { user = row; break; }
+        }
+      }
+      if (!user || seenUsers.has(user.entry_id)) continue;
+      seenUsers.add(user.entry_id);
+      if (user.entry_start_seq >= beforeSeq) continue;
+      const rows = [];
+      let complete = true;
+      let bytes = 0;
+      for (const row of followingRows.iterate(workerData.sessionId, user.entry_start_seq, maxTurnRows + 1)) {
+        meta.turnRowsRead += 1;
+        if (row.role === 'user' && row.entry_id !== user.entry_id) break;
+        rows.push(row);
+        bytes += Number(row.bytes) || 0;
+        if (rows.length > maxTurnRows || bytes > maxTurnBytes) {
+          complete = false;
+          meta.skippedOversizedTurns += 1;
+          break;
+        }
+      }
+      if (!complete) continue;
+      if (rows.some(row => row.entry_end_seq >= beforeSeq)) {
+        meta.skippedFencedTurns += 1;
+        continue;
+      }
+      if (meta.readBytes + bytes > maxReadBytes) { meta.candidateCapped = true; continue; }
+      const messages = rows.map(row => {
+        const full = readEntry.get(workerData.sessionId, row.entry_id);
+        const entry = parseEntry(full, generation);
+        return { ...entry, id: entry.entryId, sessionId: workerData.sessionId, content: full.text_body };
+      });
+      meta.readBytes += bytes;
+      turns.push({ id: user.entry_id, userSeq: Number(user.entry_start_seq), messages });
+    }
+    const termDocumentFrequency = Object.create(null);
+    for (const term of terms) termDocumentFrequency[term.toLocaleLowerCase()] = 0;
+    for (const turn of turns) {
+      turn.relevance = scoreRecallTurn(terms, turn.messages.map(message => message.content).join('\n'));
+      for (const term of turn.relevance.matchedTerms) termDocumentFrequency[term.toLocaleLowerCase()] += 1;
+    }
+    const stats = { sampleSize: turns.length, termDocumentFrequency };
+    const rejections = {};
+    for (const turn of turns) {
+      turn.relevance = scoreRecallTurn(terms, turn.messages.map(message => message.content).join('\n'), stats);
+      turn.score = turn.relevance.score;
+      turn.matchedTerms = turn.relevance.matchedTerms;
+      if (!turn.score) rejections[turn.relevance.reason] = (rejections[turn.relevance.reason] || 0) + 1;
+    }
+    const selected = turns.filter(turn => turn.score > 0)
+      .sort((a, b) => b.score - a.score || b.userSeq - a.userSeq).slice(0, limit);
+    if (workerData.testHooksEnabled && request._testBarrier instanceof SharedArrayBuffer) {
+      const barrier = new Int32Array(request._testBarrier);
+      Atomics.store(barrier, 0, 1);
+      Atomics.notify(barrier, 0);
+      while (Atomics.load(barrier, 1) === 0) Atomics.wait(barrier, 1, 0, 100);
+    }
+    const sourceAfter = currentSourceToken();
+    if (sourceBefore.fingerprint !== sourceAfter.fingerprint) {
+      return { turns: [], meta: { ...meta, status: 'not_ready', reason: 'stale_result' } };
+    }
+    return {
+      turns: selected,
+      meta: { ...meta, reason: selected.length ? 'matched' : terms.length ? 'no_match' : 'generic_prompt',
+        ...stats, rejections, sourceFingerprint: sourceAfter.fingerprint },
+    };
+  } finally {
+    db.close();
+  }
+}
+
 function outlineIndex(request) {
   const db = openDatabase(workerData.databasePath);
   try {
@@ -544,6 +694,7 @@ async function run() {
       try {
         let result;
         if (op === 'search') result = queryIndex(payload);
+        else if (op === 'recall-turns') result = recallTurns(payload);
         else if (op === 'outline') result = outlineIndex(payload);
         else if (op === 'validate-anchor') result = validateAnchor(payload);
         else if (op === 'validate-and-read-window') result = validateAndReadWindow(payload);

package/yeaft/conversation/history-index.js

@@ -2,6 +2,7 @@ import { Worker } from 'node:worker_threads';
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { writeAtomic } from '../storage/atomic.js';
+import { extractRecallTerms, scoreRecallTurn } from './recall-relevance.js';
 import {
   conversationIndexDatabasePath,
   conversationIndexManifestPath,
@@ -11,6 +12,7 @@ import {
 } from './history-index-state.js';
 
 const MAX_REBUILD_RETRIES = 3;
+const RECALL_WAIT_MS = 1_500;
 const MAX_HISTORY_INDEX_MANAGERS = 8;
 const HISTORY_INDEX_IDLE_MS = 5 * 60_000;
 const DESTRUCTIVE_MUTATION_REASONS = new Set([
@@ -103,7 +105,6 @@ class HistoryIndexQueryWorker {
         testHooksEnabled: process.env.NODE_ENV === 'test',
       },
     });
-    this.worker.unref();
     this.worker.on('message', message => {
       if (message?.type === 'fatal') {
         this.#rejectAll(new Error(message.error));
@@ -112,6 +113,7 @@ class HistoryIndexQueryWorker {
       const pending = this.pending.get(message?.requestId);
       if (!pending) return;
       this.pending.delete(message.requestId);
+      if (this.pending.size === 0) this.worker.unref();
       if (message.error) {
         const error = new Error(message.error);
         if (message.code) error.code = message.code;
@@ -122,17 +124,22 @@ class HistoryIndexQueryWorker {
     this.worker.on('exit', code => {
       if (code !== 0) this.#rejectAll(new Error(`history index query worker exited ${code}`));
     });
+    // Installing a message listener refs the MessagePort again. Idle indexes
+    // must not keep one-shot CLI processes alive; only in-flight reads do.
+    this.worker.unref();
   }
 
   #rejectAll(error) {
     for (const pending of this.pending.values()) pending.reject(error);
     this.pending.clear();
+    this.worker.unref();
   }
 
   request(op, payload) {
     const requestId = `history-index-${process.pid}-${++requestCounter}`;
     return new Promise((resolve, reject) => {
       this.pending.set(requestId, { resolve, reject });
+      this.worker.ref();
       this.worker.postMessage({ requestId, op, payload });
     });
   }
@@ -396,10 +403,62 @@ class SessionHistoryIndex {
     throw error;
   }
 
+  // A newly persisted user invalidates even a warm index on every query. Give
+  // rebuilds a bounded opportunity to catch up, without ever trusting an old
+  // prefix (a destructive mutation may have preceded the latest append).
+  // The first cold call starts a background build; subsequent calls join it.
+  async recall(payload) {
+    const deadline = Date.now() + RECALL_WAIT_MS;
+    const notReady = reason => ({ turns: [], meta: { status: 'not_ready', reason } });
+    const withinDeadline = async promise => {
+      let timer;
+      try {
+        return await Promise.race([
+          promise,
+          new Promise((_, reject) => {
+            timer = setTimeout(() => {
+              const error = new Error('history recall readiness deadline exceeded');
+              error.code = 'index_building';
+              reject(error);
+            }, Math.max(0, deadline - Date.now()));
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+    // Do not cancel a timed-out build: the next query must be able to make
+    // progress, rather than continually restarting a cold or stale rebuild.
+    if (this.rebuildPromise || this.rebuildTimer) await withinDeadline(this.rebuild());
+    await withinDeadline(this.ensureReady({ allowStale: true, waitForBuild: false }));
+    if (readConversationMutationRevision(this.ownerRoot, 'session', this.sessionId)
+      !== Number(this.activeManifest?.sourceRevision)) {
+      await withinDeadline(this.rebuild());
+    }
+    const worker = this.active;
+    const manifest = this.activeManifest;
+    const revision = readConversationMutationRevision(this.ownerRoot, 'session', this.sessionId);
+    if (revision !== Number(manifest?.sourceRevision)) {
+      this.scheduleRebuild();
+      return notReady('stale_result');
+    }
+    // Never retry a result invalidated during its read. Raw source fingerprints
+    // fence external edits too; revision and generation fence manager races.
+    const result = await withinDeadline(worker.request('recall-turns', payload));
+    if (worker !== this.active || manifest !== this.activeManifest
+      || revision !== readConversationMutationRevision(this.ownerRoot, 'session', this.sessionId)
+      || result.meta?.status === 'not_ready') {
+      this.scheduleRebuild();
+      return notReady('stale_result');
+    }
+    return result;
+  }
+
   async request(op, payload) {
     this.leases += 1;
     this.touch();
     try {
+      if (op === 'recall-turns') return await this.recall(payload);
       const mutation = readConversationMutationInfo(this.ownerRoot, 'session', this.sessionId);
       const allowStale = op === 'outline'
         && !payload?.cursor
@@ -494,6 +553,42 @@ export async function searchConversationIndex(ownerRoot, sessionId, query, opts
   });
 }
 
+/**
+ * Recall complete visible user/assistant turns from this owner-root Session.
+ * beforeSeq excludes that user turn and all later rows (exclusive seq fence).
+ * limit defaults to 8, capped at 10. maxTurnRows/maxTurnBytes/maxReadBytes may
+ * only lower hard worker caps. Canonical message IDs identify entries; their
+ * sourceMessageIds preserve all persisted identities, including aggregated VP
+ * replies. The first cold call yields not_ready and starts a background build;
+ * later calls wait up to 1500ms for readiness and the worker read, without
+ * cancelling a timed-out build. Mutations during a read yield not_ready.
+ * Discovery is bounded, not exhaustive: each >=3-character term uses the first
+ * 32 trigram candidates (before seq filtering), and shorter terms only inspect
+ * the newest 512 eligible entry metadata rows. A ready/no_match is not proof
+ * that the entire Session lacks a match; meta.candidateCapped exposes caps.
+ */
+export async function recallConversationTurns(ownerRoot, sessionId, prompt, opts = {}) {
+  const terms = extractRecallTerms(prompt);
+  const eligibility = scoreRecallTurn(terms, terms.join(' '));
+  if (!eligibility.score) {
+    return { turns: [], meta: { status: 'ready', reason: eligibility.reason, terms } };
+  }
+  try {
+    return await requestConversationHistoryIndex(ownerRoot, sessionId, 'recall-turns', {
+      prompt: typeof prompt === 'string' ? prompt.slice(0, 4096) : '',
+      beforeSeq: opts.beforeSeq,
+      limit: Math.min(10, Math.max(1, Math.floor(Number(opts.limit) || 8))),
+      maxTurnRows: opts.maxTurnRows,
+      maxTurnBytes: opts.maxTurnBytes,
+      maxReadBytes: opts.maxReadBytes,
+      ...(process.env.NODE_ENV === 'test' ? { _testBarrier: opts._testBarrier } : {}),
+    });
+  } catch (error) {
+    if (!['index_building', 'stale_result', 'source_changed'].includes(error?.code)) throw error;
+    return { turns: [], meta: { status: 'not_ready', reason: error.code, terms } };
+  }
+}
+
 export async function loadConversationOutlineFromIndex(ownerRoot, sessionId, opts = {}) {
   return requestConversationHistoryIndex(ownerRoot, sessionId, 'outline', {
     ...opts,

package/yeaft/conversation/persist.js

@@ -351,8 +351,10 @@ export function projectVisibleSessionMessages(messages) {
   }
 
   const visible = [];
-  for (const row of rows) {
-    if (!row || (row.role !== 'user' && row.role !== 'assistant')) continue;
+  for (const sourceRow of rows) {
+    if (!sourceRow || (sourceRow.role !== 'user' && sourceRow.role !== 'assistant')) continue;
+    // Public history never owns provider-private continuation payloads.
+    const { providerState, thinkingBlocks, ...row } = sourceRow;
     if (!isVisibleConversationRow(row)) continue;
     if (row.role !== 'assistant' || !Array.isArray(row.toolCalls) || row.toolCalls.length === 0) {
       if (row.role === 'assistant' && !row.content && !row.attachments && !row.images
@@ -502,19 +504,18 @@ function serializeMessage(msg) {
   // bytes that don't need to be human-readable. Without this round-trip
   // the next Anthropic request 400s with "content[].thinking in the
   // thinking mode must be passed back to the API".
-  if (msg.thinkingBlocks && msg.thinkingBlocks.length > 0) {
+  if (msg.providerState) fm.push(`providerStateB64: ${Buffer.from(JSON.stringify(msg.providerState)).toString('base64')}`);
+  if (!msg.providerState && msg.thinkingBlocks && msg.thinkingBlocks.length > 0) {
     fm.push(`thinkingBlocks:`);
     for (const tb of msg.thinkingBlocks) {
-      if (!tb || typeof tb.signature !== 'string' || !tb.signature) continue;
+      if (!tb) continue;
       if (tb.redacted) {
         if (typeof tb.data !== 'string') continue;
         const dataB64 = Buffer.from(tb.data, 'utf8').toString('base64');
-        const signatureB64 = Buffer.from(tb.signature, 'utf8').toString('base64');
         fm.push(`  - redacted: true`);
         fm.push(`    dataB64: ${dataB64}`);
-        fm.push(`    signatureB64: ${signatureB64}`);
       } else {
-        if (typeof tb.thinking !== 'string') continue;
+        if (typeof tb.thinking !== 'string' || typeof tb.signature !== 'string' || !tb.signature) continue;
         const thinkingB64 = Buffer.from(tb.thinking, 'utf8').toString('base64');
         const signatureB64 = Buffer.from(tb.signature, 'utf8').toString('base64');
         fm.push(`  - thinkingB64: ${thinkingB64}`);
@@ -646,7 +647,11 @@ export function parseMessage(raw) {
   }
 
   // task-327d: parse thinkingBlocks (mirror of toolCalls parser above)
-  if (frontmatter.includes('thinkingBlocks:')) {
+  const stateMatch = frontmatter.match(/^providerStateB64: (.+)$/m);
+  if (stateMatch) {
+    try { msg.providerState = JSON.parse(Buffer.from(stateMatch[1], 'base64').toString('utf8')); } catch { /* legacy invalid row */ }
+  }
+  if (!msg.providerState && frontmatter.includes('thinkingBlocks:')) {
     const thinkingBlocks = [];
     const tbMatch = frontmatter.match(/thinkingBlocks:\n((?:\s+-\s+[\s\S]*?)(?=\n\w|$))/);
     if (tbMatch) {
@@ -672,7 +677,7 @@ export function parseMessage(raw) {
         }
         // Both fields required — an unsigned block would 400 on replay.
         if (tb.redacted) {
-          if (typeof tb.data === 'string' && typeof tb.signature === 'string' && tb.signature) {
+          if (typeof tb.data === 'string') {
             thinkingBlocks.push(tb);
           }
         } else if (typeof tb.thinking === 'string' && typeof tb.signature === 'string' && tb.signature) {
@@ -1532,13 +1537,17 @@ export class ConversationStore {
    *
    * @param {string} sessionId — required; null/empty returns []
    * @param {number} [turnsLimit=DEFAULT_RECENT_TURNS]
+   * @param {{includeReflections?: boolean, beforeSeq?: number}} [options]
+   *   beforeSeq anchors the window before a durable user row (exclusive), so
+   *   later queued inputs cannot displace that query's history.
    * @returns {object[]}
    */
-  loadRecentBySession(sessionId, turnsLimit = DEFAULT_RECENT_TURNS, { includeReflections = false } = {}) {
+  loadRecentBySession(sessionId, turnsLimit = DEFAULT_RECENT_TURNS, { includeReflections = false, beforeSeq = Infinity } = {}) {
     if (!sessionId) return [];
     if (turnsLimit === Infinity || turnsLimit < 0) {
       const all = this.#loadSessionMessages(sessionId);
       const filtered = all.filter(m => m && m.sessionId === sessionId
+        && (!Number.isFinite(beforeSeq) || parseSeqFromId(m.id) < beforeSeq)
         && (!isHiddenConversationRow(m) || (includeReflections && m._reflection === true)));
       return pairSanitize(filtered);
     }
@@ -1547,6 +1556,7 @@ export class ConversationStore {
     const { messages, truncated } = this.#loadRecentSessionWindow(sessionId, turnsLimit, {
       roles: null,
       includeReflections,
+      beforeSeq: Number.isFinite(beforeSeq) ? beforeSeq : Infinity,
     });
     if (truncated) {
       maybeWarnHistoryTruncated(sessionId, this.#dir, turnsLimit);
@@ -1616,6 +1626,7 @@ export class ConversationStore {
           const copy = { ...m };
           delete copy.toolCalls;
           delete copy.thinkingBlocks;
+          delete copy.providerState;
           out.push(copy);
         }
         continue;