@clawroom/sdk 0.5.2 → 0.5.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawroom/sdk",
-  "version": "0.5.2",
+  "version": "0.5.20",
   "description": "ClawRoom SDK — polling client and protocol types for connecting any agent to ClawRoom",
   "type": "module",
   "license": "MIT",

package/src/client.ts

@@ -1,6 +1,8 @@
 import type {
   AgentChatProfile,
+  AgentResultFile,
   AgentMessage,
+  AgentWorkRef,
   ServerTask,
   ServerChatMessage,
 } from "./protocol.js";
@@ -13,11 +15,14 @@ const DEFAULT_AGENT_CHAT_PROFILE: AgentChatProfile = {
   role: "No role defined",
   systemPrompt: "No system prompt configured",
   memory: "No memory recorded yet",
-  focus: "No focus items",
+  continuityPacket: "No continuity packet available yet",
 };
 
 export type TaskCallback = (task: ServerTask) => void;
 export type ChatCallback = (messages: ServerChatMessage[]) => void;
+export type ConnectedCallback = (agentId: string) => void;
+export type DisconnectedCallback = () => void;
+export type Unsubscribe = () => void;
 
 export type ClawroomClientOptions = {
   endpoint?: string;
@@ -33,6 +38,17 @@ export type ClawroomClientOptions = {
   };
 };
 
