@aix-chat/core 0.1.0

package/dist/domain/chat.js

@@ -0,0 +1,265 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor); } }
+function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/** 一个完整的对话轮次：用户消息 + （可选）AI 回应 */
+
+/**
+ * Chat — 核心交互实体
+ *
+ * 职责：
+ *   - 接管 Provider 的 onMessage / onComplete / onError 回调
+ *   - 维护消息列表与请求状态
+ *   - 提供 subscribe / getSnapshot 供 React hooks 订阅
+ *   - 支持 Turn 级重试（retry）
+ *   - 通过 onComplete / onError 向外透传会话级事件
+ *
+ * 不负责：
+ *   - WebSocket 连接管理（ConnectionStatus 由 hooks 层管理）
+ *   - 历史分页加载
+ *   - Provider 的创建与生命周期
+ */
+export var Chat = /*#__PURE__*/function () {
+  function Chat(provider) {
+    _classCallCheck(this, Chat);
+    _defineProperty(this, "provider", void 0);
+    /** 会话完成后的外部回调（由 useSessions 等注入） */
+    _defineProperty(this, "onComplete", void 0);
+    /** 会话出错后的外部回调 */
+    _defineProperty(this, "onError", void 0);
+    _defineProperty(this, "onMessage", void 0);
+    _defineProperty(this, "_messages", []);
+    _defineProperty(this, "_isRequesting", false);
+    _defineProperty(this, "_error", void 0);
+    _defineProperty(this, "_lastInput", void 0);
+    _defineProperty(this, "_listeners", new Set());
+    this.provider = provider;
+    this._wireCallbacks();
+  }
+
+  // ── 内部 callback 接管 ──────────────────────────────────
+  _createClass(Chat, [{
+    key: "_wireCallbacks",
+    value: function _wireCallbacks() {
+      var _this = this;
+      this.provider.onMessage = function (msg) {
+        var _this$onMessage;
+        var idx = _this._messages.findIndex(function (m) {
+          return m.id === msg.id;
+        });
+        if (idx >= 0) {
+          _this._messages = _this._messages.map(function (m, i) {
+            return i === idx ? _objectSpread(_objectSpread({}, m), msg) : m;
+          });
+        } else {
+          _this._messages = [].concat(_toConsumableArray(_this._messages), [msg]);
+        }
+        (_this$onMessage = _this.onMessage) === null || _this$onMessage === void 0 || _this$onMessage.call(_this, msg);
+        _this._notify();
+      };
+      this.provider.onComplete = function (msgs) {
+        var _this$onComplete;
+        _this._isRequesting = false;
+        if (msgs !== null && msgs !== void 0 && msgs.length) {
+          var last = msgs[msgs.length - 1];
+          _this._messages = _this._messages.map(function (m) {
+            return m.id === last.id ? _objectSpread(_objectSpread({}, m), {}, {
+              status: 'done'
+            }) : m;
+          });
+        }
+        _this._notify();
+        (_this$onComplete = _this.onComplete) === null || _this$onComplete === void 0 || _this$onComplete.call(_this, _this._messages);
+      };
+      this.provider.onError = function (error) {
+        var _this$onError;
+        _this._isRequesting = false;
+        _this._error = error;
+        _this._notify();
+        (_this$onError = _this.onError) === null || _this$onError === void 0 || _this$onError.call(_this, error);
+      };
+    }
+
+    // ── 公开操作 ────────────────────────────────────────────
+
+    /**
+     * 发起请求
+     * 调用后 isRequesting = true，Provider 回调驱动后续状态转换
+     */
+  }, {
+    key: "send",
+    value: function send(input, assistantMessageId) {
+      var _this2 = this;
+      if (this._isRequesting) return;
+      this._isRequesting = true;
+      this._error = undefined;
+      this._lastInput = input;
+      this._notify();
+      this.provider.request(input, assistantMessageId).catch(function (err) {
+        // provider.onError 通常已处理，此处作为最后保障
+        if (_this2._isRequesting) {
+          var _this2$onError;
+          _this2._isRequesting = false;
+          _this2._error = err instanceof Error ? err : new Error(String(err));
+          _this2._notify();
+          (_this2$onError = _this2.onError) === null || _this2$onError === void 0 || _this2$onError.call(_this2, _this2._error);
+        }
+      });
+    }
+
+    /** 中止当前请求 */
+  }, {
+    key: "abort",
+    value: function abort() {
+      this.provider.abort();
+      // isRequesting 由 onError / onComplete 回调置 false
+    }
+
+    /**
+     * Turn 级重试
+     *
+     * 找到最后一个 Turn，如果其 assistant message 处于 error / aborted 状态，
+     * 则删除该 assistant message，使用相同的 input 重新发送。
+     *
+     * Turn 从 messages 数组中派生，不额外存储。
+     */
+  }, {
+    key: "retry",
+    value: function retry() {
+      var _turn$assistantMessag;
+      if (this._isRequesting || !this._lastInput) return;
+      var turn = this._getLastTurn();
+      if (!turn) return;
+      var assistantStatus = (_turn$assistantMessag = turn.assistantMessage) === null || _turn$assistantMessag === void 0 ? void 0 : _turn$assistantMessag.status;
+      if (assistantStatus !== 'error' && assistantStatus !== 'aborted') return;
+
+      // 删除最后一个用户消息之后的所有 assistant 消息（清理失败的回应）
+      var userMsgIdx = this._messages.findIndex(function (m) {
+        return m.id === turn.userMessage.id;
+      });
+      if (userMsgIdx < 0) return;
+      this._messages = this._messages.slice(0, userMsgIdx + 1);
+
+      // 用相同的 input 重新发送
+      this.send(this._lastInput);
+    }
+
+    /** 是否可以重试（最后一个 Turn 有失败的 assistant message） */
+  }, {
+    key: "canRetry",
+    value: function canRetry() {
+      var _turn$assistantMessag2;
+      if (this._isRequesting || !this._lastInput) return false;
+      var turn = this._getLastTurn();
+      var status = turn === null || turn === void 0 || (_turn$assistantMessag2 = turn.assistantMessage) === null || _turn$assistantMessag2 === void 0 ? void 0 : _turn$assistantMessag2.status;
+      return status === 'error' || status === 'aborted';
+    }
+
+    /** 手动添加一条消息（如用户消息、历史消息） */
+  }, {
+    key: "addMessage",
+    value: function addMessage(message) {
+      this._messages = [].concat(_toConsumableArray(this._messages), [message]);
+      this._notify();
+    }
+
+    /** 批量设置消息列表（如加载历史、清空） */
+  }, {
+    key: "setMessages",
+    value: function setMessages(messages) {
+      this._messages = messages;
+      this._notify();
+    }
+  }, {
+    key: "getMessages",
+    value: function getMessages() {
+      return this._messages;
+    }
+  }, {
+    key: "getIsRequesting",
+    value: function getIsRequesting() {
+      return this._isRequesting;
+    }
+
+    // ── React 订阅接口 ───────────────────────────────────────
+  }, {
+    key: "getSnapshot",
+    value: function getSnapshot() {
+      return {
+        messages: this._messages,
+        isRequesting: this._isRequesting,
+        error: this._error,
+        canRetry: this.canRetry()
+      };
+    }
+
+    /**
+     * 订阅状态变更，返回取消订阅函数
+     * 适用于 useSyncExternalStore / useEffect 场景
+     */
+  }, {
+    key: "subscribe",
+    value: function subscribe(listener) {
+      var _this3 = this;
+      this._listeners.add(listener);
+      return function () {
+        return _this3._listeners.delete(listener);
+      };
+    }
+
+    // ── 生命周期 ─────────────────────────────────────────────
+
+    /** 清理所有订阅和 Provider 回调，防止内存泄漏 */
+  }, {
+    key: "destroy",
+    value: function destroy() {
+      this._listeners.clear();
+      this.provider.onMessage = undefined;
+      this.provider.onComplete = undefined;
+      this.provider.onError = undefined;
+    }
+
+    // ── 私有工具 ─────────────────────────────────────────────
+
+    /**
+     * 从消息列表中派生最后一个 Turn
+     * Turn = 最后一条 user 消息 + 其后的 assistant 消息（若有）
+     */
+  }, {
+    key: "_getLastTurn",
+    value: function _getLastTurn() {
+      for (var i = this._messages.length - 1; i >= 0; i--) {
+        if (this._messages[i].role === 'user') {
+          var userMessage = this._messages[i];
+          var assistantMessage = this._messages.slice(i + 1).find(function (m) {
+            return m.role === 'assistant';
+          });
+          return {
+            userMessage: userMessage,
+            assistantMessage: assistantMessage
+          };
+        }
+      }
+      return null;
+    }
+  }, {
+    key: "_notify",
+    value: function _notify() {
+      this._listeners.forEach(function (l) {
+        return l();
+      });
+    }
+  }]);
+  return Chat;
+}();

