@yanhaidao/wecom 2.3.10 → 2.3.12

package/src/runtime.ts

@@ -1,7 +1,10 @@
 export {
   getAccountRuntimeSnapshot,
+  getBotWsPushHandle,
   getWecomRuntime,
   registerAccountRuntime,
+  registerBotWsPushHandle,
   setWecomRuntime,
+  unregisterBotWsPushHandle,
   unregisterAccountRuntime,
 } from "./app/index.js";

package/src/transport/bot-ws/reply.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+
+import { createBotWsReplyHandle } from "./reply.js";
+
+type ReplyHandleParams = Parameters<typeof createBotWsReplyHandle>[0];
+
+describe("createBotWsReplyHandle", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("uses configured placeholder content for immediate ws ack", async () => {
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-1" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      placeholderContent: "正在思考...",
+    });
+
+    expect(replyStream).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: { req_id: "req-1" },
+      }),
+      expect.any(String),
+      "正在思考...",
+      false,
+    );
+  });
+
+  it("keeps placeholder alive until the first real ws chunk arrives", async () => {
+    vi.useFakeTimers();
+
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    const handle = createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-keepalive" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      placeholderContent: "正在思考...",
+    });
+
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(replyStream).toHaveBeenCalledTimes(2);
+
+    await handle.deliver({ text: "最终回复" }, { kind: "final" });
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(replyStream).toHaveBeenCalledTimes(3);
+    expect(replyStream).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        headers: { req_id: "req-keepalive" },
+      }),
+      expect.any(String),
+      "最终回复",
+      true,
+    );
+  });
+
+  it("does not auto-send placeholder when disabled", () => {
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-2" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      autoSendPlaceholder: false,
+    });
+
+    expect(replyStream).not.toHaveBeenCalled();
+  });
+
+  it("swallows expired stream update errors during delivery", async () => {
+    const expiredError = {
+      headers: { req_id: "req-expired" },
+      errcode: 846608,
+      errmsg: "stream message update expired (>6 minutes), cannot update",
+    };
+    const replyStream = vi.fn().mockRejectedValue(expiredError);
+    const onFail = vi.fn();
+    const handle = createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: "req-expired" },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      autoSendPlaceholder: false,
+      onFail,
+    });
+
+    await expect(handle.deliver({ text: "最终回复" }, { kind: "final" })).resolves.toBeUndefined();
+
+    expect(replyStream).toHaveBeenCalledTimes(1);
+    expect(onFail).toHaveBeenCalledWith(expiredError);
+  });
+
+  it.each([
+    [{ headers: { req_id: "req-invalid" }, errcode: 846605, errmsg: "invalid req_id" }],
+    [{ headers: { req_id: "req-expired" }, errcode: 846608, errmsg: "stream message update expired (>6 minutes), cannot update" }],
+  ])("does not retry error reply when the ws reply window is already closed", async (error) => {
+    const replyStream = vi.fn().mockResolvedValue(undefined);
+    const onFail = vi.fn();
+    const handle = createBotWsReplyHandle({
+      client: {
+        replyStream,
+      } as unknown as ReplyHandleParams["client"],
+      frame: {
+        headers: { req_id: String(error.headers.req_id) },
+        body: {},
+      } as unknown as ReplyHandleParams["frame"],
+      accountId: "default",
+      autoSendPlaceholder: false,
+      onFail,
+    });
+
+    await handle.fail?.(error);
+
+    expect(replyStream).not.toHaveBeenCalled();
+    expect(onFail).toHaveBeenCalledTimes(1);
+  });
+});

package/src/transport/bot-ws/reply.ts

@@ -1,11 +1,45 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk";
 import { generateReqId, type WsFrame, type BaseMessage, type EventMessage, type WSClient } from "@wecom/aibot-node-sdk";
 
 import type { ReplyHandle, ReplyPayload } from "../../types/index.js";
 
