kode-sdk 2.7.0

package/dist/tools/builtin.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.builtin = void 0;
+const fs_read_1 = require("./fs_read");
+const fs_write_1 = require("./fs_write");
+const fs_edit_1 = require("./fs_edit");
+const fs_glob_1 = require("./fs_glob");
+const fs_grep_1 = require("./fs_grep");
+const fs_multi_edit_1 = require("./fs_multi_edit");
+const fs_rm_1 = require("./fs_rm");
+const bash_run_1 = require("./bash_run");
+const bash_logs_1 = require("./bash_logs");
+const bash_kill_1 = require("./bash_kill");
+const todo_read_1 = require("./todo_read");
+const todo_write_1 = require("./todo_write");
+const task_run_1 = require("./task_run");
+exports.builtin = {
+    fs: () => [fs_read_1.FsRead, fs_write_1.FsWrite, fs_edit_1.FsEdit, fs_glob_1.FsGlob, fs_grep_1.FsGrep, fs_multi_edit_1.FsMultiEdit, fs_rm_1.FsRm],
+    bash: () => [bash_run_1.BashRun, bash_logs_1.BashLogs, bash_kill_1.BashKill],
+    todo: () => [todo_read_1.TodoRead, todo_write_1.TodoWrite],
+    task: (templates) => {
+        if (!templates || templates.length === 0) {
+            return null;
+        }
+        return (0, task_run_1.createTaskRunTool)(templates);
+    },
+};

