@elizaos/ui 2.0.0-beta.2 → 2.0.3-beta.3

package/api/client-base.js

@@ -4,9 +4,11 @@
  * Separated from client.ts so domain augmentation files can import the class
  * without circular dependency issues.
  */
+import { extractAssistantReplyText, stripAssistantStageDirections, } from "@elizaos/shared";
 import { getBootConfig, setBootConfig } from "../config/boot-config.js";
-import { hydrateAndroidLocalAgentTokenForUrl } from "../onboarding/local-agent-token.js";
-import { stripAssistantStageDirections } from "../utils/assistant-text.js";
+import { NETWORK_STATUS_CHANGE_EVENT, } from "../events/index.js";
+import { hydrateAndroidLocalAgentTokenForUrl } from "../first-run/local-agent-token.js";
+import { isMobileLocalAgentIpcUrl } from "../first-run/mobile-runtime-mode.js";
 import { clearElizaApiBase, clearElizaApiToken, getElizaApiBase, getElizaApiToken, setElizaApiBase, setElizaApiToken, } from "../utils/eliza-globals.js";
 import { mergeStreamingText } from "../utils/streaming-text.js";
 import { androidNativeAgentTransportForUrl } from "./android-native-agent-transport.js";
@@ -27,6 +29,36 @@ const ELIZA_CLOUD_CONTROL_PLANE_HOSTS = new Set([
     "www.elizacloud.ai",
     "dev.elizacloud.ai",
 ]);
+const REPLAYABLE_WS_EVENT_TYPES = new Set(["shell:navigate:view"]);
+const WS_EVENT_BACKLOG_LIMIT = 8;
+const CHAT_TURN_STATUS_KINDS = new Set([
+    "thinking",
+    "streaming",
+    "running_action",
+    "running_tool",
+    "evaluating",
+    "waking",
+    "speaking",
+]);
+/** Build a typed ChatTurnStatus from a `type: "status"` SSE event, or null when
+ *  the `kind` is missing/unknown (defensive: a future server kind is ignored,
+ *  not crashed on). */
+function parseChatTurnStatus(parsed) {
+    if (!parsed.kind || !CHAT_TURN_STATUS_KINDS.has(parsed.kind))
+        return null;
+    return {
+        kind: parsed.kind,
+        ...(typeof parsed.label === "string" && parsed.label
+            ? { label: parsed.label }
+            : {}),
+        ...(typeof parsed.actionName === "string" && parsed.actionName
+            ? { actionName: parsed.actionName }
+            : {}),
+        ...(typeof parsed.toolName === "string" && parsed.toolName
+            ? { toolName: parsed.toolName }
+            : {}),
+    };
+}
 function normalizeBaseUrl(value) {
     const trimmed = value?.slice(0, 4096).trim() ?? "";
     let end = trimmed.length;
@@ -45,6 +77,257 @@ function isElizaCloudControlPlaneBase(value) {
         return false;
     }
 }
