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

package/dist/core/agent/message-queue.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageQueue = void 0;
+const logger_1 = require("../../utils/logger");
+const errors_1 = require("../errors");
+class MessageQueue {
+    constructor(options) {
+        this.options = options;
+        this.pending = [];
+    }
+    send(content, opts = {}) {
+        const kind = opts.kind ?? 'user';
+        const isText = typeof content === 'string';
+        if (kind === 'reminder' && !isText) {
+            throw new errors_1.MultimodalValidationError('Reminder messages must be plain text.');
+        }
+        const payload = isText
+            ? kind === 'reminder'
+                ? this.options.wrapReminder(content, opts.reminder)
+                : content
+            : content;
+        const id = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        this.pending.push({
+            message: {
+                role: 'user',
+                content: isText ? [{ type: 'text', text: payload }] : payload,
+            },
+            kind,
+            metadata: { id, ...(opts.metadata || {}) },
+        });
+        if (kind === 'user') {
+            this.options.ensureProcessing();
+        }
+        return id;
+    }
+    async flush() {
+        if (this.pending.length === 0)
+            return;
+        const queue = this.pending;
+        try {
+            // 先添加到消息历史
+            for (const entry of queue) {
+                this.options.addMessage(entry.message, entry.kind);
+            }
+            // 持久化成功后才清空队列
+            await this.options.persist();
+            // 成功：从队列中移除已处理的消息
+            this.pending = this.pending.filter(item => !queue.includes(item));
+        }
+        catch (err) {
+            // 失败：保留队列，下次重试
+            logger_1.logger.error('[MessageQueue] Flush failed, messages retained:', err);
+            throw err; // 重新抛出让调用者知道失败
+        }
+    }
+}
+exports.MessageQueue = MessageQueue;

package/dist/core/agent/permission-manager.d.ts

@@ -0,0 +1,9 @@
+import { PermissionConfig } from '../template';
+import { ToolDescriptor } from '../../tools/registry';
+import { PermissionDecision } from '../permission-modes';
+export declare class PermissionManager {
+    private readonly config;
+    private readonly descriptors;
+    constructor(config: PermissionConfig, descriptors: Map<string, ToolDescriptor>);
+    evaluate(toolName: string): PermissionDecision;
+}

package/dist/core/agent/permission-manager.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionManager = void 0;
+const permission_modes_1 = require("../permission-modes");
+class PermissionManager {
+    constructor(config, descriptors) {
+        this.config = config;
+        this.descriptors = descriptors;
+    }
+    evaluate(toolName) {
+        if (this.config.denyTools?.includes(toolName)) {
+            return 'deny';
+        }
+        if (this.config.allowTools && this.config.allowTools.length > 0 && !this.config.allowTools.includes(toolName)) {
+            return 'deny';
+        }
+        if (this.config.requireApprovalTools?.includes(toolName)) {
+            return 'ask';
+        }
+        const handler = permission_modes_1.permissionModes.get(this.config.mode || 'auto') || permission_modes_1.permissionModes.get('auto');
+        if (!handler) {
+            return 'allow';
+        }
+        const context = {
+            toolName,
+            descriptor: this.descriptors.get(toolName),
+            config: this.config,
+        };
+        return handler(context);
+    }
+}
+exports.PermissionManager = PermissionManager;

package/dist/core/agent/todo-manager.d.ts

@@ -0,0 +1,26 @@
+import { TodoService, TodoInput, TodoItem } from '../todo';
+import { TodoConfig } from '../template';
+import { ReminderOptions } from '../types';
+import { EventBus } from '../events';
+export interface TodoManagerOptions {
+    service?: TodoService;
+    config?: TodoConfig;
+    events: EventBus;
+    remind: (content: string, options?: ReminderOptions) => void;
+}
+export declare class TodoManager {
+    private readonly opts;
+    private stepsSinceReminder;
+    constructor(opts: TodoManagerOptions);
+    get enabled(): boolean;
+    list(): TodoItem[];
+    setTodos(todos: TodoInput[]): Promise<void>;
+    update(todo: TodoInput): Promise<void>;
+    remove(id: string): Promise<void>;
+    handleStartup(): void;
+    onStep(): void;
+    private publishChange;
+    private sendReminder;
+    private sendEmptyReminder;
+    private formatTodoReminder;
+}

