From 9e22b8560cdcac21b61782c944c68e263adfd6a9 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 22:22:21 -0400 Subject: [PATCH] docs: document sdk facade contracts --- src/plugin-sdk/acp-runtime.ts | 1 + src/plugin-sdk/agent-core.ts | 2 ++ src/plugin-sdk/anthropic-cli.ts | 2 ++ src/plugin-sdk/feishu-security.ts | 1 + src/plugin-sdk/matrix-deps.ts | 2 ++ src/plugin-sdk/provider-zai-endpoint.ts | 2 ++ src/plugin-sdk/qa-lab.ts | 2 ++ src/plugin-sdk/synology-chat.ts | 1 + 8 files changed, 13 insertions(+) diff --git a/src/plugin-sdk/acp-runtime.ts b/src/plugin-sdk/acp-runtime.ts index 485470cb9ddc..523c87d9bfc0 100644 --- a/src/plugin-sdk/acp-runtime.ts +++ b/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)) { diff --git a/src/plugin-sdk/agent-core.ts b/src/plugin-sdk/agent-core.ts index 40b9d054f6ab..2e94764adf5e 100644 --- a/src/plugin-sdk/agent-core.ts +++ b/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 }); diff --git a/src/plugin-sdk/anthropic-cli.ts b/src/plugin-sdk/anthropic-cli.ts index 89c03cd1c7c2..b4dcc8e4eb07 100644 --- a/src/plugin-sdk/anthropic-cli.ts +++ b/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"]; diff --git a/src/plugin-sdk/feishu-security.ts b/src/plugin-sdk/feishu-security.ts index 56ca20b643a0..bb0620680b27 100644 --- a/src/plugin-sdk/feishu-security.ts +++ b/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( diff --git a/src/plugin-sdk/matrix-deps.ts b/src/plugin-sdk/matrix-deps.ts index 488998a3284b..f4583241fba7 100644 --- a/src/plugin-sdk/matrix-deps.ts +++ b/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"]; diff --git a/src/plugin-sdk/provider-zai-endpoint.ts b/src/plugin-sdk/provider-zai-endpoint.ts index 750f620be687..00611307ccc8 100644 --- a/src/plugin-sdk/provider-zai-endpoint.ts +++ b/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; diff --git a/src/plugin-sdk/qa-lab.ts b/src/plugin-sdk/qa-lab.ts index 59e81aa1aaa2..d89b7978e176 100644 --- a/src/plugin-sdk/qa-lab.ts +++ b/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(); diff --git a/src/plugin-sdk/synology-chat.ts b/src/plugin-sdk/synology-chat.ts index 4447ee7110ba..87ae676438de 100644 --- a/src/plugin-sdk/synology-chat.ts +++ b/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(