+function findSseEventBreak(chunkBuffer) {
+    const lfBreak = chunkBuffer.indexOf("\n\n");
+    const crlfBreak = chunkBuffer.indexOf("\r\n\r\n");
+    if (lfBreak === -1 && crlfBreak === -1)
+        return null;
+    if (lfBreak === -1)
+        return { index: crlfBreak, length: 4 };
+    if (crlfBreak === -1)
+        return { index: lfBreak, length: 2 };
+    return lfBreak < crlfBreak
+        ? { index: lfBreak, length: 2 }
+        : { index: crlfBreak, length: 4 };
+}
+function parseStreamChatDataLine(line) {
+    const payload = line.startsWith("data:") ? line.slice(5).trim() : "";
+    if (!payload)
+        return null;
+    try {
+        const parsed = JSON.parse(payload);
+        if (!parsed.type && typeof parsed.text === "string")
+            parsed.type = "token";
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function applyStreamChatTokenEvent(parsed, state, onToken) {
+    const chunk = parsed.text ?? "";
+    const nextFullText = typeof parsed.fullText === "string"
+        ? parsed.fullText
+        : chunk
+            ? mergeStreamingText(state.fullText, chunk)
+            : state.fullText;
+    if (nextFullText === state.fullText)
+        return false;
+    state.fullText = nextFullText;
+    onToken(chunk, state.fullText);
+    return false;
+}
+function applyStreamChatDoneEvent(parsed, state) {
+    state.receivedDone = true;
+    if (typeof parsed.fullText === "string")
+        state.doneText = parsed.fullText;
+    if (typeof parsed.agentName === "string" && parsed.agentName.trim()) {
+        state.doneAgentName = parsed.agentName;
+    }
+    if (typeof parsed.thought === "string" && parsed.thought.trim()) {
+        state.doneThought = parsed.thought;
+    }
+    if (parsed.noResponseReason === "ignored") {
+        state.doneNoResponseReason = "ignored";
+    }
+    if (typeof parsed.failureKind === "string") {
+        state.doneFailureKind = parsed.failureKind;
+    }
+    if (parsed.localInference && typeof parsed.localInference === "object") {
+        state.doneLocalInference = parsed.localInference;
+    }
+    if (Array.isArray(parsed.actionResults)) {
+        state.doneActionResults = parsed.actionResults;
+    }
+    if (parsed.usage) {
+        state.doneUsage = {
+            promptTokens: parsed.usage.promptTokens ?? 0,
+            completionTokens: parsed.usage.completionTokens ?? 0,
+            totalTokens: parsed.usage.totalTokens ?? 0,
+            model: parsed.usage.model,
+        };
+    }
+    return true;
+}
+function applyStreamChatDataLine(line, state, onToken, onStatus) {
+    const parsed = parseStreamChatDataLine(line);
+    if (!parsed)
+        return false;
+    if (parsed.type === "token") {
+        return applyStreamChatTokenEvent(parsed, state, onToken);
+    }
+    if (parsed.type === "status") {
+        // Additive: a non-terminal status event. Surface it (when a consumer wants
+        // it) and keep reading — it never ends the stream.
+        if (onStatus) {
+            const status = parseChatTurnStatus(parsed);
+            if (status)
+                onStatus(status);
+        }
+        return false;
+    }
+    if (parsed.type === "done") {
+        return applyStreamChatDoneEvent(parsed, state);
+    }
+    if (parsed.type === "error") {
+        throw new Error(parsed.message ?? "generation failed");
+    }
+    return false;
+}
+function isLocalAgentIpcBase(value) {
+    const normalized = normalizeBaseUrl(value);
+    if (!normalized)
+        return false;
+    return isMobileLocalAgentIpcUrl(normalized);
+}
+function isSharedRuntimeRestAdapterBase(value) {
+    const normalized = normalizeBaseUrl(value);
+    if (!normalized)
+        return false;
+    try {
+        const url = new URL(normalized);
+        // Shared-runtime agents are served by the Cloud Worker over REST/SSE, not
+        // by a stateful agent server with `/ws`. Treat both the current adapter
+        // base and the legacy bridge base as connected so the shell does not show
+        // the lost-connection overlay while REST chat remains usable.
+        return /^\/api\/v1\/eliza\/agents\/[^/]+(?:\/bridge)?$/.test(url.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function shouldTreatAsConnectedWithoutWebSocket(value) {
+    return (isIosInProcessLocalAgentBase(value) ||
+        isLocalAgentIpcBase(value) ||
+        isSharedRuntimeRestAdapterBase(value) ||
+        isDedicatedCloudAgentBase(value));
+}
+// A dedicated cloud agent lives on its own subdomain (<id>.elizacloud.ai) and
+// serves chat over REST. Its `/ws` upgrade is NOT currently proxied by the
+// agent-router (the upgrade returns 404), so attempting the WebSocket only
+// produced a "Reconnecting… (N/15)" header for ~95s before degrading. Treat
+// these bases like the shared-runtime adapter — connected-over-REST with no WS
+// attempt — so there is no reconnect churn. (The WS-reconnect-exhaustion degrade
+// in connectWs.onclose is kept as a safety net; revisit once the agent-router
+// proxies the `/ws` upgrade and the agent advertises it via /api/config so we
+// can re-enable realtime.)
+function isDedicatedCloudAgentBase(value) {
+    const normalized = normalizeBaseUrl(value);
+    if (!normalized)
+        return false;
+    try {
+        const host = new URL(normalized).hostname.toLowerCase();
+        return (host.endsWith(".elizacloud.ai") &&
+            !ELIZA_CLOUD_CONTROL_PLANE_HOSTS.has(host));
+    }
+    catch {
+        return false;
+    }
+}
+function getInjectedWsBase() {
+    if (typeof window === "undefined")
+        return undefined;
+    const values = [
+        window.__ELIZA_WS_BASE__,
+        window.__ELIZAOS_WS_BASE__,
+    ];
+    for (const value of values) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Network status — listens for the bridged Capacitor `networkStatusChange`
+// event so the WS reconnect scheduler can park itself during airplane mode
+// instead of burning all 5 backoff attempts.
+// ---------------------------------------------------------------------------
+let lastKnownNetworkConnected = true;
+const networkStatusListeners = new Set();
+function isNetworkStatusChangeEvent(ev) {
+    if (!("detail" in ev))
+        return false;
+    const detail = ev.detail;
+    return (typeof detail === "object" &&
+        detail !== null &&
+        typeof detail.connected === "boolean");
+}
+if (typeof document !== "undefined") {
+    document.addEventListener(NETWORK_STATUS_CHANGE_EVENT, (ev) => {
+        if (!isNetworkStatusChangeEvent(ev))
+            return;
+        const next = ev.detail.connected;
+        if (next === lastKnownNetworkConnected)
+            return;
+        lastKnownNetworkConnected = next;
+        for (const listener of networkStatusListeners) {
+            try {
+                listener(next);
+            }
+            catch {
+                // ignore listener errors — they don't get to break network state
+            }
+        }
+    });
+}
+/** Test-only: reset the cached network state. */
+export function __resetNetworkStatusForTests() {
+    lastKnownNetworkConnected = true;
+    networkStatusListeners.clear();
+}
+/** Test-only: read the last bridged network status. */
+export function __getLastKnownNetworkConnected() {
+    return lastKnownNetworkConnected;
+}
+// ---------------------------------------------------------------------------
+// Dedicated-agent resume (HTTP 202) handling
+// ---------------------------------------------------------------------------
+// A non-running dedicated cloud agent answers with `202 Accepted` + `Retry-After`
+// while it auto-resumes (the unified-auth Worker, #8628). The client honours that
+// contract: it waits the advertised delay and re-issues the request a bounded
+// number of times, so callers see the eventual real response instead of a 202
+// placeholder body — which otherwise surfaced as an empty reply on the first
+// message sent after a dedicated agent had idled.
+const RESUME_MAX_RETRIES = 6;
+const RESUME_DEFAULT_DELAY_MS = 5_000;
+const RESUME_MIN_DELAY_MS = 500;
+const RESUME_MAX_DELAY_MS = 10_000;
+/** Clamp the agent's advertised `Retry-After` (seconds) into a sane wait (ms). */
+function resumeRetryDelayMs(res) {
+    const header = res.headers.get("Retry-After");
+    const seconds = header !== null && Number.isFinite(Number(header))
+        ? Number(header)
+        : Number.NaN;
+    const ms = Number.isFinite(seconds)
+        ? seconds * 1_000
+        : RESUME_DEFAULT_DELAY_MS;
+    return Math.min(RESUME_MAX_DELAY_MS, Math.max(RESUME_MIN_DELAY_MS, ms));
+}
+/** Resolve after `ms`, or early if `signal` aborts. Never rejects. */
+function sleepUnlessAborted(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
 // ---------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------
@@ -56,17 +339,22 @@ export class ElizaClient {
     requestTransport = fetchAgentTransport;
     ws = null;
     wsHandlers = new Map();
+    wsEventBacklog = new Map();
     wsSendQueue = [];
     wsSendQueueLimit = 32;
     reconnectTimer = null;
     backoffMs = 500;
     wsHasConnectedOnce = false;
+    networkStatusUnsubscribe = null;
     // Connection state tracking for backend crash handling
     connectionState = "disconnected";
     reconnectAttempt = 0;
     disconnectedAt = null;
     connectionStateListeners = new Set();
     maxReconnectAttempts = 15;
+    // Fired exactly once per successful reconnect (never on the first connect)
+    // so consumers can reconcile state that drifted during the network gap.
+    resyncListeners = new Set();
     // UI language propagation — set by AppContext so the backend can
     // localise responses when needed.
     _uiLanguage = null;
@@ -74,6 +362,17 @@ export class ElizaClient {
     setUiLanguage(lang) {
         this._uiLanguage = lang || null;
     }
+    /**
+     * Stable id for a single logical client message. Used as an idempotency key
+     * so a resend after reconnect is de-dupable server-side. Falls back to a
+     * time+random token when crypto.randomUUID is unavailable.
+     */
+    static generateMessageId() {
+        if (typeof globalThis.crypto?.randomUUID === "function") {
+            return globalThis.crypto.randomUUID();
+        }
+        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    }
     static generateClientId() {
         let random;
         if (typeof globalThis.crypto?.randomUUID === "function") {
@@ -94,8 +393,12 @@ export class ElizaClient {
         this._token = token?.trim() || null;
         const bootBase = getBootConfig().apiBase;
         const injectedBase = getElizaApiBase();
-        const storedBaseRaw = typeof window !== "undefined" && window.localStorage
-            ? window.localStorage.getItem(LOCAL_STORAGE_API_BASE_KEY)
+        const localStorageGetItem = typeof window !== "undefined" &&
+            typeof window.localStorage?.getItem === "function"
+            ? window.localStorage.getItem.bind(window.localStorage)
+            : null;
+        const storedBaseRaw = localStorageGetItem
+            ? localStorageGetItem(LOCAL_STORAGE_API_BASE_KEY)
             : null;
         const storedBase = isElizaCloudControlPlaneBase(storedBaseRaw)
             ? null
@@ -227,112 +530,49 @@ export class ElizaClient {
                 message: "API not available (no HTTP origin)",
             });
         }
-        const requestUrl = (() => {
-            if (this.baseUrl) {
-                return `${this.baseUrl}${path}`;
-            }
-            if (typeof window !== "undefined") {
-                const proto = window.location.protocol;
-                if (proto === "http:" || proto === "https:") {
-                    return new URL(path, window.location.origin).toString();
-                }
-            }
-            return path;
-        })();
-        const makeRequest = async (token) => {
-            const timeoutMs = options?.timeoutMs ?? defaultFetchTimeoutMs(path, init);
-            const abortController = new AbortController();
-            let timeoutId;
-            let timedOut = false;
-            let abortListener;
-            if (init?.signal?.aborted) {
-                throw new ApiError({
-                    kind: "network",
-                    path,
-                    message: "Request aborted",
-                });
-            }
-            timeoutId = setTimeout(() => {
-                timedOut = true;
-                abortController.abort();
-            }, timeoutMs);
-            if (init?.signal) {
-                abortListener = () => {
-                    abortController.abort();
-                };
-                init.signal.addEventListener("abort", abortListener, { once: true });
-            }
-            const requestInit = {
-                ...init,
-                signal: abortController.signal,
-                headers: {
-                    "X-ElizaOS-Client-Id": this.clientId,
-                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
-                    ...(this._uiLanguage
-                        ? { "X-ElizaOS-UI-Language": this._uiLanguage }
-                        : {}),
-                    ...init?.headers,
-                },
-            };
-            try {
-                const transport = this.requestTransport === fetchAgentTransport
-                    ? ((await androidNativeAgentTransportForUrl(requestUrl)) ??
-                        (await iosInProcessAgentTransportForUrl(requestUrl)) ??
-                        desktopHttpTransportForUrl(requestUrl) ??
-                        nativeCloudHttpTransportForUrl(requestUrl) ??
-                        this.requestTransport)
-                    : this.requestTransport;
-                return await transport.request(requestUrl, requestInit, { timeoutMs });
-            }
-            catch (err) {
-                if (timedOut) {
-                    throw new ApiError({
-                        kind: "timeout",
-                        path,
-                        message: `Request timed out after ${timeoutMs}ms`,
-                    });
-                }
-                if (abortController.signal.aborted) {
-                    throw new ApiError({
-                        kind: "network",
-                        path,
-                        message: "Request aborted",
-                        cause: err,
-                    });
-                }
-                if (err instanceof ApiError) {
-                    throw err;
-                }
-                throw new ApiError({
-                    kind: "network",
-                    path,
-                    message: err instanceof Error && err.message
-                        ? err.message
-                        : "Network request failed",
-                    cause: err,
-                });
-            }
-            finally {
-                if (timeoutId !== undefined) {
-                    clearTimeout(timeoutId);
-                }
-                if (init?.signal && abortListener) {
-                    init.signal.removeEventListener("abort", abortListener);
-                }
-            }
-        };
+        const requestUrl = this.rawRequestUrl(path);
         const token = this.apiToken ?? (await hydrateAndroidLocalAgentTokenForUrl(requestUrl));
-        let res = await makeRequest(token);
+        let res = await this.rawRequestOnce(path, requestUrl, init, options, token);
         if (res.status === 401) {
             const hydratedToken = await hydrateAndroidLocalAgentTokenForUrl(requestUrl, { force: true });
             const retryToken = hydratedToken ?? (!token ? this.apiToken : null);
             if (retryToken && retryToken !== token) {
-                res = await makeRequest(retryToken);
+                res = await this.rawRequestOnce(path, requestUrl, init, options, retryToken);
             }
         }
+        // 202 Accepted: a non-running dedicated cloud agent is auto-resuming (#8628).
+        // Wait the advertised Retry-After and re-issue, bounded, so callers see the
+        // eventual response instead of a 202 placeholder. Non-202 responses skip this
+        // loop entirely, so ordinary requests are byte-for-byte unaffected.
+        let resumeRetries = 0;
+        if (res.status === 202)
+            options?.onResuming?.();
+        while (res.status === 202 && resumeRetries < RESUME_MAX_RETRIES) {
+            if (init?.signal?.aborted)
+                break;
+            await sleepUnlessAborted(resumeRetryDelayMs(res), init?.signal);
+            if (init?.signal?.aborted)
+                break;
+            resumeRetries += 1;
+            res = await this.rawRequestOnce(path, requestUrl, init, options, token);
+        }
+        // Resume budget exhausted while the agent is still 202 (resuming): surface a
+        // distinguishable error instead of returning the empty 202 placeholder as a
+        // success — otherwise the chat/stream path renders an empty reply. allowNonOk
+        // callers and aborted requests still get the raw response.
+        if (res.status === 202 && !options?.allowNonOk && !init?.signal?.aborted) {
+            throw new ApiError({
+                kind: "http",
+                path,
+                status: 202,
+                message: "Agent is still starting up — please try again in a moment.",
+                code: "agent_resuming",
+                retryAfter: resumeRetryDelayMs(res) / 1000,
+            });
+        }
         if (!res.ok && !options?.allowNonOk) {
-            const body = (await res
-                .json()
+            const body = (await this.readBodyText(res, path, options?.timeoutMs, init)
+                .then((text) => JSON.parse(text))
                 .catch(() => ({ error: res.statusText })));
             const message = typeof body?.error === "string"
                 ? body.error
@@ -365,6 +605,138 @@ export class ElizaClient {
         }
         return res;
     }
+    rawRequestUrl(path) {
+        if (this.baseUrl)
+            return `${this.baseUrl}${path}`;
+        if (typeof window !== "undefined") {
+            const proto = window.location.protocol;
+            if (proto === "http:" || proto === "https:") {
+                return new URL(path, window.location.origin).toString();
+            }
+        }
+        return path;
+    }
+    async rawRequestOnce(path, requestUrl, init, options, token) {
+        const timeoutMs = options?.timeoutMs ?? defaultFetchTimeoutMs(path, init);
+        const abortController = new AbortController();
+        let timedOut = false;
+        let abortListener;
+        if (init?.signal?.aborted) {
+            throw new ApiError({
+                kind: "network",
+                path,
+                message: "Request aborted",
+            });
+        }
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            abortController.abort();
+        }, timeoutMs);
+        if (init?.signal) {
+            abortListener = () => abortController.abort();
+            init.signal.addEventListener("abort", abortListener, { once: true });
+        }
+        try {
+            const requestInit = this.rawRequestInit(init, abortController, token);
+            const transport = await this.rawRequestTransport(requestUrl);
+            return await transport.request(requestUrl, requestInit, { timeoutMs });
+        }
+        catch (err) {
+            return this.throwRawRequestError(err, path, timeoutMs, timedOut, abortController);
+        }
+        finally {
+            clearTimeout(timeoutId);
+            if (init?.signal && abortListener) {
+                init.signal.removeEventListener("abort", abortListener);
+            }
+        }
+    }
+    rawRequestInit(init, abortController, token) {
+        return {
+            ...init,
+            signal: abortController.signal,
+            headers: {
+                "X-ElizaOS-Client-Id": this.clientId,
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                ...(this._uiLanguage
+                    ? { "X-ElizaOS-UI-Language": this._uiLanguage }
+                    : {}),
+                ...init?.headers,
+            },
+        };
+    }
+    async rawRequestTransport(requestUrl) {
+        if (this.requestTransport !== fetchAgentTransport) {
+            return this.requestTransport;
+        }
+        return ((await androidNativeAgentTransportForUrl(requestUrl)) ??
+            (await iosInProcessAgentTransportForUrl(requestUrl)) ??
+            desktopHttpTransportForUrl(requestUrl) ??
+            nativeCloudHttpTransportForUrl(requestUrl) ??
+            this.requestTransport);
+    }
+    throwRawRequestError(err, path, timeoutMs, timedOut, abortController) {
+        if (timedOut) {
+            throw new ApiError({
+                kind: "timeout",
+                path,
+                message: `Request timed out after ${timeoutMs}ms`,
+            });
+        }
+        if (abortController.signal.aborted) {
+            throw new ApiError({
+                kind: "network",
+                path,
+                message: "Request aborted",
+                cause: err,
+            });
+        }
+        if (err instanceof ApiError)
+            throw err;
+        throw new ApiError({
+            kind: "network",
+            path,
+            message: err instanceof Error && err.message
+                ? err.message
+                : "Network request failed",
+            cause: err,
+        });
+    }
+    /**
+     * Reads a response body with the same budget the request itself had. The
+     * per-request abort timer in {@link rawRequestOnce} is cleared the moment
+     * HEADERS arrive, so without this a response whose body stream stalls
+     * (proxies, USB/adb relays, dropped radios) pends forever — JSON consumers
+     * must never await an unbounded body. Streaming consumers (SSE) keep their
+     * own idle timeout and do not go through here.
+     */
+    async readBodyText(res, path, timeoutMs, init) {
+        // Must mirror the request phase's budget (rawRequestOnce uses
+        // defaultFetchTimeoutMs(path, init)). Passing `undefined` here forced the
+        // GET branch -> 10s for every route, so the body read of a long POST
+        // (chat 600s, ASR/TTS 180s, reset 60s) would spuriously time out on slow
+        // on-device builds that emit headers early then take >10s to finish.
+        const budgetMs = timeoutMs ?? defaultFetchTimeoutMs(path, init);
+        let timeoutId;
+        try {
+            return await Promise.race([
+                res.text(),
+                new Promise((_, reject) => {
+                    timeoutId = setTimeout(() => {
+                        reject(new ApiError({
+                            kind: "timeout",
+                            path,
+                            status: res.status,
+                            message: `Response body timed out after ${budgetMs}ms`,
+                        }));
+                    }, budgetMs);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     async fetch(path, init, options) {
         const res = await this.rawRequest(path, {
             ...init,
@@ -376,7 +748,7 @@ export class ElizaClient {
         if (res.status === 204) {
             return undefined;
         }
-        const text = await res.text();
+        const text = await this.readBodyText(res, path, options?.timeoutMs, init);
         if (text === "") {
             return undefined;
         }
@@ -396,8 +768,47 @@ export class ElizaClient {
         }
     }
     // --- WebSocket ---
+    rememberReplayableWsEvent(type, data) {
+        if (!REPLAYABLE_WS_EVENT_TYPES.has(type))
+            return;
+        const backlog = this.wsEventBacklog.get(type) ?? [];
+        backlog.push(data);
+        if (backlog.length > WS_EVENT_BACKLOG_LIMIT) {
+            backlog.splice(0, backlog.length - WS_EVENT_BACKLOG_LIMIT);
+        }
+        this.wsEventBacklog.set(type, backlog);
+    }
+    replayBackloggedWsEvents(type, handler) {
+        const backlog = this.wsEventBacklog.get(type);
+        if (!backlog?.length)
+            return;
+        const pending = backlog.slice();
+        queueMicrotask(() => {
+            if (!this.wsHandlers.get(type)?.has(handler))
+                return;
+            for (const data of pending) {
+                try {
+                    handler(data);
+                }
+                catch {
+                    // Match normal WS dispatch: a handler error must not poison replay.
+                }
+            }
+            const current = this.wsEventBacklog.get(type);
+            if (!current?.length)
+                return;
+            const delivered = new Set(pending);
+            const remaining = current.filter((data) => !delivered.has(data));
+            if (remaining.length > 0) {
+                this.wsEventBacklog.set(type, remaining);
+            }
+            else {
+                this.wsEventBacklog.delete(type);
+            }
+        });
+    }
     connectWs() {
-        if (isIosInProcessLocalAgentBase(this.baseUrl)) {
+        if (shouldTreatAsConnectedWithoutWebSocket(this.baseUrl)) {
             this.backoffMs = 500;
             this.reconnectAttempt = 0;
             this.disconnectedAt = null;
@@ -413,14 +824,23 @@ export class ElizaClient {
         }
         let host;
         let wsProtocol;
-        if (this.baseUrl) {
+        const wsBase = getInjectedWsBase();
+        if (wsBase) {
+            const parsed = new URL(wsBase);
+            host = parsed.host;
+            wsProtocol =
+                parsed.protocol === "https:" || parsed.protocol === "wss:"
+                    ? "wss:"
+                    : "ws:";
+        }
+        else if (this.baseUrl) {
             const parsed = new URL(this.baseUrl);
             host = parsed.host;
             wsProtocol = parsed.protocol === "https:" ? "wss:" : "ws:";
         }
         else {
             // In non-HTTP environments (electrobun://, file://, etc.)
-            // window.location.host may be empty or a non-routable placeholder like "-".
+            // window.location.host may be empty or a non-routable value like "-".
             const loc = window.location;
             if (loc.protocol !== "http:" && loc.protocol !== "https:")
                 return;
@@ -430,7 +850,7 @@ export class ElizaClient {
         if (!host)
             return;
         // On Capacitor native (iosScheme/androidScheme = "https"), the origin host
-        // is a dummy bundle host (e.g. "localhost" with no server behind it).
+        // is a synthetic bundle host (e.g. "localhost" with no server behind it).
         // Skip WS if we have no explicit baseUrl and the host doesn't look like a
         // real backend (no port, not an IP, not a known API domain).
         if (!this.baseUrl && typeof host === "string") {
@@ -441,6 +861,14 @@ export class ElizaClient {
         }
         let url = `${wsProtocol}//${host}/ws`;
         const params = new URLSearchParams({ clientId: this.clientId });
+        // Browsers cannot set Authorization on `new WebSocket(url)`. Pass the same
+        // token HTTP uses as a query param; cloud servers (ELIZA_ALLOW_WS_QUERY_TOKEN=1)
+        // honor it during the upgrade handshake. Self-hosted servers without that
+        // flag will ignore the query token and fall back to the post-open
+        // `{type:"auth"}` message below.
+        const token = this.apiToken;
+        if (token)
+            params.set("token", token);
         url += `?${params.toString()}`;
         this.ws = new WebSocket(url);
         this.ws.onopen = () => {
@@ -456,6 +884,7 @@ export class ElizaClient {
             this.emitConnectionStateChange();
             // Notify listeners when the WS reconnects (not on the first connect)
             // so they can re-hydrate state that may have been lost during the gap.
+            // Fired once per reconnect — consumers refetch on demand, never poll.
             if (this.wsHasConnectedOnce) {
                 const handlers = this.wsHandlers.get("ws-reconnected");
                 if (handlers) {
@@ -463,6 +892,9 @@ export class ElizaClient {
                         handler({ type: "ws-reconnected" });
                     }
                 }
+                for (const listener of this.resyncListeners) {
+                    listener();
+                }
             }
             this.wsHasConnectedOnce = true;
             if (this.wsSendQueue.length > 0 &&
@@ -489,11 +921,14 @@ export class ElizaClient {
                 const data = JSON.parse(event.data);
                 const type = data.type;
                 const handlers = this.wsHandlers.get(type);
-                if (handlers) {
+                if (handlers?.size) {
                     for (const handler of handlers) {
                         handler(data);
                     }
                 }
+                else {
+                    this.rememberReplayableWsEvent(type, data);
+                }
                 // Also fire "all" handlers
                 const allHandlers = this.wsHandlers.get("*");
                 if (allHandlers) {
@@ -515,7 +950,18 @@ export class ElizaClient {
             this.reconnectAttempt++;
             // Update state based on attempt count
             if (this.reconnectAttempt >= this.maxReconnectAttempts) {
-                this.connectionState = "failed";
+                // A dedicated cloud agent serves chat over REST independently of the
+                // realtime WS, so a WS that can't connect must NOT raise the fatal
+                // full-screen "Lost backend connection" overlay. Degrade to a non-fatal
+                // connected-over-REST state and keep probing in the background (see
+                // scheduleReconnect's 30s loop) so live updates resume on WS recovery.
+                if (isDedicatedCloudAgentBase(this.baseUrl)) {
+                    this.connectionState = "connected";
+                    this.disconnectedAt = null;
+                }
+                else {
+                    this.connectionState = "failed";
+                }
             }
             else {
                 this.connectionState = "reconnecting";
@@ -530,6 +976,17 @@ export class ElizaClient {
     scheduleReconnect() {
         if (this.reconnectTimer)
             return;
+        // Skip the backoff timer when the device reports no network — the
+        // browser's `online`/`offline` events plus Capacitor's bridged
+        // `networkStatusChange` event will wake us up when connectivity
+        // returns. Without this, airplane mode (or a flaky cellular hand-
+        // off) burns through all `maxReconnectAttempts` in seconds, leaving
+        // the UI in the long-poll fallback even after the network comes
+        // back.
+        if (!lastKnownNetworkConnected) {
+            this.armNetworkStatusWake();
+            return;
+        }
         // After the short backoff window is exhausted, keep probing at a
         // low frequency so the UI can recover without a full page refresh.
         if (this.reconnectAttempt >= this.maxReconnectAttempts) {
@@ -545,6 +1002,28 @@ export class ElizaClient {
         }, this.backoffMs);
         this.backoffMs = Math.min(this.backoffMs * 1.5, 10000);
     }
+    /**
+     * Arms a one-shot network-status listener that re-runs `connectWs()` the
+     * moment the device reports connectivity again. Calling twice has no
+     * additional effect; the existing listener stays in place.
+     */
+    armNetworkStatusWake() {
+        if (this.networkStatusUnsubscribe)
+            return;
+        const listener = (connected) => {
+            if (!connected)
+                return;
+            const unsubscribe = this.networkStatusUnsubscribe;
+            this.networkStatusUnsubscribe = null;
+            if (unsubscribe)
+                unsubscribe();
+            this.connectWs();
+        };
+        networkStatusListeners.add(listener);
+        this.networkStatusUnsubscribe = () => {
+            networkStatusListeners.delete(listener);
+        };
+    }
     emitConnectionStateChange() {
         const state = this.getConnectionState();
         for (const listener of this.connectionStateListeners) {
@@ -572,6 +1051,19 @@ export class ElizaClient {
             this.connectionStateListeners.delete(listener);
         };
     }
+    /**
+     * Subscribe to reconnect events. The listener fires once each time the
+     * WebSocket re-establishes after a drop (never on the initial connect), so
+     * callers can reconcile state that may have drifted during the gap — e.g.
+     * refetch the active conversation's recent messages. Returns an unsubscribe
+     * function. This is edge-triggered, not a poll.
+     */
+    onReconnect(listener) {
+        this.resyncListeners.add(listener);
+        return () => {
+            this.resyncListeners.delete(listener);
+        };
+    }
     /** Reset connection state and restart reconnection attempts. */
     resetConnection() {
         this.reconnectAttempt = 0;
@@ -585,15 +1077,26 @@ export class ElizaClient {
         this.emitConnectionStateChange();
         this.connectWs();
     }
-    /** Send an arbitrary JSON message over the WebSocket connection. */
+    /**
+     * Send an arbitrary JSON message over the WebSocket connection.
+     *
+     * Every message is stamped with a stable client-generated `msgId` (unless the
+     * caller already supplied one). The id is assigned once and travels with the
+     * payload, so a message that gets queued while offline and flushed after a
+     * reconnect carries the *same* id on the resend — letting the server dedupe
+     * `(clientId, msgId)` instead of double-processing it.
+     */
     sendWsMessage(data) {
-        const payload = JSON.stringify(data);
+        const message = typeof data.msgId === "string" && data.msgId.length > 0
+            ? data
+            : { ...data, msgId: ElizaClient.generateMessageId() };
+        const payload = JSON.stringify(message);
         if (this.ws?.readyState === WebSocket.OPEN) {
             this.ws.send(payload);
             return;
         }
         // Keep only the newest active-conversation update while disconnected.
-        if (data.type === "active-conversation") {
+        if (message.type === "active-conversation") {
             this.wsSendQueue = this.wsSendQueue.filter((queued) => {
                 try {
                     const parsed = JSON.parse(queued);
@@ -605,8 +1108,6 @@ export class ElizaClient {
             });
         }
         if (this.wsSendQueue.length >= this.wsSendQueueLimit) {
-            const droppedType = typeof data.type === "string" ? data.type : "unknown";
-            console.warn("[ws] send queue full - dropping:", droppedType);
             this.wsSendQueue.shift();
         }
         this.wsSendQueue.push(payload);
@@ -619,6 +1120,7 @@ export class ElizaClient {
             this.wsHandlers.set(type, new Set());
         }
         this.wsHandlers.get(type)?.add(handler);
+        this.replayBackloggedWsEvents(type, handler);
         return () => {
             this.wsHandlers.get(type)?.delete(handler);
         };
@@ -628,9 +1130,14 @@ export class ElizaClient {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        if (this.networkStatusUnsubscribe) {
+            this.networkStatusUnsubscribe();
+            this.networkStatusUnsubscribe = null;
+        }
         this.ws?.close();
         this.ws = null;
         this.wsSendQueue = [];
+        this.wsEventBacklog.clear();
         // Reset connection state on intentional disconnect
         this.reconnectAttempt = 0;
         this.disconnectedAt = null;
@@ -639,7 +1146,9 @@ export class ElizaClient {
     }
     // --- Text normalization helpers (used by chat domain methods) ---
     normalizeAssistantText(text) {
-        const stripped = stripAssistantStageDirections(text);
+        if (typeof text !== "string")
+            return GENERIC_NO_RESPONSE_TEXT;
+        const stripped = stripAssistantStageDirections(extractAssistantReplyText(text) ?? text);
         const trimmed = stripped.trim();
         if (trimmed.length === 0) {
             if (text.trim().length === 0 ||
@@ -654,7 +1163,7 @@ export class ElizaClient {
         return trimmed;
     }
     normalizeGreetingText(text) {
-        const stripped = stripAssistantStageDirections(text);
+        const stripped = stripAssistantStageDirections(extractAssistantReplyText(text) ?? text);
         const trimmed = stripped.trim();
         if (trimmed.length === 0 || /^\(?no response\)?$/i.test(trimmed)) {
             return "";
@@ -662,7 +1171,18 @@ export class ElizaClient {
         return trimmed;
     }
     // --- Streaming chat endpoint (used by chat domain methods) ---
-    async streamChatEndpoint(path, text, onToken, channelType = "DM", signal, images, conversationMode, metadata) {
+    async streamChatEndpoint(path, text, onToken, channelType = "DM", signal, images, metadata, 
+    /** Additive: in-flight phase changes (thinking / streaming / running_action
+     *  / waking …). Omitting it leaves the token/done/error behaviour unchanged. */
+    onStatus) {
+        // Idempotency key for the chat send. The HTTP chat path (POST
+        // /api/chat[/:conversationId]/stream) lives in
+        // packages/agent/src/api/chat-routes.ts, which is owned by the chat swarm.
+        // Server-side dedupe by `clientMessageId` should hook there, where the
+        // request body is parsed before the message is persisted/generated. The id
+        // is generated here so the contract is in place regardless of when that
+        // dedupe lands.
+        const clientMessageId = ElizaClient.generateMessageId();
         const res = await this.rawRequest(path, {
             method: "POST",
             headers: {
@@ -672,99 +1192,32 @@ export class ElizaClient {
             body: JSON.stringify({
                 text,
                 channelType,
+                clientMessageId,
                 ...(images?.length ? { images } : {}),
-                ...(conversationMode ? { conversationMode } : {}),
                 ...(metadata ? { metadata } : {}),
             }),
             signal,
-        });
+        }, 
+        // A non-running cloud agent 202s and auto-resumes; surface `waking` so the
+        // chat shows the agent booting instead of stalled dots.
+        onStatus ? { onResuming: () => onStatus({ kind: "waking" }) } : undefined);
         if (!res.body) {
             throw new Error("Streaming not supported by this browser");
         }
         const decoder = new TextDecoder();
         const reader = res.body.getReader();
         let buffer = "";
-        let fullText = "";
-        let doneText = null;
-        let doneAgentName = null;
-        let doneNoResponseReason = null;
-        let doneUsage;
-        let doneFailureKind;
-        let doneLocalInference;
-        let receivedDone = false;
-        const findSseEventBreak = (chunkBuffer) => {
-            const lfBreak = chunkBuffer.indexOf("\n\n");
-            const crlfBreak = chunkBuffer.indexOf("\r\n\r\n");
-            if (lfBreak === -1 && crlfBreak === -1)
-                return null;
-            if (lfBreak === -1)
-                return { index: crlfBreak, length: 4 };
-            if (crlfBreak === -1)
-                return { index: lfBreak, length: 2 };
-            return lfBreak < crlfBreak
-                ? { index: lfBreak, length: 2 }
-                : { index: crlfBreak, length: 4 };
-        };
-        const parseDataLine = (line) => {
-            const payload = line.startsWith("data:") ? line.slice(5).trim() : "";
-            if (!payload)
-                return;
-            let parsed;
-            try {
-                parsed = JSON.parse(payload);
-            }
-            catch {
-                return;
-            }
-            if (!parsed.type && typeof parsed.text === "string") {
-                parsed.type = "token";
-            }
-            if (parsed.type === "token") {
-                const chunk = parsed.text ?? "";
-                const nextFullText = typeof parsed.fullText === "string"
-                    ? parsed.fullText
-                    : chunk
-                        ? mergeStreamingText(fullText, chunk)
-                        : fullText;
-                if (nextFullText === fullText)
-                    return;
-                fullText = nextFullText;
-                onToken(chunk, fullText);
-                return;
-            }
-            if (parsed.type === "done") {
-                receivedDone = true;
-                if (typeof parsed.fullText === "string")
-                    doneText = parsed.fullText;
-                if (typeof parsed.agentName === "string" && parsed.agentName.trim()) {
-                    doneAgentName = parsed.agentName;
-                }
-                if (parsed.noResponseReason === "ignored") {
-                    doneNoResponseReason = "ignored";
-                }
-                if (typeof parsed.failureKind === "string") {
-                    doneFailureKind = parsed.failureKind;
-                }
-                if (parsed.localInference &&
-                    typeof parsed.localInference === "object") {
-                    doneLocalInference = parsed.localInference;
-                }
-                if (parsed.usage) {
-                    doneUsage = {
-                        promptTokens: parsed.usage.promptTokens ?? 0,
-                        completionTokens: parsed.usage.completionTokens ?? 0,
-                        totalTokens: parsed.usage.totalTokens ?? 0,
-                        model: parsed.usage.model,
-                    };
-                }
-                // Terminal event: stop reading immediately instead of waiting for the
-                // server to close the body (some stacks leave the stream open briefly).
-                void reader.cancel("elizaos-sse-terminal-done").catch(() => { });
-                return;
-            }
-            if (parsed.type === "error") {
-                throw new Error(parsed.message ?? "generation failed");
-            }
+        const streamState = {
+            fullText: "",
+            doneText: null,
+            doneAgentName: null,
+            doneThought: null,
+            doneNoResponseReason: null,
+            doneUsage: undefined,
+            doneFailureKind: undefined,
+            doneLocalInference: undefined,
+            doneActionResults: undefined,
+            receivedDone: false,
         };
         // Contract: the API must emit `data: {"type":"done",...}` or
         // `data: {"type":"error",...}` and then end the response. If the server
@@ -783,8 +1236,7 @@ export class ElizaClient {
                 });
                 ({ done, value } = await Promise.race([readPromise, timeoutPromise]));
             }
-            catch (streamErr) {
-                console.warn("[api-client] SSE stream interrupted:", streamErr);
+            catch {
                 void reader.cancel("elizaos-sse-idle-timeout").catch(() => { });
                 break;
             }
@@ -798,30 +1250,49 @@ export class ElizaClient {
                 for (const line of rawEvent.split(/\r?\n/)) {
                     if (!line.startsWith("data:"))
                         continue;
-                    parseDataLine(line);
+                    if (applyStreamChatDataLine(line, streamState, onToken, onStatus)) {
+                        buffer = "";
+                        void reader.cancel("elizaos-sse-terminal-done").catch(() => { });
+                        break;
+                    }
                 }
+                if (streamState.receivedDone)
+                    break;
                 eventBreak = findSseEventBreak(buffer);
             }
+            if (streamState.receivedDone)
+                break;
         }
-        if (buffer.trim()) {
+        if (!streamState.receivedDone && buffer.trim()) {
             for (const line of buffer.split(/\r?\n/)) {
-                if (line.startsWith("data:"))
-                    parseDataLine(line);
+                if (line.startsWith("data:")) {
+                    applyStreamChatDataLine(line, streamState, onToken, onStatus);
+                }
             }
         }
-        const resolvedText = doneNoResponseReason === "ignored"
+        const resolvedText = streamState.doneNoResponseReason === "ignored"
             ? ""
-            : this.normalizeAssistantText(doneText ?? fullText);
+            : this.normalizeAssistantText(streamState.doneText ?? streamState.fullText);
         return {
             text: resolvedText,
-            agentName: doneAgentName ?? "Eliza",
-            completed: receivedDone,
-            ...(doneNoResponseReason
-                ? { noResponseReason: doneNoResponseReason }
+            agentName: streamState.doneAgentName ?? "Eliza",
+            completed: streamState.receivedDone,
+            ...(streamState.doneThought
+                ? { reasoning: streamState.doneThought }
+                : {}),
+            ...(streamState.doneNoResponseReason
+                ? { noResponseReason: streamState.doneNoResponseReason }
+                : {}),
+            ...(streamState.doneUsage ? { usage: streamState.doneUsage } : {}),
+            ...(streamState.doneFailureKind
+                ? { failureKind: streamState.doneFailureKind }
+                : {}),
+            ...(streamState.doneLocalInference
+                ? { localInference: streamState.doneLocalInference }
+                : {}),
+            ...(streamState.doneActionResults?.length
+                ? { actionResults: streamState.doneActionResults }
                 : {}),
-            ...(doneUsage ? { usage: doneUsage } : {}),
-            ...(doneFailureKind ? { failureKind: doneFailureKind } : {}),
-            ...(doneLocalInference ? { localInference: doneLocalInference } : {}),
         };
     }
 }