@zhin.js/adapter-satori 1.1.18 → 1.1.20

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @zhin.js/adapter-satori
 
+## 1.1.20
+
+### Patch Changes
+
+- Updated dependencies [5e878ba]
+  - @zhin.js/page@1.1.12
+
+## 1.1.19
+
+### Patch Changes
+
+- 2c3610a: Move account lifecycle ownership into the generic Adapter base and let native Endpoints retain their SDK Client inheritance. Infer platform-specific operation Sessions from a single adapter registry while preserving command parameter, option, configuration and factory inference.
+
+  Bind message replies, management ports, login challenges and Agent cancellation to the captured account incarnation. Persist runtime account intent with encrypted, revision-checked Host storage; keep account management independent of Root process restarts. Require explicit operator confirmation before importing existing accounts, and give replacement accounts a new identity without inheriting previous Sessions.
+
+  Expose account save, start, stop, update and replacement through the existing adapter Console, with exact account ownership, truthful pending/unknown outcomes and no startup configuration or environment-file rewrites.
+
+  Complete the target migration across every adapter, the public authoring API, generators, examples and Console. This intentionally removes the old create factory, inheritable Endpoint/ClientEndpoint classes, Client descriptors and file-rewrite account management; plugin authors must use createAdapter, native Client inheritance and the single AdapterRegistry. Satori and OneBot12 require explicit platform/userId selection, and WeCom requires a separate agentId.
+
+  Verify opaque credential changes before the same configuration snapshot is committed. Drain admitted native callbacks across close/rollback, cancel target work on stop, and keep raw transport parsing, platform ACK timing and SDK native methods under their existing owners. Account metadata conceals credentials carried in URLs.
+
+- a9f4e48: PATCH COMPATIBILITY CUTOVER: this batch intentionally changes plugin APIs. The maintainer explicitly chose patch releases with declared version boundaries. Upgrade the complete tested dependency set; patch numbering does not promise compatibility with the removed interfaces.
+
+  The first planned floors are zhin.js 1.1.19, Core 1.1.54, Adapter 1.1.26, FeatureKit 1.1.10, Plugin Runtime 1.1.18, Runtime/Isolate 1.1.16 and Agent 1.1.45. Keep old-interface plugins with the earlier locked stack until they are migrated. Adapter's independent Feature API changes from 1.0.0 to 2.0.0; official consumers declare ^2.0.0. Existing Feature API admission rejects explicitly incompatible ranges; omitted API metadata keeps its existing behavior and does not certify compatibility. Runtime engine and patch-only release gates remain unchanged.
+
+  Use the native-Client Adapter target contract, canonical FeatureKit AdapterRegistry augmentation and named Endpoint control/management requests. Route message controls from canonical message/conversation refs; retain exact source authority and propagate caller/account/explicit-Root-stop cancellation. Replace removed Agent activity feedback exports with source-bound feedback. HMR pause/resume belongs to concrete plugin instances; plugins choose accepted-work policy without changing Controller commit/rollback authority. Cooperative worker/process control cancellation does not kill an isolate or reopen retired business admission.
+
+  Provide authenticated historical-data preview, exact selected binding, transactional application, authoritative inspection and explicit resumption, including active games. Preserve before-images and journals; never replay an unconfirmed effect, infer an account from an alias, or reuse historical permission grants. Owner V2 approvals remain inactive legacy data, while new writes use V3. Rollback requires matching software, lockfile and verified data; installing old code alone cannot read a new V3 approval file. Conflicting after-images are never overwritten.
+
+  See docs/plans/adapter-operation-version-boundaries.md and the Chinese/English upgrade guide for the complete version inventory, custom-plugin changes, acceptance and recovery sequence. These code and metadata changes do not authorize merging, publication, deployment, login, production migration or removal of installed workspace patches.
+
+- Updated dependencies [2c3610a]
+- Updated dependencies [a9f4e48]
+- Updated dependencies [f8505b0]
+- Updated dependencies [2c3610a]
+  - @zhin.js/adapter@1.1.26
+  - @zhin.js/feature-kit@1.1.10
+  - @zhin.js/core@1.1.54
+  - @zhin.js/host-http@1.1.12
+  - @zhin.js/client@1.1.22
+  - @zhin.js/page@1.1.11
+  - @zhin.js/skill@1.1.11
+
 ## 1.1.18
 
 ### Patch Changes

