@bubblebrain-ai/bubble 0.0.10 → 0.0.12

package/dist/feishu/agent-host/approval-ui.js

@@ -0,0 +1,214 @@
+/**
+ * Feishu-side approval handler.
+ *
+ * We don't implement ApprovalController ourselves — we reuse the existing
+ * `PermissionAwareApprovalController` and provide its `handlerRef.current`,
+ * which is the function called when interactive approval is required.
+ *
+ * That handler:
+ *   1. Builds an approval card with [批准] [拒绝] [批准并加入会话允许列表] buttons.
+ *   2. Sends the card to the chat (separately from the run-state card).
+ *   3. Returns a Promise that resolves when the matching `cardAction` event
+ *      arrives (and the clicker is the original user).
+ *   4. Times out after `timeoutMs`, rejecting with feedback.
+ *
+ * Caller responsibilities:
+ *   - Wire the LarkChannel `cardAction` listener to call `dispatch(evt)`.
+ *   - On scope shutdown, call `cancelAll()` so any pending prompt rejects.
+ */
+import { formatApprovalRequest } from "./approval-card.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+let CALLBACK_SEQ = 0;
+export class FeishuApprovalUI {
+    opts;
+    pending = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Create a handler suitable for `PermissionAwareApprovalController.handlerRef.current`.
+     * The handler is closure-bound to (chatId, originalUserId) so each scope
+     * gets its own clicker-restricted prompt.
+     */
+    makeHandler(chatId, originalUserId) {
+        return async (req) => this.prompt(chatId, originalUserId, req);
+    }
+    async prompt(chatId, originalUserId, req) {
+        const callbackId = `bub_${Date.now().toString(36)}_${(CALLBACK_SEQ++).toString(36)}`;
+        const summary = formatApprovalRequest(req);
+        const card = buildPromptCard({
+            title: summary.title,
+            body: summary.body,
+            callbackId,
+            kind: req.type,
+        });
+        let sent;
+        try {
+            sent = await this.opts.sendCard(chatId, card);
+        }
+        catch (err) {
+            return {
+                action: "reject",
+                feedback: `Failed to send approval card: ${err.message}`,
+            };
+        }
+        const timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                const pending = this.pending.get(callbackId);
+                if (!pending)
+                    return;
+                this.pending.delete(callbackId);
+                void this.opts.updateCard(pending.cardMessageId, buildTimeoutCard(summary));
+                resolve({ action: "reject", feedback: "Approval timed out after 60s." });
+            }, timeoutMs);
+            const entry = {
+                callbackId,
+                cardMessageId: sent.messageId,
+                originalUserId,
+                chatId,
+                request: req,
+                resolve,
+                timer,
+            };
+            this.pending.set(callbackId, entry);
+        });
+    }
+    /** Called by the channel-level cardAction listener. */
+    async dispatch(evt) {
+        const value = evt.value;
+        if (!value || typeof value !== "object")
+            return false;
+        if (value.__bubble !== "approval")
+            return false;
+        const callbackId = String(value.callbackId ?? "");
+        const action = String(value.action ?? "");
+        const pending = this.pending.get(callbackId);
+        if (!pending) {
+            // Stale callback or for another instance — silently ignore but consume.
+            return true;
+        }
+        if (evt.cardMessageId !== pending.cardMessageId)
+            return false;
+        // Only the original requester may click. Clicks from anyone else are
+        // ignored (and we leave the card as-is so the real user can still act).
+        if (evt.clickerOpenId !== pending.originalUserId) {
+            return true;
+        }
+        this.pending.delete(callbackId);
+        clearTimeout(pending.timer);
+        let decision;
+        let resultCardKind = "approved";
+        if (action === "approve") {
+            decision = { action: "approve" };
+            resultCardKind = "approved";
+        }
+        else if (action === "reject") {
+            decision = { action: "reject", feedback: "User rejected via Feishu." };
+            resultCardKind = "rejected";
+        }
+        else if (action === "approve_remember" && pending.request.type === "bash") {
+            this.opts.bashAllowlist?.add(pending.request.command);
+            decision = { action: "approve" };
+            resultCardKind = "remembered";
+        }
+        else {
+            decision = { action: "reject", feedback: `Unknown approval action: ${action}` };
+            resultCardKind = "rejected";
+        }
+        try {
+            await this.opts.updateCard(pending.cardMessageId, buildResolvedCard(formatApprovalRequest(pending.request), resultCardKind));
+        }
+        catch {
+            // Best effort — the decision already returned.
+        }
+        pending.resolve(decision);
+        return true;
+    }
+    /** Reject all pending prompts (e.g. on shutdown or run abort). */
+    cancelAll(reason = "Run cancelled") {
+        for (const [callbackId, pending] of this.pending.entries()) {
+            clearTimeout(pending.timer);
+            this.pending.delete(callbackId);
+            pending.resolve({ action: "reject", feedback: reason });
+        }
+    }
+    /** Cancel any pending approvals attached to a specific chat (used per scope on /stop). */
+    cancelForChat(chatId, reason = "Run cancelled") {
+        for (const [callbackId, pending] of this.pending.entries()) {
+            if (pending.chatId !== chatId)
+                continue;
+            clearTimeout(pending.timer);
+            this.pending.delete(callbackId);
+            pending.resolve({ action: "reject", feedback: reason });
+        }
+    }
+    pendingCount() {
+        return this.pending.size;
+    }
+}
+function buildPromptCard(input) {
+    const buttons = [
+        {
+            tag: "button",
+            text: { tag: "plain_text", content: "✅ 批准" },
+            type: "primary",
+            value: { __bubble: "approval", callbackId: input.callbackId, action: "approve" },
+        },
+        {
+            tag: "button",
+            text: { tag: "plain_text", content: "❌ 拒绝" },
+            type: "danger",
+            value: { __bubble: "approval", callbackId: input.callbackId, action: "reject" },
+        },
+    ];
+    if (input.kind === "bash") {
+        buttons.push({
+            tag: "button",
+            text: { tag: "plain_text", content: "✅+ 本会话都允许" },
+            type: "default",
+            value: { __bubble: "approval", callbackId: input.callbackId, action: "approve_remember" },
+        });
+    }
+    return {
+        config: { update_multi: true, wide_screen_mode: true },
+        header: {
+            title: { tag: "plain_text", content: `⚠️ 需要批准：${input.title}` },
+            template: "orange",
+        },
+        elements: [
+            { tag: "markdown", content: input.body },
+            { tag: "hr" },
+            { tag: "action", actions: buttons },
+        ],
+    };
+}
+function buildResolvedCard(summary, kind) {
+    const label = kind === "approved"
+        ? "✅ 已批准"
+        : kind === "remembered"
+            ? "✅ 已批准（本会话内同命令免询问）"
+            : "❌ 已拒绝";
+    const template = kind === "rejected" ? "red" : "green";
+    return {
+        config: { update_multi: true, wide_screen_mode: true },
+        header: {
+            title: { tag: "plain_text", content: `${label}：${summary.title}` },
+            template,
+        },
+        elements: [{ tag: "markdown", content: summary.body }],
+    };
+}
+function buildTimeoutCard(summary) {
+    return {
+        config: { update_multi: true, wide_screen_mode: true },
+        header: {
+            title: { tag: "plain_text", content: `⏱ 超时未响应：${summary.title}` },
+            template: "grey",
+        },
+        elements: [
+            { tag: "markdown", content: summary.body },
+            { tag: "note", elements: [{ tag: "plain_text", content: "60 秒未点击，已自动拒绝" }] },
+        ],
+    };
+}

