mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 06:30:42 +00:00
docs(plugins): catalog active deprecations in sdk-migration and cross-link from hooks
This commit is contained in:
Vincent Koc
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="command-auth help builders → command-status">
|
||||
**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";
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Mention gating helpers → resolveInboundMentionDecision">
|
||||
**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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Channel runtime shim and channel actions helpers">
|
||||
`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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Web search provider tool() helper → createTool() on the plugin">
|
||||
**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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Plaintext channel envelopes → BodyForAgent">
|
||||
**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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Provider discovery types → provider catalog types">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Thinking policy hooks → resolveThinkingProfile">
|
||||
**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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="External OAuth provider fallback → contracts.externalAuthProviders">
|
||||
**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"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Provider env-var lookup → setup.providers[].envVars">
|
||||
**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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory plugin registration → registerMemoryCapability">
|
||||
**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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subagent session messages types renamed">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="runtime.tasks.flow → runtime.tasks.flows">
|
||||
**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);
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Embedded extension factories → agent tool-result middleware">
|
||||
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`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OpenClawSchemaType alias → OpenClawConfig">
|
||||
`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";
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Removal timeline
|
||||
|
||||
| When | What happens |
|
||||
|
||||
Reference in New Issue
Block a user