@bubblebrain-ai/bubble 0.0.9 → 0.0.11

package/dist/feishu/card/budget.js

@@ -0,0 +1,134 @@
+/**
+ * Card size budget. Two limits matter:
+ *   - per-element: ~30KB on `cardElement.content` updates (Feishu error 11310)
+ *   - per-card total: ~150KB on the patch request body
+ *
+ * Strategy:
+ *   1. Truncate any single element text to maxBytesPerElement, marking it.
+ *   2. If the rendered card serializes above maxBytesPerCard, collapse the
+ *      *oldest* tool blocks first into one-line summaries, keeping the most
+ *      recent few intact. Text/thinking blocks are truncated from the head.
+ */
+export function utf8Bytes(s) {
+    return Buffer.byteLength(s, "utf8");
+}
+/**
+ * Return a truncated version of `text` such that its UTF-8 byte size is
+ * at most `maxBytes`. Adds a trailing ellipsis when truncation happens.
+ */
+export function truncateToBytes(text, maxBytes) {
+    if (utf8Bytes(text) <= maxBytes)
+        return text;
+    const ellipsis = "…"; // U+2026 == 3 UTF-8 bytes
+    const ellipsisBytes = utf8Bytes(ellipsis);
+    const budget = Math.max(0, maxBytes - ellipsisBytes);
+    // Binary search for the largest prefix that fits within `budget` bytes.
+    let lo = 0;
+    let hi = text.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (utf8Bytes(text.slice(0, mid)) <= budget) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return text.slice(0, lo) + ellipsis;
+}
+/**
+ * Reduce `state.blocks` so that each block's user-visible text fits within
+ * `maxBytesPerElement`. Does not enforce total-card budget — see
+ * `applyCardBudget` for that.
+ */
+export function clampBlocksToElementBudget(state, maxBytesPerElement) {
+    for (const block of state.blocks) {
+        switch (block.kind) {
+            case "text":
+                block.text = truncateToBytes(block.text, maxBytesPerElement);
+                break;
+            case "thinking":
+                block.text = truncateToBytes(block.text, maxBytesPerElement);
+                break;
+            case "tool":
+                block.argsPreview = truncateToBytes(block.argsPreview, Math.min(maxBytesPerElement, 4000));
+                if (block.resultPreview) {
+                    block.resultPreview = truncateToBytes(block.resultPreview, Math.min(maxBytesPerElement, 8000));
+                }
+                break;
+        }
+    }
+}
+/**
+ * Best-effort compress to fit the card's total byte budget. Mutates `state`.
+ *
+ * Heuristics (run until under budget or no more reductions possible):
+ *   1. Collapse all completed tool blocks except the last 2 into one-line summaries
+ *   2. Truncate text blocks from the head to half their current size
+ *   3. Drop the oldest text/thinking blocks entirely
+ *
+ * The estimator uses a rough serialization length (sum of relevant fields)
+ * rather than the actual card JSON — cheap enough to call per update.
+ */
+export function applyCardBudget(state, opts) {
+    clampBlocksToElementBudget(state, opts.maxBytesPerElement);
+    if (estimateBytes(state) <= opts.maxBytesPerCard)
+        return;
+    // Step 1: collapse old completed tool blocks (keep newest 2 verbose).
+    const toolIndices = [];
+    for (let i = 0; i < state.blocks.length; i++) {
+        if (state.blocks[i].kind === "tool")
+            toolIndices.push(i);
+    }
+    const keepVerboseTools = toolIndices.slice(-2);
+    for (const idx of toolIndices) {
+        if (keepVerboseTools.includes(idx))
+            continue;
+        const tool = state.blocks[idx];
+        if (tool.status === "running")
+            continue;
+        // Replace verbose preview with a 60-char summary.
+        if (tool.resultPreview) {
+            tool.resultPreview = truncateToBytes(tool.resultPreview, 200);
+        }
+        tool.argsPreview = truncateToBytes(tool.argsPreview, 80);
+    }
+    if (estimateBytes(state) <= opts.maxBytesPerCard)
+        return;
+    // Step 2: halve text blocks from the head until under budget.
+    for (const block of state.blocks) {
+        if (block.kind !== "text" && block.kind !== "thinking")
+            continue;
+        if (block.text.length > 200) {
+            block.text = "…" + block.text.slice(Math.floor(block.text.length / 2));
+        }
+        if (estimateBytes(state) <= opts.maxBytesPerCard)
+            return;
+    }
+    // Step 3: drop oldest text/thinking blocks (keep tool history intact).
+    while (estimateBytes(state) > opts.maxBytesPerCard && state.blocks.length > 0) {
+        const idx = state.blocks.findIndex((b) => b.kind === "text" || b.kind === "thinking");
+        if (idx === -1)
+            break;
+        state.blocks.splice(idx, 1);
+    }
+}
+function estimateBytes(state) {
+    let total = 256; // header / footer / scaffold
+    for (const block of state.blocks) {
+        switch (block.kind) {
+            case "text":
+                total += utf8Bytes(block.text) + 32;
+                break;
+            case "thinking":
+                total += utf8Bytes(block.text) + 48;
+                break;
+            case "tool":
+                total += utf8Bytes(block.name) + utf8Bytes(block.argsPreview) + 64;
+                if (block.resultPreview)
+                    total += utf8Bytes(block.resultPreview);
+                break;
+        }
+    }
+    return total;
+}

