mocode-ai 0.7.2 → 0.7.3

package/dist/agent/core.js

@@ -8,6 +8,7 @@ import { readFileSync } from 'node:fs';
 import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
 import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
+import { validateToolArguments } from '../tools/validation.js';
 import { getPlanDisabledTools, getRuntimeDisabledTools } from '../tools/constants.js';
 import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, dropContextFromHistory, createTraceEvent, summarizeToolArguments, safeProviderId, } from '../session/index.js';
@@ -479,6 +480,20 @@ export async function runAgentCore(opts) {
                             ...(tc.id ? { providerToolCallId: tc.id } : {}),
                         });
                     }
+                    const traceToolRetry = (tc, index, retry) => {
+                        const traceCall = tracedCalls[index];
+                        emitTrace('tool_retry', {
+                            tool: tc.name,
+                            argumentHash: traceCall.args.sha256,
+                            attempt: retry.attempt,
+                            nextAttempt: retry.nextAttempt,
+                            waitMs: retry.waitMs,
+                            code: retry.code,
+                        }, {
+                            toolCallId: traceCall.toolCallId,
+                            ...(tc.id ? { providerToolCallId: tc.id } : {}),
+                        });
+                    };
                     const traceToolEnd = (tc, index, outcome) => {
                         const traceCall = tracedCalls[index];
                         emitTrace('tool_call_end', {
@@ -488,7 +503,9 @@ export async function runAgentCore(opts) {
                             code: outcome.code,
                             retryable: outcome.retryable,
                             durationMs: outcome.durationMs ?? 0,
-                            retry: 0,
+                            attempt: outcome.attempts ?? 1,
+                            retry: Math.max(0, (outcome.attempts ?? 1) - 1),
+                            retryDelayMs: outcome.retryDelayMs ?? 0,
                             changedFiles: outcome.changedFiles ?? [],
                         }, {
                             toolCallId: traceCall.toolCallId,
@@ -529,7 +546,10 @@ export async function runAgentCore(opts) {
                             for (const tc of batch)
                                 hooks.onToolHeader?.(tc);
                             hooks.onToolStart?.(batch[0].name);
-                            const started = batch.map((tc) => executeToolOutcome(tc.name, tc.arguments, signal, { dropContext }));
+                            const started = batch.map((tc, offset) => executeToolOutcome(tc.name, tc.arguments, signal, {
+                                dropContext,
+                                onRetry: (retry) => traceToolRetry(tc, i + offset, retry),
+                            }));
                             for (let k = 0; k < batch.length; k++) {
                                 const tc = batch[k];
                                 const outcome = await started[k];
@@ -559,8 +579,11 @@ export async function runAgentCore(opts) {
                                 const tc = batch[k];
                                 const parsed = parseArgs(tc.arguments);
                                 const tool = tools.find((candidate) => candidate.name === tc.name);
+                                const argumentsValid = tool && parsed !== null
+                                    ? validateToolArguments(tool, parsed).valid
+                                    : false;
                                 let denied;
-                                if (tool) {
+                                if (tool && argumentsValid) {
                                     const perm = await checkPermission(tool, parsed ?? {}, signal);
                                     emitTrace('permission', {
                                         source: 'agent_tool',
@@ -586,13 +609,14 @@ export async function runAgentCore(opts) {
                             const firstAllowed = entries.find((entry) => !entry.denied);
                             if (firstAllowed)
                                 hooks.onToolStart?.(firstAllowed.tc.name);
-                            const started = entries.map((entry) => entry.denied
+                            const started = entries.map((entry, offset) => entry.denied
                                 ? Promise.resolve(entry.denied)
                                 : executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
                                     dropContext,
                                     onLockAcquired: (lockedArgs) => {
                                         entry.diff = readDiffContext(entry.tc, lockedArgs);
                                     },
+                                    onRetry: (retry) => traceToolRetry(entry.tc, i + offset, retry),
                                 }));
                             for (let k = 0; k < entries.length; k++) {
                                 const entry = entries[k];
@@ -642,7 +666,10 @@ export async function runAgentCore(opts) {
                             // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
                             const parsed = parseArgs(tc.arguments);
                             const tool = tools.find((t) => t.name === tc.name);
-                            if (tool) {
+                            const argumentsValid = tool && parsed !== null
+                                ? validateToolArguments(tool, parsed).valid
+                                : false;
+                            if (tool && argumentsValid) {
                                 const perm = await checkPermission(tool, parsed ?? {}, signal);
                                 emitTrace('permission', {
                                     source: 'agent_tool',
@@ -676,6 +703,7 @@ export async function runAgentCore(opts) {
                                     if (mutationParsed)
                                         diff = readDiffContext(tc, lockedArgs);
                                 },
+                                onRetry: (retry) => traceToolRetry(tc, i, retry),
                             });
                             traceToolEnd(tc, i, outcome);
                             const output = outcome.output;

package/dist/permissions/index.js

@@ -33,7 +33,13 @@ export function permissionFingerprint(tool, args) {
         subject = { command: args.command.trim() };
     }
     else {
-        const resources = tool.capabilities?.resources?.(args).filter(Boolean).sort();
+        let resources;
+        try {
+            resources = tool.capabilities?.resources?.(args).filter(Boolean).sort();
+        }
+        catch {
+            resources = undefined;
+        }
         // File mutations may be granted by their concrete resource. Coarse resources such as
         // "workspace" must retain arguments so task/process-like calls cannot become tool-wide.
         subject = resources?.length && typeof args.path === 'string'

package/dist/tools/builtins/edit-file.js

@@ -30,10 +30,20 @@ export const editFileTool = {
         const normNew = newStr.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
         const count = norm.split(normOld).length - 1;
         if (count === 0) {
-            return `错误:在 ${path} 中未找到 old_string。不要重试相同参数；请先 read_file 读取目标区域，再从返回内容逐字复制新的 old_string 后重试。`;
+            return {
+                status: 'error',
+                code: 'EDIT_CONFLICT',
+                retryable: false,
+                output: `错误:在 ${path} 中未找到 old_string。不要重试相同参数；请先 read_file 读取目标区域，再从返回内容逐字复制新的 old_string 后重试。`,
+            };
         }
         if (count > 1) {
-            return `错误:old_string 在 ${path} 中出现 ${count} 次,不唯一。请加入更多上下文使其唯一。`;
+            return {
+                status: 'error',
+                code: 'EDIT_CONFLICT',
+                retryable: false,
+                output: `错误:old_string 在 ${path} 中出现 ${count} 次,不唯一。请加入更多上下文使其唯一。`,
+            };
         }
         // 用函数形式替换,避免 new_string 里的 $ 被当特殊模式
         const updated = norm.replace(normOld, () => normNew);
@@ -45,7 +55,7 @@ export const editFileTool = {
             return {
                 status: 'error',
                 code: 'POSTCONDITION_FAILED',
-                retryable: true,
+                retryable: false,
                 output: postcondition.diagnostics
                     .map((item) => `[${item.code ?? 'V0_FAILED'}] ${item.file ?? path}: ${item.message}`)
                     .join('\n'),

package/dist/tools/builtins/web-fetch.js

@@ -49,7 +49,12 @@ export const webFetchTool = {
             const contentType = resp.headers.get('content-type') ?? '';
             const text = await resp.text();
             if (!resp.ok) {
-                return `错误:抓取失败 HTTP ${resp.status} ${resp.statusText}\n${text.slice(0, 500)}`;
+                return {
+                    status: 'error',
+                    code: 'HTTP_ERROR',
+                    retryable: resp.status === 408 || resp.status === 429 || resp.status >= 500,
+                    output: `错误:抓取失败 HTTP ${resp.status} ${resp.statusText}\n${text.slice(0, 500)}`,
+                };
             }
             const isHtml = /html/i.test(contentType) ||
                 /^\s*<!doctype html/i.test(text) ||
@@ -65,12 +70,23 @@ export const webFetchTool = {
         }
         catch (e) {
             if (ctrl.signal.aborted) {
-                if (externalSignal?.aborted)
-                    return `错误:已中断: ${url.href}`;
-                return `错误:抓取超时(${FETCH_TIMEOUT_MS}ms): ${url.href}`;
+                if (externalSignal?.aborted) {
+                    return { status: 'aborted', code: 'ABORTED', retryable: false, output: `错误:已中断: ${url.href}` };
+                }
+                return {
+                    status: 'error',
+                    code: 'TIMEOUT',
+                    retryable: true,
+                    output: `错误:抓取超时(${FETCH_TIMEOUT_MS}ms): ${url.href}`,
+                };
             }
             const msg = e instanceof Error ? e.message : String(e);
-            return `错误:抓取失败: ${msg}`;
+            return {
+                status: 'error',
+                code: 'NETWORK_ERROR',
+                retryable: true,
+                output: `错误:抓取失败: ${msg}`,
+            };
         }
         finally {
             clearTimeout(timer);

package/dist/tools/builtins/web-search.js

@@ -75,7 +75,12 @@ export const webSearchTool = {
                 data = JSON.parse(text);
             }
             catch {
-                return `错误:搜索返回非 JSON(HTTP ${resp.status}): ${text.slice(0, 500)}`;
+                return {
+                    status: 'error',
+                    code: 'HTTP_ERROR',
+                    retryable: resp.status === 408 || resp.status === 429 || resp.status >= 500,
+                    output: `错误:搜索返回非 JSON(HTTP ${resp.status}): ${text.slice(0, 500)}`,
+                };
             }
             // AnySearch 成功返回 code===0;否则把 message/request_id 喂回 LLM。
             if (!resp.ok || data?.code !== 0) {
@@ -92,7 +97,13 @@ export const webSearchTool = {
                 else if (resp.status === 429) {
                     hint = ' 触发限流,请稍后重试。';
                 }
-                return `错误:搜索失败 [${code}] ${message}${rid}${hint}`;
+                return {
+                    status: 'error',
+                    code: !resp.ok || Number(code) === 429 ? 'HTTP_ERROR' : 'EXECUTION_ERROR',
+                    retryable: resp.status === 408 || resp.status === 429 ||
+                        resp.status >= 500 || Number(code) === 429,
+                    output: `错误:搜索失败 [${code}] ${message}${rid}${hint}`,
+                };
             }
             const results = data?.data?.results;
             if (!Array.isArray(results) || results.length === 0) {
@@ -129,10 +140,23 @@ export const webSearchTool = {
         }
         catch (e) {
             if (ctrl.signal.aborted) {
-                return `错误:搜索超时(${SEARCH_TIMEOUT_MS}ms)。`;
+                if (externalSignal?.aborted) {
+                    return { status: 'aborted', code: 'ABORTED', retryable: false, output: '错误:搜索已中断。' };
+                }
+                return {
+                    status: 'error',
+                    code: 'TIMEOUT',
+                    retryable: true,
+                    output: `错误:搜索超时(${SEARCH_TIMEOUT_MS}ms)。`,
+                };
             }
             const msg = e instanceof Error ? e.message : String(e);
-            return `错误:联网搜索请求失败: ${msg}`;
+            return {
+                status: 'error',
+                code: 'NETWORK_ERROR',
+                retryable: true,
+                output: `错误:联网搜索请求失败: ${msg}`,
+            };
         }
         finally {
             clearTimeout(timer);

package/dist/tools/builtins/write-file.js

@@ -25,7 +25,7 @@ export const writeFileTool = {
             return {
                 status: 'error',
                 code: 'POSTCONDITION_FAILED',
-                retryable: true,
+                retryable: false,
                 output: postcondition.diagnostics
                     .map((item) => `[${item.code ?? 'V0_FAILED'}] ${item.file ?? path}: ${item.message}`)
                     .join('\n'),

package/dist/tools/registry.js

@@ -2,6 +2,8 @@ import { builtinTools } from './builtins/index.js';
 import { beginPathMutation, beginWorkspaceMutation, endPathMutation, endWorkspaceMutation, getCurrentTurnMutationState, } from '../rollback/index.js';
 import { enforceSandbox } from '../sandbox/index.js';
 import { resolveResourceLockRequests, toolResourceLockManager } from './resource-lock.js';
+import { executeWithToolRetry } from './retry.js';
+import { validateToolArguments } from './validation.js';
 import { t } from '../i18n/index.js';
 import { isToolErrorOutput } from './result.js';
 /**
@@ -67,7 +69,7 @@ function isStructuredOutcome(value) {
         typeof value.status === 'string' && typeof value.code === 'string' &&
         typeof value.retryable === 'boolean' && typeof value.output === 'string';
 }
-function normalizeOutcome(value, capabilities, durationMs, changedFiles) {
+function normalizeOutcome(value, durationMs, changedFiles) {
     if (isStructuredOutcome(value)) {
         return {
             ...value,
@@ -79,7 +81,8 @@ function normalizeOutcome(value, capabilities, durationMs, changedFiles) {
     return {
         status: failed ? 'error' : 'success',
         code: failed ? 'EXECUTION_ERROR' : 'OK',
-        retryable: failed && capabilities.retry !== 'never',
+        // Legacy string errors carry no transient classification and are never retried blindly.
+        retryable: false,
         output: value,
         changedFiles,
         durationMs,
@@ -95,92 +98,145 @@ function terminalOutcome(status, code, output, startedAt, changedFiles = []) {
         durationMs: Date.now() - startedAt,
     };
 }
-/**
- * 结构化工具调度入口。永不抛错；旧字符串工具在此归一化为 ToolOutcome。
- * 权限仍由 Agent 在展示工具头之前预检，保持现有交互时序。
- */
-export async function executeToolOutcome(name, argsRaw, signal, opts) {
+function isTransientExecutionError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const value = error;
+    if (value.name === 'AbortError' || value.name === 'APIUserAbortError')
+        return false;
+    if (value.status === 408 || value.status === 429 ||
+        (typeof value.status === 'number' && value.status >= 500))
+        return true;
+    if (['ETIMEDOUT', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'EPIPE']
+        .includes(value.code ?? ''))
+        return true;
+    return value.name === 'APIConnectionError' ||
+        value.name === 'APIConnectionTimeoutError' ||
+        (typeof value.message === 'string' && /\btime(?:d)?\s*out\b|ETIMEDOUT/i.test(value.message));
+}
+function executionErrorOutcome(name, error, startedAt, changedFiles) {
+    const transient = isTransientExecutionError(error);
+    const value = error;
+    const timeout = transient && (value?.code === 'ETIMEDOUT' ||
+        value?.name === 'APIConnectionTimeoutError' ||
+        (error instanceof Error && /\btime(?:d)?\s*out\b|ETIMEDOUT/i.test(error.message)));
+    return {
+        status: 'error',
+        code: timeout ? 'TIMEOUT' : transient ? 'NETWORK_ERROR' : 'EXECUTION_ERROR',
+        retryable: transient,
+        output: t('toolError.execution', {
+            name,
+            message: error instanceof Error ? error.message : String(error),
+        }),
+        changedFiles,
+        durationMs: Date.now() - startedAt,
+    };
+}
+/** One complete attempt: acquire/release locks and capture rollback independently. */
+async function executeToolAttempt(tool, args, signal, opts, notifyLockAcquired) {
     const startedAt = Date.now();
-    if (signal?.aborted) {
-        return terminalOutcome('aborted', 'ABORTED', t('command.interrupted'), startedAt);
-    }
-    const tool = findTool(name);
-    if (!tool) {
-        return terminalOutcome('error', 'UNKNOWN_TOOL', t('toolError.unknown', { name }), startedAt);
-    }
-    let args;
-    try {
-        args = argsRaw.trim() ? JSON.parse(argsRaw) : {};
-    }
-    catch {
-        return terminalOutcome('error', 'INVALID_JSON', t('toolError.invalidJson', { name, arguments: argsRaw }), startedAt);
-    }
     const capabilities = getToolCapabilities(tool);
     let mutationVersionBefore;
     let capturedPath;
     try {
-        const sandboxError = enforceSandbox(name, args);
-        if (sandboxError) {
-            return terminalOutcome('denied', 'SANDBOX_DENIED', sandboxError, startedAt);
-        }
         const requests = resolveResourceLockRequests(capabilities, args);
         return await toolResourceLockManager.withLocks(requests, signal, async () => {
-            // Diff 等执行前观察必须发生在真正持锁之后；同路径排队调用才能看到前序写入结果。
-            opts?.onLockAcquired?.(args);
+            if (notifyLockAcquired)
+                opts?.onLockAcquired?.(args);
             const mutationBefore = getCurrentTurnMutationState();
             mutationVersionBefore = mutationBefore.version;
-            const pathCapture = isFileMutationTool(name) && typeof args.path === 'string' && args.path
+            const pathCapture = isFileMutationTool(tool.name) && typeof args.path === 'string' && args.path
                 ? beginPathMutation(args.path)
                 : null;
             capturedPath = pathCapture?.path;
-            // 进程和未知扩展可能间接改动任意文件；其 workspace lock 同时隔离全盘捕获。
             const workspaceCapture = capabilities.effect === 'process' || capabilities.effect === 'unknown'
                 ? beginWorkspaceMutation()
                 : null;
             let raw;
             try {
-                raw = await tool.execute(args, {
-                    signal,
-                    dropContext: opts?.dropContext,
-                });
+                raw = await tool.execute(args, { signal, dropContext: opts?.dropContext });
             }
             finally {
                 if (pathCapture)
-                    endPathMutation(pathCapture, name);
+                    endPathMutation(pathCapture, tool.name);
                 if (workspaceCapture)
-                    endWorkspaceMutation(workspaceCapture, name);
+                    endWorkspaceMutation(workspaceCapture, tool.name);
             }
             const mutationAfter = getCurrentTurnMutationState();
             const changedFiles = mutationAfter.version !== mutationBefore.version
                 ? pathCapture
-                    ? mutationAfter.changedFiles
-                        .filter((item) => item.path === pathCapture.path)
-                        .map((item) => item.path)
+                    ? mutationAfter.changedFiles.filter((item) => item.path === pathCapture.path).map((item) => item.path)
                     : mutationAfter.changedFiles.map((item) => item.path)
                 : [];
             if (signal?.aborted) {
                 return terminalOutcome('aborted', 'ABORTED', String(isStructuredOutcome(raw) ? raw.output : raw), startedAt, changedFiles);
             }
-            return normalizeOutcome(raw, capabilities, Date.now() - startedAt, changedFiles);
+            return normalizeOutcome(raw, Date.now() - startedAt, changedFiles);
         });
     }
     catch (error) {
         const mutationAfter = getCurrentTurnMutationState();
-        const changedFiles = mutationVersionBefore !== undefined &&
-            mutationAfter.version !== mutationVersionBefore
+        const changedFiles = mutationVersionBefore !== undefined && mutationAfter.version !== mutationVersionBefore
             ? capturedPath
-                ? mutationAfter.changedFiles
-                    .filter((item) => item.path === capturedPath)
-                    .map((item) => item.path)
+                ? mutationAfter.changedFiles.filter((item) => item.path === capturedPath).map((item) => item.path)
                 : mutationAfter.changedFiles.map((item) => item.path)
             : [];
         if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
             return terminalOutcome('aborted', 'ABORTED', t('command.interrupted'), startedAt, changedFiles);
         }
-        return terminalOutcome('error', 'EXECUTION_ERROR', t('toolError.execution', {
-            name,
-            message: error instanceof Error ? error.message : String(error),
-        }), startedAt, changedFiles);
+        return executionErrorOutcome(tool.name, error, startedAt, changedFiles);
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * 结构化工具调度入口。永不抛错；旧字符串工具在此归一化为 ToolOutcome。
+ * 权限仍由 Agent 在展示工具头之前预检，保持现有交互时序。
+ */
+export async function executeToolOutcome(name, argsRaw, signal, opts) {
+    const startedAt = Date.now();
+    if (signal?.aborted) {
+        return terminalOutcome('aborted', 'ABORTED', t('command.interrupted'), startedAt);
+    }
+    const tool = findTool(name);
+    if (!tool) {
+        return terminalOutcome('error', 'UNKNOWN_TOOL', t('toolError.unknown', { name }), startedAt);
+    }
+    let parsed;
+    try {
+        parsed = argsRaw.trim() ? JSON.parse(argsRaw) : {};
+    }
+    catch {
+        return terminalOutcome('error', 'INVALID_JSON', t('toolError.invalidJson', { name, arguments: argsRaw }), startedAt);
+    }
+    const validation = validateToolArguments(tool, parsed);
+    if (!validation.valid) {
+        return terminalOutcome('error', validation.code, `错误:工具 ${name} 参数无效: ${validation.message}`, startedAt);
+    }
+    const args = parsed;
+    const fingerprint = `${name}\x00${stableJson(args)}`;
+    const sandboxError = enforceSandbox(name, args);
+    if (sandboxError) {
+        return terminalOutcome('denied', 'SANDBOX_DENIED', sandboxError, startedAt);
+    }
+    const capabilities = getToolCapabilities(tool);
+    try {
+        return await executeWithToolRetry(capabilities, fingerprint, signal, (attempt) => executeToolAttempt(tool, args, signal, opts, attempt === 1), opts?.onRetry);
+    }
+    catch (error) {
+        if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
+            return terminalOutcome('aborted', 'ABORTED', t('command.interrupted'), startedAt);
+        }
+        return executionErrorOutcome(name, error, startedAt, []);
     }
 }
 /** 字符串兼容入口：现有调用方、TUI 和 LLM history 无需同步迁移。 */

package/dist/tools/retry.js

@@ -0,0 +1,105 @@
+export const TOOL_RETRY_MAX_ATTEMPTS = 3;
+export const TOOL_RETRY_BASE_MS = 250;
+export const TOOL_RETRY_MAX_MS = 1_000;
+export const TOOL_RETRY_TOTAL_BUDGET_MS = 15_000;
+export const TOOL_RETRY_SAME_ARGS_WINDOW_MS = 60_000;
+export const TOOL_RETRY_SAME_ARGS_BUDGET = 2;
+const NEVER_RETRY_CODES = new Set([
+    'INVALID_JSON',
+    'INVALID_ARGUMENTS',
+    'INVALID_TOOL_SCHEMA',
+    'UNKNOWN_TOOL',
+    'SANDBOX_DENIED',
+    'PERMISSION_DENIED',
+    'TOOL_DISABLED',
+    'MODE_DENIED',
+    'ABORTED',
+    'EDIT_CONFLICT',
+    'POSTCONDITION_FAILED',
+    'PROCESS_FAILED',
+    'MCP_ERROR',
+]);
+const fingerprintBudgets = new Map();
+const MAX_TRACKED_FINGERPRINTS = 512;
+function reserveFingerprintRetry(fingerprint, now) {
+    let budget = fingerprintBudgets.get(fingerprint);
+    if (!budget || now - budget.startedAt >= TOOL_RETRY_SAME_ARGS_WINDOW_MS) {
+        budget = { startedAt: now, retries: 0 };
+        fingerprintBudgets.set(fingerprint, budget);
+    }
+    if (budget.retries >= TOOL_RETRY_SAME_ARGS_BUDGET)
+        return false;
+    budget.retries++;
+    if (fingerprintBudgets.size > MAX_TRACKED_FINGERPRINTS) {
+        const oldest = fingerprintBudgets.keys().next().value;
+        if (oldest)
+            fingerprintBudgets.delete(oldest);
+    }
+    return true;
+}
+function shouldRetry(outcome, capabilities) {
+    return capabilities.retry !== 'never' &&
+        outcome.status === 'error' &&
+        outcome.retryable === true &&
+        !NEVER_RETRY_CODES.has(outcome.code);
+}
+function backoff(attempt) {
+    return Math.min(TOOL_RETRY_MAX_MS, TOOL_RETRY_BASE_MS * 2 ** (attempt - 1));
+}
+function abortError() {
+    const error = new Error('Tool retry aborted');
+    error.name = 'AbortError';
+    return error;
+}
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(abortError());
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(abortError());
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** Retry safe/idempotent transient outcomes; each execute call owns one complete lock attempt. */
+export async function executeWithToolRetry(capabilities, fingerprint, signal, execute, onRetry) {
+    const startedAt = Date.now();
+    let retryDelayMs = 0;
+    for (let attempt = 1; attempt <= TOOL_RETRY_MAX_ATTEMPTS; attempt++) {
+        const outcome = await execute(attempt);
+        const elapsed = Date.now() - startedAt;
+        const waitMs = backoff(attempt);
+        const canRetry = attempt < TOOL_RETRY_MAX_ATTEMPTS &&
+            shouldRetry(outcome, capabilities) &&
+            elapsed + waitMs <= TOOL_RETRY_TOTAL_BUDGET_MS &&
+            !signal?.aborted &&
+            reserveFingerprintRetry(fingerprint, Date.now());
+        if (!canRetry) {
+            return {
+                ...outcome,
+                durationMs: elapsed,
+                attempts: attempt,
+                retryDelayMs,
+            };
+        }
+        try {
+            onRetry?.({ attempt, nextAttempt: attempt + 1, waitMs, code: outcome.code });
+        }
+        catch {
+            // Retry telemetry is best-effort and must never change tool execution.
+        }
+        await sleep(waitMs, signal);
+        retryDelayMs += waitMs;
+    }
+    throw new Error('unreachable tool retry state');
+}
+/** Test/session reset seam; production never needs to clear the bounded TTL map. */
+export function resetToolRetryBudgets() {
+    fingerprintBudgets.clear();
+}

package/dist/tools/validation.js

@@ -0,0 +1,80 @@
+import Ajv from 'ajv';
+import Ajv2020 from 'ajv/dist/2020.js';
+const options = {
+    allErrors: true,
+    strict: false,
+    coerceTypes: false,
+    useDefaults: false,
+    removeAdditional: false,
+    validateFormats: false,
+    allowUnionTypes: true,
+};
+const draft7 = new Ajv(options);
+const draft2020 = new Ajv2020(options);
+const cache = new WeakMap();
+function compile(schema) {
+    const cached = cache.get(schema);
+    if (cached)
+        return cached;
+    const preferred = typeof schema.$schema === 'string' && schema.$schema.includes('2020-12')
+        ? [draft2020, draft7]
+        : [draft7, draft2020];
+    let lastError;
+    for (const ajv of preferred) {
+        try {
+            const result = { valid: true, validate: ajv.compile(schema) };
+            cache.set(schema, result);
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    const result = {
+        valid: false,
+        message: lastError instanceof Error ? lastError.message : String(lastError),
+    };
+    cache.set(schema, result);
+    return result;
+}
+function formatErrors(errors) {
+    if (!errors?.length)
+        return '参数不符合 JSON Schema';
+    return errors.slice(0, 5).map((error) => {
+        const location = error.instancePath || '/';
+        if (error.keyword === 'required') {
+            const property = String(error.params.missingProperty ?? '?');
+            return `${location} 缺少必填字段 ${JSON.stringify(property)}`;
+        }
+        if (error.keyword === 'additionalProperties') {
+            const property = String(error.params.additionalProperty ?? '?');
+            return `${location} 含未知字段 ${JSON.stringify(property)}`;
+        }
+        return `${location} ${error.message ?? error.keyword}`;
+    }).join('; ');
+}
+/** Validate without coercing, defaulting, removing, or otherwise mutating model arguments. */
+export function validateToolArguments(tool, args) {
+    if (!args || typeof args !== 'object' || Array.isArray(args)) {
+        return {
+            valid: false,
+            code: 'INVALID_ARGUMENTS',
+            message: '参数根节点必须是 JSON object',
+        };
+    }
+    const compiled = compile(tool.parameters);
+    if (!compiled.valid) {
+        return {
+            valid: false,
+            code: 'INVALID_TOOL_SCHEMA',
+            message: `工具 schema 无法编译: ${compiled.message}`,
+        };
+    }
+    if (compiled.validate(args))
+        return { valid: true };
+    return {
+        valid: false,
+        code: 'INVALID_ARGUMENTS',
+        message: formatErrors(compiled.validate.errors),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "prepare": "npm run build"
   },
   "dependencies": {
+    "ajv": "8.20.0",
     "cli-highlight": "^2.1.11",
     "dotenv": "^16.0.0",
     "fast-glob": "^3.0.0",