mocode-ai 0.7.2 → 1.0.1

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { contentHash } from '../../changeset/index.js';
 import { MAX_FILE_LINES } from '../constants.js';
 /** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
  * 配合 description 中的 PAGINATION IS MANDATORY 引导。
@@ -30,6 +31,7 @@ export const readFileTool = {
         // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
         const limit = Math.min(Number(args.limit ?? DEFAULT_READ_LIMIT), MAX_FILE_LINES);
         const data = await readFile(resolve(path), 'utf8');
+        const artifactHeader = `[artifact source=read_file path=${path} hash=${contentHash(data)}]`;
         const lines = data.split(/\r?\n/);
         const start = Math.max(0, offset - 1);
         const end = Math.min(lines.length, start + limit);
@@ -38,8 +40,8 @@ export const readFileTool = {
             .map((l, i) => `${String(start + i + 1).padStart(6, ' ')}\t${l}`)
             .join('\n');
         if (end < lines.length) {
-            return body + `\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`;
+            return artifactHeader + '\n' + body + `\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`;
         }
-        return body || '(空文件)';
+        return artifactHeader + '\n' + (body || '(空文件)');
     },
 };

package/dist/tools/builtins/task.js

@@ -8,12 +8,12 @@ import { isSubAgentEnabled } from '../../config/index.js';
 //
 // 适用:分而治之的复杂任务 / 隔离上下文避免子任务工具噪声撑爆主窗口。
 // 多个 task 在共享工作区期间由 capability scheduler 串行执行；隔离 workspace 落地后再开放并行写。
-export const taskTool = {
-    name: 'task',
+export const subAgentTool = {
+    name: 'sub-agent',
     risk: 'dangerous',
     description: [
-        'Spawn a sub-agent for an isolated sub-task (independent history; only its final summary returns to you).',
-        'Use when a task splits into independent parts or its many tool calls would bloat your context.',
+        'Spawn a capable worker for an isolated sub-task; only its structured result returns.',
+        'Pass context with facts the main agent already knows to prevent duplicate exploration and token waste.',
         'Cannot recursively spawn sub-agents.',
     ].join(''),
     parameters: {
@@ -26,11 +26,23 @@ export const taskTool = {
             tools: {
                 type: 'array',
                 items: { type: 'string' },
-                description: 'Optional whitelist of tool names the sub-agent is allowed to use (e.g. ["read_file","glob","grep","codegraph"] for read-only investigation). Omit to allow all tools. If the sub-task needs verification/build/test (running scripts, typecheck, etc.), remember to include "run_command".',
+                description: 'Optional whitelist for deliberate specialization. Omit it to preserve the worker full capability for its mode.',
             },
             maxSteps: {
                 type: 'number',
-                description: 'Optional step limit for the sub-agent (default 50). Lower if the sub-task should be quick.',
+                description: 'Optional loop-safety override. By default the worker uses the same step ceiling as the main agent; this is not a token budget.',
+            },
+            mode: {
+                type: 'string', enum: ['read', 'write'],
+                description: 'read tasks may run in parallel; write tasks use an isolated overlay and are merged by the coordinator.',
+            },
+            writeSet: {
+                type: 'array', items: { type: 'string' },
+                description: 'Known workspace-relative paths this task may write. Unknown write sets conservatively use the workspace lock.',
+            },
+            context: {
+                type: 'string',
+                description: 'Concise facts already learned by the main agent. Passing this avoids duplicate repository exploration.',
             },
         },
         required: ['prompt'],
@@ -47,20 +59,39 @@ export const taskTool = {
         const maxSteps = typeof args.maxSteps === 'number' && args.maxSteps > 0
             ? Math.floor(args.maxSteps)
             : undefined;
+        const mode = args.mode === 'write' ? 'write' : 'read';
+        const writeSet = Array.isArray(args.writeSet) ? args.writeSet.map(String) : undefined;
+        const context = typeof args.context === 'string' ? args.context.slice(0, 4000) : undefined;
         // 透传主 agent 的 abort signal:主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)。
-        const result = await spawnAgent({ prompt, tools, maxSteps, signal: ctx?.signal });
+        const result = await spawnAgent({ prompt, tools, maxSteps, signal: ctx?.signal, mode, writeSet, context });
+        let output;
         if (!result.completed) {
-            return t('task.interrupted');
+            output = `[SubAgentResult status=${result.status} tokens=${result.usage.totalTokens} readSet=${JSON.stringify(result.readSet)} changeSet=${result.changeSet?.id ?? 'none'} verification=not-run]\n${result.summary ?? t('task.interrupted')}`;
         }
-        if (!result.summary) {
-            return t('task.noSummary');
+        else if (!result.summary) {
+            output = t('task.noSummary');
         }
-        // 摘要可能很长,截到 MAX_OUTPUT 保主 history 不爆。
-        const summary = result.summary;
-        if (summary.length > MAX_OUTPUT) {
-            return (summary.slice(0, MAX_OUTPUT) +
-                `\n\n${t('task.summaryTruncated', { count: summary.length - MAX_OUTPUT })}`);
+        else {
+            // 摘要可能很长,截到 MAX_OUTPUT 保主 history 不爆。
+            const summary = [
+                result.summary,
+                `\n[SubAgentResult status=${result.status} tokens=${result.usage.totalTokens} prompt=${result.usage.promptTokens} completion=${result.usage.completionTokens} cached=${result.usage.cachedTokens} readSet=${JSON.stringify(result.readSet)} changeSet=${result.changeSet?.id ?? 'none'} verification=deferred-to-coordinator]`,
+            ].filter(Boolean).join('\n');
+            output = summary.length > MAX_OUTPUT ? (summary.slice(0, MAX_OUTPUT) +
+                `\n\n${t('task.summaryTruncated', { count: summary.length - MAX_OUTPUT })}`) : summary;
         }
-        return summary;
+        const code = result.status === 'aborted'
+            ? 'ABORTED'
+            : result.status === 'conflict'
+                ? 'CHANGE_CONFLICT'
+                : result.completed ? 'OK' : 'EXECUTION_ERROR';
+        const outcome = {
+            status: result.status === 'aborted' ? 'aborted' : result.completed ? 'success' : 'error',
+            code,
+            retryable: false,
+            output,
+            usage: result.usage,
+        };
+        return outcome;
     },
 };

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

@@ -1,36 +1,71 @@
-import { writeFile, mkdir } from 'node:fs/promises';
-import { resolve, dirname } from 'node:path';
-import { verifyWrittenFile } from '../../verification/postconditions.js';
-// ---------- write_file ----------
+import { commitChangeSet, createChangeSet, normalizeContentHash, summarizeChangeSet, } from '../../changeset/index.js';
+function conflict(path, details) {
+    return {
+        status: 'error',
+        code: 'CHANGE_CONFLICT',
+        retryable: false,
+        changedFiles: [],
+        staleFiles: [path],
+        output: `CHANGE_CONFLICT: ${path} was not changed. ${details} Do not retry these arguments. Call read_file on this exact path, then use the returned hash; use expected_hash=null only if read_file reports that the path is missing.`,
+    };
+}
 export const writeFileTool = {
     name: 'write_file',
-    description: 'Create or overwrite a file; parent dirs created.',
+    description: 'Create or replace one file transactionally. expected_hash may be omitted (or null) only for create-only writes to a path that must not exist; overwriting requires the hash from a fresh read_file artifact header.',
     risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {
             path: { type: 'string', description: 'File path' },
             content: { type: 'string', description: 'Full file content' },
+            expected_hash: {
+                type: ['string', 'null'],
+                description: 'Optional sha256 hash from read_file. Omit or pass null only when the path must not exist.',
+            },
         },
         required: ['path', 'content'],
     },
-    async execute(args) {
-        const path = String(args.path);
+    async execute(args, ctx) {
+        const file = String(args.path);
         const content = String(args.content);
-        const full = resolve(path);
-        await mkdir(dirname(full), { recursive: true });
-        await writeFile(full, content, 'utf8');
-        const postcondition = await verifyWrittenFile(full, content);
-        if (postcondition.status === 'failed') {
+        let expectedHash = null;
+        // Missing and explicit null are both safe create-only requests. They never
+        // overwrite: ChangeSet compares expectedHash=null against the current path.
+        if (args.expected_hash != null) {
+            expectedHash = normalizeContentHash(String(args.expected_hash));
+            if (!expectedHash)
+                return conflict(file, 'expected_hash 必须是 null 或 sha256:<64 hex>。');
+        }
+        const operation = expectedHash === null ? 'create' : 'update';
+        const result = await commitChangeSet(createChangeSet([{
+                path: file,
+                operation,
+                expectedHash,
+                replacement: content,
+            }]), ctx?.signal);
+        if (result.status === 'conflict') {
+            const item = result.conflicts[0];
+            return conflict(file, `expected=${item?.expectedHash ?? 'missing'}, actual=${item?.actualHash ?? 'missing'}。请重新读取后再写入。`);
+        }
+        if (result.status === 'failed') {
             return {
                 status: 'error',
-                code: 'POSTCONDITION_FAILED',
-                retryable: true,
-                output: postcondition.diagnostics
-                    .map((item) => `[${item.code ?? 'V0_FAILED'}] ${item.file ?? path}: ${item.message}`)
-                    .join('\n'),
+                code: 'EXECUTION_ERROR',
+                retryable: false,
+                changedFiles: [],
+                output: `错误:ChangeSet 提交失败并已执行恢复: ${result.error}`,
             };
         }
-        return `已写入 ${path} (${content.length} 字符, sha256=${postcondition.actualHash})`;
+        const summary = summarizeChangeSet(result.changeSet);
+        return {
+            status: 'success',
+            code: 'OK',
+            retryable: false,
+            changedFiles: result.changedFiles,
+            changeSet: summary,
+            output: result.changedFiles.length === 0
+                ? `文件 ${file} 内容未变化 (ChangeSet ${summary.id})。`
+                : `已事务化写入 ${file} (${content.length} 字符, ChangeSet ${summary.id}, sha256=${summary.changes[0]?.afterHash})。`,
+        };
     },
 };

package/dist/tools/constants.js

@@ -26,7 +26,7 @@ export const IGNORE = ['**/node_modules/**', '**/.git/**'];
 // ── plan 模式(只读规划,不执行)──────────────────────────────────────────────
 /**
  * plan 模式下从工具 schema 里剔除的工具(模型根本看不到 → 调不到):
- * 写盘 / 命令 / 记忆写入类 + task(派生子 agent,plan 模式只读不可有副作用)。单一事实源,
+ * 写盘 / 命令 / 记忆写入类 + sub-agent（派生子 agent，plan 模式只读不可有副作用）。单一事实源,
  * 被 llm(planChatTools)与 agent(防御 backstop)共用。
  * 只读工具(read_file/glob/grep/codegraph/web_search/web_fetch/use_skill/ask_human/memory_search/memory_list)保留。
  */
@@ -37,7 +37,7 @@ export const PLAN_DISABLED_TOOLS = new Set([
     'memory_save',
     'memory_update',
     'memory_forget',
-    'task',
+    'sub-agent',
 ]);
 /**
  * 按当前 isMemoryEnabled() 现算 plan 模式应屏蔽的工具。
@@ -56,5 +56,5 @@ export function getPlanDisabledTools() {
 }
 /** auto/plan 共用的运行时功能开关防线；关闭时即使模型幻觉调用也不得执行。 */
 export function getRuntimeDisabledTools() {
-    return isSubAgentEnabled() ? new Set() : new Set(['task']);
+    return isSubAgentEnabled() ? new Set() : new Set(['sub-agent']);
 }

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,148 @@ 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
+            // Transactional tools own their full write-set capture inside ChangeSet commit.
+            const pathCapture = !capabilities.delegatesResourceLocks &&
+                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);
+                const aborted = terminalOutcome('aborted', 'ABORTED', String(isStructuredOutcome(raw) ? raw.output : raw), startedAt, changedFiles);
+                return isStructuredOutcome(raw) ? { ...aborted, usage: raw.usage } : aborted;
             }
-            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 无需同步迁移。 */