@zhin.js/adapter-kook 7.0.14 → 8.0.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @zhin.js/adapter-kook
 
+## 8.0.1
+
+### Patch Changes
+
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+  - @zhin.js/permission@1.0.4
+
+## 8.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
 ## 7.0.14
 
 ### Patch Changes

package/README.md

@@ -20,7 +20,7 @@ pnpm add @zhin.js/adapter-kook
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/kook.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `@zhin.js/host-http` — Webhook 模式 POST 路由（WebSocket 不需要）
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
@@ -97,7 +97,16 @@ platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；Capa
 
 ## 迁移后出站能力变化
 
-迁移到 Plugin Runtime 后，出站统一经 `messageGatewayToken` 渲染并由 endpoint 编码为 KMarkdown（`sendChannelMsg` / `sendPrivateMsg`）。canonical `markdown` 保留格式；图片、视频、音频和文件仅有远程 URL 时可表示为 KMarkdown 链接。卡片消息与附件上传仍未接入统一出站通道。
+迁移到 Plugin Runtime 后，出站统一经 `outboundMessageToken` 渲染并由 endpoint 编码为 KMarkdown（`sendChannelMsg` / `sendPrivateMsg`）。canonical `markdown` 保留格式；图片、视频、音频和文件仅有远程 URL 时可表示为 KMarkdown 链接。卡片消息与附件上传仍未接入统一出站通道。
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| WebSocket 无法上线 | 检查 Bot Token、网络与机器人能力开关 |
+| Webhook challenge 失败 | 检查公网路径、`verify_token` 与 HTTP Host |
+| 频道消息未触发 | 检查应用订阅、频道权限与机器人是否已加入服务器 |
+| 附件表现为链接 | 当前统一出站不上传附件；使用远程 URL 或按能力降级 |
 
 ## 许可证
 

package/adapters/kook.js

@@ -4,7 +4,6 @@
  * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
 import { resolveKookConfig, } from "../lib/protocol.js";
