@rrwebcloud/openclaw-session-recording 2026.3.28-2 → 2026.3.28-4

package/README.md

@@ -8,6 +8,14 @@ Portable rrweb replay plugin for OpenClaw-managed browsers.
 openclaw plugins install @rrwebcloud/openclaw-session-recording
 ```
 
+If you are working from this repository checkout instead of the published
+package, use:
+
+```bash
+openclaw plugins install -l ./extensions/rrweb-replay
+openclaw plugins install -l ./extensions/diagnostics-otel
+```
+
 ## Minimal config
 
 ```yaml
@@ -29,3 +37,4 @@ plugins:
 - the browser extension is optional for the runtime uploader path and is only needed when you specifically want extension-side behavior
 - the plugin targets managed Chromium browser profiles such as `openclaw`
 - `replay_session_info` exposes the active replay metadata
+- When `diagnostics-otel` is enabled, replay-aware spans include `openclaw.replay.*` attributes. See [Logging](../../docs/logging.md).

package/index.ts

@@ -30,6 +30,8 @@ type ReplaySessionState = {
   currentProfile?: string;
   currentCdpUrl?: string;
   recordingPolicy: RrwebReplayConfig["recordingPolicy"];
+  armed?: boolean;
+  legacyMetadataUploaded?: boolean;
   status: "active" | "ended";
   reason?: string;
   updatedAt: string;
@@ -42,8 +44,12 @@ type ReplayStateStore = {
 const RRWEB_PLUGIN_ID = "rrweb-replay";
 const DEFAULT_RRWEB_API_BASE_URL = "https://api.rrwebcloud.com";
 const DEFAULT_RRWEB_CDN_URL = "https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.js";
+const DEFAULT_GATEWAY_PORT = 18789;
+const LEGACY_REPLAY_WINDOW_KEY = "__openclawRrwebLegacyRecorder";
 const LEGACY_BROWSER_RUNTIME_REASON =
   "This OpenClaw host does not export plugin-sdk/browser-runtime. Automatic rrweb extension wiring requires OpenClaw >=2026.3.24. On legacy hosts, install/configure the rrweb browser addon separately or upgrade OpenClaw.";
+const LEGACY_DIRECT_INJECTION_REASON =
+  "Using legacy direct page injection because plugin-sdk/browser-runtime is unavailable on this host.";
 
 type BrowserRuntimeCompat = {
   clearManagedBrowserReplayContextsForSession: (sessionKey: string) => void;
@@ -251,6 +257,10 @@ function buildReplaySessionState(params: {
     currentProfile: params.previous?.currentProfile,
     currentCdpUrl: params.previous?.currentCdpUrl,
     recordingPolicy: params.config.recordingPolicy,
+    armed:
+      params.previous?.armed ??
+      (params.config.recordingPolicy === "browser-only" ? true : false),
+    legacyMetadataUploaded: params.previous?.legacyMetadataUploaded,
     status: "active",
     ...(params.reason ? { reason: params.reason } : {}),
     updatedAt,
@@ -266,8 +276,8 @@ function describeReplayAvailability(params: {
   }
   if (!params.browserRuntimeAvailable) {
     return {
-      enabled: false,
-      reason: LEGACY_BROWSER_RUNTIME_REASON,
+      enabled: true,
+      reason: LEGACY_DIRECT_INJECTION_REASON,
     };
   }
   const publicKey = resolveConfiguredSecret({
@@ -284,6 +294,233 @@ function describeReplayAvailability(params: {
   return { enabled: true };
 }
 
+function isFinitePositiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function resolveGatewayPort(config: OpenClawConfig): number {
+  const envPort = Number.parseInt(process.env.OPENCLAW_GATEWAY_PORT ?? "", 10);
+  if (Number.isFinite(envPort) && envPort > 0) {
+    return envPort;
+  }
+  const gateway = (config as { gateway?: { port?: unknown } }).gateway;
+  if (isFinitePositiveInteger(gateway?.port)) {
+    return Math.floor(gateway.port);
+  }
+  return DEFAULT_GATEWAY_PORT;
+}
+
+function resolveBrowserControlBaseUrl(config: OpenClawConfig): string {
+  return `http://127.0.0.1:${resolveGatewayPort(config) + 2}`;
+}
+
+function resolveBrowserControlHeaders(config: OpenClawConfig): Record<string, string> {
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  const auth = (config as { gateway?: { auth?: Record<string, unknown> } }).gateway?.auth;
+  if (!auth || typeof auth !== "object") {
+    return headers;
+  }
+  const token = typeof auth.token === "string" ? auth.token.trim() : "";
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+    return headers;
+  }
+  const password = typeof auth.password === "string" ? auth.password.trim() : "";
+  if (password) {
+    headers["x-openclaw-password"] = password;
+  }
+  return headers;
+}
+
+async function fetchJsonWithTimeout<T>(
+  url: string,
+  init: RequestInit & { timeoutMs?: number },
+): Promise<T> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(new Error("timed out")), init.timeoutMs ?? 20_000);
+  try {
+    const response = await fetch(url, { ...init, signal: ctrl.signal });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(body || `${response.status} ${response.statusText}`);
+    }
+    return (await response.json()) as T;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function buildBrowserControlUrl(config: OpenClawConfig, route: string, profile?: string): string {
+  const url = new URL(route, `${resolveBrowserControlBaseUrl(config)}/`);
+  if (profile?.trim()) {
+    url.searchParams.set("profile", profile.trim());
+  }
+  return url.toString();
+}
+
+function buildLegacyReplayPreviewUrl(serverUrl: string | undefined, replaySessionId: string): string {
+  return `${normalizeServerUrl(serverUrl) ?? DEFAULT_RRWEB_API_BASE_URL}/recordings/${replaySessionId}/preview`;
+}
+
+function buildLegacyReplayIngestUrl(serverUrl: string | undefined, replaySessionId: string): string {
+  return `${normalizeServerUrl(serverUrl) ?? DEFAULT_RRWEB_API_BASE_URL}/recordings/${replaySessionId}/ingest`;
+}
+
+function buildLegacyReplayMetadataEvent(params: {
+  sessionKey?: string;
+  sessionId?: string;
+  replaySessionId: string;
+}): Record<string, unknown> {
+  return {
+    timestamp: Date.now(),
+    type: 5,
+    data: {
+      tag: "recording-meta",
+      payload: {
+        session_key: params.sessionKey,
+        session_id: params.sessionId,
+        replay_session_id: params.replaySessionId,
+      },
+    },
+  };
+}
+
+function buildLegacyReplayInstallScript(params: {
+  replaySessionId: string;
+  replayUrl: string;
+  rrwebCdnUrl: string;
+}): string {
+  return `async () => {
+    const stateKey = ${JSON.stringify(LEGACY_REPLAY_WINDOW_KEY)};
+    const rrwebCdnUrl = ${JSON.stringify(params.rrwebCdnUrl)};
+    const replaySessionId = ${JSON.stringify(params.replaySessionId)};
+    const replayUrl = ${JSON.stringify(params.replayUrl)};
+    const state = window[stateKey] && typeof window[stateKey] === "object" ? window[stateKey] : {};
+    window[stateKey] = state;
+    state.recordingId = replaySessionId;
+    state.previewUrl = replayUrl;
+    state.queue = Array.isArray(state.queue) ? state.queue : [];
+    const ensureScript = () => new Promise((resolve, reject) => {
+      if (window.rrweb && typeof window.rrweb.record === "function") {
+        resolve();
+        return;
+      }
+      const selector = 'script[data-openclaw-rrweb="' + rrwebCdnUrl + '"]';
+      const existing = document.querySelector(selector);
+      if (existing) {
+        existing.addEventListener("load", () => resolve(), { once: true });
+        existing.addEventListener("error", () => reject(new Error("rrweb script failed to load")), { once: true });
+        return;
+      }
+      const script = document.createElement("script");
+      script.src = rrwebCdnUrl;
+      script.async = true;
+      script.dataset.openclawRrweb = rrwebCdnUrl;
+      script.onload = () => resolve();
+      script.onerror = () => reject(new Error("rrweb script failed to load"));
+      const parent = document.head || document.body || document.documentElement;
+      if (!parent) {
+        reject(new Error("No DOM parent available for rrweb script"));
+        return;
+      }
+      parent.appendChild(script);
+    });
+    if (!state.started) {
+      if (document.readyState === "loading") {
+        await new Promise((resolve) => document.addEventListener("DOMContentLoaded", resolve, { once: true }));
+      }
+      await ensureScript();
+      if (!window.rrweb || typeof window.rrweb.record !== "function") {
+        throw new Error("rrweb recorder unavailable");
+      }
+      state.stop = window.rrweb.record({
+        emit(event) {
+          state.queue.push(event);
+        },
+        recordCanvas: false,
+        collectFonts: false,
+      });
+      state.started = true;
+    }
+    window.__OPENCLAW_RRWEB_SESSION__ = {
+      sessionId: replaySessionId,
+      url: replayUrl,
+      provider: "rrwebcloud",
+    };
+    return {
+      ok: true,
+      replaySessionId,
+      replayUrl,
+      queued: Array.isArray(state.queue) ? state.queue.length : 0,
+    };
+  }`;
+}
+
+function buildLegacyReplayFlushScript(): string {
+  return `() => {
+    const state = window[${JSON.stringify(LEGACY_REPLAY_WINDOW_KEY)}];
+    if (!state || typeof state !== "object") {
+      return { ok: false, events: [] };
+    }
+    const queue = Array.isArray(state.queue) ? state.queue : [];
+    const events = queue.splice(0, queue.length);
+    return {
+      ok: true,
+      replaySessionId: typeof state.recordingId === "string" ? state.recordingId : undefined,
+      replayUrl: typeof state.previewUrl === "string" ? state.previewUrl : undefined,
+      events,
+    };
+  }`;
+}
+
+async function browserControlActEvaluate(params: {
+  config: OpenClawConfig;
+  profile: string;
+  targetId?: string;
+  fn: string;
+}): Promise<{ ok?: boolean; result?: unknown; targetId?: string; url?: string }> {
+  return await fetchJsonWithTimeout(
+    buildBrowserControlUrl(params.config, "/act", params.profile),
+    {
+      method: "POST",
+      headers: resolveBrowserControlHeaders(params.config),
+      body: JSON.stringify({
+        kind: "evaluate",
+        fn: params.fn,
+        ...(params.targetId ? { targetId: params.targetId } : {}),
+      }),
+    },
+  );
+}
+
+function resolveBrowserTargetId(params: {
+  eventParams: Record<string, unknown>;
+  result?: unknown;
+}): string | undefined {
+  const topLevel = typeof params.eventParams.targetId === "string" ? params.eventParams.targetId.trim() : "";
+  if (topLevel) {
+    return topLevel;
+  }
+  const nestedRequest =
+    params.eventParams.request && typeof params.eventParams.request === "object" && !Array.isArray(params.eventParams.request)
+      ? (params.eventParams.request as Record<string, unknown>)
+      : null;
+  const nested = typeof nestedRequest?.targetId === "string" ? nestedRequest.targetId.trim() : "";
+  if (nested) {
+    return nested;
+  }
+  if (params.result && typeof params.result === "object" && !Array.isArray(params.result)) {
+    const resultTargetId =
+      typeof (params.result as Record<string, unknown>).targetId === "string"
+        ? ((params.result as Record<string, unknown>).targetId as string).trim()
+        : "";
+    if (resultTargetId) {
+      return resultTargetId;
+    }
+  }
+  return undefined;
+}
+
 async function loadBrowserRuntimeCompat(): Promise<BrowserRuntimeCompat | null> {
   try {
     const mod = (await import("openclaw/plugin-sdk/browser-runtime")) as BrowserRuntimeCompat;
@@ -347,6 +584,148 @@ function resolveConfiguredPublicKey(config: RrwebReplayConfig): string | undefin
   });
 }
 
+async function ensureLegacyReplayCapture(params: {
+  api: OpenClawPluginApi;
+  pluginConfig: RrwebReplayConfig;
+  entry: ReplaySessionState;
+  profile: string;
+  targetId?: string;
+}): Promise<ReplaySessionState> {
+  const publicKey = resolveConfiguredPublicKey(params.pluginConfig);
+  if (!publicKey) {
+    return params.entry;
+  }
+  const replayUrl =
+    params.entry.replayUrl ??
+    buildLegacyReplayPreviewUrl(params.entry.replayServerUrl, params.entry.replaySessionId);
+  const response = await browserControlActEvaluate({
+    config: params.api.config,
+    profile: params.profile,
+    targetId: params.targetId,
+    fn: buildLegacyReplayInstallScript({
+      replaySessionId: params.entry.replaySessionId,
+      replayUrl,
+      rrwebCdnUrl: DEFAULT_RRWEB_CDN_URL,
+    }),
+  });
+  const payload =
+    response.result && typeof response.result === "object" && !Array.isArray(response.result)
+      ? (response.result as Record<string, unknown>)
+      : null;
+  const replaySessionId =
+    typeof payload?.replaySessionId === "string" && payload.replaySessionId.trim()
+      ? payload.replaySessionId.trim()
+      : params.entry.replaySessionId;
+  const nextReplayUrl =
+    typeof payload?.replayUrl === "string" && payload.replayUrl.trim()
+      ? payload.replayUrl.trim()
+      : replayUrl;
+  return await upsertReplaySession({
+    api: params.api,
+    config: params.pluginConfig,
+    sessionKey: params.entry.sessionKey,
+    sessionId: params.entry.sessionId,
+    mutate: (current) => ({
+      ...current,
+      replaySessionId,
+      replayUrl: nextReplayUrl,
+      currentProfile: params.profile,
+      armed: true,
+      reason: LEGACY_DIRECT_INJECTION_REASON,
+      updatedAt: new Date().toISOString(),
+    }),
+  });
+}
+
+async function flushLegacyReplayCapture(params: {
+  api: OpenClawPluginApi;
+  pluginConfig: RrwebReplayConfig;
+  entry: ReplaySessionState;
+  profile: string;
+  targetId?: string;
+}): Promise<ReplaySessionState> {
+  const publicKey = resolveConfiguredPublicKey(params.pluginConfig);
+  if (!publicKey) {
+    return params.entry;
+  }
+  const response = await browserControlActEvaluate({
+    config: params.api.config,
+    profile: params.profile,
+    targetId: params.targetId,
+    fn: buildLegacyReplayFlushScript(),
+  }).catch(() => null);
+  const payload =
+    response?.result && typeof response.result === "object" && !Array.isArray(response.result)
+      ? (response.result as Record<string, unknown>)
+      : null;
+  const replaySessionId =
+    typeof payload?.replaySessionId === "string" && payload.replaySessionId.trim()
+      ? payload.replaySessionId.trim()
+      : params.entry.replaySessionId;
+  const replayUrl =
+    typeof payload?.replayUrl === "string" && payload.replayUrl.trim()
+      ? payload.replayUrl.trim()
+      : params.entry.replayUrl ??
+        buildLegacyReplayPreviewUrl(params.entry.replayServerUrl, replaySessionId);
+  const events = Array.isArray(payload?.events)
+    ? payload.events.filter(
+        (event): event is Record<string, unknown> =>
+          Boolean(event && typeof event === "object" && !Array.isArray(event)),
+      )
+    : [];
+  if (events.length === 0 && params.entry.legacyMetadataUploaded) {
+    return params.entry;
+  }
+  const lines: string[] = [];
+  if (!params.entry.legacyMetadataUploaded) {
+    lines.push(
+      JSON.stringify(
+        buildLegacyReplayMetadataEvent({
+          sessionKey: params.entry.sessionKey,
+          sessionId: params.entry.sessionId,
+          replaySessionId,
+        }),
+      ),
+    );
+  }
+  for (const event of events) {
+    lines.push(JSON.stringify(event));
+  }
+  const ingestResponse = await fetch(
+    buildLegacyReplayIngestUrl(params.entry.replayServerUrl, replaySessionId),
+    {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${publicKey}`,
+        "content-type": "application/x-ndjson",
+      },
+      body: lines.join("\n"),
+    },
+  );
+  if (!ingestResponse.ok) {
+    const body = await ingestResponse.text().catch(() => "");
+    throw new Error(
+      `rrwebcloud ingest failed (${ingestResponse.status}): ${body || ingestResponse.statusText}`,
+    );
+  }
+  return await upsertReplaySession({
+    api: params.api,
+    config: params.pluginConfig,
+    sessionKey: params.entry.sessionKey,
+    sessionId: params.entry.sessionId,
+    mutate: (current) => ({
+      ...current,
+      replaySessionId,
+      replayUrl,
+      currentProfile: params.profile,
+      armed: true,
+      legacyMetadataUploaded: true,
+      reason: LEGACY_DIRECT_INJECTION_REASON,
+      updatedAt: new Date().toISOString(),
+    }),
+  });
+}
+
 async function upsertReplaySession(params: {
   api: OpenClawPluginApi;
   config: RrwebReplayConfig;
@@ -449,7 +828,24 @@ async function armReplayContext(params: {
     preferredProfile: params.preferredProfile ?? replayEntry.currentProfile,
   });
   if (!params.browserRuntime || !profile || !profile.cdpUrl) {
-    return replayEntry;
+    return await upsertReplaySession({
+      api: params.api,
+      config: params.pluginConfig,
+      sessionKey: params.sessionKey,
+      sessionId: params.sessionId,
+      mutate: (entry) => ({
+        ...entry,
+        replaySessionId: replayEntry.replaySessionId,
+        replayUrl:
+          replayEntry.replayUrl ??
+          buildLegacyReplayPreviewUrl(replayEntry.replayServerUrl, replayEntry.replaySessionId),
+        currentProfile: profile?.name ?? entry.currentProfile,
+        currentCdpUrl: profile?.cdpUrl ?? entry.currentCdpUrl,
+        armed: true,
+        reason: LEGACY_DIRECT_INJECTION_REASON,
+        updatedAt: new Date().toISOString(),
+      }),
+    });
   }
   params.browserRuntime.setManagedBrowserReplayContext({
     cdpUrl: profile.cdpUrl,
@@ -473,6 +869,7 @@ async function armReplayContext(params: {
       replaySessionId: replayEntry.replaySessionId,
       currentProfile: profile.name,
       currentCdpUrl: profile.cdpUrl,
+      armed: true,
       updatedAt: new Date().toISOString(),
     }),
   });
@@ -584,7 +981,7 @@ const rrwebReplayPlugin = {
           return;
         }
         if (!browserRuntime) {
-          ctx.logger.warn(`[rrweb-replay] ${LEGACY_BROWSER_RUNTIME_REASON}`);
+          ctx.logger.warn(`[rrweb-replay] ${LEGACY_DIRECT_INJECTION_REASON}`);
           return;
         }
         if (!extensionDir) {
@@ -656,7 +1053,7 @@ const rrwebReplayPlugin = {
         config: pluginConfig,
         browserRuntimeAvailable: Boolean(browserRuntime),
       });
-      if (event.toolName !== "browser" || pluginConfig.recordingPolicy !== "browser-only") {
+      if (event.toolName !== "browser") {
         return;
       }
       if (!availability.enabled) {
@@ -666,7 +1063,7 @@ const rrwebReplayPlugin = {
         typeof event.params.profile === "string" && event.params.profile.trim()
           ? event.params.profile.trim()
           : undefined;
-      await armReplayContext({
+      const replayEntry = await armReplayContext({
         api,
         pluginConfig,
         browserRuntime,
@@ -674,6 +1071,59 @@ const rrwebReplayPlugin = {
         sessionId: ctx.sessionId,
         preferredProfile: rawProfile,
       });
+      if (browserRuntime || !replayEntry.armed) {
+        return;
+      }
+      const targetId = resolveBrowserTargetId({ eventParams: event.params });
+      const profile =
+        rawProfile || replayEntry.currentProfile || pluginConfig.browserProfiles[0] || "openclaw";
+      await ensureLegacyReplayCapture({
+        api,
+        pluginConfig,
+        entry: replayEntry,
+        profile,
+        targetId,
+      }).catch(() => undefined);
+    });
+
+    api.on("after_tool_call", async (event, ctx) => {
+      const browserRuntime = await browserRuntimePromise;
+      if (event.toolName !== "browser" || browserRuntime) {
+        return;
+      }
+      const replayEntry = await getReplaySessionEntry({
+        api,
+        sessionKey: ctx.sessionKey,
+        sessionId: ctx.sessionId,
+      });
+      if (!replayEntry?.armed) {
+        return;
+      }
+      const profile =
+        (typeof event.params.profile === "string" && event.params.profile.trim()) ||
+        replayEntry.currentProfile ||
+        pluginConfig.browserProfiles[0] ||
+        "openclaw";
+      const targetId = resolveBrowserTargetId({
+        eventParams: event.params,
+        result: event.result,
+      });
+      const prepared = await ensureLegacyReplayCapture({
+        api,
+        pluginConfig,
+        entry: replayEntry,
+        profile,
+        targetId,
+      }).catch(() => replayEntry);
+      await flushLegacyReplayCapture({
+        api,
+        pluginConfig,
+        entry: prepared,
+        profile,
+        targetId,
+      }).catch((err) => {
+        api.logger.warn(`[rrweb-replay] legacy capture flush failed: ${String(err)}`);
+      });
     });
 
     api.registerTool(
@@ -692,4 +1142,13 @@ const rrwebReplayPlugin = {
   },
 };
 
+export const __testing = {
+  buildLegacyReplayInstallScript,
+  buildLegacyReplayFlushScript,
+  buildLegacyReplayIngestUrl,
+  buildLegacyReplayPreviewUrl,
+  resolveBrowserControlBaseUrl,
+  resolveBrowserControlHeaders,
+};
+
 export default rrwebReplayPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rrwebcloud/openclaw-session-recording",
-  "version": "2026.3.28-2",
+  "version": "2026.3.28-4",
   "description": "OpenClaw rrweb replay plugin",
   "license": "MIT",
   "files": [

package/skills/rrweb-replay/SKILL.md

@@ -16,6 +16,7 @@ Operational notes:
 - The plugin targets OpenClaw-managed Chromium profiles such as `openclaw`
 - The streamlined OpenClaw path records rrweb events in the managed browser and uploads authenticated NDJSON from runtime code
 - The streamlined OpenClaw path only needs a public key; the rrweb Cloud API endpoint defaults to `https://api.rrwebcloud.com` and recording does not require a secret key
+- When `diagnostics-otel` is enabled, replay metadata is also exported on spans as `openclaw.replay.*`
 - Minimal config:
 
 ```yaml