docs: document plugin runtime load context

src/plugins/runtime/channel-runtime-contexts.ts

@@ -69,6 +69,7 @@ function doesRuntimeContextWatcherMatch(params: {
   return true;
 }
 
+/** Creates the in-memory channel runtime context registry used by plugin runtime surfaces. */
 export function createChannelRuntimeContextRegistry(): ChannelRuntimeContextRegistry {
   const runtimeContexts = new Map<string, StoredRuntimeContext>();
   const runtimeContextWatchers = new Set<{

src/plugins/runtime/load-context.ts

@@ -18,6 +18,7 @@ import type { PluginLogger } from "../types.js";
 
 const log = createSubsystemLogger("plugins");
 
+/** Resolved plugin runtime load context shared by runtime loader callers. */
 export type PluginRuntimeLoadContext = {
   rawConfig: OpenClawConfig;
   config: OpenClawConfig;
@@ -30,6 +31,7 @@ export type PluginRuntimeLoadContext = {
   installRecords?: Record<string, PluginInstallRecord>;
 };
 
+/** Runtime load option values that can be passed directly to plugin loading. */
 export type PluginRuntimeResolvedLoadValues = Pick<
   PluginLoadOptions,
   | "config"
@@ -42,6 +44,7 @@ export type PluginRuntimeResolvedLoadValues = Pick<
   | "installRecords"
 >;
 
+/** Options accepted while resolving plugin runtime load context. */
 export type PluginRuntimeLoadContextOptions = {
   config?: OpenClawConfig;
   activationSourceConfig?: OpenClawConfig;
@@ -51,6 +54,7 @@ export type PluginRuntimeLoadContextOptions = {
   manifestRegistry?: PluginManifestRegistry;
 };
 
+/** Creates the default plugin runtime loader logger. */
 export function createPluginRuntimeLoaderLogger(): PluginLogger {
   return {
     info: (message) => log.info(message),
@@ -60,6 +64,7 @@ export function createPluginRuntimeLoaderLogger(): PluginLogger {
   };
 }
 
+/** Resolves config, manifests, install records, and auto-enable state for runtime loads. */
 export function resolvePluginRuntimeLoadContext(
   options?: PluginRuntimeLoadContextOptions,
 ): PluginRuntimeLoadContext {
@@ -93,6 +98,7 @@ export function resolvePluginRuntimeLoadContext(
   const workspaceDir =
     options?.workspaceDir ?? resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
   if (metadataSnapshot) {
+    // Reusable snapshots stay available to later manifest-policy lookups for this runtime load.
     if (isReusableCurrentPluginMetadataSnapshot(metadataSnapshot)) {
       setCurrentPluginMetadataSnapshot(metadataSnapshot, {
         config: rawConfig,
@@ -117,6 +123,7 @@ export function resolvePluginRuntimeLoadContext(
   };
 }
 
+/** Builds plugin load options from a resolved runtime load context. */
 export function buildPluginRuntimeLoadOptions(
   context: PluginRuntimeLoadContext,
   overrides?: Partial<PluginLoadOptions>,
@@ -124,6 +131,7 @@ export function buildPluginRuntimeLoadOptions(
   return buildPluginRuntimeLoadOptionsFromValues(context, overrides);
 }
 
+/** Builds plugin load options from explicit runtime load values. */
 export function buildPluginRuntimeLoadOptionsFromValues(
   values: PluginRuntimeResolvedLoadValues,
   overrides?: Partial<PluginLoadOptions>,

src/plugins/runtime/metadata-registry-loader.ts

@@ -10,6 +10,7 @@ import {
   type PluginRuntimeLoadContext,
 } from "./load-context.js";
 
+/** Loads a non-activated plugin metadata registry snapshot for validation/status callers. */
 export function loadPluginMetadataRegistrySnapshot(options?: {
   config?: OpenClawConfig;
   activationSourceConfig?: OpenClawConfig;

src/plugins/runtime/runtime-agent.ts

@@ -38,6 +38,7 @@ function resolveRuntimeThinkingCatalog(
   return configuredCatalog.length > 0 ? configuredCatalog : undefined;
 }
 
+/** Creates the plugin runtime agent facade with lazy embedded-agent/session helpers. */
 export function createRuntimeAgent(): PluginRuntime["agent"] {
   const agentRuntime = {
     defaults: {

src/plugins/runtime/runtime-cache.ts

@@ -1,3 +1,4 @@
+/** Defines a lazily computed enumerable property on a runtime facade. */
 export function defineCachedValue(target: object, key: PropertyKey, create: () => unknown): void {
   let cached: unknown;
   let ready = false;

src/plugins/runtime/runtime-embedded-agent.runtime.ts

@@ -1 +1,2 @@
+/** Lazy runtime barrel for embedded-agent execution. */
 export { runEmbeddedAgent } from "../../agents/embedded-agent.js";

src/plugins/runtime/runtime-logging.ts

@@ -15,6 +15,7 @@ function writeRuntimeLog(
   log(message);
 }
 
+/** Creates the plugin runtime logging facade. */
 export function createRuntimeLogging(): PluginRuntime["logging"] {
   return {
     shouldLogVerbose,

src/plugins/runtime/task-domain-types.ts

@@ -11,6 +11,7 @@ import type {
 } from "../../tasks/task-registry.types.js";
 import type { DeliveryContext } from "../../utils/delivery-context.types.js";
 
+/** Aggregate task-run counts exposed to plugin task views. */
 export type TaskRunAggregateSummary = {
   total: number;
   active: number;
@@ -20,6 +21,7 @@ export type TaskRunAggregateSummary = {
   byRuntime: TaskRuntimeCounts;
 };
 
+/** Public task run summary exposed through plugin runtime task APIs. */
 export type TaskRunView = {
   id: string;
   runtime: TaskRuntime;
@@ -48,8 +50,10 @@ export type TaskRunView = {
   terminalOutcome?: TaskTerminalOutcome;
 };
 
+/** Detailed task run view; currently equal to the summary view. */
 export type TaskRunDetail = TaskRunView;
 
+/** Result returned when cancelling a task run. */
 export type TaskRunCancelResult = {
   found: boolean;
   cancelled: boolean;
@@ -57,6 +61,7 @@ export type TaskRunCancelResult = {
   task?: TaskRunDetail;
 };
 
+/** Public task flow summary exposed through plugin runtime task APIs. */
 export type TaskFlowView = {
   id: string;
   ownerKey: string;
@@ -71,6 +76,7 @@ export type TaskFlowView = {
   endedAt?: number;
 };
 
+/** Detailed task flow view with state, wait, blocked, and task summary data. */
 export type TaskFlowDetail = TaskFlowView & {
   state?: JsonValue;
   wait?: JsonValue;