@aotui/runtime 1.0.0

package/dist/spi/core/id-factory.js

@@ -0,0 +1,119 @@
+/**
+ * SPI Layer - ID Factory Functions
+ *
+ * 提供类型安全的 ID 创建函数。
+ *
+ * 使用工厂函数代替直接 `as TYPE` 断言，确保 ID 格式一致性。
+ *
+ * @example
+ * ```typescript
+ * import { createDesktopId, createAppId } from '@aotui/runtime';
+ *
+ * const desktopId = createDesktopId();           // 'dt_abc12345'
+ * const customId = createDesktopId('dt_my-id');  // 'dt_my-id'
+ * const appId = createAppId(0);                   // 'app_0'
+ * ```
+ *
+ * @module @aotui/runtime/spi/core
+ */
+import { randomUUID } from 'crypto';
+// ============================================================================
+// ID Prefixes (Internal Convention)
+// ============================================================================
+/**
+ * ID 前缀约定（内部使用）
+ *
+ * @internal
+ */
+export const ID_PREFIXES = {
+    Desktop: 'dt_',
+    App: 'app_',
+    View: 'view_',
+    Snapshot: 'snap_',
+    Operation: 'op_'
+};
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * 创建 DesktopID
+ *
+ * @param id - 可选的自定义 ID（应包含 'dt_' 前缀）
+ * @returns Branded DesktopID
+ */
+export function createDesktopId(id) {
+    return (id ?? `${ID_PREFIXES.Desktop}${randomUUID().slice(0, 8)}`);
+}
+/**
+ * 创建 AppID
+ *
+ * @param indexOrId - App 索引号或现有 ID 字符串
+ * @returns Branded AppID
+ */
+export function createAppId(indexOrId) {
+    if (typeof indexOrId === 'number') {
+        return `${ID_PREFIXES.App}${indexOrId}`;
+    }
+    return indexOrId;
+}
+/**
+ * 创建 ViewID
+ *
+ * @param indexOrId - View 索引号或现有 ID 字符串
+ * @returns Branded ViewID
+ */
+export function createViewId(indexOrId) {
+    if (typeof indexOrId === 'number') {
+        return `${ID_PREFIXES.View}${indexOrId}`;
+    }
+    return indexOrId;
+}
+/**
+ * 创建 SnapshotID
+ *
+ * @param id - 可选的现有 ID 字符串
+ * @returns Branded SnapshotID
+ */
+export function createSnapshotId(id) {
+    return (id ?? `${ID_PREFIXES.Snapshot}${randomUUID().slice(0, 8)}`);
+}
+/**
+ * 创建 OperationID
+ *
+ * @param name - 操作名称
+ * @returns Branded OperationID
+ */
+export function createOperationId(name) {
+    return name;
+}
+// ============================================================================
+// Type Guards (for runtime validation in future)
+// ============================================================================
+/**
+ * 检查字符串是否为有效的 DesktopID 格式
+ *
+ * @param value - 要检查的字符串
+ * @returns 类型谓词
+ */
+export function isDesktopId(value) {
+    return typeof value === 'string' && value.startsWith(ID_PREFIXES.Desktop);
+}
+/**
+ * 检查字符串是否为有效的 AppID 格式
+ */
+export function isAppId(value) {
+    return typeof value === 'string' && value.startsWith(ID_PREFIXES.App);
+}
+/**
+ * 检查字符串是否为有效的 ViewID 格式
+ */
+export function isViewId(value) {
+    return typeof value === 'string' && value.startsWith(ID_PREFIXES.View);
+}
+/**
+ * 检查字符串是否为有效的 SnapshotID 格式
+ */
+export function isSnapshotId(value) {
+    return typeof value === 'string' && value.startsWith(ID_PREFIXES.Snapshot);
+}
+//# sourceMappingURL=id-factory.js.map

