kode-sdk 2.7.0

package/dist/skills/parser.d.ts

@@ -0,0 +1,40 @@
+import { SkillMetadata, SkillParseResult } from './types';
+/**
+ * SKILL.md 文件解析器
+ *
+ * 解析包含 YAML frontmatter 和 Markdown 正文的 SKILL.md 文件
+ */
+export declare class SkillsParser {
+    /**
+     * 解析 SKILL.md 文件内容
+     *
+     * @param content - SKILL.md 文件的完整内容
+     * @returns 解析后的元数据和正文
+     * @throws 如果格式无效
+     *
+     * @example
+     * ```typescript
+     * const parser = new SkillsParser();
+     * const result = parser.parse(`---
+     * name: my-skill
+     * description: A helpful skill
+     * ---
+     *
+     * # My Skill
+     *
+     * Instructions here...
+     * `);
+     * console.log(result.metadata.name); // 'my-skill'
+     * console.log(result.body); // '# My Skill\n\nInstructions here...'
+     * ```
+     */
+    parse(content: string): SkillParseResult;
+    /**
+     * 检查内容是否是有效的 SKILL.md 格式（不抛出异常）
+     */
+    isValid(content: string): boolean;
+    /**
+     * 仅提取元数据（不解析完整正文，用于快速发现）
+     */
+    parseMetadataOnly(content: string): SkillMetadata;
+}

