durar-ai 2026.4.4

package/docs/plugins/sdk-channel-plugins.md

@@ -0,0 +1,508 @@
+---
+title: "Building Channel Plugins"
+sidebarTitle: "Channel Plugins"
+summary: "Step-by-step guide to building a messaging channel plugin for Durar"
+read_when:
+  - You are building a new messaging channel plugin
+  - You want to connect Durar to a messaging platform
+  - You need to understand the ChannelPlugin adapter surface
+---
+
+# Building Channel Plugins
+
+This guide walks through building a channel plugin that connects Durar to a
+messaging platform. By the end you will have a working channel with DM security,
+pairing, reply threading, and outbound messaging.
+
+<Info>
+  If you have not built any Durar plugin before, read
+  [Getting Started](/plugins/building-plugins) first for the basic package
+  structure and manifest setup.
+</Info>
+
+## How channel plugins work
+
+Channel plugins do not need their own send/edit/react tools. Durar keeps one
+shared `message` tool in core. Your plugin owns:
+
+- **Config** — account resolution and setup wizard
+- **Security** — DM policy and allowlists
+- **Pairing** — DM approval flow
+- **Session grammar** — how provider-specific conversation ids map to base chats, thread ids, and parent fallbacks
+- **Outbound** — sending text, media, and polls to the platform
+- **Threading** — how replies are threaded
+
+Core owns the shared message tool, prompt wiring, the outer session-key shape,
+generic `:thread:` bookkeeping, and dispatch.
+
+If your platform stores extra scope inside conversation ids, keep that parsing
+in the plugin with `messaging.resolveSessionConversation(...)`. That is the
+canonical hook for mapping `rawId` to the base conversation id, optional thread
+id, explicit `baseConversationId`, and any `parentConversationCandidates`.
+When you return `parentConversationCandidates`, keep them ordered from the
+narrowest parent to the broadest/base conversation.
+
+Bundled plugins that need the same parsing before the channel registry boots
+can also expose a top-level `session-key-api.ts` file with a matching
+`resolveSessionConversation(...)` export. Core uses that bootstrap-safe surface
+only when the runtime plugin registry is not available yet.
+
+`messaging.resolveParentConversationCandidates(...)` remains available as a
+legacy compatibility fallback when a plugin only needs parent fallbacks on top
+of the generic/raw id. If both hooks exist, core uses
+`resolveSessionConversation(...).parentConversationCandidates` first and only
+falls back to `resolveParentConversationCandidates(...)` when the canonical hook
+omits them.
+
+## Approvals and channel capabilities
+
+Most channel plugins do not need approval-specific code.
+
+- Core owns same-chat `/approve`, shared approval button payloads, and generic fallback delivery.
+- Prefer one `approvalCapability` object on the channel plugin when the channel needs approval-specific behavior.
+- `approvalCapability.authorizeActorAction` and `approvalCapability.getActionAvailabilityState` are the canonical approval-auth seam.
+- Use `outbound.shouldSuppressLocalPayloadPrompt` or `outbound.beforeDeliverPayload` for channel-specific payload lifecycle behavior such as hiding duplicate local approval prompts or sending typing indicators before delivery.
+- Use `approvalCapability.delivery` only for native approval routing or fallback suppression.
+- Use `approvalCapability.render` only when a channel truly needs custom approval payloads instead of the shared renderer.
+- If a channel can infer stable owner-like DM identities from existing config, use `createResolvedApproverActionAuthAdapter` from `Durar/plugin-sdk/approval-runtime` to restrict same-chat `/approve` without adding approval-specific core logic.
+- If a channel needs native approval delivery, keep channel code focused on target normalization and transport hooks. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability`, and `createChannelNativeApprovalRuntime` from `Durar/plugin-sdk/approval-runtime` so core owns request filtering, routing, dedupe, expiry, and gateway subscription.
+- Native approval channels must route both `accountId` and `approvalKind` through those helpers. `accountId` keeps multi-account approval policy scoped to the right bot account, and `approvalKind` keeps exec vs plugin approval behavior available to the channel without hardcoded branches in core.
+- Preserve the delivered approval id kind end-to-end. Native clients should not
+  guess or rewrite exec vs plugin approval routing from channel-local state.
+- Different approval kinds can intentionally expose different native surfaces.
+  Current bundled examples:
+  - Slack keeps native approval routing available for both exec and plugin ids.
+  - Matrix keeps native DM/channel routing for exec approvals only and leaves
+    plugin approvals on the shared same-chat `/approve` path.
+- `createApproverRestrictedNativeApprovalAdapter` still exists as a compatibility wrapper, but new code should prefer the capability builder and expose `approvalCapability` on the plugin.
+
+For hot channel entrypoints, prefer the narrower runtime subpaths when you only
+need one part of that family:
+
+- `Durar/plugin-sdk/approval-auth-runtime`
+- `Durar/plugin-sdk/approval-client-runtime`
+- `Durar/plugin-sdk/approval-delivery-runtime`
+- `Durar/plugin-sdk/approval-native-runtime`
+- `Durar/plugin-sdk/approval-reply-runtime`
+
+Likewise, prefer `Durar/plugin-sdk/setup-runtime`,
+`Durar/plugin-sdk/setup-adapter-runtime`,
+`Durar/plugin-sdk/reply-runtime`,
+`Durar/plugin-sdk/reply-dispatch-runtime`,
+`Durar/plugin-sdk/reply-reference`, and
+`Durar/plugin-sdk/reply-chunking` when you do not need the broader umbrella
+surface.
+
+For setup specifically:
+
+- `Durar/plugin-sdk/setup-runtime` covers the runtime-safe setup helpers:
+  import-safe setup patch adapters (`createPatchedAccountSetupAdapter`,
+  `createEnvPatchedAccountSetupAdapter`,
+  `createSetupInputPresenceValidator`), lookup-note output,
+  `promptResolvedAllowFrom`, `splitSetupEntries`, and the delegated
+  setup-proxy builders
+- `Durar/plugin-sdk/setup-adapter-runtime` is the narrow env-aware adapter
+  seam for `createEnvPatchedAccountSetupAdapter`
+- `Durar/plugin-sdk/channel-setup` covers the optional-install setup
+  builders plus a few setup-safe primitives:
+  `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
+  `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
+  `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, and
+  `splitSetupEntries`
+- use the broader `Durar/plugin-sdk/setup` seam only when you also need the
+  heavier shared setup/config helpers such as
+  `moveSingleAccountChannelSectionToDefaultAccount(...)`
+
+If your channel only wants to advertise "install this plugin first" in setup
+surfaces, prefer `createOptionalChannelSetupSurface(...)`. The generated
+adapter/wizard fail closed on config writes and finalization, and they reuse
+the same install-required message across validation, finalize, and docs-link
+copy.
+
+For other hot channel paths, prefer the narrow helpers over broader legacy
+surfaces:
+
+- `Durar/plugin-sdk/account-core`,
+  `Durar/plugin-sdk/account-id`,
+  `Durar/plugin-sdk/account-resolution`, and
+  `Durar/plugin-sdk/account-helpers` for multi-account config and
+  default-account fallback
+- `Durar/plugin-sdk/inbound-envelope` and
+  `Durar/plugin-sdk/inbound-reply-dispatch` for inbound route/envelope and
+  record-and-dispatch wiring
+- `Durar/plugin-sdk/messaging-targets` for target parsing/matching
+- `Durar/plugin-sdk/outbound-media` and
+  `Durar/plugin-sdk/outbound-runtime` for media loading plus outbound
+  identity/send delegates
+- `Durar/plugin-sdk/thread-bindings-runtime` for thread-binding lifecycle
+  and adapter registration
+- `Durar/plugin-sdk/agent-media-payload` only when a legacy agent/media
+  payload field layout is still required
+- `Durar/plugin-sdk/telegram-command-config` for Telegram custom-command
+  normalization, duplicate/conflict validation, and a fallback-stable command
+  config contract
+
+Auth-only channels can usually stop at the default path: core handles approvals and the plugin just exposes outbound/auth capabilities. Native approval channels such as Matrix, Slack, Telegram, and custom chat transports should use the shared native helpers instead of rolling their own approval lifecycle.
+
+## Walkthrough
+
+<Steps>
+  <a id="step-1-package-and-manifest"></a>
+  <Step title="Package and manifest">
+    Create the standard plugin files. The `channel` field in `package.json` is
+    what makes this a channel plugin. For the full package-metadata surface,
+    see [Plugin Setup and Config](/plugins/sdk-setup#Durarchannel):
+
+    <CodeGroup>
+    ```json package.json
+    {
+      "name": "@myorg/Durar-acme-chat",
+      "version": "1.0.0",
+      "type": "module",
+      "Durar": {
+        "extensions": ["./index.ts"],
+        "setupEntry": "./setup-entry.ts",
+        "channel": {
+          "id": "acme-chat",
+          "label": "Acme Chat",
+          "blurb": "Connect Durar to Acme Chat."
+        }
+      }
+    }
+    ```
+
+    ```json Durar.plugin.json
+    {
+      "id": "acme-chat",
+      "kind": "channel",
+      "channels": ["acme-chat"],
+      "name": "Acme Chat",
+      "description": "Acme Chat channel plugin",
+      "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "acme-chat": {
+            "type": "object",
+            "properties": {
+              "token": { "type": "string" },
+              "allowFrom": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+    ```
+    </CodeGroup>
+
+  </Step>
+
+  <Step title="Build the channel plugin object">
+    The `ChannelPlugin` interface has many optional adapter surfaces. Start with
+    the minimum — `id` and `setup` — and add adapters as you need them.
+
+    Create `src/channel.ts`:
+
+    ```typescript src/channel.ts
+    import {
+      createChatChannelPlugin,
+      createChannelPluginBase,
+    } from "Durar/plugin-sdk/channel-core";
+    import type { DurarConfig } from "Durar/plugin-sdk/channel-core";
+    import { acmeChatApi } from "./client.js"; // your platform API client
+
+    type ResolvedAccount = {
+      accountId: string | null;
+      token: string;
+      allowFrom: string[];
+      dmPolicy: string | undefined;
+    };
+
+    function resolveAccount(
+      cfg: DurarConfig,
+      accountId?: string | null,
+    ): ResolvedAccount {
+      const section = (cfg.channels as Record<string, any>)?.["acme-chat"];
+      const token = section?.token;
+      if (!token) throw new Error("acme-chat: token is required");
+      return {
+        accountId: accountId ?? null,
+        token,
+        allowFrom: section?.allowFrom ?? [],
+        dmPolicy: section?.dmSecurity,
+      };
+    }
+
+    export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
+      base: createChannelPluginBase({
+        id: "acme-chat",
+        setup: {
+          resolveAccount,
+          inspectAccount(cfg, accountId) {
+            const section =
+              (cfg.channels as Record<string, any>)?.["acme-chat"];
+            return {
+              enabled: Boolean(section?.token),
+              configured: Boolean(section?.token),
+              tokenStatus: section?.token ? "available" : "missing",
+            };
+          },
+        },
+      }),
+
+      // DM security: who can message the bot
+      security: {
+        dm: {
+          channelKey: "acme-chat",
+          resolvePolicy: (account) => account.dmPolicy,
+          resolveAllowFrom: (account) => account.allowFrom,
+          defaultPolicy: "allowlist",
+        },
+      },
+
+      // Pairing: approval flow for new DM contacts
+      pairing: {
+        text: {
+          idLabel: "Acme Chat username",
+          message: "Send this code to verify your identity:",
+          notify: async ({ target, code }) => {
+            await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
+          },
+        },
+      },
+
+      // Threading: how replies are delivered
+      threading: { topLevelReplyToMode: "reply" },
+
+      // Outbound: send messages to the platform
+      outbound: {
+        attachedResults: {
+          sendText: async (params) => {
+            const result = await acmeChatApi.sendMessage(
+              params.to,
+              params.text,
+            );
+            return { messageId: result.id };
+          },
+        },
+        base: {
+          sendMedia: async (params) => {
+            await acmeChatApi.sendFile(params.to, params.filePath);
+          },
+        },
+      },
+    });
+    ```
+
+    <Accordion title="What createChatChannelPlugin does for you">
+      Instead of implementing low-level adapter interfaces manually, you pass
+      declarative options and the builder composes them:
+
+      | Option | What it wires |
+      | --- | --- |
+      | `security.dm` | Scoped DM security resolver from config fields |
+      | `pairing.text` | Text-based DM pairing flow with code exchange |
+      | `threading` | Reply-to-mode resolver (fixed, account-scoped, or custom) |
+      | `outbound.attachedResults` | Send functions that return result metadata (message IDs) |
+
+      You can also pass raw adapter objects instead of the declarative options
+      if you need full control.
+    </Accordion>
+
+  </Step>
+
+  <Step title="Wire the entry point">
+    Create `index.ts`:
+
+    ```typescript index.ts
+    import { defineChannelPluginEntry } from "Durar/plugin-sdk/channel-core";
+    import { acmeChatPlugin } from "./src/channel.js";
+
+    export default defineChannelPluginEntry({
+      id: "acme-chat",
+      name: "Acme Chat",
+      description: "Acme Chat channel plugin",
+      plugin: acmeChatPlugin,
+      registerCliMetadata(api) {
+        api.registerCli(
+          ({ program }) => {
+            program
+              .command("acme-chat")
+              .description("Acme Chat management");
+          },
+          {
+            descriptors: [
+              {
+                name: "acme-chat",
+                description: "Acme Chat management",
+                hasSubcommands: false,
+              },
+            ],
+          },
+        );
+      },
+      registerFull(api) {
+        api.registerGatewayMethod(/* ... */);
+      },
+    });
+    ```
+
+    Put channel-owned CLI descriptors in `registerCliMetadata(...)` so Durar
+    can show them in root help without activating the full channel runtime,
+    while normal full loads still pick up the same descriptors for real command
+    registration. Keep `registerFull(...)` for runtime-only work.
+    If `registerFull(...)` registers gateway RPC methods, use a
+    plugin-specific prefix. Core admin namespaces (`config.*`,
+    `exec.approvals.*`, `wizard.*`, `update.*`) stay reserved and always
+    resolve to `operator.admin`.
+    `defineChannelPluginEntry` handles the registration-mode split automatically. See
+    [Entry Points](/plugins/sdk-entrypoints#definechannelpluginentry) for all
+    options.
+
+  </Step>
+
+  <Step title="Add a setup entry">
+    Create `setup-entry.ts` for lightweight loading during onboarding:
+
+    ```typescript setup-entry.ts
+    import { defineSetupPluginEntry } from "Durar/plugin-sdk/channel-core";
+    import { acmeChatPlugin } from "./src/channel.js";
+
+    export default defineSetupPluginEntry(acmeChatPlugin);
+    ```
+
+    Durar loads this instead of the full entry when the channel is disabled
+    or unconfigured. It avoids pulling in heavy runtime code during setup flows.
+    See [Setup and Config](/plugins/sdk-setup#setup-entry) for details.
+
+  </Step>
+
+  <Step title="Handle inbound messages">
+    Your plugin needs to receive messages from the platform and forward them to
+    Durar. The typical pattern is a webhook that verifies the request and
+    dispatches it through your channel's inbound handler:
+
+    ```typescript
+    registerFull(api) {
+      api.registerHttpRoute({
+        path: "/acme-chat/webhook",
+        auth: "plugin", // plugin-managed auth (verify signatures yourself)
+        handler: async (req, res) => {
+          const event = parseWebhookPayload(req);
+
+          // Your inbound handler dispatches the message to Durar.
+          // The exact wiring depends on your platform SDK —
+          // see a real example in the bundled Microsoft Teams or Google Chat plugin package.
+          await handleAcmeChatInbound(api, event);
+
+          res.statusCode = 200;
+          res.end("ok");
+          return true;
+        },
+      });
+    }
+    ```
+
+    <Note>
+      Inbound message handling is channel-specific. Each channel plugin owns
+      its own inbound pipeline. Look at bundled channel plugins
+      (for example the Microsoft Teams or Google Chat plugin package) for real patterns.
+    </Note>
+
+  </Step>
+
+<a id="step-6-test"></a>
+<Step title="Test">
+Write colocated tests in `src/channel.test.ts`:
+
+    ```typescript src/channel.test.ts
+    import { describe, it, expect } from "vitest";
+    import { acmeChatPlugin } from "./channel.js";
+
+    describe("acme-chat plugin", () => {
+      it("resolves account from config", () => {
+        const cfg = {
+          channels: {
+            "acme-chat": { token: "test-token", allowFrom: ["user1"] },
+          },
+        } as any;
+        const account = acmeChatPlugin.setup!.resolveAccount(cfg, undefined);
+        expect(account.token).toBe("test-token");
+      });
+
+      it("inspects account without materializing secrets", () => {
+        const cfg = {
+          channels: { "acme-chat": { token: "test-token" } },
+        } as any;
+        const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
+        expect(result.configured).toBe(true);
+        expect(result.tokenStatus).toBe("available");
+      });
+
+      it("reports missing config", () => {
+        const cfg = { channels: {} } as any;
+        const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
+        expect(result.configured).toBe(false);
+      });
+    });
+    ```
+
+    ```bash
+    pnpm test -- <bundled-plugin-root>/acme-chat/
+    ```
+
+    For shared test helpers, see [Testing](/plugins/sdk-testing).
+
+  </Step>
+</Steps>
+
+## File structure
+
+```
+<bundled-plugin-root>/acme-chat/
+├── package.json              # Durar.channel metadata
+├── Durar.plugin.json      # Manifest with config schema
+├── index.ts                  # defineChannelPluginEntry
+├── setup-entry.ts            # defineSetupPluginEntry
+├── api.ts                    # Public exports (optional)
+├── runtime-api.ts            # Internal runtime exports (optional)
+└── src/
+    ├── channel.ts            # ChannelPlugin via createChatChannelPlugin
+    ├── channel.test.ts       # Tests
+    ├── client.ts             # Platform API client
+    └── runtime.ts            # Runtime store (if needed)
+```
+
+## Advanced topics
+
+<CardGroup cols={2}>
+  <Card title="Threading options" icon="git-branch" href="/plugins/sdk-entrypoints#registration-mode">
+    Fixed, account-scoped, or custom reply modes
+  </Card>
+  <Card title="Message tool integration" icon="puzzle" href="/plugins/architecture#channel-plugins-and-the-shared-message-tool">
+    describeMessageTool and action discovery
+  </Card>
+  <Card title="Target resolution" icon="crosshair" href="/plugins/architecture#channel-target-resolution">
+    inferTargetChatType, looksLikeId, resolveTarget
+  </Card>
+  <Card title="Runtime helpers" icon="settings" href="/plugins/sdk-runtime">
+    TTS, STT, media, subagent via api.runtime
+  </Card>
+</CardGroup>
+
+<Note>
+Some bundled helper seams still exist for bundled-plugin maintenance and
+compatibility. They are not the recommended pattern for new channel plugins;
+prefer the generic channel/setup/reply/runtime subpaths from the common SDK
+surface unless you are maintaining that bundled plugin family directly.
+</Note>
+
+## Next steps
+
+- [Provider Plugins](/plugins/sdk-provider-plugins) — if your plugin also provides models
+- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
+- [SDK Testing](/plugins/sdk-testing) — test utilities and contract tests
+- [Plugin Manifest](/plugins/manifest) — full manifest schema