@yeaft/webchat-agent 1.0.351 → 1.0.352

package/yeaft/llm/anthropic.js

@@ -20,6 +20,7 @@ import {
   redactRawRequest,
   safeHeaders,
   SseLineBuffer,
+  createBoundedTextAccumulator,
   toWellFormedJson,
 } from './adapter.js';
 import {
@@ -242,7 +243,7 @@ export class AnthropicAdapter extends LLMAdapter {
    * @param {{ model: string, system: string, messages: import('./adapter.js').UnifiedMessage[], tools?: import('./adapter.js').UnifiedToolDef[], maxTokens?: number, effort?: 'low'|'medium'|'high'|'xhigh'|'max', effortSource?: 'user'|'auto', effortContext?: object, signal?: AbortSignal, onRawExchange?: ({rawRequest, rawResponse}) => void }} params
    * @returns {AsyncGenerator<import('./adapter.js').StreamEvent>}
    */
-  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, effortSource, effortContext, signal, onRawExchange, onRequestStart }) {
+  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, effortSource, effortContext, signal, onRawExchange, rawExchangeMaxBytes = 512 * 1024, onRequestStart }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -323,11 +324,10 @@ export class AnthropicAdapter extends LLMAdapter {
     // signature → next turn 400s identically).
     /** @type {Map<number, { kind: string, [k: string]: any }>} */
     const blockByIndex = new Map();
-    // Accumulate raw SSE body verbatim for the debug panel. No truncation:
-    // see `redactRawRequest` in adapter.js for the verbatim-design rationale.
-    // Push-then-join keeps allocation bounded for multi-MiB payloads (avoids
-    // O(n²) string concat).
-    const rawSseBodyChunks = [];
+    // Keep raw SSE chunks only until the engine receives the bounded exchange
+    // callback. The engine owns the configured byte budget; the adapter avoids
+    // quadratic string concatenation by storing chunks separately.
+    const rawSseBody = createBoundedTextAccumulator(rawExchangeMaxBytes);
     const responseHeaders = safeHeaders(response);
     const responseStatus = response.status;
     let sawStop = false;
@@ -344,7 +344,7 @@ export class AnthropicAdapter extends LLMAdapter {
         if (done) break;
 
         const chunkText = decoder.decode(value, { stream: true });
-        rawSseBodyChunks.push(chunkText);
+        rawSseBody.push(chunkText);
         const lines = sseLines.push(chunkText);
 
         for (const line of lines) {
@@ -515,8 +515,11 @@ export class AnthropicAdapter extends LLMAdapter {
             rawResponse: {
               status: responseStatus,
               headers: responseHeaders,
-              body: rawSseBodyChunks.join(''),
+              body: rawSseBody.text(),
               format: 'sse',
+              truncated: rawSseBody.truncated,
+              originalBytes: rawSseBody.totalBytes,
+              maxBytes: rawSseBody.maxBytes,
             },
           });
         } catch { /* ignore */ }

package/yeaft/llm/openai-responses.js

@@ -39,6 +39,7 @@ import {
   redactRawRequest,
   safeHeaders,
   SseLineBuffer,
+  createBoundedTextAccumulator,
   toWellFormedJson,
 } from './adapter.js';
 import {
@@ -259,7 +260,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
    * `api-key` headers are auto-redacted (see `redactRawRequest` in
    * `adapter.js`); request-body fields are caller-controlled.
    */
-  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, effortSource, effortContext = {}, extraBody, signal, onRawExchange, onRequestStart }) {
+  async *stream({ model, system, messages, tools, maxTokens = 16384, effort, effortSource, effortContext = {}, extraBody, signal, onRawExchange, rawExchangeMaxBytes = 512 * 1024, onRequestStart }) {
     if (signal?.aborted) throw new LLMAbortError();
 
     const body = {
@@ -346,11 +347,10 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
     const emittedToolCallIds = new Set();
     let sawToolCall = false;
 
-    // Accumulate raw SSE body verbatim for the debug panel. No truncation:
-    // see `redactRawRequest` in adapter.js for the verbatim-design rationale.
-    // Push-then-join keeps allocation bounded for multi-MiB payloads (avoids
-    // O(n²) string concat).
-    const rawSseBodyChunks = [];
+    // Keep raw SSE chunks only until the engine receives the bounded exchange
+    // callback. The engine owns the configured byte budget; the adapter avoids
+    // quadratic string concatenation by storing chunks separately.
+    const rawSseBody = createBoundedTextAccumulator(rawExchangeMaxBytes);
     const responseHeaders = safeHeaders(response);
     const responseStatus = response.status;
     let sawTerminalEvent = false;
@@ -364,7 +364,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
         });
         if (done) break;
         const chunkText = decoder.decode(value, { stream: true });
-        rawSseBodyChunks.push(chunkText);
+        rawSseBody.push(chunkText);
 
         // SSE events are separated by blank lines; SseLineBuffer yields each
         // completed line (newline stripped) in O(n) total.
@@ -503,8 +503,11 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
             rawResponse: {
               status: responseStatus,
               headers: responseHeaders,
-              body: rawSseBodyChunks.join(''),
+              body: rawSseBody.text(),
               format: 'sse',
+              truncated: rawSseBody.truncated,
+              originalBytes: rawSseBody.totalBytes,
+              maxBytes: rawSseBody.maxBytes,
             },
           });
         } catch { /* ignore */ }

