nodmix 2026.5.25

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

@@ -0,0 +1,137 @@
+---
+summary: "Experimental channel ingress API for inbound message authorization"
+read_when:
+  - Building or migrating a messaging channel plugin
+  - Changing DM or group allowlists, route gates, command auth, event auth, or mention activation
+  - Reviewing channel ingress redaction or SDK compatibility boundaries
+title: "Channel ingress API"
+sidebarTitle: "Channel Ingress"
+---
+
+# Channel ingress API
+
+Channel ingress is the experimental access-control boundary for inbound channel
+events. Use `nodmix/plugin-sdk/channel-ingress-runtime` for receive paths.
+The older `nodmix/plugin-sdk/channel-ingress` subpath stays exported as a
+deprecated compatibility facade for third-party plugins.
+
+Plugins own platform facts and side effects. Core owns generic policy: DM/group
+allowlists, pairing-store DM entries, route gates, command gates, event auth,
+mention activation, redacted diagnostics, and admission.
+
+## Runtime Resolver
+
+```ts
+import {
+  defineStableChannelIngressIdentity,
+  resolveChannelMessageIngress,
+} from "nodmix/plugin-sdk/channel-ingress-runtime";
+
+const identity = defineStableChannelIngressIdentity({
+  key: "platform-user-id",
+  normalize: normalizePlatformUserId,
+  sensitivity: "pii",
+});
+
+const result = await resolveChannelMessageIngress({
+  channelId: "my-channel",
+  accountId,
+  identity,
+  subject: { stableId: platformUserId },
+  conversation: { kind: isGroup ? "group" : "direct", id: conversationId },
+  event: { kind: "message", authMode: "inbound", mayPair: !isGroup },
+  policy: {
+    dmPolicy: config.dmPolicy,
+    groupPolicy: config.groupPolicy,
+    groupAllowFromFallbackToAllowFrom: true,
+  },
+  allowFrom: config.allowFrom,
+  groupAllowFrom: config.groupAllowFrom,
+  accessGroups: cfg.accessGroups,
+  route,
+  readStoreAllowFrom,
+  command: hasControlCommand ? { allowTextCommands: true, hasControlCommand } : undefined,
+});
+```
+
+Do not precompute effective allowlists, command owners, or command groups. The
+resolver derives them from raw allowlists, store callbacks, route descriptors,
+access groups, policy, and conversation kind.
+
+## Result
+
+Bundled plugins should consume modern projections directly:
+
+- `ingress`: ordered gate decision and admission
+- `senderAccess`: sender/conversation authorization only
+- `routeAccess`: route and route-sender projection
+- `commandAccess`: command authorization; false when no command gate ran
+- `activationAccess`: mention/activation result
+
+Event authorization remains available on the ordered `ingress.graph` and the
+decisive `ingress.reasonCode`; no separate event projection is emitted.
+
+Deprecated third-party SDK helpers may rebuild older shapes internally. New
+bundled receive paths should not translate modern results back into local DTOs.
+
+## Access Groups
+
+`accessGroup:<name>` entries stay redacted. Core resolves static
+`message.senders` groups itself and calls `resolveAccessGroupMembership` only
+for dynamic groups that require a platform lookup. Missing, unsupported, and
+failed groups fail closed.
+
+## Event Modes
+
+| `authMode`       | Meaning                                          |
+| ---------------- | ------------------------------------------------ |
+| `inbound`        | normal inbound sender gates                      |
+| `command`        | command gates for callbacks or scoped buttons    |
+| `origin-subject` | actor must match the original message subject    |
+| `route-only`     | route gates only for route-scoped trusted events |
+| `none`           | plugin-owned internal events bypass shared auth  |
+
+Use `mayPair: false` for reactions, buttons, callbacks, and native commands.
+
+## Routes And Activation
+
+Use route descriptors for room, topic, guild, thread, or nested route policy:
+
+```ts
+route: {
+  id: "room",
+  allowed: roomAllowed,
+  enabled: roomEnabled,
+  senderPolicy: "replace",
+  senderAllowFrom: roomAllowFrom,
+  blockReason: "room_sender_not_allowlisted",
+}
+```
+
+Use `channelIngressRoutes(...)` when a plugin has several optional route
+descriptors; it filters disabled branches while keeping route facts generic and
+ordered by each descriptor's `precedence`.
+
+Mention gating is an activation gate. A mention miss returns
+`admission: "skip"` so the turn kernel does not process an observe-only turn.
+Most channels should leave activation after sender and command gates. Public
+chat surfaces that must quiet non-mentioned traffic before sender allowlist
+noise can opt into `activation.order: "before-sender"` when text-command
+bypass is disabled. Channels with implicit activation, such as replies in bot
+threads, can pass `activation.allowedImplicitMentionKinds`; the projected
+`activationAccess.shouldBypassMention` then reports when command or implicit
+activation bypassed an explicit mention.
+
+## Redaction
+
+Raw sender values and raw allowlist entries are resolver input only. They must
+not appear in resolved state, decisions, diagnostics, snapshots, or
+compatibility facts. Use opaque subject ids, entry ids, route ids, and
+diagnostic ids.
+
+## Verification
+
+```bash
+pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.ts
+pnpm plugin-sdk:api:check
+```

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

