kode-sdk 2.7.0

package/dist/core/context-manager.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextManager = void 0;
+const compression_1 = require("./compression");
+// ============================================================================
+// ContextManager 实现
+// ============================================================================
+/**
+ * ContextManager v3 - 支持多种压缩策略的上下文管理器
+ *
+ * 职责：
+ * 1. 分析上下文使用情况（token 估算）
+ * 2. 根据配置选择压缩策略（simple 或 ai）
+ * 3. 委托策略执行压缩
+ * 4. 提供历史记录查询接口
+ *
+ * 策略模式：
+ * - simple: 简单截断（保留最近消息 + 文本摘要）
+ * - ai: AI 智能压缩（使用 LLM 生成结构化摘要）
+ */
+class ContextManager {
+    constructor(store, agentId, opts) {
+        this.store = store;
+        this.agentId = agentId;
+        // 根据配置选择策略
+        this.strategy = this.createStrategy(opts);
+    }
+    /**
+     * 创建压缩策略
+     *
+     * 默认值基于 Claude 官方最佳实践：
+     * - maxTokens: 64K = 50% 的 128K 上下文窗口（对标 Claude 默认 100K/200K）
+     * - compressToTokens: 40K = 约 62.5% 的 maxTokens
+     * @see https://platform.claude.com/cookbook/tool-use-automatic-context-compaction
+     */
+    createStrategy(opts) {
+        const maxTokens = opts?.maxTokens ?? 64000;
+        const compressToTokens = opts?.compressToTokens ?? 40000;
+        // 如果选择 AI 策略且提供了必要配置
+        if (opts?.algorithm === 'ai' && opts?.modelConfig && opts?.modelFactory) {
+            return new compression_1.AICompressionStrategy({
+                store: this.store,
+                agentId: this.agentId,
+                maxTokens,
+                compressToTokens,
+                modelConfig: opts.modelConfig,
+                modelFactory: opts.modelFactory,
+                summaryModelConfig: opts.summaryModelConfig,
+                summaryPrompt: opts.summaryPrompt,
+                preserveRecentTurns: opts.preserveRecentTurns,
+                eventEmitter: opts.eventEmitter,
+            });
+        }
+        // 默认使用简单策略
+        return new compression_1.SimpleCompressionStrategy({
+            store: this.store,
+            agentId: this.agentId,
+            maxTokens,
+            compressToTokens,
+            compressionModel: opts?.compressionModel,
+            compressionPrompt: opts?.compressionPrompt,
+            eventEmitter: opts?.eventEmitter,
+        });
+    }
+    /**
+     * 分析上下文使用情况（粗略的 token 估算）
+     *
+     * 方法签名保持不变，委托给策略执行
+     */
+    analyze(messages) {
+        return this.strategy.analyze(messages);
+    }
+    /**
+     * 压缩上下文并保存历史
+     *
+     * 方法签名保持不变，委托给策略执行
+     *
+     * 流程：
+     * 1. 保存 HistoryWindow（压缩前的完整快照）
+     * 2. 执行压缩（根据策略不同，方式不同）
+     * 3. 保存 CompressionRecord（压缩元信息）
+     * 4. 保存重要文件快照（如果有 FilePool）
+     * 5. 返回压缩结果
+     */
+    async compress(messages, events, filePool, sandbox) {
+        return this.strategy.compress(messages, events, filePool, sandbox);
+    }
+    /**
+     * 恢复历史窗口（用于审计或调试）
+     */
+    async loadHistory() {
+        return await this.store.loadHistoryWindows(this.agentId);
+    }
+    /**
+     * 加载压缩记录
+     */
+    async loadCompressions() {
+        return await this.store.loadCompressionRecords(this.agentId);
+    }
+    /**
+     * 加载恢复的文件
+     */
+    async loadRecoveredFiles() {
+        return await this.store.loadRecoveredFiles(this.agentId);
+    }
+}
+exports.ContextManager = ContextManager;

package/dist/core/errors.d.ts

