refactor(plugin-sdk): expose prepared runtime helper surfaces

mcaxtr · mcaxtr · commit 95d73431ddc3 · 2026-05-07T10:06:20.000-03:00
diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -1,2 +1,2 @@
-25d5e7d7532d99d06187813e1cf75d3192fb2bf330862bfd1d4d4a50c91c77c9  plugin-sdk-api-baseline.json
-9f9758f36694c4004ab8c2fb772815c91cc2035de872a0e53f053537b2156910  plugin-sdk-api-baseline.jsonl
+28e280d21693216c99cfa8da553589b41741d37c0ada956e316ee01d3d6c202c  plugin-sdk-api-baseline.json
+633dae33da97f6a073c5561709c57d5c0b7ff67af0512d0261f05455c24b38de  plugin-sdk-api-baseline.jsonl
diff --git a/scripts/lib/plugin-sdk-doc-metadata.ts b/scripts/lib/plugin-sdk-doc-metadata.ts
@@ -101,6 +101,15 @@ export const pluginSdkDocMetadata = {
   "runtime-store": {
     category: "runtime",
   },
+  "agent-runtime": {
+    category: "runtime",
+  },
+  "speech-core": {
+    category: "provider",
+  },
+  "tts-runtime": {
+    category: "runtime",
+  },
   "allow-from": {
     category: "utilities",
   },
diff --git a/src/plugin-sdk/agent-runtime.ts b/src/plugin-sdk/agent-runtime.ts
@@ -10,6 +10,7 @@ export * from "../agents/identity.js";
 export * from "../agents/model-auth-markers.js";
 export * from "../agents/model-auth.js";
 export * from "../agents/model-catalog.js";
+export * from "../agents/model-catalog-scope.js";
 export * from "../agents/model-selection.js";
 export * from "../agents/simple-completion-runtime.js";
 export * from "../agents/pi-embedded-block-chunker.js";
diff --git a/src/plugin-sdk/channel-entry-contract.ts b/src/plugin-sdk/channel-entry-contract.ts
@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { emptyChannelConfigSchema } from "../channels/plugins/config-schema.js";
+import type { ChannelOutboundAdapter } from "../channels/plugins/types.adapters.js";
 import type { ChannelConfigSchema } from "../channels/plugins/types.config.js";
 import type { ChannelLegacyStateMigrationPlan } from "../channels/plugins/types.core.js";
 import type { ChannelPlugin } from "../channels/plugins/types.plugin.js";
@@ -52,6 +53,7 @@ type DefineBundledChannelEntryOptions<TPlugin = ChannelPlugin> = {
   description: string;
   importMetaUrl: string;
   plugin: BundledEntryModuleRef;
+  outbound?: BundledEntryModuleRef;
   secrets?: BundledEntryModuleRef;
   configSchema?: ChannelEntryConfigSchema<TPlugin> | (() => ChannelEntryConfigSchema<TPlugin>);
   runtime?: BundledEntryModuleRef;
@@ -108,6 +110,9 @@ export type BundledChannelEntryContract<TPlugin = ChannelPlugin> = {
   features?: BundledChannelEntryFeatures;
   register: (api: OpenClawPluginApi) => void;
   loadChannelPlugin: (options?: BundledEntryModuleLoadOptions) => TPlugin;
+  loadChannelOutbound?: (
+    options?: BundledEntryModuleLoadOptions,
+  ) => ChannelOutboundAdapter | undefined;
   loadChannelSecrets?: (
     options?: BundledEntryModuleLoadOptions,
   ) => ChannelPlugin["secrets"] | undefined;
@@ -435,6 +440,7 @@ export function defineBundledChannelEntry<TPlugin = ChannelPlugin>({
   description,
   importMetaUrl,
   plugin,
+  outbound,
   secrets,
   configSchema,
   runtime,
@@ -449,6 +455,14 @@ export function defineBundledChannelEntry<TPlugin = ChannelPlugin>({
       : ((configSchema ?? emptyChannelConfigSchema()) as ChannelEntryConfigSchema<TPlugin>);
   const loadChannelPlugin = (options?: BundledEntryModuleLoadOptions) =>
     loadBundledEntryExportSync<TPlugin>(importMetaUrl, plugin, options);
+  const loadChannelOutbound = outbound
+    ? (options?: BundledEntryModuleLoadOptions) =>
+        loadBundledEntryExportSync<ChannelOutboundAdapter | undefined>(
+          importMetaUrl,
+          outbound,
+          options,
+        )
+    : undefined;
   const loadChannelSecrets = secrets
     ? (options?: BundledEntryModuleLoadOptions) =>
         loadBundledEntryExportSync<ChannelPlugin["secrets"] | undefined>(
@@ -511,6 +525,7 @@ export function defineBundledChannelEntry<TPlugin = ChannelPlugin>({
       profile("bundled-register:registerFull", () => registerFull?.(api));
     },
     loadChannelPlugin,
+    ...(loadChannelOutbound ? { loadChannelOutbound } : {}),
     ...(loadChannelSecrets ? { loadChannelSecrets } : {}),
     ...(loadChannelAccountInspector ? { loadChannelAccountInspector } : {}),
     ...(setChannelRuntime ? { setChannelRuntime } : {}),
diff --git a/src/plugin-sdk/speech-core.ts b/src/plugin-sdk/speech-core.ts
@@ -37,6 +37,7 @@ export { parseTtsDirectives } from "../tts/directives.js";
 export {
   canonicalizeSpeechProviderId,
   getSpeechProvider,
+  listLoadedSpeechProviders,
   listSpeechProviders,
   normalizeSpeechProviderId,
 } from "../tts/provider-registry.js";
diff --git a/src/plugin-sdk/tts-runtime.ts b/src/plugin-sdk/tts-runtime.ts
@@ -33,6 +33,10 @@ function loadFacadeModule(): FacadeModule {
   });
 }
 
+export function prewarmTtsRuntimeFacade(): void {
+  loadFacadeModule();
+}
+
 export const _test: FacadeModule["_test"] = createLazyFacadeObjectValue(
   () => loadFacadeModule()._test,
 );
diff --git a/src/tts/provider-registry.ts b/src/tts/provider-registry.ts
@@ -1,4 +1,5 @@
 import type { OpenClawConfig } from "../config/types.js";
+import { getActiveRuntimePluginRegistry } from "../plugins/active-runtime-registry.js";
 import {
   resolvePluginCapabilityProvider,
   resolvePluginCapabilityProviders,
@@ -17,6 +18,10 @@ function resolveSpeechProviderPluginEntries(cfg?: OpenClawConfig): SpeechProvide
   });
 }
 
+function resolveLoadedSpeechProviderPluginEntries(): SpeechProviderPlugin[] {
+  return (getActiveRuntimePluginRegistry()?.speechProviders ?? []).map((entry) => entry.provider);
+}
+
 const defaultSpeechProviderRegistryResolver: SpeechProviderRegistryResolver = {
   getProvider: (providerId, cfg) =>
     resolvePluginCapabilityProvider({
@@ -31,7 +36,19 @@ const defaultSpeechProviderRegistry = createSpeechProviderRegistry(
   defaultSpeechProviderRegistryResolver,
 );
 
+const loadedSpeechProviderRegistry = createSpeechProviderRegistry({
+  getProvider: (providerId) =>
+    resolveLoadedSpeechProviderPluginEntries().find((provider) => {
+      if (provider.id === providerId) {
+        return true;
+      }
+      return provider.aliases?.includes(providerId) ?? false;
+    }),
+  listProviders: () => resolveLoadedSpeechProviderPluginEntries(),
+});
+
 export const listSpeechProviders = defaultSpeechProviderRegistry.listSpeechProviders;
+export const listLoadedSpeechProviders = loadedSpeechProviderRegistry.listSpeechProviders;
 export const getSpeechProvider = defaultSpeechProviderRegistry.getSpeechProvider;
 export const canonicalizeSpeechProviderId =
   defaultSpeechProviderRegistry.canonicalizeSpeechProviderId;
