@cicctencent/agent-core 0.1.16 → 0.1.18

package/dist/esm/runtime/run-controller.js

@@ -0,0 +1,89 @@
+// ============================================================
+// RunController — Engine 执行、事件映射、RunRegistry、持久化 Sink 编排
+// ============================================================
+import { RunRegistry } from "./run-registry.js";
+import { createAgentEventCollectorState, mapAgentEvent } from "../utils/event-adapter.js";
+export class RunController {
+    registry;
+    persistence;
+    eventAdapter;
+    flushIntervalMs;
+    flushChars;
+    constructor(options = {}) {
+        this.registry = options.registry || new RunRegistry();
+        this.persistence = options.persistence;
+        this.eventAdapter = options.eventAdapter || {};
+        this.flushIntervalMs = options.flushIntervalMs ?? 5000;
+        this.flushChars = options.flushChars ?? 500;
+    }
+    subscribe(threadId, callback) {
+        return this.registry.subscribe(threadId, callback);
+    }
+    getBufferedEvents(threadId) {
+        return this.registry.getBufferedEvents(threadId);
+    }
+    async run(engine, options) {
+        const run = this.registry.startRun(options.threadId, options.sessionId, options.traceId);
+        const emitted = [];
+        let lastFlushedLen = 0;
+        let flushTimer = null;
+        let terminalStatus = 'done';
+        let terminalError;
+        const isCurrentRun = () => this.registry.getRun(options.threadId) === run;
+        await this.persistence?.onRunStart?.(run);
+        const flush = async () => {
+            if (!isCurrentRun())
+                return;
+            if (run.fullContent.length === lastFlushedLen && run.status === 'running')
+                return;
+            lastFlushedLen = run.fullContent.length;
+            run.lastFlushAt = Date.now();
+            await this.persistence?.onFlush?.(run);
+        };
+        flushTimer = setInterval(() => { flush().catch(() => undefined); }, this.flushIntervalMs);
+        if (typeof flushTimer === 'object' && 'unref' in flushTimer)
+            flushTimer.unref();
+        const state = createAgentEventCollectorState();
+        const adapterOptions = { ...this.eventAdapter, toolRegistry: options.toolRegistry || this.eventAdapter.toolRegistry };
+        try {
+            for await (const event of engine.run(options)) {
+                if (!isCurrentRun())
+                    break;
+                const mapped = mapAgentEvent(event, state, adapterOptions);
+                if (!mapped)
+                    continue;
+                emitted.push(mapped);
+                this.registry.addEvent(options.threadId, mapped.event, mapped.data);
+                const buffered = { event: mapped.event, data: mapped.data };
+                await this.persistence?.onEvent?.(run, buffered, event);
+                if (event.type === 'error') {
+                    terminalStatus = 'error';
+                    terminalError = event.error || 'Agent execution failed';
+                }
+                if (run.fullContent.length - lastFlushedLen >= this.flushChars) {
+                    await flush();
+                }
+            }
+            await flush();
+            if (isCurrentRun()) {
+                this.registry.finishRun(options.threadId, terminalStatus, terminalError);
+                await this.persistence?.onRunFinish?.(run, terminalStatus, terminalError);
+            }
+            return { run, events: emitted };
+        }
+        catch (err) {
+            const message = err?.message || String(err);
+            if (isCurrentRun()) {
+                this.registry.addEvent(options.threadId, 'error', { error: message });
+                this.registry.finishRun(options.threadId, 'error', message);
+                await this.persistence?.onRunFinish?.(run, 'error', message);
+            }
+            return { run, events: emitted };
+        }
+        finally {
+            if (flushTimer)
+                clearInterval(flushTimer);
+        }
+    }
+}
+//# sourceMappingURL=run-controller.js.map

package/dist/esm/runtime/run-controller.js.map

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

package/dist/esm/sandbox/local-sandbox.d.ts