@@ -0,0 +1,6 @@
+export type ResumeErrorCode = 'SESSION_NOT_FOUND' | 'AGENT_NOT_FOUND' | 'TEMPLATE_NOT_FOUND' | 'TEMPLATE_VERSION_MISMATCH' | 'SANDBOX_INIT_FAILED' | 'CORRUPTED_DATA';
+export declare class ResumeError extends Error {
+    readonly code: ResumeErrorCode;
+    constructor(code: ResumeErrorCode, message: string);
+}
+export declare function assert(condition: any, code: ResumeErrorCode, message: string): asserts condition;

package/dist/core/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResumeError = void 0;
+exports.assert = assert;
+class ResumeError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ResumeError';
+    }
+}
+exports.ResumeError = ResumeError;
+function assert(condition, code, message) {
+    if (!condition) {
+        throw new ResumeError(code, message);
+    }
+}

package/dist/core/events.d.ts

@@ -0,0 +1,49 @@
+import { AgentEvent, AgentEventEnvelope, ControlEvent, MonitorEvent, ProgressEvent, Timeline, Bookmark } from '../core/types';
+import { Store } from '../infra/store';
+type ControlEventType = ControlEvent['type'];
+type MonitorEventType = MonitorEvent['type'];
+type SubscriberChannel = 'progress' | 'control' | 'monitor';
+export declare class EventBus {
+    private cursor;
+    private seq;
+    private timeline;
+    private subscribers;
+    private controlEmitter;
+    private monitorEmitter;
+    private store?;
+    private agentId?;
+    private failedEvents;
+    private readonly MAX_FAILED_BUFFER;
+    constructor();
+    setStore(store: Store, agentId: string): void;
+    emitProgress(event: ProgressEvent): AgentEventEnvelope<ProgressEvent>;
+    emitControl(event: ControlEvent): AgentEventEnvelope<ControlEvent>;
+    emitMonitor(event: MonitorEvent): AgentEventEnvelope<MonitorEvent>;
+    subscribeProgress(opts?: {
+        since?: Bookmark;
+        kinds?: Array<ProgressEvent['type']>;
+    }): AsyncIterable<AgentEventEnvelope<ProgressEvent>>;
+    subscribe(channels?: SubscriberChannel[], opts?: {
+        since?: Bookmark;
+        kinds?: Array<AgentEvent['type']>;
+    }): AsyncIterable<AgentEventEnvelope>;
+    onControl<T extends ControlEventType>(type: T, handler: (evt: Extract<ControlEvent, {
+        type: T;
+    }>) => void): () => void;
+    onMonitor<T extends MonitorEventType>(type: T, handler: (evt: Extract<MonitorEvent, {
+        type: T;
+    }>) => void): () => void;
+    getTimeline(since?: number): Timeline[];
+    getCursor(): number;
+    getLastBookmark(): Bookmark | undefined;
+    reset(): void;
+    private emit;
+    private isCriticalEvent;
+    private retryFailedEvents;
+    getFailedEventCount(): number;
+    flushFailedEvents(): Promise<void>;
+    private notifySubscribers;
+    private replayHistory;
+    private iterableFor;
+}
+export {};

