docs: document plugin runtime helpers

src/plugins/capability-runtime-vitest-shims/config-runtime.ts

@@ -1,3 +1,4 @@
+// Config-runtime Vitest shims expose lightweight config helpers for capability runtime tests.
 import { resolveActiveTalkProviderConfig } from "../../config/talk.js";
 import type { OpenClawConfig } from "../../config/types.js";
 

src/plugins/capability-runtime-vitest-shims/speech-core.ts

@@ -1,3 +1,4 @@
+// Speech-core Vitest shims expose speech capability types without loading full runtime code.
 export type {
   SpeechDirectiveTokenParseContext,
   SpeechDirectiveTokenParseResult,

src/plugins/compat/registry.test.ts

@@ -1,3 +1,4 @@
+// Plugin compatibility registry tests cover compatibility metadata loading and validation.
 import fs from "node:fs";
 import { beforeAll, describe, expect, it } from "vitest";
 import { listGitTrackedFiles } from "../../test-utils/repo-files.js";

src/plugins/compat/registry.ts

@@ -1,3 +1,4 @@
+// Plugin compatibility registry exposes known plugin compatibility metadata to doctor/update flows.
 import type { PluginCompatRecord } from "./types.js";
 
 const CHANNEL_RUNTIME_SDK_SURFACE = ["openclaw/plugin-sdk/channel", "runtime"].join("-");

src/plugins/compat/types.ts

@@ -1,3 +1,4 @@
+// Plugin compatibility types describe lifecycle status for plugin migration and deprecation checks.
 export type PluginCompatStatus = "active" | "deprecated" | "removal-pending" | "removed";
 
 export type PluginCompatOwner =

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

@@ -1,3 +1,4 @@
+// Channel runtime context helpers build plugin runtime context for channel execution.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type {
   ChannelRuntimeContextEvent,

src/plugins/runtime/gateway-bindings.ts

@@ -1,3 +1,4 @@
+// Gateway binding helpers expose plugin runtime bindings through gateway-safe singletons.
 import { resolveGlobalSingleton } from "../../shared/global-singleton.js";
 import type { PluginRuntime } from "./types.js";
 

src/plugins/runtime/gateway-request-scope.test.ts

@@ -1,3 +1,4 @@
+// Gateway request scope tests cover request-local plugin runtime context propagation.
 import { describe, expect, it, vi } from "vitest";
 import type { PluginRuntimeGatewayRequestScope } from "./gateway-request-scope.js";
 

src/plugins/runtime/gateway-request-scope.ts

@@ -1,3 +1,4 @@
+// Gateway request scope tracks request-local plugin runtime context across async work.
 import { AsyncLocalStorage } from "node:async_hooks";
 import type {
   GatewayRequestContext,

src/plugins/runtime/index.test.ts

@@ -1,3 +1,4 @@
+// Plugin runtime index tests cover runtime entrypoint exports and registry setup.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../agents/defaults.js";
 import {

src/plugins/runtime/load-context.ts

@@ -1,3 +1,4 @@
+// Plugin runtime load context helpers resolve agent and workspace facts for runtime activation.
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agents/agent-scope.js";
 import { getRuntimeConfig } from "../../config/config.js";
 import { applyPluginAutoEnable } from "../../config/plugin-auto-enable.js";

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

@@ -1,3 +1,4 @@
+// Metadata registry loader tests cover metadata-only plugin registry assembly.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { PluginLoadOptions } from "../loader.js";
 

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

@@ -1,3 +1,4 @@
+// Metadata registry loader builds plugin metadata registries without activating runtime barrels.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { loadOpenClawPlugins } from "../loader.js";
 import type { PluginManifestRegistry } from "../manifest-registry.js";

src/plugins/runtime/runtime-agent.ts

@@ -1,3 +1,4 @@
+// Runtime agent helpers resolve agent-scoped directories and config for plugin execution.
 import { resolveAgentDir, resolveAgentWorkspaceDir } from "../../agents/agent-scope.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../agents/defaults.js";
 import { resolveAgentIdentity } from "../../agents/identity.js";

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

@@ -1,3 +1,4 @@
+// Runtime channel tests cover channel plugin runtime send, reply, and capability behavior.
 import { describe, expect, it, vi } from "vitest";
 import { createRuntimeChannel } from "./runtime-channel.js";
 

src/plugins/runtime/runtime-channel.ts

@@ -1,3 +1,4 @@
+// Runtime channel helpers adapt channel plugin APIs into core channel send and reply flows.
 import { convertMarkdownTables } from "../../../packages/markdown-core/src/tables.js";
 import { resolveEffectiveMessagesConfig, resolveHumanDelayConfig } from "../../agents/identity.js";
 import {

src/plugins/runtime/runtime-config.test.ts

@@ -1,3 +1,4 @@
+// Runtime config tests cover plugin runtime config normalization and lookup.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 

src/plugins/runtime/runtime-llm.runtime.ts

@@ -1,3 +1,4 @@
+// Runtime LLM helpers adapt plugin provider hooks into the core model runtime.
 import { asFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { modelKey } from "../../agents/model-ref-shared.js";

src/plugins/runtime/runtime-logging.test.ts

@@ -1,3 +1,4 @@
+// Runtime logging tests cover plugin runtime log routing and verbosity behavior.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loggingMocks = vi.hoisted(() => {

src/plugins/runtime/runtime-logging.ts

@@ -1,3 +1,4 @@
+// Runtime logging helpers route plugin runtime logs through OpenClaw verbosity controls.
 import { shouldLogVerbose } from "../../globals.js";
 import { getChildLogger } from "../../logging.js";
 import { normalizeLogLevel } from "../../logging/levels.js";

src/plugins/runtime/runtime-model-auth.runtime.test.ts

@@ -1,3 +1,4 @@
+// Runtime model auth tests cover provider auth resolution inside plugin runtime loading.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const hoisted = vi.hoisted(() => ({

src/plugins/runtime/runtime-plugin-boundary.ts

@@ -1,3 +1,4 @@
+// Runtime plugin boundary helpers enforce package and source boundaries for runtime loading.
 import fs from "node:fs";
 import path from "node:path";
 import { getRuntimeConfig } from "../../config/config.js";

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

@@ -1,3 +1,4 @@
+// Runtime registry loader tests cover plugin runtime assembly and activation boundaries.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createEmptyPluginRegistry } from "../registry.js";
 

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

@@ -1,3 +1,4 @@
+// Runtime registry loader assembles activated plugin runtimes from config and registry metadata.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { withActivatedPluginIds } from "../activation-context.js";
 import {

src/plugins/runtime/runtime-task-test-harness.ts

@@ -1,3 +1,4 @@
+// Runtime task test harness helpers build mocked plugin runtimes for task-flow tests.
 import { vi } from "vitest";
 import { resetDetachedTaskLifecycleRuntimeForTests } from "../../tasks/detached-task-runtime.js";
 import {

src/plugins/runtime/runtime-taskflow.test.ts

@@ -1,3 +1,4 @@
+// Runtime task-flow tests cover plugin task-flow registration and execution behavior.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { getTaskFlowById } from "../../tasks/task-flow-registry.js";
 import { getTaskById } from "../../tasks/task-registry.js";

src/plugins/runtime/runtime-taskflow.ts

@@ -1,3 +1,4 @@
+// Runtime task-flow helpers adapt plugin task descriptors into executable task flows.
 import {
   cancelFlowByIdForOwner,
   getFlowTaskSummary,

src/plugins/runtime/runtime-tasks.test.ts

@@ -1,3 +1,4 @@
+// Runtime task tests cover plugin task runtime registration, invocation, and cleanup.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   getDetachedTaskLifecycleRuntime,

src/plugins/runtime/runtime-tasks.types.ts

@@ -1,3 +1,4 @@
+// Runtime task types describe plugin task runtime config and invocation options.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { TaskDeliveryState } from "../../tasks/task-registry.types.js";
 import type { OpenClawPluginToolContext } from "../tool-types.js";

src/plugins/runtime/runtime-web-channel-plugin.test.ts

@@ -1,3 +1,4 @@
+// Runtime web-channel plugin tests cover web channel plugin activation and runtime behavior.
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 afterEach(() => {

src/plugins/runtime/standalone-runtime-registry-loader.test.ts

@@ -1,3 +1,4 @@
+// Standalone runtime registry loader tests cover registry loading outside gateway startup.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { clearPluginLoaderCache, testing } from "../loader.js";
 import { createEmptyPluginRegistry } from "../registry-empty.js";

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

@@ -1,3 +1,4 @@
+// Standalone runtime registry loader builds plugin runtime registries outside gateway startup.
 import {
   type ActiveRuntimePluginRegistrySurface,
   getLoadedRuntimePluginRegistry,

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

@@ -1,3 +1,4 @@
+// Task domain types define plugin task-flow payloads shared by runtime adapters.
 import type { JsonValue } from "../../tasks/task-flow-registry.types.js";
 import type {
   TaskDeliveryStatus,

src/plugins/runtime/types.ts

@@ -1,3 +1,4 @@
+// Plugin runtime types describe activated plugin capabilities exposed to core execution.
 import type { PluginRuntimeChannel } from "./types-channel.js";
 import type { PluginRuntimeCore, RuntimeLogger } from "./types-core.js";