botmux 3.7.1 → 3.8.0

package/dist/im/lark/invite-command.js

@@ -0,0 +1,239 @@
+/**
+ * 拉 bot 进群元命令：`@bot /invite @目标bot [@目标bot2 ...]`，也支持
+ * `@bot /invite --app cli_xxx（可多个）` 直接按 app_id 拉任意飞书应用。
+ *
+ * 与 /grant 同款拦截模型（在 dispatcher 路由/spawn 之前处理，见 event-dispatcher）：
+ *  - 必须明确 @ 本 bot 才执行（多 bot 群防重复处理）——执行方（inviter）必须本身
+ *    在群内，飞书要求 inviter 是群成员，本 bot 处理这条消息天然满足；
+ *  - 仅 owner 可用（对齐 /grant 的权限模型）；
+ *  - 命令词之后的 @ 才是目标（共享 mention-targets.ts 的位置解析）。
+ *
+ * 目标 mention → larkAppId 的解析不走群成员表（目标恰恰不在群里），改查
+ * 部署级共享花名册 bots-info.json（每个 daemon 启动时 merge 写入），按显示名
+ * 唯一匹配（大小写不敏感，与 /group 的 knownBotNames 判定同款）；重名 / 查无
+ * 时按目标报错，并提示用 --app 直通。已在群内的目标（live 群 bot 成员表能
+ * 对上的）跳过并报「已在群内」，幂等。
+ *
+ * 拉人走 services/groups-store.ts 的 addBotToChat（proxy=本 bot），与 /group、
+ * dashboard groups 面板、vc-agent 共用同一封装；批量失败时回退逐个拉（镜像
+ * group-creator 的批处理回退）。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getOwnerOpenId, getBotOpenId } from '../../bot-registry.js';
+import { config } from '../../config.js';
+import { isBotMentioned, extractMessageTextForRouting } from './event-dispatcher.js';
+import { stripLeadingMentions } from './message-parser.js';
+import { addBotToChat } from '../../services/groups-store.js';
+import { listChatBotMembers, replyMessage } from './client.js';
+import { localeForBot, t } from '../../i18n/index.js';
+import { logger } from '../../utils/logger.js';
+import { parseTargetsAfterCommand, isCommandTargetOnly, stripAllMentions } from './mention-targets.js';
+const INVITE_CMD_PATTERN = /\/invite\b/i;
+/** app_id 的合法形状（飞书自建/商店应用均为 cli_ 前缀）。 */
+const APP_ID_PATTERN = /^cli_[A-Za-z0-9]+$/;
+/** 飞书 chatMembers.create 的 id_list 上限很小（实测 >5 即 400，见 group-creator），按 5 一批。 */
+const INVITE_BATCH_SIZE = 5;
+/** 读部署共享花名册 bots-info.json；文件缺失/损坏按空花名册处理（名字解析全部走不通，提示 --app）。 */
+export function readBotsInfoEntries() {
+    try {
+        const p = join(config.session.dataDir, 'bots-info.json');
+        if (!existsSync(p))
+            return [];
+        const raw = JSON.parse(readFileSync(p, 'utf-8'));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((e) => typeof e?.larkAppId === 'string' && e.larkAppId);
+    }
+    catch {
+        return [];
+    }
+}
+/** 从已 stripLeadingMentions 的命令文本解析 --app 参数。 */
+export function parseInviteArgs(text, mentions) {
+    // 先剥 mention 显示名（避免 @名字 里的空格干扰 token 切分），再去命令词。
+    const body = stripAllMentions(text, mentions).replace(INVITE_CMD_PATTERN, ' ');
+    const appIds = [];
+    const badAppTokens = [];
+    const leftoverTokens = [];
+    const tokens = body.split(/\s+/).filter(Boolean);
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        const inline = /^--app=(\S+)$/.exec(tok);
+        if (inline) {
+            (APP_ID_PATTERN.test(inline[1]) ? appIds : badAppTokens).push(inline[1]);
+            continue;
+        }
+        if (tok === '--app') {
+            const next = tokens[++i];
+            if (next === undefined) {
+                badAppTokens.push('');
+                continue;
+            }
+            (APP_ID_PATTERN.test(next) ? appIds : badAppTokens).push(next);
+            continue;
+        }
+        leftoverTokens.push(tok);
+    }
+    return { appIds: [...new Set(appIds)], badAppTokens, leftover: leftoverTokens.join(' ') };
+}
+/** 批量拉人；整批全失败且 >1 个时回退逐个拉（镜像 group-creator 的批处理回退）。 */
+async function addBotsResilient(larkAppId, chatId, ids) {
+    let results = [];
+    for (let i = 0; i < ids.length; i += INVITE_BATCH_SIZE) {
+        const batch = ids.slice(i, i + INVITE_BATCH_SIZE);
+        let r = await addBotToChat(larkAppId, chatId, batch);
+        if (batch.length > 1 && r.every(x => !x.ok)) {
+            // 整批失败可能是单个坏 id 拖累全批 → 逐个隔离重试，让好 id 落进去。
+            const perId = [];
+            for (const id of batch)
+                perId.push(...await addBotToChat(larkAppId, chatId, [id]));
+            r = perId;
+        }
+        results.push(...r);
+    }
+    return results;
+}
+/** 返回 true 表示已拦截（不再进入路由/spawn）。 */
+export async function tryHandleInviteCommand(larkAppId, message, senderOpenId) {
+    const rawText = extractMessageTextForRouting(message);
+    if (!rawText)
+        return false;
+    // 先 strip 掉开头的 @<mention>（含本 bot），否则 `@bot /invite @x` 匹配不到命令词。
+    const text = stripLeadingMentions(rawText.trim(), message?.mentions ?? []);
+    if (!/^\/invite(\s|$)/i.test(text))
+        return false;
+    const myOpenId = getBotOpenId(larkAppId);
+    const messageId = message.message_id;
+    const chatId = message.chat_id;
+    const loc = localeForBot(larkAppId);
+    const reply = (key, params) => replyMessage(larkAppId, messageId, t(key, params, loc))
+        .catch(err => logger.debug(`invite ${key} reply failed: ${err}`));
+    // 本 bot 只是作为 /invite 的【目标】被 @（`@OperatorBot /invite @ThisBot`）→ 命令属于
+    // 前导 @ 的操作 bot，本 bot 必须静默放手（同 /grant 的 target-only 守卫）。传 larkAppId
+    // 让 guard 也认 app_id 形态的本 bot @（群外/协作 bot 常以 app_id 被 @，只认 open_id 会漏判）。
+    if (isCommandTargetOnly(message, myOpenId, INVITE_CMD_PATTERN, larkAppId)) {
+        logger.debug(`[invite:${larkAppId}] ignoring /invite where this bot is only a target`);
+        return true;
+    }
+    // 私聊拉不了成员。必须在 isBotMentioned 选举门之前：DM 里没有群成员表、用户
+    // @ 不出本 bot，放选举门后面这条提示永远不可达，用户只会看到沉默。
+    if (message?.chat_type === 'p2p') {
+        await reply('cmd.invite.p2p');
+        return true;
+    }
+    // 多 bot 群：必须明确 @ 当前 bot 才由本 daemon 处理；否则吞掉（不喂 CLI）。
+    if (!isBotMentioned(larkAppId, message, senderOpenId))
+        return true;
+    // owner 强闸门（对齐 /grant）。
+    const owner = getOwnerOpenId(larkAppId);
+    if (!senderOpenId || senderOpenId !== owner) {
+        await reply('cmd.invite.owner_only');
+        return true;
+    }
+    if (!chatId) {
+        await reply('cmd.invite.usage');
+        return true;
+    }
+    const mentionTargets = parseTargetsAfterCommand(message, myOpenId, INVITE_CMD_PATTERN);
+    const args = parseInviteArgs(text, message?.mentions ?? []);
+    if (args.badAppTokens.length > 0 || args.leftover) {
+        await reply('cmd.invite.usage');
+        return true;
+    }
+    if (mentionTargets.length === 0 && args.appIds.length === 0) {
+        await reply('cmd.invite.usage');
+        return true;
+    }
+    // live 群 bot 成员表：already-in-chat 判定的权威源。拿不到就降级为空表——
+    // 飞书 API 自身对重复拉人也是幂等报错，不至于出错事（与 /group 对 listChatBotMembers
+    // 的容错一致）。
+    let roster = [];
+    try {
+        roster = await listChatBotMembers(larkAppId, chatId);
+    }
+    catch (e) {
+        logger.warn(`[invite:${larkAppId}] failed to list chat bot members (already-in-chat detection degraded): ${e?.message ?? e}`);
+    }
+    const rosterOpenIds = new Set(roster.map(m => m.openId));
+    const rosterAppIds = new Set(roster.map(m => m.larkAppId).filter(Boolean));
+    const rosterNameById = new Map(roster.filter(m => m.larkAppId).map(m => [m.larkAppId, m.displayName || m.name || m.larkAppId]));
+    const botsInfo = readBotsInfoEntries();
+    const byLowerName = new Map();
+    for (const e of botsInfo) {
+        const k = e.botName?.toLowerCase();
+        if (!k)
+            continue;
+        (byLowerName.get(k) ?? byLowerName.set(k, []).get(k)).push(e);
+    }
+    const nameOf = (appId) => botsInfo.find(e => e.larkAppId === appId)?.botName ?? rosterNameById.get(appId) ?? appId;
+    const toInvite = [];
+    const already = [];
+    const unresolved = [];
+    const ambiguous = [];
+    for (const tgt of mentionTargets) {
+        // 已在群内：open_id 命中 live 成员表即跳过（app_id 形态目标无 open_id，靠下方 appId 分支的 rosterAppIds 判定）。
+        if (tgt.openId && rosterOpenIds.has(tgt.openId)) {
+            already.push(tgt.name);
+            continue;
+        }
+        // 目标 mention 自带 app_id（飞书对「群外 bot」的 @ 形态）→ app_id 就是待拉 id，
+        // 直接用，跳过名字→花名册解析（更可靠，规避重名/查无）。
+        if (tgt.appId) {
+            if (tgt.appId === larkAppId || rosterAppIds.has(tgt.appId))
+                already.push(tgt.name);
+            else if (!toInvite.includes(tgt.appId))
+                toInvite.push(tgt.appId);
+            continue;
+        }
+        // 仅有 open_id（无 app_id）：按显示名查部署花名册解析出 app_id。
+        const candidates = tgt.name ? (byLowerName.get(tgt.name.toLowerCase()) ?? []) : [];
+        if (candidates.length === 1) {
+            const appId = candidates[0].larkAppId;
+            if (appId === larkAppId || rosterAppIds.has(appId))
+                already.push(tgt.name);
+            else if (!toInvite.includes(appId))
+                toInvite.push(appId);
+        }
+        else if (candidates.length > 1) {
+            ambiguous.push(t('cmd.invite.ambiguous_item', { name: tgt.name, apps: candidates.map(c => c.larkAppId).join('、') }, loc));
+        }
+        else {
+            unresolved.push(tgt.name || tgt.openId);
+        }
+    }
+    for (const appId of args.appIds) {
+        if (appId === larkAppId || rosterAppIds.has(appId))
+            already.push(nameOf(appId));
+        else if (!toInvite.includes(appId))
+            toInvite.push(appId);
+    }
+    const added = [];
+    const failed = [];
+    if (toInvite.length > 0) {
+        const results = await addBotsResilient(larkAppId, chatId, toInvite);
+        for (const r of results) {
+            if (r.ok)
+                added.push(nameOf(r.id));
+            else
+                failed.push(t('cmd.invite.failed_item', { name: nameOf(r.id), reason: r.error ?? 'unknown' }, loc));
+        }
+    }
+    const sections = [];
+    if (added.length)
+        sections.push(t('cmd.invite.ok', { names: added.join('、') }, loc));
+    if (already.length)
+        sections.push(t('cmd.invite.already', { names: [...new Set(already)].join('、') }, loc));
+    if (unresolved.length)
+        sections.push(t('cmd.invite.unresolved', { names: [...new Set(unresolved)].join('、') }, loc));
+    if (ambiguous.length)
+        sections.push(...ambiguous);
+    if (failed.length)
+        sections.push(...failed);
+    const body = sections.join('\n') || t('cmd.invite.usage', undefined, loc);
+    await replyMessage(larkAppId, messageId, toInvite.length > 0 || already.length > 0 ? t('cmd.invite.header', undefined, loc) + '\n' + body : body).catch(err => logger.debug(`invite result reply failed: ${err}`));
+    logger.info(`[invite:${larkAppId}] chat=${chatId} added=[${added}] already=[${already}] ` +
+        `unresolved=[${unresolved}] ambiguous=${ambiguous.length} failed=[${failed}]`);
+    return true;
+}
+//# sourceMappingURL=invite-command.js.map