+type AgentHeartbeatResponse = {
+  ok?: boolean;
+  agentId?: string;
+};
+
+type AgentPollResponse = {
+  agentId?: string;
+  task: ServerTask | null;
+  chat: ServerChatMessage[] | null;
+};
+
 /**
  * ClawRoom SDK client.
  * WebSocket primary for real-time push, HTTP polling as fallback.
@@ -40,13 +56,19 @@ export type ClawroomClientOptions = {
 export class ClawroomClient {
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private heartbeatInFlight = false;
+  private pollInFlight = false;
   protected stopped = false;
   protected readonly httpBase: string;
   protected readonly options: ClawroomClientOptions;
   protected taskCallbacks: TaskCallback[] = [];
   protected chatCallbacks: ChatCallback[] = [];
+  private connectedCallbacks: ConnectedCallback[] = [];
+  private disconnectedCallbacks: DisconnectedCallback[] = [];
   private wsTransport: WsTransport | null = null;
   private recentChatIds = new Set<string>();
+  private connectedAgentId: string | null = null;
+  private isConnectedValue = false;
 
   constructor(options: ClawroomClientOptions) {
     this.options = options;
@@ -58,12 +80,26 @@ export class ClawroomClient {
     return this.httpBase.replace(/\/api\/agents$/, "").replace(/^http/, "ws") + "/api/ws";
   }
 
+  get connected(): boolean {
+    return this.isConnectedValue;
+  }
+
+  get agentId(): string | null {
+    return this.connectedAgentId;
+  }
+
+  get isAlive(): boolean {
+    return !this.stopped;
+  }
+
   connect(): void {
     this.stopped = false;
     this.startHeartbeat();
     void this.register();
 
     // WebSocket transport
+    this.wsTransport?.disconnect();
+    this.wsTransport = null;
     this.wsTransport = new WsTransport({
       url: this.wsUrl,
       token: this.options.token,
@@ -72,29 +108,34 @@ export class ClawroomClient {
       onDisconnected: () => { this.options.log?.info?.("[clawroom] WebSocket disconnected"); },
       onMessage: (msg) => {
         if (msg.type === "task" && msg.task) {
-          for (const cb of this.taskCallbacks) cb(msg.task);
+          const task = msg.task as ServerTask;
+          void this.dispatchTask(task);
         }
         if (msg.type === "chat" && Array.isArray(msg.messages)) {
-          const fresh = msg.messages.filter((m: ServerChatMessage) => this.rememberChat(m.messageId));
+          const fresh = msg.messages.filter((m: ServerChatMessage) => this.rememberChat(m.workId ?? m.messageId));
           if (fresh.length > 0) {
             for (const cb of this.chatCallbacks) cb(fresh);
-            this.ackChatBestEffort(fresh.map((m: ServerChatMessage) => m.messageId));
           }
         }
-        if (msg.type === "message" && msg.message) {
-          const agentProfile = msg.agentProfile ?? msg.message.agentProfile ?? DEFAULT_AGENT_CHAT_PROFILE;
+        const message = getRecord(msg.message);
+        if (msg.type === "message" && message) {
+          const agentProfile = resolveAgentChatProfile(msg.agentProfile, message.agentProfile);
           const delivered = [{
-            messageId: msg.message.id ?? msg.messageId,
-            channelId: msg.message.channelId ?? "",
-            content: msg.message.content ?? "",
-            context: Array.isArray(msg.context) ? msg.context : [],
-            isMention: msg.isMention ?? false,
+            workId: getString(message.workId),
+            leaseToken: getString(message.leaseToken),
+            messageId: getString(message.id, getString(msg.messageId)),
+            channelId: getString(message.channelId),
+            content: getString(message.content),
+            attachments: getAttachments(msg.attachments) ?? getAttachments(message.attachments),
+            context: getContext(msg.context),
+            isMention: typeof msg.isMention === "boolean" ? msg.isMention : false,
+            wakeReason: getWakeReason(msg.wakeReason) ?? getWakeReason(message.wakeReason),
+            triggerReason: getOptionalString(msg.triggerReason) ?? getOptionalString(message.triggerReason),
             agentProfile,
           }] as ServerChatMessage[];
-          const fresh = delivered.filter((m) => this.rememberChat(m.messageId));
+          const fresh = delivered.filter((m) => this.rememberChat(m.workId ?? m.messageId));
           if (fresh.length > 0) {
             for (const cb of this.chatCallbacks) cb(fresh);
-            this.ackChatBestEffort(fresh.map((m) => m.messageId));
           }
         }
       },
@@ -117,14 +158,84 @@ export class ClawroomClient {
     this.stopPolling();
     this.wsTransport?.disconnect();
     this.wsTransport = null;
+    this.recentChatIds.clear();
+    this.markDisconnected();
+    this.connectedAgentId = null;
+  }
+
+  async send(message: AgentMessage): Promise<void> {
+    await this.sendViaHttp(message);
+  }
+
+  onTask(cb: TaskCallback): Unsubscribe {
+    this.taskCallbacks.push(cb);
+    return () => this.offTask(cb);
+  }
+
+  offTask(cb: TaskCallback): void {
+    removeCallback(this.taskCallbacks, cb);
+  }
+
+  onChatMessage(cb: ChatCallback): Unsubscribe {
+    this.chatCallbacks.push(cb);
+    return () => this.offChatMessage(cb);
+  }
+
+  offChatMessage(cb: ChatCallback): void {
+    removeCallback(this.chatCallbacks, cb);
+  }
+
+  onConnected(cb: ConnectedCallback): Unsubscribe {
+    this.connectedCallbacks.push(cb);
+    return () => this.offConnected(cb);
+  }
+
+  offConnected(cb: ConnectedCallback): void {
+    removeCallback(this.connectedCallbacks, cb);
+  }
+
+  onDisconnected(cb: DisconnectedCallback): Unsubscribe {
+    this.disconnectedCallbacks.push(cb);
+    return () => this.offDisconnected(cb);
+  }
+
+  offDisconnected(cb: DisconnectedCallback): void {
+    removeCallback(this.disconnectedCallbacks, cb);
+  }
+
+  async sendComplete(taskId: string, output: string, attachments?: AgentResultFile[], workRef?: AgentWorkRef): Promise<void> {
+    await this.send({ type: "agent.complete", taskId, output, attachments, workRef });
+  }
+
+  async sendFail(taskId: string, reason: string, workRef?: AgentWorkRef): Promise<void> {
+    await this.send({ type: "agent.fail", taskId, reason, workRef });
+  }
+
+  async sendProgress(taskId: string, message: string, workRef?: AgentWorkRef): Promise<void> {
+    await this.send({ type: "agent.progress", taskId, message, workRef });
   }
 
-  send(message: AgentMessage): void {
-    this.sendViaHttp(message).catch(() => {});
+  async sendChatReply(channelId: string, content: string, replyTo?: string, workRefs?: AgentWorkRef[]): Promise<void> {
+    await this.send({ type: "agent.chat.reply", channelId, content, replyTo, workRefs });
   }
 
-  onTask(cb: TaskCallback): void { this.taskCallbacks.push(cb); }
-  onChatMessage(cb: ChatCallback): void { this.chatCallbacks.push(cb); }
+  async sendTyping(channelId: string): Promise<void> {
+    await this.send({ type: "agent.typing", channelId });
+  }
+
+  async sendReflection(reflection: {
+    scope: "chat" | "task";
+    status: string;
+    summary: string;
+    channelId?: string | null;
+    taskId?: string | null;
+    messageId?: string | null;
+    toolsUsed?: string[];
+    responseExcerpt?: string | null;
+    detail?: Record<string, unknown>;
+  }): Promise<void> {
+    await this.httpRequest("POST", "/reflections", reflection);
+  }
 
   // ── Heartbeat ─────────────────────────────────────────
 
@@ -144,54 +255,73 @@ export class ClawroomClient {
   }
 
   protected async register(): Promise<void> {
+    if (this.heartbeatInFlight) return;
+    this.heartbeatInFlight = true;
     try {
-      await this.httpRequest("POST", "/heartbeat", {
+      const response = await this.httpRequest("POST", "/heartbeat", {
         deviceId: this.options.deviceId,
         skills: this.options.skills,
         kind: this.options.kind ?? "openclaw",
-      });
-      this.onPollSuccess(undefined);
+      }) as AgentHeartbeatResponse;
+      this.onPollSuccess(response.agentId);
     } catch (err) {
       this.options.log?.warn?.(`[clawroom] heartbeat error: ${err}`);
-      this.onPollError(err);
+      if (!this.wsTransport?.connected) {
+        this.onPollError(err);
+      }
+    } finally {
+      this.heartbeatInFlight = false;
     }
   }
 
   protected async pollTick(): Promise<void> {
-    if (this.stopped) return;
+    if (this.stopped || this.pollInFlight) return;
+    this.pollInFlight = true;
     try {
-      const res = await this.httpRequest("POST", "/poll", {});
+      const res = await this.httpRequest("POST", "/poll", {}) as AgentPollResponse;
       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);
+        await this.dispatchTask(res.task);
       }
       if (res.chat && Array.isArray(res.chat) && res.chat.length > 0) {
-        const fresh = res.chat.filter((m: ServerChatMessage) => this.rememberChat(m.messageId));
+        const fresh = res.chat.filter((m: ServerChatMessage) => this.rememberChat(m.workId ?? m.messageId));
         if (fresh.length > 0) {
           this.options.log?.info?.(`[clawroom] received ${fresh.length} chat mention(s)`);
           for (const cb of this.chatCallbacks) cb(fresh);
-          this.ackChatBestEffort(fresh.map((m: ServerChatMessage) => m.messageId));
         }
       }
     } catch (err) {
       this.options.log?.warn?.(`[clawroom] poll error: ${err}`);
       this.onPollError(err);
+    } finally {
+      this.pollInFlight = false;
     }
   }
 
-  protected onPollSuccess(_agentId: string | undefined): void {}
-  protected onPollError(_err: unknown): void {}
+  protected onPollSuccess(agentId: string | undefined): void {
+    this.markConnected(agentId);
+  }
+
+  protected onPollError(err: unknown): void {
+    void err;
+    if (this.wsTransport?.connected) return;
+    this.markDisconnected();
+  }
 
   // ── HTTP ──────────────────────────────────────────────
 
   private async sendViaHttp(message: AgentMessage): Promise<void> {
     switch (message.type) {
-      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.complete": await this.httpRequest("POST", "/complete", { taskId: message.taskId, output: message.output, attachments: message.attachments, workRef: message.workRef }); break;
+      case "agent.fail": await this.httpRequest("POST", "/fail", { taskId: message.taskId, reason: message.reason, workRef: message.workRef }); break;
+      case "agent.progress": await this.httpRequest("POST", "/progress", { taskId: message.taskId, message: message.message, workRef: message.workRef }); 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.chat.reply": await this.httpRequest("POST", "/chat/reply", {
+        channelId: message.channelId,
+        content: message.content,
+        replyTo: message.replyTo,
+        workRefs: message.workRefs,
+      }); break;
       case "agent.typing": await this.httpRequest("POST", "/typing", { channelId: message.channelId }); break;
     }
   }
@@ -202,18 +332,26 @@ export class ClawroomClient {
       headers: { "Content-Type": "application/json", "Authorization": `Bearer ${this.options.token}` },
       body: JSON.stringify(body),
     });
+    const text = await res.text().catch(() => "");
     if (!res.ok) {
-      const text = await res.text().catch(() => "");
       this.onHttpError(res.status, text);
       throw new Error(`HTTP ${res.status}: ${text}`);
     }
-    return res.json();
+    if (!text) return null;
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new Error(`Invalid JSON response from ${path}`);
+    }
   }
 
-  protected onHttpError(_status: number, _text: string): void {}
+  protected onHttpError(status: number, text: string): void {
+    void status;
+    void text;
+  }
 
   private rememberChat(messageId?: string): boolean {
-    if (!messageId) return true;
+    if (!messageId) return false;
     if (this.recentChatIds.has(messageId)) return false;
     this.recentChatIds.add(messageId);
     if (this.recentChatIds.size > 1000) {
@@ -223,15 +361,70 @@ export class ClawroomClient {
     return true;
   }
 
-  private ackChatBestEffort(messageIds: string[]): void {
-    void this.ackChat(messageIds).catch((err) => {
-      this.options.log?.warn?.(`[clawroom] chat ack error: ${err}`);
-    });
+  private async dispatchTask(task: ServerTask): Promise<void> {
+    this.options.log?.info?.(`[clawroom] received task ${task.taskId}: ${task.title}`);
+    for (const cb of this.taskCallbacks) cb(task);
   }
 
-  private async ackChat(messageIds: string[]): Promise<void> {
-    const ids = Array.from(new Set(messageIds.filter(Boolean)));
-    if (ids.length === 0) return;
-    await this.httpRequest("POST", "/chat/ack", { messageIds: ids });
+  private markConnected(agentId?: string): void {
+    if (agentId) this.connectedAgentId = agentId;
+    if (!this.connectedAgentId || this.isConnectedValue) return;
+    this.isConnectedValue = true;
+    for (const callback of this.connectedCallbacks) callback(this.connectedAgentId);
+  }
+
+  private markDisconnected(): void {
+    if (!this.isConnectedValue) return;
+    this.isConnectedValue = false;
+    for (const callback of this.disconnectedCallbacks) callback();
+  }
+}
+
+function removeCallback<T>(callbacks: T[], callback: T): void {
+  const index = callbacks.indexOf(callback);
+  if (index !== -1) callbacks.splice(index, 1);
+}
+
+function getRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function getString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function getOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function getAttachments(value: unknown): ServerChatMessage["attachments"] | undefined {
+  return Array.isArray(value) ? value as ServerChatMessage["attachments"] : undefined;
+}
+
+function getContext(value: unknown): ServerChatMessage["context"] {
+  return Array.isArray(value) ? value as ServerChatMessage["context"] : [];
+}
+
+function getWakeReason(value: unknown): ServerChatMessage["wakeReason"] | undefined {
+  return typeof value === "string" ? value as ServerChatMessage["wakeReason"] : undefined;
+}
+
+function getAgentChatProfile(value: unknown): AgentChatProfile | null {
+  const record = getRecord(value);
+  if (!record) return null;
+  return {
+    role: getString(record.role, DEFAULT_AGENT_CHAT_PROFILE.role),
+    systemPrompt: getString(record.systemPrompt, DEFAULT_AGENT_CHAT_PROFILE.systemPrompt),
+    memory: getString(record.memory, DEFAULT_AGENT_CHAT_PROFILE.memory),
+    continuityPacket: getString(record.continuityPacket, DEFAULT_AGENT_CHAT_PROFILE.continuityPacket),
+  };
+}
+
+function resolveAgentChatProfile(...values: unknown[]): AgentChatProfile {
+  for (const value of values) {
+    const profile = getAgentChatProfile(value);
+    if (profile) return profile;
   }
+  return DEFAULT_AGENT_CHAT_PROFILE;
 }

package/src/index.ts

@@ -7,6 +7,7 @@ export type { WsTransportOptions } from "./ws-transport.js";
 
 export type {
   AgentChatProfile,
+  ChatAttachmentRef,
   AgentMessage,
   AgentHeartbeat,
   AgentComplete,

package/src/machine-client.ts

@@ -4,7 +4,7 @@
  */
 
 import * as os from "node:os";
