@yeaft/webchat-agent 1.0.639 → 1.0.640

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.639",
+  "version": "1.0.640",
   "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/attachments.js

@@ -312,9 +312,16 @@ export function resolvePersistedAttachmentPath(attachmentPath, opts = {}) {
   }
 }
 
-/** Shared bounded read for model history and browser preview. Never follows symlinks. */
-function readPersistedAttachment(att, opts, maxBytes) {
-  const absPath = resolvePersistedAttachmentPath(att?.path, opts);
+/**
+ * Read a bounded, owner-scoped attachment for host consumers, never via symlinks.
+ * Ownership is derived from opts, not the supplied path or attachment metadata.
+ * @param {string} attachmentPath
+ * @param {{cwd?:string, legacyRoot?:string, yeaftDir?:string, sessionId?:string}} opts
+ * @param {number} maxBytes
+ * @returns {{path:string, buffer:Buffer, modified:string}}
+ */
+export function readPersistedAttachmentFile(attachmentPath, opts, maxBytes) {
+  const absPath = resolvePersistedAttachmentPath(attachmentPath, opts);
   if (!absPath) throw new Error('file missing or outside this Session / 文件缺失或不属于本会话');
   const fd = openSync(absPath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
   try {
@@ -328,17 +335,23 @@ function readPersistedAttachment(att, opts, maxBytes) {
       if (!read) throw new Error('image changed while reading');
       offset += read;
     }
-    return {
-      data: buffer.toString('base64'),
-      mimeType: att.mimeType || 'image/png',
-      filename: att.name || basename(absPath),
-      bytes: buffer.length,
-    };
+    return { path: absPath, buffer, modified: stat.mtime.toISOString() };
   } finally {
     closeSync(fd);
   }
 }
 
+/** Shared bounded read for model history and browser preview. Never follows symlinks. */
+function readPersistedAttachment(att, opts, maxBytes) {
+  const { path, buffer } = readPersistedAttachmentFile(att?.path, opts, maxBytes);
+  return {
+    data: buffer.toString('base64'),
+    mimeType: att.mimeType || 'image/png',
+    filename: att.name || basename(path),
+    bytes: buffer.length,
+  };
+}
+
 /** Short-lived web preview; missing/denied/oversized images have no preview. */
 export function persistedAttachmentPreviewPayload(att, opts = {}) {
   if (!att?.isImage || !att.path) return null;

package/yeaft/engine.js

@@ -19,6 +19,7 @@
 
 import { randomUUID, createHash } from 'crypto';
 import { QueryProgress, progressReminder } from './query-progress.js';
+import { createWebResearchState } from './web-research.js';
 import { promises as fsp } from 'fs';
 import { join, resolve as resolvePath } from 'path';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
@@ -30,6 +31,7 @@ import {
   pickProjectDocFile,
   selectProjectDocContext,
   projectDocPathHintsFromToolCall,
+  projectDocToolCallNeedsWriteReview,
   projectDocWriteScopesNeedingReload,
   DEFAULT_PROJECT_DOC_MAX_BYTES,
 } from './sessions/project-doc.js';
@@ -1444,6 +1446,7 @@ export class Engine {
       effortDecision: snapshotEffortDecision(vpCtx?.effortDecision),
       requestIdentity: vpCtx?.requestIdentity,
       queryTurnId: vpCtx?.queryTurnId,
+      webResearch: vpCtx?.webResearch,
       historyBeforeSeq: vpCtx?.historyBeforeSeq,
       yeaftDir: this.#yeaftDir,
       managedCliReady: this.#managedCliReady,
@@ -2596,6 +2599,9 @@ export class Engine {
     const queryDuplicateSuppressions = new Map();
     const queryValidationFailures = new Map();
     const fileReadObservations = new Map();
+    // Success reuse and in-flight sharing must not cross user turns, Sessions,
+    // or child Engines. Never copy this ledger into parentEngineDeps.
+    const webResearch = createWebResearchState();
     let duplicateReminderAwaitingResponse = false;
     const queryNumber = (this.#__queryCounter = (this.#__queryCounter || 0) + 1);
 
@@ -4295,6 +4301,7 @@ export class Engine {
         effortDecision: snapshotEffortDecision(requestEffortDecision),
         requestIdentity,
         queryTurnId,
+        webResearch,
         historyBeforeSeq: Number.isFinite(persistedQueryUser?.seq) ? persistedQueryUser.seq : parseSeqFromId(persistedQueryUser?.id),
         router,
         senderVpId,
@@ -4602,15 +4609,31 @@ export class Engine {
           : this.#tools.has(tc.name);
         const toolProjectDocPathHints = projectDocPathHintsFromToolCall(tc.name, tc.input);
         const readOnlyTool = hasTool ? isReadOnlyTool(this, tc.name, tc.input) : false;
-        const missingProjectDocScopes = hasTool && !readOnlyTool
-          ? projectDocWriteScopesNeedingReload(projectDocContext, toolProjectDocPathHints)
+        const projectDocWrite = hasTool
+          && projectDocToolCallNeedsWriteReview(tc.name, tc.input, readOnlyTool);
+        const missingProjectDocScopes = projectDocWrite
+          // Shell code is opaque: cwd alone cannot identify its write targets.
+          // Load all omitted rules rather than interpreting command words as paths.
+          ? projectDocWriteScopesNeedingReload(projectDocContext, tc.name === 'Bash' ? [] : toolProjectDocPathHints)
           : new Set();
         // A changed rule source was not present in the request that generated
         // this write, even when its scope label is unchanged. Never replay it.
-        const freshProjectDocSource = hasTool && !readOnlyTool
+        const freshProjectDocSource = projectDocWrite
           ? this.#getProjectDocBlock(workDir) : projectDocSource;
         const projectDocSourceChanged = freshProjectDocSource !== projectDocSource;
-        const needsProjectDocReload = missingProjectDocScopes.size > 0 || projectDocSourceChanged;
+        const nextProjectDocPathHints = [...new Set([
+          ...projectDocLoadedPathHints, ...toolProjectDocPathHints,
+        ])];
+        const reloadedProjectDocContext = missingProjectDocScopes.size > 0 || projectDocSourceChanged
+          ? selectProjectDocContext(freshProjectDocSource, {
+              prompt, messages, pathHints: nextProjectDocPathHints,
+              language: this.#config.language || 'en',
+              forcedScopes: [...projectDocContext.selectedScopes, ...missingProjectDocScopes],
+            })
+          : projectDocContext;
+        // Scope bookkeeping (including core sections already shown) is not a
+        // new instruction. Only stop a write when its model-visible rules change.
+        const needsProjectDocReload = reloadedProjectDocContext.text !== projectDocContext.text;
 
         if (abortSkipped) {
           output = `Skipped ${tc.name} because the turn was aborted before this tool started.`;
@@ -4659,22 +4682,15 @@ export class Engine {
           yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true, suppressed: true, threadId: this.currentThreadId };
         } else if (needsProjectDocReload) {
           projectDocSource = freshProjectDocSource;
-          projectDocLoadedPathHints = [...new Set([
-            ...projectDocLoadedPathHints,
-            ...toolProjectDocPathHints,
-          ])];
-          const previouslySelectedProjectDocScopes = new Set(projectDocContext.selectedScopes);
-          projectDocContext = selectProjectDocContext(projectDocSource, {
-            prompt,
-            messages,
-            pathHints: projectDocLoadedPathHints,
-            language: this.#config.language || 'en',
-            forcedScopes: [...previouslySelectedProjectDocScopes, ...missingProjectDocScopes],
-          });
+          projectDocLoadedPathHints = nextProjectDocPathHints;
+          projectDocContext = reloadedProjectDocContext;
           const zh = String(this.#config?.language || '').toLowerCase().startsWith('zh');
+          const target = toolProjectDocPathHints.length > 0
+            ? (zh ? `路径 ${toolProjectDocPathHints.join(', ')}` : toolProjectDocPathHints.join(', '))
+            : (zh ? `${tc.name} 写操作` : `the ${tc.name} write`);
           const notice = zh
-            ? `项目规则已针对路径 ${toolProjectDocPathHints.join(', ')} 重新加载。先复核新载入的规则，再重新提交写操作；本次调用未执行。`
-            : `Project rules were reloaded for ${toolProjectDocPathHints.join(', ')}. Review the newly loaded rules before resubmitting the write; this call was not executed.`;
+            ? `项目规则已针对${target}重新加载。先复核新载入的规则，再重新提交写操作；本次调用未执行。`
+            : `Project rules were reloaded for ${target}. Review the newly loaded rules before resubmitting the write; this call was not executed.`;
           promptNotices = [notice];
           systemPrompt = buildCurrentSystemPrompt();
           output = notice;

package/yeaft/query-progress.js

@@ -26,6 +26,18 @@ function resultHash(output) {
   return createHash('sha256').update(typeof output === 'string' ? output : JSON.stringify(output) || '').digest('hex');
 }
 
+/** Web advice/reuse annotations are not new evidence; raw output stays intact. */
+function observationOutput(call, output) {
+  if (call.name !== 'WebFetch' && call.name !== 'WebSearch') return output;
+  try {
+    const value = typeof output === 'string' ? JSON.parse(output.replace(/^Error:\s*/, '')) : output;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return output;
+    const { researchGuidance, relatedPriorQuery, convergenceHint, reused, reuseReason,
+      priorQuery, priorAuthorizationFailure, hint, ...evidence } = value;
+    return evidence;
+  } catch { return output; }
+}
+
 function failureKind(output, call, readOnly) {
   const text = typeof output === 'string' ? output : JSON.stringify(output) || '';
   const errorText = text.replace(/^Error:\s*/, '');
@@ -143,10 +155,11 @@ export class QueryProgress {
     // change duplicate detection, replay protection or loop-guard decisions.
     if (pendingOutcome) this.#pendingOutcomes.set(call.id, { stats, isError, executed });
     const key = `${call.name}:${argsHashOf(call.input)}`;
-    const hash = resultHash(output);
+    const observation = observationOutput(call, output);
+    const hash = resultHash(observation);
     if (isError) {
       const prior = this.#failures.get(key);
-      const kind = failureKind(output, call, readOnly);
+      const kind = failureKind(observation, call, readOnly);
       if (executed && !readOnly) {
         // A partial mutation may have changed even a previously unreadable
         // resource. Permit verification, never a replay of the mutation itself.

package/yeaft/response-presentation.js

@@ -20,16 +20,20 @@ export const PRESENTATION_SCHEMA = obj({
     block('diagram', { nodes: arr(obj({ id: str(40), label: str(160) }, ['id', 'label']), 12), edges: arr(obj({ from: str(40), to: str(40), label: str(120) }, ['from', 'to']), 24, 0) }, ['nodes', 'edges']),
     block('image', { url: str(2000), alt: str(240), caption: str(1000) }, ['url', 'alt']),
     block('link', { url: str(2000), text: str(1000) }, ['url', 'text']),
-    block('map', { points: arr(obj({ label: str(160), latitude: { type: 'number', minimum: -90, maximum: 90 }, longitude: { type: 'number', minimum: -180, maximum: 180 }, detail: str(1000) }, ['label', 'latitude', 'longitude']), 20), embed: obj({ provider: { type: 'string', enum: ['openstreetmap', 'google'] }, url: str(2000) }, ['provider']) }, ['points']),
+    block('map', { points: arr(obj({ label: str(160), latitude: { type: 'number', minimum: -90, maximum: 90 }, longitude: { type: 'number', minimum: -180, maximum: 180 }, detail: str(1000) }, ['label', 'latitude', 'longitude']), 20), embed: { anyOf: [
+      obj({ provider: { type: 'string', enum: ['openstreetmap'] }, url: str(2000) }, ['provider']),
+      obj({ provider: { type: 'string', enum: ['google'] }, url: str(2000) }, ['provider', 'url']),
+    ] } }, ['points']),
   ] }, 12),
 }, ['summary', 'blocks']);
 
-export const PRESENT_RESPONSE_DESCRIPTION = `Publish a rich user-visible response inside this turn: cards, metrics, comparison tables, bar/line charts, timelines, relationship diagrams, images, artifact links or maps. Cards may include an optional image {url,alt,fit:cover|contain} and source/action url; use contain for weather icons or team logos and cover for photography. Optional: use normal text for simple answers. Supply a self-contained summary for copying, search, model history and older clients; do not repeat the whole rich answer afterwards. Use only verified data, mark uncertainty, and never fabricate chart values or coordinates. No HTML/JavaScript, arbitrary SVG, styling or executable content. Image/link URLs must be credential-free HTTP(S); images load automatically in the reader’s browser without a referrer. Links open in the owning in-app browser by default; the reader can explicitly choose a new tab. Maps default to offline coordinate sketches. Set map.embed={provider:openstreetmap} for the dedicated OSM street-map embed, or {provider:google,url} with a verified official https://www.google.com/maps/embed?pb=... share URL (not a homepage or API-key URL). Embed availability depends on the reader's network; coordinates remain available. Never invent routes, ETAs, weather or scores; attach verified image sources and dated data. phase=progress continues work; phase=final is a delivery intent, not proof of task success. Runtime still owns persistence, cancellation and turn termination. Validation failure publishes nothing; correct the payload or answer in text.`;
+export const PRESENT_RESPONSE_DESCRIPTION = `Publish a rich user-visible response inside this turn: cards, metrics, comparison tables, bar/line charts, timelines, relationship diagrams, images, artifact links or maps. Cards may include an optional image {url,alt,fit:cover|contain} and source/action url; use contain for weather icons or team logos and cover for photography. Optional: use normal text for simple answers. Supply a self-contained summary for copying, search, model history and older clients; do not repeat the whole rich answer afterwards. Use only verified data, mark uncertainty, and never fabricate chart values or coordinates. No HTML/JavaScript, arbitrary SVG, styling or executable content. Image/link URLs must be credential-free HTTP(S); images load automatically in the reader’s browser without a referrer. Links open in the owning in-app browser by default; the reader can explicitly choose a new tab. Maps default to offline coordinate sketches. Set map.embed={provider:openstreetmap} without a URL; runtime generates the dedicated OSM street-map embed, or {provider:google,url} with a verified official https://www.google.com/maps/embed?pb=... share URL (not a homepage or API-key URL). Embed availability depends on the reader's network; coordinates remain available. Never invent routes, ETAs, weather or scores; attach verified image sources and dated data. phase=progress continues work; phase=final is a delivery intent, not proof of task success. Runtime still owns persistence, cancellation and turn termination. Validation failure publishes nothing; correct the payload or answer in text.`;
 
 function check(value, schema, path) {
   if (schema.anyOf) {
-    const candidate = schema.anyOf.find(s => value?.type === s.properties.type.enum[0]);
-    if (!candidate) throw new Error(`${path}: unsupported block type`);
+    const key = schema.anyOf[0].properties.type ? 'type' : 'provider';
+    const candidate = schema.anyOf.find(s => s.properties[key].enum.includes(value?.[key]));
+    if (!candidate) throw new Error(`${path}.${key}: unsupported value`);
     return check(value, candidate, path);
   }
   if (schema.type === 'object') {
@@ -87,7 +91,25 @@ export function safePresentationUrl(value) {
 
 /** Only official map share embeds are allowed. API keys/configuration never enter transcripts. */
 export function normalizeMapEmbed(embed) {
-  if (embed?.provider === 'openstreetmap' && embed.url === undefined) return { provider: 'openstreetmap' };
+  if (embed?.provider === 'openstreetmap') {
+    if (embed.url !== undefined) {
+      // Compatibility for official legacy OSM embeds. Never reuse a model URL:
+      // normalize it to provider-only so the reader generates the bounds/marker.
+      const url = new URL(safePresentationUrl(embed.url));
+      const keys = [...url.searchParams.keys()];
+      const tuple = (name, count) => {
+        const parts = (url.searchParams.get(name) || '').split(',');
+        return parts.length === count && parts.every(part => part.trim() && Number.isFinite(Number(part)));
+      };
+      if (url.origin !== 'https://www.openstreetmap.org' || url.pathname !== '/export/embed.html' || url.hash
+        || new Set(keys).size !== keys.length || keys.some(key => !['bbox', 'layer', 'marker'].includes(key))
+        || !tuple('bbox', 4) || (url.searchParams.has('marker') && !tuple('marker', 2))
+        || (url.searchParams.has('layer') && url.searchParams.get('layer') !== 'mapnik')) {
+        throw new Error('map: invalid legacy OpenStreetMap embed URL; use provider-only openstreetmap');
+      }
+    }
+    return { provider: 'openstreetmap' };
+  }
   if (embed?.provider === 'google') {
     const url = new URL(safePresentationUrl(embed.url));
     const params = [...url.searchParams];

package/yeaft/sessions/project-doc.js

@@ -201,22 +201,45 @@ export function selectProjectDocContext(text, {
   };
 }
 
-/** Extract concrete workspace path hints from a tool call input. */
+// These tools manage runtime state, not project files. Do not confuse their
+// side effects (or an Agent's target cwd) with a write in this workspace.
+const PROJECT_DOC_LIFECYCLE_TOOLS = new Set([
+  'Skill', 'EnterWorktree', 'ExitWorktree', 'AskUser', 'PresentResponse',
+  'DiscoverTools', 'HistorySearch', 'ListTasks', 'ReadTaskLog', 'WaitTask',
+  'CancelTask', 'SpawnAgent', 'Agent', 'UpdateAgent', 'PromptAgent', 'SendMessage',
+  'WaitAgent', 'CloseAgent', 'ListAgents', 'RouteForward', 'CreateWorkItem', 'JsReplReset',
+]);
+
+/** Project-rule review is separate from tool caching/concurrency metadata. */
+export function projectDocToolCallNeedsWriteReview(toolName, input = {}, readOnly = false) {
+  if (readOnly || PROJECT_DOC_LIFECYCLE_TOOLS.has(toolName)) return false;
+  if (toolName === 'NotebookEdit') return input?.action !== 'read';
+  if (toolName === 'ImageGeneration') return Boolean(input?.output_path);
+  if (toolName === 'Bash') {
+    // Deliberately exact: no compound commands, substitutions, redirects or
+    // arbitrary options. Everything else remains a potential write.
+    const command = typeof input?.command === 'string' ? input.command.trim() : '';
+    return !/^(?:pwd(?:[ \t]+-[LP])?|git[ \t]+status(?:[ \t]+--short)?)$/.test(command);
+  }
+  // FileWrite/FileEdit/ApplyPatch and unknown extension tools fail closed.
+  return true;
+}
+
+/** Extract concrete workspace path hints, never shell code or lifecycle inputs. */
 export function projectDocPathHintsFromToolCall(toolName, input = {}) {
+  if (PROJECT_DOC_LIFECYCLE_TOOLS.has(toolName)) return [];
   const hints = [];
   for (const key of ['file_path', 'path', 'cwd', 'workDir', 'notebook_path', 'output_path']) {
     if (typeof input?.[key] === 'string' && input[key].trim()) hints.push(input[key].trim());
   }
-  if (toolName === 'Bash' && typeof input?.command === 'string' && input.command.trim()) {
-    hints.push(input.command.trim());
-  }
   if (toolName === 'ApplyPatch' && typeof input?.patch === 'string') {
-    for (const match of input.patch.matchAll(/^\+\+\+\s+(?:b\/)?(.+)$/gm)) {
+    // Include deletion targets too; +++ /dev/null has no destination path.
+    for (const match of input.patch.matchAll(/^(?:---|\+\+\+)\s+(?:[ab]\/)?(.+)$/gm)) {
       const path = match[1]?.trim();
       if (path && path !== '/dev/null') hints.push(path);
     }
   }
-  return hints;
+  return [...new Set(hints)];
 }
 
 export function projectDocWriteScopesNeedingReload(projectDocContext, pathHints) {

package/yeaft/stats/tool-usage.js

@@ -19,7 +19,8 @@
  *       totalDurationMs: number,
  *       durations: number[],   // ring of last N durations for p50/p95
  *       lastCalledAt: ISO8601 string,
- *       lastError: string | null
+ *       lastError: string | null,
+ *       recentOutcomes: (null | string)[] // last 100: null=success, safe reason=error
  *     }
  *   }
  * }
@@ -44,6 +45,62 @@ const DEFAULT_RING_SIZE = 100;
 const DEFAULT_FLUSH_EVERY_N = 20;
 const DEFAULT_FLUSH_INTERVAL_MS = 30_000;
 const SCHEMA_VERSION = 1;
+const RECENT_WINDOW_SIZE = 100;
+
+// Fixed vocabulary: never persist arbitrary messages, paths, URLs or provider
+// strings as category keys. Unknown structured codes fall back to a category.
+const ERROR_REASONS = new Set([
+  'invalid_arguments', 'git_cwd_outside_repository', 'git_exit_unconfirmed',
+  'git_timeout', 'git_output_limit', 'git_failed', 'git_filter_inspection_failed',
+  'git_execution_error', 'bash_exit_nonzero', 'exit_nonzero',
+  'timeout', 'cancelled', 'permission', 'not_found', 'network', 'rate_limit', 'conflict', 'http_error', 'other',
+]);
+
+function safeReason(value) {
+  return typeof value === 'string' && ERROR_REASONS.has(value) ? value : null;
+}
+
+function errorReason(errorMessage, errorCode) {
+  const explicit = safeReason(errorCode);
+  if (explicit) return explicit;
+  const text = typeof errorMessage === 'string' ? errorMessage.slice(0, 500) : '';
+  let code;
+  try {
+    const parsed = JSON.parse(text);
+    code = parsed?.code ?? parsed?.errorCode ?? parsed?.failureType ?? parsed?.error?.code;
+  } catch {
+    // Engine output may end mid-JSON. Only accept a complete allowlisted code
+    // value; do not turn a truncated/free-form value into a category key.
+    code = text.match(/"(?:code|errorCode|failureType)"\s*:\s*"([A-Za-z0-9_-]{1,64})"/)?.[1];
+  }
+  const structured = safeReason(code);
+  if (structured) return structured;
+  if (/timed?\s*out|timeout|ETIMEDOUT/i.test(text)) return 'timeout';
+  if (/abort|cancelled|canceled/i.test(text)) return 'cancelled';
+  if (/rate.?limit|too many requests|\b429\b/i.test(text)) return 'rate_limit';
+  if (/EACCES|EPERM|permission denied|access denied|forbidden|unauthorized|\b40[13]\b/i.test(text)) return 'permission';
+  if (/ENOENT|not found|does not exist|\b404\b/i.test(text)) return 'not_found';
+  if (/ECONN|ENOTFOUND|EAI_AGAIN|fetch failed|network|socket/i.test(text)) return 'network';
+  if (/already exists|uncommitted changes|conflict/i.test(text)) return 'conflict';
+  if (/HTTP\s*(?:error[: ]*)?[45]\d\d/i.test(text)) return 'http_error';
+  return 'other';
+}
+
+function readToolRecord(rec, ringSize) {
+  return {
+    callCount: Number(rec.callCount) || 0,
+    errorCount: Number(rec.errorCount) || 0,
+    totalDurationMs: Number(rec.totalDurationMs) || 0,
+    durations: Array.isArray(rec.durations) ? rec.durations.slice(-ringSize) : [],
+    lastCalledAt: typeof rec.lastCalledAt === 'string' ? rec.lastCalledAt : null,
+    lastError: typeof rec.lastError === 'string' ? rec.lastError : null,
+    // Old durations/lastError cannot tell us which calls failed. Never infer
+    // recent outcomes from lifetime counters on legacy files.
+    recentOutcomes: Array.isArray(rec.recentOutcomes)
+      ? rec.recentOutcomes.slice(-RECENT_WINDOW_SIZE).map(value => value === null ? null : safeReason(value) || 'other')
+      : [],
+  };
+}
 
 function defaultStatsPath() {
   return join(homedir(), '.yeaft', 'stats', 'tool-usage.json');
@@ -57,6 +114,7 @@ function emptyToolRecord() {
     durations: [],
     lastCalledAt: null,
     lastError: null,
+    recentOutcomes: [],
   };
 }
 
@@ -116,14 +174,7 @@ export class ToolUsageStats {
       if (parsed && typeof parsed === 'object' && parsed.tools && typeof parsed.tools === 'object') {
         for (const [name, rec] of Object.entries(parsed.tools)) {
           if (!rec || typeof rec !== 'object') continue;
-          this.#tools[name] = {
-            callCount: Number(rec.callCount) || 0,
-            errorCount: Number(rec.errorCount) || 0,
-            totalDurationMs: Number(rec.totalDurationMs) || 0,
-            durations: Array.isArray(rec.durations) ? rec.durations.slice(-this.#ringSize) : [],
-            lastCalledAt: typeof rec.lastCalledAt === 'string' ? rec.lastCalledAt : null,
-            lastError: typeof rec.lastError === 'string' ? rec.lastError : null,
-          };
+          this.#tools[name] = readToolRecord(rec, this.#ringSize);
         }
       }
     } catch {
@@ -143,14 +194,7 @@ export class ToolUsageStats {
       if (parsed && typeof parsed === 'object' && parsed.tools && typeof parsed.tools === 'object') {
         for (const [name, rec] of Object.entries(parsed.tools)) {
           if (!rec || typeof rec !== 'object') continue;
-          this.#tools[name] = {
-            callCount: Number(rec.callCount) || 0,
-            errorCount: Number(rec.errorCount) || 0,
-            totalDurationMs: Number(rec.totalDurationMs) || 0,
-            durations: Array.isArray(rec.durations) ? rec.durations.slice(-this.#ringSize) : [],
-            lastCalledAt: typeof rec.lastCalledAt === 'string' ? rec.lastCalledAt : null,
-            lastError: typeof rec.lastError === 'string' ? rec.lastError : null,
-          };
+          this.#tools[name] = readToolRecord(rec, this.#ringSize);
         }
       }
     } catch {
@@ -162,9 +206,12 @@ export class ToolUsageStats {
    * Record a single tool execution. Updates in-memory counters and
    * may trigger a throttled persist.
    *
-   * @param {{ name: string, durationMs?: number, isError?: boolean, errorMessage?: string }} args
+   * `errorCode` is optional structured metadata; `isError` alone controls
+   * failure accounting. Category extraction never changes that outcome.
+   *
+   * @param {{ name: string, durationMs?: number, isError?: boolean, errorMessage?: string|null, errorCode?: string|null }} args
    */
-  record({ name, durationMs = 0, isError = false, errorMessage = null } = {}) {
+  record({ name, durationMs = 0, isError = false, errorMessage = null, errorCode = null } = {}) {
     if (typeof name !== 'string' || !name) return;
     const dur = Math.max(0, Number(durationMs) || 0);
     let rec = this.#tools[name];
@@ -179,6 +226,10 @@ export class ToolUsageStats {
       rec.durations.splice(0, rec.durations.length - this.#ringSize);
     }
     rec.lastCalledAt = new Date().toISOString();
+    rec.recentOutcomes.push(isError ? errorReason(errorMessage, errorCode) : null);
+    if (rec.recentOutcomes.length > RECENT_WINDOW_SIZE) {
+      rec.recentOutcomes.splice(0, rec.recentOutcomes.length - RECENT_WINDOW_SIZE);
+    }
     if (isError) {
       rec.errorCount += 1;
       if (typeof errorMessage === 'string' && errorMessage) {
@@ -260,10 +311,12 @@ export class ToolUsageStats {
   }
 
   /**
-   * Snapshot for CLI/UI rendering. Computes p50/p95/avg/errorRate per
-   * tool from the in-memory rings.
+   * Snapshot for CLI/UI rendering. Existing counters/errorRate remain lifetime
+   * values; recent is based only on recorded outcomes, never historical totals.
+   * Its reason counters sum to recent.errorCount and its rate is null when
+   * there are no samples (including legacy files with no recentOutcomes).
    *
-   * @returns {Record<string, {callCount: number, errorCount: number, errorRate: number, avgMs: number, p50Ms: number, p95Ms: number, lastCalledAt: string|null, lastError: string|null}>}
+   * @returns {Record<string, {callCount: number, errorCount: number, errorRate: number, avgMs: number, p50Ms: number, p95Ms: number, lastCalledAt: string|null, lastError: string|null, recent: {windowSize: number, callCount: number, errorCount: number, errorRate: number|null, errorReasons: Record<string, number>}}> }
    */
   snapshot() {
     /** @type {Record<string, any>} */
@@ -271,6 +324,14 @@ export class ToolUsageStats {
     for (const [name, rec] of Object.entries(this.#tools)) {
       const sorted = rec.durations.slice().sort((a, b) => a - b);
       const avg = rec.callCount > 0 ? rec.totalDurationMs / rec.callCount : 0;
+      const errorReasons = Object.create(null);
+      let recentErrors = 0;
+      for (const reason of rec.recentOutcomes) {
+        if (reason === null) continue;
+        recentErrors += 1;
+        errorReasons[reason] = (errorReasons[reason] || 0) + 1;
+      }
+      const recentCalls = rec.recentOutcomes.length;
       out[name] = {
         callCount: rec.callCount,
         errorCount: rec.errorCount,
@@ -280,6 +341,13 @@ export class ToolUsageStats {
         p95Ms: Math.round(percentile(sorted, 95)),
         lastCalledAt: rec.lastCalledAt,
         lastError: rec.lastError,
+        recent: {
+          windowSize: RECENT_WINDOW_SIZE,
+          callCount: recentCalls,
+          errorCount: recentErrors,
+          errorRate: recentCalls > 0 ? recentErrors / recentCalls : null,
+          errorReasons,
+        },
       };
     }
     return out;

package/yeaft/tools/git-read.js

@@ -54,16 +54,18 @@ function errorOutput(message, operation) {
   });
 }
 
-// Some strict-schema providers require every property. Treat their empty
-// placeholders as omitted, without accepting unknown keys or non-default
-// arguments belonging to another operation.
+// Some strict-schema providers require every property. Treat empty
+// placeholders as omitted. limit is harmless catalogue metadata outside log:
+// providers may fill any schema-valid value, not just the default of 20.
+// Unknown keys and substantive revision/path fields remain operation-specific.
 function normalizeInput(input) {
   const result = { ...input };
   for (const key of ['cwd', 'base', 'head', 'revision', 'paths', 'limit']) {
     if (result[key] === null || result[key] === undefined
         || (['cwd', 'base', 'head', 'revision'].includes(key) && result[key] === '')
         || (key === 'paths' && Array.isArray(result[key]) && result[key].length === 0)
-        || (key === 'limit' && result.operation !== 'log' && result[key] === DEFAULT_LOG_LIMIT)) {
+        || (key === 'limit' && result.operation !== 'log'
+          && Number.isInteger(result[key]) && result[key] >= 1 && result[key] <= MAX_LOG_LIMIT)) {
       delete result[key];
     }
   }
@@ -297,7 +299,7 @@ GitRead 不 fetch、不写 Git 状态、不创建 worktree。它禁用 pager、e
         items: { type: 'string', minLength: 1, maxLength: MAX_VALUE_LENGTH },
         description: 'diff/show only; empty/omitted means all paths',
       },
-      limit: { type: 'integer', minimum: 1, maximum: MAX_LOG_LIMIT, description: 'log only; default 20. Empty optional fields are ignored; omit fields for other operations.' },
+      limit: { type: 'integer', minimum: 1, maximum: MAX_LOG_LIMIT, description: 'Maximum log entries, default 20. Ignored by status/diff/show for strict-schema compatibility. Empty optional fields are treated as omitted.' },
     },
     required: ['operation'],
   },