package/dist/im/lark/invite-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite-command.js","sourceRoot":"","sources":["../../../src/im/lark/invite-command.ts"],"names":[],"mappings":"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"}

package/dist/im/lark/md-card.d.ts

@@ -19,7 +19,41 @@
  * the outer block (CommonMark spec).
  */
 import { type Locale } from '../../i18n/index.js';
+import { REPLY_CARD_FOOTER_ELEMENT_ID } from './reply-card-footer-signature.js';
+export { REPLY_CARD_FOOTER_MARKER } from './reply-card-footer-signature.js';
 export type LocalHomeLinkMode = 'filesystem' | 'lexical' | 'disabled';
+/** Native usage facts rendered in a Bot reply-card footer. Context is the
+ * latest context-window measurement; tokens are cumulative for the Session.
+ * Missing facts are omitted independently and must never be estimated. */
+export interface CardUsageSnapshot {
+    context: {
+        usedTokens: number;
+        windowTokens?: number;
+        percentUsed?: number;
+    } | null;
+    tokens: {
+        in: number;
+        out: number;
+    } | null;
+    /** Delta for the latest user turn (small, matches the CLI TUI's per-turn
+     *  ↑↓). Null for dialects without per-turn tracking. Rendered on the live
+     *  streaming card; the reply-card footer stays compact and omits it. */
+    turnTokens?: {
+        in: number;
+        out: number;
+    } | null;
+}
+export interface ReplyCardFooter {
+    /** Fully wrapped markdown content, reusable inside the voice-button row. */
+    content: string;
+    /** Standalone footer element used by ordinary reply cards. */
+    element: {
+        tag: 'markdown';
+        element_id: typeof REPLY_CARD_FOOTER_ELEMENT_ID;
+        text_size: 'notation_small_v2';
+        content: string;
+    };
+}
 /**
  * Restore the leading slash when a model emits the current user's home path
  * as a relative Markdown link destination. Codex file links are normally
@@ -41,11 +75,38 @@ export declare const DEFAULT_BRAND_LABEL = "[botmux](https://github.com/deepcold
  * `brandLabel` (see {@link resolveBrandLabel}):
  *   • `undefined` (unset)  → the default botmux link
  *   • `''` / whitespace    → `null` (brand suppressed)
- *   • any other string     → returned verbatim (markdown allowed)
+ *   • any other string     → one trimmed line (markdown allowed)
  * Returning `null` lets callers drop the brand — and, when there's also no
  * recipient, the whole footer (HR included) — so an empty brand reads clean.
  */
 export declare function brandFooterSegment(brand: string | undefined): string | null;
