pikiloop 0.4.0

package/dist/channels/wecom/channel.js

@@ -0,0 +1,479 @@
+/**
+ * WeChat Work / 企业微信 智能机器人 channel transport — Smart Bot WebSocket.
+ *
+ * Endpoint:   wss://openws.work.weixin.qq.com
+ * Frame envelope:
+ *   { cmd, headers: { req_id }, body }
+ *   responses omit `cmd` and may carry { errcode, errmsg }
+ *
+ * Outbound:
+ *   - aibot_subscribe { bot_id, secret }              — auth + register
+ *   - ping                                              — heartbeat (30s)
+ *   - aibot_respond_msg (stream, finish=true)         — reply to a callback
+ *   - aibot_send_msg (markdown)                        — proactive send
+ *
+ * Inbound:
+ *   - aibot_msg_callback { msgid, chatid, chattype, from.userid, msgtype, text/voice/image/file/mixed/quote }
+ *
+ * Caveats:
+ *   - text/voice messages are dispatched as text. Image/file/mixed payloads
+ *     reference encrypted URLs that require a separate corp-secret + AES key
+ *     to download — out of scope for this minimal transport.
+ *   - The protocol has no edit primitive. editMessage is a no-op.
+ *   - Plain text messages may be sent via aibot_respond_msg (in conversation,
+ *     when we still hold the original req_id) or aibot_send_msg (proactive
+ *     send to a known chatid). We use the original req_id for the first
+ *     reply and switch to aibot_send_msg for follow-up messages in the same
+ *     conversation (e.g. streaming result deliveries).
+ */
+import { EventEmitter } from 'node:events';
+import { WebSocket } from 'ws';
+import { Channel, DEFAULT_CHANNEL_CAPABILITIES, splitText, sleep, } from '../base.js';
+import { WECOM_LIMITS } from '../../core/constants.js';
+import { writeScopedLog } from '../../core/logging.js';
+import { ChannelHealth } from '../health.js';
+const WC_MAX = WECOM_LIMITS.maxMessageLength;
+const WC_HEARTBEAT_MS = WECOM_LIMITS.heartbeatInterval;
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err ?? 'unknown error');
+}
+export class WeComChannel extends Channel {
+    capabilities = {
+        ...DEFAULT_CHANNEL_CAPABILITIES,
+        // Smart Bot WS protocol has no edit primitive.
+    };
+    knownChats = new Set();
+    botId;
+    botSecret;
+    endpoint;
+    allowedUserIds;
+    ws = null;
+    running = false;
+    listenResolve = null;
+    heartbeatTimer = null;
+    missedPong = 0;
+    reqSeq = 0;
+    chatMeta = new Map();
+    /** req_id -> deferred ack handler. */
+    pendingAcks = new Map();
+    /** Dedup by msgid. */
+    seenMsgIds = new Set();
+    seenMsgQueue = [];
+    static SEEN_CAP = 256;
+    /** Subscribe ack waiter — only set during initial handshake. */
+    subscribeAck = null;
+    internalEmitter = new EventEmitter();
+    messageHandlers = new Set();
+    errorHandlers = new Set();
+    constructor(opts) {
+        super();
+        this.botId = opts.botId;
+        this.botSecret = opts.botSecret;
+        this.endpoint = (opts.endpoint || WECOM_LIMITS.defaultEndpoint).replace(/\/+$/, '/');
+        this.allowedUserIds = opts.allowedUserIds;
+        this.internalEmitter.setMaxListeners(0);
+    }
+    onMessage(handler) { this.messageHandlers.add(handler); return this; }
+    onError(handler) { this.errorHandlers.add(handler); return this; }
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
+    async connect() {
+        const shortId = this.botId.length > 12 ? `${this.botId.slice(0, 6)}...${this.botId.slice(-4)}` : this.botId;
+        this.bot = {
+            id: this.botId,
+            username: `wecom_${shortId}`,
+            displayName: `WeCom ${shortId}`,
+        };
+        return this.bot;
+    }
+    async listen() {
+        this.running = true;
+        const health = new ChannelHealth({
+            label: 'WeCom',
+            opAction: 'WS connect',
+            initialDelayMs: WECOM_LIMITS.initialRetryDelay,
+            maxDelayMs: WECOM_LIMITS.maxRetryDelay,
+            sustainedFailureHint: 'verify wecomBotId / wecomBotSecret / wecomEndpoint in setting.json',
+            log: (msg, level) => this.log(msg, level),
+        });
+        while (this.running) {
+            const connectedAt = Date.now();
+            let connectionErr = null;
+            try {
+                await this.runConnection();
+            }
+            catch (err) {
+                connectionErr = err;
+                this.emitError(err instanceof Error ? err : new Error(describeError(err)));
+            }
+            if (!this.running)
+                break;
+            // A connection that survived >2 heartbeats counts as "healthy session
+            // ended" → reset backoff and reconnect quickly. Anything shorter is
+            // treated as a failed attempt that advances exponential backoff.
+            const wasLongLived = Date.now() - connectedAt > 2 * WC_HEARTBEAT_MS;
+            const delayMs = wasLongLived
+                ? (health.recordSuccess(), WECOM_LIMITS.initialRetryDelay)
+                : health.recordFailure(connectionErr ?? new Error('connection dropped'));
+            await sleep(delayMs);
+        }
+    }
+    disconnect() {
+        this.running = false;
+        this.stopHeartbeat();
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch { }
+            this.ws = null;
+        }
+        this.listenResolve?.();
+        this.listenResolve = null;
+    }
+    // ========================================================================
+    // Single-connection lifecycle
+    // ========================================================================
+    runConnection() {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.stopHeartbeat();
+                this.failPendingAcks();
+                try {
+                    ws.close();
+                }
+                catch { }
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            this.debug(`[ws] dialing ${this.endpoint}`);
+            const ws = new WebSocket(this.endpoint);
+            this.ws = ws;
+            this.missedPong = 0;
+            ws.on('open', () => {
+                this.subscribe().catch(err => finish(err instanceof Error ? err : new Error(describeError(err))));
+            });
+            ws.on('message', raw => {
+                try {
+                    const text = raw instanceof Buffer ? raw.toString('utf-8') : String(raw);
+                    const frame = JSON.parse(text);
+                    this.handleFrame(frame);
+                }
+                catch (err) {
+                    this.debug(`[ws] invalid json: ${describeError(err)}`);
+                }
+            });
+            ws.on('error', err => {
+                const error = err instanceof Error ? err : new Error(describeError(err));
+                finish(error);
+            });
+            ws.on('close', (code, reasonBuf) => {
+                const reason = reasonBuf?.toString?.() || '';
+                const detail = reason ? `${code} ${reason}` : `${code}`;
+                finish(new Error(`websocket closed: ${detail}`));
+            });
+        });
+    }
+    async subscribe() {
+        const reqId = this.makeReqId('aibot_subscribe');
+        const frame = {
+            cmd: 'aibot_subscribe',
+            headers: { req_id: reqId },
+            body: { bot_id: this.botId, secret: this.botSecret },
+        };
+        await new Promise((resolve, reject) => {
+            this.subscribeAck = err => err ? reject(err) : resolve();
+            this.writeFrame(frame).catch(err => {
+                this.subscribeAck = null;
+                reject(err instanceof Error ? err : new Error(describeError(err)));
+            });
+            // Defensive timeout — server should ack within seconds.
+            const timer = setTimeout(() => {
+                if (!this.subscribeAck)
+                    return;
+                const ack = this.subscribeAck;
+                this.subscribeAck = null;
+                ack(new Error('subscribe ack timeout'));
+            }, 10_000);
+            timer.unref?.();
+        });
+        this.debug('[ws] subscribed successfully');
+        this.startHeartbeat();
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.missedPong >= 2) {
+                this.log('[ws] no heartbeat ack for 2 consecutive pings — closing', 'warn');
+                try {
+                    this.ws?.close();
+                }
+                catch { }
+                return;
+            }
+            this.missedPong++;
+            const reqId = this.makeReqId('ping');
+            void this.writeFrame({ cmd: 'ping', headers: { req_id: reqId } }).catch(() => { });
+        }, WC_HEARTBEAT_MS);
+        this.heartbeatTimer.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    // ========================================================================
+    // Frame dispatch
+    // ========================================================================
+    handleFrame(frame) {
+        const cmd = frame.cmd || '';
+        const reqId = frame.headers?.req_id || '';
+        if (cmd === 'aibot_msg_callback') {
+            this.handleMsgCallback(frame);
+            return;
+        }
+        if (cmd === 'aibot_event_callback') {
+            this.debug(`[ws] event callback (ignored) req_id=${reqId}`);
+            return;
+        }
+        if (!cmd) {
+            // Response frame; route by req_id prefix.
+            if (reqId.startsWith('ping')) {
+                this.missedPong = 0;
+                return;
+            }
+            if (reqId.startsWith('aibot_subscribe')) {
+                const ack = this.subscribeAck;
+                this.subscribeAck = null;
+                if (typeof frame.errcode === 'number' && frame.errcode !== 0) {
+                    ack?.(new Error(`subscribe failed: errcode=${frame.errcode} errmsg=${frame.errmsg || ''}`));
+                }
+                else {
+                    ack?.(null);
+                }
+                return;
+            }
+            const pending = this.pendingAcks.get(reqId);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingAcks.delete(reqId);
+                if (typeof frame.errcode === 'number' && frame.errcode !== 0) {
+                    pending.reject(new Error(`ack errcode=${frame.errcode} errmsg=${frame.errmsg || ''}`));
+                }
+                else {
+                    pending.resolve();
+                }
+            }
+            return;
+        }
+        this.debug(`[ws] unhandled cmd=${cmd}`);
+    }
+    handleMsgCallback(frame) {
+        const body = frame.body || {};
+        const msgId = String(body.msgid || '').trim();
+        const reqId = frame.headers?.req_id || '';
+        if (!msgId)
+            return;
+        if (this.seenMsgIds.has(msgId))
+            return;
+        this.seenMsgIds.add(msgId);
+        this.seenMsgQueue.push(msgId);
+        while (this.seenMsgQueue.length > WeComChannel.SEEN_CAP) {
+            this.seenMsgIds.delete(this.seenMsgQueue.shift());
+        }
+        const userId = String(body.from?.userid || '').trim();
+        if (!userId)
+            return;
+        if (!this.isAllowed(userId)) {
+            this.debug(`[recv] blocked: userid=${userId} not in allowlist`);
+            return;
+        }
+        const chatType = String(body.chattype || 'single');
+        const chatId = String(body.chatid || '').trim() || userId;
+        this.knownChats.add(chatId);
+        const meta = this.chatMeta.get(chatId) ?? { pendingReqId: null };
+        meta.pendingReqId = reqId || meta.pendingReqId;
+        this.chatMeta.set(chatId, meta);
+        const text = this.extractInboundText(body);
+        const ctx = {
+            chatId,
+            messageId: msgId,
+            chatType,
+            reqId: reqId || '',
+            from: { userId },
+            reply: (replyText, opts) => this.send(chatId, replyText, opts),
+            editReply: () => Promise.resolve(),
+            channel: this,
+            raw: body,
+        };
+        const payload = { text, files: [] };
+        void this.dispatchInbound(payload, ctx);
+    }
+    extractInboundText(body) {
+        if (!body)
+            return '';
+        const direct = String(body.text?.content || '').trim();
+        if (direct)
+            return this.stripBotMention(direct, body.aibotid);
+        if (body.msgtype === 'voice') {
+            const voice = body.voice || {};
+            const transcript = String(voice.content || voice.text || '').trim();
+            if (transcript)
+                return this.stripBotMention(transcript, body.aibotid);
+        }
+        if (body.msgtype === 'mixed' && Array.isArray(body.mixed?.msg_item)) {
+            const parts = [];
+            for (const item of body.mixed.msg_item) {
+                if (item?.msgtype === 'text' && item.text?.content)
+                    parts.push(String(item.text.content));
+            }
+            const joined = parts.join('\n').trim();
+            if (joined)
+                return this.stripBotMention(joined, body.aibotid);
+        }
+        return '';
+    }
+    stripBotMention(text, aibotid) {
+        let out = text;
+        if (aibotid)
+            out = out.replace(new RegExp(`@${aibotid}`, 'g'), '');
+        if (this.botId)
+            out = out.replace(new RegExp(`@${this.botId}`, 'g'), '');
+        return out.trim();
+    }
+    async dispatchInbound(payload, ctx) {
+        for (const handler of this.messageHandlers) {
+            try {
+                await handler(payload, ctx);
+            }
+            catch (error) {
+                this.emitError(error instanceof Error ? error : new Error(describeError(error)));
+            }
+        }
+    }
+    // ========================================================================
+    // Outgoing primitives
+    // ========================================================================
+    async send(chatId, text, _opts) {
+        const chat = String(chatId);
+        const trimmed = (text || '').trim() || '(empty)';
+        const chunks = splitText(trimmed, WC_MAX);
+        let lastReqId = null;
+        const meta = this.chatMeta.get(chat);
+        const replyReqId = meta?.pendingReqId;
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            // First chunk: prefer aibot_respond_msg if we hold a fresh req_id.
+            if (i === 0 && replyReqId) {
+                const streamId = this.makeReqId('stream');
+                const frame = {
+                    cmd: 'aibot_respond_msg',
+                    headers: { req_id: replyReqId },
+                    body: {
+                        msgtype: 'stream',
+                        stream: { id: streamId, finish: true, content: chunk },
+                    },
+                };
+                await this.writeFrame(frame);
+                // The server treats the req_id as consumed after stream finish=true.
+                if (meta)
+                    meta.pendingReqId = null;
+                lastReqId = replyReqId;
+                continue;
+            }
+            const reqId = this.makeReqId('aibot_send_msg');
+            const frame = {
+                cmd: 'aibot_send_msg',
+                headers: { req_id: reqId },
+                body: {
+                    chatid: chat,
+                    msgtype: 'markdown',
+                    markdown: { content: chunk },
+                },
+            };
+            await this.writeAndAwaitAck(reqId, frame, 5_000);
+            lastReqId = reqId;
+        }
+        return lastReqId;
+    }
+    async editMessage(_chatId, _msgId, _text, _opts) {
+        // No edit primitive in the Smart Bot WS protocol.
+    }
+    async deleteMessage(_chatId, _msgId) {
+        // No delete primitive.
+    }
+    async sendTyping(_chatId, _opts) {
+        // No typing indicator.
+    }
+    // ========================================================================
+    // Frame writing helpers
+    // ========================================================================
+    writeFrame(frame) {
+        return new Promise((resolve, reject) => {
+            const ws = this.ws;
+            if (!ws || ws.readyState !== ws.OPEN) {
+                reject(new Error('wecom-ws: not connected'));
+                return;
+            }
+            ws.send(JSON.stringify(frame), err => {
+                if (err)
+                    reject(err instanceof Error ? err : new Error(describeError(err)));
+                else
+                    resolve();
+            });
+        });
+    }
+    writeAndAwaitAck(reqId, frame, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingAcks.delete(reqId);
+                // Fall back to non-blocking on timeout to avoid deadlocks.
+                this.debug(`[ws] ack timeout req_id=${reqId} — proceeding`);
+                resolve();
+            }, timeoutMs);
+            timer.unref?.();
+            this.pendingAcks.set(reqId, { resolve, reject, timer });
+            this.writeFrame(frame).catch(err => {
+                const pending = this.pendingAcks.get(reqId);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pendingAcks.delete(reqId);
+                }
+                reject(err);
+            });
+        });
+    }
+    failPendingAcks() {
+        for (const [reqId, pending] of this.pendingAcks) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('wecom-ws: connection closed'));
+            this.pendingAcks.delete(reqId);
+        }
+    }
+    makeReqId(prefix) {
+        this.reqSeq += 1;
+        return `${prefix}_${this.reqSeq}`;
+    }
+    isAllowed(userId) {
+        if (!this.allowedUserIds?.size)
+            return true;
+        return this.allowedUserIds.has(userId);
+    }
+    emitError(error) {
+        for (const handler of this.errorHandlers) {
+            try {
+                handler(error);
+            }
+            catch { }
+        }
+    }
+    debug(msg) { this.log(msg, 'debug'); }
+    log(msg, level = 'info') { writeScopedLog('wecom', msg, { level }); }
+}