@occum-net/occumclaw 0.1.0

package/api.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared HTTP helpers for authenticated requests to the occum.net API.
+ */
+
+export interface ToolConfig {
+  agentToken: string;
+  apiUrl: string;
+}
+
+/** Make an authenticated request to the occum.net API. */
+export async function apiRequest(
+  config: ToolConfig,
+  path: string,
+  opts?: RequestInit
+): Promise<any> {
+  const res = await fetch(`${config.apiUrl}${path}`, {
+    ...opts,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${config.agentToken}`,
+      ...opts?.headers,
+    },
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`API ${res.status}: ${body}`);
+  }
+
+  return res.json();
+}

package/index.ts

@@ -0,0 +1,472 @@
+/**
+ * @occum-net/occumclaw — OpenClaw Channel Plugin
+ *
+ * Registers occum.net as a channel in OpenClaw, following the same pattern
+ * as the Telegram connector. When a message arrives on the agent's control
+ * channel via WebSocket, it is dispatched through OpenClaw's full agent
+ * pipeline (routing → LLM → response) and the reply is POSTed back to
+ * occum.net.
+ *
+ * Configuration (set via `openclaw config set`):
+ *   channels.occum.accounts.default.agentToken  — Agent bearer token (occ_...)
+ *   channels.occum.accounts.default.apiUrl      — API base URL (default: https://api.occum.net)
+ *
+ * Legacy config path (auto-migrated):
+ *   plugins.entries.occumclaw.config.agentToken
+ *   plugins.entries.occumclaw.config.apiUrl
+ */
+
+import { OccumWsClient, type OccumEvent, type AuthOkData } from "./ws-client";
+import { apiRequest, type ToolConfig } from "./api";
+import { createSendMessageTool, createListChannelsTool, createGetEventsTool } from "./tools";
+
+// ─── OpenClaw Plugin SDK types (inline to avoid hard dependency) ────────────
+
+interface PluginLogger {
+  info(msg: string, ...args: any[]): void;
+  warn(msg: string, ...args: any[]): void;
+  error(msg: string, ...args: any[]): void;
+}
+
+interface ToolContext {
+  config: Record<string, any>;
+}
+
+/** Minimal MsgContext — only the fields we need for dispatch. */
+interface MsgContext {
+  Body?: string;
+  BodyForAgent?: string;
+  CommandBody?: string;
+  From?: string;
+  To?: string;
+  SessionKey?: string;
+  AccountId?: string;
+  Provider?: string;
+  ChatType?: string;
+  SenderId?: string;
+  SenderName?: string;
+  Timestamp?: number;
+  CommandAuthorized?: boolean;
+  MessageSid?: string;
+}
+
+interface ReplyPayload {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+  isError?: boolean;
+}
+
+interface ReplyDispatchKindInfo {
+  kind: "tool" | "block" | "final";
+}
+
+interface DispatchParams {
+  ctx: MsgContext;
+  cfg: any;
+  dispatcherOptions: {
+    deliver: (payload: ReplyPayload, info: ReplyDispatchKindInfo) => Promise<void>;
+    onError?: (err: unknown, info: ReplyDispatchKindInfo) => void;
+  };
+}
+
+interface ChannelRuntime {
+  reply: {
+    dispatchReplyWithBufferedBlockDispatcher: (params: DispatchParams) => Promise<any>;
+  };
+  routing: {
+    buildAgentSessionKey: (...args: any[]) => string;
+    resolveAgentRoute: (...args: any[]) => any;
+  };
+  session: {
+    recordInboundSession: (...args: any[]) => any;
+  };
+}
+
+interface ChannelLogSink {
+  info?(msg: string): void;
+  warn?(msg: string): void;
+  error?(msg: string): void;
+}
+
+interface ChannelGatewayContext {
+  cfg: any;
+  accountId: string;
+  account: OccumAccount;
+  runtime: any;
+  abortSignal: AbortSignal;
+  log?: ChannelLogSink;
+  getStatus: () => any;
+  setStatus: (next: any) => void;
+  channelRuntime?: ChannelRuntime;
+}
+
+interface OpenClawPluginApi {
+  logger: PluginLogger;
+  runtime?: any;
+  registerTool(
+    factory: (ctx: ToolContext) => any,
+    opts: { name: string; optional: boolean }
+  ): void;
+  registerChannel(registration: { plugin: any }): void;
+}
+
+// ─── Account Config ─────────────────────────────────────────────────────────
+
+interface OccumAccount {
+  agentToken: string;
+  apiUrl: string;
+}
+
+function resolveApiUrl(raw?: string): string {
+  return (raw ?? "https://api.occum.net").replace(/\/+$/, "") + "/v1";
+}
+
+/**
+ * Resolve account config from OpenClaw config.
+ * Supports both channel-style config and legacy plugin config.
+ */
+function resolveAccount(cfg: any, accountId?: string | null): OccumAccount {
+  // Channel-style: channels.occum.accounts.<accountId>
+  const acctId = accountId ?? "default";
+  const channelAcct = cfg?.channels?.occum?.accounts?.[acctId];
+  if (channelAcct?.agentToken) {
+    return {
+      agentToken: channelAcct.agentToken,
+      apiUrl: resolveApiUrl(channelAcct.apiUrl),
+    };
+  }
+
+  // Plugin config: plugins.entries.occumclaw.config
+  const pluginCfg = cfg?.plugins?.entries?.occumclaw?.config;
+  if (pluginCfg?.agentToken) {
+    return {
+      agentToken: pluginCfg.agentToken,
+      apiUrl: resolveApiUrl(pluginCfg.apiUrl),
+    };
+  }
+
+  return { agentToken: "", apiUrl: resolveApiUrl() };
+}
+
+function listAccountIds(cfg: any): string[] {
+  // Channel-style accounts
+  const channelAccounts = cfg?.channels?.occum?.accounts;
+  if (channelAccounts && typeof channelAccounts === "object") {
+    return Object.keys(channelAccounts);
+  }
+  // Plugin config: single implicit account
+  const pluginCfg = cfg?.plugins?.entries?.occumclaw?.config;
+  if (pluginCfg?.agentToken) {
+    return ["default"];
+  }
+  return [];
+}
+
+// ─── Channel Plugin ─────────────────────────────────────────────────────────
+
+function createOccumChannelPlugin(logger: PluginLogger) {
+  return {
+    id: "occum" as const,
+
+    meta: {
+      id: "occum" as const,
+      label: "Occum.net",
+      selectionLabel: "Occum.net",
+      docsPath: "/docs/occum",
+      blurb: "Connect to occum.net for bidirectional agent communication",
+    },
+
+    capabilities: {
+      chatTypes: ["direct" as const],
+    },
+
+    config: {
+      listAccountIds: (cfg: any) => listAccountIds(cfg),
+      resolveAccount: (cfg: any, accountId?: string | null) => resolveAccount(cfg, accountId),
+      isConfigured: (account: OccumAccount) => !!account.agentToken,
+      isEnabled: (account: OccumAccount) => !!account.agentToken,
+    },
+
+    outbound: {
+      deliveryMode: "direct" as const,
+
+      async sendText(ctx: {
+        cfg: any;
+        to: string;
+        text: string;
+        accountId?: string | null;
+      }) {
+        const account = resolveAccount(ctx.cfg, ctx.accountId);
+        const config: ToolConfig = { agentToken: account.agentToken, apiUrl: account.apiUrl };
+
+        // `to` is the occum.net channel ID (UUIDv7 string)
+        const channelId = ctx.to;
+
+        const event = await apiRequest(config, `/channels/${channelId}/messages`, {
+          method: "POST",
+          body: JSON.stringify({ text: ctx.text }),
+        });
+
+        return {
+          channel: "occum",
+          messageId: String(event.id),
+          channelId,
+        };
+      },
+    },
+
+    gateway: {
+      async startAccount(ctx: ChannelGatewayContext) {
+        const { account, cfg, abortSignal, log } = ctx;
+
+        if (!account.agentToken) {
+          log?.warn?.("No agentToken configured — skipping occum.net connection");
+          return;
+        }
+
+        if (!ctx.channelRuntime) {
+          log?.warn?.("channelRuntime not available — cannot dispatch to agent");
+          log?.warn?.("Requires OpenClaw Plugin SDK 2026.2.19+");
+          return;
+        }
+
+        const channelRuntime = ctx.channelRuntime;
+        const config: ToolConfig = { agentToken: account.agentToken, apiUrl: account.apiUrl };
+
+        // Discover agent identity
+        let agentId: string | null = null;
+        let controlChannelId: string | null = null;
+        try {
+          const me = await apiRequest(config, "/agents/me");
+          agentId = me.id;
+          controlChannelId = me.controlChannelId;
+          log?.info?.(`Agent identity: ${me.name} (${agentId}), control channel #${controlChannelId}`);
+        } catch (err) {
+          log?.warn?.(`Failed to discover agent identity: ${err}`);
+        }
+
+        ctx.setStatus({
+          accountId: ctx.accountId,
+          enabled: true,
+          configured: true,
+          running: true,
+          connected: false,
+        });
+
+        // Track processed events to avoid re-dispatch
+        const processedEvents = new Set<string>();
+
+        const wsClient = new OccumWsClient({
+          apiUrl: account.apiUrl,
+          agentToken: account.agentToken,
+          log: (msg) => log?.info?.(`[ws] ${msg}`),
+
+          onConnected: (data: AuthOkData) => {
+            agentId = data.agentId;
+            log?.info?.(`Authenticated as agent ${data.agentId}`);
+            log?.info?.(`Subscribed to ${data.channels.length} channel(s)`);
+            ctx.setStatus({
+              accountId: ctx.accountId,
+              enabled: true,
+              configured: true,
+              running: true,
+              connected: true,
+            });
+          },
+
+          onEvent: (event: OccumEvent) => {
+            if (event.eventType !== "message") return;
+
+            // Don't respond to own messages
+            if (event.senderType === "agent" && event.senderAgentId === agentId) return;
+
+            // Dedup
+            if (processedEvents.has(event.id)) return;
+            processedEvents.add(event.id);
+            // Cap the dedup set
+            if (processedEvents.size > 1000) {
+              const first = processedEvents.values().next().value;
+              if (first) processedEvents.delete(first);
+            }
+
+            const text = (event.body as { text?: string }).text;
+            if (!text) return;
+
+            const senderLabel = event.senderType === "user"
+              ? `User #${event.senderUserId}`
+              : `Agent ${event.senderAgentId}`;
+
+            log?.info?.(`[occum] ${senderLabel} on #${event.channelId}: "${text.slice(0, 80)}${text.length > 80 ? "..." : ""}"`);
+
+            // ── Work session lifecycle + dispatch ─────────────────────
+            const replyChannelId = event.channelId;
+            const sessionId = crypto.randomUUID();
+
+            const msgCtx: MsgContext = {
+              Body: text,
+              BodyForAgent: text,
+              CommandBody: text,
+              From: event.senderType === "user"
+                ? `user:${event.senderUserId}`
+                : `agent:${event.senderAgentId}`,
+              To: replyChannelId,
+              SessionKey: `occum-${ctx.accountId}-${event.channelId}`,
+              AccountId: ctx.accountId,
+              Provider: "occum",
+              ChatType: "direct",
+              SenderId: event.senderType === "user"
+                ? String(event.senderUserId)
+                : String(event.senderAgentId),
+              SenderName: senderLabel,
+              Timestamp: new Date(event.createdAt).getTime(),
+              CommandAuthorized: true,
+              MessageSid: event.id,
+            };
+
+            // Start work session, dispatch, then complete
+            (async () => {
+              // Start work session
+              try {
+                await apiRequest(config, `/channels/${event.channelId}/work`, {
+                  method: "POST",
+                  body: JSON.stringify({ sessionId }),
+                });
+                log?.info?.(`[occum] Work session ${sessionId} started on #${event.channelId}`);
+              } catch (err) {
+                log?.warn?.(`[occum] Failed to start work session: ${err}`);
+                // Continue with dispatch even if work session creation fails
+              }
+
+              let replyText = "";
+              try {
+                await channelRuntime.reply
+                  .dispatchReplyWithBufferedBlockDispatcher({
+                    ctx: msgCtx,
+                    cfg,
+                    dispatcherOptions: {
+                      deliver: async (payload: ReplyPayload) => {
+                        if (!payload.text) return;
+                        replyText += payload.text;
+                        try {
+                          await apiRequest(config, `/channels/${event.channelId}/messages`, {
+                            method: "POST",
+                            body: JSON.stringify({ text: payload.text }),
+                          });
+                          log?.info?.(`[occum] Reply sent to #${event.channelId} (${payload.text.length} chars)`);
+                        } catch (err) {
+                          log?.error?.(`[occum] Failed to send reply: ${err}`);
+                        }
+                      },
+                      onError: (err) => {
+                        log?.error?.(`[occum] Dispatch error: ${err}`);
+                      },
+                    },
+                  });
+
+                // Complete work session on success
+                const summary = replyText
+                  ? replyText.slice(0, 120) + (replyText.length > 120 ? "…" : "")
+                  : "Completed";
+                try {
+                  await apiRequest(config, `/channels/${event.channelId}/work/${sessionId}/complete`, {
+                    method: "POST",
+                    body: JSON.stringify({ summary }),
+                  });
+                  log?.info?.(`[occum] Work session ${sessionId} completed`);
+                } catch (err) {
+                  log?.warn?.(`[occum] Failed to complete work session: ${err}`);
+                }
+              } catch (err: any) {
+                log?.error?.(`[occum] dispatchReply failed: ${err}`);
+                // Complete work session with error summary
+                try {
+                  await apiRequest(config, `/channels/${event.channelId}/work/${sessionId}/complete`, {
+                    method: "POST",
+                    body: JSON.stringify({ summary: `Error: ${String(err).slice(0, 100)}` }),
+                  });
+                } catch {
+                  // Best effort
+                }
+              }
+            })();
+          },
+
+          onDisconnected: () => {
+            log?.info?.("Disconnected from occum.net");
+            ctx.setStatus({
+              accountId: ctx.accountId,
+              enabled: true,
+              configured: true,
+              running: true,
+              connected: false,
+            });
+          },
+        });
+
+        wsClient.connect();
+
+        // Return a promise that stays pending until gateway shutdown.
+        // This keeps OpenClaw from treating the account as "exited" and
+        // auto-restarting it.
+        return new Promise<void>((resolve) => {
+          abortSignal.addEventListener("abort", () => {
+            wsClient.disconnect();
+            log?.info?.("Gateway shutdown — disconnected from occum.net");
+            resolve();
+          });
+        });
+      },
+
+      async stopAccount(ctx: ChannelGatewayContext) {
+        ctx.log?.info?.("Stopping occum.net account");
+        // The abort signal from startAccount handles cleanup
+      },
+    },
+  };
+}
+
+// ─── Plugin Entry ───────────────────────────────────────────────────────────
+
+export default {
+  id: "occumclaw",
+  name: "Occum.net Connector",
+
+  register(api: OpenClawPluginApi) {
+    const logger = api.logger;
+
+    // ── Register as a channel (Telegram-style) ─────────────────────────
+    const channelPlugin = createOccumChannelPlugin(logger);
+    api.registerChannel({ plugin: channelPlugin });
+
+    // ── Register agent tools ───────────────────────────────────────────
+    // These let the agent proactively interact with occum.net channels
+    // beyond just replying to inbound messages.
+
+    api.registerTool(
+      (ctx) => {
+        const account = resolveAccount(ctx.config ?? {});
+        return createSendMessageTool({ agentToken: account.agentToken, apiUrl: account.apiUrl });
+      },
+      { name: "occumclaw", optional: true }
+    );
+
+    api.registerTool(
+      (ctx) => {
+        const account = resolveAccount(ctx.config ?? {});
+        return createListChannelsTool({ agentToken: account.agentToken, apiUrl: account.apiUrl });
+      },
+      { name: "occumclaw", optional: true }
+    );
+
+    api.registerTool(
+      (ctx) => {
+        const account = resolveAccount(ctx.config ?? {});
+        return createGetEventsTool({ agentToken: account.agentToken, apiUrl: account.apiUrl });
+      },
+      { name: "occumclaw", optional: true }
+    );
+
+    logger.info("Occum.net channel plugin registered");
+  },
+};

