kode-sdk 2.7.0

package/dist/core/checkpointer.d.ts

@@ -0,0 +1,96 @@
+import type { Message, ToolCallRecord } from './types';
+import type { ToolDescriptor } from '../tools/registry';
+/**
+ * Agent 状态快照
+ */
+export interface AgentState {
+    status: 'ready' | 'working' | 'paused' | 'completed' | 'failed';
+    stepCount: number;
+    lastSfpIndex: number;
+    lastBookmark?: {
+        seq: number;
+        timestamp: number;
+    };
+}
+/**
+ * Checkpoint 数据结构
+ */
+export interface Checkpoint {
+    id: string;
+    agentId: string;
+    sessionId?: string;
+    timestamp: number;
+    version: string;
+    state: AgentState;
+    messages: Message[];
+    toolRecords: ToolCallRecord[];
+    tools: ToolDescriptor[];
+    config: {
+        model: string;
+        systemPrompt?: string;
+        templateId?: string;
+    };
+    metadata: {
+        isForkPoint?: boolean;
+        parentCheckpointId?: string;
+        tags?: string[];
+        [key: string]: any;
+    };
+}
+/**
+ * Checkpoint 元数据（列表时使用）
+ */
+export interface CheckpointMetadata {
+    id: string;
+    agentId: string;
+    sessionId?: string;
+    timestamp: number;
+    isForkPoint?: boolean;
+    tags?: string[];
+}
+/**
+ * Checkpointer 接口
+ *
+ * 提供可选的持久化机制，解耦 Store 强依赖
+ */
+export interface Checkpointer {
+    /**
+     * 保存 checkpoint
+     */
+    save(checkpoint: Checkpoint): Promise<string>;
+    /**
+     * 加载 checkpoint
+     */
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    /**
+     * 列出 Agent 的所有 checkpoints
+     */
+    list(agentId: string, options?: {
+        sessionId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<CheckpointMetadata[]>;
+    /**
+     * 删除 checkpoint
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Fork checkpoint（可选）
+     */
+    fork?(checkpointId: string, newAgentId: string): Promise<string>;
+}
+/**
+ * 内存 Checkpointer（默认实现）
+ */
+export declare class MemoryCheckpointer implements Checkpointer {
+    private checkpoints;
+    save(checkpoint: Checkpoint): Promise<string>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    list(agentId: string, options?: {
+        sessionId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<CheckpointMetadata[]>;
+    delete(checkpointId: string): Promise<void>;
+    fork(checkpointId: string, newAgentId: string): Promise<string>;
+}

package/dist/core/checkpointer.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCheckpointer = void 0;
+/**
+ * 内存 Checkpointer（默认实现）
+ */
+class MemoryCheckpointer {
+    constructor() {
+        this.checkpoints = new Map();
+    }
+    async save(checkpoint) {
+        this.checkpoints.set(checkpoint.id, JSON.parse(JSON.stringify(checkpoint)));
+        return checkpoint.id;
+    }
+    async load(checkpointId) {
+        const checkpoint = this.checkpoints.get(checkpointId);
+        return checkpoint ? JSON.parse(JSON.stringify(checkpoint)) : null;
+    }
+    async list(agentId, options) {
+        const allCheckpoints = Array.from(this.checkpoints.values())
+            .filter((cp) => cp.agentId === agentId)
+            .filter((cp) => !options?.sessionId || cp.sessionId === options.sessionId)
+            .sort((a, b) => b.timestamp - a.timestamp);
+        const start = options?.offset || 0;
+        const end = options?.limit ? start + options.limit : undefined;
+        const slice = allCheckpoints.slice(start, end);
+        return slice.map((cp) => ({
+            id: cp.id,
+            agentId: cp.agentId,
+            sessionId: cp.sessionId,
+            timestamp: cp.timestamp,
+            isForkPoint: cp.metadata.isForkPoint,
+            tags: cp.metadata.tags,
+        }));
+    }
+    async delete(checkpointId) {
+        this.checkpoints.delete(checkpointId);
+    }
+    async fork(checkpointId, newAgentId) {
+        const original = await this.load(checkpointId);
+        if (!original) {
+            throw new Error(`Checkpoint not found: ${checkpointId}`);
+        }
+        const forked = {
+            ...original,
+            id: `${newAgentId}:${Date.now()}`,
+            agentId: newAgentId,
+            timestamp: Date.now(),
+            metadata: {
+                ...original.metadata,
+                parentCheckpointId: checkpointId,
+            },
+        };
+        return await this.save(forked);
+    }
+}
+exports.MemoryCheckpointer = MemoryCheckpointer;

package/dist/core/checkpointers/file.d.ts

@@ -0,0 +1,20 @@
+import type { Checkpointer, Checkpoint, CheckpointMetadata } from '../checkpointer';
+/**
+ * File-based Checkpointer
+ *
+ * 将 checkpoints 保存到本地文件系统
+ */
+export declare class FileCheckpointer implements Checkpointer {
+    private readonly baseDir;
+    constructor(baseDir: string);
+    save(checkpoint: Checkpoint): Promise<string>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    list(agentId: string, options?: {
+        sessionId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<CheckpointMetadata[]>;
+    delete(checkpointId: string): Promise<void>;
+    fork(checkpointId: string, newAgentId: string): Promise<string>;
+    private ensureDir;
+}

package/dist/core/checkpointers/file.js

@@ -0,0 +1,153 @@
+"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.FileCheckpointer = void 0;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+/**
+ * File-based Checkpointer
+ *
+ * 将 checkpoints 保存到本地文件系统
+ */
+class FileCheckpointer {
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    async save(checkpoint) {
+        await this.ensureDir();
+        const agentDir = path.join(this.baseDir, checkpoint.agentId);
+        await fs_1.promises.mkdir(agentDir, { recursive: true });
+        const filePath = path.join(agentDir, `${checkpoint.id}.json`);
+        await fs_1.promises.writeFile(filePath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+        return checkpoint.id;
+    }
+    async load(checkpointId) {
+        try {
+            // 扫描所有 agent 目录查找 checkpoint
+            const agentDirs = await fs_1.promises.readdir(this.baseDir);
+            for (const agentId of agentDirs) {
+                const agentDir = path.join(this.baseDir, agentId);
+                const stat = await fs_1.promises.stat(agentDir);
+                if (!stat.isDirectory())
+                    continue;
+                const filePath = path.join(agentDir, `${checkpointId}.json`);
+                try {
+                    const content = await fs_1.promises.readFile(filePath, 'utf-8');
+                    return JSON.parse(content);
+                }
+                catch {
+                    continue;
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async list(agentId, options) {
+        const agentDir = path.join(this.baseDir, agentId);
+        try {
+            const files = await fs_1.promises.readdir(agentDir);
+            const checkpoints = [];
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const filePath = path.join(agentDir, file);
+                const content = await fs_1.promises.readFile(filePath, 'utf-8');
+                const checkpoint = JSON.parse(content);
+                if (options?.sessionId && checkpoint.sessionId !== options.sessionId) {
+                    continue;
+                }
+                checkpoints.push({
+                    id: checkpoint.id,
+                    agentId: checkpoint.agentId,
+                    sessionId: checkpoint.sessionId,
+                    timestamp: checkpoint.timestamp,
+                    isForkPoint: checkpoint.metadata.isForkPoint,
+                    tags: checkpoint.metadata.tags,
+                });
+            }
+            // 按时间排序
+            checkpoints.sort((a, b) => b.timestamp - a.timestamp);
+            // 分页
+            const start = options?.offset || 0;
+            const end = options?.limit ? start + options.limit : undefined;
+            return checkpoints.slice(start, end);
+        }
+        catch {
+            return [];
+        }
+    }
+    async delete(checkpointId) {
+        try {
+            const agentDirs = await fs_1.promises.readdir(this.baseDir);
+            for (const agentId of agentDirs) {
+                const filePath = path.join(this.baseDir, agentId, `${checkpointId}.json`);
+                try {
+                    await fs_1.promises.unlink(filePath);
+                    return;
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    async fork(checkpointId, newAgentId) {
+        const original = await this.load(checkpointId);
+        if (!original) {
+            throw new Error(`Checkpoint not found: ${checkpointId}`);
+        }
+        const forked = {
+            ...original,
+            id: `${newAgentId}:${Date.now()}`,
+            agentId: newAgentId,
+            timestamp: Date.now(),
+            metadata: {
+                ...original.metadata,
+                parentCheckpointId: checkpointId,
+            },
+        };
+        return await this.save(forked);
+    }
+    async ensureDir() {
+        await fs_1.promises.mkdir(this.baseDir, { recursive: true });
+    }
+}
+exports.FileCheckpointer = FileCheckpointer;

package/dist/core/checkpointers/index.d.ts

@@ -0,0 +1,3 @@
+export { MemoryCheckpointer } from '../checkpointer';
+export { FileCheckpointer } from './file';
+export { RedisCheckpointer } from './redis';

package/dist/core/checkpointers/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCheckpointer = exports.FileCheckpointer = exports.MemoryCheckpointer = void 0;
+var checkpointer_1 = require("../checkpointer");
+Object.defineProperty(exports, "MemoryCheckpointer", { enumerable: true, get: function () { return checkpointer_1.MemoryCheckpointer; } });
+var file_1 = require("./file");
+Object.defineProperty(exports, "FileCheckpointer", { enumerable: true, get: function () { return file_1.FileCheckpointer; } });
+var redis_1 = require("./redis");
+Object.defineProperty(exports, "RedisCheckpointer", { enumerable: true, get: function () { return redis_1.RedisCheckpointer; } });

package/dist/core/checkpointers/redis.d.ts

@@ -0,0 +1,35 @@
+import type { Checkpointer, Checkpoint, CheckpointMetadata } from '../checkpointer';
+/**
+ * Redis 配置
+ */
+export interface RedisCheckpointerConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    keyPrefix?: string;
+    ttl?: number;
+}
+/**
+ * Redis-based Checkpointer
+ *
+ * 使用 Redis 存储 checkpoints（需要 ioredis）
+ */
+export declare class RedisCheckpointer implements Checkpointer {
+    private redis;
+    private keyPrefix;
+    private ttl?;
+    constructor(config?: RedisCheckpointerConfig);
+    save(checkpoint: Checkpoint): Promise<string>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    list(agentId: string, options?: {
+        sessionId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<CheckpointMetadata[]>;
+    delete(checkpointId: string): Promise<void>;
+    fork(checkpointId: string, newAgentId: string): Promise<string>;
+    disconnect(): Promise<void>;
+    private getKey;
+    private getIndexKey;
+}

package/dist/core/checkpointers/redis.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCheckpointer = void 0;
+/**
+ * Redis-based Checkpointer
+ *
+ * 使用 Redis 存储 checkpoints（需要 ioredis）
+ */
+class RedisCheckpointer {
+    constructor(config = {}) {
+        this.keyPrefix = config.keyPrefix || 'kode:checkpoint:';
+        this.ttl = config.ttl;
+        // 延迟加载 ioredis（可选依赖）
+        try {
+            const Redis = require('ioredis');
+            this.redis = new Redis({
+                host: config.host || 'localhost',
+                port: config.port || 6379,
+                password: config.password,
+                db: config.db || 0,
+            });
+        }
+        catch (error) {
+            throw new Error('ioredis is required for RedisCheckpointer. Install it with: npm install ioredis');
+        }
+    }
+    async save(checkpoint) {
+        const key = this.getKey(checkpoint.id);
+        const value = JSON.stringify(checkpoint);
+        if (this.ttl) {
+            await this.redis.setex(key, this.ttl, value);
+        }
+        else {
+            await this.redis.set(key, value);
+        }
+        // 添加到 agent 的索引
+        const indexKey = this.getIndexKey(checkpoint.agentId);
+        await this.redis.zadd(indexKey, checkpoint.timestamp, checkpoint.id);
+        return checkpoint.id;
+    }
+    async load(checkpointId) {
+        const key = this.getKey(checkpointId);
+        const value = await this.redis.get(key);
+        if (!value)
+            return null;
+        return JSON.parse(value);
+    }
+    async list(agentId, options) {
+        const indexKey = this.getIndexKey(agentId);
+        // 按时间倒序获取 checkpoint IDs
+        const start = options?.offset || 0;
+        const end = options?.limit ? start + options.limit - 1 : -1;
+        const ids = await this.redis.zrevrange(indexKey, start, end);
+        const checkpoints = [];
+        for (const id of ids) {
+            const checkpoint = await this.load(id);
+            if (!checkpoint)
+                continue;
+            if (options?.sessionId && checkpoint.sessionId !== options.sessionId) {
+                continue;
+            }
+            checkpoints.push({
+                id: checkpoint.id,
+                agentId: checkpoint.agentId,
+                sessionId: checkpoint.sessionId,
+                timestamp: checkpoint.timestamp,
+                isForkPoint: checkpoint.metadata.isForkPoint,
+                tags: checkpoint.metadata.tags,
+            });
+        }
+        return checkpoints;
+    }
+    async delete(checkpointId) {
+        const checkpoint = await this.load(checkpointId);
+        if (!checkpoint)
+            return;
+        // 删除 checkpoint
+        const key = this.getKey(checkpointId);
+        await this.redis.del(key);
+        // 从索引中移除
+        const indexKey = this.getIndexKey(checkpoint.agentId);
+        await this.redis.zrem(indexKey, checkpointId);
+    }
+    async fork(checkpointId, newAgentId) {
+        const original = await this.load(checkpointId);
+        if (!original) {
+            throw new Error(`Checkpoint not found: ${checkpointId}`);
+        }
+        const forked = {
+            ...original,
+            id: `${newAgentId}:${Date.now()}`,
+            agentId: newAgentId,
+            timestamp: Date.now(),
+            metadata: {
+                ...original.metadata,
+                parentCheckpointId: checkpointId,
+            },
+        };
+        return await this.save(forked);
+    }
+    async disconnect() {
+        if (this.redis) {
+            await this.redis.quit();
+        }
+    }
+    getKey(checkpointId) {
+        return `${this.keyPrefix}${checkpointId}`;
+    }
+    getIndexKey(agentId) {
+        return `${this.keyPrefix}index:${agentId}`;
+    }
+}
+exports.RedisCheckpointer = RedisCheckpointer;

package/dist/core/compression/ai-strategy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AI 智能压缩策略
+ *
+ * 使用 LLM 生成结构化摘要：
+ * - 按 token 数保留消息（而非消息数）
+ * - 使用 AI 生成高质量摘要
+ * - 保留关键上下文信息
+ * - 内置降级机制
+ */
+import { Message, Timeline } from '../types';
+import { Sandbox } from '../../infra/sandbox';
+import { ICompressionStrategy, ContextUsage, CompressionResult, FilePoolState, AICompressionStrategyOptions } from './types';
+export declare class AICompressionStrategy implements ICompressionStrategy {
+    private readonly store;
+    private readonly agentId;
+    private readonly maxTokens;
+    private readonly compressToTokens;
+    private readonly preserveRecentTurns;
+    private readonly summaryPrompt?;
+    private readonly eventEmitter?;
+    private readonly summaryModel;
+    constructor(opts: AICompressionStrategyOptions);
+    /**
+     * 创建摘要模型
+     *
+     * 优先使用单独配置的摘要模型，否则复用主模型配置
+     */
+    private createSummaryModel;
+    /**
+     * 分析上下文使用情况
+     */
+    analyze(messages: Message[]): ContextUsage;
+    /**
+     * 执行压缩
+     */
+    compress(messages: Message[], events: Timeline[], filePool?: FilePoolState, sandbox?: Sandbox): Promise<CompressionResult | undefined>;
+    /**
+     * 使用 AI 生成摘要
+     */
+    private generateAISummary;
+    /**
+     * 生成简单摘要（降级方案）
+     */
+    private generateSimpleSummary;
+    /**
+     * 预览文本（截断长文本）
+     */
+    private preview;
+    /**
+     * 处理孤立的 tool_result
+     */
+    private sanitizeOrphanToolResults;
+}