@clawroom/sdk 0.2.3 → 0.4.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.4.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 */
@@ -21,6 +21,8 @@ export type ClawroomClientOptions = {
   deviceId: string;
   /** Agent skills */
   skills: string[];
+  /** Agent kind (e.g. "openclaw", "claude-code", "codex", "custom"). Defaults to "openclaw" */
+  kind?: string;
   /** Optional logger */
   log?: {
     info?: (message: string, ...args: unknown[]) => void;
@@ -32,8 +34,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 +48,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 +64,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 +95,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 +114,73 @@ 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,
+        kind: this.options.kind ?? "openclaw",
       });
+      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

@@ -1,15 +1,18 @@
 export { ClawroomClient } from "./client.js";
 export type { ClawroomClientOptions } from "./client.js";
+export { ClawroomMachineClient } from "./machine-client.js";
+export type { ClawroomMachineClientOptions } from "./machine-client.js";
 
 export type {
   AgentMessage,
   AgentHeartbeat,
-  AgentClaim,
   AgentComplete,
   AgentProgress,
   AgentResultFile,
   AgentFail,
+  AgentChatReply,
+  AgentTyping,
   ServerMessage,
   ServerTask,
-  ServerClaimAck,
+  ServerChatMessage,
 } from "./protocol.js";

package/src/machine-client.ts

@@ -0,0 +1,127 @@
+/**
+ * ClawRoom Machine Client — machine-level auth with multi-agent support.
+ */
+
+import * as os from "node:os";
+
+export type ClawroomMachineClientOptions = {
+  endpoint?: string;
+  apiKey: string;
+  hostname?: string;
+  capabilities?: string[];
+  log?: {
+    info?: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+    error?: (message: string, ...args: unknown[]) => void;
+  };
+};
+
+type AgentWork = {
+  agentId: string;
+  agentName: string;
+  task: { type: "server.task"; taskId: string; title: string; description: string; input: string; skillTags: string[] } | null;
+  chat: Array<{ messageId: string; channelId: string; content: string; isMention: boolean; context: unknown[] }> | null;
+};
+
+export class ClawroomMachineClient {
+  private options: ClawroomMachineClientOptions;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private taskHandler: ((agentId: string, task: AgentWork["task"]) => void) | null = null;
+  private chatHandler: ((agentId: string, messages: NonNullable<AgentWork["chat"]>) => void) | null = null;
+  private _connected = false;
+  private _stopped = false;
+
+  constructor(options: ClawroomMachineClientOptions) {
+    this.options = options;
+  }
+
+  private get baseUrl(): string {
+    return this.options.endpoint ?? "http://localhost:3000/api/machines";
+  }
+
+  private async httpRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.options.apiKey}`,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+    return res.json();
+  }
+
+  onAgentTask(handler: (agentId: string, task: AgentWork["task"]) => void) {
+    this.taskHandler = handler;
+  }
+
+  onAgentChat(handler: (agentId: string, messages: NonNullable<AgentWork["chat"]>) => void) {
+    this.chatHandler = handler;
+  }
+
+  async sendAgentComplete(agentId: string, taskId: string, output: string) {
+    // Use agent-level API via machine auth proxy (or direct)
+    await this.httpRequest("POST", "/complete", { agentId, taskId, output });
+  }
+
+  async sendAgentFail(agentId: string, taskId: string, reason: string) {
+    await this.httpRequest("POST", "/fail", { agentId, taskId, reason });
+  }
+
+  async sendAgentChatReply(agentId: string, channelId: string, content: string) {
+    await this.httpRequest("POST", "/chat-reply", { agentId, channelId, content });
+  }
+
+  async sendAgentTyping(agentId: string, channelId: string) {
+    await this.httpRequest("POST", "/typing", { agentId, channelId });
+  }
+
+  get connected() { return this._connected; }
+  get stopped() { return this._stopped; }
+
+  connect() {
+    this._stopped = false;
+    const hostname = this.options.hostname ?? os.hostname();
+    const hbBody = { hostname, capabilities: this.options.capabilities };
+
+    // Heartbeat every 30s
+    this.heartbeatTimer = setInterval(async () => {
+      try {
+        await this.httpRequest("POST", "/heartbeat", hbBody);
+        if (!this._connected) { this._connected = true; this.options.log?.info?.("[machine] connected"); }
+      } catch (err) {
+        if (this._connected) { this._connected = false; this.options.log?.warn?.("[machine] disconnected"); }
+        this.options.log?.warn?.(`[machine] heartbeat error: ${err}`);
+      }
+    }, 30_000);
+
+    // Initial heartbeat
+    this.httpRequest("POST", "/heartbeat", hbBody)
+      .then(() => { this._connected = true; this.options.log?.info?.("[machine] connected"); })
+      .catch((err) => this.options.log?.warn?.(`[machine] initial heartbeat failed: ${err}`));
+
+    // Poll every 10s
+    this.pollTimer = setInterval(async () => {
+      if (!this._connected) return;
+      try {
+        const result = (await this.httpRequest("POST", "/poll", {})) as { machineId: string; agents: AgentWork[] };
+        for (const agent of result.agents) {
+          if (agent.task && this.taskHandler) this.taskHandler(agent.agentId, agent.task);
+          if (agent.chat && agent.chat.length > 0 && this.chatHandler) this.chatHandler(agent.agentId, agent.chat);
+        }
+      } catch (err) {
+        this.options.log?.warn?.(`[machine] poll error: ${err}`);
+      }
+    }, 10_000);
+  }
+
+  disconnect() {
+    this._stopped = true;
+    this._connected = false;
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    if (this.pollTimer) clearInterval(this.pollTimer);
+  }
+}

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,20 @@ 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;
+  isMention: boolean;
+  context: Array<{
+    id: string;
+    senderType: string;
+    senderName: string;
+    content: string;
+    createdAt: number;
+  }>;
 }
 
 export type ServerMessage =
   | ServerTask
-  | ServerClaimAck;
+  | ServerChatMessage;