package/dist/feishu/card/renderer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * RunState → Feishu interactive card JSON (v1 schema).
+ *
+ * Schema reference:
+ *   - top-level: { config, header, elements }
+ *   - element tags: 'markdown' | 'div' | 'hr' | 'note' | 'action' | 'collapsible_panel'
+ *   - card config MUST include `update_multi: true` to be patch-able
+ *
+ * The `LarkChannel.stream({ card: { initial, producer } })` path consumes
+ * exactly this shape — the producer calls `ctrl.update(nextCard)` with a
+ * fresh render on each agent event.
+ */
+import type { RunState } from "./run-state-types.js";
+import { type BudgetOptions } from "./budget.js";
+export interface RenderOptions {
+    budget: BudgetOptions;
+    /** Whether to render a Stop button while running. Default: true. */
+    showStopButton?: boolean;
+    /** Opaque token to identify this run for button callbacks. */
+    runToken?: string;
+    /**
+     * Use `collapsible_panel` elements to hide thinking + finished tool detail.
+     * Default true. Set false if your Feishu card host doesn't render the
+     * `collapsible_panel` tag — completed tools fall back to a chip + one-line
+     * result preview, and thinking falls back to a compact status note.
+     */
+    collapsible?: boolean;
+}
+export declare function renderCard(state: RunState, opts: RenderOptions): object;

package/dist/feishu/card/renderer.js

