botmux 2.47.0 → 2.47.2

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

@@ -4,10 +4,14 @@ const cliDisplayNames = {
     'aiden': 'Aiden',
     'coco': 'CoCo',
     'codex': 'Codex',
+    'codex-app': 'Codex App',
     'cursor': 'Cursor',
     'gemini': 'Gemini',
     'opencode': 'OpenCode',
     'antigravity': 'Antigravity',
+    'mtr': 'MTR',
+    'hermes': 'Hermes',
+    'mira': 'Mira',
 };
 export function getCliDisplayName(cliId) {
     return cliDisplayNames[cliId] ?? cliId;
@@ -129,14 +133,70 @@ export function buildSessionClosedCard(sessionId, rootId, title, cliId, workingD
     };
     return JSON.stringify(card);
 }
+/**
+ * Build a frozen-snapshot card to PATCH onto the source-chat streaming card
+ * after `/relay` moves the session elsewhere.
+ *
+ * Why this exists: a live streaming card carries action buttons (close /
+ * toggle display / get write link). Those buttons identify their session by
+ * `session_id` in the value payload, so clicking them after relay still
+ * reaches the now-relocated session — closing it, toggling its display
+ * mode, etc. — but the visible feedback all lands on the NEW card in the
+ * target chat, not this one. The source-chat card then looks like a "live
+ * console" while actually being a footgun. PATCH it to an inert snapshot
+ * so the user sees clearly it's historical.
+ *
+ * Last-frame rendering:
+ *   - imageKey present (session was in 'screenshot' / expanded mode at
+ *     relay time) → embed the same img element the live card had.
+ *     img_key is a Lark server resource independent of the card it lived
+ *     on, so the PATCHed card can still reference it.
+ *   - imageKey absent (hidden / collapsed mode) → render nothing extra.
+ *     The header + body notice already convey the state; raw tmux pane
+ *     text as a code-block is too long and noisy (王皓 caught this in
+ *     testing).
+ *
+ * No action buttons are rendered in either case.
+ */
+export function buildRelayedFrozenCard(title, cliId, imageKey, locale) {
+    const cliName = getCliDisplayName(cliId ?? 'claude-code');
+    const body = `**${escapeMd(title || cliName)}**\n` +
+        `${t('card.body.relay_frozen', undefined, locale)}`;
+    const elements = [
+        { tag: 'markdown', content: body },
+    ];
+    if (imageKey) {
+        elements.push({
+            tag: 'img',
+            img_key: imageKey,
+            alt: { tag: 'plain_text', content: '' },
+            mode: 'fit_horizontal',
+            preview: true,
+        });
+    }
+    const card = {
+        config: { wide_screen_mode: true },
+        header: {
+            title: { tag: 'plain_text', content: t('card.status.relay_frozen', undefined, locale) },
+            template: 'grey',
+        },
+        elements,
+    };
+    return JSON.stringify(card);
+}
 /**
  * Feishu card API rejects payloads exceeding ~109 KB (error 230025).
  * Cap markdown content byte size with headroom for card JSON overhead.
  */
 const MAX_CONTENT_BYTES = 100_000;
