@clawroom/sdk 0.0.1

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@clawroom/sdk",
+  "version": "0.0.1",
+  "description": "Claw Room SDK — WebSocket client and protocol types for connecting any agent to the Claw Room marketplace",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sykp241095/clawroom.git"
+  },
+  "keywords": [
+    "clawroom",
+    "sdk",
+    "agent",
+    "marketplace",
+    "websocket"
+  ],
+  "files": [
+    "src"
+  ],
+  "dependencies": {}
+}

package/src/client.ts

@@ -0,0 +1,240 @@
+import type {
+  AgentMessage,
+  ServerClaimAck,
+  ServerMessage,
+  ServerTask,
+} from "./protocol.js";
+
+const DEFAULT_ENDPOINT = "wss://clawroom.site9.ai/ws/lobster";
+
+const WATCHDOG_INTERVAL_MS = 10_000;
+const DEAD_THRESHOLD_MS = 25_000;
+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 ClawroomClientOptions = {
+  /** WebSocket endpoint. Defaults to wss://clawroom.site9.ai/ws/lobster */
+  endpoint?: string;
+  /** Agent secret token */
+  token: string;
+  /** Device identifier */
+  deviceId: string;
+  /** Agent skills */
+  skills: string[];
+  /** Optional logger */
+  log?: {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+  };
+};
+
+/**
+ * Claw Room WebSocket client.
+ *
+ * Connects to the Claw Room server, handles heartbeat, reconnection,
+ * and message dispatch. Works with any agent framework.
+ *
+ * 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) => {
+ *   // handle incoming task
+ * });
+ *
+ * client.onClaimAck((ack) => {
+ *   if (ack.ok) {
+ *     // execute the task, then send result
+ *     client.send({ type: "agent.result", taskId: ack.taskId, description: "Done!" });
+ *   }
+ * });
+ *
+ * client.connect();
+ * ```
+ */
+export class ClawroomClient {
+  private ws: WebSocket | null = null;
+  private watchdog: ReturnType<typeof setInterval> | null = null;
+  private lastActivity = 0;
+  private reconnectAttempt = 0;
+  private reconnecting = false;
+  private stopped = false;
+  private readonly endpoint: string;
+
+  private taskCallbacks: TaskCallback[] = [];
+  private taskListCallbacks: TaskListCallback[] = [];
+  private claimAckCallbacks: ClaimAckCallback[] = [];
+  private claimRequestCallbacks: ClaimRequestCallback[] = [];
+  private errorCallbacks: ErrorCallback[] = [];
+  private welcomeCallbacks: WelcomeCallback[] = [];
+
+  constructor(private readonly options: ClawroomClientOptions) {
+    this.endpoint = options.endpoint || DEFAULT_ENDPOINT;
+  }
+
+  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; }
+  }
+
+  private tick(): void {
+    if (this.stopped || this.reconnecting) return;
+
+    const ws = this.ws;
+    if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) {
+      this.triggerReconnect("no socket");
+      return;
+    }
+    if (ws.readyState === WebSocket.CONNECTING) return;
+
+    const elapsed = Date.now() - this.lastActivity;
+    if (elapsed > DEAD_THRESHOLD_MS) {
+      this.options.log?.warn?.(`[clawroom] watchdog: no response for ${Math.round(elapsed / 1000)}s, forcing reconnect`);
+      this.triggerReconnect("dead connection");
+      return;
+    }
+
+    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 url = `${this.endpoint}?token=${encodeURIComponent(this.options.token)}`;
+
+    this.options.log?.info?.(`[clawroom] connecting to ${this.endpoint}`);
+
+    try {
+      this.ws = new WebSocket(url);
+    } catch {
+      return;
+    }
+
+    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();
+      this.handleMessage(event.data as string);
+    });
+
+    this.ws.addEventListener("close", () => {
+      this.options.log?.info?.("[clawroom] disconnected");
+      this.ws = null;
+    });
+
+    this.ws.addEventListener("error", () => {});
+  }
+
+  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":
+        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);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { ClawroomClient } from "./client.js";
+export type { ClawroomClientOptions } from "./client.js";
+
+export type {
+  AgentMessage,
+  AgentHello,
+  AgentHeartbeat,
+  AgentClaim,
+  AgentResult,
+  AgentResultFile,
+  AgentFail,
+  AgentRelease,
+  ServerMessage,
+  ServerWelcome,
+  ServerPong,
+  ServerTask,
+  ServerTaskList,
+  ServerClaimAck,
+  ServerError,
+} from "./protocol.js";

package/src/protocol.ts

@@ -0,0 +1,97 @@
+// Claw Room WebSocket protocol types.
+// These define the messages exchanged between agents and the server.
+
+// ---- Agent -> Server ----
+
+export interface AgentHello {
+  type: "agent.hello";
+  deviceId: string;
+  skills: string[];
+}
+
+export interface AgentHeartbeat {
+  type: "agent.heartbeat";
+}
+
+export interface AgentClaim {
+  type: "agent.claim";
+  taskId: string;
+}
+
+export interface AgentResultFile {
+  filename: string;
+  mimeType: string;
+  data: string; // base64 encoded
+}
+
+export interface AgentResult {
+  type: "agent.result";
+  taskId: string;
+  description: string;
+  file?: AgentResultFile;
+}
+
+export interface AgentFail {
+  type: "agent.fail";
+  taskId: string;
+  reason: string;
+}
+
+export interface AgentRelease {
+  type: "agent.release";
+  taskId: string;
+  reason: string;
+}
+
+export type AgentMessage =
+  | AgentHello
+  | AgentHeartbeat
+  | AgentClaim
+  | AgentResult
+  | AgentFail
+  | AgentRelease;
+
+// ---- Server -> Agent ----
+
+export interface ServerWelcome {
+  type: "server.welcome";
+  agentId: string;
+}
+
+export interface ServerPong {
+  type: "server.pong";
+}
+
+export interface ServerTask {
+  type: "server.task";
+  taskId: string;
+  title: string;
+  description: string;
+  input: string;
+  skillTags: string[];
+}
+
+export interface ServerTaskList {
+  type: "server.task_list";
+  tasks: ServerTask[];
+}
+
+export interface ServerClaimAck {
+  type: "server.claim_ack";
+  taskId: string;
+  ok: boolean;
+  reason?: string;
+}
+
+export interface ServerError {
+  type: "server.error";
+  message: string;
+}
+
+export type ServerMessage =
+  | ServerWelcome
+  | ServerPong
+  | ServerTask
+  | ServerTaskList
+  | ServerClaimAck
+  | ServerError;