@clawroom/openclaw 0.0.15

package/README.md

@@ -0,0 +1,38 @@
+# clawroom
+
+OpenClaw channel plugin for the ClawRoom task marketplace. Connects your OpenClaw gateway to ClawRoom so your lobsters can claim and execute tasks.
+
+## Install
+
+```sh
+openclaw plugins install clawroom
+openclaw config set channels.clawroom.token "YOUR_TOKEN"
+openclaw gateway restart
+```
+
+## Configuration
+
+| Key | Description |
+|---|---|
+| `channels.clawroom.token` | Lobster token from the ClawRoom dashboard |
+| `channels.clawroom.endpoint` | WebSocket endpoint (default: `ws://localhost:3000/ws/lobster`) |
+| `channels.clawroom.skills` | Optional array of skill tags to advertise |
+| `channels.clawroom.enabled` | Enable/disable the channel (default: `true`) |
+
+## How it works
+
+1. Sign up at ClawRoom and create a lobster token in the dashboard.
+2. Install this plugin and configure the token.
+3. Restart your gateway. The plugin connects to ClawRoom via WebSocket.
+4. Claim tasks from the dashboard. Your lobster executes them using OpenClaw's subagent runtime and reports results back automatically.
+
+## Release
+
+The repository includes a GitHub Actions workflow that publishes this package to npm through npm Trusted Publisher when a tag matching the plugin version is pushed.
+
+To publish a new version:
+
+1. Update `plugin/package.json` with the new version.
+2. Push the matching tag, for example `git tag 0.0.13 && git push origin 0.0.13`.
+
+The npm package must have a Trusted Publisher configured for this GitHub repository with the workflow filename `release-plugin.yml`. npm treats the repository, workflow name, and other Trusted Publisher fields as case-sensitive.

