kode-sdk 2.7.0

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

package/dist/core/pool.d.ts

@@ -0,0 +1,31 @@
+import { Agent, AgentConfig, AgentDependencies } from './agent';
+import { AgentStatus, SnapshotId } from './types';
+export interface AgentPoolOptions {
+    dependencies: AgentDependencies;
+    maxAgents?: number;
+}
+export declare class AgentPool {
+    private agents;
+    private deps;
+    private maxAgents;
+    constructor(opts: AgentPoolOptions);
+    create(agentId: string, config: AgentConfig): Promise<Agent>;
+    get(agentId: string): Agent | undefined;
+    list(opts?: {
+        prefix?: string;
+    }): string[];
+    status(agentId: string): Promise<AgentStatus | undefined>;
+    fork(agentId: string, snapshotSel?: SnapshotId | {
+        at?: string;
+    }): Promise<Agent>;
+    resume(agentId: string, config: AgentConfig, opts?: {
+        autoRun?: boolean;
+        strategy?: 'crash' | 'manual';
+    }): Promise<Agent>;
+    resumeAll(configFactory: (agentId: string) => AgentConfig, opts?: {
+        autoRun?: boolean;
+        strategy?: 'crash' | 'manual';
+    }): Promise<Agent[]>;
+    delete(agentId: string): Promise<void>;
+    size(): number;
+}

package/dist/core/pool.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentPool = void 0;
+const agent_1 = require("./agent");
+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) {
+                console.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;
+    }
+}
+exports.AgentPool = AgentPool;

package/dist/core/room.d.ts

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

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.d.ts

@@ -0,0 +1,33 @@
+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 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 {};

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/template.d.ts

@@ -0,0 +1,69 @@
+import { Hooks } from './hooks';
+export type PermissionDecisionMode = 'auto' | 'approval' | 'readonly' | (string & {});
+export interface PermissionConfig {
+    mode: PermissionDecisionMode;
+    requireApprovalTools?: string[];
+    allowTools?: string[];
+    denyTools?: string[];
+    metadata?: Record<string, any>;
+}
+export interface SubAgentConfig {
+    templates?: string[];
+    depth: number;
+    inheritConfig?: boolean;
+    overrides?: {
+        permission?: PermissionConfig;
+        todo?: TodoConfig;
+    };
+}
+export interface TodoConfig {
+    enabled: boolean;
+    remindIntervalSteps?: number;
+    storagePath?: string;
+    reminderOnStart?: boolean;
+}
+export interface AgentTemplateDefinition {
+    id: string;
+    name?: string;
+    desc?: string;
+    version?: string;
+    systemPrompt: string;
+    model?: string;
+    sandbox?: Record<string, any>;
+    tools?: '*' | string[];
+    permission?: PermissionConfig;
+    runtime?: TemplateRuntimeConfig;
+    hooks?: Hooks;
+    metadata?: Record<string, any>;
+}
+/**
+ * Skills 自动激活配置
+ */
+export interface TemplateSkillsConfig {
+    /** 启动时自动激活的 Skills（核心 Skills） */
+    autoActivate?: string[];
+    /** 推荐激活的 Skills（在系统提示中显示推荐） */
+    recommend?: string[];
+    /**
+     * 强制启用的 Skills（不可被用户关闭）。
+     *
+     * 若未指定，默认等同于 autoActivate（即：自动激活的核心技能默认视为必需）。
+     */
+    locked?: string[];
+}
+export interface TemplateRuntimeConfig {
+    exposeThinking?: boolean;
+    todo?: TodoConfig;
+    subagents?: SubAgentConfig;
+    /** Skills 自动激活配置 */
+    skills?: TemplateSkillsConfig;
+    metadata?: Record<string, any>;
+}
+export declare class AgentTemplateRegistry {
+    private templates;
+    register(template: AgentTemplateDefinition): void;
+    bulkRegister(templates: AgentTemplateDefinition[]): void;
+    has(id: string): boolean;
+    get(id: string): AgentTemplateDefinition;
+    list(): AgentTemplateDefinition[];
+}

package/dist/core/template.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTemplateRegistry = void 0;
+class AgentTemplateRegistry {
+    constructor() {
+        this.templates = new Map();
+    }
+    register(template) {
+        if (!template.id)
+            throw new Error('Template id is required');
+        if (!template.systemPrompt || !template.systemPrompt.trim()) {
+            throw new Error(`Template ${template.id} must provide a non-empty systemPrompt`);
+        }
+        this.templates.set(template.id, template);
+    }
+    bulkRegister(templates) {
+        for (const tpl of templates) {
+            this.register(tpl);
+        }
+    }
+    has(id) {
+        return this.templates.has(id);
+    }
+    get(id) {
+        const tpl = this.templates.get(id);
+        if (!tpl) {
+            throw new Error(`Template not found: ${id}`);
+        }
+        return tpl;
+    }
+    list() {
+        return Array.from(this.templates.values());
+    }
+}
+exports.AgentTemplateRegistry = AgentTemplateRegistry;