@@ -0,0 +1,59 @@
+import type { ShellExecutor, FileSystemExecutor } from '../tool/types.js';
+import type { Sandbox, SandboxConfig, SandboxManager, ScriptLanguage } from './types.js';
+export interface LocalSandboxOptions extends Partial<SandboxConfig> {
+    allowedReadDirs?: string[];
+    env?: Record<string, string | undefined>;
+    cleanupOnDestroy?: boolean;
+    strictPath?: boolean;
+}
+export declare class LocalSandboxFileSystemExecutor implements FileSystemExecutor {
+    private readonly rootDir;
+    private readonly maxFileSize;
+    private readonly allowedReadDirs;
+    private readonly strictPath;
+    constructor(rootDir: string, maxFileSize?: number, allowedReadDirs?: string[], strictPath?: boolean);
+    readFile(filePath: string): Promise<string>;
+    readFileBuffer(filePath: string): Promise<Buffer>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    appendFile(filePath: string, content: string): Promise<void>;
+    listDir(dirPath: string): Promise<string[]>;
+    private isInside;
+    private safeInRoot;
+    private resolveWritePath;
+    private resolveReadPath;
+}
+export declare class LocalSandboxShellExecutor implements ShellExecutor {
+    private readonly rootDir;
+    private readonly commandRestriction;
+    private readonly maxBuffer;
+    private guard;
+    private outputBuffer;
+    private env;
+    constructor(rootDir: string, commandRestriction?: boolean, env?: Record<string, string | undefined>, maxBuffer?: number);
+    exec(command: string, timeout?: number): Promise<string>;
+    write(_data: string): void;
+    read(lines?: number): string;
+}
+export declare class LocalSandbox implements Sandbox {
+    readonly id: string;
+    readonly rootDir: string;
+    private fsExecutor;
+    private shellExecutor;
+    private cleanupOnDestroy;
+    constructor(id: string, options: LocalSandboxOptions);
+    init(): Promise<void>;
+    getShellExecutor(): ShellExecutor;
+    getFileSystemExecutor(): FileSystemExecutor;
+    runScript(language: ScriptLanguage, code: string, timeout?: number): Promise<string>;
+    destroy(): Promise<void>;
+}
+export declare class LocalSandboxManager implements SandboxManager {
+    private readonly options;
+    private sandboxes;
+    constructor(options?: LocalSandboxOptions);
+    create(id: string, config?: Partial<SandboxConfig>): Promise<Sandbox>;
+    get(id: string): Sandbox | undefined;
+    destroy(id: string): Promise<void>;
+    destroyAll(): Promise<void>;
+}
+//# sourceMappingURL=local-sandbox.d.ts.map

package/dist/esm/sandbox/local-sandbox.d.ts.map

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

package/dist/esm/sandbox/local-sandbox.js