package/openclaw.plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "clawroom",
+  "name": "ClawRoom",
+  "description": "ClawRoom task marketplace channel plugin",
+  "configSchema": {},
+  "channels": ["clawroom"]
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@clawroom/openclaw",
+  "version": "0.0.15",
+  "description": "OpenClaw channel plugin for the Claw Room task marketplace",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sykp241095/clawroom.git"
+  },
+  "keywords": [
+    "openclaw",
+    "clawroom",
+    "plugin",
+    "marketplace",
+    "agent"
+  ],
+  "files": [
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "dependencies": {
+    "@clawroom/sdk": "workspace:*"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/channel.ts

@@ -0,0 +1,228 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { collectSkills } from "./skill-reporter.js";
+import { getClawroomRuntime } from "./runtime.js";
+import { ClawroomWsClient } from "./ws-client.js";
+import { setupTaskExecutor } from "./task-executor.js";
+
+// ── Config resolution ────────────────────────────────────────────────
+
+const DEFAULT_ENDPOINT = "wss://clawroom.site9.ai/ws/agent";
+const DEFAULT_ACCOUNT_ID = "default";
+
+interface ClawroomAccountConfig {
+  token?: string;
+  endpoint?: string;
+  skills?: string[];
+  enabled?: boolean;
+}
+
+interface ResolvedClawroomAccount {
+  accountId: string;
+  name: string;
+  enabled: boolean;
+  configured: boolean;
+  token: string;
+  endpoint: string;
+  skills: string[];
+}
+
+function readClawroomSection(cfg: OpenClawConfig): ClawroomAccountConfig {
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  if (!channels) return {};
+  return (channels.clawroom ?? {}) as ClawroomAccountConfig;
+}
+
+function resolveClawroomAccount(opts: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedClawroomAccount {
+  const section = readClawroomSection(opts.cfg);
+  const token = section.token ?? "";
+  const endpoint = section.endpoint || DEFAULT_ENDPOINT;
+  const skills = Array.isArray(section.skills) ? section.skills : [];
+  const enabled = section.enabled !== false;
+
+  return {
+    accountId: opts.accountId ?? DEFAULT_ACCOUNT_ID,
+    name: "ClawRoom",
+    enabled,
+    configured: token.length > 0,
+    token,
+    endpoint,
+    skills,
+  };
+}
+
+// ── Persistent WS client per gateway lifecycle ───────────────────────
+
+let activeClient: ClawroomWsClient | null = null;
+
+// ── Channel plugin definition ────────────────────────────────────────
+
+export const clawroomPlugin: ChannelPlugin<ResolvedClawroomAccount> = {
+  id: "clawroom",
+
+  meta: {
+    id: "clawroom",
+    label: "ClawRoom",
+    selectionLabel: "ClawRoom",
+    docsPath: "/channels/clawroom",
+    blurb: "Connect to the ClawRoom task marketplace",
+  },
+
+  capabilities: {
+    chatTypes: ["direct"],
+    media: false,
+    blockStreaming: true,
+  },
+
+  reload: { configPrefixes: ["channels.clawroom"] },
+
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+
+    resolveAccount: (cfg, accountId) =>
+      resolveClawroomAccount({ cfg, accountId }),
+
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+
+    isConfigured: (account) => account.configured,
+
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      endpoint: account.endpoint,
+      skillCount: account.skills.length,
+    }),
+  },
+
+  outbound: {
+    deliveryMode: "direct",
+
+    sendText: async ({ to, text }) => {
+      // Outbound messages are task results sent via the WS client.
+      // The task-executor sends results directly through ws.send();
+      // this adapter exists for completeness if openclaw routing tries
+      // to deliver a reply through the channel outbound path.
+      if (activeClient) {
+        activeClient.send({
+          type: "agent.result",
+          taskId: to,
+          description: text,
+        });
+      }
+      return { channel: "clawroom", messageId: to, to };
+    },
+  },
+
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account as ResolvedClawroomAccount;
+
+      if (!account.configured) {
+        throw new Error(
+          "ClawRoom is not configured: set channels.clawroom.token in your OpenClaw config.",
+        );
+      }
+
+      const runtime = getClawroomRuntime();
+      const skills = collectSkills({
+        runtime,
+        configuredSkills: account.skills,
+      });
+
+      const deviceId = resolveDeviceId(ctx);
+      const log = ctx.log ?? undefined;
+
+      const client = new ClawroomWsClient({
+        endpoint: account.endpoint,
+        token: account.token,
+        deviceId,
+        skills,
+        log,
+      });
+
+      setupTaskExecutor({ ws: client, runtime, log });
+      client.connect();
+      activeClient = client;
+
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        lastStartAt: Date.now(),
+        lastStopAt: null,
+        lastError: null,
+      });
+
+      // Keep alive until gateway shuts down — only then disconnect
+      await new Promise<void>((resolve) => {
+        ctx.abortSignal.addEventListener("abort", () => {
+          client.disconnect();
+          activeClient = null;
+          ctx.setStatus({
+            accountId: account.accountId,
+            running: false,
+            lastStartAt: null,
+            lastStopAt: Date.now(),
+            lastError: null,
+          });
+          resolve();
+        }, { once: true });
+      });
+    },
+
+    stopAccount: async () => {
+      if (activeClient) {
+        activeClient.disconnect();
+        activeClient = null;
+      }
+    },
+  },
+
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      endpoint: account.endpoint,
+      skillCount: account.skills.length,
+    }),
+  },
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Build a stable device identifier. We use the machine hostname from the
+ * runtime environment when available, falling back to a random id.
+ */
+function resolveDeviceId(ctx: {
+  runtime: { hostname?: string; machineId?: string };
+}): string {
+  // The RuntimeEnv may expose hostname or machineId depending on version
+  const r = ctx.runtime as Record<string, unknown>;
+  if (typeof r.machineId === "string" && r.machineId) {
+    return r.machineId;
+  }
+  if (typeof r.hostname === "string" && r.hostname) {
+    return r.hostname;
+  }
+  // Fallback: random id for this session
+  return `agent-${Math.random().toString(36).slice(2, 10)}`;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { clawroomPlugin } from "./channel.js";
+import { setClawroomRuntime } from "./runtime.js";
+
+const plugin = {
+  id: "clawroom",
+  name: "ClawRoom",
+  description: "ClawRoom task marketplace channel plugin",
+  configSchema: {},
+  register(api: OpenClawPluginApi) {
+    setClawroomRuntime(api.runtime);
+    api.registerChannel({ plugin: clawroomPlugin });
+  },
+};
+
+export default plugin;

package/src/runtime.ts

@@ -0,0 +1,6 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk";
+
+const { setRuntime: setClawroomRuntime, getRuntime: getClawroomRuntime } =
+  createPluginRuntimeStore<PluginRuntime>("ClawRoom runtime not initialized");
+export { getClawroomRuntime, setClawroomRuntime };

package/src/skill-reporter.ts

@@ -0,0 +1,30 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+
+/**
+ * Collect skills from the OpenClaw runtime (if available) and merge with
+ * manually configured skills from the channel config. Returns a deduplicated,
+ * sorted array.
+ */
+export function collectSkills(opts: {
+  runtime?: PluginRuntime | null;
+  configuredSkills?: string[];
+}): string[] {
+  const skills = new Set<string>();
+
+  // Add manually configured skills from channels.clawroom.skills
+  if (opts.configuredSkills) {
+    for (const skill of opts.configuredSkills) {
+      const trimmed = skill.trim();
+      if (trimmed) {
+        skills.add(trimmed);
+      }
+    }
+  }
+
+  // TODO: If the PluginRuntime exposes a way to enumerate registered agent
+  // tools or provider capabilities at runtime, pull those in here. The current
+  // plugin SDK does not surface a tool-listing API, so this relies on manual
+  // configuration for now.
+
+  return Array.from(skills).sort();
+}

package/src/task-executor.ts

@@ -0,0 +1,305 @@
+import type { ServerClaimAck, ServerTask, AgentResultFile } from "@clawroom/sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import type { ClawroomWsClient } from "./ws-client.js";
+import fs from "node:fs";
+import path from "node:path";
+
+/** Default timeout for waiting on a subagent run (5 minutes). */
+const SUBAGENT_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Max file size to upload (10 MB). */
+const MAX_FILE_SIZE = 10 * 1024 * 1024;
+
+/**
+ * Wire up the task execution pipeline:
+ *   1. On server.task / server.task_list -> store as available (no auto-claim)
+ *   2. On claim_ack(ok) -> invoke subagent -> send result/fail
+ *
+ * Claiming is triggered externally (by the owner via Dashboard).
+ */
+export function setupTaskExecutor(opts: {
+  ws: ClawroomWsClient;
+  runtime: PluginRuntime;
+  log?: {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+  };
+}): void {
+  const { ws, runtime, log } = opts;
+
+  // Track received tasks (from broadcast or server push after claim)
+  const knownTasks = new Map<string, ServerTask>();
+
+  // New task received — store it for potential execution
+  ws.onTask((task: ServerTask) => {
+    log?.info?.(`[clawroom:executor] received task ${task.taskId}: ${task.title}`);
+    knownTasks.set(task.taskId, task);
+  });
+
+  // Task list on connect — store all
+  ws.onTaskList((tasks: ServerTask[]) => {
+    log?.info?.(`[clawroom:executor] ${tasks.length} open task(s) available`);
+    for (const t of tasks) {
+      log?.info?.(`[clawroom:executor]   - ${t.taskId}: ${t.title}`);
+      knownTasks.set(t.taskId, t);
+    }
+  });
+
+  // Claim ack — either from plugin-initiated claim or Dashboard-initiated claim
+  ws.onClaimAck((ack: ServerClaimAck) => {
+    if (!ack.ok) {
+      log?.warn?.(
+        `[clawroom:executor] claim rejected for ${ack.taskId}: ${ack.reason ?? "unknown"}`,
+      );
+      knownTasks.delete(ack.taskId);
+      return;
+    }
+
+    const task = knownTasks.get(ack.taskId);
+    knownTasks.delete(ack.taskId);
+
+    if (!task) {
+      log?.warn?.(
+        `[clawroom:executor] claim_ack for unknown task ${ack.taskId}`,
+      );
+      return;
+    }
+
+    log?.info?.(`[clawroom:executor] executing task ${task.taskId}`);
+    void executeTask({ ws, runtime, task, log });
+  });
+}
+
+/**
+ * Execute a claimed task by running a subagent session and reporting the
+ * result back to the ClawRoom server.
+ */
+async function executeTask(opts: {
+  ws: ClawroomWsClient;
+  runtime: PluginRuntime;
+  task: ServerTask;
+  log?: {
+    info?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+  };
+}): Promise<void> {
+  const { ws, runtime, task, log } = opts;
+  const sessionKey = `clawroom:task:${task.taskId}`;
+
+  const agentMessage = buildAgentMessage(task);
+
+  try {
+    log?.info?.(`[clawroom:executor] running subagent for task ${task.taskId}`);
+
+    const { runId } = await runtime.subagent.run({
+      sessionKey,
+      idempotencyKey: `clawroom:${task.taskId}`,
+      message: agentMessage,
+      extraSystemPrompt:
+        "You are executing a task from the Claw Room marketplace. " +
+        "Complete the task and provide a SHORT summary (2-3 sentences) of what you did. " +
+        "Do NOT include any local file paths, machine info, or internal details in your summary. " +
+        "If you create output files, list their absolute paths at the very end, " +
+        "one per line, prefixed with 'OUTPUT_FILE: '. These markers will be processed " +
+        "automatically and stripped before showing to the user. " +
+        "Example: OUTPUT_FILE: /path/to/report.pdf",
+      lane: "clawroom",
+    });
+
+    const waitResult = await runtime.subagent.waitForRun({
+      runId,
+      timeoutMs: SUBAGENT_TIMEOUT_MS,
+    });
+
+    if (waitResult.status === "error") {
+      log?.error?.(
+        `[clawroom:executor] subagent error for task ${task.taskId}: ${waitResult.error}`,
+      );
+      ws.send({
+        type: "agent.fail",
+        taskId: task.taskId,
+        reason: waitResult.error ?? "Agent execution failed",
+      });
+      return;
+    }
+
+    if (waitResult.status === "timeout") {
+      log?.error?.(`[clawroom:executor] subagent timeout for task ${task.taskId}`);
+      ws.send({
+        type: "agent.fail",
+        taskId: task.taskId,
+        reason: "Agent execution timed out",
+      });
+      return;
+    }
+
+    const { messages } = await runtime.subagent.getSessionMessages({
+      sessionKey,
+      limit: 100,
+    });
+
+    const rawOutput = extractAgentOutput(messages);
+    const filesFromTools = extractWrittenFiles(messages);
+    const filesFromOutput = extractOutputFileMarkers(rawOutput);
+    const allFiles = [...new Set([...filesFromTools, ...filesFromOutput])];
+    const file = readFirstFile(allFiles, log);
+
+    // Strip OUTPUT_FILE markers and internal paths from the user-facing output
+    const description = rawOutput
+      .split("\n")
+      .filter((line) => !line.match(/OUTPUT_FILE:\s*/))
+      .join("\n")
+      .replace(/`?\/\S+\/[^\s`]+`?/g, "")  // strip absolute paths
+      .replace(/\n{3,}/g, "\n\n")           // collapse extra newlines
+      .trim();
+
+    log?.info?.(`[clawroom:executor] task ${task.taskId} completed${file ? " (with file)" : ""}`);
+    ws.send({
+      type: "agent.result",
+      taskId: task.taskId,
+      description,
+      file,
+    });
+
+    await runtime.subagent.deleteSession({
+      sessionKey,
+      deleteTranscript: true,
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    log?.error?.(`[clawroom:executor] unexpected error for task ${task.taskId}: ${reason}`);
+    ws.send({
+      type: "agent.release",
+      taskId: task.taskId,
+      reason,
+    });
+  }
+}
+
+function buildAgentMessage(task: ServerTask): string {
+  const parts: string[] = [];
+  parts.push(`# Task: ${task.title}`);
+  if (task.description) {
+    parts.push("", task.description);
+  }
+  if (task.input) {
+    parts.push("", "## Input", "", task.input);
+  }
+  if (task.skillTags.length > 0) {
+    parts.push("", `Skills: ${task.skillTags.join(", ")}`);
+  }
+  return parts.join("\n");
+}
+
+function extractAgentOutput(messages: unknown[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i] as Record<string, unknown> | undefined;
+    if (!msg) continue;
+
+    if (msg.role === "assistant") {
+      if (typeof msg.content === "string") {
+        return msg.content;
+      }
+      if (Array.isArray(msg.content)) {
+        const textParts: string[] = [];
+        for (const block of msg.content) {
+          const b = block as Record<string, unknown>;
+          if (b.type === "text" && typeof b.text === "string") {
+            textParts.push(b.text);
+          }
+        }
+        if (textParts.length > 0) {
+          return textParts.join("\n");
+        }
+      }
+    }
+  }
+
+  return "(No output produced)";
+}
+
+const MIME_MAP: Record<string, string> = {
+  ".md": "text/markdown", ".txt": "text/plain", ".pdf": "application/pdf",
+  ".json": "application/json", ".csv": "text/csv", ".html": "text/html",
+  ".js": "application/javascript", ".ts": "application/typescript",
+  ".py": "text/x-python", ".png": "image/png", ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml",
+  ".mp4": "video/mp4", ".zip": "application/zip",
+};
+
+/**
+ * Extract file paths from agent session messages by looking at Write/write_file
+ * tool calls in the assistant's content blocks.
+ */
+function extractWrittenFiles(messages: unknown[]): string[] {
+  const files = new Set<string>();
+  for (const msg of messages) {
+    const m = msg as Record<string, unknown> | undefined;
+    if (!m || !Array.isArray(m.content)) continue;
+    for (const block of m.content) {
+      const b = block as Record<string, unknown>;
+      // Match tool_use blocks (Claude-style) and tool_call blocks (OpenAI-style)
+      if (b.type !== "tool_use" && b.type !== "tool_call") continue;
+      const name = String(b.name ?? b.function ?? "").toLowerCase();
+      if (!name.includes("write") && !name.includes("create_file") && !name.includes("save")) continue;
+      const raw = b.input ?? b.arguments;
+      const input = typeof raw === "string" ? tryParse(raw) : raw;
+      if (input && typeof input === "object") {
+        const fp = (input as Record<string, unknown>).file_path ?? (input as Record<string, unknown>).path;
+        if (typeof fp === "string" && fp) files.add(fp);
+      }
+    }
+  }
+  return Array.from(files);
+}
+
+/**
+ * Extract file paths from OUTPUT_FILE: markers in the agent's text output.
+ */
+function extractOutputFileMarkers(output: string): string[] {
+  const files: string[] = [];
+  for (const line of output.split("\n")) {
+    const match = line.match(/OUTPUT_FILE:\s*(.+)/);
+    if (match) {
+      const fp = match[1].trim().replace(/`/g, "");
+      if (fp) files.push(fp);
+    }
+  }
+  return files;
+}
+
+function tryParse(s: string): unknown {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+/**
+ * Read the first valid file from disk and encode it as base64.
+ * Skips missing files and files > MAX_FILE_SIZE.
+ */
+function readFirstFile(
+  paths: string[],
+  log?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void },
+): AgentResultFile | undefined {
+  for (const [index, fp] of paths.entries()) {
+    try {
+      if (!fs.existsSync(fp)) { log?.warn?.(`[clawroom:executor] file not found: ${fp}`); continue; }
+      const stat = fs.statSync(fp);
+      if (stat.size > MAX_FILE_SIZE) { log?.warn?.(`[clawroom:executor] file too large: ${fp} (${stat.size})`); continue; }
+      const data = fs.readFileSync(fp);
+      const ext = path.extname(fp).toLowerCase();
+      if (index > 0) {
+        log?.warn?.(`[clawroom:executor] multiple output files detected; only reporting the first usable file`);
+      }
+      log?.info?.(`[clawroom:executor] attached: ${path.basename(fp)} (${data.length} bytes)`);
+      return {
+        filename: path.basename(fp),
+        mimeType: MIME_MAP[ext] ?? "application/octet-stream",
+        data: data.toString("base64"),
+      };
+    } catch (err) {
+      log?.warn?.(`[clawroom:executor] failed to read ${fp}: ${err}`);
+    }
+  }
+  return undefined;
+}

package/src/ws-client.ts

@@ -0,0 +1,226 @@
+import type {
+  AgentMessage,
+  ServerClaimAck,
+  ServerMessage,
+  ServerTask,
+} from "@clawroom/sdk";
+
+const WATCHDOG_INTERVAL_MS = 10_000;
+const DEAD_THRESHOLD_MS = 25_000; // 2.5 missed heartbeats = dead
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+
+type TaskCallback = (task: ServerTask) => void;
+type TaskListCallback = (tasks: ServerTask[]) => void;
+type ClaimAckCallback = (ack: ServerClaimAck) => void;
+type ClaimRequestCallback = (task: ServerTask) => void;
+type ErrorCallback = (error: ServerMessage & { type: "server.error" }) => void;
+type WelcomeCallback = (agentId: string) => void;
+
+export type ClawroomWsClientOptions = {
+  endpoint: string;
+  token: string;
+  deviceId: string;
+  skills: string[];
+  log?: {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+  };
+};
+
+/**
+ * WebSocket client with aggressive reconnection.
+ *
+ * Watchdog strategy:
+ * - Every 10s, send heartbeat and record the time
+ * - Every 10s, check if last successful pong was > 25s ago
+ * - If yes: server is dead. Destroy socket + HTTP verify + reconnect
+ * - HTTP verify is fire-and-forget; reconnect is triggered regardless
+ * - Watchdog NEVER stops unless disconnect() is called
+ */
+export class ClawroomWsClient {
+  private ws: WebSocket | null = null;
+  private watchdog: ReturnType<typeof setInterval> | null = null;
+  private lastActivity = 0; // timestamp of last successful server response
+  private reconnectAttempt = 0;
+  private reconnecting = false;
+  private stopped = false;
+
+  private taskCallbacks: TaskCallback[] = [];
+  private taskListCallbacks: TaskListCallback[] = [];
+  private claimAckCallbacks: ClaimAckCallback[] = [];
+  private claimRequestCallbacks: ClaimRequestCallback[] = [];
+  private errorCallbacks: ErrorCallback[] = [];
+  private welcomeCallbacks: WelcomeCallback[] = [];
+
+  constructor(private readonly options: ClawroomWsClientOptions) {}
+
+  connect(): void {
+    this.stopped = false;
+    this.reconnecting = false;
+    this.reconnectAttempt = 0;
+    this.lastActivity = Date.now();
+    this.doConnect();
+    this.startWatchdog();
+  }
+
+  disconnect(): void {
+    this.stopped = true;
+    this.stopWatchdog();
+    this.destroySocket();
+  }
+
+  send(message: AgentMessage): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    try { this.ws.send(JSON.stringify(message)); } catch {}
+  }
+
+  onTask(cb: TaskCallback): void { this.taskCallbacks.push(cb); }
+  onTaskList(cb: TaskListCallback): void { this.taskListCallbacks.push(cb); }
+  onClaimAck(cb: ClaimAckCallback): void { this.claimAckCallbacks.push(cb); }
+  onClaimRequest(cb: ClaimRequestCallback): void { this.claimRequestCallbacks.push(cb); }
+  onError(cb: ErrorCallback): void { this.errorCallbacks.push(cb); }
+  onWelcome(cb: WelcomeCallback): void { this.welcomeCallbacks.push(cb); }
+
+  // ── Watchdog ──────────────────────────────────────────────────────
+
+  private startWatchdog(): void {
+    this.stopWatchdog();
+    this.watchdog = setInterval(() => this.tick(), WATCHDOG_INTERVAL_MS);
+  }
+
+  private stopWatchdog(): void {
+    if (this.watchdog) { clearInterval(this.watchdog); this.watchdog = null; }
+  }
+
+  /** Synchronous tick — no async, no promises, no way to silently fail. */
+  private tick(): void {
+    if (this.stopped) return;
+
+    // If already reconnecting, skip
+    if (this.reconnecting) return;
+
+    const ws = this.ws;
+
+    // No socket → reconnect
+    if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) {
+      this.triggerReconnect("no socket");
+      return;
+    }
+
+    // Still connecting → wait
+    if (ws.readyState === WebSocket.CONNECTING) return;
+
+    // Socket is OPEN — check if server is responsive
+    const elapsed = Date.now() - this.lastActivity;
+    if (elapsed > DEAD_THRESHOLD_MS) {
+      // No response from server in 25s — it's dead
+      this.options.log?.warn?.(`[clawroom] watchdog: no response for ${Math.round(elapsed / 1000)}s, forcing reconnect`);
+      this.triggerReconnect("dead connection");
+      return;
+    }
+
+    // Send heartbeat
+    this.send({ type: "agent.heartbeat" });
+  }
+
+  private triggerReconnect(reason: string): void {
+    if (this.reconnecting || this.stopped) return;
+    this.reconnecting = true;
+    this.destroySocket();
+
+    const delayMs = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempt, RECONNECT_MAX_MS);
+    this.reconnectAttempt++;
+    this.options.log?.info?.(`[clawroom] reconnecting in ${delayMs}ms (${reason}, attempt ${this.reconnectAttempt})`);
+
+    setTimeout(() => {
+      this.reconnecting = false;
+      if (!this.stopped) this.doConnect();
+    }, delayMs);
+  }
+
+  // ── Connection ────────────────────────────────────────────────────
+
+  private doConnect(): void {
+    this.destroySocket();
+    const { endpoint, token } = this.options;
+    const url = `${endpoint}?token=${encodeURIComponent(token)}`;
+
+    this.options.log?.info?.(`[clawroom] connecting to ${endpoint}`);
+
+    try {
+      this.ws = new WebSocket(url);
+    } catch {
+      return; // watchdog will retry
+    }
+
+    this.ws.addEventListener("open", () => {
+      this.options.log?.info?.("[clawroom] connected");
+      this.reconnectAttempt = 0;
+      this.lastActivity = Date.now();
+      this.send({
+        type: "agent.hello",
+        deviceId: this.options.deviceId,
+        skills: this.options.skills,
+      });
+    });
+
+    this.ws.addEventListener("message", (event) => {
+      this.lastActivity = Date.now(); // ANY message = server is alive
+      this.handleMessage(event.data as string);
+    });
+
+    this.ws.addEventListener("close", () => {
+      this.options.log?.info?.("[clawroom] disconnected");
+      this.ws = null;
+      // Don't reconnect here — watchdog handles it
+    });
+
+    this.ws.addEventListener("error", () => {
+      // watchdog handles it
+    });
+  }
+
+  private destroySocket(): void {
+    if (this.ws) {
+      try { this.ws.close(); } catch {}
+      this.ws = null;
+    }
+  }
+
+  // ── Message handling ──────────────────────────────────────────────
+
+  private handleMessage(raw: string): void {
+    let msg: ServerMessage;
+    try { msg = JSON.parse(raw) as ServerMessage; } catch { return; }
+
+    switch (msg.type) {
+      case "server.welcome":
+        this.options.log?.info?.(`[clawroom] welcome, agentId=${msg.agentId}`);
+        for (const cb of this.welcomeCallbacks) cb(msg.agentId);
+        break;
+      case "server.pong":
+        // lastActivity already updated in message handler
+        break;
+      case "server.task":
+        this.options.log?.info?.(`[clawroom] received task ${msg.taskId}: ${msg.title}`);
+        for (const cb of this.taskCallbacks) cb(msg);
+        break;
+      case "server.task_list":
+        this.options.log?.info?.(`[clawroom] received ${msg.tasks.length} open task(s)`);
+        for (const cb of this.taskListCallbacks) cb(msg.tasks);
+        break;
+      case "server.claim_ack":
+        this.options.log?.info?.(`[clawroom] claim_ack taskId=${msg.taskId} ok=${msg.ok}${msg.reason ? ` reason=${msg.reason}` : ""}`);
+        for (const cb of this.claimAckCallbacks) cb(msg);
+        break;
+      case "server.error":
+        this.options.log?.error?.(`[clawroom] server error: ${msg.message}`);
+        for (const cb of this.errorCallbacks) cb(msg);
+        break;
+      default:
+        this.options.log?.warn?.("[clawroom] unknown message type", msg);
+    }
+  }
+}