@lingxiao-office/sdk 1.0.0

package/dist/agents/runtime/ToolCallSafety.js

@@ -0,0 +1,319 @@
+import { writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { randomUUID } from 'crypto';
+import { registerCleanup } from '../../core/CleanupRegistry.js';
+const TRUNCATED_OUTPUT_REJECTED_TOOLS = new Set(['structured_patch', 'file_create']);
+// ─── Partial Content Rescue Config ──────────────────────────────────────────
+/** 拒绝消息中内联预览的最大字符数（避免消息本身撑爆上下文） */
+const PARTIAL_PREVIEW_CHARS = 2000;
+/** 临时文件追踪上限（FIFO 淘汰最旧） */
+const MAX_PARTIAL_TEMP_FILES = 20;
+// ─── Partial Content Temp File Tracking ──────────────────────────────────────
+// 与 Shell.ts 的 trackShellTempFile 同一模式：Map 保留插入序，头部即最旧，
+// 超上限时 FIFO 淘汰；进程退出时 registerCleanup 清理所有残留文件。
+const partialTempFiles = new Map();
+function trackPartialTempFile(filePath) {
+    partialTempFiles.set(filePath, Date.now());
+    while (partialTempFiles.size > MAX_PARTIAL_TEMP_FILES) {
+        const oldest = partialTempFiles.keys().next().value;
+        if (oldest === undefined)
+            break;
+        try {
+            rmSync(oldest, { force: true });
+        }
+        catch { /* tolerate */ }
+        partialTempFiles.delete(oldest);
+    }
+}
+registerCleanup(() => {
+    for (const p of partialTempFiles.keys()) {
+        try {
+            rmSync(p, { force: true });
+        }
+        catch { /* tolerate */ }
+    }
+    partialTempFiles.clear();
+}, 19);
+// ─── JSON Argument Parsing ───────────────────────────────────────────────────
+/**
+ * 尝试解析工具调用的 arguments JSON。
+ * 返回 null 表示解析失败（参数被截断或为空）。
+ */
+function tryParseArgs(argsStr) {
+    if (!argsStr)
+        return null;
+    try {
+        const parsed = JSON.parse(argsStr);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 检测工具调用的 arguments 是否为空对象 `{}`。
+ * 当 streaming 截断导致 arguments chunks 丢失时，parser 会返回空对象。
+ * 对文件编辑类工具，空参数永远不合法。
+ */
+function hasEmptyArgs(toolCall) {
+    const argsStr = toolCall.function.arguments;
+    if (!argsStr)
+        return true;
+    try {
+        const parsed = JSON.parse(argsStr);
+        return typeof parsed === 'object' && parsed !== null && Object.keys(parsed).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Partial Content Extraction ──────────────────────────────────────────────
+/**
+ * 反转义 JSON 字符串中的转义序列。
+ * 使用单次正则扫描避免多次 replace 的顺序依赖问题。
+ */
+function unescapeJsonString(s) {
+    return s.replace(/\\(u[\dA-Fa-f]{4}|.)/g, (_match, seq) => {
+        if (seq[0] === 'u') {
+            try {
+                return String.fromCharCode(parseInt(seq.slice(1), 16));
+            }
+            catch {
+                return seq;
+            }
+        }
+        switch (seq) {
+            case 'n': return '\n';
+            case 't': return '\t';
+            case 'r': return '\r';
+            case '"': return '"';
+            case '\\': return '\\';
+            case '/': return '/';
+            case 'b': return '\b';
+            case 'f': return '\f';
+            default: return seq; // 未知转义：保留字符
+        }
+    });
+}
+/**
+ * 从截断的 file_create arguments 中提取 partial content。
+ *
+ * 当 max_tokens 截断导致 JSON 不完整时，JSON.parse 会失败。
+ * 此函数用正则从残缺 JSON 中提取 "content" 字段的已传输部分，
+ * 即使字符串没有闭合引号也能提取。
+ *
+ * 返回 null 表示无法提取（如 content 字段尚未开始传输）。
+ */
+export function extractPartialFileContent(argsStr) {
+    if (!argsStr)
+        return null;
+    // 匹配 "content":"..." — 即使字符串被截断（无闭合引号）也能捕获已传输部分。
+    // (?:[^"\\]|\\.)* 匹配非引号非反斜杠字符或转义序列，不要求闭合引号。
+    const match = argsStr.match(/"content"\s*:\s*"((?:[^"\\]|\\.)*)/);
+    if (!match || !match[1])
+        return null;
+    return unescapeJsonString(match[1]);
+}
+/**
+ * 从截断的 arguments 中提取 path 字段。
+ * path 通常在 content 之前传输，所以即使 content 被截断，path 往往是完整的。
+ */
+export function extractPathFromArgs(argsStr) {
+    if (!argsStr)
+        return null;
+    const match = argsStr.match(/"path"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+    if (!match || !match[1])
+        return null;
+    return unescapeJsonString(match[1]);
+}
+/**
+ * 将 partial content 保存到临时文件，返回文件路径。
+ * 模型可用 file_read 读取完整部分内容，避免在上下文中重复传输。
+ */
+function savePartialContent(content) {
+    try {
+        const tmpFile = join(tmpdir(), `lingxiao_partial_${randomUUID()}.txt`);
+        writeFileSync(tmpFile, content, 'utf-8');
+        trackPartialTempFile(tmpFile);
+        return tmpFile;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Rescue Message Builders ─────────────────────────────────────────────────
+/**
+ * 为被截断的 file_create 构建结构化拒绝消息。
+ */
+function buildFileCreateRescueMessage(targetPath, partialContent, partialFilePath) {
+    const parts = [
+        `[截断保护] file_create 的 content 参数在传输中被截断，已拒绝执行以防止写入不完整文件。`,
+    ];
+    if (targetPath) {
+        parts.push(`目标文件: ${targetPath}`);
+    }
+    if (partialContent && partialContent.length > 0) {
+        parts.push(`已提取部分内容: ${partialContent.length} 字符`);
+        if (partialFilePath) {
+            parts.push(`完整部分内容已保存到: ${partialFilePath}（可用 file_read 读取）`);
+        }
+        const preview = partialContent.slice(0, PARTIAL_PREVIEW_CHARS);
+        if (partialContent.length > PARTIAL_PREVIEW_CHARS) {
+            parts.push(`部分内容预览（前 ${PARTIAL_PREVIEW_CHARS} 字符）:\n${preview}\n...（剩余 ${partialContent.length - PARTIAL_PREVIEW_CHARS} 字符已保存到临时文件）`);
+        }
+        else {
+            parts.push(`部分内容:\n${preview}`);
+        }
+    }
+    parts.push('');
+    parts.push('续接策略（选择一种，不要从头重新生成整个文件）:');
+    parts.push('1. 拆分写入: 用 file_create 写入已提取的部分内容（到截断点为止），再用 structured_patch 的 append hunk 追加剩余内容');
+    parts.push('2. 分段写入: 将完整文件按逻辑段落拆分为多次 file_create + structured_patch append，每次 content 不超过 800 行');
+    parts.push('3. 如果部分内容不可用或质量不确定，从头生成但务必控制单次写入长度在 800 行以内');
+    return parts.join('\n');
+}
+/**
+ * 为被截断的 structured_patch 构建拒绝消息。
+ */
+function buildStructuredPatchRescueMessage(targetPath) {
+    const parts = [
+        `[截断保护] structured_patch 的参数在传输中被截断，已拒绝执行以防止错误修改文件。`,
+    ];
+    if (targetPath) {
+        parts.push(`目标文件: ${targetPath}`);
+    }
+    parts.push('');
+    parts.push('续接策略:');
+    parts.push('1. 减少 hunk 数量: 每次只传 1-2 个 hunk，确保每个 hunk 的 search/replace 内容完整');
+    parts.push('2. 缩短 replace 内容: 如果单个 hunk 的 replace 内容过长，拆分为多个小 hunk 分批执行');
+    parts.push('3. 先 file_read 确认文件当前内容，再分批 patch');
+    return parts.join('\n');
+}
+/**
+ * 为空参数的文件工具构建拒绝消息（参数在流式传输中完全丢失）。
+ */
+function buildEmptyArgsMessage(toolName) {
+    return [
+        `[参数丢失] 工具 "${toolName}" 的参数在流式传输中丢失（收到空对象 {}）。这通常是因为模型输出被截断或 streaming 连接中断。`,
+        '',
+        '续接策略:',
+        '1. 重新生成完整的工具调用，确保包含所有必需参数（path、content 等）',
+        '2. 如果内容过长导致截断，将文件拆分为多次写入：先 file_create 写前半部分，再 structured_patch append 追加后半部分',
+        '3. 每次 content 控制在 800 行以内以避免再次截断',
+    ].join('\n');
+}
+// ─── Main Functions ──────────────────────────────────────────────────────────
+/**
+ * 检测 file_create 的 content 参数是否可能被截断。
+ *
+ * StreamingToolCallParser 的 safeJsonParse 会尝试闭合残缺 JSON（补引号+括号），
+ * 修复后 JSON.parse 成功但 content 值实际是被截断的。此时 arguments 是合法 JSON，
+ * 但文件内容不完整——直接执行会写入半截文件。
+ *
+ * 检测策略：如果 content 字段存在且非空，但 JSON 字符串以 content 值的闭合引号
+ * 之前结束（即原始 arguments 字符串不以 } 闭合），视为被截断。
+ */
+function isFileCreateContentTruncated(argsStr, parsed) {
+    // 原始 JSON 字符串必须以 } 闭合才算完整
+    const trimmed = argsStr.trim();
+    if (trimmed.endsWith('}'))
+        return false;
+    // 不以 } 结尾 = 原始 JSON 被截断后由 safeJsonParse 修复
+    // 如果 content 字段存在，说明 content 值可能不完整
+    return parsed.content !== undefined && parsed.content !== null;
+}
+/**
+ * 截断保护 + Partial Content Rescue。
+ *
+ * 当 wasOutputTruncated=true 时调用。改进点：
+ * 1. 先尝试 JSON.parse — 如果参数完整且未被截断（JSON 以 } 闭合），正常执行。
+ * 2. 如果 JSON.parse 成功但原始字符串不以 } 结尾（safeJsonParse 修复的截断 JSON），
+ *    仍然拦截——content 值可能被截断，直接写入会生成不完整文件。
+ * 3. 如果 JSON.parse 失败（参数严重截断），从残缺 JSON 中提取 partial content 并落盘，
+ *    返回带续接策略的结构化拒绝消息。
+ * 4. 对 file_create 提取 content 字段；对 structured_patch 不提取（hunk 结构复杂，
+ *    半截 hunk 应用会导致错误修改），只给出续接指导。
+ */
+export function executeToolCallsWithTruncationGuard(toolCalls, executeToolCallsBatch) {
+    const safeToolCalls = [];
+    const rescueResults = [];
+    for (const tc of toolCalls) {
+        if (!TRUNCATED_OUTPUT_REJECTED_TOOLS.has(tc.function.name)) {
+            // 非文件编辑工具：不受截断保护约束，正常执行
+            safeToolCalls.push(tc);
+            continue;
+        }
+        const argsStr = tc.function.arguments || '';
+        const parsed = tryParseArgs(argsStr);
+        // 路径 A：JSON.parse 成功且原始字符串以 } 闭合 = 参数真正完整
+        if (parsed !== null && !isFileCreateContentTruncated(argsStr, parsed)) {
+            safeToolCalls.push(tc);
+            continue;
+        }
+        // 路径 B：JSON.parse 失败 或 safeJsonParse 修复的截断 JSON → 拦截 + Rescue
+        const targetPath = extractPathFromArgs(argsStr);
+        if (tc.function.name === 'file_create') {
+            // 优先从原始残缺字符串提取（更完整），fallback 到 parsed 中的值
+            let partialContent = extractPartialFileContent(argsStr);
+            if (!partialContent && parsed && typeof parsed.content === 'string') {
+                // safeJsonParse 修复后的 content 值（可能被截断但仍是有效字符串）
+                partialContent = parsed.content;
+            }
+            const partialFilePath = partialContent && partialContent.length > 0
+                ? savePartialContent(partialContent)
+                : null;
+            rescueResults.push({
+                toolCall: tc,
+                result: buildFileCreateRescueMessage(targetPath, partialContent, partialFilePath),
+            });
+        }
+        else if (tc.function.name === 'structured_patch') {
+            rescueResults.push({
+                toolCall: tc,
+                result: buildStructuredPatchRescueMessage(targetPath),
+            });
+        }
+        else {
+            rescueResults.push({
+                toolCall: tc,
+                result: buildEmptyArgsMessage(tc.function.name),
+            });
+        }
+    }
+    const results = safeToolCalls.length > 0
+        ? executeToolCallsBatch(safeToolCalls)
+        : Promise.resolve([]);
+    return results.then(r => [...r, ...rescueResults]);
+}
+/**
+ * 空参数保护：拦截文件编辑类工具的空 `{}` 参数调用。
+ *
+ * 当 streaming 截断（如 max_tokens 耗尽、provider 中断）导致 tool call 的
+ * arguments chunks 丢失时，StreamingToolCallParser 会返回 args={}。
+ * 对文件编辑工具这永远不合法——阻止执行并给出明确提示，避免模型因误解错误信息而死循环重试。
+ *
+ * 此函数在 wasOutputTruncated=false 时也可独立使用。
+ * 改进：拒绝消息升级为带续接策略的结构化消息，而非简单的"请重新输出"。
+ */
+export function rejectEmptyArgsFileTools(toolCalls, executeToolCallsBatch) {
+    const emptyArgsFileTools = [];
+    const normalToolCalls = [];
+    for (const tc of toolCalls) {
+        if (TRUNCATED_OUTPUT_REJECTED_TOOLS.has(tc.function.name) && hasEmptyArgs(tc)) {
+            emptyArgsFileTools.push(tc);
+        }
+        else {
+            normalToolCalls.push(tc);
+        }
+    }
+    const results = normalToolCalls.length > 0
+        ? executeToolCallsBatch(normalToolCalls)
+        : Promise.resolve([]);
+    const rejectedResults = emptyArgsFileTools.map(tc => ({
+        toolCall: tc,
+        result: buildEmptyArgsMessage(tc.function.name),
+    }));
+    return results.then(r => [...r, ...rejectedResults]);
+}
+//# sourceMappingURL=ToolCallSafety.js.map

package/dist/agents/runtime/ToolCallSafety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolCallSafety.js","sourceRoot":"","sources":["../../../src/agents/runtime/ToolCallSafety.ts"],"names":[],"mappings":"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"}

package/dist/agents/runtime/ToolFailureLoopGuard.d.ts

@@ -0,0 +1,163 @@
+/**
+ * ToolFailureLoopGuard — 工具调用连续失败熔断器
+ *
+ * 解决问题：当前 LLM Agent 在 toolName + args 完全相同的调用上反复失败时（尤其是
+ * permission / mode / write_scope / sandbox / network / schema 这类「状态类」错误），
+ * 会陷入"工具报失败 → LLM 读到错误 → 重试同一调用 → 工具再次同样失败"的死循环，
+ * 持续消耗 token 与 round budget。旧 ToolLoopDetector 仅检测"同 toolName + 相同 arguments
+ * 的循环调用"（成功也会计入），不区分错误类型，无法识别"持续失败但 LLM 不断重试"场景。
+ *
+ * 本类定位：
+ *   - key = `${toolName}::${argsHash}::${errorSignature}` 三元组
+ *   - errorSignature = `${errorKind}:${errorCode}`，errorKind ∈ permission/mode/write_scope/
+ *     sandbox/network/schema/other，由 ToolErrorEnvelope.code 推导
+ *   - 默认 threshold=3：同一 key 累计失败 3 次时触发熔断
+ *   - 熔断动作：emit('agent:tool_failure_loop', ...) + 返回 LoopGuardDecision { tripped, ... }
+ *     调用方（BaseAgentRuntime）据此跳过 LLM 自循环：拒绝再次重试同一调用，转去 escalate_to_leader
+ *     或 requestPermissionFromLeader
+ *   - 状态类错误可枚举集合（PERMISSION/MODE/WRITE_SCOPE/SANDBOX/NETWORK/SCHEMA）即使
+ *     retryable=true 也会被计数 —— 这些错误继续重试没有意义
+ *
+ * 用法：
+ *   const guard = new ToolFailureLoopGuard({ threshold: 3, emitter });
+ *   const decision = guard.record(toolName, args, errorCode, errorMessage);
+ *   if (decision.tripped) { return escalateToLeader(decision); }
+ *
+ * 设计取舍：
+ *   - 不持久化到 db（in-memory only），agent 进程重启即清空；避免 state 漂移
+ *   - 不绑定具体 tool 实现（ToolResult 来源 Registry.execute / executeToolCall 都可）
+ *   - argsHash 用 stableJson（与 ToolLoopDetector 一致），保证 {a:1,b:2}≡{b:2,a:1}
+ *   - 触发后保留 1 分钟上下文（trippedKeys）防止同 key 快速重复熔断刷屏
+ *   - 支持 session 维度隔离：跨 session 不串数据
+ */
+import type { EventEmitter } from '../../core/EventEmitter.js';
+/** 错误大类，用于归一化 argsHash+errorSignature 的第三段。 */
+export type ToolFailureErrorKind = 'permission' | 'mode' | 'write_scope' | 'sandbox' | 'network' | 'schema' | 'precondition' | 'execution' | 'timeout' | 'aborted' | 'other';
+/**
+ * 哪些 errorKind 属于"状态类错误"（继续重试无意义，必须升级）。
+ * 状态类错误到达阈值时，强制 trip 并由 BaseAgentRuntime 走 escalate 路径。
+ * precondition/execution/timeout/aborted/other 不强制升级（可能可按工具提示修复或因临时抖动重试有效）。
+ */
+export declare const STATE_ERROR_KINDS: ReadonlySet<ToolFailureErrorKind>;
+export interface ToolFailureLoopGuardOptions {
+    /** 显式开启失败熔断；默认读取 LINGXIAO_TOOL_FAILURE_LOOP_GUARD，未设置时关闭。 */
+    enabled?: boolean;
+    /** 同一 key 连续失败次数阈值；默认 3。 */
+    threshold?: number;
+    /** trip 后保留记忆时长（ms），防止快速重试再次触发；默认 60_000。 */
+    trippedRetentionMs?: number;
+    /** 单 session 最多跟踪多少个 key；超过时淘汰最旧；默认 256。 */
+    maxKeysPerSession?: number;
+}
+export interface ToolFailureSignature {
+    toolName: string;
+    argsHash: string;
+    errorKind: ToolFailureErrorKind;
+    errorCode: string;
+}
+export interface ToolFailureRecord extends ToolFailureSignature {
+    count: number;
+    firstSeenAtMs: number;
+    lastSeenAtMs: number;
+    /** 最近一次 error 原始 message（用于上报时给 Leader / Health 看的可读摘要） */
+    lastErrorMessage: string;
+    tripped: boolean;
+    trippedAtMs: number;
+}
+export interface ToolFailureLoopEvent {
+    sessionId: string;
+    agentId: string;
+    agentName: string;
+    taskId?: string;
+    signature: ToolFailureSignature;
+    count: number;
+    threshold: number;
+    /** 是否在 STATE_ERROR_KINDS 集合内（必须升级）。 */
+    requiresEscalation: boolean;
+    lastErrorMessage: string;
+    timestamp: number;
+}
+export interface LoopGuardDecision {
+    /** 当前 key 是否达到阈值。 */
+    tripped: boolean;
+    /** 当前累计次数（tripped=true 时为 threshold 之后的下一个数）。 */
+    count: number;
+    /** 错误大类。 */
+    errorKind: ToolFailureErrorKind;
+    /** 当前 key 的归一化签名。 */
+    signature: ToolFailureSignature;
+    /** 是否在 STATE_ERROR_KINDS 集合内（true 时调用方必须走 escalate，不允许 LLM 自循环）。 */
+    requiresEscalation: boolean;
+}
+/**
+ * Disabled by default: this guard can hide the original tool error/recovery hint.
+ * Enable only for diagnostics with LINGXIAO_TOOL_FAILURE_LOOP_GUARD=1.
+ */
+export declare function isToolFailureLoopGuardEnabled(): boolean;
+/** 从 errorCode + errorMessage 推导 errorKind。 */
+export declare function classifyToolFailure(errorCode: string, errorMessage: string): ToolFailureErrorKind;
+/**
+ * ToolFailureLoopGuard — 跨 session 独立的失败熔断器。
+ *
+ * 每个 sessionId 维护独立的 Map<key, ToolFailureRecord>，避免跨 session 串数据。
+ * 触发熔断时通过 emitter 广播 `agent:tool_failure_loop` 事件，
+ * BaseAgentRuntime / AgentHealthMonitor / LeaderPermissionManager 各自订阅并按职责响应。
+ */
+export declare class ToolFailureLoopGuard {
+    private readonly options;
+    private emitter?;
+    private readonly enabled;
+    private readonly threshold;
+    private readonly trippedRetentionMs;
+    private readonly maxKeysPerSession;
+    /** sessionId → (key → record) */
+    private readonly states;
+    /** sessionId → 最近一次触发时间（仅作 debug / 测试观测用） */
+    private readonly lastTrippedAt;
+    constructor(options?: ToolFailureLoopGuardOptions, emitter?: EventEmitter | undefined);
+    /**
+     * 进程级惰性单例允许之后再注入 emitter。用 setter 不用下标访问，避开 TS 严格检查
+     * （emitter 在 constructor 是 optional，且 TS 不允许下标访问 readonly 字段）。
+     * 多次调用以最后一次为准。
+     */
+    setEmitter(emitter: EventEmitter | undefined): void;
+    /**
+     * 记录一次工具失败并返回决策。
+     *
+     * 调用方应在以下场景调用：
+     *   1. Registry.execute 返回 success=false
+     *   2. BaseAgentRuntime.executeToolCall 看到工具失败
+     *   3. 任何 LLM 自循环路径上的失败点
+     *
+     * 若 decision.tripped 为 true，调用方应停止对该 toolCall 的本地重试，
+     * 改走 escalate 路径（escalate_to_leader / requestPermissionFromLeader）。
+     */
+    record(input: {
+        sessionId: string;
+        agentId: string;
+        agentName: string;
+        taskId?: string;
+        toolName: string;
+        args: unknown;
+        errorCode: string;
+        errorMessage: string;
+    }): LoopGuardDecision;
+    /**
+     * 工具调用成功时调用，清除同 (toolName, argsHash) 下所有 errorKind 的失败记录。
+     * 防止"成功后下次又因不同 errorKind 失败"被错误归并。
+     */
+    clearOnSuccess(sessionId: string, toolName: string, args: unknown): void;
+    /** 清空某 session 的所有失败记录（agent terminated / session 结束时调用）。 */
+    resetSession(sessionId: string): void;
+    /** 测试 / 观测用：返回某 session 当前的失败记录快照。 */
+    snapshot(sessionId: string): ToolFailureRecord[];
+    /** 测试 / 观测用：返回某 session 触发的熔断 key 数量。 */
+    countTripped(sessionId: string): number;
+    private getOrCreateSessionMap;
+    private evictOldest;
+    private emitTripped;
+}
+export declare function getToolFailureLoopGuard(emitter?: EventEmitter): ToolFailureLoopGuard;
+/** 测试 / 进程退出时调用，重置全局单例。 */
+export declare function resetToolFailureLoopGuard(): void;
+//# sourceMappingURL=ToolFailureLoopGuard.d.ts.map

package/dist/agents/runtime/ToolFailureLoopGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolFailureLoopGuard.d.ts","sourceRoot":"","sources":["../../../src/agents/runtime/ToolFailureLoopGuard.ts"],"names":[],"mappings":"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"}