package/dist/core/events.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBus = void 0;
+const events_1 = require("events");
+class EventBus {
+    constructor() {
+        this.cursor = 0;
+        this.seq = 0;
+        this.timeline = [];
+        this.subscribers = new Map();
+        this.controlEmitter = new events_1.EventEmitter();
+        this.monitorEmitter = new events_1.EventEmitter();
+        this.failedEvents = [];
+        this.MAX_FAILED_BUFFER = 1000;
+        this.subscribers.set('progress', new Set());
+        this.subscribers.set('control', new Set());
+        this.subscribers.set('monitor', new Set());
+        // Node.js EventEmitter treats the "error" event specially: emitting it without a listener throws.
+        // Our Monitor channel intentionally uses event.type === 'error' for structured error telemetry.
+        // Add a default no-op listener so that Monitor errors never crash the host process when no callback is registered.
+        this.monitorEmitter.on('error', () => { });
+        this.controlEmitter.on('error', () => { });
+    }
+    setStore(store, agentId) {
+        this.store = store;
+        this.agentId = agentId;
+    }
+    emitProgress(event) {
+        const envelope = this.emit('progress', event);
+        this.notifySubscribers('progress', envelope);
+        return envelope;
+    }
+    emitControl(event) {
+        const envelope = this.emit('control', event);
+        this.controlEmitter.emit(event.type, envelope.event);
+        this.notifySubscribers('control', envelope);
+        return envelope;
+    }
+    emitMonitor(event) {
+        const envelope = this.emit('monitor', event);
+        this.monitorEmitter.emit(event.type, envelope.event);
+        this.notifySubscribers('monitor', envelope);
+        return envelope;
+    }
+    subscribeProgress(opts) {
+        const subscriber = new EventSubscriber(opts?.kinds);
+        this.subscribers.get('progress').add(subscriber);
+        if (opts?.since) {
+            void this.replayHistory('progress', subscriber, opts.since);
+        }
+        const bus = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        const value = (await subscriber.next());
+                        if (!value) {
+                            bus.subscribers.get('progress').delete(subscriber);
+                            return { done: true, value: undefined };
+                        }
+                        return { done: false, value };
+                    },
+                    async return() {
+                        subscriber.close();
+                        bus.subscribers.get('progress').delete(subscriber);
+                        return { done: true, value: undefined };
+                    },
+                };
+            },
+        };
+    }
+    subscribe(channels = ['progress', 'control', 'monitor'], opts) {
+        const subscriber = new EventSubscriber(opts?.kinds);
+        for (const channel of channels) {
+            this.subscribers.get(channel).add(subscriber);
+            if (opts?.since) {
+                void this.replayHistory(channel, subscriber, opts.since);
+            }
+        }
+        return this.iterableFor(channels, subscriber);
+    }
+    onControl(type, handler) {
+        this.controlEmitter.on(type, handler);
+        return () => this.controlEmitter.off(type, handler);
+    }
+    onMonitor(type, handler) {
+        this.monitorEmitter.on(type, handler);
+        return () => this.monitorEmitter.off(type, handler);
+    }
+    getTimeline(since) {
+        return since !== undefined ? this.timeline.filter((t) => t.cursor >= since) : this.timeline;
+    }
+    getCursor() {
+        return this.cursor;
+    }
+    getLastBookmark() {
+        const last = this.timeline[this.timeline.length - 1];
+        return last?.bookmark;
+    }
+    reset() {
+        this.cursor = 0;
+        this.seq = 0;
+        this.timeline = [];
+        for (const set of this.subscribers.values()) {
+            set.clear();
+        }
+        this.controlEmitter.removeAllListeners();
+        this.monitorEmitter.removeAllListeners();
+    }
+    emit(channel, event) {
+        const bookmark = {
+            seq: this.seq++,
+            timestamp: Date.now(),
+        };
+        const eventWithChannel = { ...event, channel };
+        const eventWithBookmark = { ...eventWithChannel, bookmark };
+        const envelope = {
+            cursor: this.cursor++,
+            bookmark,
+            event: eventWithBookmark,
+        };
+        const timelineEntry = {
+            cursor: envelope.cursor,
+            bookmark,
+            event: envelope.event,
+        };
+        this.timeline.push(timelineEntry);
+        if (this.timeline.length > 10000) {
+            this.timeline = this.timeline.slice(-5000);
+        }
+        if (this.store && this.agentId) {
+            const isCritical = this.isCriticalEvent(event);
+            this.store.appendEvent(this.agentId, timelineEntry)
+                .then(() => {
+                // 成功后尝试重试之前失败的事件
+                if (this.failedEvents.length > 0) {
+                    void this.retryFailedEvents();
+                }
+            })
+                .catch((err) => {
+                if (isCritical) {
+                    // 关键事件失败：缓存到内存
+                    this.failedEvents.push(timelineEntry);
+                    if (this.failedEvents.length > this.MAX_FAILED_BUFFER) {
+                        this.failedEvents = this.failedEvents.slice(-this.MAX_FAILED_BUFFER);
+                    }
+                    // 发送降级的内存 Monitor 事件（不持久化）
+                    try {
+                        this.monitorEmitter.emit('storage_failure', {
+                            type: 'storage_failure',
+                            severity: 'critical',
+                            failedEvent: event.type,
+                            bufferedCount: this.failedEvents.length,
+                            error: err.message
+                        });
+                    }
+                    catch {
+                        // 降级事件发送失败也不阻塞
+                    }
+                }
+                else {
+                    // 非关键事件失败：仅记录日志
+                    console.warn(`[EventBus] Failed to persist non-critical event: ${event.type}`, err);
+                }
+            });
+        }
+        return envelope;
+    }
+    isCriticalEvent(event) {
+        const criticalTypes = new Set([
+            'tool:end',
+            'done',
+            'permission_decided',
+            'agent_resumed',
+            'state_changed',
+            'breakpoint_changed',
+            'error',
+        ]);
+        return criticalTypes.has(event.type);
+    }
+    async retryFailedEvents() {
+        if (!this.store || !this.agentId || this.failedEvents.length === 0)
+            return;
+        const toRetry = this.failedEvents.splice(0, 10);
+        for (const event of toRetry) {
+            try {
+                await this.store.appendEvent(this.agentId, event);
+            }
+            catch (err) {
+                this.failedEvents.unshift(event);
+                break;
+            }
+        }
+    }
+    getFailedEventCount() {
+        return this.failedEvents.length;
+    }
+    async flushFailedEvents() {
+        while (this.failedEvents.length > 0) {
+            await this.retryFailedEvents();
+            if (this.failedEvents.length > 0) {
+                await new Promise(resolve => setTimeout(resolve, 1000));
+            }
+        }
+    }
+    notifySubscribers(channel, envelope) {
+        const subscribers = this.subscribers.get(channel);
+        if (!subscribers)
+            return;
+        for (const subscriber of subscribers) {
+            if (subscriber.accepts(envelope)) {
+                subscriber.push(envelope);
+            }
+        }
+    }
+    async replayHistory(channel, subscriber, since) {
+        if (this.store && this.agentId) {
+            try {
+                const opts = { channel: channel, since };
+                for await (const entry of this.store.readEvents(this.agentId, opts)) {
+                    const envelope = entry;
+                    if (subscriber.accepts(envelope)) {
+                        subscriber.push(envelope);
+                    }
+                }
+                return;
+            }
+            catch (error) {
+                console.error('Failed to replay events from store:', error);
+            }
+        }
+        const past = this.timeline.filter((t) => {
+            if (t.event.channel !== channel)
+                return false;
+            if (!since)
+                return true;
+            return t.bookmark.seq > since.seq;
+        });
+        for (const entry of past) {
+            const envelope = entry;
+            if (subscriber.accepts(envelope)) {
+                subscriber.push(envelope);
+            }
+        }
+    }
+    iterableFor(channel, subscriber) {
+        const channels = Array.isArray(channel) ? channel : [channel];
+        const bus = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next: async () => {
+                        const value = (await subscriber.next());
+                        if (!value) {
+                            for (const ch of channels)
+                                bus.subscribers.get(ch).delete(subscriber);
+                            return { done: true, value: undefined };
+                        }
+                        return { done: false, value };
+                    },
+                    return: async () => {
+                        subscriber.close();
+                        for (const ch of channels)
+                            bus.subscribers.get(ch).delete(subscriber);
+                        return { done: true, value: undefined };
+                    },
+                };
+            },
+        };
+    }
+}
+exports.EventBus = EventBus;
+class EventSubscriber {
+    constructor(kinds) {
+        this.kinds = kinds;
+        this.queue = [];
+        this.waiting = null;
+        this.closed = false;
+    }
+    accepts(envelope) {
+        if (!this.kinds || this.kinds.length === 0)
+            return true;
+        return this.kinds.includes(String(envelope.event.type));
+    }
+    push(envelope) {
+        if (this.closed)
+            return;
+        if (this.waiting) {
+            this.waiting(envelope);
+            this.waiting = null;
+        }
+        else {
+            this.queue.push(envelope);
+        }
+    }
+    async next() {
+        if (this.closed)
+            return null;
+        if (this.queue.length > 0)
+            return this.queue.shift();
+        return new Promise((resolve) => {
+            this.waiting = resolve;
+        });
+    }
+    close() {
+        this.closed = true;
+        if (this.waiting) {
+            this.waiting(null);
+            this.waiting = null;
+        }
+    }
+}

