lark-remote 0.5.12 → 0.5.13

package/dist/bridge/run-usage.js

@@ -0,0 +1,96 @@
+import { normalizeResultUsage } from '../runner/common/result-usage.js';
+export class RunUsageCollector {
+    contextLength;
+    finalContextLength;
+    finalContextLimit;
+    finalCompactCount;
+    finalCacheReadTokens;
+    finalCacheCreationTokens;
+    finalTotalTokens;
+    liveInput;
+    liveOutput;
+    liveContextLimit;
+    finalInputTokens;
+    finalOutputTokens;
+    finalCumulativeTotalTokens;
+    finalCumulativeInputTokens;
+    finalCumulativeOutputTokens;
+    finalCumulativeCacheReadTokens;
+    finalCumulativeCacheCreationTokens;
+    finalReasoningTokens;
+    resultNotSuccess = false;
+    get liveInputTokens() {
+        return this.liveInput;
+    }
+    get liveOutputTokens() {
+        return this.liveOutput;
+    }
+    observeCompaction(postTokens) {
+        this.contextLength = postTokens;
+    }
+    observeResult(event) {
+        this.resultNotSuccess = event.subtype !== 'success';
+        if (!event.usage)
+            return;
+        const usage = normalizeResultUsage(event.usage);
+        if (!this.contextLength)
+            this.contextLength = usage.contextLength;
+        this.liveInput = usage.inputTokens;
+        this.liveOutput = usage.outputTokens;
+        this.liveContextLimit = usage.contextLimit;
+        if (usage.cacheReadTokens !== undefined)
+            this.finalCacheReadTokens = usage.cacheReadTokens;
+        if (usage.cacheCreationTokens !== undefined) {
+            this.finalCacheCreationTokens = usage.cacheCreationTokens;
+        }
+        if (usage.totalTokens !== undefined)
+            this.finalTotalTokens = usage.totalTokens;
+        if (usage.reasoningTokens !== undefined)
+            this.finalReasoningTokens = usage.reasoningTokens;
+    }
+    finalize(finalUsage, authority) {
+        this.finalContextLength = finalUsage?.contextLength ?? this.contextLength;
+        this.finalContextLimit = finalUsage?.contextLimit ?? this.liveContextLimit;
+        this.finalCompactCount = finalUsage?.compactCount;
+        this.finalCumulativeTotalTokens = finalUsage?.cumulativeTotalTokens;
+        this.finalCumulativeInputTokens = finalUsage?.cumulativeInputTokens;
+        this.finalCumulativeOutputTokens = finalUsage?.cumulativeOutputTokens;
+        this.finalCumulativeCacheReadTokens = finalUsage?.cumulativeCacheReadTokens;
+        this.finalCumulativeCacheCreationTokens = finalUsage?.cumulativeCacheCreationTokens;
+        const useLiveFlowScope = authority !== 'jsonl' && this.liveInput !== undefined && this.liveOutput !== undefined;
+        if (useLiveFlowScope) {
+            this.finalInputTokens = this.liveInput;
+            this.finalOutputTokens = this.liveOutput;
+            return;
+        }
+        this.finalInputTokens = finalUsage?.inputTokens ?? this.liveInput;
+        this.finalOutputTokens = finalUsage?.outputTokens ?? this.liveOutput;
+        this.finalCacheReadTokens = finalUsage?.cacheReadTokens ?? this.finalCacheReadTokens;
+        this.finalCacheCreationTokens =
+            finalUsage?.cacheCreationTokens ?? this.finalCacheCreationTokens;
+        this.finalTotalTokens = finalUsage?.totalTokens ?? this.finalTotalTokens;
+    }
+    meta() {
+        return {
+            contextLength: this.finalContextLength,
+            contextLimit: this.finalContextLimit,
+            compactCount: this.finalCompactCount,
+            cacheReadTokens: this.finalCacheReadTokens,
+            cacheCreationTokens: this.finalCacheCreationTokens,
+            totalTokens: this.finalTotalTokens,
+            inputTokens: this.finalInputTokens,
+            outputTokens: this.finalOutputTokens,
+            cumulativeTotalTokens: this.finalCumulativeTotalTokens,
+            cumulativeInputTokens: this.finalCumulativeInputTokens,
+            cumulativeOutputTokens: this.finalCumulativeOutputTokens,
+            cumulativeCacheReadTokens: this.finalCumulativeCacheReadTokens,
+            cumulativeCacheCreationTokens: this.finalCumulativeCacheCreationTokens,
+            reasoningTokens: this.finalReasoningTokens,
+        };
+    }
+    logSummary(runId) {
+        const meta = this.meta();
+        return `[lark-remote] final usage runId=${runId} contextLength=${meta.contextLength} contextLimit=${meta.contextLimit ?? 'undefined'} compactCount=${meta.compactCount ?? 'undefined'} cacheRead=${meta.cacheReadTokens ?? 'undefined'} cacheCreate=${meta.cacheCreationTokens ?? 'undefined'}`;
+    }
+}
+//# sourceMappingURL=run-usage.js.map

