autosnippet 3.3.0 → 3.3.3

package/dist/lib/agent/forge/DynamicComposer.js

@@ -0,0 +1,99 @@
+/**
+ * DynamicComposer — 运行时动态工具组合
+ *
+ * 将已有的原子工具按 sequential / parallel / conditional 策略组合成复合工具。
+ * 组合结果注册为临时工具（通过 TemporaryToolRegistry）。
+ *
+ * 与 PipelineStrategy 的区别：
+ *   - PipelineStrategy 是 Agent 执行策略（Agent 层）
+ *   - DynamicComposer 是工具组合（Tool 层），产出物是单个工具
+ */
+import Logger from '#infra/logging/Logger.js';
+/* ────────────────────── Class ────────────────────── */
+export class DynamicComposer {
+    #registry;
+    #logger = Logger.getInstance();
+    constructor(registry) {
+        this.#registry = registry;
+    }
+    /**
+     * 验证组合 spec 的可行性（所有工具是否存在）
+     */
+    validate(spec) {
+        const missing = [];
+        for (const step of spec.steps) {
+            if (!this.#registry.has(step.tool)) {
+                missing.push(step.tool);
+            }
+        }
+        return { valid: missing.length === 0, missingTools: missing };
+    }
+    /**
+     * 构建组合工具
+     */
+    compose(spec) {
+        // 验证
+        const { valid, missingTools } = this.validate(spec);
+        if (!valid) {
+            return {
+                success: false,
+                error: `Missing tools: ${missingTools.join(', ')}`,
+            };
+        }
+        if (spec.steps.length === 0) {
+            return {
+                success: false,
+                error: 'Composition must have at least one step',
+            };
+        }
+        const registry = this.#registry;
+        const logger = this.#logger;
+        // 根据策略构建 handler
+        const handler = spec.mergeStrategy === 'parallel'
+            ? this.#buildParallelHandler(spec, registry, logger)
+            : this.#buildSequentialHandler(spec, registry, logger);
+        return { success: true, handler };
+    }
+    /* ── Internal ── */
+    #buildSequentialHandler(spec, registry, logger) {
+        return async (params, context) => {
+            let prevResult = params;
+            for (const step of spec.steps) {
+                const args = typeof step.args === 'function' ? step.args(prevResult) : { ...step.args, ...params };
+                logger.debug(`DynamicComposer [${spec.name}]: executing step "${step.tool}"`);
+                const result = await registry.execute(step.tool, args, context);
+                if (step.extractKey && typeof result === 'object' && result !== null) {
+                    prevResult = result[step.extractKey];
+                }
+                else {
+                    prevResult = result;
+                }
+            }
+            return prevResult;
+        };
+    }
+    #buildParallelHandler(spec, registry, logger) {
+        return async (params, context) => {
+            logger.debug(`DynamicComposer [${spec.name}]: executing ${spec.steps.length} steps in parallel`);
+            const promises = spec.steps.map(async (step) => {
+                const args = typeof step.args === 'function' ? step.args(params) : { ...step.args, ...params };
+                const result = await registry.execute(step.tool, args, context);
+                if (step.extractKey && typeof result === 'object' && result !== null) {
+                    return { tool: step.tool, result: result[step.extractKey] };
+                }
+                return { tool: step.tool, result };
+            });
+            const results = await Promise.allSettled(promises);
+            const merged = {};
+            for (const r of results) {
+                if (r.status === 'fulfilled') {
+                    merged[r.value.tool] = r.value.result;
+                }
+                else {
+                    merged[`error_${Object.keys(merged).length}`] = r.reason?.message ?? 'Unknown error';
+                }
+            }
+            return merged;
+        };
+    }
+}

package/dist/lib/agent/forge/SandboxRunner.d.ts

