@hypercli.com/sdk 2026.3.16 → 2026.3.18

package/dist/gateway.js

@@ -7,6 +7,7 @@
  * Protocol: OpenClaw Gateway v3
  */
 import { getPublicKeyAsync, signAsync, utils as edUtils } from "@noble/ed25519";
+import NodeWebSocket from "ws";
 class GatewayRequestError extends Error {
     gatewayCode;
     details;
@@ -21,8 +22,8 @@ const PROTOCOL_VERSION = 3;
 const DEFAULT_TIMEOUT = 15_000;
 const CHAT_TIMEOUT = 120_000;
 const RECONNECT_CLOSE_CODE = 4008;
-const DEFAULT_CLIENT_ID = "openclaw-control-ui";
-const DEFAULT_CLIENT_MODE = "webchat";
+const DEFAULT_CLIENT_ID = "cli";
+const DEFAULT_CLIENT_MODE = "cli";
 const DEFAULT_CLIENT_VERSION = "@hypercli/sdk";
 const DEFAULT_CAPS = ["tool-events"];
 const CONNECT_TIMER_MS = 750;
@@ -72,6 +73,122 @@ function asRecord(value) {
         ? value
         : null;
 }
+function extractMessageText(message) {
+    if (typeof message === "string") {
+        return message;
+    }
+    const record = asRecord(message);
+    if (!record) {
+        return null;
+    }
+    const content = record.content;
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        const parts = content
+            .map((entry) => {
+            const item = asRecord(entry);
+            if (!item || item.type !== "text" || typeof item.text !== "string" || !item.text) {
+                return null;
+            }
+            return item.text;
+        })
+            .filter((value) => typeof value === "string");
+        if (parts.length > 0) {
+            return parts.join("\n");
+        }
+    }
+    return typeof record.text === "string" ? record.text : null;
+}
+function extractMessageRunId(message) {
+    const record = asRecord(message);
+    if (!record) {
+        return null;
+    }
+    const directRunId = typeof record.runId === "string" ? record.runId.trim() : "";
+    if (directRunId) {
+        return directRunId;
+    }
+    const agentRunId = typeof record.agentRunId === "string" ? record.agentRunId.trim() : "";
+    if (agentRunId) {
+        return agentRunId;
+    }
+    const meta = asRecord(record.meta);
+    const metaRunId = typeof meta?.runId === "string" ? meta.runId.trim() : "";
+    return metaRunId || null;
+}
+function latestHistoryAssistantText(messages, acceptedRunIds) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = asRecord(messages[index]);
+        if (!message) {
+            continue;
+        }
+        const role = typeof message.role === "string" ? message.role.trim().toLowerCase() : "";
+        if (role !== "assistant") {
+            continue;
+        }
+        const messageRunId = extractMessageRunId(message);
+        if (messageRunId && acceptedRunIds.size > 0 && !acceptedRunIds.has(messageRunId)) {
+            continue;
+        }
+        const text = extractMessageText(message)?.trim();
+        if (text) {
+            return text;
+        }
+    }
+    return null;
+}
+function streamDelta(previousText, nextText) {
+    if (!nextText) {
+        return { delta: "", nextText: previousText };
+    }
+    if (previousText && nextText.startsWith(previousText)) {
+        return { delta: nextText.slice(previousText.length), nextText };
+    }
+    if (nextText === previousText) {
+        return { delta: "", nextText: previousText };
+    }
+    return { delta: nextText, nextText };
+}
+function parseAgentSessionKey(sessionKey) {
+    const normalized = (sessionKey ?? "").trim().toLowerCase();
+    if (!normalized) {
+        return null;
+    }
+    const parts = normalized.split(":").filter(Boolean);
+    if (parts.length < 3 || parts[0] !== "agent") {
+        return null;
+    }
+    const agentId = parts[1]?.trim();
+    const rest = parts.slice(2).join(":").trim();
+    if (!agentId || !rest) {
+        return null;
+    }
+    return { agentId, rest };
+}
+function sameSessionKey(left, right) {
+    const normalizedLeft = (left ?? "").trim().toLowerCase();
+    const normalizedRight = (right ?? "").trim().toLowerCase();
+    if (!normalizedLeft || !normalizedRight) {
+        return false;
+    }
+    if (normalizedLeft === normalizedRight) {
+        return true;
+    }
+    const parsedLeft = parseAgentSessionKey(normalizedLeft);
+    const parsedRight = parseAgentSessionKey(normalizedRight);
+    if (parsedLeft && parsedRight) {
+        return parsedLeft.agentId === parsedRight.agentId && parsedLeft.rest === parsedRight.rest;
+    }
+    if (parsedLeft) {
+        return parsedLeft.rest === normalizedRight;
+    }
+    if (parsedRight) {
+        return normalizedLeft === parsedRight.rest;
+    }
+    return false;
+}
 function splitConfigPath(path) {
     return path
         .split(".")
@@ -641,7 +758,12 @@ export class GatewayClient {
         this.caps = Array.isArray(options.caps)
             ? options.caps.map((cap) => cap.trim()).filter(Boolean)
             : [...DEFAULT_CAPS];
-        this.origin = options.origin ?? "https://hypercli.com";
+        // Non-browser SDK clients should not send Origin by default. OpenClaw
+        // treats any Origin header as browser-originated and applies browser
+        // origin checks to the connection.
+        this.origin = typeof options.origin === "string" && options.origin.trim()
+            ? options.origin.trim()
+            : undefined;
         this.defaultTimeout = options.timeout ?? DEFAULT_TIMEOUT;
         this.onHello = options.onHello;
         this.onClose = options.onClose;
@@ -766,7 +888,8 @@ export class GatewayClient {
     openSocket() {
         if (this.closed || this.ws)
             return;
-        if (typeof WebSocket === "undefined") {
+        const useBrowserSocket = "localStorage" in globalThis && typeof WebSocket !== "undefined";
+        if (!useBrowserSocket && typeof NodeWebSocket === "undefined") {
             throw new Error("WebSocket is not available in this environment");
         }
         if (this.reconnectTimer) {
@@ -776,20 +899,38 @@ export class GatewayClient {
         const wsUrl = this.token
             ? `${this.url}${this.url.includes("?") ? "&" : "?"}token=${encodeURIComponent(this.token)}`
             : this.url;
-        const ws = new WebSocket(wsUrl);
+        const ws = useBrowserSocket
+            ? new WebSocket(wsUrl)
+            : new NodeWebSocket(wsUrl, this.origin ? { headers: { Origin: this.origin } } : undefined);
         this.ws = ws;
-        ws.onopen = () => {
+        if (useBrowserSocket) {
+            ws.onopen = () => {
+                this.queueConnect();
+            };
+            ws.onmessage = (event) => {
+                this.handleMessage(String(event.data ?? ""));
+            };
+            ws.onerror = () => {
+                // Close handling covers retries and surfaced errors.
+            };
+            ws.onclose = (event) => {
+                this.handleClose(ws, event.code ?? 1006, String(event.reason ?? ""));
+            };
+            return;
+        }
+        const nodeWs = ws;
+        nodeWs.on("open", () => {
             this.queueConnect();
-        };
-        ws.onmessage = (event) => {
-            this.handleMessage(String(event.data ?? ""));
-        };
-        ws.onerror = () => {
+        });
+        nodeWs.on("message", (data) => {
+            this.handleMessage(typeof data === "string" ? data : data.toString());
+        });
+        nodeWs.on("error", () => {
             // Close handling covers retries and surfaced errors.
-        };
-        ws.onclose = (event) => {
-            this.handleClose(ws, event.code ?? 1006, String(event.reason ?? ""));
-        };
+        });
+        nodeWs.on("close", (code, reason) => {
+            this.handleClose(ws, code ?? 1006, reason?.toString() ?? "");
+        });
     }
     queueConnect() {
         this.connectNonce = null;
@@ -1112,15 +1253,89 @@ export class GatewayClient {
         return normalizeOpenClawConfigSchema(res) ?? { schema: {}, uiHints: {} };
     }
     async configPatch(patch) {
-        await this.rpc("config.patch", { patch });
+        const { hash, baseHash } = await this.rpc("config.get");
+        await this.rpc("config.patch", {
+            raw: JSON.stringify(patch),
+            baseHash: hash ?? baseHash ?? "",
+        });
+    }
+    async configApply(config) {
+        const { hash, baseHash } = await this.rpc("config.get");
+        await this.rpc("config.apply", {
+            raw: JSON.stringify(config),
+            baseHash: hash ?? baseHash ?? "",
+        });
     }
     async configSet(config) {
-        await this.rpc("config.set", { config });
+        const { hash, baseHash } = await this.rpc("config.get");
+        await this.rpc("config.set", {
+            raw: JSON.stringify(config),
+            baseHash: hash ?? baseHash ?? "",
+        });
     }
     async modelsList() {
         const res = await this.rpc("models.list");
         return res?.models ?? res ?? [];
     }
+    async waitReady(timeoutMs = 300_000, options = {}) {
+        const retryIntervalMs = options.retryIntervalMs ?? 5_000;
+        const probe = options.probe ?? "config";
+        const deadline = Date.now() + timeoutMs;
+        let lastError = null;
+        while (!this.closed) {
+            try {
+                if (!this.connected) {
+                    await this.connect();
+                }
+                if (probe === "status") {
+                    return await this.status();
+                }
+                return await this.configGet();
+            }
+            catch (error) {
+                lastError = error;
+                this.close();
+                if (Date.now() >= deadline) {
+                    break;
+                }
+                await new Promise((resolve) => setTimeout(resolve, retryIntervalMs));
+            }
+        }
+        const detail = lastError instanceof Error ? `: ${lastError.message}` : "";
+        throw new Error(`Gateway readiness probe timed out after ${timeoutMs}ms${detail}`);
+    }
+    async channelsStatus(probe = false, timeoutMs) {
+        const params = { probe };
+        if (timeoutMs !== undefined)
+            params.timeoutMs = timeoutMs;
+        return await this.rpc("channels.status", params);
+    }
+    async channelsLogout(channel, accountId) {
+        const params = { channel };
+        if (accountId)
+            params.accountId = accountId;
+        return await this.rpc("channels.logout", params);
+    }
+    async webLoginStart(options = {}) {
+        const params = {};
+        if (options.force)
+            params.force = true;
+        if (options.timeoutMs !== undefined)
+            params.timeoutMs = options.timeoutMs;
+        if (options.verbose)
+            params.verbose = true;
+        if (options.accountId)
+            params.accountId = options.accountId;
+        return await this.rpc("web.login.start", params, 30_000);
+    }
+    async webLoginWait(options = {}) {
+        const params = {};
+        if (options.timeoutMs !== undefined)
+            params.timeoutMs = options.timeoutMs;
+        if (options.accountId)
+            params.accountId = options.accountId;
+        return await this.rpc("web.login.wait", params, CHAT_TIMEOUT);
+    }
     // ---------------------------------------------------------------------------
     // Sessions
     // ---------------------------------------------------------------------------
@@ -1148,6 +1363,7 @@ export class GatewayClient {
     async sendChat(message, sessionKey = "main", agentId, attachments) {
         const params = {
             message,
+            deliver: false,
             sessionKey,
             idempotencyKey: makeId(),
         };
@@ -1167,90 +1383,151 @@ export class GatewayClient {
         if (!this.connected || !this.ws) {
             throw new Error("Not connected");
         }
-        const id = makeId();
-        const req = {
-            type: "req",
-            id,
-            method: "chat.send",
-            params: {
-                message,
-                sessionKey,
-                idempotencyKey: makeId(),
-            },
-        };
-        const events = [];
+        const idempotencyKey = makeId();
+        const acceptedRunIds = new Set([idempotencyKey]);
+        const queuedEvents = [];
         let resolveWait = null;
-        let done = false;
-        let error = null;
-        // Temporary event handler for chat events
+        let streamedDisplayText = false;
+        let lastLegacyText = "";
         const handler = (evt) => {
-            if (evt.event?.startsWith("chat.")) {
-                const payload = evt.payload ?? {};
+            if (evt.event === "chat" || evt.event?.startsWith("chat.")) {
+                queuedEvents.push(evt);
+                const waiter = resolveWait;
+                resolveWait = null;
+                waiter?.();
+            }
+        };
+        this.eventHandlers.add(handler);
+        try {
+            const ack = await this.rpc("chat.send", {
+                message,
+                deliver: false,
+                sessionKey,
+                idempotencyKey,
+            }, CHAT_TIMEOUT);
+            const serverRunId = typeof ack?.runId === "string" ? ack.runId.trim() : "";
+            if (serverRunId) {
+                acceptedRunIds.add(serverRunId);
+            }
+            let deadline = Date.now() + CHAT_TIMEOUT;
+            while (Date.now() < deadline) {
+                if (queuedEvents.length === 0) {
+                    const remainingMs = Math.max(100, Math.min(1000, deadline - Date.now()));
+                    await new Promise((resolve) => {
+                        const timer = setTimeout(() => {
+                            if (resolveWait === release) {
+                                resolveWait = null;
+                            }
+                            resolve();
+                        }, remainingMs);
+                        const release = () => {
+                            clearTimeout(timer);
+                            resolve();
+                        };
+                        resolveWait = release;
+                    });
+                    continue;
+                }
+                const evt = queuedEvents.shift();
+                const payload = asRecord(evt.payload) ?? {};
+                const payloadRunId = typeof payload.runId === "string" ? payload.runId.trim() : "";
+                const payloadSessionKey = typeof payload.sessionKey === "string" ? payload.sessionKey.trim() : "";
+                if (payloadRunId && !acceptedRunIds.has(payloadRunId)) {
+                    continue;
+                }
+                if (payloadSessionKey && !sameSessionKey(payloadSessionKey, sessionKey)) {
+                    continue;
+                }
+                deadline = Date.now() + CHAT_TIMEOUT;
                 if (evt.event === "chat.content") {
-                    events.push({ type: "content", text: payload.text ?? "" });
+                    const text = typeof payload.text === "string" ? payload.text : "";
+                    if (text) {
+                        streamedDisplayText = true;
+                        yield { type: "content", text };
+                    }
+                    continue;
                 }
-                else if (evt.event === "chat.thinking") {
-                    events.push({ type: "thinking", text: payload.text ?? "" });
+                if (evt.event === "chat.thinking") {
+                    yield { type: "thinking", text: typeof payload.text === "string" ? payload.text : "" };
+                    continue;
                 }
-                else if (evt.event === "chat.tool_call") {
-                    events.push({ type: "tool_call", data: payload });
+                if (evt.event === "chat.tool_call") {
+                    yield { type: "tool_call", data: payload };
+                    continue;
                 }
-                else if (evt.event === "chat.tool_result") {
-                    events.push({ type: "tool_result", data: payload });
+                if (evt.event === "chat.tool_result") {
+                    yield { type: "tool_result", data: payload };
+                    continue;
                 }
-                else if (evt.event === "chat.done") {
-                    events.push({ type: "done" });
-                    done = true;
+                if (evt.event === "chat.done") {
+                    yield { type: "done", data: payload };
+                    return;
                 }
-                else if (evt.event === "chat.error") {
-                    events.push({ type: "error", text: payload.message ?? "Unknown error" });
-                    done = true;
+                if (evt.event === "chat.error") {
+                    yield {
+                        type: "error",
+                        text: typeof payload.message === "string" ? payload.message : "Unknown error",
+                        data: payload,
+                    };
+                    return;
                 }
-                resolveWait?.();
-            }
-        };
-        this.eventHandlers.add(handler);
-        // Also listen for the RPC response
-        const timer = setTimeout(() => {
-            this.pending.delete(id);
-            error = new Error("Chat timeout");
-            done = true;
-            resolveWait?.();
-        }, CHAT_TIMEOUT);
-        this.pending.set(id, {
-            resolve: () => {
-                clearTimeout(timer);
-                done = true;
-                resolveWait?.();
-            },
-            reject: (rejection) => {
-                clearTimeout(timer);
-                error = rejection instanceof Error ? rejection : new Error(String(rejection));
-                done = true;
-                resolveWait?.();
-            },
-            timer,
-        });
-        this.ws.send(JSON.stringify(req));
-        try {
-            while (!done || events.length > 0) {
-                if (events.length > 0) {
-                    yield events.shift();
+                if (evt.event !== "chat") {
+                    continue;
                 }
-                else if (!done) {
-                    await new Promise((resolve) => {
-                        resolveWait = resolve;
-                    });
-                    resolveWait = null;
+                const state = typeof payload.state === "string" ? payload.state.trim().toLowerCase() : "";
+                const currentText = extractMessageText(payload.message) ?? "";
+                if (state === "delta") {
+                    const streamed = streamDelta(lastLegacyText, currentText);
+                    lastLegacyText = streamed.nextText;
+                    if (streamed.delta) {
+                        streamedDisplayText = true;
+                        yield { type: "content", text: streamed.delta, data: payload };
+                    }
+                    continue;
+                }
+                if (state === "final") {
+                    if (currentText) {
+                        const streamed = streamDelta(lastLegacyText, currentText);
+                        lastLegacyText = streamed.nextText;
+                        if (streamed.delta) {
+                            streamedDisplayText = true;
+                            yield { type: "content", text: streamed.delta, data: payload };
+                        }
+                        yield { type: "done", data: payload };
+                        return;
+                    }
+                    if (streamedDisplayText || lastLegacyText) {
+                        yield { type: "done", data: payload };
+                        return;
+                    }
+                    const historyText = latestHistoryAssistantText(await this.chatHistory(sessionKey, 20), acceptedRunIds);
+                    if (historyText) {
+                        yield { type: "content", text: historyText, data: payload };
+                    }
+                    yield { type: "done", data: payload };
+                    return;
+                }
+                if (state === "error" || state === "aborted") {
+                    if (currentText) {
+                        const streamed = streamDelta(lastLegacyText, currentText);
+                        lastLegacyText = streamed.nextText;
+                        if (streamed.delta) {
+                            streamedDisplayText = true;
+                            yield { type: "content", text: streamed.delta, data: payload };
+                        }
+                    }
+                    yield {
+                        type: "error",
+                        text: typeof payload.errorMessage === "string" ? payload.errorMessage : state,
+                        data: payload,
+                    };
+                    return;
                 }
             }
-            if (error)
-                throw error;
+            throw new Error("Streaming chat.send timed out");
         }
         finally {
-            clearTimeout(timer);
             this.eventHandlers.delete(handler);
-            this.pending.delete(id);
         }
     }
     // ---------------------------------------------------------------------------