package/openclaw.plugin.json

@@ -0,0 +1,20 @@
+{
+  "id": "occumclaw",
+  "name": "Occum.net Connector",
+  "description": "Registers occum.net as a channel in OpenClaw for bidirectional agent communication via WebSocket",
+  "version": "0.2.0",
+  "channel": "occum",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "agentToken": { "type": "string" },
+      "apiUrl": { "type": "string", "default": "https://api.occum.net" }
+    },
+    "required": ["agentToken"]
+  },
+  "uiHints": {
+    "agentToken": { "label": "Agent Token", "sensitive": true },
+    "apiUrl": { "label": "API URL", "placeholder": "https://api.occum.net" }
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@occum-net/occumclaw",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "OpenClaw plugin that connects to occum.net for bidirectional agent communication via WebSocket",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {},
+  "files": [
+    "index.ts",
+    "api.ts",
+    "ws-client.ts",
+    "tools.ts",
+    "openclaw.plugin.json",
+    "skills"
+  ],
+  "keywords": [
+    "occum",
+    "openclaw",
+    "agent",
+    "websocket",
+    "plugin"
+  ],
+  "license": "MIT"
+}

package/tools.ts

@@ -0,0 +1,101 @@
+/**
+ * OpenClaw agent tools for interacting with occum.net.
+ *
+ * These tools are registered with the OpenClaw plugin API so the agent
+ * can send messages, list channels, and fetch events on occum.net.
+ */
+
+import { apiRequest, type ToolConfig } from "./api";
+
+/** JSON Schema for tool inputs */
+const StringProp = (desc: string) => ({ type: "string" as const, description: desc });
+const NumberProp = (desc: string) => ({ type: "number" as const, description: desc });
+
+// ─── Tool Definitions ───────────────────────────────────────────────────────
+
+export function createSendMessageTool(config: ToolConfig) {
+  return {
+    name: "occum_send_message",
+    description:
+      "Send a message to a channel on occum.net. Use this when the user wants to " +
+      "communicate through the occum.net platform. If no channelId is specified, " +
+      "the message is sent to the agent's control channel.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        text: StringProp("The message text to send"),
+        channelId: StringProp("Channel ID to send to (defaults to control channel)"),
+      },
+      required: ["text"],
+    },
+    async execute(input: { text: string; channelId?: string }): Promise<any> {
+      // Discover control channel if no channelId given
+      let targetChannel = input.channelId;
+      if (!targetChannel) {
+        const me = await apiRequest(config, "/agents/me");
+        targetChannel = me.controlChannelId;
+        if (!targetChannel) {
+          return { error: "No control channel found for this agent" };
+        }
+      }
+
+      const event = await apiRequest(config, `/channels/${targetChannel}/messages`, {
+        method: "POST",
+        body: JSON.stringify({ text: input.text }),
+      });
+      return { sent: true, eventId: event.id, channelId: targetChannel };
+    },
+  };
+}
+
+export function createListChannelsTool(config: ToolConfig) {
+  return {
+    name: "occum_list_channels",
+    description: "List all channels the agent is a member of on occum.net.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {},
+    },
+    async execute(): Promise<any> {
+      const channels = await apiRequest(config, "/channels");
+      return {
+        channels: channels.map((ch: any) => ({
+          id: ch.id,
+          name: ch.name,
+          type: ch.type,
+          description: ch.description,
+        })),
+      };
+    },
+  };
+}
+
+export function createGetEventsTool(config: ToolConfig) {
+  return {
+    name: "occum_get_events",
+    description:
+      "Fetch recent events (messages, work sessions, etc.) from a channel on occum.net. " +
+      "Supports cursor-based pagination.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        channelId: StringProp("Channel ID to fetch events from"),
+        limit: NumberProp("Max events to return (default 20, max 100)"),
+        after: StringProp("Cursor: return events after this event ID"),
+      },
+      required: ["channelId"],
+    },
+    async execute(input: { channelId: string; limit?: number; after?: string }): Promise<any> {
+      const params = new URLSearchParams();
+      if (input.limit) params.set("limit", String(input.limit));
+      if (input.after) params.set("after", input.after);
+      const qs = params.toString();
+
+      const events = await apiRequest(
+        config,
+        `/channels/${input.channelId}/events${qs ? `?${qs}` : ""}`
+      );
+      return { events, count: events.length };
+    },
+  };
+}

