docs: document remaining plugin sdk files

src/plugin-sdk/acp-runtime.test.ts

@@ -1,3 +1,4 @@
+// ACP runtime tests cover plugin-facing ACP runtime setup and gateway dispatch behavior.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { buildTestCtx } from "../auto-reply/reply/test-ctx.js";
 

src/plugin-sdk/agent-dir-compat.ts

@@ -1,3 +1,4 @@
+// Agent directory compatibility helpers resolve legacy and current agent directory locations.
 import { resolveDefaultAgentDir } from "../agents/agent-scope-config.js";
 import { resolveUserPath } from "../utils.js";
 

src/plugin-sdk/browser-bridge.test.ts

@@ -1,3 +1,4 @@
+// Browser bridge tests cover browser control bridge requests and local server behavior.
 import type { Server } from "node:http";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 

src/plugin-sdk/browser-cdp.ts

@@ -1,3 +1,4 @@
+// Browser CDP helpers connect plugin browser automation to Chrome DevTools Protocol sessions.
 import { redactSensitiveText } from "../logging/redact.js";
 
 /** Detect an operator-supplied port before WHATWG URL normalization drops default ports. */

src/plugin-sdk/browser-config.test.ts

@@ -1,3 +1,4 @@
+// Browser config tests cover plugin browser configuration defaults and overrides.
 import { describe, expect, it } from "vitest";
 import type { BrowserControlAuth } from "./browser-config.js";
 import {

src/plugin-sdk/browser-facades.test.ts

@@ -1,3 +1,4 @@
+// Browser facade tests cover browser plugin facade loading and runtime API shape.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loadBundledPluginPublicSurfaceModuleSync = vi.hoisted(() => vi.fn());

src/plugin-sdk/browser-host-inspection.test.ts

@@ -1,3 +1,4 @@
+// Browser host inspection tests cover browser host discovery and inspection helpers.
 import { beforeEach, describe, it, vi } from "vitest";
 import {
   expectBrowserHostInspectionDelegation,

src/plugin-sdk/browser-subpaths.test.ts

@@ -1,3 +1,4 @@
+// Browser subpath tests cover plugin SDK browser subpath exports and lazy boundaries.
 import { describe, expect, it } from "vitest";
 import { parseBrowserHttpUrl, redactCdpUrl } from "./browser-cdp.js";
 import { resolveBrowserControlAuth } from "./browser-control-auth.js";

src/plugin-sdk/channel-config-helpers.ts

@@ -1,3 +1,4 @@
+// Channel config helpers normalize account and channel config values for plugin setup.
 import { normalizeOptionalLowercaseString } from "../../packages/normalization-core/src/string-coerce.js";
 import { normalizeStringEntries } from "../../packages/normalization-core/src/string-normalization.js";
 import {

src/plugin-sdk/channel-entry-contract.test.ts

@@ -1,3 +1,4 @@
+// Channel entry contract tests cover SDK channel entrypoint exports and package boundaries.
 import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";

src/plugin-sdk/channel-ingress-runtime.test.ts

@@ -1,3 +1,4 @@
+// Channel ingress runtime tests cover inbound message normalization and runtime contracts.
 import { describe, expect, expectTypeOf, it, vi } from "vitest";
 import type { AccessFacts } from "../channels/turn/types.js";
 import {

src/plugin-sdk/channel-lifecycle.core.ts

@@ -1,3 +1,4 @@
+// Channel lifecycle core contracts define account lifecycle snapshots and sync hooks.
 import type { ChannelAccountSnapshot } from "../channels/plugins/types.core.js";
 import { createRunStateMachine, type RunStateStatusSink } from "../channels/run-state-machine.js";
 import { KeyedAsyncQueue } from "./keyed-async-queue.js";

src/plugin-sdk/channel-policy.ts

@@ -1,3 +1,4 @@
+// Channel policy helpers evaluate plugin channel runtime policy and operator-facing warnings.
 import {
   normalizeStringEntries,
   uniqueStrings,

src/plugin-sdk/channel-setup.test.ts

@@ -1,3 +1,4 @@
+// Channel setup tests cover setup wizard finalize behavior and config write contracts.
 import { runSetupWizardFinalize } from "openclaw/plugin-sdk/plugin-test-runtime";
 import { describe, expect, it } from "vitest";
 import { createOptionalChannelSetupSurface } from "./channel-setup.js";

src/plugin-sdk/channel-setup.ts

@@ -1,3 +1,4 @@
+// Channel setup contracts expose setup wizard hooks and account config writes to plugins.
 import type { ChannelSetupWizard } from "../channels/plugins/setup-wizard-types.js";
 import type { ChannelSetupAdapter } from "../channels/plugins/types.adapters.js";
 import {

src/plugin-sdk/delivery-queue-runtime.ts

@@ -1,3 +1,4 @@
+// Delivery queue runtime helpers persist and replay outbound plugin delivery work.
 import {
   drainPendingDeliveries as coreDrainPendingDeliveries,
   type DeliverFn,

src/plugin-sdk/extension-shared.test.ts

@@ -1,3 +1,4 @@
+// Extension shared tests cover plugin-safe shared runtime helpers and proxy configuration.
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/plugin-sdk/facade-loader.ts

@@ -1,3 +1,4 @@
+// Facade loader helpers resolve plugin public API modules from source, dist, or installed roots.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";

src/plugin-sdk/facade-runtime.test.ts

@@ -1,3 +1,4 @@
+// Facade runtime tests cover installed plugin facade loading and fallback resolution.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

src/plugin-sdk/fetch-auth.test.ts

@@ -1,3 +1,4 @@
+// Fetch auth tests cover scoped bearer fallback retries and request header preservation.
 import { describe, expect, it, vi } from "vitest";
 import { fetchWithBearerAuthScopeFallback } from "./fetch-auth.js";
 import { resolveRequestUrl } from "./request-url.js";

src/plugin-sdk/inbound-reply-dispatch.test.ts

@@ -1,3 +1,4 @@
+// Inbound reply dispatch tests cover plugin reply routing from inbound channel messages.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { DispatchReplyWithBufferedBlockDispatcher } from "../auto-reply/reply/provider-dispatcher.types.js";
 import type { FinalizedMsgContext } from "../auto-reply/templating.js";

src/plugin-sdk/lmstudio-runtime.test.ts

@@ -1,3 +1,4 @@
+// LM Studio runtime tests cover provider runtime setup, auth status, and model discovery.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loadBundledPluginPublicSurfaceModuleSync = vi.hoisted(() => vi.fn());

src/plugin-sdk/memory-core-host-runtime-core.ts

@@ -1,3 +1,4 @@
+// Memory core host runtime exports bridge memory host runtime-core APIs into the SDK.
 export * from "../../packages/memory-host-sdk/src/runtime-core.js";
 export {
   DEFAULT_AGENT_COMPACTION_RESERVE_TOKENS_FLOOR,

src/plugin-sdk/outbound-media.test.ts

@@ -1,3 +1,4 @@
+// Outbound media tests cover plugin media attachment normalization and access policy.
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const loadWebMediaMock = vi.hoisted(() => vi.fn());

src/plugin-sdk/pairing-access.ts

@@ -1,3 +1,4 @@
+// Pairing access helpers resolve channel/device pairing visibility for plugin callers.
 import type { ChannelId } from "../channels/plugins/types.public.js";
 import type { PluginRuntime } from "../plugins/runtime/types.js";
 import { normalizeAccountId } from "../routing/session-key.js";

src/plugin-sdk/provider-auth-result.test.ts

@@ -1,3 +1,4 @@
+// Provider auth result tests cover status result normalization and display metadata.
 import { describe, expect, it } from "vitest";
 import { MAX_DATE_TIMESTAMP_MS } from "../../packages/normalization-core/src/number-coercion.js";
 import { buildOauthProviderAuthResult } from "./provider-auth-result.js";

src/plugin-sdk/provider-auth-result.ts

@@ -1,3 +1,4 @@
+// Provider auth result helpers normalize credential checks into stable setup/status results.
 import { asDateTimestampMs } from "../../packages/normalization-core/src/number-coercion.js";
 import { buildAuthProfileId } from "../agents/auth-profiles/identity.js";
 import type { AuthProfileCredential } from "../agents/auth-profiles/types.js";

src/plugin-sdk/provider-auth-runtime.test.ts

@@ -1,3 +1,4 @@
+// Provider auth runtime tests cover OAuth callback handling and provider auth flow helpers.
 import { createServer } from "node:net";
 import { describe, expect, it, vi } from "vitest";
 import { MAX_TIMER_TIMEOUT_MS } from "../shared/number-coercion.js";

src/plugin-sdk/provider-auth-runtime.ts

@@ -1,3 +1,4 @@
+// Provider auth runtime helpers implement OAuth loopback, token exchange, and auth persistence.
 import crypto from "node:crypto";
 import fs from "node:fs";
 import { createServer } from "node:http";

src/plugin-sdk/provider-auth.test.ts

@@ -1,3 +1,4 @@
+// Provider auth tests cover credential resolution, setup state, and auth method contracts.
 import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import type { AuthProfileStore } from "../agents/auth-profiles/types.js";
 

src/plugin-sdk/provider-catalog-shared.test.ts

@@ -1,3 +1,4 @@
+// Provider catalog shared tests cover catalog hashing, normalization, and model visibility.
 import type { ModelCatalogProvider } from "@openclaw/model-catalog-core/model-catalog-types";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {

src/plugin-sdk/provider-entry.test.ts

@@ -1,3 +1,4 @@
+// Provider entry tests cover provider plugin entry contracts and catalog integration.
 import { describe, expect, it } from "vitest";
 import type { ModelDefinitionConfig } from "../config/types.models.js";
 import { capturePluginRegistration } from "../plugins/captured-registration.js";

src/plugin-sdk/provider-entry.ts

@@ -1,3 +1,4 @@
+// Provider entry contracts define provider plugin hooks, model catalogs, and runtime adapters.
 import type { UnifiedModelCatalogEntry } from "@openclaw/model-catalog-core/model-catalog-types";
 import {
   normalizeStringEntries,

src/plugin-sdk/provider-oauth-runtime.test.ts

@@ -1,3 +1,4 @@
+// Provider OAuth runtime tests cover PKCE redirects, callback parsing, and token exchange helpers.
 import { describe, expect, it } from "vitest";
 import {
   parseOAuthAuthorizationInput,

src/plugin-sdk/provider-openai-chatgpt-auth.test.ts

@@ -1,3 +1,4 @@
+// OpenAI ChatGPT auth tests cover auth status normalization and token expiry handling.
 import { describe, expect, it } from "vitest";
 import {
   buildOpenAICodexCredentialExtra,

src/plugin-sdk/provider-openai-chatgpt-auth.ts

@@ -1,3 +1,4 @@
+// OpenAI ChatGPT auth helpers normalize OAuth session data for provider plugins.
 import { resolveExpiresAtMsFromEpochSeconds } from "../../packages/normalization-core/src/number-coercion.js";
 import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
 

src/plugin-sdk/provider-stream.test.ts

@@ -1,3 +1,4 @@
+// Provider stream tests cover shared stream-wrapper families and payload compatibility.
 import type { StreamFn } from "openclaw/plugin-sdk/agent-core";
 import { describe, expect, it } from "vitest";
 import { createAssistantMessageEventStream } from "../llm/utils/event-stream.js";

src/plugin-sdk/provider-tools.test.ts

@@ -1,3 +1,4 @@
+// Provider tool tests cover tool schema conversion and provider payload compatibility.
 import { describe, expect, it } from "vitest";
 import {
   buildProviderToolCompatFamilyHooks,

src/plugin-sdk/provider-web-search-contract-fields.ts

@@ -1,3 +1,4 @@
+// Provider web-search contract fields expose shared config keys for web-search-capable providers.
 import type { SearchConfigRecord } from "../agents/tools/web-search-provider-common.js";
 import {
   getScopedCredentialValue,

src/plugin-sdk/qa-channel-protocol.test.ts

@@ -1,3 +1,4 @@
+// QA channel protocol tests cover synthetic channel payload validation and parsing.
 import { describe, expect, it } from "vitest";
 import { sanitizeQaBusToolCalls } from "./qa-channel-protocol.js";
 

src/plugin-sdk/qa-channel.test.ts

@@ -1,3 +1,4 @@
+// QA channel tests cover QA channel runtime behavior and mocked message delivery.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loadBundledPluginPublicSurfaceModuleSync = vi.hoisted(() => vi.fn());

src/plugin-sdk/qa-runtime.ts

@@ -1,3 +1,4 @@
+// QA runtime helpers register and execute plugin QA scenarios from local files.
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import { createServer } from "node:net";

src/plugin-sdk/reply-payload.test.ts

@@ -1,3 +1,4 @@
+// Reply payload tests cover reply target parsing, media payloads, and approval metadata.
 import { describe, expect, it, vi } from "vitest";
 import {
   buildTtsSupplementMediaPayload,

src/plugin-sdk/run-command.ts

@@ -1,3 +1,4 @@
+// Run command helpers execute plugin commands with normalized errors and captured output.
 import { formatErrorMessage } from "../infra/errors.js";
 import { runCommandWithTimeout } from "../process/exec.js";
 

src/plugin-sdk/runtime-store.ts

@@ -1,3 +1,4 @@
+// Runtime store exports expose plugin runtime type contracts without loading runtime code.
 export type { PluginRuntime } from "../plugins/runtime/types.js";
 
 const pluginRuntimeStoreRegistryKey = Symbol.for("openclaw.plugin-sdk.runtime-store-registry");

src/plugin-sdk/secret-input.ts

@@ -1,3 +1,4 @@
+// Secret input helpers normalize credential prompt definitions for plugin setup flows.
 import { z } from "zod";
 import {
   hasConfiguredSecretInput,

src/plugin-sdk/session-transcript-hit.test.ts

@@ -1,3 +1,4 @@
+// Session transcript hit tests cover transcript match formatting and path resolution.
 import { describe, expect, it } from "vitest";
 import type { SessionEntry } from "../config/sessions/types.js";
 import {

src/plugin-sdk/ssrf-policy.test.ts

@@ -1,3 +1,4 @@
+// SSRF policy tests cover URL allow/deny decisions for plugin network helpers.
 import { describe, expect, it, vi } from "vitest";
 import type { LookupFn } from "../infra/net/ssrf.js";
 import {

src/plugin-sdk/ssrf-policy.ts

@@ -1,3 +1,4 @@
+// SSRF policy helpers enforce network target safety for plugin HTTP requests.
 import { asNullableRecord } from "../../packages/normalization-core/src/record-coerce.js";
 import { normalizeLowercaseStringOrEmpty } from "../../packages/normalization-core/src/string-coerce.js";
 import { normalizeUniqueStringEntries } from "../../packages/normalization-core/src/string-normalization.js";

src/plugin-sdk/status-helpers.test.ts

@@ -1,3 +1,4 @@
+// Status helper tests cover plugin status normalization and user-facing summaries.
 import { describe, expect, it } from "vitest";
 import {
   createAsyncComputedAccountStatusAdapter,

src/plugin-sdk/temp-path.test.ts

@@ -1,3 +1,4 @@
+// Temp path tests cover plugin SDK temp directory creation and cleanup helpers.
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";

src/plugin-sdk/test-helpers/agents/openclaw-owned-tool-runtime-contract.ts

@@ -1,3 +1,4 @@
+// OpenClaw-owned tool runtime contract helpers mock agent tool runtimes in SDK tests.
 import { vi } from "vitest";
 import { resetAdjustedParamsByToolCallIdForTests } from "../../../agents/agent-tools.before-tool-call.state.js";
 import type { AgentToolResult } from "../../../agents/runtime/index.js";

src/plugin-sdk/test-helpers/agents/schema-normalization-runtime-contract.ts

@@ -1,3 +1,4 @@
+// Schema normalization runtime contract helpers create tools for provider schema tests.
 export function createParameterFreeTool(name = "ping") {
   return {
     name,

src/plugin-sdk/test-helpers/agents/transcript-repair-runtime-contract.ts

@@ -1,3 +1,4 @@
+// Transcript repair runtime contract helpers build agent transcript repair fixtures.
 import type { AgentMessage } from "../../../agents/runtime/index.js";
 
 export const QUEUED_USER_MESSAGE_MARKER =

src/plugin-sdk/test-helpers/channel-contract-suites.ts

@@ -1,3 +1,4 @@
+// Channel contract suites provide reusable expectations for channel plugin test coverage.
 import { expect, it } from "vitest";
 import type {
   ChannelAccountSnapshot,

src/plugin-sdk/test-helpers/dashscope-video-provider.ts

@@ -1,3 +1,4 @@
+// Dashscope video provider test helpers mock video provider runtime behavior.
 import { expect, vi } from "vitest";
 import type { VideoGenerationResult } from "../video-generation.js";
 

src/plugin-sdk/test-helpers/onboard-config.ts

@@ -1,3 +1,4 @@
+// Onboard config test helpers build model/provider config fixtures for plugin tests.
 import type { ModelApi } from "../provider-model-shared.js";
 import type { OpenClawConfig } from "../testing.js";
 

src/plugin-sdk/test-helpers/outbound-delivery.ts

@@ -1,3 +1,4 @@
+// Outbound delivery test helpers re-export channel delivery fixtures for plugin tests.
 export {
   addTestHook,
   createEmptyPluginRegistry,

src/plugin-sdk/test-helpers/plugin-runtime-mock.ts

@@ -1,3 +1,4 @@
+// Plugin runtime mock helpers build minimal runtime doubles for plugin SDK tests.
 import { vi } from "vitest";
 import {
   normalizeInboundTextNewlines,

src/plugin-sdk/test-helpers/provider-auth-contract.ts

@@ -1,3 +1,4 @@
+// Provider auth contract helpers define reusable tests for provider auth implementations.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { clearRuntimeAuthProfileStoreSnapshots, type AuthProfileStore } from "../agent-runtime.js";
 import { createNonExitingRuntime } from "../runtime.js";

src/plugin-sdk/test-helpers/provider-contract-suites.ts

@@ -1,3 +1,4 @@
+// Provider contract suites provide shared assertions for provider plugin behavior.
 import { expect, it } from "vitest";
 import type { ProviderPlugin } from "../provider-model-shared.js";
 import type { WebFetchProviderPlugin } from "../provider-web-fetch-contract.js";

src/plugin-sdk/test-helpers/provider-contract.ts

@@ -1,3 +1,4 @@
+// Provider contract helpers expose reusable provider plugin contract test setup.
 import { describe, expect, it } from "vitest";
 import {
   providerContractLoadError,

src/plugin-sdk/test-helpers/provider-discovery-contract.ts

@@ -1,3 +1,4 @@
+// Provider discovery contract helpers define reusable discovery tests for provider plugins.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { AuthProfileStore, OpenClawConfig } from "../provider-auth.js";
 import {

src/plugin-sdk/test-helpers/provider-runtime-contract.ts

@@ -1,3 +1,4 @@
+// Provider runtime contract helpers define reusable runtime tests for provider plugins.
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ProviderRuntimeModel } from "../plugin-entry.js";
 import { registerProviderPlugin, requireRegisteredProvider } from "../plugin-test-runtime.js";

src/plugin-sdk/test-helpers/public-surface-loader.ts

@@ -1,3 +1,4 @@
+// Public surface loader test helpers import SDK subpaths for export-contract assertions.
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";

src/plugin-sdk/test-helpers/stt-live-audio.ts

@@ -1,3 +1,4 @@
+// STT live audio test helpers provide audio fixtures and expectations for speech plugins.
 import { expect } from "vitest";
 import type {
   RealtimeTranscriptionProviderConfig,

src/plugin-sdk/test-helpers/temp-home.ts

@@ -1,3 +1,4 @@
+// Temp home test helpers create isolated OpenClaw home directories for plugin tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/plugin-sdk/tool-payload.test.ts

@@ -1,3 +1,4 @@
+// Tool payload tests cover model tool-call schema conversion and compatibility payloads.
 import { describe, expect, it } from "vitest";
 import {
   extractToolPayload,

src/plugin-sdk/tool-plugin.ts

@@ -1,3 +1,4 @@
+// Tool plugin contracts describe plugin-provided tools, schemas, and invocation hooks.
 import { Type, type Static, type TSchema } from "typebox";
 import type { AgentToolResult, AgentToolUpdateCallback } from "../agents/runtime/index.js";
 import { jsonResult, textResult } from "../agents/tools/common.js";

src/plugin-sdk/tts-runtime.ts

@@ -1,3 +1,4 @@
+// TTS runtime exports expose text-to-speech runtime helpers through the plugin SDK.
 export {
   TtsAutoSchema,
   TtsConfigSchema,

src/plugin-sdk/windows-spawn.ts

@@ -1,3 +1,4 @@
+// Windows spawn helpers resolve Windows command execution details for plugin runtimes.
 import { readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import {