@lcap/wave-sandbox-sdk 0.0.1

package/src/modules/agent.ts

@@ -0,0 +1,624 @@
+import type { Socket } from 'socket.io-client';
+import type {
+  TextBlock,
+  ToolBlock,
+  ErrorBlock,
+  SubagentBlock,
+  McpServerStatus,
+  AssistantMessage,
+} from '../types/agent-types.js';
+import type { HttpResponse } from '../types/index.js';
+import { createSocketHandler, onSocketEvent } from '../utils/socket.js';
+
+/**
+ * 附件接口
+ */
+export interface Attachment {
+  url?: string;
+  path?: string;
+  mimeType: string;
+  content?: string;
+}
+
+/**
+ * 发送消息选项
+ */
+export interface SendMessageOptions {
+  id: string;
+  sessionId: string;
+  message: string;
+  attachments?: Attachment[];
+}
+
+/**
+ * 消息队列项
+ */
+export interface ProcessQueueItem {
+  options: SendMessageOptions;
+  assistantMessageId: string;
+}
+
+/**
+ * 消息队列变化事件数据
+ */
+export interface MessageQueueChangedEvent {
+  queue: ProcessQueueItem[];
+  current: {
+    sessionId: string;
+    assistantMessageId?: string;
+    senderMessageId: string;
+    message?: AssistantMessage; // 当前正在执行的消息, 初始化链接时会有值
+  } | null;
+}
+
+/**
+ * 消息发送事件数据
+ */
+export interface MessageSendEvent {
+  sessionId: string;
+  assistantMessageId: string;
+  senderMessageId: string;
+  options: SendMessageOptions;
+}
+
+/**
+ * 消息运行事件数据
+ */
+export interface MessageRunningEvent {
+  sessionId: string;
+  assistantMessageId: string;
+  senderMessageId: string;
+}
+
+/**
+ * 消息完成事件数据
+ */
+export interface MessageFinishedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  status: 'pending' | 'running' | 'finished' | 'error' | 'aborted';
+}
+
+/**
+ * 初始化事件数据
+ */
+export interface InitializingEvent {
+  sessionId: string;
+}
+
+/**
+ * 初始化完成事件数据
+ */
+export interface InitializedEvent {
+  sessionId: string;
+  restoreSessionId?: string;
+}
+
+/**
+ * 消息块添加事件数据
+ */
+export interface MessageBlockAddedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    blocks: Array<TextBlock | ToolBlock | ErrorBlock | SubagentBlock>;
+  };
+}
+
+/**
+ * 消息块更新事件数据（用于流式更新）
+ */
+export interface MessageBlockUpdatedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    type: 'text';
+    content: string;
+  };
+}
+
+/**
+ * 工具块更新事件数据
+ */
+export interface MessageToolBlockUpdatedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: ToolBlock;
+}
+
+/**
+ * 子代理块添加事件数据
+ */
+export interface MessageSubagentBlockAddEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    subagentId: string;
+    blocks: Array<TextBlock | ToolBlock | ErrorBlock>;
+  };
+}
+
+/**
+ * 子代理块状态更新事件数据
+ */
+export interface MessageSubagentBlockStatusUpdatedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    subagentId: string;
+    status: 'active' | 'completed' | 'error' | 'aborted';
+  };
+}
+
+/**
+ * 子代理块内容更新事件数据
+ */
+export interface MessageSubagentBlockContentUpdatedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    subagentId: string;
+    type: 'text';
+    content: string;
+  };
+}
+
+/**
+ * 子代理工具块更新事件数据
+ */
+export interface MessageSubagentToolBlockUpdatedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    subagentId: string;
+    toolBlock: ToolBlock;
+  };
+}
+
+/**
+ * 错误块添加事件数据
+ */
+export interface MessageErrorBlockAddedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: ErrorBlock;
+}
+
+/**
+ * 命令输出消息添加事件数据
+ */
+export interface MessageCommandOutputMessageAddedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    command: string;
+  };
+}
+
+/**
+ * 命令输出消息更新事件数据
+ */
+export interface MessageCommandOutputMessageUpdatedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    command: string;
+    output: string;
+  };
+}
+
+/**
+ * 命令输出消息完成事件数据
+ */
+export interface MessageCommandOutputMessageCompletedEvent {
+  sessionId: string;
+  assistantMessageId?: string;
+  senderMessageId: string;
+  data: {
+    command: string;
+    exitCode: number;
+  };
+}
+
+/**
+ * MCP 服务器变化事件数据
+ */
+export interface McpServersChangeEvent {
+  sessionId: string;
+  servers: McpServerStatus[];
+}
+
+/**
+ * 文档解析开始事件数据
+ */
+export interface DocumentParseStartEvent {
+  sessionId: string;
+  senderMessageId: string;
+  index: number;
+  url: string;
+  mimeType: string;
+}
+
+/**
+ * 文档解析完成事件数据
+ */
+export interface DocumentParseCompleteEvent {
+  sessionId: string;
+  senderMessageId: string;
+  index: number;
+  url: string;
+  mimeType: string;
+  outputPath: string;
+  contentLength?: number;
+  pageCount?: number;
+}
+
+/**
+ * 文档解析错误事件数据
+ */
+export interface DocumentParseErrorEvent {
+  sessionId: string;
+  senderMessageId: string;
+  index: number;
+  url: string;
+  mimeType: string;
+  error: string;
+}
+
+/**
+ * Agent 事件名称映射
+ */
+export type AgentEventMap = {
+  'agent:message-send': MessageSendEvent;
+  'agent:message-running': MessageRunningEvent;
+  'agent:message-finished': MessageFinishedEvent;
+  'agent:message-queue-changed': MessageQueueChangedEvent;
+  'agent:initializing': InitializingEvent;
+  'agent:initialized': InitializedEvent;
+  'agent:message-block-added': MessageBlockAddedEvent;
+  'agent:message-block-updated': MessageBlockUpdatedEvent;
+  'agent:message-tool-block-updated': MessageToolBlockUpdatedEvent;
+  'agent:message-subagent-block-add': MessageSubagentBlockAddEvent;
+  'agent:message-subagent-block-status-updated': MessageSubagentBlockStatusUpdatedEvent;
+  'agent:message-subagent-block-content-updated': MessageSubagentBlockContentUpdatedEvent;
+  'agent:message-subagent-tool-block-updated': MessageSubagentToolBlockUpdatedEvent;
+  'agent:message-error-block-added': MessageErrorBlockAddedEvent;
+  'agent:message-command-output-message-added': MessageCommandOutputMessageAddedEvent;
+  'agent:message-command-output-message-updated': MessageCommandOutputMessageUpdatedEvent;
+  'agent:message-command-output-message-completed': MessageCommandOutputMessageCompletedEvent;
+  'agent:mcp-servers-change': McpServersChangeEvent;
+  'agent:document-parse-start': DocumentParseStartEvent;
+  'agent:document-parse-complete': DocumentParseCompleteEvent;
+  'agent:document-parse-error': DocumentParseErrorEvent;
+};
+
+/**
+ * Agent 事件名称类型
+ */
+export type AgentEventName = keyof AgentEventMap;
+
+/**
+ * Agent 模块
+ */
+export class AgentModule {
+  constructor(
+    private socket: Socket,
+    private baseUrl: string,
+    private projectId?: string
+  ) {}
+
+  /**
+   * 获取查询参数
+   */
+  private getQueryParams(): string {
+    if (this.projectId) {
+      return `projectId=${encodeURIComponent(this.projectId)}`;
+    }
+    return '';
+  }
+
+  /**
+   * 发送消息
+   * @param options 发送消息选项
+   * @returns Promise<string> 返回 assistantMessageId
+   */
+  async sendMessage(options: SendMessageOptions): Promise<string> {
+    const result = await createSocketHandler<SendMessageOptions, { assistantMessageId: string }>(
+      this.socket,
+      'agent:sendMessage',
+      () => options
+    );
+    return result.assistantMessageId;
+  }
+
+  /**
+   * 中止消息
+   * @param messageId 消息 ID
+   */
+  async abortMessage(messageId: string): Promise<void> {
+    return createSocketHandler<{ messageId: string }, void>(this.socket, 'agent:abortMessage', () => ({
+      messageId,
+    }));
+  }
+
+  /**
+   * 删除 session，包括日志记录和 agent 对象
+   * @param sessionId 会话 ID
+   * @throws 如果当前正在处理该 session 的消息，则抛出错误
+   */
+  async removeSession(sessionId: string): Promise<void> {
+    return createSocketHandler<{ sessionId: string }, void>(this.socket, 'agent:removeSession', () => ({
+      sessionId,
+    }));
+  }
+
+  /**
+   * 获取指定 session 的消息日志文件列表
+   * @param sessionId 会话 ID
+   * @returns Promise<string[] | null> 返回文件列表（倒序，最新的在前），如果没有文件则返回 null
+   */
+  async getSessionFiles(sessionId: string): Promise<string[] | null> {
+    const result = await createSocketHandler<{ sessionId: string }, { files: string[] } | null>(
+      this.socket,
+      'agent:getSessionFiles',
+      () => ({ sessionId })
+    );
+    return result ? result.files : null;
+  }
+
+  /**
+   * 获取当前 wave-agent 的完整状态
+   * @returns Promise<MessageQueueChangedEvent | null> 返回当前状态，如果没有活动状态则返回 null
+   */
+  async getCurrentState(): Promise<MessageQueueChangedEvent | null> {
+    const queryParams = this.getQueryParams();
+    const url = `${this.baseUrl}/api/agent/currentState${queryParams ? `?${queryParams}` : ''}`;
+    const response = await fetch(url);
+    const result: HttpResponse<MessageQueueChangedEvent | null> = await response.json();
+
+    if (result.status === 'error') {
+      throw new Error(result.message);
+    }
+
+    return result.data;
+  }
+
+  /**
+   * 监听消息发送事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageSend(callback: (event: MessageSendEvent) => void): () => void {
+    return onSocketEvent<MessageSendEvent>(this.socket, 'agent:message-send', callback);
+  }
+
+  /**
+   * 监听消息运行事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageRunning(callback: (event: MessageRunningEvent) => void): () => void {
+    return onSocketEvent<MessageRunningEvent>(this.socket, 'agent:message-running', callback);
+  }
+
+  /**
+   * 监听消息完成事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageFinished(callback: (event: MessageFinishedEvent) => void): () => void {
+    return onSocketEvent<MessageFinishedEvent>(this.socket, 'agent:message-finished', callback);
+  }
+
+  /**
+   * 监听消息队列变化事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageQueueChanged(callback: (event: MessageQueueChangedEvent) => void): () => void {
+    return onSocketEvent<MessageQueueChangedEvent>(this.socket, 'agent:message-queue-changed', callback);
+  }
+
+  /**
+   * 监听初始化事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onInitializing(callback: (event: InitializingEvent) => void): () => void {
+    return onSocketEvent<InitializingEvent>(this.socket, 'agent:initializing', callback);
+  }
+
+  /**
+   * 监听初始化完成事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onInitialized(callback: (event: InitializedEvent) => void): () => void {
+    return onSocketEvent<InitializedEvent>(this.socket, 'agent:initialized', callback);
+  }
+
+  /**
+   * 监听消息块添加事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageBlockAdded(callback: (event: MessageBlockAddedEvent) => void): () => void {
+    return onSocketEvent<MessageBlockAddedEvent>(this.socket, 'agent:message-block-added', callback);
+  }
+
+  /**
+   * 监听消息块更新事件（用于流式内容更新）
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageBlockUpdated(callback: (event: MessageBlockUpdatedEvent) => void): () => void {
+    return onSocketEvent<MessageBlockUpdatedEvent>(this.socket, 'agent:message-block-updated', callback);
+  }
+
+  /**
+   * 监听工具块更新事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageToolBlockUpdated(callback: (event: MessageToolBlockUpdatedEvent) => void): () => void {
+    return onSocketEvent<MessageToolBlockUpdatedEvent>(this.socket, 'agent:message-tool-block-updated', callback);
+  }
+
+  /**
+   * 监听子代理块添加事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageSubagentBlockAdd(callback: (event: MessageSubagentBlockAddEvent) => void): () => void {
+    return onSocketEvent<MessageSubagentBlockAddEvent>(this.socket, 'agent:message-subagent-block-add', callback);
+  }
+
+  /**
+   * 监听子代理块状态更新事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageSubagentBlockStatusUpdated(callback: (event: MessageSubagentBlockStatusUpdatedEvent) => void): () => void {
+    return onSocketEvent<MessageSubagentBlockStatusUpdatedEvent>(
+      this.socket,
+      'agent:message-subagent-block-status-updated',
+      callback
+    );
+  }
+
+  /**
+   * 监听子代理块内容更新事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageSubagentBlockContentUpdated(callback: (event: MessageSubagentBlockContentUpdatedEvent) => void): () => void {
+    return onSocketEvent<MessageSubagentBlockContentUpdatedEvent>(
+      this.socket,
+      'agent:message-subagent-block-content-updated',
+      callback
+    );
+  }
+
+  /**
+   * 监听子代理工具块更新事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageSubagentToolBlockUpdated(callback: (event: MessageSubagentToolBlockUpdatedEvent) => void): () => void {
+    return onSocketEvent<MessageSubagentToolBlockUpdatedEvent>(
+      this.socket,
+      'agent:message-subagent-tool-block-updated',
+      callback
+    );
+  }
+
+  /**
+   * 监听错误块添加事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageErrorBlockAdded(callback: (event: MessageErrorBlockAddedEvent) => void): () => void {
+    return onSocketEvent<MessageErrorBlockAddedEvent>(this.socket, 'agent:message-error-block-added', callback);
+  }
+
+  /**
+   * 监听命令输出消息添加事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageCommandOutputMessageAdded(callback: (event: MessageCommandOutputMessageAddedEvent) => void): () => void {
+    return onSocketEvent<MessageCommandOutputMessageAddedEvent>(
+      this.socket,
+      'agent:message-command-output-message-added',
+      callback
+    );
+  }
+
+  /**
+   * 监听命令输出消息更新事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageCommandOutputMessageUpdated(callback: (event: MessageCommandOutputMessageUpdatedEvent) => void): () => void {
+    return onSocketEvent<MessageCommandOutputMessageUpdatedEvent>(
+      this.socket,
+      'agent:message-command-output-message-updated',
+      callback
+    );
+  }
+
+  /**
+   * 监听命令输出消息完成事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMessageCommandOutputMessageCompleted(
+    callback: (event: MessageCommandOutputMessageCompletedEvent) => void
+  ): () => void {
+    return onSocketEvent<MessageCommandOutputMessageCompletedEvent>(
+      this.socket,
+      'agent:message-command-output-message-completed',
+      callback
+    );
+  }
+
+  /**
+   * 监听 MCP 服务器变化事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onMcpServersChange(callback: (event: McpServersChangeEvent) => void): () => void {
+    return onSocketEvent<McpServersChangeEvent>(this.socket, 'agent:mcp-servers-change', callback);
+  }
+
+  /**
+   * 监听文档解析开始事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onDocumentParseStart(callback: (event: DocumentParseStartEvent) => void): () => void {
+    return onSocketEvent<DocumentParseStartEvent>(this.socket, 'agent:document-parse-start', callback);
+  }
+
+  /**
+   * 监听文档解析完成事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onDocumentParseComplete(callback: (event: DocumentParseCompleteEvent) => void): () => void {
+    return onSocketEvent<DocumentParseCompleteEvent>(this.socket, 'agent:document-parse-complete', callback);
+  }
+
+  /**
+   * 监听文档解析错误事件
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  onDocumentParseError(callback: (event: DocumentParseErrorEvent) => void): () => void {
+    return onSocketEvent<DocumentParseErrorEvent>(this.socket, 'agent:document-parse-error', callback);
+  }
+
+  /**
+   * 通用事件监听方法，用于监听自定义事件
+   * @param eventName 事件名称（必须以 'agent:' 开头）
+   * @param callback 回调函数
+   * @returns 取消监听的函数
+   */
+  on<T = unknown>(eventName: string, callback: (event: T) => void): () => void {
+    if (!eventName.startsWith('agent:')) {
+      throw new Error(`事件名称必须以 'agent:' 开头，当前事件名称: ${eventName}`);
+    }
+    return onSocketEvent<T>(this.socket, eventName, callback);
+  }
+}

