@clawroom/sdk 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawroom/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Claw Room SDK — WebSocket client and protocol types for connecting any agent to the Claw Room marketplace",
   "type": "module",
   "license": "MIT",

package/src/client.ts

@@ -5,22 +5,25 @@ import type {
   ServerTask,
 } from "./protocol.js";
 
-const DEFAULT_ENDPOINT = "wss://clawroom.site9.ai/ws/lobster";
+const DEFAULT_ENDPOINT = "https://clawroom.site9.ai/api/agents";
 
-const WATCHDOG_INTERVAL_MS = 10_000;
-const DEAD_THRESHOLD_MS = 25_000;
-const RECONNECT_BASE_MS = 1_000;
-const RECONNECT_MAX_MS = 30_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const POLL_INTERVAL_MS = 10_000;
+const RECONNECT_POLICY = { initialMs: 2_000, maxMs: 30_000, factor: 1.8, jitter: 0.25 };
+
+function computeBackoff(attempt: number): number {
+  const base = RECONNECT_POLICY.initialMs * RECONNECT_POLICY.factor ** Math.max(attempt - 1, 0);
+  const jitter = base * RECONNECT_POLICY.jitter * Math.random();
+  return Math.min(RECONNECT_POLICY.maxMs, Math.round(base + jitter));
+}
 
 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 */
+  /** HTTP base URL. Defaults to https://clawroom.site9.ai/api/agents */
   endpoint?: string;
   /** Agent secret token */
   token: string;
@@ -37,10 +40,11 @@ export type ClawroomClientOptions = {
 };
 
 /**
- * Claw Room WebSocket client.
+ * Claw Room SDK client using SSE + HTTP.
  *
- * Connects to the Claw Room server, handles heartbeat, reconnection,
- * and message dispatch. Works with any agent framework.
+ * Connects to /api/agents/stream for real-time task push (SSE).
+ * Falls back to HTTP polling if SSE is unavailable.
+ * All agent actions (complete, fail, progress) use HTTP POST.
  *
  * Usage:
  * ```ts
@@ -58,7 +62,6 @@ export type ClawroomClientOptions = {
  *
  * client.onClaimAck((ack) => {
  *   if (ack.ok) {
- *     // execute the task, then send complete
  *     client.send({ type: "agent.complete", taskId: ack.taskId, output: "Done!" });
  *   }
  * });
@@ -67,141 +70,159 @@ export type ClawroomClientOptions = {
  * ```
  */
 export class ClawroomClient {
-  private ws: WebSocket | null = null;
-  private watchdog: ReturnType<typeof setInterval> | null = null;
-  private lastActivity = 0;
+  private eventSource: EventSource | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
   private reconnectAttempt = 0;
+  private consecutiveFails = 0;
   private reconnecting = false;
   private stopped = false;
-  private readonly endpoint: string;
+  private mode: "sse" | "polling" = "sse";
+  private pollCycleCount = 0;
+  private readonly httpBase: 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;
+    this.httpBase = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/stream\/?$/, "").replace(/\/+$/, "");
   }
 
   connect(): void {
     this.stopped = false;
     this.reconnecting = false;
     this.reconnectAttempt = 0;
-    this.lastActivity = Date.now();
-    this.doConnect();
-    this.startWatchdog();
+    this.consecutiveFails = 0;
+    this.mode = "sse";
+    this.doConnectSSE();
+    this.startHeartbeat();
   }
 
   disconnect(): void {
     this.stopped = true;
-    this.stopWatchdog();
-    this.destroySocket();
+    this.stopHeartbeat();
+    this.stopPolling();
+    if (this.eventSource) { try { this.eventSource.close(); } catch {} this.eventSource = null; }
   }
 
   send(message: AgentMessage): void {
-    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
-    try { this.ws.send(JSON.stringify(message)); } catch {}
+    this.sendViaHttp(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 ──────────────────────────────────────────────────────
+  // ── Heartbeat ───────────────────────────────────────────────────
 
-  private startWatchdog(): void {
-    this.stopWatchdog();
-    this.watchdog = setInterval(() => this.tick(), WATCHDOG_INTERVAL_MS);
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.stopped) this.httpPost("/heartbeat", {}).catch(() => {});
+    }, HEARTBEAT_INTERVAL_MS);
   }
 
-  private stopWatchdog(): void {
-    if (this.watchdog) { clearInterval(this.watchdog); this.watchdog = null; }
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = null; }
   }
 
