ocuclaw 0.1.0

package/dist/runtime/upstream-runtime.js

@@ -0,0 +1,931 @@
+function normalizeLogger(logger) {
+  if (!logger || typeof logger !== "object") {
+    return console;
+  }
+  return {
+    info: typeof logger.info === "function" ? logger.info.bind(logger) : console.log,
+    warn: typeof logger.warn === "function" ? logger.warn.bind(logger) : console.warn,
+    error: typeof logger.error === "function" ? logger.error.bind(logger) : console.error,
+    debug:
+      typeof logger.debug === "function" ? logger.debug.bind(logger) : console.debug,
+  };
+}
+
+const DEFAULT_MODEL_PROVIDER = "anthropic";
+const DEFAULT_MODEL_ID = "claude-opus-4-6";
+
+function modelRefKey(provider, model) {
+  return `${provider}/${model}`;
+}
+
+function normalizeProviderId(rawProvider) {
+  const normalized = String(rawProvider || "").trim().toLowerCase();
+  if (normalized === "z.ai" || normalized === "z-ai") {
+    return "zai";
+  }
+  if (normalized === "opencode-zen") {
+    return "opencode";
+  }
+  if (normalized === "qwen") {
+    return "qwen-portal";
+  }
+  if (normalized === "kimi-code") {
+    return "kimi-coding";
+  }
+  return normalized;
+}
+
+function parseModelRef(raw, defaultProvider) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  const slash = trimmed.indexOf("/");
+  if (slash === -1) {
+    const provider = normalizeProviderId(defaultProvider);
+    if (!provider) return null;
+    return { provider, model: trimmed };
+  }
+  const provider = normalizeProviderId(trimmed.slice(0, slash));
+  const model = trimmed.slice(slash + 1).trim();
+  if (!provider || !model) return null;
+  return { provider, model };
+}
+
+function buildModelAliasIndex(config) {
+  const aliasIndex = new Map();
+  const modelEntries =
+    config &&
+    config.agents &&
+    config.agents.defaults &&
+    config.agents.defaults.models &&
+    typeof config.agents.defaults.models === "object" &&
+    !Array.isArray(config.agents.defaults.models)
+      ? config.agents.defaults.models
+      : {};
+  for (const [rawKey, rawEntry] of Object.entries(modelEntries)) {
+    const parsed = parseModelRef(String(rawKey || ""), DEFAULT_MODEL_PROVIDER);
+    if (!parsed) continue;
+    const alias =
+      rawEntry &&
+      typeof rawEntry === "object" &&
+      typeof rawEntry.alias === "string"
+        ? rawEntry.alias.trim()
+        : "";
+    if (!alias) continue;
+    aliasIndex.set(alias.toLowerCase(), parsed);
+  }
+  return aliasIndex;
+}
+
+function resolveModelRefFromString(raw, aliasIndex) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  if (!trimmed.includes("/")) {
+    const aliasMatch = aliasIndex.get(trimmed.toLowerCase());
+    if (aliasMatch) {
+      return aliasMatch;
+    }
+  }
+  return parseModelRef(trimmed, DEFAULT_MODEL_PROVIDER);
+}
+
+function resolveConfiguredDefaultModelRef(config, aliasIndex) {
+  const modelConfig =
+    config && config.agents && config.agents.defaults
+      ? config.agents.defaults.model
+      : undefined;
+  const rawModel = (() => {
+    if (typeof modelConfig === "string") return modelConfig.trim();
+    if (
+      modelConfig &&
+      typeof modelConfig === "object" &&
+      typeof modelConfig.primary === "string"
+    ) {
+      return modelConfig.primary.trim();
+    }
+    return "";
+  })();
+  if (rawModel) {
+    if (!rawModel.includes("/")) {
+      const aliasMatch = aliasIndex.get(rawModel.toLowerCase());
+      if (aliasMatch) {
+        return aliasMatch;
+      }
+      return { provider: DEFAULT_MODEL_PROVIDER, model: rawModel };
+    }
+    const parsed = resolveModelRefFromString(rawModel, aliasIndex);
+    if (parsed) {
+      return parsed;
+    }
+  }
+  return { provider: DEFAULT_MODEL_PROVIDER, model: DEFAULT_MODEL_ID };
+}
+
+function resolveConfiguredModelRefs(config) {
+  const aliasIndex = buildModelAliasIndex(config || {});
+  const refs = [];
+  const seen = new Set();
+
+  function addRef(ref) {
+    if (!ref || !ref.provider || !ref.model) return;
+    const key = modelRefKey(ref.provider, ref.model);
+    if (seen.has(key)) return;
+    seen.add(key);
+    refs.push(ref);
+  }
+
+  addRef(resolveConfiguredDefaultModelRef(config || {}, aliasIndex));
+
+  const modelConfig =
+    config && config.agents && config.agents.defaults
+      ? config.agents.defaults.model
+      : undefined;
+  const imageModelConfig =
+    config && config.agents && config.agents.defaults
+      ? config.agents.defaults.imageModel
+      : undefined;
+
+  const modelFallbacks =
+    modelConfig &&
+    typeof modelConfig === "object" &&
+    Array.isArray(modelConfig.fallbacks)
+      ? modelConfig.fallbacks
+      : [];
+  for (const raw of modelFallbacks) {
+    const parsed = resolveModelRefFromString(String(raw || ""), aliasIndex);
+    addRef(parsed);
+  }
+
+  const imagePrimary =
+    imageModelConfig &&
+    typeof imageModelConfig === "object" &&
+    typeof imageModelConfig.primary === "string"
+      ? imageModelConfig.primary.trim()
+      : "";
+  if (imagePrimary) {
+    const parsed = resolveModelRefFromString(imagePrimary, aliasIndex);
+    addRef(parsed);
+  }
+
+  const imageFallbacks =
+    imageModelConfig &&
+    typeof imageModelConfig === "object" &&
+    Array.isArray(imageModelConfig.fallbacks)
+      ? imageModelConfig.fallbacks
+      : [];
+  for (const raw of imageFallbacks) {
+    const parsed = resolveModelRefFromString(String(raw || ""), aliasIndex);
+    addRef(parsed);
+  }
+
+  const modelEntries =
+    config &&
+    config.agents &&
+    config.agents.defaults &&
+    config.agents.defaults.models &&
+    typeof config.agents.defaults.models === "object" &&
+    !Array.isArray(config.agents.defaults.models)
+      ? config.agents.defaults.models
+      : {};
+  for (const rawKey of Object.keys(modelEntries)) {
+    const parsed = parseModelRef(String(rawKey || ""), DEFAULT_MODEL_PROVIDER);
+    addRef(parsed);
+  }
+
+  return refs;
+}
+
+function extractConfigObject(configSnapshot) {
+  if (
+    configSnapshot &&
+    typeof configSnapshot === "object" &&
+    configSnapshot.config &&
+    typeof configSnapshot.config === "object" &&
+    !Array.isArray(configSnapshot.config)
+  ) {
+    return configSnapshot.config;
+  }
+  return {};
+}
+
+function mapConfiguredCatalogRows(modelsCatalogRows, configSnapshot) {
+  const byKey = new Map();
+  for (const row of modelsCatalogRows) {
+    byKey.set(modelRefKey(row.provider, row.id), row);
+  }
+  const config = extractConfigObject(configSnapshot);
+  const configuredRefs = resolveConfiguredModelRefs(config);
+  const out = [];
+  for (const ref of configuredRefs) {
+    const key = modelRefKey(ref.provider, ref.model);
+    const row = byKey.get(key);
+    if (row) {
+      out.push(row);
+    } else {
+      out.push({
+        provider: ref.provider,
+        id: ref.model,
+        name: ref.model,
+      });
+    }
+  }
+  return out;
+}
+
+function normalizeModelCatalogRows(rows) {
+  if (!Array.isArray(rows)) return [];
+  const out = [];
+  for (const row of rows) {
+    if (!row || typeof row !== "object") continue;
+    const provider =
+      typeof row.provider === "string" ? row.provider.trim() : "";
+    const id = typeof row.id === "string" ? row.id.trim() : "";
+    if (!provider || !id) continue;
+    const name =
+      typeof row.name === "string" && row.name.trim() ? row.name.trim() : id;
+    const model = { provider, id, name };
+    if (Number.isFinite(row.contextWindow) && row.contextWindow > 0) {
+      model.contextWindow = Math.floor(row.contextWindow);
+    }
+    if (typeof row.reasoning === "boolean") {
+      model.reasoning = row.reasoning;
+    }
+    out.push(model);
+  }
+  return out;
+}
+
+function normalizeSkillsCatalogRows(rows) {
+  if (!Array.isArray(rows)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const row of rows) {
+    if (!row || typeof row !== "object" || row.eligible !== true) continue;
+    const name = typeof row.name === "string" ? row.name.trim() : "";
+    if (!name) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({
+      name,
+      description:
+        typeof row.description === "string" && row.description.trim()
+          ? row.description.trim()
+          : "",
+    });
+  }
+  return out;
+}
+
+export function createUpstreamRuntime(opts = {}) {
+  const logger = normalizeLogger(opts.logger);
+  const gatewayBridge = opts.gatewayBridge;
+  const conversationState = opts.conversationState;
+  const sessionService = opts.sessionService;
+  const handler = opts.handler;
+  const emitDebug = typeof opts.emitDebug === "function" ? opts.emitDebug : () => {};
+  const broadcastPages =
+    typeof opts.broadcastPages === "function" ? opts.broadcastPages : () => {};
+  const broadcastStatus =
+    typeof opts.broadcastStatus === "function" ? opts.broadcastStatus : () => {};
+  const broadcastActivity =
+    typeof opts.broadcastActivity === "function"
+      ? opts.broadcastActivity
+      : (activity) => activity;
+  const resetActivityStatusAdapter =
+    typeof opts.resetActivityStatusAdapter === "function"
+      ? opts.resetActivityStatusAdapter
+      : () => {};
+  const getServer =
+    typeof opts.getServer === "function" ? opts.getServer : () => null;
+  const getVoiceRuntime =
+    typeof opts.getVoiceRuntime === "function" ? opts.getVoiceRuntime : () => null;
+
+  const modelsCacheTtlMs =
+    Number.isFinite(opts.modelsCacheTtlMs) && opts.modelsCacheTtlMs > 0
+      ? Math.floor(opts.modelsCacheTtlMs)
+      : 300000;
+
+  let openclawConnected = false;
+  let agentName = 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;
+  const upstreamRunPipeline = new Map();
+  let streamingThrottleTimer = null;
+  let pendingStreamingText = null;
+  let bootstrapRefreshTimer = null;
+  let bootstrapRefreshNonce = 0;
+
+  function getAgentName() {
+    return agentName;
+  }
+
+  function isConnected() {
+    return openclawConnected;
+  }
+
+  function clearStreamingThrottleTimer() {
+    if (!streamingThrottleTimer) return;
+    clearTimeout(streamingThrottleTimer);
+    streamingThrottleTimer = null;
+  }
+
+  function clearBootstrapRefreshTimer() {
+    if (!bootstrapRefreshTimer) return;
+    clearTimeout(bootstrapRefreshTimer);
+    bootstrapRefreshTimer = null;
+  }
+
+  function onConnectedStateEstablished(trigger) {
+    refreshModelCatalog(true).then((snapshot) => {
+      emitDebug(
+        "relay.session",
+        "models_catalog_prefetched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          count: Array.isArray(snapshot.models) ? snapshot.models.length : 0,
+          stale: !!snapshot.stale,
+          trigger,
+        }),
+      );
+    });
+    refreshSkillsCatalog(true).then((snapshot) => {
+      emitDebug(
+        "relay.session",
+        "skills_catalog_prefetched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          count: Array.isArray(snapshot.skills) ? snapshot.skills.length : 0,
+          stale: !!snapshot.stale,
+          trigger,
+        }),
+      );
+    });
+  }
+
+  function applyConnectedStatus(connected, trigger, emitTransportEvent = true) {
+    const wasConnected = openclawConnected;
+    openclawConnected = !!connected;
+    sessionService.handleUpstreamStatusChange(openclawConnected);
+    if (!openclawConnected) {
+      inFlightModelsCatalogFetch = null;
+      inFlightSkillsCatalogFetch = null;
+      cachedSkillsCatalogStale = true;
+      resetActivityStatusAdapter();
+    } else if (!wasConnected) {
+      onConnectedStateEstablished(trigger);
+    }
+    if (emitTransportEvent) {
+      emitDebug(
+        "relay.transport",
+        "upstream_status",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          status: openclawConnected ? "connected" : "disconnected",
+          trigger,
+        }),
+      );
+    }
+    broadcastStatus();
+  }
+
+  async function refreshUpstreamBootstrap(trigger, attempt = 0) {
+    const refreshNonce = ++bootstrapRefreshNonce;
+    clearBootstrapRefreshTimer();
+    const sessionKey = sessionService.ensureSessionKey();
+    const [statusResult, identityResult] = await Promise.allSettled([
+      gatewayBridge.request("status", {}),
+      gatewayBridge.request("agent.identity.get", { sessionKey }),
+    ]);
+    if (refreshNonce !== bootstrapRefreshNonce) return;
+
+    const statusOk = statusResult.status === "fulfilled";
+    const identityOk = identityResult.status === "fulfilled";
+
+    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();
+      }
+      return;
+    }
+
+    emitDebug(
+      "relay.transport",
+      "upstream_state_bootstrap_failed",
+      attempt >= 4 ? "warn" : "debug",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({
+        trigger,
+        attempt,
+        statusError:
+          statusResult.status === "rejected" && statusResult.reason
+            ? statusResult.reason.message || String(statusResult.reason)
+            : null,
+        identityError:
+          identityResult.status === "rejected" && identityResult.reason
+            ? identityResult.reason.message || String(identityResult.reason)
+            : null,
+      }),
+    );
+    if (attempt >= 4) return;
+    const retryDelayMs = Math.min(250 * (attempt + 1), 1000);
+    bootstrapRefreshTimer = setTimeout(() => {
+      bootstrapRefreshTimer = null;
+      refreshUpstreamBootstrap(trigger, attempt + 1).catch((err) => {
+        logger.warn(`[relay] Upstream bootstrap retry failed: ${err.message}`);
+      });
+    }, retryDelayMs);
+  }
+
+  function flushPendingStreamingText() {
+    if (!pendingStreamingText) return;
+    const server = getServer();
+    if (server) {
+      server.broadcast(handler.formatStreaming(pendingStreamingText));
+    }
+    pendingStreamingText = null;
+  }
+
+  function modelCatalogSnapshot(nowMs) {
+    const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+    const hasCache = Array.isArray(cachedModelsCatalog);
+    const ageMs = hasCache ? now - cachedModelsCatalogFetchedAt : Infinity;
+    const ttlExpired = ageMs >= modelsCacheTtlMs;
+    return {
+      models: hasCache ? cachedModelsCatalog : [],
+      fetchedAtMs: hasCache ? cachedModelsCatalogFetchedAt : now,
+      stale: !hasCache || cachedModelsCatalogStale || ttlExpired,
+    };
+  }
+
+  function cacheModelCatalog(models, fetchedAtMs, stale) {
+    cachedModelsCatalog = Array.isArray(models) ? models : [];
+    cachedModelsCatalogFetchedAt = Number.isFinite(fetchedAtMs)
+      ? Math.floor(fetchedAtMs)
+      : Date.now();
+    cachedModelsCatalogStale = !!stale;
+    return modelCatalogSnapshot(cachedModelsCatalogFetchedAt);
+  }
+
+  function skillsCatalogSnapshot(nowMs) {
+    const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+    const hasCache = Array.isArray(cachedSkillsCatalog);
+    return {
+      skills: hasCache ? cachedSkillsCatalog : [],
+      fetchedAtMs: hasCache ? cachedSkillsCatalogFetchedAt : now,
+      stale: !hasCache || cachedSkillsCatalogStale,
+    };
+  }
+
+  function cacheSkillsCatalog(skills, fetchedAtMs, stale) {
+    cachedSkillsCatalog = Array.isArray(skills) ? skills : [];
+    cachedSkillsCatalogFetchedAt = Number.isFinite(fetchedAtMs)
+      ? Math.floor(fetchedAtMs)
+      : Date.now();
+    cachedSkillsCatalogStale = !!stale;
+    return skillsCatalogSnapshot(cachedSkillsCatalogFetchedAt);
+  }
+
+  async function refreshModelCatalog(force) {
+    const snapshot = modelCatalogSnapshot();
+    if (!force && !snapshot.stale) {
+      return snapshot;
+    }
+    if (inFlightModelsCatalogFetch) {
+      return inFlightModelsCatalogFetch;
+    }
+    if (!openclawConnected) {
+      return snapshot;
+    }
+
+    inFlightModelsCatalogFetch = gatewayBridge
+      .request("models.list", {})
+      .then(async (result) => {
+        const allModels = normalizeModelCatalogRows(result && result.models);
+        const configSnapshot = await gatewayBridge.request("config.get", {});
+        const models = mapConfiguredCatalogRows(allModels, configSnapshot);
+        return cacheModelCatalog(models, Date.now(), false);
+      })
+      .catch((err) => {
+        emitDebug(
+          "relay.session",
+          "models_catalog_refresh_failed",
+          "warn",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({
+            message: err && err.message ? err.message : String(err),
+            hadCache: Array.isArray(cachedModelsCatalog),
+          }),
+        );
+        if (Array.isArray(cachedModelsCatalog)) {
+          cachedModelsCatalogStale = true;
+          return modelCatalogSnapshot();
+        }
+        return cacheModelCatalog([], Date.now(), true);
+      });
+
+    return inFlightModelsCatalogFetch.finally(() => {
+      inFlightModelsCatalogFetch = null;
+    });
+  }
+
+  async function refreshSkillsCatalog(force) {
+    const snapshot = skillsCatalogSnapshot();
+    if (!force && !snapshot.stale) {
+      return snapshot;
+    }
+    if (inFlightSkillsCatalogFetch) {
+      return inFlightSkillsCatalogFetch;
+    }
+    if (!openclawConnected) {
+      return snapshot;
+    }
+
+    inFlightSkillsCatalogFetch = gatewayBridge
+      .request("skills.status", {})
+      .then((result) => {
+        const skills = normalizeSkillsCatalogRows(result && result.skills);
+        return cacheSkillsCatalog(skills, Date.now(), false);
+      })
+      .catch((err) => {
+        emitDebug(
+          "relay.session",
+          "skills_catalog_refresh_failed",
+          "warn",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({
+            message: err && err.message ? err.message : String(err),
+            hadCache: Array.isArray(cachedSkillsCatalog),
+          }),
+        );
+        if (Array.isArray(cachedSkillsCatalog)) {
+          cachedSkillsCatalogStale = true;
+          return skillsCatalogSnapshot();
+        }
+        return cacheSkillsCatalog([], Date.now(), true);
+      });
+
+    return inFlightSkillsCatalogFetch.finally(() => {
+      inFlightSkillsCatalogFetch = null;
+    });
+  }
+
+  function trackAcceptedRun(entry) {
+    if (!entry || !entry.runId) return;
+    upstreamRunPipeline.set(entry.runId, {
+      runId: entry.runId,
+      sessionKey: entry.sessionKey || null,
+      messageId: entry.messageId || null,
+      sendStartedAt: entry.sendStartedAt || Date.now(),
+      ackAt: entry.ackAt || Date.now(),
+      lifecycleStartAt: null,
+      firstStreamingAt: null,
+    });
+  }
+
+  async function getModelsCatalogSnapshot() {
+    const snapshot = modelCatalogSnapshot();
+    if (snapshot.stale && openclawConnected) {
+      return refreshModelCatalog(true);
+    }
+    return snapshot;
+  }
+
+  async function getSkillsCatalogSnapshot() {
+    const snapshot = skillsCatalogSnapshot();
+    if (snapshot.stale && openclawConnected) {
+      return refreshSkillsCatalog(true);
+    }
+    return snapshot;
+  }
+
+  function handleSessionChanged(trigger) {
+    if (!openclawConnected) {
+      cachedSkillsCatalogStale = true;
+      return;
+    }
+    refreshSkillsCatalog(true).catch((err) => {
+      logger.warn(`[relay] Skills catalog refresh failed after ${trigger}: ${err.message}`);
+    });
+  }
+
+  gatewayBridge.on("history", (data) => {
+    if (!sessionService.isCurrentSession(data.sessionKey)) return;
+    emitDebug(
+      "openclaw.history",
+      "history",
+      "debug",
+      { sessionKey: data.sessionKey || sessionService.ensureSessionKey() },
+      () => ({
+        messageCount: Array.isArray(data.messages) ? data.messages.length : 0,
+      }),
+    );
+    conversationState.hydrate(data.messages, agentName);
+    broadcastPages();
+  });
+
+  gatewayBridge.on("thinkingDebug", (data) => {
+    if (!sessionService.isCurrentSession(data.sessionKey)) return;
+    emitDebug(
+      "openclaw.history",
+      "thinking_payload",
+      "debug",
+      {
+        sessionKey: data.sessionKey || sessionService.ensureSessionKey(),
+        runId: data.runId || null,
+      },
+      () => ({
+        source: data.source || null,
+        signatureId: data.signatureId || null,
+        rawKeys: Array.isArray(data.rawKeys) ? data.rawKeys : [],
+        rawPayload:
+          data.rawPayload && typeof data.rawPayload === "object" ? data.rawPayload : null,
+        summaryKey: data.summaryKey || null,
+        detailKey: data.detailKey || null,
+        labelKey: data.labelKey || null,
+        labelRaw: data.labelRaw || null,
+        labelSource: data.labelSource || null,
+        thinkingSummarySource: data.thinkingSummarySource || data.labelSource || null,
+        normalizedSummary: data.normalizedSummary || null,
+        normalizedDetail: data.normalizedDetail || null,
+        label: data.label || null,
+        detail: data.detail || null,
+        boldLabelCandidate: data.boldLabelCandidate || null,
+        boldLabelMatchesCurrentLabel:
+          typeof data.boldLabelMatchesCurrentLabel === "boolean"
+            ? data.boldLabelMatchesCurrentLabel
+            : null,
+      }),
+    );
+  });
+
+  gatewayBridge.on("message", (data) => {
+    if (!sessionService.isCurrentSession(data.sessionKey)) return;
+    const runId = data.runId || null;
+    const runPipeline = runId ? upstreamRunPipeline.get(runId) : null;
+    if (runPipeline) {
+      const completedAt = Date.now();
+      emitDebug(
+        "relay.protocol",
+        "run_complete",
+        "debug",
+        {
+          sessionKey: data.sessionKey || sessionService.ensureSessionKey(),
+          runId,
+        },
+        () => ({
+          messageId: runPipeline.messageId,
+          sendToCompleteMs: completedAt - runPipeline.sendStartedAt,
+          ackToCompleteMs: runPipeline.ackAt ? (completedAt - runPipeline.ackAt) : null,
+          runStartToCompleteMs: runPipeline.lifecycleStartAt
+            ? (completedAt - runPipeline.lifecycleStartAt)
+            : null,
+          firstStreamingToCompleteMs: runPipeline.firstStreamingAt
+            ? (completedAt - runPipeline.firstStreamingAt)
+            : null,
+        }),
+      );
+      upstreamRunPipeline.delete(runId);
+    }
+    emitDebug(
+      "openclaw.run",
+      "message",
+      "info",
+      {
+        sessionKey: data.sessionKey || sessionService.ensureSessionKey(),
+        runId,
+      },
+      () => ({
+        role: data.role || null,
+        contentBlocks: Array.isArray(data.content) ? data.content.length : 0,
+      }),
+    );
+
+    clearStreamingThrottleTimer();
+    flushPendingStreamingText();
+    conversationState.addMessage(data.role, data.content);
+    broadcastPages();
+
+    const voiceRuntime = getVoiceRuntime();
+    if (voiceRuntime && typeof voiceRuntime.onAgentMessage === "function") {
+      voiceRuntime.onAgentMessage();
+    }
+  });
+
+  gatewayBridge.on("activity", (data) => {
+    if (!sessionService.isCurrentSession(data.sessionKey)) return;
+    const runId = data.runId || null;
+    const origin = data.origin || null;
+    const phase = data.phase || null;
+    if (
+      runId &&
+      data.state === "thinking" &&
+      origin === "lifecycle" &&
+      phase === "start"
+    ) {
+      const now = Date.now();
+      const runPipeline = upstreamRunPipeline.get(runId);
+      if (runPipeline && !runPipeline.lifecycleStartAt) {
+        runPipeline.lifecycleStartAt = now;
+      }
+      emitDebug(
+        "relay.protocol",
+        "run_lifecycle_start",
+        "debug",
+        { sessionKey: data.sessionKey || sessionService.ensureSessionKey(), runId },
+        () => ({
+          messageId: runPipeline ? runPipeline.messageId : null,
+          sendToRunStartMs: runPipeline ? (now - runPipeline.sendStartedAt) : null,
+          ackToRunStartMs: runPipeline && runPipeline.ackAt ? (now - runPipeline.ackAt) : null,
+        }),
+      );
+    }
+    broadcastActivity(data);
+  });
+
+  gatewayBridge.on("streaming", (data) => {
+    if (!sessionService.isCurrentSession(data.sessionKey)) return;
+    const runId = data.runId || null;
+    if (runId) {
+      const now = Date.now();
+      const runPipeline = upstreamRunPipeline.get(runId);
+      if (runPipeline && !runPipeline.firstStreamingAt) {
+        runPipeline.firstStreamingAt = now;
+        emitDebug(
+          "relay.protocol",
+          "run_first_streaming",
+          "debug",
+          { sessionKey: data.sessionKey || sessionService.ensureSessionKey(), runId },
+          () => ({
+            messageId: runPipeline.messageId,
+            sendToFirstStreamingMs: now - runPipeline.sendStartedAt,
+            ackToFirstStreamingMs: runPipeline.ackAt ? (now - runPipeline.ackAt) : null,
+            runStartToFirstStreamingMs: runPipeline.lifecycleStartAt
+              ? (now - runPipeline.lifecycleStartAt)
+              : null,
+          }),
+        );
+      }
+    }
+    const { text } = conversationState._markdownToPlainText(data.text, {
+      stripReplyTags: true,
+    });
+    const prefix = agentName || "Agent";
+    pendingStreamingText = `${prefix}: ${text}`;
+    emitDebug(
+      "openclaw.run",
+      "streaming",
+      "debug",
+      {
+        sessionKey: data.sessionKey || sessionService.ensureSessionKey(),
+        runId,
+      },
+      () => ({
+        textChars: pendingStreamingText.length,
+      }),
+    );
+
+    if (!streamingThrottleTimer) {
+      const server = getServer();
+      if (server) {
+        server.broadcast(handler.formatStreaming(pendingStreamingText));
+      }
+      pendingStreamingText = null;
+      streamingThrottleTimer = setTimeout(() => {
+        streamingThrottleTimer = null;
+        flushPendingStreamingText();
+      }, 150);
+    }
+  });
+
+  gatewayBridge.on("status", (statusString) => {
+    applyConnectedStatus(statusString === "connected", "status_event");
+  });
+
+  gatewayBridge.on("agentIdentity", (data) => {
+    agentName = data && data.name ? data.name : null;
+    conversationState.setAgentName(agentName || "Agent");
+    broadcastStatus();
+  });
+
+  gatewayBridge.on("connected", () => {
+    refreshUpstreamBootstrap("connected_event").catch((err) => {
+      logger.warn(`[relay] Upstream connected bootstrap failed: ${err.message}`);
+    });
+  });
+
+  gatewayBridge.on("protocol", (data) => {
+    emitDebug(
+      "relay.protocol",
+      "protocol_frame",
+      "debug",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({
+        direction: data.direction || null,
+        frameType: data.frame && data.frame.type ? data.frame.type : null,
+      }),
+    );
+    const server = getServer();
+    if (!server) return;
+    const msg = handler.formatProtocol(data.direction, data.frame);
+    for (const clientId of server.getClientIds()) {
+      if (handler.isProtocolSubscriber(clientId)) {
+        server.unicast(clientId, msg);
+      }
+    }
+  });
+
+  gatewayBridge.on("approval", (data) => {
+    emitDebug(
+      "approvals.timeline",
+      "approval_requested",
+      "info",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({
+        approvalId: data && data.id ? data.id : null,
+      }),
+    );
+    const server = getServer();
+    if (server) {
+      server.broadcast(handler.formatApproval(data));
+    }
+  });
+
+  gatewayBridge.on("approvalResolved", (data) => {
+    emitDebug(
+      "approvals.timeline",
+      "approval_resolved",
+      "info",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({
+        approvalId: data && data.id ? data.id : null,
+        decision: data && data.decision ? data.decision : null,
+      }),
+    );
+    const server = getServer();
+    if (server) {
+      server.broadcast(handler.formatApprovalResolved(data));
+    }
+  });
+
+  gatewayBridge.on("error", (err) => {
+    logger.error(`[relay] Upstream error: ${err.message}`);
+    emitDebug(
+      "relay.transport",
+      "upstream_error",
+      "error",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({ message: err.message || null }),
+    );
+  });
+
+  return {
+    getAgentName,
+    getModelsCatalogSnapshot,
+    getSkillsCatalogSnapshot,
+    handleSessionChanged,
+    isConnected,
+    start() {
+      return refreshUpstreamBootstrap("runtime_start");
+    },
+    stop() {
+      clearStreamingThrottleTimer();
+      clearBootstrapRefreshTimer();
+      bootstrapRefreshNonce += 1;
+      pendingStreamingText = null;
+      inFlightModelsCatalogFetch = null;
+      inFlightSkillsCatalogFetch = null;
+      upstreamRunPipeline.clear();
+    },
+    trackAcceptedRun,
+  };
+}