@@ -0,0 +1,188 @@
+// ============================================================
+// LocalSandbox — 基于本地进程的默认沙箱实现
+// ============================================================
+import { exec as cpExec } from 'child_process';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { existsSync } from 'fs';
+import { getProjectDataPath } from "../utils/data-dir.js";
+import { SecurityGuard } from "../security/guard.js";
+import { DEFAULT_SANDBOX_CONFIG, SANDBOX_BLOCKED_COMMANDS, SANDBOX_SAFE_ENV_KEYS } from "./types.js";
+function filterEnv(env) {
+    const filtered = {};
+    for (const key of SANDBOX_SAFE_ENV_KEYS)
+        if (env[key])
+            filtered[key] = env[key];
+    filtered.PYTHONIOENCODING = 'utf-8';
+    filtered.PYTHONUTF8 = '1';
+    return filtered;
+}
+const LANGUAGE_MAP = {
+    python: { ext: '.py', command: 'python3' },
+    nodejs: { ext: '.cjs', command: 'node' },
+    shell: { ext: '.sh', command: process.platform === 'win32' ? 'bash' : 'bash' },
+};
+export class LocalSandboxFileSystemExecutor {
+    rootDir;
+    maxFileSize;
+    allowedReadDirs;
+    strictPath;
+    constructor(rootDir, maxFileSize = DEFAULT_SANDBOX_CONFIG.maxFileSize, allowedReadDirs = [], strictPath = false) {
+        this.rootDir = rootDir;
+        this.maxFileSize = maxFileSize;
+        this.allowedReadDirs = allowedReadDirs;
+        this.strictPath = strictPath;
+    }
+    async readFile(filePath) {
+        return fs.readFile(this.resolveReadPath(filePath), 'utf-8');
+    }
+    async readFileBuffer(filePath) {
+        return fs.readFile(this.resolveReadPath(filePath));
+    }
+    async writeFile(filePath, content) {
+        const resolved = this.resolveWritePath(filePath);
+        const size = Buffer.byteLength(content, 'utf-8');
+        if (size > this.maxFileSize)
+            throw new Error(`Sandbox: file size ${size} bytes exceeds limit ${this.maxFileSize} bytes`);
+        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        await fs.writeFile(resolved, content, 'utf-8');
+    }
+    async appendFile(filePath, content) {
+        const resolved = this.resolveWritePath(filePath);
+        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        await fs.appendFile(resolved, content, 'utf-8');
+    }
+    async listDir(dirPath) {
+        const entries = await fs.readdir(this.resolveReadPath(dirPath), { withFileTypes: true });
+        return entries.map(e => e.isDirectory() ? `${e.name}/` : e.name);
+    }
+    isInside(target, base) {
+        const rel = path.relative(path.resolve(base), path.resolve(target));
+        return !rel.startsWith('..') && !path.isAbsolute(rel);
+    }
+    safeInRoot(filePath) {
+        return path.resolve(this.rootDir, path.basename(filePath));
+    }
+    resolveWritePath(filePath) {
+        const resolved = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(this.rootDir, filePath);
+        return this.isInside(resolved, this.rootDir) ? resolved : this.safeInRoot(filePath);
+    }
+    resolveReadPath(filePath) {
+        const resolved = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(this.rootDir, filePath);
+        if (this.isInside(resolved, this.rootDir))
+            return resolved;
+        for (const dir of this.allowedReadDirs)
+            if (this.isInside(resolved, dir))
+                return resolved;
+        return this.safeInRoot(filePath);
+    }
+}
+export class LocalSandboxShellExecutor {
+    rootDir;
+    commandRestriction;
+    maxBuffer;
+    guard;
+    outputBuffer = [];
+    env;
+    constructor(rootDir, commandRestriction = true, env = process.env, maxBuffer = 500) {
+        this.rootDir = rootDir;
+        this.commandRestriction = commandRestriction;
+        this.maxBuffer = maxBuffer;
+        this.guard = new SecurityGuard({ deleteProtection: true, blacklistEnabled: true, rules: SANDBOX_BLOCKED_COMMANDS });
+        this.env = filterEnv(env);
+    }
+    async exec(command, timeout = DEFAULT_SANDBOX_CONFIG.execTimeout) {
+        if (this.commandRestriction) {
+            const sanitized = this.guard.sanitize(command.trim());
+            if (!sanitized.safe)
+                return `[Sandbox blocked] ${sanitized.reason}`;
+            if (sanitized.rewritten)
+                command = sanitized.rewritten;
+        }
+        const shellCommand = process.platform === 'win32' ? `chcp 65001 >nul 2>&1 & ${command}` : command;
+        return new Promise(resolve => {
+            cpExec(shellCommand, {
+                timeout,
+                maxBuffer: 1024 * 1024 * 5,
+                windowsHide: true,
+                encoding: 'buffer',
+                cwd: this.rootDir,
+                env: this.env,
+            }, (error, stdoutBuf, stderrBuf) => {
+                const stdout = stdoutBuf ? stdoutBuf.toString('utf-8') : '';
+                const stderr = stderrBuf ? stderrBuf.toString('utf-8') : '';
+                let output = [stdout, stderr].filter(Boolean).join('\n');
+                if (error && !output.trim())
+                    output = error.message;
+                this.outputBuffer.push(...output.split('\n'));
+                if (this.outputBuffer.length > this.maxBuffer)
+                    this.outputBuffer = this.outputBuffer.slice(-this.maxBuffer);
+                resolve(output || '(no output)');
+            });
+        });
+    }
+    write(_data) { }
+    read(lines = 50) {
+        return this.outputBuffer.slice(Math.max(0, this.outputBuffer.length - lines)).join('\n') || '(no terminal output)';
+    }
+}
+export class LocalSandbox {
+    id;
+    rootDir;
+    fsExecutor;
+    shellExecutor;
+    cleanupOnDestroy;
+    constructor(id, options) {
+        this.id = id;
+        this.rootDir = options.rootDir || path.join(getProjectDataPath(), 'sandboxes', id);
+        this.cleanupOnDestroy = options.cleanupOnDestroy ?? false;
+        const maxFileSize = options.maxFileSize ?? DEFAULT_SANDBOX_CONFIG.maxFileSize;
+        const allowedReadDirs = options.allowedReadDirs?.map(d => path.resolve(d)) || [];
+        this.fsExecutor = new LocalSandboxFileSystemExecutor(this.rootDir, maxFileSize, allowedReadDirs, options.strictPath ?? false);
+        this.shellExecutor = new LocalSandboxShellExecutor(this.rootDir, options.commandRestriction ?? DEFAULT_SANDBOX_CONFIG.commandRestriction, options.env);
+    }
+    async init() {
+        await fs.mkdir(this.rootDir, { recursive: true });
+    }
+    getShellExecutor() { return this.shellExecutor; }
+    getFileSystemExecutor() { return this.fsExecutor; }
+    async runScript(language, code, timeout) {
+        const spec = LANGUAGE_MAP[language];
+        const filename = `script_${Date.now()}_${crypto.randomBytes(4).toString('hex')}${spec.ext}`;
+        await this.fsExecutor.writeFile(filename, code);
+        return this.shellExecutor.exec(`${spec.command} ${filename}`, timeout);
+    }
+    async destroy() {
+        if (this.cleanupOnDestroy && existsSync(this.rootDir))
+            await fs.rm(this.rootDir, { recursive: true, force: true });
+    }
+}
+export class LocalSandboxManager {
+    options;
+    sandboxes = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async create(id, config) {
+        const existing = this.sandboxes.get(id);
+        if (existing)
+            return existing;
+        const sandbox = new LocalSandbox(id, { ...this.options, ...config });
+        await sandbox.init();
+        this.sandboxes.set(id, sandbox);
+        return sandbox;
+    }
+    get(id) { return this.sandboxes.get(id); }
+    async destroy(id) {
+        const sandbox = this.sandboxes.get(id);
+        if (!sandbox)
+            return;
+        await sandbox.destroy();
+        this.sandboxes.delete(id);
+    }
+    async destroyAll() {
+        await Promise.all([...this.sandboxes.keys()].map(id => this.destroy(id)));
+    }
+}
+//# sourceMappingURL=local-sandbox.js.map

