@lcap/wave-sandbox-sdk 0.0.1

package/dist/modules/project.js

@@ -0,0 +1,64 @@
+import { createSocketHandler, onSocketEvent } from '../utils/socket.js';
+/**
+ * 项目模块
+ */
+export class ProjectModule {
+    constructor(socket, baseUrl, projectId) {
+        this.socket = socket;
+        this.baseUrl = baseUrl;
+        this.projectId = projectId;
+    }
+    /**
+     * 获取查询参数
+     */
+    getQueryParams() {
+        if (this.projectId) {
+            return `projectId=${encodeURIComponent(this.projectId)}`;
+        }
+        return '';
+    }
+    /**
+     * 获取项目信息
+     */
+    async getInfo() {
+        const url = `${this.baseUrl}/project/info${this.projectId ? `?${this.getQueryParams()}` : ''}`;
+        const response = await fetch(url);
+        const result = await response.json();
+        if (result.status === 'error') {
+            throw new Error(result.message);
+        }
+        return result.data;
+    }
+    /**
+     * 获取项目文件列表
+     */
+    async getFiles() {
+        const url = `${this.baseUrl}/project/files${this.projectId ? `?${this.getQueryParams()}` : ''}`;
+        const response = await fetch(url);
+        const result = await response.json();
+        if (result.status === 'error') {
+            throw new Error(result.message);
+        }
+        return result.data.files;
+    }
+    /**
+     * 开始监听项目变化
+     */
+    async watch() {
+        return createSocketHandler(this.socket, 'project:watch', () => undefined);
+    }
+    /**
+     * 停止监听项目变化
+     */
+    async unwatch() {
+        return createSocketHandler(this.socket, 'project:unwatch', () => undefined);
+    }
+    /**
+     * 监听项目文件变化
+     * @param callback 文件变化回调函数
+     * @returns 取消监听的函数
+     */
+    onFileChange(callback) {
+        return onSocketEvent(this.socket, 'project:file-change', callback);
+    }
+}

package/dist/types/agent-types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Agent 消息块类型
+ * 这些类型原本来自 wave-agent-sdk，现在复制到项目中以避免外部依赖
+ */
+/**
+ * 文本块
+ */
+export interface TextBlock {
+    type: 'text';
+    content: string;
+    customCommandContent?: string;
+    source?: 'user' | 'hook';
+}
+/**
+ * 工具块
+ */
+export interface ToolBlock {
+    type: 'tool';
+    parameters?: string;
+    result?: string;
+    shortResult?: string;
+    images?: Array<{
+        data: string;
+        mediaType?: string;
+    }>;
+    id?: string;
+    name?: string;
+    /**
+     * Tool execution stage:
+     * - 'start': Tool call initiated (from AI service streaming)
+     * - 'streaming': Tool parameters being streamed (from AI service)
+     * - 'running': Tool execution in progress (from AI manager)
+     * - 'end': Tool execution completed (from AI manager)
+     */
+    stage: 'start' | 'streaming' | 'running' | 'end';
+    success?: boolean;
+    error?: string | Error;
+    compactParams?: string;
+    parametersChunk?: string;
+}
+/**
+ * 错误块
+ */
+export interface ErrorBlock {
+    type: 'error';
+    content: string;
+}
+export interface SubagentConfiguration {
+    name: string;
+    description: string;
+    tools?: string[];
+    model?: string;
+    systemPrompt: string;
+    filePath: string;
+    scope: 'project' | 'user';
+    priority: number;
+}
+/**
+ * 子代理块
+ */
+export interface SubagentBlock {
+    type: 'subagent';
+    subagentId: string;
+    subagentName: string;
+    status: 'active' | 'completed' | 'error' | 'aborted';
+    configuration: SubagentConfiguration;
+    blocks: AssistantBlock[];
+}
+/**
+ * MCP 服务器配置
+ */
+export interface McpServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * MCP 服务器状态
+ */
+export interface McpServerStatus {
+    name: string;
+    config: McpServerConfig;
+    status: 'disconnected' | 'connected' | 'connecting' | 'error';
+    tools?: Array<{
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+    }>;
+    toolCount?: number;
+    capabilities?: string[];
+    lastConnected?: number;
+    error?: string;
+}
+/**
+ * 附件接口
+ */
+export interface Attachment {
+    url?: string;
+    path?: string;
+    mimeType: string;
+    content?: string;
+}
+/**
+ * 发送消息选项
+ */
+export interface SendMessageOptions {
+    id: string;
+    sessionId: string;
+    message: string;
+    attachments?: Attachment[];
+}
+export interface UserMessage {
+    role: 'user';
+    id: string;
+    content: string;
+    attachments?: Attachment[];
+    lastModified?: number;
+}
+export type AssistantBlock = TextBlock | ToolBlock | ErrorBlock | SubagentBlock;
+export interface AssistantMessage {
+    role: 'assistant';
+    id: string;
+    blocks: AssistantBlock[];
+    status: 'pending' | 'running' | 'finished' | 'error' | 'aborted';
+    lastModified?: number;
+}
+export type ChatMessage = UserMessage | AssistantMessage;

