@zhin.js/adapter-slack 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.1.5
+
+### Patch Changes
+
+- b9b3953: Map canonical reply segments to Slack thread replies instead of displaying a literal reply placeholder. Existing conversation thread routing takes precedence.
+
+  Give unnamed uploads a MIME-derived filename extension and preserve explicit media filenames, rather than using image alt text as the filename.
+
+- 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

@@ -143,3 +143,31 @@ MIT
 成功发送返回平台 `ts` 组成的消息引用，不以本地时间替代缺失回执。
 文件上传失败会让本次发送失败；分段消息中某段缺少有效回执时，停止后续分段。
 前面已成功的文件或分段不会自动回滚；发送失败可能表示部分已送达，请先核对目标会话再重试。
+# Socket Mode 可控断线验收
+
+`streamProxy: { port: 18443, serverName: "实际网关域名" }` 使用 SDK 合法 `clientOptions.agent`。配置网关的 WSS 仅改 TCP 路由为 `127.0.0.1:18443`，保留真实 URL、Host、TLS SNI、证书链和域名校验。SDK 的 discovery API 仍用标准 HTTPS Agent 直连 `slack.com`；其他网关及 WebSocket Upgrade 到 API 域名均明确拒绝，不绕代理。日志仅包含安全 hostname，不打印完整 URL/query/token。
+
+验收项目通过 `SLACK_STREAM_PROXY_PORT` / `SLACK_STREAM_PROXY_SERVER_NAME` 进程变量临时覆盖，需同时填写，留空直连。未知域名可先设占位值，从拒绝日志获取真实 hostname，再启动 `scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host 实际网关域名 --upstream-port 443 --port 18443 --control-port 18444`；将 serverName 同步为此域名。不要覆盖已有 `.env`。平台更换动态网关时停止验收并更新固定上游，不能直连继续取恢复证据。
+
+Socket SDK 的自动重连已关闭；start/stop/reconnect 由统一 Endpoint lifecycle 管理，SDK 保留协议心跳。断线销毁当前 Agent/Socket，重连新建实例；旧实例回调不进入消息链，stop 取消待重连。可观察 Endpoint `transportState` 的 open/重连/stopped。
+
+先验证正常消息，再 POST 代理 `/cut`，观察 Socket 关闭和生命周期退出 open；POST `/recover`，观察新连接 open，再发送唯一新 probe 验证真实入站及可见回复。切断只覆盖 Socket 入站，普通 Web API 出站仍直连，不代表所有网络恢复或离线消息无损。完成后停止代理、移除临时覆盖。实际 SDK 的本地 TLS/hello 握手、断线恢复与防绕过回归通过，真实平台结果另记。
+
+### 出站失败与重试边界
+
+默认 WebClient 禁用 SDK 网络/5xx 自动重试，并以 `rejectRateLimitedCalls: true` 返回 429，不在后台排队重发。平台明确返回拒绝记为 rejected；连接中断、408、5xx、缺少真实时间戳记为 unknown，调用者不得把 unknown 当成“未发送”盲目重试。实机 WSS 故障代理只控制入站长连接，不能作为 Web API 故障证据。本地真实 SDK HTTP fixture 已验证每种故障只出现一个 POST；不代表真实租户已通过。
+
+SDK 官方选项依据：[Slack Web API 文档](https://docs.slack.dev/tools/node-slack-sdk/web-api/)。若需 API 专用故障入口，应在专用测试实例 WebClient 的正式 `agent` 选项注入固定 loopback TCP 路由，保留真实 slack.com URL、SNI 和证书校验；验收项目现提供独立 `webApiProxy` / `SLACK_WEB_API_PROXY_PORT`，不能用 WSS proxy 冒充 API proxy。
+
+### 专用 Web API 故障入口
+
+可选 endpoint `webApiProxy: { port: 18560 }` 仅作用于该实例的 JSON Web API 客户端。目的地固定 `slack.com:443`，真实 HTTPS URL/SNI/证书校验保留，TCP 只路由到 `127.0.0.1:18560`；错误域名拒绝、不回退直连。默认关闭，与 Socket `streamProxy` 独立；SocketModeClient 的连接发现和 WSS 不走此代理。停止 endpoint 会销毁专用 agent。上传使用其他域名，此专用代理明确拒绝，故只用于 JSON消息/引用/按钮/链接探针，不据此验收文件上传。
+
+使用现有透明TCP故障代理：
+
+```bash
+node scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host slack.com --upstream-port 443 --port 18560 --control-port 18561
+SLACK_WEB_API_PROXY_PORT=18560 pnpm --filter platform-acceptance-bot dev:slack
+```
+
+启动代理 forwarding 后先发新的 `/acceptance probe:slack-api-baseline`，确认真实回执；control `POST /cut` 只切 API TCP，WSS保持连接，再发独立新样本并确认报告 unknown且无后台重发。`POST /recover` 后先确认旧样本没有补发，再发新样本验证恢复。每个未知样本都保留并检查平台可见消息；禁止因为 unknown 重发同一业务。TCP cut 发生在请求前不能证明“平台已接收但回执丢失”，这一情况已有本地 TLS fixture 在服务收到 POST 后切断覆盖，实机未单独证明。

package/adapters/slack/index.js

@@ -17,6 +17,7 @@ export default defineAdapter({
     segments: {
         outboundMedia: ['url', 'upload', 'path'],
         interactive: 'native',
+        markdown: 'native',
     },
     create(context) {
         const config = resolveSlackConfig(context.config);

package/adapters/slack/index.ts

@@ -22,6 +22,7 @@ export default defineAdapter<SlackEndpointConfig>({
   segments: {
     outboundMedia: ['url', 'upload', 'path'],
     interactive: 'native',
+    markdown: 'native',
   },
   create(context) {
     const config = resolveSlackConfig(context.config);

package/lib/endpoint.d.ts

@@ -1,5 +1,4 @@
-import { Endpoint } from 'zhin.js/adapter';
-import type { EndpointControl, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type ResolvedSlackConfig, type SlackEvent, type SlackInteractionPayload, type SlackMessageEvent, type SlackSlashCommand } from './protocol.js';
@@ -122,6 +121,7 @@ export interface SlackEndpointOptions {
     readonly createSocket?: (opts: {
         readonly appToken: string;
         readonly clientPingTimeout: number;
+        readonly autoReconnectEnabled: false;
     }) => SlackSocketLike;
 }
 export declare class SlackEndpoint extends Endpoint<SlackWebClientLike> implements SlackWebhookHandler {
@@ -132,6 +132,7 @@ export declare class SlackEndpoint extends Endpoint<SlackWebClientLike> implemen
     /** Console 展示 / AdapterIndex live name（多 endpoint 时与 entry name 一致）。 */
     get name(): string;
     get client(): SlackWebClientLike;
+    get transportState(): import("@zhin.js/adapter").EndpointLifecycleState;
     get platformUserId(): string | undefined;
     get config(): ResolvedSlackConfig;
     start(): Promise<void>;

package/lib/endpoint.js

@@ -1,9 +1,12 @@
-import { Endpoint } from 'zhin.js/adapter';
 /**
  * SlackEndpoint — lifecycle, outbound, admit, Socket Mode, agent tool surface.
  */
 import { SocketModeClient } from '@slack/socket-mode';
-import { WebClient } from '@slack/web-api';
+import { createSlackWebApiAgent } from './web-api-proxy.js';
+import { createSlackStreamAgent } from './stream-proxy.js';
+import { slackSocketConnectionError } from './socket-error.js';
+import { createSlackWebClient, slackDeliveryError } from './web-client.js';
+import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { formatInboundContent, formatInteractionContent, formatSlashContent, resolveSlackChannelType, slackInboundConversation, } from './protocol.js';
 import { createSlackInboundFilterState, shouldDropSlackInboundMessage, } from './slack-inbound-filter.js';
@@ -19,7 +22,9 @@ export class SlackEndpoint extends Endpoint {
     #inboundFilter = createSlackInboundFilterState();
     #messageChannelMap = new Map();
     #client;
+    #webApiAgent;
     #socket;
+    #lifecycle;
     #routeReleases = [];
     #botUserId;
     #open = false;
@@ -58,6 +63,7 @@ export class SlackEndpoint extends Endpoint {
         super();
         this.#logger = getAdapterLogger('slack', options.config.id);
         this.#options = options;
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id });
     }
     /** Console 展示 / AdapterIndex live name（多 endpoint 时与 entry name 一致）。 */
     get name() {
@@ -68,6 +74,7 @@ export class SlackEndpoint extends Endpoint {
             throw new Error('Slack client not connected');
         return this.#client;
     }
+    get transportState() { return this.config.mode === 'socket' ? this.#lifecycle.state : this.#started ? 'open' : 'stopped'; }
     get platformUserId() {
         return this.#botUserId;
     }
@@ -80,8 +87,10 @@ export class SlackEndpoint extends Endpoint {
         this.#started = true;
         try {
             const { config } = this.#options;
+            if (config.webApiProxy && !this.#options.createClient)
+                this.#webApiAgent = createSlackWebApiAgent(config.webApiProxy);
             this.#client = this.#options.createClient?.(config.token)
-                ?? new WebClient(config.token);
+                ?? createSlackWebClient(config.token, this.#webApiAgent ? { agent: this.#webApiAgent } : {});
             if (config.mode === 'socket') {
                 await this.#startSocket();
             }
@@ -117,6 +126,9 @@ export class SlackEndpoint extends Endpoint {
     }
     async stop() {
         this.#open = false;
+        this.#webApiAgent?.destroy();
+        this.#webApiAgent = undefined;
+        await this.#lifecycle.stop();
         if (this.#socket) {
             try {
                 await this.#socket.disconnect();
@@ -137,9 +149,14 @@ export class SlackEndpoint extends Endpoint {
             throw new Error('Slack client not connected');
         const channel = conversation.id;
         const threadTs = conversation.threadId;
-        const result = await sendSlackContent(this.#client, payload, { channel, threadTs }, this.#logger);
-        this.trackMessageChannel(result.ts, channel);
-        return formatSlackMessageRef(channel, result.ts);
+        try {
+            const result = await sendSlackContent(this.#client, payload, { channel, threadTs }, this.#logger);
+            this.trackMessageChannel(result.ts, channel);
+            return formatSlackMessageRef(channel, result.ts);
+        }
+        catch (error) {
+            throw slackDeliveryError(error);
+        }
     }
     /** Test / internal: admit a message event when open. */
     admit(event) {
@@ -203,6 +220,7 @@ export class SlackEndpoint extends Endpoint {
             conversation,
             message: { conversation, id: actionTs },
             content: formatInteractionContent(payload),
+            segments: [{ type: 'action', data: { id: actionTs, payload: payload.actions[0].value ?? payload.actions[0].action_id, ...(messageTs ? { sourceMessageId: messageTs } : {}) } }],
             sender: { id: userId },
             endpointId: this.#options.config.id,
             metadata: Object.freeze({
@@ -334,26 +352,39 @@ export class SlackEndpoint extends Endpoint {
         if (!config.appToken.startsWith('xapp-')) {
             throw new Error(`Slack appToken 格式不正确：Socket Mode 需要 xapp- 前缀的 App-Level Token（当前看起来是 ${config.appToken.slice(0, 5)}…，xoxb- 是 bot token，请填到 token 字段）`);
         }
-        this.#socket = this.#options.createSocket?.({
-            appToken: config.appToken,
-            clientPingTimeout: config.clientPingTimeout,
-        }) ?? new SocketModeClient({
-            appToken: config.appToken,
-            clientPingTimeout: config.clientPingTimeout,
-        });
-        this.#socket.on('slack_event', async ({ ack, body }) => {
-            await ack();
-            this.handleEnvelope(body);
-        });
-        this.#socket.on('interactive', async ({ ack, body }) => {
-            await ack();
-            this.admitInteraction(body);
-        });
-        this.#socket.on('slash_commands', async ({ ack, body }) => {
-            await ack();
-            this.admitSlashCommand(body);
+        await this.#lifecycle.start(async (handle) => {
+            let active = true;
+            let connectionError;
+            const agent = config.streamProxy ? createSlackStreamAgent(config.streamProxy) : undefined;
+            const socket = this.#options.createSocket?.({ appToken: config.appToken, clientPingTimeout: config.clientPingTimeout, autoReconnectEnabled: false })
+                ?? new SocketModeClient({ appToken: config.appToken, clientPingTimeout: config.clientPingTimeout,
+                    autoReconnectEnabled: false, ...(agent ? { clientOptions: { agent } } : {}) });
+            this.#socket = socket;
+            const release = () => { if (!active)
+                return; active = false; if (this.#socket === socket)
+                this.#socket = undefined; agent?.destroy(); void socket.disconnect().catch(() => { }); };
+            handle.onForceClose(release);
+            socket.on('disconnected', () => { if (!active)
+                return; release(); handle.notifyClosed('Slack socket disconnected'); });
+            socket.on('error', error => { connectionError = slackSocketConnectionError(error); if (!active)
+                return; release(); handle.notifyClosed('Slack socket error'); });
+            socket.on('slack_event', async ({ ack, body }) => { if (!active || this.#socket !== socket)
+                return; await ack(); if (active)
+                this.handleEnvelope(body); });
+            socket.on('interactive', async ({ ack, body }) => { if (!active || this.#socket !== socket)
+                return; await ack(); if (active)
+                this.admitInteraction(body); });
+            socket.on('slash_commands', async ({ ack, body }) => { if (!active || this.#socket !== socket)
+                return; await ack(); if (active)
+                this.admitSlashCommand(body); });
+            try {
+                await socket.start();
+            }
+            catch (error) {
+                release();
+                throw connectionError ?? slackSocketConnectionError(error);
+            }
         });
-        await this.#socket.start();
     }
 }
 /** Slack Web API 分页上限（每页 1000，cursor 翻页直到 next_cursor 为空）。 */

package/lib/protocol.d.ts

@@ -2,6 +2,8 @@ import type { IncomingMessage } from 'node:http';
 import { type ConversationRef } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface SlackEndpointConfig {
+    readonly webApiProxy?: import('./web-api-proxy.js').SlackWebApiProxy;
+    readonly streamProxy?: import('./stream-proxy.js').SlackStreamProxy;
     readonly id: string;
     readonly token: string;
     readonly signingSecret?: string;
@@ -12,6 +14,8 @@ export interface SlackEndpointConfig {
     readonly clientPingTimeout?: number;
 }
 export interface ResolvedSlackConfig {
+    readonly webApiProxy?: import('./web-api-proxy.js').SlackWebApiProxy;
+    readonly streamProxy?: import('./stream-proxy.js').SlackStreamProxy;
     readonly context: 'slack';
     readonly id: string;
     readonly token: string;
@@ -126,6 +130,7 @@ export declare function formatSlashContent(cmd: SlackSlashCommand): string;
  * Segment canonicalization is intentionally not done here.
  */
 export declare function formatOutboundWire(payload: unknown): {
+    replyTo?: string;
     text: string;
     blocks: Record<string, unknown>[];
     attachments: Record<string, unknown>[];

package/lib/protocol.js

@@ -14,6 +14,11 @@ function dropOutboundMedia(type, reason) {
 const SLACK_SIG_VERSION = 'v0';
 const MAX_TIMESTAMP_DRIFT_SECONDS = 300;
 export function resolveSlackConfig(config) {
+    if (config.webApiProxy && (!Number.isInteger(config.webApiProxy.port) || config.webApiProxy.port < 1 || config.webApiProxy.port > 65535))
+        throw new TypeError('Invalid Slack webApiProxy port');
+    if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
+        || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName) || config.streamProxy.serverName === 'slack.com'))
+        throw new TypeError('Invalid Slack streamProxy port/serverName');
     const id = requiredEndpointField(config.id, 'id');
     const token = requiredEndpointField(config.token, 'token');
     const socketMode = config.socketMode;
@@ -26,6 +31,8 @@ export function resolveSlackConfig(config) {
         ? requiredEndpointField(config.appToken, 'appToken')
         : config.appToken?.trim();
     return {
+        ...(config.webApiProxy ? { webApiProxy: config.webApiProxy } : {}),
+        ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
         context: 'slack',
         id,
         token,
@@ -110,6 +117,7 @@ export function formatOutboundWire(payload) {
     const blocks = [];
     const attachments = [];
     const files = [];
+    let replyTo;
     for (const item of items) {
         if (typeof item === 'string') {
             text += item;
@@ -117,6 +125,11 @@ export function formatOutboundWire(payload) {
         }
         const data = item.data ?? {};
         switch (item.type) {
+            case 'reply':
+                if (typeof data.message_id === 'string' && data.message_id)
+                    replyTo = data.message_id;
+                break;
+            case 'markdown':
             case 'text':
                 text += String(data.text ?? data.content ?? '');
                 break;
@@ -149,7 +162,7 @@ export function formatOutboundWire(payload) {
                     });
                     break;
                 }
-                const imageFile = resolveMediaToFile(media, String(data.alt ?? media.file_name ?? 'image'));
+                const imageFile = resolveMediaToFile(media, String(media.file_name ?? mediaDefaultFilename('image', media)));
                 if (imageFile)
                     files.push(imageFile);
                 else
@@ -164,13 +177,16 @@ export function formatOutboundWire(payload) {
                     dropOutboundMedia(item.type, 'missing_media_ref');
                     break;
                 }
-                const mediaFile = resolveMediaToFile(media, String(data.name ?? media.file_name ?? item.type));
+                const mediaFile = resolveMediaToFile(media, String(media.file_name ?? data.name ?? mediaDefaultFilename(item.type, media)));
                 if (mediaFile)
                     files.push(mediaFile);
                 else
                     dropOutboundMedia(item.type, 'unsupported_media_kind');
                 break;
             }
+            case 'share':
+                attachments.push({ title: String(data.title ?? ''), title_link: String(data.url ?? ''), text: String(data.description ?? data.content ?? ''), ...(data.image ? { image_url: String(data.image) } : {}) });
+                break;
             case 'keyboard':
                 blocks.push(...keyboardToBlockKitBlocks(data));
                 break;
@@ -178,7 +194,7 @@ export function formatOutboundWire(payload) {
                 text += String(data.text ?? `[${item.type}]`);
         }
     }
-    return { text, blocks, attachments, files };
+    return { text, blocks, attachments, files, ...(replyTo ? { replyTo } : {}) };
 }
 export function keyboardToBlockKitBlocks(data) {
     const rows = data.rows;
@@ -190,7 +206,7 @@ export function keyboardToBlockKitBlocks(data) {
             type: 'button',
             text: { type: 'plain_text', text: String(btn.label ?? btn.text ?? 'button').slice(0, 75) },
             action_id: String(btn.id ?? btn.action_id ?? `btn_${blocks.length}_${index}`),
-            ...(btn.value != null ? { value: String(btn.value) } : {}),
+            ...(btn.payload != null || btn.value != null ? { value: String(btn.payload ?? btn.value) } : {}),
             ...(btn.style === 'primary' ? { style: 'primary' } : {}),
             ...(btn.style === 'danger' ? { style: 'danger' } : {}),
         }));
@@ -207,6 +223,14 @@ export function keyboardToBlockKitBlocks(data) {
  * - kind=path → 记录本地路径，上传前读盘；
  * - kind=file → Slack 无平台不透明文件引用可直发，返回 undefined 由调用方丢弃留痕。
  */
+function mediaDefaultFilename(kind, media) {
+    const extension = {
+        'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp',
+        'audio/mpeg': 'mp3', 'audio/ogg': 'ogg', 'audio/wav': 'wav',
+        'video/mp4': 'mp4', 'video/webm': 'webm', 'application/pdf': 'pdf',
+    }[media.mime_type?.split(';')[0].trim().toLowerCase() ?? ''];
+    return `${kind}${extension ? `.${extension}` : ''}`;
+}
 function resolveMediaToFile(media, name) {
     switch (media.kind) {
         case 'base64':

package/lib/slack-outbound.js

@@ -3,11 +3,12 @@ import { formatOutboundWire, keyboardToBlockKitBlocks } from './protocol.js';
 const SLACK_MAX_BLOCKS_PER_MESSAGE = 48;
 export async function sendSlackContent(client, content, opts, logger) {
     const wire = formatOutboundWire(content);
+    const threadTs = opts.threadTs ?? wire.replyTo;
     const blocks = [...wire.blocks];
     const textDelivery = applyTextMrkdwnBlocks(wire.text, blocks);
     for (const pf of wire.files) {
         try {
-            await uploadFile(client, opts.channel, pf, opts.threadTs);
+            await uploadFile(client, opts.channel, pf, threadTs);
         }
         catch (e) {
             logger.error('Failed to upload file:', e);
@@ -16,7 +17,7 @@ export async function sendSlackContent(client, content, opts, logger) {
     }
     return postSlackMessage(client, {
         channel: opts.channel,
-        threadTs: opts.threadTs,
+        threadTs,
         blocks,
         attachments: wire.attachments,
         fallbackText: textDelivery.fallbackText,

package/lib/socket-error.d.ts

@@ -0,0 +1,2 @@
+/** SDK can reject start() with undefined; never pass raw URL-bearing SDK errors to logs. */
+export declare function slackSocketConnectionError(value: unknown): Error;

package/lib/socket-error.js

@@ -0,0 +1,13 @@
+/** SDK can reject start() with undefined; never pass raw URL-bearing SDK errors to logs. */
+export function slackSocketConnectionError(value) {
+    const proxyReason = 'Slack Stream proxy gateway identity changed; update fixed upstream before retrying';
+    const source = value && typeof value === 'object' ? value : undefined;
+    if (source?.message === proxyReason || source?.original?.message === proxyReason) {
+        return new Error('Slack Socket Mode gateway identity changed; fault proxy refused the connection');
+    }
+    const code = source?.original?.code ?? source?.code;
+    const safeCodes = ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ERR_TLS_CERT_ALTNAME_INVALID', 'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'];
+    if (typeof code === 'string' && safeCodes.includes(code))
+        return new Error(`Slack Socket Mode connection failed (${code})`);
+    return new Error('Slack Socket Mode connection failed; SDK did not confirm a connection');
+}

package/lib/stream-proxy.d.ts

@@ -0,0 +1,6 @@
+import { Agent } from 'node:https';
+export interface SlackStreamProxy {
+    readonly port: number;
+    readonly serverName: string;
+}
+export declare function createSlackStreamAgent(proxy: SlackStreamProxy): Agent;

package/lib/stream-proxy.js

@@ -0,0 +1,23 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { Socket } from 'node:net';
+import { getLogger } from '@zhin.js/logger';
+export function createSlackStreamAgent(proxy) {
+    const agent = new Agent({ keepAlive: false });
+    const direct = agent.createConnection.bind(agent);
+    agent.createConnection = (options, callback) => {
+        const hostname = String(options.hostname ?? options.host ?? '');
+        const headers = options.headers;
+        const upgrade = Object.entries(headers ?? {}).some(([name, value]) => name.toLowerCase() === 'upgrade' && String(value).toLowerCase() === 'websocket');
+        if (hostname === proxy.serverName && Number(options.port ?? 443) === 443)
+            return tls.connect({ ...options, path: undefined,
+                host: '127.0.0.1', port: proxy.port, servername: hostname, rejectUnauthorized: true });
+        if (!upgrade && hostname === 'slack.com' && Number(options.port ?? 443) === 443)
+            return direct(options, callback);
+        getLogger('slack').warn(`Stream proxy rejected gateway hostname: ${hostname}`);
+        const rejected = new Socket();
+        queueMicrotask(() => rejected.destroy(new Error('Slack Stream proxy gateway identity changed; update fixed upstream before retrying')));
+        return rejected;
+    };
+    return agent;
+}

package/lib/web-api-proxy.d.ts

@@ -0,0 +1,6 @@
+import { Agent } from 'node:https';
+export interface SlackWebApiProxy {
+    readonly port: number;
+}
+/** JSON Web API only: keep slack.com identity, route TCP to a fixed loopback port. */
+export declare function createSlackWebApiAgent(proxy: SlackWebApiProxy): Agent;

package/lib/web-api-proxy.js

@@ -0,0 +1,18 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { Socket } from 'node:net';
+/** JSON Web API only: keep slack.com identity, route TCP to a fixed loopback port. */
+export function createSlackWebApiAgent(proxy) {
+    const agent = new Agent({ keepAlive: false });
+    agent.createConnection = options => {
+        const hostname = String(options.hostname ?? options.host ?? '');
+        if (hostname !== 'slack.com' || Number(options.port ?? 443) !== 443) {
+            const rejected = new Socket();
+            queueMicrotask(() => rejected.destroy(new Error('Slack Web API proxy rejected destination identity')));
+            return rejected;
+        }
+        return tls.connect({ ...options, path: undefined,
+            host: '127.0.0.1', port: proxy.port, servername: 'slack.com', rejectUnauthorized: true });
+    };
+    return agent;
+}

package/lib/web-client.d.ts

@@ -0,0 +1,5 @@
+import { WebClient, type WebClientOptions } from '@slack/web-api';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** A non-idempotent outbound API call gets exactly one transport attempt. */
+export declare function createSlackWebClient(token: string, options?: WebClientOptions): WebClient;
+export declare function slackDeliveryError(error: unknown): EndpointDeliveryError;

package/lib/web-client.js

@@ -0,0 +1,15 @@
+import { WebClient, ErrorCode } from '@slack/web-api';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** A non-idempotent outbound API call gets exactly one transport attempt. */
+export function createSlackWebClient(token, options = {}) {
+    return new WebClient(token, { ...options, retryConfig: { retries: 0 }, rejectRateLimitedCalls: true });
+}
+export function slackDeliveryError(error) {
+    if (error instanceof EndpointDeliveryError)
+        return error;
+    const value = error;
+    const status = typeof value?.statusCode === 'number' ? value.statusCode : undefined;
+    const rejected = value?.code === ErrorCode.PlatformError || value?.code === ErrorCode.RateLimitedError
+        || value?.code === ErrorCode.HTTPError && status !== undefined && status >= 400 && status < 500 && status !== 408;
+    return new EndpointDeliveryError(rejected ? 'platform_rejected' : 'delivery_unconfirmed', rejected ? 'Slack rejected outbound request' : 'Slack outbound outcome is unknown', rejected ? 'rejected' : 'unknown');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-slack",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Zhin.js Slack adapter for Plugin Runtime (Socket Mode / HTTP Events)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,24 +34,24 @@
   "dependencies": {
     "@slack/socket-mode": "^2.0.7",
     "@slack/web-api": "^7.19.0",
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.39",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.3",
-    "@zhin.js/core": "^1.1.39",
-    "@zhin.js/host-http": "^1.1.2",
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
+    "@zhin.js/host-http": "^1.1.3",
     "@zhin.js/permission": "^1.1.3",
-    "zhin.js": "^1.1.4"
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -69,7 +69,7 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.4"
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/schema.json

@@ -88,6 +88,42 @@
           "id": {
             "type": "string",
             "description": "Slack bot name"
+          },
+          "streamProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "serverName": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[^\\s/:@?#]+$"
+              }
+            },
+            "required": [
+              "port",
+              "serverName"
+            ],
+            "description": "Socket故障验收：WSS固定loopback TCP，API仍标准TLS直连"
+          },
+          "webApiProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            },
+            "required": [
+              "port"
+            ],
+            "description": "出站JSON Web API专用故障代理：仅slack.com:443，固定loopbackTCP，保留SNI和证书校验，与Socket代理独立；上传域名不适用"
           }
         },
         "required": [

package/src/endpoint.ts

@@ -1,15 +1,19 @@
-import { Endpoint } from 'zhin.js/adapter';
 /**
  * SlackEndpoint — lifecycle, outbound, admit, Socket Mode, agent tool surface.
  */
 import { SocketModeClient } from '@slack/socket-mode';
-import { WebClient } from '@slack/web-api';
-import type {
-  EndpointFriend,
-  EndpointGroup,
-  EndpointControl,
-  EndpointManagement,
-  EndpointSendRequest,
+import { createSlackWebApiAgent } from './web-api-proxy.js';
+import { createSlackStreamAgent } from './stream-proxy.js';
+import { slackSocketConnectionError } from './socket-error.js';
+import { createSlackWebClient, slackDeliveryError } from './web-client.js';
+import {
+  Endpoint,
+  createEndpointLifecycle,
+  type EndpointFriend,
+  type EndpointGroup,
+  type EndpointControl,
+  type EndpointManagement,
+  type EndpointSendRequest,
 } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
@@ -96,6 +100,7 @@ export interface SlackEndpointOptions {
   readonly createSocket?: (opts: {
     readonly appToken: string;
     readonly clientPingTimeout: number;
+    readonly autoReconnectEnabled: false;
   }) => SlackSocketLike;
 }
 
@@ -106,7 +111,9 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
   readonly #inboundFilter = createSlackInboundFilterState();
   readonly #messageChannelMap = new Map<string, string>();
   #client?: SlackWebClientLike;
+  #webApiAgent?: ReturnType<typeof createSlackWebApiAgent>;
   #socket?: SlackSocketLike;
+  readonly #lifecycle: ReturnType<typeof createEndpointLifecycle>;
   #routeReleases: HttpRouteRegistration[] = [];
   #botUserId?: string;
   #open = false;
@@ -142,6 +149,7 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
     super();
     this.#logger = getAdapterLogger('slack', options.config.id);
     this.#options = options;
+    this.#lifecycle = createEndpointLifecycle({ name: options.config.id });
   }
 
   /** Console 展示 / AdapterIndex live name（多 endpoint 时与 entry name 一致）。 */
@@ -154,6 +162,8 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
     return this.#client;
   }
 
+  get transportState() { return this.config.mode === 'socket' ? this.#lifecycle.state : this.#started ? 'open' : 'stopped'; }
+
   get platformUserId(): string | undefined {
     return this.#botUserId;
   }
@@ -167,8 +177,9 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
     this.#started = true;
     try {
       const { config } = this.#options;
+      if (config.webApiProxy && !this.#options.createClient) this.#webApiAgent = createSlackWebApiAgent(config.webApiProxy);
       this.#client = this.#options.createClient?.(config.token)
-        ?? (new WebClient(config.token) as unknown as SlackWebClientLike);
+        ?? (createSlackWebClient(config.token, this.#webApiAgent ? { agent: this.#webApiAgent } : {}) as unknown as SlackWebClientLike);
 
       if (config.mode === 'socket') {
         await this.#startSocket();
@@ -209,6 +220,9 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
 
   async stop(): Promise<void> {
     this.#open = false;
+    this.#webApiAgent?.destroy();
+    this.#webApiAgent = undefined;
+    await this.#lifecycle.stop();
     if (this.#socket) {
       try {
         await this.#socket.disconnect();
@@ -227,6 +241,7 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
     if (!this.#client) throw new Error('Slack client not connected');
     const channel = conversation.id;
     const threadTs = conversation.threadId;
+    try {
     const result = await sendSlackContent(
       this.#client,
       payload,
@@ -235,6 +250,7 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
     );
     this.trackMessageChannel(result.ts, channel);
     return formatSlackMessageRef(channel, result.ts);
+    } catch (error) { throw slackDeliveryError(error); }
   }
 
   /** Test / internal: admit a message event when open. */
@@ -295,6 +311,7 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
       conversation,
       message: { conversation, id: actionTs },
       content: formatInteractionContent(payload),
+      segments: [{ type: 'action', data: { id: actionTs, payload: payload.actions[0].value ?? payload.actions[0].action_id, ...(messageTs ? { sourceMessageId: messageTs } : {}) } }],
       sender: { id: userId },
       endpointId: this.#options.config.id,
       metadata: Object.freeze({
@@ -430,28 +447,23 @@ export class SlackEndpoint extends Endpoint<SlackWebClientLike> implements Slack
     if (!config.appToken.startsWith('xapp-')) {
       throw new Error(`Slack appToken 格式不正确：Socket Mode 需要 xapp- 前缀的 App-Level Token（当前看起来是 ${config.appToken.slice(0, 5)}…，xoxb- 是 bot token，请填到 token 字段）`);
     }
-    this.#socket = this.#options.createSocket?.({
-      appToken: config.appToken,
-      clientPingTimeout: config.clientPingTimeout,
-    }) ?? new SocketModeClient({
-      appToken: config.appToken,
-      clientPingTimeout: config.clientPingTimeout,
-    }) as unknown as SlackSocketLike;
-
-    this.#socket.on('slack_event', async ({ ack, body }) => {
-      await ack();
-      this.handleEnvelope(body);
+    await this.#lifecycle.start(async handle => {
+      let active = true;
+      let connectionError: Error | undefined;
+      const agent = config.streamProxy ? createSlackStreamAgent(config.streamProxy) : undefined;
+      const socket = this.#options.createSocket?.({ appToken: config.appToken!, clientPingTimeout: config.clientPingTimeout, autoReconnectEnabled: false })
+        ?? new SocketModeClient({ appToken: config.appToken!, clientPingTimeout: config.clientPingTimeout,
+          autoReconnectEnabled: false, ...(agent ? { clientOptions: { agent } } : {}) }) as unknown as SlackSocketLike;
+      this.#socket = socket;
+      const release = () => { if (!active) return; active = false; if (this.#socket === socket) this.#socket = undefined; agent?.destroy(); void socket.disconnect().catch(() => {}); };
+      handle.onForceClose(release);
+      socket.on('disconnected', () => { if (!active) return; release(); handle.notifyClosed('Slack socket disconnected'); });
+      socket.on('error', error => { connectionError = slackSocketConnectionError(error); if (!active) return; release(); handle.notifyClosed('Slack socket error'); });
+      socket.on('slack_event', async ({ ack, body }) => { if (!active || this.#socket !== socket) return; await ack(); if (active) this.handleEnvelope(body); });
+      socket.on('interactive', async ({ ack, body }) => { if (!active || this.#socket !== socket) return; await ack(); if (active) this.admitInteraction(body as SlackInteractionPayload); });
+      socket.on('slash_commands', async ({ ack, body }) => { if (!active || this.#socket !== socket) return; await ack(); if (active) this.admitSlashCommand(body as SlackSlashCommand); });
+      try { await socket.start(); } catch (error) { release(); throw connectionError ?? slackSocketConnectionError(error); }
     });
-    this.#socket.on('interactive', async ({ ack, body }) => {
-      await ack();
-      this.admitInteraction(body as SlackInteractionPayload);
-    });
-    this.#socket.on('slash_commands', async ({ ack, body }) => {
-      await ack();
-      this.admitSlashCommand(body as SlackSlashCommand);
-    });
-
-    await this.#socket.start();
   }
 }
 

package/src/protocol.ts

@@ -20,6 +20,8 @@ const MAX_TIMESTAMP_DRIFT_SECONDS = 300;
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface SlackEndpointConfig {
+  readonly webApiProxy?: import('./web-api-proxy.js').SlackWebApiProxy;
+  readonly streamProxy?: import('./stream-proxy.js').SlackStreamProxy;
   readonly id: string;
   readonly token: string;
   readonly signingSecret?: string;
@@ -31,6 +33,8 @@ export interface SlackEndpointConfig {
 }
 
 export interface ResolvedSlackConfig {
+  readonly webApiProxy?: import('./web-api-proxy.js').SlackWebApiProxy;
+  readonly streamProxy?: import('./stream-proxy.js').SlackStreamProxy;
   readonly context: 'slack';
   readonly id: string;
   readonly token: string;
@@ -118,6 +122,9 @@ export interface SlackWireSegment {
 }
 
 export function resolveSlackConfig(config: SlackEndpointConfig): ResolvedSlackConfig {
+  if (config.webApiProxy && (!Number.isInteger(config.webApiProxy.port) || config.webApiProxy.port < 1 || config.webApiProxy.port > 65535)) throw new TypeError('Invalid Slack webApiProxy port');
+  if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
+    || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName) || config.streamProxy.serverName === 'slack.com')) throw new TypeError('Invalid Slack streamProxy port/serverName');
   const id = requiredEndpointField(config.id, 'id');
   const token = requiredEndpointField(config.token, 'token');
   const socketMode = config.socketMode;
@@ -132,6 +139,8 @@ export function resolveSlackConfig(config: SlackEndpointConfig): ResolvedSlackCo
     : config.appToken?.trim();
 
   return {
+    ...(config.webApiProxy ? { webApiProxy: config.webApiProxy } : {}),
+    ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
     context: 'slack',
     id,
     token,
@@ -214,6 +223,7 @@ export function formatSlashContent(cmd: SlackSlashCommand): string {
  * Segment canonicalization is intentionally not done here.
  */
 export function formatOutboundWire(payload: unknown): {
+  replyTo?: string;
   text: string;
   blocks: Record<string, unknown>[];
   attachments: Record<string, unknown>[];
@@ -242,6 +252,7 @@ export function formatOutboundWire(payload: unknown): {
   const blocks: Record<string, unknown>[] = [];
   const attachments: Record<string, unknown>[] = [];
   const files: Array<{ buffer?: Buffer; url?: string; path?: string; name?: string }> = [];
+  let replyTo: string | undefined;
 
   for (const item of items) {
     if (typeof item === 'string') {
@@ -250,6 +261,10 @@ export function formatOutboundWire(payload: unknown): {
     }
     const data = item.data ?? {};
     switch (item.type) {
+      case 'reply':
+        if (typeof data.message_id === 'string' && data.message_id) replyTo = data.message_id;
+        break;
+      case 'markdown':
       case 'text':
         text += String(data.text ?? data.content ?? '');
         break;
@@ -281,7 +296,7 @@ export function formatOutboundWire(payload: unknown): {
           });
           break;
         }
-        const imageFile = resolveMediaToFile(media, String(data.alt ?? media.file_name ?? 'image'));
+        const imageFile = resolveMediaToFile(media, String(media.file_name ?? mediaDefaultFilename('image', media)));
         if (imageFile) files.push(imageFile);
         else dropOutboundMedia(item.type, 'unsupported_media_kind');
         break;
@@ -294,11 +309,14 @@ export function formatOutboundWire(payload: unknown): {
           dropOutboundMedia(item.type, 'missing_media_ref');
           break;
         }
-        const mediaFile = resolveMediaToFile(media, String(data.name ?? media.file_name ?? item.type));
+        const mediaFile = resolveMediaToFile(media, String(media.file_name ?? data.name ?? mediaDefaultFilename(item.type, media)));
         if (mediaFile) files.push(mediaFile);
         else dropOutboundMedia(item.type, 'unsupported_media_kind');
         break;
       }
+      case 'share':
+        attachments.push({ title: String(data.title ?? ''), title_link: String(data.url ?? ''), text: String(data.description ?? data.content ?? ''), ...(data.image ? { image_url: String(data.image) } : {}) });
+        break;
       case 'keyboard':
         blocks.push(...keyboardToBlockKitBlocks(data));
         break;
@@ -307,7 +325,7 @@ export function formatOutboundWire(payload: unknown): {
     }
   }
 
-  return { text, blocks, attachments, files };
+  return { text, blocks, attachments, files, ...(replyTo ? { replyTo } : {}) };
 }
 
 export function keyboardToBlockKitBlocks(data: Record<string, unknown>): Record<string, unknown>[] {
@@ -320,7 +338,7 @@ export function keyboardToBlockKitBlocks(data: Record<string, unknown>): Record<
       type: 'button',
       text: { type: 'plain_text', text: String(btn.label ?? btn.text ?? 'button').slice(0, 75) },
       action_id: String(btn.id ?? btn.action_id ?? `btn_${blocks.length}_${index}`),
-      ...(btn.value != null ? { value: String(btn.value) } : {}),
+      ...(btn.payload != null || btn.value != null ? { value: String(btn.payload ?? btn.value) } : {}),
       ...(btn.style === 'primary' ? { style: 'primary' } : {}),
       ...(btn.style === 'danger' ? { style: 'danger' } : {}),
     }));
@@ -338,6 +356,15 @@ export function keyboardToBlockKitBlocks(data: Record<string, unknown>): Record<
  * - kind=path → 记录本地路径，上传前读盘；
  * - kind=file → Slack 无平台不透明文件引用可直发，返回 undefined 由调用方丢弃留痕。
  */
+function mediaDefaultFilename(kind: string, media: MediaRef): string {
+  const extension = ({
+    'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp',
+    'audio/mpeg': 'mp3', 'audio/ogg': 'ogg', 'audio/wav': 'wav',
+    'video/mp4': 'mp4', 'video/webm': 'webm', 'application/pdf': 'pdf',
+  } as Record<string, string>)[media.mime_type?.split(';')[0].trim().toLowerCase() ?? ''];
+  return `${kind}${extension ? `.${extension}` : ''}`;
+}
+
 function resolveMediaToFile(
   media: MediaRef,
   name: string,

package/src/slack-outbound.ts

@@ -31,12 +31,13 @@ export async function sendSlackContent(
   logger: Logger,
 ): Promise<SlackOutboundResult> {
   const wire = formatOutboundWire(content);
+  const threadTs = opts.threadTs ?? wire.replyTo;
   const blocks = [...wire.blocks];
   const textDelivery = applyTextMrkdwnBlocks(wire.text, blocks);
 
   for (const pf of wire.files) {
     try {
-      await uploadFile(client, opts.channel, pf, opts.threadTs);
+      await uploadFile(client, opts.channel, pf, threadTs);
     } catch (e) {
       logger.error('Failed to upload file:', e);
       throw e;
@@ -45,7 +46,7 @@ export async function sendSlackContent(
 
   return postSlackMessage(client, {
     channel: opts.channel,
-    threadTs: opts.threadTs,
+    threadTs,
     blocks,
     attachments: wire.attachments,
     fallbackText: textDelivery.fallbackText,

package/src/socket-error.ts

@@ -0,0 +1,12 @@
+/** SDK can reject start() with undefined; never pass raw URL-bearing SDK errors to logs. */
+export function slackSocketConnectionError(value: unknown): Error {
+  const proxyReason = 'Slack Stream proxy gateway identity changed; update fixed upstream before retrying';
+  const source = value && typeof value === 'object' ? value as { message?: unknown; code?: unknown; original?: { message?: unknown; code?: unknown } } : undefined;
+  if (source?.message === proxyReason || source?.original?.message === proxyReason) {
+    return new Error('Slack Socket Mode gateway identity changed; fault proxy refused the connection');
+  }
+  const code = source?.original?.code ?? source?.code;
+  const safeCodes = ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ERR_TLS_CERT_ALTNAME_INVALID', 'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'];
+  if (typeof code === 'string' && safeCodes.includes(code)) return new Error(`Slack Socket Mode connection failed (${code})`);
+  return new Error('Slack Socket Mode connection failed; SDK did not confirm a connection');
+}

package/src/stream-proxy.ts

@@ -0,0 +1,22 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { Socket } from 'node:net';
+import { getLogger } from '@zhin.js/logger';
+export interface SlackStreamProxy { readonly port: number; readonly serverName: string }
+export function createSlackStreamAgent(proxy: SlackStreamProxy): Agent {
+  const agent = new Agent({ keepAlive: false });
+  const direct = agent.createConnection.bind(agent);
+  agent.createConnection = (options, callback) => {
+    const hostname = String(options.hostname ?? options.host ?? '');
+    const headers = options.headers as Record<string, unknown> | undefined;
+    const upgrade = Object.entries(headers ?? {}).some(([name, value]) => name.toLowerCase() === 'upgrade' && String(value).toLowerCase() === 'websocket');
+    if (hostname === proxy.serverName && Number(options.port ?? 443) === 443) return tls.connect({ ...options as tls.ConnectionOptions, path: undefined,
+      host: '127.0.0.1', port: proxy.port, servername: hostname, rejectUnauthorized: true });
+    if (!upgrade && hostname === 'slack.com' && Number(options.port ?? 443) === 443) return direct(options, callback);
+    getLogger('slack').warn(`Stream proxy rejected gateway hostname: ${hostname}`);
+    const rejected = new Socket();
+    queueMicrotask(() => rejected.destroy(new Error('Slack Stream proxy gateway identity changed; update fixed upstream before retrying')));
+    return rejected;
+  };
+  return agent;
+}

package/src/web-api-proxy.ts

@@ -0,0 +1,21 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { Socket } from 'node:net';
+
+export interface SlackWebApiProxy { readonly port: number }
+
+/** JSON Web API only: keep slack.com identity, route TCP to a fixed loopback port. */
+export function createSlackWebApiAgent(proxy: SlackWebApiProxy): Agent {
+  const agent = new Agent({ keepAlive: false });
+  agent.createConnection = options => {
+    const hostname = String(options.hostname ?? options.host ?? '');
+    if (hostname !== 'slack.com' || Number(options.port ?? 443) !== 443) {
+      const rejected = new Socket();
+      queueMicrotask(() => rejected.destroy(new Error('Slack Web API proxy rejected destination identity')));
+      return rejected;
+    }
+    return tls.connect({ ...options as tls.ConnectionOptions, path: undefined,
+      host: '127.0.0.1', port: proxy.port, servername: 'slack.com', rejectUnauthorized: true });
+  };
+  return agent;
+}

package/src/web-client.ts

@@ -0,0 +1,17 @@
+import { WebClient, ErrorCode, type WebClientOptions } from '@slack/web-api';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+
+/** A non-idempotent outbound API call gets exactly one transport attempt. */
+export function createSlackWebClient(token: string, options: WebClientOptions = {}): WebClient {
+  return new WebClient(token, { ...options, retryConfig: { retries: 0 }, rejectRateLimitedCalls: true });
+}
+
+export function slackDeliveryError(error: unknown): EndpointDeliveryError {
+  if (error instanceof EndpointDeliveryError) return error;
+  const value = error as { code?: unknown; statusCode?: unknown } | undefined;
+  const status = typeof value?.statusCode === 'number' ? value.statusCode : undefined;
+  const rejected = value?.code === ErrorCode.PlatformError || value?.code === ErrorCode.RateLimitedError
+    || value?.code === ErrorCode.HTTPError && status !== undefined && status >= 400 && status < 500 && status !== 408;
+  return new EndpointDeliveryError(rejected ? 'platform_rejected' : 'delivery_unconfirmed',
+    rejected ? 'Slack rejected outbound request' : 'Slack outbound outcome is unknown', rejected ? 'rejected' : 'unknown');
+}