@agentdock/sdk 0.4.0

package/README.md

@@ -0,0 +1,101 @@
+# @agentbox/sdk
+
+> 客户端 SDK — Socket.IO 连接管理 + 类型安全 RPC + 离线队列。
+
+## 概述
+
+sdk 包为 Web 前端和其他客户端提供与 AgentBox server 的连接能力：
+
+- **自动重连**：断线后指数退避重连，连接状态实时可观测
+- **RPC 封装**：类型安全的远程调用，Promise 风格
+- **离线队列**：断线期间的 RPC 调用自动入队，重连后按序 flush
+- **事件流**：订阅 CoreUpdate 实时推送
+
+## 在架构中的位置
+
+```
+wire → crypto → sdk → web
+```
+
+依赖 wire（协议定义）和 crypto（加密），被 web 包使用。
+
+## 模块结构
+
+```
+src/
+├── client.ts  # AgentboxClient — 连接管理 + 事件订阅 + 状态监听
+├── rpc.ts     # RpcClient — 类型安全 RPC + 离线队列 + flush
+└── index.ts   # Barrel exports
+```
+
+## API 参考
+
+### createClient (client.ts)
+
+```typescript
+import { createClient } from '@agentbox/sdk';
+import type { AgentboxClient, ClientConfig } from '@agentbox/sdk';
+
+const client: AgentboxClient = createClient({
+  serverUrl: 'https://api.agentbox.dev',
+  token: 'user-auth-token',
+  clientType: 'web', // 'web' | 'daemon' | 'cli'
+  autoConnect: true, // 默认 true
+});
+
+// 连接状态监听
+const unsub = client.onStatus((status: ConnectionStatus) => {
+  // 'connected' | 'connecting' | 'disconnected' | 'error'
+  console.log('Connection:', status);
+});
+
+// 订阅实时更新
+const unsub2 = client.onUpdate((update: CoreUpdate) => {
+  // 处理增量更新（会话事件、消息等）
+});
+
+// 手动连接/断开
+client.connect();
+client.disconnect(); // 清理所有事件监听器（L16 教训）
+```
+
+### createRpcClient (rpc.ts)
+
+```typescript
+import { createRpcClient } from '@agentbox/sdk';
+import type { RpcClient, RpcTransport } from '@agentbox/sdk';
+
+const rpc: RpcClient = createRpcClient(transport);
+
+// 调用 RPC 方法（在线时立即发送，离线时入队）
+const result: RpcResult = await rpc.call('method-name', params);
+
+// 离线队列在重连时自动 flush（带互斥锁防竞态，L19 教训）
+```
+
+### 类型定义
+
+```typescript
+type ConnectionStatus = 'connected' | 'connecting' | 'disconnected' | 'error';
+type ClientType = 'web' | 'daemon' | 'cli';
+type Unsubscribe = () => void;
+type StatusListener = (status: ConnectionStatus) => void;
+type UpdateListener = (update: CoreUpdate) => void;
+```
+
+## 开发
+
+```bash
+# 运行测试（42 tests）
+pnpm --filter @agentbox/sdk test
+
+# 覆盖率（目标 90%+）
+pnpm --filter @agentbox/sdk test:coverage
+```
+
+## 设计决策
+
+- **Socket.IO 而非原生 WebSocket**：自动重连、命名空间、房间、二进制支持
+- **RPC + 离线队列**：离线期间操作不丢失，重连后补发
+- **flush 互斥锁**：防止两次 reconnect 触发竞态（L19 教训）
+- **disconnect 清理**：所有 `on()` 注册都有对应 `off()` 清理（L16 教训）

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * AgentBox SDK client — Socket.IO connection management.
+ *
+ * Provides a uniform interface for connecting to the AgentBox server
+ * with auto-reconnection, status tracking, and event handling.
+ */
+import { type Socket } from 'socket.io-client';
+/** Connection status for the client. */
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** Client scope type for auth. */
+export type ClientType = 'user-scoped' | 'session-scoped' | 'machine-scoped';
+/** Status change listener. */
+export type StatusListener = (status: ConnectionStatus) => void;
+/** Update data listener. */
+export type UpdateListener = (data: unknown) => void;
+/** Unsubscribe function returned by event registration. */
+export type Unsubscribe = () => void;
+/** Socket factory — returns a Socket-like object. Used for DI in tests. */
+export type SocketFactory = (endpoint: string, opts: Record<string, unknown>) => Socket;
+/** Client configuration. */
+export interface ClientConfig {
+    /** Server endpoint URL. */
+    readonly endpoint: string;
+    /** Authentication token. */
+    readonly token: string;
+    /** Socket.IO path (default: '/v1/updates'). */
+    readonly path?: string;
+    /** Client scope type (default: 'user-scoped'). */
+    readonly clientType?: ClientType;
+    /** Session ID (required for session-scoped). */
+    readonly sessionId?: string;
+    /** Machine ID (required for machine-scoped). */
+    readonly machineId?: string;
+    /** Reconnection delay in ms (default: 1000). */
+    readonly reconnectionDelay?: number;
+    /** Max reconnection delay in ms (default: 5000). */
+    readonly reconnectionDelayMax?: number;
+    /** Internal: socket factory for testing. */
+    readonly _socketFactory?: SocketFactory;
+}
+/** AgentBox client interface. */
+export interface AgentboxClient {
+    /** Connect to the server. */
+    connect(): void;
+    /** Disconnect from the server. */
+    disconnect(): void;
+    /** Get the current connection status. */
+    getStatus(): ConnectionStatus;
+    /** Listen for status changes. Returns unsubscribe function. */
+    onStatusChange(listener: StatusListener): Unsubscribe;
+    /** Listen for server update events. Returns unsubscribe function. */
+    onUpdate(listener: UpdateListener): Unsubscribe;
+    /** Emit an event with acknowledgement (RPC-style). */
+    emitWithAck<T>(event: string, data: unknown): Promise<T>;
+    /** Subscribe to a raw socket event. Returns unsubscribe function. */
+    on(event: string, handler: (...args: unknown[]) => void): Unsubscribe;
+    /** Emit a raw socket event (fire-and-forget). */
+    emit(event: string, ...args: unknown[]): void;
+}
+export declare function createClient(config: ClientConfig): AgentboxClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAM,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wCAAwC;AACxC,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAErF,kCAAkC;AAClC,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE7E,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEhE,4BAA4B;AAC5B,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;AAErD,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;AAExF,4BAA4B;AAC5B,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC;CACzC;AAED,iCAAiC;AACjC,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,OAAO,IAAI,IAAI,CAAC;IAChB,kCAAkC;IAClC,UAAU,IAAI,IAAI,CAAC;IACnB,yCAAyC;IACzC,SAAS,IAAI,gBAAgB,CAAC;IAC9B,+DAA+D;IAC/D,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,WAAW,CAAC;IACtD,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,WAAW,CAAC;IAChD,sDAAsD;IACtD,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzD,qEAAqE;IACrE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,WAAW,CAAC;IACtE,iDAAiD;IACjD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/C;AAYD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAiJjE"}