package/dist/core/agent/todo-manager.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TodoManager = void 0;
+class TodoManager {
+    constructor(opts) {
+        this.opts = opts;
+        this.stepsSinceReminder = 0;
+    }
+    get enabled() {
+        return !!this.opts.service && !!this.opts.config?.enabled;
+    }
+    list() {
+        return this.opts.service ? this.opts.service.list() : [];
+    }
+    async setTodos(todos) {
+        if (!this.opts.service)
+            throw new Error('Todo service not enabled for this agent');
+        const prev = this.opts.service.list();
+        await this.opts.service.setTodos(todos);
+        this.publishChange(prev, this.opts.service.list());
+    }
+    async update(todo) {
+        if (!this.opts.service)
+            throw new Error('Todo service not enabled for this agent');
+        const prev = this.opts.service.list();
+        await this.opts.service.update(todo);
+        this.publishChange(prev, this.opts.service.list());
+    }
+    async remove(id) {
+        if (!this.opts.service)
+            throw new Error('Todo service not enabled for this agent');
+        const prev = this.opts.service.list();
+        await this.opts.service.delete(id);
+        this.publishChange(prev, this.opts.service.list());
+    }
+    handleStartup() {
+        if (!this.enabled || !this.opts.config?.reminderOnStart)
+            return;
+        const todos = this.list().filter((todo) => todo.status !== 'completed');
+        if (todos.length === 0) {
+            this.sendEmptyReminder();
+        }
+        else {
+            this.sendReminder(todos, 'startup');
+        }
+    }
+    onStep() {
+        if (!this.enabled)
+            return;
+        if (!this.opts.config?.remindIntervalSteps)
+            return;
+        if (this.opts.config.remindIntervalSteps <= 0)
+            return;
+        this.stepsSinceReminder += 1;
+        if (this.stepsSinceReminder < this.opts.config.remindIntervalSteps)
+            return;
+        const todos = this.list().filter((todo) => todo.status !== 'completed');
+        if (todos.length === 0)
+            return;
+        this.sendReminder(todos, 'interval');
+    }
+    publishChange(previous, current) {
+        if (!this.opts.events)
+            return;
+        this.stepsSinceReminder = 0;
+        this.opts.events.emitMonitor({ channel: 'monitor', type: 'todo_changed', previous, current });
+        if (current.length === 0) {
+            this.sendEmptyReminder();
+        }
+    }
+    sendReminder(todos, reason) {
+        this.stepsSinceReminder = 0;
+        this.opts.events.emitMonitor({ channel: 'monitor', type: 'todo_reminder', todos, reason });
+        this.opts.remind(this.formatTodoReminder(todos), { category: 'todo', priority: 'medium' });
+    }
+    sendEmptyReminder() {
+        this.opts.remind('当前 todo 列表为空，如需跟踪任务请使用 todo_write 建立清单。', {
+            category: 'todo',
+            priority: 'low',
+        });
+    }
+    formatTodoReminder(todos) {
+        const bulletList = todos
+            .slice(0, 10)
+            .map((todo, index) => `${index + 1}. [${todo.status}] ${todo.title}`)
+            .join('\n');
+        const more = todos.length > 10 ? `\n… 还有 ${todos.length - 10} 项` : '';
+        return `Todo 列表仍有未完成项：\n${bulletList}${more}\n请结合 todo_write 及时更新进度，不要向用户直接提及本提醒。`;
+    }
+}
+exports.TodoManager = TodoManager;

package/dist/core/agent/tool-runner.d.ts

@@ -0,0 +1,9 @@
+export declare class ToolRunner {
+    private readonly concurrency;
+    private active;
+    private readonly queue;
+    constructor(concurrency: number);
+    run<T>(task: () => Promise<T>): Promise<T>;
+    clear(): void;
+    private flush;
+}