package/dist/core/file-pool.d.ts

@@ -0,0 +1,43 @@
+import { Sandbox } from '../infra/sandbox';
+export interface FileRecord {
+    path: string;
+    lastRead?: number;
+    lastEdit?: number;
+    lastReadMtime?: number;
+    lastEditMtime?: number;
+    lastKnownMtime?: number;
+}
+export interface FileFreshness {
+    isFresh: boolean;
+    lastRead?: number;
+    lastEdit?: number;
+    currentMtime?: number;
+}
+interface FilePoolOptions {
+    watch?: boolean;
+    onChange?: (event: {
+        path: string;
+        mtime: number;
+    }) => void;
+}
+export declare class FilePool {
+    private readonly sandbox;
+    private records;
+    private watchers;
+    private readonly watchEnabled;
+    private readonly onChange?;
+    constructor(sandbox: Sandbox, opts?: FilePoolOptions);
+    private getMtime;
+    recordRead(path: string): Promise<void>;
+    recordEdit(path: string): Promise<void>;
+    recordDelete(path: string): Promise<void>;
+    validateWrite(path: string): Promise<FileFreshness>;
+    checkFreshness(path: string): Promise<FileFreshness>;
+    getTrackedFiles(): string[];
+    private ensureWatch;
+    getAccessedFiles(): Array<{
+        path: string;
+        mtime: number;
+    }>;
+}
+export {};