@@ -0,0 +1,458 @@
+---
+summary: "Message lifecycle API for channel plugins, including durable sends, receipts, live preview, receive ack policy, and legacy migration"
+title: "Channel message API"
+read_when:
+  - You are building or refactoring a messaging channel plugin
+  - You need durable final reply delivery, receipts, live preview finalization, or receive acknowledgement policy
+  - You are migrating from legacy reply pipeline or inbound reply dispatch helpers
+---
+
+Channel plugins should expose one `message` adapter from
+`nodmix/plugin-sdk/channel-message`. The adapter describes the native message
+lifecycle that the platform supports:
+
+```text
+receive -> route and record -> agent turn -> durable final send
+send -> render batch -> platform I/O -> receipt -> lifecycle side effects
+live preview -> final edit or fallback -> receipt
+```
+
+Core owns queueing, durability, generic retry policy, hooks, receipts, and the
+shared `message` tool. The plugin owns native send/edit/delete calls, target
+normalization, platform threading, selected quotes, notification flags, account
+state, and platform-specific side effects.
+
+Use this page together with [Building channel plugins](/plugins/sdk-channel-plugins).
+
+The `channel-message` subpath is intentionally cheap enough for hot plugin
+bootstrap files such as `channel.ts`: it exposes adapter contracts, capability
+proofs, receipts, and compatibility facades without loading outbound delivery.
+Runtime delivery helpers are available from
+`nodmix/plugin-sdk/channel-message-runtime` for monitor/send code paths that
+are already doing asynchronous message I/O.
+
+New channel and plugin send code should use the message lifecycle helpers from
+`nodmix/plugin-sdk/channel-message-runtime`: `sendDurableMessageBatch`,
+`withDurableMessageSendContext`, or `deliverInboundReplyWithMessageSendContext`.
+The older
+`deliverOutboundPayloads(...)` helper in `nodmix/plugin-sdk/outbound-runtime`
+is deprecated compatibility/runtime substrate for outbound internals, recovery,
+and legacy adapters. Do not use it for new channel or plugin send paths.
+
+`sendDurableMessageBatch(...)` returns an explicit lifecycle outcome:
+
+- `sent` - at least one visible platform message was delivered.
+- `suppressed` - no platform message should be treated as missing. Stable
+  reasons include `cancelled_by_message_sending_hook`,
+  `empty_after_message_sending_hook`, `no_visible_payload`,
+  `adapter_returned_no_identity`, and legacy `no_visible_result`.
+- `partial_failed` - at least one platform message was delivered before a later
+  payload or side effect failed. The result includes the delivered receipt prefix
+  plus the failure.
+- `failed` - no platform receipt was produced.
+
+Use `payloadOutcomes` when a batch mixes sent, suppressed, and failed payloads.
+Do not infer hook cancellation by checking whether the old direct-delivery array
+is empty.
+
+Compatibility dispatchers that still need the buffered reply dispatcher should
+build reply-prefix options with `createChannelMessageReplyPipeline(...)` from
+`nodmix/plugin-sdk/channel-message`, then call the runtime's
+`channel.turn.runPrepared(...)`. That keeps session recording and dispatch
+ordering on the shared turn lifecycle without adding another public turn wrapper.
+
+## Minimal adapter
+
+Most new channel plugins can start with a small adapter:
+
+```typescript
+import {
+  defineChannelMessageAdapter,
+  createMessageReceiptFromOutboundResults,
+} from "nodmix/plugin-sdk/channel-message";
+
+export const demoMessageAdapter = defineChannelMessageAdapter({
+  id: "demo",
+  durableFinal: {
+    capabilities: {
+      text: true,
+      replyTo: true,
+      thread: true,
+      messageSendingHooks: true,
+    },
+  },
+  send: {
+    text: async ({ cfg, to, text, accountId, replyToId, threadId, signal }) => {
+      const sent = await sendDemoMessage({
+        cfg,
+        to,
+        text,
+        accountId: accountId ?? undefined,
+        replyToId: replyToId ?? undefined,
+        threadId: threadId == null ? undefined : String(threadId),
+        signal,
+      });
+
+      return {
+        receipt: createMessageReceiptFromOutboundResults({
+          results: [{ channel: "demo", messageId: sent.id, conversationId: to }],
+          kind: "text",
+          threadId: threadId == null ? undefined : String(threadId),
+          replyToId: replyToId ?? undefined,
+        }),
+      };
+    },
+  },
+});
+```
+
+Then attach it to the channel plugin:
+
+```typescript
+export const demoPlugin = createChatChannelPlugin({
+  base: {
+    id: "demo",
+    message: demoMessageAdapter,
+    // other channel plugin fields
+  },
+});
+```
+
+Only declare capabilities that the adapter really preserves. Every declared
+capability should have a contract test.
+
+## Outbound bridge
+
+If the channel already has a compatible `outbound` adapter, prefer deriving the
+message adapter instead of duplicating send code:
+
+```typescript
+import { createChannelMessageAdapterFromOutbound } from "nodmix/plugin-sdk/channel-message";
+
+const demoMessageAdapter = createChannelMessageAdapterFromOutbound({
+  id: "demo",
+  outbound: demoOutboundAdapter,
+});
+```
+
+The bridge converts old outbound send results into `MessageReceipt` values. New
+code should pass receipts end to end and only derive legacy ids at compatibility
+edges with `listMessageReceiptPlatformIds(...)` or
+`resolveMessageReceiptPrimaryId(...)`.
+If no receive policy is supplied, `createChannelMessageAdapterFromOutbound(...)`
+uses `manual` receive acknowledgement policy. That makes plugin-owned platform
+acknowledgement explicit without changing channels that acknowledge webhooks,
+sockets, or polling offsets outside generic receive context.
+
+## Message tool sends
+
+The shared `message(action="send")` path should use the same core delivery
+lifecycle as final replies. If a channel needs provider-specific shaping for the
+tool send, implement `actions.prepareSendPayload(...)` instead of sending from
+`actions.handleAction(...)`.
+
+`prepareSendPayload(...)` receives the normalized core `ReplyPayload` plus the
+full action context. Return a payload with channel-specific data in
+`payload.channelData.<channel>` and let core call `sendMessage(...)`,
+the message lifecycle runtime, the write-ahead queue, message-sending hooks,
+retry, recovery, and ack cleanup. The lifecycle runtime may call
+`deliverOutboundPayloads(...)` internally as compatibility substrate, but channel
+plugins should not call it directly for new send behavior.
+
+Return `null` only when the send cannot be represented as a durable payload, for
+example because it contains a non-serializable component factory. Core will keep
+the legacy plugin action fallback for compatibility, but new channel send
+features should be expressible as durable payload data.
+
+```typescript
+export const demoActions: ChannelMessageActionAdapter = {
+  describeMessageTool: () => ({ actions: ["send"], capabilities: ["presentation"] }),
+  prepareSendPayload: ({ ctx, payload }) => {
+    if (ctx.action !== "send") {
+      return null;
+    }
+    return {
+      ...payload,
+      channelData: {
+        ...payload.channelData,
+        demo: {
+          ...(payload.channelData?.demo as object | undefined),
+          nativeCard: ctx.params.card,
+        },
+      },
+    };
+  },
+};
+```
+
+The outbound adapter then reads `payload.channelData.demo` inside `sendPayload`.
+This keeps platform-specific rendering in the plugin while core still owns
+persist, retry, recover, hooks, and ack.
+
+Prepared `message(action="send")` payloads and generic final-reply delivery use
+core delivery with best-effort queueing by default. Required durable queueing is
+only valid after core verifies the channel can reconcile a send whose outcome is
+unknown after a crash. If the adapter cannot implement `reconcileUnknownSend`,
+keep the prepared send path best-effort; core will still try the write-ahead
+queue, but queue persistence or uncertain crash recovery is not part of the
+required delivery contract.
+
+## Durable final capabilities
+
+Durable final delivery is opt in per side effect. Core will only use generic
+durable delivery when the adapter declares every capability needed by the
+payload and delivery options.
+
+| Capability             | Declare when                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| `text`                 | The adapter can send text and return a receipt.                                      |
+| `media`                | Media sends return receipts for every visible platform message.                      |
+| `payload`              | The adapter preserves rich reply payload semantics, not only text and one media URL. |
+| `replyTo`              | Native reply targets reach the platform.                                             |
+| `thread`               | Native thread, topic, or channel thread targets reach the platform.                  |
+| `silent`               | Notification suppression reaches the platform.                                       |
+| `nativeQuote`          | Selected quote metadata reaches the platform.                                        |
+| `messageSendingHooks`  | Core message-sending hooks can cancel or rewrite content before platform I/O.        |
+| `batch`                | Multi-part rendered batches are replayable as one durable plan.                      |
+| `reconcileUnknownSend` | The adapter can resolve `unknown_after_send` recovery without blind replay.          |
+| `afterSendSuccess`     | Channel-local after-send side effects run once.                                      |
+| `afterCommit`          | Channel-local after-commit side effects run once.                                    |
+
+Best-effort final delivery does not require `reconcileUnknownSend`; it uses the
+shared lifecycle when the adapter preserves the payload's visible semantics, and
+falls back to direct platform I/O if queue persistence is unavailable. Required
+durable final delivery must explicitly require `reconcileUnknownSend`. If the
+adapter cannot determine whether a started/unknown send reached the platform,
+do not declare that capability; core will reject required durable delivery
+before queueing.
+
+When a caller needs durable delivery, derive requirements instead of building
+maps by hand:
+
+```typescript
+import { deriveDurableFinalDeliveryRequirements } from "nodmix/plugin-sdk/channel-message";
+
+const requiredCapabilities = deriveDurableFinalDeliveryRequirements({
+  payload,
+  replyToId,
+  threadId,
+  silent,
+  payloadTransport: true,
+  extraCapabilities: {
+    nativeQuote: hasSelectedQuote(payload),
+  },
+});
+```
+
+`messageSendingHooks` is required by default. Set `messageSendingHooks: false`
+only for a path that intentionally cannot run global message-sending hooks.
+
+## Durable send contract
+
+A durable final send has stricter semantics than legacy channel-owned delivery:
+
+- Create the durable intent before platform I/O.
+- If durable delivery returns a handled result, do not fall back to legacy send.
+- Treat hook cancellation and no-send results as terminal.
+- Treat `unsupported` as a pre-intent result only.
+- For required durability, fail before platform I/O if the queue cannot record
+  that platform send has started.
+- For required final delivery and required prepared message-tool sends,
+  preflight `reconcileUnknownSend`; recovery must be able to ack an
+  already-sent message or replay only after the adapter proves the original send
+  did not happen.
+- For `best_effort`, queue write failures may fall back to direct platform I/O.
+- Forward abort signals to media loading and platform sends.
+- Run after-commit hooks after queue ack; direct best-effort fallback runs them
+  after successful platform I/O because there is no durable queue commit.
+- Return receipts for every visible platform message id.
+- Use `reconcileUnknownSend` when a platform can check whether an uncertain send
+  already reached the user.
+
+This contract avoids duplicate sends after crashes and avoids bypassing
+message-sending cancellation hooks.
+
+## Receipts
+
+`MessageReceipt` is the new internal record of what the platform accepted:
+
+```typescript
+type MessageReceipt = {
+  primaryPlatformMessageId?: string;
+  platformMessageIds: string[];
+  parts: MessageReceiptPart[];
+  threadId?: string;
+  replyToId?: string;
+  editToken?: string;
+  deleteToken?: string;
+  sentAt: number;
+  raw?: readonly MessageReceiptSourceResult[];
+};
+```
+
+Use `createMessageReceiptFromOutboundResults(...)` when adapting an existing
+send result. Use `createPreviewMessageReceipt(...)` when a live preview message
+becomes the final receipt. Avoid adding new owner-local `messageIds` fields.
+Legacy `ChannelDeliveryResult.messageIds` is still produced at compatibility
+edges.
+
+## Live preview
+
+Channels that stream draft previews or progress updates should declare live
+capabilities:
+
+```typescript
+const demoMessageAdapter = defineChannelMessageAdapter({
+  id: "demo",
+  live: {
+    capabilities: {
+      draftPreview: true,
+      previewFinalization: true,
+      progressUpdates: true,
+      quietFinalization: true,
+    },
+    finalizer: {
+      capabilities: {
+        finalEdit: true,
+        normalFallback: true,
+        discardPending: true,
+        previewReceipt: true,
+        retainOnAmbiguousFailure: true,
+      },
+    },
+  },
+});
+```
+
+Use `defineFinalizableLivePreviewAdapter(...)` and
+`deliverWithFinalizableLivePreviewAdapter(...)` for runtime finalization. The
+finalizer decides whether the final reply edits the preview in place, sends a
+normal fallback, discards pending preview state, keeps an ambiguous failed edit
+without duplicating the message, and returns the final receipt.
+
+## Receive ack policy
+
+Inbound receivers that control platform acknowledgement timing should declare
+receive policy:
+
+```typescript
+const demoMessageAdapter = defineChannelMessageAdapter({
+  id: "demo",
+  receive: {
+    defaultAckPolicy: "after_agent_dispatch",
+    supportedAckPolicies: ["after_receive_record", "after_agent_dispatch"],
+  },
+});
+```
+
+Adapters that do not declare receive policy default to:
+
+```typescript
+{
+  receive: {
+    defaultAckPolicy: "manual",
+    supportedAckPolicies: ["manual"],
+  },
+}
+```
+
+Use the default when the platform has no acknowledgement to defer, already
+acknowledges before asynchronous processing, or needs protocol-specific response
+semantics. Declare one of the staged policies only when the receiver actually
+uses receive context to move platform acknowledgement later.
+
+Policies:
+
+| Policy                 | Use when                                                                                 |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `after_receive_record` | The platform can be acknowledged after the inbound event is parsed and recorded.         |
+| `after_agent_dispatch` | The platform should wait until the agent dispatch has been accepted.                     |
+| `after_durable_send`   | The platform should wait until final delivery has a durable decision.                    |
+| `manual`               | The plugin owns acknowledgement because platform semantics do not match a generic stage. |
+
+Use `createMessageReceiveContext(...)` in receivers that defer ack state, and
+`shouldAckMessageAfterStage(...)` when the receiver needs to test whether a
+stage has satisfied the configured policy.
+
+## Contract tests
+
+Capability declarations are part of the plugin contract. Back them with tests:
+
+```typescript
+import {
+  verifyChannelMessageAdapterCapabilityProofs,
+  verifyChannelMessageLiveCapabilityAdapterProofs,
+  verifyChannelMessageLiveFinalizerProofs,
+  verifyChannelMessageReceiveAckPolicyAdapterProofs,
+} from "nodmix/plugin-sdk/channel-message";
+
+it("backs declared message capabilities", async () => {
+  await expect(
+    verifyChannelMessageAdapterCapabilityProofs({
+      adapterName: "demo",
+      adapter: demoMessageAdapter,
+      proofs: {
+        text: async () => {
+          const result = await demoMessageAdapter.send!.text!(textCtx);
+          expect(result.receipt.platformMessageIds).toContain("msg-1");
+        },
+        replyTo: async () => {
+          await demoMessageAdapter.send!.text!({ ...textCtx, replyToId: "parent-1" });
+          expect(sendDemoMessage).toHaveBeenCalledWith(
+            expect.objectContaining({
+              replyToId: "parent-1",
+            }),
+          );
+        },
+        messageSendingHooks: () => {
+          expect(demoMessageAdapter.durableFinal!.capabilities!.messageSendingHooks).toBe(true);
+        },
+      },
+    }),
+  ).resolves.toContainEqual({ capability: "text", status: "verified" });
+});
+```
+
+Add live and receive proof suites when the adapter declares those features. A
+missing proof should fail the test rather than silently widening the durable
+surface.
+
+## Deprecated compatibility APIs
+
+These APIs remain importable for third-party compatibility. Do not use them for
+new channel code.
+
+| Deprecated API                               | Replacement                                                                                                                |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `nodmix/plugin-sdk/channel-reply-pipeline` | `nodmix/plugin-sdk/channel-message`                                                                                      |
+| `createChannelTurnReplyPipeline(...)`        | `createChannelMessageReplyPipeline(...)` for compatibility dispatchers, or a `message` adapter for new channel code        |
+| `buildChannelMessageReplyDispatchBase(...)`  | `createChannelMessageReplyPipeline(...)` plus `channel.turn.runPrepared(...)`, or a `message` adapter for new channel code |
+| `dispatchChannelMessageReplyWithBase(...)`   | `createChannelMessageReplyPipeline(...)` plus `channel.turn.runPrepared(...)`, or a `message` adapter for new channel code |
+| `recordChannelMessageReplyDispatch(...)`     | `createChannelMessageReplyPipeline(...)` plus `channel.turn.runPrepared(...)`, or a `message` adapter for new channel code |
+| `deliverOutboundPayloads(...)`               | `sendDurableMessageBatch(...)` or `deliverInboundReplyWithMessageSendContext(...)` from `channel-message-runtime`          |
+| `deliverDurableInboundReplyPayload(...)`     | `deliverInboundReplyWithMessageSendContext(...)` from `nodmix/plugin-sdk/channel-message-runtime`                        |
+| `dispatchInboundReplyWithBase(...)`          | `createChannelMessageReplyPipeline(...)` plus `channel.turn.runPrepared(...)`, or a `message` adapter for new channel code |
+| `recordInboundSessionAndDispatchReply(...)`  | `createChannelMessageReplyPipeline(...)` plus `channel.turn.runPrepared(...)`, or a `message` adapter for new channel code |
+| `resolveChannelSourceReplyDeliveryMode(...)` | `resolveChannelMessageSourceReplyDeliveryMode(...)`                                                                        |
+| `deliverFinalizableDraftPreview(...)`        | `defineFinalizableLivePreviewAdapter(...)` plus `deliverWithFinalizableLivePreviewAdapter(...)`                            |
+| `DraftPreviewFinalizerDraft`                 | `LivePreviewFinalizerDraft`                                                                                                |
+| `DraftPreviewFinalizerResult`                | `LivePreviewFinalizerResult`                                                                                               |
+
+Compatibility dispatchers can still use `createReplyPrefixContext(...)`,
+`createReplyPrefixOptions(...)`, and `createTypingCallbacks(...)` through the
+message facade. New lifecycle code should avoid the old
+`channel-reply-pipeline` subpath.
+
+## Migration checklist
+
+1. Add `message: defineChannelMessageAdapter(...)` or
+   `message: createChannelMessageAdapterFromOutbound(...)` to the channel plugin.
+2. Return `MessageReceipt` from text, media, and payload sends.
+3. Declare only capabilities backed by native behavior and tests.
+4. Replace hand-written durable requirement maps with
+   `deriveDurableFinalDeliveryRequirements(...)`.
+5. Move preview finalization through the live preview helpers when the channel
+   edits draft messages in place.
+6. Declare receive ack policy only when the receiver can really defer platform
+   acknowledgement.
+7. Keep legacy reply dispatch helpers only at compatibility edges.