@shareai-lab/kode-sdk 1.0.0-beta.9 → 2.7.0

package/dist/tools/task_run/prompt.js

@@ -0,0 +1,25 @@
+"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.
+
+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,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tool = tool;
+exports.tools = tools;
+const zod_1 = require("zod");
+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 (使用 Zod v4 原生方法)
+    let input_schema;
+    if (def.parameters) {
+        // Zod v4: 使用 zodToJsonSchema 的替代方案
+        // 由于 zod-to-json-schema 已被弃用，我们需要手动转换 Zod schema 为 JSON Schema
+        input_schema = zodToJsonSchemaManual(def.parameters);
+    }
+    else {
+        input_schema = { 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,
+                            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));
+}
+/**
+ * 手动转换 Zod Schema 为 JSON Schema (替代已弃用的 zod-to-json-schema)
+ *
+ * 设计原则：
+ * - 简洁：只处理工具定义中常用的 Zod 类型
+ * - 健壮：对于不支持的类型，返回默认的 object schema
+ * - 可扩展：可以根据需要添加更多类型的支持
+ */
+function zodToJsonSchemaManual(zodType) {
+    // 处理 ZodEffects 类型（经过 .transform()、.refine() 等转换的 schema）
+    const typeName = zodType._def?.typeName;
+    if (typeName === 'ZodEffects' || (typeof typeName === 'string' && typeName.includes('ZodEffects'))) {
+        const innerSchema = zodType._def.schema;
+        if (innerSchema) {
+            return zodToJsonSchemaManual(innerSchema);
+        }
+        return { type: 'object', properties: {}, required: [] };
+    }
+    // 如果是 ZodObject
+    if (zodType instanceof zod_1.z.ZodObject) {
+        // Zod v4: shape 是属性而非方法
+        const shape = zodType.shape || zodType._def.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            const fieldSchema = convertZodType(value);
+            properties[key] = fieldSchema;
+            // 检查是否可选
+            const isOptional = isZodTypeOptional(value);
+            if (!isOptional) {
+                required.push(key);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required,
+        };
+    }
+    // 默认返回空对象
+    return {
+        type: 'object',
+        properties: {},
+        required: [],
+    };
+}
+/**
+ * 转换 Zod 类型为 JSON Schema 类型
+ */
+function convertZodType(zodType) {
+    // 处理可选类型
+    if (zodType instanceof zod_1.z.ZodOptional) {
+        const innerType = zodType._def.innerType;
+        return convertZodType(innerType);
+    }
+    // 处理默认值类型
+    if (zodType instanceof zod_1.z.ZodDefault) {
+        const innerType = zodType._def.innerType;
+        return convertZodType(innerType);
+    }
+    // 基本类型映射
+    if (zodType instanceof zod_1.z.ZodString) {
+        return { type: 'string' };
+    }
+    if (zodType instanceof zod_1.z.ZodNumber) {
+        return { type: 'number' };
+    }
+    if (zodType instanceof zod_1.z.ZodBoolean) {
+        return { type: 'boolean' };
+    }
+    if (zodType instanceof zod_1.z.ZodArray) {
+        const elementType = zodType._def.type;
+        return {
+            type: 'array',
+            items: convertZodType(elementType),
+        };
+    }
+    if (zodType instanceof zod_1.z.ZodObject) {
+        return zodToJsonSchemaManual(zodType);
+    }
+    if (zodType instanceof zod_1.z.ZodEnum) {
+        return {
+            type: 'string',
+            enum: zodType._def.values,
+        };
+    }
+    if (zodType instanceof zod_1.z.ZodLiteral) {
+        return {
+            type: typeof zodType._def.value,
+            const: zodType._def.value,
+        };
+    }
+    // 未知类型，默认为 object（避免意外返回 string）
+    return { type: 'object', properties: {}, required: [] };
+}
+/**
+ * 检查 Zod 类型是否可选
+ */
+function isZodTypeOptional(zodType) {
+    return (zodType instanceof zod_1.z.ZodOptional ||
+        zodType instanceof zod_1.z.ZodDefault ||
+        zodType.isNullable?.() === true);
+}

package/dist/tools/toolkit.d.ts