package/dist/feishu/agent-host/run-driver.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-message driver: takes a user prompt for a given scope, builds an
+ * Agent, and streams its execution to a Feishu interactive card.
+ *
+ * Lifecycle:
+ *   1. Resolve session (cwd + permissionMode) via SessionBinder
+ *   2. Build PermissionAwareApprovalController (UI handler bound to scope)
+ *   3. Construct tools + Agent for this run
+ *   4. Open a streaming card via channel.stream(); inside its producer:
+ *      a. iterate agent.run() events through the RunState reducer
+ *      b. throttle/dispatch ctrl.update() with re-rendered card
+ *   5. Handle abort, error, and idle-timeout terminal states
+ */
+import type { AgentEvent } from "../../types.js";
+import type { BubbleChannel } from "../channel/channel.js";
+import type { ScopeConfig } from "../types.js";
+import type { ScopeKey } from "../types.js";
+import type { FeishuRuntimeDeps } from "./runtime-deps.js";
+import type { FeishuApprovalUI } from "./approval-ui.js";
+import type { SessionBinder } from "../scope/session-binder.js";
+export interface RunDriverOptions {
+    channel: BubbleChannel;
+    deps: FeishuRuntimeDeps;
+    binder: SessionBinder;
+    approvalUI: FeishuApprovalUI;
+    outputThrottleMs: number;
+    idleTimeoutMinutes: number;
+    maxBytesPerElement: number;
+    maxBytesPerCard: number;
+}
+export interface RunRequest {
+    scopeKey: ScopeKey;
+    scope: ScopeConfig;
+    chatId: string;
+    userId: string;
+    prompt: string;
+    replyToMessageId?: string;
+    abortSignal: AbortSignal;
+}
+export declare class RunDriver {
+    private readonly opts;
+    constructor(opts: RunDriverOptions);
+    /**
+     * Execute one run for one message. Returns when the agent has finished
+     * (or been aborted). Throws only on truly unexpected errors — typical
+     * failures (agent error, abort) are reflected in the card.
+     */
+    runOnce(req: RunRequest): Promise<void>;
+    private resolveProvider;
+}
+export type { AgentEvent };

