@rrwebcloud/openclaw-session-recording 2026.3.28-1 → 2026.3.28-3

package/README.md

@@ -15,15 +15,17 @@ plugins:
   entries:
     rrweb-replay:
       enabled: true
-      publicKey: pk_live_your_public_key
-      extensionMode: bundled
+      publicKey: public_key_rr_your_public_key
 ```
 
 ## Notes
 
-- OpenClaw `2026.3.24+` uses the full automatic browser-runtime integration path
+- OpenClaw `2026.3.24+` uses the automatic browser-runtime integration path
 - OpenClaw `2026.3.13` loads in legacy compatibility mode and reports clear next steps instead of failing on install
 - `serverUrl` defaults to `https://api.rrwebcloud.com`
-- `secretKey` is not required for the bundled browser flow
+- `publicKey` is required for rrwebcloud ingest
+- `secretKey` is not required for recording; it is only needed if you want to query rrwebcloud APIs yourself
+- OpenClaw now records rrweb events locally and uploads authenticated NDJSON from runtime code; it does not rely on browser-side `record.js` ingest
+- 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

package/index.ts

@@ -2,9 +2,12 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { Type } from "@sinclair/typebox";
-import { readJsonFileWithFallback, writeJsonFileAtomically } from "openclaw/plugin-sdk/json-store";
-import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import { type AnyAgentTool, type OpenClawConfig } from "openclaw/plugin-sdk/plugin-entry";
+import {
+  definePluginEntry,
+  type AnyAgentTool,
+  type OpenClawConfig,
+  type OpenClawPluginApi,
+} from "openclaw/plugin-sdk/plugin-entry";
 
 type RrwebReplayConfig = {
   enabled: boolean;
@@ -39,6 +42,7 @@ 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 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.";
 
@@ -57,6 +61,8 @@ type BrowserRuntimeCompat = {
     replaySessionId: string;
     replayServerUrl?: string;
     replayUrl?: string;
+    replayPublicKey?: string;
+    replayRrwebCdnUrl?: string;
     updatedAt: string;
   }) => void;
   unregisterManagedBrowserExtensions: (sourceId: string) => void;
@@ -187,15 +193,44 @@ function resolvePluginStateFile(api: OpenClawPluginApi): string {
   );
 }
 
