durar-ai 2026.4.4

package/docs/plugins/sdk-entrypoints.md

@@ -0,0 +1,210 @@
+---
+title: "Plugin Entry Points"
+sidebarTitle: "Entry Points"
+summary: "Reference for definePluginEntry, defineChannelPluginEntry, and defineSetupPluginEntry"
+read_when:
+  - You need the exact type signature of definePluginEntry or defineChannelPluginEntry
+  - You want to understand registration mode (full vs setup vs CLI metadata)
+  - You are looking up entry point options
+---
+
+# Plugin Entry Points
+
+Every plugin exports a default entry object. The SDK provides three helpers for
+creating them.
+
+<Tip>
+  **Looking for a walkthrough?** See [Channel Plugins](/plugins/sdk-channel-plugins)
+  or [Provider Plugins](/plugins/sdk-provider-plugins) for step-by-step guides.
+</Tip>
+
+## `definePluginEntry`
+
+**Import:** `Durar/plugin-sdk/plugin-entry`
+
+For provider plugins, tool plugins, hook plugins, and anything that is **not**
+a messaging channel.
+
+```typescript
+import { definePluginEntry } from "Durar/plugin-sdk/plugin-entry";
+
+export default definePluginEntry({
+  id: "my-plugin",
+  name: "My Plugin",
+  description: "Short summary",
+  register(api) {
+    api.registerProvider({
+      /* ... */
+    });
+    api.registerTool({
+      /* ... */
+    });
+  },
+});
+```
+
+| Field          | Type                                                             | Required | Default             |
+| -------------- | ---------------------------------------------------------------- | -------- | ------------------- |
+| `id`           | `string`                                                         | Yes      | —                   |
+| `name`         | `string`                                                         | Yes      | —                   |
+| `description`  | `string`                                                         | Yes      | —                   |
+| `kind`         | `string`                                                         | No       | —                   |
+| `configSchema` | `DurarPluginConfigSchema \| () => DurarPluginConfigSchema` | No       | Empty object schema |
+| `register`     | `(api: DurarPluginApi) => void`                               | Yes      | —                   |
+
+- `id` must match your `Durar.plugin.json` manifest.
+- `kind` is for exclusive slots: `"memory"` or `"context-engine"`.
+- `configSchema` can be a function for lazy evaluation.
+- Durar resolves and memoizes that schema on first access, so expensive schema
+  builders only run once.
+
+## `defineChannelPluginEntry`
+
+**Import:** `Durar/plugin-sdk/channel-core`
+
+Wraps `definePluginEntry` with channel-specific wiring. Automatically calls
+`api.registerChannel({ plugin })`, exposes an optional root-help CLI metadata
+seam, and gates `registerFull` on registration mode.
+
+```typescript
+import { defineChannelPluginEntry } from "Durar/plugin-sdk/channel-core";
+
+export default defineChannelPluginEntry({
+  id: "my-channel",
+  name: "My Channel",
+  description: "Short summary",
+  plugin: myChannelPlugin,
+  setRuntime: setMyRuntime,
+  registerCliMetadata(api) {
+    api.registerCli(/* ... */);
+  },
+  registerFull(api) {
+    api.registerGatewayMethod(/* ... */);
+  },
+});
+```
+
+| Field                 | Type                                                             | Required | Default             |
+| --------------------- | ---------------------------------------------------------------- | -------- | ------------------- |
+| `id`                  | `string`                                                         | Yes      | —                   |
+| `name`                | `string`                                                         | Yes      | —                   |
+| `description`         | `string`                                                         | Yes      | —                   |
+| `plugin`              | `ChannelPlugin`                                                  | Yes      | —                   |
+| `configSchema`        | `DurarPluginConfigSchema \| () => DurarPluginConfigSchema` | No       | Empty object schema |
+| `setRuntime`          | `(runtime: PluginRuntime) => void`                               | No       | —                   |
+| `registerCliMetadata` | `(api: DurarPluginApi) => void`                               | No       | —                   |
+| `registerFull`        | `(api: DurarPluginApi) => void`                               | No       | —                   |
+
+- `setRuntime` is called during registration so you can store the runtime reference
+  (typically via `createPluginRuntimeStore`). It is skipped during CLI metadata
+  capture.
+- `registerCliMetadata` runs during both `api.registrationMode === "cli-metadata"`
+  and `api.registrationMode === "full"`.
+  Use it as the canonical place for channel-owned CLI descriptors so root help
+  stays non-activating while normal CLI command registration remains compatible
+  with full plugin loads.
+- `registerFull` only runs when `api.registrationMode === "full"`. It is skipped
+  during setup-only loading.
+- Like `definePluginEntry`, `configSchema` can be a lazy factory and Durar
+  memoizes the resolved schema on first access.
+- For plugin-owned root CLI commands, prefer `api.registerCli(..., { descriptors: [...] })`
+  when you want the command to stay lazy-loaded without disappearing from the
+  root CLI parse tree. For channel plugins, prefer registering those descriptors
+  from `registerCliMetadata(...)` and keep `registerFull(...)` focused on runtime-only work.
+- If `registerFull(...)` also registers gateway RPC methods, keep them on a
+  plugin-specific prefix. Reserved core admin namespaces (`config.*`,
+  `exec.approvals.*`, `wizard.*`, `update.*`) are always coerced to
+  `operator.admin`.
+
+## `defineSetupPluginEntry`
+
+**Import:** `Durar/plugin-sdk/channel-core`
+
+For the lightweight `setup-entry.ts` file. Returns just `{ plugin }` with no
+runtime or CLI wiring.
+
+```typescript
+import { defineSetupPluginEntry } from "Durar/plugin-sdk/channel-core";
+
+export default defineSetupPluginEntry(myChannelPlugin);
+```
+
+Durar loads this instead of the full entry when a channel is disabled,
+unconfigured, or when deferred loading is enabled. See
+[Setup and Config](/plugins/sdk-setup#setup-entry) for when this matters.
+
+In practice, pair `defineSetupPluginEntry(...)` with the narrow setup helper
+families:
+
+- `Durar/plugin-sdk/setup-runtime` for runtime-safe setup helpers such as
+  import-safe setup patch adapters, lookup-note output,
+  `promptResolvedAllowFrom`, `splitSetupEntries`, and delegated setup proxies
+- `Durar/plugin-sdk/channel-setup` for optional-install setup surfaces
+- `Durar/plugin-sdk/setup-tools` for setup/install CLI/archive/docs helpers
+
+Keep heavy SDKs, CLI registration, and long-lived runtime services in the full
+entry.
+
+## Registration mode
+
+`api.registrationMode` tells your plugin how it was loaded:
+
+| Mode              | When                              | What to register                                                                          |
+| ----------------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
+| `"full"`          | Normal gateway startup            | Everything                                                                                |
+| `"setup-only"`    | Disabled/unconfigured channel     | Channel registration only                                                                 |
+| `"setup-runtime"` | Setup flow with runtime available | Channel registration plus only the lightweight runtime needed before the full entry loads |
+| `"cli-metadata"`  | Root help / CLI metadata capture  | CLI descriptors only                                                                      |
+
+`defineChannelPluginEntry` handles this split automatically. If you use
+`definePluginEntry` directly for a channel, check mode yourself:
+
+```typescript
+register(api) {
+  if (api.registrationMode === "cli-metadata" || api.registrationMode === "full") {
+    api.registerCli(/* ... */);
+    if (api.registrationMode === "cli-metadata") return;
+  }
+
+  api.registerChannel({ plugin: myPlugin });
+  if (api.registrationMode !== "full") return;
+
+  // Heavy runtime-only registrations
+  api.registerService(/* ... */);
+}
+```
+
+Treat `"setup-runtime"` as the window where setup-only startup surfaces must
+exist without re-entering the full bundled channel runtime. Good fits are
+channel registration, setup-safe HTTP routes, setup-safe gateway methods, and
+delegated setup helpers. Heavy background services, CLI registrars, and
+provider/client SDK bootstraps still belong in `"full"`.
+
+For CLI registrars specifically:
+
+- use `descriptors` when the registrar owns one or more root commands and you
+  want Durar to lazy-load the real CLI module on first invocation
+- make sure those descriptors cover every top-level command root exposed by the
+  registrar
+- use `commands` alone only for eager compatibility paths
+
+## Plugin shapes
+
+Durar classifies loaded plugins by their registration behavior:
+
+| Shape                 | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| **plain-capability**  | One capability type (e.g. provider-only)           |
+| **hybrid-capability** | Multiple capability types (e.g. provider + speech) |
+| **hook-only**         | Only hooks, no capabilities                        |
+| **non-capability**    | Tools/commands/services but no capabilities        |
+
+Use `Durar plugins inspect <id>` to see a plugin's shape.
+
+## Related
+
+- [SDK Overview](/plugins/sdk-overview) — registration API and subpath reference
+- [Runtime Helpers](/plugins/sdk-runtime) — `api.runtime` and `createPluginRuntimeStore`
+- [Setup and Config](/plugins/sdk-setup) — manifest, setup entry, deferred loading
+- [Channel Plugins](/plugins/sdk-channel-plugins) — building the `ChannelPlugin` object
+- [Provider Plugins](/plugins/sdk-provider-plugins) — provider registration and hooks

package/docs/plugins/sdk-migration.md

@@ -0,0 +1,359 @@
+---
+title: "Plugin SDK Migration"
+sidebarTitle: "Migrate to SDK"
+summary: "Migrate from the legacy backwards-compatibility layer to the modern plugin SDK"
+read_when:
+  - You see the Durar_PLUGIN_SDK_COMPAT_DEPRECATED warning
+  - You see the Durar_EXTENSION_API_DEPRECATED warning
+  - You are updating a plugin to the modern plugin architecture
+  - You maintain an external Durar plugin
+---
+
+# Plugin SDK Migration
+
+Durar has moved from a broad backwards-compatibility layer to a modern plugin
+architecture with focused, documented imports. If your plugin was built before
+the new architecture, this guide helps you migrate.
+
+## What is changing
+
+The old plugin system provided two wide-open surfaces that let plugins import
+anything they needed from a single entry point:
+
+- **`Durar/plugin-sdk/compat`** — a single import that re-exported dozens of
+  helpers. It was introduced to keep older hook-based plugins working while the
+  new plugin architecture was being built.
+- **`Durar/extension-api`** — a bridge that gave plugins direct access to
+  host-side helpers like the embedded agent runner.
+
+Both surfaces are now **deprecated**. They still work at runtime, but new
+plugins must not use them, and existing plugins should migrate before the next
+major release removes them.
+
+<Warning>
+  The backwards-compatibility layer will be removed in a future major release.
+  Plugins that still import from these surfaces will break when that happens.
+</Warning>
+
+## Why this changed
+
+The old approach caused problems:
+
+- **Slow startup** — importing one helper loaded dozens of unrelated modules
+- **Circular dependencies** — broad re-exports made it easy to create import cycles
+- **Unclear API surface** — no way to tell which exports were stable vs internal
+
+The modern plugin SDK fixes this: each import path (`Durar/plugin-sdk/\<subpath\>`)
+is a small, self-contained module with a clear purpose and documented contract.
+
+Legacy provider convenience seams for bundled channels are also gone. Imports
+such as `Durar/plugin-sdk/slack`, `Durar/plugin-sdk/discord`,
+`Durar/plugin-sdk/signal`, `Durar/plugin-sdk/whatsapp`,
+channel-branded helper seams, and
+`Durar/plugin-sdk/telegram-core` were private mono-repo shortcuts, not
+stable plugin contracts. Use narrow generic SDK subpaths instead. Inside the
+bundled plugin workspace, keep provider-owned helpers in that plugin's own
+`api.ts` or `runtime-api.ts`.
+
+Current bundled provider examples:
+
+- Anthropic keeps Claude-specific stream helpers in its own `api.ts` /
+  `contract-api.ts` seam
+- OpenAI keeps provider builders, default-model helpers, and realtime provider
+  builders in its own `api.ts`
+- OpenRouter keeps provider builder and onboarding/config helpers in its own
+  `api.ts`
+
+## How to migrate
+
+<Steps>
+  <Step title="Audit Windows wrapper fallback behavior">
+    If your plugin uses `Durar/plugin-sdk/windows-spawn`, unresolved Windows
+    `.cmd`/`.bat` wrappers now fail closed unless you explicitly pass
+    `allowShellFallback: true`.
+
+    ```typescript
+    // Before
+    const program = applyWindowsSpawnProgramPolicy({ candidate });
+
+    // After
+    const program = applyWindowsSpawnProgramPolicy({
+      candidate,
+      // Only set this for trusted compatibility callers that intentionally
+      // accept shell-mediated fallback.
+      allowShellFallback: true,
+    });
+    ```
+
+    If your caller does not intentionally rely on shell fallback, do not set
+    `allowShellFallback` and handle the thrown error instead.
+
+  </Step>
+
+  <Step title="Find deprecated imports">
+    Search your plugin for imports from either deprecated surface:
+
+    ```bash
+    grep -r "plugin-sdk/compat" my-plugin/
+    grep -r "Durar/extension-api" my-plugin/
+    ```
+
+  </Step>
+
+  <Step title="Replace with focused imports">
+    Each export from the old surface maps to a specific modern import path:
+
+    ```typescript
+    // Before (deprecated backwards-compatibility layer)
+    import {
+      createChannelReplyPipeline,
+      createPluginRuntimeStore,
+      resolveControlCommandGate,
+    } from "Durar/plugin-sdk/compat";
+
+    // After (modern focused imports)
+    import { createChannelReplyPipeline } from "Durar/plugin-sdk/channel-reply-pipeline";
+    import { createPluginRuntimeStore } from "Durar/plugin-sdk/runtime-store";
+    import { resolveControlCommandGate } from "Durar/plugin-sdk/command-auth";
+    ```
+
+    For host-side helpers, use the injected plugin runtime instead of importing
+    directly:
+
+    ```typescript
+    // Before (deprecated extension-api bridge)
+    import { runEmbeddedPiAgent } from "Durar/extension-api";
+    const result = await runEmbeddedPiAgent({ sessionId, prompt });
+
+    // After (injected runtime)
+    const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
+    ```
+
+    The same pattern applies to other legacy bridge helpers:
+
+    | Old import | Modern equivalent |
+    | --- | --- |
+    | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
+    | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
+    | `resolveAgentIdentity` | `api.runtime.agent.resolveAgentIdentity` |
+    | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
+    | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
+    | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
+    | session store helpers | `api.runtime.agent.session.*` |
+
+  </Step>
+
+  <Step title="Build and test">
+    ```bash
+    pnpm build
+    pnpm test -- my-plugin/
+    ```
+  </Step>
+</Steps>
+
+## Import path reference
+
+<Accordion title="Common import path table">
+  | Import path | Purpose | Key exports |
+  | --- | --- | --- |
+  | `plugin-sdk/plugin-entry` | Canonical plugin entry helper | `definePluginEntry` |
+  | `plugin-sdk/core` | Legacy umbrella re-export for channel entry definitions/builders | `defineChannelPluginEntry`, `createChatChannelPlugin` |
+  | `plugin-sdk/config-schema` | Root config schema export | `DurarSchema` |
+  | `plugin-sdk/provider-entry` | Single-provider entry helper | `defineSingleProviderPluginEntry` |
+  | `plugin-sdk/channel-core` | Focused channel entry definitions and builders | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
+  | `plugin-sdk/setup` | Shared setup wizard helpers | Allowlist prompts, setup status builders |
+  | `plugin-sdk/setup-runtime` | Setup-time runtime helpers | Import-safe setup patch adapters, lookup-note helpers, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies |
+  | `plugin-sdk/setup-adapter-runtime` | Setup adapter helpers | `createEnvPatchedAccountSetupAdapter` |
+  | `plugin-sdk/setup-tools` | Setup tooling helpers | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
+  | `plugin-sdk/account-core` | Multi-account helpers | Account list/config/action-gate helpers |
+  | `plugin-sdk/account-id` | Account-id helpers | `DEFAULT_ACCOUNT_ID`, account-id normalization |
+  | `plugin-sdk/account-resolution` | Account lookup helpers | Account lookup + default-fallback helpers |
+  | `plugin-sdk/account-helpers` | Narrow account helpers | Account list/account-action helpers |
+  | `plugin-sdk/channel-setup` | Setup wizard adapters | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
+  | `plugin-sdk/channel-pairing` | DM pairing primitives | `createChannelPairingController` |
+  | `plugin-sdk/channel-reply-pipeline` | Reply prefix + typing wiring | `createChannelReplyPipeline` |
+  | `plugin-sdk/channel-config-helpers` | Config adapter factories | `createHybridChannelConfigAdapter` |
+  | `plugin-sdk/channel-config-schema` | Config schema builders | Channel config schema types |
+  | `plugin-sdk/telegram-command-config` | Telegram command config helpers | Command-name normalization, description trimming, duplicate/conflict validation |
+  | `plugin-sdk/channel-policy` | Group/DM policy resolution | `resolveChannelGroupRequireMention` |
+  | `plugin-sdk/channel-lifecycle` | Account status tracking | `createAccountStatusSink` |
+  | `plugin-sdk/inbound-envelope` | Inbound envelope helpers | Shared route + envelope builder helpers |
+  | `plugin-sdk/inbound-reply-dispatch` | Inbound reply helpers | Shared record-and-dispatch helpers |
+  | `plugin-sdk/messaging-targets` | Messaging target parsing | Target parsing/matching helpers |
+  | `plugin-sdk/outbound-media` | Outbound media helpers | Shared outbound media loading |
+  | `plugin-sdk/outbound-runtime` | Outbound runtime helpers | Outbound identity/send delegate helpers |
+  | `plugin-sdk/thread-bindings-runtime` | Thread-binding helpers | Thread-binding lifecycle and adapter helpers |
+  | `plugin-sdk/agent-media-payload` | Legacy media payload helpers | Agent media payload builder for legacy field layouts |
+  | `plugin-sdk/channel-runtime` | Deprecated compatibility shim | Legacy channel runtime utilities only |
+  | `plugin-sdk/channel-send-result` | Send result types | Reply result types |
+  | `plugin-sdk/runtime-store` | Persistent plugin storage | `createPluginRuntimeStore` |
+  | `plugin-sdk/runtime` | Broad runtime helpers | Runtime/logging/backup/plugin-install helpers |
+  | `plugin-sdk/runtime-env` | Narrow runtime env helpers | Logger/runtime env, timeout, retry, and backoff helpers |
+  | `plugin-sdk/plugin-runtime` | Shared plugin runtime helpers | Plugin commands/hooks/http/interactive helpers |
+  | `plugin-sdk/hook-runtime` | Hook pipeline helpers | Shared webhook/internal hook pipeline helpers |
+  | `plugin-sdk/lazy-runtime` | Lazy runtime helpers | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
+  | `plugin-sdk/process-runtime` | Process helpers | Shared exec helpers |
+  | `plugin-sdk/cli-runtime` | CLI runtime helpers | Command formatting, waits, version helpers |
+  | `plugin-sdk/gateway-runtime` | Gateway helpers | Gateway client and channel-status patch helpers |
+  | `plugin-sdk/config-runtime` | Config helpers | Config load/write helpers |
+  | `plugin-sdk/telegram-command-config` | Telegram command helpers | Fallback-stable Telegram command validation helpers when the bundled Telegram contract surface is unavailable |
+  | `plugin-sdk/approval-runtime` | Approval prompt helpers | Exec/plugin approval payload, approval capability/profile helpers, native approval routing/runtime helpers |
+  | `plugin-sdk/approval-auth-runtime` | Approval auth helpers | Approver resolution, same-chat action auth |
+  | `plugin-sdk/approval-client-runtime` | Approval client helpers | Native exec approval profile/filter helpers |
+  | `plugin-sdk/approval-delivery-runtime` | Approval delivery helpers | Native approval capability/delivery adapters |
+  | `plugin-sdk/approval-native-runtime` | Approval target helpers | Native approval target/account binding helpers |
+  | `plugin-sdk/approval-reply-runtime` | Approval reply helpers | Exec/plugin approval reply payload helpers |
+  | `plugin-sdk/security-runtime` | Security helpers | Shared trust, DM gating, external-content, and secret-collection helpers |
+  | `plugin-sdk/ssrf-policy` | SSRF policy helpers | Host allowlist and private-network policy helpers |
+  | `plugin-sdk/ssrf-runtime` | SSRF runtime helpers | Pinned-dispatcher, guarded fetch, SSRF policy helpers |
+  | `plugin-sdk/collection-runtime` | Bounded cache helpers | `pruneMapToMaxSize` |
+  | `plugin-sdk/diagnostic-runtime` | Diagnostic gating helpers | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
+  | `plugin-sdk/error-runtime` | Error formatting helpers | `formatUncaughtError`, `isApprovalNotFoundError`, error graph helpers |
+  | `plugin-sdk/fetch-runtime` | Wrapped fetch/proxy helpers | `resolveFetch`, proxy helpers |
+  | `plugin-sdk/host-runtime` | Host normalization helpers | `normalizeHostname`, `normalizeScpRemoteHost` |
+  | `plugin-sdk/retry-runtime` | Retry helpers | `RetryConfig`, `retryAsync`, policy runners |
+  | `plugin-sdk/allow-from` | Allowlist formatting | `formatAllowFromLowercase` |
+  | `plugin-sdk/allowlist-resolution` | Allowlist input mapping | `mapAllowlistResolutionInputs` |
+  | `plugin-sdk/command-auth` | Command gating and command-surface helpers | `resolveControlCommandGate`, sender-authorization helpers, command registry helpers |
+  | `plugin-sdk/secret-input` | Secret input parsing | Secret input helpers |
+  | `plugin-sdk/webhook-ingress` | Webhook request helpers | Webhook target utilities |
+  | `plugin-sdk/webhook-request-guards` | Webhook body guard helpers | Request body read/limit helpers |
+  | `plugin-sdk/reply-runtime` | Shared reply runtime | Inbound dispatch, heartbeat, reply planner, chunking |
+  | `plugin-sdk/reply-dispatch-runtime` | Narrow reply dispatch helpers | Finalize + provider dispatch helpers |
+  | `plugin-sdk/reply-history` | Reply-history helpers | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
+  | `plugin-sdk/reply-reference` | Reply reference planning | `createReplyReferencePlanner` |
+  | `plugin-sdk/reply-chunking` | Reply chunk helpers | Text/markdown chunking helpers |
+  | `plugin-sdk/session-store-runtime` | Session store helpers | Store path + updated-at helpers |
+  | `plugin-sdk/state-paths` | State path helpers | State and OAuth dir helpers |
+  | `plugin-sdk/routing` | Routing/session-key helpers | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, session-key normalization helpers |
+  | `plugin-sdk/status-helpers` | Channel status helpers | Channel/account status summary builders, runtime-state defaults, issue metadata helpers |
+  | `plugin-sdk/target-resolver-runtime` | Target resolver helpers | Shared target resolver helpers |
+  | `plugin-sdk/string-normalization-runtime` | String normalization helpers | Slug/string normalization helpers |
+  | `plugin-sdk/request-url` | Request URL helpers | Extract string URLs from request-like inputs |
+  | `plugin-sdk/run-command` | Timed command helpers | Timed command runner with normalized stdout/stderr |
+  | `plugin-sdk/param-readers` | Param readers | Common tool/CLI param readers |
+  | `plugin-sdk/tool-send` | Tool send extraction | Extract canonical send target fields from tool args |
+  | `plugin-sdk/temp-path` | Temp path helpers | Shared temp-download path helpers |
+  | `plugin-sdk/logging-core` | Logging helpers | Subsystem logger and redaction helpers |
+  | `plugin-sdk/markdown-table-runtime` | Markdown-table helpers | Markdown table mode helpers |
+  | `plugin-sdk/reply-payload` | Message reply types | Reply payload types |
+  | `plugin-sdk/provider-setup` | Curated local/self-hosted provider setup helpers | Self-hosted provider discovery/config helpers |
+  | `plugin-sdk/self-hosted-provider-setup` | Focused OpenAI-compatible self-hosted provider setup helpers | Same self-hosted provider discovery/config helpers |
+  | `plugin-sdk/provider-auth-runtime` | Provider runtime auth helpers | Runtime API-key resolution helpers |
+  | `plugin-sdk/provider-auth-api-key` | Provider API-key setup helpers | API-key onboarding/profile-write helpers |
+  | `plugin-sdk/provider-auth-result` | Provider auth-result helpers | Standard OAuth auth-result builder |
+  | `plugin-sdk/provider-auth-login` | Provider interactive login helpers | Shared interactive login helpers |
+  | `plugin-sdk/provider-env-vars` | Provider env-var helpers | Provider auth env-var lookup helpers |
+  | `plugin-sdk/provider-model-shared` | Shared provider model/replay helpers | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, shared replay-policy builders, provider-endpoint helpers, and model-id normalization helpers |
+  | `plugin-sdk/provider-catalog-shared` | Shared provider catalog helpers | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
+  | `plugin-sdk/provider-onboard` | Provider onboarding patches | Onboarding config helpers |
+  | `plugin-sdk/provider-http` | Provider HTTP helpers | Generic provider HTTP/endpoint capability helpers |
+  | `plugin-sdk/provider-web-fetch` | Provider web-fetch helpers | Web-fetch provider registration/cache helpers |
+  | `plugin-sdk/provider-web-search` | Provider web-search helpers | Web-search provider registration/cache/config helpers |
+  | `plugin-sdk/provider-tools` | Provider tool/schema compat helpers | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema cleanup + diagnostics, and xAI compat helpers such as `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
+  | `plugin-sdk/provider-usage` | Provider usage helpers | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`, and other provider usage helpers |
+  | `plugin-sdk/provider-stream` | Provider stream wrapper helpers | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, stream wrapper types, and shared Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helpers |
+  | `plugin-sdk/keyed-async-queue` | Ordered async queue | `KeyedAsyncQueue` |
+  | `plugin-sdk/media-runtime` | Shared media helpers | Media fetch/transform/store helpers plus media payload builders |
+  | `plugin-sdk/media-understanding` | Media-understanding helpers | Media understanding provider types plus provider-facing image/audio helper exports |
+  | `plugin-sdk/text-runtime` | Shared text helpers | Assistant-visible-text stripping, markdown render/chunking/table helpers, redaction helpers, directive-tag helpers, safe-text utilities, and related text/logging helpers |
+  | `plugin-sdk/text-chunking` | Text chunking helpers | Outbound text chunking helper |
+  | `plugin-sdk/speech` | Speech helpers | Speech provider types plus provider-facing directive, registry, and validation helpers |
+  | `plugin-sdk/speech-core` | Shared speech core | Speech provider types, registry, directives, normalization |
+  | `plugin-sdk/realtime-transcription` | Realtime transcription helpers | Provider types and registry helpers |
+  | `plugin-sdk/realtime-voice` | Realtime voice helpers | Provider types and registry helpers |
+  | `plugin-sdk/image-generation-core` | Shared image-generation core | Image-generation types, failover, auth, and registry helpers |
+  | `plugin-sdk/video-generation` | Video-generation helpers | Video-generation provider/request/result types |
+  | `plugin-sdk/video-generation-core` | Shared video-generation core | Video-generation types, failover helpers, provider lookup, and model-ref parsing |
+  | `plugin-sdk/interactive-runtime` | Interactive reply helpers | Interactive reply payload normalization/reduction |
+  | `plugin-sdk/channel-config-primitives` | Channel config primitives | Narrow channel config-schema primitives |
+  | `plugin-sdk/channel-config-writes` | Channel config-write helpers | Channel config-write authorization helpers |
+  | `plugin-sdk/channel-plugin-common` | Shared channel prelude | Shared channel plugin prelude exports |
+  | `plugin-sdk/channel-status` | Channel status helpers | Shared channel status snapshot/summary helpers |
+  | `plugin-sdk/allowlist-config-edit` | Allowlist config helpers | Allowlist config edit/read helpers |
+  | `plugin-sdk/group-access` | Group access helpers | Shared group-access decision helpers |
+  | `plugin-sdk/direct-dm` | Direct-DM helpers | Shared direct-DM auth/guard helpers |
+  | `plugin-sdk/extension-shared` | Shared extension helpers | Passive-channel/status helper primitives |
+  | `plugin-sdk/webhook-targets` | Webhook target helpers | Webhook target registry and route-install helpers |
+  | `plugin-sdk/webhook-path` | Webhook path helpers | Webhook path normalization helpers |
+  | `plugin-sdk/web-media` | Shared web media helpers | Remote/local media loading helpers |
+  | `plugin-sdk/zod` | Zod re-export | Re-exported `zod` for plugin SDK consumers |
+  | `plugin-sdk/memory-core` | Bundled memory-core helpers | Memory manager/config/file/CLI helper surface |
+  | `plugin-sdk/memory-core-engine-runtime` | Memory engine runtime facade | Memory index/search runtime facade |
+  | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine | Memory host foundation engine exports |
+  | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding engine | Memory host embedding engine exports |
+  | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine | Memory host QMD engine exports |
+  | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine | Memory host storage engine exports |
+  | `plugin-sdk/memory-core-host-multimodal` | Memory host multimodal helpers | Memory host multimodal helpers |
+  | `plugin-sdk/memory-core-host-query` | Memory host query helpers | Memory host query helpers |
+  | `plugin-sdk/memory-core-host-secret` | Memory host secret helpers | Memory host secret helpers |
+  | `plugin-sdk/memory-core-host-status` | Memory host status helpers | Memory host status helpers |
+  | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI runtime | Memory host CLI runtime helpers |
+  | `plugin-sdk/memory-core-host-runtime-core` | Memory host core runtime | Memory host core runtime helpers |
+  | `plugin-sdk/memory-core-host-runtime-files` | Memory host file/runtime helpers | Memory host file/runtime helpers |
+  | `plugin-sdk/memory-lancedb` | Bundled memory-lancedb helpers | Memory-lancedb helper surface |
+  | `plugin-sdk/testing` | Test utilities | Test helpers and mocks |
+</Accordion>
+
+This table is intentionally the common migration subset, not the full SDK
+surface. The full list of 200+ entrypoints lives in
+`scripts/lib/plugin-sdk-entrypoints.json`.
+
+That list still includes some bundled-plugin helper seams such as
+`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
+`plugin-sdk/zalo-setup`, and `plugin-sdk/matrix*`. Those remain exported for
+bundled-plugin maintenance and compatibility, but they are intentionally
+omitted from the common migration table and are not the recommended target for
+new plugin code.
+
+The same rule applies to other bundled-helper families such as:
+
+- browser support helpers: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support`
+- Matrix: `plugin-sdk/matrix*`
+- LINE: `plugin-sdk/line*`
+- IRC: `plugin-sdk/irc*`
+- bundled helper/plugin surfaces like `plugin-sdk/googlechat`,
+  `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
+  `plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
+  `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
+  `plugin-sdk/twitch`,
+  `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`,
+  `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
+  `plugin-sdk/thread-ownership`, and `plugin-sdk/voice-call`
+
+`plugin-sdk/github-copilot-token` currently exposes the narrow token-helper
+surface `DEFAULT_COPILOT_API_BASE_URL`,
+`deriveCopilotApiBaseUrlFromToken`, and `resolveCopilotApiToken`.
+
+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.
+
+## Removal timeline
+
+| When                   | What happens                                                            |
+| ---------------------- | ----------------------------------------------------------------------- |
+| **Now**                | Deprecated surfaces emit runtime warnings                               |
+| **Next major release** | Deprecated surfaces will be removed; plugins still using them will fail |
+
+All core plugins have already been migrated. External plugins should migrate
+before the next major release.
+
+## Suppressing the warnings temporarily
+
+Set these environment variables while you work on migrating:
+
+```bash
+Durar_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 Durar gateway run
+Durar_SUPPRESS_EXTENSION_API_WARNING=1 Durar gateway run
+```
+
+This is a temporary escape hatch, not a permanent solution.
+
+## Related
+
+- [Getting Started](/plugins/building-plugins) — build your first plugin
+- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
+- [Channel Plugins](/plugins/sdk-channel-plugins) — building channel plugins
+- [Provider Plugins](/plugins/sdk-provider-plugins) — building provider plugins
+- [Plugin Internals](/plugins/architecture) — architecture deep dive
+- [Plugin Manifest](/plugins/manifest) — manifest schema reference