package/dist/core/time-bridge.d.ts

@@ -0,0 +1,18 @@
+import { Scheduler } from './scheduler';
+export interface TimeBridgeOptions {
+    scheduler: Scheduler;
+    driftToleranceMs?: number;
+    logger?: (msg: string, meta?: Record<string, any>) => void;
+}
+export declare class TimeBridge {
+    private readonly scheduler;
+    private readonly driftTolerance;
+    private readonly logger?;
+    private readonly timers;
+    constructor(opts: TimeBridgeOptions);
+    everyMinutes(minutes: number, callback: () => void | Promise<void>): string;
+    cron(expr: string, callback: () => void | Promise<void>): string;
+    stop(timerId: string): void;
+    dispose(): void;
+    private generateId;
+}

package/dist/core/time-bridge.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeBridge = void 0;
+class TimeBridge {
+    constructor(opts) {
+        this.timers = new Map();
+        this.scheduler = opts.scheduler;
+        this.driftTolerance = opts.driftToleranceMs ?? 5000;
+        this.logger = opts.logger;
+    }
+    everyMinutes(minutes, callback) {
+        if (!Number.isFinite(minutes) || minutes <= 0) {
+            throw new Error('everyMinutes: interval must be positive');
+        }
+        const interval = minutes * 60 * 1000;
+        const id = this.generateId('minutes');
+        const scheduleNext = () => {
+            const due = Date.now() + interval;
+            const handle = setTimeout(() => tick(due), interval);
+            entry.cancel = () => clearTimeout(handle);
+        };
+        const spec = `every:${minutes}m`;
+        const tick = (due) => {
+            this.scheduler.enqueue(async () => {
+                const drift = Math.abs(Date.now() - due);
+                if (drift > this.driftTolerance) {
+                    this.logger?.('timebridge:drift', { id, drift, expectedInterval: interval });
+                }
+                await callback();
+                this.scheduler.notifyExternalTrigger({ taskId: id, spec, kind: 'time' });
+            });
+            scheduleNext();
+        };
+        const entry = {
+            id,
+            cancel: () => undefined,
+        };
+        this.timers.set(id, entry);
+        scheduleNext();
+        return id;
+    }
+    cron(expr, callback) {
+        const parts = expr.trim().split(/\s+/);
+        if (parts.length !== 5) {
+            throw new Error(`Unsupported cron expression: ${expr}`);
+        }
+        const minute = Number(parts[0]);
+        const hour = Number(parts[1]);
+        if (!Number.isInteger(minute) || !Number.isInteger(hour)) {
+            throw new Error(`Cron expression must be numeric minutes/hours: ${expr}`);
+        }
+        const id = this.generateId('cron');
+        const scheduleNext = () => {
+            const now = new Date();
+            const next = new Date(now.getFullYear(), now.getMonth(), now.getDate(), hour, minute, 0, 0);
+            if (next <= now) {
+                next.setDate(next.getDate() + 1);
+            }
+            const due = next.getTime();
+            const delay = Math.max(0, due - Date.now());
+            const handle = setTimeout(() => tick(due), delay);
+            entry.cancel = () => clearTimeout(handle);
+        };
+        const tick = (due) => {
+            this.scheduler.enqueue(async () => {
+                const drift = Math.abs(Date.now() - due);
+                if (drift > this.driftTolerance) {
+                    this.logger?.('timebridge:drift', { id, drift, spec: expr });
+                }
+                await callback();
+                this.scheduler.notifyExternalTrigger({ taskId: id, spec: expr, kind: 'cron' });
+            });
+            scheduleNext();
+        };
+        const entry = {
+            id,
+            cancel: () => undefined,
+        };
+        this.timers.set(id, entry);
+        scheduleNext();
+        return id;
+    }
+    stop(timerId) {
+        const entry = this.timers.get(timerId);
+        if (!entry)
+            return;
+        entry.cancel();
+        this.timers.delete(timerId);
+    }
+    dispose() {
+        for (const entry of this.timers.values()) {
+            entry.cancel();
+        }
+        this.timers.clear();
+    }
+    generateId(prefix) {
+        return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    }
+}
+exports.TimeBridge = TimeBridge;