package/dist/client.js

@@ -0,0 +1,145 @@
+/**
+ * AgentBox SDK client — Socket.IO connection management.
+ *
+ * Provides a uniform interface for connecting to the AgentBox server
+ * with auto-reconnection, status tracking, and event handling.
+ */
+import { io } from 'socket.io-client';
+import createDebug from 'debug';
+// ── Factory ─────────────────────────────────────────────────────────
+/**
+ * Create an AgentBox client instance.
+ *
+ * @param config - Client configuration.
+ * @returns An AgentboxClient ready to be connected.
+ */
+const log = createDebug('agentbox:sdk:client');
+export function createClient(config) {
+    let status = 'disconnected';
+    let socket = null;
+    const statusListeners = new Set();
+    const updateListeners = new Set();
+    const createSocket = config._socketFactory ?? io;
+    // Buffer for event listeners registered before connect()
+    const pendingListeners = [];
+    function setStatus(newStatus) {
+        status = newStatus;
+        for (const listener of statusListeners) {
+            listener(newStatus);
+        }
+    }
+    function emitUpdate(data) {
+        for (const listener of updateListeners) {
+            listener(data);
+        }
+    }
+    function buildAuth() {
+        const auth = {
+            token: config.token,
+            clientType: config.clientType ?? 'user-scoped',
+        };
+        if (config.sessionId) {
+            auth['sessionId'] = config.sessionId;
+        }
+        if (config.machineId) {
+            auth['machineId'] = config.machineId;
+        }
+        return auth;
+    }
+    return {
+        connect() {
+            if (socket)
+                return;
+            setStatus('connecting');
+            socket = createSocket(config.endpoint, {
+                path: config.path ?? '/v1/updates',
+                auth: buildAuth(),
+                transports: ['websocket', 'polling'],
+                reconnection: true,
+                reconnectionDelay: config.reconnectionDelay ?? 1000,
+                reconnectionDelayMax: config.reconnectionDelayMax ?? 5000,
+                reconnectionAttempts: Infinity,
+                autoConnect: false,
+            });
+            socket.on('connect', () => {
+                log('connected to %s', config.endpoint);
+                setStatus('connected');
+            });
+            socket.on('disconnect', (reason) => {
+                log('disconnected: %s', reason);
+                setStatus('disconnected');
+            });
+            socket.on('connect_error', (err) => {
+                log('connect_error: %s', err instanceof Error ? err.message : err);
+                setStatus('error');
+            });
+            socket.on('update', (data) => {
+                emitUpdate(data);
+            });
+            socket.on('ephemeral', (data) => {
+                emitUpdate(data);
+            });
+            // Replay any event listeners registered before connect()
+            for (const { event, handler } of pendingListeners) {
+                socket.on(event, handler);
+            }
+            pendingListeners.length = 0;
+            // Connect after all listeners are registered (avoids race with autoConnect)
+            socket.connect();
+        },
+        disconnect() {
+            if (socket) {
+                // Clean up all event listeners before disconnecting (L16)
+                socket.removeAllListeners();
+                socket.disconnect();
+                socket = null;
+                setStatus('disconnected');
+            }
+        },
+        getStatus() {
+            return status;
+        },
+        onStatusChange(listener) {
+            statusListeners.add(listener);
+            return () => {
+                statusListeners.delete(listener);
+            };
+        },
+        onUpdate(listener) {
+            updateListeners.add(listener);
+            return () => {
+                updateListeners.delete(listener);
+            };
+        },
+        async emitWithAck(event, data) {
+            if (!socket || !socket.connected) {
+                throw new Error('Not connected');
+            }
+            return socket.emitWithAck(event, data);
+        },
+        on(event, handler) {
+            if (socket) {
+                socket.on(event, handler);
+            }
+            else {
+                pendingListeners.push({ event, handler });
+            }
+            return () => {
+                if (socket) {
+                    socket.off(event, handler);
+                }
+                else {
+                    const idx = pendingListeners.findIndex((p) => p.event === event && p.handler === handler);
+                    if (idx !== -1)
+                        pendingListeners.splice(idx, 1);
+                }
+            };
+        },
+        emit(event, ...args) {
+            if (socket?.connected) {
+                socket.emit(event, ...args);
+            }
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createClient } from './client.js';
+export type { AgentboxClient, ClientConfig, ClientType, ConnectionStatus, StatusListener, UpdateListener, Unsubscribe, } from './client.js';
+export { createRpcClient } from './rpc.js';
+export type { RpcClient, RpcTransport, RpcResult } from './rpc.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EACV,cAAc,EACd,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// @agentdock/sdk — Client SDK for AgentBox
+export { createClient } from './client.js';
+export { createRpcClient } from './rpc.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU3C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}

package/dist/rpc.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RPC client — typed method calls over Socket.IO with offline queue.
+ *
+ * When disconnected, calls are queued and automatically flushed
+ * when the transport reconnects.
+ */
+/** RPC call result. */
+export interface RpcResult<T = unknown> {
+    readonly ok: boolean;
+    readonly result?: T;
+    readonly error?: string;
+}
+/** Transport abstraction for RPC calls. */
+export interface RpcTransport {
+    /** Emit an event and wait for acknowledgement. */
+    emitWithAck<T>(event: string, data: unknown): Promise<T>;
+    /** Whether the transport is currently connected. */
+    isConnected(): boolean;
+}
+/** RPC client interface. */
+export interface RpcClient {
+    /** Call an RPC method. Queues if disconnected. */
+    call<T = unknown>(method: string, params: unknown): Promise<RpcResult<T>>;
+    /** Get the number of queued (offline) calls. */
+    getQueueSize(): number;
+    /** Flush queued calls (call after reconnection). */
+    flush(): Promise<void>;
+}
+/**
+ * Create an RPC client.
+ *
+ * @param transport - Transport layer for sending RPC calls.
+ * @returns An RpcClient instance.
+ */
+export declare function createRpcClient(transport: RpcTransport): RpcClient;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,uBAAuB;AACvB,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzD,oDAAoD;IACpD,WAAW,IAAI,OAAO,CAAC;CACxB;AAUD,4BAA4B;AAC5B,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,gDAAgD;IAChD,YAAY,IAAI,MAAM,CAAC;IACvB,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,CAyDlE"}

package/dist/rpc.js

@@ -0,0 +1,72 @@
+/**
+ * RPC client — typed method calls over Socket.IO with offline queue.
+ *
+ * When disconnected, calls are queued and automatically flushed
+ * when the transport reconnects.
+ */
+import createDebug from 'debug';
+const log = createDebug('agentbox:sdk:rpc');
+// ── Factory ─────────────────────────────────────────────────────────
+/**
+ * Create an RPC client.
+ *
+ * @param transport - Transport layer for sending RPC calls.
+ * @returns An RpcClient instance.
+ */
+export function createRpcClient(transport) {
+    const queue = [];
+    let isFlushing = false;
+    async function executeCall(method, params) {
+        return transport.emitWithAck('rpc-call', {
+            method,
+            params,
+        });
+    }
+    return {
+        call(method, params) {
+            if (transport.isConnected()) {
+                log('call %s', method);
+                return executeCall(method, params);
+            }
+            log('queued %s (offline, queue=%d)', method, queue.length + 1);
+            return new Promise((resolve, reject) => {
+                queue.push({
+                    method,
+                    params,
+                    resolve: resolve,
+                    reject,
+                });
+            });
+        },
+        getQueueSize() {
+            return queue.length;
+        },
+        async flush() {
+            if (!transport.isConnected())
+                return;
+            if (isFlushing)
+                return;
+            isFlushing = true;
+            log('flushing %d queued calls', queue.length);
+            try {
+                while (queue.length > 0) {
+                    const item = queue.shift();
+                    if (!item)
+                        break;
+                    try {
+                        const result = await executeCall(item.method, item.params);
+                        item.resolve(result);
+                    }
+                    catch (err) {
+                        log('flush failed for %s: %s', item.method, err);
+                        item.reject(err instanceof Error ? err : new Error(String(err)));
+                    }
+                }
+            }
+            finally {
+                isFlushing = false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,WAAW,MAAM,OAAO,CAAC;AAEhC,MAAM,GAAG,GAAG,WAAW,CAAC,kBAAkB,CAAC,CAAC;AAmC5C,uEAAuE;AAEvE;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAuB;IACrD,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,IAAI,UAAU,GAAG,KAAK,CAAC;IAEvB,KAAK,UAAU,WAAW,CAAI,MAAc,EAAE,MAAe;QAC3D,OAAO,SAAS,CAAC,WAAW,CAAe,UAAU,EAAE;YACrD,MAAM;YACN,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,IAAI,CAAc,MAAc,EAAE,MAAe;YAC/C,IAAI,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC;gBAC5B,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;gBACvB,OAAO,WAAW,CAAI,MAAM,EAAE,MAAM,CAAC,CAAC;YACxC,CAAC;YAED,GAAG,CAAC,+BAA+B,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC/D,OAAO,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACnD,KAAK,CAAC,IAAI,CAAC;oBACT,MAAM;oBACN,MAAM;oBACN,OAAO,EAAE,OAAmC;oBAC5C,MAAM;iBACP,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;QAED,YAAY;YACV,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE;gBAAE,OAAO;YACrC,IAAI,UAAU;gBAAE,OAAO;YACvB,UAAU,GAAG,IAAI,CAAC;YAClB,GAAG,CAAC,0BAA0B,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAE9C,IAAI,CAAC;gBACH,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;oBAC3B,IAAI,CAAC,IAAI;wBAAE,MAAM;oBAEjB,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;wBAC3D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;oBACvB,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;wBACjD,IAAI,CAAC,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACnE,CAAC;gBACH,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,UAAU,GAAG,KAAK,CAAC;YACrB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@agentdock/sdk",
+  "version": "0.4.0",
+  "description": "Client SDK for AgentDock — Socket.IO, RPC, offline queue",
+  "license": "UNLICENSED",
+  "author": "kevin8536945",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "debug": "^4.4.3",
+    "socket.io-client": "^4.8.3",
+    "@agentdock/wire": "0.4.0",
+    "@agentdock/crypto": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@vitest/coverage-v8": "^3.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ && tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  }
+}