kode-sdk 2.7.0

package/dist/tools/registry.d.ts

@@ -0,0 +1,29 @@
+import { Hooks } from '../core/hooks';
+import { ToolContext } from '../core/types';
+export type ToolSource = 'builtin' | 'registered' | 'mcp';
+export interface ToolDescriptor {
+    source: ToolSource;
+    name: string;
+    registryId?: string;
+    config?: Record<string, any>;
+    metadata?: Record<string, any>;
+}
+export interface ToolInstance {
+    name: string;
+    description: string;
+    input_schema: any;
+    hooks?: Hooks;
+    permissionDetails?: (call: any, ctx: ToolContext) => any;
+    exec(args: any, ctx: ToolContext): Promise<any>;
+    prompt?: string | ((ctx: ToolContext) => string | Promise<string>);
+    toDescriptor(): ToolDescriptor;
+}
+export type ToolFactory = (config?: Record<string, any>) => ToolInstance;
+export declare class ToolRegistry {
+    private factories;
+    register(id: string, factory: ToolFactory): void;
+    has(id: string): boolean;
+    create(id: string, config?: Record<string, any>): ToolInstance;
+    list(): string[];
+}
+export declare const globalToolRegistry: ToolRegistry;

package/dist/tools/registry.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalToolRegistry = exports.ToolRegistry = void 0;
+class ToolRegistry {
+    constructor() {
+        this.factories = new Map();
+    }
+    register(id, factory) {
+        this.factories.set(id, factory);
+    }
+    has(id) {
+        return this.factories.has(id);
+    }
+    create(id, config) {
+        const factory = this.factories.get(id);
+        if (!factory) {
+            throw new Error(`Tool not registered: ${id}`);
+        }
+        return factory(config);
+    }
+    list() {
+        return Array.from(this.factories.keys());
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+exports.globalToolRegistry = new ToolRegistry();

package/dist/tools/skill_activate/index.d.ts

@@ -0,0 +1,5 @@
+export declare const PROMPT = "\n### skill_activate\n\n\u6FC0\u6D3B\u4E00\u4E2A Skill\uFF0C\u5C06\u5176\u5B8C\u6574\u6307\u4EE4\u52A0\u8F7D\u5230\u4E0A\u4E0B\u6587\u4E2D\u3002\n\n\u4F7F\u7528\u573A\u666F\uFF1A\n- \u5F53\u4EFB\u52A1\u9700\u8981\u7279\u5B9A Skill \u7684\u4E13\u4E1A\u77E5\u8BC6\u65F6\n- \u5728 skill_list \u67E5\u770B\u53EF\u7528 Skills \u540E\u9009\u62E9\u6FC0\u6D3B\n- \u9700\u8981\u9075\u5FAA\u7279\u5B9A\u5F00\u53D1\u89C4\u8303\u6216\u6D41\u7A0B\u65F6\n\n\u6CE8\u610F\uFF1A\n- \u6FC0\u6D3B\u540E Skill \u7684\u5B8C\u6574\u6307\u4EE4\u4F1A\u6CE8\u5165\u5230\u4E0A\u4E0B\u6587\n- \u5982\u679C Skill \u5305\u542B scripts/\uFF0C\u53EF\u4EE5\u4F7F\u7528 skill_resource \u52A0\u8F7D\n- \u6FC0\u6D3B\u4F1A\u6301\u4E45\u5316\uFF0CResume \u65F6\u81EA\u52A8\u6062\u590D\n";
+/**
+ * skill_activate 工具 - 激活 Skill 并加载完整指令
+ */
+export declare const SkillActivate: import("..").ToolInstance;

package/dist/tools/skill_activate/index.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillActivate = exports.PROMPT = void 0;
+const zod_1 = require("zod");
+const tool_1 = require("../tool");
+exports.PROMPT = `
+### skill_activate
+
+激活一个 Skill，将其完整指令加载到上下文中。
+
+使用场景：
+- 当任务需要特定 Skill 的专业知识时
+- 在 skill_list 查看可用 Skills 后选择激活
+- 需要遵循特定开发规范或流程时
+
+注意：
+- 激活后 Skill 的完整指令会注入到上下文
+- 如果 Skill 包含 scripts/，可以使用 skill_resource 加载
+- 激活会持久化，Resume 时自动恢复
+`;
+/**
+ * skill_activate 工具 - 激活 Skill 并加载完整指令
+ */
+exports.SkillActivate = (0, tool_1.tool)({
+    name: 'skill_activate',
+    description: 'Activate a skill and load its full instructions into context',
+    parameters: zod_1.z.object({
+        name: zod_1.z.string().describe('Name of the skill to activate'),
+    }),
+    async execute(args, ctx) {
+        const manager = ctx.agent?.getSkillsManager?.();
+        if (!manager) {
+            return {
+                ok: false,
+                error: 'Skills not configured for this agent',
+                recommendations: ['确认 Agent 配置中启用了 skills'],
+            };
+        }
+        try {
+            const skill = await ctx.agent.activateSkill(args.name);
+            return {
+                ok: true,
+                message: `Skill "${skill.name}" activated`,
+                description: skill.description,
+                hasScripts: (skill.resources?.scripts?.length || 0) > 0,
+                hasReferences: (skill.resources?.references?.length || 0) > 0,
+                hasAssets: (skill.resources?.assets?.length || 0) > 0,
+                resources: skill.resources,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error.message || String(error),
+                recommendations: [
+                    '使用 skill_list 查看可用的 Skills',
+                    '确认 Skill 名称拼写正确',
+                ],
+            };
+        }
+    },
+    metadata: { readonly: true },
+});

package/dist/tools/skill_list/index.d.ts

@@ -0,0 +1,5 @@
+export declare const PROMPT = "\n### skill_list\n\n\u5217\u51FA\u5F53\u524D\u53EF\u7528\u7684 Skills\u3002\u8FD4\u56DE\u6BCF\u4E2A Skill \u7684\u540D\u79F0\u3001\u63CF\u8FF0\u548C\u6FC0\u6D3B\u72B6\u6001\u3002\n\n\u4F7F\u7528\u573A\u666F\uFF1A\n- \u5F53\u9700\u8981\u4E86\u89E3\u6709\u54EA\u4E9B Skills \u53EF\u7528\u65F6\n- \u5728\u9009\u62E9\u6FC0\u6D3B\u54EA\u4E2A Skill \u4E4B\u524D\n- \u68C0\u67E5 Skill \u7684\u6FC0\u6D3B\u72B6\u6001\n";
+/**
+ * skill_list 工具 - 列出可用的 Skills
+ */
+export declare const SkillList: import("..").ToolInstance;

package/dist/tools/skill_list/index.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillList = exports.PROMPT = void 0;
+const zod_1 = require("zod");
+const tool_1 = require("../tool");
+exports.PROMPT = `
+### skill_list
+
+列出当前可用的 Skills。返回每个 Skill 的名称、描述和激活状态。
+
+使用场景：
+- 当需要了解有哪些 Skills 可用时
+- 在选择激活哪个 Skill 之前
+- 检查 Skill 的激活状态
+`;
+/**
+ * skill_list 工具 - 列出可用的 Skills
+ */
+exports.SkillList = (0, tool_1.tool)({
+    name: 'skill_list',
+    description: 'List available skills with their names, descriptions, and activation status',
+    parameters: zod_1.z.object({}),
+    async execute(_args, ctx) {
+        const manager = ctx.agent?.getSkillsManager?.();
+        if (!manager) {
+            return {
+                ok: false,
+                error: 'Skills not configured for this agent',
+                recommendations: ['确认 Agent 配置中启用了 skills'],
+            };
+        }
+        const skills = manager.list();
+        return {
+            ok: true,
+            skills: skills.map((s) => ({
+                name: s.name,
+                description: s.description,
+                activated: manager.isActivated(s.name),
+                hasScripts: (s.resources?.scripts?.length || 0) > 0,
+                hasReferences: (s.resources?.references?.length || 0) > 0,
+                hasAssets: (s.resources?.assets?.length || 0) > 0,
+            })),
+            count: skills.length,
+            activatedCount: skills.filter((s) => manager.isActivated(s.name)).length,
+        };
+    },
+    metadata: { readonly: true },
+});

package/dist/tools/skill_resource/index.d.ts

@@ -0,0 +1,5 @@
+export declare const PROMPT = "\n### skill_resource\n\n\u52A0\u8F7D\u5DF2\u6FC0\u6D3B Skill \u7684\u8D44\u6E90\u6587\u4EF6\u5185\u5BB9\uFF08scripts/\u3001references/\u3001assets/ \u76EE\u5F55\u4E0B\u7684\u6587\u4EF6\uFF09\u3002\n\n\u4F7F\u7528\u573A\u666F\uFF1A\n- \u9700\u8981\u8BFB\u53D6 Skill \u63D0\u4F9B\u7684\u53C2\u8003\u6587\u6863\n- \u9700\u8981\u52A0\u8F7D Skill \u7684\u6A21\u677F\u6216\u8D44\u6E90\u6587\u4EF6\n- \u67E5\u770B Skill \u7684\u793A\u4F8B\u4EE3\u7801\n\n\u6CE8\u610F\uFF1A\n- \u53EA\u80FD\u52A0\u8F7D\u5DF2\u6FC0\u6D3B Skill \u7684\u8D44\u6E90\n- resourcePath \u662F\u76F8\u5BF9\u4E8E Skill \u76EE\u5F55\u7684\u8DEF\u5F84\n- \u652F\u6301 scripts/\u3001references/\u3001assets/ \u76EE\u5F55\u4E0B\u7684\u6587\u4EF6\n";
+/**
+ * skill_resource 工具 - 加载 Skill 资源文件
+ */
+export declare const SkillResource: import("..").ToolInstance;

package/dist/tools/skill_resource/index.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillResource = exports.PROMPT = void 0;
+const zod_1 = require("zod");
+const tool_1 = require("../tool");
+exports.PROMPT = `
+### skill_resource
+
+加载已激活 Skill 的资源文件内容（scripts/、references/、assets/ 目录下的文件）。
+
+使用场景：
+- 需要读取 Skill 提供的参考文档
+- 需要加载 Skill 的模板或资源文件
+- 查看 Skill 的示例代码
+
+注意：
+- 只能加载已激活 Skill 的资源
+- resourcePath 是相对于 Skill 目录的路径
+- 支持 scripts/、references/、assets/ 目录下的文件
+`;
+/**
+ * skill_resource 工具 - 加载 Skill 资源文件
+ */
+exports.SkillResource = (0, tool_1.tool)({
+    name: 'skill_resource',
+    description: 'Load a resource file from an activated skill (scripts, references, assets)',
+    parameters: zod_1.z.object({
+        skillName: zod_1.z.string().describe('Name of the skill'),
+        resourcePath: zod_1.z.string().describe('Path relative to skill directory (e.g., "references/guide.md")'),
+    }),
+    async execute(args, ctx) {
+        const manager = ctx.agent?.getSkillsManager?.();
+        if (!manager) {
+            return {
+                ok: false,
+                error: 'Skills not configured for this agent',
+                recommendations: ['确认 Agent 配置中启用了 skills'],
+            };
+        }
+        const skill = manager.get(args.skillName);
+        if (!skill) {
+            return {
+                ok: false,
+                error: `Skill not found: ${args.skillName}`,
+                recommendations: [
+                    '使用 skill_list 查看可用的 Skills',
+                    '确认 Skill 名称拼写正确',
+                ],
+            };
+        }
+        if (!manager.isActivated(args.skillName)) {
+            return {
+                ok: false,
+                error: `Skill "${args.skillName}" is not activated`,
+                recommendations: [
+                    `使用 skill_activate 激活 "${args.skillName}"`,
+                ],
+            };
+        }
+        try {
+            const content = await manager.loadResource(args.skillName, args.resourcePath);
+            return {
+                ok: true,
+                skillName: args.skillName,
+                resourcePath: args.resourcePath,
+                content,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error.message || String(error),
+                recommendations: [
+                    '检查资源路径是否正确',
+                    '确认文件存在于 Skill 目录中',
+                    `可用资源: ${JSON.stringify(skill.resources || {})}`,
+                ],
+            };
+        }
+    },
+    metadata: { readonly: true },
+});

package/dist/tools/task_run/index.d.ts

@@ -0,0 +1,7 @@
+export interface AgentTemplate {
+    id: string;
+    system?: string;
+    tools?: string[];
+    whenToUse?: string;
+}
+export declare function createTaskRunTool(templates: AgentTemplate[]): import("..").ToolInstance;

package/dist/tools/task_run/index.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskRunTool = createTaskRunTool;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const prompt_1 = require("./prompt");
+function createTaskRunTool(templates) {
+    if (!templates || templates.length === 0) {
+        throw new Error('Cannot create task_run tool: no agent templates provided');
+    }
+    const TaskRun = (0, tool_1.tool)({
+        name: 'task_run',
+        description: prompt_1.DESCRIPTION,
+        parameters: zod_1.z.object({
+            description: zod_1.z.string().describe('Short description of the task (3-5 words)'),
+            prompt: zod_1.z.string().describe('Detailed instructions for the sub-agent'),
+            agentTemplateId: zod_1.z.string().describe('Agent template ID to use for this task'),
+            context: zod_1.z.string().optional().describe('Additional context to append'),
+        }),
+        async execute(args, ctx) {
+            const { description, prompt, agentTemplateId, context } = args;
+            const template = templates.find((tpl) => tpl.id === agentTemplateId);
+            if (!template) {
+                const availableTemplates = templates
+                    .map((tpl) => `  - ${tpl.id}: ${tpl.whenToUse || 'General purpose agent'}`)
+                    .join('\n');
+                throw new Error(`Agent template '${agentTemplateId}' not found.\n\nAvailable templates:\n${availableTemplates}\n\nPlease choose one of the available template IDs.`);
+            }
+            const detailedPrompt = [
+                `# Task: ${description}`,
+                prompt,
+                context ? `\n# Additional Context\n${context}` : undefined,
+            ]
+                .filter(Boolean)
+                .join('\n\n');
+            if (!ctx.agent?.delegateTask) {
+                throw new Error('Task delegation not supported by this agent version');
+            }
+            const result = await ctx.agent.delegateTask({
+                templateId: template.id,
+                prompt: detailedPrompt,
+                tools: template.tools,
+                callId: ctx.callId,
+            });
+            return {
+                status: result.status,
+                template: template.id,
+                text: result.text,
+                permissionIds: result.permissionIds,
+                agentId: result.agentId,
+            };
+        },
+        metadata: {
+            readonly: false,
+            version: '1.0',
+        },
+    });
+    TaskRun.prompt = (0, prompt_1.generatePrompt)(templates);
+    return TaskRun;
+}

package/dist/tools/task_run/prompt.d.ts

@@ -0,0 +1,5 @@
+export declare const DESCRIPTION = "Delegate a task to a specialized sub-agent";
+export declare function generatePrompt(templates: Array<{
+    id: string;
+    whenToUse?: string;
+}>): string;

package/dist/tools/task_run/prompt.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESCRIPTION = void 0;
+exports.generatePrompt = generatePrompt;
+exports.DESCRIPTION = 'Delegate a task to a specialized sub-agent';
+function generatePrompt(templates) {
+    const templateList = templates
+        .map((tpl) => `- agentTemplateId: ${tpl.id}\n  whenToUse: ${tpl.whenToUse || 'General purpose tasks'}`)
+        .join('\n');
+    return `Delegate complex, multi-step work to specialized sub-agents.
+
+Instructions:
+- Always provide a concise "description" (3-5 words) and a detailed "prompt" outlining deliverables.
+- REQUIRED: Set "agentTemplateId" to one of the available template IDs below.
+- Optionally supply "context" for extra background information.
+- The tool returns the sub-agent's final text and any pending permissions.
+
+Parallel Execution:
+- Multiple task_run calls in the same response will execute in parallel.
+- Use this for independent tasks that don't depend on each other's output.
+
+Available agent templates:
+${templateList}
+
+Safety/Limitations:
+- Sub-agents inherit the same sandbox and tool restrictions.
+- Task delegation depth may be limited to prevent infinite recursion.
+- Sub-agents cannot access parent agent state or context directly.`;
+}

package/dist/tools/todo_read/index.d.ts

@@ -0,0 +1 @@
+export declare const TodoRead: import("..").ToolInstance;

package/dist/tools/todo_read/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TodoRead = void 0;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const prompt_1 = require("./prompt");
+exports.TodoRead = (0, tool_1.tool)({
+    name: 'todo_read',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({}),
+    async execute(_args, ctx) {
+        if (ctx.agent?.getTodos) {
+            return { todos: ctx.agent.getTodos() };
+        }
+        const service = ctx.services?.todo;
+        if (!service) {
+            return {
+                todos: [],
+                note: 'Todo service not enabled for this agent'
+            };
+        }
+        return { todos: service.list() };
+    },
+    metadata: {
+        readonly: true,
+        version: '1.0',
+    },
+});
+exports.TodoRead.prompt = prompt_1.PROMPT;

package/dist/tools/todo_read/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "Read the current todo list managed by the agent";
+export declare const PROMPT = "Retrieve the canonical list of todos that this agent maintains.\n\nGuidelines:\n- Use this before planning or reprioritizing work\n- The returned list reflects the current state of all tracked tasks\n- Each todo includes: id, title, status, and optional assignee/notes\n\nTodo Status Values:\n- pending: Not yet started\n- in_progress: Currently being worked on\n- completed: Finished\n\nLimitations:\n- Returns empty list if todo service is not enabled for this agent";

package/dist/tools/todo_read/prompt.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Read the current todo list managed by the agent';
+exports.PROMPT = `Retrieve the canonical list of todos that this agent maintains.
+
+Guidelines:
+- Use this before planning or reprioritizing work
+- The returned list reflects the current state of all tracked tasks
+- Each todo includes: id, title, status, and optional assignee/notes
+
+Todo Status Values:
+- pending: Not yet started
+- in_progress: Currently being worked on
+- completed: Finished
+
+Limitations:
+- Returns empty list if todo service is not enabled for this agent`;

package/dist/tools/todo_write/index.d.ts

@@ -0,0 +1 @@
+export declare const TodoWrite: import("..").ToolInstance;

package/dist/tools/todo_write/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TodoWrite = void 0;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const prompt_1 = require("./prompt");
+const todoItemSchema = zod_1.z.object({
+    id: zod_1.z.string().describe('Unique identifier for the todo'),
+    title: zod_1.z.string().describe('Clear description of the task'),
+    status: zod_1.z.enum(['pending', 'in_progress', 'completed']).describe('Current status'),
+    assignee: zod_1.z.string().optional().describe('Who is responsible'),
+    notes: zod_1.z.string().optional().describe('Additional context'),
+});
+exports.TodoWrite = (0, tool_1.tool)({
+    name: 'todo_write',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        todos: zod_1.z.array(todoItemSchema).describe('Array of todo items'),
+    }),
+    async execute(args, ctx) {
+        const { todos } = args;
+        const inProgressCount = todos.filter((t) => t.status === 'in_progress').length;
+        if (inProgressCount > 1) {
+            throw new Error(`Only one todo can be "in_progress" at a time. Found ${inProgressCount} in_progress todos.`);
+        }
+        if (!ctx.agent?.setTodos) {
+            const service = ctx.services?.todo;
+            if (!service) {
+                throw new Error('Todo service not enabled for this agent');
+            }
+            await service.setTodos(todos);
+            return { ok: true, count: todos.length };
+        }
+        await ctx.agent.setTodos(todos);
+        return { ok: true, count: todos.length };
+    },
+    metadata: {
+        readonly: false,
+        version: '1.0',
+    },
+});
+exports.TodoWrite.prompt = prompt_1.PROMPT;

