@openclaw/plugin-inspector 0.3.17 → 0.3.18

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## Unreleased
+## 0.3.18 - 2026-07-21
+
+### Highlights
+
+- Keep compatibility capture current with OpenClaw's evolving hook, gateway, workspace-linking, blob-store, and Zod runtime surfaces.
+
+### Fixed
+
+- Mock the current plugin blob-store runtime so Diffs and other trusted plugins can be captured without persistent state.
+- Parse OpenClaw hook names after their source declaration became private and added a TypeScript `satisfies` constraint.
+- Run synthetic gateway lifecycle hooks around ordinary probes while preserving capture indexes and report order, so `gateway_stop` teardown cannot invalidate later compatibility checks.
+- Link isolated plugin workspaces to the OpenClaw checkout without npm normalizing duplicated dependency and peer declarations back to registry ranges.
+- Keep mocked Zod schemas chainable through unsupported methods such as `pipe()` and `catch()`.
 
 ## 0.3.17 - 2026-06-29
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/capture-api.js

@@ -194,6 +194,8 @@ function registrationReturnValue(name, args, context) {
 
 function createRuntimeContext(options) {
   const runtime = options.runtime ?? {};
+  const blobStores = new Map();
+  const syncKeyedStores = new Map();
   return {
     ...runtime,
     agent: runtime.agent ?? {},
@@ -203,11 +205,149 @@ function createRuntimeContext(options) {
     tts: runtime.tts ?? {},
     state: {
       resolveStateDir: () => options.stateDir ?? process.cwd(),
+      openBlobStore(storeOptions) {
+        const existing = blobStores.get(storeOptions.namespace);
+        if (existing) {
+          return existing;
+        }
+        const store = createBlobStoreContext(storeOptions);
+        blobStores.set(storeOptions.namespace, store);
+        return store;
+      },
+      openSyncKeyedStore({ namespace }) {
+        const existing = syncKeyedStores.get(namespace);
+        if (existing) {
+          return existing;
+        }
+        const store = createSyncKeyedStoreContext();
+        syncKeyedStores.set(namespace, store);
+        return store;
+      },
       ...(runtime.state ?? {}),
     },
   };
 }
 
+function createBlobStoreContext(options) {
+  const values = new Map();
+  const entryInfo = (key, entry) => ({
+    key,
+    metadata: entry.metadata,
+    sizeBytes: entry.bytes.byteLength,
+    createdAt: entry.createdAt,
+    ...(entry.expiresAt === undefined ? {} : { expiresAt: entry.expiresAt }),
+  });
+  const read = (key) => {
+    const entry = values.get(key);
+    if (!entry) {
+      return undefined;
+    }
+    if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+      return undefined;
+    }
+    return { ...entryInfo(key, entry), bytes: Uint8Array.from(entry.bytes) };
+  };
+  const register = async (key, bytes, metadata, registerOptions) => {
+    const createdAt = Date.now();
+    const ttlMs = registerOptions?.ttlMs ?? options.defaultTtlMs;
+    values.set(key, {
+      bytes: Uint8Array.from(bytes),
+      metadata,
+      createdAt,
+      ...(ttlMs === undefined ? {} : { expiresAt: createdAt + ttlMs }),
+    });
+  };
+  return {
+    register,
+    async registerIfAbsent(key, bytes, metadata, registerOptions) {
+      if (values.has(key)) {
+        return false;
+      }
+      await register(key, bytes, metadata, registerOptions);
+      return true;
+    },
+    async lookup(key) {
+      return read(key);
+    },
+    async entries() {
+      return [...values.keys()].flatMap((key) => {
+        const entry = read(key);
+        if (!entry) {
+          return [];
+        }
+        const { bytes: _bytes, ...info } = entry;
+        return [info];
+      });
+    },
+    async delete(key) {
+      return values.delete(key);
+    },
+    async deleteExpiredKey(key) {
+      const entry = values.get(key);
+      if (!entry || entry.expiresAt === undefined || entry.expiresAt > Date.now()) {
+        return undefined;
+      }
+      values.delete(key);
+      return entryInfo(key, entry);
+    },
+    async deleteExpired() {
+      const expired = [];
+      for (const [key, entry] of values) {
+        if (entry.expiresAt === undefined || entry.expiresAt > Date.now()) {
+          continue;
+        }
+        values.delete(key);
+        expired.push(entryInfo(key, entry));
+      }
+      return expired;
+    },
+    async clear() {
+      values.clear();
+    },
+  };
+}
+
+function createSyncKeyedStoreContext() {
+  const values = new Map();
+  return {
+    register(key, value) {
+      values.set(key, value);
+    },
+    registerIfAbsent(key, value) {
+      if (values.has(key)) {
+        return false;
+      }
+      values.set(key, value);
+      return true;
+    },
+    update(key, updateValue) {
+      const next = updateValue(values.get(key));
+      if (next === undefined) {
+        return false;
+      }
+      values.set(key, next);
+      return true;
+    },
+    lookup(key) {
+      return values.get(key);
+    },
+    consume(key) {
+      const value = values.get(key);
+      values.delete(key);
+      return value;
+    },
+    delete(key) {
+      return values.delete(key);
+    },
+    entries() {
+      return [...values].map(([key, value]) => ({ key, value, createdAt: 0 }));
+    },
+    clear() {
+      values.clear();
+    },
+  };
+}
+
 function createSecretContext(options) {
   const secrets = new Map(Object.entries(options.secretValues ?? {}));
   return {

package/src/link-openclaw-workspace-cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { writeJsonFileAtomic } from "./json-file.js";
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const specifier = process.argv[2];
+  await linkOpenClawWorkspace(path.resolve(process.cwd(), "package.json"), specifier);
+}
+
+export async function linkOpenClawWorkspace(packageJsonPath, specifier) {
+  if (typeof specifier !== "string" || !specifier.startsWith("file:")) {
+    throw new TypeError("link-openclaw-workspace requires a file: dependency specifier");
+  }
+
+  const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+  let linked = false;
+  for (const section of ["dependencies", "optionalDependencies"]) {
+    if (Object.hasOwn(packageJson[section] ?? {}, "openclaw")) {
+      packageJson[section].openclaw = specifier;
+      linked = true;
+    }
+  }
+
+  if (!linked) {
+    packageJson.dependencies ??= {};
+    packageJson.dependencies.openclaw = specifier;
+  }
+
+  await writeJsonFileAtomic(packageJsonPath, packageJson);
+}

package/src/openclaw-target.js

@@ -37,7 +37,7 @@ export async function readOpenClawTargetSurface(options = {}) {
   const registrySource = await readFile(registryPath, "utf8");
   const compatRecordEntries = parseCompatRecordEntries(registrySource);
   const hookTypesSource = existsSync(hookTypesPath) ? await readFile(hookTypesPath, "utf8") : "";
-  const hookNames = hookTypesSource ? parseExportedStringArray(hookTypesSource, "PLUGIN_HOOK_NAMES") : [];
+  const hookNames = hookTypesSource ? parseConstStringArray(hookTypesSource, "PLUGIN_HOOK_NAMES") : [];
   const apiBuilderSource = existsSync(apiBuilderPath) ? await readFile(apiBuilderPath, "utf8") : "";
   const apiRegistrars = apiBuilderSource ? parseApiRegistrars(apiBuilderSource) : [];
   const manifestTypesSource = existsSync(manifestTypesPath) ? await readFile(manifestTypesPath, "utf8") : "";
@@ -198,6 +198,15 @@ export function parsePluginSdkExports(packageJson) {
 
 export function parseExportedStringArray(source, exportName) {
   const match = source.match(new RegExp(`export\\s+const\\s+${exportName}\\s*=\\s*\\[([\\s\\S]*?)\\]\\s+as\\s+const`));
+  return parseStringArrayMatch(match);
+}
+
+function parseConstStringArray(source, constName) {
+  const match = source.match(new RegExp(`(?:export\\s+)?const\\s+${constName}\\s*=\\s*\\[([\\s\\S]*?)\\]\\s+as\\s+const`));
+  return parseStringArrayMatch(match);
+}
+
+function parseStringArrayMatch(match) {
   if (!match) {
     return [];
   }

package/src/sdk-mock.js

@@ -968,11 +968,11 @@ function createSchema(defaultValue, shape) {
     },
   };
   return new Proxy(schema, {
-    get(target, property) {
+    get(target, property, receiver) {
       if (property in target) {
         return target[property];
       }
-      return () => target;
+      return () => receiver;
     },
   });
 }

package/src/synthetic-probes.js

@@ -236,6 +236,11 @@ export const syntheticRegistrationExecutionProfiles = {
     callableProperties: [],
     reason: "session actions are captured as registration metadata before session runtime execution",
   },
+  registerSessionCatalog: {
+    mode: "metadata-only",
+    callableProperties: [],
+    reason: "session catalogs are captured as registration metadata before catalog runtime execution",
+  },
   registerService: {
     mode: "lifecycle-opt-in",
     callableProperties: ["start", "stop", "dispose"],
@@ -591,23 +596,37 @@ export async function runCapturedSyntheticProbes(capture, options = {}) {
   const hookContexts = options.hookContexts ?? defaultSyntheticHookContexts;
   const captured = capture.captured ?? [];
   const retained = new Map((capture.retained ?? []).map((item) => [item.captureIndex, item]));
-  const results = [];
+  const resultsByCaptureIndex = new Map();
+  const executionEntries = captured
+    .map((entry, captureIndex) => ({ entry, captureIndex }))
+    .sort(
+      (left, right) =>
+        syntheticLifecyclePhase(left.entry) - syntheticLifecyclePhase(right.entry) ||
+        left.captureIndex - right.captureIndex,
+    );
 
-  for (let index = 0; index < captured.length; index += 1) {
-    const entry = captured[index];
-    const retainedEntry = retained.get(index);
+  for (const { entry, captureIndex } of executionEntries) {
+    const retainedEntry = retained.get(captureIndex);
     if (!retainedEntry) {
-      results.push(blockedResult(entry, index, "handler retention was not enabled"));
+      resultsByCaptureIndex.set(captureIndex, [blockedResult(entry, captureIndex, "handler retention was not enabled")]);
       continue;
     }
     if (entry.kind === "hook") {
-      results.push(await runHookProbe(entry, retainedEntry, index, { hookEvents, hookContexts }));
+      resultsByCaptureIndex.set(captureIndex, [
+        await runHookProbe(entry, retainedEntry, captureIndex, { hookEvents, hookContexts }),
+      ]);
       continue;
     }
     if (entry.kind === "registration") {
-      results.push(...(await runRegistrationProbes(entry, retainedEntry, index, options)));
+      resultsByCaptureIndex.set(
+        captureIndex,
+        await runRegistrationProbes(entry, retainedEntry, captureIndex, options),
+      );
     }
   }
+  // Execute in lifecycle order, but keep report rows and captureIndex values
+  // stable for downstream consumers that compare artifacts across runs.
+  const results = captured.flatMap((_, captureIndex) => resultsByCaptureIndex.get(captureIndex) ?? []);
 
   return {
     entrypoint: capture.entrypoint,
@@ -622,6 +641,19 @@ export async function runCapturedSyntheticProbes(capture, options = {}) {
   };
 }
 
+function syntheticLifecyclePhase(entry) {
+  if (entry.kind !== "hook") {
+    return 1;
+  }
+  if (entry.name === "gateway_start") {
+    return 0;
+  }
+  if (entry.name === "gateway_stop") {
+    return 2;
+  }
+  return 1;
+}
+
 export function renderSyntheticProbeMarkdown(plan, options = {}) {
   return [
     `# ${options.title ?? "Plugin Inspector Synthetic Probes"}`,

package/src/workspace-plan.js

@@ -241,9 +241,10 @@ async function buildEntrypointPlan({ fixtureId, entrypoint, packageSummary, pack
   });
 
   if (requiredCapabilities.includes("target-openclaw-link")) {
+    const targetSpecifier = `file:${targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath)}`;
     steps.push({
       kind: "link-openclaw",
-      command: `${shellQuote(packageManager)} pkg set ${shellQuote(`dependencies.openclaw=file:${targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath)}`)}`,
+      command: `node ${shellQuote(helperScript(settings, workspacePath, settings.linkOpenClawWorkspaceScript, "link-openclaw-workspace-cli.js"))} ${shellQuote(targetSpecifier)}`,
       cwd: workspacePath,
       reason: "link the plugin's openclaw peer dependency to the target checkout under test",
     });
@@ -325,6 +326,7 @@ function workspaceSettings(options) {
   return {
     captureScript: options.captureScript ?? defaultWorkspacePlanOptions.captureScript,
     defaultTargetOpenClawWorkspacePath: options.defaultTargetOpenClawWorkspacePath ?? "../../../openclaw",
+    linkOpenClawWorkspaceScript: options.linkOpenClawWorkspaceScript,
     optInEnv: options.optInEnv ?? defaultWorkspacePlanOptions.optInEnv,
     resultsRoot: repoRelative(options.resultsRoot ?? defaultWorkspacePlanOptions.resultsRoot),
     rootDir: path.resolve(options.rootDir ?? process.cwd()),