mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-10 04:10:44 +00:00
954 lines
34 KiB
TypeScript
954 lines
34 KiB
TypeScript
import type { PluginCompatRecord } from "./types.js";
|
|
|
|
const CHANNEL_RUNTIME_SDK_SURFACE = ["openclaw/plugin-sdk/channel", "runtime"].join("-");
|
|
const LEGACY_CONFIG_MIGRATE_TEST_PATH = [
|
|
"src/commands/doctor/shared/legacy-config",
|
|
"migrate.test.ts",
|
|
].join("-");
|
|
|
|
export const PLUGIN_COMPAT_RECORDS = [
|
|
{
|
|
code: "legacy-before-agent-start",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-24",
|
|
warningStarts: "2026-04-24",
|
|
removeAfter: "2026-07-24",
|
|
replacement: "`before_model_resolve` and `before_prompt_build` hooks",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["plugin hooks", "plugins inspect", "status diagnostics"],
|
|
diagnostics: ["plugin compatibility notice"],
|
|
tests: ["src/plugins/status.test.ts", "src/plugins/contracts/shape.contract.test.ts"],
|
|
releaseNote:
|
|
"Legacy `before_agent_start` hook compatibility remains wired while plugins migrate to modern hook stages.",
|
|
},
|
|
{
|
|
code: "hook-only-plugin-shape",
|
|
status: "active",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
replacement: "explicit capability registration",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["plugin shape inspection", "plugins inspect", "status diagnostics"],
|
|
diagnostics: ["plugin compatibility notice"],
|
|
tests: ["src/plugins/status.test.ts", "src/plugins/contracts/shape.contract.test.ts"],
|
|
},
|
|
{
|
|
code: "legacy-root-sdk-import",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-24",
|
|
warningStarts: "2026-04-24",
|
|
removeAfter: "2026-07-24",
|
|
replacement: "focused `openclaw/plugin-sdk/<subpath>` imports",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["openclaw/plugin-sdk", "openclaw/plugin-sdk/compat"],
|
|
diagnostics: ["OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED"],
|
|
tests: [
|
|
"src/plugins/contracts/plugin-sdk-index.test.ts",
|
|
"src/plugins/contracts/plugin-sdk-root-alias.test.ts",
|
|
"src/plugins/contracts/plugin-sdk-subpaths.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "hook.before_tool_call.terminal-block-approval",
|
|
status: "active",
|
|
owner: "agent-runtime",
|
|
introduced: "2026-04-29",
|
|
docsPath: "/plugins/hooks",
|
|
surfaces: ["before_tool_call block result", "before_tool_call approval result"],
|
|
diagnostics: ["hook runner contract probe"],
|
|
tests: [
|
|
"src/plugins/hooks.security.test.ts",
|
|
"src/agents/pi-tools.before-tool-call.e2e.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "hook.llm-observer.privacy-payload",
|
|
status: "active",
|
|
owner: "agent-runtime",
|
|
introduced: "2026-04-29",
|
|
docsPath: "/plugins/hooks",
|
|
surfaces: ["llm_input", "llm_output", "agent_end", "allowConversationAccess"],
|
|
diagnostics: ["conversation access hook contract probe"],
|
|
tests: ["src/agents/cli-runner.reliability.test.ts", "src/config/schema.help.quality.test.ts"],
|
|
},
|
|
{
|
|
code: "api.capture.runtime-registrars",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-29",
|
|
docsPath: "/plugins/architecture-internals",
|
|
surfaces: [
|
|
"createCapturedPluginRegistration",
|
|
"capturePluginRegistration",
|
|
"OpenClawPluginApi",
|
|
],
|
|
diagnostics: ["runtime registration capture contract probe"],
|
|
tests: ["src/plugins/captured-registration.test.ts"],
|
|
},
|
|
{
|
|
code: "channel.runtime.envelope-config-metadata",
|
|
status: "active",
|
|
owner: "channel",
|
|
introduced: "2026-04-29",
|
|
docsPath: "/plugins/sdk-channel-plugins",
|
|
surfaces: ["api.registerChannel", "channel setup metadata", "channel message envelope"],
|
|
diagnostics: ["channel runtime contract probe"],
|
|
tests: [
|
|
"src/plugin-sdk/channel-entry-contract.test.ts",
|
|
"src/plugins/captured-registration.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "bundled-channel-sdk-compat-facades",
|
|
status: "active",
|
|
owner: "sdk",
|
|
introduced: "2026-04-28",
|
|
replacement:
|
|
"generic channel SDK subpaths or plugin-local `api.ts` / `runtime-api.ts` barrels for new plugins",
|
|
docsPath: "/plugins/sdk-overview",
|
|
surfaces: [
|
|
"openclaw/plugin-sdk/discord component message helpers",
|
|
"openclaw/plugin-sdk/telegram-account resolveTelegramAccount",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility registry"],
|
|
tests: [
|
|
"src/plugin-sdk/discord.test.ts",
|
|
"src/plugin-sdk/telegram-account.test.ts",
|
|
"src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "bundled-channel-config-schema-legacy",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-28",
|
|
deprecated: "2026-04-28",
|
|
warningStarts: "2026-04-28",
|
|
removeAfter: "2026-07-28",
|
|
replacement:
|
|
"`openclaw/plugin-sdk/bundled-channel-config-schema` for maintained bundled plugins; plugin-local schemas for third-party plugins",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["openclaw/plugin-sdk/channel-config-schema-legacy"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: [
|
|
"src/plugins/contracts/config-footprint-guardrails.test.ts",
|
|
"test/extension-test-boundary.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "plugin-sdk-testing-barrel",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-28",
|
|
deprecated: "2026-04-28",
|
|
warningStarts: "2026-04-28",
|
|
removeAfter: "2026-07-28",
|
|
replacement:
|
|
"focused `openclaw/plugin-sdk/*` test subpaths such as `plugin-test-runtime`, `channel-test-helpers`, `test-env`, and `test-fixtures`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["openclaw/plugin-sdk/testing"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: [
|
|
"src/plugins/compat/registry.test.ts",
|
|
"scripts/check-no-extension-test-core-imports.ts",
|
|
"test/extension-test-boundary.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "channel-route-key-aliases",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-28",
|
|
deprecated: "2026-04-28",
|
|
warningStarts: "2026-04-28",
|
|
removeAfter: "2026-07-28",
|
|
replacement: "`channelRouteDedupeKey` and `channelRouteCompactKey`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [
|
|
"openclaw/plugin-sdk/channel-route channelRouteIdentityKey",
|
|
"openclaw/plugin-sdk/channel-route channelRouteKey",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: [
|
|
"src/plugin-sdk/channel-route.test.ts",
|
|
"src/plugins/contracts/plugin-sdk-subpaths.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "channel-target-comparable-aliases",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-28",
|
|
deprecated: "2026-04-28",
|
|
warningStarts: "2026-04-28",
|
|
removeAfter: "2026-07-28",
|
|
replacement:
|
|
"`resolveRouteTargetForChannel`, `ChannelRouteParsedTarget`, `channelRouteTargetsMatchExact`, and `channelRouteTargetsShareConversation`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [
|
|
"src/channels/plugins/target-parsing ComparableChannelTarget",
|
|
"src/channels/plugins/target-parsing resolveComparableTargetForChannel",
|
|
"src/channels/plugins/target-parsing comparableChannelTargetsMatch",
|
|
"src/channels/plugins/target-parsing comparableChannelTargetsShareRoute",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: [
|
|
"src/channels/plugins/target-parsing.test.ts",
|
|
"src/plugins/contracts/plugin-sdk-subpaths.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "bundled-plugin-allowlist",
|
|
status: "active",
|
|
owner: "config",
|
|
introduced: "2026-04-24",
|
|
replacement: "manifest-owned plugin enablement and scoped load plans",
|
|
docsPath: "/plugins/architecture",
|
|
surfaces: ["plugins.allow", "bundled provider startup", "plugins status"],
|
|
diagnostics: ["plugin status report"],
|
|
tests: ["src/plugins/status.test.ts", "src/plugins/config-state.test.ts"],
|
|
},
|
|
{
|
|
code: "bundled-plugin-enablement",
|
|
status: "active",
|
|
owner: "config",
|
|
introduced: "2026-04-24",
|
|
replacement: "manifest-owned plugin defaults and scoped load plans",
|
|
docsPath: "/plugins/architecture",
|
|
surfaces: ["plugins.entries", "bundled provider startup", "plugins status"],
|
|
diagnostics: ["plugin status report"],
|
|
tests: ["src/plugins/status.test.ts", "src/plugins/config-state.test.ts"],
|
|
},
|
|
{
|
|
code: "bundled-plugin-vitest-defaults",
|
|
status: "active",
|
|
owner: "config",
|
|
introduced: "2026-04-24",
|
|
replacement: "explicit test plugin config fixtures",
|
|
docsPath: "/plugins/architecture",
|
|
surfaces: ["Vitest plugin defaults", "bundled provider tests"],
|
|
diagnostics: ["test-only compatibility path"],
|
|
tests: ["src/plugins/config-state.test.ts"],
|
|
},
|
|
{
|
|
code: "provider-auth-env-vars",
|
|
status: "deprecated",
|
|
owner: "setup",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-24",
|
|
warningStarts: "2026-04-24",
|
|
removeAfter: "2026-07-24",
|
|
replacement: "`setup.providers[].envVars` and `providerAuthChoices`",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["openclaw.plugin.json providerAuthEnvVars", "provider setup"],
|
|
diagnostics: ["manifest compatibility diagnostic"],
|
|
tests: ["src/plugins/setup-registry.test.ts", "src/plugins/provider-auth-choices.test.ts"],
|
|
},
|
|
{
|
|
code: "channel-env-vars",
|
|
status: "deprecated",
|
|
owner: "channel",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-24",
|
|
warningStarts: "2026-04-24",
|
|
removeAfter: "2026-07-24",
|
|
replacement: "`channelConfigs.<id>.schema` and setup descriptors",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["openclaw.plugin.json channelEnvVars", "channel setup"],
|
|
diagnostics: ["manifest compatibility diagnostic"],
|
|
tests: [
|
|
"src/plugins/setup-registry.test.ts",
|
|
"src/channels/plugins/setup-group-access.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "activation-agent-harness-hint",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-24",
|
|
replacement:
|
|
"top-level `cliBackends[]` for CLI aliases and future `agentRuntime` ownership metadata",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["activation.onAgentHarnesses", "activation planner"],
|
|
diagnostics: ["activation plan compat reason"],
|
|
tests: ["src/plugins/activation-planner.test.ts"],
|
|
},
|
|
{
|
|
code: "legacy-implicit-startup-sidecar",
|
|
status: "deprecated",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-28",
|
|
deprecated: "2026-04-28",
|
|
warningStarts: "2026-04-28",
|
|
removeAfter: "2026-07-28",
|
|
replacement:
|
|
"`activation.onStartup: true` for startup work or `activation.onStartup: false` for inert plugins",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["Gateway startup plugin planning", "openclaw.plugin.json activation"],
|
|
diagnostics: ["plugin compatibility notice"],
|
|
tests: ["src/plugins/channel-plugin-ids.test.ts", "src/plugins/installed-plugin-index.test.ts"],
|
|
},
|
|
{
|
|
code: "activation-provider-hint",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-24",
|
|
replacement: "`providers[]` manifest ownership",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["activation.onProviders", "activation planner"],
|
|
diagnostics: ["activation plan compat reason"],
|
|
tests: ["src/plugins/activation-planner.test.ts"],
|
|
},
|
|
{
|
|
code: "activation-channel-hint",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-24",
|
|
replacement: "`channels[]` manifest ownership",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["activation.onChannels", "activation planner"],
|
|
diagnostics: ["activation plan compat reason"],
|
|
tests: ["src/plugins/activation-planner.test.ts"],
|
|
},
|
|
{
|
|
code: "activation-command-hint",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-24",
|
|
replacement: "`commandAliases` or command contribution metadata",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["activation.onCommands", "activation planner"],
|
|
diagnostics: ["activation plan compat reason"],
|
|
tests: ["src/plugins/activation-planner.test.ts"],
|
|
},
|
|
{
|
|
code: "activation-route-hint",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-24",
|
|
replacement: "HTTP route contribution metadata",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["activation.onRoutes", "activation planner"],
|
|
diagnostics: ["activation plan compat reason"],
|
|
tests: ["src/plugins/activation-planner.test.ts"],
|
|
},
|
|
{
|
|
code: "activation-config-path-hint",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-27",
|
|
replacement: "manifest contribution ownership for root config surfaces",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["activation.onConfigPaths", "startup plugin selection"],
|
|
diagnostics: ["activation plan compat reason"],
|
|
tests: ["src/plugins/channel-plugin-ids.test.ts"],
|
|
},
|
|
{
|
|
code: "activation-capability-hint",
|
|
status: "active",
|
|
owner: "plugin-execution",
|
|
introduced: "2026-04-24",
|
|
replacement: "manifest contribution ownership",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["activation.onCapabilities", "activation planner"],
|
|
diagnostics: ["activation plan compat reason"],
|
|
tests: ["src/plugins/activation-planner.test.ts"],
|
|
},
|
|
{
|
|
code: "embedded-harness-config-alias",
|
|
status: "deprecated",
|
|
owner: "agent-runtime",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-25",
|
|
warningStarts: "2026-04-25",
|
|
removeAfter: "2026-07-25",
|
|
replacement: "`agentRuntime` config naming",
|
|
docsPath: "/plugins/sdk-agent-harness",
|
|
surfaces: ["agents.defaults.embeddedHarness", "model/provider runtime selection"],
|
|
diagnostics: ["agent runtime config compatibility"],
|
|
tests: [LEGACY_CONFIG_MIGRATE_TEST_PATH],
|
|
},
|
|
{
|
|
code: "agent-harness-sdk-alias",
|
|
status: "deprecated",
|
|
owner: "agent-runtime",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-25",
|
|
warningStarts: "2026-04-25",
|
|
removeAfter: "2026-07-25",
|
|
replacement: "`openclaw/plugin-sdk/agent-runtime`",
|
|
docsPath: "/plugins/sdk-agent-harness",
|
|
surfaces: ["openclaw/plugin-sdk/agent-harness", "openclaw/plugin-sdk/agent-harness-runtime"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-subpaths.test.ts"],
|
|
},
|
|
{
|
|
code: "agent-harness-id-alias",
|
|
status: "deprecated",
|
|
owner: "agent-runtime",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-25",
|
|
warningStarts: "2026-04-25",
|
|
removeAfter: "2026-07-25",
|
|
replacement: "`agentRuntime` ids and policy metadata",
|
|
docsPath: "/plugins/sdk-agent-harness",
|
|
surfaces: ["manifest/catalog execution policy", "runtime selection"],
|
|
diagnostics: ["agent runtime compatibility warning"],
|
|
tests: ["src/plugins/provider-runtime.test.ts", "src/web/provider-runtime-shared.test.ts"],
|
|
},
|
|
{
|
|
code: "generated-bundled-channel-config-fallback",
|
|
status: "active",
|
|
owner: "channel",
|
|
introduced: "2026-04-24",
|
|
replacement: "manifest registry `channelConfigs` metadata",
|
|
docsPath: "/plugins/manifest",
|
|
surfaces: ["generated bundled channel config metadata", "channel config validation"],
|
|
diagnostics: ["channel config metadata fallback"],
|
|
tests: ["src/plugins/contracts/config-footprint-guardrails.test.ts"],
|
|
},
|
|
{
|
|
code: "disable-persisted-plugin-registry-env",
|
|
status: "deprecated",
|
|
owner: "config",
|
|
introduced: "2026-04-25",
|
|
deprecated: "2026-04-25",
|
|
warningStarts: "2026-04-25",
|
|
removeAfter: "2026-07-25",
|
|
replacement: "`openclaw plugins registry --refresh` and `openclaw doctor --fix`",
|
|
docsPath: "/cli/plugins#registry",
|
|
surfaces: ["OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY", "plugin registry reads"],
|
|
diagnostics: ["persisted-registry-disabled"],
|
|
tests: ["src/plugins/plugin-registry.test.ts"],
|
|
},
|
|
{
|
|
code: "plugin-registry-install-migration-env",
|
|
status: "deprecated",
|
|
owner: "config",
|
|
introduced: "2026-04-25",
|
|
deprecated: "2026-04-25",
|
|
warningStarts: "2026-04-25",
|
|
removeAfter: "2026-07-25",
|
|
replacement: "`openclaw plugins registry --refresh` and `openclaw doctor --fix`",
|
|
docsPath: "/cli/plugins#registry",
|
|
surfaces: [
|
|
"OPENCLAW_DISABLE_PLUGIN_REGISTRY_MIGRATION",
|
|
"OPENCLAW_FORCE_PLUGIN_REGISTRY_MIGRATION",
|
|
"package postinstall plugin registry migration",
|
|
],
|
|
diagnostics: ["postinstall migration skip", "postinstall migration force deprecation warning"],
|
|
tests: ["src/commands/doctor/shared/plugin-registry-migration.test.ts"],
|
|
},
|
|
{
|
|
code: "plugin-install-config-ledger",
|
|
status: "deprecated",
|
|
owner: "config",
|
|
introduced: "2026-04-25",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "state-managed `plugins/installs.json` install ledger",
|
|
docsPath: "/cli/plugins#registry",
|
|
surfaces: ["plugins.installs authored config", "plugin install/update migration"],
|
|
diagnostics: ["config write migration warning", "doctor registry migration"],
|
|
tests: [
|
|
"src/config/io.write-config.test.ts",
|
|
"src/commands/doctor/shared/plugin-registry-migration.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "bundled-plugin-load-path-aliases",
|
|
status: "deprecated",
|
|
owner: "config",
|
|
introduced: "2026-04-25",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "packaged bundled plugins resolved through the persisted plugin registry",
|
|
docsPath: "/cli/plugins#registry",
|
|
surfaces: ["plugins.load.paths entries pointing at bundled plugin source/dist paths"],
|
|
diagnostics: ["doctor bundled plugin load-path warning"],
|
|
tests: ["src/commands/doctor/shared/bundled-plugin-load-paths.test.ts"],
|
|
},
|
|
{
|
|
code: "plugin-owned-web-search-config",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-26",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`plugins.entries.<plugin>.config.webSearch`",
|
|
docsPath: "/tools/web",
|
|
surfaces: ["tools.web.search.apiKey", "tools.web.search.<provider>"],
|
|
diagnostics: ["doctor legacy web-search config migration"],
|
|
tests: ["src/commands/doctor/shared/legacy-web-search-migrate.test.ts"],
|
|
},
|
|
{
|
|
code: "plugin-owned-web-fetch-config",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-26",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`plugins.entries.firecrawl.config.webFetch`",
|
|
docsPath: "/tools/web-fetch",
|
|
surfaces: ["tools.web.fetch.firecrawl"],
|
|
diagnostics: ["doctor legacy web-fetch config migration"],
|
|
tests: ["src/commands/doctor/shared/legacy-web-fetch-migrate.test.ts"],
|
|
},
|
|
{
|
|
code: "plugin-owned-x-search-config",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-26",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`plugins.entries.xai.config.webSearch.apiKey`",
|
|
docsPath: "/tools/grok-search",
|
|
surfaces: ["tools.web.x_search.apiKey"],
|
|
diagnostics: ["doctor legacy x_search config migration"],
|
|
tests: [
|
|
"src/commands/doctor/shared/legacy-x-search-migrate.test.ts",
|
|
LEGACY_CONFIG_MIGRATE_TEST_PATH,
|
|
],
|
|
},
|
|
{
|
|
code: "plugin-activate-entrypoint-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`register(api)` plugin entrypoint",
|
|
docsPath: "/plugins/sdk-entrypoints",
|
|
surfaces: ["plugin module `activate(api)`", "plugin loader registration"],
|
|
diagnostics: ["loader compatibility path"],
|
|
tests: ["src/plugins/loader.test.ts"],
|
|
},
|
|
{
|
|
code: "setup-runtime-fallback",
|
|
status: "active",
|
|
owner: "setup",
|
|
introduced: "2026-04-24",
|
|
replacement: "`setup.requiresRuntime: false` with complete setup descriptors",
|
|
docsPath: "/plugins/manifest#setup-reference",
|
|
surfaces: ["setup-api runtime fallback", "setup.requiresRuntime omitted"],
|
|
diagnostics: ["setup registry runtime diagnostic"],
|
|
tests: ["src/plugins/setup-registry.test.ts", "src/plugins/setup-registry.runtime.test.ts"],
|
|
},
|
|
{
|
|
code: "provider-discovery-hook-alias",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`catalog.run(...)` provider catalog hook",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["provider plugin `discovery` hook", "provider catalog resolution"],
|
|
diagnostics: ["provider validation warning when catalog and discovery both register"],
|
|
tests: ["src/plugins/provider-discovery.test.ts", "src/plugins/provider-validation.test.ts"],
|
|
},
|
|
{
|
|
code: "channel-exposure-legacy-aliases",
|
|
status: "deprecated",
|
|
owner: "channel",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`openclaw.channel.exposure` metadata",
|
|
docsPath: "/plugins/sdk-setup",
|
|
surfaces: ["openclaw.channel.showConfigured", "openclaw.channel.showInSetup"],
|
|
diagnostics: ["channel exposure compatibility path"],
|
|
tests: ["src/commands/channel-setup/discovery.test.ts"],
|
|
},
|
|
{
|
|
code: "channel-runtime-sdk-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement:
|
|
"focused channel SDK subpaths, especially `openclaw/plugin-sdk/channel-runtime-context`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [CHANNEL_RUNTIME_SDK_SURFACE],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-subpaths.test.ts"],
|
|
},
|
|
{
|
|
code: "command-auth-status-builders",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`openclaw/plugin-sdk/command-status`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [
|
|
"openclaw/plugin-sdk/command-auth buildCommandsMessage",
|
|
"openclaw/plugin-sdk/command-auth buildCommandsMessagePaginated",
|
|
"openclaw/plugin-sdk/command-auth buildHelpMessage",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugin-sdk/command-auth.test.ts"],
|
|
},
|
|
{
|
|
code: "clawdbot-config-type-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`OpenClawConfig`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["openclaw/plugin-sdk `ClawdbotConfig` type export"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-index.test.ts"],
|
|
},
|
|
{
|
|
code: "openclaw-schema-type-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-26",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`OpenClawConfig` from `openclaw/plugin-sdk/config-schema`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["openclaw/plugin-sdk `OpenClawSchemaType` type export"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-index.test.ts"],
|
|
},
|
|
{
|
|
code: "legacy-extension-api-import",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement:
|
|
"injected `api.runtime.*` helpers or focused `openclaw/plugin-sdk/<subpath>` imports",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["openclaw/extension-api"],
|
|
diagnostics: ["OPENCLAW_EXTENSION_API_DEPRECATED"],
|
|
tests: ["src/plugins/sdk-alias.test.ts", "src/index.test.ts"],
|
|
},
|
|
{
|
|
code: "memory-split-registration",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`api.registerMemoryCapability({ promptBuilder, flushPlanResolver, runtime })`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [
|
|
"api.registerMemoryPromptSection",
|
|
"api.registerMemoryFlushPlan",
|
|
"api.registerMemoryRuntime",
|
|
"src/plugins/memory-state split registration helpers",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/memory-state.test.ts", "src/plugins/loader.test.ts"],
|
|
},
|
|
{
|
|
code: "provider-static-capabilities-bag",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement:
|
|
"explicit provider hooks such as `buildReplayPolicy`, `normalizeToolSchemas`, and `wrapStreamFn`",
|
|
docsPath: "/plugins/sdk-provider-plugins",
|
|
surfaces: ["ProviderPlugin.capabilities", "ProviderCapabilities"],
|
|
diagnostics: ["provider validation warning"],
|
|
tests: [
|
|
"src/plugins/provider-runtime.test.ts",
|
|
"src/plugins/contracts/provider-family-plugin-tests.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "provider-discovery-type-aliases",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement:
|
|
"`ProviderCatalogOrder`, `ProviderCatalogContext`, `ProviderCatalogResult`, and `ProviderPluginCatalog`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [
|
|
"ProviderDiscoveryOrder",
|
|
"ProviderDiscoveryContext",
|
|
"ProviderDiscoveryResult",
|
|
"ProviderPluginDiscovery",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-index.test.ts"],
|
|
},
|
|
{
|
|
code: "provider-thinking-policy-hooks",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`resolveThinkingProfile`",
|
|
docsPath: "/plugins/sdk-provider-plugins",
|
|
surfaces: [
|
|
"ProviderPlugin.isBinaryThinking",
|
|
"ProviderPlugin.supportsXHighThinking",
|
|
"ProviderPlugin.resolveDefaultThinkingLevel",
|
|
],
|
|
diagnostics: ["provider runtime compatibility warning"],
|
|
tests: ["src/plugins/provider-runtime.test.ts"],
|
|
},
|
|
{
|
|
code: "provider-external-oauth-profiles-hook",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`contracts.externalAuthProviders` plus `resolveExternalAuthProfiles`",
|
|
docsPath: "/plugins/sdk-provider-plugins",
|
|
surfaces: ["ProviderPlugin.resolveExternalOAuthProfiles"],
|
|
diagnostics: ["provider external auth fallback warning"],
|
|
tests: ["src/plugins/provider-runtime.test.ts"],
|
|
},
|
|
{
|
|
code: "agent-tool-result-harness-alias",
|
|
status: "deprecated",
|
|
owner: "agent-runtime",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`runtime` and `runtimes` agent tool-result middleware fields",
|
|
docsPath: "/plugins/sdk-agent-harness",
|
|
surfaces: [
|
|
"AgentToolResultMiddlewareHarness",
|
|
"AgentToolResultMiddlewareContext.harness",
|
|
"AgentToolResultMiddlewareOptions.harnesses",
|
|
"normalizeAgentToolResultMiddlewareHarnesses",
|
|
],
|
|
diagnostics: ["agent runtime compatibility warning"],
|
|
tests: [
|
|
"src/plugins/captured-registration.test.ts",
|
|
"src/agents/codex-app-server.extensions.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "runtime-config-load-write",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-27",
|
|
deprecated: "2026-04-27",
|
|
warningStarts: "2026-04-27",
|
|
removeAfter: "2026-07-27",
|
|
replacement:
|
|
"`api.runtime.config.current()`, passed config values, `mutateConfigFile(...)`, or `replaceConfigFile(...)`",
|
|
docsPath: "/plugins/sdk-runtime#config-loading-and-writes",
|
|
surfaces: ["api.runtime.config.loadConfig", "api.runtime.config.writeConfigFile"],
|
|
diagnostics: [
|
|
"plugin runtime compatibility warning",
|
|
"deprecated internal config API guard",
|
|
"runtime channel config boundary guard",
|
|
],
|
|
tests: [
|
|
"src/plugins/runtime/runtime-config.test.ts",
|
|
"src/plugins/contracts/deprecated-internal-config-api.test.ts",
|
|
"src/plugins/contracts/config-boundary-guard.test.ts",
|
|
],
|
|
},
|
|
{
|
|
code: "runtime-taskflow-legacy-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement:
|
|
"`api.runtime.tasks.managedFlows` for managed mutations or `api.runtime.tasks.flows` for DTO reads",
|
|
docsPath: "/plugins/sdk-runtime",
|
|
surfaces: ["api.runtime.taskFlow", "api.runtime.tasks.flow"],
|
|
diagnostics: ["plugin runtime compatibility warning"],
|
|
tests: ["src/plugins/runtime/index.test.ts", "src/plugins/runtime/runtime-tasks.test.ts"],
|
|
},
|
|
{
|
|
code: "runtime-subagent-get-session-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`api.runtime.subagent.getSessionMessages`",
|
|
docsPath: "/plugins/sdk-runtime",
|
|
surfaces: ["api.runtime.subagent.getSession"],
|
|
diagnostics: ["plugin runtime compatibility warning"],
|
|
tests: ["src/plugins/runtime/index.test.ts"],
|
|
},
|
|
{
|
|
code: "runtime-stt-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`api.runtime.mediaUnderstanding.transcribeAudioFile`",
|
|
docsPath: "/plugins/sdk-runtime",
|
|
surfaces: ["api.runtime.stt.transcribeAudioFile"],
|
|
diagnostics: ["plugin runtime compatibility warning"],
|
|
tests: ["src/plugins/runtime/index.test.ts"],
|
|
},
|
|
{
|
|
code: "runtime-inbound-envelope-alias",
|
|
status: "deprecated",
|
|
owner: "channel",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`BodyForAgent` plus structured user-context blocks",
|
|
docsPath: "/plugins/sdk-runtime",
|
|
surfaces: ["api.runtime.channel.reply.formatInboundEnvelope"],
|
|
diagnostics: ["channel runtime compatibility warning"],
|
|
tests: ["src/plugins/runtime/index.test.ts"],
|
|
},
|
|
{
|
|
code: "channel-native-message-schema-helpers",
|
|
status: "deprecated",
|
|
owner: "channel",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "semantic `presentation` capabilities",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [
|
|
"openclaw/plugin-sdk/channel-actions createMessageToolButtonsSchema",
|
|
"openclaw/plugin-sdk/channel-actions createMessageToolCardSchema",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-subpaths.test.ts"],
|
|
},
|
|
{
|
|
code: "channel-mention-gating-legacy-helpers",
|
|
status: "deprecated",
|
|
owner: "channel",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "`resolveInboundMentionDecision({ facts, policy })`",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: [
|
|
"openclaw/plugin-sdk/channel-inbound resolveMentionGating",
|
|
"openclaw/plugin-sdk/channel-inbound resolveMentionGatingWithBypass",
|
|
"openclaw/plugin-sdk/channel-mention-gating resolveMentionGating",
|
|
"openclaw/plugin-sdk/channel-mention-gating resolveMentionGatingWithBypass",
|
|
],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-subpaths.test.ts"],
|
|
},
|
|
{
|
|
code: "provider-web-search-core-wrapper",
|
|
status: "deprecated",
|
|
owner: "provider",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "provider-owned `createTool(...)` on the returned `WebSearchProviderPlugin`",
|
|
docsPath: "/plugins/sdk-provider-plugins",
|
|
surfaces: ["openclaw/plugin-sdk/provider-web-search createPluginBackedWebSearchProvider"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugins/contracts/plugin-sdk-subpaths.test.ts"],
|
|
},
|
|
{
|
|
code: "approval-capability-approvals-alias",
|
|
status: "deprecated",
|
|
owner: "channel",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement:
|
|
"top-level `delivery`, `nativeRuntime`, `render`, and `native` approval capability fields",
|
|
docsPath: "/plugins/sdk-channel-plugins",
|
|
surfaces: ["createChannelApprovalCapability({ approvals })"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: ["src/plugin-sdk/approval-delivery-helpers.test.ts"],
|
|
},
|
|
{
|
|
code: "plugin-sdk-test-utils-alias",
|
|
status: "deprecated",
|
|
owner: "sdk",
|
|
introduced: "2026-04-24",
|
|
deprecated: "2026-04-26",
|
|
warningStarts: "2026-04-26",
|
|
removeAfter: "2026-07-26",
|
|
replacement: "focused `openclaw/plugin-sdk/*` test subpaths",
|
|
docsPath: "/plugins/sdk-migration",
|
|
surfaces: ["openclaw/plugin-sdk/test-utils"],
|
|
diagnostics: ["plugin SDK compatibility warning"],
|
|
tests: [
|
|
"src/plugins/compat/registry.test.ts",
|
|
"src/plugins/contracts/plugin-sdk-subpaths.test.ts",
|
|
],
|
|
},
|
|
] as const satisfies readonly PluginCompatRecord[];
|
|
|
|
export type PluginCompatCode = (typeof PLUGIN_COMPAT_RECORDS)[number]["code"];
|
|
export type KnownPluginCompatRecord = PluginCompatRecord<PluginCompatCode>;
|
|
|
|
const pluginCompatRecordByCode = new Map<PluginCompatCode, KnownPluginCompatRecord>(
|
|
PLUGIN_COMPAT_RECORDS.map((record) => [record.code, record]),
|
|
);
|
|
|
|
export function listPluginCompatRecords(): readonly KnownPluginCompatRecord[] {
|
|
return PLUGIN_COMPAT_RECORDS;
|
|
}
|
|
|
|
export function getPluginCompatRecord(code: PluginCompatCode): KnownPluginCompatRecord {
|
|
const record = pluginCompatRecordByCode.get(code);
|
|
if (!record) {
|
|
throw new Error(`Unknown plugin compatibility code: ${code}`);
|
|
}
|
|
return record;
|
|
}
|
|
|
|
export function isPluginCompatCode(code: string): code is PluginCompatCode {
|
|
return pluginCompatRecordByCode.has(code as PluginCompatCode);
|
|
}
|
|
|
|
export function listDeprecatedPluginCompatRecords(): readonly KnownPluginCompatRecord[] {
|
|
return PLUGIN_COMPAT_RECORDS.filter((record) =>
|
|
(["deprecated", "removal-pending"] as readonly string[]).includes(record.status),
|
|
);
|
|
}
|