-/** Truncate content to fit within MAX_CONTENT_BYTES, keeping the tail (most recent output). */
-export function truncateContent(content, locale) {
-    if (Buffer.byteLength(content, 'utf-8') <= MAX_CONTENT_BYTES)
+/**
+ * Truncate content to fit within `maxBytes`, keeping the tail (most recent
+ * output). Defaults to {@link MAX_CONTENT_BYTES}; callers that wrap the content
+ * in additional card JSON (e.g. the private snapshot's code fence) pass a
+ * tighter budget so the whole card stays under Feishu's ~109 KB hard limit.
+ */
+export function truncateContent(content, locale, maxBytes = MAX_CONTENT_BYTES) {
+    if (Buffer.byteLength(content, 'utf-8') <= maxBytes)
         return content;
     // Binary search for the longest suffix that fits
     const lines = content.split('\n');
@@ -145,7 +205,7 @@ export function truncateContent(content, locale) {
     while (lo < hi) {
         const mid = Math.floor((lo + hi) / 2);
         const candidate = lines.slice(mid).join('\n');
-        if (Buffer.byteLength(candidate, 'utf-8') <= MAX_CONTENT_BYTES - 30) {
+        if (Buffer.byteLength(candidate, 'utf-8') <= maxBytes - 30) {
             hi = mid;
         }
         else {
@@ -154,36 +214,29 @@ export function truncateContent(content, locale) {
     }
     return `${t('card.status.truncated_prefix', undefined, locale)}\n${lines.slice(lo).join('\n')}`;
 }
-/**
- * Build a Feishu streaming card that shows live terminal output + controls.
- * This card is PATCHed in-place as the CLI works.
- *
- * displayMode:
- *   - 'hidden'     — body collapsed; only header + main controls visible.
- *   - 'screenshot' — img element (rendered server-side, uploaded for img_key).
- *
- * Quick-action buttons (Esc, ^C, Tab, Space, Enter, ←↑↓→, ½屏 ↑/↓) appear
- * whenever displayMode !== 'hidden'.
- */
-export function buildStreamingCard(sessionId, rootId, terminalUrl, title, screenContent, status, cliId, displayMode = 'hidden', cardNonce, imageKey, adoptMode, showTakeover, locale, usageLimit) {
-    const effectiveCliId = cliId ?? 'claude-code';
-    const cliName = getCliDisplayName(effectiveCliId);
-    const actionBase = { root_id: rootId, session_id: sessionId, cli_id: effectiveCliId, ...(cardNonce ? { card_nonce: cardNonce } : {}) };
-    const displayStatus = status === 'limited' && usageLimit?.retryReady ? 'retry_ready' : status;
-    const templateMap = { starting: 'yellow', working: 'blue', idle: 'green', analyzing: 'purple', limited: 'red', retry_ready: 'green' };
-    const statusLabel = (s) => {
-        switch (s) {
-            case 'starting': return t('card.status.starting', undefined, locale);
-            case 'working': return t('card.status.working', undefined, locale);
-            case 'idle': return t('card.status.idle', undefined, locale);
-            case 'analyzing': return t('card.status.analyzing', undefined, locale);
-            case 'limited': return usageLimit?.retryReady
-                ? t('card.status.retry_ready', undefined, locale)
-                : t('card.status.limited', undefined, locale);
-        }
-    };
-    const elements = [];
-    // ── Output body ─────────────────────────────────────────────────────────
+/** Byte budget for the private snapshot's text fallback. Well under the ~109 KB
+ *  card limit, leaving room for JSON escaping + the card's structural overhead. */
+const PRIVATE_SNAPSHOT_TEXT_MAX = 50_000;
+const STREAM_TEMPLATE_MAP = {
+    starting: 'yellow', working: 'blue', idle: 'green', analyzing: 'purple', limited: 'red', retry_ready: 'green',
+};
+/** Header status label for a streaming/snapshot card. Shared by the live card
+ *  and the private snapshot so the two never drift. */
+function streamStatusLabel(status, usageLimit, locale) {
+    switch (status) {
+        case 'starting': return t('card.status.starting', undefined, locale);
+        case 'working': return t('card.status.working', undefined, locale);
+        case 'idle': return t('card.status.idle', undefined, locale);
+        case 'analyzing': return t('card.status.analyzing', undefined, locale);
+        case 'limited': return usageLimit?.retryReady
+            ? t('card.status.retry_ready', undefined, locale)
+            : t('card.status.limited', undefined, locale);
+    }
+}
+/** Push the shared "output body" elements (usage-limit notice + screenshot) used
+ *  by both {@link buildStreamingCard} and {@link buildPrivateSnapshotCard}. */
+function pushStreamBody(elements, opts) {
+    const { status, usageLimit, displayMode, imageKey, cliName, locale } = opts;
     if (status === 'limited' && usageLimit) {
         elements.push({
             tag: 'markdown',
@@ -195,19 +248,33 @@ export function buildStreamingCard(sessionId, rootId, terminalUrl, title, screen
     }
     if (displayMode === 'screenshot') {
         if (imageKey) {
-            elements.push({
-                tag: 'img',
-                img_key: imageKey,
-                alt: { tag: 'plain_text', content: '' },
-                mode: 'fit_horizontal',
-                preview: true,
-            });
+            elements.push({ tag: 'img', img_key: imageKey, alt: { tag: 'plain_text', content: '' }, mode: 'fit_horizontal', preview: true });
         }
         else {
             elements.push({ tag: 'markdown', content: t('card.status.waiting_screenshot', undefined, locale) });
         }
         elements.push({ tag: 'hr' });
     }
+}
+/**
+ * Build a Feishu streaming card that shows live terminal output + controls.
+ * This card is PATCHed in-place as the CLI works.
+ *
+ * displayMode:
+ *   - 'hidden'     — body collapsed; only header + main controls visible.
+ *   - 'screenshot' — img element (rendered server-side, uploaded for img_key).
+ *
+ * Quick-action buttons (Esc, ^C, Tab, Space, Enter, ←↑↓→, ½屏 ↑/↓) appear
+ * whenever displayMode !== 'hidden'.
+ */
+export function buildStreamingCard(sessionId, rootId, terminalUrl, title, screenContent, status, cliId, displayMode = 'hidden', cardNonce, imageKey, adoptMode, showTakeover, locale, usageLimit, writableTerminalUrl) {
+    const effectiveCliId = cliId ?? 'claude-code';
+    const cliName = getCliDisplayName(effectiveCliId);
+    const actionBase = { root_id: rootId, session_id: sessionId, cli_id: effectiveCliId, ...(cardNonce ? { card_nonce: cardNonce } : {}) };
+    const displayStatus = status === 'limited' && usageLimit?.retryReady ? 'retry_ready' : status;
+    const elements = [];
+    // ── Output body (shared with the private snapshot card) ──────────────────
+    pushStreamBody(elements, { status, usageLimit, displayMode, imageKey, cliName, locale });
     // ── Main control row: display toggle, mode toggle, terminal, manage ─────
     const headerActions = [];
     headerActions.push({
@@ -277,6 +344,16 @@ export function buildStreamingCard(sessionId, rootId, terminalUrl, title, screen
         });
     }
     elements.push({ tag: 'action', actions: headerActions });
+    // ── Writable terminal link (opt-in) ─────────────────────────────────────
+    // When the bot enables `writableTerminalLinkInCard`, embed the token-bearing
+    // link right in the card so anyone here can open a writable terminal without
+    // the get-write-link → DM round-trip. The link is intentionally group-visible.
+    if (writableTerminalUrl) {
+        elements.push({
+            tag: 'markdown',
+            content: t('card.writable_terminal_link', { url: writableTerminalUrl }, locale),
+        });
+    }
     // ── Quick-action keys (only when the screenshot is visible — in text mode
     //    there's no visible cursor/input, so these keys would fire blindly) ──
     if (displayMode === 'screenshot') {
@@ -311,8 +388,94 @@ export function buildStreamingCard(sessionId, rootId, terminalUrl, title, screen
     const card = {
         config: { wide_screen_mode: true },
         header: {
-            title: { tag: 'plain_text', content: `🖥️ ${cliName} · ${escapeMd(title)} — ${statusLabel(status)}` },
-            template: templateMap[displayStatus],
+            title: { tag: 'plain_text', content: `🖥️ ${cliName} · ${escapeMd(title)} — ${streamStatusLabel(status, usageLimit, locale)}` },
+            template: STREAM_TEMPLATE_MAP[displayStatus],
+        },
+        elements,
+    };
+    return JSON.stringify(card);
+}
+/**
+ * Build a static "private snapshot" card for `/card` in private mode — sent via
+ * the ephemeral API to one user at a time. Unlike {@link buildStreamingCard} it
+ * is **never PATCH-updated** (ephemeral cards can't be), so it carries only a
+ * one-shot snapshot of the terminal screenshot plus three buttons:
+ *   • read-only "open terminal" link (a plain URL button — no callback);
+ *   • "get write link", whose callback DMs the writable link to the clicker;
+ *   • "close session", whose callback kills the session and (in private mode)
+ *     sends the "closed" card ephemeral to the owner audience too — so the
+ *     session title / CLI name / workingDir on it don't leak to the group.
+ * The last two have callbacks but neither patches THIS card (one DMs, the other
+ * sends a fresh card), so both work fine on an ephemeral card. Both are
+ * `canOperate`-gated in the handler — talk-only viewers who tap them are denied.
+ * The patch-driven controls (toggle/refresh/export/term keys) and the inline
+ * writable link are still omitted: those need to update this card, which
+ * ephemeral cards can't do.
+ */
+export function buildPrivateSnapshotCard(terminalUrl, title, status, cliId, imageKey, screenContent, sessionId, rootId, locale, usageLimit) {
+    const effectiveCliId = cliId ?? 'claude-code';
+    const cliName = getCliDisplayName(effectiveCliId);
+    const displayStatus = status === 'limited' && usageLimit?.retryReady ? 'retry_ready' : status;
+    // `visibility: 'private'` pins this card's privacy intent onto the action
+    // itself, so a later callback (notably `close`) keeps sending ephemeral even
+    // if the bot's `privateCard` config is toggled off after the card was sent —
+    // otherwise the closed card (session title / workingDir / resume command)
+    // could leak to the group. See the `close` handler in card-handler.ts.
+    const actionBase = { root_id: rootId, session_id: sessionId, cli_id: effectiveCliId, visibility: 'private' };
+    const elements = [];
+    // Show the terminal once: prefer the rendered screenshot when present;
+    // otherwise fall back to a code-block of the latest screen text so the
+    // snapshot isn't empty (common when the bot has the streaming card disabled
+    // or display mode never flipped to screenshot — `lastScreenContent` is still
+    // kept up to date regardless). pushStreamBody also emits the usage-limit
+    // notice, which applies in either case.
+    pushStreamBody(elements, {
+        status, usageLimit, displayMode: imageKey ? 'screenshot' : 'hidden', imageKey, cliName, locale,
+    });
+    if (!imageKey) {
+        const text = (screenContent ?? '').replace(/[ \t\r\n]+$/, '');
+        if (text) {
+            const body = truncateContent(text, locale, PRIVATE_SNAPSHOT_TEXT_MAX);
+            // Fence must be longer than the longest backtick run in the body, else
+            // terminal output containing ``` would break out of the code block.
+            const maxRun = (body.match(/`+/g) ?? []).reduce((m, r) => Math.max(m, r.length), 0);
+            const fence = '`'.repeat(Math.max(3, maxRun + 1));
+            elements.push({ tag: 'markdown', content: `${fence}\n${body}\n${fence}` });
+            elements.push({ tag: 'hr' });
+        }
+    }
+    elements.push({
+        tag: 'action',
+        actions: [
+            {
+                tag: 'button',
+                text: { tag: 'plain_text', content: t('card.btn.open_terminal', undefined, locale) },
+                type: 'primary',
+                multi_url: { url: terminalUrl, pc_url: terminalUrl, android_url: terminalUrl, ios_url: terminalUrl },
+            },
+            {
+                tag: 'button',
+                text: { tag: 'plain_text', content: t('card.btn.get_write_link', undefined, locale) },
+                type: 'default',
+                value: { action: 'get_write_link', ...actionBase },
+            },
+            {
+                tag: 'button',
+                text: { tag: 'plain_text', content: t('card.btn.close_session', undefined, locale) },
+                type: 'danger',
+                value: { action: 'close', ...actionBase },
+            },
+        ],
+    });
+    elements.push({
+        tag: 'note',
+        elements: [{ tag: 'lark_md', content: t('card.private.snapshot_note', undefined, locale) }],
+    });
+    const card = {
+        config: { wide_screen_mode: true },
+        header: {
+            title: { tag: 'plain_text', content: `🔒 ${cliName} · ${escapeMd(title)} — ${streamStatusLabel(status, usageLimit, locale)}` },
+            template: STREAM_TEMPLATE_MAP[displayStatus],
         },
         elements,
     };
@@ -385,19 +548,22 @@ export function buildGrantCard(o, locale) {
         ? t('card.grant.body_request', { name: escapeMd(o.requesterName), owner: o.ownerOpenId }, locale)
         : t('card.grant.body_owner', { name: escapeMd(o.requesterName), owner: o.ownerOpenId }, locale);
     const v = { target_open_id: o.requesterOpenId, chat_id: o.chatId, nonce: o.nonce };
+    // 「全局授权对话」只在 owner 主动发卡时出现：owner 一眼明确要给全局；request 模式（成员
+    // 自助申请）只提供「本群」，避免成员把自己申请到全局。两个授权按钮都是 talk-only。
+    const grantButtons = [
+        { tag: 'button', type: 'primary', text: { tag: 'plain_text', content: t('card.grant.btn_chat', undefined, locale) }, value: { action: 'grant_chat', ...v } },
+    ];
+    if (o.mode === 'owner') {
+        grantButtons.push({ tag: 'button', type: 'default', text: { tag: 'plain_text', content: t('card.grant.btn_global', undefined, locale) }, value: { action: 'grant_global', ...v } });
+    }
+    grantButtons.push({ tag: 'button', type: 'danger', text: { tag: 'plain_text', content: t('card.grant.btn_deny', undefined, locale) }, value: { action: 'grant_deny', ...v } });
     const card = {
         config: { wide_screen_mode: true },
         header: { template: 'orange', title: { tag: 'plain_text', content: t('card.grant.title', undefined, locale) } },
         elements: [
             { tag: 'div', text: { tag: 'lark_md', content: body } },
             { tag: 'hr' },
-            {
-                tag: 'action',
-                actions: [
-                    { tag: 'button', type: 'primary', text: { tag: 'plain_text', content: t('card.grant.btn_chat', undefined, locale) }, value: { action: 'grant_chat', ...v } },
-                    { tag: 'button', type: 'danger', text: { tag: 'plain_text', content: t('card.grant.btn_deny', undefined, locale) }, value: { action: 'grant_deny', ...v } },
-                ],
-            },
+            { tag: 'action', actions: grantButtons },
             { tag: 'note', elements: [{ tag: 'lark_md', content: t('card.grant.note', undefined, locale) }] },
         ],
     };
@@ -570,6 +736,270 @@ function formatDuration(ms) {
     const d = Math.floor(h / 24);
     return `${d}d${h % 24}h`;
 }
+function relayPickerTypeTag(mode, locale) {
+    switch (mode) {
+        case 'p2p': return t('card.relay.type_p2p', undefined, locale);
+        case 'topic': return t('card.relay.type_topic', undefined, locale);
+        default: return t('card.relay.type_group', undefined, locale); // 'group' or undefined
+    }
+}
+const RELAY_PICKER_PAGE_SIZE = 5;
+const RELAY_SEARCH_FIELD = 'search';
+/**
+ * Match against title / chatLabel / workingDir / cliId. Case-insensitive
+ * substring. Empty / whitespace query matches everything.
+ */
+function relayPickerFilter(entries, query) {
+    const q = (query ?? '').trim().toLowerCase();
+    if (!q)
+        return entries;
+    return entries.filter((e) => {
+        const haystack = [e.title, e.chatLabel, e.workingDir, e.cliId]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase();
+        return haystack.includes(q);
+    });
+}
+/**
+ * Card listing the operator's relayable sessions, paginated 5 per page with
+ * a search box at the top and a confirm button at the bottom. Layout:
+ *
+ *   ┌──────────────────────────────────────┐
+ *   │ 📋 选择要接力的会话                   │  header
+ *   ├──────────────────────────────────────┤
+ *   │ 🔍 [______________] [搜索]            │  form: input + submit button
+ *   ├──────────────────────────────────────┤
+ *   │  [interactive_container 1]            │  current page (≤5 cards),
+ *   │  [interactive_container 2]            │  each clickable for selection
+ *   │   ...                                 │
+ *   ├──────────────────────────────────────┤
+ *   │  [← 上一页]  1 / 4  [下一页 →]        │  paginator row
+ *   ├──────────────────────────────────────┤
+ *   │   [确认接力到本群]                    │  primary button (only when
+ *   │                                       │   a selected session is on
+ *   │                                       │   the current filtered set)
+ *   └──────────────────────────────────────┘
+ *
+ * State (search / page / selected) is propagated entirely via the value
+ * objects on each button and container — Lark cards are stateless, so any
+ * server-side re-render must reconstruct from what the click sent us.
+ * That's why every interactive value here carries `search`, `page`,
+ * `target_chat_id`, `root_id`.
+ *
+ * Note: typing into the search box without clicking 搜索 does NOT update
+ * the in-callback state — container/paginator clicks use whatever search
+ * was applied at card-render time. To apply a new filter, click 搜索.
+ */
+export function buildRelayPickerCard(entries, targetChatId, targetRootMessageId, invokerOpenId, locale, state) {
+    const searchQuery = state?.searchQuery ?? '';
+    const requestedPage = state?.page ?? 0;
+    const selectedSessionId = state?.selectedSessionId;
+    const elements = [];
+    // ─── Filter & paginate ───────────────────────────────────────────────
+    const filtered = relayPickerFilter(entries, searchQuery);
+    const totalPages = Math.max(1, Math.ceil(filtered.length / RELAY_PICKER_PAGE_SIZE));
+    const page = Math.min(Math.max(0, requestedPage), totalPages - 1);
+    const start = page * RELAY_PICKER_PAGE_SIZE;
+    const visible = filtered.slice(start, start + RELAY_PICKER_PAGE_SIZE);
+    // Common state object carried by every interactive value so re-renders
+    // can reconstruct what the user was looking at. `invoker_open_id` pins the
+    // card to the user who originally summoned it — card-handler refuses
+    // re-render / confirm clicks from anyone else, so the menu doesn't get
+    // silently swapped to a passer-by's session list.
+    const stateValue = {
+        target_chat_id: targetChatId,
+        root_id: targetRootMessageId,
+        invoker_open_id: invokerOpenId,
+        search: searchQuery,
+        page,
+        selected: selectedSessionId ?? '',
+    };
+    // ─── Search box ─────────────────────────────────────────────────────
+    // v2 input supports `behaviors` natively — pressing Enter or clicking
+    // the built-in submit icon inside the input fires the callback. No
+    // separate 搜索 button needed (王皓 reported that button rendered as
+    // "..." due to cramped column width; the auto-submit input avoids the
+    // problem entirely AND removes the manual click).
+    //
+    // On submit the callback delivers `action.input_value` (the typed
+    // string) and `action.value` (our state object). card-handler reads
+    // input_value to update search, resets page to 0 and clears selection.
+    elements.push({
+        tag: 'input',
+        name: RELAY_SEARCH_FIELD,
+        placeholder: { tag: 'plain_text', content: t('card.relay.search_placeholder', undefined, locale) },
+        default_value: searchQuery,
+        width: 'fill',
+        behaviors: [
+            {
+                type: 'callback',
+                value: { action: 'relay_search', ...stateValue, selected: '' /* new search → reset selection */ },
+            },
+        ],
+    });
+    elements.push({ tag: 'hr' });
+    // ─── Empty / no-match notice ────────────────────────────────────────
+    if (entries.length === 0) {
+        elements.push({ tag: 'markdown', content: t('card.relay.empty', undefined, locale) });
+        return JSON.stringify(wrapCard(elements, locale));
+    }
+    if (filtered.length === 0) {
+        elements.push({
+            tag: 'markdown',
+            content: t('card.relay.empty_filtered', { query: searchQuery }, locale),
+        });
+        return JSON.stringify(wrapCard(elements, locale));
+    }
+    // ─── Session cards (current page) ───────────────────────────────────
+    const p2pLocationLabel = t('card.relay.type_p2p', undefined, locale);
+    const labelType = t('card.relay.field_type', undefined, locale);
+    const labelLocation = t('card.relay.field_location', undefined, locale);
+    const labelTime = t('card.relay.field_time', undefined, locale);
+    const selectedTag = t('card.relay.selected_tag', undefined, locale);
+    const hasValidSelection = !!selectedSessionId && filtered.some(e => e.sessionId === selectedSessionId);
+    visible.forEach((e) => {
+        const isSelected = e.sessionId === selectedSessionId;
+        const typeTag = relayPickerTypeTag(e.chatMode, locale);
+        const locationLine = e.chatMode === 'p2p' ? p2pLocationLabel : e.chatLabel;
+        const titleLine = isSelected
+            ? `**✅ ${escapeMd(e.title)}** \`${selectedTag}\``
+            : `**${escapeMd(e.title)}**`;
+        const lines = [
+            titleLine,
+            `${labelType}: ${typeTag}`,
+            `${labelLocation}: ${escapeMd(locationLine)}`,
+        ];
+        if (e.lastMessageAt) {
+            lines.push(`${labelTime}: ${formatDuration(Date.now() - e.lastMessageAt)}`);
+        }
+        elements.push({
+            tag: 'interactive_container',
+            width: 'fill',
+            padding: '8px 12px',
+            background_style: isSelected ? 'laser' : 'default',
+            has_border: true,
+            border_color: isSelected ? 'blue-500' : 'grey-200',
+            corner_radius: '8px',
+            behaviors: [
+                {
+                    type: 'callback',
+                    value: { action: 'relay_select', session_id: e.sessionId, ...stateValue },
+                },
+            ],
+            elements: [{ tag: 'markdown', content: lines.join('\n') }],
+        });
+    });
+    // ─── Paginator (only when more than one page) ───────────────────────
+    if (totalPages > 1) {
+        elements.push({
+            tag: 'column_set',
+            flex_mode: 'none',
+            horizontal_spacing: 'default',
+            columns: [
+                {
+                    tag: 'column',
+                    width: 'weighted',
+                    weight: 1,
+                    vertical_align: 'center',
+                    elements: [
+                        {
+                            tag: 'button',
+                            text: { tag: 'plain_text', content: t('card.relay.btn_prev_page', undefined, locale) },
+                            type: 'default',
+                            disabled: page === 0,
+                            behaviors: [
+                                {
+                                    type: 'callback',
+                                    value: { action: 'relay_page', ...stateValue, page: Math.max(0, page - 1) },
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    tag: 'column',
+                    width: 'weighted',
+                    weight: 2,
+                    vertical_align: 'center',
+                    elements: [
+                        {
+                            tag: 'markdown',
+                            text_align: 'center',
+                            content: t('card.relay.page_indicator', { current: page + 1, total: totalPages }, locale),
+                        },
+                    ],
+                },
+                {
+                    tag: 'column',
+                    width: 'weighted',
+                    weight: 1,
+                    vertical_align: 'center',
+                    elements: [
+                        {
+                            tag: 'button',
+                            text: { tag: 'plain_text', content: t('card.relay.btn_next_page', undefined, locale) },
+                            type: 'default',
+                            disabled: page === totalPages - 1,
+                            behaviors: [
+                                {
+                                    type: 'callback',
+                                    value: { action: 'relay_page', ...stateValue, page: Math.min(totalPages - 1, page + 1) },
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+    }
+    // ─── Confirm button or hint ─────────────────────────────────────────
+    elements.push({ tag: 'hr' });
+    if (hasValidSelection) {
+        elements.push({
+            tag: 'column_set',
+            flex_mode: 'none',
+            columns: [
+                {
+                    tag: 'column',
+                    width: 'weighted',
+                    weight: 1,
+                    elements: [
+                        {
+                            tag: 'button',
+                            text: { tag: 'plain_text', content: t('card.relay.btn_confirm', undefined, locale) },
+                            type: 'primary',
+                            behaviors: [
+                                {
+                                    type: 'callback',
+                                    value: { action: 'relay_confirm', session_id: selectedSessionId, ...stateValue },
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+    }
+    else {
+        elements.push({
+            tag: 'markdown',
+            content: `<font color='grey'>${t('card.relay.hint_pick_first', undefined, locale)}</font>`,
+        });
+    }
+    return JSON.stringify(wrapCard(elements, locale));
+}
+function wrapCard(elements, locale) {
+    return {
+        schema: '2.0',
+        config: { update_multi: true },
+        header: {
+            title: { tag: 'plain_text', content: t('card.relay.title', undefined, locale) },
+            template: 'blue',
+        },
+        body: { direction: 'vertical', elements },
+    };
+}
 export function buildAdoptSelectCard(sessions, rootMessageId, locale) {
     const unknownUptime = t('card.adopt.uptime_unknown', undefined, locale);
     const options = sessions.map((s) => {