package/src/modules/exec.ts

@@ -0,0 +1,49 @@
+import type { Socket } from 'socket.io-client';
+import { createSocketHandler, onSocketEvent } from '../utils/socket.js';
+
+/**
+ * 命令执行模块
+ */
+export class ExecModule {
+  constructor(private socket: Socket) {}
+
+  /**
+   * 执行命令
+   * @param sessionId 会话 ID
+   * @param command 要执行的命令
+   * @returns Promise<number> 命令退出码
+   */
+  async exec(sessionId: string, command: string): Promise<number> {
+    return createSocketHandler<{ sessionId: string; command: string }, number>(
+      this.socket,
+      'cmd:exec',
+      () => ({ sessionId, command })
+    );
+  }
+
+  /**
+   * 中止命令执行
+   * @param sessionId 会话 ID
+   */
+  async abort(sessionId: string): Promise<void> {
+    return createSocketHandler<{ sessionId: string }, void>(
+      this.socket,
+      'cmd:abort',
+      () => ({ sessionId })
+    );
+  }
+
+  /**
+   * 监听命令输出
+   * @param sessionId 会话 ID
+   * @param callback 输出回调函数，接收 Uint8Array 数据（浏览器环境）
+   * @returns 取消监听的函数
+   */
+  onOutput(
+    sessionId: string,
+    callback: (data: Uint8Array) => void
+  ): () => void {
+    const eventName = `cmd:exec-output-${sessionId}`;
+    return onSocketEvent<Uint8Array>(this.socket, eventName, callback);
+  }
+}