@@ -12,6 +11,7 @@ import { kookRuntimeStateToken } from "../lib/kook-runtime-state.js";
 export { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
     // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
     // 无按钮交互面，交互段降级纯文本。
     segments: {
@@ -21,8 +21,6 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveKookConfig(context.config);
-        const gateway = context.use(messageGatewayToken);
-        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
         context.use(kookRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -31,16 +29,12 @@ export default defineAdapter({
         if (config.connection === 'webhook') {
             return new KookWebhookEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
         }
         return new KookWebsocketEndpoint({
             id: context.id,
-            gateway,
-            sideEvents,
             config,
         });
     },

package/adapters/kook.ts

@@ -3,7 +3,6 @@
  * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import {
   KookWebhookEndpoint,
@@ -27,6 +26,7 @@ export type { CreateKookClient, KookClientTransport } from '../src/ws.js';
 
 export default defineAdapter<KookAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
   // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
   // 无按钮交互面，交互段降级纯文本。
   segments: {
@@ -36,8 +36,6 @@ export default defineAdapter<KookAdapterConfig>({
   },
   create(context) {
     const config = resolveKookConfig(context.config);
-    const gateway = context.use(messageGatewayToken);
-    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
     context.use(kookRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -46,16 +44,12 @@ export default defineAdapter<KookAdapterConfig>({
     if (config.connection === 'webhook') {
       return new KookWebhookEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
     }
     return new KookWebsocketEndpoint({
       id: context.id,
-      gateway,
-      sideEvents,
       config,
     });
   },

package/agent/tools/blacklist.ts

@@ -1,29 +1,27 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
+export default defineAgentTool<{ guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
   description: 'KOOK 服务器黑名单管理：添加/移除',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
     action: z.enum(['add', 'remove']).describe('add|remove'),
     user_id: z.string().describe('用户 ID'),
     remark: z.string().optional().describe('备注（add 可选）'),
   }),
-  platforms: ['kook'],
+  adapter: 'kook',
   tags: ['kook'],
   permissions: [platformPermit('guild_admin')],
-  async execute({ endpoint_id, guild_id, action, user_id, remark }: { endpoint_id: string; guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }) {
-    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
+  async execute({ guild_id, action, user_id, remark }: { guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }, context) {
+    const member = context.$client.pickGuildMember(guild_id, user_id);
     switch (action) {
       case 'add': {
-        const success = await endpoint.addToBlacklist(guild_id, user_id, remark);
+        const success = await member.addToBlackList(remark);
         return { success, message: success ? `已将 ${user_id} 加入黑名单` : '操作失败' };
       }
       case 'remove': {
-        const success = await endpoint.removeFromBlacklist(guild_id, user_id);
+        const success = await member.removeFromBlackList();
         return { success, message: success ? `已将 ${user_id} 从黑名单移除` : '操作失败' };
       }
       default:

package/agent/tools/create_role.ts

@@ -1,21 +1,19 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; name: string }>({
+export default defineAgentTool<{ guild_id: string; name: string }>({
   description: '在 KOOK 服务器中创建新角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
     name: z.string().describe('角色名称'),
   }),
-  platforms: ['kook'],
+  adapter: 'kook',
   tags: ['kook'],
   permissions: [platformPermit('guild_owner')],
-  async execute({ endpoint_id, guild_id, name  }: { endpoint_id: string; guild_id: string; name: string }) {
-    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
-    const role = await endpoint.createRole(guild_id, name);
+  async execute({ guild_id, name  }: { guild_id: string; name: string }, context) {
+    const client = context.$client;
+    const role = await client.pickGuild(guild_id).createRole(name);
     return {
       success: true,
       message: `已创建角色 "${name}"`,

package/agent/tools/delete_role.ts

@@ -1,21 +1,19 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; role_id: string }>({
+export default defineAgentTool<{ guild_id: string; role_id: string }>({
   description: '删除 KOOK 服务器中的角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
-  platforms: ['kook'],
+  adapter: 'kook',
   tags: ['kook'],
   permissions: [platformPermit('guild_owner')],
-  async execute({ endpoint_id, guild_id, role_id  }: { endpoint_id: string; guild_id: string; role_id: string }) {
-    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
-    const success = await endpoint.deleteRole(guild_id, role_id);
+  async execute({ guild_id, role_id  }: { guild_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.pickGuild(guild_id).deleteRole(role_id);
     return { success, message: success ? `已删除角色 ${role_id}` : '删除角色失败' };
   },
 });

package/agent/tools/grant_role.ts

@@ -1,22 +1,20 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
   description: '给用户授予 KOOK 服务器角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
     user_id: z.string().describe('用户 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
-  platforms: ['kook'],
+  adapter: 'kook',
   tags: ['kook'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; user_id: string; role_id: string }) {
-    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
-    const success = await endpoint.grantRole(guild_id, user_id, role_id);
+  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.pickGuildMember(guild_id, user_id).grant(role_id);
     return { success, message: success ? `已授予用户 ${user_id} 角色 ${role_id}` : '授予角色失败' };
   },
 });

package/agent/tools/list_roles.ts

@@ -1,18 +1,16 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string }>({
+export default defineAgentTool<{ guild_id: string }>({
   description: '获取 KOOK 服务器的角色列表',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
   }),
-  platforms: ['kook'],
+  adapter: 'kook',
   tags: ['kook'],
-  async execute({ endpoint_id, guild_id  }: { endpoint_id: string; guild_id: string }) {
-    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
-    const roles = await endpoint.getRoleList(guild_id);
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = context.$client;
+    const roles = await client.pickGuild(guild_id).getRoleList();
     return {
       roles: roles.map((r) => ({
         id: String(r.role_id),

package/agent/tools/revoke_role.ts

@@ -1,22 +1,20 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
   description: '撤销用户的 KOOK 服务器角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
     user_id: z.string().describe('用户 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
-  platforms: ['kook'],
+  adapter: 'kook',
   tags: ['kook'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; user_id: string; role_id: string }) {
-    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
-    const success = await endpoint.revokeRole(guild_id, user_id, role_id);
+  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.pickGuildMember(guild_id, user_id).revoke(role_id);
     return { success, message: success ? `已撤销用户 ${user_id} 的角色 ${role_id}` : '撤销角色失败' };
   },
 });

package/lib/client.d.ts

@@ -0,0 +1,11 @@
+import type { KookClientTransport } from './ws.js';
+export type KookClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly kook: {
+            readonly client: KookClientTransport;
+            readonly events: KookClientEventMap;
+        };
+    }
+}
+export declare const kookClient: import("@zhin.js/adapter").EndpointClientToken<KookClientTransport, KookClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const kookClient = defineEndpointClient('kook');

package/lib/endpoint.d.ts

@@ -1,57 +1,41 @@
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { Endpoint } from 'zhin.js/adapter';
+import { 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 KookInboundMessage, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
+import { type KookInboundMessage, type KookWebhookEventData, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
 import { type CreateKookClient, type KookClientTransport } from './ws.js';
 export interface KookEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedKookWebsocketConfig;
     readonly createClient?: CreateKookClient;
 }
-export declare class KookWebsocketEndpoint implements EndpointInstance {
+export declare class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
     #private;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: KookEndpointOptions);
+    get client(): KookClientTransport;
     start(): Promise<void>;
     open(): void;
     close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    /** Test / internal: admit a message when open. */
+    /** Test / internal: admit a normalized message when open. */
     admit(msg: KookInboundMessage): void;
     recallMessage(messageId: string): Promise<void>;
-    getRoleList(guildId: string): Promise<{
-        role_id: string | number;
-        name: string;
-        color?: number;
-        position?: number;
-        permissions?: unknown;
-    }[]>;
-    createRole(guildId: string, name: string): Promise<{
-        role_id: string | number;
-        name: string;
-    }>;
-    deleteRole(guildId: string, roleId: string): Promise<boolean>;
-    grantRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
-    revokeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
-    addToBlacklist(guildId: string, userId: string, remark?: string): Promise<boolean>;
-    removeFromBlacklist(guildId: string, userId: string): Promise<boolean>;
 }
 export interface KookWebhookEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedKookWebhookConfig;
     readonly createClient?: CreateKookClient;
 }
-export declare class KookWebhookEndpoint implements EndpointInstance {
+export declare class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
     #private;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: KookWebhookEndpointOptions);
+    get client(): KookClientTransport;
     /** Used by webhook handler. */
     get isOpen(): boolean;
     get config(): ResolvedKookWebhookConfig;
@@ -61,26 +45,11 @@ export declare class KookWebhookEndpoint implements EndpointInstance {
     close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    admitEvent(event: KookWebhookEventData): void;
     /** Test / internal: admit a message when open. */
     admit(msg: KookInboundMessage): void;
     recallMessage(messageId: string): Promise<void>;
     checkAndRememberSn(sn: number): boolean;
-    getRoleList(guildId: string): Promise<{
-        role_id: string | number;
-        name: string;
-        color?: number;
-        position?: number;
-        permissions?: unknown;
-    }[]>;
-    createRole(guildId: string, name: string): Promise<{
-        role_id: string | number;
-        name: string;
-    }>;
-    deleteRole(guildId: string, roleId: string): Promise<boolean>;
-    grantRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
-    revokeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
-    addToBlacklist(guildId: string, userId: string, remark?: string): Promise<boolean>;
-    removeFromBlacklist(guildId: string, userId: string): Promise<boolean>;
 }
 /**
  * KOOK endpoint 的 EndpointManagement 语义端口（websocket / webhook 共用）。

package/lib/endpoint.js

@@ -1,29 +1,33 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { registerKookAgentEndpoint } from './kook-agent-deps.js';
-import { formatInboundContent, formatOutboundKmarkdown, isKookBotMentioned, kookInboundConversation, senderDisplayName, } from './protocol.js';
+import { formatInboundContent, formatOutboundKmarkdown, isKookBotMentioned, kookInboundConversation, normalizeKookWebhookEvent, senderDisplayName, } from './protocol.js';
 import { registerKookWebhookRoutes } from './webhook.js';
 import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
-export class KookWebsocketEndpoint {
+export class KookWebsocketEndpoint extends Endpoint {
     #logger;
     #options;
     #createClient;
     #client = null;
     #open = false;
     #started = false;
-    #unregisterAgent;
     management = createKookEndpointManagement(() => this.#requireClient());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('kook', options.config.id);
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateClient;
     }
+    get client() {
+        return this.#requireClient();
+    }
     async start() {
         if (this.#started)
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerKookAgentEndpoint(this.#options.config.id, this);
             this.#client = this.#createClient(this.#options.config);
             this.#bindClient(this.#client);
             await this.#client.connect();
@@ -48,8 +52,6 @@ export class KookWebsocketEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         if (this.#client) {
             try {
                 this.#client.removeAllListeners();
@@ -78,7 +80,7 @@ export class KookWebsocketEndpoint {
         }));
         return messageId;
     }
-    /** Test / internal: admit a message when open. */
+    /** Test / internal: admit a normalized message when open. */
     admit(msg) {
         if (!this.#open)
             return;
@@ -86,7 +88,7 @@ export class KookWebsocketEndpoint {
             return;
         const conversation = kookInboundConversation(String(this.#options.id), msg);
         const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
@@ -116,37 +118,26 @@ export class KookWebsocketEndpoint {
             return;
         await this.#requireClient().recallMsg?.(messageId);
     }
-    // ── Agent tool surface ──────────────────────────────────────────────
-    async getRoleList(guildId) {
-        return this.#requireClient().pickGuild(guildId).getRoleList();
-    }
-    async createRole(guildId, name) {
-        return this.#requireClient().pickGuild(guildId).createRole(name);
-    }
-    async deleteRole(guildId, roleId) {
-        return this.#requireClient().pickGuild(guildId).deleteRole(roleId);
-    }
-    async grantRole(guildId, userId, roleId) {
-        return this.#requireClient().pickGuildMember(guildId, userId).grant(roleId);
-    }
-    async revokeRole(guildId, userId, roleId) {
-        return this.#requireClient().pickGuildMember(guildId, userId).revoke(roleId);
-    }
-    async addToBlacklist(guildId, userId, remark) {
-        return this.#requireClient().pickGuildMember(guildId, userId).addToBlackList(remark);
-    }
-    async removeFromBlacklist(guildId, userId) {
-        return this.#requireClient().pickGuildMember(guildId, userId).removeFromBlackList();
-    }
     #bindClient(client) {
         client.on('message', (raw) => {
+            this.#emitPlatformEvent('message', raw);
             const msg = normalizeKookMessage(raw);
             if (msg)
                 this.admit(msg);
         });
         const receiver = client.receiver;
         receiver?.on('event', (raw) => {
-            receiveKookSideEvent(this.#options.sideEvents, this.#options.config.id, raw, this.#logger);
+            this.#emitPlatformEvent('event', raw);
+            receiveKookSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, raw, this.#logger);
+        });
+    }
+    #emitPlatformEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'kook_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
         });
     }
     #requireClient() {
@@ -155,7 +146,7 @@ export class KookWebsocketEndpoint {
         return this.#client;
     }
 }
-export class KookWebhookEndpoint {
+export class KookWebhookEndpoint extends Endpoint {
     #logger;
     #options;
     #createClient;
@@ -164,13 +155,17 @@ export class KookWebhookEndpoint {
     #processedSn = new Set();
     #open = false;
     #started = false;
-    #unregisterAgent;
     management = createKookEndpointManagement(() => this.#requireClient());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('kook', options.config.id);
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateWebhookClient;
     }
+    get client() {
+        return this.#requireClient();
+    }
     /** Used by webhook handler. */
     get isOpen() {
         return this.#open;
@@ -186,7 +181,6 @@ export class KookWebhookEndpoint {
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerKookAgentEndpoint(this.#options.config.id, this);
             this.#client = this.#createClient(this.#options.config);
             await this.#client.init();
             this.#routeReleases.push(...registerKookWebhookRoutes(this.#options.http, this));
@@ -214,8 +208,6 @@ export class KookWebhookEndpoint {
         this.#open = false;
         for (const release of this.#routeReleases.splice(0))
             release();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         this.#processedSn.clear();
         if (this.#client) {
             try {
@@ -245,6 +237,23 @@ export class KookWebhookEndpoint {
         }));
         return messageId;
     }
+    admitEvent(event) {
+        void this.emitPlatform(String(event.type ?? 'event'), event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'kook_platform_event_failed',
+                event: String(event.type ?? 'event'),
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (receiveKookSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, event, this.#logger))
+            return;
+        const message = normalizeKookWebhookEvent(event, {
+            ignore: this.#options.config.ignore,
+            selfId: this.selfId,
+        });
+        if (message)
+            this.admit(message);
+    }
     /** Test / internal: admit a message when open. */
     admit(msg) {
         if (!this.#open)
@@ -253,7 +262,7 @@ export class KookWebhookEndpoint {
             return;
         const conversation = kookInboundConversation(String(this.#options.id), msg);
         const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
@@ -294,27 +303,6 @@ export class KookWebhookEndpoint {
         }
         return true;
     }
-    async getRoleList(guildId) {
-        return this.#requireClient().pickGuild(guildId).getRoleList();
-    }
-    async createRole(guildId, name) {
-        return this.#requireClient().pickGuild(guildId).createRole(name);
-    }
-    async deleteRole(guildId, roleId) {
-        return this.#requireClient().pickGuild(guildId).deleteRole(roleId);
-    }
-    async grantRole(guildId, userId, roleId) {
-        return this.#requireClient().pickGuildMember(guildId, userId).grant(roleId);
-    }
-    async revokeRole(guildId, userId, roleId) {
-        return this.#requireClient().pickGuildMember(guildId, userId).revoke(roleId);
-    }
-    async addToBlacklist(guildId, userId, remark) {
-        return this.#requireClient().pickGuildMember(guildId, userId).addToBlackList(remark);
-    }
-    async removeFromBlacklist(guildId, userId) {
-        return this.#requireClient().pickGuildMember(guildId, userId).removeFromBlackList();
-    }
     #requireClient() {
         if (!this.#client)
             throw new Error('KOOK client not initialized');