@clawroom/sdk 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawroom/sdk",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "ClawRoom SDK — polling client and protocol types for connecting any agent to ClawRoom",
   "type": "module",
   "license": "MIT",
@@ -19,5 +19,7 @@
   "files": [
     "src"
   ],
-  "dependencies": {}
+  "dependencies": {
+    "@clawroom/protocol": "^0.5.1"
+  }
 }

package/src/client.ts

@@ -1,29 +1,31 @@
 import type {
+  AgentChatProfile,
   AgentMessage,
   ServerTask,
   ServerChatMessage,
 } from "./protocol.js";
+import { WsTransport } from "./ws-transport.js";
 
 const DEFAULT_ENDPOINT = "https://clawroom.site9.ai/api/agents";
-
 const HEARTBEAT_INTERVAL_MS = 30_000;
 const POLL_INTERVAL_MS = 10_000;
+const DEFAULT_AGENT_CHAT_PROFILE: AgentChatProfile = {
+  role: "No role defined",
+  systemPrompt: "No system prompt configured",
+  memory: "No memory recorded yet",
+  focus: "No focus items",
+};
 
 export type TaskCallback = (task: ServerTask) => void;
 export type ChatCallback = (messages: ServerChatMessage[]) => void;
 
 export type ClawroomClientOptions = {
-  /** HTTP base URL. Defaults to https://clawroom.site9.ai/api/agents */
   endpoint?: string;
-  /** Agent secret token */
   token: string;
-  /** Device identifier */
   deviceId: string;
-  /** Agent skills */
   skills: string[];
-  /** Agent kind (e.g. "openclaw", "claude-code", "codex", "custom"). Defaults to "openclaw" */
   kind?: string;
-  /** Optional logger */
+  wsUrl?: string;
   log?: {
     info?: (message: string, ...args: unknown[]) => void;
     warn?: (message: string, ...args: unknown[]) => void;
@@ -32,34 +34,8 @@ export type ClawroomClientOptions = {
 };
 
 /**
- * ClawRoom SDK client using HTTP polling.
- *
- * Agents register with /heartbeat and receive assigned tasks + chat via /poll.
- * All agent actions (complete, fail, progress, chat reply) use HTTP POST.
- *
- * Usage:
- * ```ts
- * import { ClawroomClient } from "@clawroom/sdk";
- *
- * const client = new ClawroomClient({
- *   token: "your-agent-secret",
- *   deviceId: "my-agent-1",
- *   skills: ["translation", "coding"],
- * });
- *
- * client.onTask((task) => {
- *   // task was assigned to this agent — execute it
- *   client.send({ type: "agent.complete", taskId: task.taskId, output: "Done!" });
- * });
- *
- * client.onChatMessage((messages) => {
- *   for (const msg of messages) {
- *     client.send({ type: "agent.chat.reply", channelId: msg.channelId, content: "Hello!" });
- *   }
- * });
- *
- * client.connect();
- * ```
+ * ClawRoom SDK client.
+ * WebSocket primary for real-time push, HTTP polling as fallback.
  */
 export class ClawroomClient {
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
@@ -67,27 +43,80 @@ export class ClawroomClient {
   protected stopped = false;
   protected readonly httpBase: string;
   protected readonly options: ClawroomClientOptions;
-
   protected taskCallbacks: TaskCallback[] = [];
   protected chatCallbacks: ChatCallback[] = [];
+  private wsTransport: WsTransport | null = null;
+  private recentChatIds = new Set<string>();
 
   constructor(options: ClawroomClientOptions) {
     this.options = options;
     this.httpBase = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
   }
 
+  private get wsUrl(): string {
+    if (this.options.wsUrl) return this.options.wsUrl;
+    return this.httpBase.replace(/\/api\/agents$/, "").replace(/^http/, "ws") + "/api/ws";
+  }
+
   connect(): void {
     this.stopped = false;
     this.startHeartbeat();
-    this.stopPolling();
-    this.pollTimer = setInterval(() => void this.pollTick(), POLL_INTERVAL_MS);
     void this.register();
+
+    // WebSocket transport
+    this.wsTransport = new WsTransport({
+      url: this.wsUrl,
+      token: this.options.token,
+      log: { info: (m) => this.options.log?.info?.(m), warn: (m) => this.options.log?.warn?.(m) },
+      onConnected: () => { this.options.log?.info?.("[clawroom] WebSocket connected"); },
+      onDisconnected: () => { this.options.log?.info?.("[clawroom] WebSocket disconnected"); },
+      onMessage: (msg) => {
+        if (msg.type === "task" && msg.task) {
+          for (const cb of this.taskCallbacks) cb(msg.task);
+        }
+        if (msg.type === "chat" && Array.isArray(msg.messages)) {
+          const fresh = msg.messages.filter((m: ServerChatMessage) => this.rememberChat(m.messageId));
+          if (fresh.length > 0) {
+            for (const cb of this.chatCallbacks) cb(fresh);
+            this.ackChatBestEffort(fresh.map((m: ServerChatMessage) => m.messageId));
+          }
+        }
+        if (msg.type === "message" && msg.message) {
+          const agentProfile = msg.agentProfile ?? msg.message.agentProfile ?? DEFAULT_AGENT_CHAT_PROFILE;
+          const delivered = [{
+            messageId: msg.message.id ?? msg.messageId,
+            channelId: msg.message.channelId ?? "",
+            content: msg.message.content ?? "",
+            context: Array.isArray(msg.context) ? msg.context : [],
+            isMention: msg.isMention ?? false,
+            agentProfile,
+          }] as ServerChatMessage[];
+          const fresh = delivered.filter((m) => this.rememberChat(m.messageId));
+          if (fresh.length > 0) {
+            for (const cb of this.chatCallbacks) cb(fresh);
+            this.ackChatBestEffort(fresh.map((m) => m.messageId));
+          }
+        }
+      },
+    });
+    this.wsTransport.connect();
+
+    // Keep HTTP polling active even when WS is up.
+    // WS is the fast path; polling is the durable delivery path.
+    this.stopPolling();
+    this.pollTimer = setInterval(() => {
+      void this.pollTick();
+    }, POLL_INTERVAL_MS);
+
+    void this.pollTick();
   }
 
   disconnect(): void {
     this.stopped = true;
     this.stopHeartbeat();
     this.stopPolling();
+    this.wsTransport?.disconnect();
+    this.wsTransport = null;
   }
 
   send(message: AgentMessage): void {
@@ -97,7 +126,7 @@ export class ClawroomClient {
   onTask(cb: TaskCallback): void { this.taskCallbacks.push(cb); }
   onChatMessage(cb: ChatCallback): void { this.chatCallbacks.push(cb); }
 
-  // ── Heartbeat ───────────────────────────────────────────────────
+  // ── Heartbeat ─────────────────────────────────────────
 
   private startHeartbeat(): void {
     this.stopHeartbeat();
@@ -133,15 +162,17 @@ export class ClawroomClient {
     try {
       const res = await this.httpRequest("POST", "/poll", {});
       this.onPollSuccess(res?.agentId);
-
       if (res.task) {
         this.options.log?.info?.(`[clawroom] received task ${res.task.taskId}: ${res.task.title}`);
         for (const cb of this.taskCallbacks) cb(res.task);
       }
-
       if (res.chat && Array.isArray(res.chat) && res.chat.length > 0) {
-        this.options.log?.info?.(`[clawroom] received ${res.chat.length} chat mention(s)`);
-        for (const cb of this.chatCallbacks) cb(res.chat);
+        const fresh = res.chat.filter((m: ServerChatMessage) => this.rememberChat(m.messageId));
+        if (fresh.length > 0) {
+          this.options.log?.info?.(`[clawroom] received ${fresh.length} chat mention(s)`);
+          for (const cb of this.chatCallbacks) cb(fresh);
+          this.ackChatBestEffort(fresh.map((m: ServerChatMessage) => m.messageId));
+        }
       }
     } catch (err) {
       this.options.log?.warn?.(`[clawroom] poll error: ${err}`);
@@ -149,12 +180,10 @@ export class ClawroomClient {
     }
   }
 
-  /** Override in subclass for lifecycle tracking */
   protected onPollSuccess(_agentId: string | undefined): void {}
-  /** Override in subclass for lifecycle tracking */
   protected onPollError(_err: unknown): void {}
 
-  // ── HTTP ────────────────────────────────────────────────────────
+  // ── HTTP ──────────────────────────────────────────────
 
   private async sendViaHttp(message: AgentMessage): Promise<void> {
     switch (message.type) {
@@ -167,7 +196,7 @@ export class ClawroomClient {
     }
   }
 
-  protected async httpRequest(method: string, path: string, body: unknown): Promise<any> {
+  protected async httpRequest(method: string, path: string, body: unknown): Promise<unknown> {
     const res = await fetch(`${this.httpBase}${path}`, {
       method,
       headers: { "Content-Type": "application/json", "Authorization": `Bearer ${this.options.token}` },
@@ -181,6 +210,28 @@ export class ClawroomClient {
     return res.json();
   }
 
-  /** Override in subclass for error handling (e.g. 401 auto-stop) */
   protected onHttpError(_status: number, _text: string): void {}
+
+  private rememberChat(messageId?: string): boolean {
+    if (!messageId) return true;
+    if (this.recentChatIds.has(messageId)) return false;
+    this.recentChatIds.add(messageId);
+    if (this.recentChatIds.size > 1000) {
+      const oldest = this.recentChatIds.values().next().value;
+      if (oldest) this.recentChatIds.delete(oldest);
+    }
+    return true;
+  }
+
+  private ackChatBestEffort(messageIds: string[]): void {
+    void this.ackChat(messageIds).catch((err) => {
+      this.options.log?.warn?.(`[clawroom] chat ack error: ${err}`);
+    });
+  }
+
+  private async ackChat(messageIds: string[]): Promise<void> {
+    const ids = Array.from(new Set(messageIds.filter(Boolean)));
+    if (ids.length === 0) return;
+    await this.httpRequest("POST", "/chat/ack", { messageIds: ids });
+  }
 }

package/src/index.ts

@@ -2,8 +2,11 @@ export { ClawroomClient } from "./client.js";
 export type { ClawroomClientOptions } from "./client.js";
 export { ClawroomMachineClient } from "./machine-client.js";
 export type { ClawroomMachineClientOptions } from "./machine-client.js";
+export { WsTransport } from "./ws-transport.js";
+export type { WsTransportOptions } from "./ws-transport.js";
 
 export type {
+  AgentChatProfile,
   AgentMessage,
   AgentHeartbeat,
   AgentComplete,

package/src/machine-client.ts

@@ -1,14 +1,18 @@
 /**
  * ClawRoom Machine Client — machine-level auth with multi-agent support.
+ * WebSocket primary for real-time push, HTTP polling as fallback.
  */
 
 import * as os from "node:os";
+import type { AgentChatProfile, ServerChatMessage } from "./protocol.js";
+import { WsTransport } from "./ws-transport.js";
 
 export type ClawroomMachineClientOptions = {
   endpoint?: string;
   apiKey: string;
   hostname?: string;
   capabilities?: string[];
+  wsUrl?: string;
   log?: {
     info?: (message: string, ...args: unknown[]) => void;
     warn?: (message: string, ...args: unknown[]) => void;
@@ -20,7 +24,24 @@ type AgentWork = {
   agentId: string;
   agentName: string;
   task: { type: "server.task"; taskId: string; title: string; description: string; input: string; skillTags: string[] } | null;
-  chat: Array<{ messageId: string; channelId: string; content: string; isMention: boolean; context: unknown[] }> | null;
+  chat: ServerChatMessage[] | null;
+};
+
+const DEFAULT_AGENT_CHAT_PROFILE: AgentChatProfile = {
+  role: "No role defined",
+  systemPrompt: "No system prompt configured",
+  memory: "No memory recorded yet",
+  focus: "No focus items",
+};
+
+type MachineHeartbeatResponse = {
+  machineId: string;
+  agents?: Array<{ id: string }>;
+};
+
+type MachinePollResponse = {
+  machineId: string;
+  agents: AgentWork[];
 };
 
 export class ClawroomMachineClient {
@@ -29,8 +50,13 @@ export class ClawroomMachineClient {
   private pollTimer: ReturnType<typeof setInterval> | null = null;
   private taskHandler: ((agentId: string, task: AgentWork["task"]) => void) | null = null;
   private chatHandler: ((agentId: string, messages: NonNullable<AgentWork["chat"]>) => void) | null = null;
+  private connectHandler: ((machineId: string) => void) | null = null;
+  private disconnectHandler: (() => void) | null = null;
   private _connected = false;
   private _stopped = false;
+  private wsTransport: WsTransport | null = null;
+  private subscribedAgentIds = new Set<string>();
+  private recentChatIds = new Map<string, number>();
 
   constructor(options: ClawroomMachineClientOptions) {
     this.options = options;
@@ -40,31 +66,29 @@ export class ClawroomMachineClient {
     return this.options.endpoint ?? "http://localhost:3000/api/machines";
   }
 
+  private get wsUrl(): string {
+    if (this.options.wsUrl) return this.options.wsUrl;
+    return this.baseUrl.replace(/\/api\/machines$/, "").replace(/^http/, "ws") + "/api/ws";
+  }
+
   private async httpRequest(method: string, path: string, body?: unknown): Promise<unknown> {
     const url = `${this.baseUrl}${path}`;
     const res = await fetch(url, {
       method,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.options.apiKey}`,
-      },
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.options.apiKey}` },
       body: body ? JSON.stringify(body) : undefined,
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
     return res.json();
   }
 
-  onAgentTask(handler: (agentId: string, task: AgentWork["task"]) => void) {
-    this.taskHandler = handler;
-  }
-
-  onAgentChat(handler: (agentId: string, messages: NonNullable<AgentWork["chat"]>) => void) {
-    this.chatHandler = handler;
-  }
+  onAgentTask(handler: (agentId: string, task: AgentWork["task"]) => void) { this.taskHandler = handler; }
+  onAgentChat(handler: (agentId: string, messages: NonNullable<AgentWork["chat"]>) => void) { this.chatHandler = handler; }
+  onConnected(handler: (machineId: string) => void) { this.connectHandler = handler; }
+  onDisconnected(handler: () => void) { this.disconnectHandler = handler; }
 
-  async sendAgentComplete(agentId: string, taskId: string, output: string) {
-    // Use agent-level API via machine auth proxy (or direct)
-    await this.httpRequest("POST", "/complete", { agentId, taskId, output });
+  async sendAgentComplete(agentId: string, taskId: string, output: string, attachments?: Array<{ filename: string; mimeType: string; data: string }>) {
+    await this.httpRequest("POST", "/complete", { agentId, taskId, output, attachments });
   }
 
   async sendAgentFail(agentId: string, taskId: string, reason: string) {
@@ -79,43 +103,145 @@ export class ClawroomMachineClient {
     await this.httpRequest("POST", "/typing", { agentId, channelId });
   }
 
+  async ackAgentChat(agentId: string, messageIds: string[]) {
+    const ids = Array.from(new Set(messageIds.filter(Boolean)));
+    if (ids.length === 0) return;
+    await this.httpRequest("POST", "/chat-ack", { agentId, messageIds: ids });
+  }
+
   get connected() { return this._connected; }
   get stopped() { return this._stopped; }
 
+  private rememberChat(messageId: string): boolean {
+    if (!messageId) return true;
+    const now = Date.now();
+    for (const [id, seenAt] of this.recentChatIds) {
+      if (now - seenAt > 10 * 60_000) this.recentChatIds.delete(id);
+    }
+    if (this.recentChatIds.has(messageId)) return false;
+    this.recentChatIds.set(messageId, now);
+    return true;
+  }
+
+  private ackAgentChatBestEffort(agentId: string, messageIds: string[]) {
+    void this.ackAgentChat(agentId, messageIds).catch((err) => {
+      this.options.log?.warn?.(`[machine] chat ack error: ${err}`);
+    });
+  }
+
+  private syncAgentSubscriptions(agentIds: string[]) {
+    if (agentIds.length === 0) return;
+    for (const agentId of agentIds) {
+      this.subscribedAgentIds.add(agentId);
+      this.wsTransport?.send({ type: "subscribe_agent", agentId });
+    }
+  }
+
+  private markConnected(machineId: string) {
+    if (!this._connected) {
+      this._connected = true;
+      this.options.log?.info?.("[machine] connected");
+      this.connectHandler?.(machineId);
+    }
+  }
+
+  private markDisconnected() {
+    if (this._connected) {
+      this._connected = false;
+      this.options.log?.warn?.("[machine] disconnected");
+      this.disconnectHandler?.();
+    }
+  }
+
+  private async pollOnce() {
+    if (!this._connected) return;
+    try {
+      const result = (await this.httpRequest("POST", "/poll", {})) as MachinePollResponse;
+      this.syncAgentSubscriptions(result.agents.map((agent) => agent.agentId));
+      for (const agent of result.agents) {
+        if (agent.task && this.taskHandler) this.taskHandler(agent.agentId, agent.task);
+        if (agent.chat && agent.chat.length > 0 && this.chatHandler) {
+          const freshMessages = agent.chat.filter((message) => this.rememberChat(message.messageId));
+          if (freshMessages.length > 0) {
+            this.chatHandler(agent.agentId, freshMessages);
+            this.ackAgentChatBestEffort(agent.agentId, freshMessages.map((message) => message.messageId));
+          }
+        }
+      }
+    } catch (err) {
+      this.options.log?.warn?.(`[machine] poll error: ${err}`);
+    }
+  }
+
   connect() {
     this._stopped = false;
     const hostname = this.options.hostname ?? os.hostname();
     const hbBody = { hostname, capabilities: this.options.capabilities };
 
-    // Heartbeat every 30s
+    // Heartbeat every 30s (always HTTP)
     this.heartbeatTimer = setInterval(async () => {
       try {
-        await this.httpRequest("POST", "/heartbeat", hbBody);
-        if (!this._connected) { this._connected = true; this.options.log?.info?.("[machine] connected"); }
-      } catch (err) {
-        if (this._connected) { this._connected = false; this.options.log?.warn?.("[machine] disconnected"); }
-        this.options.log?.warn?.(`[machine] heartbeat error: ${err}`);
+        const result = (await this.httpRequest("POST", "/heartbeat", hbBody)) as MachineHeartbeatResponse;
+        this.syncAgentSubscriptions((result.agents ?? []).map((agent) => agent.id));
+        this.markConnected(result.machineId);
+      } catch {
+        this.markDisconnected();
       }
     }, 30_000);
 
-    // Initial heartbeat
     this.httpRequest("POST", "/heartbeat", hbBody)
-      .then(() => { this._connected = true; this.options.log?.info?.("[machine] connected"); })
+      .then((result) => {
+        const data = result as MachineHeartbeatResponse;
+        this.syncAgentSubscriptions((data.agents ?? []).map((agent) => agent.id));
+        this.markConnected(data.machineId);
+      })
       .catch((err) => this.options.log?.warn?.(`[machine] initial heartbeat failed: ${err}`));
 
-    // Poll every 10s
-    this.pollTimer = setInterval(async () => {
-      if (!this._connected) return;
-      try {
-        const result = (await this.httpRequest("POST", "/poll", {})) as { machineId: string; agents: AgentWork[] };
-        for (const agent of result.agents) {
-          if (agent.task && this.taskHandler) this.taskHandler(agent.agentId, agent.task);
-          if (agent.chat && agent.chat.length > 0 && this.chatHandler) this.chatHandler(agent.agentId, agent.chat);
+    // WebSocket transport
+    this.wsTransport = new WsTransport({
+      url: this.wsUrl,
+      token: this.options.apiKey,
+      log: { info: (m) => this.options.log?.info?.(m), warn: (m) => this.options.log?.warn?.(m) },
+      onConnected: () => {
+        this.syncAgentSubscriptions([...this.subscribedAgentIds]);
+        this.options.log?.info?.("[machine] WebSocket connected");
+      },
+      onDisconnected: () => {
+        this.options.log?.info?.("[machine] WebSocket disconnected, HTTP polling active");
+      },
+      onMessage: (msg) => {
+        if (msg.type === "message") {
+          const m = msg.message;
+          const targetAgentId = msg.agentId ?? m?.agentId;
+          const messageId = m?.id ?? msg.messageId ?? "";
+          if (m && targetAgentId && this.chatHandler && this.rememberChat(messageId)) {
+            const agentProfile = msg.agentProfile ?? m.agentProfile ?? DEFAULT_AGENT_CHAT_PROFILE;
+            const messages = [{
+              messageId,
+              channelId: m.channelId ?? "",
+              content: m.content ?? "",
+              isMention: msg.isMention ?? false,
+              context: msg.context ?? [],
+              agentProfile,
+            }];
+            this.chatHandler(targetAgentId, messages);
+            this.ackAgentChatBestEffort(targetAgentId, messages.map((message) => message.messageId));
+          }
         }
-      } catch (err) {
-        this.options.log?.warn?.(`[machine] poll error: ${err}`);
-      }
+        if (msg.type === "task" && msg.agentId && this.taskHandler) {
+          this.taskHandler(msg.agentId, msg.task);
+        }
+      },
+    });
+    this.wsTransport.connect();
+
+    // Keep HTTP polling active even when WS is up.
+    // Machine WS chat delivery is best-effort; polling is the durable delivery path.
+    this.pollTimer = setInterval(async () => {
+      await this.pollOnce();
     }, 10_000);
+
+    void this.pollOnce();
   }
 
   disconnect() {
@@ -123,5 +249,7 @@ export class ClawroomMachineClient {
     this._connected = false;
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
     if (this.pollTimer) clearInterval(this.pollTimer);
+    this.wsTransport?.disconnect();
+    this.wsTransport = null;
   }
 }

package/src/protocol.ts

@@ -1,83 +1,21 @@
-// ClawRoom protocol types.
-// These define the messages exchanged between agents and the server.
-
-// ---- Agent -> Server ----
-
-export interface AgentHeartbeat {
-  type: "agent.heartbeat";
-}
-
-export interface AgentResultFile {
-  filename: string;
-  mimeType: string;
-  data: string; // base64 encoded
-}
-
-export interface AgentComplete {
-  type: "agent.complete";
-  taskId: string;
-  output: string;
-  attachments?: AgentResultFile[];
-}
-
-export interface AgentProgress {
-  type: "agent.progress";
-  taskId: string;
-  message: string;
-  percent?: number;
-}
-
-export interface AgentFail {
-  type: "agent.fail";
-  taskId: string;
-  reason: string;
-}
-
-export interface AgentChatReply {
-  type: "agent.chat.reply";
-  channelId: string;
-  content: string;
-  replyTo?: string;
-}
-
-export interface AgentTyping {
-  type: "agent.typing";
-  channelId: string;
-}
-
-export type AgentMessage =
-  | AgentHeartbeat
-  | AgentComplete
-  | AgentProgress
-  | AgentFail
-  | AgentChatReply
-  | AgentTyping;
-
-// ---- Server -> Agent ----
-
-export interface ServerTask {
-  type: "server.task";
-  taskId: string;
-  title: string;
-  description: string;
-  input: string;
-  skillTags: string[];
-}
-
-export interface ServerChatMessage {
-  messageId: string;
-  channelId: string;
-  content: string;
-  isMention: boolean;
-  context: Array<{
-    id: string;
-    senderType: string;
-    senderName: string;
-    content: string;
-    createdAt: number;
-  }>;
-}
-
-export type ServerMessage =
-  | ServerTask
-  | ServerChatMessage;
+export type {
+  AgentChatProfile,
+  AgentHeartbeat,
+  AgentResultFile,
+  AgentComplete,
+  AgentProgress,
+  AgentFail,
+  AgentChatReply,
+  AgentTyping,
+  AgentMessage,
+  ServerTask,
+  ServerChatMessage,
+  ServerMessage,
+  RuntimeDef,
+} from "@clawroom/protocol";
+
+export {
+  RUNTIMES,
+  BRIDGE_MANAGED_RUNTIME_IDS,
+  RUNTIME_MAP,
+} from "@clawroom/protocol";

package/src/ws-transport.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared WebSocket transport with auto-reconnect and fallback support.
+ * Used by both ClawroomClient and ClawroomMachineClient.
+ */
+
+export type WsTransportOptions = {
+  url: string;
+  token: string;
+  onMessage: (msg: any) => void;
+  onConnected: () => void;
+  onDisconnected: () => void;
+  log?: {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+  };
+};
+
+export class WsTransport {
+  private ws: any = null;
+  private options: WsTransportOptions;
+  private _connected = false;
+  private stopped = false;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectDelay = 1000;
+  private failCount = 0;
+
+  static readonly MAX_RECONNECT_DELAY = 60_000;
+  static readonly MAX_RECONNECT_FAILS = 10;
+
+  constructor(options: WsTransportOptions) {
+    this.options = options;
+  }
+
+  get connected() { return this._connected; }
+
+  async connect() {
+    if (this.stopped) return;
+
+    let WebSocket: any;
+    try {
+      WebSocket = (await import("ws")).default;
+    } catch {
+      this.options.log?.info?.("ws module not available, skipping WebSocket");
+      return;
+    }
+
+    try {
+      this.ws = new WebSocket(this.options.url);
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws.on("open", () => {
+      this.reconnectDelay = 1000;
+      this.ws.send(JSON.stringify({ type: "auth", token: this.options.token }));
+    });
+
+    this.ws.on("message", (raw: any) => {
+      let msg: any;
+      try { msg = JSON.parse(raw.toString()); } catch { return; }
+
+      if (msg.type === "auth_ok") {
+        this._connected = true;
+        this.failCount = 0;
+        this.options.onConnected();
+        return;
+      }
+
+      if (msg.type === "auth_error") {
+        this._connected = false;
+        this.options.log?.warn?.(`WS auth failed: ${msg.error ?? "unknown"}`);
+        this.ws?.close();
+        return;
+      }
+
+      if (msg.type === "pong") return;
+
+      this.options.onMessage(msg);
+    });
+
+    this.ws.on("close", () => {
+      const wasConnected = this._connected;
+      this._connected = false;
+      if (wasConnected) this.options.onDisconnected();
+      if (!this.stopped) this.scheduleReconnect();
+    });
+
+    this.ws.on("error", () => {
+      this._connected = false;
+    });
+  }
+
+  send(msg: any) {
+    if (this._connected && this.ws?.readyState === 1) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  disconnect() {
+    this.stopped = true;
+    this._connected = false;
+    if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null; }
+    if (this.ws) { this.ws.close(); this.ws = null; }
+  }
+
+  private scheduleReconnect() {
+    if (this.stopped || this.reconnectTimer) return;
+
+    this.failCount++;
+    if (this.failCount > WsTransport.MAX_RECONNECT_FAILS) {
+      this.options.log?.warn?.(`WS reconnect failed ${this.failCount} times, giving up. HTTP polling active.`);
+      return;
+    }
+
+    const jitter = Math.random() * 3000;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, Math.min(this.reconnectDelay + jitter, WsTransport.MAX_RECONNECT_DELAY));
+    this.reconnectDelay = Math.min(this.reconnectDelay * 2, WsTransport.MAX_RECONNECT_DELAY);
+  }
+}