package/dist/esm/sandbox/local-sandbox.js.map

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

package/dist/esm/tool/builtin-tools.d.ts

@@ -0,0 +1,22 @@
+import type { RegisteredTool } from './types.js';
+import type { ToolRegistry } from './registry.js';
+import type { SkillManager } from '../skill/manager.js';
+export interface BuiltinToolOptions {
+    includeShell?: boolean;
+    includeFileSystem?: boolean;
+    includeToolDoc?: boolean;
+    includeSkillLoader?: boolean;
+    toolRegistry?: ToolRegistry;
+    skillManager?: SkillManager;
+    toolResultStore?: ToolResultStoreLike;
+}
+export interface ToolResultStoreLike {
+    read(callId: string): string | null;
+    has?(callId: string): boolean;
+}
+export declare function createShellTools(): RegisteredTool[];
+export declare function createFileSystemTools(): RegisteredTool[];
+export declare function createToolDocTool(registry?: ToolRegistry): RegisteredTool;
+export declare function createSkillLoaderTool(skillManager?: SkillManager): RegisteredTool;
+export declare function createBuiltinTools(options?: BuiltinToolOptions): RegisteredTool[];
+//# sourceMappingURL=builtin-tools.d.ts.map

package/dist/esm/tool/builtin-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-tools.d.ts","sourceRoot":"","sources":["../../../src/tool/builtin-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED,wBAAgB,gBAAgB,IAAI,cAAc,EAAE,CA2CnD;AAED,wBAAgB,qBAAqB,IAAI,cAAc,EAAE,CAkFxD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,cAAc,CA0BzE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,cAAc,CAyBjF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,kBAAuB,GAAG,cAAc,EAAE,CAOrF"}