package/yeaft/llm/router.js

@@ -610,7 +610,7 @@ export class AdapterRouter extends LLMAdapter {
       const filtered = filterEffortForModel({ ...params, model: resolved.modelId }, resolved);
       const sanitized = sanitizeMessagesForWire(filtered);
       try {
-        yield* resolved.adapter.stream({ ...sanitized, model: resolved.modelId, effortContext });
+        yield* resolved.adapter.stream({ ...sanitized, model: resolved.modelId, effortContext, rawExchangeMaxBytes: params.rawExchangeMaxBytes });
         return;
       } catch (err) {
         this.#annotateAuthError(err, provider, params.model);

package/yeaft/perf-trace.js

@@ -1,20 +1,88 @@
 import { appendFileSync, mkdirSync, readdirSync, rmSync } from 'fs';
 import { join } from 'path';
+import { normalizeUtf8ByteBudget, toWellFormedText, utf8PrefixWithinBytes } from './utf8.js';
 
 const MAX_DETAIL_STRING = 512;
 const DEFAULT_RETENTION_DAYS = 3;
-let lastCleanupDay = null;
+const DEFAULT_FLUSH_INTERVAL_MS = 1_000;
+const DEFAULT_MAX_QUEUE_SIZE = 5_000;
+const DEFAULT_RAW_EXCHANGE_MAX_BYTES = 512 * 1024;
+const lastCleanupDays = new Map();
+const queues = new Map();
+const flushTimers = new Map();
 
-function retentionDays() {
-  const raw = Number(process.env.PERF_TRACE_RETENTION_DAYS || process.env.YEAFT_PERF_TRACE_RETENTION_DAYS || DEFAULT_RETENTION_DAYS);
-  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_RETENTION_DAYS;
+function telemetryConfig(config) {
+  const value = config?.telemetry && typeof config.telemetry === 'object' ? config.telemetry : {};
+  const number = (candidate, fallback, min, max) => {
+    const parsed = Number(candidate);
+    if (!Number.isFinite(parsed)) return fallback;
+    return Math.min(max, Math.max(min, Math.floor(parsed)));
+  };
+  return {
+    enabled: value.enabled !== false,
+    retentionDays: number(value.retentionDays, DEFAULT_RETENTION_DAYS, 1, 3650),
+    flushIntervalMs: number(value.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS, 0, 60_000),
+    maxQueueSize: number(value.maxQueueSize, DEFAULT_MAX_QUEUE_SIZE, 100, 50_000),
+    rawExchangeMaxBytes: number(value.rawExchangeMaxBytes, DEFAULT_RAW_EXCHANGE_MAX_BYTES, 0, 4 * 1024 * 1024),
+    traceTextMaxBytes: number(value.traceTextMaxBytes, 256 * 1024, 0, 4 * 1024 * 1024),
+  };
+}
+
+export function resolveAgentLocalRoot(config) {
+  for (const candidate of [config?.yeaftDir, config?.dir]) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim();
+  }
+  return null;
+}
+
+function queueKey(config) {
+  return resolveAgentLocalRoot(config);
+}
+
+export function truncateUtf8Text(value, maxBytes = DEFAULT_RAW_EXCHANGE_MAX_BYTES) {
+  const limit = normalizeUtf8ByteBudget(maxBytes, DEFAULT_RAW_EXCHANGE_MAX_BYTES);
+  const text = toWellFormedText(value);
+  const originalBytes = Buffer.byteLength(text, 'utf8');
+  if (originalBytes <= limit) return { value: text, truncated: false, originalBytes };
+
+  // One code-point pass avoids the old repeated slice + Buffer.byteLength()
+  // backtracking loop, which could stall the event loop on a large raw
+  // request or response. The shared helper also refuses to split surrogate
+  // pairs and normalizes lone surrogates before producing a preview.
+  const prefix = utf8PrefixWithinBytes(text, limit);
+  return { value: prefix.text, truncated: true, originalBytes };
 }
 
-function cleanupOldTraceFiles(root) {
+export function boundRawExchange(value, maxBytes = DEFAULT_RAW_EXCHANGE_MAX_BYTES) {
+  const limit = normalizeUtf8ByteBudget(maxBytes, DEFAULT_RAW_EXCHANGE_MAX_BYTES);
+  if (value == null || limit <= 0) return limit <= 0 && value != null ? { __truncated: true, maxBytes: limit } : value;
+  if (typeof value === 'string') {
+    const result = truncateUtf8Text(value, limit);
+    return result.truncated ? { __truncated: true, maxBytes: limit, originalBytes: result.originalBytes, preview: result.value } : result.value;
+  }
+  try {
+    const json = JSON.stringify(value);
+    const result = truncateUtf8Text(json, limit);
+    if (!result.truncated) return JSON.parse(json);
+    return { __truncated: true, maxBytes: limit, originalBytes: result.originalBytes, preview: result.value };
+  } catch {
+    return { __truncated: true, maxBytes: limit };
+  }
+}
+
+function retentionDays(config) {
+  const configured = Number(telemetryConfig(config).retentionDays);
+  const env = Number(process.env.PERF_TRACE_RETENTION_DAYS || process.env.YEAFT_PERF_TRACE_RETENTION_DAYS);
+  if (Number.isFinite(env) && env > 0) return Math.floor(env);
+  return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_RETENTION_DAYS;
+}
+
+function cleanupOldTraceFiles(root, config = null) {
   const day = new Date().toISOString().slice(0, 10);
-  if (lastCleanupDay === day) return;
-  lastCleanupDay = day;
-  const keepMs = retentionDays() * 24 * 60 * 60 * 1000;
+  const key = root;
+  if (lastCleanupDays.get(key) === day) return;
+  lastCleanupDays.set(key, day);
+  const keepMs = retentionDays(config) * 24 * 60 * 60 * 1000;
   const cutoff = Date.now() - keepMs;
   try {
     for (const file of readdirSync(root)) {
@@ -57,15 +125,74 @@ export function perfNowMs() {
   return Number(process.hrtime.bigint()) / 1e6;
 }
 
+function flushQueue(key, config) {
+  const queue = queues.get(key);
+  if (!queue || queue.length === 0) return 0;
+  const batch = queue.splice(0, queue.length);
+  const root = join(key, 'perf-traces');
+  const day = new Date().toISOString().slice(0, 10);
+  try {
+    mkdirSync(root, { recursive: true });
+    cleanupOldTraceFiles(root, config);
+    appendFileSync(join(root, `${day}.jsonl`), batch.map(row => JSON.stringify(row)).join('\n') + '\n');
+    return batch.length;
+  } catch (err) {
+    // Put the batch back only when the queue has room. Losing diagnostics is
+    // preferable to blocking the engine or growing memory without a bound.
+    const limit = telemetryConfig(config).maxQueueSize;
+    queues.set(key, [...batch.slice(-limit), ...(queues.get(key) || [])].slice(-limit));
+    if (process.env.YEAFT_PERF_TRACE_DEBUG === '1') {
+      console.warn('[Yeaft] perf trace write failed:', err?.message || err);
+    }
+    return 0;
+  }
+}
+
+function scheduleFlush(key, config) {
+  if (flushTimers.has(key)) return;
+  const delay = telemetryConfig(config).flushIntervalMs;
+  if (delay <= 0) {
+    queueMicrotask(() => flushQueue(key, config));
+    return;
+  }
+  const timer = setTimeout(() => {
+    flushTimers.delete(key);
+    flushQueue(key, config);
+  }, delay);
+  if (typeof timer.unref === 'function') timer.unref();
+  flushTimers.set(key, timer);
+}
+
+export function flushAgentPerfTrace(config) {
+  const key = queueKey(config);
+  if (!key) return 0;
+  const timer = flushTimers.get(key);
+  if (timer) {
+    clearTimeout(timer);
+    flushTimers.delete(key);
+  }
+  return flushQueue(key, config);
+}
+
+export function flushAllAgentPerfTraces() {
+  let count = 0;
+  for (const [key, queue] of queues) {
+    if (!queue.length) continue;
+    const config = { yeaftDir: key };
+    count += flushQueue(key, config);
+  }
+  for (const timer of flushTimers.values()) clearTimeout(timer);
+  flushTimers.clear();
+  return count;
+}
+
 export function recordAgentPerfTrace(config, event = {}) {
   const traceId = typeof event.traceId === 'string' && event.traceId.trim()
     ? event.traceId.trim()
     : (typeof event.perfTraceId === 'string' && event.perfTraceId.trim() ? event.perfTraceId.trim() : null);
-  if (!traceId) return false;
-  const yeaftDir = config?.yeaftDir;
-  if (typeof yeaftDir !== 'string' || !yeaftDir.trim()) return false;
-  const root = join(yeaftDir.trim(), 'perf-traces');
-  const day = new Date().toISOString().slice(0, 10);
+  const key = queueKey(config);
+  const settings = telemetryConfig(config);
+  if (!traceId || !key || !settings.enabled) return false;
   const row = {
     traceId,
     source: 'agent',
@@ -82,20 +209,25 @@ export function recordAgentPerfTrace(config, event = {}) {
     ok: typeof event.ok === 'boolean' ? event.ok : null,
     detail: sanitizeValue(event.detail || null),
   };
-  try {
-    mkdirSync(root, { recursive: true });
-    cleanupOldTraceFiles(root);
-    appendFileSync(join(root, `${day}.jsonl`), `${JSON.stringify(row)}\n`);
-    return true;
-  } catch (err) {
-    if (process.env.YEAFT_PERF_TRACE_DEBUG === '1') {
-      console.warn('[Yeaft] perf trace write failed:', err?.message || err);
-    }
-    return false;
-  }
+  const queue = queues.get(key) || [];
+  if (queue.length >= settings.maxQueueSize) queue.shift();
+  queue.push(row);
+  queues.set(key, queue);
+  // Never write synchronously from the engine phase hook. The timer batches
+  // events across the turn; session shutdown calls flushAgentPerfTrace() as a
+  // durability boundary for short-lived CLI runs.
+  if (queue.length >= settings.maxQueueSize) flushQueue(key, config);
+  else scheduleFlush(key, config);
+  return true;
 }
 
 export const __perfTraceForTest = {
   sanitizeValue,
   cleanupOldTraceFiles,
+  telemetryConfig,
+  queues,
+  flushTimers,
+  boundRawExchange,
+  truncateUtf8Text,
+  flushAllAgentPerfTraces,
 };

package/yeaft/session.js

@@ -16,6 +16,7 @@
 import { initYeaftDir, DEFAULT_YEAFT_DIR, isWritable } from './init.js';
 import { loadConfig, loadMCPConfig } from './config.js';
 import { createTrace } from './debug-trace.js';
+import { flushAgentPerfTrace } from './perf-trace.js';
 import { createLLMAdapter } from './llm/adapter.js';
 import { withUsageAccounting } from './llm/usage-accounting.js';
 import { recordAgentTokenUsage } from '../metrics.js';
@@ -254,6 +255,7 @@ export async function loadSession(options = {}) {
   const trace = createTrace({
     enabled: config.debug === true,
     dirPath: yeaftDir,
+    textMaxBytes: config.telemetry?.traceTextMaxBytes,
   });
 
   // ─── 4. Create LLM adapter ────────────────────────────
@@ -591,6 +593,11 @@ export async function loadSession(options = {}) {
     } catch {
       // Trace might not have close() (NullTrace)
     }
+    try {
+      flushAgentPerfTrace(config);
+    } catch {
+      // Performance telemetry is best-effort and must not block shutdown.
+    }
     try {
       if (memoryIndex) memoryIndex.close();
     } catch {

package/yeaft/sessions/session-crud.js

@@ -403,14 +403,17 @@ export function restoreSessionToRegistry(defaultYeaftDir, sessionId, workDir) {
   return importedMeta;
 }
 
-export function resolveSessionYeaftDir(defaultYeaftDir, sessionId) {
+/**
+ * Resolve an already-existing Session owner without bootstrapping or migrating
+ * Session storage. Read-only callers must use this instead of
+ * resolveSessionYeaftDir(): the latter intentionally repairs the manifest for
+ * runtime/CRUD entry points.
+ */
+export function findExistingSessionYeaftDir(defaultYeaftDir, sessionId) {
   if (!defaultYeaftDir || !sessionId) return defaultYeaftDir;
 
-  const manifestReady = hasSessionManifest(defaultYeaftDir);
-  ensureSessionManifestReady(defaultYeaftDir);
   const manifestDir = resolveManifestSessionDir(defaultYeaftDir, sessionId);
   if (manifestDir) return join(manifestDir, '..', '..');
-  if (manifestReady) return defaultYeaftDir;
 
   const registry = readWorkDirRegistry(defaultYeaftDir);
   const workDir = normalizeWorkDir(registry[sessionId]);
@@ -426,6 +429,18 @@ export function resolveSessionYeaftDir(defaultYeaftDir, sessionId) {
   return defaultYeaftDir;
 }
 
+export function resolveSessionYeaftDir(defaultYeaftDir, sessionId) {
+  if (!defaultYeaftDir || !sessionId) return defaultYeaftDir;
+
+  const manifestReady = hasSessionManifest(defaultYeaftDir);
+  ensureSessionManifestReady(defaultYeaftDir);
+  const manifestDir = resolveManifestSessionDir(defaultYeaftDir, sessionId);
+  if (manifestDir) return join(manifestDir, '..', '..');
+  if (manifestReady) return defaultYeaftDir;
+
+  return findExistingSessionYeaftDir(defaultYeaftDir, sessionId);
+}
+
 /** Build a safe group id from a display name (slug + ulid-lite suffix). */
 export function makeSessionId(name) {
   const slug = String(name || 'session')

package/yeaft/sub-agent/runner.js

@@ -422,6 +422,10 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
           scenario: 'chat',
           vpPersona,
           sessionId: agent.parentSessionId || deps.parentSessionId || null,
+          // SpawnAgent records the caller-provided cwd on the agent. Thread it
+          // into the child Engine just like a parent query's workDir so child
+          // file tools resolve relative paths in the requested workspace.
+          workDir: agent.cwd,
           projectSessionIds: queuedPrompt.projectSessionIds,
           projectLabel: queuedPrompt.projectLabel,
           projectInstruction: queuedPrompt.projectInstruction,

package/yeaft/tools/agent.js

@@ -341,6 +341,10 @@ use it as the default workflow or call it repeatedly in a loop.`,
   },
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
+  // The child driver is fire-and-forget and inherits writable workspace
+  // tools. A parent query therefore cannot safely reuse filesystem snapshots
+  // after a SpawnAgent call returns.
+  mayMutateWorkspaceAfterReturn: () => true,
   async execute(input, ctx) {
     // NB: every envelope below puts `next_steps` (or `error_next_steps`) at
     // the FIRST position because `agent/yeaft/tools/registry.js` caps tool

package/yeaft/tools/ask-user.js

@@ -56,6 +56,7 @@ Guidelines:
   },
   isConcurrencySafe: () => false,
   isReadOnly: () => true,
+  cacheWithinQuery: false,
   // This is an intentionally user-driven wait, not a stalled tool call.
   timeoutMs: 0,
   async execute(input, ctx) {

package/yeaft/tools/bash.js

@@ -171,6 +171,10 @@ Guidelines:
   timeoutMs: 0,
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
+  // A detached shell task can write after this tool has returned. Once one is
+  // launched, same-query filesystem reads must execute instead of reusing a
+  // snapshot captured before the task's eventual mutation.
+  mayMutateWorkspaceAfterReturn: input => input?.background === true,
   isDestructive: (input) => {
     if (!input?.command) return false;
     const cmd = input.command.toLowerCase();

package/yeaft/tools/create-work-item.js

@@ -49,6 +49,9 @@ Use this when work must continue beyond the current turn, needs role handoffs, r
   },
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
+  // The Work Center watcher can advance from triage into a writable Action
+  // after creation returns. A paused item has no watcher-owned execution.
+  mayMutateWorkspaceAfterReturn: input => input?.start !== false,
   async execute(input, ctx = {}) {
     const sessionId = typeof ctx.sessionId === 'string' ? ctx.sessionId.trim() : '';
     if (!sessionId) throw new Error('CreateWorkItem requires an active Session');

package/yeaft/tools/file-read.js

@@ -139,6 +139,7 @@ Guidelines:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  cacheWithinQuery: true,
   async execute(input, ctx) {
     const { file_path, offset = 0, column_offset = 0, limit = DEFAULT_LIMIT } = input;
     if (!file_path) return JSON.stringify({ error: 'file_path is required' });

package/yeaft/tools/glob.js

@@ -164,6 +164,7 @@ Guidelines:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  cacheWithinQuery: true,
   async execute(input, ctx) {
     const { pattern, path: searchPath, limit = 500 } = input;
     if (!pattern) return JSON.stringify({ error: 'pattern is required' });

package/yeaft/tools/grep.js

@@ -922,6 +922,7 @@ Guidelines:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  cacheWithinQuery: true,
   async execute(input, ctx) {
     const {
       pattern, path: searchPath, output_mode = 'files_with_matches',

package/yeaft/tools/history-search.js

@@ -7,6 +7,7 @@
 
 import { defineTool } from './types.js';
 import { searchMessages } from '../conversation/search.js';
+import { findExistingSessionYeaftDir } from '../sessions/session-crud.js';
 
 const DEFAULT_RESULT_LIMIT = 10;
 const MAX_SNIPPET_CHARS = 1000;
@@ -137,7 +138,7 @@ export default defineTool({
   description: {
     en: `Search through past conversation history.
 
-Searches message content for all whitespace-separated terms (case-insensitive).
+Searches message content for all whitespace-separated terms (case-insensitive) from persisted Session history.
 Inside a Session, search is limited to that Session plus sibling Sessions in the same Project on this Agent. Tool-result messages are excluded. Useful for finding previous discussions, decisions, or code snippets.
 
 Results are returned newest-first with a bounded matching snippet and source metadata.`,
@@ -171,7 +172,8 @@ Results are returned newest-first with a bounded matching snippet and source met
   isReadOnly: () => true,
   async execute(input, ctx) {
     const { keyword, limit = DEFAULT_RESULT_LIMIT } = input;
-    if (!keyword) return JSON.stringify({ error: 'keyword is required' });
+    const normalizedKeyword = typeof keyword === 'string' ? keyword.trim() : '';
+    if (!normalizedKeyword) return JSON.stringify({ error: 'keyword is required' });
 
     const yeaftDir = ctx?.yeaftDir;
     if (!yeaftDir) {
@@ -179,44 +181,96 @@ Results are returned newest-first with a bounded matching snippet and source met
     }
 
     try {
-      const telemetry = {};
       const projectSessionIds = Array.isArray(ctx?.projectSessionIds)
         ? ctx.projectSessionIds.filter(id => typeof id === 'string' && id.trim()).map(id => id.trim())
         : [];
       const scopedSessionIds = ctx?.sessionId
         ? Array.from(new Set([ctx.sessionId, ...projectSessionIds]))
         : null;
-      const results = searchMessages(yeaftDir, keyword, limit, {
-        telemetry,
-        ...(scopedSessionIds ? { sessionIds: scopedSessionIds } : {}),
+      const telemetry = {};
+      let indexedResults = [];
+
+      if (scopedSessionIds) {
+        // The index manager builds/rebuilds SQLite state and Session location
+        // repair may migrate the manifest. Both are writes, so they cannot run
+        // behind a read-only/cachable tool declaration. Scan only existing
+        // transcript files; normal Session boot and maintenance own indexing.
+        for (const sessionId of scopedSessionIds) {
+          const storeDir = findExistingSessionYeaftDir(yeaftDir, sessionId);
+          const scanTelemetry = {};
+          const messages = searchMessages(storeDir, normalizedKeyword, limit, {
+            telemetry: scanTelemetry,
+            sessionIds: [sessionId],
+          });
+          telemetry.scannedSessions = (telemetry.scannedSessions || 0) + 1;
+          telemetry.scannedFiles = (telemetry.scannedFiles || 0) + (scanTelemetry.scannedFiles || 0);
+          telemetry.scannedMessages = (telemetry.scannedMessages || 0) + (scanTelemetry.scannedMessages || 0);
+          telemetry.scannedBytes = (telemetry.scannedBytes || 0) + (scanTelemetry.scannedBytes || 0);
+          for (const message of messages) {
+            indexedResults.push({
+              messageId: message.id || null,
+              sessionId: message.sessionId || sessionId,
+              role: message.role,
+              content: buildSnippet(message.content || '', normalizedKeyword),
+              mode: message.mode || null,
+              time: message.time || message.timestamp || null,
+              source: message.historySource || 'session-scan',
+              turnId: message.turnId || null,
+              _seq: 0,
+            });
+          }
+        }
+      } else {
+        // CLI and legacy callers without a Session context retain the old
+        // global search path. The indexed path requires an explicit session
+        // because it is intentionally scoped and owner-safe.
+        const legacyResults = searchMessages(yeaftDir, normalizedKeyword, limit, { telemetry });
+        indexedResults = legacyResults.map(msg => ({
+          messageId: msg.id || null,
+          sessionId: msg.sessionId || null,
+          role: msg.role,
+          content: buildSnippet(msg.content, normalizedKeyword),
+          mode: msg.mode,
+          time: msg.time || msg.timestamp || null,
+          source: msg.historySource || null,
+          _seq: 0,
+        }));
+      }
+
+      indexedResults.sort((a, b) => {
+        const time = String(b.time || '').localeCompare(String(a.time || ''));
+        if (time !== 0) return time;
+        return (b._seq || 0) - (a._seq || 0);
       });
+      const results = indexedResults.slice(0, Math.max(1, Math.min(100, Number(limit) || DEFAULT_RESULT_LIMIT)));
       const searchTelemetry = {
         resultCount: results.length,
-        scannedFiles: telemetry.scannedFiles || 0,
-        scannedMessages: telemetry.scannedMessages || 0,
-        scannedBytes: telemetry.scannedBytes || 0,
+        ...(scopedSessionIds
+          ? {
+              scannedSessions: telemetry.scannedSessions || 0,
+              scannedFiles: telemetry.scannedFiles || 0,
+              scannedMessages: telemetry.scannedMessages || 0,
+              scannedBytes: telemetry.scannedBytes || 0,
+            }
+          : {
+              scannedFiles: telemetry.scannedFiles || 0,
+              scannedMessages: telemetry.scannedMessages || 0,
+              scannedBytes: telemetry.scannedBytes || 0,
+            }),
       };
 
       if (results.length === 0) {
         return serializeHistorySearchOutput({
           results: [],
-          message: `No matches found for "${keyword}"`,
+          message: `No matches found for "${normalizedKeyword}"`,
           telemetry: searchTelemetry,
         });
       }
 
       return serializeHistorySearchOutput({
-        results: results.map(msg => ({
-          messageId: msg.id || null,
-          sessionId: msg.sessionId || null,
-          role: msg.role,
-          content: buildSnippet(msg.content, keyword),
-          mode: msg.mode,
-          time: msg.time || msg.timestamp || null,
-          source: msg.historySource || null,
-        })),
+        results: results.map(({ _seq, ...result }) => result),
         totalResults: results.length,
-        keyword,
+        keyword: normalizedKeyword,
         telemetry: searchTelemetry,
       });
     } catch (err) {

package/yeaft/tools/js-repl.js

@@ -100,6 +100,7 @@ REPL 上下文在多次调用间保持——一次调用中定义的变量和函
   },
   isConcurrencySafe: () => false,
   isReadOnly: () => true,
+  cacheWithinQuery: false,
   async execute(input, ctx) {
     const { code, reset } = input || {};
 

package/yeaft/tools/list-agents.js

@@ -57,6 +57,7 @@ stale/stalled 诊断、result 尾部和消息数量。将此作为异步子 Agen
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  cacheWithinQuery: false,
   async execute(input, ctx) {
     const includeTerminal = Boolean(input?.include_closed || input?.include_terminal);
     const agents = getAgentRegistry();

package/yeaft/tools/list-dir.js

@@ -52,6 +52,7 @@ This is better than using Bash with 'ls' because it provides structured output.`
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  cacheWithinQuery: true,
   async execute(input, ctx) {
     const { path: dirPath, show_hidden = true } = input;