package/dist/bridge/session-writeback.d.ts

@@ -0,0 +1,18 @@
+import type { AgentKind, TurnStartedEvent } from '../runner/index.js';
+import type { SessionStore } from '../session/index.js';
+interface InitEvent {
+    session_id: string;
+    cwd?: string;
+}
+interface WritebackContext {
+    sessionStore: SessionStore;
+    userId: string;
+    agentKind: AgentKind;
+    cwd: string;
+    sessionEpochAtStart: number;
+    runId: string;
+}
+export declare function writeBackInitSession(ctx: WritebackContext, event: InitEvent): void;
+export declare function writeBackTurnStarted(ctx: WritebackContext, event: TurnStartedEvent): boolean;
+export declare function writeBackResultSession(ctx: WritebackContext, sessionId: string | undefined): void;
+export {};

package/dist/bridge/session-writeback.js

@@ -0,0 +1,36 @@
+import { getLogger } from '../logger/index.js';
+function pointerMoved(ctx) {
+    return ctx.sessionStore.getSessionEpoch(ctx.userId, ctx.agentKind) !== ctx.sessionEpochAtStart;
+}
+export function writeBackInitSession(ctx, event) {
+    if (pointerMoved(ctx)) {
+        getLogger().info(`[lark-remote] system.init write-back skipped: session pointer moved since run start runId=${ctx.runId} sessionId=${event.session_id}`);
+        return;
+    }
+    const eventCwd = typeof event.cwd === 'string' ? event.cwd : '';
+    const hasCwd = !!ctx.sessionStore.getCwd(ctx.userId);
+    const realCwd = eventCwd.length > 0 ? eventCwd : ctx.cwd;
+    if (hasCwd && eventCwd && eventCwd !== ctx.cwd) {
+        getLogger().info(`[lark-remote] system.init: cwd=${ctx.cwd}, session cwd=${eventCwd}`);
+        ctx.sessionStore.setSessionIdAndSessionCwd(ctx.userId, ctx.agentKind, event.session_id, realCwd);
+        return;
+    }
+    const bootstrapSessionCwd = !hasCwd && eventCwd.length > 0 ? eventCwd : undefined;
+    ctx.sessionStore.setSessionIdAndCwd(ctx.userId, ctx.agentKind, event.session_id, realCwd, bootstrapSessionCwd);
+}
+export function writeBackTurnStarted(ctx, event) {
+    if (pointerMoved(ctx)) {
+        getLogger().info(`[lark-remote] turn_started write-back skipped: session pointer moved since run start runId=${ctx.runId} sessionId=${event.threadId}`);
+        return false;
+    }
+    ctx.sessionStore.setSessionIdAndCwd(ctx.userId, ctx.agentKind, event.threadId, ctx.cwd);
+    getLogger().info(`[lark-remote] turn_started session write-back runId=${ctx.runId} sessionId=${event.threadId}`);
+    return true;
+}
+export function writeBackResultSession(ctx, sessionId) {
+    if (!sessionId || pointerMoved(ctx))
+        return;
+    ctx.sessionStore.setSessionIdAndCwd(ctx.userId, ctx.agentKind, sessionId, ctx.cwd);
+    getLogger().info(`[lark-remote] result session write-back runId=${ctx.runId} sessionId=${sessionId}`);
+}
+//# sourceMappingURL=session-writeback.js.map

package/dist/card/bash-card-session.js