package/dist/feishu/agent-host/run-driver.js

@@ -0,0 +1,302 @@
+/**
+ * Per-message driver: takes a user prompt for a given scope, builds an
+ * Agent, and streams its execution to a Feishu interactive card.
+ *
+ * Lifecycle:
+ *   1. Resolve session (cwd + permissionMode) via SessionBinder
+ *   2. Build PermissionAwareApprovalController (UI handler bound to scope)
+ *   3. Construct tools + Agent for this run
+ *   4. Open a streaming card via channel.stream(); inside its producer:
+ *      a. iterate agent.run() events through the RunState reducer
+ *      b. throttle/dispatch ctrl.update() with re-rendered card
+ *   5. Handle abort, error, and idle-timeout terminal states
+ */
+import chalk from "chalk";
+import { Agent } from "../../agent.js";
+import { BudgetLedger } from "../../agent/budget-ledger.js";
+import { PermissionAwareApprovalController } from "../../approval/controller.js";
+import { BashAllowlist } from "../../approval/session-cache.js";
+import { getLspService } from "../../lsp/index.js";
+import { buildSystemPrompt } from "../../system-prompt.js";
+import { FileStateTracker } from "../../tools/file-state.js";
+import { createAllTools } from "../../tools/index.js";
+import { displayModel, encodeModel, decodeModel } from "../../provider-registry.js";
+import { buildMemoryPrompt, recordMemoryCitations } from "../../memory/index.js";
+import { getDefaultThinkingLevel } from "../../provider-transform.js";
+import { createSessionTitleUpdater } from "../../session-title.js";
+import { applyCardBudget } from "../card/budget.js";
+import { renderCard } from "../card/renderer.js";
+import { createInitialRunState } from "../card/run-state-types.js";
+import { hasInFlightTool, markError, markInterrupted, markIdleTimeout, reduceRunState } from "../card/run-state.js";
+export class RunDriver {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Execute one run for one message. Returns when the agent has finished
+     * (or been aborted). Throws only on truly unexpected errors — typical
+     * failures (agent error, abort) are reflected in the card.
+     */
+    async runOnce(req) {
+        // 1. Resolve session
+        const session = this.opts.binder.openOrBootstrap(req.scopeKey, req.scope.cwd, req.scope.defaultPermissionMode);
+        // 2. Build approval controller wired to FeishuApprovalUI
+        const bashAllowlist = new BashAllowlist();
+        const approvalHandlerRef = {
+            current: this.opts.approvalUI.makeHandler(req.chatId, req.userId),
+        };
+        let agentRef;
+        const approvalController = new PermissionAwareApprovalController({
+            getMode: () => agentRef?.mode ?? session.permissionMode,
+            handlerRef: approvalHandlerRef,
+            bashAllowlist,
+            cwd: session.cwd,
+            getRuleSet: () => this.opts.deps.settingsManager.getMerged().ruleSet,
+        });
+        // 3. Build tools + Agent
+        const lspService = getLspService(session.cwd, this.opts.deps.settingsManager.getMerged().lsp);
+        const fileStateTracker = new FileStateTracker(session.cwd);
+        let agentForPlan;
+        const planController = {
+            getMode: () => agentForPlan?.mode ?? session.permissionMode,
+            requestApproval: async (_plan) => 
+            // Feishu v1: plan mode just reject — encourages agent to summarize first.
+            ({ action: "reject", reason: "Plan approval over Feishu not implemented; use /mode default." }),
+            setMode: (mode) => agentForPlan?.setMode(mode),
+        };
+        const todoStore = {
+            getTodos: () => agentRef?.getTodos() ?? [],
+            setTodos: (todos) => agentRef?.setTodos(todos),
+        };
+        const tools = createAllTools(session.cwd, this.opts.deps.skillRegistry, {
+            todoStore,
+            planController,
+            approvalController,
+            lspService,
+            fileStateTracker,
+            // questionController intentionally omitted — Feishu v1 doesn't surface
+            // the question tool to the agent.
+        });
+        tools.push(...this.opts.deps.mcpManager.getToolEntries());
+        const promptCacheKey = session.manager.getOrCreatePromptCacheKey();
+        const { provider, providerId, model } = await this.resolveProvider(session, promptCacheKey);
+        const skills = this.opts.deps.skillRegistry.summaries();
+        const memoryPrompt = buildMemoryPrompt(session.cwd);
+        const thinkingLevel = this.opts.deps.userConfig.getDefaultThinkingLevel()
+            ?? getDefaultThinkingLevel(providerId, decodeModel(model).modelId);
+        const initialMode = session.permissionMode;
+        const systemPrompt = buildSystemPrompt({
+            agentName: "Bubble",
+            configuredProvider: providerId || "none",
+            configuredModel: model ? displayModel(model) : "none",
+            configuredModelId: model || "none",
+            thinkingLevel,
+            mode: initialMode,
+            workingDir: session.cwd,
+            tools: tools.map((t) => t.name),
+            memoryPrompt,
+        });
+        const budgetLedger = new BudgetLedger();
+        let sessionTitleUpdater;
+        const agent = new Agent({
+            provider,
+            providerId,
+            model,
+            sessionID: session.manager.getSessionFile(),
+            tools,
+            systemPrompt,
+            temperature: 0.2,
+            thinkingLevel,
+            mode: initialMode,
+            todos: session.manager.getTodos(),
+            onMessageAppend: (message) => {
+                if (message.role === "system" || message.role === "meta")
+                    return;
+                session.manager.appendMessage(message);
+                sessionTitleUpdater?.handlePersistedMessage(message);
+                if (message.role === "assistant") {
+                    recordMemoryCitations(session.cwd, message.content);
+                }
+            },
+            onToolResult: (toolName, result) => {
+                if (toolName !== "skill" || result.isError)
+                    return;
+                const match = result.content.match(/^Skill:\s+([^\n]+)$/m);
+                if (match?.[1])
+                    session.manager.appendMarker("skill_activated", match[1].trim());
+            },
+            onTodosUpdate: (todos) => session.manager.appendTodosSnapshot(todos),
+            onModeUpdate: (mode) => {
+                session.manager.appendMarker("mode_switch", mode);
+                this.opts.binder.setMode(req.scopeKey, mode);
+            },
+            budgetLedger,
+            skills,
+            memoryPrompt,
+            fileStateTracker,
+            agentCategories: this.opts.deps.userConfig.getAgentCategories(),
+            providerFactory: (route) => this.opts.deps.createProviderForRoute(route, promptCacheKey),
+        });
+        sessionTitleUpdater = createSessionTitleUpdater({
+            sessionManager: session.manager,
+            complete: (messages, completeOptions) => agent.complete(messages, completeOptions),
+        });
+        agentRef = agent;
+        agentForPlan = agent;
+        session.manager.updateMetadata({
+            ...(agent.model ? { model: agent.model } : {}),
+            cwd: session.cwd,
+            thinkingLevel: agent.thinking,
+            reasoningEffort: agent.thinking,
+        });
+        // Restore prior history into the running Agent instance.
+        if (!session.fresh) {
+            const history = session.manager.getMessages();
+            if (history.length > 0) {
+                agent.messages = [{ role: "system", content: systemPrompt }, ...history];
+                if (agent.mode === "plan")
+                    agent.injectModeReminder();
+            }
+        }
+        // 4. Build RunState + stream the card.
+        const runState = createInitialRunState({
+            scope: {
+                chatId: req.chatId,
+                userId: req.userId,
+                displayName: req.scope.displayName,
+                cwd: session.cwd,
+            },
+            mode: initialMode,
+        });
+        const runToken = `run_${Date.now().toString(36)}`;
+        const budgetOpts = {
+            maxBytesPerElement: this.opts.maxBytesPerElement,
+            maxBytesPerCard: this.opts.maxBytesPerCard,
+        };
+        const collapsible = process.env.BUBBLE_FEISHU_NO_COLLAPSIBLE !== "1";
+        const renderOpts = { budget: budgetOpts, runToken, collapsible };
+        const initialCard = renderCard(runState, renderOpts);
+        // Idle watchdog: aborts the run if no progress AND no in-flight tool
+        // for idleTimeoutMinutes.
+        const idleAbort = new AbortController();
+        const idleMs = this.opts.idleTimeoutMinutes * 60 * 1000;
+        let lastProgressAt = Date.now();
+        const watchdog = setInterval(() => {
+            if (req.abortSignal.aborted)
+                return;
+            if (Date.now() - lastProgressAt < idleMs)
+                return;
+            if (hasInFlightTool(runState)) {
+                lastProgressAt = Date.now();
+                return;
+            }
+            idleAbort.abort();
+        }, Math.min(idleMs / 4, 30_000));
+        const combinedAbort = composeSignals([req.abortSignal, idleAbort.signal]);
+        try {
+            await this.opts.channel.stream(req.chatId, {
+                card: {
+                    initial: initialCard,
+                    producer: async (ctrl) => {
+                        try {
+                            for await (const event of agent.run(req.prompt, session.cwd, { abortSignal: combinedAbort })) {
+                                lastProgressAt = Date.now();
+                                reduceRunState(runState, event);
+                                // Trip event-aware updates: for tool_end and agent_end we
+                                // push immediately; text_delta relies on SDK throttle.
+                                if (event.type === "tool_start" || event.type === "tool_end" || event.type === "agent_end") {
+                                    await ctrl.update(renderCard(runState, renderOpts));
+                                }
+                                else {
+                                    await ctrl.update(renderCard(runState, renderOpts));
+                                }
+                                if (combinedAbort.aborted)
+                                    break;
+                            }
+                        }
+                        catch (err) {
+                            if (req.abortSignal.aborted) {
+                                markInterrupted(runState);
+                            }
+                            else if (idleAbort.signal.aborted) {
+                                markIdleTimeout(runState);
+                            }
+                            else {
+                                markError(runState, err);
+                            }
+                        }
+                        finally {
+                            applyCardBudget(runState, budgetOpts);
+                            await ctrl.update(renderCard(runState, { ...renderOpts, showStopButton: false }));
+                        }
+                    },
+                },
+            }, req.replyToMessageId ? { replyTo: req.replyToMessageId } : undefined);
+        }
+        catch (err) {
+            // Failed before producer started — surface a plain text fallback.
+            try {
+                await this.opts.channel.send(req.chatId, {
+                    text: `❌ Bubble run failed to start: ${err.message}`,
+                });
+            }
+            catch {
+                // If even text send failed, log to stderr.
+                console.error(chalk.red(`[feishu] failed to send fallback: ${err.message}`));
+            }
+        }
+        finally {
+            clearInterval(watchdog);
+            // Cancel any pending approval prompts attached to this run.
+            this.opts.approvalUI.cancelForChat(req.chatId, "Run ended");
+        }
+    }
+    async resolveProvider(session, promptCacheKey) {
+        const registry = this.opts.deps.providerRegistry;
+        const userConfig = this.opts.deps.userConfig;
+        // Read session metadata for an explicit model preference, fall back to
+        // user config, then provider default.
+        const configuredModel = userConfig.getDefaultModel();
+        const defaultProvider = registry.getDefault();
+        const fallbackProviderId = defaultProvider?.id ?? "";
+        const normalizedConfigured = configuredModel
+            ? (configuredModel.includes(":")
+                ? configuredModel
+                : (fallbackProviderId ? encodeModel(fallbackProviderId, configuredModel) : ""))
+            : "";
+        const { providerId: effectiveProviderId, modelId: effectiveModelId } = normalizedConfigured
+            ? decodeModel(normalizedConfigured)
+            : { providerId: undefined, modelId: "" };
+        const activeProviderId = effectiveProviderId || fallbackProviderId;
+        if (registry.supportsOAuth(activeProviderId) && registry.getAuthStorage().has(activeProviderId)) {
+            await registry.prepareProvider(activeProviderId);
+        }
+        const target = registry.getConfigured().find((p) => p.id === activeProviderId) || defaultProvider;
+        if (!target?.apiKey) {
+            throw new Error(`No provider configured — set up one in terminal Bubble before /serve.`);
+        }
+        const activeModel = effectiveModelId
+            ? encodeModel(activeProviderId, effectiveModelId)
+            : "";
+        const provider = this.opts.deps.createProvider(activeProviderId, target.apiKey, target.baseURL, promptCacheKey);
+        return { provider, providerId: activeProviderId, model: activeModel };
+    }
+}
+function composeSignals(signals) {
+    const valid = signals.filter((s) => !!s);
+    if (valid.length === 0)
+        return new AbortController().signal;
+    if (valid.length === 1)
+        return valid[0];
+    const merged = new AbortController();
+    const handler = () => merged.abort();
+    for (const s of valid) {
+        if (s.aborted) {
+            merged.abort();
+            break;
+        }
+        s.addEventListener("abort", handler, { once: true });
+    }
+    return merged.signal;
+}