@@ -0,0 +1,60 @@
+/**
+ * SandboxRunner — 工具锻造沙箱验证
+ *
+ * 在受限环境中执行锻造的工具代码 + 测试用例，验证安全性和正确性。
+ * 使用 Node.js vm 模块提供隔离执行环境。
+ *
+ * 安全约束：
+ *   - 5s 执行超时
+ *   - 禁止 require/import (无文件系统 / 网络 / 子进程)
+ *   - 内存限制 via vm 上下文隔离
+ *   - 只暴露 console.log, JSON, Math, Date, Array, Object, String 等纯函数
+ */
+export interface SandboxTestCase {
+    /** 测试描述 */
+    description: string;
+    /** 调用参数 */
+    input: Record<string, unknown>;
+    /** 预期输出（用 deepEqual 比较） */
+    expectedOutput: unknown;
+}
+export interface SandboxResult {
+    /** 是否全部通过 */
+    success: boolean;
+    /** 各测试用例结果 */
+    testResults: Array<{
+        description: string;
+        passed: boolean;
+        actualOutput?: unknown;
+        error?: string;
+    }>;
+    /** 总执行时间 (ms) */
+    executionTime: number;
+    /** 安全检查结果 */
+    safetyCheck: {
+        passed: boolean;
+        violations: string[];
+    };
+}
+export declare class SandboxRunner {
+    #private;
+    /**
+     * 对工具代码进行安全检查
+     */
+    checkSafety(code: string): {
+        passed: boolean;
+        violations: string[];
+    };
+    /**
+     * 在沙箱中执行工具代码 + 测试用例
+     *
+     * @param code 工具函数代码（应 export default 或赋给 __toolHandler__）
+     * @param testCases 测试用例
+     */
+    run(code: string, testCases: SandboxTestCase[]): SandboxResult;
+    /**
+     * 从验证通过的代码创建可调用 handler
+     * 返回的 handler 每次调用都在新沙箱中执行（隔离）
+     */
+    createHandler(code: string): (params: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>;
+}

package/dist/lib/agent/forge/SandboxRunner.js

@@ -0,0 +1,251 @@
+/**
+ * SandboxRunner — 工具锻造沙箱验证
+ *
+ * 在受限环境中执行锻造的工具代码 + 测试用例，验证安全性和正确性。
+ * 使用 Node.js vm 模块提供隔离执行环境。
+ *
+ * 安全约束：
+ *   - 5s 执行超时
+ *   - 禁止 require/import (无文件系统 / 网络 / 子进程)
+ *   - 内存限制 via vm 上下文隔离
+ *   - 只暴露 console.log, JSON, Math, Date, Array, Object, String 等纯函数
+ */
+import { createContext, runInContext } from 'node:vm';
+import Logger from '#infra/logging/Logger.js';
+/* ────────────────────── Constants ────────────────────── */
+const EXECUTION_TIMEOUT_MS = 5000;
+/** 禁止使用的模式 */
+const FORBIDDEN_PATTERNS = [
+    /\brequire\s*\(/,
+    /\bimport\s*\(/,
+    /\bprocess\b/,
+    /\b__dirname\b/,
+    /\b__filename\b/,
+    /\bglobal\b/,
+    /\bglobalThis\b/,
+    /\beval\s*\(/,
+    /\bFunction\s*\(/,
+    /\bfetch\s*\(/,
+    /\bXMLHttpRequest\b/,
+    /\bWebSocket\b/,
+    /\bchild_process\b/,
+    /\bfs\b\./,
+    /\bnet\b\./,
+    /\bhttp\b\./,
+    /\bhttps\b\./,
+];
+/* ────────────────────── Class ────────────────────── */
+export class SandboxRunner {
+    #logger = Logger.getInstance();
+    /**
+     * 对工具代码进行安全检查
+     */
+    checkSafety(code) {
+        const violations = [];
+        for (const pattern of FORBIDDEN_PATTERNS) {
+            if (pattern.test(code)) {
+                violations.push(`Forbidden pattern detected: ${pattern.source}`);
+            }
+        }
+        return { passed: violations.length === 0, violations };
+    }
+    /**
+     * 在沙箱中执行工具代码 + 测试用例
+     *
+     * @param code 工具函数代码（应 export default 或赋给 __toolHandler__）
+     * @param testCases 测试用例
+     */
+    run(code, testCases) {
+        const start = Date.now();
+        // 1. 安全检查
+        const safetyCheck = this.checkSafety(code);
+        if (!safetyCheck.passed) {
+            return {
+                success: false,
+                testResults: [],
+                executionTime: Date.now() - start,
+                safetyCheck,
+            };
+        }
+        // 2. 构建沙箱上下文 — 只暴露安全的全局对象
+        const logs = [];
+        const sandbox = createContext({
+            console: {
+                log: (...args) => logs.push(args.map(String).join(' ')),
+                warn: (...args) => logs.push(`[warn] ${args.map(String).join(' ')}`),
+                error: (...args) => logs.push(`[error] ${args.map(String).join(' ')}`),
+            },
+            JSON,
+            Math,
+            Date,
+            Array,
+            Object,
+            String,
+            Number,
+            Boolean,
+            RegExp,
+            Map,
+            Set,
+            Error,
+            TypeError,
+            RangeError,
+            parseInt,
+            parseFloat,
+            isNaN,
+            isFinite,
+            encodeURIComponent,
+            decodeURIComponent,
+            // 工具函数占位，由代码赋值
+            __toolHandler__: null,
+        });
+        // 3. 加载工具代码
+        try {
+            const wrappedCode = `${code}\n;(typeof toolHandler !== 'undefined') && (__toolHandler__ = toolHandler);`;
+            runInContext(wrappedCode, sandbox, {
+                timeout: EXECUTION_TIMEOUT_MS,
+                filename: 'forged-tool.js',
+            });
+        }
+        catch (err) {
+            return {
+                success: false,
+                testResults: [
+                    {
+                        description: 'Code loading',
+                        passed: false,
+                        error: `Failed to load tool code: ${err.message}`,
+                    },
+                ],
+                executionTime: Date.now() - start,
+                safetyCheck,
+            };
+        }
+        const handler = sandbox.__toolHandler__;
+        if (typeof handler !== 'function') {
+            return {
+                success: false,
+                testResults: [
+                    {
+                        description: 'Handler check',
+                        passed: false,
+                        error: 'Tool code must define a `toolHandler` function',
+                    },
+                ],
+                executionTime: Date.now() - start,
+                safetyCheck,
+            };
+        }
+        // 4. 执行测试用例
+        const testResults = [];
+        let allPassed = true;
+        for (const tc of testCases) {
+            try {
+                const testCode = `__toolHandler__(${JSON.stringify(tc.input)})`;
+                const actual = runInContext(testCode, sandbox, {
+                    timeout: EXECUTION_TIMEOUT_MS,
+                    filename: 'forged-tool-test.js',
+                });
+                const passed = SandboxRunner.#deepEqual(actual, tc.expectedOutput);
+                if (!passed) {
+                    allPassed = false;
+                }
+                testResults.push({
+                    description: tc.description,
+                    passed,
+                    actualOutput: actual,
+                    error: passed
+                        ? undefined
+                        : `Expected ${JSON.stringify(tc.expectedOutput)}, got ${JSON.stringify(actual)}`,
+                });
+            }
+            catch (err) {
+                allPassed = false;
+                testResults.push({
+                    description: tc.description,
+                    passed: false,
+                    error: err.message,
+                });
+            }
+        }
+        this.#logger.debug(`SandboxRunner: ${testResults.filter((t) => t.passed).length}/${testResults.length} tests passed`);
+        return {
+            success: allPassed,
+            testResults,
+            executionTime: Date.now() - start,
+            safetyCheck,
+        };
+    }
+    /**
+     * 从验证通过的代码创建可调用 handler
+     * 返回的 handler 每次调用都在新沙箱中执行（隔离）
+     */
+    createHandler(code) {
+        return async (params) => {
+            const sandbox = createContext({
+                console: { log: () => { }, warn: () => { }, error: () => { } },
+                JSON,
+                Math,
+                Date,
+                Array,
+                Object,
+                String,
+                Number,
+                Boolean,
+                RegExp,
+                Map,
+                Set,
+                Error,
+                TypeError,
+                RangeError,
+                parseInt,
+                parseFloat,
+                isNaN,
+                isFinite,
+                encodeURIComponent,
+                decodeURIComponent,
+                __toolHandler__: null,
+            });
+            const wrappedCode = `${code}\n;(typeof toolHandler !== 'undefined') && (__toolHandler__ = toolHandler);`;
+            runInContext(wrappedCode, sandbox, {
+                timeout: EXECUTION_TIMEOUT_MS,
+                filename: 'forged-tool.js',
+            });
+            const handler = sandbox.__toolHandler__;
+            if (typeof handler !== 'function') {
+                throw new Error('Forged tool code does not define a toolHandler function');
+            }
+            const execCode = `__toolHandler__(${JSON.stringify(params)})`;
+            const result = runInContext(execCode, sandbox, {
+                timeout: EXECUTION_TIMEOUT_MS,
+                filename: 'forged-tool-exec.js',
+            });
+            // 如果返回 Promise-like，需特殊处理（vm 里一般不会有真正的 Promise）
+            return result;
+        };
+    }
+    /** 简单深度比较 */
+    static #deepEqual(a, b) {
+        if (a === b) {
+            return true;
+        }
+        if (a === null || b === null || typeof a !== typeof b) {
+            return false;
+        }
+        if (typeof a !== 'object') {
+            return false;
+        }
+        const aObj = a;
+        const bObj = b;
+        const keysA = Object.keys(aObj);
+        const keysB = Object.keys(bObj);
+        if (keysA.length !== keysB.length) {
+            return false;
+        }
+        for (const key of keysA) {
+            if (!SandboxRunner.#deepEqual(aObj[key], bObj[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+}

package/dist/lib/agent/forge/TemporaryToolRegistry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * TemporaryToolRegistry — TTL 临时工具注册
+ *
+ * 在 ToolRegistry 之上增加 TTL 自动回收机制。
+ * 锻造的工具默认 30 分钟有效，到期自动从 ToolRegistry 中移除。
+ *
+ * 设计：
+ *   - 装饰器模式，不修改 ToolRegistry 核心逻辑
+ *   - 定期检查（60s 间隔）清理过期工具
+ *   - 支持手动续期和提前回收
+ */
+import type { SignalBus } from '#infra/signal/SignalBus.js';
+interface ToolRegistryLike {
+    register(toolDef: {
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+        handler: Function;
+    }): void;
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+}
+export interface TemporaryTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    handler: (params: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>;
+    /** 锻造模式 */
+    forgeMode: 'reuse' | 'compose' | 'generate';
+    /** 注册时间 (ms) */
+    registeredAt: number;
+    /** 过期时间 (ms)，0 = never */
+    expiresAt: number;
+}
+export interface TemporaryToolInfo {
+    name: string;
+    forgeMode: string;
+    registeredAt: number;
+    expiresAt: number;
+    remainingMs: number;
+}
+export declare class TemporaryToolRegistry {
+    #private;
+    constructor(registry: ToolRegistryLike, options?: {
+        signalBus?: SignalBus;
+    });
+    /**
+     * 注册一个临时工具
+     */
+    registerTemporary(tool: Omit<TemporaryTool, 'registeredAt' | 'expiresAt'>, ttlMs?: number): void;
+    /**
+     * 手动回收临时工具
+     */
+    revoke(name: string): boolean;
+    /**
+     * 续期临时工具
+     */
+    renew(name: string, additionalMs?: number): boolean;
+    /**
+     * 清理过期工具
+     */
+    cleanup(): number;
+    /**
+     * 获取所有临时工具信息
+     */
+    list(): TemporaryToolInfo[];
+    /**
+     * 检查是否是临时工具
+     */
+    isTemporary(name: string): boolean;
+    /** 临时工具数量 */
+    get size(): number;
+    /** 停止定期清理（用于 shutdown） */
+    dispose(): void;
+}
+export {};

package/dist/lib/agent/forge/TemporaryToolRegistry.js

@@ -0,0 +1,154 @@
+/**
+ * TemporaryToolRegistry — TTL 临时工具注册
+ *
+ * 在 ToolRegistry 之上增加 TTL 自动回收机制。
+ * 锻造的工具默认 30 分钟有效，到期自动从 ToolRegistry 中移除。
+ *
+ * 设计：
+ *   - 装饰器模式，不修改 ToolRegistry 核心逻辑
+ *   - 定期检查（60s 间隔）清理过期工具
+ *   - 支持手动续期和提前回收
+ */
+import Logger from '#infra/logging/Logger.js';
+/* ────────────────────── Constants ────────────────────── */
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const CLEANUP_INTERVAL_MS = 60 * 1000; // 60 seconds
+/* ────────────────────── Class ────────────────────── */
+export class TemporaryToolRegistry {
+    #registry;
+    #tempTools = new Map();
+    #cleanupTimer = null;
+    #signalBus;
+    #logger = Logger.getInstance();
+    constructor(registry, options = {}) {
+        this.#registry = registry;
+        this.#signalBus = options.signalBus ?? null;
+        this.#startCleanup();
+    }
+    /**
+     * 注册一个临时工具
+     */
+    registerTemporary(tool, ttlMs = DEFAULT_TTL_MS) {
+        const now = Date.now();
+        const entry = {
+            ...tool,
+            registeredAt: now,
+            expiresAt: ttlMs > 0 ? now + ttlMs : 0,
+        };
+        // 如果已存在同名临时工具，先移除
+        if (this.#tempTools.has(tool.name)) {
+            this.revoke(tool.name);
+        }
+        // 注册到主 ToolRegistry
+        this.#registry.register({
+            name: tool.name,
+            description: `[Forged:${tool.forgeMode}] ${tool.description}`,
+            parameters: tool.parameters,
+            handler: tool.handler,
+        });
+        this.#tempTools.set(tool.name, entry);
+        if (this.#signalBus) {
+            this.#signalBus.send('forge', 'TemporaryToolRegistry', 1, {
+                target: tool.name,
+                metadata: { action: 'registered', forgeMode: tool.forgeMode, ttlMs },
+            });
+        }
+        this.#logger.debug(`TemporaryToolRegistry: registered "${tool.name}" (mode=${tool.forgeMode}, ttl=${ttlMs}ms)`);
+    }
+    /**
+     * 手动回收临时工具
+     */
+    revoke(name) {
+        const tool = this.#tempTools.get(name);
+        if (!tool) {
+            return false;
+        }
+        this.#registry.unregister(name);
+        this.#tempTools.delete(name);
+        if (this.#signalBus) {
+            this.#signalBus.send('forge', 'TemporaryToolRegistry', 0, {
+                target: name,
+                metadata: { action: 'revoked' },
+            });
+        }
+        this.#logger.debug(`TemporaryToolRegistry: revoked "${name}"`);
+        return true;
+    }
+    /**
+     * 续期临时工具
+     */
+    renew(name, additionalMs = DEFAULT_TTL_MS) {
+        const tool = this.#tempTools.get(name);
+        if (!tool) {
+            return false;
+        }
+        tool.expiresAt = Date.now() + additionalMs;
+        return true;
+    }
+    /**
+     * 清理过期工具
+     */
+    cleanup() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [name, tool] of this.#tempTools) {
+            if (tool.expiresAt > 0 && tool.expiresAt <= now) {
+                this.#registry.unregister(name);
+                this.#tempTools.delete(name);
+                cleaned++;
+                this.#logger.debug(`TemporaryToolRegistry: expired "${name}"`);
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * 获取所有临时工具信息
+     */
+    list() {
+        const now = Date.now();
+        const result = [];
+        for (const [name, tool] of this.#tempTools) {
+            result.push({
+                name,
+                forgeMode: tool.forgeMode,
+                registeredAt: tool.registeredAt,
+                expiresAt: tool.expiresAt,
+                remainingMs: tool.expiresAt > 0 ? Math.max(0, tool.expiresAt - now) : -1,
+            });
+        }
+        return result;
+    }
+    /**
+     * 检查是否是临时工具
+     */
+    isTemporary(name) {
+        return this.#tempTools.has(name);
+    }
+    /** 临时工具数量 */
+    get size() {
+        return this.#tempTools.size;
+    }
+    /** 停止定期清理（用于 shutdown） */
+    dispose() {
+        if (this.#cleanupTimer) {
+            clearInterval(this.#cleanupTimer);
+            this.#cleanupTimer = null;
+        }
+        // 回收所有临时工具
+        for (const name of [...this.#tempTools.keys()]) {
+            this.revoke(name);
+        }
+    }
+    /* ── Internal ── */
+    #startCleanup() {
+        this.#cleanupTimer = setInterval(() => {
+            this.cleanup();
+        }, CLEANUP_INTERVAL_MS);
+        // 允许 Node.js 进程在只剩此 timer 时退出
+        if (this.#cleanupTimer &&
+            typeof this.#cleanupTimer === 'object' &&
+            'unref' in this.#cleanupTimer) {
+            this.#cleanupTimer.unref();
+        }
+    }
+}