+/** Format usage as one segment shared by reply-card footers and the live
+ * streaming card. The caller supplies native facts; this module only formats
+ * them and never infers a context window or token count. Returns null when no
+ * valid native metric is available.
+ *
+ * `variant`:
+ *   - `'footer'` (default): minimal — context only. Reply-card footers are
+ *     cramped (brand · usage · 发送给), so the large cumulative token string is
+ *     dropped here (it lives on the streaming card / usage ledger). 上下文占用
+ *     is the one glanceable "how full am I" metric worth keeping.
+ *   - `'streaming'`: rich — context + `本轮 ↑X ↓Y`(per-turn delta, matches the
+ *     CLI TUI) + `累计 ↑A ↓B`(session total). The live card has room and
+ *     refreshes during execution. */
+export declare function cardUsageFooterSegment(usage: CardUsageSnapshot, locale?: Locale, variant?: 'footer' | 'streaming'): string | null;
+/** Build the one canonical footer shared by all Bot Session reply cards.
+ * Ordering, i18n, the parser marker, grey styling, and recipient rendering live
+ * here so direct sends and daemon fallbacks cannot drift apart. */
+export declare function buildReplyCardFooter(opts: {
+    brand?: string;
+    recipientOpenIds?: readonly string[];
+    usage?: CardUsageSnapshot;
+    locale?: Locale;
+}): ReplyCardFooter | null;
+/** Clone a caller-supplied schema-2 card and append the canonical reply
+ * footer. Returns null for cards without a v2 `body.elements` array or when a
+ * caller-owned element already occupies the globally unique footer id. */
+export declare function appendReplyCardFooterToV2Card(card: Record<string, unknown>, opts: Parameters<typeof buildReplyCardFooter>[0]): Record<string, unknown> | null;
 /** Normalize source bytes that must be settled before the card is rendered. */
 export declare function prepareCardMarkdown(input: string, cwd?: string, localHomeLinkMode?: LocalHomeLinkMode): string;
 /**
@@ -98,10 +159,10 @@ export declare function hasMarkdown(text: string): boolean;
  *
  * `brand` is the sending bot's configured `brandLabel` (see
  * {@link brandFooterSegment}): unset → default botmux link, `''` → brand
- * suppressed, else custom. When brand and recipient are both absent the whole
- * footer (HR included) is omitted.
+ * suppressed, else custom. When brand, usage, and recipient are all absent the
+ * whole footer (HR included) is omitted.
  */
