docs(plugins): document channel route sdk

docs/plugins/compatibility.md

@@ -111,6 +111,8 @@ Current compatibility records include:
   `registerMemoryCapability`
 - legacy channel SDK helpers for native message schemas, mention gating,
   inbound envelope formatting, and approval capability nesting
+- legacy channel route key and comparable-target helper aliases while plugins
+  move to `openclaw/plugin-sdk/channel-route`
 - activation hints that are being replaced by manifest contribution ownership
 - `setup-api` runtime fallback while setup descriptors move to cold
   `setup.requiresRuntime: false` metadata

docs/plugins/sdk-channel-plugins.md

@@ -57,6 +57,15 @@ id, explicit `baseConversationId`, and any `parentConversationCandidates`.
 When you return `parentConversationCandidates`, keep them ordered from the
 narrowest parent to the broadest/base conversation.
 
+Use `openclaw/plugin-sdk/channel-route` when plugin code needs to normalize
+route-like fields, compare a child thread with its parent route, or build a
+stable dedupe key from `{ channel, to, accountId, threadId }`. The helper
+normalizes numeric thread ids the same way core does, so plugins should prefer
+it over ad hoc `String(threadId)` comparisons.
+Plugins with provider-specific target grammar can inject their parser into
+`resolveChannelRouteTargetWithParser(...)` and still get the same route target
+shape and thread fallback semantics core uses.
+
 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
@@ -87,6 +96,8 @@ Most channel plugins do not need approval-specific code.
 - Use `approvalCapability.describeExecApprovalSetup` when the channel wants the disabled-path reply to explain the exact config knobs needed to enable native exec approvals. The hook receives `{ channel, channelLabel, accountId }`; named-account channels should render account-scoped paths such as `channels.<channel>.accounts.<id>.execApprovals.*` instead of top-level defaults.
 - If a channel can infer stable owner-like DM identities from existing config, use `createResolvedApproverActionAuthAdapter` from `openclaw/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 plus transport/presentation facts. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, and `createApproverRestrictedNativeApprovalCapability` from `openclaw/plugin-sdk/approval-runtime`. Put the channel-specific facts behind `approvalCapability.nativeRuntime`, ideally via `createChannelApprovalNativeRuntimeAdapter(...)` or `createLazyChannelApprovalNativeRuntimeAdapter(...)`, so core can assemble the handler and own request filtering, routing, dedupe, expiry, gateway subscription, and routed-elsewhere notices. `nativeRuntime` is split into a few smaller seams:
+- `createChannelNativeOriginTargetResolver` uses the shared channel-route matcher by default for `{ to, accountId, threadId }` targets. Pass `targetsMatch` only when a channel has provider-specific equivalence rules, such as Slack timestamp prefix matching.
+- Pass `normalizeTargetForMatch` to `createChannelNativeOriginTargetResolver` when the channel needs to canonicalize provider ids before the default route matcher or a custom `targetsMatch` callback runs, while preserving the original target for delivery. Use `normalizeTarget` only when the resolved delivery target itself should be canonicalized.
 - `availability` — whether the account is configured and whether a request should be handled
 - `presentation` — map the shared approval view model into pending/resolved/expired native payloads or final actions
 - `transport` — prepare targets plus send/update/delete native approval messages

docs/plugins/sdk-migration.md

@@ -322,6 +322,30 @@ releases.
 
   </Step>
 
+  <Step title="Migrate channel route helpers">
+    New channel route code should use `openclaw/plugin-sdk/channel-route`.
+    The older route-key and comparable-target names remain as compatibility
+    aliases during the migration window, but new plugins should use the route
+    names that describe the behavior directly:
+
+    | Old helper | Modern helper |
+    | --- | --- |
+    | `channelRouteIdentityKey(...)` | `channelRouteDedupeKey(...)` |
+    | `channelRouteKey(...)` | `channelRouteCompactKey(...)` |
+    | `ComparableChannelTarget` | `ChannelRouteParsedTarget` |
+    | `resolveComparableTargetForChannel(...)` | `resolveRouteTargetForChannel(...)` |
+    | `resolveComparableTargetForLoadedChannel(...)` | `resolveRouteTargetForLoadedChannel(...)` |
+    | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` |
+    | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` |
+
+    The modern route helpers normalize `{ channel, to, accountId, threadId }`
+    consistently across native approvals, reply suppression, inbound dedupe,
+    cron delivery, and session routing. If your plugin owns custom target
+    grammar, use `resolveChannelRouteTargetWithParser(...)` to adapt that
+    parser into the same route target contract.
+
+  </Step>
+
   <Step title="Build and test">
     ```bash
     pnpm build

docs/plugins/sdk-subpaths.md

@@ -82,7 +82,8 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
     | `plugin-sdk/channel-logging` | Channel logging helpers for inbound drops and typing/ack failures |
     | `plugin-sdk/channel-send-result` | Reply result types |
     | `plugin-sdk/channel-actions` | Channel message-action helpers, plus deprecated native schema helpers kept for plugin compatibility |
-    | `plugin-sdk/channel-targets` | Target parsing/matching helpers |
+    | `plugin-sdk/channel-route` | Shared route normalization, parser-driven target resolution, thread-id stringification, dedupe/compact route keys, parsed-target types, and route/target comparison helpers |
+    | `plugin-sdk/channel-targets` | Target parsing helpers; route comparison callers should use `plugin-sdk/channel-route` |
     | `plugin-sdk/channel-contract` | Channel contract types |
     | `plugin-sdk/channel-feedback` | Feedback/reaction wiring |
     | `plugin-sdk/channel-secret-runtime` | Narrow secret-contract helpers such as `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, and secret target types |