+async function readJsonFileWithFallbackLocal<T>(
+  filePath: string,
+  fallback: T,
+): Promise<{ value: T; exists: boolean }> {
+  try {
+    const raw = await fs.promises.readFile(filePath, "utf8");
+    return { value: JSON.parse(raw) as T, exists: true };
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") {
+      return { value: fallback, exists: false };
+    }
+    return { value: fallback, exists: false };
+  }
+}
+
+async function writeJsonFileAtomicallyLocal(filePath: string, value: unknown): Promise<void> {
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 }).catch(() => {
+    // Best-effort directory creation; write below will surface any real failure.
+  });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
+  await fs.promises.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await fs.promises.rename(tempPath, filePath);
+}
+
 async function loadReplayState(api: OpenClawPluginApi): Promise<ReplayStateStore> {
   const filePath = resolvePluginStateFile(api);
-  const { value } = await readJsonFileWithFallback<ReplayStateStore>(filePath, { sessions: {} });
+  const { value } = await readJsonFileWithFallbackLocal<ReplayStateStore>(filePath, {
+    sessions: {},
+  });
   return value;
 }
 
 async function saveReplayState(api: OpenClawPluginApi, state: ReplayStateStore): Promise<void> {
   const filePath = resolvePluginStateFile(api);
-  await writeJsonFileAtomically(filePath, state);
+  await writeJsonFileAtomicallyLocal(filePath, state);
 }
 
 function buildReplaySessionState(params: {
@@ -225,7 +260,6 @@ function buildReplaySessionState(params: {
 
 function describeReplayAvailability(params: {
   config: RrwebReplayConfig;
-  extensionDir: string | null;
   browserRuntimeAvailable: boolean;
 }): { enabled: boolean; reason?: string } {
   if (!params.config.enabled) {
@@ -237,12 +271,6 @@ function describeReplayAvailability(params: {
       reason: LEGACY_BROWSER_RUNTIME_REASON,
     };
   }
-  if (!params.extensionDir) {
-    return {
-      enabled: false,
-      reason: "Replay extension directory is missing. Check rrweb-replay.extensionMode/path.",
-    };
-  }
   const publicKey = resolveConfiguredSecret({
     value: params.config.publicKey,
     envVarName: params.config.publicKeyEnvVar,
@@ -313,6 +341,13 @@ function resolveBrowserProfileForReplay(params: {
   return { name: profileName, driver };
 }
 
+function resolveConfiguredPublicKey(config: RrwebReplayConfig): string | undefined {
+  return resolveConfiguredSecret({
+    value: config.publicKey,
+    envVarName: config.publicKeyEnvVar,
+  });
+}
+
 async function upsertReplaySession(params: {
   api: OpenClawPluginApi;
   config: RrwebReplayConfig;
@@ -425,6 +460,8 @@ async function armReplayContext(params: {
     replaySessionId: replayEntry.replaySessionId,
     replayServerUrl: replayEntry.replayServerUrl,
     replayUrl: replayEntry.replayUrl,
+    replayPublicKey: resolveConfiguredPublicKey(params.pluginConfig),
+    replayRrwebCdnUrl: DEFAULT_RRWEB_CDN_URL,
     updatedAt: new Date().toISOString(),
   });
   return await upsertReplaySession({
@@ -445,7 +482,6 @@ async function armReplayContext(params: {
 function createReplaySessionInfoTool(params: {
   api: OpenClawPluginApi;
   pluginConfig: RrwebReplayConfig;
-  extensionDir: string | null;
   browserRuntimePromise: Promise<BrowserRuntimeCompat | null>;
   context: {
     sessionKey?: string;
@@ -476,7 +512,6 @@ function createReplaySessionInfoTool(params: {
         rawParams && typeof rawParams === "object" ? (rawParams as Record<string, unknown>) : null;
       const availability = describeReplayAvailability({
         config: params.pluginConfig,
-        extensionDir: params.extensionDir,
         browserRuntimeAvailable: Boolean(browserRuntime),
       });
       const activate = toolParams?.activate === true;
@@ -530,7 +565,7 @@ function createReplaySessionInfoTool(params: {
   };
 }
 
-export default definePluginEntry({
+const rrwebReplayPlugin = {
   id: RRWEB_PLUGIN_ID,
   name: "rrweb Replay",
   description: "Portable rrweb replay bootstrap for OpenClaw-managed browsers.",
@@ -554,8 +589,8 @@ export default definePluginEntry({
           return;
         }
         if (!extensionDir) {
-          ctx.logger.warn(
-            "[rrweb-replay] extension directory missing; replay browser extension was not registered",
+          ctx.logger.info(
+            "[rrweb-replay] extension directory missing; continuing with runtime-side rrwebcloud upload only",
           );
           return;
         }
@@ -578,7 +613,6 @@ export default definePluginEntry({
       const browserRuntime = await browserRuntimePromise;
       const availability = describeReplayAvailability({
         config: pluginConfig,
-        extensionDir,
         browserRuntimeAvailable: Boolean(browserRuntime),
       });
       await upsertReplaySession({
@@ -621,7 +655,6 @@ export default definePluginEntry({
       const browserRuntime = await browserRuntimePromise;
       const availability = describeReplayAvailability({
         config: pluginConfig,
-        extensionDir,
         browserRuntimeAvailable: Boolean(browserRuntime),
       });
       if (event.toolName !== "browser" || pluginConfig.recordingPolicy !== "browser-only") {
@@ -649,7 +682,6 @@ export default definePluginEntry({
         createReplaySessionInfoTool({
           api,
           pluginConfig,
-          extensionDir,
           browserRuntimePromise,
           context: {
             sessionKey: context.sessionKey,
@@ -659,4 +691,6 @@ export default definePluginEntry({
       { name: "replay_session_info", optional: true },
     );
   },
-});
+};
+
+export default rrwebReplayPlugin;

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@rrwebcloud/openclaw-session-recording",
-  "version": "2026.3.28-1",
+  "version": "2026.3.28-3",
   "description": "OpenClaw rrweb replay plugin",
   "license": "MIT",
-  "type": "module",
   "files": [
     ".codex-plugin/",
     "README.md",
@@ -12,6 +11,10 @@
     "openclaw.plugin.json",
     "skills/"
   ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@sinclair/typebox": "0.34.48"
   },
@@ -26,11 +29,10 @@
       "optional": true
     }
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "openclaw": {
-    "extensions": ["./index.ts"],
+    "extensions": [
+      "./index.ts"
+    ],
     "install": {
       "npmSpec": "@rrwebcloud/openclaw-session-recording",
       "localPath": "extensions/rrweb-replay",

package/skills/rrweb-replay/SKILL.md

@@ -7,14 +7,15 @@ What it does:
 - Explains whether the `rrweb-replay` plugin is configured and active
 - Shows the current replay session id via `replay_session_info`
 - Helps activate replay context when `recordingPolicy` is `opt-in-tool`
-- Points you to browser profile and extension troubleshooting
+- Points you to browser profile and rrwebcloud upload troubleshooting
 
 Operational notes:
 
 - Runtime setup is handled by the native `rrweb-replay` plugin, not by this skill
 - The core browser runtime can also expose replay through `browser.replay.*` when the rrwebcloud extension artifact is wired directly into managed browser startup
 - The plugin targets OpenClaw-managed Chromium profiles such as `openclaw`
-- The streamlined OpenClaw path only needs a public key; the bundled browser bootstrap defaults to the rrweb Cloud API endpoint and does not require a secret key
+- 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
 - Minimal config:
 
 ```yaml
@@ -22,17 +23,15 @@ plugins:
   entries:
     rrweb-replay:
       enabled: true
-      publicKey: pk_live_your_public_key
-      extensionMode: bundled
+      publicKey: public_key_rr_your_public_key
 ```
 
 - If replay reports disabled, check:
-  - `browser.replay.enabled`
-  - `browser.replay.extensionPath`
   - `plugins.entries.rrweb-replay`
-  - `rrweb-replay.extensionMode` / `rrweb-replay.extensionPath`
   - `rrweb-replay.publicKey` or `rrweb-replay.publicKeyEnvVar`
-  - `browser.profiles.<name>.extensions` only if you are bypassing the plugin runtime seam
+  - `rrweb-replay.serverUrl` only if you intentionally override the default API host
+  - `browser.profiles.<name>.driver` is a managed profile such as `openclaw`
+  - `browser.profiles.<name>.extensions` only if you are intentionally layering extension-side behavior on top of runtime upload
 
 Useful command/tool flow:
 
@@ -42,7 +41,7 @@ Useful command/tool flow:
 
 Troubleshooting:
 
-- Missing extension directory: the bundled bootstrap extension was not staged; verify plugin install layout
+- Missing extension directory: runtime upload can still work; only extension-side behavior is unavailable
 - No replay session id: start a new OpenClaw session or use the browser tool so the plugin can bind session metadata
 - Wrong profile: pass `profile` to `replay_session_info activate=true` or use the browser tool with an explicit `profile`
 - Advanced setup: only override `rrweb-replay.serverUrl` if you are targeting a non-default replay API endpoint