@clawroom/sdk 0.5.25 → 0.5.27

package/src/machine-client.ts

@@ -1,356 +0,0 @@
-/**
- * ClawRoom Machine Client — machine-level auth with multi-agent support.
- * WebSocket primary for real-time push, HTTP polling as fallback.
- */
-
-import * as os from "node:os";
-import type { AgentChatProfile, AgentWorkRef, ServerChatMessage, ServerTask } from "./protocol.js";
-import { WsTransport } from "./ws-transport.js";
-
-export type ClawroomMachineClientOptions = {
-  endpoint?: string;
-  apiKey: string;
-  hostname?: string;
-  capabilities?: string[];
-  wsUrl?: string;
-  log?: {
-    info?: (message: string, ...args: unknown[]) => void;
-    warn?: (message: string, ...args: unknown[]) => void;
-    error?: (message: string, ...args: unknown[]) => void;
-  };
-};
-
-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: 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;
-  agents?: Array<{ id: string }>;
-};
-
-type MachinePollResponse = {
-  machineId: string;
-  agents: AgentWork[];
-};
-
-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 recentChatIds = new Map<string, number>();
-
-  constructor(options: ClawroomMachineClientOptions) {
-    this.options = options;
-  }
-
-  private get baseUrl(): string {
-    return this.options.endpoint ?? "http://localhost:3000/api/machines";
-  }
-
-  private get wsUrl(): string {
-    if (this.options.wsUrl) return this.options.wsUrl;
-    return this.baseUrl.replace(/\/api\/machines$/, "").replace(/^http/, "ws") + "/api/ws";
-  }
-
-  private async httpRequest(method: string, path: string, body?: unknown): Promise<unknown> {
-    const url = `${this.baseUrl}${path}`;
-    const res = await fetch(url, {
-      method,
-      headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.options.apiKey}` },
-      body: body ? JSON.stringify(body) : undefined,
-    });
-    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
-    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 }>, workRef?: AgentWorkRef) {
-    await this.httpRequest("POST", "/complete", { agentId, taskId, output, attachments, workRef });
-  }
-
-  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, 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 | 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 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 || this.pollInFlight) return;
-    this.pollInFlight = true;
-    try {
-      const result = (await this.httpRequest("POST", "/poll", {})) as MachinePollResponse;
-      for (const agent of result.agents) {
-        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) {
-          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,
-      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.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);
-
-    sendHeartbeat().catch((err) => this.options.log?.warn?.(`[machine] initial heartbeat failed: ${err}`));
-
-    // WebSocket transport
-    this.wsTransport = new WsTransport({
-      url: this.wsUrl,
-      token: this.options.apiKey,
-      log: { info: (m) => this.options.log?.info?.(m), warn: (m) => this.options.log?.warn?.(m) },
-      onConnected: () => {
-        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 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: 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);
-          }
-        }
-        const taskAgentId = getOptionalString(msg.agentId);
-        if (msg.type === "task" && taskAgentId && this.taskHandler) {
-          this.taskHandler(taskAgentId, (msg.task as AgentWork["task"] | undefined) ?? null);
-        }
-      },
-    });
-    this.wsTransport.connect();
-
-    // Keep HTTP polling active even when WS is up.
-    // Machine WS chat delivery is best-effort; polling is the durable delivery path.
-    this.pollTimer = setInterval(async () => {
-      await this.pollOnce();
-    }, 10_000);
-
-    void this.pollOnce();
-  }
-
-  disconnect() {
-    this._stopped = true;
-    this._connected = false;
-    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,22 +0,0 @@
-export type {
-  AgentChatProfile,
-  ChatAttachmentRef,
-  AgentHeartbeat,
-  AgentResultFile,
-  AgentComplete,
-  AgentProgress,
-  AgentFail,
-  AgentChatReply,
-  AgentTyping,
-  AgentMessage,
-  ServerTask,
-  ServerChatMessage,
-  ServerMessage,
-  RuntimeDef,
-} from "@clawroom/protocol";
-
-export {
-  RUNTIMES,
-  BRIDGE_MANAGED_RUNTIME_IDS,
-  RUNTIME_MAP,
-} from "@clawroom/protocol";

package/src/ws-transport.ts

@@ -1,218 +0,0 @@
-/**
- * Shared WebSocket transport with auto-reconnect and fallback support.
- * 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: 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 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;
-
-  constructor(options: WsTransportOptions) {
-    this.options = options;
-  }
-
-  get connected() { return this._connected; }
-
-  async connect() {
-    this.stopped = false;
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-    if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1)) return;
-
-    if (this.ws) {
-      const staleSocket = this.ws;
-      this.ws = null;
-      this.closeSocket(staleSocket);
-    }
-
-    try {
-      this.ws = await this.createSocket();
-      if (!this.ws) return;
-    } catch {
-      this._connected = false;
-      this.scheduleReconnect();
-      return;
-    }
-
-    const socket = this.ws;
-
-    socket.on("open", () => {
-      this.reconnectDelay = 1000;
-      socket.send(JSON.stringify({ type: "auth", token: this.options.token }));
-    });
-
-    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;
-      }
-
-      if (msg.type === "auth_error") {
-        this._connected = false;
-        this.options.log?.warn?.(`WS auth failed: ${msg.error ?? "unknown"}`);
-        socket.close();
-        return;
-      }
-
-      if (msg.type === "pong") return;
-
-      this.options.onMessage(msg);
-    });
-
-    socket.on("close", () => {
-      this.handleDisconnect(socket);
-    });
-
-    socket.on("error", () => {
-      this.handleDisconnect(socket);
-      try {
-        if (socket.readyState === 0 || socket.readyState === 1) socket.close();
-      } catch {
-        /* ignore close errors */
-      }
-    });
-  }
-
-  send(msg: Record<string, unknown>): boolean {
-    const payload = JSON.stringify(msg);
-    if (this._connected && this.ws?.readyState === 1) {
-      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; }
-    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++;
-    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;
-    }
-
-    const jitter = Math.random() * 3000;
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.connect();
-    }, 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);
-    }
-  }
-}