package/dist/tools/define.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 简化的工具定义 API - 提供更好的开发体验
+ *
+ * 设计目标：
+ * 1. 自动从 TypeScript 类型生成 input_schema
+ * 2. 简化 metadata 为 readonly/noEffect 布尔值
+ * 3. 支持工具内发射自定义事件
+ */
+import { ToolContext } from '../core/types';
+import { ToolInstance } from './registry';
+export interface ToolAttributes {
+    /** 工具是否为只读（不修改任何状态） */
+    readonly?: boolean;
+    /** 工具是否无副作用（可安全重试） */
+    noEffect?: boolean;
+}
+export interface ParamDef {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description?: string;
+    required?: boolean;
+    default?: any;
+    enum?: any[];
+    items?: ParamDef;
+    properties?: Record<string, ParamDef>;
+}
+export interface EnhancedToolContext extends ToolContext {
+    /** 发射自定义事件（会自动添加到 monitor 通道） */
+    emit(eventType: string, data?: any): void;
+}
+export interface SimpleToolDef<TArgs = any, TResult = any> {
+    /** 工具名称 */
+    name: string;
+    /** 工具描述 */
+    description: string;
+    /** 参数定义（可选，如果提供则自动生成 schema） */
+    params?: Record<string, ParamDef>;
+    /** 或者直接提供 JSON Schema（兼容老方式） */
+    input_schema?: any;
+    /** 工具属性 */
+    attributes?: ToolAttributes;
+    /** Prompt 说明书 */
+    prompt?: string;
+    /** 执行函数 */
+    exec(args: TArgs, ctx: EnhancedToolContext): Promise<TResult> | TResult;
+}
+/**
+ * 定义工具（简化版）
+ *
+ * @example
+ * ```ts
+ * const greet = defineTool({
+ *   name: 'greet',
+ *   description: 'Greet a person',
+ *   params: {
+ *     name: { type: 'string', description: 'Person name' },
+ *     formal: { type: 'boolean', description: 'Use formal greeting', required: false }
+ *   },
+ *   attributes: { readonly: true, noEffect: true },
+ *   async exec(args, ctx) {
+ *     const greeting = args.formal ? `Good day, ${args.name}` : `Hi ${args.name}!`;
+ *
+ *     // 自定义事件
+ *     ctx.emit('greeting_sent', { name: args.name, greeting });
+ *
+ *     return { greeting };
+ *   }
+ * });
+ * ```
+ */
+export declare function defineTool<TArgs = any, TResult = any>(def: SimpleToolDef<TArgs, TResult>, options?: {
+    autoRegister?: boolean;
+}): ToolInstance;
+/**
+ * 批量定义工具
+ */
+export declare function defineTools(defs: SimpleToolDef[]): ToolInstance[];
+/**
+ * 工具装饰器（实验性 - 需要 experimentalDecorators）
+ *
+ * @example
+ * ```ts
+ * class MyTools {
+ *   @tool({
+ *     description: 'Calculate sum',
+ *     params: {
+ *       a: { type: 'number' },
+ *       b: { type: 'number' }
+ *     },
+ *     attributes: { readonly: true, noEffect: true }
+ *   })
+ *   async sum(args: { a: number; b: number }, ctx: EnhancedToolContext) {
+ *     return args.a + args.b;
+ *   }
+ * }
+ * ```
+ */
+export declare function tool(config: Omit<SimpleToolDef, 'name' | 'exec'>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * 从带装饰器的类提取所有工具
+ */
+export declare function extractTools(instance: any): ToolInstance[];

package/dist/tools/define.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * 简化的工具定义 API - 提供更好的开发体验
+ *
+ * 设计目标：
+ * 1. 自动从 TypeScript 类型生成 input_schema
+ * 2. 简化 metadata 为 readonly/noEffect 布尔值
+ * 3. 支持工具内发射自定义事件
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTool = defineTool;
+exports.defineTools = defineTools;
+exports.tool = tool;
+exports.extractTools = extractTools;
+const registry_1 = require("./registry");
+/**
+ * 从参数定义自动生成 JSON Schema
+ */
+function generateSchema(params) {
+    if (!params) {
+        return { type: 'object', properties: {} };
+    }
+    const properties = {};
+    const required = [];
+    for (const [key, def] of Object.entries(params)) {
+        const prop = { type: def.type };
+        if (def.description)
+            prop.description = def.description;
+        if (def.enum)
+            prop.enum = def.enum;
+        if (def.default !== undefined)
+            prop.default = def.default;
+        if (def.type === 'array' && def.items) {
+            prop.items = generateSchemaProp(def.items);
+        }
+        if (def.type === 'object' && def.properties) {
+            const nested = generateSchema(def.properties);
+            prop.properties = nested.properties;
+            if (nested.required?.length > 0) {
+                prop.required = nested.required;
+            }
+        }
+        properties[key] = prop;
+        if (def.required !== false) { // default required
+            required.push(key);
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+}
+function generateSchemaProp(def) {
+    const prop = { type: def.type };
+    if (def.description)
+        prop.description = def.description;
+    if (def.enum)
+        prop.enum = def.enum;
+    if (def.type === 'array' && def.items) {
+        prop.items = generateSchemaProp(def.items);
+    }
+    if (def.type === 'object' && def.properties) {
+        const nested = generateSchema(def.properties);
+        prop.properties = nested.properties;
+        if (nested.required?.length > 0) {
+            prop.required = nested.required;
+        }
+    }
+    return prop;
+}
+/**
+ * 定义工具（简化版）
+ *
+ * @example
+ * ```ts
+ * const greet = defineTool({
+ *   name: 'greet',
+ *   description: 'Greet a person',
+ *   params: {
+ *     name: { type: 'string', description: 'Person name' },
+ *     formal: { type: 'boolean', description: 'Use formal greeting', required: false }
+ *   },
+ *   attributes: { readonly: true, noEffect: true },
+ *   async exec(args, ctx) {
+ *     const greeting = args.formal ? `Good day, ${args.name}` : `Hi ${args.name}!`;
+ *
+ *     // 自定义事件
+ *     ctx.emit('greeting_sent', { name: args.name, greeting });
+ *
+ *     return { greeting };
+ *   }
+ * });
+ * ```
+ */
+function defineTool(def, options) {
+    // 自动生成 schema 或使用提供的
+    const input_schema = def.input_schema || generateSchema(def.params);
+    const toolInstance = {
+        name: def.name,
+        description: def.description,
+        input_schema,
+        prompt: def.prompt,
+        async exec(args, ctx) {
+            // 增强上下文，添加 emit 方法
+            const enhancedCtx = {
+                ...ctx,
+                emit(eventType, data) {
+                    // 发射自定义事件到 monitor 通道
+                    ctx.agent?.events?.emitMonitor({
+                        type: 'tool_custom_event',
+                        toolName: def.name,
+                        eventType,
+                        data,
+                        timestamp: Date.now(),
+                    });
+                },
+            };
+            return await def.exec(args, enhancedCtx);
+        },
+        toDescriptor() {
+            const metadata = {
+                tuned: false,
+            };
+            // 转换简化的 attributes 为内部 metadata
+            if (def.attributes?.readonly) {
+                metadata.access = 'read';
+                metadata.mutates = false;
+            }
+            else {
+                metadata.access = 'write';
+                metadata.mutates = true;
+            }
+            if (def.attributes?.noEffect !== undefined) {
+                metadata.safe = def.attributes.noEffect;
+            }
+            if (def.prompt) {
+                metadata.prompt = def.prompt;
+            }
+            return {
+                source: 'registered',
+                name: def.name,
+                registryId: def.name,
+                metadata,
+            };
+        },
+    };
+    // 自动注册到全局 registry (支持 Resume)
+    if (options?.autoRegister !== false) {
+        registry_1.globalToolRegistry.register(def.name, (_config) => {
+            // 工厂函数：根据 config 重建工具实例
+            // 注意：使用 autoRegister: false 避免重复注册
+            return defineTool(def, { autoRegister: false });
+        });
+    }
+    return toolInstance;
+}
+/**
+ * 批量定义工具
+ */
+function defineTools(defs) {
+    return defs.map((def) => defineTool(def));
+}
+/**
+ * 工具装饰器（实验性 - 需要 experimentalDecorators）
+ *
+ * @example
+ * ```ts
+ * class MyTools {
+ *   @tool({
+ *     description: 'Calculate sum',
+ *     params: {
+ *       a: { type: 'number' },
+ *       b: { type: 'number' }
+ *     },
+ *     attributes: { readonly: true, noEffect: true }
+ *   })
+ *   async sum(args: { a: number; b: number }, ctx: EnhancedToolContext) {
+ *     return args.a + args.b;
+ *   }
+ * }
+ * ```
+ */
+function tool(config) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        // 存储工具配置到类的元数据
+        if (!target.constructor._toolConfigs) {
+            target.constructor._toolConfigs = new Map();
+        }
+        target.constructor._toolConfigs.set(propertyKey, {
+            ...config,
+            name: propertyKey,
+            exec: originalMethod,
+        });
+    };
+}
+/**
+ * 从带装饰器的类提取所有工具
+ */
+function extractTools(instance) {
+    const configs = instance.constructor._toolConfigs;
+    if (!configs)
+        return [];
+    const tools = [];
+    for (const [_methodName, config] of configs) {
+        tools.push(defineTool({
+            ...config,
+            exec: config.exec.bind(instance),
+        }, { autoRegister: true } // 装饰器定义的工具也自动注册
+        ));
+    }
+    return tools;
+}

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

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

package/dist/tools/fs_edit/index.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsEdit = void 0;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const type_inference_1 = require("../type-inference");
+const prompt_1 = require("./prompt");
+exports.FsEdit = (0, tool_1.tool)({
+    name: 'fs_edit',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        path: type_inference_1.patterns.filePath('Path to file within the sandbox'),
+        old_string: zod_1.z.string().describe('String to replace'),
+        new_string: zod_1.z.string().describe('Replacement string'),
+        replace_all: zod_1.z.boolean().optional().describe('Replace all occurrences (default: false)'),
+    }),
+    async execute(args, ctx) {
+        const { path, old_string, new_string, replace_all = false } = args;
+        const content = await ctx.sandbox.fs.read(path);
+        if (replace_all) {
+            const occurrences = content.split(old_string).length - 1;
+            if (occurrences === 0) {
+                return { ok: false, error: 'old_string not found in file' };
+            }
+            const updated = content.split(old_string).join(new_string);
+            await ctx.sandbox.fs.write(path, updated);
+            await ctx.services?.filePool?.recordEdit(path);
+            return {
+                ok: true,
+                path,
+                replacements: occurrences,
+                lines: updated.split('\n').length,
+            };
+        }
+        else {
+            const occurrences = content.split(old_string).length - 1;
+            if (occurrences === 0) {
+                return { ok: false, error: 'old_string not found in file' };
+            }
+            if (occurrences > 1) {
+                return {
+                    ok: false,
+                    error: `old_string appears ${occurrences} times; set replace_all=true or provide more specific text`,
+                };
+            }
+            const updated = content.replace(old_string, new_string);
+            await ctx.sandbox.fs.write(path, updated);
+            await ctx.services?.filePool?.recordEdit(path);
+            return {
+                ok: true,
+                path,
+                replacements: 1,
+                lines: updated.split('\n').length,
+            };
+        }
+    },
+    metadata: {
+        readonly: false,
+        version: '1.0',
+    },
+});
+exports.FsEdit.prompt = prompt_1.PROMPT;

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

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "Edit a file by replacing old_string with new_string";
+export declare const PROMPT = "Use this tool for precise in-place edits.\n\nGuidelines:\n- Provide a unique \"old_string\" snippet to replace. If multiple matches exist, set \"replace_all\" to true.\n- Combine with fs_read to confirm the current file state before editing.\n- The tool integrates with FilePool to ensure the file has not changed externally.\n- If old_string is not unique, the tool will reject the operation unless replace_all is true.\n\nSafety/Limitations:\n- Single replacements require exact unique matches to avoid unintended changes.\n- Freshness validation prevents conflicts with external modifications.";