package/dist/spi/core/id-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-factory.js","sourceRoot":"","sources":["../../../src/spi/core/id-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGpC,+EAA+E;AAC/E,oCAAoC;AACpC,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACvB,OAAO,EAAE,KAAK;IACd,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,OAAO;IACb,QAAQ,EAAE,OAAO;IACjB,SAAS,EAAE,KAAK;CACV,CAAC;AAEX,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,EAAW;IACvC,OAAO,CAAC,EAAE,IAAI,GAAG,WAAW,CAAC,OAAO,GAAG,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAc,CAAC;AACpF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,SAA0B;IAClD,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,GAAG,WAAW,CAAC,GAAG,GAAG,SAAS,EAAW,CAAC;IACrD,CAAC;IACD,OAAO,SAAkB,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,SAA0B;IACnD,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,GAAG,WAAW,CAAC,IAAI,GAAG,SAAS,EAAY,CAAC;IACvD,CAAC;IACD,OAAO,SAAmB,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAW;IACxC,OAAO,CAAC,EAAE,IAAI,GAAG,WAAW,CAAC,QAAQ,GAAG,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAe,CAAC;AACtF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC1C,OAAO,IAAmB,CAAC;AAC/B,CAAC;AAED,+EAA+E;AAC/E,iDAAiD;AACjD,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IAClC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC3E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC/E,CAAC"}

package/dist/spi/core/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SPI Core Layer - Foundation Types
+ *
+ * 最基础的类型定义，零外部依赖。
+ * 这是整个 AOTUI 框架的"语言"。
+ *
+ * @module @aotui/runtime/spi/core
+ */
+export type { SnapshotID, DesktopID, AppID, ViewID, OperationID, } from './types.js';
+export { createDesktopId, createAppId, createViewId, createSnapshotId, createOperationId, isDesktopId, isAppId, isViewId, isSnapshotId, ID_PREFIXES, } from './id-factory.js';
+export type { DataPayload, IndexMap, } from './types.js';
+export type { DesktopStatus, AppState, DesktopState, AppConfig, } from './types.js';
+export type { OperationContext, OperationScope, Operation, OperationError, OperationResult, OperationPayload, SystemOperationContext, ISystemOperation, IDesktopForOperation, ISystemOperationRegistry, } from './operations.js';
+export type { UpdateSignal } from './signals.js';
+export type { CachedSnapshot, StructuredSnapshot, AppStateFragment, ViewStateFragment } from './snapshot.js';
+export { isSnapshotExpired } from './snapshot.js';
+export type { Tool, ToolCall, ToolCallResult, OperationParamDef, OperationDef, } from './tool-call.js';
+export { ERROR_CODES, AOTUIError, createOperationError, failedResult, } from './errors.js';
+export type { ErrorCode } from './errors.js';
+export type { OperationLogScope, OperationLogEntry, IOperationLogBuffer, OperationLogParams, } from './operation-log.js';
+export type { LLMOutputEvent, LLMOutputEventMeta, LLMOutputListener, } from './llm-output.js';

package/dist/spi/core/index.js