package/README.md

@@ -22,19 +22,19 @@ pnpm add @zhin.js/adapter-satori
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/satori/index.ts`（`defineAdapter`）
-- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/core` — `endpointSpec.events` 入站、统一出站管道
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - `@zhin.js/host-http` — Webhook 模式需 `httpHostToken` 注册 POST 路由
 - 配置经插件 `schema.json` 落到顶层 `<instanceKey>`（`baseUrl` / `token` / …）
 
-入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef：DIRECT 频道 → kind `private`，其余 → kind `group`、所属 guild 进 `parent`）  
+入站：`endpoint[endpointSpec].events.emit('message.receive', { conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef：DIRECT 频道 → kind `private`，其余 → kind `group`、所属 guild 进 `parent`）
+
 出站：`send({ conversation, payload })` → Satori `message.create`（`channel_id = conversation.id`；payload 已由 gateway/core 渲染；无 segment-mapper）
 
-入站 `metadata.mentioned`：消息 content 中 `<at id="…"/>` 元素的 id 等于登录 selfId（READY/事件 `login.user.id`）时置 `true`。
+入站 `metadata.mentioned`：消息 content 中 `<at id="…"/>` 元素的 id 等于登录 selfId（配置的 `userId`）时置 `true`。
 
-每个 Endpoint 的 `$client` 是 `@imhelper/satori-v1` 的 `SatoriV1Client`。业务代码直接调用
-`$client.call(resource, method, params)` 或其公开便捷方法；Client 负责协议事件变换，Endpoint
-只负责 Satori IDENTIFY/心跳、Webhook 鉴权和 Zhin 投影。
+每个 Endpoint 直接继承 `@imhelper/satori-v1` 的 `SatoriV1Client`，由所属 `SatoriAdapter` 管理。业务代码直接调用
+`$client.call(resource, method, params)` 或其公开便捷方法；协议事件变换、Satori IDENTIFY/心跳与 Webhook 鉴权由该实际 Client 处理，Zhin 投影经 `endpointSpec.events` 接入。
 
 ## 前置条件
 
@@ -54,17 +54,21 @@ satori:
   heartbeat_interval: 10000
   endpoints:
     - id: satori-bot
+      platform: qq
+      userId: "123456789"
       baseUrl: "http://127.0.0.1:5140"
       token: "${SATORI_TOKEN}"
 ```
 
 主配置 `plugins` 映射需引用 `@zhin.js/adapter-satori`（`instanceKey: satori`）。
 
-### 可选字段
+### Endpoint 字段
 
 | 字段 | 说明 |
 |------|------|
 | `heartbeat_interval` | WS PING 间隔（毫秒），默认 `10000` |
+| `platform` | 必填，远端 login 的平台标识 |
+| `userId` | 必填，远端 login 的用户标识（字符串） |
 | `token` | Bearer；可在 YAML 中引用 `${SATORI_TOKEN}` |
 
 ### Webhook
@@ -77,12 +81,14 @@ satori:
   connection: webhook
   endpoints:
     - id: satori-bot
