@openclaw/plugin-inspector 0.3.23 → 0.3.25

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.3.25 - 2026-09-09
+
+### Fixed
+
+- Invoke each synthetic Gateway method once, including registrations with options, and validate its first emitted response's JSON wire representation instead of treating any nonthrowing callback as successful. Preserve explicit response authority, returned-payload fallback, deferred replies within the existing deadline, and accepted-only initial responses.
+- Bound synthetic callback waits and cancellation, stop dependent probes after a timeout, and supervise CLI capture plus retained callbacks in one child. Validate report shape and counts before delivery while preserving complete failed-row reports, bounded plugin output, and in-process callback identity. Thanks @SebTardif.
+- Run `registerService` start, stop, and dispose probes serially so teardown cannot overlap startup.
+- Bound real-SDK CLI capture in an owned child, including stalled imports, busy registration, and retained timers. Give in-process capture a finite 30-second default deadline while preserving caller runtime and handler identity; arbitrary in-process JavaScript cannot be forcibly canceled. Thanks @SebTardif.
+- Capture and synthetically probe compiled CommonJS plugins with generated SDK mocks, including lazy `require()` calls, and discover their SDK source references. CommonJS mocking requires Node.js 22.15+ synchronous module hooks; the package engine and existing ESM/TypeScript capture remain unchanged.
+- Bound mock-SDK capture and profile child lifetimes, output, and process sampling; clean owned POSIX descendants through stdio close and keep timeout/cancellation outcomes unsuccessful. Flush complete capture JSON before exiting despite retained plugin timers. Thanks @SebTardif.
+- Profile the default import-loop capture runner directly so its timeout also owns plugin execution. Validate fresh, bounded capture artifacts; RSS/CPU and wall-time measurements now exclude the intermediate CLI wrapper and are not directly comparable with historical profiles.
+- Bound OpenClaw npm metadata and tarball downloads with a deadline through response-body reads, reject oversized responses, and release failed downloads. Resolve `latest` and `beta` through the small npm dist-tags endpoint before fetching exact-version metadata, keeping the 16 MiB metadata limit usable.
+- Capture plugins that bind `api.runtime.modelAuth` during registration with credential-free defaults; auth acquisition remains an explicit synthetic failure.
+- Report absent build output and missing entrypoints before SDK alias blockers in cold-import readiness, preserving build-required totals and all remediation evidence.
+- Recognize board widget content kinds, memory prompt preparation, transcript source providers, worker providers, and MCP server connection resolvers as metadata-only synthetic probes without invoking runtime callbacks.
+
+## 0.3.24 - 2026-08-31
+
+### Fixed
+
+- Recognize compiled CommonJS plugin factory calls when checking expected channel registrations, preserving source references and excluding factory values passed to wrappers.
+- Classify widget presenters as metadata-only synthetic probes without invoking presentation callbacks.
+
 ## 0.3.23 - 2026-08-30
 
 ### Fixed

package/README.md

@@ -208,6 +208,8 @@ plugin-inspector --help
 
 ## Runtime Capture
 
+Static inspection recognizes direct plugin factory calls and compiled CommonJS
+calls such as `(0, sdk.defineBundledChannelEntry)(...)` without importing them.
 Runtime capture imports plugin entrypoints in an isolated subprocess and records
 what `register(api)` does. Use it when static inspection cannot prove the actual
 registrations made at runtime.
@@ -230,9 +232,41 @@ That keeps compatibility CI offline and credential-free. It does not call live
 services, launch OpenClaw, run provider SDKs, or emulate service lifecycle side
 effects.
 
+CommonJS SDK mocking, including compiled `.cjs` entrypoints and lazy `require()`
+calls in synthetic handlers, requires Node.js 22.15 or newer with
+`module.registerHooks()`. On older Node versions, upgrade Node.js or use an
+ESM/TypeScript entrypoint. This capability requirement does not change the
+package's Node.js `>=22` engine range or gate existing ESM/TypeScript capture.
+Static inspection also discovers literal CommonJS SDK `require()` references.
+
+The default capture `api.runtime.modelAuth` passes synthetic provider IDs through
+unchanged, returns fresh empty auth stores and profile lists, and reports no
+configured API keys. Auth acquisition rejects with a mock-auth-unavailable error;
+it never looks up host credentials. This supports registration and no-auth
+callbacks, not provider alias validation or authenticated execution. An explicitly
+supplied runtime is preserved unchanged, including an empty runtime.
+
+Synthetic probes classify widget presenters as metadata-only. They record the
+registration without calling its match, availability, or presentation callbacks,
+including when channel, provider, or lifecycle execution is enabled.
+
 Use `--real-sdk` only when the plugin workspace already has real SDK
 dependencies installed and you intentionally want that path.
 