package/dist/types/agent-types.js

@@ -0,0 +1,5 @@
+/**
+ * Agent 消息块类型
+ * 这些类型原本来自 wave-agent-sdk，现在复制到项目中以避免外部依赖
+ */
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * HTTP API 响应类型
+ */
+export interface HttpSuccessResponse<T = unknown> {
+    status: 'ok';
+    data: T;
+}
+export interface HttpErrorResponse {
+    status: 'error';
+    message: string;
+}
+export type HttpResponse<T = unknown> = HttpSuccessResponse<T> | HttpErrorResponse;
+/**
+ * Socket API 响应类型
+ */
+export interface SocketSuccessResponse<T = unknown> {
+    success: true;
+    data: T;
+}
+export interface SocketErrorResponse {
+    success: false;
+    errorMessage: string;
+}
+export type SocketResponse<T = unknown> = SocketSuccessResponse<T> | SocketErrorResponse;
+/**
+ * 文件类型
+ */
+export declare enum FileType {
+    Unknown = 0,
+    File = 1,
+    Directory = 2,
+    SymbolicLink = 64
+}
+/**
+ * 文件状态信息
+ */
+export interface FileStat {
+    type: FileType;
+    size: number;
+    ctime: number;
+    mtime: number;
+}
+/**
+ * 目录项
+ */
+export type DirectoryItem = [string, FileType];
+/**
+ * 文件变化事件类型
+ */
+export type FileChangeType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir';
+/**
+ * 文件变化事件
+ */
+export interface FileChangeEvent {
+    type: FileChangeType;
+    path: string;
+    /** 是否为二进制文件（仅在 add 和 change 事件中存在） */
+    isBinary?: boolean;
+}
+/**
+ * 端口状态类型
+ */
+export type PortStatusType = 'open' | 'close';
+/**
+ * 端口状态变化事件
+ */
+export interface PortStatusChangedEvent {
+    port: number;
+    type: PortStatusType;
+}
+/**
+ * 项目信息
+ */
+export interface ProjectInfo {
+    projectId: string;
+    workdir: string;
+    workspace: boolean;
+}
+/**
+ * 项目文件信息
+ */
+export interface ProjectFile {
+    path: string;
+}
+/**
+ * SDK 配置选项
+ */
+export interface SDKOptions {
+    /** 服务器地址，例如 'http://localhost:3030' */
+    url: string;
+    /** 项目 ID（可选，用于工作空间模式） */
+    projectId?: string;
+    /** 连接选项 */
+    options?: {
+        /** 自动连接 */
+        autoConnect?: boolean;
+        /** 重连选项 */
+        reconnection?: boolean;
+        /** 重连延迟 */
+        reconnectionDelay?: number;
+        /** 最大重连次数 */
+        reconnectionAttempts?: number;
+    };
+}
+export type { TextBlock, ToolBlock, ErrorBlock, SubagentBlock, McpServerConfig, McpServerStatus, Attachment, SendMessageOptions, UserMessage, AssistantBlock, AssistantMessage, ChatMessage, } from './agent-types.js';

package/dist/types/index.js

@@ -0,0 +1,10 @@
+/**
+ * 文件类型
+ */
+export var FileType;
+(function (FileType) {
+    FileType[FileType["Unknown"] = 0] = "Unknown";
+    FileType[FileType["File"] = 1] = "File";
+    FileType[FileType["Directory"] = 2] = "Directory";
+    FileType[FileType["SymbolicLink"] = 64] = "SymbolicLink";
+})(FileType || (FileType = {}));

package/dist/utils/socket.d.ts

