@yeaft/webchat-agent 1.0.208 → 1.0.210

package/yeaft/tools/grep.js

@@ -17,11 +17,15 @@ const MAX_LINES = 250;
 
 /** Hard cap before Grep output reaches history, debug events, or WebSocket. */
 const MAX_OUTPUT_BYTES = 512 * 1024;
+const SEARCH_RESULT_BYTES = 32 * 1024;
 const OUTPUT_TRUNCATED_MARKER = '\n\n[Output truncated]';
 const MAX_CAPTURE_BYTES = MAX_OUTPUT_BYTES - Buffer.byteLength(OUTPUT_TRUNCATED_MARKER, 'utf8');
 
 /** Keep one pathological source line from consuming the whole output budget. */
 const MAX_LINE_BYTES = 16 * 1024;
+const FALLBACK_CONCURRENCY = 8;
+const SKIP_DIRS = new Set(['node_modules', '.git', '__pycache__', '.next', 'dist', 'build', '.cache']);
+let ripgrepAvailability;
 
 /** Binary extensions to skip. */
 const BINARY_EXTS = new Set([
@@ -108,12 +112,22 @@ function createOutputCollector(maxBytes = MAX_OUTPUT_BYTES) {
 /**
  * Check if ripgrep is available.
  */
+export function setRipgrepAvailabilityForTests(value) {
+  ripgrepAvailability = value;
+}
+
 function hasRipgrep() {
-  return new Promise((resolve) => {
+  if (typeof ripgrepAvailability === 'boolean') return Promise.resolve(ripgrepAvailability);
+  if (ripgrepAvailability) return ripgrepAvailability;
+  ripgrepAvailability = new Promise((resolve) => {
     const proc = spawn('rg', ['--version'], { stdio: 'pipe', windowsHide: true });
     proc.on('close', (code) => resolve(code === 0));
     proc.on('error', () => resolve(false));
+  }).then((available) => {
+    ripgrepAvailability = available;
+    return available;
   });
+  return ripgrepAvailability;
 }
 
 /**
@@ -121,15 +135,9 @@ function hasRipgrep() {
  */
 export function runRipgrep(pattern, searchPath, options, spawnProcess = spawn) {
   return new Promise((resolve, reject) => {
-    const args = [
-      pattern,
-      searchPath,
-      '--no-heading',
-      '--line-number',
-      '--color', 'never',
-    ];
-
+    const args = [pattern, searchPath, '--no-heading', '--line-number', '--color', 'never'];
     if (options.caseInsensitive) args.push('-i');
+    if (options.fixedStrings) args.push('-F');
     if (options.glob) args.push('--glob', options.glob);
     if (options.type) args.push('--type', options.type);
     if (options.filesOnly) args.push('-l');
@@ -138,52 +146,92 @@ export function runRipgrep(pattern, searchPath, options, spawnProcess = spawn) {
     if (options.before) args.push('-B', String(options.before));
     if (options.after) args.push('-A', String(options.after));
     if (options.multiline) args.push('-U', '--multiline-dotall');
-    args.push('--max-count', String(options.maxResults || 500));
 
     const proc = spawnProcess('rg', args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    const requestedBudget = Number(options.byteBudget);
+    const stdoutBudget = Number.isFinite(requestedBudget) && requestedBudget >= 0
+      ? Math.min(requestedBudget, MAX_OUTPUT_BYTES)
+      : MAX_OUTPUT_BYTES;
+    const stdoutMarker = truncateUtf8(OUTPUT_TRUNCATED_MARKER, stdoutBudget);
     const stdoutChunks = [];
     const stderrChunks = [];
-    let capturedBytes = 0;
-    let truncatedStream = null;
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let stdoutLines = 0;
+    let stoppedForLimit = false;
+    let stopRequested = false;
     let settled = false;
 
-    function capture(streamName, chunk, chunks) {
-      if (truncatedStream) return;
+    function stop() {
+      if (stopRequested) return;
+      stopRequested = true;
+      try { proc.kill(); } catch {}
+    }
+
+    function captureStdout(chunk) {
+      if (stdoutTruncated || stoppedForLimit) return;
+      let buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const maxResults = Math.max(1, options.maxResults || 500);
+      let cursor = 0;
+      while (stdoutLines < maxResults) {
+        const newline = buffer.indexOf(0x0a, cursor);
+        if (newline === -1) break;
+        stdoutLines += 1;
+        cursor = newline + 1;
+      }
+      if (stdoutLines >= maxResults) {
+        buffer = buffer.subarray(0, cursor);
+        stoppedForLimit = true;
+      }
+
+      const remaining = stdoutBudget - stdoutBytes;
+      if (buffer.length > remaining) {
+        if (remaining > 0) stdoutChunks.push(buffer.subarray(0, remaining));
+        stdoutBytes = stdoutBudget;
+        stdoutTruncated = true;
+      } else {
+        stdoutChunks.push(buffer);
+        stdoutBytes += buffer.length;
+      }
+      if (stdoutTruncated || stoppedForLimit) stop();
+    }
+
+    function captureStderr(chunk) {
+      if (stderrTruncated) return;
       const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-      const remaining = MAX_CAPTURE_BYTES - capturedBytes;
+      const remaining = MAX_OUTPUT_BYTES - stderrBytes;
       if (buffer.length > remaining) {
-        if (remaining > 0) chunks.push(buffer.subarray(0, remaining));
-        capturedBytes = MAX_CAPTURE_BYTES;
-        truncatedStream = streamName;
-        try { proc.kill(); } catch {}
+        if (remaining > 0) stderrChunks.push(buffer.subarray(0, remaining));
+        stderrBytes = MAX_OUTPUT_BYTES;
+        stderrTruncated = true;
+        stop();
         return;
       }
-      chunks.push(buffer);
-      capturedBytes += buffer.length;
+      stderrChunks.push(buffer);
+      stderrBytes += buffer.length;
     }
 
-    function decodeCaptured(chunks, wasTruncated) {
-      // Buffer decoding normally expands each invalid byte to the three-byte
-      // U+FFFD replacement character. Use a one-byte replacement, then enforce
-      // the final encoded-byte boundary as a last line of defense.
-      const marker = wasTruncated ? OUTPUT_TRUNCATED_MARKER : '';
-      const maxTextBytes = MAX_OUTPUT_BYTES - Buffer.byteLength(marker, 'utf8');
+    function decodeCaptured(chunks, maxBytes, wasTruncated, marker = OUTPUT_TRUNCATED_MARKER) {
+      const boundedMarker = wasTruncated ? truncateUtf8(marker, maxBytes) : '';
+      const maxTextBytes = Math.max(0, maxBytes - Buffer.byteLength(boundedMarker, 'utf8'));
       const decoded = Buffer.concat(chunks).toString('utf8').replaceAll('\ufffd', '?').replace(/\r/g, '');
-      return truncateUtf8(decoded, maxTextBytes) + marker;
+      return truncateUtf8(decoded, maxTextBytes) + boundedMarker;
     }
 
-    proc.stdout.on('data', (chunk) => capture('stdout', chunk, stdoutChunks));
-    proc.stderr.on('data', (chunk) => capture('stderr', chunk, stderrChunks));
+    proc.stdout.on('data', captureStdout);
+    proc.stderr.on('data', captureStderr);
     proc.on('close', (code) => {
       if (settled) return;
       settled = true;
-      const stdout = decodeCaptured(stdoutChunks, truncatedStream === 'stdout');
-      const stderr = decodeCaptured(stderrChunks, truncatedStream === 'stderr');
-      if (code === 0 || code === 1 || truncatedStream === 'stdout') resolve(stdout);
+      const stdout = decodeCaptured(stdoutChunks, stdoutBudget, stdoutTruncated, stdoutMarker);
+      const stderr = decodeCaptured(stderrChunks, MAX_OUTPUT_BYTES, stderrTruncated);
+      if (code === 0 || code === 1 || stoppedForLimit || stdoutTruncated) resolve(stdout);
       else reject(new Error(stderr || `rg exited with code ${code}`));
     });
     proc.on('error', (err) => {
-      if (settled) return;
+      if (settled || stopRequested) return;
       settled = true;
       reject(err);
     });
@@ -194,67 +242,94 @@ export function runRipgrep(pattern, searchPath, options, spawnProcess = spawn) {
  * Fallback: Node.js grep implementation.
  */
 export async function nodeGrep(pattern, searchPath, options) {
-  const regex = new RegExp(pattern, options.caseInsensitive ? 'gi' : 'g');
-  const output = createOutputCollector();
+  const regexSource = options.fixedStrings
+    ? pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    : pattern;
+  const regex = new RegExp(regexSource, options.caseInsensitive ? 'gi' : 'g');
+  const output = createOutputCollector(options.byteBudget || SEARCH_RESULT_BYTES);
+  const maxResults = Math.max(1, options.maxResults || 500);
   let resultCount = 0;
-  const SKIP = new Set(['node_modules', '.git', '__pycache__', '.next', 'dist', 'build', '.cache']);
+  let stopped = false;
+
+  function compileGlob(glob) {
+    const escaped = glob.replace(/\\/g, '/')
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*\*/g, '\0').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]')
+      .replace(/\0/g, '.*');
+    return new RegExp(`^${escaped}$`);
+  }
+  const globMatcher = options.glob ? compileGlob(options.glob) : null;
+  const typeExtensions = {
+    js: ['.js', '.jsx', '.mjs', '.cjs'], ts: ['.ts', '.tsx', '.mts', '.cts'],
+    py: ['.py'], rust: ['.rs'], go: ['.go'], java: ['.java'],
+    json: ['.json'], yaml: ['.yaml', '.yml'], markdown: ['.md', '.markdown'],
+    html: ['.html', '.htm'], css: ['.css'], shell: ['.sh', '.bash', '.zsh'],
+  };
+
+  function matchesFilters(fullPath) {
+    const relPath = relative(searchPath, fullPath).replace(/\\/g, '/');
+    if (globMatcher && !globMatcher.test(relPath) && !globMatcher.test(relPath.split('/').pop())) return false;
+    if (!options.type) return true;
+    const extensions = typeExtensions[options.type];
+    return Boolean(extensions?.includes(extname(fullPath).toLowerCase()));
+  }
+
+  function addResult(value) {
+    resultCount += 1;
+    if (!output.add(value) || resultCount >= maxResults) stopped = true;
+  }
+
+  async function searchFile(fullPath) {
+    if (stopped || !matchesFilters(fullPath) || BINARY_EXTS.has(extname(fullPath).toLowerCase())) return;
+    try {
+      const fileStat = await stat(fullPath);
+      if (fileStat.size > 1024 * 1024 || stopped) return;
+      const content = decodeTextFile(await readFile(fullPath));
+      if (content == null) return;
+      const relPath = relative(searchPath, fullPath);
+      regex.lastIndex = 0;
+      if (options.filesOnly) {
+        if (regex.test(content)) addResult(relPath);
+      } else if (options.count) {
+        const matches = content.match(regex);
+        if (matches) addResult(`${relPath}:${matches.length}`);
+      } else {
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length && !stopped; i += 1) {
+          regex.lastIndex = 0;
+          if (regex.test(lines[i])) addResult(`${relPath}:${i + 1}:${lines[i]}`);
+        }
+      }
+    } catch {
+      // Skip unreadable files.
+    }
+  }
 
   async function searchDir(dir) {
-    if (resultCount >= (options.maxResults || 500)) return;
+    if (stopped) return;
     let entries;
     try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
-
+    const files = [];
+    const directories = [];
     for (const entry of entries) {
-      if (resultCount >= (options.maxResults || 500)) return;
       const fullPath = join(dir, entry.name);
-
       if (entry.isDirectory()) {
-        if (SKIP.has(entry.name)) continue;
-        await searchDir(fullPath);
-      } else {
-        const ext = extname(entry.name).toLowerCase();
-        if (BINARY_EXTS.has(ext)) continue;
-
-        try {
-          const fileStat = await stat(fullPath);
-          if (fileStat.size > 1024 * 1024) continue; // skip files > 1MB
-
-          const buffer = await readFile(fullPath);
-          const content = decodeTextFile(buffer);
-          if (content == null) continue;
-          const relPath = relative(searchPath, fullPath);
-
-          if (options.filesOnly) {
-            if (regex.test(content)) {
-              resultCount += 1;
-              if (!output.add(relPath)) return;
-            }
-            regex.lastIndex = 0;
-          } else if (options.count) {
-            const matches = content.match(regex);
-            if (matches) {
-              resultCount += 1;
-              if (!output.add(`${relPath}:${matches.length}`)) return;
-            }
-          } else {
-            const lines = content.split('\n');
-            for (let i = 0; i < lines.length; i++) {
-              if (regex.test(lines[i])) {
-                resultCount += 1;
-                if (!output.add(`${relPath}:${i + 1}:${lines[i]}`)) return;
-              }
-              regex.lastIndex = 0;
-              if (resultCount >= (options.maxResults || 500)) return;
-            }
-          }
-        } catch {
-          // Skip unreadable files
-        }
-      }
+        const relPath = relative(searchPath, fullPath).replace(/\\/g, '/');
+        if (!SKIP_DIRS.has(entry.name) && relPath !== '.yeaft/worktrees' && !relPath.startsWith('.yeaft/worktrees/')) directories.push(fullPath);
+      } else files.push(fullPath);
+    }
+    for (let i = 0; i < files.length && !stopped; i += FALLBACK_CONCURRENCY) {
+      await Promise.all(files.slice(i, i + FALLBACK_CONCURRENCY).map(searchFile));
+    }
+    for (const child of directories) {
+      if (stopped) break;
+      await searchDir(child);
     }
   }
 
-  await searchDir(searchPath);
+  const rootStat = await stat(searchPath);
+  if (rootStat.isDirectory()) await searchDir(searchPath);
+  else await searchFile(searchPath);
   return output.toString();
 }
 
@@ -336,6 +411,13 @@ Guidelines:
           zh: '不区分大小写搜索（默认 false）',
         },
       },
+      fixed_strings: {
+        type: 'boolean',
+        description: {
+          en: 'Treat the pattern as a literal string (default: false)',
+          zh: '将模式视为普通字符串而非正则表达式（默认 false）',
+        },
+      },
       context: {
         type: 'number',
         description: {
@@ -365,7 +447,8 @@ Guidelines:
         },
       },
       head_limit: {
-        type: 'number',
+        type: 'integer',
+        minimum: 1,
         description: {
           en: 'Limit output to first N results (default: 250)',
           zh: '限制输出前 N 条结果（默认 250）',
@@ -379,12 +462,16 @@ Guidelines:
   async execute(input, ctx) {
     const {
       pattern, path: searchPath, output_mode = 'files_with_matches',
-      glob: globFilter, type, case_insensitive = false,
+      glob: globFilter, type, case_insensitive = false, fixed_strings = false,
       context, before, after, multiline = false,
       head_limit = MAX_LINES,
     } = input;
 
     if (!pattern) return JSON.stringify({ error: 'pattern is required' });
+    if (!Number.isInteger(head_limit) || head_limit < 1) {
+      return JSON.stringify({ error: 'head_limit must be a positive integer' });
+    }
+    const headLimit = Math.min(head_limit, 10000);
 
     const cwd = ctx?.cwd || process.cwd();
     const absPath = searchPath ? resolve(cwd, searchPath) : cwd;
@@ -397,13 +484,15 @@ Guidelines:
       caseInsensitive: case_insensitive,
       glob: globFilter,
       type,
+      fixedStrings: fixed_strings,
       filesOnly: output_mode === 'files_with_matches',
       count: output_mode === 'count',
       context,
       before,
       after,
       multiline,
-      maxResults: head_limit * 2,
+      maxResults: headLimit,
+      byteBudget: SEARCH_RESULT_BYTES,
     };
 
     try {
@@ -423,9 +512,9 @@ Guidelines:
       // Limit output lines, then enforce the byte budget at the actual tool
       // boundary so prefixes, JSON escaping, and result markers are included.
       const lines = result.trim().split('\n');
-      if (lines.length > head_limit) {
+      if (lines.length > headLimit) {
         return boundToolOutput(
-          lines.slice(0, head_limit).join('\n') + `\n\n... (${lines.length - head_limit} more results)`,
+          lines.slice(0, headLimit).join('\n') + `\n\n... (${lines.length - headLimit} more results)`,
         );
       }
 

package/yeaft/tools/mcp-tools.js

@@ -111,6 +111,7 @@ export function buildMcpFlattenedTools(mcpManager) {
         t.description || `MCP tool ${fullName.split('__').slice(1).join('__')} from server ${t.server}`
       ),
       parameters: t.inputSchema || { type: 'object', properties: {} },
+      errorOutput: null,
       async execute(input = {}, _ctx) {
         // Look up the manager fresh on each call. We deliberately don't
         // close over a server reference — hot-reload may have replaced
@@ -125,7 +126,11 @@ export function buildMcpFlattenedTools(mcpManager) {
           throw new Error(`MCP manager not available for ${flattenedName}`);
         }
         const result = await mcpManager.callTool(fullName, input || {});
-        return formatMcpResult(result);
+        const output = formatMcpResult(result);
+        if (result && typeof result === 'object' && result.isError === true) {
+          throw new Error(output || `MCP tool ${fullName} failed`);
+        }
+        return output;
       },
     });
   });
@@ -262,7 +267,11 @@ Usage guidelines:
 
     try {
       const result = await mcpManager.callTool(tool_name, args, timeout_ms || 30000);
-      return formatMcpResult(result);
+      const output = formatMcpResult(result);
+      if (result && typeof result === 'object' && result.isError === true) {
+        throw new Error(output || `MCP tool ${tool_name} failed`);
+      }
+      return output;
     } catch (err) {
       return JSON.stringify({
         error: err.message,

package/yeaft/tools/read-task-log.js

@@ -7,8 +7,8 @@ import { defineTool } from './types.js';
 export default defineTool({
   name: 'ReadTaskLog',
   description: {
-    en: 'Read a background task log by taskId. Supports tail reads and byte offsets.',
-    zh: '按 taskId 读取后台任务日志。支持 tail 和字节 offset。',
+    en: 'Read a background task log by taskId. The first read defaults to the tail. For later reads, pass the previous nextOffset as offset to receive only new bytes; an explicit offset defaults tail to false.',
+    zh: '按 taskId 读取后台任务日志。首次读取默认返回末尾；后续把上次返回的 nextOffset 作为 offset 传入即可只读取新增字节，显式传 offset 时 tail 默认 false。',
   },
   parameters: {
     type: 'object',
@@ -28,10 +28,11 @@ export default defineTool({
     const taskId = input.taskId;
     if (!taskId) return JSON.stringify({ error: 'taskId is required' });
     const sessionId = input.sessionId || ctx.sessionId || 'default';
+    const hasOffset = Number.isFinite(input.offset);
     const result = ctx.taskManager.readTaskLog(sessionId, taskId, {
       offset: input.offset,
       maxBytes: input.maxBytes,
-      tail: input.tail !== false,
+      tail: typeof input.tail === 'boolean' ? input.tail : !hasOffset,
     });
     return JSON.stringify(result, null, 2);
   },

package/yeaft/tools/registry.js

@@ -37,7 +37,7 @@ export const FORWARD_TOOL_NAMES = Object.freeze(['RouteForward']);
  * persisted transcripts need the raw result. The engine/history replay path
  * applies this only when building messages for the model.
  */
-export const TOOL_RESULT_MAX_BYTES = 10 * 1024;
+export const TOOL_RESULT_MAX_BYTES = 32 * 1024;
 
 function normalizeLanguage(language) {
   return String(language || '').toLowerCase().startsWith('zh') ? 'zh' : 'en';
@@ -194,24 +194,49 @@ export function normalizeToolOutput(output) {
   return text;
 }
 
+export function isToolErrorOutput(output) {
+  const text = normalizeToolOutput(output).trim();
+  if (!text.startsWith('{')) return false;
+  try {
+    const parsed = JSON.parse(text);
+    return Boolean(
+      parsed
+      && typeof parsed === 'object'
+      && !Array.isArray(parsed)
+      && typeof parsed.error === 'string'
+      && parsed.error.trim(),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function truncateUtf8(text, maxBytes) {
+  if (maxBytes <= 0) return '';
+  const buffer = Buffer.from(String(text), 'utf8');
+  if (buffer.length <= maxBytes) return String(text);
+  let end = maxBytes;
+  while (end > 0 && (buffer[end] & 0xc0) === 0x80) end -= 1;
+  return buffer.subarray(0, end).toString('utf8');
+}
+
 export function truncateToolResultIfNeeded(output, { toolName, language } = {}) {
   const text = normalizeToolOutput(output);
   const originalBytes = Buffer.byteLength(text, 'utf8');
   if (originalBytes <= TOOL_RESULT_MAX_BYTES) return text;
 
-  const chunks = [];
-  let used = 0;
-  for (const ch of text) {
-    const n = Buffer.byteLength(ch, 'utf8');
-    if (used + n > TOOL_RESULT_MAX_BYTES) break;
-    chunks.push(ch);
-    used += n;
+  const markerFor = name => normalizeLanguage(language) === 'zh'
+    ? `\n\n[已截断：${name} 返回 ${formatSize(originalBytes)}，上限为 ${formatSize(TOOL_RESULT_MAX_BYTES)}；原因：单个 tool result 超过 ${formatSize(TOOL_RESULT_MAX_BYTES)}，模型消息历史不会看到剩余内容]`
+    : `\n\n[truncated: ${name} returned ${formatSize(originalBytes)}, capped at ${formatSize(TOOL_RESULT_MAX_BYTES)}; reason: single tool result exceeded ${formatSize(TOOL_RESULT_MAX_BYTES)}, the model message history will not see the rest]`;
+  let marker = markerFor(String(toolName || 'tool'));
+  if (Buffer.byteLength(marker, 'utf8') > TOOL_RESULT_MAX_BYTES) {
+    const fixedMarker = markerFor('');
+    const nameBudget = Math.max(0, TOOL_RESULT_MAX_BYTES - Buffer.byteLength(fixedMarker, 'utf8'));
+    marker = markerFor(truncateUtf8(String(toolName || 'tool'), nameBudget));
   }
-  const head = chunks.join('');
-  const marker = normalizeLanguage(language) === 'zh'
-    ? `\n\n[已截断：${toolName} 返回 ${formatSize(originalBytes)}，上限为 ${formatSize(TOOL_RESULT_MAX_BYTES)}；原因：单个 tool result 超过 ${formatSize(TOOL_RESULT_MAX_BYTES)}，模型消息历史不会看到剩余内容]`
-    : `\n\n[truncated: ${toolName} returned ${formatSize(originalBytes)}, capped at ${formatSize(TOOL_RESULT_MAX_BYTES)}; reason: single tool result exceeded ${formatSize(TOOL_RESULT_MAX_BYTES)}, the model message history will not see the rest]`;
-  return head + marker;
+  marker = truncateUtf8(marker, TOOL_RESULT_MAX_BYTES);
+  const contentBudget = Math.max(0, TOOL_RESULT_MAX_BYTES - Buffer.byteLength(marker, 'utf8'));
+  return truncateUtf8(text, contentBudget) + marker;
 }
 
 /**

package/yeaft/tools/types.js

@@ -62,6 +62,7 @@
  * @property {(input?: object) => boolean} [isConcurrencySafe] — can run in parallel?
  * @property {(input?: object) => boolean} [isReadOnly] — read-only operation?
  * @property {(input?: object) => boolean} [isDestructive] — destructive operation?
+ * @property {'json-error-envelope' | null} [errorOutput] — explicit returned-output error contract; null means only thrown errors fail
  */
 
 /**
@@ -75,6 +76,7 @@
  *   isConcurrencySafe?: (input?: object) => boolean,
  *   isReadOnly?: (input?: object) => boolean,
  *   isDestructive?: (input?: object) => boolean,
+ *   errorOutput?: 'json-error-envelope' | null,
  *   timeoutMs?: number,
  * }} def
  * @returns {ToolDef}
@@ -88,6 +90,7 @@ export function defineTool({
   isConcurrencySafe = () => false,
   isReadOnly = () => false,
   isDestructive = () => false,
+  errorOutput = 'json-error-envelope',
   timeoutMs,
 }) {
   if (!name) throw new Error('Tool must have a name');
@@ -101,6 +104,7 @@ export function defineTool({
     isConcurrencySafe,
     isReadOnly,
     isDestructive,
+    errorOutput,
   };
   // Legacy tool-name aliases. Registered as extra lookup keys so old
   // jsonl tool_calls (e.g. `SendMessage` → `PromptAgent`) keep resolving,

package/yeaft/web-bridge.js

@@ -6537,18 +6537,50 @@ export async function handleYeaftLoadHistory(msg) {
 }
 
 /**
- * Handle a "load older messages" pagination request. Reads `turns` more
- * turns of history strictly older than `beforeSeq` for `sessionId`, and
- * emits them in a single `yeaft_history_chunk` envelope (NOT a
- * `yeaft_output` — that pipeline appends, but the frontend needs to
- * PREPEND these older messages above what it already has).
+ * Load one lightweight Conversation Outline page. The response contains only
+ * visible user/assistant metadata and bounded snippets; full message bodies and
+ * tool payloads stay on the Agent. `beforeSeq` is an exclusive older-page
+ * cursor, and `includeTotal` avoids recounting after the first page.
  *
- * Tool replay is NOT included in this PR — same projection as
- * `handleYeaftLoadHistory` (user / assistant text only). On any internal
- * failure we still emit an empty chunk so the spinner clears.
- *
- * @param {object} msg — { sessionId, beforeSeq, turns }
+ * @param {object} msg — { sessionId, beforeSeq, limit, includeTotal }
  */
+export async function handleYeaftLoadHistoryOutline(msg) {
+  const sessionId = typeof msg?.sessionId === 'string' ? msg.sessionId.trim() : '';
+  const requestId = typeof msg?.requestId === 'string' ? msg.requestId : null;
+  const beforeSeq = Number.isFinite(msg?.beforeSeq) ? msg.beforeSeq : null;
+  const limit = Math.min(100, Math.max(1, Number.isFinite(msg?.limit) ? Math.floor(msg.limit) : 50));
+  const response = {
+    type: 'yeaft_history_outline',
+    requestId,
+    sessionId: sessionId || null,
+    results: [],
+    hasMore: false,
+    nextBeforeSeq: null,
+    totalCount: null,
+    _requestClientId: msg?._requestClientId || null,
+  };
+
+  if (!sessionId) {
+    sendToServer({ ...response, error: 'invalid_session' });
+    return;
+  }
+
+  try {
+    const defaultYeaftDir = ctx.CONFIG?.yeaftDir || DEFAULT_YEAFT_DIR;
+    const storeDir = resolveSessionYeaftDir(defaultYeaftDir, sessionId);
+    const store = new ConversationStore(storeDir);
+    const result = store.loadVisibleOutlineBySession(sessionId, {
+      limit,
+      beforeSeq,
+      includeTotal: msg?.includeTotal !== false,
+    });
+    sendToServer({ ...response, ...result });
+  } catch (err) {
+    console.error('[Yeaft] Session history outline failed:', err?.message || err);
+    sendToServer({ ...response, error: 'outline_failed' });
+  }
+}
+
 export async function handleYeaftSearchHistory(msg) {
   const sessionId = typeof msg?.sessionId === 'string' ? msg.sessionId.trim() : '';
   const query = typeof msg?.query === 'string' ? msg.query.trim().slice(0, 500) : '';