@hypercli.com/sdk 2026.6.26 → 2026.7.31

package/dist/openclaw/gateway.js

@@ -8,6 +8,57 @@
  */
 import { getPublicKeyAsync, signAsync, utils as edUtils } from "@noble/ed25519";
 import NodeWebSocket from "ws";
+export const OPENCLAW_INTERNAL_MAIN_SESSION_KEY = "main";
+export const OPENCLAW_SDK_SESSION_PREFIX = "hcli:";
+export const OPENCLAW_DASHBOARD_SESSION_PREFIX = "dashboard:";
+export function createOpenClawSessionKey(existingSessionKeys = [], prefix = OPENCLAW_SDK_SESSION_PREFIX) {
+    const resolvedPrefix = prefix.trim();
+    const existing = new Set(existingSessionKeys
+        .map((key) => key?.trim())
+        .filter((key) => Boolean(key)));
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const suffix = typeof globalThis.crypto?.randomUUID === "function"
+            ? globalThis.crypto.randomUUID()
+            : `local-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+        const key = `${resolvedPrefix}${suffix}`;
+        if (!existing.has(key))
+            return key;
+    }
+    return `${resolvedPrefix}local-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function createOpenClawSdkSessionKey(existingSessionKeys = []) {
+    return createOpenClawSessionKey(existingSessionKeys, OPENCLAW_SDK_SESSION_PREFIX);
+}
+export function isOpenClawInternalMainSessionKey(sessionKey) {
+    const normalized = (sessionKey ?? "").trim().toLowerCase();
+    if (!normalized)
+        return false;
+    const parsed = parseAgentSessionKey(normalized);
+    return (parsed?.rest ?? normalized) === OPENCLAW_INTERNAL_MAIN_SESSION_KEY;
+}
+export function isOpenClawSdkSessionKey(sessionKey) {
+    const normalized = (sessionKey ?? "").trim().toLowerCase();
+    if (!normalized)
+        return false;
+    const parsed = parseAgentSessionKey(normalized);
+    return (parsed?.rest ?? normalized).startsWith(OPENCLAW_SDK_SESSION_PREFIX);
+}
+export class GatewayChatStreamInterruptedError extends Error {
+    static code = "GATEWAY_CHAT_STREAM_INTERRUPTED";
+    code = GatewayChatStreamInterruptedError.code;
+    reason;
+    expectedSequence;
+    receivedSequence;
+    constructor(reason, sequence) {
+        super(reason === "sequence-gap" && sequence
+            ? `Gateway chat stream interrupted by a sequence gap (expected ${sequence.expected}, received ${sequence.received})`
+            : "Gateway chat stream interrupted by an event without run or session identity");
+        this.name = "GatewayChatStreamInterruptedError";
+        this.reason = reason;
+        this.expectedSequence = sequence?.expected;
+        this.receivedSequence = sequence?.received;
+    }
+}
 class GatewayRequestError extends Error {
     gatewayCode;
     details;
@@ -18,11 +69,23 @@ class GatewayRequestError extends Error {
         this.details = error.details;
     }
 }
-const MIN_PROTOCOL_VERSION = 3;
-const PROTOCOL_VERSION = 4;
-const DEFAULT_TIMEOUT = 15_000;
-const CHAT_TIMEOUT = 120_000;
+export function isOpenClawGatewayMethodUnsupported(error, method) {
+    const record = error && typeof error === "object" ? error : null;
+    const code = typeof record?.gatewayCode === "string" ? record.gatewayCode.trim().toUpperCase() : "";
+    if (["METHOD_NOT_FOUND", "NOT_IMPLEMENTED", "UNIMPLEMENTED", "UNSUPPORTED_METHOD"].includes(code))
+        return true;
+    const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    if (!/unknown method|method not found|not implemented|unsupported method/i.test(message))
+        return false;
+    return !method || message.toLowerCase().includes(method.trim().toLowerCase());
+}
+export const MIN_GATEWAY_VERSION = 3;
+export const MAX_GATEWAY_VERSION = 4;
+const DEFAULT_CONNECTION_TIMEOUT = 30_000;
+const WEB_LOGIN_WAIT_TIMEOUT = 120_000;
+const DEFAULT_AGENT_TIMEOUT = 900_000;
 const SKILLS_MUTATION_TIMEOUT = 300_000;
+const PLUGIN_MUTATION_TIMEOUT = 300_000;
 const RECONNECT_CLOSE_CODE = 4008;
 const DEFAULT_CLIENT_ID = "cli";
 const DEFAULT_CLIENT_MODE = "cli";
@@ -35,6 +98,9 @@ const BACKOFF_MULTIPLIER = 1.7;
 const OPERATOR_ROLE = "operator";
 const OPERATOR_SCOPES = ["operator.admin", "operator.approvals", "operator.pairing"];
 const STORAGE_KEY = "openclaw.device.auth.v1";
+const EPHEMERAL_SESSION_PREFIX = "session-hypercli-ephemeral-";
+const EPHEMERAL_RUN_ID_SUPPRESSION_MS = DEFAULT_AGENT_TIMEOUT + 5 * 60_000;
+const EPHEMERAL_TURN_CLOSE_WAIT_MS = 1_000;
 const CONNECT_ERROR_PAIRING_REQUIRED = "PAIRING_REQUIRED";
 const CONNECT_ERROR_AUTH_TOKEN_MISMATCH = "AUTH_TOKEN_MISMATCH";
 const CONNECT_ERROR_AUTH_RATE_LIMITED = "AUTH_RATE_LIMITED";
@@ -42,13 +108,16 @@ const CONNECT_ERROR_DEVICE_TOKEN_MISMATCH = "AUTH_DEVICE_TOKEN_MISMATCH";
 const VALID_CLIENT_IDS = new Set([
     "webchat-ui",
     "openclaw-control-ui",
+    "openclaw-tui",
     "webchat",
     "cli",
     "gateway-client",
     "openclaw-macos",
     "openclaw-ios",
+    "openclaw-watchos",
     "openclaw-android",
     "node-host",
+    "openclaw-worker",
     "test",
     "fingerprint",
     "openclaw-probe",
@@ -59,6 +128,7 @@ const VALID_CLIENT_MODES = new Set([
     "ui",
     "backend",
     "node",
+    "worker",
     "probe",
     "test",
 ]);
@@ -72,11 +142,94 @@ function makeId() {
         return (char === "x" ? random : (random & 0x3) | 0x8).toString(16);
     });
 }
+function channelConfigPatch(channelId, config, accountId, defaultAccount = false) {
+    if (!accountId)
+        return { channels: { [channelId]: config } };
+    return {
+        channels: {
+            [channelId]: {
+                accounts: { [accountId]: config },
+                ...(defaultAccount ? { defaultAccount: accountId } : {}),
+            },
+        },
+    };
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
         : null;
 }
+function protocolError(code, message, record) {
+    const frameType = typeof record?.type === "string" ? record.type : undefined;
+    const event = typeof record?.event === "string" ? record.event : undefined;
+    const requestId = typeof record?.id === "string" ? record.id : undefined;
+    return {
+        code,
+        message,
+        ...(frameType ? { frameType } : {}),
+        ...(event ? { event } : {}),
+        ...(requestId ? { requestId } : {}),
+    };
+}
+function normalizeGatewayResponseError(value) {
+    if (typeof value === "string" && value.trim()) {
+        return { code: "UNAVAILABLE", message: value.trim() };
+    }
+    const error = asRecord(value);
+    return {
+        code: typeof error?.code === "string" && error.code.trim() ? error.code : "UNAVAILABLE",
+        message: typeof error?.message === "string" && error.message.trim()
+            ? error.message
+            : "gateway request failed",
+        ...(error?.details !== undefined ? { details: error.details } : {}),
+    };
+}
+function decodeGatewayFrame(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: protocolError("INVALID_JSON", "gateway frame is not valid JSON") };
+    }
+    const record = asRecord(value);
+    if (!record) {
+        return { ok: false, error: protocolError("INVALID_FRAME", "gateway frame must be an object") };
+    }
+    if (record.type === "event") {
+        if (typeof record.event !== "string" || !record.event.trim()) {
+            return { ok: false, error: protocolError("INVALID_EVENT", "gateway event requires a non-empty string event", record) };
+        }
+        if (record.seq !== undefined && (!Number.isSafeInteger(record.seq) || record.seq < 0)) {
+            return { ok: false, error: protocolError("INVALID_EVENT", "gateway event seq must be a non-negative safe integer", record) };
+        }
+        return { ok: true, frame: record };
+    }
+    if (record.type === "res") {
+        if (typeof record.id !== "string" || !record.id.trim()) {
+            return { ok: false, error: protocolError("INVALID_RESPONSE", "gateway response requires a non-empty string id", record) };
+        }
+        if (typeof record.ok !== "boolean") {
+            return { ok: false, error: protocolError("INVALID_RESPONSE", "gateway response ok must be a boolean", record) };
+        }
+        if (record.ok) {
+            return { ok: true, frame: { type: "res", id: record.id, ok: true, payload: record.payload } };
+        }
+        return {
+            ok: true,
+            frame: {
+                type: "res",
+                id: record.id,
+                ok: false,
+                error: normalizeGatewayResponseError(record.error),
+            },
+        };
+    }
+    return {
+        ok: false,
+        error: protocolError("INVALID_FRAME", "gateway frame type must be event or res", record),
+    };
+}
 function asContentItems(value) {
     if (!Array.isArray(value)) {
         return [];
@@ -129,7 +282,7 @@ function normalizeToolArgs(value) {
     }
 }
 function stringifyToolResult(value) {
-    if (value == null) {
+    if (value === null || value === undefined) {
         return undefined;
     }
     if (typeof value === "string") {
@@ -144,6 +297,8 @@ function stringifyToolResult(value) {
 }
 function gatewayToolCallId(record) {
     const direct = (typeof record.id === "string" && record.id.trim()) ||
+        (typeof record.call_id === "string" && record.call_id.trim()) ||
+        (typeof record.callId === "string" && record.callId.trim()) ||
         (typeof record.toolCallId === "string" && record.toolCallId.trim()) ||
         (typeof record.tool_call_id === "string" && record.tool_call_id.trim());
     return direct || undefined;
@@ -171,7 +326,7 @@ function mergeGatewayToolResult(toolCalls, result) {
             index = cursor;
             break;
         }
-        if (result.name && entry.name === result.name && entry.result == null) {
+        if (result.name && entry.name === result.name && (entry.result === null || entry.result === undefined)) {
             index = cursor;
             break;
         }
@@ -213,7 +368,18 @@ export function extractGatewayChatMediaUrls(message) {
         if (item.type !== "image" && item.type !== "audio" && item.type !== "input_audio" && item.type !== "output_audio") {
             continue;
         }
-        const source = asRecord(item.source);
+        const isAudio = item.type === "audio" || item.type === "input_audio" || item.type === "output_audio";
+        if (typeof item.url === "string" && item.url.trim()) {
+            mediaUrls.push(item.url);
+            continue;
+        }
+        if (typeof item.openUrl === "string" && item.openUrl.trim()) {
+            mediaUrls.push(item.openUrl);
+            continue;
+        }
+        const source = asRecord(item.source) ?? (isAudio
+            ? asRecord(item.audio) ?? asRecord(item.input_audio) ?? asRecord(item.output_audio) ?? item
+            : null);
         if (!source) {
             continue;
         }
@@ -221,13 +387,43 @@ export function extractGatewayChatMediaUrls(message) {
             mediaUrls.push(source.url);
             continue;
         }
-        if (source.type === "base64" && typeof source.data === "string" && source.data.trim()) {
-            const mimeType = typeof source.media_type === "string" && source.media_type.trim()
-                ? source.media_type.trim()
-                : item.type === "image"
-                    ? "image/png"
-                    : "audio/mpeg";
-            mediaUrls.push(`data:${mimeType};base64,${source.data}`);
+        if (isAudio && typeof source.url === "string" && source.url.trim()) {
+            mediaUrls.push(source.url.trim());
+            continue;
+        }
+        if (typeof source.data === "string" && source.data.trim()) {
+            if (isAudio && /^data:audio\//i.test(source.data.trim())) {
+                mediaUrls.push(source.data.trim());
+                continue;
+            }
+            const rawMimeType = [source.media_type, source.mime_type, item.media_type, item.mime_type]
+                .find((value) => typeof value === "string" && value.trim());
+            const rawFormat = [source.format, item.format]
+                .find((value) => typeof value === "string" && value.trim());
+            const format = typeof rawFormat === "string" ? rawFormat.trim().toLowerCase() : "";
+            const normalizedMimeType = typeof rawMimeType === "string"
+                ? rawMimeType.trim().split(";", 1)[0].trim()
+                : "";
+            const audioMimeTypes = {
+                aac: "audio/aac",
+                flac: "audio/flac",
+                m4a: "audio/mp4",
+                mp3: "audio/mpeg",
+                oga: "audio/ogg",
+                ogg: "audio/ogg",
+                opus: "audio/ogg",
+                wav: "audio/wav",
+                weba: "audio/webm",
+                webm: "audio/webm",
+            };
+            const mimeType = isAudio
+                ? (/^audio\/[A-Za-z0-9.+-]+$/i.test(normalizedMimeType)
+                    ? normalizedMimeType
+                    : audioMimeTypes[format] ?? "audio/mpeg")
+                : (/^image\/[A-Za-z0-9.+-]+$/i.test(normalizedMimeType)
+                    ? normalizedMimeType
+                    : "image/png");
+            mediaUrls.push(`data:${mimeType};base64,${source.data.trim()}`);
         }
     }
     if (typeof record.mediaUrl === "string" && record.mediaUrl.trim()) {
@@ -240,7 +436,7 @@ export function extractGatewayChatMediaUrls(message) {
             }
         }
     }
-    return mediaUrls;
+    return Array.from(new Set(mediaUrls));
 }
 export function extractGatewayChatToolCalls(message) {
     const record = asRecord(message);
@@ -256,6 +452,8 @@ export function extractGatewayChatToolCalls(message) {
             kind === "tool_call" ||
             kind === "tooluse" ||
             kind === "tool_use" ||
+            kind === "function_call" ||
+            kind === "functioncall" ||
             (name && (item.arguments !== undefined || item.args !== undefined))) {
             toolCalls.push({
                 ...(id ? { id } : {}),
@@ -264,11 +462,11 @@ export function extractGatewayChatToolCalls(message) {
             });
             continue;
         }
-        if (kind === "toolresult" || kind === "tool_result") {
+        if (kind === "toolresult" || kind === "tool_result" || kind === "function_call_output" || kind === "functioncalloutput") {
             toolCalls = mergeGatewayToolResult(toolCalls, {
                 ...(id ? { id } : {}),
                 name: name ?? "tool",
-                result: stringifyToolResult(item.text ?? item.content ?? item.result),
+                result: stringifyToolResult(item.text ?? item.content ?? item.result ?? item.output),
             });
         }
     }
@@ -284,6 +482,9 @@ export function extractGatewayChatToolCalls(message) {
                 ...(gatewayToolCallId(tool) ? { id: gatewayToolCallId(tool) } : {}),
                 name,
                 args: normalizeToolArgs(tool.arguments ?? tool.args),
+                ...(stringifyToolResult(tool.result ?? tool.output ?? tool.content ?? tool.text) !== undefined
+                    ? { result: stringifyToolResult(tool.result ?? tool.output ?? tool.content ?? tool.text) }
+                    : {}),
             });
         }
     }
@@ -292,7 +493,7 @@ export function extractGatewayChatToolCalls(message) {
     const role = typeof record.role === "string" ? record.role.trim().toLowerCase() : "";
     if (topLevelToolName &&
         topLevelResult &&
-        (role === "toolresult" || role === "tool_result" || record.toolCallId || record.tool_call_id)) {
+        (role === "toolresult" || role === "tool_result" || role === "function_call_output" || record.toolCallId || record.tool_call_id || record.call_id || record.callId)) {
         toolCalls = mergeGatewayToolResult(toolCalls, {
             ...(gatewayToolCallId(record) ? { id: gatewayToolCallId(record) } : {}),
             name: topLevelToolName,
@@ -312,6 +513,11 @@ export function normalizeGatewayChatMessage(message) {
     const mediaUrls = extractGatewayChatMediaUrls(record);
     const timestamp = typeof record.timestamp === "number" ? record.timestamp : undefined;
     const role = typeof record.role === "string" && record.role.trim() ? record.role : "assistant";
+    const messageId = protocolIdentityString(record.messageId);
+    const turnId = protocolIdentityString(record.turnId);
+    const runId = extractMessageRunId(record) ?? undefined;
+    const sessionKey = chatPayloadSessionKey(record);
+    const revision = protocolRevision(record.revision);
     if (!text && !thinking && toolCalls.length === 0 && mediaUrls.length === 0) {
         return null;
     }
@@ -322,6 +528,11 @@ export function normalizeGatewayChatMessage(message) {
         toolCalls,
         mediaUrls,
         ...(timestamp !== undefined ? { timestamp } : {}),
+        ...(messageId ? { messageId } : {}),
+        ...(turnId ? { turnId } : {}),
+        ...(runId ? { runId } : {}),
+        ...(sessionKey ? { sessionKey } : {}),
+        ...(revision !== undefined ? { revision } : {}),
     };
 }
 function extractMessageText(message) {
@@ -369,7 +580,25 @@ function extractMessageRunId(message) {
     const metaRunId = typeof meta?.runId === "string" ? meta.runId.trim() : "";
     return metaRunId || null;
 }
-function latestHistoryAssistantText(messages, acceptedRunIds) {
+function historyAssistantBaseline(messages, priorAssistantTexts = []) {
+    const assistantTexts = messages.flatMap((candidate) => {
+        const message = asRecord(candidate);
+        const role = typeof message?.role === "string" ? message.role.trim().toLowerCase() : "";
+        const text = role === "assistant" ? extractMessageText(message)?.trim() : "";
+        return text ? [text] : [];
+    });
+    const useTrackedPrior = priorAssistantTexts.length > assistantTexts.length;
+    return {
+        count: Math.max(assistantTexts.length, priorAssistantTexts.length),
+        latestText: useTrackedPrior
+            ? priorAssistantTexts[priorAssistantTexts.length - 1] ?? ""
+            : assistantTexts[assistantTexts.length - 1] ?? "",
+    };
+}
+function latestHistoryAssistantText(messages, acceptedRunIds, baseline) {
+    const currentBaseline = historyAssistantBaseline(messages);
+    const hasNewUncorrelatedAssistant = baseline === undefined || Boolean(baseline && (currentBaseline.count > baseline.count ||
+        currentBaseline.latestText !== baseline.latestText));
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = asRecord(messages[index]);
         if (!message) {
@@ -383,6 +612,9 @@ function latestHistoryAssistantText(messages, acceptedRunIds) {
         if (messageRunId && acceptedRunIds.size > 0 && !acceptedRunIds.has(messageRunId)) {
             continue;
         }
+        if (!messageRunId && !hasNewUncorrelatedAssistant) {
+            continue;
+        }
         const text = extractMessageText(message)?.trim();
         if (text) {
             return text;
@@ -402,6 +634,59 @@ function streamDelta(previousText, nextText) {
     }
     return { delta: nextText, nextText };
 }
+function appendStreamContent(previousText, text, replace) {
+    if (replace)
+        return reconcileStreamContent(previousText, text, true);
+    if (!text)
+        return null;
+    return { text, nextText: previousText + text, replace: false };
+}
+function reconcileStreamContent(previousText, snapshot, replace = false) {
+    if (replace)
+        return { text: snapshot, nextText: snapshot, replace: true };
+    if (snapshot === previousText)
+        return null;
+    if (snapshot.startsWith(previousText)) {
+        const text = snapshot.slice(previousText.length);
+        return text ? { text, nextText: snapshot, replace: false } : null;
+    }
+    if (previousText.startsWith(snapshot))
+        return null;
+    return { text: snapshot, nextText: snapshot, replace: true };
+}
+function protocolIdentityString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function chatPayloadSessionKey(payload) {
+    return protocolIdentityString(payload.canonicalSessionKey) ?? protocolIdentityString(payload.sessionKey);
+}
+function protocolRevision(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : protocolIdentityString(value);
+}
+function chatEventIdentity(payload) {
+    const message = asRecord(payload.message);
+    const eventId = protocolIdentityString(payload.eventId) ?? protocolIdentityString(message?.eventId);
+    const messageId = protocolIdentityString(payload.messageId) ?? protocolIdentityString(message?.messageId);
+    const turnId = protocolIdentityString(payload.turnId) ?? protocolIdentityString(message?.turnId);
+    const runId = protocolIdentityString(payload.runId) ?? extractMessageRunId(message);
+    const sessionKey = chatPayloadSessionKey(payload) ?? (message ? chatPayloadSessionKey(message) : undefined);
+    const revision = protocolRevision(payload.revision) ?? protocolRevision(message?.revision);
+    return {
+        ...(eventId ? { eventId } : {}),
+        ...(messageId ? { messageId } : {}),
+        ...(turnId ? { turnId } : {}),
+        ...(runId ? { runId } : {}),
+        ...(sessionKey ? { sessionKey } : {}),
+        ...(revision !== undefined ? { revision } : {}),
+    };
+}
+function applyChatEventContent(currentText, event) {
+    if (event.type !== "content")
+        return currentText;
+    return event.replace === true ? event.text ?? "" : currentText + (event.text ?? "");
+}
 function parseAgentSessionKey(sessionKey) {
     const normalized = (sessionKey ?? "").trim().toLowerCase();
     if (!normalized) {
@@ -440,6 +725,89 @@ function sameSessionKey(left, right) {
     }
     return false;
 }
+function isReservedEphemeralSessionKey(sessionKey) {
+    return /^session-hypercli-ephemeral-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(sessionKey.trim().toLowerCase());
+}
+function validateEphemeralCanonicalKey(requestedKey, canonicalKey) {
+    if (!isReservedEphemeralSessionKey(requestedKey))
+        return null;
+    if (canonicalKey === requestedKey)
+        return canonicalKey;
+    if (!canonicalKey.startsWith("agent:"))
+        return null;
+    const agentSeparator = canonicalKey.indexOf(":", "agent:".length);
+    if (agentSeparator <= "agent:".length)
+        return null;
+    if (!canonicalKey.slice("agent:".length, agentSeparator).trim())
+        return null;
+    return canonicalKey.slice(agentSeparator + 1) === requestedKey ? canonicalKey : null;
+}
+function valueReferencesEphemeralSession(value, activeSessionKeys, seen = new WeakSet()) {
+    if (typeof value === "string") {
+        const candidate = value.trim();
+        const unscoped = parseAgentSessionKey(candidate)?.rest ?? candidate;
+        return isReservedEphemeralSessionKey(unscoped) || activeSessionKeys.some((key) => sameSessionKey(candidate, key));
+    }
+    if (!value || typeof value !== "object" || seen.has(value))
+        return false;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.some((item) => valueReferencesEphemeralSession(item, activeSessionKeys, seen));
+    }
+    return Object.values(value).some((item) => valueReferencesEphemeralSession(item, activeSessionKeys, seen));
+}
+async function promiseSettlesWithin(promise, timeoutMs) {
+    let timeout = null;
+    try {
+        return await Promise.race([
+            promise.then(() => true, () => true),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+async function booleanPromiseWithin(promise, timeoutMs) {
+    let timeout = null;
+    try {
+        return await Promise.race([
+            promise.catch(() => false),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function isChatStreamGatewayEvent(event) {
+    if (event.event === "chat" || event.event.startsWith("chat."))
+        return true;
+    if (event.event !== "agent")
+        return false;
+    const payload = asRecord(event.payload) ?? {};
+    const stream = typeof payload.stream === "string" ? payload.stream.toLowerCase() : "";
+    return stream === "tool" || stream === "lifecycle";
+}
+function isTerminalChatStreamGatewayEvent(event) {
+    if (event.event === "chat.done" || event.event === "chat.error")
+        return true;
+    const payload = asRecord(event.payload) ?? {};
+    if (event.event === "agent" && String(payload.stream ?? "").toLowerCase() === "lifecycle") {
+        const phase = String(asRecord(payload.data)?.phase ?? "").toLowerCase();
+        return phase === "end" || phase === "error";
+    }
+    if (event.event !== "chat")
+        return false;
+    const state = String(payload.state ?? "").toLowerCase();
+    return state === "final" || state === "error" || state === "aborted";
+}
 function splitConfigPath(path) {
     return path
         .split(".")
@@ -665,6 +1033,23 @@ function normalizeClientMode(value) {
     const normalized = value?.trim().toLowerCase();
     return normalized && VALID_CLIENT_MODES.has(normalized) ? normalized : DEFAULT_CLIENT_MODE;
 }
+function normalizeOptionalString(value) {
+    return value?.trim() || undefined;
+}
+function normalizeProtocolVersion(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.trunc(value)
+        : fallback;
+}
+function normalizePermissions(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const entries = Object.entries(value)
+        .filter(([key, allowed]) => key.trim() && typeof allowed === "boolean")
+        .map(([key, allowed]) => [key.trim(), allowed]);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
 function getNavigatorLike() {
     const maybeNavigator = globalThis.navigator;
     return maybeNavigator ?? null;
@@ -1072,6 +1457,11 @@ export class GatewayClient {
     url;
     token;
     gatewayToken;
+    bootstrapToken;
+    deviceToken;
+    password;
+    approvalRuntimeToken;
+    agentRuntimeIdentityToken;
     deploymentId;
     apiKey;
     apiBase;
@@ -1081,13 +1471,31 @@ export class GatewayClient {
     clientDisplayName;
     clientVersion;
     clientPlatform;
+    clientDeviceFamily;
     clientInstanceId;
     caps;
+    role;
+    scopes;
+    commands;
+    permissions;
+    pathEnv;
+    minProtocol;
+    maxProtocol;
     origin;
     defaultTimeout;
     ws = null;
     pending = new Map();
     eventHandlers = new Set();
+    internalEventHandlers = new Set();
+    internalStreamCloseHandlers = new Set();
+    activeNormalChatStreams = new Set();
+    activeStrictChatStreams = new Set();
+    activeEphemeralSessionKeys = new Map();
+    suppressedEphemeralRunIds = new Map();
+    pendingEphemeralChatAcks = 0;
+    deferredEphemeralCorrelationEvents = new Set();
+    deferredEphemeralEventsCanRepublish = true;
+    suppressUncorrelatedChatEventsUntil = 0;
     connectionStateHandlers = new Set();
     connected = false;
     connectionState = "disconnected";
@@ -1112,37 +1520,58 @@ export class GatewayClient {
     onDisconnect = null;
     constructor(options) {
         this.url = options.url;
-        this.token = options.token?.trim() || undefined;
-        this.gatewayToken = options.gatewayToken?.trim() || undefined;
-        this.deploymentId = options.deploymentId?.trim() || undefined;
-        this.apiKey = options.apiKey?.trim() || undefined;
+        this.token = normalizeOptionalString(options.token);
+        this.gatewayToken = normalizeOptionalString(options.gatewayToken);
+        this.bootstrapToken = normalizeOptionalString(options.bootstrapToken);
+        this.deviceToken = normalizeOptionalString(options.deviceToken);
+        this.password = normalizeOptionalString(options.password);
+        this.approvalRuntimeToken = normalizeOptionalString(options.approvalRuntimeToken);
+        this.agentRuntimeIdentityToken = normalizeOptionalString(options.agentRuntimeIdentityToken);
+        this.deploymentId = normalizeOptionalString(options.deploymentId);
+        this.apiKey = normalizeOptionalString(options.apiKey);
         this.apiBase = options.apiBase?.trim().replace(/\/$/, "") || undefined;
         this.autoApprovePairing = options.autoApprovePairing === true;
         this.clientId = normalizeClientId(options.clientId);
         this.clientMode = normalizeClientMode(options.clientMode);
         this.clientVersion = options.clientVersion?.trim() || DEFAULT_CLIENT_VERSION;
         this.clientPlatform = resolvePlatform(options.platform);
+        this.clientDeviceFamily = normalizeOptionalString(options.deviceFamily);
         this.clientDisplayName = resolveClientDisplayName(options.clientDisplayName, this.clientPlatform);
-        this.clientInstanceId = options.instanceId?.trim() || makeId();
+        this.clientInstanceId = normalizeOptionalString(options.instanceId) || makeId();
         this.caps = Array.isArray(options.caps)
             ? options.caps.map((cap) => cap.trim()).filter(Boolean)
             : [...DEFAULT_CAPS];
+        this.role = options.role?.trim() || OPERATOR_ROLE;
+        this.scopes = Array.isArray(options.scopes)
+            ? options.scopes.map((scope) => scope.trim()).filter(Boolean)
+            : this.role === OPERATOR_ROLE
+                ? [...OPERATOR_SCOPES]
+                : [];
+        this.commands = Array.isArray(options.commands)
+            ? options.commands.map((command) => command.trim()).filter(Boolean)
+            : undefined;
+        this.permissions = normalizePermissions(options.permissions);
+        this.pathEnv = normalizeOptionalString(options.pathEnv);
+        this.minProtocol = normalizeProtocolVersion(options.minProtocol, MIN_GATEWAY_VERSION);
+        this.maxProtocol = normalizeProtocolVersion(options.maxProtocol, MAX_GATEWAY_VERSION);
         // 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.defaultTimeout = options.timeout ?? DEFAULT_CONNECTION_TIMEOUT;
         this.onHello = options.onHello;
         this.onClose = options.onClose;
         this.onGap = options.onGap;
+        this.onProtocolError = options.onProtocolError;
         this.onPairing = options.onPairing;
-        this.pairingState = loadPendingPairing(this.storageScope(), OPERATOR_ROLE);
+        this.pairingState = loadPendingPairing(this.storageScope(), this.role);
     }
     onHello;
     onClose;
     onGap;
+    onProtocolError;
     onPairing;
     get version() {
         return this._version;
@@ -1188,6 +1617,153 @@ export class GatewayClient {
         this.eventHandlers.add(handler);
         return () => this.eventHandlers.delete(handler);
     }
+    currentEphemeralSessionKeys() {
+        const now = Date.now();
+        for (const [sessionKey, expiresAt] of this.activeEphemeralSessionKeys) {
+            if (expiresAt !== null && expiresAt <= now)
+                this.activeEphemeralSessionKeys.delete(sessionKey);
+        }
+        return [...this.activeEphemeralSessionKeys.keys()];
+    }
+    shouldSuppressPublicEvent(event, handledInternally) {
+        if (handledInternally)
+            return true;
+        const payload = asRecord(event.payload) ?? {};
+        const activeSessionKeys = this.currentEphemeralSessionKeys();
+        if (valueReferencesEphemeralSession(payload, activeSessionKeys))
+            return true;
+        const sessionKey = chatPayloadSessionKey(payload)?.trim() ?? "";
+        const unscopedSessionKey = parseAgentSessionKey(sessionKey)?.rest ?? sessionKey;
+        if (isReservedEphemeralSessionKey(unscopedSessionKey))
+            return true;
+        if (sessionKey &&
+            activeSessionKeys.some((activeKey) => sameSessionKey(sessionKey, activeKey))) {
+            return true;
+        }
+        const runId = typeof payload.runId === "string" ? payload.runId.trim() : "";
+        const suppressedRunExpiry = runId ? this.suppressedEphemeralRunIds.get(runId) : undefined;
+        if (suppressedRunExpiry !== undefined) {
+            if (suppressedRunExpiry > Date.now())
+                return true;
+            this.suppressedEphemeralRunIds.delete(runId);
+        }
+        if (runId &&
+            !sessionKey &&
+            isChatStreamGatewayEvent(event) &&
+            this.suppressUncorrelatedChatEventsUntil > Date.now()) {
+            return true;
+        }
+        if (activeSessionKeys.length > 0 && event.event === "activity.log" && !sessionKey && !runId) {
+            return true;
+        }
+        return (activeSessionKeys.length > 0 &&
+            !sessionKey &&
+            !runId &&
+            isChatStreamGatewayEvent(event));
+    }
+    suppressEphemeralRunId(runId) {
+        const normalized = runId.trim();
+        if (!normalized)
+            return;
+        const now = Date.now();
+        for (const [candidate, expiresAt] of this.suppressedEphemeralRunIds) {
+            if (expiresAt <= now)
+                this.suppressedEphemeralRunIds.delete(candidate);
+        }
+        this.suppressedEphemeralRunIds.set(normalized, now + EPHEMERAL_RUN_ID_SUPPRESSION_MS);
+    }
+    beginEphemeralChatAcknowledgement() {
+        if (this.pendingEphemeralChatAcks === 0)
+            this.deferredEphemeralEventsCanRepublish = true;
+        this.pendingEphemeralChatAcks += 1;
+    }
+    deferEphemeralCorrelationEvent(event) {
+        if (this.pendingEphemeralChatAcks > 0)
+            this.deferredEphemeralCorrelationEvents.add(event);
+    }
+    finishEphemeralChatAcknowledgement(canRepublishDeferredEvents) {
+        if (this.pendingEphemeralChatAcks <= 0)
+            return;
+        this.deferredEphemeralEventsCanRepublish &&= canRepublishDeferredEvents;
+        this.pendingEphemeralChatAcks -= 1;
+        if (this.pendingEphemeralChatAcks > 0)
+            return;
+        if (!this.deferredEphemeralEventsCanRepublish) {
+            this.suppressUncorrelatedChatEventsUntil = Math.max(this.suppressUncorrelatedChatEventsUntil, Date.now() + EPHEMERAL_RUN_ID_SUPPRESSION_MS);
+        }
+        const deferredEvents = [...this.deferredEphemeralCorrelationEvents];
+        this.deferredEphemeralCorrelationEvents.clear();
+        const shouldRepublish = this.deferredEphemeralEventsCanRepublish;
+        this.deferredEphemeralEventsCanRepublish = true;
+        if (shouldRepublish)
+            deferredEvents.forEach((event) => this.publishPublicEvent(event));
+    }
+    publishPublicEvent(event, handledInternally = false) {
+        if (this.shouldSuppressPublicEvent(event, handledInternally))
+            return;
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Event handlers are isolated from the socket lifecycle.
+            }
+        }
+    }
+    notifyInternalStreamClose(error) {
+        for (const handler of this.internalStreamCloseHandlers) {
+            try {
+                handler(error);
+            }
+            catch {
+                // Stream close handlers are isolated from the socket lifecycle.
+            }
+        }
+    }
+    interruptNormalChatStreams(error) {
+        for (const stream of [...this.activeNormalChatStreams])
+            stream.close(error);
+    }
+    handleForwardSequenceGap(info, receivedEvent) {
+        try {
+            this.onGap?.(info);
+        }
+        catch {
+            // Gap callbacks are observational and must not affect the socket.
+        }
+        queueMicrotask(() => {
+            const error = new GatewayChatStreamInterruptedError("sequence-gap", info);
+            const streams = new Set([
+                ...this.activeNormalChatStreams,
+                ...this.activeStrictChatStreams,
+            ]);
+            for (const stream of streams) {
+                if (stream.terminalEvent !== receivedEvent)
+                    stream.close(error);
+            }
+        });
+    }
+    reportProtocolError(info) {
+        try {
+            this.onProtocolError?.(info);
+        }
+        catch {
+            // Protocol diagnostics are observational and must not affect the socket.
+        }
+    }
+    rejectMalformedPendingResponse(info) {
+        if (info.frameType !== "res" || !info.requestId)
+            return;
+        const pending = this.pending.get(info.requestId);
+        if (!pending)
+            return;
+        this.pending.delete(info.requestId);
+        pending.cleanup();
+        pending.reject(new GatewayRequestError({
+            code: "PROTOCOL_ERROR",
+            message: info.message,
+        }));
+    }
     /** Connect and keep reconnecting until stopped */
     connect() {
         return this.start();
@@ -1231,7 +1807,9 @@ export class GatewayClient {
         if (ws) {
             ws.close();
         }
-        this.flushPending(new Error("gateway client stopped"));
+        const stoppedError = new Error("gateway client stopped");
+        this.flushPending(stoppedError);
+        this.notifyInternalStreamClose(stoppedError);
         if (this.rejectConnectPromise) {
             this.rejectConnectPromise(new Error("gateway client stopped"));
         }
@@ -1245,7 +1823,7 @@ export class GatewayClient {
             storePendingPairing(pairing, this.storageScope());
         }
         else {
-            clearPendingPairing(this.storageScope(), OPERATOR_ROLE);
+            clearPendingPairing(this.storageScope(), this.role);
         }
         this.onPairing?.(pairing);
     }
@@ -1299,6 +1877,7 @@ export class GatewayClient {
             ? new WebSocket(wsUrl)
             : new NodeWebSocket(wsUrl, this.origin ? { headers: { Origin: this.origin } } : undefined);
         this.ws = ws;
+        this.lastSeq = null;
         if (useBrowserSocket) {
             ws.onopen = () => {
                 this.queueConnect();
@@ -1361,7 +1940,7 @@ export class GatewayClient {
     }
     flushPending(error) {
         for (const [, pending] of this.pending) {
-            clearTimeout(pending.timer);
+            pending.cleanup();
             pending.reject(error);
         }
         this.pending.clear();
@@ -1381,7 +1960,9 @@ export class GatewayClient {
         }
         const error = this.pendingConnectError;
         this.pendingConnectError = null;
-        this.flushPending(new Error(`gateway closed (${code}): ${reason || "no reason"}`));
+        const closeError = new Error(`gateway closed (${code}): ${reason || "no reason"}`);
+        this.flushPending(closeError);
+        this.notifyInternalStreamClose(closeError);
         this.onClose?.({ code, reason, error });
         if (!this.closed) {
             this.onDisconnect?.();
@@ -1419,34 +2000,53 @@ export class GatewayClient {
         let storedDeviceToken = null;
         try {
             identity = await loadOrCreateDeviceIdentity();
-            storedDeviceToken = loadStoredDeviceToken(identity.deviceId, this.storageScope(), OPERATOR_ROLE)?.token ?? null;
-            const authToken = this.gatewayToken ?? storedDeviceToken;
-            const authDeviceToken = this.pendingDeviceTokenRetry ? (storedDeviceToken ?? undefined) : undefined;
+            storedDeviceToken = loadStoredDeviceToken(identity.deviceId, this.storageScope(), this.role)?.token ?? null;
+            const resolvedDeviceToken = this.deviceToken ?? storedDeviceToken ?? undefined;
+            const authToken = this.gatewayToken ?? resolvedDeviceToken;
+            const authBootstrapToken = !this.gatewayToken && !resolvedDeviceToken && !this.password
+                ? this.bootstrapToken
+                : undefined;
+            const authDeviceToken = this.deviceToken ?? (this.pendingDeviceTokenRetry ? resolvedDeviceToken : undefined);
+            const signatureToken = authToken ?? authBootstrapToken;
             const signedAtMs = Date.now();
             const payload = buildDeviceAuthPayload({
                 deviceId: identity.deviceId,
                 clientId: this.clientId,
                 clientMode: this.clientMode,
-                role: OPERATOR_ROLE,
-                scopes: OPERATOR_SCOPES,
+                role: this.role,
+                scopes: this.scopes,
                 signedAtMs,
-                token: authToken ?? null,
+                token: signatureToken ?? null,
                 nonce,
             });
             const signature = await signDevicePayload(identity.privateKey, payload);
+            const auth = {};
+            if (authToken)
+                auth.token = authToken;
+            if (authBootstrapToken)
+                auth.bootstrapToken = authBootstrapToken;
+            if (authDeviceToken)
+                auth.deviceToken = authDeviceToken;
+            if (this.password)
+                auth.password = this.password;
+            if (this.approvalRuntimeToken)
+                auth.approvalRuntimeToken = this.approvalRuntimeToken;
+            if (this.agentRuntimeIdentityToken)
+                auth.agentRuntimeIdentityToken = this.agentRuntimeIdentityToken;
             const params = {
-                minProtocol: MIN_PROTOCOL_VERSION,
-                maxProtocol: PROTOCOL_VERSION,
+                minProtocol: this.minProtocol,
+                maxProtocol: this.maxProtocol,
                 client: {
                     id: this.clientId,
                     ...(this.clientDisplayName ? { displayName: this.clientDisplayName } : {}),
                     version: this.clientVersion,
                     platform: this.clientPlatform,
+                    ...(this.clientDeviceFamily ? { deviceFamily: this.clientDeviceFamily } : {}),
                     mode: this.clientMode,
                     ...(this.clientInstanceId ? { instanceId: this.clientInstanceId } : {}),
                 },
-                role: OPERATOR_ROLE,
-                scopes: [...OPERATOR_SCOPES],
+                role: this.role,
+                scopes: [...this.scopes],
                 device: {
                     id: identity.deviceId,
                     publicKey: identity.publicKey,
@@ -1455,30 +2055,21 @@ export class GatewayClient {
                     nonce,
                 },
                 caps: this.caps,
-                ...(authToken
-                    ? {
-                        auth: {
-                            ...(authToken ? { token: authToken } : {}),
-                            ...(authDeviceToken ? { deviceToken: authDeviceToken } : {}),
-                        },
-                    }
-                    : authDeviceToken
-                        ? {
-                            auth: {
-                                deviceToken: authDeviceToken,
-                            },
-                        }
-                        : {}),
+                ...(this.commands ? { commands: this.commands } : {}),
+                ...(this.permissions ? { permissions: this.permissions } : {}),
+                ...(this.pathEnv ? { pathEnv: this.pathEnv } : {}),
+                ...(Object.keys(auth).length ? { auth } : {}),
                 ...(resolveUserAgent() ? { userAgent: resolveUserAgent() } : {}),
                 ...(resolveLocale() ? { locale: resolveLocale() } : {}),
             };
-            const hello = await this.sendRawRequest("connect", params, this.defaultTimeout, true);
+            const hello = await this.sendRawRequest("connect", params, { timeoutMs: this.defaultTimeout }, true);
             if (hello?.auth?.deviceToken) {
+                this.deviceToken = hello.auth.deviceToken;
                 storeStoredDeviceToken({
                     deviceId: identity.deviceId,
                     scope: this.storageScope(),
                     gatewayUrl: this.url,
-                    role: hello.auth.role ?? OPERATOR_ROLE,
+                    role: hello.auth.role ?? this.role,
                     token: hello.auth.deviceToken,
                     scopes: hello.auth.scopes ?? [],
                 });
@@ -1510,7 +2101,7 @@ export class GatewayClient {
             // one-shot flag to prevent infinite recursion if the retry also fails.
             if (identity && detailCode === CONNECT_ERROR_DEVICE_TOKEN_MISMATCH && !this.deviceTokenMismatchRetried) {
                 this.deviceTokenMismatchRetried = true;
-                clearStoredDeviceToken(identity.deviceId, this.storageScope(), OPERATOR_ROLE);
+                clearStoredDeviceToken(identity.deviceId, this.storageScope(), this.role);
                 this.connectSent = false;
                 this.pendingConnectError = null;
                 this.pendingDeviceTokenRetry = false;
@@ -1531,7 +2122,7 @@ export class GatewayClient {
                 return;
             }
             if (identity && detailCode === CONNECT_ERROR_PAIRING_REQUIRED) {
-                clearStoredDeviceToken(identity.deviceId, this.storageScope(), OPERATOR_ROLE);
+                clearStoredDeviceToken(identity.deviceId, this.storageScope(), this.role);
             }
             if (detailCode === CONNECT_ERROR_PAIRING_REQUIRED && requestId) {
                 if (this.canAutoApprovePairing() && !this.autoApproveAttemptedRequestIds.has(requestId)) {
@@ -1556,7 +2147,7 @@ export class GatewayClient {
                         this.pendingConnectError = toCloseError(approvalError);
                         this.updatePairingState({
                             requestId,
-                            role: OPERATOR_ROLE,
+                            role: this.role,
                             gatewayUrl: this.url,
                             ...(identity ? { deviceId: identity.deviceId } : {}),
                             status: "failed",
@@ -1569,7 +2160,7 @@ export class GatewayClient {
                     // No auto-approve — surface pairing state so the UI can prompt.
                     this.updatePairingState({
                         requestId,
-                        role: OPERATOR_ROLE,
+                        role: this.role,
                         gatewayUrl: this.url,
                         ...(identity ? { deviceId: identity.deviceId } : {}),
                         status: "pending",
@@ -1583,19 +2174,18 @@ export class GatewayClient {
         }
     }
     handleMessage(raw) {
-        let message;
-        try {
-            message = JSON.parse(raw);
-        }
-        catch {
+        const decoded = decodeGatewayFrame(raw);
+        if (!decoded.ok) {
+            this.reportProtocolError(decoded.error);
+            this.rejectMalformedPendingResponse(decoded.error);
             return;
         }
+        const message = decoded.frame;
         if (message.type === "event") {
             const gatewayEvent = message;
             if (gatewayEvent.event === "connect.challenge") {
-                const nonce = gatewayEvent.payload && typeof gatewayEvent.payload.nonce === "string"
-                    ? gatewayEvent.payload.nonce.trim()
-                    : "";
+                const challenge = asRecord(gatewayEvent.payload);
+                const nonce = typeof challenge?.nonce === "string" ? challenge.nonce.trim() : "";
                 if (!nonce) {
                     this.pendingConnectError = {
                         code: "DEVICE_AUTH_NONCE_REQUIRED",
@@ -1608,67 +2198,161 @@ export class GatewayClient {
                 void this.sendConnect();
                 return;
             }
+            let sequenceGap = null;
             if (typeof gatewayEvent.seq === "number") {
-                if (this.lastSeq !== null && gatewayEvent.seq > this.lastSeq + 1) {
-                    this.onGap?.({ expected: this.lastSeq + 1, received: gatewayEvent.seq });
+                if (this.lastSeq !== null) {
+                    if (gatewayEvent.seq === this.lastSeq) {
+                        this.reportProtocolError({
+                            code: "DUPLICATE_SEQUENCE",
+                            message: "duplicate gateway event sequence was discarded",
+                            frameType: "event",
+                            event: gatewayEvent.event,
+                        });
+                        return;
+                    }
+                    if (gatewayEvent.seq < this.lastSeq) {
+                        this.reportProtocolError({
+                            code: "OUT_OF_ORDER_SEQUENCE",
+                            message: "out-of-order gateway event sequence was discarded",
+                            frameType: "event",
+                            event: gatewayEvent.event,
+                        });
+                        return;
+                    }
+                    if (gatewayEvent.seq > this.lastSeq + 1) {
+                        sequenceGap = { expected: this.lastSeq + 1, received: gatewayEvent.seq };
+                    }
                 }
                 this.lastSeq = gatewayEvent.seq;
             }
-            for (const handler of this.eventHandlers) {
+            const payload = asRecord(gatewayEvent.payload) ?? {};
+            const identity = chatEventIdentity(payload);
+            if (isChatStreamGatewayEvent(gatewayEvent) &&
+                !identity.runId &&
+                !identity.sessionKey &&
+                this.activeNormalChatStreams.size > 1) {
+                this.reportProtocolError({
+                    code: "AMBIGUOUS_CHAT_STREAM_EVENT",
+                    message: "chat stream event without run or session identity was discarded",
+                    frameType: "event",
+                    event: gatewayEvent.event,
+                });
+                this.interruptNormalChatStreams(new GatewayChatStreamInterruptedError("ambiguous-event"));
+                if (sequenceGap)
+                    this.handleForwardSequenceGap(sequenceGap, gatewayEvent);
+                return;
+            }
+            let handledInternally = false;
+            for (const handler of this.internalEventHandlers) {
                 try {
-                    handler(gatewayEvent);
+                    handledInternally = handler(gatewayEvent) || handledInternally;
                 }
                 catch {
-                    // Event handlers are isolated from the socket lifecycle.
+                    // Internal stream handlers are isolated from the socket lifecycle.
                 }
             }
-            return;
-        }
-        if (message.type !== "res") {
+            this.publishPublicEvent(gatewayEvent, handledInternally);
+            if (sequenceGap)
+                this.handleForwardSequenceGap(sequenceGap, gatewayEvent);
             return;
         }
         const pending = this.pending.get(message.id);
         if (!pending) {
             return;
         }
+        const payload = message.ok ? asRecord(message.payload) : null;
+        if (pending.expectFinal && payload?.status === "accepted") {
+            if (!pending.acceptedNotified) {
+                pending.acceptedNotified = true;
+                try {
+                    pending.onAccepted?.(payload);
+                }
+                catch {
+                    // Accepted callbacks are observational and must not break the request.
+                }
+            }
+            return;
+        }
         this.pending.delete(message.id);
-        clearTimeout(pending.timer);
+        pending.cleanup();
         if (message.ok) {
             pending.resolve(message.payload);
             return;
         }
-        pending.reject(new GatewayRequestError({
-            code: message.error?.code ?? "UNAVAILABLE",
-            message: message.error?.message ?? "gateway request failed",
-            details: message.error?.details,
-        }));
+        pending.reject(new GatewayRequestError(message.error));
     }
-    sendRawRequest(method, params = {}, timeout = this.defaultTimeout, allowBeforeHello = false) {
+    sendRawRequest(method, params = {}, options = {}, allowBeforeHello = false) {
         if (!this.ws || !isSocketOpen(this.ws)) {
             return Promise.reject(new Error("gateway not connected"));
         }
         if (!allowBeforeHello && !this.connected) {
             return Promise.reject(new Error("gateway not connected"));
         }
+        if (options.signal?.aborted) {
+            return Promise.reject(createGatewayRequestAbortError(method));
+        }
         const id = makeId();
         const request = { type: "req", id, method, params };
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
+        const expectFinal = options.expectFinal === true;
+        const timeout = options.timeoutMs === null
+            ? null
+            : typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs)
+                ? Math.max(0, options.timeoutMs)
+                : expectFinal
+                    ? null
+                    : this.defaultTimeout;
+        const promise = new Promise((resolve, reject) => {
+            const timer = timeout === null
+                ? null
+                : setTimeout(() => {
+                    const pending = this.pending.get(id);
+                    this.pending.delete(id);
+                    pending?.cleanup();
+                    reject(new Error(`RPC timeout: ${method}`));
+                }, timeout);
+            const abortHandler = () => {
+                const pending = this.pending.get(id);
                 this.pending.delete(id);
-                reject(new Error(`RPC timeout: ${method}`));
-            }, timeout);
-            this.pending.set(id, { resolve, reject, timer });
-            this.ws?.send(JSON.stringify(request));
+                pending?.cleanup();
+                reject(createGatewayRequestAbortError(method));
+            };
+            const cleanup = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                options.signal?.removeEventListener("abort", abortHandler);
+            };
+            this.pending.set(id, {
+                resolve,
+                reject,
+                expectFinal,
+                timer,
+                cleanup,
+                onAccepted: options.onAccepted,
+            });
+            options.signal?.addEventListener("abort", abortHandler, { once: true });
         });
+        try {
+            this.ws?.send(JSON.stringify(request));
+        }
+        catch (error) {
+            const pending = this.pending.get(id);
+            this.pending.delete(id);
+            pending?.cleanup();
+            throw error;
+        }
+        return promise;
     }
     // ---------------------------------------------------------------------------
     // RPC
     // ---------------------------------------------------------------------------
     rpc(method, params = {}, timeout) {
-        return this.sendRawRequest(method, params, timeout ?? this.defaultTimeout);
+        return this.sendRawRequest(method, params, {
+            timeoutMs: timeout === undefined ? this.defaultTimeout : timeout,
+        });
     }
-    request(method, params = {}, timeout) {
-        return this.rpc(method, params, timeout);
+    request(method, params = {}, options) {
+        return this.sendRawRequest(method, params, typeof options === "object" && options !== null ? options : { timeoutMs: options });
     }
     // ---------------------------------------------------------------------------
     // Config
@@ -1691,6 +2375,9 @@ export class GatewayClient {
         const res = await this.rpc("config.schema");
         return normalizeOpenClawConfigSchema(res) ?? { schema: {}, uiHints: {} };
     }
+    async configSchemaLookup(path) {
+        return await this.rpc("config.schema.lookup", { path });
+    }
     async configPatch(patch) {
         const { hash, baseHash } = await this.rpc("config.get");
         await this.rpc("config.patch", {
@@ -1712,6 +2399,42 @@ export class GatewayClient {
             baseHash: hash ?? baseHash ?? "",
         });
     }
+    async configureSlackSocket(config, accountId) {
+        await this.configPatch(channelConfigPatch("slack", { ...config, mode: "socket" }, accountId));
+    }
+    async configureSlackHttp(config, accountId) {
+        await this.configPatch(channelConfigPatch("slack", { ...config, mode: "http" }, accountId));
+    }
+    async configureSlackRelay(options, accountId) {
+        if ("relay" in options) {
+            await this.configPatch(channelConfigPatch("slack", {
+                ...options,
+                enterpriseOrgInstall: false,
+                mode: "relay",
+            }, accountId));
+            return;
+        }
+        const relayConfig = {
+            mode: "relay",
+            ...(options.botToken ? { botToken: options.botToken } : {}),
+            relay: {
+                url: options.url,
+                authToken: {
+                    source: "env",
+                    provider: "default",
+                    id: options.authTokenEnv ?? "HYPER_AGENTS_API_KEY",
+                },
+                gatewayId: options.gatewayId,
+            },
+        };
+        await this.configPatch(channelConfigPatch("slack", relayConfig, options.accountId, Boolean(options.accountId)));
+    }
+    async configureTelegram(config, accountId) {
+        await this.configPatch(channelConfigPatch("telegram", config, accountId));
+    }
+    async configureWhatsapp(config, accountId) {
+        await this.configPatch(channelConfigPatch("whatsapp", config, accountId));
+    }
     async modelsList() {
         const res = await this.rpc("models.list");
         return res?.models ?? res ?? [];
@@ -1781,18 +2504,111 @@ export class GatewayClient {
         const detail = lastError instanceof Error ? `: ${lastError.message}` : "";
         throw new Error(`Gateway readiness probe timed out after ${timeoutMs}ms${detail}`);
     }
-    async channelsStatus(probe = false, timeoutMs) {
+    async channelsStatus(probe = false, timeoutMs, channel) {
         const params = { probe };
         if (timeoutMs !== undefined)
             params.timeoutMs = timeoutMs;
+        if (channel !== undefined)
+            params.channel = channel;
         return await this.rpc("channels.status", params);
     }
+    async channelsStart(channel, accountId) {
+        const params = { channel };
+        if (accountId !== undefined)
+            params.accountId = accountId;
+        return await this.rpc("channels.start", params);
+    }
+    async channelsStop(channel, accountId) {
+        const params = { channel };
+        if (accountId !== undefined)
+            params.accountId = accountId;
+        return await this.rpc("channels.stop", params);
+    }
     async channelsLogout(channel, accountId) {
         const params = { channel };
-        if (accountId)
+        if (accountId !== undefined)
             params.accountId = accountId;
         return await this.rpc("channels.logout", params);
     }
+    async messageAction(params) {
+        const request = {
+            channel: params.channel,
+            action: params.action,
+            params: params.params,
+            idempotencyKey: params.idempotencyKey ?? makeId(),
+        };
+        if (params.accountId !== undefined)
+            request.accountId = params.accountId;
+        if (params.sessionKey !== undefined)
+            request.sessionKey = params.sessionKey;
+        if (params.sessionId !== undefined)
+            request.sessionId = params.sessionId;
+        if (params.inboundTurnKind !== undefined)
+            request.inboundTurnKind = params.inboundTurnKind;
+        if (params.agentId !== undefined)
+            request.agentId = params.agentId;
+        if (params.conversationReadOrigin !== undefined) {
+            request.conversationReadOrigin = params.conversationReadOrigin;
+        }
+        return await this.rpc("message.action", request);
+    }
+    async send(params) {
+        return await this.rpc("send", {
+            ...params,
+            idempotencyKey: params.idempotencyKey ?? makeId(),
+        });
+    }
+    async readMediaBytes(pathOrUrl) {
+        const token = this.gatewayToken ?? this.deviceToken ?? this.password;
+        if (!token) {
+            throw new Error("Gateway media requires an auth token");
+        }
+        if (typeof globalThis.fetch !== "function") {
+            throw new Error("fetch is not available in this runtime");
+        }
+        const base = new URL(this.url);
+        const protocol = base.protocol === "wss:" ? "https:" : base.protocol === "ws:" ? "http:" : base.protocol;
+        const url = pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")
+            ? pathOrUrl
+            : `${protocol}//${base.host}${pathOrUrl.startsWith("/") ? pathOrUrl : `/${pathOrUrl}`}`;
+        const response = await globalThis.fetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok) {
+            throw new Error(`Gateway media read failed: ${response.status} ${response.statusText}`);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async pluginsList() {
+        return await this.rpc("plugins.list", {});
+    }
+    async pluginsInstall(params) {
+        return await this.rpc("plugins.install", params, Math.max(PLUGIN_MUTATION_TIMEOUT, this.defaultTimeout));
+    }
+    async pluginsSetEnabled(params) {
+        return await this.rpc("plugins.setEnabled", params);
+    }
+    async pluginsUninstall(params) {
+        return await this.rpc("plugins.uninstall", params, Math.max(PLUGIN_MUTATION_TIMEOUT, this.defaultTimeout));
+    }
+    async pluginsRefresh() {
+        return await this.rpc("plugins.refresh", {});
+    }
+    async toolsCatalog(params = {}) {
+        return await this.rpc("tools.catalog", params);
+    }
+    async toolsEffective(params) {
+        return await this.rpc("tools.effective", params);
+    }
+    async toolsInvoke(params) {
+        return await this.rpc("tools.invoke", {
+            ...params,
+            idempotencyKey: params.idempotencyKey ?? makeId(),
+        });
+    }
+    async commandsList(params = {}) {
+        return await this.rpc("commands.list", params);
+    }
     async webLoginStart(options = {}) {
         const params = {};
         if (options.force)
@@ -1811,19 +2627,38 @@ export class GatewayClient {
             params.timeoutMs = options.timeoutMs;
         if (options.accountId)
             params.accountId = options.accountId;
-        return await this.rpc("web.login.wait", params, CHAT_TIMEOUT);
+        if (options.currentQrDataUrl)
+            params.currentQrDataUrl = options.currentQrDataUrl;
+        return await this.rpc("web.login.wait", params, WEB_LOGIN_WAIT_TIMEOUT);
     }
     // ---------------------------------------------------------------------------
     // Sessions
     // ---------------------------------------------------------------------------
-    async sessionsList() {
+    async sessionsListResult() {
         const res = await this.rpc("sessions.list");
-        return res?.sessions ?? res ?? [];
+        if (Array.isArray(res))
+            return { sessions: res };
+        if (!res || typeof res !== "object")
+            return { sessions: [] };
+        return {
+            ...res,
+            sessions: Array.isArray(res.sessions) ? res.sessions : [],
+        };
+    }
+    async sessionsList() {
+        return (await this.sessionsListResult()).sessions;
     }
     async sessionsPreview(sessionKey, limit = 20) {
         const res = await this.rpc("sessions.preview", { keys: [sessionKey], limit });
         return res?.previews?.[0]?.items ?? [];
     }
+    async sessionsSubscribe() {
+        const result = await this.rpc("sessions.subscribe", {});
+        return result?.subscribed === true;
+    }
+    async sessionsCreate(params = {}) {
+        return await this.rpc("sessions.create", params);
+    }
     async sessionsPatch(patch) {
         return await this.rpc("sessions.patch", patch);
     }
@@ -1832,7 +2667,14 @@ export class GatewayClient {
         if (sessionKey)
             params.sessionKey = sessionKey;
         const res = await this.rpc("chat.history", params);
-        return res?.messages ?? res ?? [];
+        if (Array.isArray(res))
+            return res;
+        if (asRecord(res) && Array.isArray(res.messages))
+            return res.messages;
+        throw new GatewayRequestError({
+            code: "PROTOCOL_ERROR",
+            message: "Gateway protocol error: chat.history response must be an array or an object with an array `messages` property",
+        });
     }
     async chatAbort(sessionKey) {
         const params = {};
@@ -1840,59 +2682,359 @@ export class GatewayClient {
             params.sessionKey = sessionKey;
         await this.rpc("chat.abort", params);
     }
-    async sendChat(message, sessionKey = "main", agentId, attachments) {
+    async sendChat(message, sessionKey, agentId, attachments) {
+        const resolvedSessionKey = sessionKey?.trim() || createOpenClawSdkSessionKey();
         const normalizedAttachments = normalizeChatAttachments(attachments);
         const params = {
             message,
             deliver: false,
-            sessionKey,
+            sessionKey: resolvedSessionKey,
             idempotencyKey: makeId(),
         };
         if (agentId)
             params.agentId = agentId;
         if (normalizedAttachments)
             params.attachments = normalizedAttachments;
-        return this.rpc("chat.send", params, CHAT_TIMEOUT);
+        return this.rpc("chat.send", params, DEFAULT_AGENT_TIMEOUT);
     }
     async sessionsReset(sessionKey, reason) {
         const params = { key: sessionKey };
         if (reason)
             params.reason = reason;
-        await this.rpc("sessions.reset", params);
+        const result = await this.rpc("sessions.reset", params);
+        const canonicalKey = result?.key ?? result?.sessionKey ?? result?.session?.key;
+        return typeof canonicalKey === "string" && canonicalKey.trim() ? canonicalKey.trim() : sessionKey;
+    }
+    async createEphemeralChatSession() {
+        if (!this.connected || !this.ws)
+            throw new Error("Not connected");
+        const requestedSessionKey = `${EPHEMERAL_SESSION_PREFIX}${makeId()}`;
+        const canonicalSessionKey = await this.sessionsReset(requestedSessionKey, "new");
+        const sessionKey = validateEphemeralCanonicalKey(requestedSessionKey, canonicalSessionKey);
+        if (!sessionKey) {
+            await this.sessionsReset(requestedSessionKey, "reset").catch(() => undefined);
+            throw new Error(`Gateway returned an unsafe ephemeral session key: ${canonicalSessionKey}`);
+        }
+        this.activeEphemeralSessionKeys.set(sessionKey, null);
+        let closed = false;
+        let activeStream = null;
+        let closePromise = null;
+        let turnsStarted = 0;
+        let backendTurnMayBeActive = false;
+        const priorAssistantTexts = [];
+        const assertOpen = () => {
+            if (closed)
+                throw new Error("Ephemeral chat session is closed.");
+        };
+        const session = {
+            sessionKey,
+            get closed() {
+                return closed;
+            },
+            chatSend: (message, attachments) => {
+                assertOpen();
+                if (activeStream || backendTurnMayBeActive) {
+                    throw new Error("Ephemeral chat session already has an active turn.");
+                }
+                normalizeChatAttachments(attachments);
+                const source = this.chatSend(message, sessionKey, attachments, {
+                    strictCorrelation: true,
+                    ephemeralSession: true,
+                    ...(turnsStarted > 0 ? { captureHistoryBaseline: true } : {}),
+                    ...(priorAssistantTexts.length > 0 ? { priorAssistantTexts: [...priorAssistantTexts] } : {}),
+                });
+                turnsStarted += 1;
+                backendTurnMayBeActive = true;
+                let turnText = "";
+                let turnRecorded = false;
+                const observeEvent = (event) => {
+                    turnText = applyChatEventContent(turnText, event);
+                    if (event.type !== "done" && event.type !== "error")
+                        return;
+                    backendTurnMayBeActive = false;
+                    if (event.type === "done" && turnText.trim() && !turnRecorded) {
+                        turnRecorded = true;
+                        priorAssistantTexts.push(turnText.trim());
+                    }
+                };
+                const release = () => {
+                    if (activeStream === stream)
+                        activeStream = null;
+                };
+                const stream = {
+                    async next(value) {
+                        try {
+                            const result = await source.next(value);
+                            if (result.done) {
+                                backendTurnMayBeActive = false;
+                                release();
+                            }
+                            else {
+                                observeEvent(result.value);
+                            }
+                            return result;
+                        }
+                        catch (error) {
+                            release();
+                            throw error;
+                        }
+                    },
+                    async return(value) {
+                        try {
+                            return await source.return(value);
+                        }
+                        finally {
+                            release();
+                        }
+                    },
+                    async throw(error) {
+                        try {
+                            const result = await source.throw(error);
+                            if (result.done) {
+                                backendTurnMayBeActive = false;
+                                release();
+                            }
+                            else {
+                                observeEvent(result.value);
+                            }
+                            return result;
+                        }
+                        catch (cause) {
+                            release();
+                            throw cause;
+                        }
+                    },
+                    [Symbol.asyncIterator]() {
+                        return stream;
+                    },
+                };
+                activeStream = stream;
+                return stream;
+            },
+            chatHistory: (limit = 50) => {
+                assertOpen();
+                return this.chatHistory(sessionKey, limit);
+            },
+            chatAbort: async () => {
+                assertOpen();
+                const stream = activeStream;
+                await this.chatAbort(sessionKey);
+                backendTurnMayBeActive = false;
+                if (stream && !await promiseSettlesWithin(stream.return(undefined), EPHEMERAL_TURN_CLOSE_WAIT_MS)) {
+                    throw new Error("Ephemeral chat turn is still stopping.");
+                }
+            },
+            close: () => {
+                if (closePromise)
+                    return closePromise;
+                closed = true;
+                const stream = activeStream;
+                const abortPromise = backendTurnMayBeActive
+                    ? this.chatAbort(sessionKey).then(() => {
+                        backendTurnMayBeActive = false;
+                        return true;
+                    }, () => false)
+                    : Promise.resolve(true);
+                const streamReturnPromise = stream?.return(undefined);
+                let cleanupComplete = false;
+                const attempt = (async () => {
+                    try {
+                        const backendStopped = await booleanPromiseWithin(abortPromise, EPHEMERAL_TURN_CLOSE_WAIT_MS);
+                        if (!backendStopped)
+                            throw new Error("Ephemeral chat turn did not stop before cleanup timed out.");
+                        if (streamReturnPromise) {
+                            await promiseSettlesWithin(streamReturnPromise, EPHEMERAL_TURN_CLOSE_WAIT_MS);
+                        }
+                        await this.sessionsReset(sessionKey, "reset");
+                        backendTurnMayBeActive = false;
+                        cleanupComplete = true;
+                    }
+                    finally {
+                        if (cleanupComplete) {
+                            this.activeEphemeralSessionKeys.delete(sessionKey);
+                        }
+                        else {
+                            this.activeEphemeralSessionKeys.set(sessionKey, Date.now() + EPHEMERAL_RUN_ID_SUPPRESSION_MS);
+                        }
+                    }
+                })();
+                closePromise = attempt;
+                void attempt.catch(() => {
+                    if (closePromise === attempt)
+                        closePromise = null;
+                });
+                return attempt;
+            },
+        };
+        return session;
+    }
+    // ---------------------------------------------------------------------------
+    // Nodes (operator-side: manage & drive paired nodes)
+    //
+    // A "node" is a device/machine connected to the same gateway with
+    // `role: "node"` that exposes a command surface. An operator lists/approves
+    // node pairings and drives them with `node.invoke`; the node executes the
+    // command locally and returns the result. This is the gateway's built-in
+    // "agent asks a connected machine to do X and use the result" path.
+    // ---------------------------------------------------------------------------
+    /** Paired nodes known to the gateway. */
+    async nodesList() {
+        const res = await this.rpc("node.list");
+        return res?.nodes ?? res ?? [];
+    }
+    /** Detailed metadata for one paired node (caps + supported invoke commands). */
+    async nodeDescribe(nodeId) {
+        return await this.rpc("node.describe", { nodeId });
+    }
+    /** Pending and paired node-pairing requests. */
+    async nodePairList() {
+        const res = await this.rpc("node.pair.list");
+        return { pending: res?.pending ?? [], paired: res?.paired ?? [] };
+    }
+    /**
+     * Approve a pending node pairing (and its declared command surface). This is
+     * the sibling of `device.pair.approve`; it requires `operator.pairing` and,
+     * for command-bearing nodes, `operator.write`/`operator.admin`.
+     */
+    async nodePairApprove(requestId) {
+        return await this.rpc("node.pair.approve", { requestId });
+    }
+    /** Reject a pending node pairing request. */
+    async nodePairReject(requestId) {
+        await this.rpc("node.pair.reject", { requestId });
+    }
+    /** Remove an already-paired node from the gateway trust set. */
+    async nodePairRemove(nodeId) {
+        await this.rpc("node.pair.remove", { nodeId });
+    }
+    /** Rename a paired node while preserving its stable node id. */
+    async nodeRename(nodeId, displayName) {
+        await this.rpc("node.rename", { nodeId, displayName });
+    }
+    /**
+     * Invoke a command on a paired node and return its result. The node must be
+     * connected, have declared `command`, and the command must be allowed by the
+     * gateway policy (declared + approved surface, and/or
+     * `gateway.nodes.allowCommands`).
+     */
+    async nodeInvoke(nodeId, command, params = {}, timeoutMs) {
+        const rpcParams = {
+            nodeId,
+            command,
+            params,
+            idempotencyKey: makeId(),
+        };
+        if (timeoutMs !== undefined)
+            rpcParams.timeoutMs = timeoutMs;
+        return await this.rpc("node.invoke", rpcParams, timeoutMs);
     }
     // ---------------------------------------------------------------------------
     // Chat (streaming via events)
     // ---------------------------------------------------------------------------
-    async *chatSend(message, sessionKey, attachments) {
+    async *chatSend(message, sessionKey, attachments, options = {}) {
         if (!this.connected || !this.ws) {
             throw new Error("Not connected");
         }
         const idempotencyKey = makeId();
         const acceptedRunIds = new Set([idempotencyKey]);
+        if (options.ephemeralSession)
+            this.suppressEphemeralRunId(idempotencyKey);
         const queuedEvents = [];
         let resolveWait = null;
-        let streamedDisplayText = false;
-        let lastLegacyText = "";
+        let correlationReady = false;
+        let emittedDisplayText = "";
         let lastThinkingText = "";
         const seenToolCallIds = new Set();
         const seenToolResultIds = new Set();
+        let acknowledgementPending = false;
+        let historyBaseline;
+        let streamCloseError = null;
+        let resolveStreamClose = null;
+        const streamClosed = new Promise((resolve) => {
+            resolveStreamClose = resolve;
+        });
+        let streamState = null;
+        const wakeWaiter = () => {
+            const waiter = resolveWait;
+            resolveWait = null;
+            waiter?.();
+        };
+        const closeHandler = (error) => {
+            if (streamCloseError)
+                return;
+            streamCloseError = error;
+            this.internalEventHandlers.delete(handler);
+            this.internalStreamCloseHandlers.delete(closeHandler);
+            if (streamState) {
+                this.activeNormalChatStreams.delete(streamState);
+                this.activeStrictChatStreams.delete(streamState);
+            }
+            resolveStreamClose?.(error);
+            wakeWaiter();
+        };
+        const stopOnStreamClose = async (promise) => {
+            return await Promise.race([
+                promise,
+                streamClosed.then((error) => Promise.reject(error)),
+            ]);
+        };
         const handler = (evt) => {
-            const isAgentStreamEvent = evt.event === "agent" &&
-                (() => {
-                    const payload = asRecord(evt.payload) ?? {};
-                    const stream = typeof payload.stream === "string" ? payload.stream.toLowerCase() : "";
-                    return stream === "tool" || stream === "lifecycle";
-                })();
-            if (evt.event === "chat" || evt.event?.startsWith("chat.") || isAgentStreamEvent) {
-                queuedEvents.push(evt);
-                const waiter = resolveWait;
-                resolveWait = null;
-                waiter?.();
+            if (!isChatStreamGatewayEvent(evt))
+                return false;
+            const payload = asRecord(evt.payload) ?? {};
+            const identity = chatEventIdentity(payload);
+            const payloadRunId = identity.runId?.trim() ?? "";
+            const payloadSessionKey = identity.sessionKey?.trim() ?? "";
+            if (payloadSessionKey && !sameSessionKey(payloadSessionKey, sessionKey))
+                return false;
+            if (payloadRunId && correlationReady && !acceptedRunIds.has(payloadRunId))
+                return false;
+            if (options.strictCorrelation) {
+                if (!payloadRunId && !payloadSessionKey)
+                    return false;
+                if (options.ephemeralSession &&
+                    !correlationReady &&
+                    payloadRunId &&
+                    !payloadSessionKey &&
+                    !acceptedRunIds.has(payloadRunId)) {
+                    this.deferEphemeralCorrelationEvent(evt);
+                }
+            }
+            queuedEvents.push(evt);
+            if (correlationReady && isTerminalChatStreamGatewayEvent(evt) && streamState) {
+                streamState.terminalEvent = evt;
             }
+            wakeWaiter();
+            return options.strictCorrelation === true;
         };
-        this.eventHandlers.add(handler);
+        streamState = { close: closeHandler, terminalEvent: null };
         try {
+            if (options.captureHistoryBaseline) {
+                try {
+                    historyBaseline = historyAssistantBaseline(await this.chatHistory(sessionKey, 20), options.priorAssistantTexts);
+                }
+                catch {
+                    historyBaseline = options.priorAssistantTexts?.length
+                        ? historyAssistantBaseline([], options.priorAssistantTexts)
+                        : null;
+                }
+            }
+            else if (options.priorAssistantTexts) {
+                historyBaseline = historyAssistantBaseline([], options.priorAssistantTexts);
+            }
             const normalizedAttachments = normalizeChatAttachments(attachments);
+            if (options.ephemeralSession) {
+                this.beginEphemeralChatAcknowledgement();
+                acknowledgementPending = true;
+            }
+            this.internalEventHandlers.add(handler);
+            this.internalStreamCloseHandlers.add(closeHandler);
+            if (options.strictCorrelation) {
+                this.activeStrictChatStreams.add(streamState);
+            }
+            else {
+                this.activeNormalChatStreams.add(streamState);
+            }
             const params = {
                 message,
                 deliver: false,
@@ -1901,25 +3043,75 @@ export class GatewayClient {
             };
             if (normalizedAttachments)
                 params.attachments = normalizedAttachments;
-            const ack = await this.rpc("chat.send", params, CHAT_TIMEOUT);
+            const ack = await stopOnStreamClose(this.rpc("chat.send", params, DEFAULT_AGENT_TIMEOUT));
             const serverRunId = typeof ack?.runId === "string" ? ack.runId.trim() : "";
             if (serverRunId) {
                 acceptedRunIds.add(serverRunId);
+                if (options.ephemeralSession)
+                    this.suppressEphemeralRunId(serverRunId);
             }
+            correlationReady = true;
+            if (queuedEvents.length > 0) {
+                for (let index = queuedEvents.length - 1; index >= 0; index -= 1) {
+                    const payload = asRecord(queuedEvents[index]?.payload) ?? {};
+                    const identity = chatEventIdentity(payload);
+                    const queuedRunId = identity.runId?.trim() ?? "";
+                    const queuedSessionKey = identity.sessionKey?.trim() ?? "";
+                    const mismatchedSession = Boolean(queuedSessionKey && !sameSessionKey(queuedSessionKey, sessionKey));
+                    const unacceptedRun = Boolean(queuedRunId && !acceptedRunIds.has(queuedRunId));
+                    if (mismatchedSession || unacceptedRun) {
+                        queuedEvents.splice(index, 1);
+                    }
+                }
+                streamState.terminalEvent =
+                    [...queuedEvents].reverse().find(isTerminalChatStreamGatewayEvent) ?? null;
+            }
+            if (acknowledgementPending) {
+                acknowledgementPending = false;
+                this.finishEphemeralChatAcknowledgement(Boolean(serverRunId));
+            }
+            const readLatestHistoryText = async () => {
+                try {
+                    return latestHistoryAssistantText(await stopOnStreamClose(this.chatHistory(sessionKey, 20)), acceptedRunIds, historyBaseline) ?? "";
+                }
+                catch (error) {
+                    if (streamCloseError)
+                        throw error;
+                    return "";
+                }
+            };
             const waitForHistoryText = async (timeoutMs = 10_000) => {
-                const historyDeadline = Date.now() + Math.min(timeoutMs, CHAT_TIMEOUT);
+                const historyDeadline = Date.now() + Math.min(timeoutMs, DEFAULT_AGENT_TIMEOUT);
                 while (true) {
-                    const historyText = latestHistoryAssistantText(await this.chatHistory(sessionKey, 20), acceptedRunIds);
+                    const historyText = await readLatestHistoryText();
                     if (historyText)
                         return historyText;
                     if (Date.now() >= historyDeadline)
                         return "";
-                    await new Promise((resolve) => setTimeout(resolve, 500));
+                    await stopOnStreamClose(new Promise((resolve) => setTimeout(resolve, 500)));
+                }
+            };
+            const reconcileHistoryAfterToolActivity = async (streamedText) => {
+                let historyText = await readLatestHistoryText();
+                if (!historyText || historyText !== streamedText)
+                    return historyText;
+                const historyDeadline = Date.now() + 1_500;
+                while (Date.now() < historyDeadline) {
+                    await stopOnStreamClose(new Promise((resolve) => setTimeout(resolve, 500)));
+                    const nextHistoryText = await readLatestHistoryText();
+                    if (!nextHistoryText)
+                        continue;
+                    historyText = nextHistoryText;
+                    if (historyText !== streamedText)
+                        break;
                 }
+                return historyText;
             };
-            let deadline = Date.now() + CHAT_TIMEOUT;
+            let deadline = Date.now() + DEFAULT_AGENT_TIMEOUT;
             while (Date.now() < deadline) {
                 if (queuedEvents.length === 0) {
+                    if (streamCloseError)
+                        throw streamCloseError;
                     const remainingMs = Math.max(100, Math.min(1000, deadline - Date.now()));
                     await new Promise((resolve) => {
                         const timer = setTimeout(() => {
@@ -1934,24 +3126,34 @@ export class GatewayClient {
                         };
                         resolveWait = release;
                     });
+                    if (queuedEvents.length === 0 && streamCloseError)
+                        throw streamCloseError;
                     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() : "";
+                const routingIdentity = chatEventIdentity(payload);
+                const payloadRunId = routingIdentity.runId?.trim() ?? "";
+                const payloadSessionKey = routingIdentity.sessionKey?.trim() ?? "";
                 if (payloadRunId && !acceptedRunIds.has(payloadRunId)) {
                     continue;
                 }
                 if (payloadSessionKey && !sameSessionKey(payloadSessionKey, sessionKey)) {
                     continue;
                 }
-                deadline = Date.now() + CHAT_TIMEOUT;
+                const identity = chatEventIdentity(payload);
+                deadline = Date.now() + DEFAULT_AGENT_TIMEOUT;
                 if (evt.event === "chat.content") {
                     const text = typeof payload.text === "string" ? payload.text : "";
-                    if (text) {
-                        streamedDisplayText = true;
-                        yield { type: "content", text };
+                    const update = appendStreamContent(emittedDisplayText, text, payload.replace === true);
+                    if (update) {
+                        emittedDisplayText = update.nextText;
+                        yield {
+                            type: "content",
+                            text: update.text,
+                            ...(update.replace ? { replace: true } : {}),
+                            ...identity,
+                        };
                     }
                     continue;
                 }
@@ -1964,6 +3166,7 @@ export class GatewayClient {
                         seenToolCallIds.add(toolCallId);
                         yield {
                             type: "tool_call",
+                            ...identity,
                             data: {
                                 ...gatewayToolStreamPayload(toolPayload),
                                 args: toolPayload.args,
@@ -1974,6 +3177,7 @@ export class GatewayClient {
                         seenToolResultIds.add(toolCallId);
                         yield {
                             type: "tool_result",
+                            ...identity,
                             data: {
                                 ...gatewayToolStreamPayload(toolPayload),
                                 result: toolPayload.result ?? toolPayload.meta ?? toolPayload.content ?? toolPayload.text ?? toolPayload.partialResult,
@@ -1988,20 +3192,29 @@ export class GatewayClient {
                     const phase = typeof lifecyclePayload.phase === "string" ? lifecyclePayload.phase.toLowerCase() : "";
                     if (phase === "end") {
                         const hasNonTextActivity = Boolean(lastThinkingText) || seenToolCallIds.size > 0 || seenToolResultIds.size > 0;
-                        const historyText = hasNonTextActivity
-                            ? ""
-                            : streamedDisplayText || lastLegacyText
-                                ? latestHistoryAssistantText(await this.chatHistory(sessionKey, 20), acceptedRunIds)
-                                : await waitForHistoryText();
+                        const historyText = emittedDisplayText && hasNonTextActivity
+                            ? await reconcileHistoryAfterToolActivity(emittedDisplayText)
+                            : emittedDisplayText
+                                ? await readLatestHistoryText()
+                                : hasNonTextActivity
+                                    ? ""
+                                    : await waitForHistoryText();
+                        if (queuedEvents.length > 0)
+                            continue;
                         if (historyText) {
-                            const streamed = streamDelta(lastLegacyText, historyText);
-                            lastLegacyText = streamed.nextText;
-                            if (streamed.delta) {
-                                streamedDisplayText = true;
-                                yield { type: "content", text: streamed.delta, data: payload };
+                            const update = reconcileStreamContent(emittedDisplayText, historyText);
+                            if (update) {
+                                emittedDisplayText = update.nextText;
+                                yield {
+                                    type: "content",
+                                    text: update.text,
+                                    ...(update.replace ? { replace: true } : {}),
+                                    ...identity,
+                                    data: payload,
+                                };
                             }
                         }
-                        yield { type: "done", data: payload };
+                        yield { type: "done", ...identity, data: payload };
                         return;
                     }
                     if (phase === "error") {
@@ -2012,6 +3225,7 @@ export class GatewayClient {
                                 : typeof payload.errorMessage === "string" && payload.errorMessage
                                     ? payload.errorMessage
                                     : phase,
+                            ...identity,
                             data: payload,
                         };
                         return;
@@ -2023,38 +3237,51 @@ export class GatewayClient {
                     if (text) {
                         lastThinkingText += text;
                     }
-                    yield { type: "thinking", text };
+                    yield { type: "thinking", text, ...identity };
                     continue;
                 }
                 if (evt.event === "chat.tool_call") {
                     const toolCallId = gatewayToolCallId(payload) ??
                         `${gatewayToolName(payload) ?? "tool"}:${JSON.stringify(payload.args ?? payload.arguments ?? null)}`;
                     seenToolCallIds.add(toolCallId);
-                    yield { type: "tool_call", data: payload };
+                    yield { type: "tool_call", ...identity, data: payload };
                     continue;
                 }
                 if (evt.event === "chat.tool_result") {
                     const toolCallId = gatewayToolCallId(payload) ??
                         `${gatewayToolName(payload) ?? "tool"}:${JSON.stringify(payload.args ?? payload.arguments ?? null)}`;
                     seenToolResultIds.add(toolCallId);
-                    yield { type: "tool_result", data: payload };
+                    yield { type: "tool_result", ...identity, data: payload };
                     continue;
                 }
                 if (evt.event === "chat.done") {
                     const hasNonTextActivity = Boolean(lastThinkingText) || seenToolCallIds.size > 0 || seenToolResultIds.size > 0;
-                    if (!streamedDisplayText && !lastLegacyText && !hasNonTextActivity) {
-                        const historyText = await waitForHistoryText();
-                        if (historyText) {
-                            yield { type: "content", text: historyText, data: payload };
+                    const historyText = emittedDisplayText && hasNonTextActivity
+                        ? await reconcileHistoryAfterToolActivity(emittedDisplayText)
+                        : !emittedDisplayText && !hasNonTextActivity
+                            ? await waitForHistoryText()
+                            : "";
+                    if (historyText) {
+                        const update = reconcileStreamContent(emittedDisplayText, historyText);
+                        if (update) {
+                            emittedDisplayText = update.nextText;
+                            yield {
+                                type: "content",
+                                text: update.text,
+                                ...(update.replace ? { replace: true } : {}),
+                                ...identity,
+                                data: payload,
+                            };
                         }
                     }
-                    yield { type: "done", data: payload };
+                    yield { type: "done", ...identity, data: payload };
                     return;
                 }
                 if (evt.event === "chat.error") {
                     yield {
                         type: "error",
                         text: typeof payload.message === "string" ? payload.message : "Unknown error",
+                        ...identity,
                         data: payload,
                     };
                     return;
@@ -2063,24 +3290,22 @@ export class GatewayClient {
                     continue;
                 }
                 const state = typeof payload.state === "string" ? payload.state.trim().toLowerCase() : "";
-                const currentText = extractMessageText(payload.message) ?? "";
+                const currentText = extractMessageText(payload.message);
                 const currentDeltaText = typeof payload.deltaText === "string" ? payload.deltaText : "";
                 const normalizedMessage = normalizeGatewayChatMessage(payload.message);
                 if (state === "delta") {
-                    const streamed = currentText
-                        ? streamDelta(lastLegacyText, currentText)
-                        : {
-                            delta: currentDeltaText,
-                            nextText: currentDeltaText
-                                ? payload.replace === true
-                                    ? currentDeltaText
-                                    : lastLegacyText + currentDeltaText
-                                : lastLegacyText,
+                    const update = currentText !== null && (currentText || payload.replace === true)
+                        ? reconcileStreamContent(emittedDisplayText, currentText, payload.replace === true)
+                        : appendStreamContent(emittedDisplayText, currentDeltaText, payload.replace === true);
+                    if (update) {
+                        emittedDisplayText = update.nextText;
+                        yield {
+                            type: "content",
+                            text: update.text,
+                            ...(update.replace ? { replace: true } : {}),
+                            ...identity,
+                            data: payload,
                         };
-                    lastLegacyText = streamed.nextText;
-                    if (streamed.delta) {
-                        streamedDisplayText = true;
-                        yield { type: "content", text: streamed.delta, data: payload };
                     }
                     continue;
                 }
@@ -2090,7 +3315,7 @@ export class GatewayClient {
                         : { delta: "", nextText: lastThinkingText };
                     lastThinkingText = thinkingDelta.nextText;
                     if (thinkingDelta.delta) {
-                        yield { type: "thinking", text: thinkingDelta.delta, data: payload };
+                        yield { type: "thinking", text: thinkingDelta.delta, ...identity, data: payload };
                     }
                     for (const toolCall of normalizedMessage?.toolCalls ?? []) {
                         const toolCallKey = toolCall.id?.trim() ||
@@ -2099,6 +3324,7 @@ export class GatewayClient {
                             seenToolCallIds.add(toolCallKey);
                             yield {
                                 type: "tool_call",
+                                ...identity,
                                 data: {
                                     ...(toolCall.id ? { toolCallId: toolCall.id } : {}),
                                     name: toolCall.name,
@@ -2110,6 +3336,7 @@ export class GatewayClient {
                             seenToolResultIds.add(toolCallKey);
                             yield {
                                 type: "tool_result",
+                                ...identity,
                                 data: {
                                     ...(toolCall.id ? { toolCallId: toolCall.id } : {}),
                                     name: toolCall.name,
@@ -2118,53 +3345,242 @@ export class GatewayClient {
                             };
                         }
                     }
-                    if (currentText) {
-                        const streamed = streamDelta(lastLegacyText, currentText);
-                        lastLegacyText = streamed.nextText;
-                        if (streamed.delta) {
-                            streamedDisplayText = true;
-                            yield { type: "content", text: streamed.delta, data: payload };
+                    if (currentText !== null && (currentText || payload.replace === true)) {
+                        const update = reconcileStreamContent(emittedDisplayText, currentText, payload.replace === true);
+                        if (update) {
+                            emittedDisplayText = update.nextText;
+                            yield {
+                                type: "content",
+                                text: update.text,
+                                ...(update.replace ? { replace: true } : {}),
+                                ...identity,
+                                data: payload,
+                            };
                         }
-                        yield { type: "done", data: payload };
+                        yield { type: "done", ...identity, data: payload };
                         return;
                     }
-                    if (streamedDisplayText || lastLegacyText) {
-                        yield { type: "done", data: payload };
+                    if (emittedDisplayText) {
+                        yield { type: "done", ...identity, data: payload };
                         return;
                     }
                     if (normalizedMessage?.thinking || (normalizedMessage?.toolCalls.length ?? 0) > 0) {
-                        yield { type: "done", data: payload };
+                        yield { type: "done", ...identity, data: payload };
                         return;
                     }
                     const historyText = await waitForHistoryText();
                     if (historyText) {
-                        yield { type: "content", text: historyText, data: payload };
+                        const update = reconcileStreamContent(emittedDisplayText, historyText);
+                        if (update) {
+                            emittedDisplayText = update.nextText;
+                            yield {
+                                type: "content",
+                                text: update.text,
+                                ...(update.replace ? { replace: true } : {}),
+                                ...identity,
+                                data: payload,
+                            };
+                        }
                     }
-                    yield { type: "done", data: payload };
+                    yield { type: "done", ...identity, 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 };
+                    if (currentText !== null && (currentText || payload.replace === true)) {
+                        const update = reconcileStreamContent(emittedDisplayText, currentText, payload.replace === true);
+                        if (update) {
+                            emittedDisplayText = update.nextText;
+                            yield {
+                                type: "content",
+                                text: update.text,
+                                ...(update.replace ? { replace: true } : {}),
+                                ...identity,
+                                data: payload,
+                            };
                         }
                     }
                     yield {
                         type: "error",
                         text: typeof payload.errorMessage === "string" ? payload.errorMessage : state,
+                        ...identity,
                         data: payload,
                     };
                     return;
                 }
             }
+            if (streamCloseError)
+                throw streamCloseError;
             throw new Error("Streaming chat.send timed out");
         }
         finally {
-            this.eventHandlers.delete(handler);
+            if (acknowledgementPending)
+                this.finishEphemeralChatAcknowledgement(false);
+            this.internalEventHandlers.delete(handler);
+            this.internalStreamCloseHandlers.delete(closeHandler);
+            this.activeNormalChatStreams.delete(streamState);
+            this.activeStrictChatStreams.delete(streamState);
+        }
+    }
+    async runEphemeralChat(message, options = {}) {
+        const prompt = message.trim();
+        if (!prompt)
+            throw new Error("Ephemeral chat requires a message.");
+        if (!this.connected || !this.ws)
+            throw new Error("Not connected");
+        const timeoutMs = options.timeoutMs ?? DEFAULT_AGENT_TIMEOUT;
+        const maxResponseChars = options.maxResponseChars ?? 128 * 1024;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > DEFAULT_AGENT_TIMEOUT) {
+            throw new Error(`Ephemeral chat timeout must be between 1 and ${DEFAULT_AGENT_TIMEOUT} milliseconds.`);
+        }
+        if (!Number.isSafeInteger(maxResponseChars) || maxResponseChars <= 0) {
+            throw new Error("Ephemeral chat response limit must be a positive integer.");
+        }
+        let session = null;
+        let terminal = false;
+        let stream = null;
+        let stopError = null;
+        let abortPromise = null;
+        let primaryError = null;
+        let cleanupError = null;
+        let resultContent = null;
+        let resolveStop = null;
+        const stopped = new Promise((resolve) => {
+            resolveStop = resolve;
+        });
+        const requestAbort = (error) => {
+            if (!stopError) {
+                stopError = error;
+                resolveStop?.(error);
+            }
+            if (session && !terminal && !abortPromise) {
+                abortPromise = session.chatAbort().catch(() => undefined);
+            }
+            void stream?.return(undefined).catch(() => undefined);
+        };
+        const dispatchEvent = async (event) => {
+            if (!options.onEvent)
+                return;
+            await Promise.race([
+                Promise.resolve().then(() => options.onEvent?.(event)),
+                stopped.then((error) => Promise.reject(error)),
+            ]);
+        };
+        const abortError = () => {
+            const error = new Error("Ephemeral chat was cancelled.");
+            error.name = "AbortError";
+            return error;
+        };
+        const handleSignalAbort = () => requestAbort(abortError());
+        const timeout = setTimeout(() => requestAbort(new Error("Ephemeral chat timed out.")), timeoutMs);
+        options.signal?.addEventListener("abort", handleSignalAbort, { once: true });
+        try {
+            if (options.signal?.aborted)
+                throw abortError();
+            session = await this.createEphemeralChatSession();
+            if (options.signal?.aborted)
+                throw abortError();
+            if (stopError)
+                throw stopError;
+            if (options.fastMode) {
+                let fastModeTerminal = false;
+                stream = session.chatSend("/fast on");
+                while (true) {
+                    const next = await Promise.race([
+                        stream.next(),
+                        stopped.then((error) => Promise.reject(error)),
+                    ]);
+                    if (next.done)
+                        break;
+                    const event = next.value;
+                    if (event.type === "error") {
+                        fastModeTerminal = true;
+                        throw new Error(event.text || "Ephemeral fast mode failed.");
+                    }
+                    if (event.type === "done") {
+                        fastModeTerminal = true;
+                        break;
+                    }
+                }
+                await stream.return(undefined).catch(() => undefined);
+                stream = null;
+                if (stopError)
+                    throw stopError;
+                if (!fastModeTerminal)
+                    throw new Error("Ephemeral fast mode ended without completing.");
+            }
+            let content = "";
+            stream = session.chatSend(prompt);
+            while (true) {
+                const next = await Promise.race([
+                    stream.next(),
+                    stopped.then((error) => Promise.reject(error)),
+                ]);
+                if (next.done)
+                    break;
+                const event = next.value;
+                if (stopError)
+                    throw stopError;
+                if (event.type === "content") {
+                    content = applyChatEventContent(content, event);
+                    if (content.length > maxResponseChars) {
+                        const error = new Error("Ephemeral chat response exceeds the configured limit.");
+                        requestAbort(error);
+                        throw error;
+                    }
+                }
+                await dispatchEvent(event);
+                if (event.type === "error") {
+                    terminal = true;
+                    throw new Error(event.text || "Ephemeral chat failed.");
+                }
+                else if (event.type === "done") {
+                    terminal = true;
+                }
+            }
+            if (stopError)
+                throw stopError;
+            if (!terminal)
+                throw new Error("Ephemeral chat ended without completing.");
+            if (!content.trim())
+                throw new Error("Ephemeral chat returned an empty response.");
+            resultContent = content;
         }
+        catch (error) {
+            if (session && !terminal)
+                requestAbort(error instanceof Error ? error : new Error("Ephemeral chat failed."));
+            await abortPromise;
+            primaryError = stopError ?? error;
+        }
+        finally {
+            clearTimeout(timeout);
+            options.signal?.removeEventListener("abort", handleSignalAbort);
+            if (stream && !primaryError) {
+                await promiseSettlesWithin(stream.return(undefined), EPHEMERAL_TURN_CLOSE_WAIT_MS);
+            }
+            if (session) {
+                try {
+                    await session.close();
+                }
+                catch (error) {
+                    cleanupError = error;
+                }
+            }
+        }
+        if (primaryError && cleanupError) {
+            const primaryMessage = primaryError instanceof Error ? primaryError.message : String(primaryError);
+            const cleanupMessage = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+            const combinedError = new Error(`${primaryMessage} Private chat cleanup also failed: ${cleanupMessage}`);
+            combinedError.name = primaryError instanceof Error ? primaryError.name : "Error";
+            combinedError.cause = cleanupError;
+            throw combinedError;
+        }
+        if (primaryError)
+            throw primaryError;
+        if (cleanupError)
+            throw cleanupError;
+        if (resultContent === null)
+            throw new Error("Ephemeral chat ended without a result.");
+        return resultContent;
     }
     // ---------------------------------------------------------------------------
     // Files (agent workspace files)
@@ -2223,4 +3639,115 @@ export class GatewayClient {
         return this.rpc("status");
     }
 }
+function createGatewayRequestAbortError(method) {
+    const err = new Error(`gateway request aborted for ${method}`);
+    err.name = "AbortError";
+    return err;
+}
+function coerceNodeInvokeRequest(payload) {
+    if (!payload || typeof payload !== "object") {
+        return null;
+    }
+    const obj = payload;
+    const id = typeof obj.id === "string" ? obj.id.trim() : "";
+    const nodeId = typeof obj.nodeId === "string" ? obj.nodeId.trim() : "";
+    const command = typeof obj.command === "string" ? obj.command.trim() : "";
+    if (!id || !nodeId || !command) {
+        return null;
+    }
+    const paramsJSON = typeof obj.paramsJSON === "string"
+        ? obj.paramsJSON
+        : obj.params !== undefined
+            ? JSON.stringify(obj.params)
+            : null;
+    return { id, nodeId, command, paramsJSON };
+}
+/**
+ * Serve a node command surface over a gateway connection. Wraps a
+ * {@link GatewayClient} connected as `role: "node"`, subscribes to
+ * `node.invoke.request`, dispatches to the registered handlers, and replies with
+ * `node.invoke.result` (JSON-encoded payload on success, or an error).
+ */
+export class NodeServer {
+    gateway;
+    handlers;
+    unsubscribe = null;
+    constructor(commands, options) {
+        this.handlers = { ...commands };
+        const nodeId = options.nodeId?.trim() || undefined;
+        this.gateway = new GatewayClient({
+            ...options,
+            clientId: options.clientId ?? "node-host",
+            clientMode: "node",
+            role: "node",
+            scopes: [],
+            caps: options.caps ?? [],
+            commands: Object.keys(this.handlers),
+            ...(nodeId ? { instanceId: nodeId } : {}),
+        });
+    }
+    /** Connect as a node and start answering invoke requests. Resolves once connected. */
+    async start() {
+        if (!this.unsubscribe) {
+            this.unsubscribe = this.gateway.onEvent((event) => {
+                if (event.event === "node.invoke.request") {
+                    void this.handleInvoke(event.payload);
+                }
+            });
+        }
+        await this.gateway.connect();
+    }
+    /** Stop answering requests and disconnect. */
+    stop() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.gateway.stop();
+    }
+    async handleInvoke(payload) {
+        const frame = coerceNodeInvokeRequest(payload);
+        if (!frame) {
+            return;
+        }
+        const result = await this.dispatch(frame);
+        try {
+            await this.gateway.request("node.invoke.result", {
+                id: frame.id,
+                nodeId: frame.nodeId,
+                ...result,
+            });
+        }
+        catch {
+            // node invoke replies are best-effort; the gateway times out stale ids.
+        }
+    }
+    async dispatch(frame) {
+        const handler = this.handlers[frame.command];
+        if (!handler) {
+            return {
+                ok: false,
+                error: { code: "INVALID_REQUEST", message: `command not supported: ${frame.command}` },
+            };
+        }
+        let params;
+        try {
+            params = frame.paramsJSON ? JSON.parse(frame.paramsJSON) : {};
+        }
+        catch {
+            return {
+                ok: false,
+                error: { code: "INVALID_REQUEST", message: "paramsJSON malformed JSON" },
+            };
+        }
+        try {
+            const result = await handler(params);
+            return { ok: true, payloadJSON: JSON.stringify(result === undefined ? null : result) };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: { code: "UNAVAILABLE", message: err instanceof Error ? err.message : String(err) },
+            };
+        }
+    }
+}
 //# sourceMappingURL=gateway.js.map