@soimy/dingtalk 2.7.0 → 3.0.0

package/README.md

@@ -44,10 +44,70 @@ openclaw plugins install -l .
 2. 确保包含 `index.ts`, `openclaw.plugin.json` 和 `package.json`。
 3. 运行 `openclaw plugins list` 确认 `dingtalk` 已显示在列表中。
 
+### 安装后必做：配置插件信任白名单（`plugins.allow`）
+
+从 OpenClaw 新版本开始，如果发现了非内置插件且 `plugins.allow` 为空，会提示：
+
+```text
+[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load ...
+```
+
+这是一条安全告警（不是安装失败），建议显式写入你信任的插件 id。
+
+#### 步骤 1：确认插件 id
+
+本插件 id 固定为：`dingtalk`（定义于 `openclaw.plugin.json`）。
+
+也可用下面命令查看已发现插件：
+
+```bash
+openclaw plugins list
+```
+
+#### 步骤 2：在 `~/.openclaw/openclaw.json` 添加 `plugins.allow`
+
+```json5
+{
+  "plugins": {
+    "enabled": true,
+    "allow": ["dingtalk"]
+  }
+}
+```
+
+如果你还有其他已安装且需要启用的插件，请一并加入，例如：
+
+```json5
+{
+  "plugins": {
+    "allow": ["dingtalk", "telegram", "voice-call"]
+  }
+}
+```
+
+#### 步骤 3：重启 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+> 注意：如果你之前已经配置过 `plugins.allow`，但没有 `dingtalk`，那么插件不会被加载。请把 `dingtalk` 加入该列表。
+
 ## 更新
 
+`openclaw plugins update` 使用插件 id（不是 npm 包名），并且仅适用于 npm 安装来源。
+
+如果你是通过 npm 安装本插件：
+
+```bash
+openclaw plugins update dingtalk
 ```
-openclaw plugins update @soimy/dingtalk
+
+如果你是本地源码/链接安装（`openclaw plugins install -l .`），请在插件目录更新代码后重启 Gateway：
+
+```bash
+git pull
+openclaw gateway restart
 ```
 
 ## 配置
@@ -140,12 +200,17 @@ openclaw configure --section channels
 
 ### 方法 2：手动配置文件
 
-在 `~/.openclaw/openclaw.json` 的 `channels` 下添加（仅作参考，交互式配置会自动生成）：
+在 `~/.openclaw/openclaw.json` 中添加（仅作参考，交互式配置会自动生成）：
 
