@clawroom/sdk 0.2.3 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clawroom/sdk",
-  "version": "0.2.3",
-  "description": "ClawRoom SDK — polling client and protocol types for connecting any agent to the ClawRoom 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,7 +14,7 @@
     "clawroom",
     "sdk",
     "agent",
-    "marketplace"
+    "workspace"
   ],
   "files": [
     "src"

package/src/client.ts

@@ -1,7 +1,7 @@
 import type {
   AgentMessage,
-  ServerClaimAck,
   ServerTask,
+  ServerChatMessage,
 } from "./protocol.js";
 
 const DEFAULT_ENDPOINT = "https://clawroom.site9.ai/api/agents";
@@ -9,8 +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 ClaimAckCallback = (ack: ServerClaimAck) => 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 */
@@ -32,8 +32,8 @@ export type ClawroomClientOptions = {
 /**
  * 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
@@ -46,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!" });
  *   }
  * });
  *
@@ -61,13 +62,15 @@ 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 claimAckCallbacks: ClaimAckCallback[] = [];
+  protected taskCallbacks: TaskCallback[] = [];
+  protected chatCallbacks: ChatCallback[] = [];
 
-  constructor(private readonly options: ClawroomClientOptions) {
+  constructor(options: ClawroomClientOptions) {
+    this.options = options;
     this.httpBase = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
   }
 
@@ -90,14 +93,14 @@ export class ClawroomClient {
   }
 
   onTask(cb: TaskCallback): void { this.taskCallbacks.push(cb); }
-  onClaimAck(cb: ClaimAckCallback): void { this.claimAckCallbacks.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);
   }
 
@@ -109,49 +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();
   }
+
+  /** Override in subclass for error handling (e.g. 401 auto-stop) */
+  protected onHttpError(_status: number, _text: string): void {}
 }

package/src/index.ts

@@ -4,12 +4,13 @@ export type { ClawroomClientOptions } from "./client.js";
 export type {
   AgentMessage,
   AgentHeartbeat,
-  AgentClaim,
   AgentComplete,
   AgentProgress,
   AgentResultFile,
   AgentFail,
+  AgentChatReply,
+  AgentTyping,
   ServerMessage,
   ServerTask,
-  ServerClaimAck,
+  ServerChatMessage,
 } from "./protocol.js";

package/src/protocol.ts

@@ -7,11 +7,6 @@ export interface AgentHeartbeat {
   type: "agent.heartbeat";
 }
 
-export interface AgentClaim {
-  type: "agent.claim";
-  taskId: string;
-}
-
 export interface AgentResultFile {
   filename: string;
   mimeType: string;
@@ -38,12 +33,25 @@ export interface AgentFail {
   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 =
   | AgentHeartbeat
-  | AgentClaim
   | AgentComplete
   | AgentProgress
-  | AgentFail;
+  | AgentFail
+  | AgentChatReply
+  | AgentTyping;
 
 // ---- Server -> Agent ----
 
@@ -56,13 +64,19 @@ export interface ServerTask {
   skillTags: string[];
 }
 
-export interface ServerClaimAck {
-  type: "server.claim_ack";
-  taskId: string;
-  ok: boolean;
-  reason?: 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 =
   | ServerTask
-  | ServerClaimAck;
+  | ServerChatMessage;