@adep/client 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @adep/client — AgentDeploy 实时客户端
+
+> **实时通道订阅库**（任务单 RT-005）：`换票 → 建连 → 订阅 → 断线自动重连 → 对称心跳`。独立于页面框架，可被非 Page 场景（如 widget 卡片渲染）复用。
+
+```bash
+npm install @adep/client
+# 或
+pnpm add @adep/client
+```
+
+## 能力总览
+
+- **票据换连**：向平台换取实时票据（ticket），以票据建立 WebSocket 连接
+- **订阅 / 取消订阅**：按通道订阅实时事件
+- **自动重连**：断线后自动重连并恢复订阅状态
+- **对称心跳**：客户端与服务端对称心跳保活
+
+## 用法
+
+```ts
+import { RealtimeClient } from '@adep/client'
+
+const client = new RealtimeClient({ server: 'wss://api.example.com' })
+await client.connect()
+
+const off = client.subscribe('room:1', (msg) => {
+  console.log('收到实时消息', msg)
+})
+
+// 不需要时取消订阅并关闭
+off()
+await client.disconnect()
+```
+
+## 说明
+
+- 仅依赖 `@adep/types` 提供消息类型契约。
+- 协议细节（票据端点 / 心跳间隔 / 重连退避）见 `packages/docs/features/realtime.md`。

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@adep/client` —— AgentDeploy 实时客户端订阅库（任务单 RT-005）。
+ *
+ * 独立 npm 包（跨边界类型契约在 `@adep/types`，运行时实现归本包），可被非 Page 场景复用：
+ * - Web / Nuxt 页面（换票带 better-auth 会话 cookie）；
+ * - FE-003 Agent 卡片渲染抽象（浏览器宿主接通 realtime 通道）；
+ * - 服务端组件 / MCP 侧（换票带 API Key，见 `httpTicketProvider` 注入 header）。
+ *
+ * 导出面 = 主类 `RealtimeClient` + 便捷工厂 `createRealtimeClient` + 换票 HTTP 提供者
+ * `httpTicketProvider` + socket 适配（`SocketFactory` / 默认工厂）+ 复用的平台实时类型。
+ */
+export { RealtimeClient, createRealtimeClient, REALTIME_SUBPROTOCOL, CLOSE_INVALID_TICKET, CLOSE_UNAUTHORIZED_SUBSCRIPTION, } from './realtime/client';
+export type { RealtimeClientOptions, RealtimeClientStatus, TicketContext, TicketProvider, TicketResult, } from './realtime/client';
+export { httpTicketProvider, TicketExchangeError } from './realtime/http-ticket';
+export type { HttpTicketProviderOptions } from './realtime/http-ticket';
+export { defaultSocketFactory } from './realtime/socket';
+export type { RealtimeSocket, SocketFactory, SocketCloseInfo } from './realtime/socket';
+export type { RealtimeChannelMessage, RealtimeClientEvent, RealtimeServerEvent } from '@adep/types';

package/dist/index.js

@@ -0,0 +1,332 @@
+// packages/client/src/realtime/socket.ts
+function adaptNativeSocket(ws) {
+  const socket = {
+    get readyState() {
+      return ws.readyState;
+    },
+    send: (data) => {
+      ws.send(data);
+    },
+    close: (code, reason) => {
+      ws.close(code, reason);
+    },
+    onopen: null,
+    onmessage: null,
+    onclose: null,
+    onerror: null
+  };
+  ws.onopen = () => socket.onopen?.();
+  ws.onmessage = (event) => socket.onmessage?.(String(event.data));
+  ws.onclose = (event) => {
+    socket.onclose?.({
+      code: event.code,
+      reason: event.reason,
+      wasClean: event.wasClean
+    });
+  };
+  ws.onerror = () => socket.onerror?.();
+  return socket;
+}
+function defaultSocketFactory() {
+  return (url, protocols) => adaptNativeSocket(new WebSocket(url, protocols));
+}
+
+// packages/client/src/realtime/client.ts
+var REALTIME_SUBPROTOCOL = "adep.v1";
+var CLOSE_INVALID_TICKET = 4400;
+var CLOSE_UNAUTHORIZED_SUBSCRIPTION = 4401;
+var WS_OPEN = 1;
+function toWsUrl(baseUrl, path) {
+  const rest = baseUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  const scheme = baseUrl.startsWith("https://") ? "wss://" : "ws://";
+  return `${scheme}${rest}${path}`;
+}
+function isChannelMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj.channel === "string" && typeof obj.seq === "number" && "data" in obj && typeof obj.publishedAt === "string";
+}
+function isServerEvent(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const type = value.type;
+  return type === "subscribed" || type === "unsubscribed" || type === "error";
+}
+var RealtimeClient = class {
+  baseUrl;
+  projectId;
+  channel;
+  exchangeTicket;
+  onMessage;
+  onStatus;
+  onReconnected;
+  reconnectInitialMs;
+  reconnectMaxMs;
+  heartbeatMs;
+  factory;
+  logFn;
+  socket = null;
+  channels;
+  started = false;
+  closedByUser = false;
+  rejected = false;
+  attempt = 0;
+  status = "idle";
+  reconnectTimer = null;
+  heartbeatTimer = null;
+  pendingOpen = null;
+  constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.projectId = options.projectId;
+    this.channel = options.channel;
+    this.exchangeTicket = options.exchangeTicket;
+    this.onMessage = options.onMessage;
+    this.onStatus = options.onStatus;
+    this.onReconnected = options.onReconnected;
+    this.reconnectInitialMs = options.reconnect?.initialMs ?? 1e3;
+    this.reconnectMaxMs = options.reconnect?.maxMs ?? 3e4;
+    this.heartbeatMs = options.heartbeatIntervalMs ?? 15e3;
+    this.factory = options.socketFactory ?? defaultSocketFactory();
+    this.logFn = options.log;
+    this.channels = /* @__PURE__ */ new Set([options.channel]);
+  }
+  get currentStatus() {
+    return this.status;
+  }
+  get socketReadyState() {
+    return this.socket?.readyState ?? 3;
+  }
+  /** 在下次进入 `open`（或已在 open）时 resolve；用于「建连 → 订阅」链路的接入等待。 */
+  whenOpen() {
+    if (this.status === "open") return Promise.resolve();
+    return new Promise((resolve) => {
+      this.pendingOpen = resolve;
+    });
+  }
+  /** 启动订阅库：换票 → 建连 → 订阅并保持。 */
+  start() {
+    this.started = true;
+    this.closedByUser = false;
+    this.rejected = false;
+    this.attempt = 0;
+    this.clearReconnectTimer();
+    this.connect(0);
+  }
+  /** 追加订阅一个 channel（已 OPEN 时即时下发订阅帧；否则随下次建连一并订阅）。 */
+  subscribe(channel) {
+    this.channels.add(channel);
+    const ws = this.socket;
+    if (ws !== null && ws.readyState === WS_OPEN) {
+      this.sendFrame(ws, { type: "subscribe", channel });
+    }
+  }
+  /** 退订某 channel。 */
+  unsubscribe(channel) {
+    this.channels.delete(channel);
+    const ws = this.socket;
+    if (ws !== null && ws.readyState === WS_OPEN) {
+      this.sendFrame(ws, { type: "unsubscribe", channel });
+    }
+  }
+  /** 主动断开：停止自动重连，正常关闭 socket。 */
+  disconnect() {
+    this.closedByUser = true;
+    this.started = false;
+    this.clearReconnectTimer();
+    this.stopHeartbeat();
+    const ws = this.socket;
+    this.socket = null;
+    if (ws !== null && ws.readyState === WS_OPEN) {
+      ws.close(1e3, "client-disconnect");
+    }
+    this.setStatus("closed");
+  }
+  // —— 建连 / 重连 ——
+  connect(attempt) {
+    this.attempt = attempt;
+    this.setStatus(attempt === 0 ? "connecting" : "reconnecting");
+    this.stopHeartbeat();
+    Promise.resolve(this.exchangeTicket({ baseUrl: this.baseUrl, projectId: this.projectId })).then(({ ticket }) => {
+      if (!this.started || this.closedByUser || this.rejected) return;
+      const url = toWsUrl(this.baseUrl, `/v1/realtime/ws/${encodeURIComponent(this.channel)}`);
+      const ws = this.factory(url, [ticket, REALTIME_SUBPROTOCOL]);
+      ws.onopen = () => this.onSocketOpen(ws);
+      ws.onmessage = (data) => this.onMessageFrame(data);
+      ws.onclose = (info) => this.onSocketClose(ws, info);
+      ws.onerror = () => {
+      };
+      this.socket = ws;
+      this.logFn?.("realtime \u5EFA\u8FDE", { attempt, channel: this.channel });
+      this.startHeartbeat();
+      return void 0;
+    }).catch((error) => {
+      this.logFn?.("realtime \u6362\u7968\u5931\u8D25", { error: String(error) });
+      this.rejected = true;
+      this.stopHeartbeat();
+      this.setStatus("error");
+    });
+  }
+  onSocketOpen(ws) {
+    if (ws !== this.socket) return;
+    for (const channel of this.channels) {
+      this.sendFrame(ws, { type: "subscribe", channel });
+    }
+    this.setStatus("open");
+    if (this.attempt > 0) {
+      this.onReconnected?.({ channel: this.channel, attempt: this.attempt });
+    }
+  }
+  onSocketClose(ws, info) {
+    if (ws !== this.socket) return;
+    this.socket = null;
+    this.stopHeartbeat();
+    if (this.closedByUser) {
+      this.setStatus("closed");
+      return;
+    }
+    const authReject = info.code === CLOSE_INVALID_TICKET || info.code === CLOSE_UNAUTHORIZED_SUBSCRIPTION;
+    if (authReject) {
+      this.rejected = true;
+      this.setStatus("error");
+      return;
+    }
+    this.setStatus("reconnecting");
+    this.scheduleReconnect(this.attempt + 1);
+  }
+  scheduleReconnect(nextAttempt) {
+    if (!this.started || this.closedByUser || this.rejected) return;
+    this.clearReconnectTimer();
+    const delay = Math.min(this.reconnectInitialMs * 2 ** nextAttempt, this.reconnectMaxMs);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.started && !this.closedByUser && !this.rejected) {
+        this.connect(nextAttempt);
+      }
+    }, delay);
+  }
+  // —— 心跳（对称 watchdog）——
+  startHeartbeat() {
+    this.stopHeartbeat();
+    if (this.heartbeatMs <= 0) return;
+    this.heartbeatTimer = setInterval(() => this.tickHeartbeat(), this.heartbeatMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  tickHeartbeat() {
+    if (!this.started || this.closedByUser || this.rejected) return;
+    const ws = this.socket;
+    if (ws === null) return;
+    if (ws.readyState !== WS_OPEN) {
+      this.logFn?.("realtime \u5FC3\u8DF3\u68C0\u6D4B\u5230\u5931\u6548\u8FDE\u63A5\uFF0C\u89E6\u53D1\u91CD\u8FDE", {
+        readyState: ws.readyState
+      });
+      this.socket = null;
+      this.stopHeartbeat();
+      this.setStatus("reconnecting");
+      this.scheduleReconnect(this.attempt + 1);
+    }
+  }
+  // —— 帧处理 ——
+  onMessageFrame(data) {
+    let frame;
+    try {
+      frame = JSON.parse(data);
+    } catch {
+      this.logFn?.("realtime \u6536\u5230\u975E JSON \u4E0B\u884C\u5E27\uFF0C\u5FFD\u7565", { data: String(data).slice(0, 64) });
+      return;
+    }
+    if (isChannelMessage(frame)) {
+      this.onMessage?.(frame);
+      return;
+    }
+    if (isServerEvent(frame)) {
+      if (frame.type === "error") {
+        this.logFn?.("realtime \u670D\u52A1\u7AEF\u9519\u8BEF\u5E27", { code: frame.code, message: frame.message });
+      }
+      return;
+    }
+    this.logFn?.("realtime \u6536\u5230\u672A\u77E5\u4E0B\u884C\u5E27\uFF0C\u5FFD\u7565", { frame });
+  }
+  sendFrame(ws, frame) {
+    if (ws.readyState === WS_OPEN) {
+      ws.send(JSON.stringify(frame));
+    }
+  }
+  clearReconnectTimer() {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+  setStatus(status) {
+    this.status = status;
+    if (status === "open") {
+      const resolve = this.pendingOpen;
+      this.pendingOpen = null;
+      resolve?.();
+    }
+    this.onStatus?.(status);
+  }
+};
+function createRealtimeClient(options) {
+  return new RealtimeClient(options);
+}
+
+// packages/client/src/realtime/http-ticket.ts
+var TicketExchangeError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "TicketExchangeError";
+  }
+};
+function errorCodeOf(body) {
+  if (typeof body === "object" && body !== null) {
+    const err = body.error;
+    if (typeof err?.code === "string") return err.code;
+  }
+  return "RT_TICKET_HTTP";
+}
+var joinUrl = (baseUrl, path) => `${baseUrl.replace(/\/+$/, "")}${path}`;
+function httpTicketProvider(options = {}) {
+  return async ({ baseUrl, projectId }) => {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(joinUrl(baseUrl, "/api/v1/realtime/ticket"), {
+      method: "POST",
+      headers: { "content-type": "application/json", ...options.headers },
+      body: JSON.stringify({ projectId })
+    });
+    if (!response.ok) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = void 0;
+      }
+      throw new TicketExchangeError(
+        response.status,
+        errorCodeOf(body),
+        `\u6362\u7968\u5931\u8D25\uFF08HTTP ${response.status}\uFF09`
+      );
+    }
+    const data = await response.json();
+    if (typeof data.ticket !== "string" || typeof data.expiresIn !== "number") {
+      throw new TicketExchangeError(response.status, "RT_TICKET_HTTP", "\u6362\u7968\u54CD\u5E94\u7F3A\u5C11 ticket \u5B57\u6BB5");
+    }
+    return { ticket: data.ticket, expiresIn: data.expiresIn };
+  };
+}
+export {
+  CLOSE_INVALID_TICKET,
+  CLOSE_UNAUTHORIZED_SUBSCRIPTION,
+  REALTIME_SUBPROTOCOL,
+  RealtimeClient,
+  TicketExchangeError,
+  createRealtimeClient,
+  defaultSocketFactory,
+  httpTicketProvider
+};

package/dist/realtime/client.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 实时客户端订阅库核心（RT-005）——独立 npm 包 `@adep/client`。
+ *
+ * 职责（PRD §2.12.9 出口场景 / §3.2.9 客户端订阅库）：
+ * 换票 → 建连 → 订阅/退订 → 断线自动重连并重新订阅 → 对称心跳。
+ *
+ * 与服务端（RT-002/003/004，`server/domains/realtime/`）的握手契约对齐：
+ * - 票据经 `Sec-WebSocket-Protocol` 携带（**首个子协议**），服务端 `handshake.ticketFromProtocol`
+ *   取第一个子协议做一次性票据兑换；本库在票据**之后**再带一个 `adep.v1` 版本协商子协议标记。
+ * - 服务端兑换失败回关闭码：4400 = 票据无效/过期/重放，4401 = 订阅未授权。
+ * - 重连后历史**不补发**（§2.12.4），由客户端经 `onReconnected` 钩子自行从约定入口
+ *   （用户函数 / cloud.db）拉取，而非服务端 push。
+ *
+ * 断线分类：
+ * - 授权类关闭（4400/4401）→ 明确 `error` 态，**不自动重连、不重试这把票据**（验收「重放被拒不静默回退」）；
+ * - 普通网络断开（1006 等）→ 指数退避自动重连 + 重新订阅 + `onReconnected` 触发历史拉取。
+ * 心跳为「对称」的 liveness watchdog：不发明协议帧（避免误触函数派发），只周期检查连接存活，
+ * 对悬空的 CONNECTING / 僵尸连接触达重连；平台侧的自动离房由 RT-004 `PresenceTracker` 兜底。
+ */
+import type { RealtimeChannelMessage } from '@adep/types';
+import type { SocketFactory } from './socket';
+/** 与服务端协商的子协议版本标记（跟随在票据之后的第二个子协议；服务端读首个子协议为票据）。 */
+export declare const REALTIME_SUBPROTOCOL = "adep.v1";
+/** 与服务端握手关闭码对齐（`server/domains/realtime/handshake.ts`）。 */
+export declare const CLOSE_INVALID_TICKET = 4400;
+export declare const CLOSE_UNAUTHORIZED_SUBSCRIPTION = 4401;
+/** 订阅库对外暴露的生命周期状态。 */
+export type RealtimeClientStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'error';
+export interface TicketContext {
+    baseUrl: string;
+    projectId: string;
+}
+export interface TicketResult {
+    ticket: string;
+    expiresIn: number;
+}
+/** 换票提供者：旧凭据 → 一次性握手票据。可同步或异步。 */
+export type TicketProvider = (ctx: TicketContext) => Promise<TicketResult> | TicketResult;
+export interface RealtimeClientOptions {
+    /** 平台 base URL（http(s)://host[:port]），用于换票与拼接 WS 地址。 */
+    baseUrl: string;
+    /** 项目 id，换票与订阅授权的求值域。 */
+    projectId: string;
+    /** 订阅的 channel 名（连接即订阅；可用 `subscribe()` 追加更多）。 */
+    channel: string;
+    /** 换票提供者。 */
+    exchangeTicket: TicketProvider;
+    /** 收到的 channel 下行消息回调。 */
+    onMessage?: (message: RealtimeChannelMessage) => void;
+    /** 生命周期状态变更回调。 */
+    onStatus?: (status: RealtimeClientStatus) => void;
+    /** 重连成功并重新订阅后触发：客户端据此自拉历史（服务端不补发）。 */
+    onReconnected?: (info: {
+        channel: string;
+        attempt: number;
+    }) => void;
+    /** 重连退避；`initialMs` 缺省 1000，`maxMs` 缺省 30000。 */
+    reconnect?: {
+        initialMs?: number;
+        maxMs?: number;
+    };
+    /** 对称心跳间隔 ms；缺省 15000，`0` = 关闭 watchdog。 */
+    heartbeatIntervalMs?: number;
+    /** 可注入 WebSocket 工厂（单测 mock）；缺省用宿主全局 WebSocket。 */
+    socketFactory?: SocketFactory;
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+export declare class RealtimeClient {
+    private readonly baseUrl;
+    private readonly projectId;
+    private readonly channel;
+    private readonly exchangeTicket;
+    private readonly onMessage;
+    private readonly onStatus;
+    private readonly onReconnected;
+    private readonly reconnectInitialMs;
+    private readonly reconnectMaxMs;
+    private readonly heartbeatMs;
+    private readonly factory;
+    private readonly logFn;
+    private socket;
+    private readonly channels;
+    private started;
+    private closedByUser;
+    private rejected;
+    private attempt;
+    private status;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private pendingOpen;
+    constructor(options: RealtimeClientOptions);
+    get currentStatus(): RealtimeClientStatus;
+    get socketReadyState(): number;
+    /** 在下次进入 `open`（或已在 open）时 resolve；用于「建连 → 订阅」链路的接入等待。 */
+    whenOpen(): Promise<void>;
+    /** 启动订阅库：换票 → 建连 → 订阅并保持。 */
+    start(): void;
+    /** 追加订阅一个 channel（已 OPEN 时即时下发订阅帧；否则随下次建连一并订阅）。 */
+    subscribe(channel: string): void;
+    /** 退订某 channel。 */
+    unsubscribe(channel: string): void;
+    /** 主动断开：停止自动重连，正常关闭 socket。 */
+    disconnect(): void;
+    private connect;
+    private onSocketOpen;
+    private onSocketClose;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private tickHeartbeat;
+    private onMessageFrame;
+    private sendFrame;
+    private clearReconnectTimer;
+    private setStatus;
+}
+/** 便捷工厂：`createRealtimeClient(options)` 等价于 `new RealtimeClient(options)`。 */
+export declare function createRealtimeClient(options: RealtimeClientOptions): RealtimeClient;
+export type { RealtimeChannelMessage, RealtimeClientEvent, RealtimeServerEvent } from '@adep/types';

package/dist/realtime/http-ticket.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 实时通道换票 HTTP 客户端（RT-005）。
+ *
+ * 订阅库的「换票」步骤：向平台 `POST /api/v1/realtime/ticket` 换一张一次性、60s 过期、HMAC 签名的
+ * 握手票据（服务端实现 RT-002 `server/domains/realtime/auth/`）。鉴权方式随宿主而变：
+ * - 浏览器 / CLI：携带 better-auth 会话 cookie；
+ * - 服务端组件 / MCP：携带 API Key（`Authorization: Bearer ...`）。
+ * 故不内置鉴权，把「带哪些请求头」交由调用方通过 `httpTicketProvider(opts)` 注入。
+ *
+ * 零依赖：仅用全局 `fetch`（可注入 `fetchImpl` 供单测 mock，规范 §8）。
+ */
+import type { TicketProvider } from './client';
+export interface HttpTicketProviderOptions {
+    /** 随请求附带的自定义头（如 cookie / Authorization）。 */
+    headers?: Record<string, string>;
+    /** 可注入的 fetch 实现（测试 / 平台代理），缺省用全局 fetch。 */
+    fetchImpl?: typeof fetch;
+}
+/** 换票失败信封的错误形状（供调用方按 code 分支）。 */
+export declare class TicketExchangeError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/**
+ * 构造「换票」的 `TicketProvider`：POST `/api/v1/realtime/ticket`，body 只带 projectId。
+ * 成功返回服务端签发的票据；非 2xx 抛 `TicketExchangeError`（resp 信封 code，如 `RT_UNAUTHORIZED`）。
+ */
+export declare function httpTicketProvider(options?: HttpTicketProviderOptions): TicketProvider;

package/dist/realtime/socket.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 实时通道客户端 WebSocket 适配层（RT-005）。
+ *
+ * 订阅库必须能在多种宿主里复用：浏览器（FE-003 卡片渲染）、Bun（服务端组件）、Node ≥22。
+ * 原生 `WebSocket` 的形态在这三者里基本一致，但回调签名与事件对象略有出入，且单测需要注入
+ * 假 socket（规范 §8：测试不依赖外部服务、网络全部 mock）。因此抽一层最小适配：
+ * - `RealtimeSocket`：本库只依赖的 socket 投影（onopen/onmessage/onclose/onerror + send/close）。
+ * - `SocketFactory`：创建 socket 的函数——测试注入 `MockSocket`，生产用 `defaultSocketFactory()`。
+ *
+ * 纯接口 + 一个默认工厂，不引任何第三方运行时依赖（对齐 packages/types 的零依赖约束）。
+ */
+/** socket close 事件的服务端关闭信息投影（对齐浏览器的 CloseEvent 关键字段）。 */
+export interface SocketCloseInfo {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/** 本库依赖的 WebSocket 最小投影。readyState 对齐原生：0=CONNECTING / 1=OPEN / 2=CLOSING / 3=CLOSED。 */
+export interface RealtimeSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: (() => void) | null;
+    onmessage: ((data: string) => void) | null;
+    onclose: ((info: SocketCloseInfo) => void) | null;
+    onerror: (() => void) | null;
+}
+/** 创建 socket 的函数；测试可注入假实现对网络事件做完全控制。 */
+export type SocketFactory = (url: string, protocols: string[]) => RealtimeSocket;
+/** 默认工厂：使用宿主全局 `WebSocket`（浏览器 / Bun / Node ≥22 均可用）。 */
+export declare function defaultSocketFactory(): SocketFactory;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@adep/client",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "AgentDeploy 实时客户端订阅库（RT-005）：换票→建连→订阅→断线自动重连→对称心跳。独立 npm 包，可被 FE-003 卡片渲染等非 Page 场景复用（见任务单 RT-005 归属裁定）。",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "build": "bun run ../../scripts/build-package.ts client"
+  },
+  "dependencies": {
+    "@adep/types": "workspace:*"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./*": {
+        "types": "./dist/*.d.ts",
+        "default": "./dist/*.js"
+      }
+    }
+  }
+}