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

package/dist/core/pool.d.ts

@@ -1,33 +1,76 @@
-import { Agent, AgentOptions } from '../core/agent';
-import { Store } from '../infra/store';
-import { AgentTemplate } from '../tools/task';
-import { AgentStatus, SnapshotId } from '../core/types';
+import { Agent, AgentConfig, AgentDependencies } from './agent';
+import { AgentStatus, SnapshotId } from './types';
 export interface AgentPoolOptions {
-    store: Store;
+    dependencies: AgentDependencies;
     maxAgents?: number;
 }
+export interface GracefulShutdownOptions {
+    /** Maximum time to wait for agents to complete current step (ms), default 30000 */
+    timeout?: number;
+    /** Save running agents list for resumeFromShutdown(), default true */
+    saveRunningList?: boolean;
+    /** Force interrupt agents that don't complete within timeout, default true */
+    forceInterrupt?: boolean;
+}
+export interface ShutdownResult {
+    /** Agents that completed gracefully */
+    completed: string[];
+    /** Agents that were interrupted due to timeout */
+    interrupted: string[];
+    /** Agents that failed to save state */
+    failed: string[];
+    /** Total shutdown time in ms */
+    durationMs: number;
+}
 export declare class AgentPool {
     private agents;
-    private store;
+    private deps;
     private maxAgents;
     constructor(opts: AgentPoolOptions);
-    create(sessionId: string, templateOrOpts: AgentTemplate | AgentOptions, overrides?: Partial<AgentOptions>): Agent;
-    get(sessionId: string): Agent | undefined;
+    create(agentId: string, config: AgentConfig): Promise<Agent>;
+    get(agentId: string): Agent | undefined;
     list(opts?: {
         prefix?: string;
     }): string[];
-    status(sessionId: string): Promise<AgentStatus | undefined>;
-    fork(sessionId: string, snapshotSel?: SnapshotId | {
+    status(agentId: string): Promise<AgentStatus | undefined>;
+    fork(agentId: string, snapshotSel?: SnapshotId | {
         at?: string;
     }): Promise<Agent>;
-    resume(sessionId: string, opts: Omit<AgentOptions, 'sessionId' | 'store'> & {
+    resume(agentId: string, config: AgentConfig, opts?: {
         autoRun?: boolean;
         strategy?: 'crash' | 'manual';
     }): Promise<Agent>;
-    resumeAll(configFactory: (sessionId: string) => Omit<AgentOptions, 'sessionId' | 'store'>, opts?: {
+    resumeAll(configFactory: (agentId: string) => AgentConfig, opts?: {
         autoRun?: boolean;
         strategy?: 'crash' | 'manual';
     }): Promise<Agent[]>;
-    delete(sessionId: string): Promise<void>;
+    delete(agentId: string): Promise<void>;
     size(): number;
+    /**
+     * 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
+     */
+    gracefulShutdown(opts?: GracefulShutdownOptions): Promise<ShutdownResult>;
+    /**
+     * Resume agents from a previous graceful shutdown
+     * Reads the running agents list and resumes each agent
+     */
+    resumeFromShutdown(configFactory: (agentId: string) => AgentConfig, opts?: {
+        autoRun?: boolean;
+        strategy?: 'crash' | 'manual';
+    }): Promise<Agent[]>;
+    /**
+     * Register signal handlers for graceful shutdown
+     * Call this in your server setup code
+     */
+    registerShutdownHandlers(configFactory?: (agentId: string) => AgentConfig, opts?: GracefulShutdownOptions): void;
+    private waitForAgentReady;
+    private persistAgentState;
+    private saveRunningAgentsList;
+    private loadRunningAgentsList;
+    private clearRunningAgentsList;
+    private sleep;
 }

package/dist/core/pool.js

@@ -1,91 +1,301 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentPool = void 0;
-const agent_1 = require("../core/agent");
+const agent_1 = require("./agent");
+const logger_1 = require("../utils/logger");
 class AgentPool {
     constructor(opts) {
         this.agents = new Map();
-        this.store = opts.store;
+        this.deps = opts.dependencies;
         this.maxAgents = opts.maxAgents || 50;
     }
-    create(sessionId, templateOrOpts, overrides) {
-        if (this.agents.has(sessionId)) {
-            throw new Error(`Agent already exists: ${sessionId}`);
+    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 = new agent_1.Agent(templateOrOpts, overrides);
-        this.agents.set(sessionId, agent);
+        const agent = await agent_1.Agent.create({ ...config, agentId }, this.deps);
+        this.agents.set(agentId, agent);
         return agent;
     }
-    get(sessionId) {
-        return this.agents.get(sessionId);
+    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(sessionId) {
-        const agent = this.agents.get(sessionId);
+    async status(agentId) {
+        const agent = this.agents.get(agentId);
         return agent ? await agent.status() : undefined;
     }
-    async fork(sessionId, snapshotSel) {
-        const agent = this.agents.get(sessionId);
+    async fork(agentId, snapshotSel) {
+        const agent = this.agents.get(agentId);
         if (!agent) {
-            throw new Error(`Agent not found: ${sessionId}`);
+            throw new Error(`Agent not found: ${agentId}`);
         }
         return agent.fork(snapshotSel);
     }
-    async resume(sessionId, opts) {
+    async resume(agentId, config, opts) {
         // 1. Check if already in pool
-        if (this.agents.has(sessionId)) {
-            return this.agents.get(sessionId);
+        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.store.exists(sessionId);
+        const exists = await this.deps.store.exists(agentId);
         if (!exists) {
-            throw new Error(`Session not found in store: ${sessionId}`);
+            throw new Error(`Agent not found in store: ${agentId}`);
         }
         // 4. Use Agent.resume() to restore
-        const agent = await agent_1.Agent.resume(sessionId, {
-            ...opts,
-            sessionId,
-            store: this.store,
-        });
+        const agent = await agent_1.Agent.resume(agentId, { ...config, agentId }, this.deps, opts);
         // 5. Add to pool
-        this.agents.set(sessionId, agent);
+        this.agents.set(agentId, agent);
         return agent;
     }
     async resumeAll(configFactory, opts) {
-        const sessionIds = await this.store.list();
+        const agentIds = await this.deps.store.list();
         const resumed = [];
-        for (const sessionId of sessionIds) {
+        for (const agentId of agentIds) {
             if (this.agents.size >= this.maxAgents)
                 break;
-            if (this.agents.has(sessionId))
+            if (this.agents.has(agentId))
                 continue;
             try {
-                const config = configFactory(sessionId);
-                const agent = await this.resume(sessionId, { ...config, ...opts });
+                const config = configFactory(agentId);
+                const agent = await this.resume(agentId, config, opts);
                 resumed.push(agent);
             }
             catch (error) {
-                console.error(`Failed to resume ${sessionId}:`, error);
+                logger_1.logger.error(`Failed to resume ${agentId}:`, error);
             }
         }
         return resumed;
     }
-    async delete(sessionId) {
-        this.agents.delete(sessionId);
-        await this.store.delete(sessionId);
+    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.d.ts

@@ -1,13 +1,13 @@
 import { AgentPool } from '../core/pool';
 export interface RoomMember {
     name: string;
-    sessionId: string;
+    agentId: string;
 }
 export declare class Room {
     private pool;
     private members;
     constructor(pool: AgentPool);
-    join(name: string, sessionId: string): void;
+    join(name: string, agentId: string): void;
     leave(name: string): void;
     say(from: string, text: string): Promise<void>;
     getMembers(): RoomMember[];

package/dist/core/room.js

@@ -6,11 +6,11 @@ class Room {
         this.pool = pool;
         this.members = new Map();
     }
-    join(name, sessionId) {
+    join(name, agentId) {
         if (this.members.has(name)) {
             throw new Error(`Member already exists: ${name}`);
         }
-        this.members.set(name, sessionId);
+        this.members.set(name, agentId);
     }
     leave(name) {
         this.members.delete(name);
@@ -20,29 +20,29 @@ class Room {
         if (mentions.length > 0) {
             // Directed message
             for (const mention of mentions) {
-                const sessionId = this.members.get(mention);
-                if (sessionId) {
-                    const agent = this.pool.get(sessionId);
+                const agentId = this.members.get(mention);
+                if (agentId) {
+                    const agent = this.pool.get(agentId);
                     if (agent) {
-                        await agent.send(`[from:${from}] ${text}`);
+                        await agent.complete(`[from:${from}] ${text}`);
                     }
                 }
             }
         }
         else {
             // Broadcast to all except sender
-            for (const [name, sessionId] of this.members) {
+            for (const [name, agentId] of this.members) {
                 if (name !== from) {
-                    const agent = this.pool.get(sessionId);
+                    const agent = this.pool.get(agentId);
                     if (agent) {
-                        await agent.send(`[from:${from}] ${text}`);
+                        await agent.complete(`[from:${from}] ${text}`);
                     }
                 }
             }
         }
     }
     getMembers() {
-        return Array.from(this.members.entries()).map(([name, sessionId]) => ({ name, sessionId }));
+        return Array.from(this.members.entries()).map(([name, agentId]) => ({ name, agentId }));
     }
     extractMentions(text) {
         const regex = /@(\w+)/g;

package/dist/core/scheduler.d.ts

@@ -1,26 +1,33 @@
-type TimeInterval = string;
-type ScheduleCallback = (ctx?: any) => void | Promise<void>;
-export declare class Scheduler {
-    private tasks;
-    private stepCounters;
-    private timers;
-    every(interval: TimeInterval, callback: ScheduleCallback): this;
-    everySteps(steps: number, callback: ScheduleCallback, targetId?: string): this;
-    daily(time: string, callback: ScheduleCallback): this;
-    weekly(dayTime: string, callback: ScheduleCallback): this;
-    notifyStep(targetId?: string): void;
-    stop(): void;
-    private parseInterval;
-    private scheduleDailyTask;
-    private scheduleWeeklyTask;
+type StepCallback = (ctx: {
+    stepCount: number;
+}) => void | Promise<void>;
+type TaskCallback = () => void | Promise<void>;
+export type AgentSchedulerHandle = string;
+type TriggerKind = 'steps' | 'time' | 'cron';
+interface SchedulerOptions {
+    onTrigger?: (info: {
+        taskId: string;
+        spec: string;
+        kind: TriggerKind;
+    }) => void;
 }
-export declare class AgentSchedulerHandle {
-    private scheduler;
-    private agentId?;
-    constructor(scheduler: Scheduler, agentId?: string | undefined);
-    every(interval: TimeInterval, callback: ScheduleCallback): this;
-    everySteps(steps: number, callback: ScheduleCallback): this;
-    daily(time: string, callback: ScheduleCallback): this;
-    weekly(dayTime: string, callback: ScheduleCallback): this;
+export declare class Scheduler {
+    private readonly stepTasks;
+    private readonly listeners;
+    private queued;
+    private readonly onTrigger?;
+    constructor(opts?: SchedulerOptions);
+    everySteps(every: number, callback: StepCallback): AgentSchedulerHandle;
+    onStep(callback: StepCallback): () => void;
+    enqueue(callback: TaskCallback): void;
+    notifyStep(stepCount: number): void;
+    cancel(taskId: AgentSchedulerHandle): void;
+    clear(): void;
+    notifyExternalTrigger(info: {
+        taskId: string;
+        spec: string;
+        kind: 'time' | 'cron';
+    }): void;
+    private generateId;
 }
 export {};