+Real-SDK CLI capture runs in an owned child, including runtime capture enabled
+by flags or plugin config. The parent bounds imports and registration, then
+cleans up retained plugin timers after the child flushes its complete result.
+It uses installed SDK dependencies without loading the mock SDK.
+
+The real-SDK programmatic API stays in-process to preserve supplied runtime
+objects and retained handler identity. Its 30-second default deadline reports
+`capture-timeout`, stops later inspector-owned phases, and aborts supported
+setup reads. Caller `signal` cancellation also stops later phases. Neither
+mechanism can preempt a synchronous JavaScript loop, unload an import, stop
+arbitrary plugin side effects, or clear plugin-owned timers in the caller's
+process. Only owned-child capture provides that process-lifetime boundary.
+Override the API budget with `timeoutMs` or `PLUGIN_INSPECTOR_CAPTURE_TIMEOUT_MS`.
+
 Runtime capture writes:
 
 - `reports/plugin-inspector-runtime-capture.json`
@@ -244,6 +278,101 @@ Capture one entrypoint directly:
 plugin-inspector capture ./dist/index.js --mock-sdk --allow-execute
 ```
 
+CLI capture, mock-SDK API capture, and import-loop/runtime profiles give each
+child a 30-second budget. Capture reports `capture-timeout`; timed-out profile samples
+always have a nonzero `exitCode`, even if a SIGTERM handler exits zero.
+Pass an `AbortSignal` as `signal` to cancel owned-child work. Cancellation is
+never a successful capture or profile sample.
+
+On POSIX, each child owns a separate process group. Completion waits for
+stdout/stderr to close and cleans descendants, including after a successful
+leader exit. Shutdown sends SIGTERM, then SIGKILL after a 1-second grace
+period. A further 1-second close deadline fails the operation if pipes remain
+open. Descendants that deliberately leave the group are not contained;
+this is lifecycle supervision, not a sandbox. Windows retains direct-child
+termination and the bounded close deadline, not POSIX group cleanup.
+
+The API options `timeoutMs`, `killGraceMs`, and `maxOutputBytes` take precedence
+over `PLUGIN_INSPECTOR_CAPTURE_TIMEOUT_MS`, `PLUGIN_INSPECTOR_CAPTURE_KILL_GRACE_MS`,
+and `PLUGIN_INSPECTOR_CAPTURE_MAX_OUTPUT_BYTES` for owned-child capture. Profiles use
+the corresponding `PLUGIN_INSPECTOR_PROFILE_*` variables. Values must be finite
+positive numbers (zero does not disable limits); invalid values fall through
+to the environment, then defaults. Durations/byte limits cannot exceed
+2,147,483,647; grace cannot exceed 30,000 ms.
+
+Each profiled stdout/stderr stream retains at most 1 MiB by default while
+continuing to drain output. Owned-child capture retains at most 10 MiB per pipe and
+fails if its JSON response is truncated; intercepted plugin stdout/stderr
+inside that response retains at most 1 MiB each. The optional `ps` sampler
+also has bounded output, execution, and cleanup.
+
+Default import-loop profiles launch the mock capture runner directly under one
+profile budget, for both baseline and plugin samples. Their JSON artifacts
+retain capture's 10 MiB default limit (`PLUGIN_INSPECTOR_CAPTURE_MAX_OUTPUT_BYTES`,
+or an explicit `maxOutputBytes` override), separately from the profile's
+1 MiB stdout/stderr limits. Artifacts are accepted only after a successful
+current capture. RSS and CPU now measure the actual runner, and wall time no
+longer includes intermediate CLI startup. Historical measurements from the
+CLI-wrapper route are not directly comparable. Custom `captureCommand` and
+`captureScript` launch contracts are unchanged; custom detached groups are
+outside the owned process group.
+
+These limits apply to owned child processes only. The public in-process
+`captureEntrypoint` path preserves retained handler identity and does not
+claim to cancel synchronous plugin code or retained callbacks.
+
+Synthetic probe APIs give each invoked callback a 30-second default budget.
+Set `timeoutMs` or `PLUGIN_INSPECTOR_PROBE_TIMEOUT_MS`; the same finite positive
+API-then-environment validation applies, with no zero or infinite opt-out.
+A timed-out callback becomes a failed row and remaining dependent probes are
+blocked. Ordinary handler failures remain failed rows without stopping
+independent probes. Caller `signal` cancellation rejects the API call.
+Timeout and cancellation abort supported handler signal arguments and observe
+late promise settlement, but cannot preempt synchronous JavaScript or arbitrary
+plugin side effects. Programmatic probes stay in-process and preserve caller
+runtime objects and retained callback identity.
+
+Gateway method probes invoke each registered handler once, including positional
+`(method, handler, options)` registrations; captured `handler`/`run`/`execute`
+aliases do not create extra calls. The handler receives synthetic Gateway
+options and a void `respond(ok, payload, error, meta)` callback. Existing
+`registrationProbeInputs` overrides remain available.
+
+The first emitted response is authoritative, even when malformed. Probes check
+its JSON-serialized response/error shape: `ok: true` passes, `ok: false` fails,
+and later responses cannot overwrite the outcome. Logging `meta` is not a wire
+field. Without an explicit response, a non-`undefined` return is adapted into a
+successful payload, including `false`, `null`, and `{ ok: false }`, matching the
+OpenClaw plugin registrar. A void handler can respond later within the existing
+probe deadline; no response or return before that deadline fails. Handler throws,
+rejections, and timeouts still fail under the ordinary probe rules.
+
+This observes the initial RPC response plus ordinary handler settlement within
+the existing deadline. It does not prove asynchronous operation completion,
+transport delivery, or authorization. An accepted-only success is valid once the
+handler settles; probes do not implicitly request `expectFinal` or reject legal
+multi-frame methods. No Gateway connection or live host call is made.
+
+`synthetic-probes-cli.js` runs capture and retained callbacks together in one
+owned child. Its whole-child budget also defaults to 30 seconds, including
+imports and registration, with `PLUGIN_INSPECTOR_PROBE_TIMEOUT_MS`,
+`PLUGIN_INSPECTOR_PROBE_KILL_GRACE_MS`, and
+`PLUGIN_INSPECTOR_PROBE_MAX_OUTPUT_BYTES` overrides. Shutdown uses the same
+bounded grace and process-group cleanup as capture. The default report and
+per-pipe limit is 10 MiB, matching capture; intercepted plugin stdout and stderr are each capped
+at 1 MiB and kept separate from the report protocol.
+
+Completed synthetic reports are still written even when they contain failed
+probe rows; the CLI exits successfully after delivering them, and CI policy
+evaluates those rows. Child timeout, cancellation, truncated output, or an
+oversized or malformed report instead exits unsuccessfully without writing a
+new output artifact. The CLI validates the report shape, row identities and
+statuses, and summary counts before publication; valid empty and blocked
+reports are preserved. This is protocol validation, not authenticated
+completion or a security sandbox: same-process plugin code can still fabricate
+a valid report. Healthy retained intervals cannot keep the child alive after
+its complete report is flushed.
+
 ## CI
 
 `plugin-inspector ci` writes the normal compatibility report plus CI-native

package/package.json

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

package/src/api.js

@@ -226,6 +226,13 @@ export async function runPluginCheck(options = {}) {
       mockSdk,
       report,
       rootDir: config.rootDir,
+      isolateCapture: options.isolateCapture,
+      timeoutMs: options.timeoutMs,
+      killGraceMs: options.killGraceMs,
+      maxOutputBytes: options.maxOutputBytes,
+      signal: options.signal,
+      env: options.env,
+      apiOptions: options.apiOptions,
     });
     const runtimeCapturePaths = await writeRuntimeCaptureReport(runtimeCapture, {
       jsonPath: path.resolve(config.rootDir, outDir, "plugin-inspector-runtime-capture.json"),

package/src/artifacts.js

@@ -1,6 +1,27 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { mkdir, open, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+export async function readBoundedJsonArtifact(filePath, maxBytes) {
+  const file = await open(filePath, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile()) throw new Error("expected a regular result file");
+    if (stat.size > maxBytes) throw new Error("result exceeded its byte limit");
+    const chunks = [];
+    let bytes = 0;
+    // end is inclusive: read at most limit + 1 even if the file grew after stat.
+    for await (const chunk of file.createReadStream({ end: maxBytes, autoClose: false })) {
+      chunks.push(chunk);
+      bytes += chunk.length;
+    }
+    if (bytes > maxBytes) throw new Error("result exceeded its byte limit");
+    return JSON.parse(Buffer.concat(chunks, bytes).toString("utf8"));
+  } finally {
+    await file.close();
+  }
+}
+
 export async function writeArtifacts(artifacts, options = {}) {
   if (!Array.isArray(artifacts) || artifacts.length === 0) {
     throw new TypeError("writeArtifacts requires at least one artifact");

package/src/capture-api.js

@@ -203,6 +203,17 @@ function createRuntimeContext(options) {
     logger: options.logger ?? console,
     now: () => new Date(0),
     tts: runtime.tts ?? {},
+    // Synthetic provider IDs pass through; capture never resolves host aliases or credentials.
+    modelAuth: {
+      resolveProviderIdForAuth: (provider) => provider,
+      ensureAuthProfileStore: () => ({ version: 1, profiles: {} }),
+      resolveAuthProfileOrder: () => [],
+      listProfilesForProvider: () => [],
+      isProviderApiKeyConfigured: () => false,
+      getApiKeyForModel: rejectCaptureModelAuth,
+      getRuntimeAuthForModel: rejectCaptureModelAuth,
+      resolveApiKeyForProvider: rejectCaptureModelAuth,
+    },
     state: {
       resolveStateDir: () => options.stateDir ?? process.cwd(),
       openBlobStore(storeOptions) {
@@ -228,6 +239,10 @@ function createRuntimeContext(options) {
   };
 }
 
+async function rejectCaptureModelAuth() {
+  throw new Error("Model auth is unavailable in capture mocks");
+}
+
 function createBlobStoreContext(options) {
   const values = new Map();
   const entryInfo = (key, entry) => ({

package/src/capture-cli.js

@@ -23,7 +23,7 @@ async function run(commandArgs) {
     throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
   }
 
-  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot });
+  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot, isolateCapture: true });
   const json = `${JSON.stringify(result, null, 2)}\n`;
   if (outputPath) {
     await writeArtifacts([{ path: outputPath, content: json }]);

package/src/capture-config.js

@@ -6,7 +6,7 @@ export async function captureApiOptionsForPlugin(apiOptions = {}, options = {})
     return apiOptions;
   }
 
-  const pluginConfig = await readSamplePluginConfig(options.pluginRoot);
+  const pluginConfig = await readSamplePluginConfig(options.pluginRoot, options.signal);
   if (pluginConfig === undefined) {
     return apiOptions;
   }
@@ -16,15 +16,16 @@ export async function captureApiOptionsForPlugin(apiOptions = {}, options = {})
   };
 }
 
-async function readSamplePluginConfig(pluginRoot) {
-  const manifestPath = await findNearestManifestPath(pluginRoot);
+async function readSamplePluginConfig(pluginRoot, signal) {
+  const manifestPath = await findNearestManifestPath(pluginRoot, signal);
   if (!manifestPath) {
     return undefined;
   }
   let manifest;
   try {
-    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    manifest = JSON.parse(await readFile(manifestPath, { encoding: "utf8", signal }));
   } catch {
+    signal?.throwIfAborted();
     return undefined;
   }
 
@@ -32,14 +33,16 @@ async function readSamplePluginConfig(pluginRoot) {
   return isPlainObject(sample) && Object.keys(sample).length > 0 ? sample : undefined;
 }
 
-async function findNearestManifestPath(pluginRoot) {
+async function findNearestManifestPath(pluginRoot, signal) {
   let current = path.resolve(pluginRoot);
   while (true) {
     const manifestPath = path.join(current, "openclaw.plugin.json");
     try {
-      await readFile(manifestPath, "utf8");
+      await readFile(manifestPath, { encoding: "utf8", signal });
       return manifestPath;
-    } catch {}
+    } catch {
+      signal?.throwIfAborted();
+    }
 
     const parent = path.dirname(current);
     if (parent === current) {

package/src/cli.js

@@ -115,6 +115,7 @@ async function runCheck(commandArgs, options = {}) {
   const ciOutputs = readCiOutputFlags(commandArgs);
   const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, paths } = await runPluginCheck({
+    isolateCapture: true,
     allowExecution,
     authorFacing,
     capture,
@@ -279,6 +280,7 @@ async function runCiCompatibilityReport({
   }
 
   const { report } = await runPluginCheck({
+    isolateCapture: true,
     allowExecution,
     authorFacing,
     capture,
@@ -307,7 +309,7 @@ async function runCapture(commandArgs) {
     throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 or --allow-execute in an isolated workspace");
   }
 
-  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot });
+  const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot, isolateCapture: true });
   const json = `${JSON.stringify(result, null, 2)}\n`;
   if (outputPath) {
     await writeArtifacts([{ path: outputPath, content: json }]);

package/src/cold-import-readiness.js

@@ -226,15 +226,15 @@ function readinessStatus(blockers) {
   if (blockers.length === 0) {
     return "ready";
   }
-  if (blockers.some((blocker) => blocker.code === "sdk-alias-required")) {
-    return "sdk-alias-required";
-  }
   if (blockers.some((blocker) => blocker.code === "build-required")) {
     return "build-required";
   }
   if (blockers.some((blocker) => blocker.code === "missing-entrypoint")) {
     return "missing";
   }
+  if (blockers.some((blocker) => blocker.code === "sdk-alias-required")) {
+    return "sdk-alias-required";
+  }
   if (blockers.some((blocker) => blocker.code === "ts-loader-required")) {
     return "ts-loader-required";
   }

package/src/import-loop-profile.js

@@ -1,12 +1,12 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { readBoundedJsonArtifact, renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
 import { resolveFromRoot } from "./path-utils.js";
-import { runProfiledProcess } from "./process-profile.js";
+import { resolveProcessLimits, runProfiledProcess } from "./process-profile.js";
 import { assertRunCount, percentile } from "./stats.js";
 
-const defaultCliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+const defaultRunnerPath = fileURLToPath(new URL("./mock-sdk-capture-runner.js", import.meta.url));
 
 export const defaultImportLoopProfileOptions = {
   entrypoint: "test/fixtures/lazy-import-plugin.mjs",
@@ -255,18 +255,49 @@ async function runCaptureSample(options) {
   const outputPath = path.join(outputDir, `${options.sampleName ?? "capture"}-${options.index}.json`);
   await mkdir(path.dirname(outputPath), { recursive: true });
 
-  const command = buildCaptureCommand({ ...options, outputPath });
+  const defaultCapture = typeof options.captureCommand !== "function" && !options.captureScript;
+  const maxOutputBytes = resolveProcessLimits({
+    ...options,
+    env: { ...process.env, ...options.env, ...options.captureEnv },
+  }, "CAPTURE").maxOutputBytes;
+  // Only the built-in route owns these sample files. An early process.exit(0)
+  // must not turn a previous capture into this run's successful result.
+  if (defaultCapture) await rm(outputPath, { force: true });
+  const command = buildCaptureCommand({ ...options, outputPath, maxOutputBytes });
   const profile = await runProfiledProcess({
     command: command.command,
     args: command.args,
     cwd: command.cwd ?? options.rootDir,
-    env: { ...process.env, ...command.env },
+    env: { ...process.env, ...options.env, ...command.env },
+    timeoutMs: options.timeoutMs,
+    maxOutputBytes: options.maxOutputBytes,
+    killGraceMs: options.killGraceMs,
+    signal: options.signal,
   });
-  const output = profile.exitCode === 0 ? await readCaptureOutput(outputPath) : null;
+  let output = null;
+  if (profile.exitCode === 0 && !profile.timedOut && !profile.cancelled) {
+    if (defaultCapture) {
+      try {
+        output = await readCaptureOutput(outputPath, maxOutputBytes);
+      } catch (error) {
+        profile.exitCode = 1;
+        profile.stderrPreview = `Invalid capture artifact: ${error.message}`;
+      }
+    } else {
+      output = await readCaptureOutput(outputPath);
+    }
+  }
+  if (options.signal?.aborted) {
+    profile.exitCode = 1;
+    profile.cancelled = true;
+    output = null;
+  }
 
   return {
     index: options.index,
     exitCode: profile.exitCode,
+    timedOut: profile.timedOut === true,
+    cancelled: profile.cancelled === true,
     status: output?.status ?? "failed",
     capturedCount: output?.captured?.length ?? 0,
     openClawLifecycle: output?.openClawLifecycle ?? null,
@@ -407,15 +438,29 @@ function buildCaptureCommand(options) {
   }
   return {
     command: process.execPath,
-    args: [defaultCliPath, "capture", options.entrypoint, "--output", options.outputPath],
+    args: [
+      "--no-warnings",
+      "--preserve-symlinks",
+      defaultRunnerPath,
+      JSON.stringify({
+        entrypoint: options.entrypoint,
+        cwd: options.rootDir,
+        outputPath: options.outputPath,
+        maxOutputBytes: options.maxOutputBytes,
+      }),
+    ],
     cwd: options.rootDir,
     env: { PLUGIN_INSPECTOR_EXECUTE_ISOLATED: "1", ...options.captureEnv },
   };
 }
 
-async function readCaptureOutput(outputPath) {
-  const { readFile } = await import("node:fs/promises");
-  return JSON.parse(await readFile(outputPath, "utf8"));
+async function readCaptureOutput(outputPath, maxOutputBytes) {
+  if (maxOutputBytes === undefined) return JSON.parse(await readFile(outputPath, "utf8"));
+  const result = await readBoundedJsonArtifact(outputPath, maxOutputBytes);
+  if (!result || typeof result.status !== "string" || !Array.isArray(result.captured)) {
+    throw new Error("expected a capture status and captured contracts");
+  }
+  return result;
 }
 
 function markdownTable(rows, headers) {