@aotui/runtime 1.0.0

package/dist/engine/core/llm-output-channel.js

@@ -0,0 +1,122 @@
+/**
+ * LLMOutputChannelService - LLM 文本输出通道
+ *
+ * [RFC-011] LLM Output Output Channel
+ *
+ * 管理 Desktop 级别的 LLM 文本发布订阅。
+ * 支持历史缓冲，新订阅者可获取最近 N 条消息。
+ *
+ * 职责:
+ * - 管理 per-Desktop 的订阅者
+ * - 维护历史消息缓冲 (默认 3 条)
+ * - 在 Desktop cleanup 时释放资源
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** 历史缓冲大小 */
+const HISTORY_SIZE = 3;
+// ============================================================================
+// Service Implementation
+// ============================================================================
+/**
+ * LLM 文本通道服务实现
+ */
+export class LLMOutputChannelService {
+    states = new Map();
+    // ─────────────────────────────────────────────────────────────
+    //  订阅管理
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * 订阅 LLM 文本事件
+     *
+     * 订阅时立即推送历史消息。
+     */
+    subscribe(desktopId, listener) {
+        const state = this.getOrCreateState(desktopId);
+        state.listeners.add(listener);
+        // 立即推送历史消息到新订阅者
+        for (const event of state.history) {
+            try {
+                listener(event);
+            }
+            catch (e) {
+                if (process.env.NODE_ENV !== 'production') {
+                    console.error('[LLMOutputChannel] Error in history replay:', e);
+                }
+            }
+        }
+        // 返回取消订阅函数
+        return () => {
+            state.listeners.delete(listener);
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  发布
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * 推送 LLM 文本事件
+     * [RFC-020] 支持结构化 payload { reasoning?, content? }
+     */
+    push(desktopId, payload, meta) {
+        const state = this.getOrCreateState(desktopId);
+        // 构建事件
+        const event = {
+            desktopId,
+            timestamp: Date.now(),
+            type: 'complete',
+            content: payload.content,
+            reasoning: payload.reasoning,
+            meta
+        };
+        // 维护历史缓冲 (FIFO)
+        state.history.push(event);
+        if (state.history.length > HISTORY_SIZE) {
+            state.history.shift();
+        }
+        // 通知所有订阅者
+        for (const listener of state.listeners) {
+            try {
+                listener(event);
+            }
+            catch (e) {
+                if (process.env.NODE_ENV !== 'production') {
+                    console.error('[LLMOutputChannel] Error in listener:', e);
+                }
+            }
+        }
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  历史查询
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * 获取历史消息
+     */
+    getHistory(desktopId) {
+        return this.states.get(desktopId)?.history ?? [];
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  生命周期
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * 清理 Desktop 相关资源
+     */
+    cleanup(desktopId) {
+        this.states.delete(desktopId);
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  内部方法
+    // ─────────────────────────────────────────────────────────────
+    getOrCreateState(desktopId) {
+        let state = this.states.get(desktopId);
+        if (!state) {
+            state = {
+                listeners: new Set(),
+                history: []
+            };
+            this.states.set(desktopId, state);
+        }
+        return state;
+    }
+}
+//# sourceMappingURL=llm-output-channel.js.map

package/dist/engine/core/llm-output-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-output-channel.js","sourceRoot":"","sources":["../../../src/engine/core/llm-output-channel.ts"],"names":[],"mappings":"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"}

package/dist/engine/core/manager.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Engine Layer - Desktop Manager Implementation
+ *
+ * 管理 Desktop 实例的生命周期和并发控制。
+ *
+ * @module @aotui/runtime/engine/desktop-manager
+ */
+import type { IDesktopManager, LockInfo, DesktopID, AppID, AppState, DesktopStatus, IDesktop, IRuntimeContext } from '../../spi/index.js';
+/**
+ * Desktop 管理器实现
+ *
+ * 封装 Desktop 的创建、存储、锁管理和生命周期控制。
+ * Kernel 通过 IDesktopManager 接口与之交互，实现依赖反转。
+ *
+ * @example
+ * ```typescript
+ * const manager = new DesktopManager();
+ * const desktopId = await manager.create();
+ * manager.acquireLock(desktopId, 'agent_1');
+ * await manager.installDynamicWorkerApp(desktopId, myApp);
+ * manager.releaseLock(desktopId, 'agent_1');
+ * ```
+ */
+import { RuntimeConfig } from '../../spi/config/index.js';
+export declare class DesktopManager implements IDesktopManager {
+    private desktops;
+    private lockService;
+    private config;
+    constructor(config?: RuntimeConfig);
+    create(desktopId?: DesktopID, context?: IRuntimeContext): Promise<DesktopID>;
+    destroy(desktopId: DesktopID): Promise<void>;
+    has(desktopId: DesktopID): boolean;
+    get(desktopId: DesktopID): IDesktop | undefined;
+    acquireLock(desktopId: DesktopID, ownerId: string): void;
+    releaseLock(desktopId: DesktopID, ownerId: string): void;
+    verifyLock(desktopId: DesktopID, ownerId: string): boolean;
+    refreshLock(desktopId: DesktopID, ownerId: string): void;
+    getLockInfo(desktopId: DesktopID): LockInfo | undefined;
+    /**
+     * [Worker-Only] 安装 App
+     */
+    installDynamicWorkerApp(desktopId: DesktopID, appModulePath: string, options?: {
+        workerScriptPath?: string;
+        appId?: string;
+        name?: string;
+        config?: import('../../spi/app/app-config.interface.js').AppLaunchConfig;
+    }): Promise<AppID>;
+    getAppStates(desktopId: DesktopID): AppState[];
+    getDesktopInfo(desktopId: DesktopID): {
+        status: DesktopStatus;
+        createdAt: number;
+    } | undefined;
+    suspend(desktopId: DesktopID): Promise<void>;
+    resume(desktopId: DesktopID): Promise<void>;
+    /**
+     * 获取 Desktop 或抛出 E_NOT_FOUND 错误
+     */
+    private getDesktopOrThrow;
+}

package/dist/engine/core/manager.js

@@ -0,0 +1,131 @@
+/**
+ * Engine Layer - Desktop Manager Implementation
+ *
+ * 管理 Desktop 实例的生命周期和并发控制。
+ *
+ * @module @aotui/runtime/engine/desktop-manager
+ */
+import { AOTUIError } from '../../spi/core/errors.js';
+import { Desktop } from './desktop.js';
+import { InMemoryLockService } from './services/lock.service.js';
+// ============================================================================
+// Desktop Manager Implementation
+// ============================================================================
+/**
+ * Desktop 管理器实现
+ *
+ * 封装 Desktop 的创建、存储、锁管理和生命周期控制。
+ * Kernel 通过 IDesktopManager 接口与之交互，实现依赖反转。
+ *
+ * @example
+ * ```typescript
+ * const manager = new DesktopManager();
+ * const desktopId = await manager.create();
+ * manager.acquireLock(desktopId, 'agent_1');
+ * await manager.installDynamicWorkerApp(desktopId, myApp);
+ * manager.releaseLock(desktopId, 'agent_1');
+ * ```
+ */
+import { RUNTIME_DEFAULTS } from '../../spi/config/index.js';
+export class DesktopManager {
+    desktops = new Map();
+    lockService;
+    config;
+    constructor(config) {
+        this.config = config ?? RUNTIME_DEFAULTS;
+        // [RFC-004] 内部服务组合: 锁管理委托给 InMemoryLockService
+        this.lockService = new InMemoryLockService((id) => this.desktops.has(id), { ttlMs: this.config.lock.ttlMs });
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  IDesktopRepository 实现
+    // ─────────────────────────────────────────────────────────────
+    async create(desktopId, context) {
+        const desktop = new Desktop(desktopId, { runtimeConfig: this.config, context });
+        this.desktops.set(desktop.id, desktop);
+        return desktop.id;
+    }
+    async destroy(desktopId) {
+        const desktop = this.desktops.get(desktopId);
+        if (desktop) {
+            await desktop.dispose();
+            this.desktops.delete(desktopId);
+            // [RFC-004] 清理关联的锁
+            this.lockService.clearLock(desktopId);
+        }
+    }
+    has(desktopId) {
+        return this.desktops.has(desktopId);
+    }
+    get(desktopId) {
+        return this.desktops.get(desktopId);
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  IDesktopLockService 实现 (Delegate)
+    // ─────────────────────────────────────────────────────────────
+    acquireLock(desktopId, ownerId) {
+        this.lockService.acquireLock(desktopId, ownerId);
+    }
+    releaseLock(desktopId, ownerId) {
+        this.lockService.releaseLock(desktopId, ownerId);
+    }
+    verifyLock(desktopId, ownerId) {
+        return this.lockService.verifyLock(desktopId, ownerId);
+    }
+    refreshLock(desktopId, ownerId) {
+        this.lockService.refreshLock(desktopId, ownerId);
+    }
+    getLockInfo(desktopId) {
+        return this.lockService.getLockInfo(desktopId);
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  IAppInstaller 实现
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * [Worker-Only] 安装 App
+     */
+    async installDynamicWorkerApp(desktopId, appModulePath, options) {
+        const desktop = this.getDesktopOrThrow(desktopId);
+        return desktop.installDynamicWorkerApp(appModulePath, options);
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  IDesktopStateAccessor 实现
+    // ─────────────────────────────────────────────────────────────
+    getAppStates(desktopId) {
+        const desktop = this.desktops.get(desktopId);
+        return desktop?.getAppStates() ?? [];
+    }
+    getDesktopInfo(desktopId) {
+        const desktop = this.desktops.get(desktopId);
+        if (!desktop)
+            return undefined;
+        return {
+            status: desktop.status,
+            createdAt: desktop.createdAt
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  IDesktopLifecycleController 实现
+    // ─────────────────────────────────────────────────────────────
+    async suspend(desktopId) {
+        const desktop = this.getDesktopOrThrow(desktopId);
+        await desktop.suspend();
+    }
+    async resume(desktopId) {
+        const desktop = this.getDesktopOrThrow(desktopId);
+        await desktop.resume();
+    }
+    // ─────────────────────────────────────────────────────────────
+    //  Internal Helpers
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * 获取 Desktop 或抛出 E_NOT_FOUND 错误
+     */
+    getDesktopOrThrow(desktopId) {
+        const desktop = this.desktops.get(desktopId);
+        if (!desktop) {
+            throw new AOTUIError('DESKTOP_NOT_FOUND', { desktopId });
+        }
+        return desktop;
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/engine/core/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/engine/core/manager.ts"],"names":[],"mappings":"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"}

package/dist/engine/core/operation-log-buffer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Operation Log Buffer
+ *
+ * Ring buffer implementation for storing operation execution logs.
+ * Maintains separate views for system-level and per-app logs.
+ *
+ * [RFC-008] Operation Execution Optimization
+ *
+ * @module @aotui/runtime/engine/core
+ */
+import type { IOperationLogBuffer, OperationLogEntry, AppID } from '../../spi/index.js';
+/**
+ * OperationLogBuffer
+ *
+ * Implements a ring buffer for operation logs with filtering capabilities.
+ *
+ * @example
+ * ```typescript
+ * const buffer = new OperationLogBuffer(50);
+ * buffer.push(entry);
+ *
+ * // Get recent system logs
+ * const systemLogs = buffer.getSystemLogs(5);
+ *
+ * // Get recent app logs
+ * const appLogs = buffer.getAppLogs('app_chat' as AppID, 3);
+ * ```
+ */
+export declare class OperationLogBuffer implements IOperationLogBuffer {
+    private logs;
+    private readonly maxSize;
+    private logCounter;
+    /**
+     * Create a new OperationLogBuffer
+     *
+     * @param maxSize - Maximum number of logs to retain (default: 50)
+     */
+    constructor(maxSize?: number);
+    /**
+     * Generate unique log ID
+     */
+    private generateLogId;
+    /**
+     * Push a new log entry to the buffer
+     *
+     * Automatically assigns an ID if not provided.
+     * Implements ring buffer behavior - oldest entries are removed when full.
+     */
+    push(entry: OperationLogEntry): void;
+    /**
+     * Get recent system-scope logs
+     *
+     * @param count - Maximum number of logs to return
+     * @returns Array of log entries, most recent last
+     */
+    getSystemLogs(count: number): OperationLogEntry[];
+    /**
+     * Get recent logs for a specific app
+     *
+     * @param appId - The app ID to filter by
+     * @param count - Maximum number of logs to return
+     * @returns Array of log entries, most recent last
+     */
+    getAppLogs(appId: AppID, count: number): OperationLogEntry[];
+    /**
+     * Get all logs (for debugging)
+     *
+     * @returns Copy of all log entries
+     */
+    getAllLogs(): OperationLogEntry[];
+    /**
+     * Get the total number of logs currently stored
+     */
+    getSize(): number;
+    /**
+     * Clear all logs
+     */
+    clear(): void;
+}

package/dist/engine/core/operation-log-buffer.js

@@ -0,0 +1,108 @@
+/**
+ * Operation Log Buffer
+ *
+ * Ring buffer implementation for storing operation execution logs.
+ * Maintains separate views for system-level and per-app logs.
+ *
+ * [RFC-008] Operation Execution Optimization
+ *
+ * @module @aotui/runtime/engine/core
+ */
+/**
+ * OperationLogBuffer
+ *
+ * Implements a ring buffer for operation logs with filtering capabilities.
+ *
+ * @example
+ * ```typescript
+ * const buffer = new OperationLogBuffer(50);
+ * buffer.push(entry);
+ *
+ * // Get recent system logs
+ * const systemLogs = buffer.getSystemLogs(5);
+ *
+ * // Get recent app logs
+ * const appLogs = buffer.getAppLogs('app_chat' as AppID, 3);
+ * ```
+ */
+export class OperationLogBuffer {
+    logs = [];
+    maxSize;
+    logCounter = 0;
+    /**
+     * Create a new OperationLogBuffer
+     *
+     * @param maxSize - Maximum number of logs to retain (default: 50)
+     */
+    constructor(maxSize = 50) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * Generate unique log ID
+     */
+    generateLogId() {
+        return `log_${++this.logCounter}`;
+    }
+    /**
+     * Push a new log entry to the buffer
+     *
+     * Automatically assigns an ID if not provided.
+     * Implements ring buffer behavior - oldest entries are removed when full.
+     */
+    push(entry) {
+        // Ensure entry has an ID
+        const entryWithId = {
+            ...entry,
+            id: entry.id || this.generateLogId()
+        };
+        this.logs.push(entryWithId);
+        // Ring buffer: remove oldest when exceeding maxSize
+        if (this.logs.length > this.maxSize) {
+            this.logs.shift();
+        }
+    }
+    /**
+     * Get recent system-scope logs
+     *
+     * @param count - Maximum number of logs to return
+     * @returns Array of log entries, most recent last
+     */
+    getSystemLogs(count) {
+        return this.logs
+            .filter(e => e.scope === 'system')
+            .slice(-count);
+    }
+    /**
+     * Get recent logs for a specific app
+     *
+     * @param appId - The app ID to filter by
+     * @param count - Maximum number of logs to return
+     * @returns Array of log entries, most recent last
+     */
+    getAppLogs(appId, count) {
+        return this.logs
+            .filter(e => e.scope === 'app' && e.appId === appId)
+            .slice(-count);
+    }
+    /**
+     * Get all logs (for debugging)
+     *
+     * @returns Copy of all log entries
+     */
+    getAllLogs() {
+        return [...this.logs];
+    }
+    /**
+     * Get the total number of logs currently stored
+     */
+    getSize() {
+        return this.logs.length;
+    }
+    /**
+     * Clear all logs
+     */
+    clear() {
+        this.logs = [];
+    }
+}
+//# sourceMappingURL=operation-log-buffer.js.map

package/dist/engine/core/operation-log-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-log-buffer.js","sourceRoot":"","sources":["../../../src/engine/core/operation-log-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,kBAAkB;IACnB,IAAI,GAAwB,EAAE,CAAC;IACtB,OAAO,CAAS;IACzB,UAAU,GAAG,CAAC,CAAC;IAEvB;;;;OAIG;IACH,YAAY,UAAkB,EAAE;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED;;OAEG;IACK,aAAa;QACjB,OAAO,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAwB;QACzB,yBAAyB;QACzB,MAAM,WAAW,GAAsB;YACnC,GAAG,KAAK;YACR,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,aAAa,EAAE;SACvC,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAE5B,oDAAoD;QACpD,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,KAAa;QACvB,OAAO,IAAI,CAAC,IAAI;aACX,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC;aACjC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,KAAY,EAAE,KAAa;QAClC,OAAO,IAAI,CAAC,IAAI;aACX,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC;aACnD,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,UAAU;QACN,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,OAAO;QACH,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK;QACD,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;CACJ"}

package/dist/engine/core/operation-log-formatter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Operation Log Formatter
+ *
+ * Generates semantic, human-readable log messages from operation entries.
+ * Follows the WHO/WHEN/WHERE/WHAT pattern for clarity.
+ *
+ * [RFC-008] Operation Execution Optimization
+ *
+ * @module @aotui/runtime/engine/core
+ */
+import type { OperationLogEntry, OperationLogParams } from '../../spi/index.js';
+/**
+ * Generate a unique log entry ID
+ */
+export declare function generateLogId(): string;
+/**
+ * Format an operation log entry into a semantic, human-readable string
+ *
+ * Format: `HH:MM:SS ✅/❌ [Actor] [Location] [Action] (Duration)`
+ *
+ * @param entry - The log entry to format
+ * @returns Formatted log string
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatOperationLog(entry);
+ * // "15:32:45 ✅ Gemini in System-Chat/ChatView sent message "Hello..." (12ms)"
+ * ```
+ */
+export declare function formatOperationLog(entry: OperationLogEntry): string;
+/**
+ * Build a complete OperationLogEntry from execution parameters
+ *
+ * @param params - Operation execution parameters
+ * @returns Complete log entry with semantic description
+ */
+export declare function buildOperationLogEntry(params: OperationLogParams): OperationLogEntry;
+/**
+ * Format operation logs as Markdown list for snapshot inclusion
+ *
+ * @param logs - Array of log entries
+ * @returns Markdown formatted string
+ */
+export declare function formatLogsAsMarkdown(logs: OperationLogEntry[]): string;