+      platform: qq
+      userId: "123456789"
       baseUrl: "http://127.0.0.1:5140"
       path: "/satori/webhook"
       token: "${SATORI_TOKEN}"
 ```
 
-SDK 会向 `path` 发送 POST，请求头 `Satori-Opcode: 0` 表示事件；适配器从首个事件的 `login` 取得 platform / userId 用于后续 API 调用。
+SDK 会向 `path` 发送 POST，请求头 `Satori-Opcode: 0` 表示事件；每个 Endpoint 必须配置 `platform` 与 `userId`。仅接纳这两个字段精确匹配的 login 事件；API 请求也固定使用这组身份。READY 中其他 login 不会改变当前账号。
 
 ## 鉴权
 
@@ -109,7 +115,7 @@ SDK 会向 `path` 发送 POST，请求头 `Satori-Opcode: 0` 表示事件；适
 启动后打开 Console 的「Satori」页（地址 `/satori`），可以：
 
 - 查看运行中的连接、点「测试连接」做连通性诊断；
-- 增删 `plugins.satori.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；
+- 经所属 Adapter 增删持久化账号、启停单个 Endpoint；凭据由 Host 加密仓储保存，不改启动 YAML 或 `.env`，不重启进程；
 - 如果适配器要求登录，页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办；
 
 读取需要 `satori:read`，写操作需要 `satori:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `satori endpoint add`。

package/adapters/satori/index.js

@@ -3,10 +3,8 @@
  * Convention entry: discover `adapters/satori/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { SatoriWebhookEndpoint, SatoriWsEndpoint } from "../../lib/endpoint.js";
-import { resolveSatoriConfig, } from "../../lib/protocol.js";
-import { satoriRuntimeStateToken } from "../../lib/satori-runtime-state.js";
+import { SatoriAdapter } from "../../lib/adapter.js";
+import {} from "../../lib/protocol.js";
 export { SatoriWebhookEndpoint, SatoriWsEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
@@ -16,23 +14,5 @@ export default defineAdapter({
         outboundMedia: ['url', 'base64'],
         interactive: 'text',
     },
-    create(context) {
-        const config = resolveSatoriConfig(context.config);
-        // 注册到插件运行时状态（satori endpoint list 的"运行中"数据源）
-        context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
-            id: config.id,
-            mode: config.connection,
-        });
-        if (config.connection === 'webhook') {
-            return new SatoriWebhookEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-            });
-        }
-        return new SatoriWsEndpoint({
-            id: context.id,
-            config,
-        });
-    },
+    createAdapter: context => new SatoriAdapter(context),
 });

package/adapters/satori/index.ts

