@zhin.js/adapter-kook 1.1.4 → 1.1.5

package/src/endpoint.ts

@@ -1,25 +1,27 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { EndpointDeliveryError, type ConversationRef } from '@zhin.js/im-contract';
 /**
  * KookEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
 import { Client } from 'kook-client';
 import {
-  createRecallEndpointControl,
+  Endpoint,
   type EndpointControl,
   type EndpointChannel,
   type EndpointGroup,
   type EndpointManagement,
   type EndpointSendRequest,
+  type EndpointTransportState,
 } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import {
   formatInboundContent,
-  formatOutboundKmarkdown,
+
   isKookBotMentioned,
   kookInboundConversation,
   normalizeKookWebhookEvent,
+  normalizeKookButtonEvent,
   senderDisplayName,
   type KookInboundMessage,
   type KookWebhookEventData,
@@ -34,6 +36,7 @@ import {
   type CreateKookClient,
   type KookClientTransport,
 } from './ws.js';
+import { recallKookMessage, sendKookOutbound } from './outbound.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
 
 export interface KookEndpointOptions {
@@ -43,6 +46,7 @@ export interface KookEndpointOptions {
 }
 
 export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
+  #sentConversations = new Map<string, ConversationRef>();
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: KookEndpointOptions;
@@ -51,7 +55,9 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
   #open = false;
   #started = false;
   readonly management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient());
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly control: EndpointControl = Object.freeze<EndpointControl>({
+    recall: (message) => recallKookMessage(this.#requireClient(), message),
+  });
 
   constructor(options: KookEndpointOptions) {
     super();
@@ -64,6 +70,11 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
     return this.#requireClient();
   }
 
+  get transportState(): EndpointTransportState | undefined {
+    if (!this.#started) return 'stopped';
+    return this.#client?.getTransportState?.();
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
@@ -94,6 +105,7 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
 
   async stop(): Promise<void> {
     this.#open = false;
+    this.#sentConversations.clear();
     if (this.#client) {
       try {
         this.#client.removeAllListeners();
@@ -108,12 +120,8 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    const body = formatOutboundKmarkdown(payload);
-    const client = this.#requireClient();
-    const result = conversation.kind === 'private'
-      ? await client.sendPrivateMsg(conversation.id, body)
-      : await client.sendChannelMsg(conversation.id, body);
-    const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+    const messageId = await sendKookOutbound(this.#requireClient(), { conversation, payload });
+    rememberKookConversation(this.#sentConversations, messageId, conversation);
     this.#logger.debug(formatCompact({
       op: 'kook_send',
       endpoint: this.#options.config.id,
@@ -155,9 +163,9 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
     });
   }
 
-  async recallMessage(messageId: string): Promise<void> {
-    if (!messageId) return;
-    await this.#requireClient().recallMsg?.(messageId);
+  async recallMessage(messageId: string, conversation?: ConversationRef): Promise<void> {
+    if (!conversation) throw new EndpointDeliveryError('unsupported_operation', 'KOOK recall requires conversation routing', 'rejected');
+    await recallKookMessage(this.#requireClient(), { id: messageId, conversation });
   }
 
   #bindClient(client: KookClientTransport): void {
@@ -168,11 +176,23 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
     });
     const receiver = (client as { receiver?: { on(event: string, listener: (...args: unknown[]) => void): void } }).receiver;
     receiver?.on('event', (raw) => {
+      if (this.#client !== client || !this.#open) return;
       this.#emitPlatformEvent('event', raw);
+      if (normalizeKookButtonEvent(raw)) {
+        void this.admitButton(raw).catch(error => this.#logger.warn(formatCompact({ op: 'kook_button_failed', error: error instanceof Error ? error.message : 'dispatch failed' })));
+        return;
+      }
       receiveKookSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, raw, this.#logger);
     });
   }
 
+  async admitButton(raw: unknown): Promise<void> {
+    if (!this.#open) throw new Error('KOOK endpoint is closed');
+    const event = normalizeKookButtonEvent(raw);
+    if (!event) throw new Error('Invalid KOOK button event');
+    await this.emitAccepted('message.receive', kookButtonIngress(String(this.#options.id), this.#options.config.id, event, this.#sentConversations.get(event.sourceMessageId)));
+  }
+
   #emitPlatformEvent(name: string, event: unknown): void {
     void this.emitPlatform(name, event).catch((error) => {
       this.#logger.warn(formatCompact({
@@ -197,6 +217,7 @@ export interface KookWebhookEndpointOptions {
 }
 
 export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
+  #sentConversations = new Map<string, ConversationRef>();
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: KookWebhookEndpointOptions;
@@ -207,7 +228,9 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
   #open = false;
   #started = false;
   readonly management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient());
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly control: EndpointControl = Object.freeze<EndpointControl>({
+    recall: (message) => recallKookMessage(this.#requireClient(), message),
+  });
 
   constructor(options: KookWebhookEndpointOptions) {
     super();
@@ -264,6 +287,7 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
 
   async stop(): Promise<void> {
     this.#open = false;
+    this.#sentConversations.clear();
     for (const release of this.#routeReleases.splice(0)) release();
     this.#processedSn.clear();
     if (this.#client) {
@@ -280,12 +304,8 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    const body = formatOutboundKmarkdown(payload);
-    const client = this.#requireClient();
-    const result = conversation.kind === 'private'
-      ? await client.sendPrivateMsg(conversation.id, body)
-      : await client.sendChannelMsg(conversation.id, body);
-    const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+    const messageId = await sendKookOutbound(this.#requireClient(), { conversation, payload });
+    rememberKookConversation(this.#sentConversations, messageId, conversation);
     this.#logger.debug(formatCompact({
       op: 'kook_send',
       endpoint: this.#options.config.id,
@@ -295,7 +315,13 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
     return messageId;
   }
 
-  admitEvent(event: KookWebhookEventData): void {
+  async admitEvent(event: KookWebhookEventData): Promise<void> {
+    if (normalizeKookButtonEvent(event)) {
+      if (!this.#open) throw new Error('KOOK endpoint is closed');
+      const button = normalizeKookButtonEvent(event)!;
+      await this.emitAccepted('message.receive', kookButtonIngress(String(this.#options.id), this.#options.config.id, button, this.#sentConversations.get(button.sourceMessageId)));
+      return;
+    }
     void this.emitPlatform(String(event.type ?? 'event'), event).catch((error) => {
       this.#logger.warn(formatCompact({
         op: 'kook_platform_event_failed',
@@ -348,9 +374,9 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
     });
   }
 
-  async recallMessage(messageId: string): Promise<void> {
-    if (!messageId) return;
-    await this.#requireClient().recallMsg?.(messageId);
+  async recallMessage(messageId: string, conversation?: ConversationRef): Promise<void> {
+    if (!conversation) throw new EndpointDeliveryError('unsupported_operation', 'KOOK recall requires conversation routing', 'rejected');
+    await recallKookMessage(this.#requireClient(), { id: messageId, conversation });
   }
 
   checkAndRememberSn(sn: number): boolean {
@@ -363,6 +389,8 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
     return true;
   }
 
+  forgetSn(sn: number): void { this.#processedSn.delete(sn); }
+
   #requireClient(): KookClientTransport {
     if (!this.#client) throw new Error('KOOK client not initialized');
     return this.#client;
@@ -380,6 +408,21 @@ function toGroupId(id: string): number {
 }
 
 /** KOOK 文字频道标记：HTTP API type=1（2=语音），kook-client 消息侧用 'GROUP'。 */