package/dist/core/agent/tool-runner.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRunner = void 0;
+class ToolRunner {
+    constructor(concurrency) {
+        this.concurrency = concurrency;
+        this.active = 0;
+        this.queue = [];
+        if (!Number.isFinite(concurrency) || concurrency <= 0) {
+            throw new Error('ToolRunner requires a positive concurrency limit');
+        }
+    }
+    run(task) {
+        return new Promise((resolve, reject) => {
+            const execute = () => {
+                this.active += 1;
+                task()
+                    .then(resolve, reject)
+                    .finally(() => {
+                    this.active -= 1;
+                    this.flush();
+                });
+            };
+            if (this.active < this.concurrency) {
+                execute();
+            }
+            else {
+                this.queue.push(execute);
+            }
+        });
+    }
+    clear() {
+        this.queue.length = 0;
+    }
+    flush() {
+        if (this.queue.length === 0)
+            return;
+        if (this.active >= this.concurrency)
+            return;
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+}
+exports.ToolRunner = ToolRunner;

package/dist/core/agent.d.ts

@@ -1,85 +1,251 @@
-import { AgentStatus, AgentInfo, AgentEvent, SubscribeOptions, SnapshotId } from './types';
+import { AgentEvent, AgentEventEnvelope, AgentInfo, AgentStatus, Bookmark, ContentBlock, ControlEvent, MonitorEvent, ProgressEvent, ReminderOptions, ResumeStrategy, SnapshotId } from './types';
 import { Hooks } from './hooks';
 import { Scheduler } from './scheduler';
-import { Provider } from '../infra/provider';
+import { TodoInput, TodoItem } from './todo';
+import { AgentTemplateRegistry, AgentTemplateDefinition, PermissionConfig, SubAgentConfig, TodoConfig } from './template';
 import { Store } from '../infra/store';
-import { Sandbox } from '../infra/sandbox';
-import { Tool } from '../tools/fs';
-import { AgentTemplate } from '../tools/task';
-export interface AgentOptions {
-    sessionId: string;
-    provider: Provider;
+import { Sandbox, SandboxKind } from '../infra/sandbox';
+import { SandboxFactory } from '../infra/sandbox-factory';
+import { ModelProvider, ModelConfig } from '../infra/provider';
+import { ToolRegistry, ToolInstance, ToolDescriptor } from '../tools/registry';
+import { ContextManagerOptions } from './context-manager';
+import { SendOptions as QueueSendOptions } from './agent/message-queue';
+export interface ModelFactory {
+    (config: ModelConfig): ModelProvider;
+}
+export interface AgentDependencies {
     store: Store;
-    sandbox: Sandbox;
-    tools?: Tool[];
-    system?: string;
-    maxTokens?: number;
-    temperature?: number;
-    maxConcurrency?: number;
-    templateId?: string;
+    templateRegistry: AgentTemplateRegistry;
+    sandboxFactory: SandboxFactory;
+    toolRegistry: ToolRegistry;
+    modelFactory?: ModelFactory;
+    skillsManager?: import('./skills/manager').SkillsManager;
+}
+export type SendOptions = QueueSendOptions;
+export interface SandboxConfig {
+    kind: SandboxKind;
+    workDir?: string;
+    enforceBoundary?: boolean;
+    allowPaths?: string[];
+    watchFiles?: boolean;
+    [key: string]: any;
+}
+export interface AgentConfig {
+    agentId?: string;
+    templateId: string;
+    templateVersion?: string;
+    model?: ModelProvider;
+    modelConfig?: ModelConfig;
+    sandbox?: Sandbox | SandboxConfig;
+    tools?: string[];
+    exposeThinking?: boolean;
+    retainThinking?: boolean;
+    multimodalContinuation?: 'history';
+    multimodalRetention?: {
+        keepRecent?: number;
+    };
+    overrides?: {
+        permission?: PermissionConfig;
+        todo?: TodoConfig;
+        subagents?: SubAgentConfig;
+        hooks?: Hooks;
+    };
+    context?: ContextManagerOptions;
+    metadata?: Record<string, any>;
+}
+interface SubAgentRuntime {
+    depthRemaining: number;
+}
+export interface CompleteResult {
+    status: 'ok' | 'paused';
+    text?: string;
+    last?: Bookmark;
+    permissionIds?: string[];
+}
+export interface StreamOptions {
+    since?: Bookmark;
+    kinds?: Array<ProgressEvent['type']>;
+}
+export interface SubscribeOptions {
+    since?: Bookmark;
+    kinds?: Array<AgentEvent['type']>;
 }
 export declare class Agent {
-    private sessionId;
-    private provider;
-    private store;
-    private sandbox;
-    private tools;
-    private system?;
-    private maxTokens;
-    private temperature;
-    private maxConcurrency;
-    private templateId;
+    private readonly config;
+    private readonly deps;
+    private readonly events;
+    private readonly hooks;
+    private readonly scheduler;
+    private readonly todoService?;
+    private readonly contextManager;
+    private readonly filePool;
+    private readonly breakpoints;
+    private readonly permissions;
+    private readonly model;
+    private readonly sandbox;
+    private readonly sandboxConfig?;
+    private readonly todoConfig?;
+    private readonly messageQueue;
+    private readonly todoManager;
+    private readonly ajv;
+    private readonly validatorCache;
+    private readonly toolControllers;
+    private readonly toolTimeoutMs;
+    private readonly maxToolConcurrency;
+    private readonly tools;
+    private readonly toolDescriptors;
+    private readonly toolDescriptorIndex;
+    private skillsManager?;
+    private createdAt;
+    private readonly pendingPermissions;
+    private readonly toolRunner;
     private messages;
     private state;
-    private lastSfpIndex;
-    private stepCount;
-    private events;
-    private hooks;
-    private scheduler?;
-    private pendingPermissions;
+    private toolRecords;
     private interrupted;
-    constructor(templateOrOpts: AgentTemplate | AgentOptions, overrides?: Partial<AgentOptions>);
-    send(text: string): Promise<string>;
-    subscribe(opts?: SubscribeOptions): AsyncIterable<AgentEvent>;
-    chat(text: string): AsyncIterable<AgentEvent>;
-    reply(text: string): Promise<string>;
-    askLLM(text: string, opts?: {
-        sessionId?: string;
-        provider?: Provider;
-        useTools?: boolean;
-        system?: string;
-    }): Promise<{
-        text: string;
-        sessionId: string;
-    }>;
+    private processingPromise;
+    private pendingNextRound;
+    private lastProcessingStart;
+    private readonly PROCESSING_TIMEOUT;
+    private stepCount;
+    private lastSfpIndex;
+    private lastBookmark?;
+    private exposeThinking;
+    private retainThinking;
+    private multimodalContinuation;
+    private multimodalRetentionKeepRecent;
+    private permission;
+    private subagents?;
+    private template;
+    private lineage;
+    private mediaCache;
+    private get persistentStore();
+    private static requireStore;
+    constructor(config: AgentConfig, deps: AgentDependencies, runtime: {
+        template: AgentTemplateDefinition;
+        model: ModelProvider;
+        sandbox: Sandbox;
+        sandboxConfig?: SandboxConfig;
+        tools: ToolInstance[];
+        toolDescriptors: ToolDescriptor[];
+        permission: PermissionConfig;
+        todoConfig?: TodoConfig;
+        subagents?: SubAgentConfig;
+        context?: ContextManagerOptions;
+    });
+    get agentId(): string;
+    static create(config: AgentConfig, deps: AgentDependencies): Promise<Agent>;
+    private initialize;
+    chatStream(input: string | ContentBlock[], opts?: StreamOptions): AsyncIterable<AgentEventEnvelope<ProgressEvent>>;
+    chat(input: string | ContentBlock[], opts?: StreamOptions): Promise<CompleteResult>;
+    complete(input: string | ContentBlock[], opts?: StreamOptions): Promise<CompleteResult>;
+    stream(input: string | ContentBlock[], opts?: StreamOptions): AsyncIterable<AgentEventEnvelope<ProgressEvent>>;
+    send(message: string | ContentBlock[], options?: SendOptions): Promise<string>;
+    schedule(): Scheduler;
+    on<T extends ControlEvent['type'] | MonitorEvent['type']>(event: T, handler: (evt: any) => void): () => void;
+    subscribe(channels?: Array<'progress' | 'control' | 'monitor'>, opts?: SubscribeOptions): AsyncIterable<AgentEventEnvelope<AgentEvent>>;
+    getTodos(): TodoItem[];
+    setTodos(todos: TodoInput[]): Promise<void>;
+    updateTodo(todo: TodoInput): Promise<void>;
+    deleteTodo(id: string): Promise<void>;
+    decide(permissionId: string, decision: 'allow' | 'deny', note?: string): Promise<void>;
     interrupt(opts?: {
         note?: string;
     }): Promise<void>;
-    decide(permId: string, decision: 'allow' | 'deny', note?: string): Promise<void>;
     snapshot(label?: string): Promise<SnapshotId>;
     fork(sel?: SnapshotId | {
         at?: string;
     }): Promise<Agent>;
-    static resume(sessionId: string, opts: AgentOptions & {
-        autoRun?: boolean;
-        strategy?: 'crash' | 'manual';
-    }): Promise<Agent>;
-    private findLastSfp;
-    private findSealedTools;
-    history(opts?: {
-        since?: number;
-        limit?: number;
-    }): Promise<AgentEvent[]>;
     status(): Promise<AgentStatus>;
     info(): Promise<AgentInfo>;
-    use(hooks: Hooks): this;
-    getHooks(): ReadonlyArray<import('./hooks').RegisteredHook>;
-    registerTools(tools: Tool[]): this;
-    schedule(): Scheduler;
-    on(event: 'permission_ask' | 'error' | 'messages_update', handler: (...args: any[]) => void): this;
-    private step;
+    private setBreakpoint;
+    remind(content: string, options?: ReminderOptions): void;
+    spawnSubAgent(templateId: string, prompt: string, runtime?: SubAgentRuntime): Promise<CompleteResult>;
+    /**
+     * Create and run a sub-agent with a task, without requiring subagents config.
+     * This is useful for tools that want to delegate work to specialized agents.
+     */
+    delegateTask(config: {
+        templateId: string;
+        prompt: string;
+        model?: string;
+        tools?: string[];
+    }): Promise<CompleteResult>;
+    static resume(agentId: string, config: AgentConfig, deps: AgentDependencies, opts?: {
+        autoRun?: boolean;
+        strategy?: ResumeStrategy;
+    }): Promise<Agent>;
+    static resumeFromStore(agentId: string, deps: AgentDependencies, opts?: {
+        autoRun?: boolean;
+        strategy?: ResumeStrategy;
+        overrides?: Partial<AgentConfig>;
+    }): Promise<Agent>;
+    private ensureProcessing;
+    private runStep;
     private executeTools;
+    private processToolCall;
+    private registerToolRecord;
+    private updateToolRecord;
+    private snapshotToolRecord;
+    private normalizeToolRecord;
+    private preview;
+    private validateBlocks;
+    private estimateBase64Bytes;
+    private resolveMultimodalBlocks;
+    private applyMediaCache;
+    private computeSha256;
+    private persistMediaCache;
+    private splitThinkBlocksIfNeeded;
+    private splitThinkText;
+    private shouldPreserveBlocks;
+    private buildMessageMetadata;
     private requestPermission;
+    private findLastSfp;
+    private appendSyntheticToolResults;
+    private autoSealIncompleteCalls;
+    private validateToolArgs;
+    private makeToolResult;
+    private buildSealPayload;
+    private wrapReminder;
     private getToolSchemas;
+    private setState;
     private persistMessages;
+    private persistToolRecords;
+    private persistInfo;
+    private registerTodoTools;
+    /**
+     * 收集所有工具的使用说明
+     */
+    private collectToolPrompts;
+    /**
+     * 渲染工具手册
+     */
+    private renderManual;
+    /**
+     * 刷新工具手册（运行时工具变更时调用）
+     */
+    private refreshToolManual;
+    /**
+     * 根据错误类型生成建议
+     */
+    private getErrorRecommendations;
+    /**
+     * 将工具手册注入到系统提示中
+     */
+    private injectManualIntoSystemPrompt;
+    /**
+     * 将skills元数据注入到系统提示中
+     * 参考openskills设计，使用<available_skills> XML格式
+     */
+    private injectSkillsMetadataIntoSystemPrompt;
+    /**
+     * 刷新skills元数据（运行时skills变更时调用）
+     * 由于支持热更新，可在执行过程中调用此方法
+     */
+    private refreshSkillsMetadata;
+    private enqueueMessage;
+    private handleExternalFileChange;
+    private relativePath;
+    private static generateAgentId;
 }
+export {};