@lcap/wave-sandbox-sdk 0.0.1

package/dist/client.d.ts

@@ -0,0 +1,64 @@
+import { type Socket } from 'socket.io-client';
+import { ExecModule } from './modules/exec.js';
+import { FileSystemModule } from './modules/file-system.js';
+import { PortModule } from './modules/port.js';
+import { ProjectModule } from './modules/project.js';
+import { AgentModule } from './modules/agent.js';
+import type { SDKOptions } from './types/index.js';
+/**
+ * Wave Sandbox SDK 客户端
+ */
+export declare class WaveSandboxClient {
+    private socket;
+    readonly exec: ExecModule;
+    readonly fileSystem: FileSystemModule;
+    /** 文件系统模块的简写别名 */
+    get fs(): FileSystemModule;
+    readonly port: PortModule;
+    readonly project: ProjectModule;
+    readonly agent: AgentModule;
+    constructor(options: SDKOptions);
+    /**
+     * 连接到服务器
+     */
+    connect(): void;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 检查是否已连接
+     */
+    get connected(): boolean;
+    /**
+     * 获取 Socket ID
+     */
+    get id(): string | undefined;
+    /**
+     * 监听连接事件
+     */
+    onConnect(callback: () => void): () => void;
+    /**
+     * 监听断开连接事件
+     */
+    onDisconnect(callback: () => void): () => void;
+    /**
+     * 监听错误事件
+     */
+    onError(callback: (error: Error) => void): () => void;
+    /**
+     * 监听重连尝试事件
+     * @param callback 回调函数，参数为当前重连尝试次数
+     */
+    onReconnectAttempt(callback: (attempt: number) => void): () => void;
+    /**
+     * 监听重连成功事件
+     * @param callback 回调函数，参数为重连尝试次数
+     */
+    onReconnect(callback: (attempt: number) => void): () => void;
+    /**
+     * 监听重连失败事件（达到最大重连次数后触发）
+     */
+    onReconnectFailed(callback: () => void): () => void;
+    getSocket(): Socket;
+}

package/dist/client.js