package/dist/core/file-pool.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilePool = void 0;
+class FilePool {
+    constructor(sandbox, opts) {
+        this.sandbox = sandbox;
+        this.records = new Map();
+        this.watchers = new Map();
+        this.watchEnabled = opts?.watch ?? true;
+        this.onChange = opts?.onChange;
+    }
+    async getMtime(path) {
+        try {
+            const stat = await this.sandbox.fs.stat(path);
+            return stat.mtimeMs;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async recordRead(path) {
+        const resolved = this.sandbox.fs.resolve(path);
+        const record = this.records.get(resolved) || { path: resolved };
+        record.lastRead = Date.now();
+        record.lastReadMtime = await this.getMtime(resolved);
+        record.lastKnownMtime = record.lastReadMtime;
+        this.records.set(resolved, record);
+        await this.ensureWatch(resolved);
+    }
+    async recordEdit(path) {
+        const resolved = this.sandbox.fs.resolve(path);
+        const record = this.records.get(resolved) || { path: resolved };
+        record.lastEdit = Date.now();
+        record.lastEditMtime = await this.getMtime(resolved);
+        record.lastKnownMtime = record.lastEditMtime;
+        this.records.set(resolved, record);
+        await this.ensureWatch(resolved);
+    }
+    async recordDelete(path) {
+        const resolved = this.sandbox.fs.resolve(path);
+        this.records.delete(resolved);
+        const watcherId = this.watchers.get(resolved);
+        if (watcherId) {
+            try {
+                this.sandbox.unwatchFiles?.(watcherId);
+            }
+            catch {
+                // best-effort
+            }
+            this.watchers.delete(resolved);
+        }
+    }
+    async validateWrite(path) {
+        const resolved = this.sandbox.fs.resolve(path);
+        const record = this.records.get(resolved);
+        const currentMtime = await this.getMtime(resolved);
+        if (!record) {
+            return { isFresh: true, currentMtime };
+        }
+        // Accept writes if the file hasn't changed since either the last read OR the last edit.
+        // This reduces false positives when the agent performs multiple writes without re-reading,
+        // while still preventing overwriting external changes (mtime drift).
+        const matchesLastRead = record.lastReadMtime !== undefined && currentMtime === record.lastReadMtime;
+        const matchesLastEdit = record.lastEditMtime !== undefined && currentMtime === record.lastEditMtime;
+        const isFresh = currentMtime === undefined || matchesLastRead || matchesLastEdit;
+        return {
+            isFresh,
+            lastRead: record.lastRead,
+            lastEdit: record.lastEdit,
+            currentMtime,
+        };
+    }
+    async checkFreshness(path) {
+        const resolved = this.sandbox.fs.resolve(path);
+        const record = this.records.get(resolved);
+        const currentMtime = await this.getMtime(resolved);
+        if (!record) {
+            return { isFresh: false, currentMtime };
+        }
+        const isFresh = record.lastRead !== undefined &&
+            (currentMtime === undefined || record.lastKnownMtime === undefined || currentMtime === record.lastKnownMtime);
+        return {
+            isFresh,
+            lastRead: record.lastRead,
+            lastEdit: record.lastEdit,
+            currentMtime,
+        };
+    }
+    getTrackedFiles() {
+        return Array.from(this.records.keys());
+    }
+    async ensureWatch(path) {
+        if (!this.watchEnabled)
+            return;
+        if (!this.sandbox.watchFiles)
+            return;
+        if (this.watchers.has(path))
+            return;
+        try {
+            const id = await this.sandbox.watchFiles([path], (event) => {
+                const record = this.records.get(path);
+                if (record) {
+                    record.lastKnownMtime = event.mtimeMs;
+                }
+                this.onChange?.({ path, mtime: event.mtimeMs });
+            });
+            this.watchers.set(path, id);
+        }
+        catch (err) {
+            // 记录 watch 失败，但不中断流程
+            console.warn(`[FilePool] Failed to watch file: ${path}`, err);
+        }
+    }
+    getAccessedFiles() {
+        return Array.from(this.records.values())
+            .filter((r) => r.lastKnownMtime !== undefined)
+            .map((r) => ({ path: r.path, mtime: r.lastKnownMtime }));
+    }
+}
+exports.FilePool = FilePool;

package/dist/core/hooks.d.ts

@@ -0,0 +1,23 @@
+import { ToolCall, ToolOutcome, HookDecision, PostHookResult, ToolContext } from '../core/types';
+import { ModelResponse } from '../infra/provider';
+export interface Hooks {
+    preToolUse?: (call: ToolCall, ctx: ToolContext) => HookDecision | Promise<HookDecision>;
+    postToolUse?: (outcome: ToolOutcome, ctx: ToolContext) => PostHookResult | Promise<PostHookResult>;
+    preModel?: (request: any) => void | Promise<void>;
+    postModel?: (response: ModelResponse) => void | Promise<void>;
+    messagesChanged?: (snapshot: any) => void | Promise<void>;
+}
+export interface RegisteredHook {
+    origin: 'agent' | 'toolTune';
+    names: Array<'preToolUse' | 'postToolUse' | 'preModel' | 'postModel'>;
+}
+export declare class HookManager {
+    private hooks;
+    register(hooks: Hooks, origin?: 'agent' | 'toolTune'): void;
+    getRegistered(): ReadonlyArray<RegisteredHook>;
+    runPreToolUse(call: ToolCall, ctx: ToolContext): Promise<HookDecision>;
+    runPostToolUse(outcome: ToolOutcome, ctx: ToolContext): Promise<ToolOutcome>;
+    runPreModel(request: any): Promise<void>;
+    runPostModel(response: ModelResponse): Promise<void>;
+    runMessagesChanged(snapshot: any): Promise<void>;
+}