+const PLACEHOLDER_KEEPALIVE_MS = 3000;
+
+function isInvalidReqIdError(error: unknown): boolean {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const errcode = "errcode" in error ? Number(error.errcode) : undefined;
+  const errmsg = "errmsg" in error ? String(error.errmsg ?? "") : "";
+  return errcode === 846605 || errmsg.includes("invalid req_id");
+}
+
+function isExpiredStreamUpdateError(error: unknown): boolean {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const errcode = "errcode" in error ? Number(error.errcode) : undefined;
+  const errmsg = "errmsg" in error ? String(error.errmsg ?? "").toLowerCase() : "";
+  return errcode === 846608 || errmsg.includes("stream message update expired");
+}
+
+/** SDK rejects with a plain Error whose message contains "ack timeout" when
+ * the WeCom server does not acknowledge a reply within 5 s.  Once timed out
+ * the reqId slot is released; further replies on the same reqId will fail. */
+function isAckTimeoutError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("ack timeout");
+}
+
+function isTerminalReplyError(error: unknown): boolean {
+  return isInvalidReqIdError(error) || isExpiredStreamUpdateError(error) || isAckTimeoutError(error);
+}
+
 export function createBotWsReplyHandle(params: {
   client: WSClient;
   frame: WsFrame<BaseMessage | EventMessage>;
   accountId: string;
+  placeholderContent?: string;
+  autoSendPlaceholder?: boolean;
   onDeliver?: () => void;
   onFail?: (error: unknown) => void;
 }): ReplyHandle {
@@ -15,15 +49,44 @@ export function createBotWsReplyHandle(params: {
     return streamId;
   };
 
-  let ackSent = false;
-  const ackTimer = setTimeout(() => {
-    if (ackSent) return;
-    ackSent = true;
-    params.client.replyStream(params.frame, resolveStreamId(), "⏳ 正在思考中...\n\n", false)
-      .catch(() => { /* ignore */ });
-  }, 4000);
+  const placeholderText = params.placeholderContent?.trim() || "⏳ 正在思考中...\n\n";
+  let streamSettled = false;
+  let placeholderInFlight = false;
+  let placeholderKeepalive: ReturnType<typeof setInterval> | undefined;
 
-  const cleanupTimer = () => clearTimeout(ackTimer);
+  const stopPlaceholderKeepalive = () => {
+    if (!placeholderKeepalive) return;
+    clearInterval(placeholderKeepalive);
+    placeholderKeepalive = undefined;
+  };
+
+  const settleStream = () => {
+    streamSettled = true;
+    stopPlaceholderKeepalive();
+  };
+
+  const sendPlaceholder = () => {
+    if (streamSettled || placeholderInFlight) return;
+    placeholderInFlight = true;
+    params.client.replyStream(params.frame, resolveStreamId(), placeholderText, false)
+      .catch((error) => {
+        if (!isTerminalReplyError(error)) {
+          return;
+        }
+        settleStream();
+        params.onFail?.(error);
+      })
+      .finally(() => {
+        placeholderInFlight = false;
+      });
+  };
+
+  if (params.autoSendPlaceholder !== false) {
+    sendPlaceholder();
+    placeholderKeepalive = setInterval(() => {
+      sendPlaceholder();
+    }, PLACEHOLDER_KEEPALIVE_MS);
+  }
 
   return {
     context: {
@@ -40,23 +103,35 @@ export function createBotWsReplyHandle(params: {
     },
     deliver: async (payload: ReplyPayload, info) => {
       if (payload.isReasoning) return;
-      
+
       const text = payload.text?.trim();
       if (!text) return;
 
-      if (!ackSent) {
-        cleanupTimer();
-        ackSent = true;
+      settleStream();
+      try {
+        await params.client.replyStream(params.frame, resolveStreamId(), text, info.kind === "final");
+      } catch (error) {
+        if (isTerminalReplyError(error)) {
+          params.onFail?.(error);
+          return;
+        }
+        throw error;
       }
-      
-      await params.client.replyStream(params.frame, resolveStreamId(), text, info.kind === "final");
       params.onDeliver?.();
     },
     fail: async (error: unknown) => {
-      cleanupTimer();
-      ackSent = true;
-      const message = error instanceof Error ? error.message : String(error);
-      await params.client.replyStream(params.frame, resolveStreamId(), `WeCom WS reply failed: ${message}`, true);
+      settleStream();
+      if (isTerminalReplyError(error)) {
+        params.onFail?.(error);
+        return;
+      }
+      const message = formatErrorMessage(error);
+      try {
+        await params.client.replyStream(params.frame, resolveStreamId(), `WeCom WS reply failed: ${message}`, true);
+      } catch (sendError) {
+        params.onFail?.(sendError);
+        return;
+      }
       params.onFail?.(error);
     },
   };

package/src/transport/bot-ws/sdk-adapter.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const sdkMockState = vi.hoisted(() => {
+  class MockWSClient {
+    readonly handlers = new Map<string, Array<(payload: any) => void>>();
+    readonly isConnected = true;
+    readonly replyStream = vi.fn().mockResolvedValue(undefined);
+
+    constructor(_options: unknown) {
+      sdkMockState.client = this;
+    }
+
+    on(event: string, handler: (payload: any) => void): void {
+      const current = this.handlers.get(event) ?? [];
+      current.push(handler);
+      this.handlers.set(event, current);
+    }
+
+    emit(event: string, payload: any): void {
+      for (const handler of this.handlers.get(event) ?? []) {
+        handler(payload);
+      }
+    }
+
+    connect(): void {}
+
+    disconnect(): void {}
+  }
+
+  return {
+    client: null as InstanceType<typeof MockWSClient> | null,
+    MockWSClient,
+  };
+});
+
+vi.mock("@wecom/aibot-node-sdk", () => ({
+  default: {
+    WSClient: sdkMockState.MockWSClient,
+  },
+  WSClient: sdkMockState.MockWSClient,
+  generateReqId: (prefix: string) => `${prefix}-1`,
+}));
+
+import { BotWsSdkAdapter } from "./sdk-adapter.js";
+
+const waitForAsyncCallbacks = async () => {
+  await Promise.resolve();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+};
+
+describe("BotWsSdkAdapter", () => {
+  const unhandledRejections: unknown[] = [];
+  const onUnhandledRejection = (reason: unknown) => {
+    unhandledRejections.push(reason);
+  };
+
+  afterEach(() => {
+    process.off("unhandledRejection", onUnhandledRejection);
+    unhandledRejections.length = 0;
+    sdkMockState.client = null;
+  });
+
+  it("contains frame handler rejections instead of leaking unhandled rejections", async () => {
+    process.on("unhandledRejection", onUnhandledRejection);
+
+    const runtime = {
+      account: {
+        accountId: "acc-1",
+        bot: {
+          wsConfigured: true,
+          ws: {
+            botId: "bot-1",
+            secret: "secret-1",
+          },
+          config: {},
+        },
+      },
+      handleEvent: vi.fn().mockRejectedValue(new Error("frame exploded")),
+      updateTransportSession: vi.fn(),
+      touchTransportSession: vi.fn(),
+      recordOperationalIssue: vi.fn(),
+    };
+    const log = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+
+    new BotWsSdkAdapter(runtime as any, log as any).start();
+
+    sdkMockState.client?.emit("message", {
+      cmd: "aibot_msg_callback",
+      headers: { req_id: "req-1" },
+      body: {
+        msgid: "msg-1",
+        msgtype: "text",
+        from: { userid: "user-1" },
+        text: { content: "hello" },
+      },
+    });
+
+    await waitForAsyncCallbacks();
+
+    expect(runtime.handleEvent).toHaveBeenCalledTimes(1);
+    expect(runtime.recordOperationalIssue).toHaveBeenCalledWith(
+      expect.objectContaining({
+        transport: "bot-ws",
+        category: "runtime-error",
+        messageId: "msg-1",
+        error: "frame exploded",
+      }),
+    );
+    expect(runtime.touchTransportSession).toHaveBeenCalledWith(
+      "bot-ws",
+      expect.objectContaining({
+        lastError: "frame exploded",
+      }),
+    );
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining("frame handler failed account=acc-1 reqId=req-1 message=frame exploded"),
+    );
+    expect(unhandledRejections).toHaveLength(0);
+  });
+});

package/src/transport/bot-ws/sdk-adapter.ts

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import AiBot, { type BaseMessage, type EventMessage, type WsFrame } from "@wecom/aibot-node-sdk";
 
 import type { RuntimeLogSink } from "../../types/index.js";
+import { registerBotWsPushHandle, unregisterBotWsPushHandle } from "../../app/index.js";
 import { mapBotWsFrameToInboundEvent } from "./inbound.js";
 import { createBotWsReplyHandle } from "./reply.js";
 import { createBotWsSessionSnapshot } from "./session.js";
@@ -38,6 +39,23 @@ export class BotWsSdkAdapter {
       },
     });
     this.client = client;
+    registerBotWsPushHandle(this.runtime.account.accountId, {
+      isConnected: () => client.isConnected,
+      sendMarkdown: async (chatId, content) => {
+        await client.sendMessage(chatId, {
+          msgtype: "markdown",
+          markdown: { content },
+        });
+        this.runtime.touchTransportSession("bot-ws", {
+          ownerId: this.ownerId,
+          running: true,
+          connected: client.isConnected,
+          authenticated: client.isConnected,
+          lastOutboundAt: Date.now(),
+          lastError: undefined,
+        });
+      },
+    });
 
     client.on("connected", () => {
       this.log.info?.(`[wecom-ws] connected account=${this.runtime.account.accountId}`);
@@ -131,6 +149,13 @@ export class BotWsSdkAdapter {
         client,
         frame,
         accountId: this.runtime.account.accountId,
+        placeholderContent: botAccount.config.streamPlaceholderContent,
+        autoSendPlaceholder:
+          event.inboundKind === "text" ||
+          event.inboundKind === "image" ||
+          event.inboundKind === "file" ||
+          event.inboundKind === "voice" ||
+          event.inboundKind === "mixed",
         onDeliver: () => {
           this.runtime.touchTransportSession("bot-ws", {
             ownerId: this.ownerId,
@@ -153,11 +178,41 @@ export class BotWsSdkAdapter {
       await this.runtime.handleEvent(event, replyHandle);
     };
 
+    const runHandleFrame = (frame: WsFrame<BaseMessage | EventMessage>) => {
+      void handleFrame(frame).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        this.log.error?.(
+          `[wecom-ws] frame handler failed account=${this.runtime.account.accountId} reqId=${frame.headers?.req_id ?? "n/a"} message=${message}`,
+        );
+        this.runtime.recordOperationalIssue({
+          transport: "bot-ws",
+          category: "runtime-error",
+          messageId: frame.body?.msgid,
+          raw: {
+            transport: "bot-ws",
+            command: frame.cmd,
+            headers: frame.headers,
+            body: frame.body,
+            envelopeType: "ws",
+          },
+          summary: `bot-ws frame handler crashed reqId=${frame.headers?.req_id ?? "n/a"}`,
+          error: message,
+        });
+        this.runtime.touchTransportSession("bot-ws", {
+          ownerId: this.ownerId,
+          running: client.isConnected,
+          connected: client.isConnected,
+          authenticated: client.isConnected,
+          lastError: message,
+        });
+      });
+    };
+
     client.on("message", (frame) => {
-      void handleFrame(frame);
+      runHandleFrame(frame);
     });
     client.on("event", (frame) => {
-      void handleFrame(frame);
+      runHandleFrame(frame);
     });
 
     client.connect();
@@ -165,6 +220,7 @@ export class BotWsSdkAdapter {
 
   stop(): void {
     this.log.info?.(`[wecom-ws] stop account=${this.runtime.account.accountId}`);
+    unregisterBotWsPushHandle(this.runtime.account.accountId);
     this.runtime.updateTransportSession(
       createBotWsSessionSnapshot({
         accountId: this.runtime.account.accountId,