docs: document sdk facade contracts

src/plugin-sdk/acp-runtime.ts

@@ -34,6 +34,7 @@ export { tryDispatchAcpReplyHook } from "./acp-runtime-backend.js";
 // Keep test helpers off the hot init path. Eagerly merging them here can
 // create a back-edge through the bundled ACP runtime chunk before the imported
 // testing bindings finish initialization.
+/** Lazy ACP test helper facade combining control-plane and runtime registry helpers. */
 export const testing = new Proxy({} as typeof managerTesting & typeof registryTesting, {
   get(_target, prop, receiver) {
     if (Reflect.has(managerTesting, prop)) {

src/plugin-sdk/agent-core.ts

@@ -7,11 +7,13 @@ import type { AgentCoreRuntimeDeps } from "../../packages/agent-core/src/runtime
 import type { CompleteSimpleFn, StreamFn } from "../../packages/llm-core/src/index.js";
 import { completeSimple, streamSimple } from "./llm.js";
 
+/** Runtime adapter that lets the package agent-core use OpenClaw LLM helpers. */
 export const openClawAgentCoreRuntime = {
   completeSimple: completeSimple as unknown as CompleteSimpleFn,
   streamSimple: streamSimple as unknown as StreamFn,
 } satisfies AgentCoreRuntimeDeps;
 
+/** Agent-core class preconfigured with OpenClaw runtime dependencies. */
 export class Agent extends CoreAgent {
   constructor(options: CoreAgentOptions = {}) {
     super({ runtime: openClawAgentCoreRuntime, ...options });

src/plugin-sdk/anthropic-cli.ts

@@ -12,7 +12,9 @@ function loadFacadeModule(): FacadeModule {
     artifactBasename: "api.js",
   });
 }
+/** Anthropic plugin backend id for Claude CLI provider detection. */
 export const CLAUDE_CLI_BACKEND_ID: FacadeModule["CLAUDE_CLI_BACKEND_ID"] =
   loadFacadeModule()["CLAUDE_CLI_BACKEND_ID"];
+/** Returns whether a provider id belongs to the Claude CLI backend family. */
 export const isClaudeCliProvider: FacadeModule["isClaudeCliProvider"] = ((...args) =>
   loadFacadeModule()["isClaudeCliProvider"](...args)) as FacadeModule["isClaudeCliProvider"];

src/plugin-sdk/feishu-security.ts

@@ -14,6 +14,7 @@ function loadSecuritySurface(): SecuritySurface {
   });
 }
 
+/** Collect Feishu plugin security findings through the lazy bundled-plugin facade. */
 export const collectFeishuSecurityAuditFindings: SecuritySurface["collectFeishuSecurityAuditFindings"] =
   ((...args) =>
     loadSecuritySurface().collectFeishuSecurityAuditFindings(

src/plugin-sdk/matrix-deps.ts

@@ -17,7 +17,9 @@ function loadFacadeModule(): FacadeModule {
   });
 }
 
+/** Ensure Matrix plugin runtime dependencies are available before Matrix setup/use. */
 export const ensureMatrixSdkInstalled: FacadeModule["ensureMatrixSdkInstalled"] = ((...args) =>
   loadFacadeModule().ensureMatrixSdkInstalled(...args)) as FacadeModule["ensureMatrixSdkInstalled"];
+/** Returns whether Matrix SDK dependencies are currently importable. */
 export const isMatrixSdkAvailable: FacadeModule["isMatrixSdkAvailable"] = ((...args) =>
   loadFacadeModule().isMatrixSdkAvailable(...args)) as FacadeModule["isMatrixSdkAvailable"];

src/plugin-sdk/provider-zai-endpoint.ts

@@ -6,8 +6,10 @@
 
 import { loadBundledPluginPublicSurfaceModuleSync } from "./facade-loader.js";
 
+/** Supported Z.AI endpoint families handled by the deprecated endpoint probe. */
 export type ZaiEndpointId = "global" | "cn" | "coding-global" | "coding-cn";
 
+/** Result of probing a Z.AI API key against one endpoint family. */
 export type ZaiDetectedEndpoint = {
   endpoint: ZaiEndpointId;
   baseUrl: string;

src/plugin-sdk/qa-lab.ts

@@ -23,9 +23,11 @@ function isMissingQaLabFacadeError(err: unknown): boolean {
   );
 }
 
+/** Register QA Lab CLI commands when the bundled QA Lab facade is present. */
 export const registerQaLabCli: FacadeModule["registerQaLabCli"] = ((...args) =>
   loadFacadeModule().registerQaLabCli(...args)) as FacadeModule["registerQaLabCli"];
 
+/** Returns whether the QA Lab CLI facade can be loaded in this package build. */
 export const isQaLabCliAvailable: FacadeModule["isQaLabCliAvailable"] = (() => {
   try {
     return loadFacadeModule().isQaLabCliAvailable();

src/plugin-sdk/synology-chat.ts

@@ -21,6 +21,7 @@ function loadFacadeModule(): FacadeModule {
   });
 }
 
+/** Collect Synology Chat security findings through the lazy bundled-plugin facade. */
 export const collectSynologyChatSecurityAuditFindings: FacadeModule["collectSynologyChatSecurityAuditFindings"] =
   ((...args) =>
     loadFacadeModule().collectSynologyChatSecurityAuditFindings(