@lingxiao-office/sdk 1.0.0

package/dist/tools/Registry.js

@@ -0,0 +1,1484 @@
+import Ajv from 'ajv';
+import { existsSync } from 'fs';
+import { resolve, isAbsolute } from 'path';
+import { Tool, createToolError, normalizeJsonSchemaForOpenAI } from './Tool.js';
+import { getToolMetadata, requiresReadFirst } from './ToolMetadata.js';
+import { auditOfficeToolExecution } from './implementations/office/OfficeAuditLog.js';
+import { auditModeEvent } from '../core/ModeAudit.js';
+import { isOfficeToolName } from './officeToolContract.js';
+import { config as runtimeConfig } from '../config.js';
+import { getToolFailureLoopGuard } from '../agents/runtime/ToolFailureLoopGuard.js';
+import { coreLogger } from '../core/Log.js';
+import { evaluateToolPermission, getToolPermissionContextFromToolContext, } from '../core/PermissionSystem.js';
+import { resolveModeRuntimeProjection } from '../core/ModeRuntimeProjection.js';
+import { resolveModeToolDecision, } from '../core/ModeToolPolicy.js';
+import { getTeamMemberRegistry } from '../core/TeamMailbox.js';
+import { normalizeToolResult } from '../contracts/types/Tool.js';
+import { getPromptCatalog } from '../agents/prompts/i18n/catalog.js';
+const jsonSchemaValidator = new Ajv({
+    allErrors: true,
+    strict: false,
+    allowUnionTypes: true,
+});
+const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 60_000;
+function normalizeExecutionTimeoutMs(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.max(1, Math.floor(value))
+        : undefined;
+}
+function resolveToolExecutionTimeoutMs(tool, parsedArgs, context) {
+    const toolSpecificTimeout = normalizeExecutionTimeoutMs(tool.getExecutionTimeoutMs?.(parsedArgs, context));
+    if (toolSpecificTimeout !== undefined) {
+        return toolSpecificTimeout;
+    }
+    const contextTimeout = typeof context?.toolExecutionTimeoutMs === 'number'
+        ? context.toolExecutionTimeoutMs
+        : typeof context?.executionTimeoutMs === 'number'
+            ? context.executionTimeoutMs
+            : undefined;
+    const configured = contextTimeout ?? runtimeConfig.tools?.execution_timeout_ms ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+    return typeof configured === 'number' && Number.isFinite(configured) && configured > 0
+        ? Math.min(600_000, Math.floor(configured))
+        : DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function formatToolTimeoutError(name, timeoutMs) {
+    return `TOOL_TIMEOUT: 工具 "${name}" 执行 watchdog 超过 ${timeoutMs}ms，已中止本次调用。请缩小输入范围、降低并发，或为该工具设置更合适的 timeout 后重试。`;
+}
+function formatToolAbortedError(name) {
+    return `TOOL_ABORTED: 工具 "${name}" 已被中止。`;
+}
+/**
+ * 从 ToolResult.error 中提取 LLM_RECOVERY.code，与 createToolError 的输出对齐。
+ * 格式: `${message}\n\nLLM_RECOVERY=${JSON.stringify({code, message, ...})}`
+ */
+function extractErrorCodeFromText(errorText) {
+    if (!errorText)
+        return '';
+    const marker = 'LLM_RECOVERY=';
+    const idx = errorText.lastIndexOf(marker);
+    if (idx < 0) {
+        const firstLine = errorText.split('\n')[0] || '';
+        const colonIdx = firstLine.indexOf(':');
+        return colonIdx > 0 ? firstLine.slice(0, colonIdx).trim() : firstLine.trim();
+    }
+    const jsonText = errorText.slice(idx + marker.length).trim();
+    try {
+        const parsed = JSON.parse(jsonText);
+        return typeof parsed?.code === 'string' ? parsed.code : '';
+    }
+    catch {
+        return '';
+    }
+}
+async function executeToolWithTimeout(name, tool, parsedArgs, context) {
+    const timeoutMs = resolveToolExecutionTimeoutMs(tool, parsedArgs, context);
+    const timeoutController = new AbortController();
+    const upstreamSignal = context?.abortSignal;
+    const signal = upstreamSignal
+        ? AbortSignal.any([upstreamSignal, timeoutController.signal])
+        : timeoutController.signal;
+    let timedOut = false;
+    let timer;
+    let abortCleanup;
+    const toolContext = { ...(context || {}), abortSignal: signal };
+    try {
+        if (signal.aborted) {
+            return { success: false, data: null, error: formatToolAbortedError(name) };
+        }
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                timedOut = true;
+                timeoutController.abort(formatToolTimeoutError(name, timeoutMs));
+                reject(new Error(formatToolTimeoutError(name, timeoutMs)));
+            }, timeoutMs);
+        });
+        const abortPromise = new Promise((_, reject) => {
+            const onAbort = () => reject(new Error(formatToolAbortedError(name)));
+            signal.addEventListener('abort', onAbort, { once: true });
+            abortCleanup = () => signal.removeEventListener('abort', onAbort);
+        });
+        const result = await Promise.race([
+            Promise.resolve(tool.execute(parsedArgs, toolContext)),
+            timeoutPromise,
+            abortPromise,
+        ]);
+        return normalizeToolResult(result);
+    }
+    catch (error) {
+        return {
+            success: false,
+            data: null,
+            error: timedOut
+                ? formatToolTimeoutError(name, timeoutMs)
+                : isAbortError(error)
+                    ? formatToolAbortedError(name)
+                    : error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        abortCleanup?.();
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string')
+        ? value
+        : undefined;
+}
+function recordValue(value) {
+    return isRecord(value) ? value : undefined;
+}
+function extractLlmRecovery(data) {
+    const recovery = isRecord(data) ? data.llm_recovery : undefined;
+    if (!isRecord(recovery))
+        return undefined;
+    const nextTool = isRecord(recovery.next_tool) && typeof recovery.next_tool.name === 'string'
+        ? {
+            name: recovery.next_tool.name,
+            ...(isRecord(recovery.next_tool.args) ? { args: recovery.next_tool.args } : {}),
+        }
+        : undefined;
+    const candidates = stringArray(recovery.candidates);
+    const exampleArgs = recordValue(recovery.example_args);
+    const retryArgs = recordValue(recovery.retry_args);
+    const dto = {
+        ...(typeof recovery.code === 'string' ? { code: recovery.code } : {}),
+        ...(typeof recovery.message === 'string' ? { message: recovery.message } : {}),
+        ...(typeof recovery.fix === 'string' ? { fix: recovery.fix } : {}),
+        ...('hints' in recovery ? { hints: recovery.hints } : {}),
+        ...(candidates ? { candidates } : {}),
+        ...(nextTool ? { next_tool: nextTool } : {}),
+        ...(exampleArgs ? { example_args: exampleArgs } : {}),
+        ...(retryArgs ? { retry_args: retryArgs } : {}),
+    };
+    return Object.keys(dto).length > 0 ? dto : undefined;
+}
+// 把单条 issue 格式化为可自我纠正的人类可读描述。
+// 关键改进：z.union（如 structured_patch 的 hunk）失败时，zod 顶层只给一句无信息量的
+// "Invalid input"。这里展开候选 variant，挑差异最小的那个，明确指出多/缺哪些字段，
+// 让调用方（含 LLM）能据此自我纠正，而不是反复瞎试。
+function formatZodIssue(issue, depth = 0) {
+    const path = issue.path && issue.path.length > 0 ? issue.path.join('.') : '(root)';
+    if (issue.code === 'invalid_union' && Array.isArray(issue.errors) && issue.errors.length > 0 && depth < 3) {
+        // 子 issue 最少的 variant = 最接近匹配的形态
+        const best = issue.errors
+            .map((variantIssues) => ({ issues: variantIssues, score: variantIssues.length }))
+            .sort((a, b) => a.score - b.score)[0];
+        if (best && best.issues.length > 0) {
+            const detail = best.issues.slice(0, 4).map((sub) => formatZodIssue(sub, depth + 1)).join('; ');
+            return `${path}: 不匹配任一允许形态，最接近的形态还差 → ${detail}`;
+        }
+    }
+    if (issue.code === 'unrecognized_keys' && Array.isArray(issue.keys) && issue.keys.length > 0) {
+        return `${path}: 含该形态不允许的字段 ${issue.keys.map((k) => `"${k}"`).join(', ')}（同一项不要混用多种形态的字段）`;
+    }
+    return `${path}: ${issue.message ?? 'invalid'}`;
+}
+function formatZodError(error) {
+    return error.issues
+        .slice(0, 8)
+        .map((issue) => formatZodIssue(issue))
+        .join('; ');
+}
+// 与 formatZodError 同源的结构化 hints：union 失败时也展开为可读描述，
+// 避免 hints 里仍是塌缩的 "Invalid input"。
+function zodErrorHints(error) {
+    return error.issues
+        .slice(0, 8)
+        .map((issue) => {
+        const path = issue.path && issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        const formatted = formatZodIssue(issue);
+        // formatZodIssue 返回 "path: detail"，hints 只取 detail 部分
+        const sep = formatted.indexOf(': ');
+        return { path, message: sep >= 0 ? formatted.slice(sep + 2) : formatted };
+    });
+}
+function levenshtein(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i]);
+    for (let j = 1; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return dp[a.length][b.length];
+}
+function parseArgsText(args) {
+    if (typeof args !== 'string')
+        return { ok: true, value: args };
+    return {
+        ok: false,
+        message: '工具参数必须直接传结构化 JSON 值，不接受 JSON 字符串容器。',
+        cause: 'top-level string tool arguments are not accepted',
+        rawPreview: `${args.slice(0, 200)}${args.length > 200 ? '...' : ''}`,
+    };
+}
+function exampleValueForSchema(schema, key) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema))
+        return 'value';
+    const s = schema;
+    if ('default' in s)
+        return s.default;
+    if (Array.isArray(s.examples) && s.examples.length > 0)
+        return s.examples[0];
+    if (Array.isArray(s.enum) && s.enum.length > 0)
+        return s.enum[0];
+    if ('const' in s)
+        return s.const;
+    const lowerKey = (key || '').toLowerCase();
+    const type = Array.isArray(s.type) ? s.type[0] : s.type;
+    if (type === 'boolean')
+        return false;
+    if (type === 'number' || type === 'integer')
+        return 1;
+    if (type === 'array')
+        return [exampleValueForSchema(s.items)];
+    if (type === 'object' || Array.isArray(s.oneOf) || Array.isArray(s.anyOf) || Array.isArray(s.allOf)) {
+        return exampleArgsFromSchema(s);
+    }
+    if (lowerKey === 'request_id' || lowerKey.endsWith('_request_id'))
+        return '<request-id>';
+    if (lowerKey === 'worker_name')
+        return '<worker-name>';
+    if (lowerKey === 'agent_name' || lowerKey.endsWith('_agent_name'))
+        return 'Sam';
+    if (lowerKey === 'task_id' || lowerKey.endsWith('_task_id'))
+        return 'T-1';
+    if (lowerKey === 'team_name')
+        return '<team-name>';
+    if (lowerKey === 'tool_name')
+        return 'shell';
+    if (lowerKey === 'reason')
+        return '需要完成当前任务的必要操作';
+    if (lowerKey === 'summary')
+        return '已完成本轮目标';
+    if (lowerKey.includes('path'))
+        return 'src/index.ts';
+    if (lowerKey.includes('url'))
+        return 'https://example.com';
+    if (lowerKey.includes('query'))
+        return 'search terms';
+    if (lowerKey.includes('command'))
+        return 'pwd';
+    if (lowerKey.includes('selector'))
+        return 'body';
+    if (lowerKey.includes('content') || lowerKey.includes('text') || lowerKey.includes('message'))
+        return 'text';
+    return 'value';
+}
+function schemaVariants(schema) {
+    const variants = Array.isArray(schema.oneOf)
+        ? schema.oneOf
+        : Array.isArray(schema.anyOf)
+            ? schema.anyOf
+            : undefined;
+    return variants?.filter(isRecord) ?? [];
+}
+function selectSchemaForArgs(schema, args) {
+    const variants = schemaVariants(schema);
+    if (variants.length === 0)
+        return schema;
+    const objectVariants = variants.filter((variant) => isRecord(variant.properties));
+    if (objectVariants.length === 0)
+        return schema;
+    if (isRecord(args)) {
+        for (const variant of objectVariants) {
+            const properties = isRecord(variant.properties) ? variant.properties : {};
+            const matches = Object.entries(properties).some(([key, prop]) => isRecord(prop) &&
+                'const' in prop &&
+                args[key] === prop.const);
+            if (matches)
+                return variant;
+        }
+    }
+    return objectVariants[0];
+}
+function schemaProperties(schema) {
+    return schema.properties && typeof schema.properties === 'object' && !Array.isArray(schema.properties)
+        ? schema.properties
+        : {};
+}
+function requiredKeysForSchema(schema) {
+    return Array.isArray(schema.required)
+        ? schema.required.filter((item) => typeof item === 'string')
+        : [];
+}
+function exampleArgsFromSchema(schema, args) {
+    const selected = selectSchemaForArgs(schema, args);
+    const properties = schemaProperties(selected);
+    const required = requiredKeysForSchema(selected);
+    const keys = required.length > 0 ? required : Object.keys(properties).slice(0, 3);
+    const out = {};
+    for (const key of keys) {
+        out[key] = exampleValueForSchema(properties[key], key);
+    }
+    return out;
+}
+function retryArgsFromSchema(schema, args) {
+    const selected = selectSchemaForArgs(schema, args);
+    const properties = schemaProperties(selected);
+    const out = exampleArgsFromSchema(selected, args);
+    if (!isRecord(args))
+        return out;
+    for (const key of Object.keys(properties)) {
+        const value = args[key];
+        const propSchema = properties[key];
+        if (value !== undefined && value !== '' && valueMatchesSchema(value, propSchema))
+            out[key] = value;
+    }
+    return out;
+}
+function valueMatchesSchema(value, schema) {
+    if (!isRecord(schema))
+        return true;
+    try {
+        const validate = jsonSchemaValidator.compile(schema);
+        return validate(value) === true;
+    }
+    catch {
+        return true;
+    }
+}
+function findSiblingObjectPropertyForKey(properties, key) {
+    let match = null;
+    for (const [propName, propSchema] of Object.entries(properties)) {
+        if (!isRecord(propSchema))
+            continue;
+        const childProps = schemaProperties(propSchema);
+        if (Object.prototype.hasOwnProperty.call(childProps, key)) {
+            if (match)
+                return null; // ambiguous: multiple siblings declare this key
+            match = propName;
+        }
+    }
+    return match;
+}
+function isStringLikeSchema(schema) {
+    if (!isRecord(schema))
+        return false;
+    const type = new Set(Array.isArray(schema.type) ? schema.type : [schema.type]);
+    if (type.has('string'))
+        return true;
+    if ('minLength' in schema || 'maxLength' in schema || 'pattern' in schema || 'format' in schema)
+        return true;
+    if (Array.isArray(schema.enum) && schema.enum.every((item) => typeof item === 'string'))
+        return true;
+    return typeof schema.const === 'string';
+}
+function coerceStringBoolean(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    if (['true', 'yes', 'y', '1', 'on', 'enabled', 'enable', 'pass', 'passed', 'success', 'succeeded', 'ok', '✅', '✓'].includes(normalized)) {
+        return true;
+    }
+    if (['false', 'no', 'n', '0', 'off', 'disabled', 'disable', 'fail', 'failed', 'failure', 'error', 'blocked', 'skipped', '❌', '✗'].includes(normalized)) {
+        return false;
+    }
+    return undefined;
+}
+function coerceBooleanForSchema(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (value === 1)
+            return true;
+        if (value === 0)
+            return false;
+    }
+    if (typeof value === 'string') {
+        return coerceStringBoolean(value) ?? value;
+    }
+    return value;
+}
+function coerceNumberForSchema(value, integer) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return value;
+    if (integer && !/^[+-]?\d+$/.test(trimmed))
+        return value;
+    if (!integer && !/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(trimmed))
+        return value;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : value;
+}
+function normalizedEnumKey(value) {
+    return value.trim().toLowerCase().replace(/[\s-]+/g, '_');
+}
+function coerceEnumForSchema(value, schema) {
+    if (!Array.isArray(schema.enum))
+        return value;
+    if (schema.enum.some((item) => Object.is(item, value)))
+        return value;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        const boolValue = coerceStringBoolean(trimmed);
+        for (const item of schema.enum) {
+            if (typeof item === 'string' && normalizedEnumKey(item) === normalizedEnumKey(trimmed))
+                return item;
+            if (typeof item === 'boolean' && boolValue !== undefined && item === boolValue)
+                return item;
+            if (typeof item === 'number') {
+                const parsed = coerceNumberForSchema(trimmed, Number.isInteger(item));
+                if (typeof parsed === 'number' && Object.is(parsed, item))
+                    return item;
+            }
+        }
+    }
+    return value;
+}
+/**
+ * items schema 是否为 primitive（string/number/integer/boolean 或 primitive enum）。
+ * 仅对 primitive-items 数组做「对象/嵌套 → 叶子拍平」，避免对 object[] 做歧义猜测。
+ */
+function isPrimitiveItemsSchema(items) {
+    if (!isRecord(items))
+        return false;
+    const typeField = Array.isArray(items.type) ? items.type[0] : items.type;
+    if (typeField === 'string' || typeField === 'number' || typeField === 'integer' || typeField === 'boolean') {
+        return true;
+    }
+    if (Array.isArray(items.enum) && items.enum.every((v) => v === null || typeof v !== 'object')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * 深度收集所有 primitive 叶子值（string/number/boolean），跳过对象 key 与 null。
+ * 用于把模型误写成嵌套对象（如 {"item":{...,"$text":"path"}} —— XML 语义泄进 JSON）
+ * 的 primitive 列表拍平回扁平数组。顺序 = 结构内文档序（深度优先）。
+ */
+export function collectPrimitiveLeaves(value, out) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === 'object') {
+        const iterable = Array.isArray(value) ? value : Object.values(value);
+        for (const v of iterable)
+            collectPrimitiveLeaves(v, out);
+        return;
+    }
+    out.push(value);
+}
+/**
+ * 把单个「应进入数组的元素」按 items schema 规整为元素列表。
+ *
+ * - primitive 叶子 → `[item]`；
+ * - null/undefined → `[]`（丢弃，避免空槽）；
+ * - object/嵌套 + primitive-items schema → 拍平成 primitive 叶子列表；
+ * - object/嵌套 + object-items schema → `[item]`（不拍平，交回递归规整/校验）。
+ *
+ * 判据全部来自声明的 schema，非启发式（不靠关键词/阈值/置信度）。
+ */
+function coerceToArrayElement(item, itemsSchema) {
+    if (item === null || item === undefined)
+        return [];
+    if (typeof item !== 'object')
+        return [item];
+    if (!isPrimitiveItemsSchema(itemsSchema))
+        return [item];
+    const leaves = [];
+    collectPrimitiveLeaves(item, leaves);
+    return leaves;
+}
+function normalizeArgsForSchema(args, schema) {
+    const normalized = normalizeToolArgs(args);
+    return normalizeValueForSchema(normalized, schema);
+}
+function normalizeValueForSchema(value, schema) {
+    if (!isRecord(schema))
+        return value;
+    const selected = selectSchemaForArgs(schema, value);
+    const variants = schemaVariants(selected);
+    if (variants.length > 0 && selected !== schema)
+        return normalizeValueForSchema(value, selected);
+    const type = Array.isArray(selected.type) ? selected.type[0] : selected.type;
+    const enumCoerced = coerceEnumForSchema(value, selected);
+    if (enumCoerced !== value)
+        return enumCoerced;
+    if (type === 'boolean')
+        return coerceBooleanForSchema(value);
+    if (type === 'integer')
+        return coerceNumberForSchema(value, true);
+    if (type === 'number')
+        return coerceNumberForSchema(value, false);
+    if (type === 'array') {
+        const itemsSchema = selected.items;
+        // value 已是数组：逐元素规整。对 primitive-items 数组，把「对象/嵌套」元素
+        // 确定性拍平为 primitive 叶子（模型常把 string[] 误写成嵌套对象，如
+        // {"item":{...,"$text":"path"}} —— XML 语义泄进 JSON）。
+        if (Array.isArray(value)) {
+            const out = [];
+            for (const item of value) {
+                for (const leaf of coerceToArrayElement(item, itemsSchema)) {
+                    out.push(normalizeValueForSchema(leaf, itemsSchema));
+                }
+            }
+            return out;
+        }
+        // value 非数组但 schema 要数组：单 primitive 包成 [value]；对象/嵌套拍平。
+        if (value !== null && value !== undefined) {
+            const leaves = coerceToArrayElement(value, itemsSchema);
+            if (leaves.length > 0) {
+                return leaves.map((leaf) => normalizeValueForSchema(leaf, itemsSchema));
+            }
+        }
+        return value;
+    }
+    if ((type === 'object' || selected.properties) && isRecord(value)) {
+        const properties = schemaProperties(selected);
+        const required = new Set(requiredKeysForSchema(selected));
+        const out = {};
+        const orphanKeys = [];
+        for (const [key, nestedValue] of Object.entries(value)) {
+            const propSchema = properties[key];
+            if (nestedValue === '' && propSchema && isStringLikeSchema(propSchema) && !required.has(key)) {
+                continue;
+            }
+            if (propSchema) {
+                out[key] = normalizeValueForSchema(nestedValue, propSchema);
+            }
+            else if (selected.additionalProperties === false) {
+                // Schema explicitly forbids extra props; ajv would hard-reject the whole
+                // call for one misplaced/extra key. Defer these orphan keys to a second
+                // pass so we can relocate them into a sibling object (already fully
+                // normalized by then) or drop them, instead of failing the whole call.
+                orphanKeys.push(key);
+            }
+            else {
+                out[key] = nestedValue;
+            }
+        }
+        // Second pass: relocate orphan keys into the sibling object property that
+        // declares them (e.g. a field mistakenly nested under the wrong object).
+        // Unrelocatable orphans are dropped, keeping required/type checks intact.
+        for (const key of orphanKeys) {
+            const target = findSiblingObjectPropertyForKey(properties, key);
+            if (!target)
+                continue;
+            const existing = isRecord(out[target]) ? out[target] : {};
+            if (existing[key] === undefined) {
+                const targetProps = schemaProperties(properties[target]);
+                existing[key] = normalizeValueForSchema(value[key], targetProps[key]);
+            }
+            out[target] = existing;
+        }
+        return out;
+    }
+    return value;
+}
+function ajvPath(error) {
+    const path = error.instancePath
+        ? error.instancePath.replace(/^\//, '').replace(/\//g, '.')
+        : '';
+    if (error.keyword === 'required' && isRecord(error.params) && typeof error.params.missingProperty === 'string') {
+        return path ? `${path}.${error.params.missingProperty}` : error.params.missingProperty;
+    }
+    if (error.keyword === 'additionalProperties' && isRecord(error.params) && typeof error.params.additionalProperty === 'string') {
+        return path ? `${path}.${error.params.additionalProperty}` : error.params.additionalProperty;
+    }
+    return path || '(root)';
+}
+function toolCatalog() {
+    return getPromptCatalog().tools;
+}
+function formatJsonSchemaErrors(errors) {
+    const fallback = toolCatalog().registry.schemaValidationFailed;
+    return (errors ?? [])
+        .slice(0, 8)
+        .map((error) => `${ajvPath(error)}: ${error.message || fallback}`)
+        .join('; ');
+}
+function jsonSchemaHints(errors) {
+    const fallback = toolCatalog().registry.schemaValidationFailed;
+    return (errors ?? [])
+        .slice(0, 8)
+        .map((error) => ({ path: ajvPath(error), message: error.message || fallback }));
+}
+function validateJsonSchemaArgs(schema, args) {
+    try {
+        const validate = jsonSchemaValidator.compile(schema);
+        if (validate(args))
+            return { ok: true, value: args };
+        const formatted = formatJsonSchemaErrors(validate.errors);
+        return {
+            ok: false,
+            formatted: formatted || toolCatalog().registry.schemaValidationFailed,
+            hints: jsonSchemaHints(validate.errors),
+        };
+    }
+    catch {
+        return { ok: true, value: args };
+    }
+}
+function validateToolProtocolArgs(toolName, args) {
+    if (toolName !== 'request_permission_update' || !isRecord(args) || args.source !== 'worker') {
+        return { ok: true };
+    }
+    const missing = ['request_id', 'worker_name'].filter((key) => {
+        const value = args[key];
+        return typeof value !== 'string' || value.trim().length === 0;
+    });
+    if (missing.length === 0)
+        return { ok: true };
+    return {
+        ok: false,
+        formatted: missing.map((key) => `${key}: must be a non-empty string when source is "worker"`).join('; '),
+        hints: missing.map((key) => ({ path: key, message: 'must be a non-empty string when source is "worker"' })),
+    };
+}
+function truncateActivityText(value, max = 220) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
+}
+function firstStringField(args, fields) {
+    for (const field of fields) {
+        const value = args[field];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function uniqueStrings(values, limit = 12) {
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (!value)
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+function extractActivityFiles(args) {
+    if (!isRecord(args))
+        return undefined;
+    const direct = uniqueStrings([
+        firstStringField(args, ['path', 'output_path', 'file', 'screenshot_path', 'cwd', 'directory']),
+        ...((stringArray(args.files) ?? [])),
+    ]);
+    return direct.length > 0 ? direct : undefined;
+}
+function extractActivityAction(toolName, args) {
+    if (!isRecord(args))
+        return toolName;
+    const action = args.action;
+    return typeof action === 'string' && action.trim() ? action.trim() : toolName;
+}
+function summarizeAgentActivity(toolName, args) {
+    const record = isRecord(args) ? args : {};
+    const action = extractActivityAction(toolName, args);
+    const files = extractActivityFiles(args);
+    const target = files?.[0]
+        ?? firstStringField(record, ['url', 'branch', 'remote', 'tool', 'name', 'terminal_id', 'uri']);
+    if (toolName === 'shell') {
+        const command = firstStringField(record, ['command']);
+        return { summary: truncateActivityText(`shell: ${command ?? '(command)'}`), target, command, files };
+    }
+    if (toolName === 'python_exec') {
+        const command = firstStringField(record, ['code']);
+        return { summary: truncateActivityText('python_exec: code snippet'), target, command: command ? truncateActivityText(command, 160) : undefined, files };
+    }
+    if (toolName === 'file_create') {
+        return { summary: `file_create: ${target ?? '(path)'}`, target, files };
+    }
+    if (toolName === 'structured_patch') {
+        const hunkCount = Array.isArray(record.hunks) ? record.hunks.length : undefined;
+        return { summary: `structured_patch: ${target ?? '(path)'}${hunkCount ? ` (${hunkCount} hunks)` : ''}`, target, files };
+    }
+    if (toolName === 'git') {
+        const message = firstStringField(record, ['message', 'branch', 'remote', 'mr_title']);
+        return { summary: truncateActivityText(`git ${action ?? ''}${message ? `: ${message}` : ''}`), target, files };
+    }
+    if (toolName === 'mcp') {
+        const server = firstStringField(record, ['server']);
+        const mcpTool = firstStringField(record, ['tool']);
+        return { summary: truncateActivityText(`mcp ${action ?? ''}${server ? ` ${server}` : ''}${mcpTool ? `/${mcpTool}` : ''}`), target, files };
+    }
+    return { summary: truncateActivityText(`${toolName}${action && action !== toolName ? `: ${action}` : ''}${target ? ` → ${target}` : ''}`), target, files };
+}
+function shouldEmitAgentActivity(toolName, metadata) {
+    if (metadata.readOnly)
+        return false;
+    if (metadata.hidden)
+        return false;
+    return metadata.tier === 'write' || metadata.tier === 'execute' || metadata.modifiesWorkspace === true;
+}
+function emitAgentActivityEvent(toolName, args, result, context, metadata, fallbackSessionId) {
+    if (!shouldEmitAgentActivity(toolName, metadata))
+        return;
+    if (!context?.emitter)
+        return;
+    const sessionId = typeof context.sessionId === 'string' && context.sessionId.trim()
+        ? context.sessionId.trim()
+        : fallbackSessionId ?? '';
+    if (!sessionId)
+        return;
+    const agentId = typeof context.agentId === 'string' && context.agentId.trim() ? context.agentId.trim() : 'leader';
+    const agentName = typeof context.agentName === 'string' && context.agentName.trim()
+        ? context.agentName.trim()
+        : agentId;
+    const activity = summarizeAgentActivity(toolName, args);
+    context.emitter.emit('agent:activity', {
+        sessionId,
+        agentId,
+        agentName,
+        taskId: typeof context.taskId === 'string' ? context.taskId : undefined,
+        toolName,
+        toolCategory: typeof metadata.category === 'string' ? metadata.category : undefined,
+        toolTier: metadata.tier,
+        action: extractActivityAction(toolName, args),
+        success: result.success,
+        timestamp: Date.now(),
+        summary: activity.summary,
+        target: activity.target,
+        files: activity.files,
+        command: activity.command,
+        error: result.success ? undefined : truncateActivityText(result.error ?? 'tool failed', 300),
+    });
+}
+export function normalizeToolArgs(args) {
+    return args;
+}
+export class ToolRegistry {
+    tools = new Map();
+    deferredTools = new Map();
+    db = null;
+    sessionId = null;
+    /** Session 级已读文件集合（绝对路径） */
+    readFiles = new Set();
+    /** Tool 变更监听器 — register/unregister 时回调，便于上层广播事件或失效缓存 */
+    changeListener = null;
+    /** Attach a DatabaseManager for persistence support */
+    setDatabase(db, sessionId) {
+        this.db = db;
+        this.sessionId = sessionId;
+    }
+    /** 注册 tool 变更监听器；同一个 listener 实例覆盖之前的 */
+    setChangeListener(fn) {
+        this.changeListener = fn;
+    }
+    /** 工具是否已注册（含 deferred） */
+    has(name) {
+        return this.tools.has(name) || this.deferredTools.has(name);
+    }
+    /** 记录文件已被读取 */
+    recordFileRead(filePath, workspace) {
+        this.readFiles.add(this.resolveAbsPath(filePath, workspace));
+    }
+    /** 检查文件是否已被读取过 */
+    hasFileBeenRead(filePath, workspace) {
+        return this.readFiles.has(this.resolveAbsPath(filePath, workspace));
+    }
+    resolveAbsPath(filePath, workspace) {
+        if (isAbsolute(filePath))
+            return filePath;
+        return resolve(workspace || process.cwd(), filePath);
+    }
+    register(tool) {
+        const existed = this.tools.has(tool.name) || this.deferredTools.has(tool.name);
+        this.tools.set(tool.name, tool);
+        this.deferredTools.delete(tool.name);
+        this.saveTool(tool);
+        try {
+            this.changeListener?.({ action: existed ? 'replace' : 'register', name: tool.name });
+        }
+        catch {
+            // listener 异常独立于注册结果
+        }
+    }
+    /** Register a tool lazily — instantiated only on first access */
+    registerDeferred(name, factory) {
+        const existed = this.tools.has(name) || this.deferredTools.has(name);
+        this.deferredTools.set(name, factory);
+        try {
+            this.changeListener?.({ action: existed ? 'replace' : 'register', name });
+        }
+        catch {
+            // ignore
+        }
+    }
+    /** 注销工具（含 deferred）。返回是否实际移除 */
+    unregister(name) {
+        const had = this.tools.delete(name);
+        const hadDeferred = this.deferredTools.delete(name);
+        const removed = had || hadDeferred;
+        if (removed) {
+            try {
+                this.changeListener?.({ action: 'unregister', name });
+            }
+            catch {
+                // ignore
+            }
+        }
+        return removed;
+    }
+    get(name) {
+        let tool = this.tools.get(name);
+        if (!tool && this.deferredTools.has(name)) {
+            const factory = this.deferredTools.get(name);
+            tool = factory();
+            this.tools.set(name, tool);
+            this.deferredTools.delete(name);
+            this.saveTool(tool);
+        }
+        return tool;
+    }
+    getLoaded() {
+        return Array.from(this.tools.values());
+    }
+    getDeferredNames() {
+        return Array.from(this.deferredTools.keys());
+    }
+    getAll() {
+        // Materialize all deferred tools
+        for (const [name, factory] of this.deferredTools) {
+            if (!this.tools.has(name)) {
+                const tool = factory();
+                this.tools.set(name, tool);
+                this.saveTool(tool);
+            }
+        }
+        this.deferredTools.clear();
+        return Array.from(this.tools.values());
+    }
+    /**
+     * 收集用于生成 provider 定义所需的最小工具集。
+     *
+     * 关键：defer 真正按需加载 —— 不再无条件调用 getAll() 全量物化。
+     *   - 指定 toolNames 时：只物化被显式请求的工具（按名 get，触发 lazy 实例化），
+     *     其余 deferred 工具保持惰性。
+     *   - 未指定 toolNames（"all" 语义）时：已加载工具全收；deferred 工具按 metadata
+     *     过滤，跳过 hidden（hidden 工具永不出现在 LLM 定义里，无需物化）。其余
+     *     deferred 工具因 schema 仅存在于实例上，仍需物化，但仅限非 hidden 子集。
+     */
+    resolveDefinitionsSource(toolNames) {
+        const requestedToolNames = toolNames ? new Set(toolNames) : null;
+        if (requestedToolNames) {
+            const resolved = [];
+            for (const name of requestedToolNames) {
+                const tool = this.get(name);
+                if (tool)
+                    resolved.push(tool);
+            }
+            return resolved;
+        }
+        const collected = new Map();
+        for (const [name, tool] of this.tools) {
+            collected.set(name, tool);
+        }
+        for (const name of this.deferredTools.keys()) {
+            if (collected.has(name))
+                continue;
+            // 隐藏工具永不会出现在 LLM 定义里 —— 保持 deferred，不物化。
+            if (getToolMetadata(name).hidden)
+                continue;
+            const tool = this.get(name);
+            if (tool)
+                collected.set(name, tool);
+        }
+        return Array.from(collected.values());
+    }
+    getDefinitions(toolNames, options = {}) {
+        const requestedToolNames = toolNames ? new Set(toolNames) : null;
+        const sourceTools = this.resolveDefinitionsSource(toolNames);
+        const filtered = requestedToolNames
+            ? sourceTools.filter(t => requestedToolNames.has(t.name))
+            : sourceTools.filter(t => !getToolMetadata(t.name).hidden);
+        return filtered
+            .filter((tool) => this.isVisibleForDefinitionScope(tool, options.scope))
+            .filter((tool) => this.isVisibleForModePolicy(tool.name, getToolMetadata(tool.name), options.modePolicy))
+            .map(tool => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: this.getSchema(tool)
+            }
+        }));
+    }
+    isVisibleForDefinitionScope(tool, scope) {
+        if (!scope || scope === 'all')
+            return true;
+        const toolScope = tool.scope ?? 'worker';
+        if (scope === 'both')
+            return toolScope === 'both';
+        return toolScope === scope || toolScope === 'both';
+    }
+    isLeaderToolContext(context) {
+        return context?.agentId === 'leader' || context?.agentName === 'leader' || Boolean(context?.leaderToolsExecutor);
+    }
+    isExecutableInContext(tool, context) {
+        return tool.scope !== 'leader' || this.isLeaderToolContext(context);
+    }
+    modeDecisionForOptions(name, metadata, options) {
+        if (!options)
+            return null;
+        const modes = options.modes;
+        return resolveModeToolDecision({
+            actor: options.actor ?? 'worker',
+            controlMode: modes.controlMode,
+            routeMode: modes.route.mode,
+            collaborationMode: modes.collaboration.mode,
+            activeModes: modes.modePlugins,
+            blackboardMode: modes.blackboard.mode,
+            permissionMode: modes.permission.mode,
+            activeTeamName: modes.collaboration.activeTeamName ?? null,
+            callerInTeamRoster: options.callerInTeamRoster,
+            callerIsTeamLeader: options.callerIsTeamLeader,
+            allowSoloEphemeralDispatch: options.allowSoloEphemeralDispatch,
+            toolName: name,
+            toolMetadata: metadata,
+        });
+    }
+    isVisibleForModePolicy(name, metadata, options) {
+        const decision = this.modeDecisionForOptions(name, metadata, options);
+        return !decision || decision.visibility === 'visible';
+    }
+    getModeRuntimeProjectionFromContext(context) {
+        const explicit = context?.modes ?? context?.modeRuntimeProjection;
+        if (explicit && typeof explicit === 'object' && !Array.isArray(explicit)) {
+            return explicit;
+        }
+        if (!context?.db || !context.sessionId)
+            return null;
+        try {
+            return resolveModeRuntimeProjection({
+                sessionId: context.sessionId,
+                db: context.db,
+                permissionContext: getToolPermissionContextFromToolContext(context),
+                blackboardAvailable: Boolean(context.blackboardGraph),
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    modeDecisionForExecution(name, metadata, context) {
+        const modes = this.getModeRuntimeProjectionFromContext(context);
+        if (!modes)
+            return null;
+        const isLeader = this.isLeaderToolContext(context);
+        const agentName = typeof context?.agentName === 'string' ? context.agentName : undefined;
+        let callerInTeamRoster = isLeader;
+        let callerIsTeamLeader = isLeader;
+        if (!isLeader && agentName && context?.sessionId && modes.collaboration.teamEnabled) {
+            try {
+                const member = getTeamMemberRegistry().getByName(agentName, context.sessionId);
+                callerInTeamRoster = Boolean(member);
+                callerIsTeamLeader = member?.role === 'leader';
+            }
+            catch {
+                callerInTeamRoster = false;
+                callerIsTeamLeader = false;
+            }
+        }
+        return resolveModeToolDecision({
+            actor: isLeader ? 'leader' : callerInTeamRoster ? 'team_member' : 'worker',
+            controlMode: modes.controlMode,
+            routeMode: modes.route.mode,
+            collaborationMode: modes.collaboration.mode,
+            activeModes: modes.modePlugins,
+            blackboardMode: modes.blackboard.mode,
+            permissionMode: modes.permission.mode,
+            activeTeamName: modes.collaboration.activeTeamName ?? null,
+            callerInTeamRoster,
+            callerIsTeamLeader,
+            toolName: name,
+            toolMetadata: metadata,
+        });
+    }
+    getSchema(tool) {
+        const schema = (() => {
+            if (typeof tool.getSchema === 'function') {
+                return tool.getSchema();
+            }
+            if (tool.schema) {
+                return tool.schema;
+            }
+            if (tool.input_schema) {
+                return tool.input_schema;
+            }
+            return { type: 'object', properties: {} };
+        })();
+        return normalizeJsonSchemaForOpenAI(schema);
+    }
+    getToolSchema(name) {
+        const tool = this.get(name);
+        return tool ? this.getSchema(tool) : null;
+    }
+    getToolInspection(name, options) {
+        const loadedTool = this.tools.get(name);
+        const deferred = this.deferredTools.has(name);
+        const tool = loadedTool ?? (options?.includeSchema || !deferred ? this.get(name) : undefined);
+        if (!tool && !deferred)
+            return null;
+        if (tool && !this.isVisibleForDefinitionScope(tool, options?.scope))
+            return null;
+        if (!this.isVisibleForModePolicy(name, getToolMetadata(name), options?.modePolicy))
+            return null;
+        const schema = tool ? this.getSchema(tool) : undefined;
+        return {
+            name,
+            description: tool?.description ?? toolCatalog().registry.deferredToolDescription(name),
+            loaded: Boolean(loadedTool || tool),
+            deferred,
+            metadata: getToolMetadata(name),
+            ...(options?.includeSchema && schema ? { schema, example_args: exampleArgsFromSchema(schema) } : {}),
+        };
+    }
+    listToolInspections(options) {
+        const names = Array.from(new Set([...this.tools.keys(), ...this.deferredTools.keys()])).sort((a, b) => a.localeCompare(b));
+        return names
+            .map((name) => this.getToolInspection(name, options))
+            .filter((item) => Boolean(item))
+            .filter((item) => options?.includeHidden || !item.metadata.hidden);
+    }
+    validateArgs(tool, args, schema) {
+        const normalizedArgs = normalizeArgsForSchema(args, schema);
+        const registryText = toolCatalog().registry;
+        if (tool instanceof Tool) {
+            const parsed = tool.parameters.safeParse(normalizedArgs);
+            if (!parsed.success) {
+                const formatted = formatZodError(parsed.error);
+                return {
+                    ok: false,
+                    result: createToolError({
+                        code: 'TOOL_ARGUMENT_VALIDATION_FAILED',
+                        message: registryText.argumentValidationMessage(formatted),
+                        retryable: true,
+                        cause: formatted,
+                        fix: registryText.argumentValidationFix,
+                        hints: zodErrorHints(parsed.error),
+                        example_args: exampleArgsFromSchema(schema, normalizedArgs),
+                        retry_args: retryArgsFromSchema(schema, normalizedArgs),
+                    }),
+                };
+            }
+            const protocolValidation = validateToolProtocolArgs(tool.name, parsed.data);
+            if (!protocolValidation.ok) {
+                return {
+                    ok: false,
+                    result: createToolError({
+                        code: 'TOOL_ARGUMENT_VALIDATION_FAILED',
+                        message: registryText.argumentValidationMessage(protocolValidation.formatted),
+                        retryable: true,
+                        cause: protocolValidation.formatted,
+                        fix: registryText.argumentValidationFix,
+                        hints: protocolValidation.hints,
+                        example_args: exampleArgsFromSchema(schema, normalizedArgs),
+                        retry_args: retryArgsFromSchema(schema, normalizedArgs),
+                    }),
+                };
+            }
+            return { ok: true, value: parsed.data };
+        }
+        const jsonValidation = validateJsonSchemaArgs(schema, normalizedArgs);
+        if (!jsonValidation.ok) {
+            const formatted = jsonValidation.formatted;
+            return {
+                ok: false,
+                result: createToolError({
+                    code: 'TOOL_ARGUMENT_VALIDATION_FAILED',
+                    message: registryText.argumentValidationMessage(formatted),
+                    retryable: true,
+                    cause: formatted,
+                    fix: registryText.argumentValidationFix,
+                    hints: jsonValidation.hints,
+                    example_args: exampleArgsFromSchema(schema, normalizedArgs),
+                    retry_args: retryArgsFromSchema(schema, normalizedArgs),
+                }),
+            };
+        }
+        const protocolValidation = validateToolProtocolArgs(tool.name, jsonValidation.value);
+        if (!protocolValidation.ok) {
+            return {
+                ok: false,
+                result: createToolError({
+                    code: 'TOOL_ARGUMENT_VALIDATION_FAILED',
+                    message: registryText.argumentValidationMessage(protocolValidation.formatted),
+                    retryable: true,
+                    cause: protocolValidation.formatted,
+                    fix: registryText.argumentValidationFix,
+                    hints: protocolValidation.hints,
+                    example_args: exampleArgsFromSchema(schema, normalizedArgs),
+                    retry_args: retryArgsFromSchema(schema, normalizedArgs),
+                }),
+            };
+        }
+        return { ok: true, value: jsonValidation.value };
+    }
+    suggestToolNames(name) {
+        const names = Array.from(new Set([...this.tools.keys(), ...this.deferredTools.keys()]));
+        return names
+            .map((candidate) => ({ candidate, score: candidate.includes(name) || name.includes(candidate) ? 0 : levenshtein(name, candidate) }))
+            .sort((a, b) => a.score - b.score || a.candidate.localeCompare(b.candidate))
+            .slice(0, 5)
+            .map((x) => x.candidate);
+    }
+    /**
+     * Shared resolution pipeline: lookup tool, parse args, validate, check read-first.
+     * Returns a discriminated union so callers can branch on the error stage.
+     */
+    resolveToolAndValidateArgs(name, args, context) {
+        const tool = this.get(name);
+        const metadata = getToolMetadata(name);
+        if (!tool) {
+            return { stage: 'not_found', candidates: this.suggestToolNames(name), metadata };
+        }
+        const schema = this.getSchema(tool);
+        if (!this.isExecutableInContext(tool, context)) {
+            return { stage: 'scope_forbidden', tool, schema, metadata };
+        }
+        const modeDecision = this.modeDecisionForExecution(name, metadata, context);
+        if (modeDecision?.visibility === 'hidden') {
+            return { stage: 'mode_forbidden', tool, schema, metadata, decision: modeDecision };
+        }
+        const parsed = parseArgsText(args ?? {});
+        if (!parsed.ok) {
+            return { stage: 'parse_failed', tool, schema, metadata, parseError: { message: parsed.message, cause: parsed.cause, rawPreview: parsed.rawPreview } };
+        }
+        const validation = this.validateArgs(tool, parsed.value, schema);
+        if (!validation.ok) {
+            return { stage: 'validation_failed', tool, schema, metadata, validationResult: validation.result };
+        }
+        if (requiresReadFirst(name)) {
+            const filePath = validation.value?.path;
+            if (filePath) {
+                const absPath = this.resolveAbsPath(filePath, context?.workspace);
+                const shouldCheck = name === 'file_create' ? existsSync(absPath) : true;
+                if (shouldCheck && !this.readFiles.has(absPath)) {
+                    return { stage: 'read_first', tool, schema, metadata, parsedArgs: validation.value, filePath };
+                }
+            }
+        }
+        return { stage: 'ok', tool, schema, metadata, parsedArgs: validation.value };
+    }
+    preflight(name, args, context) {
+        const resolution = this.resolveToolAndValidateArgs(name, args, context);
+        const registryText = toolCatalog().registry;
+        switch (resolution.stage) {
+            case 'not_found':
+                return {
+                    ok: false,
+                    tool: name,
+                    found: false,
+                    metadata: resolution.metadata,
+                    repair: {
+                        code: 'TOOL_NOT_FOUND',
+                        message: registryText.toolNotFoundCause(name),
+                        fix: registryText.toolNotFoundFix(resolution.candidates),
+                        candidates: resolution.candidates,
+                    },
+                };
+            case 'parse_failed':
+                return {
+                    ok: false,
+                    tool: name,
+                    found: true,
+                    schema: resolution.schema,
+                    metadata: resolution.metadata,
+                    repair: {
+                        code: 'TOOL_ARGUMENT_PARSE_FAILED',
+                        message: resolution.parseError.message,
+                        fix: registryText.argumentParseFix,
+                        hints: { raw_preview: resolution.parseError.rawPreview, cause: resolution.parseError.cause },
+                        example_args: exampleArgsFromSchema(resolution.schema),
+                    },
+                };
+            case 'scope_forbidden':
+                return {
+                    ok: false,
+                    tool: name,
+                    found: true,
+                    schema: resolution.schema,
+                    metadata: resolution.metadata,
+                    repair: {
+                        code: 'TOOL_SCOPE_FORBIDDEN',
+                        message: registryText.scopeForbiddenCause(name),
+                        fix: registryText.scopeForbiddenFix,
+                    },
+                };
+            case 'mode_forbidden':
+                return {
+                    ok: false,
+                    tool: name,
+                    found: true,
+                    schema: resolution.schema,
+                    metadata: resolution.metadata,
+                    repair: {
+                        code: resolution.decision.reason,
+                        message: `Tool "${name}" is hidden in the current session mode (${resolution.decision.reason}).`,
+                        fix: 'Use an available tool for the current mode, or explicitly switch the relevant session mode before retrying.',
+                    },
+                };
+            case 'validation_failed': {
+                const recovery = extractLlmRecovery(resolution.validationResult.data);
+                return {
+                    ok: false,
+                    tool: name,
+                    found: true,
+                    schema: resolution.schema,
+                    metadata: resolution.metadata,
+                    repair: {
+                        code: recovery?.code || 'TOOL_ARGUMENT_VALIDATION_FAILED',
+                        message: recovery?.message || registryText.validationFailedMessage,
+                        fix: recovery?.fix || registryText.validationFailedFix,
+                        hints: recovery?.hints,
+                        candidates: recovery?.candidates,
+                        next_tool: recovery?.next_tool,
+                        example_args: recovery?.example_args || exampleArgsFromSchema(resolution.schema),
+                        retry_args: recovery?.retry_args || retryArgsFromSchema(resolution.schema),
+                    },
+                };
+            }
+            case 'read_first':
+                return {
+                    ok: false,
+                    tool: name,
+                    found: true,
+                    schema: resolution.schema,
+                    metadata: resolution.metadata,
+                    normalizedArgs: resolution.parsedArgs,
+                    repair: {
+                        code: 'FILE_MUST_BE_READ_FIRST',
+                        message: registryText.fileMustReadFirstMessage(resolution.filePath),
+                        fix: registryText.fileMustReadFirstFix,
+                        next_tool: { name: 'file_read', args: { path: resolution.filePath } },
+                    },
+                };
+            case 'ok':
+                return {
+                    ok: true,
+                    tool: name,
+                    found: true,
+                    schema: resolution.schema,
+                    metadata: resolution.metadata,
+                    normalizedArgs: resolution.parsedArgs,
+                };
+        }
+    }
+    async execute(name, args, context) {
+        const resolution = this.resolveToolAndValidateArgs(name, args, context);
+        const registryText = toolCatalog().registry;
+        if (resolution.stage === 'not_found') {
+            return createToolError({
+                code: 'TOOL_NOT_FOUND',
+                message: registryText.toolNotFoundMessage(name),
+                retryable: true,
+                cause: registryText.toolNotFoundCause(name),
+                fix: registryText.toolNotFoundFix(resolution.candidates),
+                candidates: resolution.candidates,
+            });
+        }
+        if (resolution.stage === 'parse_failed') {
+            return createToolError({
+                code: 'TOOL_ARGUMENT_PARSE_FAILED',
+                message: resolution.parseError.message,
+                retryable: true,
+                cause: resolution.parseError.cause,
+                fix: registryText.argumentParseFix,
+                hints: { raw_preview: resolution.parseError.rawPreview },
+            });
+        }
+        if (resolution.stage === 'scope_forbidden') {
+            return createToolError({
+                code: 'TOOL_SCOPE_FORBIDDEN',
+                message: registryText.scopeForbiddenMessage(name),
+                retryable: false,
+                cause: registryText.scopeForbiddenCause(name),
+                fix: registryText.scopeForbiddenFix,
+            });
+        }
+        if (resolution.stage === 'mode_forbidden') {
+            return createToolError({
+                code: resolution.decision.reason,
+                message: `MODE_TOOL_FORBIDDEN: ${resolution.decision.reason}`,
+                retryable: true,
+                cause: `Tool "${name}" is hidden in the current session mode.`,
+                fix: 'Use an available tool for the current mode, or explicitly switch the relevant session mode before retrying.',
+            });
+        }
+        if (resolution.stage === 'validation_failed') {
+            return resolution.validationResult;
+        }
+        if (resolution.stage === 'read_first') {
+            return createToolError({
+                code: 'FILE_MUST_BE_READ_FIRST',
+                message: registryText.fileMustReadFirstMessage(resolution.filePath),
+                retryable: true,
+                cause: registryText.fileMustReadFirstCause,
+                fix: registryText.fileMustReadFirstFix,
+                next_tool: { name: 'file_read', args: { path: resolution.filePath } },
+            });
+        }
+        // stage === 'ok'
+        const { tool } = resolution;
+        const parsedArgs = resolution.parsedArgs;
+        // Office 模式的 fail-closed 由上方 resolveToolAndValidateArgs 的 mode_forbidden
+        // 统一挡（ModeToolPolicy → findModeOfTool），此处不再旁路复检。审计仍按工具归属执行。
+        const isOfficeTool = isOfficeToolName(name);
+        // ── Permission check ──
+        const permissionDecision = evaluateToolPermission(name, parsedArgs, getToolPermissionContextFromToolContext(context));
+        if (!permissionDecision.allowed) {
+            return createToolError({
+                code: 'PERMISSION_REQUIRED',
+                message: `PERMISSION_REQUIRED: ${permissionDecision.reason}`,
+                retryable: true,
+                cause: permissionDecision.reason,
+                fix: registryText.permissionRequiredFix,
+            });
+        }
+        // ── Execute tool ──
+        const toolResult = await executeToolWithTimeout(name, tool, parsedArgs, context);
+        emitAgentActivityEvent(name, parsedArgs, toolResult, context, resolution.metadata, this.sessionId);
+        if (isOfficeTool) {
+            await auditOfficeToolExecution({
+                tool: name,
+                args: parsedArgs,
+                result: toolResult,
+                context: {
+                    ...context,
+                    sessionId: context?.sessionId || this.sessionId || context?.sessionId,
+                    db: context?.db || this.db || context?.db,
+                },
+            });
+            // 统一 per-mode metrics 出口（jsonl 仍由上面写入，这里只补可观测计数）。
+            auditModeEvent('office', {
+                kind: 'office_tool_call',
+                tool: name,
+                success: toolResult.success,
+                argsSummary: parsedArgs,
+            });
+        }
+        // ── ToolFailureLoopGuard：失败侧集中上报 ──
+        // Registry 是失败事实的唯一权威出口（mode_forbidden / scope_forbidden / 工具执行异常
+        // 全部走这里返回），由 Registry 集中上报可保证：所有走 resolveToolAndValidateArgs
+        // 早期失败的分支也都被记入熔断器，避免 BaseAgentRuntime 入口被旁路。
+        if (!toolResult.success) {
+            const errorText = typeof toolResult.error === 'string' ? toolResult.error : '';
+            if (errorText) {
+                try {
+                    getToolFailureLoopGuard(undefined).record({
+                        sessionId: context?.sessionId || this.sessionId || '<unknown>',
+                        agentId: String(context?.agentId || ''),
+                        agentName: String(context?.agentName || ''),
+                        taskId: typeof context?.taskId === 'string' ? context.taskId : undefined,
+                        toolName: name,
+                        args: parsedArgs,
+                        errorCode: extractErrorCodeFromText(errorText),
+                        errorMessage: errorText.split('\n\nLLM_RECOVERY=')[0] || errorText,
+                    });
+                }
+                catch {
+                    // 上报失败不应影响主路径
+                }
+            }
+        }
+        // ── 记录文件内容已知的工具 ──
+        if (toolResult.success && (name === 'file_read' ||
+            name === 'file_create' ||
+            name === 'structured_patch')) {
+            const filePath = parsedArgs?.path;
+            if (filePath) {
+                this.recordFileRead(filePath, context?.workspace);
+            }
+        }
+        if (toolResult.success && (name === 'file_create' || name === 'structured_patch')) {
+            const filePath = parsedArgs?.path;
+            if (filePath && context?.assumptionTracker) {
+                try {
+                    const batch = await context.assumptionTracker.onFilesChanged([filePath]);
+                    if (batch.falsified.length > 0) {
+                        await context.assumptionFeedback?.(batch);
+                    }
+                }
+                catch (error) {
+                    coreLogger.warn(`[ToolRegistry] assumption verification skipped after ${name}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        return toolResult;
+    }
+    // === Persistence ===
+    saveTool(tool) {
+        if (!this.db || !this.sessionId)
+            return;
+        try {
+            const toolType = tool instanceof Tool ? 'class' : 'custom';
+            const schema = this.getSchema(tool);
+            this.db.saveToolRegistration(this.sessionId, tool.name, {
+                type: toolType,
+                description: tool.description,
+                schema: JSON.stringify(schema),
+            });
+        }
+        catch {
+            // Persistence failure should not break registration
+        }
+    }
+    /** Load tool registration metadata from DB. Returns metadata for caller to reconstruct tools. */
+    loadTools() {
+        if (!this.db || !this.sessionId)
+            return [];
+        const rows = this.db.loadToolRegistrations(this.sessionId);
+        return rows.map((r) => ({
+            tool_name: r.tool_name,
+            tool_type: r.tool_type,
+            tool_description: r.tool_description,
+            tool_schema: (() => {
+                try {
+                    return JSON.parse(r.tool_schema);
+                }
+                catch { /* expected: malformed schema JSON */
+                    return {};
+                }
+            })(),
+        }));
+    }
+    /** Save all currently registered tools to DB */
+    persistAll() {
+        for (const tool of this.getAll()) {
+            this.saveTool(tool);
+        }
+    }
+    /** Save already-loaded tools without instantiating deferred tools. */
+    persistLoaded() {
+        for (const tool of this.tools.values()) {
+            this.saveTool(tool);
+        }
+    }
+    /** Clear persisted tool registrations for this session */
+    clearPersistedTools() {
+        if (!this.db || !this.sessionId)
+            return;
+        try {
+            this.db.clearToolRegistrations(this.sessionId);
+        }
+        catch {
+            // Ignore
+        }
+    }
+}
+let defaultToolRegistry;
+export function getToolRegistry() {
+    defaultToolRegistry ??= new ToolRegistry();
+    return defaultToolRegistry;
+}
+//# sourceMappingURL=Registry.js.map