package/dist/tools/todo_write/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "Replace the todo list managed by the agent";
+export declare const PROMPT = "Replace the agent-managed todo list with a new array of todos.\n\nGuidelines:\n- Always provide structured IDs, titles, and statuses\n- Only ONE item may have \"in_progress\" status at any time\n- IDs should be unique and descriptive\n- Titles should be clear and actionable\n\nTodo Structure:\n- id (required): Unique identifier for the todo\n- title (required): Clear description of the task\n- status (required): \"pending\" | \"in_progress\" | \"completed\"\n- assignee (optional): Who is responsible\n- notes (optional): Additional context or details\n\nSafety/Limitations:\n- This operation replaces the entire todo list\n- Previous todos not included in the new list will be removed\n- Returns error if todo service is not enabled";

package/dist/tools/todo_write/prompt.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Replace the todo list managed by the agent';
+exports.PROMPT = `Replace the agent-managed todo list with a new array of todos.
+
+Guidelines:
+- Always provide structured IDs, titles, and statuses
+- Only ONE item may have "in_progress" status at any time
+- IDs should be unique and descriptive
+- Titles should be clear and actionable
+
+Todo Structure:
+- id (required): Unique identifier for the todo
+- title (required): Clear description of the task
+- status (required): "pending" | "in_progress" | "completed"
+- assignee (optional): Who is responsible
+- notes (optional): Additional context or details
+
+Safety/Limitations:
+- This operation replaces the entire todo list
+- Previous todos not included in the new list will be removed
+- Returns error if todo service is not enabled`;

