@rethinkingstudio/clawpilot 1.0.0

package/src/relay/gateway-client.ts

@@ -0,0 +1,333 @@
+import { WebSocket } from "ws";
+import { randomUUID, generateKeyPairSync, createPrivateKey, sign, createPublicKey, createHash } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Device identity (Ed25519, persisted across restarts)
+// ---------------------------------------------------------------------------
+
+const IDENTITY_PATH = join(homedir(), ".clawai", "device-identity.json");
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+interface DeviceIdentity {
+  deviceId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+}
+
+function base64UrlEncode(buf: Buffer): string {
+  return buf.toString("base64").replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/g, "");
+}
+
+function rawPublicKeyBytes(publicKeyPem: string): Buffer {
+  const key = createPublicKey(publicKeyPem);
+  const spki = key.export({ type: "spki", format: "der" }) as Buffer;
+  if (
+    spki.length === ED25519_SPKI_PREFIX.length + 32 &&
+    spki.subarray(0, ED25519_SPKI_PREFIX.length).equals(ED25519_SPKI_PREFIX)
+  ) {
+    return spki.subarray(ED25519_SPKI_PREFIX.length);
+  }
+  return spki;
+}
+
+function loadOrCreateDeviceIdentity(): DeviceIdentity {
+  if (existsSync(IDENTITY_PATH)) {
+    try {
+      const stored = JSON.parse(readFileSync(IDENTITY_PATH, "utf8")) as DeviceIdentity & { version?: number };
+      if (stored.deviceId && stored.publicKeyPem && stored.privateKeyPem) {
+        return { deviceId: stored.deviceId, publicKeyPem: stored.publicKeyPem, privateKeyPem: stored.privateKeyPem };
+      }
+    } catch { /* fall through */ }
+  }
+
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const publicKeyPem  = publicKey.export({ type: "spki",  format: "pem" }).toString();
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+  const deviceId = createHash("sha256").update(rawPublicKeyBytes(publicKeyPem)).digest("hex");
+  const identity: DeviceIdentity = { deviceId, publicKeyPem, privateKeyPem };
+
+  mkdirSync(join(homedir(), ".clawai"), { recursive: true });
+  writeFileSync(IDENTITY_PATH, JSON.stringify({ version: 1, ...identity, createdAtMs: Date.now() }, null, 2) + "\n", { mode: 0o600 });
+  return identity;
+}
+
+function buildSignedDevice(identity: DeviceIdentity, opts: {
+  clientId: string;
+  clientMode: string;
+  role: string;
+  scopes: string[];
+  signedAtMs: number;
+  token?: string;
+  nonce?: string;
+}): { id: string; publicKey: string; signature: string; signedAt: number; nonce?: string } {
+  const version = opts.nonce ? "v2" : "v1";
+  const payload = [
+    version,
+    identity.deviceId,
+    opts.clientId,
+    opts.clientMode,
+    opts.role,
+    opts.scopes.join(","),
+    String(opts.signedAtMs),
+    opts.token ?? "",
+    ...(version === "v2" ? [opts.nonce ?? ""] : []),
+  ].join("|");
+
+  const key = createPrivateKey(identity.privateKeyPem);
+  const signature = base64UrlEncode(sign(null, Buffer.from(payload, "utf8"), key));
+
+  return {
+    id: identity.deviceId,
+    publicKey: base64UrlEncode(rawPublicKeyBytes(identity.publicKeyPem)),
+    signature,
+    signedAt: opts.signedAtMs,
+    nonce: opts.nonce,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Wire frame types (OpenClaw protocol v3)
+// ---------------------------------------------------------------------------
+
+interface ReqFrame {
+  type: "req";
+  id: string;
+  method: string;
+  params?: unknown;
+}
+
+interface ResFrame {
+  type: "res";
+  id: string;
+  ok: boolean;
+  payload?: unknown;
+  error?: { message?: string };
+}
+
+interface EvtFrame {
+  type: "event";
+  event: string;
+  payload?: unknown;
+  seq?: number;
+}
+
+const PROTOCOL_VERSION = 3;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface GatewayClientOptions {
+  url: string;
+  token?: string;
+  password?: string;
+  onConnected: () => void;
+  onEvent: (eventName: string, payload: unknown) => void;
+  onDisconnected: (reason: string) => void;
+}
+
+export class OpenClawGatewayClient {
+  private ws: WebSocket | null = null;
+  private pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: unknown) => void }>();
+  private backoffMs = 1000;
+  private stopped = false;
+  private connectNonce: string | null = null;
+  private connectSent = false;
+  private storedDeviceToken: string | null = null;
+  private connectTimer: ReturnType<typeof setTimeout> | null = null;
+  private tickTimer: ReturnType<typeof setInterval> | null = null;
+  private lastTick = 0;
+  private tickIntervalMs = 30_000;
+  private readonly identity: DeviceIdentity;
+
+  constructor(private readonly opts: GatewayClientOptions) {
+    this.identity = loadOrCreateDeviceIdentity();
+  }
+
+  start(): void {
+    if (this.stopped) return;
+    this.ws = new WebSocket(this.opts.url, { maxPayload: 25 * 1024 * 1024 });
+
+    this.ws.on("open", () => {
+      this.connectNonce = null;
+      this.connectSent = false;
+      // Fallback: send connect after 1 s if challenge hasn't arrived
+      this.connectTimer = setTimeout(() => this.sendConnect(), 1000);
+    });
+
+    this.ws.on("message", (data) => {
+      const raw = typeof data === "string" ? data : data.toString();
+      this.handleMessage(raw);
+    });
+
+    this.ws.on("close", (code, reason) => {
+      const reasonText = reason.toString() || `code ${code}`;
+      this.teardown();
+      this.opts.onDisconnected(reasonText);
+      this.scheduleReconnect();
+    });
+
+    this.ws.on("error", (err) => {
+      console.error(`[gateway-client] ws error: ${String(err)}`);
+    });
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.teardown();
+    this.ws?.close();
+    this.ws = null;
+    this.flushPending(new Error("gateway client stopped"));
+  }
+
+  send(method: string, params?: unknown): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("gateway not connected");
+    }
+    const frame: ReqFrame = { type: "req", id: randomUUID(), method, params };
+    this.ws.send(JSON.stringify(frame));
+  }
+
+  async request<T = unknown>(method: string, params?: unknown): Promise<T> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("gateway not connected");
+    }
+    const id = randomUUID();
+    const frame: ReqFrame = { type: "req", id, method, params };
+    const p = new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve: (v) => resolve(v as T), reject });
+    });
+    this.ws.send(JSON.stringify(frame));
+    return p;
+  }
+
+  // -------------------------------------------------------------------------
+
+  private sendConnect(): void {
+    if (this.connectSent) return;
+    this.connectSent = true;
+    if (this.connectTimer) { clearTimeout(this.connectTimer); this.connectTimer = null; }
+
+    const role = "operator";
+    const scopes = ["operator.admin"];
+    const clientId = "gateway-client";
+    const clientMode = "backend";
+    const signedAtMs = Date.now();
+    const nonce = this.connectNonce ?? undefined;
+    const authToken = this.storedDeviceToken ?? this.opts.token;
+
+    const device = buildSignedDevice(this.identity, {
+      clientId, clientMode, role, scopes, signedAtMs,
+      token: authToken ?? undefined,
+      nonce,
+    });
+
+    const params = {
+      minProtocol: PROTOCOL_VERSION,
+      maxProtocol: PROTOCOL_VERSION,
+      role,
+      scopes,
+      caps: ["tool-events"],
+      commands: ["chat.push"],
+      client: {
+        id: clientId,
+        displayName: "ClawAI Relay",
+        version: "1.0.0",
+        platform: process.platform,
+        mode: clientMode,
+      },
+      device,
+      auth: authToken || this.opts.password
+        ? { token: authToken, password: this.opts.password }
+        : undefined,
+    };
+
+    this.request<{ policy?: { tickIntervalMs?: number }; auth?: { deviceToken?: string } }>("connect", params)
+      .then((helloOk) => {
+        const deviceToken = helloOk?.auth?.deviceToken;
+        if (typeof deviceToken === "string") {
+          this.storedDeviceToken = deviceToken;
+        }
+        if (typeof helloOk?.policy?.tickIntervalMs === "number") {
+          this.tickIntervalMs = helloOk.policy.tickIntervalMs;
+        }
+        this.backoffMs = 1000;
+        this.lastTick = Date.now();
+        this.startTickWatch();
+        this.opts.onConnected();
+      })
+      .catch((err: unknown) => {
+        console.error(`[gateway-client] connect failed: ${String(err)}`);
+        this.ws?.close(1008, "connect failed");
+      });
+  }
+
+  private handleMessage(raw: string): void {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let parsed: any;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (typeof parsed?.type !== "string") return;
+
+    if (parsed.type === "event") {
+      const evt = parsed as EvtFrame;
+
+      if (evt.event === "connect.challenge") {
+        const nonce = (evt.payload as { nonce?: unknown } | undefined)?.nonce;
+        if (typeof nonce === "string") {
+          this.connectNonce = nonce;
+          this.sendConnect();
+        }
+        return;
+      }
+
+      if (evt.event === "tick") { this.lastTick = Date.now(); return; }
+
+      this.opts.onEvent(evt.event!, evt.payload ?? null);
+      return;
+    }
+
+    if (parsed.type === "res") {
+      const res = parsed as ResFrame;
+      const pending = this.pending.get(res.id);
+      if (!pending) return;
+      this.pending.delete(res.id);
+      if (res.ok) pending.resolve(res.payload);
+      else pending.reject(new Error(res.error?.message ?? "gateway error"));
+    }
+  }
+
+  private startTickWatch(): void {
+    if (this.tickTimer) clearInterval(this.tickTimer);
+    const interval = Math.max(this.tickIntervalMs, 1000);
+    this.tickTimer = setInterval(() => {
+      if (this.stopped || !this.lastTick) return;
+      if (Date.now() - this.lastTick > this.tickIntervalMs * 2) {
+        this.ws?.close(4000, "tick timeout");
+      }
+    }, interval);
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped) return;
+    const delay = this.backoffMs;
+    this.backoffMs = Math.min(this.backoffMs * 2, 30_000);
+    setTimeout(() => this.start(), delay).unref();
+  }
+
+  private teardown(): void {
+    if (this.connectTimer) { clearTimeout(this.connectTimer); this.connectTimer = null; }
+    if (this.tickTimer) { clearInterval(this.tickTimer); this.tickTimer = null; }
+  }
+
+  private flushPending(err: Error): void {
+    for (const p of this.pending.values()) p.reject(err);
+    this.pending.clear();
+  }
+}

