@shareai-lab/kode-sdk 2.7.1 → 2.7.2

package/dist/core/file-pool.js

@@ -0,0 +1,125 @@
+"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.watchPending = new Map(); // per-path 锁，防止并发创建 watcher
+        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;
+        // 检查是否有正在进行的 watch 操作（per-path 锁）
+        const pending = this.watchPending.get(path);
+        if (pending) {
+            await pending; // 等待已有操作完成
+            return;
+        }
+        // 创建 watch 操作并存储 Promise
+        const watchPromise = this.doWatch(path);
+        this.watchPending.set(path, watchPromise);
+        try {
+            await watchPromise;
+        }
+        finally {
+            this.watchPending.delete(path);
+        }
+    }
+    async doWatch(path) {
+        // 再次检查（可能在等待期间已被设置）
+        if (this.watchers.has(path))
+            return;
+        if (!this.sandbox.watchFiles)
+            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.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookManager = void 0;
+class HookManager {
+    constructor() {
+        this.hooks = [];
+    }
+    register(hooks, origin = 'agent') {
+        this.hooks.push({ hooks, origin });
+    }
+    getRegistered() {
+        return this.hooks.map(({ hooks, origin }) => ({
+            origin,
+            names: [
+                hooks.preToolUse && 'preToolUse',
+                hooks.postToolUse && 'postToolUse',
+                hooks.preModel && 'preModel',
+                hooks.postModel && 'postModel',
+            ].filter(Boolean),
+        }));
+    }
+    async runPreToolUse(call, ctx) {
+        for (const { hooks } of this.hooks) {
+            if (hooks.preToolUse) {
+                const result = await hooks.preToolUse(call, ctx);
+                if (result)
+                    return result;
+            }
+        }
+        return undefined;
+    }
+    async runPostToolUse(outcome, ctx) {
+        let current = outcome;
+        for (const { hooks } of this.hooks) {
+            if (hooks.postToolUse) {
+                const result = await hooks.postToolUse(current, ctx);
+                if (result && typeof result === 'object') {
+                    if ('replace' in result) {
+                        current = result.replace;
+                    }
+                    else if ('update' in result) {
+                        current = { ...current, ...result.update };
+                    }
+                }
+            }
+        }
+        return current;
+    }
+    async runPreModel(request) {
+        for (const { hooks } of this.hooks) {
+            if (hooks.preModel) {
+                await hooks.preModel(request);
+            }
+        }
+    }
+    async runPostModel(response) {
+        for (const { hooks } of this.hooks) {
+            if (hooks.postModel) {
+                await hooks.postModel(response);
+            }
+        }
+    }
+    async runMessagesChanged(snapshot) {
+        for (const { hooks } of this.hooks) {
+            if (hooks.messagesChanged) {
+                await hooks.messagesChanged(snapshot);
+            }
+        }
+    }
+}
+exports.HookManager = HookManager;

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

package/dist/core/pool.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentPool = void 0;
+const agent_1 = require("./agent");
+const logger_1 = require("../utils/logger");
+class AgentPool {
+    constructor(opts) {
+        this.agents = new Map();
+        this.deps = opts.dependencies;
+        this.maxAgents = opts.maxAgents || 50;
+    }
+    async create(agentId, config) {
+        if (this.agents.has(agentId)) {
+            throw new Error(`Agent already exists: ${agentId}`);
+        }
+        if (this.agents.size >= this.maxAgents) {
+            throw new Error(`Pool is full (max ${this.maxAgents} agents)`);
+        }
+        const agent = await agent_1.Agent.create({ ...config, agentId }, this.deps);
+        this.agents.set(agentId, agent);
+        return agent;
+    }
+    get(agentId) {
+        return this.agents.get(agentId);
+    }
+    list(opts) {
+        const ids = Array.from(this.agents.keys());
+        return opts?.prefix ? ids.filter((id) => id.startsWith(opts.prefix)) : ids;
+    }
+    async status(agentId) {
+        const agent = this.agents.get(agentId);
+        return agent ? await agent.status() : undefined;
+    }
+    async fork(agentId, snapshotSel) {
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new Error(`Agent not found: ${agentId}`);
+        }
+        return agent.fork(snapshotSel);
+    }
+    async resume(agentId, config, opts) {
+        // 1. Check if already in pool
+        if (this.agents.has(agentId)) {
+            return this.agents.get(agentId);
+        }
+        // 2. Check pool capacity
+        if (this.agents.size >= this.maxAgents) {
+            throw new Error(`Pool is full (max ${this.maxAgents} agents)`);
+        }
+        // 3. Verify session exists
+        const exists = await this.deps.store.exists(agentId);
+        if (!exists) {
+            throw new Error(`Agent not found in store: ${agentId}`);
+        }
+        // 4. Use Agent.resume() to restore
+        const agent = await agent_1.Agent.resume(agentId, { ...config, agentId }, this.deps, opts);
+        // 5. Add to pool
+        this.agents.set(agentId, agent);
+        return agent;
+    }
+    async resumeAll(configFactory, opts) {
+        const agentIds = await this.deps.store.list();
+        const resumed = [];
+        for (const agentId of agentIds) {
+            if (this.agents.size >= this.maxAgents)
+                break;
+            if (this.agents.has(agentId))
+                continue;
+            try {
+                const config = configFactory(agentId);
+                const agent = await this.resume(agentId, config, opts);
+                resumed.push(agent);
+            }
+            catch (error) {
+                logger_1.logger.error(`Failed to resume ${agentId}:`, error);
+            }
+        }
+        return resumed;
+    }
+    async delete(agentId) {
+        this.agents.delete(agentId);
+        await this.deps.store.delete(agentId);
+    }
+    size() {
+        return this.agents.size;
+    }
+    /**
+     * Gracefully shutdown all agents in the pool
+     * 1. Stop accepting new operations
+     * 2. Wait for running agents to complete current step
+     * 3. Persist all agent states
+     * 4. Optionally save running agents list for recovery
+     */
+    async gracefulShutdown(opts) {
+        const startTime = Date.now();
+        const timeout = opts?.timeout ?? 30000;
+        const saveRunningList = opts?.saveRunningList ?? true;
+        const forceInterrupt = opts?.forceInterrupt ?? true;
+        const result = {
+            completed: [],
+            interrupted: [],
+            failed: [],
+            durationMs: 0,
+        };
+        const agentIds = Array.from(this.agents.keys());
+        logger_1.logger.info(`[AgentPool] Starting graceful shutdown for ${agentIds.length} agents`);
+        // Group agents by state
+        const workingAgents = [];
+        const readyAgents = [];
+        for (const [id, agent] of this.agents) {
+            const status = await agent.status();
+            if (status.state === 'WORKING') {
+                workingAgents.push({ id, agent });
+            }
+            else {
+                readyAgents.push({ id, agent });
+            }
+        }
+        // 1. Persist ready agents immediately
+        for (const { id, agent } of readyAgents) {
+            try {
+                await this.persistAgentState(agent);
+                result.completed.push(id);
+            }
+            catch (error) {
+                logger_1.logger.error(`[AgentPool] Failed to persist agent ${id}:`, error);
+                result.failed.push(id);
+            }
+        }
+        // 2. Wait for working agents with timeout
+        if (workingAgents.length > 0) {
+            logger_1.logger.info(`[AgentPool] Waiting for ${workingAgents.length} working agents...`);
+            const waitPromises = workingAgents.map(async ({ id, agent }) => {
+                try {
+                    const completed = await this.waitForAgentReady(agent, timeout);
+                    if (completed) {
+                        await this.persistAgentState(agent);
+                        return { id, status: 'completed' };
+                    }
+                    else if (forceInterrupt) {
+                        await agent.interrupt({ note: 'Graceful shutdown timeout' });
+                        await this.persistAgentState(agent);
+                        return { id, status: 'interrupted' };
+                    }
+                    else {
+                        return { id, status: 'interrupted' };
+                    }
+                }
+                catch (error) {
+                    logger_1.logger.error(`[AgentPool] Error during shutdown for agent ${id}:`, error);
+                    return { id, status: 'failed' };
+                }
+            });
+            const results = await Promise.all(waitPromises);
+            for (const { id, status } of results) {
+                if (status === 'completed') {
+                    result.completed.push(id);
+                }
+                else if (status === 'interrupted') {
+                    result.interrupted.push(id);
+                }
+                else {
+                    result.failed.push(id);
+                }
+            }
+        }
+        // 3. Save running agents list for recovery
+        if (saveRunningList) {
+            try {
+                await this.saveRunningAgentsList(agentIds);
+                logger_1.logger.info(`[AgentPool] Saved running agents list: ${agentIds.length} agents`);
+            }
+            catch (error) {
+                logger_1.logger.error(`[AgentPool] Failed to save running agents list:`, error);
+            }
+        }
+        result.durationMs = Date.now() - startTime;
+        logger_1.logger.info(`[AgentPool] Graceful shutdown completed in ${result.durationMs}ms`, {
+            completed: result.completed.length,
+            interrupted: result.interrupted.length,
+            failed: result.failed.length,
+        });
+        return result;
+    }
+    /**
+     * Resume agents from a previous graceful shutdown
+     * Reads the running agents list and resumes each agent
+     */
+    async resumeFromShutdown(configFactory, opts) {
+        const runningList = await this.loadRunningAgentsList();
+        if (!runningList || runningList.length === 0) {
+            logger_1.logger.info('[AgentPool] No running agents list found, nothing to resume');
+            return [];
+        }
+        logger_1.logger.info(`[AgentPool] Resuming ${runningList.length} agents from shutdown`);
+        const resumed = [];
+        for (const agentId of runningList) {
+            if (this.agents.size >= this.maxAgents) {
+                logger_1.logger.warn(`[AgentPool] Pool is full, cannot resume more agents`);
+                break;
+            }
+            try {
+                const config = configFactory(agentId);
+                const agent = await this.resume(agentId, config, {
+                    autoRun: opts?.autoRun ?? false,
+                    strategy: opts?.strategy ?? 'crash',
+                });
+                resumed.push(agent);
+            }
+            catch (error) {
+                logger_1.logger.error(`[AgentPool] Failed to resume agent ${agentId}:`, error);
+            }
+        }
+        // Clear the running agents list after successful resume
+        await this.clearRunningAgentsList();
+        logger_1.logger.info(`[AgentPool] Resumed ${resumed.length}/${runningList.length} agents`);
+        return resumed;
+    }
+    /**
+     * Register signal handlers for graceful shutdown
+     * Call this in your server setup code
+     */
+    registerShutdownHandlers(configFactory, opts) {
+        const handler = async (signal) => {
+            logger_1.logger.info(`[AgentPool] Received ${signal}, initiating graceful shutdown...`);
+            try {
+                const result = await this.gracefulShutdown(opts);
+                logger_1.logger.info(`[AgentPool] Shutdown complete:`, result);
+                process.exit(0);
+            }
+            catch (error) {
+                logger_1.logger.error(`[AgentPool] Shutdown failed:`, error);
+                process.exit(1);
+            }
+        };
+        process.on('SIGTERM', () => handler('SIGTERM'));
+        process.on('SIGINT', () => handler('SIGINT'));
+        logger_1.logger.info('[AgentPool] Shutdown handlers registered for SIGTERM and SIGINT');
+    }
+    // ========== Private Helper Methods ==========
+    async waitForAgentReady(agent, timeout) {
+        const startTime = Date.now();
+        const pollInterval = 100; // ms
+        while (Date.now() - startTime < timeout) {
+            const status = await agent.status();
+            if (status.state !== 'WORKING') {
+                return true;
+            }
+            await this.sleep(pollInterval);
+        }
+        return false;
+    }
+    async persistAgentState(agent) {
+        // Agent's internal persist methods are private, so we rely on the fact that
+        // state is automatically persisted during normal operation.
+        // This is a no-op placeholder for potential future explicit persist calls.
+        // The agent's state is already persisted via WAL mechanism.
+    }
+    async saveRunningAgentsList(agentIds) {
+        const meta = {
+            agentIds,
+            shutdownAt: new Date().toISOString(),
+            version: '1.0.0',
+        };
+        // Use the store's saveInfo to persist to a special key
+        // We use a well-known agent ID prefix for pool metadata
+        const poolMetaId = '__pool_meta__';
+        await this.deps.store.saveInfo(poolMetaId, {
+            agentId: poolMetaId,
+            templateId: '__pool_meta__',
+            createdAt: new Date().toISOString(),
+            runningAgents: meta,
+        });
+    }
+    async loadRunningAgentsList() {
+        const poolMetaId = '__pool_meta__';
+        try {
+            const info = await this.deps.store.loadInfo(poolMetaId);
+            if (info && info.runningAgents) {
+                return info.runningAgents.agentIds;
+            }
+        }
+        catch {
+            // Ignore errors, return null
+        }
+        return null;
+    }
+    async clearRunningAgentsList() {
+        const poolMetaId = '__pool_meta__';
+        try {
+            await this.deps.store.delete(poolMetaId);
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.AgentPool = AgentPool;

package/dist/core/room.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Room = void 0;
+class Room {
+    constructor(pool) {
+        this.pool = pool;
+        this.members = new Map();
+    }
+    join(name, agentId) {
+        if (this.members.has(name)) {
+            throw new Error(`Member already exists: ${name}`);
+        }
+        this.members.set(name, agentId);
+    }
+    leave(name) {
+        this.members.delete(name);
+    }
+    async say(from, text) {
+        const mentions = this.extractMentions(text);
+        if (mentions.length > 0) {
+            // Directed message
+            for (const mention of mentions) {
+                const agentId = this.members.get(mention);
+                if (agentId) {
+                    const agent = this.pool.get(agentId);
+                    if (agent) {
+                        await agent.complete(`[from:${from}] ${text}`);
+                    }
+                }
+            }
+        }
+        else {
+            // Broadcast to all except sender
+            for (const [name, agentId] of this.members) {
+                if (name !== from) {
+                    const agent = this.pool.get(agentId);
+                    if (agent) {
+                        await agent.complete(`[from:${from}] ${text}`);
+                    }
+                }
+            }
+        }
+    }
+    getMembers() {
+        return Array.from(this.members.entries()).map(([name, agentId]) => ({ name, agentId }));
+    }
+    extractMentions(text) {
+        const regex = /@(\w+)/g;
+        const mentions = [];
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            mentions.push(match[1]);
+        }
+        return mentions;
+    }
+}
+exports.Room = Room;

package/dist/core/scheduler.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scheduler = void 0;
+class Scheduler {
+    constructor(opts) {
+        this.stepTasks = new Map();
+        this.listeners = new Set();
+        this.queued = Promise.resolve();
+        this.onTrigger = opts?.onTrigger;
+    }
+    everySteps(every, callback) {
+        if (!Number.isFinite(every) || every <= 0) {
+            throw new Error('everySteps: interval must be positive');
+        }
+        const id = this.generateId('steps');
+        this.stepTasks.set(id, {
+            id,
+            every,
+            callback,
+            lastTriggered: 0,
+        });
+        return id;
+    }
+    onStep(callback) {
+        this.listeners.add(callback);
+        return () => this.listeners.delete(callback);
+    }
+    enqueue(callback) {
+        this.queued = this.queued.then(() => Promise.resolve(callback())).catch(() => undefined);
+    }
+    notifyStep(stepCount) {
+        for (const listener of this.listeners) {
+            void Promise.resolve(listener({ stepCount }));
+        }
+        for (const task of this.stepTasks.values()) {
+            const shouldTrigger = stepCount - task.lastTriggered >= task.every;
+            if (!shouldTrigger)
+                continue;
+            task.lastTriggered = stepCount;
+            void Promise.resolve(task.callback({ stepCount }));
+            this.onTrigger?.({ taskId: task.id, spec: `steps:${task.every}`, kind: 'steps' });
+        }
+    }
+    cancel(taskId) {
+        this.stepTasks.delete(taskId);
+    }
+    clear() {
+        this.stepTasks.clear();
+        this.listeners.clear();
+    }
+    notifyExternalTrigger(info) {
+        this.onTrigger?.(info);
+    }
+    generateId(prefix) {
+        return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    }
+}
+exports.Scheduler = Scheduler;

package/dist/core/skills/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Skills 模块导出
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxFileManager = exports.OperationStatus = exports.OperationType = exports.OperationQueue = exports.SkillsManagementManager = exports.generateSkillsMetadataXml = exports.SkillsManager = void 0;
+// 路径2: Agent使用（现有模块）
+var manager_1 = require("./manager");
+Object.defineProperty(exports, "SkillsManager", { enumerable: true, get: function () { return manager_1.SkillsManager; } });
+var xml_generator_1 = require("./xml-generator");
+Object.defineProperty(exports, "generateSkillsMetadataXml", { enumerable: true, get: function () { return xml_generator_1.generateSkillsMetadataXml; } });
+// 路径1: 技能管理（新增模块）
+var management_manager_1 = require("./management-manager");
+Object.defineProperty(exports, "SkillsManagementManager", { enumerable: true, get: function () { return management_manager_1.SkillsManagementManager; } });
+var operation_queue_1 = require("./operation-queue");
+Object.defineProperty(exports, "OperationQueue", { enumerable: true, get: function () { return operation_queue_1.OperationQueue; } });
+Object.defineProperty(exports, "OperationType", { enumerable: true, get: function () { return operation_queue_1.OperationType; } });
+Object.defineProperty(exports, "OperationStatus", { enumerable: true, get: function () { return operation_queue_1.OperationStatus; } });
+var sandbox_file_manager_1 = require("./sandbox-file-manager");
+Object.defineProperty(exports, "SandboxFileManager", { enumerable: true, get: function () { return sandbox_file_manager_1.SandboxFileManager; } });