@shareai-lab/kode-sdk 2.7.1 → 2.7.2

package/dist/tools/fs_multi_edit/index.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsMultiEdit = 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 editSchema = zod_1.z.object({
+    path: type_inference_1.patterns.filePath('File path'),
+    find: zod_1.z.string().describe('Existing text to replace'),
+    replace: zod_1.z.string().describe('Replacement text'),
+    replace_all: zod_1.z.boolean().optional().describe('Replace all occurrences (default: false)'),
+});
+exports.FsMultiEdit = (0, tool_1.tool)({
+    name: 'fs_multi_edit',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        edits: zod_1.z.array(editSchema).describe('List of edit operations'),
+    }),
+    async execute(args, ctx) {
+        const { edits } = args;
+        const results = [];
+        for (const edit of edits) {
+            try {
+                const freshness = await ctx.services?.filePool?.validateWrite(edit.path);
+                if (freshness && !freshness.isFresh) {
+                    results.push({
+                        path: edit.path,
+                        replacements: 0,
+                        status: 'skipped',
+                        message: 'File changed externally',
+                    });
+                    continue;
+                }
+                const content = await ctx.sandbox.fs.read(edit.path);
+                if (edit.replace_all) {
+                    const occurrences = content.split(edit.find).length - 1;
+                    if (occurrences === 0) {
+                        results.push({
+                            path: edit.path,
+                            replacements: 0,
+                            status: 'skipped',
+                            message: 'Pattern not found',
+                        });
+                        continue;
+                    }
+                    const updated = content.split(edit.find).join(edit.replace);
+                    await ctx.sandbox.fs.write(edit.path, updated);
+                    await ctx.services?.filePool?.recordEdit(edit.path);
+                    results.push({
+                        path: edit.path,
+                        replacements: occurrences,
+                        status: 'ok',
+                    });
+                }
+                else {
+                    const index = content.indexOf(edit.find);
+                    if (index === -1) {
+                        results.push({
+                            path: edit.path,
+                            replacements: 0,
+                            status: 'skipped',
+                            message: 'Pattern not found',
+                        });
+                        continue;
+                    }
+                    const occurrences = content.split(edit.find).length - 1;
+                    if (occurrences > 1) {
+                        results.push({
+                            path: edit.path,
+                            replacements: 0,
+                            status: 'skipped',
+                            message: `Pattern occurs ${occurrences} times; set replace_all=true if intended`,
+                        });
+                        continue;
+                    }
+                    const updated = content.replace(edit.find, edit.replace);
+                    await ctx.sandbox.fs.write(edit.path, updated);
+                    await ctx.services?.filePool?.recordEdit(edit.path);
+                    results.push({
+                        path: edit.path,
+                        replacements: 1,
+                        status: 'ok',
+                    });
+                }
+            }
+            catch (error) {
+                results.push({
+                    path: edit.path,
+                    replacements: 0,
+                    status: 'error',
+                    message: error?.message || String(error),
+                });
+            }
+        }
+        return {
+            ok: results.every((r) => r.status === 'ok'),
+            results,
+        };
+    },
+    metadata: {
+        readonly: false,
+        version: '1.0',
+    },
+});
+exports.FsMultiEdit.prompt = prompt_1.PROMPT;

package/dist/tools/fs_multi_edit/prompt.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Apply multiple string replacements across files';
+exports.PROMPT = `Batch apply targeted edits across files.
+
+Guidelines:
+- Each operation specifies a path and the text to replace.
+- Use fs_read to verify context beforehand.
+- All edits are applied sequentially; failures are isolated per file.
+- Each edit includes status feedback (ok, skipped, or error).
+
+Safety/Limitations:
+- Freshness validation prevents conflicts with external modifications.
+- Failed edits are reported but don't halt the batch.
+- Non-unique patterns require explicit replace_all flag.`;

package/dist/tools/fs_read/index.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsRead = 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.FsRead = (0, tool_1.tool)({
+    name: 'fs_read',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        path: type_inference_1.patterns.filePath('Path to file relative to sandbox root'),
+        offset: type_inference_1.patterns.optionalNumber('Line offset (1-indexed)'),
+        limit: type_inference_1.patterns.optionalNumber('Max lines to read'),
+    }),
+    async execute(args, ctx) {
+        const { path, offset, limit } = args;
+        const content = await ctx.sandbox.fs.read(path);
+        const lines = content.split('\n');
+        const startLine = offset ? offset - 1 : 0;
+        const endLine = limit ? startLine + limit : lines.length;
+        const selected = lines.slice(startLine, endLine);
+        await ctx.services?.filePool?.recordRead(path);
+        const truncated = endLine < lines.length;
+        const result = selected.join('\n');
+        return {
+            path,
+            offset: startLine + 1,
+            limit: selected.length,
+            truncated,
+            totalLines: lines.length,
+            content: result,
+        };
+    },
+    metadata: {
+        readonly: true,
+        version: '1.0',
+    },
+});
+exports.FsRead.prompt = prompt_1.PROMPT;

