@clawroom/openclaw 0.5.0 → 0.5.19

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

@@ -0,0 +1,17 @@
+{
+  "name": "@clawroom/protocol",
+  "version": "0.5.19",
+  "description": "ClawRoom shared types — models, messages, and protocol definitions",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawroom/clawroom.git"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

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

@@ -0,0 +1,170 @@
+export interface AgentHeartbeat {
+  type: "agent.heartbeat";
+}
+
+export interface AgentWorkRef {
+  workId: string;
+  leaseToken: string;
+}
+
+export interface AgentResultFile {
+  filename: string;
+  mimeType: string;
+  data: string;
+}
+
+export interface AgentComplete {
+  type: "agent.complete";
+  taskId: string;
+  output: string;
+  attachments?: AgentResultFile[];
+  workRef?: AgentWorkRef;
+}
+
+export interface AgentProgress {
+  type: "agent.progress";
+  taskId: string;
+  message: string;
+  workRef?: AgentWorkRef;
+}
+
+export interface AgentFail {
+  type: "agent.fail";
+  taskId: string;
+  reason: string;
+  workRef?: AgentWorkRef;
+}
+
+export interface AgentChatReply {
+  type: "agent.chat.reply";
+  channelId: string;
+  content: string;
+  replyTo?: string;
+  workRefs?: AgentWorkRef[];
+}
+
+export interface AgentTyping {
+  type: "agent.typing";
+  channelId: string;
+}
+
+export type AgentMessage =
+  | AgentHeartbeat
+  | AgentComplete
+  | AgentProgress
+  | AgentFail
+  | AgentChatReply
+  | AgentTyping;
+
+export interface ServerTask {
+  type: "server.task";
+  taskId: string;
+  title: string;
+  description: string;
+  input: 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;
+    senderName: string;
+    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;
+
+/**
+ * Runtime definitions — shared between bridge, server, and UI.
+ *
+ * bridgeManaged = true:  executed by bridge daemon (spawns CLI process, messages via /api/bridge/poll)
+ * bridgeManaged = false: executed by something else (e.g. OpenClaw plugin, messages via /api/machines/poll)
+ */
+export interface RuntimeDef {
+  id: string;
+  displayName: string;
+  /** CLI binary name to detect on PATH (empty = not detectable) */
+  binary: string;
+  /** Whether the bridge daemon spawns and manages a CLI process for this runtime */
+  bridgeManaged: boolean;
+  /** Badge color for UI */
+  badgeColor: string;
+}
+
+export const RUNTIMES: RuntimeDef[] = [
+  { id: "claude-code", displayName: "Claude Code", binary: "claude", bridgeManaged: true, badgeColor: "bg-[#7c5cbf] text-white" },
+  { id: "codex", displayName: "Codex", binary: "codex", bridgeManaged: true, badgeColor: "bg-[#2ea043] text-white" },
+  { id: "qwen-code", displayName: "Qwen Code", binary: "qwen", bridgeManaged: true, badgeColor: "bg-[#1a73e8] text-white" },
+  { id: "kimi", displayName: "Kimi", binary: "kimi", bridgeManaged: true, badgeColor: "bg-[#ff6b35] text-white" },
+  { id: "openclaw", displayName: "OpenClaw", binary: "", bridgeManaged: false, badgeColor: "bg-[var(--color-border)] text-[var(--color-text-secondary)]" },
+];
+
+/** Bridge-managed runtimes: server skips dequeue in /api/machines/poll (they use /api/bridge/poll instead) */
+export const BRIDGE_MANAGED_RUNTIME_IDS = new Set(RUNTIMES.filter((r) => r.bridgeManaged).map((r) => r.id));
+export const RUNTIME_MAP = new Map(RUNTIMES.map((r) => [r.id, r]));

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

@@ -0,0 +1,25 @@
+{
+  "name": "@clawroom/sdk",
+  "version": "0.5.19",
+  "description": "ClawRoom SDK — polling client and protocol types for connecting any agent to ClawRoom",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawroom/clawroom.git"
+  },
+  "keywords": [
+    "clawroom",
+    "sdk",
+    "agent",
+    "workspace"
+  ],
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@clawroom/protocol": "^0.5.1"
+  }
+}

