@zhin.js/adapter-discord 1.1.26 → 1.1.28

package/lib/endpoint.js

@@ -1,15 +1,17 @@
 import { createDiscordSelfProfile, createDiscordRestSelfProfile } from './self-profile.js';
 import { DiscordRestRequestError } from './rest-request-error.js';
+import { isDiscordChannelObfuscated } from './channel-visibility.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
 import { Client, ChannelType } from 'discord.js';
 import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, createEndpointOperation, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { connectDiscordGatewayClient, discordClientOptions, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
-import { discordInboundConversation, formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
+import { connectDiscordGatewayClient, discordClientOptions, DEFAULT_INTENTS, toMessageCreateOptions, } from './gateway.js';
+import { discordChannelOf, discordInboundConversation, formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
 import { registerDiscordInteractionRoutes } from './webhook.js';
 import { receiveDiscordGuildMemberSideEvent } from './side-event-dispatch.js';
+import { discordGuildPermissionNamesFromChannelBitfield, discordPermissionNames, discordSenderStanding, discordStandingFromPermissions, } from './sender-standing.js';
 const DISCORD_API = 'https://discord.com/api/v10';
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
@@ -137,11 +139,11 @@ export class DiscordGatewayEndpoint extends Client {
     }
     async #sendFramework({ conversation, payload, signal }) {
         const body = formatOutboundBody(payload);
-        const snowflake = await this.#sendBody({ channelId: conversation.id, body, signal });
+        const snowflake = await this.#sendBody({ channelId: discordChannelOf(conversation), body, signal });
         this.#logger.debug(formatCompact({
             op: 'discord_send',
             endpoint: this.#options.config.id,
-            target: conversation.id,
+            target: discordChannelOf(conversation),
             messageId: snowflake,
         }));
         return snowflake;