package/dist/tools/fs_edit/prompt.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Edit a file by replacing old_string with new_string';
+exports.PROMPT = `Use this tool for precise in-place edits.
+
+Guidelines:
+- Provide a unique "old_string" snippet to replace. If multiple matches exist, set "replace_all" to true.
+- Combine with fs_read to confirm the current file state before editing.
+- The tool integrates with FilePool to ensure the file has not changed externally.
+- If old_string is not unique, the tool will reject the operation unless replace_all is true.
+
+Safety/Limitations:
+- Single replacements require exact unique matches to avoid unintended changes.
+- Freshness validation prevents conflicts with external modifications.`;

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

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

package/dist/tools/fs_glob/index.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsGlob = void 0;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const type_inference_1 = require("../type-inference");
+const prompt_1 = require("./prompt");
+exports.FsGlob = (0, tool_1.tool)({
+    name: 'fs_glob',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        pattern: zod_1.z.string().describe('Glob pattern to match'),
+        cwd: type_inference_1.patterns.optionalString('Optional directory to resolve from'),
+        dot: zod_1.z.boolean().optional().describe('Include dotfiles (default: false)'),
+        limit: type_inference_1.patterns.optionalNumber('Maximum number of results (default: 200)'),
+    }),
+    async execute(args, ctx) {
+        const { pattern, cwd, dot = false, limit = 200 } = args;
+        const matches = await ctx.sandbox.fs.glob(pattern, {
+            cwd,
+            dot,
+            absolute: false,
+        });
+        // Heuristic: Next.js dynamic route segments use "[id]" which is interpreted as a glob character class.
+        // If the user/model passes patterns like "app/**/[id]/route.ts", the match set will be empty.
+        // Auto-retry with escaped brackets to improve UX.
+        let usedPattern = pattern;
+        let effectiveMatches = matches;
+        if (matches.length === 0) {
+            const escaped = escapeNextRouteSegments(pattern);
+            if (escaped !== pattern) {
+                const retry = await ctx.sandbox.fs.glob(escaped, { cwd, dot, absolute: false });
+                if (retry.length > 0) {
+                    usedPattern = escaped;
+                    effectiveMatches = retry;
+                }
+            }
+        }
+        const truncated = effectiveMatches.length > limit;
+        const results = effectiveMatches.slice(0, limit);
+        return {
+            ok: true,
+            pattern,
+            usedPattern: usedPattern === pattern ? undefined : usedPattern,
+            cwd: cwd || '.',
+            truncated,
+            count: effectiveMatches.length,
+            matches: results,
+        };
+    },
+    metadata: {
+        readonly: true,
+        version: '1.0',
+    },
+});
+exports.FsGlob.prompt = prompt_1.PROMPT;
+function escapeNextRouteSegments(pattern) {
+    // Match "[id]" style segments (letters/numbers/underscore only) and escape them as "[[]id[]]".
+    return pattern.replace(/\[([A-Za-z0-9_]+)\]/g, (_m, name) => `[[]${name}[]]`);
+}

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

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "List files matching glob patterns";
+export declare const PROMPT = "Use this tool to locate files with glob patterns (e.g. \"src/**/*.ts\").\n\nGuidelines:\n- It respects sandbox boundaries and returns relative paths by default.\n- Use standard glob syntax: * (any chars), ** (recursive directories), ? (single char).\n- Square brackets are special in glob patterns. To match a literal Next.js dynamic segment like \"[id]\", escape it:\n  - Recommended: \"[[]id[]]\" (micromatch/fast-glob compatible)\n  - Alternative: \"\\\\[id\\\\]\"\n- Set \"dot\" to true to include hidden files (starting with .).\n- Results are limited to prevent overwhelming responses.\n\nSafety/Limitations:\n- All paths are restricted to the sandbox root directory.\n- Large result sets are truncated with a warning.";