package/dist/esm/tool/builtin-tools.js

@@ -0,0 +1,214 @@
+// ============================================================
+// Builtin Tools — 可选通用工具工厂
+// ============================================================
+export function createShellTools() {
+    return [
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'execute_command',
+                    description: 'Execute a shell command through the injected ToolContext.shell executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            command: { type: 'string', description: 'Shell command to execute' },
+                            timeout: { type: 'number', description: 'Timeout in milliseconds' },
+                        },
+                        required: ['command'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                const command = String(args.command || '').trim();
+                if (!command)
+                    return 'ERROR: execute_command requires non-empty command.';
+                return ctx.shell.exec(command, Number(args.timeout) || undefined);
+            },
+            category: 'builtin',
+            concurrent: false,
+        },
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'read_terminal',
+                    description: 'Read recent terminal output from the injected ToolContext.shell executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: { lines: { type: 'number', description: 'Number of lines to read' } },
+                    },
+                },
+            },
+            executor: async (args, ctx) => ctx.shell.read(Number(args.lines) || 50),
+            category: 'builtin',
+            concurrent: true,
+        },
+    ];
+}
+export function createFileSystemTools() {
+    return [
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'read_file',
+                    description: 'Read a text file through the injected ToolContext.fs executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: { path: { type: 'string', description: 'File path to read' } },
+                        required: ['path'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                if (!ctx.fs)
+                    return 'Error: FileSystem executor not available';
+                const filePath = String(args.path || '').trim();
+                if (!filePath)
+                    return 'Error: path is required.';
+                return ctx.fs.readFile(filePath);
+            },
+            category: 'builtin',
+            concurrent: true,
+        },
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'write_file',
+                    description: 'Write text content to a file through the injected ToolContext.fs executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path to write' },
+                            content: { type: 'string', description: 'Text content' },
+                        },
+                        required: ['path', 'content'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                if (!ctx.fs)
+                    return 'Error: FileSystem executor not available';
+                const filePath = String(args.path || '').trim();
+                if (!filePath)
+                    return 'Error: path is required.';
+                await ctx.fs.writeFile(filePath, String(args.content ?? ''));
+                return `File written: ${filePath}`;
+            },
+            category: 'builtin',
+            concurrent: false,
+        },
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'append_file',
+                    description: 'Append text content to a file through the injected ToolContext.fs executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path to append' },
+                            content: { type: 'string', description: 'Text content to append' },
+                        },
+                        required: ['path', 'content'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                if (!ctx.fs)
+                    return 'Error: FileSystem executor not available';
+                const filePath = String(args.path || '').trim();
+                if (!filePath)
+                    return 'Error: path is required.';
+                if (ctx.fs.appendFile)
+                    await ctx.fs.appendFile(filePath, String(args.content ?? ''));
+                else {
+                    let existing = '';
+                    try {
+                        existing = await ctx.fs.readFile(filePath);
+                    }
+                    catch {
+                        existing = '';
+                    }
+                    await ctx.fs.writeFile(filePath, existing + String(args.content ?? ''));
+                }
+                return `Content appended to: ${filePath}`;
+            },
+            category: 'builtin',
+            concurrent: false,
+        },
+    ];
+}
+export function createToolDocTool(registry) {
+    return {
+        definition: {
+            type: 'function',
+            function: {
+                name: 'read_tool_doc',
+                description: 'Read full schema/documentation for a registered tool. Use tool_name="list" to list names.',
+                parameters: {
+                    type: 'object',
+                    properties: { tool_name: { type: 'string', description: 'Tool name, or "list"' } },
+                    required: ['tool_name'],
+                },
+            },
+        },
+        executor: async (args, ctx) => {
+            const toolRegistry = ctx.custom?.toolRegistry || registry;
+            if (!toolRegistry)
+                return 'Error: ToolRegistry not available';
+            const name = String(args.tool_name || '').trim();
+            if (name === 'list')
+                return toolRegistry.listNames().join('\n');
+            const tool = toolRegistry.get(name);
+            if (!tool)
+                return `Tool not found: ${name}`;
+            return JSON.stringify(tool.definition.function, null, 2);
+        },
+        category: 'builtin',
+        concurrent: true,
+    };
+}
+export function createSkillLoaderTool(skillManager) {
+    return {
+        definition: {
+            type: 'function',
+            function: {
+                name: 'load_skill',
+                description: 'Load full instructions for an available skill by skill_id.',
+                parameters: {
+                    type: 'object',
+                    properties: { skill_id: { type: 'string', description: 'Skill id' } },
+                    required: ['skill_id'],
+                },
+            },
+        },
+        executor: async (args, ctx) => {
+            const manager = ctx.custom?.skillManager || skillManager;
+            if (!manager)
+                return 'Error: SkillManager not available';
+            const id = String(args.skill_id || '').trim();
+            const skill = manager.get(id);
+            if (!skill)
+                return `Skill not found: ${id}`;
+            return skill.content || '';
+        },
+        category: 'builtin',
+        concurrent: true,
+    };
+}
+export function createBuiltinTools(options = {}) {
+    const tools = [];
+    if (options.includeShell ?? true)
+        tools.push(...createShellTools());
+    if (options.includeFileSystem ?? true)
+        tools.push(...createFileSystemTools());
+    if (options.includeToolDoc ?? true)
+        tools.push(createToolDocTool(options.toolRegistry));
+    if (options.includeSkillLoader ?? true)
+        tools.push(createSkillLoaderTool(options.skillManager));
+    return tools;
+}
+//# sourceMappingURL=builtin-tools.js.map

