ocuclaw 1.2.4 → 1.3.0

package/dist/runtime/upstream-runtime.js

@@ -1,3 +1,14 @@
+import { createHash } from "node:crypto";
+import {
+  buildRateLimitInfoFromSnapshot,
+  selectProviderUsageSnapshot,
+} from "./provider-usage-select.js";
+import { stripAllTaggedSpans } from "../domain/tagged-span-strip.js";
+import { parseTaggedSpans } from "../domain/tagged-span-parser.js";
+import { EMOJI_TAG_FAMILY_CONFIG } from "../domain/neural-emoji-reactor-tag-config.js";
+import { PACE_TAG_FAMILY_CONFIG } from "../domain/neural-pace-modulator-tag-config.js";
+import { createSessionContextService } from "./session-context-service.js";
+
 function normalizeLogger(logger) {
   if (!logger || typeof logger !== "object") {
     return console;
@@ -13,6 +24,24 @@ function normalizeLogger(logger) {
 
 const DEFAULT_MODEL_PROVIDER = "anthropic";
 const DEFAULT_MODEL_ID = "claude-opus-4-6";
+const POOL_OUTCOME_FRESHNESS_MS = 10 * 60 * 1000;
+
+// Dropped from 150 ms to 33 ms after Session 3 memoization (StreamingBuffer.displayedText
+// + MessageScreenPageSliceCache) reduced per-frame client-side cost. Session 1's earlier
+// 33 ms run produced ~15 s of long-tasks per ~10 s of streaming and a 10.8 s probe gap;
+// the Session-3 re-validation must confirm those signals stay near the 150 ms baseline.
+export const STREAMING_REBROADCAST_THROTTLE_MS = 33;
+
+function fullMessageText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b && b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text)
+      .join("");
+  }
+  return "";
+}
 
 function modelRefKey(provider, model) {
   return `${provider}/${model}`;
@@ -285,6 +314,8 @@ export function createUpstreamRuntime(opts = {}) {
   const sessionService = opts.sessionService;
   const handler = opts.handler;
   const emitDebug = typeof opts.emitDebug === "function" ? opts.emitDebug : () => {};
+  const operationRegistry = opts.operationRegistry || null;
+  const now = typeof opts.now === "function" ? opts.now : () => Date.now();
   const broadcastPages =
     typeof opts.broadcastPages === "function" ? opts.broadcastPages : () => {};
   const broadcastStatus =
@@ -293,6 +324,14 @@ export function createUpstreamRuntime(opts = {}) {
     typeof opts.broadcastActivity === "function"
       ? opts.broadcastActivity
       : (activity) => activity;
+  const broadcastProviderUsageSnapshot =
+    typeof opts.broadcastProviderUsageSnapshot === "function"
+      ? opts.broadcastProviderUsageSnapshot
+      : () => {};
+  const getCurrentSessionModelConfigSnapshot =
+    typeof opts.getCurrentSessionModelConfigSnapshot === "function"
+      ? opts.getCurrentSessionModelConfigSnapshot
+      : () => null;
   const resetActivityStatusAdapter =
     typeof opts.resetActivityStatusAdapter === "function"
       ? opts.resetActivityStatusAdapter
@@ -302,13 +341,162 @@ export function createUpstreamRuntime(opts = {}) {
   const getVoiceRuntime =
     typeof opts.getVoiceRuntime === "function" ? opts.getVoiceRuntime : () => null;
 
+  const gatewayUrl = typeof opts.gatewayUrl === "string" ? opts.gatewayUrl : null;
+  const gatewayToken = typeof opts.gatewayToken === "string" ? opts.gatewayToken : null;
+  // Cap on the encoded data URI length. Real-world OpenClaw avatars from the
+  // gateway can be >1 MB PNGs; the original 256 KB cap silently dropped them.
+  // 4 MB is generous for a one-shot identity broadcast over loopback/tailnet
+  // and is still tight enough to keep status frames from ballooning if a
+  // pathologically large image is configured.
+  const MAX_AVATAR_DATA_URI_BYTES = 4 * 1024 * 1024;
+
+  function gatewayHttpOriginFromWsUrl(wsUrl) {
+    if (typeof wsUrl !== "string") return null;
+    if (wsUrl.startsWith("wss://")) return "https://" + wsUrl.slice("wss://".length);
+    if (wsUrl.startsWith("ws://"))  return "http://"  + wsUrl.slice("ws://".length);
+    return null;
+  }
+
+  async function defaultFetchAgentAvatar(agentId, _source) {
+    if (!gatewayUrl || !gatewayToken || !agentId) return null;
+    const origin = gatewayHttpOriginFromWsUrl(gatewayUrl);
+    if (!origin) return null;
+    const url = `${origin}/avatar/${encodeURIComponent(agentId)}`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${gatewayToken}` },
+    });
+    if (!res.ok) return null;
+    const contentType = res.headers.get("content-type") || "";
+    const buffer = Buffer.from(await res.arrayBuffer());
+    return { contentType, body: buffer };
+  }
+
+  const fetchAgentAvatar =
+    typeof opts.fetchAgentAvatar === "function" ? opts.fetchAgentAvatar : defaultFetchAgentAvatar;
+
+  /** @type {Map<string, {dataUri: string, hash: string}>} */
+  const avatarCache = new Map();
+  /** @type {Map<string, Promise<{dataUri: string, hash: string}|null>>} */
+  const inFlightAvatarFetches = new Map();
+  /** @type {Map<string, string>} */ // hash → cacheKey
+  const avatarHashIndex = new Map();
+
+  async function resolveAgentAvatar(agentId, avatarSource) {
+    if (!agentId || typeof avatarSource !== "string" || !avatarSource) return null;
+
+    // For data: URIs, decode the base64 payload to compute a hash, but skip the
+    // gateway fetch entirely. Same dedupe semantics as remote sources.
+    if (avatarSource.startsWith("data:")) {
+      const cacheKey = `${agentId}|${avatarSource}`;
+      const cached = avatarCache.get(cacheKey);
+      if (cached) return cached;
+      const commaIndex = avatarSource.indexOf(",");
+      if (commaIndex < 0) return null;
+      if (avatarSource.length > MAX_AVATAR_DATA_URI_BYTES) {
+        emitDebug(
+          "relay.session",
+          "agent_avatar_resolve_dropped",
+          "warn",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({
+            reason: "oversize",
+            agentId,
+            dataUriBytes: avatarSource.length,
+            capBytes: MAX_AVATAR_DATA_URI_BYTES,
+          }),
+        );
+        return null;
+      }
+      const base64 = avatarSource.slice(commaIndex + 1);
+      const buffer = Buffer.from(base64, "base64");
+      const hash = createHash("sha256").update(buffer).digest("hex");
+      const entry = { dataUri: avatarSource, hash };
+      avatarCache.set(cacheKey, entry);
+      avatarHashIndex.set(hash, cacheKey);
+      return entry;
+    }
+
+    const cacheKey = `${agentId}|${avatarSource}`;
+    if (avatarCache.has(cacheKey)) return avatarCache.get(cacheKey);
+    if (inFlightAvatarFetches.has(cacheKey)) return inFlightAvatarFetches.get(cacheKey);
+
+    const promise = (async () => {
+      try {
+        const result = await fetchAgentAvatar(agentId, avatarSource);
+        if (!result || !result.body) {
+          emitDebug(
+            "relay.session",
+            "agent_avatar_resolve_dropped",
+            "warn",
+            { sessionKey: sessionService.ensureSessionKey() },
+            () => ({ reason: "empty_response", agentId }),
+          );
+          return null;
+        }
+        const contentType = String(result.contentType || "").toLowerCase();
+        if (!contentType.startsWith("image/")) {
+          emitDebug(
+            "relay.session",
+            "agent_avatar_resolve_dropped",
+            "warn",
+            { sessionKey: sessionService.ensureSessionKey() },
+            () => ({ reason: "non_image_content_type", agentId, contentType }),
+          );
+          return null;
+        }
+        const buffer = Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+        const base64 = buffer.toString("base64");
+        const dataUri = `data:${contentType};base64,${base64}`;
+        if (dataUri.length > MAX_AVATAR_DATA_URI_BYTES) {
+          emitDebug(
+            "relay.session",
+            "agent_avatar_resolve_dropped",
+            "warn",
+            { sessionKey: sessionService.ensureSessionKey() },
+            () => ({
+              reason: "oversize",
+              agentId,
+              dataUriBytes: dataUri.length,
+              capBytes: MAX_AVATAR_DATA_URI_BYTES,
+            }),
+          );
+          return null;
+        }
+        const hash = createHash("sha256").update(buffer).digest("hex");
+        const entry = { dataUri, hash };
+        avatarCache.set(cacheKey, entry);
+        avatarHashIndex.set(hash, cacheKey);
+        return entry;
+      } catch (err) {
+        emitDebug(
+          "relay.session",
+          "agent_avatar_resolve_failed",
+          "warn",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({ message: err && err.message ? err.message : String(err) }),
+        );
+        return null;
+      } finally {
+        inFlightAvatarFetches.delete(cacheKey);
+      }
+    })();
+
+    inFlightAvatarFetches.set(cacheKey, promise);
+    return promise;
+  }
+
   const modelsCacheTtlMs =
     Number.isFinite(opts.modelsCacheTtlMs) && opts.modelsCacheTtlMs > 0
       ? Math.floor(opts.modelsCacheTtlMs)
       : 300000;
+  const providerUsageCacheTtlMs =
+    Number.isFinite(opts.providerUsageCacheTtlMs) && opts.providerUsageCacheTtlMs > 0
+      ? Math.floor(opts.providerUsageCacheTtlMs)
+      : 60000;
 
   let openclawConnected = false;
-  let agentName = null;
+  /** @type {{name: string|null, emoji: string|null, avatarDataUri: string|null, avatarHash: string|null}} */
+  let agentIdentity = { name: null, emoji: null, avatarDataUri: null, avatarHash: null };
   /** @type {Array<{provider: string, id: string, name: string, contextWindow?: number, reasoning?: boolean}>|null} */
   let cachedModelsCatalog = null;
   let cachedModelsCatalogFetchedAt = 0;
@@ -321,14 +509,44 @@ export function createUpstreamRuntime(opts = {}) {
   let cachedSkillsCatalogStale = true;
   /** @type {Promise<{skills: Array, fetchedAtMs: number, stale: boolean}>|null} */
   let inFlightSkillsCatalogFetch = null;
+  let cachedProviderUsageSummary = null;
+  let cachedProviderUsageFetchedAt = 0;
+  let cachedProviderUsageObservedAt = 0;
+  let cachedProviderUsageStale = true;
+  /** @type {Promise<object>|null} */
+  let inFlightProviderUsageFetch = null;
+  const providerOutcomeState = new Map();
+  const cachedAuthProfileCounts = new Map();
   const upstreamRunPipeline = new Map();
   let streamingThrottleTimer = null;
-  let pendingStreamingText = null;
+  let pendingStreaming = null;
+  /** @type {{runId: string, sessionKey: string}|null} */
+  let activeTyping = null;
   let bootstrapRefreshTimer = null;
   let bootstrapRefreshNonce = 0;
 
   function getAgentName() {
-    return agentName;
+    return agentIdentity.name;
+  }
+
+  function getAgentEmoji() {
+    return agentIdentity.emoji;
+  }
+
+  function getAgentAvatarDataUri() {
+    return agentIdentity.avatarDataUri;
+  }
+
+  function getAgentAvatarHash() {
+    return agentIdentity.avatarHash;
+  }
+
+  function getAgentAvatarDataUriByHash(hash) {
+    if (typeof hash !== "string" || !hash) return null;
+    const cacheKey = avatarHashIndex.get(hash);
+    if (!cacheKey) return null;
+    const entry = avatarCache.get(cacheKey);
+    return entry ? entry.dataUri : null;
   }
 
   function isConnected() {
@@ -374,6 +592,31 @@ export function createUpstreamRuntime(opts = {}) {
         }),
       );
     });
+    refreshProviderUsage(true).then((snapshot) => {
+      emitDebug(
+        "relay.session",
+        "provider_usage_prefetched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          hasProvider: !!(snapshot && snapshot.provider),
+          stale: !!(snapshot && snapshot.stale),
+          trigger,
+        }),
+      );
+    });
+    sessionService.getCurrentSessionModelConfig().then((config) => {
+      emitDebug(
+        "relay.session",
+        "session_model_config_prefetched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          hasProvider: !!(config && config.modelProvider),
+          trigger,
+        }),
+      );
+    });
   }
 
   function applyConnectedStatus(connected, trigger, emitTransportEvent = true) {
@@ -381,10 +624,27 @@ export function createUpstreamRuntime(opts = {}) {
     openclawConnected = !!connected;
     sessionService.handleUpstreamStatusChange(openclawConnected);
     if (!openclawConnected) {
+      clearTyping("upstream_disconnected");
       inFlightModelsCatalogFetch = null;
       inFlightSkillsCatalogFetch = null;
+      inFlightProviderUsageFetch = null;
       cachedSkillsCatalogStale = true;
+      cachedProviderUsageStale = true;
       resetActivityStatusAdapter();
+      // Drop the identity-tier overlays so the WebUI brand slot reverts to the
+      // OcuClaw mark while disconnected (spec 2026-04-27).
+      if (
+        agentIdentity.emoji != null ||
+        agentIdentity.avatarDataUri != null ||
+        agentIdentity.avatarHash != null
+      ) {
+        agentIdentity = {
+          ...agentIdentity,
+          emoji: null,
+          avatarDataUri: null,
+          avatarHash: null,
+        };
+      }
     } else if (!wasConnected) {
       onConnectedStateEstablished(trigger);
     }
@@ -403,6 +663,85 @@ export function createUpstreamRuntime(opts = {}) {
     broadcastStatus();
   }
 
+  function applyAgentIdentity(identity, source) {
+    const agentId =
+      identity && typeof identity.agentId === "string" && identity.agentId ? identity.agentId : null;
+    const avatarSource =
+      identity && typeof identity.avatar === "string" && identity.avatar ? identity.avatar : null;
+    // Data: URIs are pass-through per spec — set them on the initial broadcast.
+    // For data: URIs the hash is cheap and synchronous — compute it now so the
+    // first status broadcast carries both fields. For remote avatars the hash
+    // arrives via the resolveAgentAvatar(...).then(...) settle below, after the
+    // initial broadcast has gone out with hash:null.
+    const inlineAvatarDataUri =
+      avatarSource && avatarSource.startsWith("data:") ? avatarSource : null;
+    let inlineAvatarHash = null;
+    if (agentId && inlineAvatarDataUri) {
+      const cacheKey = `${agentId}|${inlineAvatarDataUri}`;
+      const cached = avatarCache.get(cacheKey);
+      if (cached) {
+        inlineAvatarHash = cached.hash;
+      } else if (inlineAvatarDataUri.length <= MAX_AVATAR_DATA_URI_BYTES) {
+        const commaIndex = inlineAvatarDataUri.indexOf(",");
+        if (commaIndex >= 0) {
+          const buffer = Buffer.from(inlineAvatarDataUri.slice(commaIndex + 1), "base64");
+          inlineAvatarHash = createHash("sha256").update(buffer).digest("hex");
+          const entry = { dataUri: inlineAvatarDataUri, hash: inlineAvatarHash };
+          avatarCache.set(cacheKey, entry);
+          avatarHashIndex.set(inlineAvatarHash, cacheKey);
+        }
+      }
+    }
+    const next = {
+      name: identity && typeof identity.name === "string" && identity.name ? identity.name : null,
+      emoji: identity && typeof identity.emoji === "string" && identity.emoji ? identity.emoji : null,
+      avatarDataUri: inlineAvatarDataUri,
+      avatarHash: inlineAvatarHash,
+    };
+    agentIdentity = next;
+    conversationState.setAgentName(next.name || "Agent");
+    emitDebug(
+      "relay.session",
+      "agent_identity_applied",
+      "info",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({
+        source,
+        hasName: !!next.name,
+        hasEmoji: !!next.emoji,
+        hasAvatarSource: !!avatarSource,
+        avatarInline: !!inlineAvatarDataUri,
+      }),
+    );
+    broadcastStatus();
+
+    if (!agentId || !avatarSource) return;
+    const generationName = next.name;
+    const generationEmoji = next.emoji;
+    resolveAgentAvatar(agentId, avatarSource).then((resolved) => {
+      // Drop if the identity changed underneath us.
+      if (
+        agentIdentity.name !== generationName ||
+        agentIdentity.emoji !== generationEmoji
+      ) {
+        return;
+      }
+      if (!resolved) return;
+      if (
+        agentIdentity.avatarDataUri === resolved.dataUri &&
+        agentIdentity.avatarHash === resolved.hash
+      ) {
+        return;
+      }
+      agentIdentity = {
+        ...agentIdentity,
+        avatarDataUri: resolved.dataUri,
+        avatarHash: resolved.hash,
+      };
+      broadcastStatus();
+    });
+  }
+
   async function refreshUpstreamBootstrap(trigger, attempt = 0) {
     const refreshNonce = ++bootstrapRefreshNonce;
     clearBootstrapRefreshTimer();
@@ -419,21 +758,7 @@ export function createUpstreamRuntime(opts = {}) {
     if (statusOk || identityOk) {
       applyConnectedStatus(true, `${trigger}_bootstrap`, !statusOk);
       if (identityOk) {
-        const identity = identityResult.value;
-        agentName = identity && identity.name ? identity.name : null;
-        conversationState.setAgentName(agentName || "Agent");
-        emitDebug(
-          "relay.session",
-          "agent_identity_bootstrap",
-          "info",
-          { sessionKey: sessionService.ensureSessionKey() },
-          () => ({
-            hasName: !!agentName,
-            trigger,
-            attempt,
-          }),
-        );
-        broadcastStatus();
+        applyAgentIdentity(identityResult.value, `${trigger}_bootstrap`);
       }
       return;
     }
@@ -467,22 +792,98 @@ export function createUpstreamRuntime(opts = {}) {
   }
 
   function flushPendingStreamingText() {
-    if (!pendingStreamingText) return;
+    if (!pendingStreaming) return;
+    const queuedStreaming = pendingStreaming;
+    pendingStreaming = null;
     const server = getServer();
     if (server) {
-      server.broadcast(handler.formatStreaming(pendingStreamingText));
+      const runId = queuedStreaming.runId || null;
+      if (runId) {
+        stopTypingForRun(runId, "first_visible_assistant_progress");
+        emitDebug(
+          "openclaw.message",
+          "agent_first_chunk",
+          "info",
+          { sessionKey: queuedStreaming.sessionKey || sessionService.ensureSessionKey() },
+          () => ({ runId }),
+        );
+      }
+      // Parse + markdown the latest cumulative text here, not per chunk: only
+      // the surviving (non-superseded) buffer reaches the parser.
+      const parsedSpans = parseTaggedSpans(queuedStreaming.rawText, [
+        EMOJI_TAG_FAMILY_CONFIG,
+        PACE_TAG_FAMILY_CONFIG,
+      ]);
+      const { text, spansByFamily } = applyMarkdownWithSpans(
+        {
+          cleanText: parsedSpans.cleanText,
+          spansByFamily: parsedSpans.spansByFamily,
+          trailingPartialTag: parsedSpans.trailingPartialTag,
+        },
+        queuedStreaming.prefix,
+        conversationState,
+      );
+      const emojiSpans = spansByFamily.emoji || [];
+      const paceSpans = spansByFamily.pace || [];
+      server.broadcast(
+        handler.formatStreaming(text, emojiSpans, paceSpans),
+      );
+      const now = Date.now();
+      const runPipeline = runId ? upstreamRunPipeline.get(runId) : null;
+      const firstRelayBroadcast = runPipeline
+        ? !runPipeline.firstRelayBroadcastAt
+        : queuedStreaming.flushReason === "first_immediate";
+      if (runPipeline && !runPipeline.firstRelayBroadcastAt) {
+        runPipeline.firstRelayBroadcastAt = now;
+        runPipeline.firstRelayBroadcastChars = text.length;
+      }
+      emitDebug(
+        "relay.protocol",
+        "streaming_rebroadcast",
+        "debug",
+        {
+          sessionKey: queuedStreaming.sessionKey || sessionService.ensureSessionKey(),
+          runId,
+        },
+        () => ({
+          reason: queuedStreaming.flushReason || "throttled_flush",
+          rebroadcastChars: text.length,
+          rawAssistantChars: queuedStreaming.rawAssistantChars,
+          assistantDeltaChars: queuedStreaming.assistantDeltaChars,
+          firstGatewayChunk:
+            typeof queuedStreaming.firstGatewayChunk === "boolean"
+              ? queuedStreaming.firstGatewayChunk
+              : null,
+          firstRelayBroadcast,
+          gatewayReceivedAtMs: queuedStreaming.gatewayReceivedAtMs,
+          gatewayToRebroadcastMs:
+            Number.isFinite(queuedStreaming.gatewayReceivedAtMs)
+              ? (now - queuedStreaming.gatewayReceivedAtMs)
+              : null,
+          sendToRebroadcastMs: runPipeline ? (now - runPipeline.sendStartedAt) : null,
+          ackToRebroadcastMs:
+            runPipeline && runPipeline.ackAt ? (now - runPipeline.ackAt) : null,
+          runStartToRebroadcastMs:
+            runPipeline && runPipeline.lifecycleStartAt
+              ? (now - runPipeline.lifecycleStartAt)
+              : null,
+          firstStreamingToRebroadcastMs:
+            runPipeline && runPipeline.firstStreamingAt
+              ? (now - runPipeline.firstStreamingAt)
+              : null,
+        }),
+      );
     }
-    pendingStreamingText = null;
   }
 
   function modelCatalogSnapshot(nowMs) {
-    const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+    const currentNow = Number.isFinite(nowMs) ? nowMs : now();
     const hasCache = Array.isArray(cachedModelsCatalog);
-    const ageMs = hasCache ? now - cachedModelsCatalogFetchedAt : Infinity;
+    const ageMs = hasCache ? currentNow - cachedModelsCatalogFetchedAt : Infinity;
     const ttlExpired = ageMs >= modelsCacheTtlMs;
     return {
       models: hasCache ? cachedModelsCatalog : [],
-      fetchedAtMs: hasCache ? cachedModelsCatalogFetchedAt : now,
+      fetchedAtMs: hasCache ? cachedModelsCatalogFetchedAt : currentNow,
       stale: !hasCache || cachedModelsCatalogStale || ttlExpired,
     };
   }
@@ -491,17 +892,17 @@ export function createUpstreamRuntime(opts = {}) {
     cachedModelsCatalog = Array.isArray(models) ? models : [];
     cachedModelsCatalogFetchedAt = Number.isFinite(fetchedAtMs)
       ? Math.floor(fetchedAtMs)
-      : Date.now();
+      : now();
     cachedModelsCatalogStale = !!stale;
     return modelCatalogSnapshot(cachedModelsCatalogFetchedAt);
   }
 
   function skillsCatalogSnapshot(nowMs) {
-    const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+    const currentNow = Number.isFinite(nowMs) ? nowMs : now();
     const hasCache = Array.isArray(cachedSkillsCatalog);
     return {
       skills: hasCache ? cachedSkillsCatalog : [],
-      fetchedAtMs: hasCache ? cachedSkillsCatalogFetchedAt : now,
+      fetchedAtMs: hasCache ? cachedSkillsCatalogFetchedAt : currentNow,
       stale: !hasCache || cachedSkillsCatalogStale,
     };
   }
@@ -510,11 +911,196 @@ export function createUpstreamRuntime(opts = {}) {
     cachedSkillsCatalog = Array.isArray(skills) ? skills : [];
     cachedSkillsCatalogFetchedAt = Number.isFinite(fetchedAtMs)
       ? Math.floor(fetchedAtMs)
-      : Date.now();
+      : now();
     cachedSkillsCatalogStale = !!stale;
     return skillsCatalogSnapshot(cachedSkillsCatalogFetchedAt);
   }
 
+  function providerUsageCacheState(nowMs) {
+    const currentNow = Number.isFinite(nowMs) ? nowMs : now();
+    const hasCache =
+      cachedProviderUsageSummary &&
+      typeof cachedProviderUsageSummary === "object" &&
+      !Array.isArray(cachedProviderUsageSummary);
+    const ageMs = hasCache ? currentNow - cachedProviderUsageObservedAt : Infinity;
+    const ttlExpired = ageMs >= providerUsageCacheTtlMs;
+    return {
+      summary: hasCache ? cachedProviderUsageSummary : null,
+      fetchedAtMs: hasCache ? cachedProviderUsageFetchedAt : currentNow,
+      stale: !hasCache || cachedProviderUsageStale || ttlExpired,
+    };
+  }
+
+  function activeProviderContext() {
+    const sessionKey = sessionService.ensureSessionKey();
+    const config = getCurrentSessionModelConfigSnapshot();
+    const configMatchesActiveSession =
+      !!config &&
+      (
+        typeof sessionService.isCurrentSession === "function"
+          ? sessionService.isCurrentSession(config.sessionKey)
+          : config.sessionKey === sessionKey
+      );
+    return {
+      sessionKey,
+      provider: normalizeProviderId(
+        configMatchesActiveSession ? config && config.modelProvider : null,
+      ),
+    };
+  }
+
+  function emptyProviderUsageSnapshot(nowMs, stale = true) {
+    const { sessionKey, provider } = activeProviderContext();
+    const fallbackFetchedAtMs = Number.isFinite(nowMs) ? Math.floor(nowMs) : now();
+    return {
+      sessionKey: sessionKey || null,
+      provider: provider || null,
+      displayName: null,
+      limitingWindowKey: null,
+      windows: [],
+      fetchedAtMs: fallbackFetchedAtMs,
+      stale: !!stale,
+      poolStatus: computePoolStatus(provider, fallbackFetchedAtMs),
+      totalProfileCount: cachedAuthProfileCounts.has(provider)
+        ? cachedAuthProfileCounts.get(provider)
+        : null,
+    };
+  }
+
+  function computePoolStatus(provider, nowMs) {
+    if (!provider) return "unknown";
+    const entry = providerOutcomeState.get(provider);
+    if (!entry) return "unknown";
+    const ageMs = nowMs - entry.lastOutcomeAtMs;
+    if (ageMs >= POOL_OUTCOME_FRESHNESS_MS) return "unknown";
+    return entry.lastOutcome;
+  }
+
+  function projectProviderUsageSnapshot(nowMs) {
+    const currentNow = Number.isFinite(nowMs) ? nowMs : now();
+    const cacheState = providerUsageCacheState(currentNow);
+    if (!cacheState.summary) {
+      return emptyProviderUsageSnapshot(cacheState.fetchedAtMs);
+    }
+    const { sessionKey, provider } = activeProviderContext();
+    const projected = selectProviderUsageSnapshot(cacheState.summary, {
+      sessionKey,
+      provider,
+      stale: cacheState.stale,
+    });
+    if (!projected) {
+      return emptyProviderUsageSnapshot(cacheState.fetchedAtMs, cacheState.stale);
+    }
+    return {
+      ...projected,
+      poolStatus: computePoolStatus(provider, currentNow),
+      totalProfileCount: cachedAuthProfileCounts.has(provider)
+        ? cachedAuthProfileCounts.get(provider)
+        : null,
+    };
+  }
+
+  async function fetchAuthProfileCounts() {
+    const result = await gatewayBridge.request("models.authStatus", {});
+    const next = new Map();
+    const providers = Array.isArray(result && result.providers) ? result.providers : [];
+    for (const entry of providers) {
+      const provider = normalizeProviderId(entry && entry.provider);
+      if (!provider) continue;
+      const profiles = Array.isArray(entry && entry.profiles) ? entry.profiles : [];
+      let count = 0;
+      for (const profile of profiles) {
+        const type = typeof profile?.type === "string" ? profile.type.trim().toLowerCase() : "";
+        if (type === "oauth" || type === "token") count += 1;
+      }
+      next.set(provider, count);
+    }
+    return next;
+  }
+
+  async function refreshProviderUsage(force) {
+    const snapshot = projectProviderUsageSnapshot();
+    if (!force && !snapshot.stale) {
+      return snapshot;
+    }
+    if (inFlightProviderUsageFetch) {
+      return inFlightProviderUsageFetch;
+    }
+    if (!openclawConnected) {
+      return snapshot;
+    }
+
+    inFlightProviderUsageFetch = (async () => {
+      const [usageResult, authStatusResult] = await Promise.allSettled([
+        gatewayBridge.request("usage.status", {}),
+        fetchAuthProfileCounts(),
+      ]);
+
+      if (authStatusResult.status === "fulfilled") {
+        cachedAuthProfileCounts.clear();
+        for (const [provider, count] of authStatusResult.value) {
+          cachedAuthProfileCounts.set(provider, count);
+        }
+      } else {
+        // Intentionally do NOT clear cachedAuthProfileCounts on rejection.
+        // Retain-on-failure preserves the caption count across transient blips;
+        // the next successful fetch overwrites. See spec
+        // 2026-05-07-rate-limit-pool-status-design.md (authStatus retain-on-failure).
+        emitDebug(
+          "relay.session",
+          "models_auth_status_refresh_failed",
+          "warn",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({
+            message: authStatusResult.reason && authStatusResult.reason.message
+              ? authStatusResult.reason.message
+              : String(authStatusResult.reason),
+            hadCount: cachedAuthProfileCounts.size > 0,
+          }),
+        );
+      }
+
+      if (usageResult.status === "fulfilled") {
+        const result = usageResult.value;
+        cachedProviderUsageSummary =
+          result && typeof result === "object" && !Array.isArray(result) ? result : {};
+        cachedProviderUsageObservedAt = now();
+        cachedProviderUsageFetchedAt =
+          Number.isFinite(result && result.updatedAt)
+            ? Math.floor(result.updatedAt)
+            : cachedProviderUsageObservedAt;
+        cachedProviderUsageStale = false;
+        const refreshedSnapshot = projectProviderUsageSnapshot(cachedProviderUsageObservedAt);
+        broadcastProviderUsageSnapshot(refreshedSnapshot);
+        return refreshedSnapshot;
+      }
+
+      const err = usageResult.reason;
+      emitDebug(
+        "relay.session",
+        "provider_usage_refresh_failed",
+        "warn",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          message: err && err.message ? err.message : String(err),
+          hadCache: !!providerUsageCacheState().summary,
+        }),
+      );
+      cachedProviderUsageStale = true;
+      if (!providerUsageCacheState().summary) {
+        cachedProviderUsageObservedAt = now();
+        cachedProviderUsageFetchedAt = cachedProviderUsageObservedAt;
+      }
+      const refreshedSnapshot = projectProviderUsageSnapshot();
+      broadcastProviderUsageSnapshot(refreshedSnapshot);
+      return refreshedSnapshot;
+    })();
+
+    return inFlightProviderUsageFetch.finally(() => {
+      inFlightProviderUsageFetch = null;
+    });
+  }
+
   async function refreshModelCatalog(force) {
     const snapshot = modelCatalogSnapshot();
     if (!force && !snapshot.stale) {
@@ -550,7 +1136,7 @@ export function createUpstreamRuntime(opts = {}) {
           cachedModelsCatalogStale = true;
           return modelCatalogSnapshot();
         }
-        return cacheModelCatalog([], Date.now(), true);
+        return cacheModelCatalog([], now(), true);
       });
 
     return inFlightModelsCatalogFetch.finally(() => {
@@ -591,7 +1177,7 @@ export function createUpstreamRuntime(opts = {}) {
           cachedSkillsCatalogStale = true;
           return skillsCatalogSnapshot();
         }
-        return cacheSkillsCatalog([], Date.now(), true);
+        return cacheSkillsCatalog([], now(), true);
       });
 
     return inFlightSkillsCatalogFetch.finally(() => {
@@ -609,6 +1195,10 @@ export function createUpstreamRuntime(opts = {}) {
       ackAt: entry.ackAt || Date.now(),
       lifecycleStartAt: null,
       firstStreamingAt: null,
+      firstGatewayReceivedAt: null,
+      firstGatewayChars: null,
+      firstRelayBroadcastAt: null,
+      firstRelayBroadcastChars: null,
     });
   }
 
@@ -628,6 +1218,40 @@ export function createUpstreamRuntime(opts = {}) {
     return snapshot;
   }
 
+  async function getProviderUsageSnapshot() {
+    const snapshot = projectProviderUsageSnapshot();
+    if (snapshot.stale && openclawConnected) {
+      return refreshProviderUsage(true);
+    }
+    return snapshot;
+  }
+
+  async function handleCurrentSessionModelConfigChanged() {
+    // The session-context window is keyed by the active model, which only
+    // becomes known once the model config resolves. On connect that resolution
+    // happens AFTER the initial connect-time context refresh has already run
+    // with a null model key, so a cached/persisted window for a cold (pre-turn)
+    // session would otherwise never be applied until the first turn warms the
+    // gateway's window. Re-refresh now that the model key is known so the
+    // cached window surfaces immediately; fire-and-forget so it doesn't block
+    // the provider-usage rebroadcast. Also keeps context correct across model
+    // switches.
+    sessionContextService.refreshActiveSessionContext().catch(() => {});
+
+    const snapshot = projectProviderUsageSnapshot();
+    if (snapshot.stale && openclawConnected) {
+      return refreshProviderUsage(true);
+    }
+    broadcastProviderUsageSnapshot(snapshot);
+    return snapshot;
+  }
+
+  async function handleCurrentSessionModelConfigCleared() {
+    const snapshot = emptyProviderUsageSnapshot(now(), false);
+    broadcastProviderUsageSnapshot(snapshot);
+    return snapshot;
+  }
+
   function handleSessionChanged(trigger) {
     if (!openclawConnected) {
       cachedSkillsCatalogStale = true;
@@ -638,6 +1262,76 @@ export function createUpstreamRuntime(opts = {}) {
     });
   }
 
+  function normalizeGatewayTimingEvent(raw) {
+    const source = raw && typeof raw === "object" ? raw : {};
+    const category =
+      source.category === "openclaw.run" || source.category === "relay.protocol"
+        ? source.category
+        : "relay.protocol";
+    const event =
+      typeof source.event === "string" && source.event.trim()
+        ? source.event.trim()
+        : "gateway_timing";
+    const severity =
+      source.severity === "debug" ||
+      source.severity === "info" ||
+      source.severity === "warn" ||
+      source.severity === "error"
+        ? source.severity
+        : "debug";
+    const context = source.context && typeof source.context === "object"
+      ? source.context
+      : {};
+    const data = source.data && typeof source.data === "object"
+      ? source.data
+      : {};
+    return {
+      category,
+      event,
+      severity,
+      context: {
+        sessionKey:
+          typeof context.sessionKey === "string" && context.sessionKey.trim()
+            ? context.sessionKey.trim()
+            : sessionService.ensureSessionKey(),
+        runId:
+          typeof context.runId === "string" && context.runId.trim()
+            ? context.runId.trim()
+            : null,
+      },
+      data,
+    };
+  }
+
+  // Session-context service: tracks contextTokens/contextWindow and broadcasts
+  // snapshots to connected WebUI clients. session.switch.applied trigger is
+  // deferred (see Task 4 plan notes — the switchSession path lives in
+  // downstream-handler.ts and is out of scope for this task).
+  let cachedRunActiveSessionKey = null;
+  // contextWindow is NOT resolved on a fresh session (the gateway warms a
+  // model's window only after the first turn). The service caches the observed
+  // window per model and reuses it for cold/new-session reads, keyed by the
+  // active session's resolved provider/model.
+  const sessionContextService = createSessionContextService({
+    gatewayBridge,
+    stateDir: opts.stateDir,
+    getActiveSessionKey: () => sessionService.ensureSessionKey() || null,
+    getActiveModelKey: () => {
+      const config = getCurrentSessionModelConfigSnapshot();
+      if (!config) return null;
+      const provider = normalizeProviderId(config.modelProvider);
+      const model = typeof config.model === "string" ? config.model.trim() : "";
+      if (!provider || !model) return null;
+      return modelRefKey(provider, model);
+    },
+    getRunActive: () => !!cachedRunActiveSessionKey,
+    nowMs: () => Date.now(),
+    broadcast: (frame) => {
+      const server = getServer();
+      if (server) server.broadcast(JSON.stringify(frame));
+    },
+  });
+
   gatewayBridge.on("history", (data) => {
     if (!sessionService.isCurrentSession(data.sessionKey)) return;
     emitDebug(
@@ -649,7 +1343,14 @@ export function createUpstreamRuntime(opts = {}) {
         messageCount: Array.isArray(data.messages) ? data.messages.length : 0,
       }),
     );
-    conversationState.hydrate(data.messages, agentName);
+    const sanitizedMessages = Array.isArray(data.messages)
+      ? data.messages.map((msg) =>
+          msg && msg.role === "assistant"
+            ? { ...msg, content: sanitizeAssistantContentBlocks(msg.content) }
+            : msg,
+        )
+      : data.messages;
+    conversationState.hydrate(sanitizedMessages, agentIdentity.name);
     broadcastPages();
   });
 
@@ -688,12 +1389,148 @@ export function createUpstreamRuntime(opts = {}) {
     );
   });
 
+  function sanitizeAssistantContentBlocks(content) {
+    if (typeof content === "string") {
+      return stripAllTaggedSpans(content);
+    }
+    if (!Array.isArray(content)) return content;
+    return content.map((block) => {
+      if (
+        block &&
+        typeof block === "object" &&
+        block.type === "text" &&
+        typeof block.text === "string"
+      ) {
+        return { ...block, text: stripAllTaggedSpans(block.text) };
+      }
+      return block;
+    });
+  }
+
+  // Unique sentinel characters used as span boundary markers through the markdown pass.
+  // These are ASCII control characters that never appear in assistant text.
+  const SPAN_START_MARK = "\x01";
+  const SPAN_END_MARK = "\x02";
+
+  function applyMarkdownWithSpans(parsed, prefix, conversationState) {
+    const { cleanText, spansByFamily } = parsed;
+    const familyNames = Object.keys(spansByFamily);
+    const totalSpans = familyNames.reduce(
+      (sum, name) => sum + spansByFamily[name].length,
+      0,
+    );
+    if (totalSpans === 0) {
+      const { text } = conversationState._markdownToPlainText(cleanText, {
+        stripReplyTags: true,
+      });
+      const empty = {};
+      for (const name of familyNames) empty[name] = [];
+      return { text: `${prefix}${text}`, spansByFamily: empty };
+    }
+    // Flatten all spans into one event list, tagged by family for routing back.
+    // Each span contributes two boundary events. Sort by offset, start-before-end on tie.
+    const events = [];
+    for (const family of familyNames) {
+      const spans = spansByFamily[family];
+      for (let i = 0; i < spans.length; i++) {
+        events.push({ offset: spans[i].start, family, spanIndex: i, isEnd: false });
+        events.push({ offset: spans[i].end, family, spanIndex: i, isEnd: true });
+      }
+    }
+    events.sort((a, b) => a.offset - b.offset || (a.isEnd ? 1 : -1));
+
+    // Build marked text, inserting one boundary marker per event.
+    let markedText = "";
+    let cursor = 0;
+    for (const ev of events) {
+      markedText += cleanText.slice(cursor, ev.offset);
+      cursor = ev.offset;
+      markedText += ev.isEnd ? SPAN_END_MARK : SPAN_START_MARK;
+    }
+    markedText += cleanText.slice(cursor);
+
+    // Run the full markdown pass on the marked text.
+    const { text: rawPost } = conversationState._markdownToPlainText(markedText, {
+      stripReplyTags: true,
+    });
+
+    // Strip markers from the post-markdown text and record their post-strip positions.
+    // Each marker, in document order, corresponds to the i-th event from `events`.
+    const eventPostPositions = [];
+    let stripped = "";
+    for (let j = 0; j < rawPost.length; j++) {
+      const ch = rawPost[j];
+      if (ch === SPAN_START_MARK || ch === SPAN_END_MARK) {
+        eventPostPositions.push(stripped.length);
+      } else {
+        stripped += ch;
+      }
+    }
+
+    const prefixLen = prefix.length;
+    const result = {};
+    for (const family of familyNames) {
+      result[family] = spansByFamily[family].map((s) => ({ ...s }));
+    }
+    for (let k = 0; k < events.length; k++) {
+      const ev = events[k];
+      const postPos = eventPostPositions[k] != null ? eventPostPositions[k] : 0;
+      const target = result[ev.family][ev.spanIndex];
+      if (!target) continue;
+      if (ev.isEnd) target.end = prefixLen + postPos;
+      else target.start = prefixLen + postPos;
+    }
+
+    return { text: `${prefix}${stripped}`, spansByFamily: result };
+  }
+
   gatewayBridge.on("message", (data) => {
     if (!sessionService.isCurrentSession(data.sessionKey)) return;
     const runId = data.runId || null;
+    if (runId) {
+      stopTypingForRun(runId, "assistant_message_committed");
+      // Flush any pending throttled streaming text BEFORE broadcasting the
+      // synthesized activity-idle. Pre-fix: activity-idle was broadcast first
+      // (below), and the final flushed streaming chunk arrived at the client
+      // AFTER stream_pipeline_turn_idle had already fired. The client's
+      // VoiceIngressCoordinator then treated the trailing chunk as the start
+      // of a new ingress turn (beginIngressStreamPipelineTurnIfNeeded returns
+      // true once streamTurnIdleLogged is set), resetting
+      // streaming_bleed_in_cursor_compose state and producing a visible
+      // ~50-char streaming-text rewind on hardware (trace
+      // 20260518-074144-Z ws 128→130). Flushing first ensures the final
+      // chunk is processed during the still-active turn; the synthesized
+      // activity-idle then runs after the buffer is up to date.
+      clearStreamingThrottleTimer();
+      flushPendingStreamingText();
+      // Synthesize an activity-idle broadcast at assistant-message-commit (=
+      // turn end at the gateway boundary). Upstream eventually emits its own
+      // terminal activity message via gatewayBridge.on("activity",...) but
+      // with ~1.5s median lag past run_complete, which leaves the
+      // thinking-indicator spinner ticking visibly past the point the agent
+      // has fully delivered its response. App-side ActivityGuardState dedupes
+      // the later upstream terminal message by runId + activityId so the real
+      // upstream activity remains authoritative for fields like detail/intent
+      // — this synth only owns the state=idle transition timing. activityId
+      // is namespaced so it cannot collide with a real upstream activityId.
+      // origin/phase=lifecycle/end satisfies isTerminalActivityBoundary so
+      // downstream consumers treat it as a real terminal boundary.
+      broadcastActivity({
+        state: "idle",
+        runId,
+        sessionKey: data.sessionKey || sessionService.ensureSessionKey(),
+        origin: "lifecycle",
+        phase: "end",
+        category: "run_complete_synth",
+        activityId: `run-complete-synth-${runId}`,
+      });
+    }
     const runPipeline = runId ? upstreamRunPipeline.get(runId) : null;
     if (runPipeline) {
       const completedAt = Date.now();
+      if (operationRegistry && typeof operationRegistry.markRunPhase === "function") {
+        operationRegistry.markRunPhase(runId, "complete");
+      }
       emitDebug(
         "relay.protocol",
         "run_complete",
@@ -730,10 +1567,26 @@ export function createUpstreamRuntime(opts = {}) {
       }),
     );
 
-    clearStreamingThrottleTimer();
-    flushPendingStreamingText();
-    conversationState.addMessage(data.role, data.content);
+    // (Moved above: flushPendingStreamingText now runs before broadcastActivity
+    //  so the client never sees a chunk arrive after stream_pipeline_turn_idle.)
+    const sanitizedContent =
+      data.role === "assistant"
+        ? sanitizeAssistantContentBlocks(data.content)
+        : data.content;
+    conversationState.addMessage(data.role, sanitizedContent);
+    if (data.role === "assistant") {
+      emitDebug(
+        "openclaw.message",
+        "agent_message",
+        "info",
+        { sessionKey: data.sessionKey || sessionService.ensureSessionKey() },
+        () => ({ text: fullMessageText(sanitizedContent), runId: data.runId || null }),
+      );
+    }
     broadcastPages();
+    // Refresh session context (token count) after each committed assistant
+    // message. Runs async so it doesn't block the message handler.
+    sessionContextService.refreshActiveSessionContext().catch(() => {});
 
     const voiceRuntime = getVoiceRuntime();
     if (voiceRuntime && typeof voiceRuntime.onAgentMessage === "function") {
@@ -752,11 +1605,15 @@ export function createUpstreamRuntime(opts = {}) {
       origin === "lifecycle" &&
       phase === "start"
     ) {
+      startTyping(runId, data.sessionKey, "lifecycle_start");
       const now = Date.now();
       const runPipeline = upstreamRunPipeline.get(runId);
       if (runPipeline && !runPipeline.lifecycleStartAt) {
         runPipeline.lifecycleStartAt = now;
       }
+      if (operationRegistry && typeof operationRegistry.markRunPhase === "function") {
+        operationRegistry.markRunPhase(runId, "lifecycle_start");
+      }
       emitDebug(
         "relay.protocol",
         "run_lifecycle_start",
@@ -768,62 +1625,155 @@ export function createUpstreamRuntime(opts = {}) {
           ackToRunStartMs: runPipeline && runPipeline.ackAt ? (now - runPipeline.ackAt) : null,
         }),
       );
+      // Signal run-start to session-context service so WebUI can show the
+      // spinner / suppress stale token counts during an active run.
+      cachedRunActiveSessionKey = data.sessionKey || sessionService.ensureSessionKey();
+      sessionContextService.broadcastRunActive(true);
+    }
+    if (runId && isTerminalActivityBoundary(data.state, phase, origin)) {
+      stopTypingForRun(runId, "terminal_activity_boundary");
+      // Run ended normally — clear run-active state and refresh token count.
+      if (cachedRunActiveSessionKey) {
+        cachedRunActiveSessionKey = null;
+        sessionContextService.broadcastRunActive(false);
+        sessionContextService.refreshActiveSessionContext().catch(() => {});
+      }
+    }
+    let activity = data;
+    let shouldRefreshProviderUsageInBackground = false;
+    if (isProviderRateLimitedLifecycleError(data)) {
+      if (!data.failoverPending) {
+        const { provider: outcomeProvider } = activeProviderContext();
+        if (outcomeProvider) {
+          providerOutcomeState.set(outcomeProvider, {
+            lastOutcome: "exhausted",
+            lastOutcomeAtMs: now(),
+          });
+        }
+      }
+      const rateLimitInfo = buildRateLimitInfoFromSnapshot(projectProviderUsageSnapshot());
+      if (rateLimitInfo) {
+        activity = {
+          ...data,
+          rateLimitInfo,
+        };
+      } else {
+        shouldRefreshProviderUsageInBackground = true;
+      }
+    }
+    broadcastActivity(activity);
+    if (shouldRefreshProviderUsageInBackground) {
+      refreshProviderUsage(true).catch((err) => {
+        logger.warn(`[relay] Provider usage refresh failed after rate limit activity: ${err.message}`);
+      });
+    }
+    if (runId && data.state === "idle" && data.isError === true && phase === "error") {
+      upstreamRunPipeline.delete(runId);
+      // Run ended with an error — clear run-active state and refresh token count.
+      if (cachedRunActiveSessionKey) {
+        cachedRunActiveSessionKey = null;
+        sessionContextService.broadcastRunActive(false);
+        sessionContextService.refreshActiveSessionContext().catch(() => {});
+      }
     }
-    broadcastActivity(data);
   });
 
   gatewayBridge.on("streaming", (data) => {
     if (!sessionService.isCurrentSession(data.sessionKey)) return;
+    const sessionKey = data.sessionKey || sessionService.ensureSessionKey();
+    const { provider: outcomeProvider } = activeProviderContext();
+    if (outcomeProvider) {
+      providerOutcomeState.set(outcomeProvider, {
+        lastOutcome: "ready",
+        lastOutcomeAtMs: now(),
+      });
+    }
     const runId = data.runId || null;
+    const nowMs = now();
+    const gatewayReceivedAtMs = Number.isFinite(data.gatewayReceivedAtMs)
+      ? Math.floor(data.gatewayReceivedAtMs)
+      : null;
+    const rawAssistantChars = Number.isFinite(data.rawAssistantChars)
+      ? Math.max(0, Math.floor(data.rawAssistantChars))
+      : (typeof data.text === "string" ? data.text.length : null);
+    const assistantDeltaChars = Number.isFinite(data.assistantDeltaChars)
+      ? Math.max(0, Math.floor(data.assistantDeltaChars))
+      : null;
+    const firstGatewayChunk =
+      typeof data.firstGatewayChunk === "boolean" ? data.firstGatewayChunk : null;
     if (runId) {
-      const now = Date.now();
       const runPipeline = upstreamRunPipeline.get(runId);
       if (runPipeline && !runPipeline.firstStreamingAt) {
-        runPipeline.firstStreamingAt = now;
+        runPipeline.firstStreamingAt = nowMs;
+        runPipeline.firstGatewayReceivedAt = gatewayReceivedAtMs;
+        runPipeline.firstGatewayChars = rawAssistantChars;
+        if (operationRegistry && typeof operationRegistry.markRunPhase === "function") {
+          operationRegistry.markRunPhase(runId, "first_stream");
+        }
         emitDebug(
           "relay.protocol",
           "run_first_streaming",
           "debug",
-          { sessionKey: data.sessionKey || sessionService.ensureSessionKey(), runId },
+          { sessionKey, runId },
           () => ({
             messageId: runPipeline.messageId,
-            sendToFirstStreamingMs: now - runPipeline.sendStartedAt,
-            ackToFirstStreamingMs: runPipeline.ackAt ? (now - runPipeline.ackAt) : null,
+            sendToFirstStreamingMs: nowMs - runPipeline.sendStartedAt,
+            ackToFirstStreamingMs: runPipeline.ackAt ? (nowMs - runPipeline.ackAt) : null,
             runStartToFirstStreamingMs: runPipeline.lifecycleStartAt
-              ? (now - runPipeline.lifecycleStartAt)
+              ? (nowMs - runPipeline.lifecycleStartAt)
               : null,
+            firstGatewayChars: rawAssistantChars,
+            gatewayToRelayIngressMs:
+              gatewayReceivedAtMs != null ? (nowMs - gatewayReceivedAtMs) : null,
           }),
         );
       }
     }
-    const { text } = conversationState._markdownToPlainText(data.text, {
-      stripReplyTags: true,
-    });
-    const prefix = agentName || "Agent";
-    pendingStreamingText = `${prefix}: ${text}`;
+    const prefix = `${agentIdentity.name || "Agent"}: `;
+    // Parse-on-flush coalescing: store the raw cumulative text and defer the
+    // parseTaggedSpans + markdown pass to flushPendingStreamingText. Chunks
+    // superseded inside the throttle window never pay parser cost.
+    pendingStreaming = {
+      rawText: data.text,
+      prefix,
+      sessionKey,
+      runId,
+      rawAssistantChars,
+      assistantDeltaChars,
+      firstGatewayChunk,
+      gatewayReceivedAtMs,
+      flushReason: "throttled_flush",
+    };
     emitDebug(
       "openclaw.run",
       "streaming",
       "debug",
       {
-        sessionKey: data.sessionKey || sessionService.ensureSessionKey(),
+        sessionKey,
         runId,
       },
       () => ({
-        textChars: pendingStreamingText.length,
+        // Raw cumulative chars: the parsed/markdown length is no longer
+        // computed here (parse-on-flush moves it to flushPendingStreamingText).
+        textChars: pendingStreaming ? pendingStreaming.rawText.length : 0,
+        rawAssistantChars,
+        assistantDeltaChars,
+        firstGatewayChunk,
+        gatewayReceivedAtMs,
+        gatewayToRelayIngressMs:
+          gatewayReceivedAtMs != null ? (nowMs - gatewayReceivedAtMs) : null,
       }),
     );
 
     if (!streamingThrottleTimer) {
-      const server = getServer();
-      if (server) {
-        server.broadcast(handler.formatStreaming(pendingStreamingText));
+      if (pendingStreaming) {
+        pendingStreaming.flushReason = "first_immediate";
       }
-      pendingStreamingText = null;
+      flushPendingStreamingText();
       streamingThrottleTimer = setTimeout(() => {
         streamingThrottleTimer = null;
         flushPendingStreamingText();
-      }, 150);
+      }, STREAMING_REBROADCAST_THROTTLE_MS);
     }
   });
 
@@ -832,15 +1782,27 @@ export function createUpstreamRuntime(opts = {}) {
   });
 
   gatewayBridge.on("agentIdentity", (data) => {
-    agentName = data && data.name ? data.name : null;
-    conversationState.setAgentName(agentName || "Agent");
-    broadcastStatus();
+    applyAgentIdentity(data, "agent_identity_event");
   });
 
   gatewayBridge.on("connected", () => {
     refreshUpstreamBootstrap("connected_event").catch((err) => {
       logger.warn(`[relay] Upstream connected bootstrap failed: ${err.message}`);
     });
+    // Give WebUI an initial session-context snapshot on reconnect so it has a
+    // baseline token count before the first agent_end refresh fires.
+    sessionContextService.refreshActiveSessionContext().catch(() => {});
+  });
+
+  gatewayBridge.on("timing", (rawEvent) => {
+    const timing = normalizeGatewayTimingEvent(rawEvent);
+    emitDebug(
+      timing.category,
+      timing.event,
+      timing.severity,
+      timing.context,
+      () => timing.data,
+    );
   });
 
   gatewayBridge.on("protocol", (data) => {
@@ -870,9 +1832,29 @@ export function createUpstreamRuntime(opts = {}) {
       "approval_requested",
       "info",
       { sessionKey: sessionService.ensureSessionKey() },
-      () => ({
-        approvalId: data && data.id ? data.id : null,
-      }),
+      () => {
+        const request = data && data.request ? data.request : {};
+        const approvalKind =
+          data && data.approvalKind === "plugin"
+            ? "plugin"
+            : data && typeof data.id === "string" && data.id.startsWith("plugin:")
+              ? "plugin"
+              : "exec";
+        const command =
+          typeof request.command === "string"
+            ? request.command
+            : approvalKind === "plugin" && typeof request.title === "string"
+              ? request.title
+              : "";
+        return {
+          approvalId: data && data.id ? data.id : null,
+          approvalKind,
+          host: typeof request.host === "string" ? request.host : null,
+          commandLength: command.length,
+          requestCommandIsEmpty: command.length === 0,
+          hasSystemRunPlan: !!(request.systemRunPlan && typeof request.systemRunPlan === "object"),
+        };
+      },
     );
     const server = getServer();
     if (server) {
@@ -909,9 +1891,19 @@ export function createUpstreamRuntime(opts = {}) {
   });
 
   return {
+    clearTyping,
+    compactActiveSession: (sessionKey) =>
+      sessionContextService.compactActiveSession(sessionKey),
     getAgentName,
+    getAgentEmoji,
+    getAgentAvatarDataUri,
+    getAgentAvatarHash,
+    getAgentAvatarDataUriByHash,
     getModelsCatalogSnapshot,
+    getProviderUsageSnapshot,
     getSkillsCatalogSnapshot,
+    handleCurrentSessionModelConfigChanged,
+    handleCurrentSessionModelConfigCleared,
     handleSessionChanged,
     isConnected,
     start() {
@@ -921,11 +1913,126 @@ export function createUpstreamRuntime(opts = {}) {
       clearStreamingThrottleTimer();
       clearBootstrapRefreshTimer();
       bootstrapRefreshNonce += 1;
-      pendingStreamingText = null;
+      pendingStreaming = null;
+      activeTyping = null;
       inFlightModelsCatalogFetch = null;
       inFlightSkillsCatalogFetch = null;
       upstreamRunPipeline.clear();
     },
     trackAcceptedRun,
   };
+
+  function isTerminalActivityBoundary(state, phase, origin) {
+    const normalizedOrigin = typeof origin === "string" ? origin.trim().toLowerCase() : "";
+    if (normalizedOrigin !== "lifecycle") {
+      return false;
+    }
+    const normalizedState = typeof state === "string" ? state.trim().toLowerCase() : "";
+    if (normalizedState === "idle" || normalizedState === "error") {
+      return true;
+    }
+    const normalizedPhase = typeof phase === "string" ? phase.trim().toLowerCase() : "";
+    return (
+      normalizedPhase === "error" ||
+      normalizedPhase === "end" ||
+      normalizedPhase === "complete" ||
+      normalizedPhase === "completed" ||
+      normalizedPhase === "done" ||
+      normalizedPhase === "failed" ||
+      normalizedPhase === "finish" ||
+      normalizedPhase === "finished"
+    );
+  }
+
+  function isProviderRateLimitedLifecycleError(activity) {
+    return !!(
+      activity &&
+      activity.isError === true &&
+      activity.code === "provider_rate_limited" &&
+      typeof activity.origin === "string" &&
+      activity.origin.trim().toLowerCase() === "lifecycle" &&
+      typeof activity.phase === "string" &&
+      activity.phase.trim().toLowerCase() === "error"
+    );
+  }
+
+  function emitTypingUpdate(state, runId, sessionKey, reason) {
+    const server = getServer();
+    if (
+      !server ||
+      !handler ||
+      typeof handler.formatTyping !== "function" ||
+      typeof runId !== "string" ||
+      !runId.trim()
+    ) {
+      return false;
+    }
+    const resolvedSessionKey =
+      typeof sessionKey === "string" && sessionKey.trim()
+        ? sessionKey.trim()
+        : sessionService.ensureSessionKey();
+    server.broadcast(
+      handler.formatTyping({
+        state,
+        runId: runId.trim(),
+        sessionKey: resolvedSessionKey,
+      }),
+    );
+    emitDebug(
+      "app.timeline",
+      "typing",
+      "debug",
+      { sessionKey: resolvedSessionKey, runId: runId.trim() },
+      () => ({
+        state,
+        reason: reason || null,
+      }),
+    );
+    return true;
+  }
+
+  function startTyping(runId, sessionKey, reason) {
+    if (typeof runId !== "string" || !runId.trim()) {
+      return false;
+    }
+    const normalizedRunId = runId.trim();
+    const resolvedSessionKey =
+      typeof sessionKey === "string" && sessionKey.trim()
+        ? sessionKey.trim()
+        : sessionService.ensureSessionKey();
+    if (activeTyping && activeTyping.runId === normalizedRunId) {
+      return false;
+    }
+    if (activeTyping) {
+      clearTyping("superseded_by_new_run");
+    }
+    activeTyping = {
+      runId: normalizedRunId,
+      sessionKey: resolvedSessionKey,
+    };
+    return emitTypingUpdate("start", normalizedRunId, resolvedSessionKey, reason);
+  }
+
+  function stopTypingForRun(runId, reason) {
+    if (
+      !activeTyping ||
+      typeof runId !== "string" ||
+      !runId.trim() ||
+      activeTyping.runId !== runId.trim()
+    ) {
+      return false;
+    }
+    const { runId: activeRunId, sessionKey } = activeTyping;
+    activeTyping = null;
+    return emitTypingUpdate("stop", activeRunId, sessionKey, reason);
+  }
+
+  function clearTyping(reason) {
+    if (!activeTyping) {
+      return false;
+    }
+    const { runId, sessionKey } = activeTyping;
+    activeTyping = null;
+    return emitTypingUpdate("stop", runId, sessionKey, reason || "clear_typing");
+  }
 }