@shareai-lab/kode-sdk 2.7.1 → 2.7.2

package/dist/tools/bash_logs/index.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BashLogs = void 0;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const prompt_1 = require("./prompt");
+const bash_run_1 = require("../bash_run");
+exports.BashLogs = (0, tool_1.tool)({
+    name: 'bash_logs',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        shell_id: zod_1.z.string().describe('Shell ID from bash_run'),
+    }),
+    async execute(args) {
+        const { shell_id } = args;
+        const proc = bash_run_1.processes.get(shell_id);
+        if (!proc) {
+            return {
+                ok: false,
+                error: `Shell not found: ${shell_id}`,
+            };
+        }
+        const isRunning = proc.code === undefined;
+        const status = isRunning ? 'running' : `completed (exit code ${proc.code})`;
+        const output = [proc.stdout, proc.stderr].filter(Boolean).join('\n').trim();
+        return {
+            ok: true,
+            shell_id,
+            status,
+            running: isRunning,
+            code: proc.code,
+            output: output || '(no output yet)',
+        };
+    },
+    metadata: {
+        readonly: true,
+        version: '1.0',
+    },
+});
+exports.BashLogs.prompt = prompt_1.PROMPT;

package/dist/tools/bash_logs/prompt.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Get output from a background bash shell';
+exports.PROMPT = `Fetch stdout/stderr from a background bash session started via bash_run with "background": true.
+
+Guidelines:
+- Provide the shell_id returned by bash_run to retrieve incremental logs.
+- Check the status to see if the process is still running or completed.
+- Output includes both stdout and stderr streams.
+
+Safety/Limitations:
+- Only processes started in the current session are accessible.
+- Process history is not persisted across SDK restarts.`;

package/dist/tools/bash_run/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processes = exports.BashRun = void 0;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const type_inference_1 = require("../type-inference");
+const prompt_1 = require("./prompt");
+const processes = new Map();
+exports.processes = processes;
+exports.BashRun = (0, tool_1.tool)({
+    name: 'bash_run',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        cmd: zod_1.z.string().describe('Command to execute'),
+        timeout_ms: type_inference_1.patterns.optionalNumber('Timeout in milliseconds (default: 120000)'),
+        background: zod_1.z.boolean().optional().describe('Run in background and return shell_id'),
+    }),
+    async execute(args, ctx) {
+        const { cmd, timeout_ms = 120000, background = false } = args;
+        if (background) {
+            const id = `shell-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+            const promise = ctx.sandbox.exec(cmd, { timeoutMs: timeout_ms });
+            const proc = {
+                id,
+                cmd,
+                startTime: Date.now(),
+                promise,
+                stdout: '',
+                stderr: '',
+            };
+            processes.set(id, proc);
+            promise.then((result) => {
+                proc.code = result.code;
+                proc.stdout = result.stdout;
+                proc.stderr = result.stderr;
+            }).catch((error) => {
+                proc.code = -1;
+                proc.stderr = error?.message || String(error);
+            });
+            return {
+                background: true,
+                shell_id: id,
+                message: `Background shell started: ${id}`,
+            };
+        }
+        else {
+            const result = await ctx.sandbox.exec(cmd, { timeoutMs: timeout_ms });
+            const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+            return {
+                background: false,
+                code: result.code,
+                output: output || '(no output)',
+            };
+        }
+    },
+    metadata: {
+        readonly: false,
+        version: '1.0',
+    },
+});
+exports.BashRun.prompt = prompt_1.PROMPT;

package/dist/tools/bash_run/prompt.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Execute a bash command';
+exports.PROMPT = `Execute shell commands inside the sandbox environment.
+
+Guidelines:
+- Commands run with the sandbox's working directory and limited privileges.
+- Capture output responsibly; large outputs are truncated and saved to temp files.
+- Respect project policies: use fs_read for inspections where possible.
+- Request approval when running high-impact commands if required by policy.
+- Set "background" to true to run long-running processes and poll with bash_logs.
+
+Safety/Limitations:
+- Commands are sandboxed and cannot escape the workspace.
+- Dangerous commands may be blocked for security.
+- Timeout defaults to 120 seconds but can be configured.
+- Background processes must be explicitly killed with bash_kill.`;

package/dist/tools/builtin.js

@@ -0,0 +1,26 @@
+"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 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],
+    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.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.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.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.js

@@ -0,0 +1,40 @@
+"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,
+        });
+        const truncated = matches.length > limit;
+        const results = matches.slice(0, limit);
+        return {
+            ok: true,
+            pattern,
+            cwd: cwd || '.',
+            truncated,
+            count: matches.length,
+            matches: results,
+        };
+    },
+    metadata: {
+        readonly: true,
+        version: '1.0',
+    },
+});
+exports.FsGlob.prompt = prompt_1.PROMPT;

package/dist/tools/fs_glob/prompt.js

@@ -0,0 +1,15 @@
+"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).
+- 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.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.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.`;