@clawroom/sdk 0.5.1 → 0.5.19

package/package.json

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

package/src/client.ts

@@ -1,5 +1,8 @@
 import type {
+  AgentChatProfile,
+  AgentResultFile,
   AgentMessage,
+  AgentWorkRef,
   ServerTask,
   ServerChatMessage,
 } from "./protocol.js";
@@ -8,9 +11,18 @@ import { WsTransport } from "./ws-transport.js";
 const DEFAULT_ENDPOINT = "https://clawroom.site9.ai/api/agents";
 const HEARTBEAT_INTERVAL_MS = 30_000;
 const POLL_INTERVAL_MS = 10_000;
+const DEFAULT_AGENT_CHAT_PROFILE: AgentChatProfile = {
+  role: "No role defined",
+  systemPrompt: "No system prompt configured",
+  memory: "No memory recorded yet",
+  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;
@@ -26,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.
@@ -33,12 +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;
@@ -50,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,
@@ -64,21 +108,48 @@ 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)) {
-          for (const cb of this.chatCallbacks) cb(msg.messages);
+          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);
+          }
+        }
+        const message = getRecord(msg.message);
+        if (msg.type === "message" && message) {
+          const agentProfile = resolveAgentChatProfile(msg.agentProfile, message.agentProfile);
+          const delivered = [{
+            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.workId ?? m.messageId));
+          if (fresh.length > 0) {
+            for (const cb of this.chatCallbacks) cb(fresh);
+          }
         }
       },
     });
     this.wsTransport.connect();
 
-    // HTTP poll fallback — only when WS is down
+    // Keep HTTP polling active even when WS is up.
+    // WS is the fast path; polling is the durable delivery path.
     this.stopPolling();
     this.pollTimer = setInterval(() => {
-      if (this.wsTransport?.connected) return;
       void this.pollTick();
     }, POLL_INTERVAL_MS);
+
+    void this.pollTick();
   }
 
   disconnect(): void {
@@ -87,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 });
+  }
+
+  async sendChatReply(channelId: string, content: string, replyTo?: string, workRefs?: AgentWorkRef[]): Promise<void> {
+    await this.send({ type: "agent.chat.reply", channelId, content, replyTo, workRefs });
   }
 
-  send(message: AgentMessage): void {
-    this.sendViaHttp(message).catch(() => {});
+  async sendTyping(channelId: string): Promise<void> {
+    await this.send({ type: "agent.typing", channelId });
   }
 
-  onTask(cb: TaskCallback): void { this.taskCallbacks.push(cb); }
-  onChatMessage(cb: ChatCallback): void { this.chatCallbacks.push(cb); }
+  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 ─────────────────────────────────────────
 
@@ -114,67 +255,176 @@ 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) {
-        this.options.log?.info?.(`[clawroom] received ${res.chat.length} chat mention(s)`);
-        for (const cb of this.chatCallbacks) cb(res.chat);
+        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);
+        }
       }
     } 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;
     }
   }
 
-  protected async httpRequest(method: string, path: string, body: unknown): Promise<any> {
+  protected async httpRequest(method: string, path: string, body: unknown): Promise<unknown> {
     const res = await fetch(`${this.httpBase}${path}`, {
       method,
       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 {
+    void status;
+    void text;
+  }
+
+  private rememberChat(messageId?: string): boolean {
+    if (!messageId) return false;
+    if (this.recentChatIds.has(messageId)) return false;
+    this.recentChatIds.add(messageId);
+    if (this.recentChatIds.size > 1000) {
+      const oldest = this.recentChatIds.values().next().value;
+      if (oldest) this.recentChatIds.delete(oldest);
+    }
+    return true;
+  }
+
+  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 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;
+}
 
-  protected onHttpError(_status: number, _text: string): void {}
+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

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

package/src/machine-client.ts

@@ -4,6 +4,7 @@
  */
 
 import * as os from "node:os";
+import type { AgentChatProfile, AgentWorkRef, ServerChatMessage, ServerTask } from "./protocol.js";
 import { WsTransport } from "./ws-transport.js";
 
 export type ClawroomMachineClientOptions = {
@@ -19,12 +20,32 @@ 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;
-  chat: Array<{ messageId: string; channelId: string; content: string; isMention: boolean; context: unknown[] }> | null;
+  task: ServerTask | null;
+  chat: ServerChatMessage[] | null;
+};
+
+const DEFAULT_AGENT_CHAT_PROFILE: AgentChatProfile = {
+  role: "No role defined",
+  systemPrompt: "No system prompt configured",
+  memory: "No memory recorded yet",
+  continuityPacket: "No continuity packet available yet",
 };
+const MAX_RECENT_CHAT_IDS = 1000;
 
 type MachineHeartbeatResponse = {
   machineId: string;
@@ -40,12 +61,15 @@ 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;
+  private disconnectHandler: (() => void) | null = null;
   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) {
@@ -69,91 +93,147 @@ 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; }
   onAgentChat(handler: (agentId: string, messages: NonNullable<AgentWork["chat"]>) => void) { this.chatHandler = handler; }
+  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 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 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;
+      this.options.log?.info?.("[machine] connected");
+      this.connectHandler?.(machineId);
+    }
+  }
+
+  private markDisconnected() {
+    if (this._connected) {
+      this._connected = false;
+      this.options.log?.warn?.("[machine] disconnected");
+      this.disconnectHandler?.();
     }
   }
 
   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);
+          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));
-        if (!this._connected) { this._connected = true; this.options.log?.info?.("[machine] connected"); }
-      } catch {
-        if (this._connected) { this._connected = false; this.options.log?.warn?.("[machine] disconnected"); }
+        this.markConnected(result.machineId);
+      } 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._connected = true;
-        this.syncAgentSubscriptions((data.agents ?? []).map((agent) => agent.id));
-        this.options.log?.info?.("[machine] connected");
-      })
-      .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({
@@ -161,29 +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)) {
-            this.chatHandler(targetAgentId, [{
+          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);
           }
         }
-        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);
         }
       },
     });
@@ -201,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,4 +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);
+    }
+  }
 }