@@ -0,0 +1,25 @@
+/**
+ * SPI Core Layer - Foundation Types
+ *
+ * 最基础的类型定义，零外部依赖。
+ * 这是整个 AOTUI 框架的"语言"。
+ *
+ * @module @aotui/runtime/spi/core
+ */
+// ============================================================================
+// ID Factory Functions
+// ============================================================================
+export { 
+// Factory Functions
+createDesktopId, createAppId, createViewId, createSnapshotId, createOperationId, 
+// Type Guards
+isDesktopId, isAppId, isViewId, isSnapshotId, 
+// Unsafe Casts (backward compatibility)
+// Constants
+ID_PREFIXES, } from './id-factory.js';
+export { isSnapshotExpired } from './snapshot.js';
+// ============================================================================
+// Error System
+// ============================================================================
+export { ERROR_CODES, AOTUIError, createOperationError, failedResult, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/spi/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/spi/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAC/E,OAAO;AACH,oBAAoB;AACpB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,iBAAiB;AACjB,cAAc;AACd,WAAW,EACX,OAAO,EACP,QAAQ,EACR,YAAY;AACZ,wCAAwC;AAExC,YAAY;AACZ,WAAW,GACd,MAAM,iBAAiB,CAAC;AA8CzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAalD,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAC/E,OAAO,EACH,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,YAAY,GACf,MAAM,aAAa,CAAC"}

package/dist/spi/core/llm-output.d.ts

@@ -0,0 +1,74 @@
+/**
+ * SPI Layer - LLM Output Types
+ *
+ * [RFC-011] LLM Output Output Channel
+ *
+ * 定义 LLM 文本输出事件类型，用于将 Agent 的文本输出
+ * 暴露给 Desktop 上的 TUI 应用。
+ *
+ * @module @aotui/runtime/spi
+ */
+import type { DesktopID } from './types.js';
+/**
+ * LLM 文本事件类型
+ *
+ * 当 LLM 产生非 Tool Call 的文本输出时触发。
+ *
+ * @example
+ * ```typescript
+ * const event: LLMOutputEvent = {
+ *     desktopId: 'desktop_1' as DesktopID,
+ *     timestamp: Date.now(),
+ *     type: 'complete',
+ *     content: 'Let me analyze this request...',
+ *     meta: { model: 'gpt-4' }
+ * };
+ * ```
+ */
+export interface LLMOutputEvent {
+    /** Desktop ID */
+    desktopId: DesktopID;
+    /** 时间戳 (毫秒) */
+    timestamp: number;
+    /**
+     * 事件类型
+     * - complete: 完整消息 (V1 only)
+     * - chunk: 流式片段 (future)
+     */
+    type: 'complete';
+    /**
+     * [RFC-020] LLM 最终回复内容
+     * 可选 - 若模型只输出 reasoning 可为空
+     */
+    content?: string;
+    /**
+     * [RFC-020] LLM 思考/推理过程
+     * DeepSeek Reasoner 等思考模型的 Chain-of-Thought 内容
+     */
+    reasoning?: string;
+    /** 元数据 (可选) */
+    meta?: LLMOutputEventMeta;
+}
+/**
+ * LLM 文本事件元数据
+ */
+export interface LLMOutputEventMeta {
+    /** 模型名称 (如 'gpt-4', 'claude-3') */
+    model?: string;
+    /** Provider ID (如 'openai', 'anthropic') */
+    providerId?: string;
+    /** Model ID (如 'gpt-4', 'claude-3-5-sonnet-20241022') */
+    modelId?: string;
+    /** 角色 */
+    role?: 'assistant' | 'system';
+    /** Token 使用情况 */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * LLM 文本通道监听器
+ */
+export type LLMOutputListener = (event: LLMOutputEvent) => void;

package/dist/spi/core/llm-output.js

@@ -0,0 +1,12 @@
+/**
+ * SPI Layer - LLM Output Types
+ *
+ * [RFC-011] LLM Output Output Channel
+ *
+ * 定义 LLM 文本输出事件类型，用于将 Agent 的文本输出
+ * 暴露给 Desktop 上的 TUI 应用。
+ *
+ * @module @aotui/runtime/spi
+ */
+export {};
+//# sourceMappingURL=llm-output.js.map

package/dist/spi/core/llm-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-output.js","sourceRoot":"","sources":["../../../src/spi/core/llm-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/spi/core/operation-log.d.ts

@@ -0,0 +1,133 @@
+/**
+ * SPI Layer - Operation Log Types
+ *
+ * Defines the structure for operation execution logs that capture:
+ * - WHO: The agent/actor that initiated the operation
+ * - WHEN: Timestamp and duration of execution
+ * - WHERE: Desktop > App > View hierarchy
+ * - WHAT: Operation name, result, and semantic description
+ *
+ * @module @aotui/runtime/spi
+ */
+import type { AppID, ViewID, DesktopID, OperationID } from './types.js';
+/**
+ * Operation execution scope
+ */
+export type OperationLogScope = 'system' | 'app';
+/**
+ * Operation Log Entry
+ *
+ * Captures complete context of an operation execution for debugging,
+ * monitoring, and Agent awareness.
+ *
+ * @example
+ * ```typescript
+ * const entry: OperationLogEntry = {
+ *     id: 'log_001',
+ *     actor: 'Gemini',
+ *     timestamp: Date.now(),
+ *     durationMs: 12,
+ *     desktopId: 'desktop_0' as DesktopID,
+ *     appId: 'app_chat' as AppID,
+ *     appName: 'System-Chat',
+ *     viewId: 'view_0' as ViewID,
+ *     viewName: 'ChatView',
+ *     scope: 'app',
+ *     operationName: 'send_message' as OperationID,
+ *     keyArgs: { content: 'Hello...' },
+ *     success: true,
+ *     semanticDescription: '15:32:45 ✅ Gemini in System-Chat/ChatView sent message "Hello..." (12ms)'
+ * };
+ * ```
+ */
+export interface OperationLogEntry {
+    /** Unique log entry ID */
+    id: string;
+    /** Actor who initiated (e.g., "Gemini", "DeepSeek", "User") */
+    actor: string;
+    /** Execution start timestamp */
+    timestamp: number;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** Desktop ID */
+    desktopId: DesktopID;
+    /** Target App ID (for app/view operations) */
+    appId?: AppID;
+    /** App display name (for human-readable logs) */
+    appName?: string;
+    /** Target View ID (for view operations) */
+    viewId?: ViewID;
+    /** View display name */
+    viewName?: string;
+    /** Operation scope */
+    scope: OperationLogScope;
+    /** Operation name */
+    operationName: OperationID;
+    /** Key arguments (sanitized, no sensitive data) */
+    keyArgs: Record<string, string>;
+    /** Execution result */
+    success: boolean;
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Human-readable semantic description */
+    semanticDescription: string;
+}
+/**
+ * Operation Log Buffer Interface
+ *
+ * Manages a ring buffer of operation log entries with filtering capabilities.
+ *
+ * Default limits:
+ * - System logs: 5 most recent
+ * - App logs: 3 most recent per app
+ */
+export interface IOperationLogBuffer {
+    /**
+     * Push a new log entry to the buffer
+     *
+     * @param entry - The log entry to add
+     */
+    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 All log entries
+     */
+    getAllLogs(): OperationLogEntry[];
+    /**
+     * Clear all logs
+     */
+    clear(): void;
+}
+/**
+ * Parameters for building an operation log entry
+ */
+export interface OperationLogParams {
+    actor: string;
+    desktopId: DesktopID;
+    scope: OperationLogScope;
+    operationName: OperationID;
+    args: Record<string, unknown>;
+    success: boolean;
+    durationMs: number;
+    appId?: AppID;
+    appName?: string;
+    viewId?: ViewID;
+    viewName?: string;
+    errorMessage?: string;
+}

package/dist/spi/core/operation-log.js

@@ -0,0 +1,13 @@
+/**
+ * SPI Layer - Operation Log Types
+ *
+ * Defines the structure for operation execution logs that capture:
+ * - WHO: The agent/actor that initiated the operation
+ * - WHEN: Timestamp and duration of execution
+ * - WHERE: Desktop > App > View hierarchy
+ * - WHAT: Operation name, result, and semantic description
+ *
+ * @module @aotui/runtime/spi
+ */
+export {};
+//# sourceMappingURL=operation-log.js.map

package/dist/spi/core/operation-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-log.js","sourceRoot":"","sources":["../../../src/spi/core/operation-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/spi/core/operations.d.ts

@@ -0,0 +1,198 @@
+/**
+ * SPI Layer - Operation Types
+ *
+ * 定义 Agent 与 Runtime 之间的操作交互协议。
+ *
+ * 术语说明:
+ * - Operation: 内部统一抽象，替代旧的 Command
+ * - ToolCall: 外部 LLM 接口 (保持不变)
+ *
+ * @module @aotui/runtime/spi
+ */
+import type { AppID, ViewID, SnapshotID, OperationID, DesktopID } from './types.js';
+import type { Tool } from './tool-call.js';
+/**
+ * 操作上下文
+ *
+ * 指定操作的目标位置 (App + View)
+ */
+export interface OperationContext {
+    /** 目标 App ID */
+    appId: AppID;
+    /**
+     * 目标 View ID (可选)
+     *
+     * 如果提供，操作路由到该 View
+     * 如果不提供，操作作为 App 级操作处理
+     */
+    viewId?: ViewID;
+    /**
+     * 快照 ID (可选，用于数据引用解析)
+     */
+    snapshotId: SnapshotID;
+}
+/**
+ * 操作范围
+ *
+ * 用于区分操作的目标层级
+ */
+export type OperationScope = 'system' | 'app' | 'view';
+/**
+ * 操作
+ *
+ * 表示 Agent 发送的单个操作指令
+ */
+export interface Operation {
+    /** 操作上下文 (目标 App/View) */
+    context: OperationContext;
+    /** 操作名称 */
+    name: OperationID;
+    /** 操作参数 */
+    args: Record<string, unknown>;
+}
+/**
+ * 操作错误
+ *
+ * 统一错误模型：
+ * - code: 机器可读的错误代码
+ * - message: 人类可读的错误描述
+ * - context: 额外调试信息（可选）
+ */
+export interface OperationError {
+    /** 错误代码（机器可读），如 E_INVALID_ARGS, E_NOT_FOUND */
+    code: string;
+    /** 错误描述（人类可读） */
+    message: string;
+    /** 额外上下文信息（可选，用于调试） */
+    context?: Record<string, unknown>;
+}
+/**
+ * 操作结果
+ */
+export interface OperationResult {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: OperationError;
+}
+/**
+ * 操作载荷
+ *
+ * 用于 Dispatcher 将已解析的操作传递给 Desktop。
+ * Desktop 负责将此载荷分发给具体的 App 容器。
+ */
+export interface OperationPayload {
+    /** 完整操作上下文 */
+    context: OperationContext;
+    /** 操作名称 */
+    operation: OperationID;
+    /** 已解析的参数 (Snapshot 引用已替换为实际数据) */
+    args: Record<string, unknown>;
+    /** 元数据 */
+    meta?: {
+        snapshotId?: SnapshotID;
+    };
+}
+/**
+ * 系统操作上下文
+ *
+ * 供 SystemOperation 执行时使用
+ */
+export interface SystemOperationContext {
+    /** Desktop ID */
+    desktopId: DesktopID;
+    /** 操作参数 */
+    args: Record<string, unknown>;
+}
+/**
+ * 系统操作接口
+ *
+ * 所有系统级操作（如 open_app, mount_view）必须实现此接口。
+ * 系统操作在编译时固定注册，不支持动态注册。
+ *
+ * @example
+ * ```typescript
+ * class OpenAppOperation implements ISystemOperation {
+ *     readonly name = 'open';
+ *     readonly aliases = ['open_app'];
+ *
+ *     async execute(ctx: SystemOperationContext, desktop: IDesktop): Promise<OperationResult> {
+ *         const appId = ctx.args.application as string;
+ *         await desktop.openApp(appId);
+ *         return { success: true };
+ *     }
+ * }
+ * ```
+ */
+export interface ISystemOperation {
+    /**
+     * 操作名称 (主名称)
+     *
+     * 用于注册和查找，如 'open', 'mount'
+     */
+    readonly name: string;
+    /**
+     * 操作别名 (可选)
+     *
+     * 用于向后兼容或语义别名，如 'expand' 是 'show' 的别名
+     */
+    readonly aliases?: readonly string[];
+    /**
+     * 执行操作
+     *
+     * @param ctx - 系统操作上下文 (包含 desktopId 和 args)
+     * @param desktop - 目标 Desktop 实例
+     * @returns 操作结果
+     */
+    execute(ctx: SystemOperationContext, desktop: IDesktopForOperation): Promise<OperationResult>;
+    /**
+     * Tool Definition (RFC-009)
+     *
+     * The LLM Tool Specification for this operation.
+     * Runtime uses this to generate the system tools list for the Agent.
+     */
+    readonly toolDefinition: Tool;
+}
+/**
+ * Desktop 接口 (供 SystemOperation 使用)
+ *
+ * 仅暴露 SystemOperation 需要的方法，避免完整 IDesktop 依赖。
+ * 这是接口隔离原则 (ISP) 的体现。
+ */
+export interface IDesktopForOperation {
+    readonly id: DesktopID;
+    openApp(appId: AppID): Promise<void>;
+    closeApp(appId: AppID): Promise<void>;
+    collapseApp(appId: AppID): Promise<void>;
+    showApp(appId: AppID): Promise<void>;
+    dismountView(appId: AppID, viewId: ViewID): Promise<void>;
+    hideView(appId: AppID, viewId: ViewID): Promise<void>;
+    showView(appId: AppID, viewId: ViewID): Promise<void>;
+    mountViewByLink(appId: AppID, parentViewId: ViewID, linkId: string): Promise<void>;
+}
+/**
+ * 系统操作注册表接口
+ *
+ * 管理所有系统级操作的注册和查找。
+ */
+export interface ISystemOperationRegistry {
+    /**
+     * 注册系统操作
+     */
+    register(operation: ISystemOperation): void;
+    /**
+     * 检查操作是否存在
+     */
+    has(name: string): boolean;
+    /**
+     * 获取操作 (通过名称或别名)
+     */
+    get(name: string): ISystemOperation | undefined;
+    /**
+     * 执行系统操作
+     */
+    execute(name: string, ctx: SystemOperationContext, desktop: IDesktopForOperation): Promise<OperationResult>;
+    /**
+     * Get all tool definitions (RFC-009)
+     */
+    getToolDefinitions(): Tool[];
+}

package/dist/spi/core/operations.js

@@ -0,0 +1,13 @@
+/**
+ * SPI Layer - Operation Types
+ *
+ * 定义 Agent 与 Runtime 之间的操作交互协议。
+ *
+ * 术语说明:
+ * - Operation: 内部统一抽象，替代旧的 Command
+ * - ToolCall: 外部 LLM 接口 (保持不变)
+ *
+ * @module @aotui/runtime/spi
+ */
+export {};
+//# sourceMappingURL=operations.js.map

package/dist/spi/core/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/spi/core/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/spi/core/signals.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SPI Layer - Signal Types
+ *
+ * 定义 Runtime 发出的信号类型。
+ */
+import type { DesktopID } from './types.js';
+/**
+ * 更新信号
+ *
+ * 当 Desktop 状态发生变化时发出。
+ */
+export interface UpdateSignal {
+    desktopId: DesktopID;
+    timestamp: number;
+    reason: 'dom_mutation' | 'app_opened' | 'app_closed' | 'manual_refresh';
+}

package/dist/spi/core/signals.js

@@ -0,0 +1,7 @@
+/**
+ * SPI Layer - Signal Types
+ *
+ * 定义 Runtime 发出的信号类型。
+ */
+export {};
+//# sourceMappingURL=signals.js.map

package/dist/spi/core/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","sourceRoot":"","sources":["../../../src/spi/core/signals.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}