package/dist/domain/conversation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Conversation — 会话元数据实体
+ * 管理层概念：会话的存在、命名、排序
+ * 不包含消息内容（消息由 Chat/MessageStore 管理）
+ */
+export interface Conversation {
+    /** 会话唯一标识 */
+    key: string;
+    /** 会话标题 */
+    title?: string;
+    /** 创建时间戳 */
+    createdAt?: number;
+    /** 最后活跃时间戳 */
+    lastActiveAt?: number;
+    /** 扩展字段 */
+    [key: string]: any;
+}

package/dist/domain/conversation.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/index.d.ts

@@ -0,0 +1,7 @@
+export type { Block } from './block';
+export type { ChatMessage, MessageRole } from './message';
+export type { MessageStatus } from './status';
+export { canTransition, isTerminal, isActive } from './status';
+export type { Conversation } from './conversation';
+export { Chat } from './chat';
+export type { ChatSnapshot } from './chat';

package/dist/domain/index.js

@@ -0,0 +1,2 @@
+export { canTransition, isTerminal, isActive } from "./status";
+export { Chat } from "./chat";

package/dist/domain/message.d.ts

@@ -0,0 +1,38 @@
+import type { Block } from './block';
+import type { MessageStatus } from './status';
+/** 消息角色 */
+export type MessageRole = 'user' | 'assistant' | 'system';
+/** 附件类型 */
+export type AttachmentType = 'image' | 'file';
+/** 消息附件（后端协议格式） */
+export interface MessageAttachment {
+    /** 附件类型: 'file' | 'image' */
+    type: AttachmentType;
+    /** 文件名称 */
+    fileName: string;
+    /** MIME 类型 */
+    mimeType: string;
+    /** 文件内容（Base64 编码） */
+    content: string;
+}
+/** 聊天消息 — 协议无关的领域实体 */
+export interface ChatMessage {
+    /** 消息 ID */
+    id: string;
+    /** 消息角色 */
+    role: MessageRole;
+    /** 文本内容 */
+    content: string;
+    /** 消息状态 */
+    status: MessageStatus;
+    /** 所属会话 key */
+    sessionKey?: string;
+    /** 结构化内容块（Parser 输出） */
+    blocks?: Block[];
+    /** 消息附件列表（图片、文件等） */
+    attachments?: MessageAttachment[];
+    /** 创建时间戳（用于排序） */
+    createdAt?: number;
+    /** 扩展字段 */
+    extra?: Record<string, any>;
+}