-import type { AgentChatProfile, ServerChatMessage } from "./protocol.js";
+import type { AgentChatProfile, AgentWorkRef, ServerChatMessage, ServerTask } from "./protocol.js";
 import { WsTransport } from "./ws-transport.js";
 
 export type ClawroomMachineClientOptions = {
@@ -20,10 +20,22 @@ export type ClawroomMachineClientOptions = {
   };
 };
 
+export type AgentReflectionPayload = {
+  scope: "chat" | "task";
+  status: string;
+  summary: string;
+  channelId?: string | null;
+  taskId?: string | null;
+  messageId?: string | null;
+  toolsUsed?: string[];
+  responseExcerpt?: string | null;
+  detail?: Record<string, unknown>;
+};
+
 type AgentWork = {
   agentId: string;
   agentName: string;
-  task: { type: "server.task"; taskId: string; title: string; description: string; input: string; skillTags: string[] } | null;
+  task: ServerTask | null;
   chat: ServerChatMessage[] | null;
 };
 
@@ -31,8 +43,9 @@ const DEFAULT_AGENT_CHAT_PROFILE: AgentChatProfile = {
   role: "No role defined",
   systemPrompt: "No system prompt configured",
   memory: "No memory recorded yet",
-  focus: "No focus items",
+  continuityPacket: "No continuity packet available yet",
 };