+function rememberKookConversation(cache: Map<string, ConversationRef>, messageId: string, conversation: ConversationRef): void {
+  cache.set(messageId, conversation);
+  while (cache.size > 2048) cache.delete(cache.keys().next().value!);
+}
+
+function kookButtonIngress(endpointKey: string, endpointId: string, event: NonNullable<ReturnType<typeof normalizeKookButtonEvent>>, sentConversation?: ConversationRef) {
+  const conversation: ConversationRef = { endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: sentConversation?.kind ?? event.channelKind, id: sentConversation?.id ?? event.channelId,
+    ...(sentConversation?.parent ? { parent: sentConversation.parent } : {}) };
+  return { conversation, message: { conversation, id: event.id }, content: `[action: ${event.payload}]`,
+    segments: [{ type: 'action', data: { id: event.id, payload: event.payload, sourceMessageId: event.sourceMessageId } }],
+    sender: { id: event.userId }, endpointId,
+    metadata: Object.freeze({ eventType: 'message_btn_click', payload: event.payload, sourceMessageId: event.sourceMessageId, timestamp: event.timestamp }) };
+}
+
 function isKookTextChannelType(type: string | number | undefined): boolean {
   return type === 1 || type === '1' || type === 'GROUP';
 }

package/src/outbound.ts

