From ff8b7145d714e04336d43e20df580b73f990d300 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Fri, 24 Apr 2026 13:03:55 -0700 Subject: [PATCH] docs(plugins): catalog active deprecations in sdk-migration and cross-link from hooks --- docs/plugins/hooks.md | 22 ++++ docs/plugins/sdk-migration.md | 217 ++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+) diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md index a8cfe86e0b5..48a9aaa8a54 100644 --- a/docs/plugins/hooks.md +++ b/docs/plugins/hooks.md @@ -223,8 +223,30 @@ resources. Do not rely on the internal `gateway:startup` hook for plugin-owned runtime services. +## Upcoming deprecations + +A few hook-adjacent surfaces are deprecated but still supported. Migrate +before the next major release: + +- **Plaintext channel envelopes** in `inbound_claim` and `message_received` + handlers. Read `BodyForAgent` and the structured user-context blocks + instead of parsing flat envelope text. See + [Plaintext channel envelopes → BodyForAgent](/plugins/sdk-migration#active-deprecations). +- **`before_agent_start`** remains for compatibility. New plugins should use + `before_model_resolve` and `before_prompt_build` instead of the combined + phase. +- **`onResolution` in `before_tool_call`** now uses the typed + `PluginApprovalResolution` union (`allow-once` / `allow-always` / `deny` / + `timeout` / `cancelled`) instead of a free-form `string`. + +For the full list — memory capability registration, provider thinking +profile, external auth providers, provider discovery types, task runtime +accessors, and the `command-auth` → `command-status` rename — see +[Plugin SDK migration → Active deprecations](/plugins/sdk-migration#active-deprecations). + ## Related +- [Plugin SDK migration](/plugins/sdk-migration) — active deprecations and removal timeline - [Building plugins](/plugins/building-plugins) - [Plugin SDK overview](/plugins/sdk-overview) - [Plugin entry points](/plugins/sdk-entrypoints) diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md index 36eb486e33a..97800589d11 100644 --- a/docs/plugins/sdk-migration.md +++ b/docs/plugins/sdk-migration.md @@ -432,6 +432,223 @@ surface `DEFAULT_COPILOT_API_BASE_URL`, Use the narrowest import that matches the job. If you cannot find an export, check the source at `src/plugin-sdk/` or ask in Discord. +## Active deprecations + +Narrower deprecations that apply across the plugin SDK, provider contract, +runtime surface, and manifest. Each one still works today but will be removed +in a future major release. The entry below every item maps the old API to its +canonical replacement. + + + + **Old (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`, + `buildCommandsMessagePaginated`, `buildHelpMessage`. + + **New (`openclaw/plugin-sdk/command-status`)**: same signatures, same + exports — just imported from the narrower subpath. `command-auth` + re-exports them as compat stubs. + + ```typescript + // Before + import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; + + // After + import { buildHelpMessage } from "openclaw/plugin-sdk/command-status"; + ``` + + + + + **Old**: `resolveInboundMentionRequirement({ facts, policy })` and + `shouldDropInboundForMention(...)` from + `openclaw/plugin-sdk/channel-inbound` or + `openclaw/plugin-sdk/channel-mention-gating`. + + **New**: `resolveInboundMentionDecision({ facts, policy })` — returns a + single decision object instead of two split calls. + + Downstream channel plugins (Slack, Discord, Matrix, MS Teams) have already + switched. + + + + + `openclaw/plugin-sdk/channel-runtime` is a compatibility shim for older + channel plugins. Do not import it from new code; use + `openclaw/plugin-sdk/channel-runtime-context` for registering runtime + objects. + + `channelActions*` helpers in `openclaw/plugin-sdk/channel-actions` are + deprecated alongside raw "actions" channel exports. Expose capabilities + through the semantic `presentation` surface instead — channel plugins + declare what they render (cards, buttons, selects) rather than which raw + action names they accept. + + + + + **Old**: `tool()` factory from `openclaw/plugin-sdk/provider-web-search`. + + **New**: implement `createTool(...)` directly on the provider plugin. + OpenClaw no longer needs the SDK helper to register the tool wrapper. + + + + + **Old**: `formatInboundEnvelope(...)` (and + `ChannelMessageForAgent.channelEnvelope`) to build a flat plaintext prompt + envelope from inbound channel messages. + + **New**: `BodyForAgent` plus structured user-context blocks. Channel + plugins attach routing metadata (thread, topic, reply-to, reactions) as + typed fields instead of concatenating them into a prompt string. The + `formatAgentEnvelope(...)` helper is still supported for synthesized + assistant-facing envelopes, but inbound plaintext envelopes are on the + way out. + + Affected areas: `inbound_claim`, `message_received`, and any custom + channel plugin that post-processed `channelEnvelope` text. + + + + + Four discovery type aliases are now thin wrappers over the + catalog-era types: + + | Old alias | New type | + | ------------------------- | ------------------------- | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext`| `ProviderCatalogContext` | + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + + Plus the legacy `ProviderCapabilities` static bag — provider plugins + should attach capability facts through the provider runtime contract + rather than a static object. + + + + + **Old** (three separate hooks on `ProviderThinkingPolicy`): + `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)`, and + `resolveDefaultThinkingLevel(ctx)`. + + **New**: a single `resolveThinkingProfile(ctx)` that returns a + `ProviderThinkingProfile` with the canonical `id`, optional `label`, and + ranked level list. OpenClaw downgrades stale stored values by profile + rank automatically. + + Implement one hook instead of three. The legacy hooks keep working during + the deprecation window but are not composed with the profile result. + + + + + **Old**: implementing `resolveExternalOAuthProfiles(...)` without + declaring the provider in the plugin manifest. + + **New**: declare `contracts.externalAuthProviders` in the plugin manifest + **and** implement `resolveExternalAuthProfiles(...)`. The old "auth + fallback" path emits a warning at runtime and will be removed. + + ```json + { + "contracts": { + "externalAuthProviders": ["anthropic", "openai"] + } + } + ``` + + + + + **Old** manifest field: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`. + + **New**: mirror the same env-var lookup into `setup.providers[].envVars` + on the manifest. This consolidates setup/status env metadata in one + place and avoids booting the plugin runtime just to answer env-var + lookups. + + `providerAuthEnvVars` remains supported through a compatibility adapter + until the deprecation window closes. + + + + + **Old**: three separate calls — + `api.registerMemoryPromptSection(...)`, + `api.registerMemoryFlushPlan(...)`, + `api.registerMemoryRuntime(...)`. + + **New**: one call on the memory-state API — + `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`. + + Same slots, single registration call. Additive memory helpers + (`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, + `registerMemoryEmbeddingProvider`) are not affected. + + + + + Two legacy type aliases still exported from `src/plugins/runtime/types.ts`: + + | Old | New | + | ----------------------------- | ------------------------------- | + | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | + | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | + + The runtime method `readSession` is deprecated in favor of + `getSessionMessages`. Same signature; the old method calls through to the + new one. + + + + + **Old**: `runtime.tasks.flow` (singular) returned a live task-flow accessor. + + **New**: `runtime.tasks.flows` (plural) returns DTO-based TaskFlow access, + which is import-safe and does not require the full task runtime to be + loaded. + + ```typescript + // Before + const flow = api.runtime.tasks.flow(ctx); + // After + const flows = api.runtime.tasks.flows(ctx); + ``` + + + + + Covered in "How to migrate → Migrate Pi tool-result extensions to + middleware" above. Included here for completeness: the Pi-only + `api.registerEmbeddedExtensionFactory(...)` path is deprecated in favor of + `api.registerAgentToolResultMiddleware(...)` with an explicit harness + list in `contracts.agentToolResultMiddleware`. + + + + `OpenClawSchemaType` re-exported from `openclaw/plugin-sdk` is now a + one-line alias for `OpenClawConfig`. Prefer the canonical name. + + ```typescript + // Before + import type { OpenClawSchemaType } from "openclaw/plugin-sdk"; + // After + import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema"; + ``` + + + + + +Extension-level deprecations (inside bundled channel/provider plugins under +`extensions/`) are tracked inside their own `api.ts` and `runtime-api.ts` +barrels. They do not affect third-party plugin contracts and are not listed +here. If you consume a bundled plugin's local barrel directly, read the +deprecation comments in that barrel before upgrading. + + ## Removal timeline | When | What happens |