@clawroom/sdk 0.2.2 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clawroom/sdk",
-  "version": "0.2.2",
-  "description": "Claw Room SDK — polling client and protocol types for connecting any agent to the Claw Room marketplace",
+  "version": "0.3.0",
+  "description": "ClawRoom SDK — polling client and protocol types for connecting any agent to ClawRoom",
   "type": "module",
   "license": "MIT",
   "main": "./src/index.ts",
@@ -14,8 +14,7 @@
     "clawroom",
     "sdk",
     "agent",
-    "marketplace",
-    "websocket"
+    "workspace"
   ],
   "files": [
     "src"

package/src/client.ts

@@ -1,8 +1,7 @@
 import type {
   AgentMessage,
-  ServerClaimAck,
-  ServerMessage,
   ServerTask,
+  ServerChatMessage,
 } from "./protocol.js";
 
 const DEFAULT_ENDPOINT = "https://clawroom.site9.ai/api/agents";
@@ -10,10 +9,8 @@ const DEFAULT_ENDPOINT = "https://clawroom.site9.ai/api/agents";
 const HEARTBEAT_INTERVAL_MS = 30_000;
 const POLL_INTERVAL_MS = 10_000;
 
-type TaskCallback = (task: ServerTask) => void;
-type TaskListCallback = (tasks: ServerTask[]) => void;
-type ClaimAckCallback = (ack: ServerClaimAck) => void;
-type ErrorCallback = (error: ServerMessage & { type: "server.error" }) => void;
+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 */
@@ -26,17 +23,17 @@ export type ClawroomClientOptions = {
   skills: string[];
   /** Optional logger */
   log?: {
-    info?: (...args: unknown[]) => void;
-    warn?: (...args: unknown[]) => void;
-    error?: (...args: unknown[]) => void;
+    info?: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+    error?: (message: string, ...args: unknown[]) => void;
   };
 };
 
 /**
- * Claw Room SDK client using HTTP polling.
+ * ClawRoom SDK client using HTTP polling.
  *
- * Agents register with /heartbeat and fetch work from /poll.
- * All agent actions (complete, fail, progress) use HTTP POST.
+ * Agents register with /heartbeat and receive assigned tasks + chat via /poll.
+ * All agent actions (complete, fail, progress, chat reply) use HTTP POST.
  *
  * Usage:
  * ```ts
@@ -49,12 +46,13 @@ export type ClawroomClientOptions = {
  * });
  *
  * client.onTask((task) => {
- *   // handle incoming task
+ *   // task was assigned to this agent — execute it
+ *   client.send({ type: "agent.complete", taskId: task.taskId, output: "Done!" });
  * });
  *
- * client.onClaimAck((ack) => {
- *   if (ack.ok) {
- *     client.send({ type: "agent.complete", taskId: ack.taskId, output: "Done!" });
+ * client.onChatMessage((messages) => {
+ *   for (const msg of messages) {
+ *     client.send({ type: "agent.chat.reply", channelId: msg.channelId, content: "Hello!" });
  *   }
  * });
  *
@@ -64,16 +62,16 @@ export type ClawroomClientOptions = {
 export class ClawroomClient {
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   private pollTimer: ReturnType<typeof setInterval> | null = null;
-  private stopped = false;
-  private readonly httpBase: string;
+  protected stopped = false;
+  protected readonly httpBase: string;
+  protected readonly options: ClawroomClientOptions;
 
-  private taskCallbacks: TaskCallback[] = [];
-  private taskListCallbacks: TaskListCallback[] = [];
-  private claimAckCallbacks: ClaimAckCallback[] = [];
-  private errorCallbacks: ErrorCallback[] = [];
+  protected taskCallbacks: TaskCallback[] = [];
+  protected chatCallbacks: ChatCallback[] = [];
 
-  constructor(private readonly options: ClawroomClientOptions) {
-    this.httpBase = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/stream\/?$/, "").replace(/\/+$/, "");
+  constructor(options: ClawroomClientOptions) {
+    this.options = options;
+    this.httpBase = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
   }
 
   connect(): void {
@@ -95,16 +93,14 @@ export class ClawroomClient {
   }
 
   onTask(cb: TaskCallback): void { this.taskCallbacks.push(cb); }
-  onTaskList(cb: TaskListCallback): void { this.taskListCallbacks.push(cb); }
-  onClaimAck(cb: ClaimAckCallback): void { this.claimAckCallbacks.push(cb); }
-  onError(cb: ErrorCallback): void { this.errorCallbacks.push(cb); }
+  onChatMessage(cb: ChatCallback): void { this.chatCallbacks.push(cb); }
 
   // ── Heartbeat ───────────────────────────────────────────────────
 
   private startHeartbeat(): void {
     this.stopHeartbeat();
     this.heartbeatTimer = setInterval(() => {
-      if (!this.stopped) this.httpPost("/heartbeat", {}).catch(() => {});
+      if (!this.stopped) void this.register();
     }, HEARTBEAT_INTERVAL_MS);
   }
 
@@ -116,64 +112,72 @@ export class ClawroomClient {
     if (this.pollTimer) { clearInterval(this.pollTimer); this.pollTimer = null; }
   }
 
-  private async register(): Promise<void> {
+  protected async register(): Promise<void> {
     try {
-      await this.httpPost("/heartbeat", {
+      await this.httpRequest("POST", "/heartbeat", {
         deviceId: this.options.deviceId,
         skills: this.options.skills,
       });
+      this.onPollSuccess(undefined);
     } catch (err) {
       this.options.log?.warn?.(`[clawroom] heartbeat error: ${err}`);
+      this.onPollError(err);
     }
   }
 
-  private async pollTick(): Promise<void> {
+  protected async pollTick(): Promise<void> {
     if (this.stopped) return;
     try {
-      const res = await this.httpPost("/poll", {});
+      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);
-        for (const cb of this.claimAckCallbacks) cb({ type: "server.claim_ack", taskId: res.task.taskId, ok: true });
+      }
+
+      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);
       }
     } catch (err) {
       this.options.log?.warn?.(`[clawroom] poll error: ${err}`);
+      this.onPollError(err);
     }
   }
 
+  /** Override in subclass for lifecycle tracking */
+  protected onPollSuccess(_agentId: string | undefined): void {}
+  /** Override in subclass for lifecycle tracking */
+  protected onPollError(_err: unknown): void {}
+
   // ── HTTP ────────────────────────────────────────────────────────
 
   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;
+      case "agent.complete": await this.httpRequest("POST", "/complete", { taskId: message.taskId, output: message.output, attachments: message.attachments }); break;
+      case "agent.fail": await this.httpRequest("POST", "/fail", { taskId: message.taskId, reason: message.reason }); break;
+      case "agent.progress": await this.httpRequest("POST", "/progress", { taskId: message.taskId, message: message.message, percent: message.percent }); break;
+      case "agent.heartbeat": await this.httpRequest("POST", "/heartbeat", {}); break;
+      case "agent.chat.reply": await this.httpRequest("POST", "/chat/reply", { channelId: message.channelId, content: message.content, replyTo: message.replyTo }); break;
+      case "agent.typing": await this.httpRequest("POST", "/typing", { channelId: message.channelId }); break;
     }
   }
 
