@zhin.js/adapter-discord 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @zhin.js/adapter-discord
 
+## 1.1.5
+
+### Patch Changes
+
+- b9b3953: Use the canonical media MIME type to assign a filename extension when an outbound attachment has no explicit name, allowing Discord to display image previews instead of unknown file attachments.
+
+  Preserve canonical reply message references in Gateway sends so quote replies reference the original message rather than silently sending plain text.
+
+- b9b3953: Project Discord Gateway readiness from the connected client's live readiness state so runtime health no longer reports an observed ready connection as offline. Loss of readiness and stop remain offline.
+
+  Enable partial DM channels so the SDK admits messages from private channels that have not yet been cached.
+
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/host-http@1.1.3
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
 ## 1.1.4
 
 ### Patch Changes

package/README.md

@@ -97,3 +97,30 @@ plugins:
 ## 许可证
 
 MIT License
+
+
+受控 Gateway 故障验收可为单个测试 endpoint 设置 `gatewayFaultProxyUrl: ws://127.0.0.1:18090/`。
+只接受此格式的 loopback origin；REST API 仍走 SDK 默认路径。入口通过正式 `ws.buildStrategy`
+使用已验证的 `@discordjs/ws` 1.2.3，SDK 继续负责心跳、Identify 和 Resume，初连及平台返回的
+区域 `resume_gateway_url` 均转到本地代理。Endpoint 的启动、停止和失败复位统一使用
+`createEndpointLifecycle`，SDK 断线恢复状态由 `isReady()` 投影为 `reconnecting`。
+
+代理启动、切断与恢复见仓库 `scripts/platform-acceptance/FAULT-PROXY.md`。
+本地 SDK 测试不能替代真实 Discord 消息及断线恢复验收。
+
+### 出站失败与重试边界
+
+Gateway 客户端的 REST 设置 `retries: 0` 并以 `rejectOnRateLimit` 拒绝后台 429 排队，二者分别覆盖网络/5xx 重试与限流重发。真实 SDK HTTP fixture 验证连接丢失、500、429、403 各只有一个 POST。已有 Gateway 代理不控制 Discord REST，不能据此宣称出站 API 故障验收通过。API 专用入口需通过正式 REST agent/dispatcher 保留 discord.com HTTPS 身份和证书校验，仅把测试实例 TCP 路由固定到 loopback。验收项目已提供独立 `restApiProxy` / `DISCORD_REST_API_PROXY_PORT`。SDK合同见 [RESTOptions](https://discord.js.org/docs/packages/rest/main/RESTOptions:Interface)。
+
+### REST 专用 TLS 故障验收
+
+Gateway 实例可选 `restApiProxy: { port: 18570 }`，默认关闭。正式 RESTOptions.agent 使用 Undici Dispatcher，只允许真实 `https://discord.com:443`，保留原API URL、SNI和证书链/域名校验，TCP固定到 `127.0.0.1:18570`。错误目的地拒绝且不回退直连。与 `gatewayFaultProxyUrl` 分开；不要同时cut两条链路。SDK REST 的 Gateway discovery 等 API 也经过此代理，启动时必须先forwarding。正式 WebSocket连接不经过此REST Dispatcher；Gateway正常运行中API断开不能被记为入站WSS已重连。
+
+```bash
+node scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host discord.com --upstream-port 443 --port 18570 --control-port 18571
+DISCORD_REST_API_PROXY_PORT=18570 pnpm --filter platform-acceptance-bot dev:discord
+```
+
+forwarding 下以新sample确认真实消息基线；control `POST /cut` 后另发新sample，出站结果须失败/unknown且无自动POST重发；`POST /recover` 后先确认旧sample未补发，再新sample确认恢复。检查平台可见消息与报告回执，不重发未知sample。此模式仅Gateway REST、JSON消息能力；Interactions Endpoint 与其他CDN目的地不适用，配置Interactions会明确拒绝。本地真实SDK TLS fixture覆盖服务收到POST后切断、可信CA但SAN不匹配拒绝、默认直连与手动恢复，不能当成实机结果。停止/连接失败会销毁专用Dispatcher，并取消尚未完成TLS握手。
+
+公开扩展点参考：[Discord RESTOptions.agent](https://discord.js.org/docs/packages/rest/main/RESTOptions:Interface)、[Undici 6.28 Agent](https://github.com/nodejs/undici/blob/v6.28.0/docs/docs/api/Agent.md)。

package/lib/endpoint.d.ts

@@ -1,5 +1,4 @@
-import { Endpoint } from 'zhin.js/adapter';
-import type { EndpointContentPort, EndpointControl, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointContentPort, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import { type MessageRef } from '@zhin.js/im-contract';
 import type { CapabilityId } from 'zhin.js';
@@ -20,6 +19,7 @@ export declare class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransp
     constructor(options: DiscordEndpointOptions);
     /** The actual discord.js-compatible client used by this connection. */
     get client(): DiscordClientTransport;
+    get transportState(): EndpointTransportState | undefined;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -63,6 +63,8 @@ export declare class DiscordInteractionsEndpoint extends Endpoint<DiscordRestCli
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(message: MessageRef): Promise<void>;
     admit(msg: DiscordInboundMessage): void;
+    /** Test / internal: admit a button interaction when open. */
+    admitButton(interaction: DiscordButtonInbound): void;
     admitPlatform(event: Record<string, unknown>): void;
 }
 /**

package/lib/endpoint.js

@@ -1,8 +1,9 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { createDiscordRestApiAgent } from './rest-api-proxy.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
 import { ChannelType } from 'discord.js';
+import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
 import { discordInboundConversation, formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
@@ -18,7 +19,9 @@ export class DiscordGatewayEndpoint extends Endpoint {
     #fetch;
     #client = null;
     #open = false;
-    #started = false;
+    #lifecycle = createEndpointLifecycle({ name: 'discord', reconnect: false });
+    #cleanup;
+    #retiring;
     management = createDiscordEndpointManagement(() => this.#requireClient());
     control = Object.freeze({
         recall: (message) => this.recallMessage(message),
@@ -44,40 +47,92 @@ export class DiscordGatewayEndpoint extends Endpoint {
     get client() {
         return this.#requireClient();
     }
+    get transportState() {
+        if (this.#lifecycle.state !== 'open')
+            return this.#lifecycle.state;
+        if (!this.#client)
+            return 'closed';
+        if (!this.#client.isReady)
+            return this.#lifecycle.state;
+        return this.#client.isReady() ? 'open' : 'reconnecting';
+    }
     async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
-        try {
-            const intents = this.#options.config.intents?.length
-                ? [...this.#options.config.intents]
-                : DEFAULT_INTENTS;
-            this.#client = this.#createClient(intents);
-            await connectDiscordGatewayClient(this.#client, this.#options.config, {
-                onPlatformEvent: (name, event) => {
-                    void this.#emitPlatformEvent(name, event);
-                },
-                onMessage: (msg) => this.admit(msg),
-                onButton: (interaction) => this.admitButton(interaction),
-                onGuildMemberAdd: (member) => {
-                    receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_increase', member, this.#logger);
-                },
-                onGuildMemberRemove: (member) => {
-                    receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_decrease', member, this.#logger);
-                },
-            });
-            this.#logger.info(formatCompact({
-                op: 'connect',
-                endpoint: this.#options.config.id,
-                mode: 'gateway',
-                user: this.#client.user?.tag,
-            }));
-        }
-        catch (error) {
-            await this.stop();
-            this.#logger.error('Failed to connect Discord gateway:', error);
-            throw error;
-        }
+        await this.#retiring;
+        await this.#lifecycle.start(async (handle) => {
+            let cleanup;
+            let cancelled = false;
+            try {
+                const intents = this.#options.config.intents?.length
+                    ? [...this.#options.config.intents]
+                    : DEFAULT_INTENTS;
+                const restAgent = this.#options.config.restApiProxy ? createDiscordRestApiAgent(this.#options.config.restApiProxy) : undefined;
+                let client;
+                try {
+                    client = this.#createClient(intents, this.#options.config.gatewayFaultProxyUrl, restAgent ? { agent: restAgent } : undefined);
+                }
+                catch (error) {
+                    await restAgent?.destroyProxy();
+                    throw error;
+                }
+                this.#client = client;
+                const abort = new AbortController();
+                let stopping;
+                cleanup = () => {
+                    cancelled = true;
+                    abort.abort();
+                    if (this.#client === client)
+                        this.#client = null;
+                    return stopping ??= (async () => { client.removeAllListeners(); try {
+                        await client.destroy();
+                    }
+                    finally {
+                        await restAgent?.destroyProxy();
+                    } })();
+                };
+                this.#cleanup = cleanup;
+                handle.onForceClose(() => { void cleanup?.().catch(() => { }); });
+                await connectDiscordGatewayClient(client, this.#options.config, {
+                    onPlatformEvent: (name, event) => {
+                        if (this.#client !== client)
+                            return;
+                        void this.#emitPlatformEvent(name, event);
+                    },
+                    onMessage: (msg) => { if (this.#client === client)
+                        return this.admit(msg); },
+                    onButton: (interaction) => { if (this.#client === client)
+                        return this.admitButton(interaction); },
+                    onGuildMemberAdd: (member) => {
+                        if (this.#client !== client)
+                            return;
+                        receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_increase', member, this.#logger);
+                    },
+                    onGuildMemberRemove: (member) => {
+                        if (this.#client !== client)
+                            return;
+                        receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_decrease', member, this.#logger);
+                    },
+                }, abort.signal);
+                if (abort.signal.aborted || this.#client !== client)
+                    return;
+                this.#logger.info(formatCompact({
+                    op: 'connect',
+                    endpoint: this.#options.config.id,
+                    mode: 'gateway',
+                    user: this.#client.user?.tag,
+                }));
+            }
+            catch (error) {
+                const stopped = cancelled;
+                try {
+                    await cleanup?.();
+                }
+                catch { /* original connect failure wins */ }
+                if (stopped)
+                    return;
+                this.#logger.error('Failed to connect Discord gateway:', error);
+                throw error;
+            }
+        });
     }
     open() {
         this.#open = true;
@@ -87,17 +142,17 @@ export class DiscordGatewayEndpoint extends Endpoint {
     }
     async stop() {
         this.#open = false;
-        if (this.#client) {
-            try {
-                this.#client.removeAllListeners();
-                await this.#client.destroy();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#client = null;
+        const cleanup = this.#cleanup;
+        this.#cleanup = undefined;
+        this.#lifecycle.stop();
+        const retiring = this.#retiring ?? Promise.resolve().then(async () => { try {
+            await cleanup?.();
         }
-        this.#started = false;
+        catch { /* best-effort SDK shutdown */ } });
+        this.#retiring = retiring;
+        await retiring;
+        if (this.#retiring === retiring)
+            this.#retiring = undefined;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
@@ -197,13 +252,26 @@ export class DiscordGatewayEndpoint extends Endpoint {
         });
     }
     async #sendBody(channelId, body) {
