ocuclaw 0.1.0

package/dist/gateway/openclaw-client.js

@@ -0,0 +1,1570 @@
+import { EventEmitter } from "node:events";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import WebSocket from "ws";
+
+// --- Constants ---
+
+const DEVICE_KEY_FILE = "ocuclaw-device-key.json";
+const DEVICE_TOKEN_FILE = "ocuclaw-device-token.json";
+
+const CLIENT_ID = "gateway-client";
+const CLIENT_VERSION = "0.1.0";
+const CLIENT_MODE = "backend";
+const ROLE = "operator";
+const SCOPES = [
+  "operator.read",
+  "operator.write",
+  "operator.approvals",
+  "operator.admin",
+];
+const PROTOCOL_VERSION = 3;
+const HISTORY_ACTIVITY_POLL_INTERVAL_MS = 500;
+const HISTORY_ACTIVITY_POLL_LIMIT = 40;
+
+const THINKING_SUMMARY_KEYS = [
+  "summary",
+  "thinkingSummary",
+  "reasoningSummary",
+  "intentLabel",
+];
+const THINKING_DETAIL_KEYS = [
+  "thinking",
+  "reasoning",
+  "thinkingText",
+  "analysis",
+];
+
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+function normalizeLogger(logger) {
+  if (!logger || typeof logger !== "object") {
+    return {
+      info: console.log.bind(console),
+      warn: console.warn.bind(console),
+      error: console.error.bind(console),
+      debug: console.debug.bind(console),
+    };
+  }
+  return {
+    info:
+      typeof logger.info === "function"
+        ? logger.info.bind(logger)
+        : typeof logger.log === "function"
+          ? logger.log.bind(logger)
+          : console.log.bind(console),
+    warn:
+      typeof logger.warn === "function"
+        ? logger.warn.bind(logger)
+        : console.warn.bind(console),
+    error:
+      typeof logger.error === "function"
+        ? logger.error.bind(logger)
+        : console.error.bind(console),
+    debug:
+      typeof logger.debug === "function"
+        ? logger.debug.bind(logger)
+        : typeof logger.info === "function"
+          ? logger.info.bind(logger)
+          : console.debug.bind(console),
+  };
+}
+
+function pickTrimmedString(...values) {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (trimmed) return trimmed;
+  }
+  return "";
+}
+
+function normalizeStateDir(stateDir) {
+  if (typeof stateDir !== "string") return null;
+  const trimmed = stateDir.trim();
+  return trimmed ? trimmed : null;
+}
+
+function resolvePersistencePaths(stateDir) {
+  const resolvedStateDir = normalizeStateDir(stateDir);
+  if (!resolvedStateDir) return null;
+  return {
+    stateDir: resolvedStateDir,
+    deviceKeyPath: path.join(resolvedStateDir, DEVICE_KEY_FILE),
+    deviceTokenPath: path.join(resolvedStateDir, DEVICE_TOKEN_FILE),
+  };
+}
+
+function writeJsonFile(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {
+    // best-effort
+  }
+}
+
+// --- Base64url helpers ---
+
+function base64UrlEncode(buf) {
+  return buf
+    .toString("base64")
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/g, "");
+}
+
+// --- Device identity ---
+
+/**
+ * Extract raw 32-byte Ed25519 public key from SPKI DER.
+ * Strips the standard 12-byte SPKI prefix for Ed25519 keys.
+ */
+function derivePublicKeyRaw(publicKeyPem) {
+  const key = crypto.createPublicKey(publicKeyPem);
+  const spki = key.export({ type: "spki", format: "der" });
+  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;
+}
+
+/**
+ * SHA-256 hex hash of the raw 32-byte public key.
+ */
+function fingerprintPublicKey(publicKeyPem) {
+  const raw = derivePublicKeyRaw(publicKeyPem);
+  return crypto.createHash("sha256").update(raw).digest("hex");
+}
+
+/**
+ * Generate a new Ed25519 keypair.
+ */
+function generateIdentity() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+  const deviceId = fingerprintPublicKey(publicKeyPem);
+  return { deviceId, publicKeyPem, privateKeyPem };
+}
+
+/**
+ * Load device identity from disk, or generate and persist a new one.
+ */
+function loadOrCreateDeviceIdentity(persistencePaths, logger) {
+  const deviceKeyPath = persistencePaths && persistencePaths.deviceKeyPath;
+  // Try loading existing key
+  try {
+    if (deviceKeyPath && fs.existsSync(deviceKeyPath)) {
+      const raw = fs.readFileSync(deviceKeyPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (
+        parsed &&
+        parsed.version === 1 &&
+        typeof parsed.deviceId === "string" &&
+        typeof parsed.publicKeyPem === "string" &&
+        typeof parsed.privateKeyPem === "string"
+      ) {
+        // Verify deviceId matches public key
+        const derivedId = fingerprintPublicKey(parsed.publicKeyPem);
+        if (derivedId && derivedId !== parsed.deviceId) {
+          // Fix stored deviceId
+          const updated = { ...parsed, deviceId: derivedId };
+          writeJsonFile(deviceKeyPath, updated);
+          logger.info(
+            `[openclaw] Loaded device identity (fixed ID): ${derivedId.slice(0, 12)}...`
+          );
+          return {
+            deviceId: derivedId,
+            publicKeyPem: parsed.publicKeyPem,
+            privateKeyPem: parsed.privateKeyPem,
+          };
+        }
+        logger.info(
+          `[openclaw] Loaded device identity: ${parsed.deviceId.slice(0, 12)}...`
+        );
+        return {
+          deviceId: parsed.deviceId,
+          publicKeyPem: parsed.publicKeyPem,
+          privateKeyPem: parsed.privateKeyPem,
+        };
+      }
+    }
+  } catch {
+    // Fall through to regenerate
+  }
+
+  // Generate new identity
+  const identity = generateIdentity();
+  if (!deviceKeyPath) {
+    logger.info(
+      `[openclaw] Generated in-memory device identity: ${identity.deviceId.slice(0, 12)}...`
+    );
+    return identity;
+  }
+  const stored = {
+    version: 1,
+    deviceId: identity.deviceId,
+    publicKeyPem: identity.publicKeyPem,
+    privateKeyPem: identity.privateKeyPem,
+    createdAtMs: Date.now(),
+  };
+  writeJsonFile(deviceKeyPath, stored);
+  logger.info(
+    `[openclaw] Generated new device identity: ${identity.deviceId.slice(0, 12)}...`
+  );
+  return identity;
+}
+
+// --- Device token cache ---
+
+/**
+ * Load cached device token from disk.
+ * Returns token string or null.
+ */
+function loadDeviceToken(deviceId, persistencePaths) {
+  const deviceTokenPath = persistencePaths && persistencePaths.deviceTokenPath;
+  try {
+    if (!deviceTokenPath || !fs.existsSync(deviceTokenPath)) return null;
+    const raw = fs.readFileSync(deviceTokenPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      parsed.version === 1 &&
+      parsed.deviceId === deviceId &&
+      typeof parsed.token === "string"
+    ) {
+      return parsed.token;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store device token to disk.
+ */
+function storeDeviceToken(deviceId, token, role, scopes, persistencePaths) {
+  const deviceTokenPath = persistencePaths && persistencePaths.deviceTokenPath;
+  if (!deviceTokenPath) return;
+  const data = {
+    version: 1,
+    deviceId,
+    token,
+    role,
+    scopes: scopes || [],
+    updatedAtMs: Date.now(),
+  };
+  writeJsonFile(deviceTokenPath, data);
+}
+
+/**
+ * Clear cached device token.
+ */
+function clearDeviceToken(persistencePaths) {
+  const deviceTokenPath = persistencePaths && persistencePaths.deviceTokenPath;
+  try {
+    if (deviceTokenPath && fs.existsSync(deviceTokenPath)) {
+      fs.unlinkSync(deviceTokenPath);
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+// --- Auth payload ---
+
+/**
+ * Build the pipe-delimited device auth payload string.
+ * Format: v2|{deviceId}|{clientId}|{clientMode}|{role}|{scopes}|{signedAtMs}|{token}|{nonce}
+ */
+function buildDeviceAuthPayload(params) {
+  const version = params.nonce ? "v2" : "v1";
+  const scopes = params.scopes.join(",");
+  const token = params.token || "";
+  const parts = [
+    version,
+    params.deviceId,
+    params.clientId,
+    params.clientMode,
+    params.role,
+    scopes,
+    String(params.signedAtMs),
+    token,
+  ];
+  if (version === "v2") {
+    parts.push(params.nonce || "");
+  }
+  return parts.join("|");
+}
+
+/**
+ * Sign a payload string with Ed25519 private key, return base64url signature.
+ */
+function signPayload(privateKeyPem, payload) {
+  const key = crypto.createPrivateKey(privateKeyPem);
+  const sig = crypto.sign(null, Buffer.from(payload, "utf8"), key);
+  return base64UrlEncode(sig);
+}
+
+/**
+ * Get the raw public key as base64url from PEM.
+ */
+function publicKeyRawBase64Url(publicKeyPem) {
+  return base64UrlEncode(derivePublicKeyRaw(publicKeyPem));
+}
+
+function isObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNullishToken(value) {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim().toLowerCase();
+  return (
+    normalized === "null" ||
+    normalized === "undefined" ||
+    normalized === "(null)" ||
+    normalized === "(undefined)" ||
+    normalized === "none"
+  );
+}
+
+function pickStringPathFromArgs(args) {
+  if (!isObject(args)) return null;
+  const keys = [
+    "path",
+    "filePath",
+    "file_path",
+    "filepath",
+    "file",
+    "target",
+    "outputPath",
+    "output_path",
+    "output",
+    "destination",
+    "dest",
+  ];
+  for (const key of keys) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim()) {
+      const trimmed = value.trim();
+      if (!isNullishToken(trimmed)) {
+        return trimmed;
+      }
+    }
+  }
+  return null;
+}
+
+function pickFirstString(obj, keys) {
+  const entry = pickFirstStringEntry(obj, keys);
+  return entry ? entry.value : null;
+}
+
+function pickFirstStringEntry(obj, keys) {
+  if (!isObject(obj)) return null;
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === "string" && value.trim()) {
+      return { key, value: value.trim() };
+    }
+  }
+  return null;
+}
+
+function normalizeThinkingText(raw) {
+  if (typeof raw !== "string") return null;
+  // Match ActivityStatus iOS app behavior: strip bold markers and trim boundaries only.
+  const cleaned = raw
+    .replace(/\*\*/g, "")
+    .trim();
+  return cleaned || null;
+}
+
+function extractFirstBoldThinkingSegment(raw) {
+  if (typeof raw !== "string") return null;
+  const match = raw.match(/\*\*([\s\S]+?)\*\*/);
+  if (!match) return null;
+  return normalizeThinkingText(match[1]);
+}
+
+function normalizeThinkingSummarySource(rawSource) {
+  if (typeof rawSource !== "string") return null;
+  const normalized = rawSource.trim().toLowerCase();
+  if (
+    normalized === "summary" ||
+    normalized === "bold" ||
+    normalized === "detail" ||
+    normalized === "generic"
+  ) {
+    return normalized;
+  }
+  return null;
+}
+
+function selectThinkingDisplayLabel({
+  summaryText,
+  boldLabelCandidate,
+  detailText,
+  preferredSource,
+}) {
+  const candidates = [
+    { source: "summary", text: summaryText },
+    { source: "bold", text: boldLabelCandidate },
+    { source: "detail", text: detailText },
+  ];
+  if (preferredSource) {
+    const preferred = candidates.find((candidate) => (
+      candidate.source === preferredSource &&
+      candidate.text
+    ));
+    if (preferred) return preferred;
+  }
+  return candidates.find((candidate) => candidate.text) || null;
+}
+
+function buildThinkingDebugRawPayload(raw) {
+  if (!isObject(raw)) return null;
+  const snapshot = {};
+  const keys = [
+    "type",
+    ...THINKING_SUMMARY_KEYS,
+    ...THINKING_DETAIL_KEYS,
+    "thinkingSignature",
+  ];
+  for (const key of keys) {
+    const value = raw[key];
+    if (typeof value === "string" && value.trim()) {
+      snapshot[key] = value.trim();
+    } else if (key === "type" && value != null) {
+      snapshot[key] = String(value);
+    }
+  }
+  return snapshot;
+}
+
+function parseThinkingSignatureId(rawSignature) {
+  if (!rawSignature) return null;
+  if (typeof rawSignature === "string") {
+    try {
+      const parsed = JSON.parse(rawSignature);
+      if (parsed && typeof parsed.id === "string" && parsed.id.trim()) {
+        return parsed.id.trim();
+      }
+    } catch {
+      return null;
+    }
+    return null;
+  }
+  if (
+    isObject(rawSignature) &&
+    typeof rawSignature.id === "string" &&
+    rawSignature.id.trim()
+  ) {
+    return rawSignature.id.trim();
+  }
+  return null;
+}
+
+function extractThinkingPayload(raw) {
+  if (!isObject(raw)) return null;
+  const summaryEntry = pickFirstStringEntry(raw, THINKING_SUMMARY_KEYS);
+  const detailEntry = pickFirstStringEntry(raw, THINKING_DETAIL_KEYS);
+  const summaryText = normalizeThinkingText(summaryEntry ? summaryEntry.value : null);
+  const detailText = normalizeThinkingText(detailEntry ? detailEntry.value : null);
+  const boldLabelCandidate = extractFirstBoldThinkingSegment(detailEntry ? detailEntry.value : null);
+  const explicitSource = normalizeThinkingSummarySource(
+    pickFirstString(raw, ["thinkingSummarySource", "labelSource"])
+  );
+  const selectedLabel = selectThinkingDisplayLabel({
+    summaryText,
+    boldLabelCandidate,
+    detailText,
+    preferredSource: explicitSource,
+  });
+  if (!selectedLabel) return null;
+  const label = selectedLabel.text;
+  const thinkingSummarySource = selectedLabel.source;
+  const labelEntry = thinkingSummarySource === "summary" ? summaryEntry : detailEntry;
+  return {
+    label,
+    detail: detailText || label,
+    signatureId: parseThinkingSignatureId(raw.thinkingSignature),
+    summaryKey: summaryEntry ? summaryEntry.key : null,
+    detailKey: detailEntry ? detailEntry.key : null,
+    summaryText,
+    detailText,
+    labelSource: thinkingSummarySource,
+    thinkingSummarySource,
+    labelKey: labelEntry ? labelEntry.key : null,
+    labelRaw: labelEntry ? labelEntry.value : null,
+    boldLabelCandidate,
+  };
+}
+
+function extractHistoryTimestampMs(rawMessage) {
+  if (!isObject(rawMessage)) return null;
+  const ts = rawMessage.timestamp;
+  if (Number.isFinite(ts)) return Math.floor(ts);
+  if (typeof ts === "string" && ts.trim()) {
+    const parsed = Number(ts);
+    if (Number.isFinite(parsed)) return Math.floor(parsed);
+  }
+  return null;
+}
+
+function normalizeRunId(rawRunId) {
+  if (typeof rawRunId !== "string") return null;
+  const trimmed = rawRunId.trim();
+  return trimmed || null;
+}
+
+function normalizeSessionKey(rawSessionKey) {
+  if (typeof rawSessionKey !== "string") return null;
+  const trimmed = rawSessionKey.trim();
+  return trimmed || null;
+}
+
+function hashThinkingKey(seed) {
+  return crypto.createHash("sha1").update(seed).digest("hex").slice(0, 16);
+}
+
+// --- OpenClaw Gateway Client ---
+
+class OpenClawClient extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this._logger = normalizeLogger(opts.logger);
+    this._gatewayUrl = pickTrimmedString(opts.gatewayUrl);
+    this._gatewayToken = pickTrimmedString(opts.gatewayToken);
+    this._persistencePaths = resolvePersistencePaths(opts.stateDir);
+    this._ws = null;
+    this._stopped = false;
+    this._pending = new Map(); // id -> { resolve, reject, expectFinal }
+    this._identity = null;
+    this._connectNonce = null;
+    this._connectSent = false;
+    this._connectTimer = null;
+    this._tickIntervalMs = 30000;
+    this._deviceToken = null; // cached from hello-ok
+
+    // --- Reconnection (step 7) ---
+    this._backoffMs = 1000;
+    this._reconnectTimer = null;
+
+    // --- Tick watch (step 7) ---
+    this._lastTick = null;
+    this._tickWatchTimer = null;
+
+    // --- Agent run state (steps 4-5) ---
+    this._activeRunId = null;
+    this._activeRunSessionKey = null;
+    this._activeRunStartedAtMs = null;
+    this._activeRunGeneration = 0;
+    this._runTextBuffer = ""; // buffered assistant deltas for current run
+
+    // --- Agent identity (step 6) ---
+    this._agentIdentity = null;
+
+    // --- Sequence tracking (step 8) ---
+    this._lastSeq = null;
+    this._gapDuringRun = false; // set if gap detected while run active
+
+    // --- History hydration (step 9) ---
+    this._historyResolved = false;
+    this._eventQueue = []; // queued agent events until history resolves
+    this._historyActivityPollTimer = null;
+    this._historyActivityPollInFlightGeneration = null;
+    this._seenThinkingSummaryIds = new Set();
+  }
+
+  setLogger(logger) {
+    this._logger = normalizeLogger(logger);
+  }
+
+  /**
+   * Begin connecting to the gateway (non-blocking).
+   */
+  start() {
+    if (this._stopped) return;
+
+    // Load or create device identity (only on first start)
+    if (!this._identity) {
+      this._identity = loadOrCreateDeviceIdentity(
+        this._persistencePaths,
+        this._logger,
+      );
+
+      // Load cached device token
+      this._deviceToken = loadDeviceToken(
+        this._identity.deviceId,
+        this._persistencePaths,
+      );
+      if (this._deviceToken) {
+        this._logger.info("[openclaw] Loaded cached device token");
+      }
+    }
+
+    this._connect();
+  }
+
+  /**
+   * Disconnect and stop.
+   */
+  stop() {
+    this._stopped = true;
+    if (this._connectTimer) {
+      clearTimeout(this._connectTimer);
+      this._connectTimer = null;
+    }
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    this._invalidateActiveRun();
+    this._stopTickWatch();
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+    this._flushPendingErrors(new Error("client stopped"));
+    this.emit("status", "stopped");
+  }
+
+  /**
+   * Send a request to the gateway. Returns a promise that resolves with the response payload.
+   * @param {string} method
+   * @param {object} [params]
+   * @param {{ expectFinal?: boolean }} [opts] - If expectFinal is true, skip intermediate
+   *   acks (status: "accepted") and resolve only on the final response.
+   */
+  request(method, params, opts) {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error("gateway not connected"));
+    }
+    const id = crypto.randomUUID();
+    const frame = { type: "req", id, method, params };
+    const expectFinal = opts && opts.expectFinal === true;
+    const promise = new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject, expectFinal });
+    });
+    const raw = JSON.stringify(frame);
+    this.emit("protocol", { direction: "out", frame });
+    this._ws.send(raw);
+    return promise;
+  }
+
+  // --- Public: messaging (step 4) ---
+
+  /**
+   * Send a user message to the OpenClaw agent.
+   * Fire-and-forget: sends the request, streaming events arrive via event handlers.
+   * @param {string} text - Message text
+   * @param {string} [sessionKey="main"] - Session key
+   * @param {object|null} [attachment] - Optional image attachment payload
+   */
+  sendMessage(text, sessionKey, attachment) {
+    const key = sessionKey || "main";
+    const idempotencyKey = crypto.randomUUID();
+    const params = { message: text, sessionKey: key, idempotencyKey };
+    if (
+      attachment &&
+      typeof attachment === "object" &&
+      typeof attachment.base64Data === "string" &&
+      attachment.base64Data
+    ) {
+      params.attachments = [
+        {
+          type: attachment.kind || "image",
+          mimeType: attachment.mimeType || "image/jpeg",
+          fileName: attachment.name || "image.jpg",
+          content: attachment.base64Data,
+        },
+      ];
+    }
+
+    // Resolve on the initial ack (accepted/queued) for immediate feedback.
+    // Agent streaming events arrive independently via event handlers.
+    return this.request(
+      "agent",
+      params,
+    ).then((result) => {
+      const status = result && result.status;
+      if (result && result.runId) {
+        this._activeRunId = result.runId;
+        this._logger.info(`[openclaw] Agent run accepted: ${result.runId}`);
+      }
+      return result;
+    }).catch((err) => {
+      this._logger.error(`[openclaw] Agent request failed: ${err.message}`);
+      this.emit("error", err);
+      throw err;
+    });
+  }
+
+  // --- Public: agent identity (step 6) ---
+
+  /**
+   * Fetch agent identity from the gateway. Caches the result.
+   * @param {string} [sessionKey] - Optional session key
+   * @returns {Promise<{agentId, name, emoji, avatar}>}
+   */
+  async fetchAgentIdentity(sessionKey) {
+    const params = sessionKey ? { sessionKey } : {};
+    const result = await this.request("agent.identity.get", params);
+    this._agentIdentity = result;
+    this.emit("agentIdentity", result);
+    this._logger.info(`[openclaw] Agent identity: ${result && result.name}`);
+    return result;
+  }
+
+  /**
+   * Resolve an exec approval request.
+   * @param {string} id - Approval request ID
+   * @param {string} decision - "allow-once", "allow-always", or "deny"
+   * @returns {Promise}
+   */
+  resolveApproval(id, decision) {
+    return this.request("exec.approval.resolve", { id, decision });
+  }
+
+  _beginActiveRun(runId, sessionKey) {
+    this._activeRunGeneration += 1;
+    this._activeRunId = normalizeRunId(runId);
+    this._activeRunSessionKey = normalizeSessionKey(sessionKey);
+    this._activeRunStartedAtMs = Date.now();
+    this._runTextBuffer = "";
+    this._gapDuringRun = false;
+    this._seenThinkingSummaryIds.clear();
+    return this._activeRunGeneration;
+  }
+
+  _invalidateActiveRun() {
+    this._activeRunGeneration += 1;
+    this._stopHistoryActivityPolling();
+    this._activeRunId = null;
+    this._activeRunSessionKey = null;
+    this._activeRunStartedAtMs = null;
+    this._runTextBuffer = "";
+    this._gapDuringRun = false;
+    this._seenThinkingSummaryIds.clear();
+    return this._activeRunGeneration;
+  }
+
+  _isActiveRunContextCurrent(context) {
+    if (!context || typeof context !== "object") return false;
+    return (
+      this._activeRunGeneration === context.generation &&
+      normalizeRunId(this._activeRunId) === context.runId &&
+      normalizeSessionKey(this._activeRunSessionKey) === context.sessionKey &&
+      Boolean(normalizeRunId(this._activeRunId)) &&
+      Boolean(normalizeSessionKey(this._activeRunSessionKey))
+    );
+  }
+
+  // --- Internal: connection ---
+
+  _connect() {
+    if (this._stopped) return;
+
+    // Close any existing WebSocket to prevent parallel connections
+    // (e.g., from shutdown handler scheduling reconnect before close fires)
+    if (this._ws) {
+      try { this._ws.close(); } catch { /* ignore */ }
+      this._ws = null;
+    }
+
+    const url = this._gatewayUrl;
+    this.emit("status", "connecting");
+    this._logger.info(`[openclaw] Connecting to ${url}`);
+
+    this._connectNonce = null;
+    this._connectSent = false;
+
+    // Reset per-connection state
+    this._lastSeq = null;
+    this._lastTick = null;
+    this._historyResolved = false;
+    this._eventQueue = [];
+    this._invalidateActiveRun();
+
+    const ws = new WebSocket(url, { maxPayload: 25 * 1024 * 1024 });
+    this._ws = ws;
+
+    ws.on("open", () => {
+      this._logger.info("[openclaw] WebSocket open, waiting for challenge...");
+      // Start a timeout: if we don't receive a challenge, send connect anyway
+      // (mirrors the reference client's queueConnect fallback)
+      this._connectTimer = setTimeout(() => {
+        this._sendConnect();
+      }, 750);
+    });
+
+    ws.on("message", (data) => {
+      this._handleMessage(data.toString());
+    });
+
+    ws.on("close", (code, reason) => {
+      const reasonText = reason ? reason.toString() : "";
+      this._logger.info(`[openclaw] WebSocket closed: ${code} ${reasonText}`);
+      this._ws = null;
+      this._stopTickWatch();
+      this._stopHistoryActivityPolling();
+      this._flushPendingErrors(new Error(`gateway closed (${code}): ${reasonText}`));
+      this.emit("disconnected", { code, reason: reasonText });
+      this.emit("status", "disconnected");
+      // Only schedule reconnect if one isn't already pending
+      // (e.g., shutdown handler may have already scheduled with a specific delay)
+      if (!this._reconnectTimer) {
+        this._scheduleReconnect();
+      }
+    });
+
+    ws.on("error", (err) => {
+      this._logger.error(`[openclaw] WebSocket error: ${err.message}`);
+      if (!this._connectSent) {
+        this.emit("error", err);
+      }
+    });
+  }
+
+  // --- Internal: message handling ---
+
+  _handleMessage(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      this._logger.error(`[openclaw] Failed to parse message: ${err.message}`);
+      return;
+    }
+
+    // Emit protocol event for every incoming frame (step 10)
+    this.emit("protocol", { direction: "in", frame: parsed });
+
+    // Event frames: { type: "event", event: "...", payload: ... }
+    if (parsed.type === "event") {
+      this._handleEvent(parsed);
+      return;
+    }
+
+    // Response frames: { type: "res", id: "...", ok: true/false, payload: ... }
+    if (parsed.type === "res") {
+      const pending = this._pending.get(parsed.id);
+      if (!pending) return;
+
+      // If expectFinal, skip intermediate acks (status: "accepted") (step 4)
+      const payload = parsed.payload;
+      const status = payload && payload.status;
+      if (pending.expectFinal && status === "accepted") {
+        // Track the runId from the ack
+        if (payload.runId) {
+          this._activeRunId = payload.runId;
+          this._logger.info(`[openclaw] Agent run accepted: ${payload.runId}`);
+        }
+        return; // Keep the pending entry, wait for final response
+      }
+
+      this._pending.delete(parsed.id);
+      if (parsed.ok) {
+        pending.resolve(parsed.payload);
+      } else {
+        const errMsg =
+          parsed.error && parsed.error.message ? parsed.error.message : "unknown error";
+        const err = new Error(errMsg);
+        if (parsed.error && typeof parsed.error.code === "string") {
+          err.code = parsed.error.code;
+        }
+        if (parsed.error && parsed.error.data !== undefined) {
+          err.data = parsed.error.data;
+        }
+        // Check for retryable hint (step 7)
+        if (parsed.error && parsed.error.retryable && parsed.error.retryAfterMs) {
+          err.retryAfterMs = parsed.error.retryAfterMs;
+        }
+        pending.reject(err);
+      }
+      return;
+    }
+  }
+
+  // --- Internal: event routing ---
+
+  _handleEvent(evt) {
+    // connect.challenge is handled before sequence tracking
+    if (evt.event === "connect.challenge") {
+      const nonce =
+        evt.payload && typeof evt.payload.nonce === "string" ? evt.payload.nonce : null;
+      if (nonce) {
+        this._logger.info("[openclaw] Received connect.challenge");
+        this._connectNonce = nonce;
+        this._sendConnect();
+      }
+      return;
+    }
+
+    // --- Sequence tracking (step 8) ---
+    const seq = typeof evt.seq === "number" ? evt.seq : null;
+    if (seq !== null) {
+      if (this._lastSeq !== null && seq > this._lastSeq + 1) {
+        const gapInfo = { expected: this._lastSeq + 1, received: seq };
+        this._logger.warn(
+          `[openclaw] Sequence gap: expected ${gapInfo.expected}, received ${gapInfo.received}`
+        );
+        this.emit("gap", gapInfo);
+        // Flag gap during active run for post-run re-fetch (step 8)
+        if (this._activeRunId) {
+          this._gapDuringRun = true;
+        }
+      }
+      this._lastSeq = seq;
+    }
+
+    // --- Tick handling (step 7) ---
+    if (evt.event === "tick") {
+      this._lastTick = Date.now();
+      return;
+    }
+
+    // --- Shutdown handling (step 7) ---
+    if (evt.event === "shutdown") {
+      const payload = evt.payload || {};
+      const restartMs = typeof payload.restartExpectedMs === "number" ? payload.restartExpectedMs : 5000;
+      this._logger.info(`[openclaw] Gateway shutdown, reconnecting in ${restartMs}ms`);
+      this.emit("status", "shutdown");
+      // Schedule reconnect after the expected restart delay
+      this._scheduleReconnect(restartMs);
+      // Close the WS immediately to prevent the close handler from scheduling
+      // a second reconnect with normal backoff (double-reconnect race).
+      if (this._ws) {
+        this._ws.close(1000, "shutdown");
+      }
+      return;
+    }
+
+    // --- Exec approval events ---
+    if (evt.event === "exec.approval.requested") {
+      this.emit("approval", evt.payload);
+      return;
+    }
+
+    if (evt.event === "exec.approval.resolved") {
+      this.emit("approvalResolved", evt.payload);
+      return;
+    }
+
+    // --- Agent events (step 5) ---
+    if (evt.event === "agent") {
+      // If history hasn't resolved yet, queue the event (step 9)
+      if (!this._historyResolved) {
+        this._eventQueue.push(evt);
+        return;
+      }
+      this._handleAgentEvent(evt.payload);
+      return;
+    }
+  }
+
+  // --- Internal: agent streaming (step 5) ---
+
+  /**
+   * Handle an agent event payload.
+   * Buffers assistant text deltas, emits activity/message events.
+   */
+  _handleAgentEvent(payload) {
+    if (!payload) return;
+
+    const { runId, stream, data } = payload;
+    if (!stream || !data) return;
+
+    switch (stream) {
+      case "lifecycle":
+        this._handleLifecycleEvent(runId, data, payload.sessionKey);
+        break;
+      case "assistant":
+        this._handleAssistantEvent(runId, data);
+        break;
+      case "tool":
+        this._handleToolEvent(runId, data);
+        break;
+      case "error":
+        this._logger.error(`[openclaw] Agent error: ${JSON.stringify(data)}`);
+        this.emit("error", new Error(data.message || "agent error"));
+        break;
+      default:
+        break;
+    }
+  }
+
+  _handleLifecycleEvent(runId, data, sessionKey) {
+    switch (data.phase) {
+      case "start":
+        this._beginActiveRun(runId, sessionKey);
+        this._startHistoryActivityPolling();
+        this.emit("activity", {
+          state: "thinking",
+          sessionKey,
+          runId,
+          origin: "lifecycle",
+          phase: "start",
+        });
+        this._logger.info(`[openclaw] Agent run started: ${runId}`);
+        break;
+
+      case "end": {
+        // Assemble full response from buffered text
+        const fullText = this._runTextBuffer;
+        const completedRunId = normalizeRunId(this._activeRunId) || normalizeRunId(runId);
+        const completedSessionKey =
+          normalizeSessionKey(sessionKey) ||
+          normalizeSessionKey(this._activeRunSessionKey) ||
+          null;
+        const gapDuringRun = this._gapDuringRun;
+
+        // Invalidate run state before emitting terminal idle so late history polls
+        // cannot reopen thinking for a completed run.
+        this._invalidateActiveRun();
+
+        this.emit("message", {
+          runId: completedRunId,
+          role: "assistant",
+          content: [{ type: "text", text: fullText }],
+          sessionKey: completedSessionKey,
+        });
+        this.emit("activity", {
+          state: "idle",
+          sessionKey: completedSessionKey,
+          runId: completedRunId,
+          origin: "lifecycle",
+          phase: "end",
+        });
+        this._logger.info(
+          `[openclaw] Agent run ended: ${completedRunId} (${fullText.length} chars)`
+        );
+
+        // If there was a gap during this run, re-fetch history (step 8)
+        if (gapDuringRun) {
+          this._logger.info("[openclaw] Gap detected during run, re-fetching history");
+          this._fetchHistory(completedSessionKey || "main").catch((err) => {
+            this._logger.error(
+              `[openclaw] Post-gap history fetch failed: ${err.message}`
+            );
+          });
+        }
+        break;
+      }
+
+      case "error":
+        this._logger.error(`[openclaw] Agent lifecycle error: ${JSON.stringify(data)}`);
+        {
+          const completedRunId = normalizeRunId(runId) || normalizeRunId(this._activeRunId);
+          const completedSessionKey =
+            normalizeSessionKey(sessionKey) ||
+            normalizeSessionKey(this._activeRunSessionKey) ||
+            null;
+          this._invalidateActiveRun();
+          this.emit("error", new Error(data.message || "agent lifecycle error"));
+          this.emit("activity", {
+            state: "idle",
+            sessionKey: completedSessionKey,
+            runId: completedRunId || null,
+            origin: "lifecycle",
+            phase: "error",
+          });
+        }
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  _handleAssistantEvent(runId, data) {
+    this._emitThinkingActivityFromPayload(
+      runId,
+      this._activeRunSessionKey,
+      data,
+      "assistant_event",
+    );
+
+    // Gateway sends accumulated text (full text so far), not deltas
+    if (typeof data.text === "string") {
+      this._runTextBuffer = data.text;
+      this.emit("streaming", {
+        text: data.text,
+        sessionKey: this._activeRunSessionKey,
+        runId: runId || this._activeRunId || null,
+      });
+    }
+  }
+
+  _handleToolEvent(runId, data) {
+    if (data.phase !== "start" || !data.name) return;
+
+    const args = isObject(data.args) ? data.args : null;
+    const pathFromData =
+      typeof data.path === "string" && data.path.trim() && !isNullishToken(data.path)
+        ? data.path.trim()
+        : null;
+    const pathFromArgs = pickStringPathFromArgs(args);
+    const path = pathFromData || pathFromArgs || null;
+
+    const activity = {
+      state: "thinking",
+      tool: data.name,
+      sessionKey: this._activeRunSessionKey,
+      runId: runId || this._activeRunId || null,
+      origin: "tool",
+      phase: "start",
+    };
+
+    if (args) activity.args = args;
+    if (path) activity.path = path;
+    if (typeof data.toolCallId === "string" && data.toolCallId.trim()) {
+      activity.activityId = data.toolCallId.trim();
+    }
+    if (Number.isFinite(data.seq)) {
+      activity.seq = Math.floor(data.seq);
+    }
+
+    this.emit("activity", activity);
+  }
+
+  _startHistoryActivityPolling() {
+    this._stopHistoryActivityPolling();
+    if (!this._activeRunId || !this._activeRunSessionKey) return;
+
+    const poll = () => {
+      this._pollHistoryActivity().catch((err) => {
+        if (!err || !err.message || !/gateway not connected/i.test(err.message)) {
+          this._logger.warn(
+            `[openclaw] Thinking-summary poll failed: ${
+              err && err.message ? err.message : String(err)
+            }`
+          );
+        }
+      });
+    };
+
+    poll();
+    this._historyActivityPollTimer = setInterval(
+      poll,
+      HISTORY_ACTIVITY_POLL_INTERVAL_MS,
+    );
+    if (this._historyActivityPollTimer.unref) {
+      this._historyActivityPollTimer.unref();
+    }
+  }
+
+  _stopHistoryActivityPolling() {
+    if (this._historyActivityPollTimer) {
+      clearInterval(this._historyActivityPollTimer);
+      this._historyActivityPollTimer = null;
+    }
+    this._historyActivityPollInFlightGeneration = null;
+  }
+
+  async _pollHistoryActivity() {
+    if (!this._historyResolved) return;
+    const runContext = {
+      generation: this._activeRunGeneration,
+      runId: normalizeRunId(this._activeRunId),
+      sessionKey: normalizeSessionKey(this._activeRunSessionKey),
+    };
+    if (!runContext.runId || !runContext.sessionKey) return;
+    if (this._historyActivityPollInFlightGeneration === runContext.generation) return;
+
+    this._historyActivityPollInFlightGeneration = runContext.generation;
+    try {
+      const result = await this.request("chat.history", {
+        sessionKey: runContext.sessionKey,
+        limit: HISTORY_ACTIVITY_POLL_LIMIT,
+      });
+      if (!this._isActiveRunContextCurrent(runContext)) {
+        this._logger.debug(
+          `[openclaw] Dropped stale thinking-summary poll for run ${runContext.runId}`
+        );
+        return;
+      }
+      const responseSessionKey =
+        normalizeSessionKey(result && result.sessionKey) || runContext.sessionKey;
+      if (responseSessionKey !== runContext.sessionKey) {
+        this._logger.debug(
+          `[openclaw] Dropped thinking-summary poll with mismatched session ${String(
+            result && result.sessionKey
+          )}`
+        );
+        return;
+      }
+      const messages = result && Array.isArray(result.messages) ? result.messages : [];
+      this._emitThinkingFromHistory(
+        messages,
+        responseSessionKey,
+        runContext,
+      );
+    } finally {
+      if (this._historyActivityPollInFlightGeneration === runContext.generation) {
+        this._historyActivityPollInFlightGeneration = null;
+      }
+    }
+  }
+
+  _emitThinkingFromHistory(messages, sessionKey, runContext) {
+    if (!Array.isArray(messages) || messages.length === 0) return;
+    if (runContext && !this._isActiveRunContextCurrent(runContext)) return;
+    const activeRunId = normalizeRunId(this._activeRunId);
+    const runStartMs = Number.isFinite(this._activeRunStartedAtMs)
+      ? this._activeRunStartedAtMs
+      : null;
+
+    for (const message of messages) {
+      if (!isObject(message)) continue;
+      if (message.role !== "assistant") continue;
+
+      const messageRunId = normalizeRunId(message.runId);
+      if (activeRunId && messageRunId && messageRunId !== activeRunId) continue;
+
+      const messageTs = extractHistoryTimestampMs(message);
+      if (
+        activeRunId &&
+        !messageRunId &&
+        runStartMs !== null &&
+        messageTs !== null &&
+        messageTs < runStartMs - 2000
+      ) {
+        continue;
+      }
+
+      const content = Array.isArray(message.content) ? message.content : [];
+      for (const contentItem of content) {
+        if (!isObject(contentItem)) continue;
+        if (contentItem.type !== "thinking") continue;
+        this._emitThinkingActivityFromPayload(
+          messageRunId || activeRunId,
+          sessionKey,
+          contentItem,
+          "history",
+        );
+      }
+    }
+  }
+
+  _emitThinkingActivityFromPayload(runId, sessionKey, rawPayload, source = "unknown") {
+    const extracted = extractThinkingPayload(rawPayload);
+    if (!extracted) return;
+
+    const normalizedRunId = normalizeRunId(runId) || normalizeRunId(this._activeRunId);
+    const dedupeSeed = extracted.signatureId || hashThinkingKey(extracted.label);
+    const dedupeKey = `${normalizedRunId || "run"}:${dedupeSeed}`;
+    if (this._seenThinkingSummaryIds.has(dedupeKey)) return;
+    this._seenThinkingSummaryIds.add(dedupeKey);
+
+    this.emit("thinkingDebug", {
+      sessionKey: sessionKey || this._activeRunSessionKey || null,
+      runId: normalizedRunId || null,
+      source,
+      signatureId: extracted.signatureId || null,
+      rawKeys: isObject(rawPayload) ? Object.keys(rawPayload).sort() : [],
+      rawPayload: buildThinkingDebugRawPayload(rawPayload),
+      summaryKey: extracted.summaryKey,
+      detailKey: extracted.detailKey,
+      labelKey: extracted.labelKey,
+      labelRaw: extracted.labelRaw,
+      labelSource: extracted.labelSource,
+      thinkingSummarySource: extracted.thinkingSummarySource,
+      normalizedSummary: extracted.summaryText || null,
+      normalizedDetail: extracted.detailText || null,
+      label: extracted.label,
+      detail: extracted.detail,
+      boldLabelCandidate: extracted.boldLabelCandidate || null,
+      boldLabelMatchesCurrentLabel: extracted.boldLabelCandidate
+        ? extracted.boldLabelCandidate === extracted.label
+        : null,
+    });
+
+    this.emit("activity", {
+      state: "thinking",
+      sessionKey: sessionKey || this._activeRunSessionKey || null,
+      runId: normalizedRunId || null,
+      origin: "thinking",
+      phase: "update",
+      summary: extracted.label,
+      thinking: extracted.detail,
+      thinkingSummarySource: extracted.thinkingSummarySource,
+    });
+  }
+
+  // --- Internal: handshake ---
+
+  _sendConnect() {
+    if (this._connectSent) return;
+    this._connectSent = true;
+
+    if (this._connectTimer) {
+      clearTimeout(this._connectTimer);
+      this._connectTimer = null;
+    }
+
+    const identity = this._identity;
+    if (!identity) {
+      this.emit("error", new Error("no device identity"));
+      return;
+    }
+
+    // Choose auth token: prefer cached device token, fall back to gateway token
+    const authToken = this._deviceToken || this._gatewayToken || undefined;
+    const canFallback = Boolean(this._deviceToken && this._gatewayToken);
+
+    const signedAtMs = Date.now();
+    const nonce = this._connectNonce || undefined;
+
+    // Build device auth payload
+    const payload = buildDeviceAuthPayload({
+      deviceId: identity.deviceId,
+      clientId: CLIENT_ID,
+      clientMode: CLIENT_MODE,
+      role: ROLE,
+      scopes: SCOPES,
+      signedAtMs,
+      token: authToken || null,
+      nonce,
+    });
+
+    // Sign with Ed25519 private key
+    const signature = signPayload(identity.privateKeyPem, payload);
+
+    // Build connect request params
+    const params = {
+      minProtocol: PROTOCOL_VERSION,
+      maxProtocol: PROTOCOL_VERSION,
+      client: {
+        id: CLIENT_ID,
+        version: CLIENT_VERSION,
+        platform: process.platform,
+        mode: CLIENT_MODE,
+      },
+      role: ROLE,
+      scopes: SCOPES,
+      caps: ["tool-events"],
+      auth: authToken ? { token: authToken } : undefined,
+      device: {
+        id: identity.deviceId,
+        publicKey: publicKeyRawBase64Url(identity.publicKeyPem),
+        signature,
+        signedAt: signedAtMs,
+        nonce,
+      },
+    };
+
+    this._logger.info("[openclaw] Sending connect request...");
+
+    this.request("connect", params)
+      .then((helloOk) => {
+        this._logger.info(
+          `[openclaw] Connected! protocol=${helloOk.protocol}, ` +
+            `tick=${helloOk.policy && helloOk.policy.tickIntervalMs}ms`
+        );
+
+        // Reset backoff on successful connect (step 7)
+        this._backoffMs = 1000;
+
+        // Cache tick interval
+        if (helloOk.policy && typeof helloOk.policy.tickIntervalMs === "number") {
+          this._tickIntervalMs = helloOk.policy.tickIntervalMs;
+        }
+
+        // Start tick watch (step 7)
+        this._lastTick = Date.now();
+        this._startTickWatch();
+
+        // Cache device token if provided
+        if (helloOk.auth && helloOk.auth.deviceToken) {
+          this._deviceToken = helloOk.auth.deviceToken;
+          storeDeviceToken(
+            identity.deviceId,
+            helloOk.auth.deviceToken,
+            helloOk.auth.role || ROLE,
+            helloOk.auth.scopes || SCOPES,
+            this._persistencePaths,
+          );
+          this._logger.info("[openclaw] Device token cached");
+        }
+
+        this.emit("connected", {
+          protocol: helloOk.protocol,
+          tickIntervalMs: this._tickIntervalMs,
+        });
+        this.emit("status", "connected");
+
+        // Post-connect: fetch agent identity (step 6) and chat history (step 9)
+        this._postConnect().catch((err) => {
+          this._logger.error(`[openclaw] Post-connect setup failed: ${err.message}`);
+          this.emit("error", err);
+        });
+      })
+      .catch((err) => {
+        this._logger.error(`[openclaw] Connect failed: ${err.message}`);
+
+        // If we were using a cached device token and have a fallback, clear and retry
+        if (canFallback) {
+          this._logger.info(
+            "[openclaw] Clearing cached device token, will use gateway token on next connect"
+          );
+          this._deviceToken = null;
+          clearDeviceToken(this._persistencePaths);
+        }
+
+        this.emit("error", err);
+        if (this._ws) {
+          this._ws.close(1008, "connect failed");
+        }
+      });
+  }
+
+  // --- Internal: post-connect setup (steps 6, 9) ---
+
+  async _postConnect() {
+    // Fetch agent identity (step 6) — non-blocking, don't gate on this
+    this.fetchAgentIdentity().catch((err) => {
+      this._logger.error(`[openclaw] Agent identity fetch failed: ${err.message}`);
+    });
+
+    // Fetch chat history (step 9) — blocks agent event processing until done
+    try {
+      await this._fetchHistory("main");
+    } catch (err) {
+      this._logger.error(`[openclaw] Chat history fetch failed: ${err.message}`);
+    }
+
+    // Mark history as resolved and drain queued events
+    this._historyResolved = true;
+    this._drainEventQueue();
+  }
+
+  // --- Internal: chat history (step 9) ---
+
+  /**
+   * Fetch chat history from the gateway.
+   * @param {string} sessionKey
+   */
+  async _fetchHistory(sessionKey) {
+    const result = await this.request("chat.history", {
+      sessionKey,
+      limit: 200,
+    });
+
+    const messages = result && Array.isArray(result.messages) ? result.messages : [];
+    this._logger.info(`[openclaw] Chat history loaded: ${messages.length} messages`);
+
+    this.emit("history", {
+      sessionKey: (result && result.sessionKey) || sessionKey,
+      messages,
+    });
+
+    return result;
+  }
+
+  /**
+   * Drain queued agent events that arrived before history resolved.
+   */
+  _drainEventQueue() {
+    const queue = this._eventQueue;
+    this._eventQueue = [];
+    for (const evt of queue) {
+      this._handleAgentEvent(evt.payload);
+    }
+  }
+
+  // --- Internal: reconnection (step 7) ---
+
+  /**
+   * Schedule a reconnect attempt with exponential backoff.
+   * @param {number} [delayOverride] - Override the backoff delay (e.g., for shutdown events)
+   */
+  _scheduleReconnect(delayOverride) {
+    if (this._stopped) return;
+
+    const delay = typeof delayOverride === "number" ? delayOverride : this._backoffMs;
+
+    // Advance backoff for next time (unless overridden)
+    if (typeof delayOverride !== "number") {
+      this._backoffMs = Math.min(this._backoffMs * 2, 30000);
+    }
+
+    this._logger.info(
+      `[openclaw] Reconnecting in ${delay}ms (backoff: ${this._backoffMs}ms)`
+    );
+
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+    }
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this.start();
+    }, delay);
+    // Don't prevent process exit while waiting to reconnect
+    if (this._reconnectTimer.unref) {
+      this._reconnectTimer.unref();
+    }
+  }
+
+  // --- Internal: tick watch (step 7) ---
+
+  /**
+   * Start watching for stale connections via tick timeout.
+   * If no tick received within 2x tickIntervalMs, close and reconnect.
+   */
+  _startTickWatch() {
+    this._stopTickWatch();
+    const interval = Math.max(this._tickIntervalMs, 1000);
+    this._tickWatchTimer = setInterval(() => {
+      if (this._stopped) return;
+      if (!this._lastTick) return;
+      const elapsed = Date.now() - this._lastTick;
+      if (elapsed > this._tickIntervalMs * 2) {
+        this._logger.warn(
+          `[openclaw] Tick timeout (${elapsed}ms since last tick), closing connection`
+        );
+        if (this._ws) {
+          this._ws.close(4000, "tick timeout");
+        }
+      }
+    }, interval);
+    // Don't prevent process exit
+    if (this._tickWatchTimer.unref) {
+      this._tickWatchTimer.unref();
+    }
+  }
+
+  /**
+   * Stop the tick watch timer.
+   */
+  _stopTickWatch() {
+    if (this._tickWatchTimer) {
+      clearInterval(this._tickWatchTimer);
+      this._tickWatchTimer = null;
+    }
+  }
+
+  // --- Internal: helpers ---
+
+  _flushPendingErrors(err) {
+    for (const [, pending] of this._pending) {
+      pending.reject(err);
+    }
+    this._pending.clear();
+  }
+}
+
+export function createPluginOpenclawClient(opts = {}) {
+  return new OpenClawClient(opts);
+}