-> 只添加dingtalk部分，内容参考上文钉钉开发者配置指南
+> 至少包含 `plugins.allow` 和 `channels.dingtalk` 两部分，内容参考上文钉钉开发者配置指南
 
 ```json5
 {
+  "plugins": {
+    "enabled": true,
+    "allow": ["dingtalk"]
+  },
+
   ...
   "channels": {
     "telegram": { ... },
@@ -496,6 +561,37 @@ await finishAICard(card, finalText, log);
 - **src/types.ts**: 类型定义
 - **utils.ts**: 通用工具函数
 
+## 测试
+
+项目已基于 Vitest 初始化自动化测试，目录结构如下：
+
+```text
+tests/
+  unit/
+    sign.test.ts               # HmacSHA256 + Base64 签名测试
+    message-transform.test.ts  # 文本/Markdown 消息转换测试
+  integration/
+    send-lifecycle.test.ts     # 插件 outbound.sendText 生命周期适配测试
+```
+
+### 运行测试
+
+```bash
+# 安装依赖（pnpm）
+pnpm install
+
+# 运行全部测试
+pnpm test
+
+# 生成覆盖率报告（coverage/）
+pnpm test:coverage
+```
+
+### Mock 约束
+
+- 所有测试中的网络请求均通过 `vi.mock('axios')` 拦截，禁止真实调用钉钉 API。
+- 集成测试通过模块 mock 隔离 `openclaw/plugin-sdk`、`dingtalk-stream` 等外部依赖。
+
 ## 许可
 
 MIT

package/index.ts

@@ -1,12 +1,13 @@
-import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
-import { emptyPluginConfigSchema } from 'openclaw/plugin-sdk';
-import { dingtalkPlugin } from './src/channel';
-import { setDingTalkRuntime } from './src/runtime';
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { dingtalkPlugin } from "./src/channel";
+import { setDingTalkRuntime } from "./src/runtime";
+import type { DingtalkPluginModule } from "./src/types";
 
-const plugin = {
-  id: 'dingtalk',
-  name: 'DingTalk Channel',
-  description: 'DingTalk (钉钉) messaging channel via Stream mode',
+const plugin: DingtalkPluginModule = {
+  id: "dingtalk",
+  name: "DingTalk Channel",
+  description: "DingTalk (钉钉) messaging channel via Stream mode",
   configSchema: emptyPluginConfigSchema(),
   register(api: OpenClawPluginApi): void {
     setDingTalkRuntime(api.runtime);

package/package.json

@@ -1,39 +1,43 @@
 {
   "name": "@soimy/dingtalk",
-  "version": "2.7.0",
+  "version": "3.0.0",
   "description": "DingTalk (钉钉) channel plugin for OpenClaw",
-  "main": "index.ts",
-  "type": "module",
-  "files": [
-    "index.ts",
-    "src",
-    "openclaw.plugin.json",
-    "clawbot.plugin.json"
-  ],
-  "scripts": {
-    "type-check": "tsc --noEmit",
-    "lint": "eslint index.ts src/",
-    "lint:fix": "eslint --fix index.ts src/ && prettier --write index.ts src/"
-  },
   "keywords": [
+    "bot",
+    "channel",
     "clawdbot",
-    "openclaw",
     "dingtalk",
-    "channel",
+    "openclaw",
     "stream",
-    "钉钉",
-    "bot"
+    "钉钉"
   ],
-  "author": "YM Shen <soimy@163.com> (http://github.com/soimy)",
+  "homepage": "https://github.com/soimy/openclaw-channel-dingtalk",
   "license": "MIT",
+  "author": "YM Shen <soimy@163.com> (http://github.com/soimy)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/soimy/openclaw-channel-dingtalk.git"
   },
-  "homepage": "https://github.com/soimy/openclaw-channel-dingtalk",
+  "files": [
+    "index.ts",
+    "src/*.ts",
+    "openclaw.plugin.json",
+    "clawbot.plugin.json"
+  ],
+  "type": "module",
+  "main": "index.ts",
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "format": "oxfmt --write package.json tsconfig.json index.ts src/*.ts",
+    "format:check": "oxfmt --check package.json tsconfig.json index.ts src/*.ts",
+    "lint": "oxlint --type-aware index.ts src",
+    "lint:fix": "oxlint --type-aware --fix index.ts src && pnpm format",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc -p tsconfig.json"
   },
   "dependencies": {
     "axios": "^1.6.0",
@@ -43,12 +47,12 @@
   },
   "devDependencies": {
     "@types/node": "^25.2.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.0.0",
-    "eslint-config-prettier": "^9.0.0",
-    "prettier": "^3.0.0",
-    "typescript": "^5.3.0"
+    "@vitest/coverage-v8": "^3.2.4",
+    "oxfmt": "0.34.0",
+    "oxlint": "^1.49.0",
+    "oxlint-tsgolint": "^0.14.2",
+    "typescript": "^5.3.0",
+    "vitest": "^3.2.4"
   },
   "peerDependencies": {
     "openclaw": ">=2026.2.13"

package/src/access-control.ts

@@ -0,0 +1,55 @@
+export type NormalizedAllowFrom = {
+  entries: string[];
+  entriesLower: string[];
+  hasWildcard: boolean;
+  hasEntries: boolean;
+};
+
+/**
+ * Normalize allowFrom list:
+ * - trim whitespace
+ * - support "dingtalk:/dd:/ding:" prefixes
+ * - precompute lower-case list for case-insensitive checks
+ */
+export function normalizeAllowFrom(list?: Array<string>): NormalizedAllowFrom {
+  const entries = (list ?? []).map((value) => String(value).trim()).filter(Boolean);
+  const hasWildcard = entries.includes("*");
+  const normalized = entries
+    .filter((value) => value !== "*")
+    .map((value) => value.replace(/^(dingtalk|dd|ding):/i, ""));
+  const normalizedLower = normalized.map((value) => value.toLowerCase());
+  return {
+    entries: normalized,
+    entriesLower: normalizedLower,
+    hasWildcard,
+    hasEntries: entries.length > 0,
+  };
+}
+
+export function isSenderAllowed(params: {
+  allow: NormalizedAllowFrom;
+  senderId?: string;
+}): boolean {
+  const { allow, senderId } = params;
+  if (!allow.hasEntries) {
+    return true;
+  }
+  if (allow.hasWildcard) {
+    return true;
+  }
+  if (senderId && allow.entriesLower.includes(senderId.toLowerCase())) {
+    return true;
+  }
+  return false;
+}
+
+export function isSenderGroupAllowed(params: {
+  allow: NormalizedAllowFrom;
+  groupId?: string;
+}): boolean {
+  const { allow, groupId } = params;
+  if (groupId && allow.entriesLower.includes(groupId.toLowerCase())) {
+    return true;
+  }
+  return false;
+}

package/src/auth.ts

@@ -0,0 +1,47 @@
+import axios from "axios";
+import type { DingTalkConfig, Logger, TokenInfo } from "./types";
+import { retryWithBackoff } from "./utils";
+
+interface TokenCache {
+  accessToken: string;
+  expiry: number;
+}
+
+// Access Token cache - keyed by clientId for multi-account support.
+const accessTokenCache = new Map<string, TokenCache>();
+
+/**
+ * Get DingTalk access token with clientId-scoped cache + retry.
+ * Refreshes token one minute before expiry to avoid near-expiry failures.
+ */
+export async function getAccessToken(config: DingTalkConfig, log?: Logger): Promise<string> {
+  const cacheKey = config.clientId;
+  const now = Date.now();
+  const cached = accessTokenCache.get(cacheKey);
+
+  if (cached && cached.expiry > now + 60000) {
+    return cached.accessToken;
+  }
+
+  const token = await retryWithBackoff(
+    async () => {
+      const response = await axios.post<TokenInfo>(
+        "https://api.dingtalk.com/v1.0/oauth2/accessToken",
+        {
+          appKey: config.clientId,
+          appSecret: config.clientSecret,
+        },
+      );
+
+      accessTokenCache.set(cacheKey, {
+        accessToken: response.data.accessToken,
+        expiry: now + response.data.expireIn * 1000,
+      });
+
+      return response.data.accessToken;
+    },
+    { maxRetries: 3, log },
+  );
+
+  return token;
+}

package/src/card-service.ts

@@ -0,0 +1,338 @@
+import { randomUUID } from "node:crypto";
+import axios from "axios";
+import { getAccessToken } from "./auth";
+import { stripTargetPrefix } from "./config";
+import { resolveOriginalPeerId } from "./peer-id-registry";
+import type {
+  AICardInstance,
+  AICardStreamingRequest,
+  DingTalkConfig,
+  DingTalkInboundMessage,
+  Logger,
+} from "./types";
+import { AICardStatus } from "./types";
+
+const DINGTALK_API = "https://api.dingtalk.com";
+// Card cache TTL (1 hour) for terminal states.
+const CARD_CACHE_TTL = 60 * 60 * 1000;
+// Thinking/tool stream snippets are truncated to keep card updates compact.
+const THINKING_TRUNCATE_LENGTH = 500;
+
+// AI Card instance cache for streaming updates.
+const aiCardInstances = new Map<string, AICardInstance>();
+// accountId:conversationId -> cardInstanceId
+const activeCardsByTarget = new Map<string, string>();
+
+// Helper to identify card terminal states.
+export function isCardInTerminalState(state: string): boolean {
+  return state === AICardStatus.FINISHED || state === AICardStatus.FAILED;
+}
+
+export function getCardById(cardId: string): AICardInstance | undefined {
+  return aiCardInstances.get(cardId);
+}
+
+export function getActiveCardIdByTarget(targetKey: string): string | undefined {
+  return activeCardsByTarget.get(targetKey);
+}
+
+export function deleteActiveCardByTarget(targetKey: string): void {
+  activeCardsByTarget.delete(targetKey);
+}
+
+export function cleanupCardCache(): void {
+  const now = Date.now();
+  // Clean terminal cards only; active cards stay in cache to support streaming continuity.
+  for (const [cardInstanceId, instance] of aiCardInstances.entries()) {
+    if (isCardInTerminalState(instance.state) && now - instance.lastUpdated > CARD_CACHE_TTL) {
+      aiCardInstances.delete(cardInstanceId);
+      for (const [targetKey, mappedCardId] of activeCardsByTarget.entries()) {
+        if (mappedCardId === cardInstanceId) {
+          activeCardsByTarget.delete(targetKey);
+          break;
+        }
+      }
+    }
+  }
+}
+
+export function formatContentForCard(content: string, type: "thinking" | "tool"): string {
+  if (!content) {
+    return "";
+  }
+
+  // Truncate to configured length and keep a visual ellipsis when truncated.
+  const truncated =
+    content.slice(0, THINKING_TRUNCATE_LENGTH) +
+    (content.length > THINKING_TRUNCATE_LENGTH ? "…" : "");
+
+  // Quote each line to improve readability in markdown card content.
+  const quotedLines = truncated
+    .split("\n")
+    .map((line) => line.replace(/^_(?=[^ ])/, "*").replace(/(?<=[^ ])_(?=$)/, "*"))
+    .map((line) => `> ${line}`)
+    .join("\n");
+
+  const emoji = type === "thinking" ? "🤔" : "🛠️";
+  const label = type === "thinking" ? "思考中" : "工具执行";
+
+  return `${emoji} **${label}**\n${quotedLines}`;
+}
+
+async function sendTemplateMismatchNotification(
+  card: AICardInstance,
+  text: string,
+  log?: Logger,
+): Promise<void> {
+  const config = card.config;
+  if (!config) {
+    return;
+  }
+  try {
+    const token = await getAccessToken(config, log);
+    const { targetId, isExplicitUser } = stripTargetPrefix(card.conversationId);
+    const resolvedTarget = resolveOriginalPeerId(targetId);
+    const isGroup = !isExplicitUser && resolvedTarget.startsWith("cid");
+    const url = isGroup
+      ? "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
+      : "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend";
+
+    // Direct markdown fallback notification to user/group, without re-entering sendMessage card flow.
+    const payload: Record<string, unknown> = {
+      robotCode: config.robotCode || config.clientId,
+      msgKey: "sampleMarkdown",
+      msgParam: JSON.stringify({ title: "OpenClaw 提醒", text }),
+    };
+
+    if (isGroup) {
+      payload.openConversationId = resolvedTarget;
+    } else {
+      payload.userIds = [resolvedTarget];
+    }
+
+    await axios({
+      url,
+      method: "POST",
+      data: payload,
+      headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+    });
+  } catch (sendErr: any) {
+    log?.warn?.(`[DingTalk][AICard] Failed to send error notification to user: ${sendErr.message}`);
+  }
+}
+
+export async function createAICard(
+  config: DingTalkConfig,
+  conversationId: string,
+  data: DingTalkInboundMessage,
+  accountId: string,
+  log?: Logger,
+): Promise<AICardInstance | null> {
+  try {
+    const token = await getAccessToken(config, log);
+    // Use randomUUID to avoid collisions across workers/restarts.
+    const cardInstanceId = `card_${randomUUID()}`;
+
+    log?.info?.(`[DingTalk][AICard] Creating and delivering card outTrackId=${cardInstanceId}`);
+    log?.debug?.(
+      `[DingTalk][AICard] conversationType=${data.conversationType}, conversationId=${conversationId}`,
+    );
+
+    const isGroup = conversationId.startsWith("cid");
+
+    if (!config.cardTemplateId) {
+      throw new Error("DingTalk cardTemplateId is not configured.");
+    }
+
+    // DingTalk createAndDeliver API payload.
+    const createAndDeliverBody = {
+      cardTemplateId: config.cardTemplateId,
+      outTrackId: cardInstanceId,
+      cardData: {
+        cardParamMap: {},
+      },
+      callbackType: "STREAM",
+      imGroupOpenSpaceModel: { supportForward: true },
+      imRobotOpenSpaceModel: { supportForward: true },
+      openSpaceId: isGroup
+        ? `dtv1.card//IM_GROUP.${conversationId}`
+        : `dtv1.card//IM_ROBOT.${conversationId}`,
+      userIdType: 1,
+      imGroupOpenDeliverModel: isGroup
+        ? { robotCode: config.robotCode || config.clientId }
+        : undefined,
+      imRobotOpenDeliverModel: !isGroup ? { spaceType: "IM_ROBOT" } : undefined,
+    };
+
+    if (isGroup && !config.robotCode) {
+      log?.warn?.(
+        "[DingTalk][AICard] robotCode not configured, using clientId as fallback. " +
+          "For best compatibility, set robotCode explicitly in config.",
+      );
+    }
+
+    log?.debug?.(
+      `[DingTalk][AICard] POST /v1.0/card/instances/createAndDeliver body=${JSON.stringify(createAndDeliverBody)}`,
+    );
+    const resp = await axios.post(
+      `${DINGTALK_API}/v1.0/card/instances/createAndDeliver`,
+      createAndDeliverBody,
+      {
+        headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
+      },
+    );
+    log?.debug?.(
+      `[DingTalk][AICard] CreateAndDeliver response: status=${resp.status} data=${JSON.stringify(resp.data)}`,
+    );
+
+    // Cache the AI card instance with config reference for token refresh/recovery.
+    const aiCardInstance: AICardInstance = {
+      cardInstanceId,
+      accessToken: token,
+      conversationId,
+      createdAt: Date.now(),
+      lastUpdated: Date.now(),
+      state: AICardStatus.PROCESSING,
+      config,
+    };
+    aiCardInstances.set(cardInstanceId, aiCardInstance);
+
+    const targetKey = `${accountId}:${conversationId}`;
+    activeCardsByTarget.set(targetKey, cardInstanceId);
+    log?.debug?.(
+      `[DingTalk][AICard] Registered active card mapping: ${targetKey} -> ${cardInstanceId}`,
+    );
+
+    return aiCardInstance;
+  } catch (err: any) {
+    log?.error?.(`[DingTalk][AICard] Create failed: ${err.message}`);
+    if (err.response) {
+      log?.error?.(
+        `[DingTalk][AICard] Error response: status=${err.response.status} data=${JSON.stringify(err.response.data)}`,
+      );
+    }
+    return null;
+  }
+}
+
+export async function streamAICard(
+  card: AICardInstance,
+  content: string,
+  finished: boolean = false,
+  log?: Logger,
+): Promise<void> {
+  // Refresh token defensively before DingTalk 2h token horizon.
+  const tokenAge = Date.now() - card.createdAt;
+  const tokenRefreshThreshold = 90 * 60 * 1000;
+
+  if (tokenAge > tokenRefreshThreshold && card.config) {
+    log?.debug?.("[DingTalk][AICard] Token age exceeds threshold, refreshing...");
+    try {
+      card.accessToken = await getAccessToken(card.config, log);
+      log?.debug?.("[DingTalk][AICard] Token refreshed successfully");
+    } catch (err: any) {
+      log?.warn?.(`[DingTalk][AICard] Failed to refresh token: ${err.message}`);
+    }
+  }
+
+  // Always use full replacement to make client rendering deterministic.
+  const streamBody: AICardStreamingRequest = {
+    outTrackId: card.cardInstanceId,
+    guid: randomUUID(),
+    key: card.config?.cardTemplateKey || "content",
+    content: content,
+    isFull: true,
+    isFinalize: finished,
+    isError: false,
+  };
+
+  log?.debug?.(
+    `[DingTalk][AICard] PUT /v1.0/card/streaming contentLen=${content.length} isFull=true isFinalize=${finished} guid=${streamBody.guid} payload=${JSON.stringify(streamBody)}`,
+  );
+
+  try {
+    const streamResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, {
+      headers: {
+        "x-acs-dingtalk-access-token": card.accessToken,
+        "Content-Type": "application/json",
+      },
+    });
+    log?.debug?.(
+      `[DingTalk][AICard] Streaming response: status=${streamResp.status}, data=${JSON.stringify(streamResp.data)}`,
+    );
+
+    card.lastUpdated = Date.now();
+    if (finished) {
+      card.state = AICardStatus.FINISHED;
+    } else if (card.state === AICardStatus.PROCESSING) {
+      card.state = AICardStatus.INPUTING;
+    }
+  } catch (err: any) {
+    // 500 unknownError usually means cardTemplateKey mismatch with template variable names.
+    if (err.response?.status === 500 && err.response?.data?.code === "unknownError") {
+      const usedKey = streamBody.key;
+      const cardTemplateId = card.config?.cardTemplateId || "(unknown)";
+      const errorMsg =
+        `⚠️ **[DingTalk] AI Card 串流更新失败 (500 unknownError)**\n\n` +
+        `这通常是因为 \`cardTemplateKey\` (当前值: \`${usedKey}\`) 与钉钉卡片模板 \`${cardTemplateId}\` 中定义的正文变量名不匹配。\n\n` +
+        `**建议操作**：\n` +
+        `1. 前往钉钉开发者后台检查该模板的“变量管理”\n` +
+        `2. 确保配置中的 \`cardTemplateKey\` 与模板中用于显示内容的字段变量名完全一致\n\n` +
+        `*注意：当前及后续消息将自动转为 Markdown 发送，直到问题修复。*\n` +
+        `*参考文档: https://github.com/soimy/openclaw-channel-dingtalk/blob/main/README.md#3-%E5%BB%BA%E7%AB%8B%E5%8D%A1%E7%89%87%E6%A8%A1%E6%9D%BF%E5%8F%AF%E9%80%89`;
+
+      log?.error?.(
+        `[DingTalk][AICard] Streaming failed with 500 unknownError. Key: ${usedKey}, Template: ${cardTemplateId}. ` +
+          `Verify that "cardTemplateKey" matches the content field variable name in your card template.`,
+      );
+
+      card.state = AICardStatus.FAILED;
+      card.lastUpdated = Date.now();
+      await sendTemplateMismatchNotification(card, errorMsg, log);
+      throw err;
+    }
+
+    // Retry once on 401 with refreshed token.
+    if (err.response?.status === 401 && card.config) {
+      log?.warn?.("[DingTalk][AICard] Received 401 error, attempting token refresh and retry...");
+      try {
+        card.accessToken = await getAccessToken(card.config, log);
+        const retryResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, {
+          headers: {
+            "x-acs-dingtalk-access-token": card.accessToken,
+            "Content-Type": "application/json",
+          },
+        });
+        log?.debug?.(
+          `[DingTalk][AICard] Retry after token refresh succeeded: status=${retryResp.status}`,
+        );
+        card.lastUpdated = Date.now();
+        if (finished) {
+          card.state = AICardStatus.FINISHED;
+        } else if (card.state === AICardStatus.PROCESSING) {
+          card.state = AICardStatus.INPUTING;
+        }
+        return;
+      } catch (retryErr: any) {
+        log?.error?.(`[DingTalk][AICard] Retry after token refresh failed: ${retryErr.message}`);
+      }
+    }
+
+    card.state = AICardStatus.FAILED;
+    card.lastUpdated = Date.now();
+    log?.error?.(
+      `[DingTalk][AICard] Streaming update failed: ${err.message}, resp=${JSON.stringify(err.response?.data)}`,
+    );
+    throw err;
+  }
+}
+
+export async function finishAICard(
+  card: AICardInstance,
+  content: string,
+  log?: Logger,
+): Promise<void> {
+  log?.debug?.(`[DingTalk][AICard] Starting finish, final content length=${content.length}`);
+  // Finalize by streaming one last full payload with isFinalize=true.
+  await streamAICard(card, content, true, log);
+}