-        const channel = await this.#requireClient().channels.fetch(channelId);
-        if (!channel || !channel.isTextBased() || !channel.send) {
-            throw new Error(`Channel ${channelId} is not a text channel`);
+        let stage = 'fetch_channel';
+        try {
+            const channel = await this.#requireClient().channels.fetch(channelId);
+            if (!channel || !channel.isTextBased() || !channel.send) {
+                throw new Error(`Channel ${channelId} is not a text channel`);
+            }
+            stage = 'render';
+            const options = await toMessageCreateOptions(body);
+            stage = 'send';
+            const result = await channel.send(options);
+            return result.id;
+        }
+        catch (error) {
+            const details = error;
+            this.#logger.warn(formatCompact({ op: 'discord_send_failed', stage,
+                code: typeof details?.code === 'number' ? details.code : 'unknown',
+                status: typeof details?.status === 'number' ? details.status : undefined,
+            }));
+            throw error;
         }
-        const options = await toMessageCreateOptions(body);
-        const result = await channel.send(options);
-        return result.id;
     }
     #requireClient() {
         if (!this.#client)
@@ -333,6 +401,31 @@ export class DiscordInteractionsEndpoint extends Endpoint {
             }));
         });
     }
+    /** Test / internal: admit a button interaction when open. */
+    admitButton(interaction) {
+        if (!this.#open)
+            return;
+        const conversation = discordInboundConversation(String(this.#options.id), interaction);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: interaction.id },
+            content: formatButtonContent(interaction),
+            segments: formatButtonSegments(interaction),
+            sender: { id: interaction.userId, name: interaction.userName },
+            endpointId: this.#options.config.id,
+            metadata: Object.freeze({
+                eventType: 'button',
+                payload: interaction.customId,
+                sourceMessageId: interaction.sourceMessageId,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'discord_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
     admitPlatform(event) {
         if (!this.#open)
             return;

package/lib/gateway-fault-proxy.d.ts

@@ -0,0 +1,19 @@
+import { Collection } from '@discordjs/collection';
+import { WebSocketShard, type IShardingStrategy, type WebSocketManager, type WebSocketShardDestroyOptions } from '@discordjs/ws';
+export declare function validateDiscordGatewayFaultProxy(value: string): string;
+/** Public gateway host only; credentials and arbitrary proxy targets are rejected. */
+export declare function discordGatewayProxyURL(proxy: string, upstream: string): string;
+/** Undo only this proxy's exact internal route when SDK updates sequence. */
+export declare function canonicalDiscordGatewayURL(proxy: string, value: string): string;
+/** Keeps SDK heartbeat/Identify/Resume. Only connection URLs use the test proxy. */
+export declare class DiscordFaultProxyStrategy implements IShardingStrategy {
+    #private;
+    readonly manager: WebSocketManager;
+    readonly proxy: string;
+    constructor(manager: WebSocketManager, proxy: string);
+    spawn(shardIds: number[]): Promise<void>;
+    connect(): Promise<void>;
+    destroy(options?: Omit<WebSocketShardDestroyOptions, 'recover'>): Promise<void>;
+    send(shardId: number, payload: Parameters<WebSocketShard['send']>[0]): Promise<void>;
+    fetchStatus(): Promise<Collection<number, import("discord.js").WebSocketShardStatus>>;
+}

package/lib/gateway-fault-proxy.js

@@ -0,0 +1,104 @@
+import { getLogger, formatCompact } from '@zhin.js/logger';
+import { Collection } from '@discordjs/collection';
+import { SimpleContextFetchingStrategy, WebSocketShard, WebSocketShardEvents, managerToFetchingStrategyOptions, } from '@discordjs/ws';
+export function validateDiscordGatewayFaultProxy(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'ws:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
+        throw new Error('Discord gateway fault proxy must be ws://127.0.0.1:PORT/');
+    return url.origin;
+}
+/** Public gateway host only; credentials and arbitrary proxy targets are rejected. */
+export function discordGatewayProxyURL(proxy, upstream) {
+    const origin = validateDiscordGatewayFaultProxy(proxy);
+    const target = new URL(upstream);
+    if (target.protocol !== 'wss:' || !/^gateway(?:-[a-z0-9-]+)?\.discord\.gg$/.test(target.hostname)
+        || (target.port && target.port !== '443') || target.username || target.password || target.pathname !== '/' || target.hash
+        || [...target.searchParams].some(([key, value]) => !(key === 'v' && /^\d{1,2}$/.test(value)) && !(key === 'encoding' && value === 'json') && !(key === 'compress' && value === 'zlib-stream')))
+        throw new Error('Invalid Discord gateway host');
+    return `${origin}/__discord_gateway/${target.hostname}`;
+}
+/** Undo only this proxy's exact internal route when SDK updates sequence. */
+export function canonicalDiscordGatewayURL(proxy, value) {
+    const origin = validateDiscordGatewayFaultProxy(proxy);
+    const url = new URL(value);
+    if (url.origin !== origin) {
+        discordGatewayProxyURL(proxy, value);
+        return value;
+    }
+    const host = url.pathname.match(/^\/__discord_gateway\/(gateway(?:-[a-z0-9-]+)?\.discord\.gg)$/)?.[1];
+    if (!host || url.username || url.password || url.search || url.hash)
+        throw new Error('Invalid internal Discord gateway route');
+    return `wss://${host}/`;
+}
+/** Keeps SDK heartbeat/Identify/Resume. Only connection URLs use the test proxy. */
+export class DiscordFaultProxyStrategy {
+    manager;
+    proxy;
+    #failureReject;
+    #failure = new Promise((_, reject) => { this.#failureReject = reject; });
+    #diagnosed = new Set();
+    #shards = new Collection();
+    constructor(manager, proxy) {
+        this.manager = manager;
+        this.proxy = proxy;
+        validateDiscordGatewayFaultProxy(proxy);
+        void this.#failure.catch(() => { });
+    }
+    async spawn(shardIds) {
+        const options = await managerToFetchingStrategyOptions(this.manager);
+        const mapped = { ...options, gatewayInformation: { ...options.gatewayInformation, url: discordGatewayProxyURL(this.proxy, options.gatewayInformation.url) } };
+        for (const shardId of shardIds) {
+            const context = new SimpleContextFetchingStrategy(this.manager, mapped);
+            const retrieve = context.retrieveSessionInfo.bind(context);
+            const update = context.updateSessionInfo.bind(context);
+            const invalid = () => {
+                const error = new Error('Invalid Discord gateway session');
+                this.#failureReject(error);
+                void Promise.resolve(this.manager.emit(WebSocketShardEvents.Error, { error, shardId })).catch(() => { });
+                void shard.destroy({ code: 1000, reason: 'Invalid gateway session' }).catch(() => { });
+            };
+            context.retrieveSessionInfo = async (id) => {
+                try {
+                    const session = await retrieve(id);
+                    if (!session)
+                        return null;
+                    const canonical = canonicalDiscordGatewayURL(this.proxy, session.resumeURL);
+                    const target = new URL(canonical);
+                    if (!this.#diagnosed.has(target.hostname) && this.#diagnosed.size < 8) {
+                        this.#diagnosed.add(target.hostname);
+                        getLogger('discord').debug(formatCompact({ op: 'discord_gateway_resume_target', hostname: target.hostname, pathIsRoot: target.pathname === '/', queryKeys: [...new Set(target.searchParams.keys())].join(',') }));
+                    }
+                    return { ...session, resumeURL: discordGatewayProxyURL(this.proxy, canonical) };
+                }
+                catch {
+                    invalid();
+                    return null;
+                }
+            };
+            context.updateSessionInfo = async (id, session) => {
+                try {
+                    return await update(id, session ? { ...session, resumeURL: canonicalDiscordGatewayURL(this.proxy, session.resumeURL) } : null);
+                }
+                catch {
+                    invalid();
+                }
+            };
+            const shard = new WebSocketShard(context, shardId);
+            for (const event of Object.values(WebSocketShardEvents))
+                shard.on(event, (payload) => this.manager.emit(event, { ...payload, shardId }));
+            this.#shards.set(shardId, shard);
+        }
+    }
+    async connect() { await Promise.race([Promise.all([...this.#shards.values()].map(shard => shard.connect())), this.#failure]); }
+    async destroy(options) {
+        await Promise.all([...this.#shards.values()].map(shard => shard.destroy(options)));
+        this.#shards.clear();
+    }
+    async send(shardId, payload) {
+        const shard = this.#shards.get(shardId);
+        if (!shard)
+            throw new RangeError('Discord shard not found');
+        await shard.send(payload);
+    }
+    async fetchStatus() { return this.#shards.mapValues(shard => shard.status); }
+}

package/lib/gateway.d.ts

@@ -1,8 +1,9 @@
-import { GatewayIntentBits, type MessageCreateOptions } from 'discord.js';
+import { GatewayIntentBits, type RESTOptions, type MessageCreateOptions } from 'discord.js';
 import { type DiscordButtonInbound, type DiscordInboundMessage, type DiscordOutboundBody, type ResolvedDiscordGatewayConfig } from './protocol.js';
 export declare const DEFAULT_INTENTS: GatewayIntentBits[];
 /** Minimal client surface used by the endpoint (real discord.js or test mock). */
 export interface DiscordClientTransport {
+    isReady?(): boolean;
     login(token: string): Promise<string>;
     destroy(): Promise<void>;
     on(event: string, listener: (...args: unknown[]) => void): void;
@@ -121,8 +122,8 @@ export interface DiscordClientTransport {
         };
     };
 }
-export type CreateDiscordClient = (intents: readonly number[]) => DiscordClientTransport;
-export declare function defaultCreateClient(intents: readonly number[]): DiscordClientTransport;
+export type CreateDiscordClient = (intents: readonly number[], gatewayFaultProxyUrl?: string, restOptions?: Partial<RESTOptions>) => DiscordClientTransport;
+export declare function defaultCreateClient(intents: readonly number[], gatewayFaultProxyUrl?: string, restOptions?: Partial<RESTOptions>): DiscordClientTransport;
 export declare function resolveSenderRole(msg: DiscordInboundMessage): string | undefined;
 export declare function normalizeDiscordMessage(raw: unknown): DiscordInboundMessage | null;
 export declare function toMessageCreateOptions(body: DiscordOutboundBody): Promise<MessageCreateOptions>;
@@ -141,4 +142,4 @@ export interface DiscordGatewayConnectHandlers {
         userName?: string;
     }): void;
 }
-export declare function connectDiscordGatewayClient(client: DiscordClientTransport, config: ResolvedDiscordGatewayConfig, handlers: DiscordGatewayConnectHandlers): Promise<void>;
+export declare function connectDiscordGatewayClient(client: DiscordClientTransport, config: ResolvedDiscordGatewayConfig, handlers: DiscordGatewayConnectHandlers, signal?: AbortSignal): Promise<void>;

package/lib/gateway.js

@@ -1,6 +1,7 @@
+import { DiscordFaultProxyStrategy } from './gateway-fault-proxy.js';
 import { createReadStream, promises as fs } from 'node:fs';
 import path from 'node:path';
-import { Client, GatewayIntentBits, EmbedBuilder, AttachmentBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle, REST, Routes, PermissionFlagsBits, } from 'discord.js';
+import { Client, 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';
 const logger = getLogger('discord');
@@ -12,8 +13,8 @@ export const DEFAULT_INTENTS = [
     GatewayIntentBits.GuildMembers,
     GatewayIntentBits.GuildMessageReactions,
 ];
-export function defaultCreateClient(intents) {
-    return new Client({ intents: [...intents] });
+export function defaultCreateClient(intents, gatewayFaultProxyUrl, restOptions = {}) {
+    return new Client({ rest: { ...restOptions, retries: 0, rejectOnRateLimit: () => true }, intents: [...intents], partials: [Partials.Channel], ...(gatewayFaultProxyUrl ? { ws: { buildStrategy: manager => new DiscordFaultProxyStrategy(manager, gatewayFaultProxyUrl) } } : {}) });
 }
 export function resolveSenderRole(msg) {
     if (msg.isGuildOwner)
@@ -78,6 +79,8 @@ export function normalizeDiscordMessage(raw) {
 }
 export async function toMessageCreateOptions(body) {
     const options = {};
+    if (body.reply)
+        options.reply = { ...body.reply };
     if (body.content)
         options.content = body.content;
     if (body.embeds?.length) {
@@ -194,9 +197,19 @@ function decodeBase64(value) {
     const comma = stripped.startsWith('data:') ? stripped.indexOf(',') : -1;
     return Buffer.from(comma >= 0 ? stripped.slice(comma + 1) : stripped, 'base64');
 }
-export async function connectDiscordGatewayClient(client, config, handlers) {
+export async function connectDiscordGatewayClient(client, config, handlers, signal) {
     return new Promise((resolve, reject) => {
         let settled = false;
+        const onAbort = () => { if (!settled) {
+            settled = true;
+            reject(new Error('Discord startup stopped'));
+        } };
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        const releaseAbort = () => signal?.removeEventListener('abort', onAbort);
         client.on('messageCreate', (raw) => {
             handlers.onPlatformEvent('messageCreate', raw);
             const msg = normalizeDiscordMessage(raw);
@@ -211,16 +224,27 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
         client.on('interactionCreate', (raw) => {
             handlers.onPlatformEvent('interactionCreate', raw);
             const interaction = raw;
-            if (!interaction.isButton?.())
+            const isButton = interaction.isButton?.() === true;
+            logger.info(formatCompact({ op: 'discord_gateway_interaction_received', button: isButton, cachedChannel: !!interaction.channel, hasChannelId: !!interaction.channelId }));
+            if (!isButton)
                 return;
-            void interaction.deferUpdate?.().catch(() => { });
-            if (!interaction.channel)
+            void interaction.deferUpdate?.().then(() => {
+                logger.info(formatCompact({ op: 'discord_gateway_button_ack', status: 'confirmed' }));
+            }).catch(() => {
+                // SDK errors may contain token-bearing callback URLs; log no raw error.
+                logger.warn(formatCompact({ op: 'discord_gateway_button_ack', status: 'failed' }));
+            });
+            const channelId = interaction.channelId ?? interaction.channel?.id;
+            if (!channelId) {
+                logger.warn(formatCompact({ op: 'discord_gateway_button_dropped', reason: 'missing_channel_id' }));
                 return;
+            }
             handlers.onButton({
                 id: interaction.id,
                 customId: interaction.customId,
-                channelId: interaction.channel.id,
-                channelKind: resolveChannelKind(interaction.channel.type),
+                channelId,
+                channelKind: interaction.channel ? resolveChannelKind(interaction.channel.type) : interaction.guildId ? 'channel' : 'private',
+                ...(interaction.guildId ? { guildId: interaction.guildId } : {}),
                 userId: interaction.user.id,
                 userName: interaction.user.username || interaction.user.displayName || interaction.user.id,
                 sourceMessageId: interaction.message?.id,
@@ -253,6 +277,8 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
             });
         });
         client.once('clientReady', () => {
+            if (signal?.aborted)
+                return;
             handlers.onPlatformEvent('clientReady', client.user);
             void (async () => {
                 try {
@@ -268,12 +294,14 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
                     }
                     if (!settled) {
                         settled = true;
+                        releaseAbort();
                         resolve();
                     }
                 }
                 catch (error) {
                     if (!settled) {
                         settled = true;
+                        releaseAbort();
                         reject(error);
                     }
                 }
@@ -283,15 +311,20 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
             logger.error('Discord client error:', error);
             if (!settled) {
                 settled = true;
+                releaseAbort();
                 reject(error instanceof Error ? error : new Error(String(error)));
             }
         });
         client.on('warn', (info) => {
             logger.warn('Discord client warning:', info);
         });
-        client.login(config.token).catch((error) => {
+        client.login(config.token).then(() => {
+            if (signal?.aborted)
+                void Promise.resolve(client.destroy()).catch(() => { });
+        }).catch((error) => {
             if (!settled) {
                 settled = true;
+                releaseAbort();
                 const raw = error instanceof Error ? error.message : String(error);
                 const tokenShapeHint = config.token.split('.').length === 3
                     ? ''

package/lib/protocol.d.ts

@@ -1,4 +1,3 @@
-/** Discord Gateway protocol helpers. Canonicalization is owned by Core. */
 import { type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
 export interface DiscordActivity {
@@ -12,6 +11,9 @@ export interface DiscordEndpointConfig {
     readonly token: string;
     /** Default `gateway`. `interactions` uses httpHostToken POST + Ed25519 verify. */
     readonly connection?: 'gateway' | 'interactions';
+    /** Test instance only: ws://127.0.0.1:PORT/ fault proxy. */
+    readonly restApiProxy?: import('./rest-api-proxy.js').DiscordRestApiProxy;
+    readonly gatewayFaultProxyUrl?: string;
     readonly intents?: readonly number[];
     readonly enableSlashCommands?: boolean;
     readonly globalCommands?: boolean;
@@ -27,6 +29,9 @@ export interface ResolvedDiscordGatewayConfig {
     readonly connection: 'gateway';
     readonly id: string;
     readonly token: string;
+    /** Test instance only: ws://127.0.0.1:PORT/ fault proxy. */
+    readonly restApiProxy?: import('./rest-api-proxy.js').DiscordRestApiProxy;
+    readonly gatewayFaultProxyUrl?: string;
     readonly intents?: readonly number[];
     readonly enableSlashCommands: boolean;
     readonly globalCommands: boolean;
@@ -70,6 +75,7 @@ export interface DiscordInboundMessage {
     readonly mentionedBot?: boolean;
 }
 export interface DiscordButtonInbound {
+    readonly guildId?: string;
     readonly id: string;
     readonly customId: string;
     readonly channelId: string;
@@ -94,6 +100,10 @@ export interface DiscordOutboundActionRow {
     components: DiscordOutboundComponentButton[];
 }
 export interface DiscordOutboundBody {
+    readonly reply?: {
+        readonly messageReference: string;
+        readonly failIfNotExists: boolean;
+    };
     readonly content?: string;
     readonly embeds?: ReadonlyArray<Record<string, unknown>>;
     readonly files?: ReadonlyArray<{