package/dist/tools/tool.d.ts

@@ -0,0 +1,43 @@
+import { ZodType } from 'zod';
+import { ToolInstance } from './registry';
+import { ToolContext } from '../core/types';
+import { Hooks } from '../core/hooks';
+/**
+ * 工具定义接口
+ */
+export interface ToolDefinition<TArgs = any, TResult = any> {
+    name: string;
+    description?: string;
+    parameters?: ZodType<TArgs>;
+    execute: (args: TArgs, ctx: EnhancedToolContext) => Promise<TResult> | TResult;
+    metadata?: {
+        version?: string;
+        tags?: string[];
+        cacheable?: boolean;
+        cacheTTL?: number;
+        timeout?: number;
+        concurrent?: boolean;
+        readonly?: boolean;
+    };
+    hooks?: Hooks;
+}
+/**
+ * 工具上下文增强接口
+ */
+export interface EnhancedToolContext extends ToolContext {
+    emit(eventType: string, data?: any): void;
+}
+/**
+ * 重载 1: tool(name, executeFn)
+ * 零配置模式，自动推断类型
+ */
+export declare function tool<TArgs = any, TResult = any>(name: string, executeFn: (args: TArgs, ctx?: EnhancedToolContext) => Promise<TResult> | TResult): ToolInstance;
+/**
+ * 重载 2: tool(definition)
+ * 完整配置模式
+ */
+export declare function tool<TArgs = any, TResult = any>(definition: ToolDefinition<TArgs, TResult>): ToolInstance;
+/**
+ * 批量定义工具
+ */
+export declare function tools(definitions: ToolDefinition[]): ToolInstance[];