@@ -0,0 +1,69 @@
+import { ZodType } from 'zod';
+import type { ToolInstance } from '../index';
+/**
+ * ToolKit 装饰器元数据
+ */
+interface ToolMethodMetadata {
+    description?: string;
+    parameters?: ZodType;
+    metadata?: any;
+}
+/**
+ * 工具方法装饰器
+ *
+ * @example
+ * ```ts
+ * class WeatherKit extends ToolKit {
+ *   @toolMethod({ description: 'Get current weather' })
+ *   async getWeather(args: { city: string }, ctx: ToolContext) {
+ *     return { temperature: 25, city: args.city };
+ *   }
+ * }
+ * ```
+ */
+export declare function toolMethod(metadata?: ToolMethodMetadata): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * ToolKit 基类
+ *
+ * 提供组织化的工具定义方式
+ *
+ * @example
+ * ```ts
+ * class DatabaseKit extends ToolKit {
+ *   constructor(private db: Database) {
+ *     super('db');
+ *   }
+ *
+ *   @toolMethod({
+ *     description: 'Query database',
+ *     parameters: z.object({ query: z.string() })
+ *   })
+ *   async query(args: { query: string }, ctx: ToolContext) {
+ *     return await this.db.query(args.query);
+ *   }
+ *
+ *   @toolMethod({ description: 'Insert record' })
+ *   async insert(args: { table: string; data: any }, ctx: ToolContext) {
+ *     return await this.db.insert(args.table, args.data);
+ *   }
+ * }
+ *
+ * // 使用
+ * const dbKit = new DatabaseKit(myDatabase);
+ * const tools = dbKit.getTools();
+ * // 返回: [db__query, db__insert]
+ * ```
+ */
+export declare class ToolKit {
+    private readonly namespace?;
+    constructor(namespace?: string | undefined);
+    /**
+     * 获取所有工具实例
+     */
+    getTools(): ToolInstance[];
+    /**
+     * 获取工具名称列表
+     */
+    getToolNames(): string[];
+}
+export {};

package/dist/tools/toolkit.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolKit = void 0;
+exports.toolMethod = toolMethod;
+const zod_1 = require("zod");
+const tool_1 = require("./tool");
+/**
+ * 工具方法装饰器
+ *
+ * @example
+ * ```ts
+ * class WeatherKit extends ToolKit {
+ *   @toolMethod({ description: 'Get current weather' })
+ *   async getWeather(args: { city: string }, ctx: ToolContext) {
+ *     return { temperature: 25, city: args.city };
+ *   }
+ * }
+ * ```
+ */
+function toolMethod(metadata = {}) {
+    return function (target, propertyKey, descriptor) {
+        // 存储元数据到类的原型
+        if (!target.constructor._toolMethods) {
+            target.constructor._toolMethods = new Map();
+        }
+        target.constructor._toolMethods.set(propertyKey, {
+            ...metadata,
+            method: descriptor.value,
+        });
+    };
+}
+/**
+ * ToolKit 基类
+ *
+ * 提供组织化的工具定义方式
+ *
+ * @example
+ * ```ts
+ * class DatabaseKit extends ToolKit {
+ *   constructor(private db: Database) {
+ *     super('db');
+ *   }
+ *
+ *   @toolMethod({
+ *     description: 'Query database',
+ *     parameters: z.object({ query: z.string() })
+ *   })
+ *   async query(args: { query: string }, ctx: ToolContext) {
+ *     return await this.db.query(args.query);
+ *   }
+ *
+ *   @toolMethod({ description: 'Insert record' })
+ *   async insert(args: { table: string; data: any }, ctx: ToolContext) {
+ *     return await this.db.insert(args.table, args.data);
+ *   }
+ * }
+ *
+ * // 使用
+ * const dbKit = new DatabaseKit(myDatabase);
+ * const tools = dbKit.getTools();
+ * // 返回: [db__query, db__insert]
+ * ```
+ */
+class ToolKit {
+    constructor(namespace) {
+        this.namespace = namespace;
+    }
+    /**
+     * 获取所有工具实例
+     */
+    getTools() {
+        const constructor = this.constructor;
+        const toolMethods = constructor._toolMethods;
+        if (!toolMethods) {
+            return [];
+        }
+        const tools = [];
+        for (const [methodName, metadata] of toolMethods) {
+            const toolName = this.namespace ? `${this.namespace}__${methodName}` : methodName;
+            const def = {
+                name: toolName,
+                description: metadata.description || `Execute ${methodName}`,
+                parameters: metadata.parameters || zod_1.z.any(),
+                execute: metadata.method.bind(this),
+                metadata: metadata.metadata,
+            };
+            tools.push((0, tool_1.tool)(def));
+        }
+        return tools;
+    }
+    /**
+     * 获取工具名称列表
+     */
+    getToolNames() {
+        return this.getTools().map((t) => t.name);
+    }
+}
+exports.ToolKit = ToolKit;