@@ -0,0 +1,109 @@
+import { readFile } from 'node:fs/promises';
+import { EndpointDeliveryError, isMediaRef, type MessageRef } from '@zhin.js/im-contract';
+import type { EndpointSendRequest } from 'zhin.js/adapter';
+import { formatOutboundKmarkdown } from './protocol.js';
+import type { KookClientTransport } from './ws.js';
+
+/** Native cards preserve mixed text/images; SDK's ordinary segments stop at first media. */
+export async function sendKookOutbound(client: KookClientTransport, { conversation, payload }: EndpointSendRequest): Promise<string> {
+  try {
+    const items = Array.isArray(payload) ? payload : payload && typeof payload === 'object' ? [payload] : [payload];
+    let quote: { message_id: string } | undefined;
+    const modules: unknown[] = [];
+    let hasImage = false;
+    let hasCard = false;
+    for (const item of items) {
+      if (item && typeof item === 'object' && item.type === 'reply') {
+        if (typeof item.data?.message_id === 'string' && item.data.message_id.trim()) quote = { message_id: item.data.message_id };
+        continue;
+      }
+      if (item && typeof item === 'object' && item.type === 'keyboard') {
+        hasCard = true;
+        const rows = item.data?.rows;
+        if (!Array.isArray(rows) || !rows.length) throw new EndpointDeliveryError('invalid_payload', 'KOOK keyboard requires button rows', 'not_sent');
+        for (const row of rows) {
+          if (!Array.isArray(row) || !row.length || row.length > 4) throw new EndpointDeliveryError('invalid_payload', 'KOOK button rows require 1-4 buttons', 'not_sent');
+          const elements = row.map(button => {
+            if (!button || typeof button !== 'object' || typeof button.label !== 'string' || !button.label.trim() || typeof button.payload !== 'string' || !button.payload) throw new EndpointDeliveryError('invalid_payload', 'KOOK buttons require label and payload', 'not_sent');
+            if (button.disabled || button.mode === 'command') throw new EndpointDeliveryError('unsupported_operation', 'KOOK disabled/command buttons are not implemented', 'not_sent');
+            return { type: 'button', theme: button.style === 'danger' ? 'danger' : button.style === 'primary' ? 'primary' : 'secondary',
+              value: button.payload, click: 'return-val', text: { type: 'plain-text', content: button.label } };
+          });
+          modules.push({ type: 'action-group', elements });
+        }
+      } else if (item && typeof item === 'object' && item.type === 'share') {
+        hasCard = true;
+        const data = item.data ?? {};
+        let url: URL;
+        try { url = new URL(data.url); } catch { throw new EndpointDeliveryError('invalid_payload', 'KOOK share requires an HTTP(S) URL', 'not_sent'); }
+        if (!['http:', 'https:'].includes(url.protocol) || typeof data.title !== 'string' || !data.title.trim()) throw new EndpointDeliveryError('invalid_payload', 'KOOK share requires URL and title', 'not_sent');
+        if (['image', 'audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined)) throw new EndpointDeliveryError('unsupported_operation', 'KOOK share media/app metadata is not implemented', 'not_sent');
+        modules.push({ type: 'section', mode: 'left', text: { type: 'plain-text', content: data.title } });
+        for (const value of [data.description, data.content]) if (typeof value === 'string' && value) modules.push({ type: 'section', mode: 'left', text: { type: 'plain-text', content: value } });
+        modules.push({ type: 'action-group', elements: [{ type: 'button', theme: 'secondary', click: 'link', value: url.href, text: { type: 'plain-text', content: '打开链接' } }] });
+      } else if (item && typeof item === 'object' && item.type === 'image') {
+        hasImage = true;
+        const media = item.data?.media;
+        if (!isMediaRef(media)) throw new EndpointDeliveryError('unsupported_media', 'KOOK image requires canonical media', 'rejected');
+        let url: string;
+        if (media.kind === 'file') url = media.value;
+        else {
+          if (!client.uploadMedia) throw new EndpointDeliveryError('unsupported_media', 'KOOK transport cannot upload images', 'rejected');
+          let bytes: Buffer;
+          if (media.kind === 'base64') bytes = Buffer.from(media.value.replace(/^data:[^,]*,/, ''), 'base64');
+          else if (media.kind === 'path') bytes = await readFile(media.value);
+          else {
+            const response = await fetch(media.value, { signal: AbortSignal.timeout(30_000) });
+            if (!response.ok) throw new EndpointDeliveryError('media_download_failed', 'KOOK media download failed', 'rejected');
+            bytes = Buffer.from(await response.arrayBuffer());
+          }
+          url = await client.uploadMedia(bytes);
+        }
+        if (typeof url !== 'string' || !/^https:\/\//.test(url)) throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK upload returned no media URL', 'unknown');
+        modules.push({ type: 'container', elements: [{ type: 'image', src: url, alt: String(item.data?.alt ?? 'image') }] });
+      } else {
+        if (item && typeof item === 'object' && ['file', 'audio', 'video'].includes(item.type)
+          && isMediaRef(item.data?.media) && !['url', 'file'].includes(item.data.media.kind)) {
+          throw new EndpointDeliveryError('unsupported_media', 'KOOK binary uploads currently support images only', 'rejected');
+        }
+        const text = formatOutboundKmarkdown([item]);
+        if (text) modules.push({ type: 'section', mode: 'left', text: { type: 'kmarkdown', content: text } });
+      }
+    }
+    const body = hasImage || hasCard ? { __isCard: true, type: 'card', theme: 'secondary', size: 'lg', modules } : formatOutboundKmarkdown(payload);
+    const result = conversation.kind === 'private'
+      ? await client.sendPrivateMsg(conversation.id, body, quote)
+      : await client.sendChannelMsg(conversation.id, body, quote);
+    const id = result?.msg_id != null ? String(result.msg_id) : '';
+    if (!id.trim()) throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK did not return a real message ID', 'unknown');
+    return id;
+  } catch (error) {
+    if (error instanceof EndpointDeliveryError) throw error;
+    // Installed SDK discards HTTP metadata; its exact numerical rejection prefix is safe to recover.
+    const code = error instanceof Error ? /error with code\((\d+)\):/.exec(error.message)?.[1] : undefined;
+    if (code && Number(code) !== 408 && !(Number(code) >= 500 && Number(code) < 600)) throw new EndpointDeliveryError('platform_rejected', `KOOK request rejected (code=${code})`, 'rejected');
+    throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK outbound outcome is unknown', 'unknown');
+  }
+}
+
+
+/** Deletion requires the canonical conversation: KOOK has separate channel/private APIs. */
+export async function recallKookMessage(client: KookClientTransport, message: MessageRef): Promise<void> {
+  if (!message.id.trim()) throw new EndpointDeliveryError('invalid_message_id', 'KOOK recall requires a message ID', 'rejected');
+  try {
+    let deleted: boolean;
+    if (message.conversation.kind === 'private') {
+      if (!client.recallPrivateMsg) throw new EndpointDeliveryError('unsupported_operation', 'KOOK transport cannot delete private messages', 'rejected');
+      deleted = await client.recallPrivateMsg(message.conversation.id, message.id);
+    } else {
+      if (!client.recallChannelMsg) throw new EndpointDeliveryError('unsupported_operation', 'KOOK transport cannot delete channel messages', 'rejected');
+      deleted = await client.recallChannelMsg(message.conversation.id, message.id);
+    }
+    if (deleted !== true) throw new EndpointDeliveryError('platform_rejected', 'KOOK did not confirm message deletion', 'rejected');
+  } catch (error) {
+    if (error instanceof EndpointDeliveryError) throw error;
+    const code = error instanceof Error ? /error with code\((\d+)\):/.exec(error.message)?.[1] : undefined;
+    if (code && Number(code) !== 408 && !(Number(code) >= 500 && Number(code) < 600)) throw new EndpointDeliveryError('platform_rejected', `KOOK deletion rejected (code=${code})`, 'rejected');
+    throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK deletion outcome is unknown', 'unknown');
+  }
+}

package/src/protocol.ts

@@ -3,7 +3,7 @@
 import { createDecipheriv, timingSafeEqual } from 'node:crypto';
 import { inflateSync } from 'node:zlib';
 import type { IncomingMessage } from 'node:http';
-import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('kook');
@@ -27,6 +27,8 @@ export enum KookPermission {
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface KookEndpointConfig {
+  readonly apiProxy?: import('./api-proxy.js').KookApiProxy;
+  readonly streamProxy?: import('./stream-proxy.js').KookStreamProxy;
   readonly id: string;
   readonly token: string;
   /** Default `websocket`. `webhook` requires httpHostToken + verify_token. */
@@ -42,6 +44,8 @@ export interface KookEndpointConfig {
 }
 
 export interface ResolvedKookWebsocketConfig {
+  readonly apiProxy?: import('./api-proxy.js').KookApiProxy;
+  readonly streamProxy?: import('./stream-proxy.js').KookStreamProxy;
   readonly context: 'kook';
   readonly connection: 'websocket';
   readonly id: string;
@@ -54,6 +58,7 @@ export interface ResolvedKookWebsocketConfig {
 }
 
 export interface ResolvedKookWebhookConfig {
+  readonly apiProxy?: import('./api-proxy.js').KookApiProxy;
   readonly context: 'kook';
   readonly connection: 'webhook';
   readonly id: string;
@@ -84,6 +89,7 @@ export interface KookWebhookEventData {
       readonly author_id?: string;
       readonly target_id?: string;
       readonly chat_code?: string;
+      readonly value?: string;
       readonly emoji?: { readonly id?: string; readonly name?: string };
     };
     readonly guild_id?: string;
@@ -125,6 +131,9 @@ export interface KookWireSegment {
 }
 
 export function resolveKookConfig(config: KookEndpointConfig): ResolvedKookConfig {
+  if (config.apiProxy && (!Number.isInteger(config.apiProxy.port) || config.apiProxy.port < 1 || config.apiProxy.port > 65535)) throw new TypeError('Invalid KOOK apiProxy 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))) throw new TypeError('Invalid KOOK streamProxy port/serverName');
   const id = requiredEndpointField(config.id, 'id');
   const token = requiredEndpointField(config.token, 'token');
   const connection = config.connection ?? 'websocket';
@@ -135,6 +144,7 @@ export function resolveKookConfig(config: KookEndpointConfig): ResolvedKookConfi
     return {
       context: 'kook',
       connection: 'webhook',
+      ...(config.apiProxy ? { apiProxy: config.apiProxy } : {}),
       id,
       token,
       webhookPath: normalizeWebhookPath(
@@ -150,6 +160,8 @@ export function resolveKookConfig(config: KookEndpointConfig): ResolvedKookConfi
   return {
     context: 'kook',
     connection: 'websocket',
+    ...(config.apiProxy ? { apiProxy: config.apiProxy } : {}),
+    ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
     id,
     token,
     data_dir: config.data_dir,
@@ -262,6 +274,9 @@ export function formatOutboundKmarkdown(payload: unknown): string {
           return String(data.text ?? data.content ?? '');
         case 'markdown':
           return String(data.content ?? data.text ?? '');
+        case 'share':
+        case 'keyboard':
+          throw new EndpointDeliveryError('unsupported_operation', 'KOOK share cards and native keyboards are not implemented', 'not_sent');
         case 'at': {
           const id = String(data.user_id ?? data.qq ?? data.id ?? '');
           return id === 'all' ? '(met)all(met)' : `(met)${id}(met)`;
@@ -441,3 +456,20 @@ export function normalizeKookWebhookEvent(
     guildId: event.extra?.guild_id,
   };
 }
+
+/** Native Card return-val events; routing and actor must come from the click event. */
+export function normalizeKookButtonEvent(raw: unknown): { id: string; sourceMessageId: string; payload: string; userId: string; channelKind: 'private' | 'channel'; channelId: string; timestamp: number } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const event = raw as KookWebhookEventData;
+  if (event.extra?.type !== 'message_btn_click') return null;
+  const body = event.extra.body;
+  if (!body || typeof body.value !== 'string' || !body.value || !body.user_id || !body.msg_id) return null;
+  // Button system notifications can use PERSON even for a channel card.
+  // body.target_id identifies the original channel; envelope target_id is the recipient.
+  const bodyTarget = body.channel_id || body.target_id;
+  const channelKind = (bodyTarget && String(bodyTarget) !== String(body.user_id)) || event.channel_type === 'GROUP' ? 'channel' : 'private';
+  const channelId = channelKind === 'private' ? String(body.user_id) : String(bodyTarget || event.target_id || '');
+  if (!channelId) return null;
+  const timestamp = event.msg_timestamp ?? Date.now();
+  return { id: String(event.msg_id || `button:${body.msg_id}:${timestamp}`), sourceMessageId: String(body.msg_id), payload: body.value, userId: String(body.user_id), channelKind, channelId, timestamp };
+}

package/src/stream-proxy.ts

@@ -0,0 +1,20 @@
+import tls from 'node:tls';
+import WebSocket from 'ws';
+import { getLogger } from '@zhin.js/logger';
+
+export interface KookStreamProxy { readonly port: number; readonly serverName: string }
+
+/** Route TCP only. WSS HTTP Host, path, ticket, TLS SNI and peer validation stay original. */
+export function createKookStreamSocket(url: string, proxy?: KookStreamProxy): WebSocket {
+  if (!proxy) return new WebSocket(url);
+  const target = new URL(url);
+  if (target.protocol !== 'wss:' || target.hostname !== proxy.serverName || (target.port && target.port !== '443')) {
+    // The hostname is safe diagnostics; never print URL/query/ticket or SDK errors.
+    getLogger('kook').warn(`Stream proxy rejected gateway hostname: ${target.hostname}`);
+    throw new Error('KOOK Stream proxy gateway identity changed; update the fixed upstream before retrying');
+  }
+  return new WebSocket(url, {
+    createConnection: (options: import('node:http').ClientRequestArgs) => tls.connect({ ...options as tls.ConnectionOptions, path: undefined, host: '127.0.0.1', port: proxy.port,
+      servername: target.hostname, rejectUnauthorized: true }),
+  });
+}

package/src/webhook.ts

@@ -6,7 +6,6 @@ import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
   isKookWebhookChallenge,
-  normalizeKookWebhookEvent,
   parseKookWebhookBody,
   readRequestBody,
   verifyKookWebhookToken,
@@ -15,7 +14,6 @@ import {
   type KookWebhookFrame,
   type ResolvedKookWebhookConfig,
 } from './protocol.js';
-import { receiveKookSideEvent } from './side-event-dispatch.js';
 
 const logger = getLogger('kook');
 
@@ -24,8 +22,9 @@ export interface KookWebhookHandler {
   readonly isOpen: boolean;
   readonly selfId?: string;
   admit(msg: KookInboundMessage): void;
-  admitEvent(event: KookWebhookEventData): void;
+  admitEvent(event: KookWebhookEventData): Promise<void> | void;
   checkAndRememberSn(sn: number): boolean;
+  forgetSn?(sn: number): void;
 }
 
 export function registerKookWebhookRoutes(
@@ -85,6 +84,11 @@ export async function handleKookWebhookRequest(
       return;
     }
 
+    if (!handler.isOpen) {
+      response.writeHead(503, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ message: 'Endpoint unavailable' }));
+      return;
+    }
     if (frame.sn != null) {
       if (!handler.checkAndRememberSn(frame.sn)) {
         response.writeHead(200, { 'Content-Type': 'application/json' });
@@ -93,8 +97,13 @@ export async function handleKookWebhookRequest(
       }
     }
 
-    if (handler.isOpen) {
-      handleKookWebhookEvent(event, handler);
+    try {
+      await handler.admitEvent(event);
+    } catch {
+      if (frame.sn != null) handler.forgetSn?.(frame.sn);
+      response.writeHead(503, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ message: 'Admission unavailable' }));
+      return;
     }
 
     response.writeHead(200, { 'Content-Type': 'application/json' });
@@ -105,10 +114,3 @@ export async function handleKookWebhookRequest(
     response.end(JSON.stringify({ message: 'OK' }));
   }
 }
-
-function handleKookWebhookEvent(
-  event: KookWebhookEventData,
-  handler: KookWebhookHandler,
-): void {
-  handler.admitEvent(event);
-}