package/dist/tools/fs_glob/prompt.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'List files matching glob patterns';
+exports.PROMPT = `Use this tool to locate files with glob patterns (e.g. "src/**/*.ts").
+
+Guidelines:
+- It respects sandbox boundaries and returns relative paths by default.
+- Use standard glob syntax: * (any chars), ** (recursive directories), ? (single char).
+- Square brackets are special in glob patterns. To match a literal Next.js dynamic segment like "[id]", escape it:
+  - Recommended: "[[]id[]]" (micromatch/fast-glob compatible)
+  - Alternative: "\\\\[id\\\\]"
+- Set "dot" to true to include hidden files (starting with .).
+- Results are limited to prevent overwhelming responses.
+
+Safety/Limitations:
+- All paths are restricted to the sandbox root directory.
+- Large result sets are truncated with a warning.`;

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

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

package/dist/tools/fs_grep/index.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsGrep = void 0;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const type_inference_1 = require("../type-inference");
+const prompt_1 = require("./prompt");
+exports.FsGrep = (0, tool_1.tool)({
+    name: 'fs_grep',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        pattern: zod_1.z.string().describe('String or regular expression to search for'),
+        path: zod_1.z.string().describe('File path or glob pattern'),
+        regex: zod_1.z.boolean().optional().describe('Interpret pattern as regular expression (default: false)'),
+        case_sensitive: zod_1.z.boolean().optional().describe('Case sensitive search (default: true)'),
+        max_results: type_inference_1.patterns.optionalNumber('Maximum matches to return (default: 200)'),
+    }),
+    async execute(args, ctx) {
+        const { pattern, path, regex = false, case_sensitive = true, max_results = 200 } = args;
+        if (!pattern) {
+            return { ok: false, error: 'pattern must not be empty' };
+        }
+        const files = await ctx.sandbox.fs.glob(path, { absolute: false, dot: true });
+        const regexPattern = regex
+            ? new RegExp(pattern, case_sensitive ? 'g' : 'gi')
+            : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), case_sensitive ? 'g' : 'gi');
+        const matches = [];
+        for (const file of files) {
+            if (matches.length >= max_results)
+                break;
+            const content = await ctx.sandbox.fs.read(file);
+            const lines = content.split('\n');
+            for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+                if (matches.length >= max_results)
+                    break;
+                const line = lines[lineIndex];
+                regexPattern.lastIndex = 0;
+                let match;
+                while ((match = regexPattern.exec(line))) {
+                    matches.push({
+                        path: file,
+                        line: lineIndex + 1,
+                        column: match.index + 1,
+                        preview: line.trim().slice(0, 200),
+                    });
+                    if (matches.length >= max_results)
+                        break;
+                    if (!regex)
+                        break;
+                }
+            }
+        }
+        return {
+            ok: true,
+            pattern,
+            path,
+            matches,
+            truncated: matches.length >= max_results && files.length > 0,
+        };
+    },
+    metadata: {
+        readonly: true,
+        version: '1.0',
+    },
+});
+exports.FsGrep.prompt = prompt_1.PROMPT;

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

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "Search for text patterns inside files";
+export declare const PROMPT = "Search one or more files for a literal string or regular expression.\n\nGuidelines:\n- Use this to locate references before editing.\n- The \"path\" parameter can be a specific file or a glob pattern (e.g., \"src/**/*.ts\").\n- Set \"regex\" to true to interpret the pattern as a regular expression.\n- Case-sensitive by default; set \"case_sensitive\" to false for case-insensitive search.\n- Results include file path, line number, column number, and a preview of the match.\n\nSafety/Limitations:\n- Result sets are limited to prevent overwhelming responses.\n- Search is constrained to the sandbox directory.";

package/dist/tools/fs_grep/prompt.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Search for text patterns inside files';
+exports.PROMPT = `Search one or more files for a literal string or regular expression.
+
+Guidelines:
+- Use this to locate references before editing.
+- The "path" parameter can be a specific file or a glob pattern (e.g., "src/**/*.ts").
+- Set "regex" to true to interpret the pattern as a regular expression.
+- Case-sensitive by default; set "case_sensitive" to false for case-insensitive search.
+- Results include file path, line number, column number, and a preview of the match.
+
+Safety/Limitations:
+- Result sets are limited to prevent overwhelming responses.
+- Search is constrained to the sandbox directory.`;

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

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