@@ -2,13 +2,10 @@
  * Convention entry: discover `adapters/satori/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { SatoriWebhookEndpoint, SatoriWsEndpoint } from '../../src/endpoint.js';
+import { SatoriAdapter } from '../../src/adapter.js';
 import {
-  resolveSatoriConfig,
   type SatoriEndpointConfig,
 } from '../../src/protocol.js';
-import { satoriRuntimeStateToken } from '../../src/satori-runtime-state.js';
 
 export { SatoriWebhookEndpoint, SatoriWsEndpoint } from '../../src/endpoint.js';
 export type {
@@ -27,23 +24,5 @@ export default defineAdapter<SatoriEndpointConfig>({
     outboundMedia: ['url', 'base64'],
     interactive: 'text',
   },
-  create(context) {
-    const config = resolveSatoriConfig(context.config);
-    // 注册到插件运行时状态（satori endpoint list 的"运行中"数据源）
-    context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
-      id: config.id,
-      mode: config.connection,
-    });
-    if (config.connection === 'webhook') {
-      return new SatoriWebhookEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-      });
-    }
-    return new SatoriWsEndpoint({
-      id: context.id,
-      config,
-    });
-  },
+  createAdapter: context => new SatoriAdapter(context),
 });

package/commands/satori/endpoint/definition.js

@@ -5,15 +5,15 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { satoriRuntimeStateToken } from "../../../lib/satori-runtime-state.js";
 export const satoriEndpointCommands = createEndpointCommands({
     adapterKey: 'satori',
     adapterDisplayName: 'Satori',
     fields: [
+        { key: 'platform', required: true, description: 'Selected Satori login platform' },
+        { key: 'userId', required: true, description: 'Selected Satori login user ID' },
         { key: 'baseUrl', required: true, description: 'Satori 服务 base URL', descriptionI18n: { en: "Satori service base URL" } },
         { key: 'path', description: 'webhook 路径（connection: webhook）', descriptionI18n: { en: "Webhook path (connection: webhook)" } },
         { key: 'token', env: true, description: 'Satori access token' },
     ],
-    running: (use) => use(satoriRuntimeStateToken).endpoints.values(),
     describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
 }, defineCommand);

package/commands/satori/endpoint/definition.ts

@@ -4,16 +4,16 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { satoriRuntimeStateToken } from '../../../src/satori-runtime-state.js';
 
 export const satoriEndpointCommands = createEndpointCommands({
   adapterKey: 'satori',
   adapterDisplayName: 'Satori',
   fields: [
+    { key: 'platform', required: true, description: 'Selected Satori login platform' },
+    { key: 'userId', required: true, description: 'Selected Satori login user ID' },
     { key: 'baseUrl', required: true, description: 'Satori 服务 base URL', descriptionI18n: { en: "Satori service base URL" } },
     { key: 'path', description: 'webhook 路径（connection: webhook）', descriptionI18n: { en: "Webhook path (connection: webhook)" } },
     { key: 'token', env: true, description: 'Satori access token' },
   ],
-  running: (use) => use(satoriRuntimeStateToken).endpoints.values(),
   describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
 }, defineCommand);

package/lib/adapter.d.ts

@@ -0,0 +1,19 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { type SatoriEndpointConfig } from './protocol.js';
+import { SatoriWsEndpoint, SatoriWebhookEndpoint } from './endpoint.js';
+import type { SatoriClientEventMap } from './client.js';
+export declare class SatoriAdapter extends Adapter<SatoriWsEndpoint | SatoriWebhookEndpoint, SatoriEndpointConfig, SatoriClientEventMap> {
+    #private;
+    constructor(context: AdapterContext<SatoriEndpointConfig>);
+    get configurationIdentityFields(): readonly string[];
+    get configurationIdentityProbeFields(): readonly string[];
+    get configurationUpdateFields(): readonly string[];
+    protected validateConfiguration(config: SatoriEndpointConfig): void;
+    protected identifyConfiguration(input: SatoriEndpointConfig, signal: AbortSignal): Promise<string>;
+    protected createEndpoint(input: SatoriEndpointConfig, execution: EndpointCreationContext): SatoriWsEndpoint | SatoriWebhookEndpoint;
+}
+declare module '@zhin.js/feature-kit' {
+    interface AdapterRegistry {
+        readonly satori: SatoriAdapter;
+    }
+}

package/lib/adapter.js

@@ -0,0 +1,29 @@
+import { Adapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { callSatoriApi, resolveSatoriConfig } from './protocol.js';
+import { SatoriWsEndpoint, SatoriWebhookEndpoint } from './endpoint.js';
+export class SatoriAdapter extends Adapter {
+    #context;
+    constructor(context) { super(); this.#context = context; }
+    get configurationIdentityFields() { return ['id', 'platform', 'userId']; }
+    get configurationIdentityProbeFields() { return ['token', 'baseUrl']; }
+    get configurationUpdateFields() { return ['connection', 'baseUrl', 'token', 'path', 'heartbeat_interval']; }
+    validateConfiguration(config) { resolveSatoriConfig(config); }
+    async identifyConfiguration(input, signal) {
+        const config = resolveSatoriConfig(input);
+        signal.throwIfAborted();
+        const login = await callSatoriApi({ ...config, signal, resource: 'login', method: 'get' });
+        signal.throwIfAborted();
+        if (!login?.platform || !login.user?.id)
+            throw new Error('Satori login identity is unavailable');
+        if (login.platform !== config.platform || login.user.id !== config.userId)
+            throw new Error('Satori returned another login identity');
+        return `satori:${JSON.stringify([login.platform, login.user.id])}`;
+    }
+    createEndpoint(input, execution) {
+        const config = resolveSatoriConfig(input), id = execution.canonicalId, signal = execution.signal;
+        return config.connection === 'webhook'
+            ? new SatoriWebhookEndpoint({ id, config, signal, http: this.#context.use(httpHostToken) })
+            : new SatoriWsEndpoint({ id, config, signal });
+    }
+}

package/lib/client.d.ts

@@ -1,18 +1,26 @@
 import { SatoriV1Client, type SatoriV1Event } from '@imhelper/satori-v1';
 import { type EventMap, type ImHelperEventMap } from 'imhelper';
 import { type ClientEventPayloads } from 'zhin.js/adapter';
-import type { ResolvedSatoriConfig, SatoriApiOptions, callSatoriApi } from './protocol.js';
+import type { ResolvedSatoriConfig, callSatoriApi } from './protocol.js';
 export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
 type SatoriClientEvents = ImHelperEventMap<string, SatoriV1Event, EventMap<string>>;
 export type SatoriClientEventMap = ClientEventPayloads<SatoriClientEvents>;
-export declare function createSatoriEndpointClient(config: ResolvedSatoriConfig, request: typeof callSatoriApi, apiOptions: () => SatoriApiOptions): SatoriV1Client;
-export declare function forwardSatoriClientEvents(client: SatoriV1Client, receive: (name: string, payload: unknown) => void): () => void;
-declare module '@zhin.js/feature-kit' {
-    interface AdapterClientRegistry {
-        readonly satori: {
-            readonly client: SatoriV1Client;
-            readonly events: SatoriClientEventMap;
-        };
-    }
+/** One account-bound caller is shared by native SDK and semantic ports. */
+export interface SatoriActionRequest {
+    readonly resource: string;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+    readonly signal?: AbortSignal;
+}
+export interface SatoriClientBinding {
+    readonly config: ResolvedSatoriConfig;
+    readonly request: typeof callSatoriApi;
+    readonly signal?: AbortSignal;
 }
-export declare const satoriClient: import("@zhin.js/adapter").EndpointClientToken<SatoriV1Client, ClientEventPayloads<SatoriClientEvents>>;
+export type SatoriActionCaller = (request: SatoriActionRequest) => Promise<unknown>;
+export declare function createSatoriActionCaller({ config, request, signal }: SatoriClientBinding): SatoriActionCaller;
+export declare function satoriClientOptions({ config, call }: {
+    readonly config: ResolvedSatoriConfig;
+    readonly call: SatoriActionCaller;
+}): ConstructorParameters<typeof SatoriV1Client>[0];
+export declare function forwardSatoriClientEvents(client: SatoriV1Client, receive: (name: string, payload: unknown) => void): () => void;

package/lib/client.js

@@ -1,15 +1,21 @@
-import { SatoriV1Client, } from '@imhelper/satori-v1';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { EventFactory } from 'imhelper';
-import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+import { forwardEndpointClientEvents, } from 'zhin.js/adapter';
 export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
-export function createSatoriEndpointClient(config, request, apiOptions) {
-    return new SatoriV1Client({
-        baseUrl: config.baseUrl,
-        selfId: config.id,
-        accessToken: config.token,
-        receiveMode: 'manual',
-        call: (resource, method, params) => request(apiOptions(), resource, method, params ?? {}),
-    });
+export function createSatoriActionCaller({ config, request, signal }) {
+    return action => {
+        const operationSignal = signal && action.signal ? AbortSignal.any([signal, action.signal]) : signal ?? action.signal;
+        if (operationSignal?.aborted)
+            throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint request ended before submission', 'not_sent', { cause: operationSignal.reason });
+        return request({ baseUrl: config.baseUrl, platform: config.platform, userId: config.userId,
+            token: config.token, ...action, signal: operationSignal });
+    };
+}
+export function satoriClientOptions({ config, call }) {
+    return { baseUrl: config.baseUrl, selfId: config.userId, platform: config.platform,
+        accessToken: config.token, receiveMode: 'manual',
+        call: (resource, method, params) => call({ resource, method, params: params ?? {} }),
+    };
 }
 const satoriClientEventNames = Object.freeze([
     ...EventFactory.getSupportedEventTypes(),
@@ -18,4 +24,3 @@ const satoriClientEventNames = Object.freeze([
 export function forwardSatoriClientEvents(client, receive) {
     return forwardEndpointClientEvents(client, satoriClientEventNames, receive);
 }
-export const satoriClient = defineEndpointClient('satori');

package/lib/console-spec.js

@@ -2,6 +2,8 @@ export const satoriConsoleSpec = {
     adapterKey: 'satori',
     adapterDisplayName: 'Satori',
     fields: [
+        { key: 'platform', required: true, description: 'Selected Satori login platform' },
+        { key: 'userId', required: true, description: 'Selected Satori login user ID' },
         { key: 'baseUrl', required: true, description: 'Satori 服务 base URL', descriptionI18n: { en: 'Satori service base URL' } },
         { key: 'path', description: 'webhook 路径（connection: webhook）', descriptionI18n: { en: 'Webhook path (connection: webhook)' } },
         { key: 'token', env: true, description: 'Satori access token' },

package/lib/console.d.ts

@@ -5,4 +5,4 @@
  */
 import { type AdapterConsoleResources } from 'zhin.js/adapter';
 import type { PluginConsoleRpc } from 'zhin.js';
-export declare function createSatoriConsoleRpc(resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;
+export declare function createSatoriConsoleRpc(_resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -4,13 +4,10 @@
  * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
  */
 import { createAdapterConsoleRpc } from 'zhin.js/adapter';
-import { satoriRuntimeStateToken } from './satori-runtime-state.js';
 import { satoriConsoleSpec } from './console-spec.js';
-export function createSatoriConsoleRpc(resources, getConfig) {
-    const state = resources.use(satoriRuntimeStateToken);
+export function createSatoriConsoleRpc(_resources, getConfig) {
     return createAdapterConsoleRpc({
         ...satoriConsoleSpec,
-        running: () => state.endpoints.values(),
         getConfig,
-    }, resources);
+    });
 }

package/lib/endpoint.d.ts

@@ -1,53 +1,44 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification, type EndpointManagement } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { callSatoriApi, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig } from './protocol.js';
-import { type SatoriClient } from './client.js';
+import { type SatoriActionCaller, SatoriClient } from './client.js';
 import { type CreateSatoriWebSocket } from './ws.js';
 export type SatoriApiCaller = typeof callSatoriApi;
 export interface SatoriWsEndpointOptions {
+    readonly signal?: AbortSignal;
     readonly id: CapabilityId;
     readonly config: ResolvedSatoriWsConfig;
     readonly createWebSocket?: CreateSatoriWebSocket;
     readonly callApi?: SatoriApiCaller;
 }
-export declare class SatoriWsEndpoint extends ClientEndpoint<SatoriClient> {
+export declare class SatoriWsEndpoint extends SatoriClient implements Endpoint {
     #private;
-    readonly client: SatoriClient;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: SatoriWsEndpointOptions);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recall(id: string, fallbackChannelId?: string): Promise<void>;
 }
 export interface SatoriWebhookEndpointOptions {
+    readonly signal?: AbortSignal;
     readonly id: CapabilityId;
     readonly http: HttpHost;
     readonly config: ResolvedSatoriWebhookConfig;
     readonly callApi?: SatoriApiCaller;
 }
-export declare class SatoriWebhookEndpoint extends ClientEndpoint<SatoriClient> {
+export declare class SatoriWebhookEndpoint extends SatoriClient implements Endpoint {
     #private;
-    readonly client: SatoriClient;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: SatoriWebhookEndpointOptions);
-    /** Used by webhook handler. */
-    get isOpen(): boolean;
-    get config(): ResolvedSatoriWebhookConfig;
-    acceptHttp(request: IncomingMessage, response: ServerResponse): Promise<void>;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recall(id: string, fallbackChannelId?: string): Promise<void>;
 }
-export type SatoriManagementApi = (resource: string, method: string, params: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Satori guild id 是平台相关字符串（多数平台为雪花号，超
+ * Number.MAX_SAFE_INTEGER）。Console 社交面只把 group_id 当 JSON 值透传、
+ * 并以字符串回传给 listGroupMembers，因此保留原始字符串（仅按契约类型
+ * 声明强转）是全链路最不丢信息的方案。
+ */
+export type SatoriManagementApi = SatoriActionCaller;
 /**
  * Satori endpoint 的 EndpointManagement 语义端口（ws / webhook 共用），
  * 数据走协议 API：guild.list / channel.list / guild-member.list。