aicq-openclaw 3.16.3

package/lib/chat.js

@@ -0,0 +1,1417 @@
+/**
+ * AICQ Chat Manager — Send/receive messages, group chat, file handling
+ *
+ * Enhanced: File/image messages received from users are saved to the
+ * `userfiles` directory. After saving, a synthetic message is injected
+ * into the AI dispatch pipeline that tells the agent about the local
+ * file path so it can process the file (read, analyze, etc.).
+ */
+const { encryptMessage, decryptMessage } = require('./crypto');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+class ChatManager {
+  constructor(identityManager, serverClient, db, uploadsDir, userfilesDir) {
+    this.identity = identityManager;
+    this.server = serverClient;
+    this.db = db;
+    this.uploadsDir = uploadsDir;
+    this.userfilesDir = userfilesDir || path.join(path.dirname(uploadsDir), 'userfiles');
+    this._onNewMessage = null;
+    // [FIX race] Server replays offline messages right after WS auth, but the channel
+    // wires setOnNewMessage() later. Buffer early arrivals instead of dropping them.
+    this._earlyQueue = [];
+
+    // Ensure userfiles directory exists
+    fs.mkdirSync(this.userfilesDir, { recursive: true });
+
+    // Incoming file chunk assembly state: fileId -> { meta, chunks }
+    this._incomingFiles = new Map();
+
+    // [AICQ integration standard] Dedup set for inbound messages.
+    // Prevents WS reconnect / server re-push from triggering duplicate
+    // processing of the same message (which caused the "Leo multi-reply
+    // flood" in teambot — fixed in cf67622). Mirrors the same dedup
+    // strategy used by hermes-plugin's _processed_ids and zagent's
+    // processedMsgs/msgIDSeen maps.
+    // Capped at 1000 entries (trimmed to 500 when exceeded).
+    this._processedMsgIds = new Set();
+
+    // Listen for incoming messages via WS
+    this.server.onMessage('relay', (data) => this._handleIncoming(data));
+    this.server.onMessage('message', (data) => this._handleIncoming(data));
+    this.server.onMessage('group_message', (data) => this._handleGroupIncoming(data));
+    this.server.onMessage('handshake_initiate', (data) => this._handleHandshakeRequest(data));
+    this.server.onMessage('friend_request', (data) => this._handleServerFriendRequest(data));
+    this.server.onMessage('friend_request_accepted', (data) => this._handleServerFriendRequestAccepted(data));
+    this.server.onMessage('friend_added', (data) => this._handleServerFriendAdded(data));
+    this.server.onMessage('presence', (data) => this._handlePresence(data));
+    this.server.onMessage('file_chunk', (data) => this._handleFileChunk(data));
+    this.server.onMessage('file', (data) => this._handleFileMessage(data));
+    this.server.onMessage('image', (data) => this._handleFileMessage(data));
+    this.server.onMessage('stream_chunk', (data) => this._handleStreamChunk(data));
+    this.server.onMessage('stream_end', (data) => this._handleStreamEnd(data));
+    this.server.onMessage('stream_cancel', (data) => this._handleStreamCancel(data));
+
+    // Map of streamId -> { cancelled: bool } for tracking user-initiated
+    // stop requests. channel.js checks this in the deliver loop to stop
+    // sending chunks for a cancelled stream.
+    this._activeStreams = new Map();
+  }
+
+  /**
+   * Register a stream so its cancel state can be tracked.
+   * Returns the stream state object (mutable: set .cancelled = true to stop).
+   */
+  registerStream(streamId) {
+    const state = { cancelled: false };
+    this._activeStreams.set(streamId, state);
+    return state;
+  }
+
+  /**
+   * Remove a stream from tracking (called on endStream / cancelStream).
+   */
+  unregisterStream(streamId) {
+    this._activeStreams.delete(streamId);
+  }
+
+  /**
+   * Handle incoming stream_cancel from server — the user clicked Stop
+   * in the web UI. Mark the stream as cancelled so channel.js's deliver
+   * loop stops sending chunks.
+   */
+  _handleStreamCancel(data) {
+    const streamId = data.stream_id;
+    console.log('[AICQ Chat] Received stream_cancel for streamId=', streamId?.slice(0, 8));
+    const state = this._activeStreams.get(streamId);
+    if (state) {
+      state.cancelled = true;
+      console.log('[AICQ Chat] Marked stream', streamId?.slice(0, 8), 'as cancelled');
+      // Abort the OpenClaw agent run (model generation + tool calls)
+      // so it stops immediately, not just the chunk delivery.
+      if (state.abortController && !state.abortController.signal.aborted) {
+        console.log('[AICQ Chat] Aborting agent run for stream', streamId?.slice(0, 8));
+        state.abortController.abort('user-cancelled');
+      }
+    }
+    // Send stream_cancel_ack back so server can relay to the UI
+    this.server.sendWS({
+      type: 'stream_cancel_ack',
+      stream_id: streamId,
+      to: data.from,
+    });
+  }
+
+  setOnNewMessage(callback) {
+    this._onNewMessage = callback;
+    const queued = this._earlyQueue.splice(0);
+    for (const m of queued) {
+      Promise.resolve().then(() => callback(m)).catch((e) => console.error('[AICQ Chat] buffered message dispatch error:', e.message));
+    }
+    if (queued.length > 0) console.log(`[AICQ Chat] Replayed ${queued.length} buffered inbound message(s)`);
+  }
+
+  _dispatchInbound(msg) {
+    if (this._onNewMessage) return Promise.resolve(this._onNewMessage(msg));
+    this._earlyQueue.push(msg);
+    if (this._earlyQueue.length > 200) this._earlyQueue.shift();
+    console.warn('[AICQ Chat] _onNewMessage not yet registered — buffering inbound message (queue size:', this._earlyQueue.length + ')');
+    return null;
+  }
+
+  /**
+   * Register a callback for real-time friend_request events.
+   * Called by channel.js to immediately accept incoming friend requests
+   * without waiting for the next startAccount cycle.
+   */
+  setOnAutoAccept(callback) {
+    this._onAutoAccept = callback;
+  }
+
+  // ─── Send Messages ────────────────────────────────────────────────
+
+  async sendMessage(agentId, targetId, content, { type = 'text', isGroup = false, mentions = [], file_url = null, file_name = null, local_path = null } = {}) {
+    const identity = this.identity.loadAgent(agentId);
+
+    if (isGroup) {
+      // [FIX edge #4b] WS group frame is the proven live fan-out path
+      // (REST POST /groups/:id/messages does not exist server-side —
+      // Gin 404 for every account). REST is only a last-resort attempt
+      // for future server versions.
+      let sent = this.server.sendWS({
+        type: 'group_message',
+        groupId: targetId,
+        content,
+        msgType: type,
+        mentions,
+      });
+      if (!sent) {
+        try {
+          await this.server._request('POST', `/groups/${targetId}/messages`, {
+            data: { type, content, ...(mentions && mentions.length ? { mentions } : {}) },
+          });
+          sent = true;
+        } catch (e) {
+          console.warn('[Chat] REST group fallback failed:', e.message);
+        }
+      }
+
+      // Save locally
+      const msg = this.db.saveMessage({
+        agent_id: agentId,
+        target_id: targetId,
+        from_id: agentId,
+        to_id: targetId,
+        type,
+        content,
+        file_url,
+        file_name,
+        local_path,
+        is_group: 1,
+        mentions,
+        status: sent ? 'sent' : 'pending',
+      });
+      // Tag outbound messages so the channel.js dispatch callback can
+      // skip them (otherwise the agent's own replies get re-dispatched
+      // as inbound, causing an infinite echo loop).
+      msg._outbound = true;
+
+      if (this._onNewMessage) this._onNewMessage(msg);
+      return msg;
+    }
+
+    // Direct message
+    // Try to encrypt if we have a session key
+    const session = this.db.loadSession(agentId, targetId);
+    let payload = content;
+    if (session && session.session_key) {
+      try {
+        payload = encryptMessage(content, session.session_key);
+      } catch (e) {
+        console.error('[Chat] Encryption failed, sending plaintext:', e.message);
+      }
+    }
+
+    // Send via WebSocket relay — use 'message' type so the aicq.me
+    // server-side handleMessage path runs (which persists the message
+    // and relays to the recipient via WS). 'relay' is a different code
+    // path that doesn't persist HTTP-side.
+    const sent = this.server.sendWS({
+      type: 'message',
+      to: targetId,
+      data: {
+        to_id: targetId,
+        type: type,
+        content: content,
+        msgType: type,
+      },
+    });
+
+    // Also send via HTTP API for guaranteed persistence (the WS path
+    // is best-effort; if the recipient is offline the message may be
+    // lost without the HTTP save).
+    try {
+      await this.server._request('POST', '/chat/messages', {
+        to_id: targetId,
+        type: type,
+        content: content,
+      });
+    } catch (e) {
+      console.warn('[Chat] HTTP /chat/messages fallback failed:', e.message);
+      // Queue offline if both WS and HTTP failed
+      if (!sent) {
+        this.db.enqueueOffline({
+          agent_id: agentId,
+          target_id: targetId,
+          data: JSON.stringify({ type: 'message', to: targetId, data: { content, type } }),
+        });
+      }
+    }
+
+    // Save locally
+    const msg = this.db.saveMessage({
+      agent_id: agentId,
+      target_id: targetId,
+      from_id: agentId,
+      to_id: targetId,
+      type,
+      content,
+      file_url,
+      file_name,
+      local_path,
+      is_group: 0,
+      mentions,
+      status: sent ? 'sent' : 'pending',
+    });
+
+    // Update session message count
+    if (session) {
+      this.db.incrementSessionMessageCount(agentId, targetId);
+    }
+    // Tag outbound messages so the channel.js dispatch callback can
+    // skip them (otherwise the agent's own replies get re-dispatched
+    // as inbound, causing an infinite echo loop).
+    msg._outbound = true;
+
+    if (this._onNewMessage) this._onNewMessage(msg);
+    return msg;
+  }
+
+  // ─── Streaming Output ─────────────────────────────────────────────
+  //
+  // The aicq.me server supports a stream protocol (WS messages of type
+  // stream_chunk + stream_end) that lets the frontend render text
+  // character-by-character as the agent produces it. The server
+  // accumulates chunks in a StreamBuffer keyed by stream_id, and on
+  // stream_end persists the accumulated text as a single direct_message
+  // (so page refresh still shows the full reply).
+  //
+  // These methods wrap the WS protocol so channel.js can stream replies.
+
+  /**
+   * Send a single stream chunk to a friend.
+   * @param {string} agentId - local agent id (unused, kept for API symmetry)
+   * @param {string} targetId - recipient account id (e.g. "1000008")
+   * @param {string} streamId - uuid identifying this stream
+   * @param {string} chunk - text content for this chunk
+   * @param {string} chunkType - "text" | "reasoning" | "tool_call" | "tool_result"
+   * @param {object} [dataField] - optional object payload for tool_call/tool_result
+   */
+  async sendStreamChunk(agentId, targetId, streamId, chunk, chunkType = 'text', dataField = null) {
+    const msg = {
+      type: 'stream_chunk',
+      to: targetId,
+      stream_id: streamId,
+      chunkType,
+      data: dataField !== null ? dataField : chunk,
+    };
+    // For text chunks, the server expects msg.data to be the string.
+    // For tool_call/tool_result, msg.data should be the object payload.
+    if (chunkType === 'text' || chunkType === 'reasoning' || chunkType === 'thinking') {
+      msg.data = chunk;
+    } else {
+      msg.data = dataField || {};
+      if (!msg.msg_id) msg.msg_id = streamId;
+    }
+    const sent = this.server.sendWS(msg);
+    if (!sent) {
+      console.warn('[Chat] sendStreamChunk: WS not open, chunk lost');
+    }
+    return sent;
+  }
+
+  /**
+   * End a stream — tells the server to persist the accumulated text
+   * as a direct_message and notify the recipient that the stream is
+   * complete.
+   */
+  async endStream(agentId, targetId, streamId, messageId = null) {
+    const msgId = messageId || `msg_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+    const sent = this.server.sendWS({
+      type: 'stream_end',
+      to: targetId,
+      stream_id: streamId,
+      msg_id: msgId,
+    });
+    if (!sent) {
+      console.warn('[Chat] endStream: WS not open, falling back to HTTP /chat/messages');
+      // Fallback: persist via HTTP so the message isn't lost
+      // (server's stream buffer would otherwise be orphaned)
+      try {
+        // We don't have the accumulated text here; the caller should
+        // also call sendMessage as a safety net if persistence matters.
+      } catch (e) {
+        console.error('[Chat] endStream HTTP fallback failed:', e.message);
+      }
+    }
+    return { sent, messageId: msgId };
+  }
+
+  /**
+   * Cancel an in-progress stream — used when the user clicks "stop".
+   * Tells the server to discard the StreamBuffer (the already-streamed
+   * chunks are NOT persisted as a direct_message).
+   */
+  async cancelStream(agentId, targetId, streamId) {
+    const sent = this.server.sendWS({
+      type: 'stream_cancel',
+      to: targetId,
+      stream_id: streamId,
+    });
+    return sent;
+  }
+
+  // ─── Receive Messages ─────────────────────────────────────────────
+
+  async _handleIncoming(data) {
+    try {
+      const agentId = this.server.currentAgentId;
+      if (!agentId) return;
+
+    const fromId = data.fromId || data.from || (data.data && data.data.from_id) || data.from_id;
+    // Server pushes {type:'message', from:..., data:{content, from_id, to_id, ...}}
+    // Some legacy paths push {type:'relay', from:..., payload:'...'}
+    let content;
+    if (data.data && typeof data.data === 'object' && data.data.content !== undefined) {
+      content = data.data.content;
+    } else if (typeof data.payload === 'string') {
+      content = data.payload;
+    } else if (typeof data.data === 'string') {
+      content = data.data;
+    } else if (typeof data.content === 'string') {
+      content = data.content;
+    } else {
+      content = '';
+    }
+    const msgType = data.msgType || (data.data && data.data.type) || data.type || 'text';
+
+    // Try to decrypt if we have a session key
+    const session = this.db.loadSession(agentId, fromId);
+    if (session && session.session_key && typeof content === 'string') {
+      try {
+        content = decryptMessage(content, session.session_key);
+      } catch (e) {
+        // Might be plaintext, keep as is
+      }
+    }
+
+    // Detect if this is a file or image message
+    const isFileMessage = this._isFileMessage(msgType, content, data);
+    let localFilePath = null;
+    let originalFileName = null;
+
+    if (isFileMessage) {
+      const fileResult = await this._saveIncomingFileToUserfiles(agentId, fromId, content, data);
+      if (fileResult) {
+        localFilePath = fileResult.localPath;
+        originalFileName = fileResult.originalName;
+      }
+    }
+
+    // Save the original message
+    const msg = this.db.saveMessage({
+      agent_id: agentId,
+      target_id: fromId,
+      from_id: fromId,
+      to_id: agentId,
+      type: isFileMessage ? (this._isImageMessage(msgType, content, data) ? 'image' : 'file') : 'text',
+      content: typeof content === 'string' ? content : JSON.stringify(content),
+      file_url: data.file_url || data.fileUrl || null,
+      file_name: originalFileName || data.file_name || data.fileName || null,
+      local_path: localFilePath,
+      is_group: 0,
+      status: 'delivered',
+    });
+
+    try {
+      await this._dispatchInbound(msg);
+    } catch (e) {
+      console.error('[AICQ Chat] _onNewMessage error:', e.message, e.stack);
+    }
+
+    // If this was a file/image message, also inject a synthetic message
+    // telling the AI agent about the local file path
+    if (isFileMessage && localFilePath && this._onNewMessage) {
+      const isImage = this._isImageMessage(msgType, content, data);
+      const fileType = isImage ? '图片' : '文件';
+      const syntheticMsg = {
+        agent_id: agentId,
+        target_id: fromId,
+        from_id: fromId,
+        to_id: agentId,
+        type: 'text',
+        content: `[用户发送了${fileType}] ${originalFileName || '未知文件名'}\n本地路径: ${localFilePath}\n请处理该${fileType}。`,
+        is_group: 0,
+        status: 'delivered',
+        _synthetic: true,  // Mark as synthetic so AI dispatch can handle it
+        _original_msg_id: msg.message_id || msg.id,
+      };
+      this._dispatchInbound(syntheticMsg);
+    }
+    } catch (e) {
+      console.error('[AICQ Chat] _handleIncoming error:', e.message, e.stack);
+    }
+  }
+
+  async _handleGroupIncoming(data) {
+    // [AICQ integration standard] Group message handler.
+    // See https://aicq.me/static/integration-guide.html#admin-group-reply
+    //
+    // Field extraction (3-level fallback, mirrors zagent e8755e9 fix):
+    //   top-level camelCase → data wrapper snake_case → data wrapper camelCase
+    // AICQ server SaveGroupMessage persists with snake_case, but WS broadcast
+    // promotes `from` to top level and keeps `sender_name` etc. in data wrapper.
+    // Without this fallback, fromId would be undefined for every group message.
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const dataWrapper = (data && data.data && typeof data.data === 'object') ? data.data : {};
+    const fromId = data.from || data.fromId || dataWrapper.from || dataWrapper.from_id || dataWrapper.fromId;
+    const groupId = data.groupId || data.group_id || dataWrapper.group_id || dataWrapper.groupId;
+    const senderName = dataWrapper.sender_name || dataWrapper.senderName || data.senderName || '';
+    const groupName = dataWrapper.group_name || dataWrapper.groupName || data.groupName || '';
+    const content = data.content || dataWrapper.content || data.text || '';
+    const msgType = data.msgType || data.msg_type || dataWrapper.msg_type || dataWrapper.msgType || 'text';
+
+    // Skip system messages (join/leave notifications)
+    if (msgType === 'system') {
+      console.log('[AICQ Chat] Skipping system message in group', groupId);
+      return;
+    }
+
+    // Skip self messages (anti echo loop)
+    if (fromId && fromId === agentId) {
+      return;
+    }
+
+    if (!content) return;
+
+    // [AICQ integration standard] Dedup: msg_id primary + (group_id, from_id,
+    // content, 10s ts window) fingerprint fallback. Mirrors teambot cf67622
+    // fix for the "Leo multi-reply flood" caused by WS reconnect / server
+    // re-push. Without this, the same group message can be processed multiple
+    // times, triggering repeated AI replies and AICQ server rate limiting.
+    const grpMsgId = dataWrapper.id || dataWrapper.messageId || data.id || data.messageId;
+    if (grpMsgId) {
+      if (this._processedMsgIds.has(grpMsgId)) {
+        console.log('[AICQ Chat] Skipping duplicate group message: msg_id=', String(grpMsgId).slice(0, 12));
+        return;
+      }
+      this._processedMsgIds.add(grpMsgId);
+      if (this._processedMsgIds.size > 1000) {
+        // Trim to 500 (keep most recent — Set preserves insertion order)
+        this._processedMsgIds = new Set(Array.from(this._processedMsgIds).slice(-500));
+      }
+    } else {
+      // Fallback fingerprint dedup (10s window)
+      const ts = data.timestamp || dataWrapper.timestamp || data.ts || 0;
+      if (typeof ts === 'number' && ts > 0 && content) {
+        const tsWindow = Math.floor(ts / 10000);
+        const fingerprint = `grp_${groupId}_${fromId}_${String(content).slice(0, 200)}_${tsWindow}`;
+        if (this._processedMsgIds.has(fingerprint)) {
+          console.log('[AICQ Chat] Skipping duplicate group message (fingerprint): from=', fromId, 'group=', groupId);
+          return;
+        }
+        this._processedMsgIds.add(fingerprint);
+        if (this._processedMsgIds.size > 1000) {
+          this._processedMsgIds = new Set(Array.from(this._processedMsgIds).slice(-500));
+        }
+      }
+    }
+
+    // Check silent mode
+    const silent = this.db.getGroupSilentMode(agentId, groupId);
+    // @mention detection: prefer server-provided mentions field, but also
+    // scan content for "@<agentName>" since the AICQ server doesn't always
+    // populate the mentions array (mirrors zagent's content-scan approach).
+    const mentions = data.mentions || dataWrapper.mentions || [];
+    const agentName = (this.identity && this.identity.loadAgent && this.identity.loadAgent(agentId) && this.identity.loadAgent(agentId).name) || '';
+    const isMentioned = mentions.includes(agentId) || mentions.includes('all')
+      || (agentName && content.includes('@' + agentName))
+      || content.includes('@all');
+
+    // Detect file/image in group message
+    const isFileMessage = this._isFileMessage(msgType, content, data);
+    let localFilePath = null;
+    let originalFileName = null;
+
+    if (isFileMessage) {
+      const fileResult = await this._saveIncomingFileToUserfiles(agentId, fromId, content, data);
+      if (fileResult) {
+        localFilePath = fileResult.localPath;
+        originalFileName = fileResult.originalName;
+      }
+    }
+
+    const msg = this.db.saveMessage({
+      agent_id: agentId,
+      target_id: groupId,
+      from_id: fromId,
+      to_id: groupId,
+      type: isFileMessage ? (this._isImageMessage(msgType, content, data) ? 'image' : 'file') : (msgType || 'text'),
+      content,
+      file_url: data.file_url || data.fileUrl || dataWrapper.file_url || dataWrapper.fileUrl || null,
+      file_name: originalFileName || data.file_name || data.fileName || dataWrapper.file_name || dataWrapper.fileName || null,
+      local_path: localFilePath,
+      is_group: 1,
+      mentions,
+      status: (silent && !isMentioned) ? 'silent' : 'delivered',
+    });
+
+    if (this._onNewMessage) this._onNewMessage(msg);
+
+    // Inject synthetic message for group file messages
+    if (isFileMessage && localFilePath && this._onNewMessage && (isMentioned || !silent)) {
+      const isImage = this._isImageMessage(msgType, content, data);
+      const fileType = isImage ? '图片' : '文件';
+      const syntheticMsg = {
+        agent_id: agentId,
+        target_id: groupId,
+        from_id: fromId,
+        to_id: groupId,
+        type: 'text',
+        content: `[群组中用户发送了${fileType}] ${originalFileName || '未知文件'}
+本地路径: ${localFilePath}
+请处理该${fileType}。`,
+        is_group: 1,
+        status: 'delivered',
+        _synthetic: true,
+        _original_msg_id: msg.message_id || msg.id,
+      };
+      this._dispatchInbound(syntheticMsg);
+    }
+  }
+
+  _handleHandshakeRequest(data) {
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    this.db.savePendingRequest({
+      agent_id: agentId,
+      session_id: data.sessionId || crypto.randomUUID(),
+      requester_id: data.requesterId || data.from,
+      requester_public_key: data.requesterPublicKey || data.exchangePublicKey || '',
+    });
+  }
+
+  /**
+   * Handle server-pushed `friend_request` WS events.
+   *
+   * The AICQ server uses a simple HTTP-based friend-request flow
+   * (POST /friends/request, POST /friends/requests/:id/accept).
+   * When user A sends a friend request to AI agent B, the server pushes
+   * a `friend_request` WS message to B. We persist it into the local
+   * pending_requests table so that:
+   *   1. The OpenClaw dashboard can list pending requests via
+   *      aicq.friends.requests gateway method.
+   *   2. The auto-accept logic in channel.js can pick it up on the
+   *      next startAccount cycle (or immediately via _tryAutoAccept).
+   *
+   * The request_id from the server is stored as session_id so that
+   * acceptRequest/rejectRequest can call the server API directly.
+   */
+  _handleServerFriendRequest(data) {
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const requestId = data.request_id || data.id;
+    if (!requestId) {
+      console.warn('[AICQ Chat] friend_request WS missing request_id', data);
+      return;
+    }
+
+    this.db.savePendingRequest({
+      agent_id: agentId,
+      session_id: requestId,
+      requester_id: data.from_id || data.from || '',
+      requester_public_key: data.from_public_key || data.public_key || '',
+    });
+    console.log(`[AICQ Chat] Received friend_request from ${data.from_id || data.from} (request_id=${requestId})`);
+
+    // Opportunistically try auto-accept if a callback is registered.
+    if (typeof this._onAutoAccept === 'function') {
+      this._onAutoAccept({
+        request_id: requestId,
+        from_id: data.from_id || data.from,
+        from_public_key: data.from_public_key || '',
+      }).catch((e) =>
+        console.warn('[AICQ Chat] Auto-accept failed:', e.message)
+      );
+    }
+  }
+
+  /**
+   * Handle server-pushed `friend_request_accepted` WS events.
+   *
+   * Fired when the OTHER side accepted OUR friend request. We add the
+   * friend locally so subsequent messages can be encrypted/sent.
+   */
+  _handleServerFriendRequestAccepted(data) {
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const friendId = data.friend_id || data.by_id || data.from_id;
+    if (!friendId) return;
+
+    // Avoid double-inserting if already a friend
+    const existing = this.db.listFriends(agentId).find((f) => f.id === friendId);
+    if (existing) return;
+
+    this.db.addFriend({
+      agent_id: agentId,
+      id: friendId,
+      public_key: data.friend_public_key || data.public_key || '',
+      fingerprint: data.friend_public_key
+        ? require('./crypto').computeFingerprint(data.friend_public_key)
+        : '',
+      friend_type: data.friend_type || 'human',
+      ai_name: data.friend_name || data.friend_agent_name || '',
+    });
+    console.log(`[AICQ Chat] friend_request_accepted — added friend ${friendId}`);
+  }
+
+  /**
+   * Handle server-pushed `friend_added` WS events.
+   *
+   * Fired as a confirmation after we accept a friend request — the
+   * server has created the bidirectional friendship. We ensure the
+   * friend is in our local DB.
+   */
+  _handleServerFriendAdded(data) {
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const friendId = data.friend_id || data.id;
+    if (!friendId) return;
+
+    const existing = this.db.listFriends(agentId).find((f) => f.id === friendId);
+    if (existing) return;
+
+    this.db.addFriend({
+      agent_id: agentId,
+      id: friendId,
+      public_key: data.friend_public_key || data.public_key || '',
+      fingerprint: data.friend_public_key
+        ? require('./crypto').computeFingerprint(data.friend_public_key)
+        : '',
+      friend_type: data.friend_type || 'human',
+      ai_name: data.friend_name || data.friend_agent_name || '',
+    });
+    console.log(`[AICQ Chat] friend_added — added friend ${friendId}`);
+  }
+
+  _handlePresence(data) {
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const friendId = data.nodeId;
+    const isOnline = data.online === true || data.status === 'online';
+    this.db.updateFriendOnline(agentId, friendId, isOnline);
+  }
+
+  async _handleFileMessage(data) {
+    // Handle explicit file/image type WS messages
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const fromId = data.fromId || data.from;
+    const content = data.content || data.data || '';
+    const isImage = data.type === 'image' || this._isImageMessage(data.type, content, data);
+
+    let localFilePath = null;
+    let originalFileName = null;
+
+    // If the file data is inline (base64), save it
+    if (data.file_data || data.fileData || data.media_data || data.mediaData || (data.data && this._isBase64Data(data.data))) {
+      const fileResult = await this._saveBase64FileToUserfiles(agentId, fromId, data);
+      if (fileResult) {
+        localFilePath = fileResult.localPath;
+        originalFileName = fileResult.originalName;
+      }
+    } else if (data.file_url || data.fileUrl || data.media_url || data.mediaUrl) {
+      // Download file from URL and save locally
+      const fileResult = await this._saveUrlFileToUserfiles(agentId, fromId, data);
+      if (fileResult) {
+        localFilePath = fileResult.localPath;
+        originalFileName = fileResult.originalName;
+      }
+    }
+
+    // Save message
+    const msg = this.db.saveMessage({
+      agent_id: agentId,
+      target_id: fromId,
+      from_id: fromId,
+      to_id: agentId,
+      type: isImage ? 'image' : 'file',
+      content,
+      file_url: data.file_url || data.fileUrl || null,
+      file_name: originalFileName || data.file_name || data.fileName || null,
+      local_path: localFilePath,
+      is_group: 0,
+      status: 'delivered',
+    });
+
+    if (this._onNewMessage) this._onNewMessage(msg);
+
+    // Inject synthetic message
+    if (localFilePath && this._onNewMessage) {
+      const fileType = isImage ? '图片' : '文件';
+      const syntheticMsg = {
+        agent_id: agentId,
+        target_id: fromId,
+        from_id: fromId,
+        to_id: agentId,
+        type: 'text',
+        content: `[用户发送了${fileType}] ${originalFileName || '未知文件名'}\n本地路径: ${localFilePath}\n请处理该${fileType}。`,
+        is_group: 0,
+        status: 'delivered',
+        _synthetic: true,
+        _original_msg_id: msg.message_id || msg.id,
+      };
+      this._dispatchInbound(syntheticMsg);
+    }
+  }
+
+  _handleFileChunk(data) {
+    // File chunk handling — assemble in userfiles dir
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const chunkData = data.data || data;
+    const fileId = chunkData.fileId || data.fileId;
+
+    if (!fileId) {
+      console.log('[Chat] File chunk without fileId from', data.from);
+      return;
+    }
+
+    // Initialize incoming transfer if needed
+    if (!this._incomingFiles.has(fileId)) {
+      this._incomingFiles.set(fileId, {
+        chunks: new Map(),
+        meta: null,
+        fromId: data.fromId || data.from,
+      });
+    }
+
+    const transfer = this._incomingFiles.get(fileId);
+
+    // If this is a file-info message
+    if (chunkData.type === 'file-info') {
+      transfer.meta = chunkData;
+      return;
+    }
+
+    // Store the chunk
+    transfer.chunks.set(chunkData.index, chunkData);
+
+    // Check if all chunks received
+    if (transfer.meta && transfer.chunks.size >= transfer.meta.totalChunks) {
+      this._assembleAndNotify(agentId, fileId, transfer);
+    }
+  }
+
+  /**
+   * Assemble received file chunks into a complete file in userfiles,
+   * then notify the AI agent about the local file path.
+   */
+  _assembleAndNotify(agentId, fileId, transfer) {
+    const { meta, chunks, fromId } = transfer;
+
+    try {
+      const sortedChunks = Array.from(chunks.entries())
+        .sort((a, b) => a[0] - b[0]);
+
+      const buffers = [];
+      for (const [index, chunk] of sortedChunks) {
+        if (chunk.encrypted) {
+          // For now, try to use raw data
+          buffers.push(Buffer.from(chunk.data, 'base64'));
+        } else {
+          buffers.push(Buffer.from(chunk.data, 'base64'));
+        }
+      }
+
+      const fileBuffer = Buffer.concat(buffers);
+      const originalName = meta.fileName || `file_${fileId}`;
+      const ext = path.extname(originalName) || '.bin';
+
+      // Save to userfiles with timestamp prefix for uniqueness
+      const timestamp = Date.now();
+      const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
+      const localPath = path.join(this.userfilesDir, safeName);
+      fs.writeFileSync(localPath, fileBuffer);
+
+      const isImage = /\.(jpg|jpeg|png|gif|webp|svg|bmp)$/i.test(ext);
+
+      // Save to chat history
+      const msg = this.db.saveMessage({
+        agent_id: agentId,
+        target_id: fromId,
+        from_id: fromId,
+        to_id: agentId,
+        type: isImage ? 'image' : 'file',
+        content: JSON.stringify({
+          fileId,
+          fileName: originalName,
+          fileSize: meta.fileSize,
+          localPath,
+        }),
+        file_name: originalName,
+        local_path: localPath,
+        is_group: 0,
+        status: 'delivered',
+      });
+
+      console.log(`[Chat] File assembled: ${originalName} -> ${localPath}`);
+
+      if (this._onNewMessage) {
+        this._onNewMessage(msg);
+
+        // Inject synthetic message
+        const fileType = isImage ? '图片' : '文件';
+        const syntheticMsg = {
+          agent_id: agentId,
+          target_id: fromId,
+          from_id: fromId,
+          to_id: agentId,
+          type: 'text',
+          content: `[用户发送了${fileType}] ${originalName}\n本地路径: ${localPath}\n文件大小: ${meta.fileSize} 字节\n请处理该${fileType}。`,
+          is_group: 0,
+          status: 'delivered',
+          _synthetic: true,
+          _original_msg_id: msg.message_id || msg.id,
+        };
+        this._dispatchInbound(syntheticMsg);
+      }
+    } catch (e) {
+      console.error(`[Chat] File assembly failed for ${fileId}:`, e.message);
+    } finally {
+      this._incomingFiles.delete(fileId);
+    }
+  }
+
+  _handleStreamChunk(data) {
+    // Incoming streaming chunk from another agent
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const fromId = data.from;
+    const chunkType = data.chunkType || 'text';
+    const chunkData = data.data;
+
+    // Notify callback so OpenClaw agent can process streaming input
+    if (this._onNewMessage) {
+      this._onNewMessage({
+        type: 'stream_chunk',
+        from_id: fromId,
+        chunk_type: chunkType,
+        data: chunkData,
+      });
+    }
+    console.log('[Chat] Stream chunk from', fromId, 'type:', chunkType);
+  }
+
+  _handleStreamEnd(data) {
+    // Incoming stream end signal from another agent
+    const agentId = this.server.currentAgentId;
+    if (!agentId) return;
+
+    const fromId = data.from;
+    const messageId = data.messageId || '';
+
+    // Notify callback so OpenClaw agent knows stream is complete
+    if (this._onNewMessage) {
+      this._onNewMessage({
+        type: 'stream_end',
+        from_id: fromId,
+        message_id: messageId,
+      });
+    }
+    console.log('[Chat] Stream end from', fromId, 'messageId:', messageId);
+  }
+
+  // ─── Chat History ─────────────────────────────────────────────────
+
+  getHistory(agentId, targetId, { limit = 50, before = null } = {}) {
+    return this.db.getChatHistory(agentId, targetId, { limit, before });
+  }
+
+  deleteMessage(agentId, messageId) {
+    this.db.deleteMessage(agentId, messageId);
+  }
+
+  // ─── File Upload ──────────────────────────────────────────────────
+
+  async handleFileUpload(agentId, targetId, file, isGroup = false) {
+    const fileId = crypto.randomUUID();
+    const ext = path.extname(file.originalname || '.bin');
+    const fileName = `${fileId}${ext}`;
+    const filePath = path.join(this.uploadsDir, fileName);
+    fs.writeFileSync(filePath, file.buffer);
+
+    const isImage = /\.(jpg|jpeg|png|gif|webp|svg|bmp)$/i.test(ext);
+
+    // Send message with file reference
+    const msg = await this.sendMessage(agentId, targetId, isImage ? '[图片]' : `[文件] ${file.originalname}`, {
+      type: isImage ? 'image' : 'file',
+      isGroup,
+      file_url: `/api/files/${fileName}`,
+      file_name: file.originalname,
+      local_path: filePath,
+    });
+
+    return msg;
+  }
+
+  // ─── Userfile Management ─────────────────────────────────────────
+
+  /**
+   * Save an uploaded file from a user to the userfiles directory.
+   * This is called when files are received via the HTTP upload API
+   * and should be processed by the AI agent.
+   */
+  async handleUserFileUpload(agentId, fromId, file, isGroup = false) {
+    const fileId = crypto.randomUUID();
+    const ext = path.extname(file.originalname || '.bin');
+    const timestamp = Date.now();
+    const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
+    const localPath = path.join(this.userfilesDir, safeName);
+
+    fs.writeFileSync(localPath, file.buffer);
+
+    const isImage = /\.(jpg|jpeg|png|gif|webp|svg|bmp)$/i.test(ext);
+    const originalName = file.originalname || safeName;
+
+    // Save to chat history
+    const msg = this.db.saveMessage({
+      agent_id: agentId,
+      target_id: fromId,
+      from_id: fromId,
+      to_id: agentId,
+      type: isImage ? 'image' : 'file',
+      content: `[${isImage ? '图片' : '文件'}] ${originalName}`,
+      file_name: originalName,
+      local_path: localPath,
+      is_group: isGroup ? 1 : 0,
+      status: 'delivered',
+    });
+
+    if (this._onNewMessage) {
+      this._onNewMessage(msg);
+
+      // Inject synthetic message for AI agent
+      const fileType = isImage ? '图片' : '文件';
+      const syntheticMsg = {
+        agent_id: agentId,
+        target_id: fromId,
+        from_id: fromId,
+        to_id: agentId,
+        type: 'text',
+        content: `[用户发送了${fileType}] ${originalName}\n本地路径: ${localPath}\n文件大小: ${file.size || file.buffer?.length || 0} 字节\n请处理该${fileType}。`,
+        is_group: isGroup ? 1 : 0,
+        status: 'delivered',
+        _synthetic: true,
+        _original_msg_id: msg.message_id || msg.id,
+      };
+      this._dispatchInbound(syntheticMsg);
+    }
+
+    return { msg, localPath, originalName };
+  }
+
+  // ─── Private Helpers ──────────────────────────────────────────────
+
+  /**
+   * Check if a message represents a file/image based on type and content.
+   */
+  _isFileMessage(msgType, content, data) {
+    // Check explicit message type
+    if (['file', 'image', 'file_chunk'].includes(msgType)) return true;
+    if (['file', 'image'].includes(data.type)) return true;
+    // Also check data.data (server wraps payload in data.data)
+    const inner = data.data || {};
+    if (['file', 'image'].includes(inner.type)) return true;
+
+    // Check for file metadata in content
+    if (typeof content === 'string') {
+      try {
+        const parsed = JSON.parse(content);
+        if (parsed.type === 'file-info' || parsed.fileId || parsed.fileName || parsed.localPath) {
+          return true;
+        }
+      } catch (e) {
+        // Not JSON
+      }
+    }
+
+    // Check for file_url, media_url, or file data
+    // aicq.me web UI uses media_url / media_data for file/image messages
+    if (data.file_url || data.fileUrl || data.file_data || data.fileData) return true;
+    if (data.media_url || data.mediaUrl || data.media_data || data.mediaData) return true;
+    if (inner.file_url || inner.fileUrl || inner.media_url || inner.mediaUrl) return true;
+    if (inner.file_data || inner.fileData || inner.media_data || inner.mediaData) return true;
+
+    // Check for known file markers in text content
+    if (typeof content === 'string' && (
+      content.startsWith('[文件]') ||
+      content.startsWith('[图片]') ||
+      content.startsWith('[File]') ||
+      content.startsWith('[Image]')
+    )) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if a message is specifically an image (vs other file types).
+   */
+  _isImageMessage(msgType, content, data) {
+    if (msgType === 'image' || data.type === 'image') return true;
+
+    // Check file extension in filename
+    const fileName = data.file_name || data.fileName || '';
+    if (/\.(jpg|jpeg|png|gif|webp|svg|bmp)$/i.test(fileName)) return true;
+
+    // Check content markers
+    if (typeof content === 'string' && content.startsWith('[图片]')) return true;
+
+    return false;
+  }
+
+  /**
+   * Save an incoming file to the userfiles directory.
+   * Handles various formats: inline base64, URL references, file-info JSON.
+   */
+  async _saveIncomingFileToUserfiles(agentId, fromId, content, data) {
+    try {
+      const fileId = crypto.randomUUID();
+      const timestamp = Date.now();
+
+      // Also check inner data (server wraps payload in data.data)
+      const inner = data.data || {};
+
+      // Try to extract file info from the message
+      let parsed = null;
+      if (typeof content === 'string') {
+        try { parsed = JSON.parse(content); } catch (e) {}
+      }
+
+      // Case 1: file-info with chunked data (already assembled elsewhere)
+      if (parsed && parsed.localPath) {
+        return {
+          localPath: parsed.localPath,
+          originalName: parsed.fileName || path.basename(parsed.localPath),
+        };
+      }
+
+      // Case 2: Base64 data inline
+      // Check both legacy (file_data/fileData) and aicq.me (media_data/mediaData) field names
+      const base64Data = data.file_data || data.fileData || data.media_data || data.mediaData
+        || inner.file_data || inner.fileData || inner.media_data || inner.mediaData
+        || (parsed && parsed.data);
+      if (base64Data) {
+        // [FIX 2026-08-27] forwarded/relay frames often drop file_name entirely
+        // — walk every field incl. unwrapping file_info JSON strings.
+        const fileName = this._extractFileName(data, inner, parsed) || 'file.bin';
+        return await this._saveBase64FileToUserfiles(agentId, fromId, {
+          ...data,
+          file_data: base64Data,
+          file_name: fileName,
+        });
+      }
+
+      // Case 3: URL reference — download and save
+      // Check both legacy (file_url/fileUrl) and aicq.me (media_url/mediaUrl) field names
+      const fileUrl = data.file_url || data.fileUrl || data.media_url || data.mediaUrl
+        || inner.file_url || inner.fileUrl || inner.media_url || inner.mediaUrl
+        || (parsed && parsed.fileUrl);
+      if (fileUrl) {
+        // [FIX 2026-08-27] full extraction chain (see _extractFileName).
+        const fileName = this._extractFileName(data, inner, parsed) || 'file.bin';
+        return await this._saveUrlFileToUserfiles(agentId, fromId, {
+          ...data,
+          file_url: fileUrl,
+          file_name: fileName,
+        });
+      }
+
+      // Case 4: Text-based file marker like [文件] filename or [图片] filename
+      if (typeof content === 'string' && (
+        content.startsWith('[文件]') ||
+        content.startsWith('[图片]') ||
+        content.startsWith('[File]') ||
+        content.startsWith('[Image]')
+      )) {
+        const originalName = content.replace(/^\[(文件|图片|File|Image)\]\s*/, '').trim() || 'unknown';
+        const ext = path.extname(originalName) || (content.includes('图片') || content.includes('Image') ? '.png' : '.bin');
+        const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
+        const localPath = path.join(this.userfilesDir, safeName);
+
+        // Create a placeholder file — the actual content may come via chunks
+        // or may already be in the uploads dir
+        const uploadsPath = path.join(this.uploadsDir, originalName);
+        if (fs.existsSync(uploadsPath)) {
+          fs.copyFileSync(uploadsPath, localPath);
+          console.log(`[Chat] Copied user file: ${originalName} -> ${localPath}`);
+          return { localPath, originalName };
+        }
+
+        // No actual file data yet — save a placeholder
+        fs.writeFileSync(localPath, Buffer.alloc(0));
+        console.log(`[Chat] Created placeholder for user file: ${localPath}`);
+        return { localPath, originalName };
+      }
+
+      return null;
+    } catch (e) {
+      console.error('[Chat] Failed to save incoming file to userfiles:', e.message);
+      return null;
+    }
+  }
+
+  /**
+   * Save a base64-encoded file to userfiles.
+   */
+  async _saveBase64FileToUserfiles(agentId, fromId, data) {
+    try {
+      const fileId = crypto.randomUUID();
+      const timestamp = Date.now();
+      const base64Data = data.file_data || data.fileData || data.data;
+      const originalName = data.file_name || data.fileName || 'file.bin';
+
+      if (!base64Data) return null;
+
+      // Strip data URL prefix if present (e.g., "data:image/png;base64,")
+      const base64Clean = base64Data.replace(/^data:[^;]+;base64,/, '');
+      const fileBuffer = Buffer.from(base64Clean, 'base64');
+
+      // [FIX 2026-08-27] placeholder names must not pin the extension to .bin:
+      // real ext > data-URL mime > magic bytes > .bin
+      let ext = '';
+      if (!/^file\.bin$/i.test(originalName)) ext = path.extname(originalName);
+      if (!ext) ext = this._inferExtFromData(base64Data);
+      if (!ext) ext = this._inferExtFromBuffer(fileBuffer);
+      if (!ext) ext = '.bin';
+      const displayName = /^file\.bin$/i.test(originalName) ? `file${ext}` : originalName;
+      const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
+      const localPath = path.join(this.userfilesDir, safeName);
+
+      fs.writeFileSync(localPath, fileBuffer);
+      console.log(`[Chat] Saved base64 user file: ${displayName} -> ${localPath} (${fileBuffer.length} bytes)`);
+
+      return { localPath, originalName: displayName };
+    } catch (e) {
+      console.error('[Chat] Failed to save base64 file:', e.message);
+      return null;
+    }
+  }
+
+  /**
+   * Download a file from URL and save to userfiles.
+   */
+  async _saveUrlFileToUserfiles(agentId, fromId, data) {
+    try {
+      const fileId = crypto.randomUUID();
+      const timestamp = Date.now();
+      const fileUrl = data.file_url || data.fileUrl;
+      const originalName = data.file_name || data.fileName || path.basename(fileUrl || 'file.bin');
+
+      // For aicq.me server URLs (/api/v1/chat/files/:id), download the file
+      // using the AI agent's JWT token
+      if (fileUrl && (fileUrl.startsWith('/api/v1/chat/files/') || fileUrl.includes('/api/v1/chat/files/'))) {
+        const downloadUrl = this.server.serverUrl + fileUrl;
+        const token = this.server.jwtToken;
+        const fetch = require('node-fetch');
+        try {
+          const resp = await fetch(downloadUrl, {
+            headers: { 'Authorization': `Bearer ${token}` },
+          });
+          if (resp.ok) {
+            const buffer = await resp.buffer();
+            const contentType = resp.headers.get('content-type') || '';
+            // [FIX 2026-08-27] forwarded frames lose the original filename and
+            // the server historically sent no Content-Type/Disposition. Priority:
+            // Content-Disposition > real ext > magic bytes > MIME > .bin
+            const dispName = this._parseDispositionFilename(resp.headers.get('content-disposition'));
+            let ext = '';
+            let chosenName = originalName;
+            if (dispName) {
+              chosenName = dispName;
+              if (path.extname(dispName)) ext = path.extname(dispName);
+            }
+            if (!ext && path.extname(originalName) && !/^file\.bin$/i.test(originalName)) {
+              ext = path.extname(originalName);
+            }
+            if (!ext) ext = this._inferExtFromBuffer(buffer);
+            if (!ext && contentType) {
+              const mime = contentType.split(';')[0].trim().toLowerCase();
+              if (mime !== 'application/octet-stream') ext = this._inferExtFromMime(mime);
+            }
+            if (!ext) ext = '.bin';
+            if (/^file\.bin$/i.test(chosenName)) chosenName = `file${ext}`;
+            const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
+            const localPath = path.join(this.userfilesDir, safeName);
+            fs.writeFileSync(localPath, buffer);
+            console.log(`[Chat] Downloaded aicq.me file: ${fileUrl} -> ${localPath} (${buffer.length} bytes, name=${chosenName})`);
+            return { localPath, originalName: chosenName };
+          } else {
+            console.warn(`[Chat] aicq.me file download failed: HTTP ${resp.status}`);
+          }
+        } catch (e) {
+          console.warn('[Chat] Failed to download aicq.me file:', e.message);
+        }
+      }
+
+      // For local server URLs (/api/files/), resolve the local path directly
+      if (fileUrl && fileUrl.startsWith('/api/files/')) {
+        const fileName = path.basename(fileUrl);
+        const uploadsPath = path.join(this.uploadsDir, fileName);
+        if (fs.existsSync(uploadsPath)) {
+          const ext = path.extname(originalName) || path.extname(uploadsPath);
+          const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
+          const localPath = path.join(this.userfilesDir, safeName);
+          fs.copyFileSync(uploadsPath, localPath);
+          console.log(`[Chat] Copied local URL file: ${fileUrl} -> ${localPath}`);
+          return { localPath, originalName };
+        }
+      }
+
+      // For other remote URLs, save a placeholder with the URL reference
+      console.log(`[Chat] Remote file URL (async download not yet supported): ${fileUrl}`);
+      const ext = path.extname(originalName) || '.bin';
+      const safeName = `${timestamp}_${fileId.substring(0, 8)}${ext}`;
+      const localPath = path.join(this.userfilesDir, safeName);
+      fs.writeFileSync(localPath, JSON.stringify({
+        type: 'url_reference',
+        url: fileUrl,
+        originalName,
+        timestamp,
+      }));
+      return { localPath, originalName };
+    } catch (e) {
+      console.error('[Chat] Failed to save URL file:', e.message);
+      return null;
+    }
+  }
+
+  /**
+   * [FIX 2026-08-27] Resolve the best-known filename for an incoming file.
+   *
+   * The "forwarded frame loses the file name" case: WS relay / group echo
+   * frames only carry media_url plus an optional file_info field that the
+   * server stores as a JSON STRING, so none of the previous inner.file_info
+   * .filename lookups ever fired and everything fell back to file.bin.
+   */
+  _extractFileName(data, inner, parsed) {
+    const candidates = [
+      data && data.file_name, data && data.fileName,
+      data && data.media_filename, data && data.mediaFilename,
+      data && data.filename, data && data.name,
+      inner && inner.file_name, inner && inner.fileName,
+      inner && inner.media_filename, inner && inner.mediaFilename,
+      inner && inner.filename, inner && inner.name,
+      parsed && parsed.fileName, parsed && parsed.file_name,
+      parsed && parsed.filename, parsed && parsed.original_name,
+      parsed && parsed.originalName, parsed && parsed.name,
+    ];
+    // file_info may be a JSON string (server persists it as TEXT) or object
+    for (const fi of [data && data.file_info, inner && inner.file_info, parsed && parsed.file_info]) {
+      if (!fi) continue;
+      try {
+        const obj = typeof fi === 'string' ? JSON.parse(fi) : fi;
+        if (obj && typeof obj === 'object') {
+          candidates.push(obj.filename, obj.file_name, obj.fileName,
+            obj.original_name, obj.originalName, obj.name);
+        }
+      } catch (e) {
+        // plain string content (not JSON)
+        if (typeof fi === 'string' && fi.trim()) candidates.push(fi.trim());
+      }
+    }
+    for (const c of candidates) {
+      if (typeof c === 'string' && c.trim()) return c.trim();
+    }
+    return '';
+  }
+
+  /**
+   * [FIX 2026-08-27] Magic-byte sniffing — recovers the real type when both
+   * the frame metadata and HTTP headers are silent.
+   */
+  _inferExtFromBuffer(buf) {
+    if (!buf || buf.length < 12) return '';
+    const startsWith = (arr, off = 0) => arr.every((b, i) => buf[off + i] === b);
+    if (startsWith([0x89, 0x50, 0x4E, 0x47])) return '.png';           // \x89PNG
+    if (startsWith([0xFF, 0xD8, 0xFF])) return '.jpg';                  // JPEG SOI
+    if (startsWith([0x47, 0x49, 0x46, 0x38])) return '.gif';            // GIF87a/89a
+    if (buf.slice(0, 4).toString('ascii') === 'RIFF'
+        && buf.slice(8, 12).toString('ascii') === 'WEBP') return '.webp';
+    if (buf.slice(0, 5).toString('ascii') === '%PDF-') return '.pdf';
+    if (startsWith([0x50, 0x4B, 0x03, 0x04]) || startsWith([0x50, 0x4B, 0x05, 0x06])) return '.zip';
+    if (buf.slice(4, 8).toString('ascii') === 'ftyp') return '.mp4';
+    if (startsWith([0x49, 0x44, 0x33]) || startsWith([0xFF, 0xFB])) return '.mp3';
+    if (startsWith([0x1F, 0x8B])) return '.gz';
+    if (buf[0] === 0x42 && buf[1] === 0x4D) return '.bmp';              // BM
+    return '';
+  }
+
+  /**
+   * Parse filename out of a Content-Disposition header value (RFC 2183/5987).
+   */
+  _parseDispositionFilename(header) {
+    if (!header) return '';
+    let m = header.match(/filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/i);
+    if (m) {
+      try { return decodeURIComponent(m[1].trim()); } catch (e) { return m[1].trim(); }
+    }
+    m = header.match(/filename\s*=\s*"([^"]+)"/i);
+    if (m) return m[1];
+    m = header.match(/filename\s*=\s*([^;]+)/i);
+    if (m) return m[1].trim();
+    return '';
+  }
+
+  /**
+   * Helper: synchronous-style fetch for downloading files.
+   * Since _saveUrlFileToUserfiles is called from sync context, we use
+   * a child_process execSync to download the file.
+   */
+  _inferExtFromMime(mime) {
+    const map = {
+      'image/png': '.png', 'image/jpeg': '.jpg', 'image/gif': '.gif',
+      'image/webp': '.webp', 'image/svg+xml': '.svg', 'image/bmp': '.bmp',
+      'application/pdf': '.pdf', 'text/plain': '.txt',
+      'application/zip': '.zip',
+      'audio/mpeg': '.mp3', 'video/mp4': '.mp4',
+    };
+    // [FIX 2026-08-27] unknown & application/octet-stream return '' so callers
+    // fall through to magic-byte sniffing instead of ending at .bin blindly.
+    return map[mime] || '';
+  }
+
+  /**
+   * Check if a string looks like base64 data.
+   */
+  _isBase64Data(str) {
+    if (typeof str !== 'string') return false;
+    if (str.startsWith('data:')) return true;
+    // Quick heuristic: long string with only base64 chars
+    if (str.length > 100 && /^[A-Za-z0-9+/=\s]+$/.test(str.substring(0, 200))) return true;
+    return false;
+  }
+
+  /**
+   * Infer file extension from base64 data URL prefix.
+   */
+  _inferExtFromData(data) {
+    if (typeof data !== 'string') return '.bin';
+    const mimeMatch = data.match(/^data:([^;]+);/);
+    if (mimeMatch) {
+      const mime = mimeMatch[1];
+      const mimeToExt = {
+        'image/png': '.png',
+        'image/jpeg': '.jpg',
+        'image/gif': '.gif',
+        'image/webp': '.webp',
+        'image/svg+xml': '.svg',
+        'image/bmp': '.bmp',
+        'application/pdf': '.pdf',
+        'text/plain': '.txt',
+        'application/json': '.json',
+        'application/zip': '.zip',
+        'audio/mpeg': '.mp3',
+        'video/mp4': '.mp4',
+      };
+      return mimeToExt[mime] || '.bin';
+    }
+    return '.bin';
+  }
+}
+
+module.exports = ChatManager;