docs: document sdk single-export contracts

steipete · steipete · commit 5d350e785a91 · 2026-06-04T22:16:29.000-04:00
diff --git a/src/plugin-sdk/agent-media-payload.ts b/src/plugin-sdk/agent-media-payload.ts
@@ -1,6 +1,7 @@
 // Agent media payload exports expose media roots and loaders for plugin-facing agent payloads.
 export { getAgentScopedMediaLocalRoots } from "../media/local-roots.js";
 
+/** Legacy agent media payload layout consumed by older agent adapters. */
 export type AgentMediaPayload = {
   MediaPath?: string;
   MediaType?: string;
diff --git a/src/plugin-sdk/browser-cdp.ts b/src/plugin-sdk/browser-cdp.ts
@@ -15,6 +15,7 @@ function hasRawExplicitPort(raw: string): boolean {
   return /:\d+$/.test(hostPort);
 }
 
+/** Parsed browser/CDP endpoint details with display-safe normalized URL variants. */
 export type BrowserHttpUrlParseResult = {
   /** Parsed URL object retained for callers that need protocol, host, path, or credentials. */
   parsed: URL;
diff --git a/src/plugin-sdk/browser-control-auth.ts b/src/plugin-sdk/browser-control-auth.ts
@@ -2,6 +2,7 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { loadBundledPluginPublicSurfaceModuleSync } from "./facade-loader.js";
 
+/** Browser control credentials resolved from config, env, or generated setup state. */
 export type BrowserControlAuth = {
   /** Bearer token accepted by the browser control HTTP surface. */
   token?: string;
diff --git a/src/plugin-sdk/command-status.runtime.ts b/src/plugin-sdk/command-status.runtime.ts
@@ -10,6 +10,7 @@ import type { ReplyPayload } from "../auto-reply/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { loadSessionEntry } from "../gateway/session-utils.js";
 
+/** Inputs for rendering direct-session status replies outside the active channel turn. */
 export type ResolveDirectStatusReplyForSessionParams = {
   /** Caller config used when the target session cannot load a config snapshot. */
   cfg: OpenClawConfig;
diff --git a/src/plugin-sdk/opencode.ts b/src/plugin-sdk/opencode.ts
@@ -11,6 +11,7 @@ const OPENCODE_SHARED_WIZARD_GROUP = {
   groupHint: OPENCODE_SHARED_HINT,
 } as const;
 
+/** Build a shared OpenCode API-key auth method for one OpenCode-compatible catalog. */
 export function createOpencodeCatalogApiKeyAuthMethod(params: {
   /** Provider id for the catalog being configured, such as `opencode` or `opencode-go`. */
   providerId: string;
diff --git a/src/plugin-sdk/outbound-media.ts b/src/plugin-sdk/outbound-media.ts
@@ -2,6 +2,7 @@
 import { buildOutboundMediaLoadOptions, type OutboundMediaAccess } from "../media/load-options.js";
 import { loadWebMedia } from "./web-media.js";
 
+/** Media loading policy used before plugin media is handed to channel delivery. */
 export type OutboundMediaLoadOptions = {
   /** Maximum allowed media payload size before the load is rejected. */
   maxBytes?: number;
diff --git a/src/plugin-sdk/provider-enable-config.ts b/src/plugin-sdk/provider-enable-config.ts
@@ -19,6 +19,7 @@ type ProviderEnableConfigCarrier = {
   };
 };
 
+/** Result of enabling a provider plugin while honoring plugin allow/deny policy. */
 export type PluginEnableResult<TConfig extends ProviderEnableConfigCarrier> = {
   /** Config object to persist after the enable attempt. Unchanged when policy blocks the plugin. */
   config: TConfig;
diff --git a/src/plugin-sdk/provider-web-search-contract-fields.ts b/src/plugin-sdk/provider-web-search-contract-fields.ts
@@ -11,6 +11,7 @@ import {
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { WebSearchProviderPlugin } from "../plugins/types.js";
 
+/** Credential storage mode advertised by a web-search-capable provider. */
 export type WebSearchProviderContractCredential =
   | { type: "none" }
   | { type: "top-level" }
diff --git a/src/plugin-sdk/run-command.ts b/src/plugin-sdk/run-command.ts
@@ -2,6 +2,7 @@
 import { formatErrorMessage } from "../infra/errors.js";
 import { runCommandWithTimeout } from "../process/exec.js";
 
+/** Captured process result returned by plugin command execution helpers. */
 export type PluginCommandRunResult = {
   /** Process exit code, with `1` used when the command failed before spawning or did not report one. */
   code: number;

Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@ function hasRawExplicitPort(raw: string): boolean {`
`15`	`15`	`return /:\d+$/.test(hostPort);`
`16`	`16`	`}`
`17`	`17`
	`18`	`+/** Parsed browser/CDP endpoint details with display-safe normalized URL variants. */`
`18`	`19`	`export type BrowserHttpUrlParseResult = {`
`19`	`20`	`/** Parsed URL object retained for callers that need protocol, host, path, or credentials. */`
`20`	`21`	`parsed: URL;`