-  private async httpPost(path: string, body: unknown): Promise<any> {
+  protected async httpRequest(method: string, path: string, body: unknown): Promise<any> {
     const res = await fetch(`${this.httpBase}${path}`, {
-      method: "POST",
+      method,
       headers: { "Content-Type": "application/json", "Authorization": `Bearer ${this.options.token}` },
       body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      this.onHttpError(res.status, text);
+      throw new Error(`HTTP ${res.status}: ${text}`);
+    }
     return res.json();
   }
 
-  // ── 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}`); 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;
-    }
-  }
+  /** Override in subclass for error handling (e.g. 401 auto-stop) */
+  protected onHttpError(_status: number, _text: string): void {}
 }

package/src/index.ts

@@ -3,19 +3,14 @@ export type { ClawroomClientOptions } from "./client.js";
 
 export type {
   AgentMessage,
-  AgentHello,
   AgentHeartbeat,
-  AgentClaim,
   AgentComplete,
   AgentProgress,
   AgentResultFile,
   AgentFail,
-  AgentRelease,
+  AgentChatReply,
+  AgentTyping,
   ServerMessage,
-  ServerWelcome,
-  ServerPong,
   ServerTask,
-  ServerTaskList,
-  ServerClaimAck,
-  ServerError,
+  ServerChatMessage,
 } from "./protocol.js";

package/src/protocol.ts

@@ -1,24 +1,12 @@
-// Claw Room protocol types.
+// ClawRoom protocol types.
 // These define the messages exchanged between agents and the server.
 
 // ---- Agent -> Server ----
 
-export interface AgentHello {
-  type: "agent.hello";
-  deviceId: string;
-  skills: string[];
-  kind?: string;
-}
-
 export interface AgentHeartbeat {
   type: "agent.heartbeat";
 }
 
-export interface AgentClaim {
-  type: "agent.claim";
-  taskId: string;
-}
-
 export interface AgentResultFile {
   filename: string;
   mimeType: string;
@@ -45,32 +33,28 @@ export interface AgentFail {
   reason: string;
 }
 
-export interface AgentRelease {
-  type: "agent.release";
-  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 =
-  | AgentHello
   | AgentHeartbeat
-  | AgentClaim
   | AgentComplete
   | AgentProgress
   | AgentFail
-  | AgentRelease;
+  | AgentChatReply
+  | AgentTyping;
 
 // ---- Server -> Agent ----
 
-export interface ServerWelcome {
-  type: "server.welcome";
-  agentId: string;
-}
-
-export interface ServerPong {
-  type: "server.pong";
-}
-
 export interface ServerTask {
   type: "server.task";
   taskId: string;
@@ -80,27 +64,19 @@ export interface ServerTask {
   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 interface ServerChatMessage {
+  messageId: string;
+  channelId: string;
+  content: string;
+  context: Array<{
+    id: string;
+    senderType: string;
+    senderName: string;
+    content: string;
+    createdAt: number;
+  }>;
 }
 
 export type ServerMessage =
-  | ServerWelcome
-  | ServerPong
   | ServerTask
-  | ServerTaskList
-  | ServerClaimAck
-  | ServerError;
+  | ServerChatMessage;