@zhin.js/adapter-icqq 8.0.12 → 8.0.14

package/src/endpoint.ts

@@ -2,35 +2,46 @@ import {
   Client,
   parseGroupMessageId,
   type Config as NativeIcqqClientConfig,
+  type FileElem,
+  type PttElem,
   type Sendable,
+  type VideoElem,
 } from '@icqqjs/icqq';
 import { inspect } from 'node:util';
 import type {
   EndpointControl,
   EndpointInstance,
   EndpointManagement,
+  EndpointPendingRequest,
   EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
-import type { MessageRef } from '@zhin.js/im-contract';
+import type { EndpointContentPort, EndpointContentResolveContext } from '@zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { receiveOneBotLikeSideEvent, SystemEvent, toCanonicalSegments, type LoginAssist } from '@zhin.js/core';
+import type {
+  ConversationMessage,
+  ConversationReference,
+  ForwardEntry,
+  MessageRef,
+  Segment,
+} from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { registerIcqqAgentEndpoint } from './icqq-agent-deps.js';
+import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
 import {
   InboundMessageDeduper,
   findIcqqNestedMessageSource,
   isIcqqBotMentioned,
   isIcqqMessagePostType,
   normalizeIcqqInboundMessage,
-  quotedPayloadFromIcqqSource,
+  messageLookupFromIcqqSource,
   resolveIcqqQuoteIdFromEvent,
+  resolveIcqqInboundMedia,
   shouldSkipSelfInboundMessage,
   type IcqqMessageEvent,
 } from './icqq-inbound.js';
 import {
-  buildIcqqInboxNoticeRow,
-  buildIcqqInboxRequestRow,
-  buildIcqqSystemRequestRow,
   isIcqqNoticePayload,
   isIcqqRequestPayload,
 } from './icqq-inbox.js';
@@ -39,7 +50,7 @@ import {
   normalizeIcqqGuildInboundMessage,
 } from './icqq-guild.js';
 import {
-  materializeOutboundBase64,
+  prepareIcqqOutboundMedia,
   resolveIcqqOutboundMediaMode,
 } from './outbound-media.js';
 import {
@@ -51,18 +62,14 @@ import {
   type ResolvedIcqqConfig,
 } from './protocol.js';
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
-
-export interface IcqqInboxHooks {
-  recordRequest(row: Record<string, unknown>): void | Promise<void>;
-  recordNotice(row: Record<string, unknown>): void | Promise<void>;
-  publish?(type: string, data: unknown): void;
-}
+import { normalizeForwardMsgResponse } from './forward-msg.js';
 
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
   readonly config: ResolvedIcqqConfig;
-  readonly inbox?: IcqqInboxHooks;
+  readonly sideEvents: SideEventGateway;
+  readonly loginAssist: LoginAssist;
 }
 
 const BOUND_EVENTS = [
@@ -90,11 +97,96 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
   readonly endpointName: string;
   readonly #guildCatalog = new IcqqGuildCatalog();
   readonly #inboundDeduper = new InboundMessageDeduper();
-  readonly #inboxDeduper = new InboundMessageDeduper();
+  readonly #sideEventDeduper = new InboundMessageDeduper();
+  readonly #loginAssistOwner = Object.freeze({});
   #open = false;
+  #retiring = false;
   #started = false;
+  #resolveStartOnline?: () => void;
   #heldInbound: IcqqInboundMessage[] = [];
   #unregisterAgent?: () => void;
+  readonly #inflightInbound = new Set<Promise<void>>();
+  readonly #messageContent = new Map<string, ConversationMessage>();
+
+  readonly content: EndpointContentPort = Object.freeze({
+    resolve: async (reference: ConversationReference, context: EndpointContentResolveContext) => {
+      context.signal.throwIfAborted();
+      if (reference.kind === 'message') {
+        const cached = this.#messageContent.get(reference.message.id);
+        return cached
+          ? Object.freeze({ status: 'resolved' as const, reference, value: cached })
+          : Object.freeze({ status: 'not_found' as const, code: 'icqq_message_not_observed' });
+      }
+      if (reference.kind === 'forward') {
+        try {
+          const entries = await this.#resolveForwardEntries(
+            reference.forwardId,
+            context,
+            { remainingEntries: context.maxEntries, path: new Set<string>() },
+            0,
+          );
+          if (entries.length === 0) return Object.freeze({ status: 'not_found' as const, code: 'icqq_forward_not_found' });
+          return Object.freeze({ status: 'resolved' as const, reference, value: Object.freeze(entries) });
+        } catch (error) {
+          if (context.signal.aborted) throw error;
+          return Object.freeze({
+            status: 'failed' as const,
+            code: 'icqq_forward_fetch_failed',
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+      if (reference.media.kind === 'url' || reference.media.kind === 'base64' || reference.media.kind === 'path') {
+        return Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+      }
+      return Object.freeze({ status: 'unsupported' as const, code: 'icqq_media_reference_unsupported' });
+    },
+  });
+
+  async #resolveForwardEntries(
+    forwardId: string,
+    context: EndpointContentResolveContext,
+    state: { remainingEntries: number; readonly path: Set<string> },
+    depth: number,
+  ): Promise<readonly ForwardEntry[]> {
+    context.signal.throwIfAborted();
+    if (state.remainingEntries <= 0 || state.path.has(forwardId)) return Object.freeze([]);
+    state.path.add(forwardId);
+    try {
+      // ICQQ does not expose a cancellable getForwardMsg API. Keep the caller's
+      // generation lease until the native operation actually settles, then honor
+      // cancellation before publishing any resolved content.
+      const raw = await this.getForwardMsg(forwardId);
+      context.signal.throwIfAborted();
+      const entries = normalizeForwardMsgResponse(raw).slice(0, state.remainingEntries);
+      state.remainingEntries -= entries.length;
+      const expanded: ForwardEntry[] = [];
+      for (const entry of entries) {
+        context.signal.throwIfAborted();
+        const segments: Segment[] = [];
+        for (const segment of entry.segments) {
+          if (segment.type !== 'forward' || depth >= context.maxDepth) {
+            segments.push(segment);
+            continue;
+          }
+          const nestedId = String((segment.data as { forward_id?: unknown }).forward_id ?? '').trim();
+          if (!nestedId || state.path.has(nestedId) || state.remainingEntries <= 0) {
+            segments.push(segment);
+            continue;
+          }
+          const nested = await this.#resolveForwardEntries(nestedId, context, state, depth + 1);
+          segments.push(Object.freeze({
+            ...segment,
+            data: Object.freeze({ ...segment.data, ...(nested.length > 0 ? { entries: nested } : {}) }),
+          }));
+        }
+        expanded.push(Object.freeze({ ...entry, segments: Object.freeze(segments) }));
+      }
+      return Object.freeze(expanded);
+    } finally {
+      state.path.delete(forwardId);
+    }
+  }
 
   readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
     listFriends: async () =>
@@ -114,6 +206,7 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
     },
     listGroupMembers: async (groupId) =>
       Array.from((await this.getGroupMemberList(Number(groupId))).values()),
+    listRequests: () => this.#listPendingRequests(),
     approveRequest: (requestId, remark) => this.#approveRequest(requestId, remark),
     rejectRequest: (requestId, reason) => this.#rejectRequest(requestId, reason),
     kickGroupMember: async (groupId, userId) => {
@@ -186,17 +279,24 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
     });
   }
 
-  async start(): Promise<void> {
+  async start(signal: AbortSignal): Promise<void> {
     if (this.#started) return;
+    signal.throwIfAborted();
     this.#started = true;
+    let resolveOnline!: () => void;
+    const onlineReady = new Promise<void>((resolve) => {
+      resolveOnline = resolve;
+    });
+    const onAbort = () => resolveOnline();
+    this.#resolveStartOnline = resolveOnline;
+    signal.addEventListener('abort', onAbort, { once: true });
     try {
-      const onlineReady = new Promise<void>((resolve) => {
-        this.on('system.online', () => resolve());
-      });
       this.#bindClientEvents();
-      await this.login(this.#options.config.password);
+      await raceAbort(Promise.resolve(this.login(this.#options.config.password)), signal);
       await onlineReady;
-      await this.#pullPendingSystemMessages();
+      signal.throwIfAborted();
+      await this.#pullPendingSystemMessages(signal);
+      signal.throwIfAborted();
       this.#unregisterAgent = registerIcqqAgentEndpoint(this.endpointName, this);
       this.#logger.info(
         `connected (direct) | friends: ${this.fl.size} | groups: ${this.gl.size}`,
@@ -205,21 +305,31 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
       await this.stop();
       this.#logger.debug(`Failed to connect ICQQ client: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
       throw error;
+    } finally {
+      signal.removeEventListener('abort', onAbort);
+      if (this.#resolveStartOnline === resolveOnline) this.#resolveStartOnline = undefined;
     }
   }
 
   open(): void {
+    this.#retiring = false;
     this.#open = true;
     const held = this.#heldInbound.splice(0);
     for (const msg of held) this.admit(msg);
   }
 
-  close(): void {
+  async close(): Promise<void> {
+    this.#retiring = true;
     this.#open = false;
+    await Promise.allSettled([...this.#inflightInbound]);
   }
 
   async stop(): Promise<void> {
+    this.#retiring = true;
     this.#open = false;
+    await Promise.allSettled([...this.#inflightInbound]);
+    this.#resolveStartOnline?.();
+    this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'endpoint_stopped');
     this.#heldInbound.length = 0;
     this.#unregisterAgent?.();
     this.#unregisterAgent = undefined;
@@ -230,8 +340,8 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
     try {
       this.terminate();
     } catch { /* ignore */ }
-    this.#inboundDeduper.clear();
-    this.#inboxDeduper.clear();
+      this.#inboundDeduper.clear();
+      this.#sideEventDeduper.clear();
     this.#guildCatalog.clear();
     this.#started = false;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
@@ -240,46 +350,70 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     if (!this.#started) throw new Error('icqq endpoint 未连接');
     const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
-    const content = Array.isArray(payload)
-      ? materializeOutboundBase64(payload, mediaMode)
-      : payload;
-    const message = formatOutboundBody(content);
-    const parsed = icqqOutboundTarget(conversation);
-    let result: { message_id?: unknown };
+    const prepared = isIcqqSegmentPayload(payload)
+      ? prepareIcqqOutboundMedia(payload, mediaMode)
+      : { content: payload, dispose() {} };
     try {
-      switch (parsed.kind) {
-        case 'private':
-          result = await this.sendPrivateMsg(parsed.userId, message as Sendable);
-          break;
-        case 'group':
-          result = await this.sendGroupMsg(parsed.groupId, message as Sendable);
-          break;
+      const message = formatOutboundBody(prepared.content);
+      const preview = formatIcqqSendablePreview(message);
+      const parsed = icqqOutboundTarget(conversation);
+      let result: { message_id?: unknown };
+      try {
+        result = await this.#sendNative(parsed, message);
+      } catch (error) {
+        this.#logger.warn(formatCompact({
+          op: 'icqq_send_failed',
+          target: `${conversation.kind}:${conversation.id}`,
+          error: describeUnknownError(error),
+          preview: truncatePreview(preview, 120),
+        }));
+        throw error;
+      }
+      const messageId = String(result?.message_id ?? `sent_${Date.now()}`);
+      this.#logger.info(
+        `send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(preview, 80)}`,
+      );
+      return messageId;
+    } finally {
+      prepared.dispose();
+    }
+  }
+
+  async #sendNative(
+    target: ReturnType<typeof icqqOutboundTarget>,
+    message: Sendable,
+  ): Promise<{ message_id?: unknown }> {
+    if (isIcqqFileElement(message)) {
+      switch (target.kind) {
+        case 'private': {
+          const id = await this.pickFriend(target.userId).sendFile(message.file, message.name);
+          return { message_id: id };
+        }
+        case 'group': {
+          const stat = await this.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
+          return { message_id: stat.fid };
+        }
         case 'temp':
-          result = await this.sendTempMsg(parsed.groupId, parsed.userId, message as Sendable);
-          break;
         case 'channel':
-          result = await this.sendGuildMsg(parsed.guildId, parsed.channelId, message as Sendable) as unknown as { message_id?: unknown };
-          break;
+          throw new TypeError(`ICQQ ${target.kind} conversation does not support file delivery`);
       }
-    } catch (error) {
-      this.#logger.warn(formatCompact({
-        op: 'icqq_send_failed',
-        target: `${conversation.kind}:${conversation.id}`,
-        error: describeUnknownError(error),
-        preview: truncatePreview(typeof message === 'string' ? message : String(message), 120),
-      }));
-      throw error;
     }
-    const messageId = String(result?.message_id ?? `sent_${Date.now()}`);
-    this.#logger.info(
-      `send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`,
-    );
-    return messageId;
+    switch (target.kind) {
+      case 'private':
+        return this.sendPrivateMsg(target.userId, message);
+      case 'group':
+        return this.sendGroupMsg(target.groupId, message);
+      case 'temp':
+        return this.sendTempMsg(target.groupId, target.userId, message);
+      case 'channel':
+        return this.sendGuildMsg(target.guildId, target.channelId, message) as unknown as { message_id?: unknown };
+    }
   }
 
-  admit(msg: IcqqInboundMessage): void {
+  admit(msg: IcqqInboundMessage, admittedBeforeRetire = false): void {
     const conversation = msg.conversation;
-    if (!this.#open) {
+    if (!this.#open && !admittedBeforeRetire) {
+      if (this.#retiring) return;
       if (this.#heldInbound.length >= INBOUND_HOLD_LIMIT) {
         const dropped = this.#heldInbound.shift();
         this.#logger.warn(formatCompact({
@@ -311,8 +445,6 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
       + (mentioned ? ' (mentioned)' : '')
       + ` | ${truncatePreview(msg.content, 80)}`,
     );
-    const quoteId = msg.metadata?.quote_id;
-    const { quote_id: _dropQuoteId, ...restMetadata } = msg.metadata ?? {};
     void this.#options.gateway.receive({
       conversation,
       message: { conversation, id: msg.id },
@@ -321,10 +453,10 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
       sender: msg.sender,
       endpointId: this.endpointName,
       ...(mentioned ? { mentioned: true } : {}),
-      ...(quoteId ? { replyTo: { id: String(quoteId) } } : {}),
+      ...(msg.replyTo ? { replyTo: msg.replyTo } : {}),
       metadata: Object.freeze({
         channelType: msg.channelType,
-        ...restMetadata,
+        ...(msg.metadata ?? {}),
       }),
     }).catch((err) => {
       this.#logger.warn(formatCompact({
@@ -350,23 +482,52 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
         }));
       }
     };
-    this.on('message.private', (event) => safe('message.private', () => this.#handleMessageEvent('message.private', event)));
-    this.on('message.group', (event) => safe('message.group', () => this.#handleMessageEvent('message.group', event)));
+    this.on('message.private', (event) => this.#startMessageEvent('message.private', event));
+    this.on('message.group', (event) => this.#startMessageEvent('message.group', event));
     this.on('message.guild', (event) => safe('message.guild', () => this.#handleGuildEvent(event)));
-    this.on('request.friend', (event) => safe('request.friend', () => this.#recordInboxRequest(serializeIcqqEvent(event))));
-    this.on('request.group', (event) => safe('request.group', () => this.#recordInboxRequest(serializeIcqqEvent(event))));
-    this.on('notice.friend', (event) => safe('notice.friend', () => this.#recordInboxNotice(serializeIcqqEvent(event))));
-    this.on('notice.group', (event) => safe('notice.group', () => this.#recordInboxNotice(serializeIcqqEvent(event))));
+    this.on('request.friend', (event) => safe('request.friend', () => this.#onRequestEvent(serializeIcqqEvent(event))));
+    this.on('request.group', (event) => safe('request.group', () => this.#onRequestEvent(serializeIcqqEvent(event))));
+    this.on('notice.friend', (event) => safe('notice.friend', () => this.#onNoticeEvent(serializeIcqqEvent(event))));
+    this.on('notice.group', (event) => safe('notice.group', () => this.#onNoticeEvent(serializeIcqqEvent(event))));
+    this.on('system.online', (event) => safe('system.online', () => {
+      this.#resolveStartOnline?.();
+      this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
+      this.#logSystemEvent('online', event);
+    }));
     this.on('system.offline', (event) => this.#logSystemEvent('offline', event));
     this.on('system.offline.network', (event) => this.#logSystemEvent('offline.network', event));
     this.on('system.offline.kickoff', (event) => this.#logSystemEvent('offline.kickoff', event));
-    this.on('system.login.qrcode', () => {
-      this.#logger.info('icqq 收到二维码登录事件，请按 icqq 默认流程扫码后继续登录');
+    this.on('system.login.qrcode', (event) => {
+      this.#logger.info('icqq 收到二维码登录事件，等待 LoginAssist / 终端确认后继续');
+      this.#handleLoginChallenge('qrcode', event);
+    });
+    this.on('system.login.device', (event) => this.#handleLoginChallenge('device', event));
+    this.on('system.login.slider', (event) => this.#handleLoginChallenge('slider', event));
+    this.on('system.login.error', (event) => {
+      this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'login_error');
+      this.#logSystemEvent('login.error', event);
+    });
+    this.on('system.login.auth', (event) => this.#handleLoginChallenge('auth', event));
+  }
+
+  #handleLoginChallenge(
+    step: 'qrcode' | 'slider' | 'device' | 'auth',
+    event: unknown,
+  ): void {
+    const payload = serializeIcqqEvent(event) ?? (event && typeof event === 'object'
+      ? event as Record<string, unknown>
+      : null);
+    this.#logSystemEvent(`login.${step}`, event);
+    void runIcqqLoginAssistStep({
+      assist: this.#options.loginAssist,
+      client: this,
+      adapter: 'icqq',
+      endpointKey: this.endpointName,
+      owner: this.#loginAssistOwner,
+      logger: this.#logger,
+      step,
+      event: payload ?? event,
     });
-    this.on('system.login.device', (event) => this.#logSystemEvent('login.device', event));
-    this.on('system.login.slider', (event) => this.#logSystemEvent('login.slider', event));
-    this.on('system.login.error', (event) => this.#logSystemEvent('login.error', event));
-    this.on('system.login.auth', (event) => this.#logSystemEvent('login.auth', event));
   }
 
   #logSystemEvent(type: string, event: unknown): void {
@@ -376,9 +537,58 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
       endpoint: this.endpointName,
       ...(payload ? { event: JSON.stringify(payload) } : {}),
     }));
+    this.#dispatchIcqqSystemSideEvent(type, payload);
+  }
+
+  #dispatchIcqqSideEvent(payload: Record<string, unknown>): void {
+    const sideEvents = this.#options.sideEvents;
+    const postType = String(payload.post_type ?? '');
+    const isRequest = postType === 'request' || postType.startsWith('request.');
+    const flag = payload.flag != null ? String(payload.flag) : '';
+    void receiveOneBotLikeSideEvent(sideEvents, {
+      adapter: 'icqq',
+      endpointKey: this.endpointName,
+      platform: 'icqq',
+      raw: payload,
+      ...(isRequest ? {
+        approve: (id, remark) => this.#approveRequest(flag || id, remark),
+        reject: (id, reason) => this.#rejectRequest(flag || id, reason),
+      } : {}),
+    }).catch((err) => {
+      this.#logger.warn(formatCompact({
+        op: 'icqq_side_event_failed',
+        endpoint: this.endpointName,
+        post_type: postType || undefined,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
+
+  #dispatchIcqqSystemSideEvent(type: string, payload: Record<string, unknown> | null): void {
+    const sideEvents = this.#options.sideEvents;
+    const { scene_type, sub_type } = parseIcqqSystemScene(type);
+    void sideEvents.receiveSystem(SystemEvent.from(payload ?? {}, {
+      $id: `system:${this.endpointName}:${type}:${Date.now()}`,
+      $adapter: 'icqq' as never,
+      $endpoint: this.endpointName,
+      $type: 'system',
+      $scene_id: this.endpointName,
+      $scene_type: scene_type,
+      $sub_type: sub_type,
+      $timestamp: Date.now(),
+    })).catch((err) => {
+      this.#logger.warn(formatCompact({
+        op: 'icqq_system_side_event_failed',
+        endpoint: this.endpointName,
+        type,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
   }
 
-  #handleMessageEvent(eventName: 'message.private' | 'message.group', event: unknown): void {
+  async #handleMessageEvent(eventName: 'message.private' | 'message.group', event: unknown): Promise<void> {
+    if (this.#retiring) return;
+    const admittedBeforeRetire = this.#open;
     const payload = serializeIcqqEvent(event);
     if (!payload || !isIcqqMessagePostType(payload)) {
       this.#logger.debug(formatCompact({
@@ -400,6 +610,14 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
       }));
       return;
     }
+    const contact = this.#resolveInboundContact(data);
+    if (contact) {
+      await resolveIcqqInboundMedia(data.message, {
+        getPttUrl: (element) => contact.getPttUrl(element as PttElem),
+        getVideoUrl: (element) => contact.getVideoUrl(element as VideoElem),
+      });
+      if (!this.#started) return;
+    }
     const normalized = normalizeIcqqInboundMessage(data);
     if (!normalized) {
       this.#logger.debug(formatCompact({
@@ -420,13 +638,31 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
       }));
       return;
     }
+    const conversation = icqqInboundConversation(String(this.#options.id), {
+      channelType: normalized.channelType,
+      channelId: normalized.channelId,
+      channelParentGroupId: normalized.channelParentGroupId,
+    });
+    const quoteId = resolveIcqqQuoteIdFromEvent(data);
+    const quoted = messageLookupFromIcqqSource(findIcqqNestedMessageSource(data));
+    if (quoteId && quoted) {
+      this.#messageContent.set(quoteId, Object.freeze({
+        ref: Object.freeze({ conversation, id: quoteId }),
+        ...(quoted.sender?.id ? { actor: Object.freeze({
+          id: quoted.sender.id,
+          ...(quoted.sender.name ? { displayName: quoted.sender.name } : {}),
+        }) } : {}),
+        segments: Object.freeze(toCanonicalSegments(
+          Array.isArray(quoted.content)
+            ? quoted.content
+            : [{ type: 'text', data: { text: quoted.content } }],
+        )),
+        timestamp: quoted.time ? quoted.time * (quoted.time < 1e12 ? 1000 : 1) : Date.now(),
+      }));
+    }
     this.admit({
       id: normalized.messageId,
-      conversation: icqqInboundConversation(String(this.#options.id), {
-        channelType: normalized.channelType,
-        channelId: normalized.channelId,
-        channelParentGroupId: normalized.channelParentGroupId,
-      }),
+      conversation,
       content: formatInboundContent(normalized.rawMessage),
       segments: normalized.content,
       sender: {
@@ -435,13 +671,47 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
         ...(normalized.senderRole ? { roles: [normalized.senderRole] } : {}),
       },
       channelType: normalized.channelType,
-      metadata: buildIcqqQuoteMetadata(data, {
+      ...(quoteId ? { replyTo: { id: quoteId } } : {}),
+      metadata: {
         nickname: normalized.nickname,
         senderRole: normalized.senderRole,
-      }),
+      },
+    }, admittedBeforeRetire);
+  }
+
+  #startMessageEvent(eventName: 'message.private' | 'message.group', event: unknown): void {
+    const operation = this.#handleMessageEvent(eventName, event);
+    this.#inflightInbound.add(operation);
+    void operation.catch((error) => {
+      this.#logInboundHandlerFailure(eventName, error);
+    }).finally(() => {
+      this.#inflightInbound.delete(operation);
     });
   }
 
+  #resolveInboundContact(data: IcqqMessageEvent) {
+    const userId = Number(data.user_id ?? data.from_id);
+    if (!Number.isFinite(userId) || userId <= 0) return null;
+    if (data.message_type === 'group' || data.group_id != null) {
+      const groupId = Number(data.group_id);
+      return Number.isFinite(groupId) && groupId > 0 ? this.pickGroup(groupId) : null;
+    }
+    const sourceGroupId = Number(data.sender?.group_id);
+    if (Number.isFinite(sourceGroupId) && sourceGroupId > 0) {
+      return this.pickMember(sourceGroupId, userId);
+    }
+    return this.pickFriend(userId);
+  }
+
+  #logInboundHandlerFailure(event: string, error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'icqq_inbound_handler_failed',
+      endpoint: this.endpointName,
+      event,
+      error: describeUnknownError(error),
+    }));
+  }
+
   #handleGuildEvent(event: unknown): void {
     const payload = serializeIcqqEvent(event);
     if (!payload || typeof payload !== 'object') return;
@@ -484,61 +754,76 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
     });
   }
 
-  #recordInboxRequest(payload: Record<string, unknown> | null): void {
+  #onRequestEvent(payload: Record<string, unknown> | null): void {
     if (!payload || !isIcqqRequestPayload(payload)) return;
-    const hooks = this.#options.inbox;
-    if (!hooks) return;
-    const row = buildIcqqInboxRequestRow(payload, this.#inboxBase());
-    if (!row) return;
-    if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`)) return;
-    void hooks.recordRequest(row);
-    hooks.publish?.('endpoint:request', row);
+    const flag = payload.flag != null ? String(payload.flag) : (payload.seq != null ? String(payload.seq) : '');
+    if (flag && !this.#sideEventDeduper.shouldProcess(`request:${flag}`)) return;
+    this.#dispatchIcqqSideEvent(payload);
   }
 
-  #recordInboxNotice(payload: Record<string, unknown> | null): void {
+  #onNoticeEvent(payload: Record<string, unknown> | null): void {
     if (!payload || !isIcqqNoticePayload(payload)) return;
-    const hooks = this.#options.inbox;
-    if (!hooks) return;
-    const row = buildIcqqInboxNoticeRow(payload, this.#inboxBase());
-    if (!row) return;
-    if (!this.#inboxDeduper.shouldProcess(`notice:${String(row.platform_notice_id)}`)) return;
-    void hooks.recordNotice(row);
-    hooks.publish?.('endpoint:notice', row);
+    const key = [
+      payload.time,
+      payload.operator_id ?? payload.user_id,
+      payload.notice_type ?? payload.type,
+      payload.sub_type,
+    ].join('_');
+    if (!this.#sideEventDeduper.shouldProcess(`notice:${key}`)) return;
+    this.#dispatchIcqqSideEvent(payload);
   }
 
-  #inboxBase(): { adapter: string; endpointKey: string } {
-    const id = String(this.#options.id);
-    return { adapter: id.split('\0').pop() ?? id, endpointKey: this.endpointName };
+  async #listPendingRequests(): Promise<readonly EndpointPendingRequest[]> {
+    const messages = await this.getSystemMsg();
+    const rows: EndpointPendingRequest[] = [];
+    for (const raw of messages) {
+      const msg = raw as unknown as IcqqSystemMessage & { request_type?: string };
+      const kind = msg.request_type === 'friend' ? 'friend' : 'group';
+      const platformRequestId = (msg.flag && String(msg.flag).trim())
+        || (msg.seq != null ? String(msg.seq) : '');
+      if (!platformRequestId || msg.user_id == null) continue;
+      const createdAt = Number(msg.time);
+      rows.push(Object.freeze({
+        platform_request_id: platformRequestId,
+        type: kind,
+        scene_type: kind === 'group' ? 'group' : null,
+        scene_id: String(kind === 'group' ? (msg.group_id ?? msg.user_id) : msg.user_id),
+        sub_type: kind === 'group' ? (msg.type != null ? String(msg.type) : null) : null,
+        actor_id: String(msg.user_id),
+        actor_name: msg.nickname != null ? String(msg.nickname) : null,
+        comment: msg.comment != null ? String(msg.comment) : null,
+        created_at: Number.isFinite(createdAt) && createdAt > 0
+          ? (createdAt < 1e12 ? createdAt * 1000 : createdAt)
+          : Date.now(),
+      }));
+    }
+    return Object.freeze(rows);
   }
 
-  async #pullPendingSystemMessages(): Promise<void> {
-    const hooks = this.#options.inbox;
-    if (!hooks) return;
+  async #pullPendingSystemMessages(signal: AbortSignal): Promise<void> {
     try {
-      const messages = await this.getSystemMsg();
-      const friendRequests: IcqqSystemMessage[] = [];
-      const groupRequests: IcqqSystemMessage[] = [];
-      for (const msg of messages) {
-        if ((msg as { request_type?: string }).request_type === 'friend') {
-          friendRequests.push(msg as unknown as IcqqSystemMessage);
-        } else {
-          groupRequests.push(msg as unknown as IcqqSystemMessage);
-        }
-      }
-      const base = this.#inboxBase();
-      const rows = [
-        ...friendRequests.map((m) => buildIcqqSystemRequestRow(m, 'friend', base)),
-        ...groupRequests.map((m) => buildIcqqSystemRequestRow(m, 'group', base)),
-      ];
-      for (const row of rows) {
-        if (!row) continue;
-        if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`)) continue;
-        void hooks.recordRequest(row);
-        hooks.publish?.('endpoint:request', row);
+      const messages = await raceAbort(Promise.resolve(this.getSystemMsg()), signal);
+      for (const raw of messages) {
+        signal.throwIfAborted();
+        const msg = raw as unknown as IcqqSystemMessage & { request_type?: string };
+        const kind = msg.request_type === 'friend' ? 'friend' : 'group';
+        const flag = msg.flag != null ? String(msg.flag) : (msg.seq != null ? String(msg.seq) : '');
+        if (!flag || !this.#sideEventDeduper.shouldProcess(`request:${flag}`)) continue;
+        this.#dispatchIcqqSideEvent({
+          post_type: 'request',
+          request_type: kind,
+          flag: msg.flag,
+          user_id: msg.user_id,
+          group_id: msg.group_id,
+          comment: msg.comment,
+          time: msg.time,
+          sub_type: msg.type,
+        });
       }
     } catch (error) {
+      if (signal.aborted) throw signal.reason ?? error;
       this.#logger.debug(formatCompact({
-        op: 'inbox_pull_system_msg',
+        op: 'side_event_pull_system_msg',
         endpoint: this.endpointName,
         error: error instanceof Error ? error.message : String(error),
       }));
@@ -578,6 +863,41 @@ export class IcqqEndpoint extends Client implements EndpointInstance {
   }
 }
 
+function formatIcqqSendablePreview(message: Sendable): string {
+  if (typeof message === 'string') return message;
+  try {
+    return JSON.stringify(message, (_key, value) => Buffer.isBuffer(value) ? '<buffer>' : value);
+  } catch {
+    return '[ICQQ Sendable]';
+  }
+}
+
+function isIcqqSegmentPayload(payload: unknown): payload is import('zhin.js').SendContent {
+  if (Array.isArray(payload)) return true;
+  return typeof payload === 'object'
+    && payload !== null
+    && typeof (payload as { type?: unknown }).type === 'string';
+}
+
+function isIcqqFileElement(message: Sendable): message is FileElem {
+  return !Array.isArray(message)
+    && typeof message !== 'string'
+    && message.type === 'file';
+}
+
+async function raceAbort<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  let rejectAbort!: (reason: unknown) => void;
+  const aborted = new Promise<never>((_resolve, reject) => { rejectAbort = reject; });
+  const onAbort = () => rejectAbort(signal.reason ?? new Error('ICQQ operation aborted'));
+  signal.addEventListener('abort', onAbort, { once: true });
+  try {
+    return await Promise.race([operation, aborted]);
+  } finally {
+    signal.removeEventListener('abort', onAbort);
+  }
+}
+
 function describeUnknownError(error: unknown): string {
   if (error instanceof Error) return error.stack ?? error.message;
   if (error && typeof error === 'object') {
@@ -625,36 +945,6 @@ function resolveNativeClientConfig(config: ResolvedIcqqConfig): NativeIcqqClient
   };
 }
 
-function buildIcqqQuoteMetadata(
-  data: IcqqMessageEvent,
-  base: Record<string, unknown>,
-): Record<string, unknown> {
-  const metadata: Record<string, unknown> = { ...base };
-  const quoteId = resolveIcqqQuoteIdFromEvent(data);
-  if (quoteId) metadata.quote_id = quoteId;
-  const quoted = quotedPayloadFromIcqqSource(findIcqqNestedMessageSource(data));
-  if (quoted?.sender?.id) metadata.quote_sender_id = quoted.sender.id;
-  if (quoted?.sender?.name) metadata.quote_sender_name = quoted.sender.name;
-  const quoteText = quoted
-    ? (typeof quoted.content === 'string'
-        ? quoted.content
-        : quoted.content
-            .map((seg) =>
-              seg && typeof seg === 'object' && seg.type === 'text'
-                ? String((seg.data as { text?: unknown } | undefined)?.text ?? '')
-                : '',
-            )
-            .join('')
-      ).trim() || quoted.raw || ''
-    : '';
-  if (quoteText) metadata.quote_content = quoteText;
-  return metadata;
-}
-
-const INBOUND_HOLD_LIMIT = 32;
-
-const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'] as const;
-
 function serializeIcqqEvent(event: unknown): Record<string, unknown> | null {
   if (!event || typeof event !== 'object') return null;
   const nativeToJSON = (event as { toJSON?: (keys: string[]) => unknown }).toJSON;
@@ -675,3 +965,23 @@ function serializeIcqqEvent(event: unknown): Record<string, unknown> | null {
   }
   return Object.keys(out).length > 0 ? out : null;
 }
+
+function parseIcqqSystemScene(type: string): { scene_type: string; sub_type: string } {
+  if (type.startsWith('login.')) {
+    return { scene_type: 'login', sub_type: type.slice('login.'.length) || 'unknown' };
+  }
+  if (type.startsWith('offline.')) {
+    return { scene_type: 'offline', sub_type: type.slice('offline.'.length) || 'unknown' };
+  }
+  if (type === 'online') {
+    return { scene_type: 'online', sub_type: 'online' };
+  }
+  if (type === 'offline') {
+    return { scene_type: 'offline', sub_type: 'offline' };
+  }
+  return { scene_type: 'system', sub_type: type };
+}
+
+const INBOUND_HOLD_LIMIT = 32;
+
+const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'] as const;