package/dist/tools/fs_read/prompt.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Read contents from a file';
+exports.PROMPT = `Use this tool to inspect files within the sandboxed workspace.
+
+Usage guidance:
+- Always pass paths relative to the sandbox working directory.
+- You may optionally provide "offset" and "limit" to control the slice of lines to inspect.
+- Large files will be truncated to keep responses compact; request additional ranges if needed.
+- Prefer batching adjacent reads in a single turn to minimize context churn.
+
+Safety/Limitations:
+- This tool is read-only and integrates with FilePool for conflict detection.
+- File modifications are tracked to warn about stale reads.
+- Paths must stay inside the sandbox root directory.`;

package/dist/tools/fs_write/index.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsWrite = 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.FsWrite = (0, tool_1.tool)({
+    name: 'fs_write',
+    description: prompt_1.DESCRIPTION,
+    parameters: zod_1.z.object({
+        path: type_inference_1.patterns.filePath('Path to file within the sandbox'),
+        content: zod_1.z.string().describe('Content to write'),
+    }),
+    async execute(args, ctx) {
+        const { path, content } = args;
+        const freshness = await ctx.services?.filePool?.validateWrite(path);
+        if (freshness && !freshness.isFresh) {
+            return {
+                ok: false,
+                error: 'File appears to have changed externally. Please read it again before writing.',
+            };
+        }
+        await ctx.sandbox.fs.write(path, content);
+        await ctx.services?.filePool?.recordEdit(path);
+        const bytes = Buffer.byteLength(content, 'utf8');
+        const lines = content.split('\n').length;
+        return {
+            ok: true,
+            path,
+            bytes,
+            lines,
+        };
+    },
+    metadata: {
+        readonly: false,
+        version: '1.0',
+    },
+});
+exports.FsWrite.prompt = prompt_1.PROMPT;

package/dist/tools/fs_write/prompt.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Write contents to a file (creates or overwrites)';
+exports.PROMPT = `Use this tool to create or overwrite files inside the sandbox.
+
+Guidelines:
+- Paths must stay inside the sandbox root. The SDK will deny attempts to escape the workspace.
+- Provide the full target contents. The previous file body will be replaced.
+- Pair with fs_read when editing existing files so the FilePool can validate freshness.
+- The tool returns the number of bytes written for auditing purposes.
+
+Safety/Limitations:
+- File freshness validation ensures you don't overwrite externally modified files.
+- Large file writes are allowed but may impact performance.`;

package/dist/tools/index.js

@@ -0,0 +1,61 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createScriptsTool = exports.createSkillsTool = exports.builtin = exports.globalToolRegistry = exports.ToolRegistry = exports.disconnectAllMCP = exports.disconnectMCP = exports.getMCPTools = exports.extractTools = exports.defineTools = exports.defineTool = exports.tools = exports.tool = void 0;
+// 统一的工具定义 API (v2.0 推荐)
+var tool_1 = require("./tool");
+Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return tool_1.tool; } });
+Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tool_1.tools; } });
+// 简化的工具定义 API (保留兼容)
+var define_1 = require("./define");
+Object.defineProperty(exports, "defineTool", { enumerable: true, get: function () { return define_1.defineTool; } });
+Object.defineProperty(exports, "defineTools", { enumerable: true, get: function () { return define_1.defineTools; } });
+Object.defineProperty(exports, "extractTools", { enumerable: true, get: function () { return define_1.extractTools; } });
+// MCP 集成
+var mcp_1 = require("./mcp");
+Object.defineProperty(exports, "getMCPTools", { enumerable: true, get: function () { return mcp_1.getMCPTools; } });
+Object.defineProperty(exports, "disconnectMCP", { enumerable: true, get: function () { return mcp_1.disconnectMCP; } });
+Object.defineProperty(exports, "disconnectAllMCP", { enumerable: true, get: function () { return mcp_1.disconnectAllMCP; } });
+// 工具注册表
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return registry_1.ToolRegistry; } });
+Object.defineProperty(exports, "globalToolRegistry", { enumerable: true, get: function () { return registry_1.globalToolRegistry; } });
+// 内置工具
+exports.builtin = __importStar(require("./builtin"));
+// Skills 工具
+var skills_1 = require("./skills");
+Object.defineProperty(exports, "createSkillsTool", { enumerable: true, get: function () { return skills_1.createSkillsTool; } });
+var scripts_1 = require("./scripts");
+Object.defineProperty(exports, "createScriptsTool", { enumerable: true, get: function () { return scripts_1.createScriptsTool; } });