@@ -76,11 +76,8 @@ export class BashCardSession extends CardSession {
         if (this.state.terminal !== 'running') {
             return;
         }
-        this.cancelPendingFlush();
-        // 若有 in-flight flush 正在 await updateCard，必须等它完成后再发终态 patch，
-        // 保证顺序（pre-terminal 先落地 → terminal 后落地 → terminal 胜出）。
-        if (this.flushP)
-            await this.flushP;
+        // 终态 patch 必须排在已开始的 pre-terminal flush 之后。
+        await this.prepareTerminalUpdate();
         this.state = {
             ...this.state,
             terminal,

package/dist/card/card-session.d.ts

@@ -117,5 +117,7 @@ export declare abstract class CardSession<S, RO = unknown> {
      * connector.updateCard if the controller is unavailable or fails.
      */
     protected updateCard(): Promise<void>;
+    private waitForControllerReady;
+    protected prepareTerminalUpdate(): Promise<void>;
     protected release(): void;
 }

package/dist/card/card-session.js

@@ -138,17 +138,7 @@ export class CardSession {
             // 二次调用也套 timeout 保护：若 controllerReady 永不 settle（首次超时失败），
             // 不能永久挂起。复用同样的 startTimeoutMs 超时。streamOutcome 已存在，
             // 不重复创建 stream。
-            let timer;
-            const timeout = new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`${this.errorPrefix} stream start timeout`)), this.startTimeoutMs);
-            });
-            try {
-                await Promise.race([this.controllerReady, timeout]);
-            }
-            finally {
-                if (timer)
-                    clearTimeout(timer);
-            }
+            await this.waitForControllerReady();
             return;
         }
         // NOTE: the two renderCard calls below are NOT redundant. The streamCard
@@ -177,17 +167,7 @@ export class CardSession {
                 this.rejectController(error);
             return { ok: false, error };
         });
-        let timer;
-        const timeout = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`${this.errorPrefix} stream start timeout`)), this.startTimeoutMs);
-        });
-        try {
-            await Promise.race([this.controllerReady, timeout]);
-        }
-        finally {
-            if (timer)
-                clearTimeout(timer);
-        }
+        await this.waitForControllerReady();
     }
     async settle() {
         this.release();
@@ -247,6 +227,24 @@ export class CardSession {
             }
         }
     }