package/dist/domain/message.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/status.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MessageStatus — 消息生命周期状态机
+ */
+export type MessageStatus = 'history' | 'pending' | 'streaming' | 'done' | 'error' | 'aborted';
+/** 判断状态转换是否合法 */
+export declare function canTransition(from: MessageStatus, to: MessageStatus): boolean;
+/** 是否为终态（不可再转换） */
+export declare function isTerminal(status: MessageStatus): boolean;
+/** 是否为活跃状态（正在处理中） */
+export declare function isActive(status: MessageStatus): boolean;

package/dist/domain/status.js

@@ -0,0 +1,30 @@
+/**
+ * MessageStatus — 消息生命周期状态机
+ */
+
+// 已中止，可重试
+
+var VALID_TRANSITIONS = {
+  history: [],
+  pending: ['streaming', 'done', 'error', 'aborted'],
+  streaming: ['done', 'error', 'aborted'],
+  done: [],
+  error: ['pending'],
+  aborted: ['pending']
+};
+
+/** 判断状态转换是否合法 */
+export function canTransition(from, to) {
+  var _VALID_TRANSITIONS$fr, _VALID_TRANSITIONS$fr2;
+  return (_VALID_TRANSITIONS$fr = (_VALID_TRANSITIONS$fr2 = VALID_TRANSITIONS[from]) === null || _VALID_TRANSITIONS$fr2 === void 0 ? void 0 : _VALID_TRANSITIONS$fr2.includes(to)) !== null && _VALID_TRANSITIONS$fr !== void 0 ? _VALID_TRANSITIONS$fr : false;
+}
+
+/** 是否为终态（不可再转换） */
+export function isTerminal(status) {
+  return VALID_TRANSITIONS[status].length === 0;
+}
+
+/** 是否为活跃状态（正在处理中） */
+export function isActive(status) {
+  return status === 'pending' || status === 'streaming';
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { ChatBridge, chatBridgeHelper, EventEmitter } from './bridge';
+export type { ChatBridgeConfig, BridgeInputRef, BridgeHandler } from './bridge';
+export type { Block } from './domain/block';
+export type { ChatMessage, MessageRole, MessageAttachment, AttachmentType } from './domain/message';
+export type { MessageStatus } from './domain/status';
+export { canTransition, isTerminal, isActive } from './domain/status';
+export type { Conversation as DomainConversation } from './domain/conversation';
+export { Chat } from './domain/chat';
+export type { ChatSnapshot } from './domain/chat';
+export type { ToolCallInfo, ApprovalRequestDetail, ApprovalRequestPayload, } from './types/message';
+export type { OpenClawBlock, TextBlock, ThinkingBlock, ToolExecutionBlock, ToolStep, ToolStatus, ApprovalBlock, ApprovalStatus, ImageBlock, } from './types/openclaw-blocks';
+export type { AlertBlock, AlertSeverity, AlertVariant, } from './types/blocks';
+export type { ParseResult } from './types/protocol';
+export type { ChatProvider } from './types/provider';
+export type { PanelTab, PanelAction, PanelActionEvent, PanelHandle, } from './types/panel';
+export type { InteractionRecord, InteractionSource, InteractionAction, } from './types/interaction';
+export type { AixContext } from './types/context';
+export { InteractionBuffer } from './utils/InteractionBuffer';

package/dist/index.js

@@ -0,0 +1,31 @@
+// ============================================================
+// @aix-chat/core
+//
+// 职责：
+//   domain/  — 领域模型（Chat、Message、MessageStatus）
+//   bridge/  — 命令式控制（ChatBridge）
+//   types/   — 公共类型契约（ChatProvider 接口、ParseResult、OpenClawBlock 等）
+// ============================================================
+
+// ── Bridge（命令式聊天控制，纯 JS，无 React 依赖）────────────
+export { ChatBridge, chatBridgeHelper, EventEmitter } from "./bridge";
+
+// ── domain（领域模型）────────────────────────────────────────
+
+export { canTransition, isTerminal, isActive } from "./domain/status";
+export { Chat } from "./domain/chat";
+
+// ── 公共类型 ────────────────────────────────────────────────
+
+// ── OpenClaw block 类型（ui 渲染契约）───────────────────────
+
+// ── 协议无关的通用 Block 类型 ────────────────────────────────
+
+// ── 协议解析结果（ui/useOpenClawRun 使用）────────────────────
+
+// ── Provider 接口（Chat 实体依赖）────────────────────────────
+
+// ── Panel / Interaction / Context 类型（副屏体系）────────────
+
+// ── 工具类 ────────────────────────────────────────────────────
+export { InteractionBuffer } from "./utils/InteractionBuffer";

package/dist/types/blocks.d.ts

@@ -0,0 +1,78 @@
+import type { Block } from '../domain/block';
+/**
+ * 系统提示的严重程度枚举。
+ *
+ * 用于驱动 `SystemNotice`(UI) 与 `AlertBlock`(数据) 的视觉表达与默认图标。
+ *
+ * - `info`    — 中性信息提示（默认蓝色，ℹ 图标）
+ * - `success` — 成功反馈（绿色，✓ 图标）
+ * - `warning` — 警告提示（橙色，⚠ 图标）
+ * - `error`   — 错误/失败（红色，✕ 图标）
+ * - `neutral` — 弱化中性（灰色，无图标）
+ *
+ * @public
+ */
+export type AlertSeverity = 'info' | 'success' | 'warning' | 'error' | 'neutral';
+/**
+ * 系统提示的视觉变体。
+ *
+ * - `inline` — 居中、无气泡、字号小、颜色淡。适合"已切换模型"、"上下文已截断" 等
+ *   中性事件，融入消息流不打断阅读。
+ * - `alert`  — 卡片形态、带边框/淡色背景，可挂载 `action`。适合"请求失败 [重试]"、
+ *   "工具调用超时" 等需要被用户注意或操作的事件。
+ *
+ * @public
+ */
+export type AlertVariant = 'inline' | 'alert';
+/**
+ * 协议无关的"系统提示"内容块。
+ *
+ * 可以作为：
+ * 1. 独立 `ChatMessage`(role='system') 的 `blocks` 数组里的一员，渲染到消息流；
+ * 2. 嵌入 `ChatMessage`(role='assistant') 的 `blocks` 中，用于"AI 回答到一半
+ *    发生异常"的内联提示场景。
+ *
+ * UI 侧由 `@aix-chat/ui` 的 `SystemNotice` 组件渲染（已注册到
+ * `MessageRenderer` 的内置 renderers，所有 preset 自动支持）。
+ *
+ * @public
+ *
+ * @example
+ * ```ts
+ * const alertBlock: AlertBlock = {
+ *   type: 'alert',
+ *   severity: 'warning',
+ *   content: '工具调用超时,请重试',
+ *   variant: 'alert',
+ *   action: { label: '重试', actionId: 'retry-tool-call' },
+ * };
+ * ```
+ */
+export interface AlertBlock extends Block {
+    /** Block 判别字段，固定为 `'alert'` */
+    type: 'alert';
+    /**
+     * 严重程度，决定默认配色与图标。
+     * @see AlertSeverity
+     */
+    severity: AlertSeverity;
+    /** 提示文案(纯文本,不解析 Markdown) */
+    content: string;
+    /**
+     * 视觉变体。未传时由渲染层默认为 `'inline'`。
+     * @see AlertVariant
+     */
+    variant?: AlertVariant;
+    /**
+     * 可选的可序列化 action 描述。
+     *
+     * 区别于 React 节点形态的 action,这里使用 `{ label, actionId }` 以便穿越
+     * SSE/WS 协议持久化。消费方在 UI 层将 `actionId` 映射到具体的点击处理。
+     */
+    action?: {
+        /** 按钮显示文案 */
+        label: string;
+        /** 业务侧自定义的 action 标识,消费方据此分发回调 */
+        actionId: string;
+    };
+}

package/dist/types/blocks.js

@@ -0,0 +1 @@
+export {};

package/dist/types/context.d.ts

@@ -0,0 +1,22 @@
+import type { InteractionRecord } from './interaction';
+import type { PanelTab } from './panel';
+/**
+ * 发消息时注入 Agent 的上下文包。
+ * 通过 PanelHandle.flushContext() 获取，注入到 ChatProvider.request() 的 panelContext 字段。
+ */
+export interface AixContext {
+    /**
+     * 副屏当前状态快照。
+     */
+    panelState: {
+        tabs: Pick<PanelTab, 'id' | 'type' | 'title'>[];
+        activeTabId: string | null;
+    };
+    /**
+     * 用户交互记录缓冲，flush 后清空。
+     *
+     * @internal SDK 提供积累机制，但数据由业务组件通过 onInteraction 自行上报。
+     * 当前阶段不作为平台能力对外推广，按需使用。
+     */
+    interactions: InteractionRecord[];
+}

package/dist/types/context.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './message';
+export * from './openclaw-blocks';
+export * from './protocol';
+export * from './provider';
+export * from './panel';
+export * from './interaction';

package/dist/types/index.js

@@ -0,0 +1,6 @@
+export * from "./message";
+export * from "./openclaw-blocks";
+export * from "./protocol";
+export * from "./provider";
+export * from "./panel";
+export * from "./interaction";

package/dist/types/interaction.d.ts

@@ -0,0 +1,46 @@
+export interface InteractionSource {
+    /** 来源类型 */
+    type: 'panel' | 'aix-ui' | string;
+    /** 来源 panel ID（type==='panel' 时） */
+    panel?: string;
+    /** 目标元素，如 "node:xxx" */
+    target?: string;
+}
+export interface InteractionAction {
+    /** 动词，如 "select"、"edit"、"delete" */
+    verb: string;
+    /** 主体描述，如 "node"、"edge" */
+    subject: string;
+    /** 操作参数 */
+    params?: Record<string, any>;
+    /** 操作前快照 */
+    before?: any;
+    /** 操作后快照 */
+    after?: any;
+}
+/**
+ * 用户交互记录协议
+ *
+ * 每条独立保留（不聚合），聚合后注入 provider.request() 的 panelContext 字段。
+ * description 由业务方生成，Agent 直接读取。
+ */
+export interface InteractionRecord {
+    id: string;
+    timestamp: number;
+    source: InteractionSource;
+    action: InteractionAction;
+    /** 自然语言描述，Agent 直接读取 */
+    description: string;
+    /**
+     * 操作发生时组件的当前状态快照。
+     * 业务组件用此字段上报整体状态（如当前选中节点列表、表单当前值等）。
+     * Agent 通过最近一条记录的 snapshot 了解组件当前状态。
+     */
+    snapshot?: Record<string, any>;
+    /**
+     * 本次操作的附加结构化数据（比 action.params 更细）。
+     * 用于描述操作本身，而非组件整体状态。
+     * SDK 不解析，原样透传给 Agent。
+     */
+    data?: Record<string, any>;
+}

package/dist/types/interaction.js

@@ -0,0 +1 @@
+export {};

package/dist/types/message.d.ts

@@ -0,0 +1,39 @@
+export type { Block } from '../domain/block';
+export type { ChatMessage, MessageRole } from '../domain/message';
+export type { MessageStatus } from '../domain/status';
+/**
+ * 工具调用信息（ParseResult 引用）
+ */
+export interface ToolCallInfo {
+    id: string;
+    toolName: string;
+    phase: 'start' | 'result';
+    arguments?: any;
+    success?: boolean;
+    result?: any;
+    error?: any;
+    startTime?: number;
+    endTime?: number;
+}
+/**
+ * 审批请求详情（ParseResult 引用）
+ */
+export interface ApprovalRequestDetail {
+    command?: string;
+    cwd?: string;
+    host?: string;
+    security?: string;
+    ask?: string;
+    agentId?: string;
+    resolvedPath?: string;
+    sessionKey?: string;
+}
+/**
+ * 审批请求信息（ParseResult 引用）
+ */
+export interface ApprovalRequestPayload {
+    id: string;
+    request: ApprovalRequestDetail;
+    createdAtMs?: number;
+    expiresAtMs?: number;
+}

package/dist/types/message.js

@@ -0,0 +1 @@
+export {};