@@ -150,7 +152,7 @@ export class DiscordGatewayEndpoint extends Client {
         if (!message.id)
             return;
         const operation = createEndpointOperation({ signal });
-        const channel = await operation.prepare(() => this.#requireClient().channels.fetch(message.conversation.id));
+        const channel = await operation.prepare(() => this.#requireClient().channels.fetch(discordChannelOf(message.conversation)));
         if (!channel?.isTextBased() || !channel.messages)
             return;
         const msg = await operation.prepare(() => channel.messages.fetch(message.id));
@@ -163,6 +165,7 @@ export class DiscordGatewayEndpoint extends Client {
         if (msg.authorBot)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), msg);
+        const platform = discordSenderStanding(msg);
         void this[endpointSpec].events.emit('message.receive', {
             conversation,
             event: msg.event,
@@ -173,7 +176,7 @@ export class DiscordGatewayEndpoint extends Client {
             sender: {
                 id: msg.authorId,
                 name: senderDisplayName(msg) || undefined,
-                ...(resolveSenderRole(msg) ? { roles: [resolveSenderRole(msg)] } : {}),
+                ...(platform ? { platform } : {}),
             },
             endpointId: this.#options.config.id,
             ...(msg.mentionedBot ? { mentioned: true } : {}),
@@ -183,7 +186,7 @@ export class DiscordGatewayEndpoint extends Client {
                 userId: msg.authorId,
                 guildId: msg.guildId,
                 permissions: msg.permissionTokens,
-                role: resolveSenderRole(msg),
+                role: platform?.standing,
             }),
         }).catch((err) => {
             this.#logger.warn(formatCompact({
@@ -221,7 +224,7 @@ export class DiscordGatewayEndpoint extends Client {
         });
     }
     async #addReaction({ message, emoji, hint, signal }) {
-        const channelId = hint?.channelId ?? message.conversation.id;
+        const channelId = hint?.channelId ?? discordChannelOf(message.conversation);
         if (!channelId || !message.id)
             return null;
         const operation = createEndpointOperation({ signal });
@@ -325,6 +328,8 @@ export class DiscordRestClient {
         return this.request({ method: 'DELETE', path: `/channels/${channelId}/messages/${messageId}`, signal });
     }
 }
+const APP_PERMISSIONS_TTL_MS = 10 * 60_000;
+const APP_PERMISSIONS_MAX = 1_000;
 export class DiscordInteractionsEndpoint extends DiscordRestClient {
     [endpointSpec];
     #logger;
@@ -333,6 +338,8 @@ export class DiscordInteractionsEndpoint extends DiscordRestClient {
     #routeReleases = [];
     #open = false;
     #started = false;
+    /** Latest interaction `app_permissions` per guild (guild-level names), for the Bot's own standing. */
+    #appPermissions = new Map();
     #control = Object.freeze({
         recall: request => this.#recallMessage(request),
     });
@@ -347,6 +354,12 @@ export class DiscordInteractionsEndpoint extends DiscordRestClient {
         this[endpointSpec] = createEndpointSpecification(this, {
             start: () => this.#startFramework(), open: () => this.#openFramework(), close: () => this.#closeFramework(),
             stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
+            // Interactions mode has no gateway session to read the bot's guild member: its own standing
+            // comes from the latest interaction's `app_permissions` in that guild (ADR 0056 §1), reduced
+            // to guild-level names like senders; without a recent interaction it stays unknown.
+            management: Object.freeze({
+                inspectSelfStanding: async ({ conversation }) => this.#selfStandingFromInteractions(conversation),
+            }),
             control: this.#control, content: this.#content,
             profile: createDiscordRestSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
         });
@@ -384,18 +397,41 @@ export class DiscordInteractionsEndpoint extends DiscordRestClient {
     }
     async #sendFramework({ conversation, payload, signal }) {
         const body = formatOutboundBody(payload);
-        const data = await this.createMessage({ channelId: conversation.id, body, signal });
+        const data = await this.createMessage({ channelId: discordChannelOf(conversation), body, signal });
         return data.id ?? '';
     }
     async #recallMessage({ message, signal }) {
         if (!message.id)
             return;
-        await this.deleteMessage({ channelId: message.conversation.id, messageId: message.id, signal });
+        await this.deleteMessage({ channelId: discordChannelOf(message.conversation), messageId: message.id, signal });
+    }
+    #selfStandingFromInteractions(conversation) {
+        const guildId = conversation.kind === 'channel' && conversation.parent?.kind === 'channel' ? conversation.parent.id : undefined;
+        const entry = guildId ? this.#appPermissions.get(guildId) : undefined;
+        if (!entry || Date.now() - entry.at > APP_PERMISSIONS_TTL_MS)
+            return undefined;
+        // The guild owner is not visible to an interaction; `administrator` still reads as `admin`.
+        return { standing: discordStandingFromPermissions(entry.names), ...(entry.names.length ? { permissions: entry.names } : {}) };
+    }
+    #recordAppPermissions(msg) {
+        const appPermissions = msg.event?.app_permissions;
+        if (!msg.guildId || appPermissions === undefined)
+            return;
+        this.#appPermissions.delete(msg.guildId);
+        this.#appPermissions.set(msg.guildId, { names: discordGuildPermissionNamesFromChannelBitfield(appPermissions), at: Date.now() });
+        while (this.#appPermissions.size > APP_PERMISSIONS_MAX) {
+            const oldest = this.#appPermissions.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#appPermissions.delete(oldest);
+        }
     }
     admit(msg) {
         if (!this.#open)
             return;
+        this.#recordAppPermissions(msg);
         const conversation = discordInboundConversation(String(this.#options.id), msg);
+        const platform = discordSenderStanding(msg);
         void this[endpointSpec].events.emit('message.receive', {
             conversation,
             event: msg.event,
@@ -406,7 +442,7 @@ export class DiscordInteractionsEndpoint extends DiscordRestClient {
             sender: {
                 id: msg.authorId,
                 name: senderDisplayName(msg) || undefined,
-                ...(resolveSenderRole(msg) ? { roles: [resolveSenderRole(msg)] } : {}),
+                ...(platform ? { platform } : {}),
             },
             endpointId: this.#options.config.id,
             metadata: Object.freeze({
@@ -474,7 +510,7 @@ async function resolveDiscordContent(fetch, token, reference, context) {
     }
     try {
         context.signal.throwIfAborted();
-        const response = await fetch(`${DISCORD_API}/channels/${reference.message.conversation.id}/messages/${reference.message.id}`, { headers: { Authorization: `Bot ${token}` }, signal: context.signal });
+        const response = await fetch(`${DISCORD_API}/channels/${discordChannelOf(reference.message.conversation)}/messages/${reference.message.id}`, { headers: { Authorization: `Bot ${token}` }, signal: context.signal });
         if (response.status === 404)
             return Object.freeze({ status: 'not_found', code: 'discord_message_not_found' });
         if (response.status === 403)
@@ -515,9 +551,34 @@ async function resolveDiscordContent(fetch, token, reference, context) {
 /**
  * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
  * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
+ * listChannels 会过滤带 CHANNEL_OBFUSCATED flag 的混淆频道（见 channel-visibility.ts）。
  */
 export function createDiscordEndpointManagement(requireClient) {
     return Object.freeze({
+        /**
+         * ADR 0056 §1: the Bot's own guild member in the conversation's guild — guild owner → `owner`;
+         * `administrator` / `moderate_members` → `admin`; roles and **guild-level** permission names
+         * (`GuildMember.permissions`, as for senders) so `bot-permission:*` and `platform-permission:*`
+         * read the same scope. Channel overwrites are left to the platform at execution time.
+         */
+        async inspectSelfStanding({ conversation, signal }) {
+            if (conversation.kind === 'private')
+                return undefined;
+            const operation = createEndpointOperation({ signal });
+            const client = requireClient();
+            const channel = await operation.run(() => client.channels.fetch(conversation.threadId ?? conversation.id));
+            if (!channel || !('guild' in channel) || !client.user)
+                return undefined;
+            const guild = channel.guild;
+            const me = guild.members.me ?? await operation.run(() => guild.members.fetchMe());
+            const permissions = me.permissions;
+            const names = permissions ? discordPermissionNames(bit => permissions.has(bit)) : [];
+            const roles = [...me.roles.cache.values()]
+                .filter(role => role.id !== guild.id)
+                .map(role => (role.name ? { id: String(role.id), name: String(role.name) } : { id: String(role.id) }));
+            const standing = discordStandingFromPermissions(names, guild.ownerId === client.user.id);
+            return { standing, ...(roles.length ? { roles } : {}), ...(names.length ? { permissions: names } : {}) };
+        },
         async listGroups(request = {}) {
             return createEndpointOperation(request).run(() => {
                 const groups = [];
@@ -545,6 +606,9 @@ export function createDiscordEndpointManagement(requireClient) {
                             continue;
                         if (channel.type !== ChannelType.GuildText)
                             continue;
+                        // 机器人无 VIEW_CHANNEL 的频道会被 Gateway 混淆下发（HTTP 列表已不返回），默认过滤以保持两条路径一致。
+                        if (isDiscordChannelObfuscated(channel))
+                            continue;
                         channels.push({
                             id: String(channel.id),
                             name: channel.name ? String(channel.name) : undefined,

package/lib/gateway.d.ts

@@ -5,6 +5,7 @@ export declare const DEFAULT_INTENTS: GatewayIntentBits[];
 /** Native SDK surface; tests inject transport below the Client rather than replacing its identity. */
 export type DiscordClientTransport = Client;
 export declare function discordClientOptions(intents: readonly number[], gatewayFaultProxyUrl?: string, restOptions?: Partial<RESTOptions>): ClientOptions;
+/** Normalized standing word (`owner` / `admin` / `member`); `undefined` outside a guild. */
 export declare function resolveSenderRole(msg: DiscordInboundMessage): string | undefined;
 export declare function normalizeDiscordMessage(raw: unknown): DiscordInboundMessage | null;
 export declare function toMessageCreateOptions(body: DiscordOutboundBody): Promise<MessageCreateOptions>;

package/lib/gateway.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { Partials, GatewayIntentBits, EmbedBuilder, AttachmentBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle, REST, Routes, PermissionFlagsBits, } from 'discord.js';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { activityTypeCode, resolveChannelKind, } from './protocol.js';
+import { discordPermissionNames, discordSenderStanding } from './sender-standing.js';
 const logger = getLogger('discord');
 export const DEFAULT_INTENTS = [
     GatewayIntentBits.Guilds,
@@ -16,15 +17,14 @@ export const DEFAULT_INTENTS = [
 export function discordClientOptions(intents, gatewayFaultProxyUrl, restOptions = {}) {
     return { rest: { ...restOptions, retries: 0, rejectOnRateLimit: () => true }, intents: [...intents], partials: [Partials.Channel], ...(gatewayFaultProxyUrl ? { ws: { buildStrategy: manager => new DiscordFaultProxyStrategy(manager, gatewayFaultProxyUrl) } } : {}) };
 }
+/** Normalized standing word (`owner` / `admin` / `member`); `undefined` outside a guild. */
 export function resolveSenderRole(msg) {
-    if (msg.isGuildOwner)
-        return 'owner';
-    const tokens = msg.permissionTokens ?? [];
-    if (tokens.includes('ADMINISTRATOR') || tokens.includes('MODERATE_MEMBERS'))
-        return 'admin';
-    if (msg.guildId)
-        return 'member';
-    return undefined;
+    return discordSenderStanding(msg)?.standing;
+}
+/** A discord.js thread channel's parent channel id (threads share their parent's conversation key, ADR 0056 §2). */
+function threadParentOf(channel) {
+    const thread = channel;
+    return thread && typeof thread.isThread === 'function' && thread.isThread() && thread.parentId ? thread.parentId : undefined;
 }
 export function normalizeDiscordMessage(raw) {
     if (!raw || typeof raw !== 'object')
@@ -33,6 +33,8 @@ export function normalizeDiscordMessage(raw) {
     if (!msg.author || !msg.channel)
         return null;
     const permissionTokens = [];
+    let platformPermissions = [];
+    let authorRoles = [];
     let isGuildOwner = false;
     const member = msg.member;
     const guild = msg.guild;
@@ -48,6 +50,13 @@ export function normalizeDiscordMessage(raw) {
             if (member.permissions.has(bit))
                 permissionTokens.push(name);
         }
+        platformPermissions = discordPermissionNames(bit => member.permissions.has(bit));
+        const cache = member.roles?.cache;
+        if (cache && typeof cache.values === 'function') {
+            authorRoles = [...cache.values()]
+                .filter((role) => role && role.id && role.id !== guild.id)
+                .map((role) => (role.name ? { id: String(role.id), name: String(role.name) } : { id: String(role.id) }));
+        }
         if (guild.ownerId === msg.author.id) {
             isGuildOwner = true;
             permissionTokens.push('guild_owner', 'ADMINISTRATOR');
@@ -60,6 +69,7 @@ export function normalizeDiscordMessage(raw) {
         content: msg.content ?? '',
         channelId: msg.channel.id,
         channelKind: resolveChannelKind(msg.channel.type),
+        ...(threadParentOf(msg.channel) ? { threadParentId: threadParentOf(msg.channel) } : {}),
         authorId: msg.author.id,
         authorName: member?.displayName || msg.author.displayName || msg.author.username,
         authorBot: msg.author.bot,
@@ -67,6 +77,8 @@ export function normalizeDiscordMessage(raw) {
         guildId: guild?.id,
         isGuildOwner,
         permissionTokens,
+        ...(platformPermissions.length ? { platformPermissions } : {}),
+        ...(authorRoles.length ? { authorRoles } : {}),
         attachments: [...msg.attachments.values()].map((a) => ({
             id: a.id,
             name: a.name ?? undefined,
@@ -256,6 +268,7 @@ export async function connectDiscordGatewayClient(client, config, handlers, sign
                     customId: interaction.customId,
                     channelId,
                     channelKind: interaction.channel ? resolveChannelKind(interaction.channel.type) : interaction.guildId ? 'channel' : 'private',
+                    ...(threadParentOf(interaction.channel) ? { threadParentId: threadParentOf(interaction.channel) } : {}),
                     ...(interaction.guildId ? { guildId: interaction.guildId } : {}),
                     userId: interaction.user.id,
                     userName: interaction.user.username || interaction.user.displayName || interaction.user.id,

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 export { activityTypeCode, formatButtonContent, formatInboundContent, formatOutboundBody, resolveChannelKind, resolveDiscordConfig, senderDisplayName, type DiscordActivity, type DiscordEndpointConfig, type DiscordButtonInbound, type DiscordInboundAttachment, type DiscordInboundMessage, type DiscordOutboundBody, type DiscordWireSegment, type ResolvedDiscordConfig, type ResolvedDiscordGatewayConfig, type ResolvedDiscordInteractionsConfig, } from './protocol.js';
 export { requireDiscordGatewayClient, type DiscordClient, type DiscordClientEventMap, } from './client.js';
-export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, } from './platform-permit.js';
+export { platformPermit } from './platform-permit.js';
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, type DiscordClientTransport, type DiscordEndpointOptions, type DiscordInteractionsEndpointOptions, } from './endpoint.js';
 export { connectDiscordGatewayClient, discordClientOptions, normalizeDiscordMessage, resolveSenderRole, toMessageCreateOptions, type DiscordGatewayConnectHandlers, } from './gateway.js';
 export { handleDiscordInteractionRequest, registerDiscordInteractionRoutes, type DiscordInteractionsHandler, } from './webhook.js';

package/lib/index.js

@@ -1,6 +1,6 @@
 export { activityTypeCode, formatButtonContent, formatInboundContent, formatOutboundBody, resolveChannelKind, resolveDiscordConfig, senderDisplayName, } from './protocol.js';
 export { requireDiscordGatewayClient, } from './client.js';
-export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, } from './platform-permit.js';
+export { platformPermit } from './platform-permit.js';
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from './endpoint.js';
 export { connectDiscordGatewayClient, discordClientOptions, normalizeDiscordMessage, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
 export { handleDiscordInteractionRequest, registerDiscordInteractionRoutes, } from './webhook.js';

package/lib/platform-permit.d.ts

@@ -1,14 +1,7 @@
 /**
- * Discord platform permit — Guild 权限位
+ * Discord platform permit helper（ADR 0056 §5）。
+ *
+ * 平台身份由适配器上报到 `sender.platform`，permit 由内置评估器（`@zhin.js/permission`）判断；
+ * 适配器不再导出自有的 permit 解析器或检查函数。
  */
-import type { PermissionSubject } from '@zhin.js/permission';
 export declare function platformPermit(perm: string): string;
-export declare function discordGroupPermitResolver(logicalPerm: string): string;
-export declare function normalizeDiscordSenderForPermit(input: {
-    isOwner?: boolean;
-    permissions?: string[];
-}): {
-    role?: string;
-    permissions?: string[];
-};
-export declare function checkDiscordPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -1,42 +1,9 @@
-const ADAPTER = 'discord';
+/**
+ * Discord platform permit helper（ADR 0056 §5）。
+ *
+ * 平台身份由适配器上报到 `sender.platform`，permit 由内置评估器（`@zhin.js/permission`）判断；
+ * 适配器不再导出自有的 permit 解析器或检查函数。
+ */
 export function platformPermit(perm) {
-    return `platform(${ADAPTER},${perm})`;
-}
-const FACTORY_PERM_MAP = {
-    scene_admin: 'moderate_members',
-    scene_owner: 'guild_owner',
-};
-export function discordGroupPermitResolver(logicalPerm) {
-    return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
-}
-export function normalizeDiscordSenderForPermit(input) {
-    const permissions = [...(input.permissions ?? [])];
-    if (input.isOwner) {
-        permissions.push('guild_owner', 'ADMINISTRATOR');
-        return { role: 'owner', permissions };
-    }
-    if (permissions.includes('ADMINISTRATOR')) {
-        return { role: 'admin', permissions };
-    }
-    if (permissions.includes('MODERATE_MEMBERS') || permissions.includes('MANAGE_GUILD')) {
-        return { role: 'admin', permissions };
-    }
-    return { role: 'member', permissions };
-}
-export function checkDiscordPlatformPermit(perm, subject) {
-    const role = subject.sender?.role?.[0];
-    const permissions = subject.sender?.permissions ?? [];
-    const has = (t) => permissions.includes(t);
-    switch (perm) {
-        case 'guild_owner':
-            return role === 'owner' || has('guild_owner');
-        case 'moderate_members':
-            return role === 'owner' || role === 'admin' || has('ADMINISTRATOR') || has('MODERATE_MEMBERS');
-        case 'manage_roles':
-            return role === 'owner' || has('ADMINISTRATOR') || has('MANAGE_ROLES');
-        case 'manage_channels':
-            return role === 'owner' || has('ADMINISTRATOR') || has('MANAGE_CHANNELS');
-        default:
-            return false;
-    }
+    return `platform-permission:${perm}`;
 }

package/lib/protocol.d.ts

@@ -68,8 +68,17 @@ export interface DiscordInboundMessage {
     readonly authorBot?: boolean;
     readonly createdTimestamp: number;
     readonly guildId?: string;
+    /** The message was sent in a thread: its parent channel (the thread itself is `channelId`). */
+    readonly threadParentId?: string;
     readonly isGuildOwner?: boolean;
     readonly permissionTokens?: readonly string[];
+    /** ADR 0056 §1: guild permission flags as snake_case names (`ban_members`, …). */
+    readonly platformPermissions?: readonly string[];
+    /** ADR 0056 §1: the member's guild roles (`@everyone` excluded). */
+    readonly authorRoles?: readonly {
+        readonly id: string;
+        readonly name?: string;
+    }[];
     readonly attachments?: readonly DiscordInboundAttachment[];
     readonly embedTitles?: readonly string[];
     readonly stickerNames?: readonly string[];
@@ -85,6 +94,8 @@ export interface DiscordButtonInbound {
     readonly customId: string;
     readonly channelId: string;
     readonly channelKind: 'private' | 'group' | 'channel';
+    /** Pressed inside a thread: its parent channel. */
+    readonly threadParentId?: string;
     readonly userId: string;
     readonly userName: string;
     readonly sourceMessageId?: string;
@@ -125,13 +136,18 @@ export declare function resolveChannelKind(channelType: number | string | undefi
 /**
  * 入站归一化 → ConversationRef：DM → 'private'；GroupDM → 'group'；
  * guild 频道 → 'channel' + guild 容器进 parent（guild 是频道容器，kind 'channel'）。
+ * 线程（thread）：会话 id 是父频道、`threadId` 是线程频道（ConversationRef 的子话题约定），
+ * 所以父频道上的角色 / 功能配置在线程里同样生效（ADR 0056 §2）；出站用 {@link discordChannelOf}。
  * endpoint.adapter = owner PluginId（CapabilityId 以 \0 分隔）。
  */
 export declare function discordInboundConversation(endpointKey: string, msg: {
     readonly channelId: string;
     readonly channelKind: 'private' | 'group' | 'channel';
     readonly guildId?: string;
+    readonly threadParentId?: string;
 }): ConversationRef;
+/** The Discord channel a conversation's messages live in: the thread when there is one. */
+export declare function discordChannelOf(conversation: Pick<ConversationRef, 'id' | 'threadId'>): string;
 export declare function senderDisplayName(msg: DiscordInboundMessage): string;
 /** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export declare function formatInboundContent(msg: DiscordInboundMessage): string;
@@ -158,4 +174,6 @@ export declare function activityTypeCode(type: DiscordActivity['type']): number;
 export declare const DISCORD_SIGNATURE_MAX_AGE_MS: number;
 export declare function verifyDiscordInteractionSignature(publicKeyHex: string, body: string, signature: string, timestamp: string, nowMs?: number): boolean;
 export declare function formatSlashCommandContent(interaction: Record<string, unknown>): string;
+/** Parent channel of a raw API channel object when it is a thread. */
+export declare function discordThreadParentOf(channel: unknown): string | undefined;
 export declare function interactionToInboundMessage(interaction: Record<string, unknown>): DiscordInboundMessage;

package/lib/protocol.js

@@ -2,6 +2,7 @@ import { validateDiscordGatewayFaultProxy } from './gateway-fault-proxy.js';
 /** Discord Gateway protocol helpers. Canonicalization is owned by Core. */
 import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
 import { isMediaRef } from '@zhin.js/im-contract';
+import { discordGuildPermissionNamesFromChannelBitfield } from './sender-standing.js';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('discord');
 export function resolveDiscordConfig(config) {
@@ -56,18 +57,26 @@ export function resolveChannelKind(channelType) {
 /**
  * 入站归一化 → ConversationRef：DM → 'private'；GroupDM → 'group'；
  * guild 频道 → 'channel' + guild 容器进 parent（guild 是频道容器，kind 'channel'）。
+ * 线程（thread）：会话 id 是父频道、`threadId` 是线程频道（ConversationRef 的子话题约定），
+ * 所以父频道上的角色 / 功能配置在线程里同样生效（ADR 0056 §2）；出站用 {@link discordChannelOf}。
  * endpoint.adapter = owner PluginId（CapabilityId 以 \0 分隔）。
  */
 export function discordInboundConversation(endpointKey, msg) {
+    const thread = msg.channelKind === 'channel' && msg.threadParentId && msg.threadParentId !== msg.channelId;
     return {
         endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
         kind: msg.channelKind,
-        id: msg.channelId,
+        id: thread ? msg.threadParentId : msg.channelId,
+        ...(thread ? { threadId: msg.channelId } : {}),
         ...(msg.guildId && msg.channelKind === 'channel'
             ? { parent: { kind: 'channel', id: msg.guildId } }
             : {}),
     };
 }
+/** The Discord channel a conversation's messages live in: the thread when there is one. */
+export function discordChannelOf(conversation) {
+    return conversation.threadId ?? conversation.id;
+}
 export function senderDisplayName(msg) {
     return msg.authorName || msg.authorId;
 }
@@ -253,6 +262,7 @@ export function formatOutboundBody(payload) {
                 embeds.push({ title: String(data.title ?? ''), url: String(data.url ?? ''), description: String(data.description ?? data.content ?? ''), ...(data.image ? { image: { url: String(data.image) } } : {}) });
                 break;
             case 'embed':
+            case 'discord:embed':
                 embeds.push({ ...data });
                 break;
             case 'keyboard': {
@@ -338,18 +348,37 @@ export function formatSlashCommandContent(interaction) {
     }
     return parts.join(' ');
 }
+/** Thread channel types (announcement / public / private thread) carry `parent_id`, the channel they belong to. */
+const THREAD_CHANNEL_TYPES = new Set([10, 11, 12]);
+/** Parent channel of a raw API channel object when it is a thread. */
+export function discordThreadParentOf(channel) {
+    if (!channel || typeof channel !== 'object')
+        return undefined;
+    const raw = channel;
+    return THREAD_CHANNEL_TYPES.has(Number(raw.type)) && typeof raw.parent_id === 'string' && raw.parent_id ? raw.parent_id : undefined;
+}
 export function interactionToInboundMessage(interaction) {
-    const user = interaction.member?.user
+    const member = interaction.member;
+    const user = member?.user
         ?? interaction.user;
+    const guildId = interaction.guild_id != null ? String(interaction.guild_id) : undefined;
+    // ADR 0056 §1: guild-level names only (the interaction bitfield includes channel overwrites).
+    const platformPermissions = guildId ? discordGuildPermissionNamesFromChannelBitfield(member?.permissions) : [];
+    const authorRoles = guildId && Array.isArray(member?.roles)
+        ? member.roles.map(String).filter((id) => id && id !== guildId).map((id) => ({ id }))
+        : [];
     return {
         event: interaction,
         id: String(interaction.id),
         content: formatSlashCommandContent(interaction),
         channelId: String(interaction.channel_id ?? ''),
         channelKind: interaction.guild_id ? 'channel' : 'private',
+        ...(discordThreadParentOf(interaction.channel) ? { threadParentId: discordThreadParentOf(interaction.channel) } : {}),
         authorId: String(user?.id ?? ''),
         authorName: String(user?.username ?? user?.id ?? ''),
         createdTimestamp: Date.now(),
-        guildId: interaction.guild_id != null ? String(interaction.guild_id) : undefined,
+        guildId,
+        ...(platformPermissions.length ? { platformPermissions } : {}),
+        ...(authorRoles.length ? { authorRoles } : {}),
     };
 }

package/lib/sender-standing.d.ts

@@ -0,0 +1,18 @@
+import type { PlatformStanding } from '@zhin.js/im-contract';
+import type { DiscordInboundMessage } from './protocol.js';
+/** `ManageRoles` → `manage_roles`, `SendTTSMessages` → `send_tts_messages`. */
+export declare function discordPermissionName(flag: string): string;
+/** All permission flag names the predicate grants. */
+export declare function discordPermissionNames(has: (bit: bigint) => boolean): string[];
+/** Permission names from an interaction's decimal bitfield string (`member.permissions`). */
+export declare function discordPermissionNamesFromBitfield(bitfield: unknown): string[];
+/**
+ * Guild-level permission names from a channel-level bitfield (interaction `member.permissions` /
+ * `app_permissions`): an administrator holds every flag server-wide; otherwise only the flags that
+ * channel overwrites cannot change are reported, so a channel overwrite (e.g. "Manage Permissions" in
+ * one channel) never reads as a server-wide `manage_roles`.
+ */
+export declare function discordGuildPermissionNamesFromChannelBitfield(bitfield: unknown): string[];
+/** Normalized standing from guild-level permission names (the guild owner is reported separately). */
+export declare function discordStandingFromPermissions(permissions: readonly string[], isOwner?: boolean): PlatformStanding['standing'];
+export declare function discordSenderStanding(msg: DiscordInboundMessage): PlatformStanding | undefined;

package/lib/sender-standing.js

@@ -0,0 +1,91 @@
+/**
+ * ADR 0056 §1: Discord guild member → normalized `sender.platform`.
+ *
+ * - `standing`: guild owner → `owner`; `Administrator` / `ModerateMembers` → `admin`; other members →
+ *   `member`. Direct messages report nothing.
+ * - `roles`: the member's guild roles (`@everyone` excluded), with names when the event carries them.
+ * - `permissions`: the member's **guild-level** permission flags as snake_case names (`ban_members`,
+ *   `manage_roles`, …). Gateway mode reads `GuildMember.permissions` (server-wide, no channel overwrites)
+ *   for senders and the Bot alike. Interactions only carry channel-level bitfields (overwrites applied),
+ *   so they report just the flags that cannot be overwritten per channel (identical at both levels) —
+ *   all flags when the member is an administrator.
+ */
+import { PermissionFlagsBits } from 'discord.js';
+const FLAG_ENTRIES = Object.entries(PermissionFlagsBits);
+/** `ManageRoles` → `manage_roles`, `SendTTSMessages` → `send_tts_messages`. */
+export function discordPermissionName(flag) {
+    return flag.replace(/([A-Z]+)([A-Z][a-z])/gu, '$1_$2').replace(/([a-z0-9])([A-Z])/gu, '$1_$2').toLowerCase();
+}
+/** All permission flag names the predicate grants. */
+export function discordPermissionNames(has) {
+    const names = [];
+    for (const [flag, bit] of FLAG_ENTRIES) {
+        try {
+            if (has(bit))
+                names.push(discordPermissionName(flag));
+        }
+        catch {
+            // A partial permission view cannot answer this bit; leave it out.
+        }
+    }
+    return names;
+}
+/** Permission names from an interaction's decimal bitfield string (`member.permissions`). */
+export function discordPermissionNamesFromBitfield(bitfield) {
+    const value = parseBitfield(bitfield);
+    return value === undefined ? [] : discordPermissionNames(bit => (value & bit) === bit);
+}
+function parseBitfield(bitfield) {
+    if (typeof bitfield !== 'string' && typeof bitfield !== 'number' && typeof bitfield !== 'bigint')
+        return undefined;
+    try {
+        return BigInt(bitfield);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Flags Discord does not allow in channel overwrites: a channel-level bitfield shows their guild value. */
+const GUILD_ONLY_FLAGS = [
+    PermissionFlagsBits.Administrator, PermissionFlagsBits.KickMembers, PermissionFlagsBits.BanMembers,
+    PermissionFlagsBits.ManageGuild, PermissionFlagsBits.ViewAuditLog, PermissionFlagsBits.ViewGuildInsights,
+    PermissionFlagsBits.ChangeNickname, PermissionFlagsBits.ManageNicknames, PermissionFlagsBits.ManageGuildExpressions,
+    PermissionFlagsBits.ModerateMembers, PermissionFlagsBits.ViewCreatorMonetizationAnalytics,
+    PermissionFlagsBits.CreateGuildExpressions,
+];
+/**
+ * Guild-level permission names from a channel-level bitfield (interaction `member.permissions` /
+ * `app_permissions`): an administrator holds every flag server-wide; otherwise only the flags that
+ * channel overwrites cannot change are reported, so a channel overwrite (e.g. "Manage Permissions" in
+ * one channel) never reads as a server-wide `manage_roles`.
+ */
+export function discordGuildPermissionNamesFromChannelBitfield(bitfield) {
+    const value = parseBitfield(bitfield);
+    if (value === undefined)
+        return [];
+    if ((value & PermissionFlagsBits.Administrator) === PermissionFlagsBits.Administrator)
+        return discordPermissionNames(() => true);
+    return discordPermissionNames(bit => GUILD_ONLY_FLAGS.includes(bit) && (value & bit) === bit);
+}
+/** Normalized standing from guild-level permission names (the guild owner is reported separately). */
+export function discordStandingFromPermissions(permissions, isOwner = false) {
+    return isOwner ? 'owner'
+        : permissions.includes('administrator') || permissions.includes('moderate_members') ? 'admin' : 'member';
+}
+export function discordSenderStanding(msg) {
+    if (!msg.guildId)
+        return undefined;
+    const permissions = msg.platformPermissions ?? [];
+    const legacy = msg.permissionTokens ?? [];
+    const standing = msg.isGuildOwner
+        ? 'owner'
+        : permissions.includes('administrator') || permissions.includes('moderate_members')
+            || legacy.includes('ADMINISTRATOR') || legacy.includes('MODERATE_MEMBERS')
+            ? 'admin'
+            : 'member';
+    return {
+        standing,
+        ...(msg.authorRoles?.length ? { roles: msg.authorRoles } : {}),
+        ...(permissions.length ? { permissions } : {}),
+    };
+}