@openclaw/plugin-inspector 0.3.24 → 0.3.26

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: [],
@@ -300,6 +321,11 @@ export const syntheticRegistrationExecutionProfiles = {
     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 = {
@@ -483,6 +509,7 @@ export const defaultSyntheticRegistrationProbeInputs = {
   registerGatewayMethod: {
     execute: gatewayProbeArgs,
     handler: gatewayProbeArgs,
+    invoke: gatewayProbeArgs,
     run: gatewayProbeArgs,
   },
   registerHttpRoute: {
@@ -597,8 +624,28 @@ 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,
+      gatewayConfig: options.apiOptions?.config ?? {},
+    });
+    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();
@@ -611,6 +658,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")]);
@@ -618,7 +669,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;
     }
@@ -719,7 +770,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");
   }
@@ -728,6 +779,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 },
@@ -746,10 +799,22 @@ 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")];
   }
+  const method = descriptor.method ?? descriptor.name;
+  if (entry.name === "registerGatewayMethod" && Object.hasOwn(options.gatewayMethodPrerequisites ?? {}, method)) {
+    const reason = options.gatewayMethodPrerequisites[method];
+    if (typeof reason !== "string" || reason.trim().length === 0) {
+      throw new TypeError(`Gateway probe prerequisite for ${method} must be a non-empty string`);
+    }
+    // A method needing host state or live credentials cannot be exercised with
+    // the default empty request. Record the missing prerequisite before calling it.
+    return [{ ...blockedResult(entry, captureIndex, reason), method }];
+  }
   if (profile.option && options[profile.option] !== true) {
     return [blockedResult(entry, captureIndex, `captured registration requires ${profile.option}=true`)];
   }
@@ -759,17 +824,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) {
@@ -786,20 +863,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;
@@ -822,21 +979,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) {
@@ -858,34 +1015,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, getRuntimeConfig: () => options.gatewayConfig },
+      signal: options.signal,
     },
   ];
 }
 
-function channelSendProbeArgs(event) {
+function channelSendProbeArgs(event, options = {}) {
   return [
     {
       source: event.source,
@@ -896,12 +1050,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,
@@ -921,7 +1075,7 @@ function channelReceiveProbeArgs(event) {
         to: "fixture-channel",
       },
       logger: console,
-      signal: new AbortController().signal,
+      signal: options.signal ?? new AbortController().signal,
     },
   ];
 }
@@ -939,7 +1093,7 @@ function interactiveProbeArgs(event) {
   ];
 }
 
-function lifecycleProbeArgs(event) {
+function lifecycleProbeArgs(event, options = {}) {
   return [
     {
       source: event.source,
@@ -947,7 +1101,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,
     },
   ];
 }
@@ -965,9 +1119,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,
@@ -988,6 +1142,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,