package/dist/esm/tool/builtin-tools.js.map

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

package/dist/esm/tool/registry.d.ts

@@ -82,6 +82,31 @@ export declare class ToolRegistry {
     registerAll(tools: RegisteredTool[]): void;
     /** 注销工具 */
     unregister(name: string): void;
+    /** 克隆当前注册表（浅拷贝工具定义与 executor 引用） */
+    clone(filter?: {
+        category?: ToolCategory;
+        names?: string[];
+        predicate?: (tool: RegisteredTool) => boolean;
+    }): ToolRegistry;
+    /** 按分类生成新注册表 */
+    filterByCategory(category: ToolCategory): ToolRegistry;
+    /** 按 metadata 条件生成新注册表 */
+    filterByMetadata(predicate: (metadata: Record<string, unknown>, tool: RegisteredTool) => boolean): ToolRegistry;
+    /** 导出扁平工具定义（用于使用方适配旧 API 或 UI 展示） */
+    toFlatTools(): Array<Omit<FlatToolOptions, 'execute'> & {
+        execute: ToolExecutor;
+    }>;
+    /** 转为 OpenAI function calling tools 格式 */
+    toOpenAITools(filter?: {
+        category?: ToolCategory;
+        names?: string[];
+    }): ToolDefinition[];
+    /** 生成工具摘要，适合注入 prompt 或 UI 列表 */
+    summary(options?: {
+        maxDescriptionLength?: number;
+        category?: ToolCategory;
+        names?: string[];
+    }): string;
     /** 获取指定工具 */
     get(name: string): RegisteredTool | undefined;
     /** 获取所有工具定义（传给 LLM） */