+const MAX_RECENT_CHAT_IDS = 1000;
 
 type MachineHeartbeatResponse = {
   machineId: string;
@@ -48,6 +61,8 @@ export class ClawroomMachineClient {
   private options: ClawroomMachineClientOptions;
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private heartbeatInFlight = false;
+  private pollInFlight = false;
   private taskHandler: ((agentId: string, task: AgentWork["task"]) => void) | null = null;
   private chatHandler: ((agentId: string, messages: NonNullable<AgentWork["chat"]>) => void) | null = null;
   private connectHandler: ((machineId: string) => void) | null = null;
@@ -55,7 +70,6 @@ export class ClawroomMachineClient {
   private _connected = false;
   private _stopped = false;
   private wsTransport: WsTransport | null = null;
-  private subscribedAgentIds = new Set<string>();
   private recentChatIds = new Map<string, number>();
 
   constructor(options: ClawroomMachineClientOptions) {
@@ -79,7 +93,15 @@ export class ClawroomMachineClient {
       body: body ? JSON.stringify(body) : undefined,
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
-    return res.json();
+    const text = await res.text();
+    if (!text.trim()) return null;
+    try {
+      return JSON.parse(text) as unknown;
+    } catch (error) {
+      throw new Error(
+        `Invalid JSON from ${path}: ${error instanceof Error ? error.message : "unknown parse error"}`,
+      );
+    }
   }
 
   onAgentTask(handler: (agentId: string, task: AgentWork["task"]) => void) { this.taskHandler = handler; }
@@ -87,56 +109,44 @@ export class ClawroomMachineClient {
   onConnected(handler: (machineId: string) => void) { this.connectHandler = handler; }
   onDisconnected(handler: () => void) { this.disconnectHandler = handler; }
 
-  async sendAgentComplete(agentId: string, taskId: string, output: string, attachments?: Array<{ filename: string; mimeType: string; data: string }>) {
-    await this.httpRequest("POST", "/complete", { agentId, taskId, output, attachments });
+  async sendAgentComplete(agentId: string, taskId: string, output: string, attachments?: Array<{ filename: string; mimeType: string; data: string }>, workRef?: AgentWorkRef) {
+    await this.httpRequest("POST", "/complete", { agentId, taskId, output, attachments, workRef });
   }
 
-  async sendAgentFail(agentId: string, taskId: string, reason: string) {
-    await this.httpRequest("POST", "/fail", { agentId, taskId, reason });
+  async sendAgentFail(agentId: string, taskId: string, reason: string, workRef?: AgentWorkRef) {
+    await this.httpRequest("POST", "/fail", { agentId, taskId, reason, workRef });
   }
 
-  async sendAgentChatReply(agentId: string, channelId: string, content: string) {
-    await this.httpRequest("POST", "/chat-reply", { agentId, channelId, content });
+  async sendAgentChatReply(agentId: string, channelId: string, content: string, replyTo?: string, workRefs?: AgentWorkRef[]) {
+    await this.httpRequest("POST", "/chat-reply", { agentId, channelId, content, replyTo, workRefs });
   }
 
   async sendAgentTyping(agentId: string, channelId: string) {
     await this.httpRequest("POST", "/typing", { agentId, channelId });
   }
 
-  async ackAgentChat(agentId: string, messageIds: string[]) {
-    const ids = Array.from(new Set(messageIds.filter(Boolean)));
-    if (ids.length === 0) return;
-    await this.httpRequest("POST", "/chat-ack", { agentId, messageIds: ids });
+  async sendAgentReflection(agentId: string, reflection: AgentReflectionPayload) {
+    await this.httpRequest("POST", "/reflections", { agentId, ...reflection });
   }
 
   get connected() { return this._connected; }
   get stopped() { return this._stopped; }
 
-  private rememberChat(messageId: string): boolean {
-    if (!messageId) return true;
+  private rememberChat(messageId?: string | null): boolean {
+    if (!messageId) return false;
     const now = Date.now();
     for (const [id, seenAt] of this.recentChatIds) {
       if (now - seenAt > 10 * 60_000) this.recentChatIds.delete(id);
     }
     if (this.recentChatIds.has(messageId)) return false;
+    if (this.recentChatIds.size >= MAX_RECENT_CHAT_IDS) {
+      const oldestId = this.recentChatIds.keys().next().value;
+      if (oldestId) this.recentChatIds.delete(oldestId);
+    }
     this.recentChatIds.set(messageId, now);
     return true;
   }
 
-  private ackAgentChatBestEffort(agentId: string, messageIds: string[]) {
-    void this.ackAgentChat(agentId, messageIds).catch((err) => {
-      this.options.log?.warn?.(`[machine] chat ack error: ${err}`);
-    });
-  }
-
-  private syncAgentSubscriptions(agentIds: string[]) {
-    if (agentIds.length === 0) return;
-    for (const agentId of agentIds) {
-      this.subscribedAgentIds.add(agentId);
-      this.wsTransport?.send({ type: "subscribe_agent", agentId });
-    }
-  }
-
   private markConnected(machineId: string) {
     if (!this._connected) {
       this._connected = true;
@@ -154,48 +164,76 @@ export class ClawroomMachineClient {
   }
 
   private async pollOnce() {
-    if (!this._connected) return;
+    if (!this._connected || this.pollInFlight) return;
+    this.pollInFlight = true;
     try {
       const result = (await this.httpRequest("POST", "/poll", {})) as MachinePollResponse;
-      this.syncAgentSubscriptions(result.agents.map((agent) => agent.agentId));
       for (const agent of result.agents) {
-        if (agent.task && this.taskHandler) this.taskHandler(agent.agentId, agent.task);
+        if (agent.task && this.taskHandler) {
+          try {
+            this.taskHandler(agent.agentId, agent.task);
+          } catch (err) {
+            this.options.log?.warn?.(
+              `[machine] task dispatch failed for agent ${agent.agentId} task ${agent.task.taskId}: ${err}`,
+            );
+          }
+        }
         if (agent.chat && agent.chat.length > 0 && this.chatHandler) {
-          const freshMessages = agent.chat.filter((message) => this.rememberChat(message.messageId));
-          if (freshMessages.length > 0) {
-            this.chatHandler(agent.agentId, freshMessages);
-            this.ackAgentChatBestEffort(agent.agentId, freshMessages.map((message) => message.messageId));
+          try {
+            const freshMessages = agent.chat.filter((message) => this.rememberChat(message.workId ?? message.messageId));
+            if (freshMessages.length > 0) {
+              this.chatHandler(agent.agentId, freshMessages);
+            }
+          } catch (err) {
+            this.options.log?.warn?.(`[machine] chat dispatch failed for agent ${agent.agentId}: ${err}`);
           }
         }
       }
     } catch (err) {
       this.options.log?.warn?.(`[machine] poll error: ${err}`);
+    } finally {
+      this.pollInFlight = false;
     }
   }
 
   connect() {
+    this.stopHeartbeat();
+    this.stopPolling();
+    this.wsTransport?.disconnect();
+    this.wsTransport = null;
     this._stopped = false;
     const hostname = this.options.hostname ?? os.hostname();
-    const hbBody = { hostname, capabilities: this.options.capabilities };
-
-    // Heartbeat every 30s (always HTTP)
-    this.heartbeatTimer = setInterval(async () => {
+    const hbBody = {
+      hostname,
+      capabilities: this.options.capabilities,
+      platform: os.platform(),
+      architecture: os.arch(),
+      osRelease: os.release(),
+    };
+    const sendHeartbeat = async () => {
+      if (this.heartbeatInFlight) return;
+      this.heartbeatInFlight = true;
       try {
         const result = (await this.httpRequest("POST", "/heartbeat", hbBody)) as MachineHeartbeatResponse;
-        this.syncAgentSubscriptions((result.agents ?? []).map((agent) => agent.id));
         this.markConnected(result.machineId);
-      } catch {
-        this.markDisconnected();
+      } catch (err) {
+        if (!this.wsTransport?.connected) {
+          this.markDisconnected();
+        } else {
+          this.options.log?.warn?.(`[machine] heartbeat failed while WS is still connected: ${err}`);
+        }
+        throw err;
+      } finally {
+        this.heartbeatInFlight = false;
       }
+    };
+
+    // Heartbeat every 30s (always HTTP)
+    this.heartbeatTimer = setInterval(() => {
+      void sendHeartbeat().catch(() => {});
     }, 30_000);
 
-    this.httpRequest("POST", "/heartbeat", hbBody)
-      .then((result) => {
-        const data = result as MachineHeartbeatResponse;
-        this.syncAgentSubscriptions((data.agents ?? []).map((agent) => agent.id));
-        this.markConnected(data.machineId);
-      })
-      .catch((err) => this.options.log?.warn?.(`[machine] initial heartbeat failed: ${err}`));
+    sendHeartbeat().catch((err) => this.options.log?.warn?.(`[machine] initial heartbeat failed: ${err}`));
 
     // WebSocket transport
     this.wsTransport = new WsTransport({
@@ -203,33 +241,37 @@ export class ClawroomMachineClient {
       token: this.options.apiKey,
       log: { info: (m) => this.options.log?.info?.(m), warn: (m) => this.options.log?.warn?.(m) },
       onConnected: () => {
-        this.syncAgentSubscriptions([...this.subscribedAgentIds]);
         this.options.log?.info?.("[machine] WebSocket connected");
       },
       onDisconnected: () => {
         this.options.log?.info?.("[machine] WebSocket disconnected, HTTP polling active");
       },
       onMessage: (msg) => {
+        const message = getRecord(msg.message);
         if (msg.type === "message") {
-          const m = msg.message;
-          const targetAgentId = msg.agentId ?? m?.agentId;
-          const messageId = m?.id ?? msg.messageId ?? "";
-          if (m && targetAgentId && this.chatHandler && this.rememberChat(messageId)) {
-            const agentProfile = msg.agentProfile ?? m.agentProfile ?? DEFAULT_AGENT_CHAT_PROFILE;
+          const targetAgentId = getOptionalString(msg.agentId) ?? getOptionalString(message?.agentId);
+          const messageId = getString(message?.id, getString(msg.messageId));
+          if (message && targetAgentId && this.chatHandler && this.rememberChat(messageId)) {
+            const agentProfile = resolveAgentChatProfile(msg.agentProfile, message?.agentProfile);
             const messages = [{
+              workId: getString(message?.workId),
+              leaseToken: getString(message?.leaseToken),
               messageId,
-              channelId: m.channelId ?? "",
-              content: m.content ?? "",
-              isMention: msg.isMention ?? false,
-              context: msg.context ?? [],
+              channelId: getString(message?.channelId),
+              content: getString(message?.content),
+              attachments: getAttachments(msg.attachments) ?? getAttachments(message?.attachments),
+              isMention: typeof msg.isMention === "boolean" ? msg.isMention : false,
+              wakeReason: getWakeReason(msg.wakeReason) ?? getWakeReason(message?.wakeReason),
+              triggerReason: getOptionalString(msg.triggerReason) ?? getOptionalString(message?.triggerReason),
+              context: getContext(msg.context),
               agentProfile,
             }];
             this.chatHandler(targetAgentId, messages);
-            this.ackAgentChatBestEffort(targetAgentId, messages.map((message) => message.messageId));
           }
         }
-        if (msg.type === "task" && msg.agentId && this.taskHandler) {
-          this.taskHandler(msg.agentId, msg.task);
+        const taskAgentId = getOptionalString(msg.agentId);
+        if (msg.type === "task" && taskAgentId && this.taskHandler) {
+          this.taskHandler(taskAgentId, (msg.task as AgentWork["task"] | undefined) ?? null);
         }
       },
     });
@@ -247,9 +289,68 @@ export class ClawroomMachineClient {
   disconnect() {
     this._stopped = true;
     this._connected = false;
-    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-    if (this.pollTimer) clearInterval(this.pollTimer);
+    this.stopHeartbeat();
+    this.stopPolling();
     this.wsTransport?.disconnect();
     this.wsTransport = null;
+    this.recentChatIds.clear();
+  }
+
+  private stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private stopPolling() {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+}
+
+function getRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function getString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function getOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function getAttachments(value: unknown): ServerChatMessage["attachments"] | undefined {
+  return Array.isArray(value) ? value as ServerChatMessage["attachments"] : undefined;
+}
+
+function getContext(value: unknown): ServerChatMessage["context"] {
+  return Array.isArray(value) ? value as ServerChatMessage["context"] : [];
+}
+
+function getWakeReason(value: unknown): ServerChatMessage["wakeReason"] | undefined {
+  return typeof value === "string" ? value as ServerChatMessage["wakeReason"] : undefined;
+}
+
+function getAgentChatProfile(value: unknown): AgentChatProfile | null {
+  const record = getRecord(value);
+  if (!record) return null;
+  return {
+    role: getString(record.role, DEFAULT_AGENT_CHAT_PROFILE.role),
+    systemPrompt: getString(record.systemPrompt, DEFAULT_AGENT_CHAT_PROFILE.systemPrompt),
+    memory: getString(record.memory, DEFAULT_AGENT_CHAT_PROFILE.memory),
+    continuityPacket: getString(record.continuityPacket, DEFAULT_AGENT_CHAT_PROFILE.continuityPacket),
+  };
+}
+
+function resolveAgentChatProfile(...values: unknown[]): AgentChatProfile {
+  for (const value of values) {
+    const profile = getAgentChatProfile(value);
+    if (profile) return profile;
   }
+  return DEFAULT_AGENT_CHAT_PROFILE;
 }

package/src/protocol.ts

@@ -1,5 +1,6 @@
 export type {
   AgentChatProfile,
+  ChatAttachmentRef,
   AgentHeartbeat,
   AgentResultFile,
   AgentComplete,

package/src/ws-transport.ts

@@ -3,26 +3,41 @@
  * Used by both ClawroomClient and ClawroomMachineClient.
  */
 
+export type WsLike = {
+  readyState: number;
+  on: (event: string, listener: (...args: unknown[]) => void) => void;
+  removeAllListeners?: (event?: string) => void;
+  send: (data: string) => void;
+  close: () => void;
+};
+
 export type WsTransportOptions = {
   url: string;
   token: string;
-  onMessage: (msg: any) => void;
+  onMessage: (msg: Record<string, unknown>) => void;
   onConnected: () => void;
   onDisconnected: () => void;
+  createSocket?: (url: string) => WsLike | Promise<WsLike>;
   log?: {
     info?: (message: string) => void;
     warn?: (message: string) => void;
   };
 };
 
+type WsModule = {
+  default: new (url: string) => WsLike;
+};
+
 export class WsTransport {
-  private ws: any = null;
+  private static readonly MAX_SEND_QUEUE = 500;
+  private ws: WsLike | null = null;
   private options: WsTransportOptions;
   private _connected = false;
   private stopped = false;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private reconnectDelay = 1000;
   private failCount = 0;
+  private sendQueue: string[] = [];
 
   static readonly MAX_RECONNECT_DELAY = 60_000;
   static readonly MAX_RECONNECT_FAILS = 10;
@@ -34,35 +49,44 @@ export class WsTransport {
   get connected() { return this._connected; }
 
   async connect() {
-    if (this.stopped) return;
+    this.stopped = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) return;
 
-    let WebSocket: any;
-    try {
-      WebSocket = (await import("ws")).default;
-    } catch {
-      this.options.log?.info?.("ws module not available, skipping WebSocket");
-      return;
+    if (this.ws) {
+      const staleSocket = this.ws;
+      this.ws = null;
+      this.closeSocket(staleSocket);
     }
 
     try {
-      this.ws = new WebSocket(this.options.url);
+      this.ws = await this.createSocket();
+      if (!this.ws) return;
     } catch {
+      this._connected = false;
       this.scheduleReconnect();
       return;
     }
 
-    this.ws.on("open", () => {
+    const socket = this.ws;
+
+    socket.on("open", () => {
       this.reconnectDelay = 1000;
-      this.ws.send(JSON.stringify({ type: "auth", token: this.options.token }));
+      socket.send(JSON.stringify({ type: "auth", token: this.options.token }));
     });
 
-    this.ws.on("message", (raw: any) => {
-      let msg: any;
-      try { msg = JSON.parse(raw.toString()); } catch { return; }
+    socket.on("message", (raw) => {
+      if (!raw || typeof raw !== "object" || !("toString" in raw) || typeof raw.toString !== "function") return;
+      let msg: Record<string, unknown>;
+      try { msg = JSON.parse(raw.toString()) as Record<string, unknown>; } catch { return; }
 
       if (msg.type === "auth_ok") {
         this._connected = true;
         this.failCount = 0;
+        this.flushSendQueue(socket);
         this.options.onConnected();
         return;
       }
@@ -70,7 +94,7 @@ export class WsTransport {
       if (msg.type === "auth_error") {
         this._connected = false;
         this.options.log?.warn?.(`WS auth failed: ${msg.error ?? "unknown"}`);
-        this.ws?.close();
+        socket.close();
         return;
       }
 
@@ -79,37 +103,70 @@ export class WsTransport {
       this.options.onMessage(msg);
     });
 
-    this.ws.on("close", () => {
-      const wasConnected = this._connected;
-      this._connected = false;
-      if (wasConnected) this.options.onDisconnected();
-      if (!this.stopped) this.scheduleReconnect();
+    socket.on("close", () => {
+      this.handleDisconnect(socket);
     });
 
-    this.ws.on("error", () => {
-      this._connected = false;
+    socket.on("error", () => {
+      this.handleDisconnect(socket);
+      try {
+        if (socket.readyState === 0 || socket.readyState === 1) socket.close();
+      } catch {
+        /* ignore close errors */
+      }
     });
   }
 
-  send(msg: any) {
+  send(msg: Record<string, unknown>): boolean {
+    const payload = JSON.stringify(msg);
     if (this._connected && this.ws?.readyState === 1) {
-      this.ws.send(JSON.stringify(msg));
+      this.ws.send(payload);
+      return true;
+    }
+    if (!this.stopped) {
+      if (!this.sendQueue.includes(payload)) {
+        if (this.sendQueue.length >= WsTransport.MAX_SEND_QUEUE) {
+          this.sendQueue.shift();
+          this.options.log?.warn?.(`WS send queue full; dropping oldest queued message`);
+        }
+        this.sendQueue.push(payload);
+      }
+      this.options.log?.warn?.("WS send queued until the socket is ready");
     }
+    return false;
   }
 
   disconnect() {
     this.stopped = true;
     this._connected = false;
     if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null; }
-    if (this.ws) { this.ws.close(); this.ws = null; }
+    this.resetReconnectState();
+    this.sendQueue = [];
+    if (this.ws) {
+      const socket = this.ws;
+      this.ws = null;
+      this.closeSocket(socket);
+    }
+  }
+
+  private handleDisconnect(socket: WsLike) {
+    if (this.ws !== socket) return;
+    this.ws = null;
+    const wasConnected = this._connected;
+    this._connected = false;
+    if (wasConnected) this.options.onDisconnected();
+    if (!this.stopped) this.scheduleReconnect();
   }
 
   private scheduleReconnect() {
     if (this.stopped || this.reconnectTimer) return;
 
     this.failCount++;
-    if (this.failCount > WsTransport.MAX_RECONNECT_FAILS) {
-      this.options.log?.warn?.(`WS reconnect failed ${this.failCount} times, giving up. HTTP polling active.`);
+    const failedAttempts = this.failCount;
+    if (failedAttempts > WsTransport.MAX_RECONNECT_FAILS) {
+      this._connected = false;
+      this.resetReconnectState();
+      this.options.log?.warn?.(`WS reconnect failed ${failedAttempts} times, giving up. HTTP polling active.`);
       return;
     }
 
@@ -120,4 +177,42 @@ export class WsTransport {
     }, Math.min(this.reconnectDelay + jitter, WsTransport.MAX_RECONNECT_DELAY));
     this.reconnectDelay = Math.min(this.reconnectDelay * 2, WsTransport.MAX_RECONNECT_DELAY);
   }
+
+  private async createSocket(): Promise<WsLike | null> {
+    if (this.options.createSocket) {
+      return await this.options.createSocket(this.options.url);
+    }
+
+    let WebSocket: WsModule["default"];
+    try {
+      WebSocket = (await import("ws") as WsModule).default;
+    } catch {
+      this.options.log?.info?.("ws module not available, skipping WebSocket");
+      return null;
+    }
+
+    return new WebSocket(this.options.url);
+  }
+
+  private closeSocket(socket: WsLike) {
+    try {
+      socket.removeAllListeners?.();
+      socket.close();
+    } catch {
+      /* ignore close errors */
+    }
+  }
+
+  private resetReconnectState() {
+    this.reconnectDelay = 1000;
+    this.failCount = 0;
+  }
+
+  private flushSendQueue(socket: WsLike) {
+    while (this.ws === socket && this._connected && socket.readyState === 1 && this.sendQueue.length > 0) {
+      const payload = this.sendQueue.shift();
+      if (!payload) continue;
+      socket.send(payload);
+    }
+  }
 }