package/node_modules/@clawroom/sdk/src/client.ts

@@ -0,0 +1,430 @@
+import type {
+  AgentChatProfile,
+  AgentResultFile,
+  AgentMessage,
+  AgentWorkRef,
+  ServerTask,
+  ServerChatMessage,
+} from "./protocol.js";
+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;
+  token: string;
+  deviceId: string;
+  skills: string[];
+  kind?: string;
+  wsUrl?: string;
+  log?: {
+    info?: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+    error?: (message: string, ...args: unknown[]) => void;
+  };
+};
+
+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.
+ */
+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;
+    this.httpBase = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+  }
+
+  private get wsUrl(): string {
+    if (this.options.wsUrl) return this.options.wsUrl;
+    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,
+      log: { info: (m) => this.options.log?.info?.(m), warn: (m) => this.options.log?.warn?.(m) },
+      onConnected: () => { this.options.log?.info?.("[clawroom] WebSocket connected"); },
+      onDisconnected: () => { this.options.log?.info?.("[clawroom] WebSocket disconnected"); },
+      onMessage: (msg) => {
+        if (msg.type === "task" && 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.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();
+
+    // 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(() => {
+      void this.pollTick();
+    }, POLL_INTERVAL_MS);
+
+    void this.pollTick();
+  }
+
+  disconnect(): void {
+    this.stopped = true;
+    this.stopHeartbeat();
+    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 });
+  }
+
+  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 ─────────────────────────────────────────
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.stopped) void this.register();
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = null; }
+  }
+
+  private stopPolling(): void {
+    if (this.pollTimer) { clearInterval(this.pollTimer); this.pollTimer = null; }
+  }
+
+  protected async register(): Promise<void> {
+    if (this.heartbeatInFlight) return;
+    this.heartbeatInFlight = true;
+    try {
+      const response = await this.httpRequest("POST", "/heartbeat", {
+        deviceId: this.options.deviceId,
+        skills: this.options.skills,
+        kind: this.options.kind ?? "openclaw",
+      }) as AgentHeartbeatResponse;
+      this.onPollSuccess(response.agentId);
+    } catch (err) {
+      this.options.log?.warn?.(`[clawroom] heartbeat error: ${err}`);
+      if (!this.wsTransport?.connected) {
+        this.onPollError(err);
+      }
+    } finally {
+      this.heartbeatInFlight = false;
+    }
+  }
+
+  protected async pollTick(): Promise<void> {
+    if (this.stopped || this.pollInFlight) return;
+    this.pollInFlight = true;
+    try {
+      const res = await this.httpRequest("POST", "/poll", {}) as AgentPollResponse;
+      this.onPollSuccess(res?.agentId);
+      if (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.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 {
+    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, 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,
+        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<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) {
+      this.onHttpError(res.status, text);
+      throw new Error(`HTTP ${res.status}: ${text}`);
+    }
+    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;
+}
+
+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

@@ -0,0 +1,22 @@
+export { ClawroomClient } from "./client.js";
+export type { ClawroomClientOptions } from "./client.js";
+export { ClawroomMachineClient } from "./machine-client.js";
+export type { ClawroomMachineClientOptions } from "./machine-client.js";
+export { WsTransport } from "./ws-transport.js";
+export type { WsTransportOptions } from "./ws-transport.js";
+
+export type {
+  AgentChatProfile,
+  ChatAttachmentRef,
+  AgentMessage,
+  AgentHeartbeat,
+  AgentComplete,
+  AgentProgress,
+  AgentResultFile,
+  AgentFail,
+  AgentChatReply,
+  AgentTyping,
+  ServerMessage,
+  ServerTask,
+  ServerChatMessage,
+} from "./protocol.js";