@clawroom/openclaw 0.5.1 → 0.5.20

package/node_modules/@clawroom/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawroom/protocol",
-  "version": "0.5.1",
+  "version": "0.5.20",
   "description": "ClawRoom shared types — models, messages, and protocol definitions",
   "type": "module",
   "license": "MIT",

package/node_modules/@clawroom/protocol/src/index.ts

@@ -2,6 +2,11 @@ export interface AgentHeartbeat {
   type: "agent.heartbeat";
 }
 
+export interface AgentWorkRef {
+  workId: string;
+  leaseToken: string;
+}
+
 export interface AgentResultFile {
   filename: string;
   mimeType: string;
@@ -13,19 +18,21 @@ export interface AgentComplete {
   taskId: string;
   output: string;
   attachments?: AgentResultFile[];
+  workRef?: AgentWorkRef;
 }
 
 export interface AgentProgress {
   type: "agent.progress";
   taskId: string;
   message: string;
-  percent?: number;
+  workRef?: AgentWorkRef;
 }
 
 export interface AgentFail {
   type: "agent.fail";
   taskId: string;
   reason: string;
+  workRef?: AgentWorkRef;
 }
 
 export interface AgentChatReply {
@@ -33,6 +40,7 @@ export interface AgentChatReply {
   channelId: string;
   content: string;
   replyTo?: string;
+  workRefs?: AgentWorkRef[];
 }
 
 export interface AgentTyping {
@@ -54,13 +62,62 @@ export interface ServerTask {
   title: string;
   description: string;
   input: string;
-  skillTags: string[];
+  channelId?: string | null;
+  workId: string;
+  leaseToken: string;
+  taskRole?: "root" | "child";
+  assignedAgentId?: string | null;
+  assignedAgentName?: string | null;
+  executionBrief?: ServerTaskExecutionBrief | null;
+  taskDiscussionContext?: ServerTaskDiscussionEntry[];
+}
+
+export interface AgentChatProfile {
+  role: string;
+  systemPrompt: string;
+  memory: string;
+  continuityPacket: string;
+}
+
+export interface ServerTaskExecutionBrief {
+  goal: string;
+  firstActions: string[];
+  blockingUnknowns: string[];
+  nonBlockingUnknowns: string[];
+  doneDefinition: string;
+  nextCheckpoint: string;
+}
+
+export interface ServerTaskDiscussionEntry {
+  id: string;
+  senderType: string;
+  senderName: string;
+  content: string;
+  createdAt: number;
+}
+
+export interface ChatAttachmentRef {
+  id?: string;
+  filename: string;
+  mimeType: string;
+  byteSize?: number;
+  downloadUrl: string;
 }
 
 export interface ServerChatMessage {
+  type: "server.chat";
+  kind: "chat_reply" | "wake";
+  workId: string;
+  leaseToken: string;
   messageId: string;
   channelId: string;
+  taskId?: string | null;
   content: string;
+  attachments?: ChatAttachmentRef[];
+  isMention?: boolean;
+  wakeReason?: "mention" | "dm" | "follow_through" | "goal_drift" | "trigger" | "broadcast" | "routed" | "coordination" | "review";
+  triggerReason?: string;
+  agentProfile: AgentChatProfile;
   context: Array<{
     id: string;
     senderType: string;
@@ -68,6 +125,17 @@ export interface ServerChatMessage {
     content: string;
     createdAt: number;
   }>;
+  replyToMessageId?: string | null;
+  senderName?: string;
+  senderType?: string;
+  createdAt?: number;
+  channelMembers?: Array<{ id: string; name: string; type: string }>;
+  taskTitle?: string | null;
+  taskRole?: "root" | "child";
+  assignedAgentId?: string | null;
+  assignedAgentName?: string | null;
+  executionBrief?: ServerTaskExecutionBrief | null;
+  taskDiscussionContext?: ServerTaskDiscussionEntry[];
 }
 
 export type ServerMessage = ServerTask | ServerChatMessage;

package/node_modules/@clawroom/sdk/package.json

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

package/node_modules/@clawroom/sdk/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/node_modules/@clawroom/sdk/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,