package/dist/feishu/agent-host/runtime-deps.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Process-level dependencies shared across all Feishu scopes / runs.
+ *
+ * Built once at serve.ts startup. Per-run dependencies (Agent,
+ * SessionManager, ApprovalController) are constructed fresh by the
+ * RunDriver against this shared bundle.
+ */
+import type { McpManager } from "../../mcp/manager.js";
+import type { ProviderRegistry } from "../../provider-registry.js";
+import type { SettingsManager } from "../../permissions/settings.js";
+import type { SkillRegistry } from "../../skills/registry.js";
+import type { UserConfig } from "../../config.js";
+import type { Provider } from "../../types.js";
+export interface FeishuRuntimeDeps {
+    /** Read-only access to settings (allow/deny rules, LSP config). */
+    settingsManager: SettingsManager;
+    /** Provider registry; we resolve the active provider per run. */
+    providerRegistry: ProviderRegistry;
+    /** User config; per-process defaults (model, thinking level, …). */
+    userConfig: UserConfig;
+    /** Skill registry; tools resolve skills against it. */
+    skillRegistry: SkillRegistry;
+    /** Live MCP tool source; tools list includes MCP entries. */
+    mcpManager: McpManager;
+    /** Factory used by main provider + subagent routes. */
+    createProvider: (providerId: string, apiKey: string, baseURL: string, promptCacheKey?: string) => Provider;
+    createProviderForRoute: (route: {
+        providerId: string;
+        model: string;
+    }, promptCacheKey?: string) => Promise<Provider>;
+    /** Resolved owner open_id (from config.app.ownerOpenId). */
+    ownerOpenId: string;
+}

package/dist/feishu/agent-host/runtime-deps.js

@@ -0,0 +1,8 @@
+/**
+ * Process-level dependencies shared across all Feishu scopes / runs.
+ *
+ * Built once at serve.ts startup. Per-run dependencies (Agent,
+ * SessionManager, ApprovalController) are constructed fresh by the
+ * RunDriver against this shared bundle.
+ */
+export {};

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+import type { RunState } from "./run-state-types.js";
+export interface BudgetOptions {
+    maxBytesPerElement: number;
+    maxBytesPerCard: number;
+}
+export declare function utf8Bytes(s: string): number;
+/**
+ * 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 declare function truncateToBytes(text: string, maxBytes: number): string;
+/**
+ * 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 declare function clampBlocksToElementBudget(state: RunState, maxBytesPerElement: number): void;
+/**
+ * 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 declare function applyCardBudget(state: RunState, opts: BudgetOptions): void;