package/dist/skills/parser.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillsParser = void 0;
+const js_yaml_1 = __importDefault(require("js-yaml"));
+/**
+ * SKILL.md 文件解析器
+ *
+ * 解析包含 YAML frontmatter 和 Markdown 正文的 SKILL.md 文件
+ */
+class SkillsParser {
+    /**
+     * 解析 SKILL.md 文件内容
+     *
+     * @param content - SKILL.md 文件的完整内容
+     * @returns 解析后的元数据和正文
+     * @throws 如果格式无效
+     *
+     * @example
+     * ```typescript
+     * const parser = new SkillsParser();
+     * const result = parser.parse(`---
+     * name: my-skill
+     * description: A helpful skill
+     * ---
+     *
+     * # My Skill
+     *
+     * Instructions here...
+     * `);
+     * console.log(result.metadata.name); // 'my-skill'
+     * console.log(result.body); // '# My Skill\n\nInstructions here...'
+     * ```
+     */
+    parse(content) {
+        // 匹配 YAML frontmatter: ---\n...\n---\n
+        const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+        const match = content.match(frontmatterRegex);
+        if (!match) {
+            throw new Error('Invalid SKILL.md format: missing YAML frontmatter. ' +
+                'File must start with --- followed by YAML content and another ---');
+        }
+        const [, frontmatterYaml, body] = match;
+        let frontmatter;
+        try {
+            frontmatter = js_yaml_1.default.load(frontmatterYaml);
+        }
+        catch (error) {
+            throw new Error(`Invalid YAML frontmatter: ${error.message}`);
+        }
+        if (!frontmatter || typeof frontmatter !== 'object') {
+            throw new Error('Invalid YAML frontmatter: must be an object');
+        }
+        // 验证必需字段
+        if (!frontmatter.name || typeof frontmatter.name !== 'string') {
+            throw new Error('Invalid SKILL.md: missing or invalid "name" field');
+        }
+        if (!frontmatter.description || typeof frontmatter.description !== 'string') {
+            throw new Error('Invalid SKILL.md: missing or invalid "description" field');
+        }
+        // 解析 allowed-tools（支持字符串和数组格式）
+        let allowedTools;
+        if (frontmatter['allowed-tools']) {
+            const raw = frontmatter['allowed-tools'];
+            if (typeof raw === 'string') {
+                // 解析空格分隔的工具列表，如 "Bash(git:*) Bash(jq:*) Read"
+                allowedTools = raw.split(/\s+/).filter(Boolean);
+            }
+            else if (Array.isArray(raw)) {
+                allowedTools = raw.map(String);
+            }
+        }
+        const metadata = {
+            name: frontmatter.name,
+            description: frontmatter.description,
+            license: frontmatter.license,
+            compatibility: frontmatter.compatibility,
+            allowedTools,
+            metadata: frontmatter.metadata,
+        };
+        return {
+            metadata,
+            body: body.trim(),
+        };
+    }
+    /**
+     * 检查内容是否是有效的 SKILL.md 格式（不抛出异常）
+     */
+    isValid(content) {
+        try {
+            this.parse(content);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 仅提取元数据（不解析完整正文，用于快速发现）
+     */
+    parseMetadataOnly(content) {
+        return this.parse(content).metadata;
+    }
+}
+exports.SkillsParser = SkillsParser;

package/dist/skills/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Agent Skills 类型定义
+ *
+ * 基于 Agent Skills 开放标准 (https://agentskills.io)
+ */
+/**
+ * SKILL.md frontmatter 元数据
+ */
+export interface SkillMetadata {
+    /** 技能名称，必需，1-64 字符，kebab-case 格式 */
+    name: string;
+    /** 技能描述，必需，1-1024 字符 */
+    description: string;
+    /** 许可证，如 "Apache-2.0" */
+    license?: string;
+    /** 兼容性说明，如 "claude-3.5-sonnet, gpt-4" */
+    compatibility?: string;
+    /** 允许使用的工具列表 */
+    allowedTools?: string[];
+    /** 自定义元数据 */
+    metadata?: Record<string, any>;
+}
+/**
+ * Skill 资源目录
+ */
+export interface SkillResources {
+    /** 可执行脚本文件列表 */
+    scripts?: string[];
+    /** 参考文档列表 */
+    references?: string[];
+    /** 资源文件列表（模板、图标等） */
+    assets?: string[];
+}
+/**
+ * 完整 Skill 定义
+ */
+export interface Skill extends SkillMetadata {
+    /** Skill 目录绝对路径 */
+    path: string;
+    /** SKILL.md Markdown 内容（激活后加载） */
+    body?: string;
+    /** 资源目录内容 */
+    resources?: SkillResources;
+    /** 解析时间戳 */
+    loadedAt?: number;
+    /** 激活时间戳 */
+    activatedAt?: number;
+}
+/**
+ * Skills 配置
+ */
+export interface SkillsConfig {
+    /** Skills 搜索路径列表 */
+    paths: string[];
+    /** 白名单：只加载这些 Skills */
+    include?: string[];
+    /** 黑名单：排除这些 Skills */
+    exclude?: string[];
+    /** 可信来源：允许执行脚本的 Skills */
+    trusted?: string[];
+    /** 是否在加载时验证格式 */
+    validateOnLoad?: boolean;
+}
+/**
+ * Skill 激活记录
+ */
+export interface SkillActivation {
+    /** Skill 名称 */
+    name: string;
+    /** 激活时间戳 */
+    activatedAt: number;
+    /** 激活来源 */
+    activatedBy: 'auto' | 'agent' | 'user';
+    /** 被授权的工具列表 */
+    toolsGranted?: string[];
+}
+/**
+ * Skills 运行时状态（用于持久化）
+ */
+export interface SkillsState {
+    /** 已发现的 Skill 名称列表 */
+    discovered: string[];
+    /** 已激活的 Skills */
+    activated: SkillActivation[];
+    /** 最后发现时间 */
+    lastDiscoveryAt: number;
+}
+/**
+ * Skill 解析结果
+ */
+export interface SkillParseResult {
+    /** 元数据 */
+    metadata: SkillMetadata;
+    /** Markdown 正文 */
+    body: string;
+}
+/**
+ * Skill 验证结果
+ */
+export interface SkillValidationResult {
+    /** 是否有效 */
+    valid: boolean;
+    /** 错误列表 */
+    errors: string[];
+    /** 警告列表 */
+    warnings?: string[];
+}

package/dist/skills/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Agent Skills 类型定义
+ *
+ * 基于 Agent Skills 开放标准 (https://agentskills.io)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/skills/validator.d.ts

@@ -0,0 +1,30 @@
+import { SkillMetadata, SkillValidationResult, Skill } from './types';
+/**
+ * Skill 格式验证器
+ *
+ * 根据 Agent Skills 规范验证 Skill 的格式和内容
+ */
+export declare class SkillsValidator {
+    /** name 字段的正则表达式：kebab-case，1-64 字符 */
+    private static readonly NAME_PATTERN;
+    /** name 最大长度 */
+    private static readonly NAME_MAX_LENGTH;
+    /** description 最大长度 */
+    private static readonly DESCRIPTION_MAX_LENGTH;
+    /**
+     * 验证 Skill 元数据
+     */
+    validate(skill: Partial<SkillMetadata>): SkillValidationResult;
+    /**
+     * 验证完整 Skill（包括路径）
+     */
+    validateFull(skill: Partial<Skill>): SkillValidationResult;
+    /**
+     * 验证 Skill 名称是否与目录名匹配
+     */
+    validateNameMatchesDirectory(skillName: string, directoryPath: string): boolean;
+    /**
+     * 快速检查是否有效
+     */
+    isValid(skill: Partial<SkillMetadata>): boolean;
+}

package/dist/skills/validator.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillsValidator = void 0;
+/**
+ * Skill 格式验证器
+ *
+ * 根据 Agent Skills 规范验证 Skill 的格式和内容
+ */
+class SkillsValidator {
+    /**
+     * 验证 Skill 元数据
+     */
+    validate(skill) {
+        const errors = [];
+        const warnings = [];
+        // 验证 name
+        if (!skill.name) {
+            errors.push('Missing required field: name');
+        }
+        else {
+            if (typeof skill.name !== 'string') {
+                errors.push('Field "name" must be a string');
+            }
+            else {
+                if (skill.name.length > SkillsValidator.NAME_MAX_LENGTH) {
+                    errors.push(`Field "name" exceeds maximum length of ${SkillsValidator.NAME_MAX_LENGTH} characters`);
+                }
+                if (!SkillsValidator.NAME_PATTERN.test(skill.name)) {
+                    errors.push('Field "name" must be kebab-case (lowercase alphanumeric with hyphens, ' +
+                        'e.g., "my-skill-name"). Cannot start or end with hyphen.');
+                }
+            }
+        }
+        // 验证 description
+        if (!skill.description) {
+            errors.push('Missing required field: description');
+        }
+        else {
+            if (typeof skill.description !== 'string') {
+                errors.push('Field "description" must be a string');
+            }
+            else {
+                if (skill.description.length === 0) {
+                    errors.push('Field "description" cannot be empty');
+                }
+                if (skill.description.length > SkillsValidator.DESCRIPTION_MAX_LENGTH) {
+                    errors.push(`Field "description" exceeds maximum length of ${SkillsValidator.DESCRIPTION_MAX_LENGTH} characters`);
+                }
+            }
+        }
+        // 验证可选字段
+        if (skill.license !== undefined && typeof skill.license !== 'string') {
+            errors.push('Field "license" must be a string');
+        }
+        if (skill.compatibility !== undefined && typeof skill.compatibility !== 'string') {
+            errors.push('Field "compatibility" must be a string');
+        }
+        if (skill.allowedTools !== undefined) {
+            if (!Array.isArray(skill.allowedTools)) {
+                errors.push('Field "allowedTools" must be an array of strings');
+            }
+            else {
+                for (let i = 0; i < skill.allowedTools.length; i++) {
+                    if (typeof skill.allowedTools[i] !== 'string') {
+                        errors.push(`Field "allowedTools[${i}]" must be a string`);
+                    }
+                }
+            }
+        }
+        if (skill.metadata !== undefined) {
+            if (typeof skill.metadata !== 'object' || skill.metadata === null || Array.isArray(skill.metadata)) {
+                errors.push('Field "metadata" must be an object');
+            }
+        }
+        // 警告：描述过短
+        if (skill.description && skill.description.length < 20) {
+            warnings.push('Description is very short. Consider providing more detail for better skill matching.');
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    /**
+     * 验证完整 Skill（包括路径）
+     */
+    validateFull(skill) {
+        const baseResult = this.validate(skill);
+        if (!skill.path) {
+            baseResult.errors.push('Missing required field: path');
+            baseResult.valid = false;
+        }
+        else if (typeof skill.path !== 'string') {
+            baseResult.errors.push('Field "path" must be a string');
+            baseResult.valid = false;
+        }
+        return baseResult;
+    }
+    /**
+     * 验证 Skill 名称是否与目录名匹配
+     */
+    validateNameMatchesDirectory(skillName, directoryPath) {
+        const path = require('path');
+        const dirName = path.basename(directoryPath);
+        return skillName === dirName;
+    }
+    /**
+     * 快速检查是否有效
+     */
+    isValid(skill) {
+        return this.validate(skill).valid;
+    }
+}
+exports.SkillsValidator = SkillsValidator;
+/** name 字段的正则表达式：kebab-case，1-64 字符 */
+SkillsValidator.NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** name 最大长度 */
+SkillsValidator.NAME_MAX_LENGTH = 64;
+/** description 最大长度 */
+SkillsValidator.DESCRIPTION_MAX_LENGTH = 1024;

package/dist/store.d.ts

@@ -0,0 +1 @@
+export { Store, JSONStore, HistoryWindow, CompressionRecord, RecoveredFile, } from './infra/store';

package/dist/store.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSONStore = void 0;
+var store_1 = require("./infra/store");
+Object.defineProperty(exports, "JSONStore", { enumerable: true, get: function () { return store_1.JSONStore; } });

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

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

package/dist/tools/bash_kill/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BashKill = 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.BashKill = (0, tool_1.tool)({
+    name: 'bash_kill',
+    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}`,
+            };
+        }
+        bash_run_1.processes.delete(shell_id);
+        return {
+            ok: true,
+            shell_id,
+            message: `Killed shell ${shell_id}`,
+        };
+    },
+    metadata: {
+        readonly: false,
+        version: '1.0',
+    },
+});
+exports.BashKill.prompt = prompt_1.PROMPT;

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

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "Kill a background bash shell";
+export declare const PROMPT = "Terminate a long-running background bash session identified by shell_id.\n\nGuidelines:\n- Use this to clean up stuck processes.\n- Provide the shell_id from bash_run to terminate that specific process.\n- Once killed, the process cannot be restarted or accessed.\n\nSafety/Limitations:\n- Only background processes started in the current session can be killed.\n- Force termination may leave incomplete work or locks.";

package/dist/tools/bash_kill/prompt.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT = exports.DESCRIPTION = void 0;
+exports.DESCRIPTION = 'Kill a background bash shell';
+exports.PROMPT = `Terminate a long-running background bash session identified by shell_id.
+
+Guidelines:
+- Use this to clean up stuck processes.
+- Provide the shell_id from bash_run to terminate that specific process.
+- Once killed, the process cannot be restarted or accessed.
+
+Safety/Limitations:
+- Only background processes started in the current session can be killed.
+- Force termination may leave incomplete work or locks.`;

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

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

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.d.ts

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "Get output from a background bash shell";
+export declare const PROMPT = "Fetch stdout/stderr from a background bash session started via bash_run with \"background\": true.\n\nGuidelines:\n- Provide the shell_id returned by bash_run to retrieve incremental logs.\n- Check the status to see if the process is still running or completed.\n- Output includes both stdout and stderr streams.\n\nSafety/Limitations:\n- Only processes started in the current session are accessible.\n- Process history is not persisted across SDK restarts.";

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.d.ts

@@ -0,0 +1,16 @@
+interface BashProcess {
+    id: string;
+    cmd: string;
+    startTime: number;
+    promise: Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    stdout: string;
+    stderr: string;
+    code?: number;
+}
+declare const processes: Map<string, BashProcess>;
+export declare const BashRun: import("..").ToolInstance;
+export { processes };

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.d.ts

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

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.d.ts

@@ -0,0 +1,9 @@
+import { ToolInstance } from './registry';
+import { AgentTemplate } from './task_run';
+export declare const builtin: {
+    fs: () => ToolInstance[];
+    bash: () => ToolInstance[];
+    todo: () => ToolInstance[];
+    task: (templates?: AgentTemplate[]) => ToolInstance | null;
+};
+export { AgentTemplate };