@@ -0,0 +1,10 @@
+import type { Socket } from 'socket.io-client';
+/**
+ * Socket 事件处理器包装器
+ * 发送事件并等待响应
+ */
+export declare function createSocketHandler<P, R>(socket: Socket, eventName: string, getPayload: () => Promise<P> | P): Promise<R>;
+/**
+ * 监听 Socket 事件
+ */
+export declare function onSocketEvent<T>(socket: Socket, eventName: string, callback: (data: T) => void): () => void;

package/dist/utils/socket.js

@@ -0,0 +1,27 @@
+/**
+ * Socket 事件处理器包装器
+ * 发送事件并等待响应
+ */
+export function createSocketHandler(socket, eventName, getPayload) {
+    return Promise.resolve(getPayload()).then((payload) => {
+        return new Promise((resolve, reject) => {
+            socket.emit(eventName, payload, (response) => {
+                if (response.success) {
+                    resolve(response.data);
+                }
+                else {
+                    reject(new Error(response.errorMessage));
+                }
+            });
+        });
+    });
+}
+/**
+ * 监听 Socket 事件
+ */
+export function onSocketEvent(socket, eventName, callback) {
+    socket.on(eventName, callback);
+    return () => {
+        socket.off(eventName, callback);
+    };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@lcap/wave-sandbox-sdk",
+  "version": "0.0.1",
+  "description": "SDK for Wave Sandbox Client",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "socket.io-client": "^4.8.1"
+  },
+  "devDependencies": {
+    "rimraf": "^6.1.2",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "dev": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "lint": "eslint --cache",
+    "format": "prettier --write ."
+  }
+}

package/src/client.ts

@@ -0,0 +1,152 @@
+import { io, 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 class WaveSandboxClient {
+  private socket: Socket;
+  public readonly exec: ExecModule;
+  public readonly fileSystem: FileSystemModule;
+  /** 文件系统模块的简写别名 */
+  public get fs(): FileSystemModule {
+    return this.fileSystem;
+  }
+  public readonly port: PortModule;
+  public readonly project: ProjectModule;
+  public readonly agent: AgentModule;
+
+  constructor(options: SDKOptions) {
+    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(): void {
+    if (!this.socket.connected) {
+      this.socket.connect();
+    }
+  }
+
+  /**
+   * 断开连接
+   */
+  disconnect(): void {
+    this.socket.disconnect();
+  }
+
+  /**
+   * 检查是否已连接
+   */
+  get connected(): boolean {
+    return this.socket.connected;
+  }
+
+  /**
+   * 获取 Socket ID
+   */
+  get id(): string | undefined {
+    return this.socket.id;
+  }
+
+  /**
+   * 监听连接事件
+   */
+  onConnect(callback: () => void): () => void {
+    this.socket.on('connect', callback);
+    return () => {
+      this.socket.off('connect', callback);
+    };
+  }
+
+  /**
+   * 监听断开连接事件
+   */
+  onDisconnect(callback: () => void): () => void {
+    this.socket.on('disconnect', callback);
+    return () => {
+      this.socket.off('disconnect', callback);
+    };
+  }
+
+  /**
+   * 监听错误事件
+   */
+  onError(callback: (error: Error) => void): () => void {
+    this.socket.on('error', callback);
+    return () => {
+      this.socket.off('error', callback);
+    };
+  }
+
+  /**
+   * 监听重连尝试事件
+   * @param callback 回调函数，参数为当前重连尝试次数
+   */
+  onReconnectAttempt(callback: (attempt: number) => void): () => void {
+    this.socket.io.on('reconnect_attempt', callback);
+    return () => {
+      this.socket.io.off('reconnect_attempt', callback);
+    };
+  }
+
+  /**
+   * 监听重连成功事件
+   * @param callback 回调函数，参数为重连尝试次数
+   */
+  onReconnect(callback: (attempt: number) => void): () => void {
+    this.socket.io.on('reconnect', callback);
+    return () => {
+      this.socket.io.off('reconnect', callback);
+    };
+  }
+
+  /**
+   * 监听重连失败事件（达到最大重连次数后触发）
+   */
+  onReconnectFailed(callback: () => void): () => void {
+    this.socket.io.on('reconnect_failed', callback);
+    return () => {
+      this.socket.io.off('reconnect_failed', callback);
+    };
+  }
+
+  getSocket(): Socket {
+    return this.socket;
+  }
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+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';