@zhin.js/adapter-discord 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @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
+
+- 43eda99: Unify Notice and Request payloads with their public types and runtime exports. Use camelCase fields, preserve native data under metadata, and bind canonical endpoint identity and request actions to the held generation. Remove legacy data aliases and from factories.
+
+  Keep login and lifecycle signals as independent SystemEvent payloads on system.receive, without chat conversation fields or user interaction. Update built-in adapter projections and authoring guidance.
+
+- Updated dependencies [43eda99]
+- Updated dependencies [0de4836]
+  - @zhin.js/core@1.1.39
+  - @zhin.js/permission@1.1.3
+  - @zhin.js/adapter@1.1.15
+
 ## 1.1.3
 
 ### 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
                     ? ''