@@ -0,0 +1,126 @@
+import { io } from 'socket.io-client';
+import { ExecModule } from './modules/exec.js';
+import { FileSystemModule } from './modules/file-system.js';
+import { PortModule } from './modules/port.js';
+import { ProjectModule } from './modules/project.js';
+import { AgentModule } from './modules/agent.js';
+/**
+ * Wave Sandbox SDK 客户端
+ */
+export class WaveSandboxClient {
+    /** 文件系统模块的简写别名 */
+    get fs() {
+        return this.fileSystem;
+    }
+    constructor(options) {
+        const { url, projectId, options: socketOptions } = options;
+        const uri = new URL(url);
+        let pathname = uri.pathname;
+        if (pathname.endsWith('/')) {
+            pathname = pathname.slice(0, pathname.length - 1);
+        }
+        pathname = pathname + '/socket.io/';
+        // 构建 Socket.IO 连接选项
+        const connectOptions = {
+            autoConnect: socketOptions?.autoConnect ?? true,
+            reconnection: socketOptions?.reconnection ?? true,
+            reconnectionDelay: socketOptions?.reconnectionDelay ?? 1000,
+            reconnectionAttempts: socketOptions?.reconnectionAttempts ?? 5,
+            query: projectId ? { projectId } : undefined,
+            path: pathname,
+        };
+        // 创建 Socket.IO 连接
+        this.socket = io(uri.host, connectOptions);
+        // 初始化各个模块
+        this.exec = new ExecModule(this.socket);
+        this.fileSystem = new FileSystemModule(this.socket, url, projectId);
+        this.port = new PortModule(this.socket);
+        this.project = new ProjectModule(this.socket, url, projectId);
+        this.agent = new AgentModule(this.socket, url, projectId);
+    }
+    /**
+     * 连接到服务器
+     */
+    connect() {
+        if (!this.socket.connected) {
+            this.socket.connect();
+        }
+    }
+    /**
+     * 断开连接
+     */
+    disconnect() {
+        this.socket.disconnect();
+    }
+    /**
+     * 检查是否已连接
+     */
+    get connected() {
+        return this.socket.connected;
+    }
+    /**
+     * 获取 Socket ID
+     */
+    get id() {
+        return this.socket.id;
+    }
+    /**
+     * 监听连接事件
+     */
+    onConnect(callback) {
+        this.socket.on('connect', callback);
+        return () => {
+            this.socket.off('connect', callback);
+        };
+    }
+    /**
+     * 监听断开连接事件
+     */
+    onDisconnect(callback) {
+        this.socket.on('disconnect', callback);
+        return () => {
+            this.socket.off('disconnect', callback);
+        };
+    }
+    /**
+     * 监听错误事件
+     */
+    onError(callback) {
+        this.socket.on('error', callback);
+        return () => {
+            this.socket.off('error', callback);
+        };
+    }
+    /**
+     * 监听重连尝试事件
+     * @param callback 回调函数，参数为当前重连尝试次数
+     */
+    onReconnectAttempt(callback) {
+        this.socket.io.on('reconnect_attempt', callback);
+        return () => {
+            this.socket.io.off('reconnect_attempt', callback);
+        };
+    }
+    /**
+     * 监听重连成功事件
+     * @param callback 回调函数，参数为重连尝试次数
+     */
+    onReconnect(callback) {
+        this.socket.io.on('reconnect', callback);
+        return () => {
+            this.socket.io.off('reconnect', callback);
+        };
+    }
+    /**
+     * 监听重连失败事件（达到最大重连次数后触发）
+     */
+    onReconnectFailed(callback) {
+        this.socket.io.on('reconnect_failed', callback);
+        return () => {
+            this.socket.io.off('reconnect_failed', callback);
+        };
+    }
+    getSocket() {
+        return this.socket;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { WaveSandboxClient } from './client.js';
+export type { SDKOptions } from './types/index.js';
+export type { HttpSuccessResponse, HttpErrorResponse, HttpResponse, SocketSuccessResponse, SocketErrorResponse, SocketResponse, FileType, FileStat, DirectoryItem, FileChangeType, FileChangeEvent, PortStatusType, PortStatusChangedEvent, ProjectInfo, ProjectFile, TextBlock, ToolBlock, ErrorBlock, SubagentBlock, McpServerConfig, McpServerStatus, } from './types/index.js';
+export { ExecModule } from './modules/exec.js';
+export { FileSystemModule } from './modules/file-system.js';
+export { PortModule } from './modules/port.js';
+export { ProjectModule } from './modules/project.js';
+export { AgentModule } from './modules/agent.js';
+export type { Attachment, SendMessageOptions, ProcessQueueItem, MessageQueueChangedEvent, MessageSendEvent, MessageRunningEvent, MessageFinishedEvent, InitializingEvent, InitializedEvent, MessageBlockAddedEvent, MessageBlockUpdatedEvent, MessageToolBlockUpdatedEvent, MessageSubagentBlockAddEvent, MessageSubagentBlockStatusUpdatedEvent, MessageSubagentBlockContentUpdatedEvent, MessageSubagentToolBlockUpdatedEvent, MessageErrorBlockAddedEvent, MessageCommandOutputMessageAddedEvent, MessageCommandOutputMessageUpdatedEvent, MessageCommandOutputMessageCompletedEvent, McpServersChangeEvent, DocumentParseStartEvent, DocumentParseCompleteEvent, DocumentParseErrorEvent, AgentEventMap, AgentEventName, } from './modules/agent.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { WaveSandboxClient } from './client.js';
+// 导出各个模块（可选，用于高级用法）
+export { ExecModule } from './modules/exec.js';
+export { FileSystemModule } from './modules/file-system.js';
+export { PortModule } from './modules/port.js';
+export { ProjectModule } from './modules/project.js';
+export { AgentModule } from './modules/agent.js';

package/dist/modules/agent.d.ts

@@ -0,0 +1,448 @@
+import type { Socket } from 'socket.io-client';
+import type { TextBlock, ToolBlock, ErrorBlock, SubagentBlock, McpServerStatus, AssistantMessage } from '../types/agent-types.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 declare class AgentModule {
+    private socket;
+    private baseUrl;
+    private projectId?;
+    constructor(socket: Socket, baseUrl: string, projectId?: string | undefined);
+    /**
+     * 获取查询参数
+     */
+    private getQueryParams;
+    /**
+     * 发送消息
+     * @param options 发送消息选项
+     * @returns Promise<string> 返回 assistantMessageId
+     */
+    sendMessage(options: SendMessageOptions): Promise<string>;
+    /**
+     * 中止消息
+     * @param messageId 消息 ID
+     */
+    abortMessage(messageId: string): Promise<void>;
+    /**
+     * 删除 session，包括日志记录和 agent 对象
+     * @param sessionId 会话 ID
+     * @throws 如果当前正在处理该 session 的消息，则抛出错误
+     */
+    removeSession(sessionId: string): Promise<void>;
+    /**
+     * 获取指定 session 的消息日志文件列表
+     * @param sessionId 会话 ID
+     * @returns Promise<string[] | null> 返回文件列表（倒序，最新的在前），如果没有文件则返回 null
+     */
+    getSessionFiles(sessionId: string): Promise<string[] | null>;
+    /**
+     * 获取当前 wave-agent 的完整状态
+     * @returns Promise<MessageQueueChangedEvent | null> 返回当前状态，如果没有活动状态则返回 null
+     */
+    getCurrentState(): Promise<MessageQueueChangedEvent | null>;
+    /**
+     * 监听消息发送事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageSend(callback: (event: MessageSendEvent) => void): () => void;
+    /**
+     * 监听消息运行事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageRunning(callback: (event: MessageRunningEvent) => void): () => void;
+    /**
+     * 监听消息完成事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageFinished(callback: (event: MessageFinishedEvent) => void): () => void;
+    /**
+     * 监听消息队列变化事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageQueueChanged(callback: (event: MessageQueueChangedEvent) => void): () => void;
+    /**
+     * 监听初始化事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onInitializing(callback: (event: InitializingEvent) => void): () => void;
+    /**
+     * 监听初始化完成事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onInitialized(callback: (event: InitializedEvent) => void): () => void;
+    /**
+     * 监听消息块添加事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageBlockAdded(callback: (event: MessageBlockAddedEvent) => void): () => void;
+    /**
+     * 监听消息块更新事件（用于流式内容更新）
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageBlockUpdated(callback: (event: MessageBlockUpdatedEvent) => void): () => void;
+    /**
+     * 监听工具块更新事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageToolBlockUpdated(callback: (event: MessageToolBlockUpdatedEvent) => void): () => void;
+    /**
+     * 监听子代理块添加事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageSubagentBlockAdd(callback: (event: MessageSubagentBlockAddEvent) => void): () => void;
+    /**
+     * 监听子代理块状态更新事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageSubagentBlockStatusUpdated(callback: (event: MessageSubagentBlockStatusUpdatedEvent) => void): () => void;
+    /**
+     * 监听子代理块内容更新事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageSubagentBlockContentUpdated(callback: (event: MessageSubagentBlockContentUpdatedEvent) => void): () => void;
+    /**
+     * 监听子代理工具块更新事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageSubagentToolBlockUpdated(callback: (event: MessageSubagentToolBlockUpdatedEvent) => void): () => void;
+    /**
+     * 监听错误块添加事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageErrorBlockAdded(callback: (event: MessageErrorBlockAddedEvent) => void): () => void;
+    /**
+     * 监听命令输出消息添加事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageCommandOutputMessageAdded(callback: (event: MessageCommandOutputMessageAddedEvent) => void): () => void;
+    /**
+     * 监听命令输出消息更新事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageCommandOutputMessageUpdated(callback: (event: MessageCommandOutputMessageUpdatedEvent) => void): () => void;
+    /**
+     * 监听命令输出消息完成事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMessageCommandOutputMessageCompleted(callback: (event: MessageCommandOutputMessageCompletedEvent) => void): () => void;
+    /**
+     * 监听 MCP 服务器变化事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onMcpServersChange(callback: (event: McpServersChangeEvent) => void): () => void;
+    /**
+     * 监听文档解析开始事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onDocumentParseStart(callback: (event: DocumentParseStartEvent) => void): () => void;
+    /**
+     * 监听文档解析完成事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onDocumentParseComplete(callback: (event: DocumentParseCompleteEvent) => void): () => void;
+    /**
+     * 监听文档解析错误事件
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    onDocumentParseError(callback: (event: DocumentParseErrorEvent) => void): () => void;
+    /**
+     * 通用事件监听方法，用于监听自定义事件
+     * @param eventName 事件名称（必须以 'agent:' 开头）
+     * @param callback 回调函数
+     * @returns 取消监听的函数
+     */
+    on<T = unknown>(eventName: string, callback: (event: T) => void): () => void;
+}