package/ws-client.ts

@@ -0,0 +1,195 @@
+/**
+ * WebSocket client for connecting to the occum.net real-time API.
+ *
+ * Handles authentication, reconnection with exponential backoff,
+ * and ping/pong keepalive. Designed to run inside an OpenClaw plugin.
+ */
+
+interface OccumWsClientOptions {
+  apiUrl: string;
+  agentToken: string;
+  onEvent: (event: OccumEvent) => void;
+  onConnected: (data: AuthOkData) => void;
+  onDisconnected: () => void;
+  log: (msg: string) => void;
+}
+
+export interface AuthOkData {
+  userId: string;
+  agentId: string | null;
+  channels: string[];
+}
+
+export interface OccumEvent {
+  type: "event";
+  id: string;
+  channelId: string;
+  eventType: "message" | "work" | "member_joined" | "member_left";
+  senderType: "user" | "agent";
+  senderUserId: string | null;
+  senderAgentId: string | null;
+  body: Record<string, unknown>;
+  createdAt: string;
+}
+
+type WsState = "disconnected" | "connecting" | "authenticating" | "connected";
+
+export class OccumWsClient {
+  private ws: WebSocket | null = null;
+  private state: WsState = "disconnected";
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private pongTimeout: ReturnType<typeof setTimeout> | null = null;
+  private destroyed = false;
+
+  private readonly wsUrl: string;
+  private readonly opts: OccumWsClientOptions;
+
+  constructor(opts: OccumWsClientOptions) {
+    this.opts = opts;
+    // Derive WS URL from API URL: https://api.occum.net/v1 → wss://api.occum.net/v1/ws
+    const base = opts.apiUrl.replace(/\/+$/, "");
+    this.wsUrl = base.replace(/^http/, "ws") + "/ws";
+  }
+
+  connect(): void {
+    if (this.destroyed) return;
+    this.cleanup();
+
+    this.state = "connecting";
+    this.opts.log(`Connecting to ${this.wsUrl}`);
+
+    try {
+      this.ws = new WebSocket(this.wsUrl);
+    } catch (err) {
+      this.opts.log(`WebSocket constructor error: ${err}`);
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws.onopen = () => {
+      this.state = "authenticating";
+      this.opts.log("Connected, authenticating...");
+      this.ws!.send(JSON.stringify({ type: "auth", token: this.opts.agentToken }));
+    };
+
+    this.ws.onmessage = (evt) => {
+      let msg: any;
+      try {
+        msg = JSON.parse(typeof evt.data === "string" ? evt.data : "");
+      } catch {
+        return;
+      }
+
+      switch (msg.type) {
+        case "auth_ok":
+          this.state = "connected";
+          this.reconnectAttempt = 0;
+          this.startPing();
+          this.opts.onConnected({
+            userId: msg.userId,
+            agentId: msg.agentId,
+            channels: msg.channels,
+          });
+          break;
+
+        case "auth_error":
+          this.opts.log(`Auth error: ${msg.message}`);
+          // Don't reconnect on auth errors — token is bad
+          this.cleanup();
+          break;
+
+        case "pong":
+          if (this.pongTimeout) {
+            clearTimeout(this.pongTimeout);
+            this.pongTimeout = null;
+          }
+          break;
+
+        case "event":
+          this.opts.onEvent(msg as OccumEvent);
+          break;
+
+        case "subscribed":
+          this.opts.log(`Subscribed to channel #${msg.channelId}`);
+          break;
+
+        case "error":
+          this.opts.log(`Server error: ${msg.message}`);
+          break;
+      }
+    };
+
+    this.ws.onclose = () => {
+      this.opts.log("Connection closed");
+      this.state = "disconnected";
+      this.opts.onDisconnected();
+      this.scheduleReconnect();
+    };
+
+    this.ws.onerror = () => {
+      // onclose will fire after this
+    };
+  }
+
+  disconnect(): void {
+    this.destroyed = true;
+    this.cleanup();
+  }
+
+  subscribe(channelId: string): void {
+    if (this.state === "connected" && this.ws) {
+      this.ws.send(JSON.stringify({ type: "subscribe", channelId }));
+    }
+  }
+
+  private startPing(): void {
+    this.stopPing();
+    this.pingTimer = setInterval(() => {
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(JSON.stringify({ type: "ping" }));
+        this.pongTimeout = setTimeout(() => {
+          this.opts.log("Pong timeout — reconnecting");
+          this.ws?.close();
+        }, 10_000);
+      }
+    }, 30_000);
+  }
+
+  private stopPing(): void {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    if (this.pongTimeout) {
+      clearTimeout(this.pongTimeout);
+      this.pongTimeout = null;
+    }
+  }
+
+  private cleanup(): void {
+    this.stopPing();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.onopen = null;
+      this.ws.onmessage = null;
+      this.ws.onclose = null;
+      this.ws.onerror = null;
+      try { this.ws.close(); } catch {}
+      this.ws = null;
+    }
+    this.state = "disconnected";
+  }
+
+  private scheduleReconnect(): void {
+    if (this.destroyed) return;
+    const delay = Math.min(1000 * 2 ** this.reconnectAttempt, 60_000);
+    this.reconnectAttempt++;
+    this.opts.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempt})`);
+    this.reconnectTimer = setTimeout(() => this.connect(), delay);
+  }
+}