-export declare function buildMarkdownCard(md: string, recipientOpenId?: string, brand?: string, locale?: Locale, workingDir?: string, localHomeLinkMode?: LocalHomeLinkMode): string;
+export declare function buildMarkdownCard(md: string, recipientOpenId?: string, brand?: string, locale?: Locale, workingDir?: string, localHomeLinkMode?: LocalHomeLinkMode, usage?: CardUsageSnapshot): string;
 /**
  * Build a contextual reply card: a title strip, an optional quoted user
  * prompt, and the assistant body rendered through the same markdown-it
@@ -126,5 +187,6 @@ export declare function buildContextualReplyCard(opts: {
     locale?: Locale;
     workingDir?: string;
     localHomeLinkMode?: LocalHomeLinkMode;
+    usage?: CardUsageSnapshot;
 }): string;
 //# sourceMappingURL=md-card.d.ts.map

package/dist/im/lark/md-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"md-card.d.ts","sourceRoot":"","sources":["../../../src/im/lark/md-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,OAAO,EAAK,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAKrD,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC;AA4FtE;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,SAAY,EACnB,GAAG,SAAgB,EACnB,UAAU,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAoB,EAClD,IAAI,GAAE,iBAAgC,GACrC,MAAM,CAiFR;AAED,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,kDAAkD,CAAC;AAEnF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG3E;AAuGD,+EAA+E;AAC/E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,GAAG,SAAgB,EACnB,iBAAiB,GAAE,iBAAgC,GAClD,MAAM,CAGR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,GAAG,SAAgB,EACnB,iBAAiB,GAAE,iBAAgC,GAClD,GAAG,EAAE,CAeP;AA0KD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EAAE,EACnB,GAAG,SAAgB,EACnB,iBAAiB,GAAE,iBAAgC,GAClD,GAAG,EAAE,CAiCP;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAcjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,EACV,eAAe,CAAC,EAAE,MAAM,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,iBAAiB,GAAE,iBAAgC,GAClD,MAAM,CAoBR;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC,GAAG,MAAM,CAyDT"}
+{"version":3,"file":"md-card.d.ts","sourceRoot":"","sources":["../../../src/im/lark/md-card.ts"],"names":[],"mappings":"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"}

package/dist/im/lark/md-card.js

@@ -24,6 +24,8 @@ import { randomBytes } from 'node:crypto';
 import { resolve } from 'node:path';
 import MarkdownIt from 'markdown-it';
 import { t } from '../../i18n/index.js';
+import { REPLY_CARD_FOOTER_ELEMENT_ID, REPLY_CARD_FOOTER_MARKER, } from './reply-card-footer-signature.js';
+export { REPLY_CARD_FOOTER_MARKER } from './reply-card-footer-signature.js';
 const md = new MarkdownIt({ html: false, linkify: false, breaks: false });
 const MAX_LOCAL_HOME_LINK_REPAIRS = 256;
 function escapeRegExp(value) {
@@ -197,14 +199,190 @@ export const DEFAULT_BRAND_LABEL = '[botmux](https://github.com/deepcoldy/botmux
  * `brandLabel` (see {@link resolveBrandLabel}):
  *   • `undefined` (unset)  → the default botmux link
  *   • `''` / whitespace    → `null` (brand suppressed)
- *   • any other string     → returned verbatim (markdown allowed)
+ *   • any other string     → one trimmed line (markdown allowed)
  * Returning `null` lets callers drop the brand — and, when there's also no
  * recipient, the whole footer (HR included) — so an empty brand reads clean.
  */
 export function brandFooterSegment(brand) {
     if (brand === undefined)
         return DEFAULT_BRAND_LABEL;
-    return brand.trim() ? brand : null;
+    const normalized = brand
+        .trim()
+        .replace(/[ \t]*(?:\r\n?|\n|\u2028|\u2029)+[ \t]*/g, ' ');
+    return normalized || null;
+}
+function compactTokenCount(value) {
+    const units = [
+        { threshold: 1_000_000_000, suffix: 'B' },
+        { threshold: 1_000_000, suffix: 'M' },
+        { threshold: 1_000, suffix: 'K' },
+    ];
+    let unitIndex = units.findIndex(candidate => value >= candidate.threshold);
+    if (unitIndex < 0)
+        return Math.round(value).toString();
+    let unit = units[unitIndex];
+    let scaled = value / unit.threshold;
+    // Avoid boundary artifacts such as 1000K/1000M after one-decimal rounding.
+    if (unitIndex > 0 && Number(scaled.toFixed(1)) >= 1_000) {
+        unit = units[--unitIndex];
+        scaled = value / unit.threshold;
+    }
+    return `${scaled.toFixed(1).replace(/\.0$/, '')}${unit.suffix}`;
+}
+function isNonNegativeFinite(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+/** Format usage as one segment shared by reply-card footers and the live
+ * streaming card. The caller supplies native facts; this module only formats
+ * them and never infers a context window or token count. Returns null when no
+ * valid native metric is available.
+ *
+ * `variant`:
+ *   - `'footer'` (default): minimal — context only. Reply-card footers are
+ *     cramped (brand · usage · 发送给), so the large cumulative token string is
+ *     dropped here (it lives on the streaming card / usage ledger). 上下文占用
+ *     is the one glanceable "how full am I" metric worth keeping.
+ *   - `'streaming'`: rich — context + `本轮 ↑X ↓Y`(per-turn delta, matches the
+ *     CLI TUI) + `累计 ↑A ↓B`(session total). The live card has room and
+ *     refreshes during execution. */
+export function cardUsageFooterSegment(usage, locale, variant = 'footer') {
+    const parts = [];
+    if (usage.context && isNonNegativeFinite(usage.context.usedTokens)) {
+        const used = compactTokenCount(usage.context.usedTokens);
+        const window = usage.context.windowTokens;
+        const windowSuffix = isNonNegativeFinite(window) && window > 0
+            ? `/${compactTokenCount(window)}`
+            : '';
+        const percentSuffix = isNonNegativeFinite(usage.context.percentUsed)
+            ? ` (${Math.min(100, Math.round(usage.context.percentUsed))}%)`
+            : '';
+        const suffix = `${windowSuffix}${percentSuffix}`;
+        parts.push(`${t('card.usage.context', undefined, locale)} ${used}${suffix}`);
+    }
+    // Footer variant is context-only (keeps the cramped reply-card footer clean);
+    // the token breakdown below is streaming-only.
+    if (variant !== 'streaming') {
+        return parts.length > 0 ? parts.join(' · ') : null;
+    }
+    // Per-turn delta (streaming only): small ↑↓ for the latest turn, labelled 本轮.
+    const turn = usage.turnTokens;
+    if (turn
+        && isNonNegativeFinite(turn.in)
+        && isNonNegativeFinite(turn.out)
+        && (turn.in > 0 || turn.out > 0)) {
+        parts.push(`${t('card.usage.turn', undefined, locale)} `
+            + `↑${compactTokenCount(turn.in)} ↓${compactTokenCount(turn.out)}`);
+    }
+    if (usage.tokens
+        && isNonNegativeFinite(usage.tokens.in)
+        && isNonNegativeFinite(usage.tokens.out)
+        // Suppress an all-zero token line: a brand-new session (or a synthetic /
+        // zero-usage transcript record read before the real turn lands) yields
+        // in=out=0, which would render a meaningless "↑0 ↓0". Omit it like any
+        // other missing metric until there is real usage to show.
+        && (usage.tokens.in > 0 || usage.tokens.out > 0)) {
+        parts.push(`${t('card.usage.total', undefined, locale)} `
+            + `↑${compactTokenCount(usage.tokens.in)} ↓${compactTokenCount(usage.tokens.out)}`);
+    }
+    return parts.length > 0 ? parts.join(' · ') : null;
+}
+/** Build the one canonical footer shared by all Bot Session reply cards.
+ * Ordering, i18n, the parser marker, grey styling, and recipient rendering live
+ * here so direct sends and daemon fallbacks cannot drift apart. */
+export function buildReplyCardFooter(opts) {
+    const parts = [];
+    const brandSeg = brandFooterSegment(opts.brand);
+    if (brandSeg)
+        parts.push(brandSeg);
+    let hasUsage = false;
+    if (opts.usage) {
+        const usageSeg = cardUsageFooterSegment(opts.usage, opts.locale);
+        if (usageSeg) {
+            parts.push(usageSeg);
+            hasUsage = true;
+        }
+    }
+    const recipientOpenIds = [...new Set((opts.recipientOpenIds ?? []).filter(Boolean))];
+    const hasRecipient = recipientOpenIds.length > 0;
+    if (hasRecipient) {
+        parts.push(`${t('card.sent_to', undefined, opts.locale)}`
+            + recipientOpenIds.map(id => `<at id=${id}></at>`).join(' '));
+    }
+    if (parts.length === 0)
+        return null;
+    // The marker is a visible, versioned link that lets the parser identify a
+    // card's footer (and strip it before a bot-to-bot relay). It doubles as the
+    // first separator. But a BRAND-ONLY footer (no usage, no recipient — the
+    // common case now that usageDisplay defaults to the streaming card body and
+    // the reply-card footer is context-only) needs no marker: appending it renders
+    // a dangling "botmux ·". The default/repository brand is plain link text with
+    // no `@`, so it cannot trigger bot-to-bot pollution and does not need the
+    // ownership marker (the parser already treats a bare repo link as ordinary
+    // content, matching the long-standing "brand-only is undecidable, keep it"
+    // contract). Any footer carrying usage or a recipient is still signed.
+    const signMarker = hasUsage || hasRecipient;
+    let signedContent;
+    if (!signMarker) {
+        signedContent = parts[0]; // brand-only — no marker
+    }
+    else if (parts.length > 1) {
+        signedContent = `${parts[0]} ${REPLY_CARD_FOOTER_MARKER} ${parts.slice(1).join(' · ')}`;
+    }
+    else {
+        // usage-only / recipient-only (brand disabled) — still marked for parsing.
+        signedContent = `${parts[0]} ${REPLY_CARD_FOOTER_MARKER}`;
+    }
+    const content = `<font color='grey'>${signedContent}</font>`;
+    return {
+        content,
+        element: {
+            tag: 'markdown',
+            element_id: REPLY_CARD_FOOTER_ELEMENT_ID,
+            text_size: 'notation_small_v2',
+            content,
+        },
+    };
+}
+/** Clone a caller-supplied schema-2 card and append the canonical reply
+ * footer. Returns null for cards without a v2 `body.elements` array or when a
+ * caller-owned element already occupies the globally unique footer id. */
+export function appendReplyCardFooterToV2Card(card, opts) {
+    const cloned = JSON.parse(JSON.stringify(card));
+    if (cloned.schema !== '2.0')
+        return null;
+    const body = cloned.body;
+    if (!body || !Array.isArray(body.elements))
+        return null;
+    const header = cloned.header;
+    const i18nHeaderTagLists = header?.i18n_text_tag_list
+        && typeof header.i18n_text_tag_list === 'object'
+        ? Object.values(header.i18n_text_tag_list)
+        : [];
+    if (containsReplyCardFooterId(body.elements)
+        || containsReplyCardFooterId(header?.text_tag_list)
+        || containsReplyCardFooterId(i18nHeaderTagLists)) {
+        return null;
+    }
+    const footer = buildReplyCardFooter(opts);
+    if (footer)
+        body.elements.push({ tag: 'hr' }, footer.element);
+    return cloned;
+}
+function containsReplyCardFooterId(value) {
+    if (Array.isArray(value))
+        return value.some(containsReplyCardFooterId);
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    if (record.element_id === REPLY_CARD_FOOTER_ELEMENT_ID)
+        return true;
+    // Follow only documented component-child slots. Callback `value`, behavior
+    // payloads, and other arbitrary business JSON are deliberately outside the
+    // card component tree even when they contain tag/element_id-shaped fields.
+    return containsReplyCardFooterId(record.elements)
+        || containsReplyCardFooterId(record.columns)
+        || containsReplyCardFooterId(record.actions)
+        || containsReplyCardFooterId(record.extra);
 }
 /** Build a Feishu native `table` element from a `table_open … table_close` token slice. */
 function buildTableFromTokens(tokens) {
@@ -605,25 +783,21 @@ export function hasMarkdown(text) {
  *
  * `brand` is the sending bot's configured `brandLabel` (see
  * {@link brandFooterSegment}): unset → default botmux link, `''` → brand
- * suppressed, else custom. When brand and recipient are both absent the whole
- * footer (HR included) is omitted.
+ * suppressed, else custom. When brand, usage, and recipient are all absent the
+ * whole footer (HR included) is omitted.
  */
-export function buildMarkdownCard(md, recipientOpenId, brand, locale, workingDir, localHomeLinkMode = 'filesystem') {
+export function buildMarkdownCard(md, recipientOpenId, brand, locale, workingDir, localHomeLinkMode = 'filesystem', usage) {
     const elements = md ? buildCardBodyElements(md, workingDir, localHomeLinkMode) : [];
-    const footerParts = [];
-    const brandSeg = brandFooterSegment(brand);
-    if (brandSeg)
-        footerParts.push(brandSeg);
-    if (recipientOpenId)
-        footerParts.push(`${t('card.sent_to', undefined, locale)}<at id=${recipientOpenId}></at>`);
-    // Empty brand + no recipient → no footer at all (skip the orphan HR too).
-    if (footerParts.length > 0) {
+    const footer = buildReplyCardFooter({
+        brand,
+        recipientOpenIds: recipientOpenId ? [recipientOpenId] : [],
+        usage,
+        locale,
+    });
+    // No brand, usage, or recipient → no footer at all (skip the orphan HR too).
+    if (footer) {
         elements.push({ tag: 'hr' });
-        elements.push({
-            tag: 'markdown',
-            text_size: 'notation_small_v2',
-            content: `<font color='grey'>${footerParts.join(' · ')}</font>`,
-        });
+        elements.push(footer.element);
     }
     return JSON.stringify({
         schema: '2.0',
@@ -655,7 +829,7 @@ function quoteLines(text) {
  * section entirely (headless variant).
  */
 export function buildContextualReplyCard(opts) {
-    const { title, userText, assistantText, assistantLabel, recipientOpenId, brand, locale, workingDir, localHomeLinkMode = 'filesystem', } = opts;
+    const { title, userText, assistantText, assistantLabel, recipientOpenId, brand, locale, workingDir, localHomeLinkMode = 'filesystem', usage, } = opts;
     const elements = [];
     elements.push({
         tag: 'markdown',
@@ -679,19 +853,15 @@ export function buildContextualReplyCard(opts) {
         : [{ tag: 'markdown', content: `*${t('common.empty_paren', undefined, locale)}*` }];
     for (const el of bodyElements)
         elements.push(el);
-    const footerParts = [];
-    const brandSeg = brandFooterSegment(brand);
-    if (brandSeg)
-        footerParts.push(brandSeg);
-    if (recipientOpenId)
-        footerParts.push(`${t('card.sent_to', undefined, locale)}<at id=${recipientOpenId}></at>`);
-    if (footerParts.length > 0) {
+    const footer = buildReplyCardFooter({
+        brand,
+        recipientOpenIds: recipientOpenId ? [recipientOpenId] : [],
+        usage,
+        locale,
+    });
+    if (footer) {
         elements.push({ tag: 'hr' });
-        elements.push({
-            tag: 'markdown',
-            text_size: 'notation_small_v2',
-            content: `<font color='grey'>${footerParts.join(' · ')}</font>`,
-        });
+        elements.push(footer.element);
     }
     return JSON.stringify({
         schema: '2.0',