@openclaw/plugin-inspector 0.3.23 → 0.3.25

package/src/synthetic-entrypoint.js

@@ -1,27 +1,22 @@
 import { rmSync } from "node:fs";
 import { mkdtemp } from "node:fs/promises";
-import { register } from "node:module";
 import os from "node:os";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { captureEntrypoint } from "./inspector.js";
-import { createMockSdkPackage } from "./sdk-mock.js";
+import { createMockSdkPackage, installMockSdkLoader } from "./sdk-mock.js";
 import { runCapturedSyntheticProbes } from "./synthetic-probes.js";
 
 export async function runEntrypointSyntheticProbes(entrypoint, options = {}) {
-  const capture = await captureEntrypointForSyntheticProbes(entrypoint, {
+  const captureOptions = {
     ...options,
     apiOptions: {
       ...(options.apiOptions ?? {}),
       retainHandlers: true,
     },
-  });
-  return runCapturedSyntheticProbes(capture, options);
-}
-
-async function captureEntrypointForSyntheticProbes(entrypoint, options) {
+  };
   if (options.mockSdk !== true) {
-    return captureEntrypoint(entrypoint, options);
+    const capture = await captureEntrypoint(entrypoint, captureOptions);
+    return runCapturedSyntheticProbes(capture, options);
   }
 
   const cwd = options.cwd ?? process.cwd();
@@ -29,15 +24,20 @@ async function captureEntrypointForSyntheticProbes(entrypoint, options) {
   const pluginRoot = path.resolve(cwd, options.pluginRoot ?? path.dirname(resolvedEntrypoint));
   const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-synthetic-mock-sdk-"));
   cleanupTempDirOnExit(workspace);
-  const { loaderPath } = await createMockSdkPackage(workspace, { pluginRoot });
-  register(pathToFileURL(loaderPath));
-
-  return captureEntrypoint(entrypoint, {
-    ...options,
-    cwd,
-    mockSdk: false,
-    pluginRoot,
-  });
+  const mockPackage = await createMockSdkPackage(workspace, { pluginRoot });
+  const stopLoader = await installMockSdkLoader(mockPackage);
+  try {
+    const capture = await captureEntrypoint(entrypoint, {
+      ...captureOptions,
+      cwd,
+      mockSdk: false,
+      pluginRoot,
+    });
+    // Retained handlers can require SDK modules lazily during invocation.
+    return await runCapturedSyntheticProbes(capture, options);
+  } finally {
+    stopLoader();
+  }
 }
 
 function cleanupTempDirOnExit(dir) {

package/src/synthetic-probes-cli.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
-import { runEntrypointSyntheticProbes, writeArtifacts } from "./advanced.js";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readBoundedJsonArtifact, writeArtifacts } from "./artifacts.js";
+import { resolveProcessLimits, startOwnedProcess } from "./process-profile.js";
 
 const args = process.argv.slice(2);
 
@@ -26,7 +31,7 @@ async function run(commandArgs) {
     throw new Error("synthetic probes import plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
   }
 
-  const results = await runEntrypointSyntheticProbes(entrypoint, {
+  const results = await runInChild(entrypoint, {
     mockSdk,
     pluginRoot,
     apiOptions: { retainHandlers: true },
@@ -43,6 +48,78 @@ async function run(commandArgs) {
   }
 }
 
+async function runInChild(entrypoint, options) {
+  const limits = resolveProcessLimits({}, "PROBE");
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-synthetic-cli-"));
+  const outputPath = path.join(workspace, "result.json");
+  const controller = new AbortController();
+  const cancel = () => controller.abort(new Error("Synthetic probes cancelled"));
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  try {
+    const runnerPath = fileURLToPath(new URL("./mock-sdk-capture-runner.js", import.meta.url));
+    const { result } = startOwnedProcess({
+      command: process.execPath,
+      args: [
+        "--no-warnings",
+        ...(options.mockSdk ? ["--preserve-symlinks"] : []),
+        runnerPath,
+        JSON.stringify({
+          ...options, ...limits, entrypoint, outputPath,
+          cwd: process.cwd(), syntheticProbes: true,
+        }),
+      ],
+      ...limits,
+      signal: controller.signal,
+    }, "PROBE");
+    const outcome = await result;
+    if (outcome.exitCode !== 0 || outcome.outputTruncated) {
+      const message = outcome.cancelled ? "Synthetic probes cancelled"
+        : outcome.timedOut ? `Synthetic probes timed out after ${limits.timeoutMs}ms`
+        : outcome.outputTruncated ? "Synthetic probe child output exceeded its byte limit"
+        : outcome.stderr.trim() || outcome.error?.message || "Synthetic probe child failed";
+      throw new Error(message);
+    }
+    controller.signal.throwIfAborted();
+    // The report is separate from plugin stdout, including direct fd writes.
+    // Only accept a fresh complete artifact after successful child cleanup.
+    const results = await readBoundedJsonArtifact(outputPath, limits.maxOutputBytes);
+    validateSyntheticReport(results);
+    controller.signal.throwIfAborted();
+    return results;
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", cancel);
+    await rm(workspace, { recursive: true, force: true });
+  }
+}
+
+function validateSyntheticReport(report) {
+  const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+  if (!isObject(report) || typeof report.entrypoint !== "string" ||
+      !["captured", "no-register-export"].includes(report.status) ||
+      !isObject(report.summary) || !Array.isArray(report.results)) {
+    throw new Error("Invalid synthetic probe report: expected entrypoint, status, summary, and results");
+  }
+  const counts = { probeCount: report.results.length, passCount: 0, failCount: 0, blockedCount: 0 };
+  for (const row of report.results) {
+    if (!isObject(row) || !Number.isSafeInteger(row.captureIndex) || row.captureIndex < 0 ||
+        !["kind", "seam", "label"].every((key) => typeof row[key] === "string") ||
+        !["pass", "fail", "blocked"].includes(row.status) ||
+        (row.status === "fail" && typeof row.error !== "string") ||
+        (row.status === "blocked" && typeof row.reason !== "string")) {
+      throw new Error("Invalid synthetic probe report: malformed result row");
+    }
+    counts[`${row.status}Count`] += 1;
+  }
+  for (const [key, expected] of Object.entries(counts)) {
+    if (!Number.isSafeInteger(report.summary[key]) || report.summary[key] < 0 ||
+        report.summary[key] !== expected) {
+      throw new Error(`Invalid synthetic probe report: invalid or inconsistent ${key}`);
+    }
+  }
+}
+
 function readFlag(commandArgs, name) {
   const index = commandArgs.indexOf(name);
   if (index === -1) {

package/src/synthetic-probes.js

@@ -1,4 +1,5 @@
 import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { resolveProcessLimits } from "./process-profile.js";
 
 export const syntheticRegistrationExecutionProfiles = {
   createChatChannelPlugin: {
@@ -46,6 +47,11 @@ export const syntheticRegistrationExecutionProfiles = {
     callableProperties: [],
     reason: "auto-enable probes are captured as registration metadata before runtime activation checks",
   },
+  registerBoardWidgetContentKind: {
+    mode: "metadata-only",
+    callableProperties: [],
+    reason: "board widget content kinds are captured as registration metadata before source validation or document composition",
+  },
   registerCli: {
     mode: "direct",
     callableProperties: ["handler", "run", "execute"],
@@ -126,6 +132,16 @@ export const syntheticRegistrationExecutionProfiles = {
     callableProperties: [],
     reason: "hosted media resolvers are captured as registration metadata before media URL resolution",
   },
+  registerMcpServerConnectionResolver: {
+    mode: "metadata-only",
+    callableProperties: [],
+    reason: "MCP server connection resolvers are captured as registration metadata before requester-bound transport resolution",
+  },
+  registerMemoryPromptPreparation: {
+    mode: "metadata-only",
+    callableProperties: [],
+    reason: "memory prompt preparation callbacks are captured as registration metadata before prompt-runtime execution",
+  },
   registerMemoryPromptSection: {
     mode: "metadata-only",
     callableProperties: [],
@@ -275,6 +291,11 @@ export const syntheticRegistrationExecutionProfiles = {
     callableProperties: [],
     reason: "text transforms are captured as registration metadata before content mutation execution",
   },
+  registerTranscriptSourceProvider: {
+    mode: "metadata-only",
+    callableProperties: [],
+    reason: "transcript source providers are captured as registration metadata before live capture or transcript import",
+  },
   registerVideoGenerationProvider: {
     mode: "metadata-only",
     callableProperties: [],
@@ -295,6 +316,16 @@ export const syntheticRegistrationExecutionProfiles = {
     callableProperties: [],
     reason: "web search providers are captured as registration metadata before provider runtime execution",
   },
+  registerWidgetPresenter: {
+    mode: "metadata-only",
+    callableProperties: [],
+    reason: "widget presenters are captured as registration metadata before presentation runtime execution",
+  },
+  registerWorkerProvider: {
+    mode: "metadata-only",
+    callableProperties: [],
+    reason: "worker providers are captured as registration metadata before cloud-worker lifecycle execution",
+  },
 };
 
 export const defaultSyntheticHookEvents = {
@@ -478,6 +509,7 @@ export const defaultSyntheticRegistrationProbeInputs = {
   registerGatewayMethod: {
     execute: gatewayProbeArgs,
     handler: gatewayProbeArgs,
+    invoke: gatewayProbeArgs,
     run: gatewayProbeArgs,
   },
   registerHttpRoute: {
@@ -592,8 +624,27 @@ export async function writeSyntheticProbePlan(plan, options = {}) {
 }
 
 export async function runCapturedSyntheticProbes(capture, options = {}) {
+  options.signal?.throwIfAborted();
   const hookEvents = options.hookEvents ?? defaultSyntheticHookEvents;
   const hookContexts = options.hookContexts ?? defaultSyntheticHookContexts;
+  const { timeoutMs } = resolveProcessLimits(options, "PROBE");
+  const controller = new AbortController();
+  const onCancel = () => controller.abort(new Error("Synthetic probes cancelled"));
+  options.signal?.addEventListener("abort", onCancel, { once: true });
+  if (options.signal?.aborted) onCancel();
+  try {
+    const result = await runCapturedProbes(capture, {
+      ...options, hookEvents, hookContexts, timeoutMs, controller, signal: controller.signal,
+    });
+    if (options.signal?.aborted) throw controller.signal.reason;
+    return result;
+  } finally {
+    options.signal?.removeEventListener("abort", onCancel);
+  }
+}
+
+async function runCapturedProbes(capture, options) {
+  const { hookEvents, hookContexts, timeoutMs, controller, signal } = options;
   const captured = capture.captured ?? [];
   const retained = new Map((capture.retained ?? []).map((item) => [item.captureIndex, item]));
   const resultsByCaptureIndex = new Map();
@@ -606,6 +657,10 @@ export async function runCapturedSyntheticProbes(capture, options = {}) {
     );
 
   for (const { entry, captureIndex } of executionEntries) {
+    if (signal.aborted) {
+      resultsByCaptureIndex.set(captureIndex, [blockedResult(entry, captureIndex, signal.reason.message)]);
+      continue;
+    }
     const retainedEntry = retained.get(captureIndex);
     if (!retainedEntry) {
       resultsByCaptureIndex.set(captureIndex, [blockedResult(entry, captureIndex, "handler retention was not enabled")]);
@@ -613,7 +668,7 @@ export async function runCapturedSyntheticProbes(capture, options = {}) {
     }
     if (entry.kind === "hook") {
       resultsByCaptureIndex.set(captureIndex, [
-        await runHookProbe(entry, retainedEntry, captureIndex, { hookEvents, hookContexts }),
+        await runHookProbe(entry, retainedEntry, captureIndex, { hookEvents, hookContexts, timeoutMs, controller }),
       ]);
       continue;
     }
@@ -714,7 +769,7 @@ function probeBlocker({ hasSyntheticArguments, execution }) {
   return null;
 }
 
-async function runHookProbe(entry, retainedEntry, captureIndex, { hookEvents, hookContexts }) {
+async function runHookProbe(entry, retainedEntry, captureIndex, { hookEvents, hookContexts, timeoutMs, controller }) {
   if (typeof retainedEntry.handler !== "function") {
     return blockedResult(entry, captureIndex, "captured hook has no callable handler");
   }
@@ -723,6 +778,8 @@ async function runHookProbe(entry, retainedEntry, captureIndex, { hookEvents, ho
     kind: "hook",
     seam: entry.name,
     label: entry.name,
+    timeoutMs,
+    controller,
     invoke: () =>
       retainedEntry.handler(
         hookEvents[entry.name] ?? { hook: entry.name },
@@ -741,7 +798,9 @@ async function runRegistrationProbes(entry, retainedEntry, captureIndex, options
   }
 
   const descriptor =
-    retainedEntry.arguments?.find((value) => value && typeof value === "object") ?? retainedEntry.returnValue;
+    entry.name === "registerGatewayMethod" && typeof retainedEntry.arguments?.[0] === "string"
+      ? retainedEntry.returnValue
+      : retainedEntry.arguments?.find((value) => value && typeof value === "object") ?? retainedEntry.returnValue;
   if (!descriptor || typeof descriptor !== "object") {
     return [blockedResult(entry, captureIndex, "captured registration has no object descriptor")];
   }
@@ -754,17 +813,29 @@ async function runRegistrationProbes(entry, retainedEntry, captureIndex, options
     return [blockedResult(entry, captureIndex, "captured registration has no supported callable probe")];
   }
 
-  return Promise.all(
-    invocations.map((invocation) =>
-      runProbe({
+  // The profile owns lifecycle order; finish each callback before starting the next.
+  const results = [];
+  for (const invocation of invocations) {
+    if (options.signal.aborted) {
+      results.push({
+        ...blockedResult(entry, captureIndex, options.signal.reason.message),
+        label: invocation.label,
+      });
+      continue;
+    }
+    results.push(
+      await runProbe({
         captureIndex,
         kind: "registration",
         seam: entry.name,
         label: invocation.label,
+        timeoutMs: options.timeoutMs,
+        controller: options.controller,
         invoke: invocation.invoke,
       }),
-    ),
-  );
+    );
+  }
+  return results;
 }
 
 function registrationInvocations(registrar, descriptor, returnValue, profile, options) {
@@ -781,20 +852,100 @@ function registrationInvocations(registrar, descriptor, returnValue, profile, op
     if (typeof callable === "function") {
       invocations.push({
         label: `${registrar}.${property}`,
-        invoke: () => invokeRegistrationCallable(callable, registrar, property, options),
+        invoke: () => registrar === "registerGatewayMethod"
+          ? invokeGatewayCallable(callable, property, descriptor, options)
+          : invokeRegistrationCallable(callable, registrar, property, options),
       });
+      // Gateway aliases describe one method, not independent lifecycle callbacks.
+      if (registrar === "registerGatewayMethod") break;
     }
   }
   return invocations;
 }
 
-function invokeRegistrationCallable(callable, registrar, property, options) {
-  const event = syntheticRegistrationEvent(registrar, property, options);
+function invokeRegistrationCallable(
+  callable, registrar, property, options,
+  event = syntheticRegistrationEvent(registrar, property, options),
+) {
   const inputFactory = options.registrationProbeInputs?.[registrar]?.[property] ?? defaultSyntheticRegistrationProbeInputs[registrar]?.[property];
   const args = inputFactory ? inputFactory(event, options) : [event];
   return callable(...args);
 }
 
+async function invokeGatewayCallable(callable, property, descriptor, options) {
+  let responded = false;
+  let closed = false;
+  let resolveResponse;
+  const response = new Promise((resolve) => { resolveResponse = resolve; });
+  const onAbort = () => {
+    closed = true;
+    resolveResponse({ error: options.signal.reason });
+  };
+  options.signal.addEventListener("abort", onAbort, { once: true });
+  const respond = (ok, payload, error) => {
+    if (closed || responded) return;
+    // Snapshot the first emission, including invalid frames. Later responses
+    // cannot recover it; logging metadata is not part of the wire envelope.
+    responded = true;
+    try {
+      resolveResponse({ frame: gatewayResponseFrame(ok, payload, error) });
+    } catch (error) {
+      resolveResponse({ error });
+    }
+  };
+  try {
+    options.signal.throwIfAborted();
+    const event = {
+      ...syntheticRegistrationEvent("registerGatewayMethod", property, options),
+      method: descriptor.method ?? descriptor.name,
+      respond,
+    };
+    const result = await invokeRegistrationCallable(callable, "registerGatewayMethod", property, options, event);
+    // OpenClaw's plugin registrar adapts returns only without an explicit reply.
+    if (!responded && result !== undefined) respond(true, result);
+    // A void handler may respond later. The existing probe deadline bounds this
+    // observation as well as handler settlement; it owns timeout/cancellation.
+    const outcome = await response;
+    if (outcome.error) throw outcome.error;
+    if (!outcome.frame.ok) {
+      throw new Error(`Gateway response error: ${outcome.frame.error?.message ?? "request failed"}`);
+    }
+    return outcome.frame;
+  } finally {
+    closed = true;
+    options.signal.removeEventListener("abort", onAbort);
+  }
+}
+
+function gatewayResponseFrame(ok, payload, error) {
+  let frame;
+  try {
+    frame = JSON.parse(JSON.stringify({ type: "res", id: "fixture-request", ok, payload, error }));
+  } catch {
+    throw new Error("Gateway response is not JSON serializable");
+  }
+  // ResponseFrameSchema / ErrorShapeSchema in OpenClaw v2026.9.3. Payload and
+  // error are optional independently of ok; error codes are nonempty strings.
+  const responseError = frame.error;
+  if (
+    typeof frame.ok !== "boolean" ||
+    (responseError !== undefined && (
+      !responseError ||
+      typeof responseError !== "object" ||
+      Array.isArray(responseError) ||
+      typeof responseError.code !== "string" || responseError.code.length === 0 ||
+      typeof responseError.message !== "string" || responseError.message.length === 0 ||
+      (responseError.retryable !== undefined && typeof responseError.retryable !== "boolean") ||
+      (responseError.retryAfterMs !== undefined &&
+        (!Number.isInteger(responseError.retryAfterMs) || responseError.retryAfterMs < 0)) ||
+      Object.keys(responseError).some((key) => !["code", "message", "details", "retryable", "retryAfterMs"].includes(key))
+    ))
+  ) {
+    throw new Error("Gateway response is malformed");
+  }
+  return frame;
+}
+
 function syntheticRegistrationEvent(registrar, property, options) {
   const hookEvents = options.hookEvents ?? defaultSyntheticHookEvents;
   const beforeToolCall = hookEvents.before_tool_call ?? defaultSyntheticHookEvents.before_tool_call;
@@ -817,21 +968,21 @@ function syntheticRegistrationEvent(registrar, property, options) {
   };
 }
 
-function toolRunProbeArgs(event) {
+function toolRunProbeArgs(event, options = {}) {
   return [
     event.params,
     {
       source: event.source,
       toolName: event.toolName,
       toolCallId: event.toolCall.id,
-      signal: new AbortController().signal,
+      signal: options.signal ?? new AbortController().signal,
       logger: console,
     },
   ];
 }
 
-function toolExecuteProbeArgs(event) {
-  return [event.toolCall.id, event.params, new AbortController().signal, () => undefined];
+function toolExecuteProbeArgs(event, options = {}) {
+  return [event.toolCall.id, event.params, options.signal ?? new AbortController().signal, () => undefined];
 }
 
 function httpRouteProbeArgs(event) {
@@ -853,34 +1004,31 @@ function httpRouteProbeArgs(event) {
   ];
 }
 
-function commandProbeArgs(event) {
+function commandProbeArgs(event, options = {}) {
   return [
     event.input,
     {
       source: event.source,
-      signal: new AbortController().signal,
+      signal: options.signal ?? new AbortController().signal,
       logger: console,
     },
   ];
 }
 
-function gatewayProbeArgs(event) {
+function gatewayProbeArgs(event, options = {}) {
   return [
     {
       ...event,
-      params: event.params,
-      body: event.body,
-      headers: event.headers,
-      respond: event.respond,
-    },
-    {
-      source: event.source,
-      logger: console,
+      req: { type: "req", id: "fixture-request", method: event.method ?? "fixture.gateway.method", params: event.params },
+      client: null,
+      isWebchatConnect: () => false,
+      context: { source: event.source, logger: console },
+      signal: options.signal,
     },
   ];
 }
 
-function channelSendProbeArgs(event) {
+function channelSendProbeArgs(event, options = {}) {
   return [
     {
       source: event.source,
@@ -891,12 +1039,12 @@ function channelSendProbeArgs(event) {
       replyToId: "fixture-reply",
       threadId: "fixture-thread",
       logger: console,
-      signal: new AbortController().signal,
+      signal: options.signal ?? new AbortController().signal,
     },
   ];
 }
 
-function channelReceiveProbeArgs(event) {
+function channelReceiveProbeArgs(event, options = {}) {
   return [
     {
       source: event.source,
@@ -916,7 +1064,7 @@ function channelReceiveProbeArgs(event) {
         to: "fixture-channel",
       },
       logger: console,
-      signal: new AbortController().signal,
+      signal: options.signal ?? new AbortController().signal,
     },
   ];
 }
@@ -934,7 +1082,7 @@ function interactiveProbeArgs(event) {
   ];
 }
 
-function lifecycleProbeArgs(event) {
+function lifecycleProbeArgs(event, options = {}) {
   return [
     {
       source: event.source,
@@ -942,7 +1090,7 @@ function lifecycleProbeArgs(event) {
       logger: console,
       runtime: { env: {}, logger: console },
       secrets: { get: async () => null, has: async () => false },
-      signal: new AbortController().signal,
+      signal: options.signal ?? new AbortController().signal,
     },
   ];
 }
@@ -960,9 +1108,9 @@ function speechProbeArgs(event) {
   ];
 }
 
-async function runProbe({ captureIndex, kind, seam, label, invoke }) {
+async function runProbe({ captureIndex, kind, seam, label, invoke, timeoutMs, controller }) {
   try {
-    const output = await invoke();
+    const output = await invokeWithTimeout(invoke, timeoutMs, controller);
     return {
       captureIndex,
       kind,
@@ -983,6 +1131,30 @@ async function runProbe({ captureIndex, kind, seam, label, invoke }) {
   }
 }
 
+function invokeWithTimeout(invoke, timeoutMs, controller) {
+  const { signal } = controller;
+  let rejectAborted;
+  const aborted = new Promise((_, reject) => { rejectAborted = reject; });
+  const onAbort = () => rejectAborted(signal.reason);
+  signal.addEventListener("abort", onAbort, { once: true });
+  const timeoutId = setTimeout(() => {
+    controller.abort(new Error(`Synthetic probe timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+  // Keep observing settlement after abort without starting dependent callbacks.
+  // In-process JavaScript itself is not preempted by this deadline.
+  const result = Promise.resolve().then(() => {
+    signal.throwIfAborted();
+    return invoke();
+  }).then((output) => {
+    signal.throwIfAborted();
+    return output;
+  });
+  return Promise.race([result, aborted]).finally(() => {
+    clearTimeout(timeoutId);
+    signal.removeEventListener("abort", onAbort);
+  });
+}
+
 function blockedResult(entry, captureIndex, reason) {
   return {
     captureIndex,