package/dist/tools/mcp.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMCPTools = getMCPTools;
+exports.disconnectMCP = disconnectMCP;
+exports.disconnectAllMCP = disconnectAllMCP;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const registry_1 = require("./registry");
+/**
+ * MCP Client 管理器
+ *
+ * 维护 MCP 客户端连接，支持多种传输方式
+ */
+class MCPClientManager {
+    constructor() {
+        this.clients = new Map();
+        this.transports = new Map();
+    }
+    async connect(serverName, config) {
+        // 如果已连接，返回现有客户端
+        if (this.clients.has(serverName)) {
+            return this.clients.get(serverName);
+        }
+        // 创建 transport
+        let transport;
+        if (config.transport === 'stdio') {
+            if (!config.command) {
+                throw new Error('command is required for stdio transport');
+            }
+            transport = new stdio_js_1.StdioClientTransport({
+                command: config.command,
+                args: config.args || [],
+                env: config.env,
+            });
+        }
+        else if (config.transport === 'sse' || config.transport === 'http') {
+            if (!config.url) {
+                throw new Error('url is required for sse/http transport');
+            }
+            transport = new sse_js_1.SSEClientTransport(new URL(config.url));
+        }
+        else {
+            throw new Error(`Unsupported transport type: ${config.transport}`);
+        }
+        // 创建客户端
+        const client = new index_js_1.Client({
+            name: 'kode-sdk',
+            version: '2.0.0',
+        }, {
+            capabilities: {},
+        });
+        // 连接
+        await client.connect(transport);
+        // 缓存
+        this.clients.set(serverName, client);
+        this.transports.set(serverName, transport);
+        return client;
+    }
+    async disconnect(serverName) {
+        const client = this.clients.get(serverName);
+        if (client) {
+            await client.close();
+            this.clients.delete(serverName);
+        }
+        const transport = this.transports.get(serverName);
+        if (transport) {
+            await transport.close();
+            this.transports.delete(serverName);
+        }
+    }
+    async disconnectAll() {
+        const servers = Array.from(this.clients.keys());
+        await Promise.all(servers.map((name) => this.disconnect(name)));
+    }
+    getClient(serverName) {
+        return this.clients.get(serverName);
+    }
+}
+const mcpManager = new MCPClientManager();
+/**
+ * 获取 MCP 工具
+ *
+ * 连接到 MCP 服务器并将其工具转换为 ToolInstance[]
+ *
+ * @example
+ * ```ts
+ * // Stdio transport
+ * const tools = await getMCPTools({
+ *   transport: 'stdio',
+ *   command: 'uvx',
+ *   args: ['mcp-server-git'],
+ *   serverName: 'git'
+ * });
+ *
+ * // HTTP/SSE transport
+ * const tools = await getMCPTools({
+ *   transport: 'sse',
+ *   url: 'http://localhost:3000/mcp',
+ *   serverName: 'company',
+ *   include: ['search', 'summarize']
+ * });
+ * ```
+ */
+async function getMCPTools(config) {
+    const serverName = config.serverName || 'default';
+    // 连接到 MCP 服务器
+    const client = await mcpManager.connect(serverName, config);
+    // 列出可用工具
+    const toolsResponse = await client.listTools();
+    const mcpTools = toolsResponse.tools;
+    // 过滤工具
+    let filtered = mcpTools;
+    if (config.include) {
+        filtered = filtered.filter((tool) => config.include.includes(tool.name));
+    }
+    if (config.exclude) {
+        filtered = filtered.filter((tool) => !config.exclude.includes(tool.name));
+    }
+    // 转换为 ToolInstance[]
+    const toolInstances = filtered.map((mcpTool) => {
+        // 生成命名空间化的工具名：mcp__serverName__toolName
+        const toolName = `mcp__${serverName}__${mcpTool.name}`;
+        const toolInstance = {
+            name: toolName,
+            description: mcpTool.description || `MCP tool: ${mcpTool.name}`,
+            input_schema: mcpTool.inputSchema,
+            async exec(args, _ctx) {
+                try {
+                    // 调用 MCP 工具
+                    const result = await client.callTool({
+                        name: mcpTool.name,
+                        arguments: args,
+                    });
+                    // 返回结果
+                    return {
+                        content: result.content,
+                        isError: result.isError,
+                    };
+                }
+                catch (error) {
+                    throw new Error(`MCP tool execution failed: ${error}`);
+                }
+            },
+            toDescriptor() {
+                return {
+                    source: 'mcp',
+                    name: toolName,
+                    registryId: toolName,
+                    metadata: {
+                        mcpServer: serverName,
+                        mcpToolName: mcpTool.name,
+                        transport: config.transport,
+                    },
+                    config: {
+                        serverName,
+                        transport: config.transport,
+                        url: config.url,
+                        command: config.command,
+                        args: config.args,
+                    },
+                };
+            },
+        };
+        // 自动注册到 global registry（支持 Resume）
+        registry_1.globalToolRegistry.register(toolName, (_registryConfig) => {
+            // Resume 时重建 MCP 连接
+            return toolInstance;
+        });
+        return toolInstance;
+    });
+    return toolInstances;
+}
+/**
+ * 断开 MCP 服务器连接
+ */
+async function disconnectMCP(serverName) {
+    await mcpManager.disconnect(serverName);
+}
+/**
+ * 断开所有 MCP 服务器连接
+ */
+async function disconnectAllMCP() {
+    await mcpManager.disconnectAll();
+}

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();