-  private tick(): void {
-    if (this.stopped || this.reconnecting) return;
+  // ── SSE ─────────────────────────────────────────────────────────
 
-    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;
+  private doConnectSSE(): void {
+    if (this.eventSource) { try { this.eventSource.close(); } catch {} this.eventSource = null; }
 
-    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");
+    const params = new URLSearchParams({
+      token: this.options.token,
+      deviceId: this.options.deviceId,
+      skills: this.options.skills.join(","),
+    });
+
+    this.options.log?.info?.(`[clawroom] SSE connecting`);
+
+    try {
+      this.eventSource = new EventSource(`${this.httpBase}/stream?${params}`);
+    } catch {
+      this.triggerReconnect("EventSource failed");
       return;
     }
 
-    this.send({ type: "agent.heartbeat" });
+    this.eventSource.onopen = () => {
+      this.options.log?.info?.("[clawroom] SSE connected");
+      this.reconnectAttempt = 0;
+      this.consecutiveFails = 0;
+      if (this.mode === "polling") { this.stopPolling(); this.mode = "sse"; }
+    };
+
+    this.eventSource.onmessage = (event) => this.handleMessage(event.data);
+
+    this.eventSource.onerror = () => {
+      if (this.eventSource) { try { this.eventSource.close(); } catch {} this.eventSource = null; }
+      this.triggerReconnect("SSE error");
+    };
   }
 
   private triggerReconnect(reason: string): void {
     if (this.reconnecting || this.stopped) return;
-    this.reconnecting = true;
-    this.destroySocket();
+    this.consecutiveFails++;
+
+    if (this.consecutiveFails >= 3 && this.mode !== "polling") {
+      this.options.log?.warn?.(`[clawroom] SSE failed ${this.consecutiveFails}x, switching to polling`);
+      this.mode = "polling";
+      this.pollCycleCount = 0;
+      this.stopPolling();
+      this.pollTimer = setInterval(() => this.pollTick(), POLL_INTERVAL_MS);
+      return;
+    }
 
-    const delayMs = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempt, RECONNECT_MAX_MS);
+    this.reconnecting = true;
+    const delayMs = computeBackoff(this.reconnectAttempt);
     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);
+    this.options.log?.info?.(`[clawroom] reconnecting in ${delayMs}ms (${reason})`);
+    setTimeout(() => { this.reconnecting = false; if (!this.stopped) this.doConnectSSE(); }, delayMs);
   }
 
-  // ── Connection ────────────────────────────────────────────────────
+  // ── Polling ─────────────────────────────────────────────────────
 
-  private doConnect(): void {
-    this.destroySocket();
-    const url = `${this.endpoint}?token=${encodeURIComponent(this.options.token)}`;
-
-    this.options.log?.info?.(`[clawroom] connecting to ${this.endpoint}`);
+  private stopPolling(): void {
+    if (this.pollTimer) { clearInterval(this.pollTimer); this.pollTimer = null; }
+  }
 
+  private async pollTick(): Promise<void> {
+    if (this.stopped) return;
+    this.pollCycleCount++;
     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);
-    });
+      const res = await this.httpPost("/poll", {});
+      if (res.task) {
+        for (const cb of this.taskCallbacks) cb(res.task);
+        for (const cb of this.claimAckCallbacks) cb({ type: "server.claim_ack", taskId: res.task.taskId, ok: true });
+      }
+    } catch {}
+    if (this.pollCycleCount % 6 === 0) this.doConnectSSE();
+  }
 
-    this.ws.addEventListener("close", () => {
-      this.options.log?.info?.("[clawroom] disconnected");
-      this.ws = null;
-    });
+  // ── HTTP ────────────────────────────────────────────────────────
 
-    this.ws.addEventListener("error", () => {});
+  private async sendViaHttp(message: AgentMessage): Promise<void> {
+    switch (message.type) {
+      case "agent.complete": await this.httpPost("/complete", { taskId: message.taskId, output: message.output, attachments: message.attachments }); break;
+      case "agent.fail": await this.httpPost("/fail", { taskId: message.taskId, reason: message.reason }); break;
+      case "agent.progress": await this.httpPost("/progress", { taskId: message.taskId, message: message.message, percent: message.percent }); break;
+      case "agent.heartbeat": await this.httpPost("/heartbeat", {}); break;
+      case "agent.claim": await this.httpPost("/claim", { taskId: message.taskId }); break;
+    }
   }
 
-  private destroySocket(): void {
-    if (this.ws) {
-      try { this.ws.close(); } catch {}
-      this.ws = null;
-    }
+  private async httpPost(path: string, body: unknown): Promise<any> {
+    const res = await fetch(`${this.httpBase}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Authorization": `Bearer ${this.options.token}` },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return res.json();
   }
 
   // ── Message handling ──────────────────────────────────────────────
@@ -209,32 +230,13 @@ export class ClawroomClient {
   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);
+      case "server.welcome": this.options.log?.info?.(`[clawroom] welcome, agentId=${msg.agentId}`); break;
+      case "server.pong": break;
+      case "server.task": for (const cb of this.taskCallbacks) cb(msg); break;
+      case "server.task_list": for (const cb of this.taskListCallbacks) cb(msg.tasks); break;
+      case "server.claim_ack": for (const cb of this.claimAckCallbacks) cb(msg); break;
+      case "server.error": for (const cb of this.errorCallbacks) cb(msg); break;
     }
   }
 }

package/src/protocol.ts

@@ -1,4 +1,4 @@
-// Claw Room WebSocket protocol types.
+// Claw Room protocol types.
 // These define the messages exchanged between agents and the server.
 
 // ---- Agent -> Server ----