ocuclaw 1.3.2 → 1.3.4

package/dist/runtime/upstream-runtime.js

@@ -8,6 +8,7 @@ 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";
+import { DISTILLER_SESSION_PREFIX } from "./session-title-distiller-helpers.js";
 
 function normalizeLogger(logger) {
   if (!logger || typeof logger !== "object") {
@@ -25,13 +26,26 @@ function normalizeLogger(logger) {
 const DEFAULT_MODEL_PROVIDER = "anthropic";
 const DEFAULT_MODEL_ID = "claude-opus-4-6";
 const POOL_OUTCOME_FRESHNESS_MS = 10 * 60 * 1000;
+const TITLE_DISTILLER_RUN_ID_PREFIX = "ocuclaw-title-";
+const TITLE_DISTILLER_SESSION_MARKER = ":title-distiller:";
 
-// 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 normalizeStreamingToken(raw) {
+  return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+
+function isTitleDistillerStreamingEvent(data) {
+  const runId = normalizeStreamingToken(data && data.runId);
+  if (runId && runId.startsWith(TITLE_DISTILLER_RUN_ID_PREFIX)) return true;
+  const sessionKey = normalizeStreamingToken(data && data.sessionKey);
+  return Boolean(
+    sessionKey &&
+      (sessionKey.startsWith(DISTILLER_SESSION_PREFIX) ||
+        sessionKey.includes(TITLE_DISTILLER_SESSION_MARKER)),
+  );
+}
+
 function fullMessageText(content) {
   if (typeof content === "string") return content;
   if (Array.isArray(content)) {
@@ -307,6 +321,232 @@ function normalizeSkillsCatalogRows(rows) {
   return out;
 }
 
+function isMethodNotFoundError(err, message) {
+  if (err && typeof err === "object") {
+    const code = err.code ?? (err.error && err.error.code);
+    if (code === -32601) return true;
+  }
+  const text = typeof message === "string" ? message.toLowerCase() : "";
+  return (
+    text.includes("method not found") ||
+    text.includes("unknown method") ||
+    text.includes("no such method") ||
+    text.includes("not supported")
+  );
+}
+
+function normalizeAgentsCatalogRows(rows) {
+  if (!Array.isArray(rows)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const row of rows) {
+    if (!row || typeof row !== "object") continue;
+    const id = typeof row.id === "string" ? row.id.trim() : "";
+    if (!id) continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const identity =
+      row.identity && typeof row.identity === "object" ? row.identity : {};
+    const identityName =
+      typeof identity.name === "string" && identity.name.trim()
+        ? identity.name.trim()
+        : "";
+    const baseName =
+      typeof row.name === "string" && row.name.trim() ? row.name.trim() : "";
+    const name = identityName || baseName || id;
+    const emoji =
+      typeof identity.emoji === "string" && identity.emoji.trim()
+        ? identity.emoji.trim()
+        : null;
+    const model = row.model && typeof row.model === "object" ? row.model : {};
+    const primaryModel =
+      typeof model.primary === "string" && model.primary.trim()
+        ? model.primary.trim()
+        : null;
+    out.push({ id, name, emoji, primaryModel });
+  }
+  return out;
+}
+
+const WORKSPACE_IDENTITY_FILENAME = "IDENTITY.md";
+
+const UPSTREAM_DEFAULT_IDENTITY_NAME = "Assistant";
+
+const IDENTITY_PLACEHOLDER_VALUES = new Set([
+  "pick something you like",
+  "ai? robot? familiar? ghost in the machine? something weirder?",
+  "how do you come across? sharp? warm? chaotic? calm?",
+  "your signature - pick one that feels right",
+  "workspace-relative path, http(s) url, or data uri",
+]);
+
+const IDENTITY_LABELS = new Set([
+  "name",
+  "emoji",
+  "creature",
+  "vibe",
+  "theme",
+  "avatar",
+]);
+
+function stripIdentityMarkup(value) {
+  let s = String(value == null ? "" : value).trim();
+  s = s.replace(/^[*_`\s]+|[*_`\s]+$/g, "").trim();
+  if (s.startsWith("(") && s.endsWith(")")) s = s.slice(1, -1).trim();
+  return s;
+}
+
+function normalizeIdentityLabel(raw) {
+  return raw.replace(/[*_`]/g, "").trim().toLowerCase();
+}
+
+function isIdentityPlaceholder(value) {
+  const normalized = String(value == null ? "" : value)
+    .replace(/[*_`()]/g, " ")
+    .replace(/[–—]/g, "-")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+  return IDENTITY_PLACEHOLDER_VALUES.has(normalized);
+}
+
+function looksLikeIdentityLabelLine(line) {
+  const cleaned = String(line).trim().replace(/^[-*]\s*/, "");
+  const colon = cleaned.indexOf(":");
+  if (colon === -1) return false;
+  return IDENTITY_LABELS.has(normalizeIdentityLabel(cleaned.slice(0, colon)));
+}
+
+const MAX_IDENTITY_NAME = 50;
+const MAX_IDENTITY_EMOJI = 16;
+
+function hasMeaningfulIdentityChars(value) {
+  return /[A-Za-z]/.test(value) || /[^\x00-\x7F]/.test(value);
+}
+
+function normalizeFallbackEmoji(value) {
+  const trimmed = stripIdentityMarkup(value);
+  if (!trimmed || trimmed.length > MAX_IDENTITY_EMOJI) return null;
+  if (trimmed.includes("/") || trimmed.includes("://")) return null;
+  let hasNonAscii = false;
+  for (let i = 0; i < trimmed.length; i += 1) {
+    if (trimmed.charCodeAt(i) > 127) {
+      hasNonAscii = true;
+      break;
+    }
+  }
+  return hasNonAscii ? trimmed : null;
+}
+
+function parseWorkspaceIdentityFallback(content) {
+  const result = {};
+  if (typeof content !== "string" || !content) return result;
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const cleaned = lines[i].trim().replace(/^[-*]\s*/, "");
+    const colon = cleaned.indexOf(":");
+    if (colon === -1) continue;
+    const label = normalizeIdentityLabel(cleaned.slice(0, colon));
+    if (label !== "name" && label !== "emoji") continue;
+    let value = stripIdentityMarkup(cleaned.slice(colon + 1));
+    if (!value) {
+
+      for (let j = i + 1; j < lines.length; j += 1) {
+        const peek = lines[j].trim();
+        if (!peek) continue;
+        if (peek.startsWith("#")) break;
+        if (/^(-{3,}|\*{3,}|_{3,})$/.test(peek)) break;
+        if (looksLikeIdentityLabelLine(peek)) break;
+        value = stripIdentityMarkup(peek);
+        break;
+      }
+    }
+    if (!value || isIdentityPlaceholder(value)) continue;
+    if (label === "name") {
+      if (!hasMeaningfulIdentityChars(value)) continue;
+      if (!result.name) {
+        result.name =
+          value.length > MAX_IDENTITY_NAME ? value.slice(0, MAX_IDENTITY_NAME) : value;
+      }
+    } else if (label === "emoji") {
+      const normalized = normalizeFallbackEmoji(value);
+      if (normalized && !result.emoji) result.emoji = normalized;
+    }
+  }
+  return result;
+}
+
+function applyIdentityFallback(identity, fallback) {
+  const name = identity && identity.name ? identity.name : null;
+  const emoji = identity && identity.emoji ? identity.emoji : null;
+  if (!fallback || (!fallback.name && !fallback.emoji)) return { name, emoji };
+
+  const needName = !name || (name === UPSTREAM_DEFAULT_IDENTITY_NAME && !emoji);
+  const needEmoji = !emoji;
+  return {
+    name: needName && fallback.name ? fallback.name : name,
+    emoji: needEmoji && fallback.emoji ? fallback.emoji : emoji,
+  };
+}
+
+function rawRowNameUnresolved(row) {
+  const identity =
+    row.identity && typeof row.identity === "object" ? row.identity : null;
+  const hasIdentityName =
+    identity && typeof identity.name === "string" && identity.name.trim();
+  const hasBaseName = typeof row.name === "string" && row.name.trim();
+  return !hasIdentityName && !hasBaseName;
+}
+
+function rawRowEmojiUnresolved(row) {
+  const identity =
+    row.identity && typeof row.identity === "object" ? row.identity : null;
+  return !(
+    identity &&
+    typeof identity.emoji === "string" &&
+    identity.emoji.trim()
+  );
+}
+
+function rawRowNeedsIdentityFallback(row) {
+  if (!row || typeof row !== "object") return false;
+  const id = typeof row.id === "string" ? row.id.trim() : "";
+  if (!id) return false;
+  return rawRowNameUnresolved(row) || rawRowEmojiUnresolved(row);
+}
+
+function lookupIdentityFallback(fallbackByAgentId, id) {
+  if (!fallbackByAgentId) return null;
+  if (typeof fallbackByAgentId.get === "function") {
+    return fallbackByAgentId.get(id) || null;
+  }
+  return fallbackByAgentId[id] || null;
+}
+
+function overlayRawAgentRowsWithFallback(rows, fallbackByAgentId) {
+  if (!Array.isArray(rows)) return [];
+  return rows.map((row) => {
+    if (!row || typeof row !== "object") return row;
+    const id = typeof row.id === "string" ? row.id.trim() : "";
+    if (!id) return row;
+    const fallback = lookupIdentityFallback(fallbackByAgentId, id);
+    if (!fallback || (!fallback.name && !fallback.emoji)) return row;
+    const fillName = rawRowNameUnresolved(row) && fallback.name;
+    const fillEmoji = rawRowEmojiUnresolved(row) && fallback.emoji;
+    if (!fillName && !fillEmoji) return row;
+    const identity =
+      row.identity && typeof row.identity === "object" ? row.identity : {};
+    return {
+      ...row,
+      identity: {
+        ...identity,
+        ...(fillName ? { name: fallback.name } : {}),
+        ...(fillEmoji ? { emoji: fallback.emoji } : {}),
+      },
+    };
+  });
+}
+
 export function createUpstreamRuntime(opts = {}) {
   const logger = normalizeLogger(opts.logger);
   const gatewayBridge = opts.gatewayBridge;
@@ -328,6 +568,10 @@ export function createUpstreamRuntime(opts = {}) {
     typeof opts.broadcastProviderUsageSnapshot === "function"
       ? opts.broadcastProviderUsageSnapshot
       : () => {};
+  const broadcastAgentsCatalog =
+    typeof opts.broadcastAgentsCatalog === "function"
+      ? opts.broadcastAgentsCatalog
+      : () => {};
   const getCurrentSessionModelConfigSnapshot =
     typeof opts.getCurrentSessionModelConfigSnapshot === "function"
       ? opts.getCurrentSessionModelConfigSnapshot
@@ -343,11 +587,7 @@ export function createUpstreamRuntime(opts = {}) {
 
   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) {
@@ -374,18 +614,15 @@ export function createUpstreamRuntime(opts = {}) {
   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);
@@ -495,36 +732,56 @@ export function createUpstreamRuntime(opts = {}) {
       : 60000;
 
   let openclawConnected = false;
-  /** @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;
   let cachedModelsCatalogStale = true;
-  /** @type {Promise<{models: Array, fetchedAtMs: number, stale: boolean}>|null} */
+
   let inFlightModelsCatalogFetch = null;
-  /** @type {Array<{name: string, description: string}>|null} */
+
   let cachedSkillsCatalog = null;
   let cachedSkillsCatalogFetchedAt = 0;
   let cachedSkillsCatalogStale = true;
-  /** @type {Promise<{skills: Array, fetchedAtMs: number, stale: boolean}>|null} */
+
   let inFlightSkillsCatalogFetch = null;
+
+  let cachedAgentsCatalog = null;
+  let cachedAgentsCatalogFetchedAt = 0;
+  let cachedAgentsCatalogStale = true;
+
+  let cachedAgentsEnvelope = { defaultId: null, mainKey: null, scope: null };
+
+  let agentsListUnsupported = false;
+
+  let inFlightAgentsCatalogFetch = 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 pendingStreaming = null;
-  /** @type {{runId: string, sessionKey: string}|null} */
+
   let activeTyping = null;
   let bootstrapRefreshTimer = null;
   let bootstrapRefreshNonce = 0;
 
+  const workspaceIdentityFallbackCache = new Map();
+
+  const inFlightWorkspaceIdentityFetches = new Map();
+
+  let lastGatewayIdentity = null;
+
+  let connectionGeneration = 0;
+
+  let workspaceIdentityFilesUnsupported = false;
+
   function getAgentName() {
     return agentIdentity.name;
   }
@@ -605,6 +862,20 @@ export function createUpstreamRuntime(opts = {}) {
         }),
       );
     });
+    refreshAgentsCatalog(true).then((snapshot) => {
+      emitDebug(
+        "relay.session",
+        "agents_catalog_prefetched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          count: Array.isArray(snapshot.agents) ? snapshot.agents.length : 0,
+          stale: !!snapshot.stale,
+          unsupported: !!snapshot.unsupported,
+          trigger,
+        }),
+      );
+    });
     sessionService.getCurrentSessionModelConfig().then((config) => {
       emitDebug(
         "relay.session",
@@ -627,12 +898,21 @@ export function createUpstreamRuntime(opts = {}) {
       clearTyping("upstream_disconnected");
       inFlightModelsCatalogFetch = null;
       inFlightSkillsCatalogFetch = null;
+      inFlightAgentsCatalogFetch = null;
       inFlightProviderUsageFetch = null;
+
+      connectionGeneration += 1;
+      lastGatewayIdentity = null;
+      workspaceIdentityFilesUnsupported = false;
+      workspaceIdentityFallbackCache.clear();
+      inFlightWorkspaceIdentityFetches.clear();
       cachedSkillsCatalogStale = true;
+      cachedAgentsCatalogStale = true;
+
+      agentsListUnsupported = false;
       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 ||
@@ -663,16 +943,67 @@ export function createUpstreamRuntime(opts = {}) {
     broadcastStatus();
   }
 
+  async function ensureWorkspaceIdentityFallback(agentId) {
+    const id = typeof agentId === "string" ? agentId.trim() : "";
+    if (!id) return null;
+    if (workspaceIdentityFilesUnsupported) return null;
+    if (workspaceIdentityFallbackCache.has(id)) {
+      return workspaceIdentityFallbackCache.get(id);
+    }
+    if (inFlightWorkspaceIdentityFetches.has(id)) {
+      return inFlightWorkspaceIdentityFetches.get(id);
+    }
+    const gen = connectionGeneration;
+    const promise = gatewayBridge
+      .request("agents.files.get", {
+        agentId: id,
+        name: WORKSPACE_IDENTITY_FILENAME,
+      })
+      .then((result) => {
+        const file = result && result.file;
+        const content =
+          file && typeof file.content === "string" ? file.content : "";
+        const parsed = parseWorkspaceIdentityFallback(content);
+        const value = parsed.name || parsed.emoji ? parsed : null;
+
+        if (gen === connectionGeneration) {
+          workspaceIdentityFallbackCache.set(id, value);
+        }
+        return value;
+      })
+      .catch((err) => {
+        const message = err && err.message ? err.message : String(err);
+
+        if (isMethodNotFoundError(err, message)) {
+          workspaceIdentityFilesUnsupported = true;
+        }
+
+        if (gen === connectionGeneration) {
+          workspaceIdentityFallbackCache.set(id, null);
+        }
+        emitDebug(
+          "relay.session",
+          "workspace_identity_fallback_failed",
+          "debug",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({ agentId: id, message }),
+        );
+        return null;
+      })
+      .finally(() => {
+        inFlightWorkspaceIdentityFetches.delete(id);
+      });
+    inFlightWorkspaceIdentityFetches.set(id, promise);
+    return promise;
+  }
+
   function applyAgentIdentity(identity, source) {
+    lastGatewayIdentity = identity || null;
     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;
@@ -698,6 +1029,17 @@ export function createUpstreamRuntime(opts = {}) {
       avatarDataUri: inlineAvatarDataUri,
       avatarHash: inlineAvatarHash,
     };
+    const fallback = agentId
+      ? workspaceIdentityFallbackCache.get(agentId)
+      : null;
+    if (fallback) {
+      const merged = applyIdentityFallback(
+        { name: next.name, emoji: next.emoji },
+        fallback,
+      );
+      next.name = merged.name;
+      next.emoji = merged.emoji;
+    }
     agentIdentity = next;
     conversationState.setAgentName(next.name || "Agent");
     emitDebug(
@@ -711,15 +1053,32 @@ export function createUpstreamRuntime(opts = {}) {
         hasEmoji: !!next.emoji,
         hasAvatarSource: !!avatarSource,
         avatarInline: !!inlineAvatarDataUri,
+        fallbackApplied: !!fallback,
       }),
     );
     broadcastStatus();
 
+    if (
+      agentId &&
+      !workspaceIdentityFallbackCache.has(agentId) &&
+      (!next.name || !next.emoji)
+    ) {
+      ensureWorkspaceIdentityFallback(agentId)
+        .then((value) => {
+          if (!value) return;
+
+          if (!openclawConnected) return;
+          if (lastGatewayIdentity !== identity) return;
+          applyAgentIdentity(identity, `${source}_workspace_fallback`);
+        })
+        .catch(() => {});
+    }
+
     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
@@ -808,8 +1167,7 @@ export function createUpstreamRuntime(opts = {}) {
           () => ({ 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,
@@ -916,6 +1274,54 @@ export function createUpstreamRuntime(opts = {}) {
     return skillsCatalogSnapshot(cachedSkillsCatalogFetchedAt);
   }
 
+  function agentsCatalogSnapshot(nowMs) {
+    const currentNow = Number.isFinite(nowMs) ? nowMs : now();
+    const hasCache = Array.isArray(cachedAgentsCatalog);
+    return {
+      agents: hasCache ? cachedAgentsCatalog : [],
+      defaultId: cachedAgentsEnvelope.defaultId,
+      mainKey: cachedAgentsEnvelope.mainKey,
+      scope: cachedAgentsEnvelope.scope,
+      fetchedAtMs: hasCache ? cachedAgentsCatalogFetchedAt : currentNow,
+      stale: !hasCache || cachedAgentsCatalogStale,
+      unsupported: agentsListUnsupported,
+    };
+  }
+
+  function cacheAgentsCatalog(agents, envelope, fetchedAtMs, stale) {
+    cachedAgentsCatalog = Array.isArray(agents) ? agents : [];
+    cachedAgentsEnvelope = {
+      defaultId:
+        envelope && typeof envelope.defaultId === "string" && envelope.defaultId
+          ? envelope.defaultId
+          : null,
+      mainKey:
+        envelope && typeof envelope.mainKey === "string" && envelope.mainKey
+          ? envelope.mainKey
+          : null,
+      scope:
+        envelope && typeof envelope.scope === "string" && envelope.scope
+          ? envelope.scope
+          : null,
+    };
+    cachedAgentsCatalogFetchedAt = Number.isFinite(fetchedAtMs)
+      ? Math.floor(fetchedAtMs)
+      : now();
+    cachedAgentsCatalogStale = !!stale;
+    const snapshot = agentsCatalogSnapshot(cachedAgentsCatalogFetchedAt);
+
+    broadcastAgentsCatalog(snapshot);
+    return snapshot;
+  }
+
+  function getAgentDisplayName(agentId) {
+    if (typeof agentId !== "string" || !agentId.trim()) return null;
+    const id = agentId.trim();
+    if (!Array.isArray(cachedAgentsCatalog)) return null;
+    const match = cachedAgentsCatalog.find((entry) => entry && entry.id === id);
+    return match ? match.name : null;
+  }
+
   function providerUsageCacheState(nowMs) {
     const currentNow = Number.isFinite(nowMs) ? nowMs : now();
     const hasCache =
@@ -1042,10 +1448,7 @@ export function createUpstreamRuntime(opts = {}) {
           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",
@@ -1185,6 +1588,76 @@ export function createUpstreamRuntime(opts = {}) {
     });
   }
 
+  async function refreshAgentsCatalog(force) {
+    const snapshot = agentsCatalogSnapshot();
+    if (agentsListUnsupported) {
+      return snapshot;
+    }
+    if (!force && !snapshot.stale) {
+      return snapshot;
+    }
+    if (inFlightAgentsCatalogFetch) {
+      return inFlightAgentsCatalogFetch;
+    }
+    if (!openclawConnected) {
+      return snapshot;
+    }
+
+    inFlightAgentsCatalogFetch = gatewayBridge
+      .request("agents.list", {})
+      .then(async (result) => {
+        const rawRows =
+          result && Array.isArray(result.agents) ? result.agents : [];
+
+        const needIds = rawRows
+          .filter(rawRowNeedsIdentityFallback)
+          .map((r) => r.id.trim());
+        if (needIds.length) {
+          await Promise.all(
+            needIds.map((id) => ensureWorkspaceIdentityFallback(id)),
+          );
+        }
+        const overlaid = overlayRawAgentRowsWithFallback(
+          rawRows,
+          workspaceIdentityFallbackCache,
+        );
+        const agents = normalizeAgentsCatalogRows(overlaid);
+        const envelope = {
+          defaultId: result && result.defaultId,
+          mainKey: result && result.mainKey,
+          scope: result && result.scope,
+        };
+        return cacheAgentsCatalog(agents, envelope, Date.now(), false);
+      })
+      .catch((err) => {
+        const message = err && err.message ? err.message : String(err);
+
+        if (isMethodNotFoundError(err, message)) {
+          agentsListUnsupported = true;
+        }
+        emitDebug(
+          "relay.session",
+          "agents_catalog_refresh_failed",
+          "warn",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({
+            message,
+            unsupported: agentsListUnsupported,
+            hadCache: Array.isArray(cachedAgentsCatalog),
+          }),
+        );
+        if (Array.isArray(cachedAgentsCatalog)) {
+          cachedAgentsCatalogStale = true;
+          return agentsCatalogSnapshot();
+        }
+        return cacheAgentsCatalog([], cachedAgentsEnvelope, now(), true);
+      });
+
+    return inFlightAgentsCatalogFetch.finally(() => {
+      inFlightAgentsCatalogFetch = null;
+    });
+  }
+
   function trackAcceptedRun(entry) {
     if (!entry || !entry.runId) return;
     upstreamRunPipeline.set(entry.runId, {
@@ -1218,6 +1691,16 @@ export function createUpstreamRuntime(opts = {}) {
     return snapshot;
   }
 
+  async function getAgentsCatalogSnapshot() {
+    const snapshot = agentsCatalogSnapshot();
+    if (snapshot.stale && !agentsListUnsupported && openclawConnected) {
+      return refreshAgentsCatalog(true);
+    }
+
+    broadcastAgentsCatalog(snapshot);
+    return snapshot;
+  }
+
   async function getProviderUsageSnapshot() {
     const snapshot = projectProviderUsageSnapshot();
     if (snapshot.stale && openclawConnected) {
@@ -1227,15 +1710,7 @@ export function createUpstreamRuntime(opts = {}) {
   }
 
   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();
@@ -1303,15 +1778,8 @@ export function createUpstreamRuntime(opts = {}) {
     };
   }
 
-  // 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,
@@ -1407,8 +1875,6 @@ export function createUpstreamRuntime(opts = {}) {
     });
   }
 
-  // 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";
 
@@ -1427,8 +1893,7 @@ export function createUpstreamRuntime(opts = {}) {
       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];
@@ -1439,7 +1904,6 @@ export function createUpstreamRuntime(opts = {}) {
     }
     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) {
@@ -1449,13 +1913,10 @@ export function createUpstreamRuntime(opts = {}) {
     }
     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++) {
@@ -1489,32 +1950,10 @@ export function createUpstreamRuntime(opts = {}) {
     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,
@@ -1567,8 +2006,6 @@ export function createUpstreamRuntime(opts = {}) {
       }),
     );
 
-    // (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)
@@ -1584,8 +2021,7 @@ export function createUpstreamRuntime(opts = {}) {
       );
     }
     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();
@@ -1625,19 +2061,26 @@ 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(() => {});
       }
+
+      if (!activeProviderContext().provider) {
+        sessionService.getCurrentSessionModelConfig().catch((err) => {
+          logger.warn(
+            `[relay] Provider re-resolve after run-end failed: ${err && err.message ? err.message : err}`,
+          );
+        });
+      }
     }
     let activity = data;
     let shouldRefreshProviderUsageInBackground = false;
@@ -1669,7 +2112,7 @@ export function createUpstreamRuntime(opts = {}) {
     }
     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);
@@ -1679,8 +2122,50 @@ export function createUpstreamRuntime(opts = {}) {
   });
 
   gatewayBridge.on("streaming", (data) => {
-    if (!sessionService.isCurrentSession(data.sessionKey)) return;
-    const sessionKey = data.sessionKey || sessionService.ensureSessionKey();
+    if (isTitleDistillerStreamingEvent(data)) {
+      const runId = data && data.runId ? data.runId : null;
+      const sessionKey = data && data.sessionKey ? data.sessionKey : sessionService.ensureSessionKey();
+      emitDebug(
+        "openclaw.run",
+        "streaming_ignored",
+        "debug",
+        { sessionKey, runId },
+        () => ({
+          reason: "title_distiller",
+          textChars: typeof data.text === "string" ? data.text.length : 0,
+        }),
+      );
+      return;
+    }
+    const runId = data.runId || null;
+    const runPipeline = runId ? upstreamRunPipeline.get(runId) : null;
+    const explicitSessionKey =
+      data && typeof data.sessionKey === "string" && data.sessionKey.trim()
+        ? data.sessionKey.trim()
+        : null;
+    const pipelineSessionKey =
+      runPipeline &&
+      typeof runPipeline.sessionKey === "string" &&
+      runPipeline.sessionKey.trim()
+        ? runPipeline.sessionKey.trim()
+        : null;
+    const sessionKey =
+      explicitSessionKey ||
+      pipelineSessionKey;
+    if (!sessionKey) {
+      emitDebug(
+        "openclaw.run",
+        "streaming_ignored",
+        "debug",
+        { sessionKey: null, runId },
+        () => ({
+          reason: "unknown_sessionless_run",
+          textChars: typeof data.text === "string" ? data.text.length : 0,
+        }),
+      );
+      return;
+    }
+    if (!sessionService.isCurrentSession(sessionKey)) return;
     const { provider: outcomeProvider } = activeProviderContext();
     if (outcomeProvider) {
       providerOutcomeState.set(outcomeProvider, {
@@ -1688,7 +2173,6 @@ export function createUpstreamRuntime(opts = {}) {
         lastOutcomeAtMs: now(),
       });
     }
-    const runId = data.runId || null;
     const nowMs = now();
     const gatewayReceivedAtMs = Number.isFinite(data.gatewayReceivedAtMs)
       ? Math.floor(data.gatewayReceivedAtMs)
@@ -1702,7 +2186,6 @@ export function createUpstreamRuntime(opts = {}) {
     const firstGatewayChunk =
       typeof data.firstGatewayChunk === "boolean" ? data.firstGatewayChunk : null;
     if (runId) {
-      const runPipeline = upstreamRunPipeline.get(runId);
       if (runPipeline && !runPipeline.firstStreamingAt) {
         runPipeline.firstStreamingAt = nowMs;
         runPipeline.firstGatewayReceivedAt = gatewayReceivedAtMs;
@@ -1730,9 +2213,7 @@ export function createUpstreamRuntime(opts = {}) {
       }
     }
     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,
@@ -1753,8 +2234,7 @@ export function createUpstreamRuntime(opts = {}) {
         runId,
       },
       () => ({
-        // 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,
@@ -1789,8 +2269,7 @@ export function createUpstreamRuntime(opts = {}) {
     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(() => {});
   });
 
@@ -1890,6 +2369,21 @@ export function createUpstreamRuntime(opts = {}) {
     );
   });
 
+  gatewayBridge.on("connectFailed", (info) => {
+
+    emitDebug(
+      "relay.transport",
+      "connect_failed",
+      "warn",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({
+        reason: info && info.reason ? info.reason : null,
+        minProtocol: info && info.minProtocol != null ? info.minProtocol : null,
+        maxProtocol: info && info.maxProtocol != null ? info.maxProtocol : null,
+      }),
+    );
+  });
+
   return {
     clearTyping,
     compactActiveSession: (sessionKey) =>
@@ -1900,6 +2394,8 @@ export function createUpstreamRuntime(opts = {}) {
     getAgentAvatarHash,
     getAgentAvatarDataUriByHash,
     getModelsCatalogSnapshot,
+    getAgentsCatalogSnapshot,
+    getAgentDisplayName,
     getProviderUsageSnapshot,
     getSkillsCatalogSnapshot,
     handleCurrentSessionModelConfigChanged,
@@ -1917,6 +2413,7 @@ export function createUpstreamRuntime(opts = {}) {
       activeTyping = null;
       inFlightModelsCatalogFetch = null;
       inFlightSkillsCatalogFetch = null;
+      inFlightAgentsCatalogFetch = null;
       upstreamRunPipeline.clear();
     },
     trackAcceptedRun,