@@ -0,0 +1,245 @@
+/**
+ * RunState → Feishu interactive card JSON (v1 schema).
+ *
+ * Schema reference:
+ *   - top-level: { config, header, elements }
+ *   - element tags: 'markdown' | 'div' | 'hr' | 'note' | 'action' | 'collapsible_panel'
+ *   - card config MUST include `update_multi: true` to be patch-able
+ *
+ * The `LarkChannel.stream({ card: { initial, producer } })` path consumes
+ * exactly this shape — the producer calls `ctrl.update(nextCard)` with a
+ * fresh render on each agent event.
+ */
+import { applyCardBudget } from "./budget.js";
+import { formatPermissionMode } from "../format.js";
+const STATUS_ICON = {
+    running: "🟢",
+    completed: "✅",
+    interrupted: "⏹",
+    error: "🟥",
+    idle_timeout: "⏱",
+};
+const STATUS_TEMPLATE = {
+    running: "blue",
+    completed: "green",
+    interrupted: "grey",
+    error: "red",
+    idle_timeout: "yellow",
+};
+const STATUS_TITLE = {
+    running: "Running",
+    completed: "Completed",
+    interrupted: "Interrupted",
+    error: "Error",
+    idle_timeout: "Idle Timeout",
+};
+const TOOL_ICON = {
+    running: "⏳",
+    ok: "✅",
+    err: "❌",
+};
+export function renderCard(state, opts) {
+    applyCardBudget(state, opts.budget);
+    const showStop = opts.showStopButton !== false && state.status === "running";
+    const useCollapsible = opts.collapsible !== false;
+    const elements = buildElements(state, showStop, opts.runToken, useCollapsible);
+    return {
+        config: { update_multi: true, wide_screen_mode: true },
+        header: {
+            title: { tag: "plain_text", content: buildHeaderTitle(state) },
+            template: STATUS_TEMPLATE[state.status],
+        },
+        elements,
+    };
+}
+function buildHeaderTitle(state) {
+    const icon = STATUS_ICON[state.status];
+    const title = STATUS_TITLE[state.status];
+    return `${icon} ${title} · ${state.scope.displayName}`;
+}
+function buildElements(state, showStop, runToken, useCollapsible) {
+    const elements = [];
+    // Top note: cwd + mode badges
+    elements.push({
+        tag: "note",
+        elements: [
+            {
+                tag: "plain_text",
+                content: `📁 ${state.scope.cwd}    🛡 ${formatPermissionMode(state.mode)}`,
+            },
+        ],
+    });
+    elements.push({ tag: "hr" });
+    // Blocks
+    if (state.blocks.length === 0) {
+        elements.push({ tag: "markdown", content: "_思考中…_" });
+    }
+    for (const block of state.blocks) {
+        switch (block.kind) {
+            case "text":
+                elements.push({
+                    tag: "markdown",
+                    content: escapeMarkdownContent(block.text) + (block.streaming ? " ▌" : ""),
+                });
+                break;
+            case "thinking": {
+                if (!block.text.trim())
+                    break;
+                if (!useCollapsible) {
+                    // Fallback: omit body, just hint that thinking happened/is happening.
+                    elements.push({
+                        tag: "note",
+                        elements: [{
+                                tag: "plain_text",
+                                content: block.streaming ? "💭 思考中…" : "💭 思考已折叠",
+                            }],
+                    });
+                    break;
+                }
+                const title = block.streaming ? "💭 思考中…" : "💭 思考过程";
+                elements.push(collapsiblePanel(title, [
+                    {
+                        tag: "markdown",
+                        content: `> ${quoteLines(block.text)}${block.streaming ? " ▌" : ""}`,
+                    },
+                ]));
+                break;
+            }
+            case "tool": {
+                const icon = TOOL_ICON[block.status];
+                if (block.status === "running") {
+                    // In-flight: keep visible so the user can see what's happening now.
+                    const head = `**${icon} ${block.name}**`;
+                    const argsLine = block.argsPreview ? `\n\`${escapeInlineCode(block.argsPreview)}\`` : "";
+                    elements.push({ tag: "markdown", content: head + argsLine });
+                }
+                else {
+                    // Completed: chip header, full args (only if truncated in title) +
+                    // result tucked into a collapsible panel.
+                    const CHIP_ARGS_LIMIT = 60;
+                    const chipTitle = buildToolChipTitle(icon, block.name, block.argsPreview, CHIP_ARGS_LIMIT);
+                    if (!useCollapsible) {
+                        // Fallback: chip title + one-line result preview, no expansion.
+                        const oneLineResult = block.resultPreview
+                            ? `\n${truncate(block.resultPreview.replace(/\s+/g, " ").trim(), 160)}`
+                            : "";
+                        elements.push({ tag: "markdown", content: chipTitle + oneLineResult });
+                        break;
+                    }
+                    const detail = [];
+                    if (block.argsPreview && block.argsPreview.length > CHIP_ARGS_LIMIT) {
+                        detail.push({
+                            tag: "markdown",
+                            content: `**args:** \`${escapeInlineCode(block.argsPreview)}\``,
+                        });
+                    }
+                    if (block.resultPreview) {
+                        detail.push({
+                            tag: "markdown",
+                            content: escapeMarkdownContent(block.resultPreview),
+                        });
+                    }
+                    if (detail.length === 0) {
+                        elements.push({ tag: "markdown", content: chipTitle });
+                    }
+                    else {
+                        elements.push(collapsiblePanel(chipTitle, detail));
+                    }
+                }
+                break;
+            }
+        }
+    }
+    elements.push({ tag: "hr" });
+    // Footer: usage + elapsed + stop button
+    const footerParts = [];
+    if (state.usage) {
+        const total = state.usage.totalTokens
+            ?? ((state.usage.promptTokens ?? 0) + (state.usage.completionTokens ?? 0));
+        footerParts.push(`📊 ${formatTokenCount(total)} tokens`);
+    }
+    footerParts.push(`⏱ ${formatElapsed(state.updatedAt - state.startedAt)}`);
+    if (state.error?.message) {
+        footerParts.push(`⚠ ${truncate(state.error.message, 200)}`);
+    }
+    elements.push({
+        tag: "note",
+        elements: [{ tag: "plain_text", content: footerParts.join("    ") }],
+    });
+    if (showStop && runToken) {
+        elements.push({
+            tag: "action",
+            actions: [
+                {
+                    tag: "button",
+                    text: { tag: "plain_text", content: "⏹ 停止" },
+                    type: "danger",
+                    value: { __bubble: "stop_run", runToken },
+                },
+            ],
+        });
+    }
+    return elements;
+}
+function collapsiblePanel(headerMarkdown, elements) {
+    return {
+        tag: "collapsible_panel",
+        expanded: false,
+        background_color: "grey-100",
+        header: {
+            title: { tag: "markdown", content: headerMarkdown },
+            vertical_align: "center",
+            padding: "4px 0px 4px 8px",
+            icon: {
+                tag: "standard_icon",
+                token: "down-small-ccm_outlined",
+                size: "16px 16px",
+            },
+            icon_position: "right",
+            icon_expanded_angle: -180,
+        },
+        elements,
+    };
+}
+function buildToolChipTitle(icon, name, argsPreview, limit) {
+    const head = `**${icon} ${name}**`;
+    if (!argsPreview)
+        return head;
+    const inline = truncate(argsPreview, limit);
+    return `${head} · \`${escapeInlineCode(inline)}\``;
+}
+function escapeMarkdownContent(text) {
+    // Feishu markdown rendering is mostly Github-flavored but doesn't tolerate
+    // unescaped pipe / backtick characters well in cards. We do a minimal
+    // pass: keep code fences intact, but ensure no element value is empty.
+    if (!text.trim())
+        return "_(empty)_";
+    return text;
+}
+function escapeInlineCode(text) {
+    // Inline code uses single backticks; replace any backtick in the value
+    // with U+2018 to avoid breaking out of the code span.
+    return text.replace(/`/g, "ʼ");
+}
+function quoteLines(text) {
+    return text.split("\n").join("\n> ");
+}
+function formatTokenCount(n) {
+    if (n >= 1000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return String(n);
+}
+function formatElapsed(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const mins = Math.floor(ms / 60_000);
+    const secs = Math.floor((ms % 60_000) / 1000);
+    return `${mins}m${secs}s`;
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 1) + "…";
+}

package/dist/feishu/card/run-state-types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * RunState — a pure, JSON-serializable view of an in-flight agent run.
+ * Fed by the reducer over AgentEvent, consumed by the card renderer.
+ */
+import type { PermissionMode, TokenUsage } from "../../types.js";
+export type RunStatus = "running" | "completed" | "interrupted" | "error" | "idle_timeout";
+export interface RunStateScope {
+    chatId: string;
+    userId: string;
+    displayName: string;
+    cwd: string;
+}
+export type RunStateBlock = TextBlock | ThinkingBlock | ToolBlock;
+export interface TextBlock {
+    kind: "text";
+    text: string;
+    streaming: boolean;
+}
+export interface ThinkingBlock {
+    kind: "thinking";
+    text: string;
+    streaming: boolean;
+}
+export interface ToolBlock {
+    kind: "tool";
+    id: string;
+    name: string;
+    argsPreview: string;
+    status: "running" | "ok" | "err";
+    resultPreview?: string;
+    startedAt: number;
+    endedAt?: number;
+}
+export interface RunState {
+    scope: RunStateScope;
+    mode: PermissionMode;
+    status: RunStatus;
+    blocks: RunStateBlock[];
+    usage?: TokenUsage;
+    startedAt: number;
+    updatedAt: number;
+    error?: {
+        message: string;
+    };
+}
+export declare function createInitialRunState(input: {
+    scope: RunStateScope;
+    mode: PermissionMode;
+}): RunState;

package/dist/feishu/card/run-state-types.js

@@ -0,0 +1,15 @@
+/**
+ * RunState — a pure, JSON-serializable view of an in-flight agent run.
+ * Fed by the reducer over AgentEvent, consumed by the card renderer.
+ */
+export function createInitialRunState(input) {
+    const now = Date.now();
+    return {
+        scope: input.scope,
+        mode: input.mode,
+        status: "running",
+        blocks: [],
+        startedAt: now,
+        updatedAt: now,
+    };
+}

package/dist/feishu/card/run-state.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure-function reducer: AgentEvent → RunState.
+ *
+ * Mutates `state` in place for performance (this runs on every streaming
+ * token). Always sets state.updatedAt. Caller is expected to immediately
+ * re-render through the (throttled) card renderer.
+ */
+import type { AgentEvent } from "../../types.js";
+import type { RunState } from "./run-state-types.js";
+export declare function reduceRunState(state: RunState, event: AgentEvent): RunState;
+/** Mark `status="interrupted"` and close any streaming blocks. */
+export declare function markInterrupted(state: RunState): RunState;
+/** Mark `status="error"`. */
+export declare function markError(state: RunState, error: Error | string): RunState;
+/** Mark `status="idle_timeout"`. */
+export declare function markIdleTimeout(state: RunState): RunState;
+/**
+ * Last-block-only check used by idle watchdog: if there's an in-flight tool,
+ * we don't count toward idle.
+ */
+export declare function hasInFlightTool(state: RunState): boolean;