+    async waitForControllerReady() {
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${this.errorPrefix} stream start timeout`)), this.startTimeoutMs);
+        });
+        try {
+            await Promise.race([this.controllerReady, timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async prepareTerminalUpdate() {
+        this.cancelPendingFlush();
+        if (this.flushP)
+            await this.flushP;
+    }
     release() {
         if (this.released)
             return;

package/dist/card/card-shared.d.ts

@@ -1,10 +1,10 @@
-import { type AgentKind } from '../runner/index.js';
+import { type AgentKind } from '../runner/types.js';
 /**
  * Display name for an agent kind in the run card header.
  *
- * Reads from the global `AgentRegistry` (set up in `index.ts` at startup)
- * when available. Falls back to a hardcoded map for callers that don't
- * wire up the registry (notably unit tests of pure render helpers).
+ * Display names are static UI labels, so the constant is the single source.
+ * Keeping a second mutable registry here made render helpers depend on startup
+ * order and forced tests to reset global state.
  */
 export declare function agentDisplayName(kind: string): string;
 export declare function terminalToLabel(terminal: string): string;

package/dist/card/card-shared.js

@@ -1,18 +1,12 @@
-import { AgentRegistry } from '../runner/index.js';
 import { AGENT_DISPLAY_NAMES } from '../runner/types.js';
 /**
  * Display name for an agent kind in the run card header.
  *
- * Reads from the global `AgentRegistry` (set up in `index.ts` at startup)
- * when available. Falls back to a hardcoded map for callers that don't
- * wire up the registry (notably unit tests of pure render helpers).
+ * Display names are static UI labels, so the constant is the single source.
+ * Keeping a second mutable registry here made render helpers depend on startup
+ * order and forced tests to reset global state.
  */
 export function agentDisplayName(kind) {
-    const globalReg = AgentRegistry.getGlobalInstance();
-    if (globalReg) {
-        return globalReg.getDisplayName(kind);
-    }
-    // Fallback for render helpers that run without the global registry.
     return AGENT_DISPLAY_NAMES[kind] ?? kind;
 }
 const TERMINAL_LABELS = {

package/dist/card/collapsible.js

@@ -76,8 +76,9 @@ export function markdownDiv(content, textSize) {
  * to be interpreted as a literal. Escape it to preserve the raw backslash.
  *
  * Note: Square brackets [] and pipe | are NOT escaped -- they are valid markdown
- * (links, tables) and escaping them breaks link rendering. Verified safe via
- * tests/escape-bracket-experiment.test.ts: unescaped []| does not trigger 11311.
+ * (links, tables) and escaping them breaks link rendering. Verified by the live
+ * regression test tests/feishu-live/escape-bracket-regression.test.ts: unescaped
+ * []| does not trigger 11311.
  */
 function escapeMarkdown(content) {
     if (!content)

package/dist/card/final-answer-overflow.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Split an authoritative final answer into plain-text messages without losing
+ * any content. Feishu cards have a hard size budget; a long answer must spill
+ * rather than being silently truncated inside the progress card.
+ */
+export declare const FINAL_ANSWER_CHUNK_BYTES = 20000;
+export declare function splitFinalAnswer(text: string, maxBytes?: number): string[];

package/dist/card/final-answer-overflow.js

@@ -0,0 +1,46 @@
+/**
+ * Split an authoritative final answer into plain-text messages without losing
+ * any content. Feishu cards have a hard size budget; a long answer must spill
+ * rather than being silently truncated inside the progress card.
+ */
+export const FINAL_ANSWER_CHUNK_BYTES = 20_000;
+export function splitFinalAnswer(text, maxBytes = FINAL_ANSWER_CHUNK_BYTES) {
+    if (!text || maxBytes <= 0)
+        return text ? [text] : [];
+    const chunks = [];
+    let rest = text;
+    let remainingBytes = Buffer.byteLength(rest, 'utf8');
+    while (remainingBytes > maxBytes) {
+        let bytes = 0;
+        let end = 0;
+        let lastNewline = 0;
+        for (const char of rest) {
+            const charBytes = Buffer.byteLength(char, 'utf8');
+            if (bytes + charBytes > maxBytes)
+                break;
+            bytes += charBytes;
+            end += char.length;
+            if (char === '\n')
+                lastNewline = end;
+        }
+        if (end === 0) {
+            // A caller can choose a byte limit smaller than one codepoint. Keep one
+            // codepoint per chunk rather than looping forever with a zero-length cut.
+            const first = Array.from(rest)[0];
+            chunks.push(first);
+            rest = rest.slice(first.length);
+            remainingBytes -= Buffer.byteLength(first, 'utf8');
+            continue;
+        }
+        // Prefer a paragraph/line boundary when it does not waste most of a chunk.
+        const cut = lastNewline > 0 && lastNewline >= Math.floor(end * 0.6) ? lastNewline : end;
+        const chunk = rest.slice(0, cut);
+        chunks.push(chunk);
+        rest = rest.slice(cut);
+        remainingBytes -= Buffer.byteLength(chunk, 'utf8');
+    }
+    if (rest)
+        chunks.push(rest);
+    return chunks;
+}
+//# sourceMappingURL=final-answer-overflow.js.map

package/dist/card/run-card-session.js

@@ -46,13 +46,8 @@ export class RunCardSession extends CardSession {
     }
     async finish(terminal, meta = {}) {
         // 终态必须即时显示（spec）：取消合批窗口，不等延迟 flush 调度。
-        this.cancelPendingFlush();
-        // 若有 in-flight flush 正在 await updateCard，必须等它完成后再发终态 patch。
-        // 否则两条并发 controller.update 无 FIFO 保证，in-flight 的 pre-terminal
-        // patch 可能在终态 patch 之后 resolve → 用户看到"思考中"终帧。
-        // await 保证顺序：pre-terminal 先落地 → terminal 后落地 → terminal 胜出。
-        if (this.flushP)
-            await this.flushP;
+        // 终态 patch 必须排在已开始的 pre-terminal flush 之后。
+        await this.prepareTerminalUpdate();
         this.state = finishRun(this.state, terminal, meta);
         await this.updateCard();
         this.release();

package/dist/card/run-renderer.d.ts

@@ -20,6 +20,12 @@ export interface RunCardRenderOptions {
      */
     sessionFallbackAvailable?: boolean;
 }
+export interface RunCardRenderOutcome {
+    card: object;
+    finalAnswerStatus: 'none' | 'full' | 'overflow';
+    /** Full text to deliver outside the card when finalAnswerStatus is overflow. */
+    finalAnswerText?: string;
+}
 type BlockGroup = {
     kind: 'thinking';
     content: string;
@@ -73,4 +79,12 @@ export declare function estimateCardBytes(state: RunState, options?: RunCardRend
  * CardKit 2.0 renderer - simplified for streaming (no tabs)
  */
 export declare function renderRunCard(state: RunState, options?: RunCardRenderOptions): object;
+/**
+ * Render a run card with metadata the bridge needs to deliver an answer that
+ * cannot fit in one Feishu card. `renderRunCard` remains the card-only API used
+ * by streaming sessions.
+ */
+export declare function renderRunCardDetailed(state: RunState, options?: RunCardRenderOptions): RunCardRenderOutcome;
+/** Exact-match marker used in the card before the answer is sent separately. */
+export declare const FINAL_ANSWER_OVERFLOW_MARKER = "_\u6700\u7EC8\u56DE\u7B54\u8F83\u957F\uFF0C\u5B8C\u6574\u5185\u5BB9\u5DF2\u968F\u540E\u53D1\u9001_";
 export {};

package/dist/card/run-renderer.js

@@ -867,6 +867,20 @@ function measurePanelBytes(title, expanded, border, content) {
  * CardKit 2.0 renderer - simplified for streaming (no tabs)
  */
 export function renderRunCard(state, options = {}) {
+    return renderRunCardDetailed(state, options).card;
+}
+/**
+ * Render a run card with metadata the bridge needs to deliver an answer that
+ * cannot fit in one Feishu card. `renderRunCard` remains the card-only API used
+ * by streaming sessions.
+ */
+export function renderRunCardDetailed(state, options = {}) {
+    if (state.finalAnswer?.content.trim()) {
+        return buildFinalAnswerPriorityCard(state, options);
+    }
+    return { card: renderLegacyRunCard(state, options), finalAnswerStatus: 'none' };
+}
+function renderLegacyRunCard(state, options) {
     // 先估后建：用廉价估算预测是否超 28KB 预算，明显超预算直接跳过完整卡构建走
     // degraded。groups/prepared 只算一次，测量与正式渲染共用同一份截断结果，
     // 避免影子测量 + 正式渲染对每个超限块双倍截断。
@@ -927,6 +941,110 @@ export function renderRunCard(state, options = {}) {
     };
     return truncatedSkeleton;
 }
+/** Exact-match marker used in the card before the answer is sent separately. */
+export const FINAL_ANSWER_OVERFLOW_MARKER = '_最终回答较长，完整内容已随后发送_';
+/**
+ * Build a card around the authoritative final answer.
+ *
+ * The answer is measured first with the fixed controls. Progress groups are
+ * added newest-first only while the whole card still fits. If the answer
+ * cannot fit even without progress/summary, the card carries an explicit
+ * marker and the bridge sends the complete answer separately.
+ */
+function buildFinalAnswerPriorityCard(state, options) {
+    const finalAnswer = state.finalAnswer;
+    const groups = groupBlocks(state.blocks);
+    const prepared = prepareGroupContent(groups);
+    const safeAnswer = truncateMarkdownTables(finalAnswer.content);
+    const requiresOverflow = safeAnswer !== finalAnswer.content;
+    const ts = formatTimestamp(finalAnswer.timestamp);
+    const answerElements = renderTextBlock(safeAnswer, ts, state.terminal !== 'running');
+    const fixedStart = [statusRow(state), ...omittedBlocksHint(state)];
+    const summary = buildSummaryContent(state, { includeNotices: false });
+    const controls = [...actionRow(state, options), ...approvalArea(state)];
+    const buildWithProgress = (start, includeSummary) => {
+        const renderedProgress = buildAnswerProgressContent(state, prepared, groups.slice(start));
+        const progress = start < groups.length
+            ? [markdownDiv(`_💡 已省略 ${start} 个早期步骤_`), ...renderedProgress]
+            : renderedProgress;
+        return assembleRunCard(state, options, [
+            ...fixedStart,
+            ...progress,
+            ...(requiresOverflow ? [markdownDiv(FINAL_ANSWER_OVERFLOW_MARKER)] : []),
+            ...answerElements,
+            ...(includeSummary ? summary : []),
+            ...controls,
+        ]);
+    };
+    let best = buildWithProgress(groups.length, true);
+    if (withinRunCardBudget(best)) {
+        for (let start = groups.length - 1; start >= 0; start--) {
+            const candidate = buildWithProgress(start, true);
+            if (!withinRunCardBudget(candidate))
+                break;
+            best = candidate;
+        }
+        return {
+            card: best,
+            finalAnswerStatus: requiresOverflow ? 'overflow' : 'full',
+            ...(requiresOverflow ? { finalAnswerText: finalAnswer.content } : {}),
+        };
+    }
+    // The answer outranks the usage summary. Keep the answer and controls first,
+    // then retry without the summary before declaring a physical overflow.
+    const withoutSummary = buildWithProgress(groups.length, false);
+    if (withinRunCardBudget(withoutSummary)) {
+        return {
+            card: withoutSummary,
+            finalAnswerStatus: requiresOverflow ? 'overflow' : 'full',
+            ...(requiresOverflow ? { finalAnswerText: finalAnswer.content } : {}),
+        };
+    }
+    const overflowCard = assembleRunCard(state, options, [
+        ...fixedStart,
+        markdownDiv(FINAL_ANSWER_OVERFLOW_MARKER),
+        ...controls,
+    ]);
+    return {
+        card: overflowCard,
+        finalAnswerStatus: 'overflow',
+        finalAnswerText: finalAnswer.content,
+    };
+}
+/** Render a contiguous progress suffix for the answer-priority card. */
+function buildAnswerProgressContent(state, prepared, visible) {
+    const elements = [];
+    const outputMax = toolOutputBudget(state);
+    const contentItems = mergeNoticesIntoContent(visible, state.notices);
+    for (const item of contentItems) {
+        if (item.kind === 'notice') {
+            elements.push(renderNoticeRow(item.notice));
+            continue;
+        }
+        const group = item;
+        if (group.kind === 'tool') {
+            elements.push(renderTool(group.tool, outputMax));
+            continue;
+        }
+        if (group.kind === 'text') {
+            const content = prepared.get(group) ?? '';
+            const ts = formatTimestamp(group.timestamp);
+            elements.push(...renderTextBlock(content, ts, state.terminal !== 'running'));
+            continue;
+        }
+        const spec = describePanelGroup(group, prepared);
+        if (!spec)
+            continue;
+        elements.push(collapsibleMarkdownPanel({
+            title: spec.title,
+            expanded: spec.expanded,
+            border: spec.border,
+            content: spec.content,
+            textSize: 'notation',
+        }));
+    }
+    return elements;
+}
 /**
  * Run 卡片的双预算检查：UTF-8 字节 ≤ 28KB **且** 元素数 ≤ `MAX_CARD_ELEMENTS`。
  *
@@ -1037,7 +1155,7 @@ function buildSummaryContent(state, options = {}) {
     }
     else {
         const result = state.resultSubtype ?? 'success';
-        const hasContent = state.blocks.length > 0;
+        const hasContent = state.blocks.length > 0 || !!state.finalAnswer?.content.trim();
         // 压缩（operationKind='compaction'）不会返回 agent 正文——引擎只压缩上下文
         // 窗口，空内容属正常，不能沿用普通 run 的「（未返回内容）」异常信号
         // （2026-09 用户反馈）。所有会压缩的 agent（codex/claude/kimi/opencode/pi）

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

@@ -13,7 +13,7 @@ export type RunTerminal = 'running' | 'finalizing' | 'done' | 'error' | 'interru
  * 禁止各自再抄一份字面量——三处漂移过一次（goal_continuing 只进白名单不进
  * 按钮判据），新增终态时必漏一处的风险是结构性的。
  */
-export declare const RUN_TERMINAL_STATES: readonly ["done", "error", "interrupted", "idle_timeout", "goal_continuing"];
+declare const RUN_TERMINAL_STATES: readonly ["done", "error", "interrupted", "idle_timeout", "goal_continuing"];
 export type RunFinalTerminal = (typeof RUN_TERMINAL_STATES)[number];
 /** 该状态是否已收尾（非 running/finalizing）。 */
 export declare function isRunTerminal(terminal: RunTerminal): terminal is RunFinalTerminal;
@@ -85,6 +85,12 @@ export interface RunNotice {
     text: string;
     timestamp?: string;
 }
+export interface FinalAnswerState {
+    content: string;
+    timestamp?: string;
+    complete: boolean;
+    source: 'protocol' | 'inferred';
+}
 export interface RunState {
     runId: string;
     terminal: RunTerminal;
@@ -94,6 +100,11 @@ export interface RunState {
     /** 本 run 结束时间（epoch ms）：终态后耗时定格，不再随渲染时刻增长。 */
     finishedAt?: number;
     blocks: RunBlock[];
+    /**
+     * The answer the user is waiting for. Kept outside `blocks` so progress
+     * traffic cannot evict or consume its display budget.
+     */
+    finalAnswer?: FinalAnswerState;
     sessionId?: string;
     resultSubtype?: 'success' | 'error' | 'interrupted';
     /** interrupted 终态的中断来源；undefined = 未归类（渲染默认文案）。 */