@clawroom/sdk 0.5.1 → 0.5.2

package/package.json

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

package/src/client.ts

@@ -1,4 +1,5 @@
 import type {
+  AgentChatProfile,
   AgentMessage,
   ServerTask,
   ServerChatMessage,
@@ -8,6 +9,12 @@ 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",
+  focus: "No focus items",
+};
 
 export type TaskCallback = (task: ServerTask) => void;
 export type ChatCallback = (messages: ServerChatMessage[]) => void;
@@ -39,6 +46,7 @@ export class ClawroomClient {
   protected taskCallbacks: TaskCallback[] = [];
   protected chatCallbacks: ChatCallback[] = [];
   private wsTransport: WsTransport | null = null;
+  private recentChatIds = new Set<string>();
 
   constructor(options: ClawroomClientOptions) {
     this.options = options;
@@ -67,18 +75,40 @@ export class ClawroomClient {
           for (const cb of this.taskCallbacks) cb(msg.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.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 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,
+            agentProfile,
+          }] as ServerChatMessage[];
+          const fresh = delivered.filter((m) => this.rememberChat(m.messageId));
+          if (fresh.length > 0) {
+            for (const cb of this.chatCallbacks) cb(fresh);
+            this.ackChatBestEffort(fresh.map((m) => m.messageId));
+          }
         }
       },
     });
     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 {
@@ -137,8 +167,12 @@ export class ClawroomClient {
         for (const cb of this.taskCallbacks) cb(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.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}`);
@@ -162,7 +196,7 @@ export class ClawroomClient {
     }
   }
 
-  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}` },
@@ -177,4 +211,27 @@ export class ClawroomClient {
   }
 
   protected onHttpError(_status: number, _text: string): void {}
+
+  private rememberChat(messageId?: string): boolean {
+    if (!messageId) return true;
+    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 ackChatBestEffort(messageIds: string[]): void {
+    void this.ackChat(messageIds).catch((err) => {
+      this.options.log?.warn?.(`[clawroom] chat ack error: ${err}`);
+    });
+  }
+
+  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 });
+  }
 }

package/src/index.ts

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

package/src/machine-client.ts

@@ -4,6 +4,7 @@
  */
 
 import * as os from "node:os";
+import type { AgentChatProfile, ServerChatMessage } from "./protocol.js";
 import { WsTransport } from "./ws-transport.js";
 
 export type ClawroomMachineClientOptions = {
@@ -23,7 +24,14 @@ 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;
+  chat: ServerChatMessage[] | null;
+};
+
+const DEFAULT_AGENT_CHAT_PROFILE: AgentChatProfile = {
+  role: "No role defined",
+  systemPrompt: "No system prompt configured",
+  memory: "No memory recorded yet",
+  focus: "No focus items",
 };
 
 type MachineHeartbeatResponse = {
@@ -42,6 +50,8 @@ export class ClawroomMachineClient {
   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 connectHandler: ((machineId: string) => void) | null = null;
+  private disconnectHandler: (() => void) | null = null;
   private _connected = false;
   private _stopped = false;
   private wsTransport: WsTransport | null = null;
@@ -74,6 +84,8 @@ export class ClawroomMachineClient {
 
   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 });
@@ -91,6 +103,12 @@ export class ClawroomMachineClient {
     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 });
+  }
+
   get connected() { return this._connected; }
   get stopped() { return this._stopped; }
 
@@ -105,6 +123,12 @@ export class ClawroomMachineClient {
     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) {
@@ -113,6 +137,22 @@ export class ClawroomMachineClient {
     }
   }
 
+  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;
     try {
@@ -122,7 +162,10 @@ export class ClawroomMachineClient {
         if (agent.task && this.taskHandler) this.taskHandler(agent.agentId, agent.task);
         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);
+          if (freshMessages.length > 0) {
+            this.chatHandler(agent.agentId, freshMessages);
+            this.ackAgentChatBestEffort(agent.agentId, freshMessages.map((message) => message.messageId));
+          }
         }
       }
     } catch (err) {
@@ -140,18 +183,17 @@ export class ClawroomMachineClient {
       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"); }
+        this.markConnected(result.machineId);
       } catch {
-        if (this._connected) { this._connected = false; this.options.log?.warn?.("[machine] disconnected"); }
+        this.markDisconnected();
       }
     }, 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");
+        this.markConnected(data.machineId);
       })
       .catch((err) => this.options.log?.warn?.(`[machine] initial heartbeat failed: ${err}`));
 
@@ -173,13 +215,17 @@ export class ClawroomMachineClient {
           const targetAgentId = msg.agentId ?? m?.agentId;
           const messageId = m?.id ?? msg.messageId ?? "";
           if (m && targetAgentId && this.chatHandler && this.rememberChat(messageId)) {
-            this.chatHandler(targetAgentId, [{
+            const agentProfile = msg.agentProfile ?? m.agentProfile ?? DEFAULT_AGENT_CHAT_PROFILE;
+            const messages = [{
               messageId,
               channelId: m.channelId ?? "",
               content: m.content ?? "",
               isMention: msg.isMention ?? false,
               context: msg.context ?? [],
-            }]);
+              agentProfile,
+            }];
+            this.chatHandler(targetAgentId, messages);
+            this.ackAgentChatBestEffort(targetAgentId, messages.map((message) => message.messageId));
           }
         }
         if (msg.type === "task" && msg.agentId && this.taskHandler) {

package/src/protocol.ts

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