@shareai-lab/kode-sdk 1.0.0-beta.8 → 2.7.0

package/dist/core/events.js

@@ -1,89 +1,289 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventBus = void 0;
-const types_1 = require("../core/types");
 const events_1 = require("events");
-const crypto_1 = require("crypto");
-class EventBus extends events_1.EventEmitter {
+const logger_1 = require("../utils/logger");
+class EventBus {
     constructor() {
-        super(...arguments);
         this.cursor = 0;
+        this.seq = 0;
         this.timeline = [];
-        this.subscribers = new Set();
+        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());
+        // Prevent Node.js ERR_UNHANDLED_ERROR when emitting 'error' events
+        // without a listener. This allows MonitorEvent with type='error' to be
+        // emitted safely. Users can still register their own 'error' handlers.
+        this.monitorEmitter.on('error', () => {
+            // No-op: errors are handled through the subscriber system
+        });
     }
-    setStore(store, sessionId) {
+    setStore(store, agentId) {
         this.store = store;
-        this.sessionId = sessionId;
-    }
-    emitEvent(event) {
-        const cursor = this.cursor++;
-        const eventId = (0, crypto_1.randomUUID)();
-        const timestamp = Date.now();
-        const fullEvent = { ...event, cursor, eventId, timestamp };
-        const timeline = { cursor, event: fullEvent };
-        this.timeline.push(timeline);
-        // Memory management: keep only last 10k events in memory
-        if (this.timeline.length > 10000) {
-            this.timeline = this.timeline.slice(-5000);
-        }
-        // Persist to store if configured
-        if (this.store && this.sessionId) {
-            this.store.appendEvent(this.sessionId, timeline).catch((err) => {
-                // Log error but don't block event emission
-                console.error('Failed to persist event:', err);
-            });
-        }
-        // Notify all subscribers
-        for (const subscriber of this.subscribers) {
-            if (subscriber.accepts(fullEvent.type)) {
-                subscriber.push(fullEvent);
-            }
-        }
-        // Emit control plane events
-        this.emit(event.type, fullEvent);
-        return cursor;
-    }
-    subscribe(opts) {
-        const subscriber = new EventSubscriber(opts?.kinds || types_1.MINIMAL_EVENT_KINDS);
-        this.subscribers.add(subscriber);
-        // Replay past events if since is specified
-        if (opts?.since !== undefined) {
-            const past = this.timeline.filter((t) => t.cursor >= opts.since);
-            for (const t of past) {
-                if (subscriber.accepts(t.event.type)) {
-                    subscriber.push(t.event);
-                }
-            }
+        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 self = this;
+        const bus = this;
         return {
-            [Symbol.asyncIterator]: () => ({
-                next: async () => {
-                    const event = await subscriber.next();
-                    if (!event) {
-                        self.subscribers.delete(subscriber);
+            [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 };
-                    }
-                    return { done: false, value: event };
-                },
-                return: async () => {
-                    subscriber.close();
-                    self.subscribers.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;
+    }
+    syncCursor(bookmark) {
+        if (!bookmark)
+            return;
+        const nextSeq = bookmark.seq + 1;
+        if (this.seq < nextSeq) {
+            this.seq = nextSeq;
+        }
+        const timelineCursor = this.timeline.length
+            ? this.timeline[this.timeline.length - 1].cursor + 1
+            : 0;
+        const nextCursor = Math.max(this.cursor, nextSeq, timelineCursor);
+        if (this.cursor < nextCursor) {
+            this.cursor = nextCursor;
+        }
+    }
     reset() {
         this.cursor = 0;
+        this.seq = 0;
         this.timeline = [];
-        this.subscribers.clear();
+        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 {
+                    // 非关键事件失败：仅记录日志
+                    logger_1.logger.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) {
+                logger_1.logger.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;
@@ -94,18 +294,20 @@ class EventSubscriber {
         this.waiting = null;
         this.closed = false;
     }
-    accepts(kind) {
-        return this.kinds.includes(kind);
+    accepts(envelope) {
+        if (!this.kinds || this.kinds.length === 0)
+            return true;
+        return this.kinds.includes(String(envelope.event.type));
     }
-    push(event) {
+    push(envelope) {
         if (this.closed)
             return;
         if (this.waiting) {
-            this.waiting(event);
+            this.waiting(envelope);
             this.waiting = null;
         }
         else {
-            this.queue.push(event);
+            this.queue.push(envelope);
         }
     }
     async next() {

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

@@ -0,0 +1,41 @@
+import { Sandbox } from '../infra/sandbox';
+export interface FileRecord {
+    path: string;
+    lastRead?: number;
+    lastEdit?: number;
+    lastReadMtime?: 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>;
+    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,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilePool = void 0;
+const logger_1 = require("../utils/logger");
+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.lastKnownMtime = await this.getMtime(resolved);
+        this.records.set(resolved, record);
+        await this.ensureWatch(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 };
+        }
+        const isFresh = record.lastRead !== undefined &&
+            (currentMtime === undefined || record.lastReadMtime === undefined || currentMtime === record.lastReadMtime);
+        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 失败，但不中断流程
+            logger_1.logger.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

@@ -1,10 +1,10 @@
 import { ToolCall, ToolOutcome, HookDecision, PostHookResult, ToolContext } from '../core/types';
-import { ProviderResponse } from '../infra/provider';
+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: ProviderResponse) => void | Promise<void>;
+    postModel?: (response: ModelResponse) => void | Promise<void>;
     messagesChanged?: (snapshot: any) => void | Promise<void>;
 }
 export interface RegisteredHook {
@@ -18,6 +18,6 @@ export declare class HookManager {
     runPreToolUse(call: ToolCall, ctx: ToolContext): Promise<HookDecision>;
     runPostToolUse(outcome: ToolOutcome, ctx: ToolContext): Promise<ToolOutcome>;
     runPreModel(request: any): Promise<void>;
-    runPostModel(response: ProviderResponse): Promise<void>;
+    runPostModel(response: ModelResponse): Promise<void>;
     runMessagesChanged(snapshot: any): Promise<void>;
 }

package/dist/core/hooks.js

@@ -34,7 +34,7 @@ class HookManager {
         for (const { hooks } of this.hooks) {
             if (hooks.postToolUse) {
                 const result = await hooks.postToolUse(current, ctx);
-                if (result) {
+                if (result && typeof result === 'object') {
                     if ('replace' in result) {
                         current = result.replace;
                     }

package/dist/core/permission-modes.d.ts

@@ -0,0 +1,31 @@
+import { PermissionConfig } from './template';
+import { ToolDescriptor } from '../tools/registry';
+export type PermissionDecision = 'allow' | 'deny' | 'ask';
+export interface PermissionEvaluationContext {
+    toolName: string;
+    descriptor?: ToolDescriptor;
+    config: PermissionConfig;
+}
+export type PermissionModeHandler = (ctx: PermissionEvaluationContext) => PermissionDecision;
+export interface SerializedPermissionMode {
+    name: string;
+    builtIn: boolean;
+}
+export declare class PermissionModeRegistry {
+    private handlers;
+    private customModes;
+    register(mode: string, handler: PermissionModeHandler, isBuiltIn?: boolean): void;
+    get(mode: string): PermissionModeHandler | undefined;
+    list(): string[];
+    /**
+     * 序列化权限模式配置
+     * 仅序列化自定义模式的名称，内置模式在 Resume 时自动恢复
+     */
+    serialize(): SerializedPermissionMode[];
+    /**
+     * 验证序列化的权限模式是否可恢复
+     * 返回缺失的自定义模式列表
+     */
+    validateRestore(serialized: SerializedPermissionMode[]): string[];
+}
+export declare const permissionModes: PermissionModeRegistry;

package/dist/core/permission-modes.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.permissionModes = exports.PermissionModeRegistry = void 0;
+class PermissionModeRegistry {
+    constructor() {
+        this.handlers = new Map();
+        this.customModes = new Set();
+    }
+    register(mode, handler, isBuiltIn = false) {
+        this.handlers.set(mode, handler);
+        if (!isBuiltIn) {
+            this.customModes.add(mode);
+        }
+    }
+    get(mode) {
+        return this.handlers.get(mode);
+    }
+    list() {
+        return Array.from(this.handlers.keys());
+    }
+    /**
+     * 序列化权限模式配置
+     * 仅序列化自定义模式的名称，内置模式在 Resume 时自动恢复
+     */
+    serialize() {
+        return Array.from(this.handlers.keys()).map(name => ({
+            name,
+            builtIn: !this.customModes.has(name)
+        }));
+    }
+    /**
+     * 验证序列化的权限模式是否可恢复
+     * 返回缺失的自定义模式列表
+     */
+    validateRestore(serialized) {
+        const missing = [];
+        for (const mode of serialized) {
+            if (!mode.builtIn && !this.handlers.has(mode.name)) {
+                missing.push(mode.name);
+            }
+        }
+        return missing;
+    }
+}
+exports.PermissionModeRegistry = PermissionModeRegistry;
+exports.permissionModes = new PermissionModeRegistry();
+const MUTATING_ACCESS = new Set(['write', 'execute', 'manage', 'mutate']);
+// 内置模式
+exports.permissionModes.register('auto', () => 'allow', true);
+exports.permissionModes.register('approval', () => 'ask', true);
+exports.permissionModes.register('readonly', (ctx) => {
+    const metadata = ctx.descriptor?.metadata || {};
+    if (metadata.mutates === true)
+        return 'deny';
+    if (metadata.mutates === false)
+        return 'allow';
+    const access = typeof metadata.access === 'string' ? metadata.access.toLowerCase() : undefined;
+    if (access && MUTATING_ACCESS.has(access))
+        return 'deny';
+    return 'ask';
+}, true);