package/dist/tools/tool.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tool = tool;
+exports.tools = tools;
+const zod_1 = require("zod");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const registry_1 = require("./registry");
+/**
+ * 实现
+ */
+function tool(nameOrDef, executeFn) {
+    // 解析参数
+    const def = typeof nameOrDef === 'string'
+        ? {
+            name: nameOrDef,
+            description: `Execute ${nameOrDef}`,
+            parameters: zod_1.z.any(),
+            execute: executeFn,
+        }
+        : nameOrDef;
+    // 生成 JSON Schema
+    const input_schema = def.parameters
+        ? (0, zod_to_json_schema_1.zodToJsonSchema)(def.parameters, { target: 'openApi3', $refStrategy: 'none' })
+        : { type: 'object', properties: {} };
+    // 创建工具实例
+    const toolInstance = {
+        name: def.name,
+        description: def.description || `Execute ${def.name}`,
+        input_schema,
+        hooks: def.hooks,
+        async exec(args, ctx) {
+            try {
+                // 参数验证
+                if (def.parameters) {
+                    const parseResult = def.parameters.safeParse(args);
+                    if (!parseResult.success) {
+                        return {
+                            ok: false,
+                            error: `Invalid parameters: ${parseResult.error.message}`,
+                            _validationError: true,
+                        };
+                    }
+                    args = parseResult.data;
+                }
+                // 增强上下文
+                const enhancedCtx = {
+                    ...ctx,
+                    emit(eventType, data) {
+                        ctx.agent?.events?.emitMonitor({
+                            type: 'tool_custom_event',
+                            toolName: def.name,
+                            eventType,
+                            data,
+                            callId: ctx.callId,
+                            timestamp: Date.now(),
+                        });
+                    },
+                };
+                // 执行工具
+                const result = await def.execute(args, enhancedCtx);
+                // 如果工具返回 {ok: false}，保持原样
+                if (result && typeof result === 'object' && 'ok' in result && result.ok === false) {
+                    return result;
+                }
+                // 正常结果
+                return result;
+            }
+            catch (error) {
+                // 捕获工具执行中的所有错误，统一返回格式
+                return {
+                    ok: false,
+                    error: error?.message || String(error),
+                    _thrownError: true,
+                };
+            }
+        },
+        toDescriptor() {
+            return {
+                source: 'registered',
+                name: def.name,
+                registryId: def.name,
+                metadata: {
+                    version: def.metadata?.version,
+                    tags: def.metadata?.tags,
+                    cacheable: def.metadata?.cacheable,
+                    cacheTTL: def.metadata?.cacheTTL,
+                    timeout: def.metadata?.timeout,
+                    concurrent: def.metadata?.concurrent,
+                    access: def.metadata?.readonly ? 'read' : 'write',
+                    mutates: !def.metadata?.readonly,
+                },
+            };
+        },
+    };
+    // 自动注册到全局 registry
+    registry_1.globalToolRegistry.register(def.name, () => toolInstance);
+    return toolInstance;
+}
+/**
+ * 批量定义工具
+ */
+function tools(definitions) {
+    return definitions.map((def) => tool(def));
+}