package/src/relay/reconnect.ts

@@ -0,0 +1,37 @@
+export interface ReconnectOptions {
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  onRetry?: (attempt: number, delayMs: number) => void;
+}
+
+/**
+ * Implements exponential backoff: 500ms → 1s → 2s → ... → 30s cap.
+ * Calls `connect` repeatedly until `connect` returns false (permanent failure)
+ * or the returned WebSocket connection stays alive.
+ *
+ * The `connect` callback should return `true` if it attempted a connection
+ * and `false` if it should stop retrying.
+ */
+export async function withReconnect(
+  connect: () => Promise<boolean>,
+  opts: ReconnectOptions = {}
+): Promise<void> {
+  const initialDelay = opts.initialDelayMs ?? 500;
+  const maxDelay = opts.maxDelayMs ?? 30_000;
+  let attempt = 0;
+  let delay = initialDelay;
+
+  while (true) {
+    const shouldRetry = await connect();
+    if (!shouldRetry) break;
+
+    attempt++;
+    opts.onRetry?.(attempt, delay);
+    await sleep(delay);
+    delay = Math.min(delay * 2, maxDelay);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/relay/relay-manager.ts

@@ -0,0 +1,148 @@
+import { WebSocket } from "ws";
+import { OpenClawGatewayClient } from "./gateway-client.js";
+
+// ---------------------------------------------------------------------------
+// Messages: relay client ↔ relay server
+// ---------------------------------------------------------------------------
+
+/** Messages the relay client sends to the relay server. */
+type ToServer =
+  | { type: "gateway_connected" }
+  | { type: "gateway_disconnected"; reason: string }
+  | { type: "event"; event: string; payload: unknown }
+  | { type: "res"; id: string; ok: boolean; payload?: unknown; error?: { message?: string } };
+
+/** Messages the relay server sends to the relay client. */
+interface FromServer {
+  type: "cmd";
+  id?: string;
+  method: string;
+  params: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface RelayManagerOptions {
+  relayServerUrl: string;
+  gatewayId: string;
+  relaySecret: string;
+  gatewayUrl: string;
+  gatewayToken?: string;
+  gatewayPassword?: string;
+  onConnected?: () => void;
+  onDisconnected?: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Connects to the cloud relay server and the local OpenClaw Gateway,
+ * then bridges messages between them indefinitely.
+ *
+ * The gateway client runs for as long as this relay connection is alive.
+ * Returns a Promise that resolves `true` (retry) when the relay server
+ * connection closes.
+ */
+export async function runRelayManager(opts: RelayManagerOptions): Promise<boolean> {
+  const wsUrl = buildRelayUrl(opts.relayServerUrl, opts.gatewayId, opts.relaySecret);
+
+  return new Promise<boolean>((resolve) => {
+    let relayWs: WebSocket;
+    try {
+      relayWs = new WebSocket(wsUrl);
+    } catch (err) {
+      console.error("Failed to create relay WebSocket:", err);
+      resolve(true);
+      return;
+    }
+
+    let gatewayClient: OpenClawGatewayClient | null = null;
+
+    function send(msg: ToServer): void {
+      if (relayWs.readyState === WebSocket.OPEN) {
+        relayWs.send(JSON.stringify(msg));
+      }
+    }
+
+    relayWs.on("open", () => {
+      console.log(`Connected to relay server (gatewayId=${opts.gatewayId})`);
+      opts.onConnected?.();
+
+      // Start the persistent gateway connection as soon as we're connected
+      // to the relay server. Its lifetime is tied to this relay session.
+      gatewayClient = new OpenClawGatewayClient({
+        url: opts.gatewayUrl,
+        token: opts.gatewayToken,
+        password: opts.gatewayPassword,
+
+        onConnected: () => {
+          console.log("Gateway connected.");
+          send({ type: "gateway_connected" });
+        },
+
+        onDisconnected: (reason) => {
+          console.log(`Gateway disconnected: ${reason}`);
+          send({ type: "gateway_disconnected", reason });
+        },
+
+        onEvent: (event, payload) => {
+          send({ type: "event", event, payload });
+        },
+      });
+
+      gatewayClient.start();
+    });
+
+    relayWs.on("message", (raw) => {
+      let msg: FromServer;
+      try {
+        msg = JSON.parse(raw.toString()) as FromServer;
+      } catch {
+        return;
+      }
+
+      if (msg.type !== "cmd" || !msg.method) return;
+
+      const requestId = msg.id;
+      console.log(`[relay] cmd received method=${msg.method} id=${requestId ?? "(no-id)"}`);
+      gatewayClient
+        ?.request(msg.method, msg.params)
+        .then((result) => {
+          console.log(`[relay] cmd ok method=${msg.method} id=${requestId ?? "(no-id)"}`);
+          if (requestId) {
+            send({ type: "res", id: requestId, ok: true, payload: result });
+          }
+        })
+        .catch((err: unknown) => {
+          console.error(`[relay] cmd failed method=${msg.method} id=${requestId ?? "(no-id)"}: ${String(err)}`);
+          if (requestId) {
+            send({ type: "res", id: requestId, ok: false, error: { message: String(err) } });
+          }
+        });
+    });
+
+    relayWs.on("close", (code, reason) => {
+      console.log(`Relay connection closed: ${code} ${reason.toString()}`);
+      opts.onDisconnected?.();
+      gatewayClient?.stop();
+      gatewayClient = null;
+      // Code 4000 = server kicked us because another relay client took over.
+      // Stop retrying so the two instances don't bounce each other forever.
+      resolve(code !== 4000);
+    });
+
+    relayWs.on("error", (err) => {
+      console.error("Relay WebSocket error:", err.message);
+      // close event will follow
+    });
+  });
+}
+
+function buildRelayUrl(serverUrl: string, gatewayId: string, relaySecret: string): string {
+  const base = serverUrl.replace(/\/+$/, "").replace(/^http/, "ws");
+  return `${base}/relay/${gatewayId}?secret=${encodeURIComponent(relaySecret)}`;
+}

package/test-chat.mjs

@@ -0,0 +1,64 @@
+import { WebSocket } from "ws";
+import { randomUUID } from "crypto";
+import { readFileSync } from "fs";
+
+const token = readFileSync("/tmp/test_token.txt", "utf8").trim();
+const url = `ws://localhost:3000/gw/295c6252c69746124af48ebbe7001f11?token=${token}`;
+
+const ws = new WebSocket(url);
+
+ws.on("open", () => {
+  console.log("[ios] connected to relay server");
+
+  ws.send(JSON.stringify({ method: "sessions.reset", params: { key: "main" } }));
+  console.log("[ios] → sessions.reset { key: 'main' }");
+
+  setTimeout(() => {
+    ws.send(JSON.stringify({
+      method: "chat.send",
+      params: {
+        sessionKey: "main",
+        message: "hello, please reply with just one short sentence",
+        idempotencyKey: randomUUID(),
+      },
+    }));
+    console.log("[ios] → chat.send");
+  }, 800);
+});
+
+let lastText = "";
+ws.on("message", (raw) => {
+  const msg = JSON.parse(raw.toString());
+  if (msg.type === "connected") { console.log("[ios] ← gateway online"); return; }
+  if (msg.type === "disconnected") { console.log("[gateway] ← disconnected:", msg.reason); return; }
+  if (msg.type === "event" && msg.event === "chat") {
+    const p = msg.payload;
+    if (p.state === "delta") {
+      const text = p.message?.content?.[0]?.text ?? "";
+      if (text !== lastText) {
+        process.stdout.write("\r[delta] " + text.slice(-80).padEnd(80));
+        lastText = text;
+      }
+    } else if (p.state === "final") {
+      const text = p.message?.content?.[0]?.text ?? "(no text)";
+      console.log("\n\n[FINAL RESPONSE]\n" + text);
+      ws.close();
+      process.exit(0);
+    } else if (p.state === "error") {
+      console.log("\n[ERROR]", p.errorMessage);
+      ws.close();
+      process.exit(1);
+    }
+    return;
+  }
+  if (msg.event !== "health" && msg.event !== "presence") {
+    console.log("[event]", JSON.stringify(msg).slice(0, 120));
+  }
+});
+
+ws.on("error", (e) => console.error("[ws error]", e.message));
+setTimeout(() => {
+  console.log("\n[timeout after 60s]");
+  ws.close();
+  process.exit(1);
+}, 60000);