Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { hasRichAnswer } from './richAnswer';
import { groupWorkRuns } from './workRunGrouping.js';
import { isContinuationMessage } from './syntheticTrigger.js';
export { groupWorkRuns, type WorkRunGroupingAdapter } from './workRunGrouping.js';
import {
type AgentTaskTerminalStatus,
type AgentTaskUpdate,
deriveAgentTaskStatus,
findAgentTaskUpdate,
isAgentTaskToolName,
subagentSpawnReceiptName,
subagentSpawnResultIndicatesRunning,
} from './agentTask';
import { HISTORY_GAP_SPLIT_MS } from './historyGap';
export interface MessageRenderSourceMessageLike {
id?: string | null;
clientId?: string | null;
role?: string | null;
content?: unknown;
createdAt?: string;
/** Renderer-local time of the latest in-place plan payload update. */
planUpdatedAtMs?: number;
toolName?: string | null;
toolInput?: unknown;
/** SDK tool-use id — used to link a Task/collab tool-call to its live `agent_task_update`. */
toolUseId?: string | null;
/**
* Owning Agent/Task tool-use id when this message was produced inside a
* subagent. Plan scanning treats it as an ownership boundary: subagent plan
* calls never compete for the top-level pinned panel.
*/
parentToolUseId?: string | null;
/**
* Host-persisted message metadata. Plan ownership only reads two keys:
* `autoResume` / `origin` — user rows carrying either are internal dispatches
* (auto-resume continuation, scheduler runs), not the user opening a new
* topic, so they must not cut a plan session boundary.
*
* Surfaces that strip `agentMeta` during projection (desktop renderer's
* ChatMessage) must instead carry the projected flags below.
*/
agentMeta?: Record<string, unknown> | null;
/** Desktop renderer projection of synthetic trigger rows (auto-resume 等)。 */
isSyntheticTrigger?: boolean;
/** Desktop renderer projection of scheduler-originated user rows. */
automationOrigin?: unknown;
/** Host-persisted SDK turn boundary on the final assistant or owning Codex plan row. */
turnCompleted?: boolean;
/**
* Host sealed this Codex plan row because its owning turn ended successfully.
* The seal closes the plan's lifecycle only — step statuses stay exactly as the
* agent last reported them. Interrupted, failed, and auto-resumed turns never
* seal, so their plan stays open while the task itself is still alive.
*/
terminalPlanSnapshot?: boolean;
/** Host time when the successful turn seal was applied. */
terminalPlanAtMs?: number;
/**
* user 消息投递方式:'steer' 是运行中插话,不开启新 turn——失败印记回扫的
* turn 所有权边界只认普通('turn')user 消息。
*/
delivery?: string | null;
}
export type MessageRenderNormalizedMessageKind =
| 'user'
| 'assistant'
| 'tool'
| 'thinking'
| 'ask_user'
| 'plan_review'
| 'system';
/**
* tool 消息携带的产出媒体的最小形状(agent 出图/出视频等,tool_result 里提取)。
* 只声明分组/去重所需字段;消费端(mobile 等)的完整媒体类型结构性兼容本形状,
* 经 `dedupeToolMediaByUrl` 的泛型签名保留原类型,渲染时可读到全量字段。
*/
export interface MessageRenderToolMediaLike {
kind: string;
url: string;
title?: string;
}
export interface MessageRenderNormalizedMessage<
TSource extends MessageRenderSourceMessageLike = MessageRenderSourceMessageLike,
> {
key: string;
source: TSource;
kind: MessageRenderNormalizedMessageKind;
label: string;
body: string;
secondaryBody?: string;
createdAt: string;
isStreaming?: boolean;
/**
* tool 消息专用:配对 tool_result 的落库时刻(ISO)。`createdAt` 是**调用发起**时刻,
* 单靠它无法知道一次工具调用什么时候结束 —— 于是一个跑了半小时以上的调用(长 Bash、
* 子 agent)后面紧跟的下一个调用会被空洞判定误伤,把一段连续工作切碎。空洞锚点优先取
* 本字段,与桌面 `MessageStream` 的 resultTsMap 同口径。缺失(结果未到 / 老数据)时退回
* `createdAt`。
*/
settledAt?: string;
/** Durable terminal lifecycle for an Agent/Task tool call. */
agentTaskStatus?: AgentTaskTerminalStatus;
/** Host 在 SDK done 边界写入。同一 user turn 的最后一次 seal 是最终答复;更早的 seal 只在带交付内容时留在工作过程外。 */
turnCompleted?: boolean;
/** SDK-proven failed sampling output remains readable inside the work fold. */
failedSamplingAttempt?: boolean;
/** tool 消息专用:配对 tool_result 提取出的产出媒体(驱动 tool_media 独立渲染项)。 */
media?: readonly MessageRenderToolMediaLike[];
files?: readonly { url: string; title: string }[];
cardIds?: readonly string[];
}
export interface MessageRenderOptions {
isSessionStreaming?: boolean;
/**
* Gate for the orphan `agent_task` sweep. Callers whose `isSessionStreaming` is broader
* than "a remote turn is running" (e.g. mobile also sets it for local sending/queueing,
* before the first remote status event arrives) should pass the narrow remote-turn signal
* here, so stale leftover updates can't flash during the send→status gap. Defaults to
* `isSessionStreaming` when omitted.
*/
renderOrphanTaskUpdates?: boolean;
}
export interface MessageRenderTodoItem {
content: string;
status: 'pending' | 'in_progress' | 'completed';
activeForm?: string;
}
export interface MessageRenderMessageItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> {
type: 'message';
key: string;
message: TMessage;
}
export interface MessageRenderThinkingItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> {
type: 'thinking';
key: string;
message: TMessage;
durationMs?: number;
redacted: boolean;
}
export interface MessageRenderToolGroupItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> {
type: 'tool_group';
key: string;
tools: TMessage[];
}
export interface MessageRenderTodoCardItem {
type: 'todo';
key: string;
todos: MessageRenderTodoItem[];
createdAt: string;
/** True only while this plan card belongs to the session's active unsettled tail. */
isStreaming?: boolean;
}
/**
* tool 产出媒体的独立渲染项(对齐桌面 MessageStream 的 'tool_media' RenderItem):
* agent 出的图/视频(lizi_art、飞书拉图等)跳出 tool_group 折叠,作为聊天流里
* 独立可见的视觉消息渲染在所属 tool_group 之后。携带的是产出媒体的 tool 消息
* 引用(同一 normalized 对象),渲染端经 `dedupeToolMediaByUrl` 拿到按 url 去重
* 的完整媒体列表。刻意不进 MessageRenderWorkChildItem —— 「工作过程」折叠时
* 产物继续留在折叠块外可见(与桌面语义一致)。
*/
export interface MessageRenderToolMediaItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> {
type: 'tool_media';
key: string;
/** 本组内携带媒体的 tool 消息(按组内顺序)。 */
tools: TMessage[];
}
/**
* A sub-agent task (Claude `Task`/`Agent`, Codex `collab:*`). Carries the originating
* tool-call (when persisted/known) and/or the live `agent_task_update`. Either may be
* absent: a linked card has both, an orphan live update has only `update`.
*/
export interface MessageRenderAgentTaskItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> {
type: 'agent_task';
key: string;
toolCall?: TMessage;
update?: AgentTaskUpdate;
createdAt: string;
}
export type MessageRenderWorkChildItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> =
| MessageRenderThinkingItem<TMessage>
| MessageRenderToolGroupItem<TMessage>
| MessageRenderTodoCardItem
| MessageRenderAgentTaskItem<TMessage>
| MessageRenderMessageItem<TMessage>
| MessageRenderWorkGroupItem<TMessage>;
export interface MessageRenderWorkGroupItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> {
type: 'work_group';
key: string;
children: MessageRenderWorkChildItem<TMessage>[];
deferred?: import('./historyView.js').DeferredHistoryWork;
durationMs?: number;
/** True only for the trailing activity run in an active turn. */
isStreaming?: boolean;
/** Epoch milliseconds of the first real activity, for a live elapsed timer. */
startedAtMs?: number;
}
export type MessageRenderItem<
TMessage extends MessageRenderNormalizedMessage = MessageRenderNormalizedMessage,
> =
| MessageRenderMessageItem<TMessage>
| MessageRenderThinkingItem<TMessage>
| MessageRenderToolGroupItem<TMessage>
| MessageRenderToolMediaItem<TMessage>
| MessageRenderTodoCardItem
| MessageRenderAgentTaskItem<TMessage>
| MessageRenderWorkGroupItem<TMessage>;
export type MessageRenderTodoSource = 'todo' | 'codex' | 'task';
export interface MessageRenderTodoInsertion {
key: string;
todos: MessageRenderTodoItem[];
/** 组成同一计划 session 的全部工具行,用于历史 prepend 后恢复旧滚动锚点。 */
sourceClientIds: string[];
createdAt?: string;
updatedAtMs?: number;
source: MessageRenderTodoSource;
/**
* 这份计划所属的 turn 已被 host 判定为成功收尾(见
* `MessageRenderSourceMessageLike.terminalPlanSnapshot`)。常驻面板据此退场,
* 不看勾选状态;未盖章就一直挂着。
*/
sealed?: boolean;
/** Persisted host time of the successful terminal seal. */
sealedAtMs?: number;
/**
* host 在中断/失败 turn 给该计划行盖的 `turnCompleted: false`(见
* `persistCodexPlanOnDone`):在下一个真实 user turn 取代它前,常驻面板不得按
* "全勾完"兜底退场。
*/
turnFailed?: boolean;
}
export interface MessageRenderLatestTodoState {
insertion: MessageRenderTodoInsertion | null;
hasPlanEvent: boolean;
isResolved: boolean;
latestPlanIndex: number;
latestInsertionIndex: number;
}
export interface MessageRenderTodoGroupingOptions {
keyPrefix?: string;
/** True when the loaded window may omit TaskCreate events or contain history gaps. */
taskHistoryMayBeIncomplete?: boolean;
}
const TASK_PLAN_TOOL_NAMES = new Set(['TaskCreate', 'TaskUpdate', 'TaskList', 'TaskGet']);
export function buildMessageRenderItems<
TMessage extends MessageRenderNormalizedMessage,
>(
messages: readonly TMessage[],
options: MessageRenderOptions = {},
taskUpdates?: ReadonlyMap<string, AgentTaskUpdate>,
): MessageRenderItem<TMessage>[] {
return groupMessageWorkRuns(
buildLinearItems(
messages,
taskUpdates,
options.renderOrphanTaskUpdates ?? (options.isSessionStreaming === true),
),
options.isSessionStreaming === true,
);
}
function buildLinearItems<
TMessage extends MessageRenderNormalizedMessage,
>(
messages: readonly TMessage[],
taskUpdates?: ReadonlyMap<string, AgentTaskUpdate>,
includeOrphanTaskUpdates = false,
): MessageRenderItem<TMessage>[] {
const sourceMessages = messages.map((message) => message.source);
const todoInsertAt = findMessageTodoInsertions(sourceMessages);
const agentPlanToolUseIds = collectAgentPlanToolUseIds(sourceMessages);
const items: MessageRenderItem<TMessage>[] = [];
// Keys (toolUseId / clientId / taskId / parentToolUseId) already surfaced as an inline
// agent_task card, so the orphan-update sweep below doesn't render the same task twice.
const renderedTaskKeys = new Set<string>();
let pendingTools: TMessage[] = [];
// 段内已见过的最晚**结束**时刻(调用发起 / 结果落库取最大值),空洞判定的锚点。
// 不能只比紧邻的上一条:并行工具会乱序完成(A 跑 40 分钟还没回,B 紧随其后一分钟就结束,
// 这时又发起 C),只比 B 的早结束时间会把 C 误判成空洞、把一段连续工作切碎
// (与桌面 MessageStream 的 pendingSegmentEndMs 同口径)。
let pendingToolsEndMs: number | null = null;
const notePendingToolEnd = (ms: number | null) => {
if (ms === null) return;
pendingToolsEndMs = pendingToolsEndMs === null ? ms : Math.max(pendingToolsEndMs, ms);
};
const flushTools = () => {
pendingToolsEndMs = null;
if (pendingTools.length === 0) return;
items.push({
type: 'tool_group',
key: `tools-${messageClientId(pendingTools[0])}`,
tools: pendingTools,
});
// tool 产出媒体(agent 出图等)提为独立 tool_media 项,紧跟所属 tool_group,
// 跳出折叠卡可见(对齐桌面 MessageStream flushSegment)。key 派生自组首 tool
// 的 clientId(与 tool_group 同源、prefix 不同),流式中组内新增 tool 时稳定。
const mediaTools = pendingTools.filter((tool) => (tool.media?.length ?? 0) > 0 || (tool.files?.length ?? 0) > 0 || (tool.cardIds?.length ?? 0) > 0);
if (dedupeToolMediaByUrl(mediaTools.flatMap((tool) => tool.media ?? [])).length > 0
|| mediaTools.some((tool) => (tool.files?.length ?? 0) > 0 || (tool.cardIds?.length ?? 0) > 0)) {
items.push({
type: 'tool_media',
key: `media-${messageClientId(pendingTools[0])}`,
tools: mediaTools,
});
}
pendingTools = [];
};
for (let index = 0; index < messages.length; index++) {
const message = messages[index];
if (message.kind === 'tool') {
if (isAgentPlanToolResult(message.source, agentPlanToolUseIds)) {
continue;
}
const toolName = toolNameOf(message.source);
if (isAgentTaskToolName(toolName)) {
flushTools();
const toolUseId = message.source.toolUseId ?? null;
const clientId = message.source.clientId ?? message.source.id ?? null;
const update = findAgentTaskUpdate(taskUpdates, toolUseId, clientId);
const linkKey = toolUseId ?? clientId ?? messageClientId(message);
renderedTaskKeys.add(linkKey);
if (update?.taskId) renderedTaskKeys.add(update.taskId);
if (update?.parentToolUseId) renderedTaskKeys.add(update.parentToolUseId);
items.push({
type: 'agent_task',
key: `task-${linkKey}`,
toolCall: message,
update,
createdAt: message.createdAt,
});
continue;
}
if (isAgentPlanToolName(toolName)) {
const insertion = todoInsertAt.get(index);
if (insertion) {
flushTools();
items.push({
type: 'todo',
key: insertion.key,
todos: insertion.todos,
createdAt: message.createdAt,
isStreaming: false,
});
}
continue;
}
// 历史窗口空洞可能正好落在两次工具调用之间(缺的是 user 行):那样两段窗口的调用会被
// 合进同一个 tool_group,组首尾时间差直接成了跨空洞的假时长,而工作组分组只看组首时间、
// 发现不了组内部的跳变。所以段内也按同一阈值切开,让「已工作 Xs」的时长和分组都落在
// 真实连续的动作上(对齐桌面 MessageStream 的段内切分)。
const callMs = parseTimestampMs(message.createdAt);
if (
pendingTools.length > 0
&& pendingToolsEndMs !== null
&& callMs !== null
&& callMs - pendingToolsEndMs > HISTORY_GAP_SPLIT_MS
) {
flushTools();
}
pendingTools.push(message);
notePendingToolEnd(callMs);
notePendingToolEnd(parseTimestampMs(message.settledAt));
continue;
}
flushTools();
if (message.kind === 'thinking') {
const thinking = parseThinking(message.source);
items.push({
type: 'thinking',
key: `thinking-${messageClientId(message)}`,
message,
durationMs: thinking.durationMs,
redacted: thinking.redacted,
});
continue;
}
items.push({
type: 'message',
key: `message-${messageClientId(message)}`,
message,
});
}
flushTools();
if (includeOrphanTaskUpdates) {
appendOrphanAgentTasks(items, taskUpdates, renderedTaskKeys);
}
return items;
}
/**
* Render live task updates that never matched a persisted tool-call (e.g. Codex collab
* agents whose spawning tool-call hasn't reached this client). Appended after the linear
* pass; de-duped against tasks already shown inline via `renderedTaskKeys`.
*
* Only invoked while the session is actively running (`isSessionStreaming`): an orphan is a
* LIVE placeholder for a tool-call that hasn't been persisted/delivered yet. When the session
* is idle, unmatched updates are stale leftovers (e.g. the originating tool-call slid out of
* the paged message window) — rendering them would replay old sub-agent cards at the tail of
* the conversation.
*/
function appendOrphanAgentTasks<
TMessage extends MessageRenderNormalizedMessage,
>(
items: MessageRenderItem<TMessage>[],
taskUpdates: ReadonlyMap<string, AgentTaskUpdate> | undefined,
renderedTaskKeys: ReadonlySet<string>,
): void {
if (!taskUpdates) return;
const seenTaskIds = new Set<string>();
for (const update of taskUpdates.values()) {
const primaryKey = update.parentToolUseId ?? update.taskId;
if (
seenTaskIds.has(update.taskId)
|| renderedTaskKeys.has(primaryKey)
|| renderedTaskKeys.has(update.taskId)
) {
continue;
}
seenTaskIds.add(update.taskId);
items.push({
type: 'agent_task',
key: `task-update-${primaryKey}`,
update,
createdAt: update.updatedAt ?? update.createdAt ?? '',
});
}
}
/**
* tool 产出媒体按 url 去重(丢弃空 url):同一 segment 内多个 tool_result 引用同一
* 张图时只渲染一次,保持插入顺序与 tool 调用顺序一致(对齐桌面 flushSegment 的
* de-dup)。泛型保留调用方的完整媒体类型(mobile 的 NormalizedToolMedia 等)。
*/
export function dedupeToolMediaByUrl<TMedia extends MessageRenderToolMediaLike>(
media: readonly TMedia[],
): TMedia[] {
const seen = new Set<string>();
const out: TMedia[] = [];
for (const item of media) {
if (!item.url || seen.has(item.url)) continue;
seen.add(item.url);
out.push(item);
}
return out;
}
/**
* 计划所有权的**唯一** user 边界判据:这个 user 行是不是"用户真的开口"的反面。
*
* 落在 user 行上但不构成边界的四类:
* - 自动续跑 / scheduler 定时消息(agentMeta.autoResume / origin;desktop 渲染层
* 投影成 isSyntheticTrigger / automationOrigin 后丢弃原 meta,两套字段都认):
* 同一件事的延续,当边界会把进行中的计划切成新 session、历史里出现重复计划卡;
* - 同轮 steer 插话:turn 还在跑,用户在指挥进行中的活,不是开新话题
* (MessageStream 的 turn 分组同样把 steer 排除在新 turn 边界外);
* - 子代理内部的 user 行(带 parentUuid / parentToolUseId):子任务的输入,当边界
* 会顶掉主线程计划、换 key 重挂载 TodoListCard。
*
* **计划分组(findMessageTodoInsertions)与失败回扫(markCodexPlanTurnFailed)共用
* 这一份判据**。两边各自推导过一次,结果是回扫只豁免了 steer:计划之后经过一次
* 自动续跑再以 terminal error 收尾时,回扫在合成 user 行上提前 break、够不到本轮
* 计划,全勾完的失败计划先按旧数据退场,等 main 的异步印记广播才复活(手机端断连
* 则要到重新加载,review P2)。
*/
function isSyntheticUserRow(message: MessageRenderSourceMessageLike): boolean {
if (isHookUserRow(message)) return false;
const meta = message.agentMeta;
return (
message.isSyntheticTrigger === true ||
(message.automationOrigin !== undefined && message.automationOrigin !== null) ||
meta?.autoResume === true ||
(meta?.origin !== undefined && meta?.origin !== null) ||
isSteerUserRow(message) ||
hasSubagentParent(message)
);
}
/**
* 会为计划开启新所有权 turn 的真实 user 行。
*
* 计划分组、失败回扫与置顶计划退场必须共用同一判据,避免一个界面已经把
* 输入视为新 turn,另一个界面却继续展示上一轮计划。
*/
export function isPlanUserBoundary(message: MessageRenderSourceMessageLike): boolean {
return message.role === 'user' && !isSyntheticUserRow(message);
}
function isHookUserRow(message: MessageRenderSourceMessageLike): boolean {
const hookSource =
(message as Record<string, unknown>).hookSource ??
message.agentMeta?.hookSource;
return hookSource !== undefined && hookSource !== null;
}
/**
* 子代理归属判定:desktop 投影出顶层 parentToolUseId;mobile / main 原始行只有
* agentMeta.parentUuid。二者任一存在即视为子代理内部消息。
*/
function hasSubagentParent(message: MessageRenderSourceMessageLike): boolean {
const explicit =
message.parentToolUseId ??
message.agentMeta?.parentToolUseId ??
message.agentMeta?.parent_tool_use_id;
if (typeof explicit === 'string' && explicit.trim().length > 0) {
// 显式的 tool-parent 字段本身就是归属证明,不需要形态消歧。
return isSubagentParentId(explicit) || !looksLikeLegacyTranscriptUuid(explicit);
}
// 裸 parentUuid 不足以证明子代理归属:旧 Claude 导入把普通 transcript 链边
// 也存在这个字段(同 latestMessageText.logic.ts 的既定判据),把它一律当子
// 代理会让旧会话的顶层计划被面板与对账整段过滤掉。只认 SDK tool-use id 形态。
const nested = (message as { source?: { agentMeta?: Record<string, unknown> | null } }).source;
for (const candidate of [message.agentMeta?.parentUuid, nested?.agentMeta?.parentUuid]) {
if (typeof candidate === 'string' && isSubagentParentId(candidate)) return true;
}
return false;
}
/** Live Claude/Codex SDK tool-use ids;裸 uuid 形态的 legacy transcript 链边不算。 */
const SUBAGENT_PARENT_ID_RE = /^(?:toolu|call)[_-]/iu;
/**
* 兼容模型(kimi 系等)的 tool-use id 形态:`${ToolName}_${序号}`。resume 前的
* 转录归一化(maker-core 的 jsonl-tool-id-normalize)还会把它改写成 `Task_x1`
* (移出铸造空间,x 可顺延)与 `Bash_5_dup2`(去重),这些都是**真实 tool-use id**
* 并被同步写进子代理行的 parent_tool_use_id。只认 toolu_/call_ 前缀会把这类
* 子代理的 TodoWrite 当成顶层计划,而 desktop 实时流因显式投影不受影响 →
* 又一次多端分叉(review P2)。
*
* 与 legacy transcript 链边不会误撞:这条形态要求"下划线 + 可选 x + 末段数字",
* RFC uuid 与 `preceding-user-uuid` 都不含下划线数字结尾。
*
* 残留边界(如实记录):**任意**自定义形态的 tool id(既非 toolu_/call_,也非
* `名字_序号`)仍会被判成非 tool parent。彻底的解法是持久化时就记下"这是显式
* tool parent"这一位,而不是让每个消费方按字符串形态猜——同 canonical 计划模型
* 那笔欠账,留待正式建模时一并收口。
*/
const COMPAT_TOOL_USE_ID_RE = /^[A-Za-z][A-Za-z0-9_-]*_x*\d+(?:_dup\d+)?$/u;
/**
* 投影侧共用的同一条判据:这个字符串是不是 SDK 的 tool-parent id 形态。
*
* 把 DB 行的裸 `agentMeta.parentUuid` 提升成显式 `parentToolUseId` 的投影(desktop
* 渲染层的历史恢复)必须先过这一关 —— legacy Claude 导入把 transcript 链边
* (`preceding-user-uuid` 这类非 RFC 串)存在同一个键上,无条件提升会让顶层计划行
* 被判成子代理、普通 user 行被当成合成边界,而保留裸字段的 mobile / main 不会,
* 于是同一份历史在两端分组不同(review P2)。
*/
export function isSubagentParentToolUseId(value: string): boolean {
return isSubagentParentId(value);
}
function isSubagentParentId(value: string): boolean {
const trimmed = value.trim();
return SUBAGENT_PARENT_ID_RE.test(trimmed) || COMPAT_TOOL_USE_ID_RE.test(trimmed);
}
function looksLikeLegacyTranscriptUuid(value: string): boolean {
return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value.trim());
}
export function findMessageTodoInsertions<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
options: MessageRenderTodoGroupingOptions = {},
): Map<number, MessageRenderTodoInsertion> {
const keyPrefix = options.keyPrefix ?? 'todo';
const resultByToolUseId = buildToolResultLookup(messages);
const sessions: Array<{
todos: MessageRenderTodoItem[];
sourceClientIds: string[];
firstIndex: number;
lastIndex: number;
source: MessageRenderTodoSource;
/** 该 session 首条计划调用之前最近一条 user 消息的下标(turn 边界锚点)。 */
userBoundaryIndex: number;
}> = [];
const lastSessionBySource = new Map<MessageRenderTodoSource, (typeof sessions)[number]>();
const taskState = new Map<string, MessageRenderTodoItem>();
let lastUserIndex = -1;
for (let index = 0; index < messages.length; index++) {
const message = messages[index];
if (message.role === 'user') {
if (isPlanUserBoundary(message)) lastUserIndex = index;
continue;
}
const source = agentPlanSource(toolNameOf(message));
if (!source) continue;
// 子代理内部的计划调用不属于顶层面板:它们的 owner 是那个 Agent/Task 工具行,
// 混进来会顶掉主线程计划(顶层"最新计划"按位置竞争,历史病 §3.1.5)。
// 两套字段都认:desktop 投影出顶层 parentToolUseId;mobile 保留原始
// agentMeta.parentUuid(normalizeRemoteMessages 不投影,父行滑出分页窗口
// 时孤儿子消息回退顶层流,不认 meta 就会把子代理清单当顶层计划)。
if (hasSubagentParent(message)) continue;
const resultText = resultByToolUseId.get(toolUseIdOf(message) ?? '');
const previous = lastSessionBySource.get(source);
const previousAllDone = previous?.todos.every((todo) => todo.status === 'completed');
const continuesCompletedTaskSession =
source === 'task'
&& Boolean(previousAllDone)
&& taskToolTargetsExistingTask(message, resultText, taskState);
// 终态章是计划 session 的硬边界:成功收尾的 turn 常留着未勾完的步骤,只看
// allDone 会让下一 turn 的计划把上一轮吞成"续写"——历史里上一轮的计划卡
// 消失、面板复用旧 key。同 toolUseId 的活跃行被新事件清章(terminalPlanSnapshot
// 置 false)后不算边界,sealed-then-updated 的复亮行为不变。
const previousSealed =
Boolean(previous) && planRowSealOf(messages[previous!.lastIndex]).sealed;
// 普通 user turn 也是所有权边界:用户开了新话题,旧的未完成计划不得把新计划
// 吞成"续期"(历史病 §3.1.2/3.1.3——串号后新计划复用旧 key、Task 状态跨
// turn 拼接)。task source 例外:显式指向已有任务的操作(TaskUpdate/TaskGet
// 带已知 id)仍是同一份清单的合法续写,但不能因此把 session 的所有权锚点
// 搬进新 turn:后续 TaskCreate 仍应另起清单,否则一个长期未完成项会把跨阶段
// 新任务持续吸进来,最终出现几十步历史与陈旧 active 项混在一张卡里。
const crossesUserBoundary =
Boolean(previous)
&& lastUserIndex > (previous?.userBoundaryIndex ?? -1)
&& !(source === 'task' && taskToolTargetsExistingTask(message, resultText, taskState));
const startsNewSession =
!previous
|| previousSealed
|| crossesUserBoundary
|| (Boolean(previousAllDone) && !continuesCompletedTaskSession);
if (source === 'task' && startsNewSession) {
taskState.clear();
}
const parsed =
extractPlanTodos(toolNameOf(message), toolInputOf(message))
?? applyTaskPlanTool(
taskState,
message,
resultText,
);
if (!parsed) continue;
if (!startsNewSession && previous) {
previous.todos = parsed;
previous.sourceClientIds.push(sourceClientId(message));
previous.lastIndex = index;
} else {
const session = {
todos: parsed,
sourceClientIds: [sourceClientId(message)],
firstIndex: index,
lastIndex: index,
source,
userBoundaryIndex: lastUserIndex,
};
sessions.push(session);
lastSessionBySource.set(source, session);
}
}
const out = new Map<number, MessageRenderTodoInsertion>();
for (const session of sessions) {
const first = messages[session.firstIndex];
const lastRow = messages[session.lastIndex];
const seal = planRowSealOf(lastRow);
out.set(session.lastIndex, {
key: `${keyPrefix}-${sourceClientId(first)}`,
todos: session.todos,
sourceClientIds: session.sourceClientIds,
createdAt: lastRow?.createdAt,
updatedAtMs: lastRow?.planUpdatedAtMs,
source: session.source,
...(seal.sealed
? {
sealed: true,
...(typeof seal.sealedAtMs === 'number' ? { sealedAtMs: seal.sealedAtMs } : {}),
}
: {}),
...(planRowTurnFailed(lastRow) ? { turnFailed: true } : {}),
});
}
return out;
}
/**
* 常驻计划面板(composer 上方钉住式)用:取整段会话里**最近一次更新**的 plan
* session 快照 —— 跨 source(TodoWrite / update_plan / Task*)按 lastIndex 取
* 最大者。面板只展示"当前计划"一份,历史 session 不再逐张呈现。
* 没有任何 plan 调用时返回 null(面板不渲染、不占位)。
*/
export function findLatestMessageTodoInsertion<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
options: MessageRenderTodoGroupingOptions = {},
): MessageRenderTodoInsertion | null {
return getLatestMessageTodoState(messages, options).insertion;
}
export function getLatestMessageTodoState<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
options: MessageRenderTodoGroupingOptions = {},
): MessageRenderLatestTodoState {
let latestPlanIndex = -1;
let latestPlanMessage: TMessage | null = null;
for (let index = 0; index < messages.length; index++) {
const message = messages[index];
if (!isAgentPlanToolName(toolNameOf(message))) continue;
// 与 findMessageTodoInsertions 同一条边界:子代理内部的计划调用不参与
// 顶层"最新计划事件"的判定,否则子调用会让顶层 insertion 判为过期。
if (hasSubagentParent(message)) continue;
latestPlanIndex = index;
latestPlanMessage = message;
}
let latest: MessageRenderTodoInsertion | null = null;
let latestIndex = -1;
for (const [index, insertion] of findMessageTodoInsertions(messages, options)) {
if (index > latestIndex) {
latestIndex = index;
latest = insertion;
}
}
const hasPlanEvent = latestPlanIndex >= 0;
const latestTaskWindowResolved =
latestPlanMessage === null ||
agentPlanSource(toolNameOf(latestPlanMessage)) !== 'task' ||
isTaskPlanWindowResolved(
messages,
latestPlanIndex,
options.taskHistoryMayBeIncomplete === true,
);
const insertionBelongsToLatestEvent =
latestIndex === latestPlanIndex && latestTaskWindowResolved;
const latestEventClearsPlan =
latestPlanMessage !== null &&
(isExplicitPlanClearEvent(latestPlanMessage) ||
latestTaskEventClearsPlan(messages, latestPlanIndex));
return {
insertion: insertionBelongsToLatestEvent ? latest : null,
hasPlanEvent,
isResolved:
!hasPlanEvent ||
insertionBelongsToLatestEvent ||
(latestTaskWindowResolved && latestEventClearsPlan),
latestPlanIndex,
latestInsertionIndex: latestIndex,
};
}
export interface CodexPlanSnapshotApplyResult<
TMessage extends MessageRenderSourceMessageLike,
> {
messages: readonly TMessage[];
changed: boolean;
toolUseId: string | null;
}
/**
* Close out a Codex plan at its owning turn's terminal event.
*
* Two independent things happen here, and keeping them separate is the whole
* point:
* - **Content**: an explicit `turn/plan/updated` snapshot carried by `done` is
* applied verbatim. Nothing else ever rewrites a step. Codex leaves open
* items on a successful turn routinely (its own prompt asks the model to tick
* them, and the model complies most of the time — not always), and inventing
* the missing ticks makes the transcript claim work that was never reported.
* - **Lifecycle**: a successful, ownership-matched turn *seals* the row. The
* seal is what retires the pinned capsule, so retiring no longer depends on
* the agent having ticked every box.
*
* Interrupted / failed turns, and any turn whose id does not match, seal
* nothing: the task is still alive and the user is usually about to steer it,
* so the plan must stay on screen. A matching non-successful terminal `done`
* does stamp `turnCompleted:false` on its plan row, immediately in memory —
* main's durable stamp (`persistCodexPlanOnDone`) lands asynchronously after
* this event is broadcast, and without the in-memory twin an all-done
* interrupted plan would be retired by the legacy fallback the moment
* streaming ends, then flash back when the durable row arrives.
*/
export function applyCodexPlanSnapshotOnDone<
TMessage extends MessageRenderSourceMessageLike,
>(
messages: readonly TMessage[],
snapshot: unknown,
turnId?: string | null,
terminalStatus?: unknown,
planUpdatedAtMs?: number,
cancelled?: boolean,
): CodexPlanSnapshotApplyResult<TMessage> {
const authoritativeSnapshot = Array.isArray(snapshot) ? snapshot : null;
// 取消标记优先于 completed:done 可同时带 cancelled:true + raw.status
// 'completed'(main 侧 isSuccessfulCodexDoneEventData 同序判定)。渲染端若
// 只看 status 会先盖章退场,随后 main 持久化 turnCompleted:false 的 DB 行
// 广播到达,计划复活——即时 UI 与落库分叉。
// 成功判据与 main 的 isSuccessfulCodexDoneEventData 逐字同序:未取消 +
// raw.status === 'completed'。其余一切(status 为别的值、缺失、被 cancelled
// 覆盖)在归属明确的 turn 上都是失败终态。
//
// "缺失也算失败"很关键:main 对缺 status 的 done 同样写 turnCompleted:false,
// 若这里不落印记,渲染端会按旧数据兜底先退场,随后落库行带失败印记到达又把
// 计划判活 → 消失再闪回(review P2)。
const isSuccessfulTerminal = terminalStatus === 'completed' && cancelled !== true;
const sealsTurn = isSuccessfulTerminal && Boolean(turnId);
// terminalStatus === undefined = 调用方没在描述终态(仅套用权威快照的调用),
// 不落任何印记;null / 其它值都来自真实 done,按失败终态处理。
const stampsFailed = Boolean(turnId) && terminalStatus !== undefined && !isSuccessfulTerminal;
if (!authoritativeSnapshot && !sealsTurn && !stampsFailed) {
return { messages, changed: false, toolUseId: null };
}
const expectedToolUseId = turnId ? `plan:${turnId}` : null;
for (let index = messages.length - 1; index >= 0; index -= 1) {
const message = messages[index];
if (message.role !== 'tool_use' || toolNameOf(message) !== 'update_plan') continue;
const content = readRecord(message.content);
const contentToolUseId = typeof content?.toolUseId === 'string' ? content.toolUseId : null;
const toolUseId = message.toolUseId ?? contentToolUseId;
if (expectedToolUseId && toolUseId !== expectedToolUseId) continue;
const input = readRecord(toolInputOf(message));
if (!Array.isArray(input?.plan)) continue;
const nextPlan = authoritativeSnapshot ?? input.plan;
const planChanged =
authoritativeSnapshot !== null && !samePlanSnapshot(input.plan, authoritativeSnapshot);
// Seal an already-sealed row again would be a no-op update that still
// restarts the capsule's grace timer, so treat it as unchanged.
const sealChanged = sealsTurn && message.terminalPlanSnapshot !== true;
const failChanged =
stampsFailed && message.terminalPlanSnapshot !== true && message.turnCompleted !== false;
if (!planChanged && !sealChanged && !failChanged) {
return { messages, changed: false, toolUseId };
}
// 生命周期印记(章 / 失败标记)同时写进顶层与 content:mobile 的 live-plan
// 缓存只保存 content(rememberLivePlanContent),overlay 会用这份缓存覆盖
// main 广播里已持久化的带章 content——章只在顶层的话,overlay 一盖计划就
// 永远"未盖章",下一 turn 的计划会把上一轮吞进同一 session。
const lifecycleStamp = {
...(sealsTurn
? {
terminalPlanSnapshot: true,
...(typeof planUpdatedAtMs === 'number' && Number.isFinite(planUpdatedAtMs)
? { terminalPlanAtMs: planUpdatedAtMs }
: {}),
}
: {}),
...(failChanged ? { turnCompleted: false } : {}),
};
const next = [...messages];
next[index] = {
...message,
...lifecycleStamp,
...(typeof planUpdatedAtMs === 'number' && Number.isFinite(planUpdatedAtMs)
? { planUpdatedAtMs }
: {}),
...(message.toolInput !== undefined
? { toolInput: { ...input, plan: nextPlan } }
: {}),
...(content
? { content: { ...content, input: { ...input, plan: nextPlan }, ...lifecycleStamp } }
: {}),
};
return { messages: next, changed: true, toolUseId };
}
return { messages, changed: false, toolUseId: null };
}
/**
* 同轮 steer 插话判定。**两套字段都认**:落库位置是 `agentMeta.delivery`
* (mobile 与 main 侧的原始行保持这个形状),desktop 渲染层把它投影成顶层
* `delivery` 后丢弃原 meta。只看顶层会让 mobile / main 的所有权回扫在插话行上
* 提前收手,全勾完的失败计划先按旧数据退场、等 main 的异步印记广播才复活
* (断连时要等到重新加载,review P2)。计划分组、失败回扫与工作过程分组共用
* 这一个谓词,不再各自推导"什么算插话"。
*/
export function isSteerUserRow(message: { delivery?: string | null; agentMeta?: object | null }): boolean {
return message.delivery === 'steer'
|| (message.agentMeta as { delivery?: unknown } | null)?.delivery === 'steer';
}
/**
* Live-side twin of main's `persistCodexPlanOnTerminalError`: a Codex turn that
* dies on a terminal `error` never gets a `done`, so nothing seals its plan row
* and nothing stamps `turnCompleted:false` in memory. Stamp the current turn's
* plan row here so the pinned capsule sees the task as alive immediately, in
* the window before the durable stamp's row broadcast arrives. Step statuses
* are untouched; already-sealed or already-stamped rows are left alone.
*
* Ownership boundary: only rows inside the failing turn's segment — after the
* latest turn-starting user message — may be stamped. Codex plan rows are
* per-turn (`plan:<turnId>` is created within its own turn), so the scan stops
* cold at the first user row that started a turn. What counts as "started a
* turn" is `isSyntheticUserRow`'s negation — the same predicate the plan
* grouping boundary uses, so steer interjections, auto-resume / scheduler
* dispatches, and subagent-internal user rows all keep the scan going instead of
* each surface re-deriving its own list. A failed turn that never emitted
* `update_plan` stamps nothing;
* reaching past the boundary would resurrect an unrelated historical plan
* (pre-seal-era all-done rows retire via the legacy fallback, and a stray
* failure stamp would flip them back to "alive" with no durable write to
* correct it — main's stamper correctly no-ops in that case).
*/
export function markCodexPlanTurnFailed<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
): { messages: readonly TMessage[]; changed: boolean; toolUseId: string | null } {
for (let index = messages.length - 1; index >= 0; index -= 1) {
const message = messages[index];
if (isPlanUserBoundary(message)) break;
if (message.role !== 'tool_use' || toolNameOf(message) !== 'update_plan') continue;
if (planRowSealOf(message).sealed || planRowTurnFailed(message)) {
return { messages, changed: false, toolUseId: null };
}
const next = [...messages];
// 印记同时落 content(与 applyCodexPlanSnapshotOnDone 同口径):mobile 的
// live-plan 缓存只存 content 并整体覆盖 overlay 之后的行,只写顶层的话
// 缓存一盖就把 main 广播的落库印记抹掉。
const content = readRecord(message.content);
next[index] = {
...message,
turnCompleted: false,
...(content ? { content: { ...content, turnCompleted: false } } : {}),
};
// toolUseId 回给调用方:mobile 按它把同一份 content 写回 live-plan 缓存。
return { messages: next, changed: true, toolUseId: toolUseIdOf(message) ?? null };
}
return { messages, changed: false, toolUseId: null };
}
function samePlanSnapshot(left: unknown[], right: unknown[]): boolean {
return JSON.stringify(left) === JSON.stringify(right);
}
export function isAgentPlanToolName(toolName: string | undefined): boolean {
return toolName === 'TodoWrite' || toolName === 'update_plan' || Boolean(toolName && TASK_PLAN_TOOL_NAMES.has(toolName));
}
export function extractPlanTodos(toolName: string | undefined, toolInput: unknown): MessageRenderTodoItem[] | null {
if (toolName === 'TodoWrite') return extractTodos(toolInput);
if (toolName !== 'update_plan') return null;
const input = readRecord(toolInput);
const structured = extractStructuredPlanItems(input?.items) ?? extractStructuredPlanItems(input?.plan);
if (structured) return structured;
const text = typeof input?.text === 'string' ? input.text : '';
if (!text.trim()) return null;
const items = text
.split(/\r?\n/)
.map(normalizePlanLine)
.filter(Boolean);
if (items.length === 0) return null;
return items.map((content, index) => ({
content,
status: index === 0 ? 'in_progress' : 'pending',
}));
}
export function extractTodos(toolInput: unknown): MessageRenderTodoItem[] | null {
const input = readRecord(toolInput);
const todos = input?.todos;
if (!Array.isArray(todos) || todos.length === 0) return null;
const out = todos
.map((item): MessageRenderTodoItem | null => {
const record = readRecord(item);
if (!record) return null;
return {
content: typeof record.content === 'string' ? record.content : String(record.content ?? ''),
status: normalizeTodoStatus(record.status) ?? 'pending',
activeForm: typeof record.activeForm === 'string' ? record.activeForm : undefined,
};
})
.filter((item): item is MessageRenderTodoItem => item !== null);
return out.length > 0 ? out : null;
}
function isExplicitPlanClearEvent(message: MessageRenderSourceMessageLike): boolean {
const toolName = toolNameOf(message);
const input = readRecord(toolInputOf(message));
if (toolName === 'TodoWrite') return Array.isArray(input?.todos) && input.todos.length === 0;
if (toolName === 'update_plan') {
return (
(Array.isArray(input?.items) && input.items.length === 0) ||
(Array.isArray(input?.plan) && input.plan.length === 0) ||
(typeof input?.text === 'string' && input.text.trim().length === 0) ||
(input !== null && Object.keys(input).length === 0)
);
}
return false;
}
function latestTaskEventClearsPlan<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
latestPlanIndex: number,
): boolean {
const latest = messages[latestPlanIndex];
const latestToolName = toolNameOf(latest);
const resultByToolUseId = buildToolResultLookup(messages);
const latestResultText = resultByToolUseId.get(toolUseIdOf(latest) ?? '');
if (latestToolName === 'TaskList') return taskListResultClearsPlan(latestResultText);
if (latestToolName !== 'TaskUpdate' && latestToolName !== 'TaskGet') return false;
if (taskToolStatus(latest, latestResultText) !== 'deleted') return false;
const taskState = new Map<string, MessageRenderTodoItem>();
let previousTaskTodos: MessageRenderTodoItem[] | null = null;
let resolvedTaskContext = false;
for (let index = 0; index <= latestPlanIndex; index += 1) {
const message = messages[index];
if (agentPlanSource(toolNameOf(message)) !== 'task') continue;
const resultText = resultByToolUseId.get(toolUseIdOf(message) ?? '');
const startsNewSession =
previousTaskTodos === null ||
(
previousTaskTodos.every((todo) => todo.status === 'completed') &&
!taskToolTargetsExistingTask(message, resultText, taskState)
);
if (startsNewSession) taskState.clear();
const hadTaskContext = taskState.size > 0;
const parsed = applyTaskPlanTool(
taskState,
message,
resultText,
);
if (parsed) {
resolvedTaskContext = true;
previousTaskTodos = parsed;
continue;
}
if (index === latestPlanIndex) {
return resolvedTaskContext && hadTaskContext && taskState.size === 0;
}
}
return false;
}
/**
* A paged history window is only a complete Task-plan snapshot when every
* status/read event in the current task session can be tied back to a visible
* TaskCreate or an authoritative TaskList snapshot. Otherwise an unrelated
* visible task can make the latest update look resolved and stop history
* backfill before the rest of the plan has been reconstructed.
*/
function isTaskPlanWindowResolved<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
latestPlanIndex: number,
hasEarlierMessages: boolean,
): boolean {
const resultByToolUseId = buildToolResultLookup(messages);
const taskState = new Map<string, MessageRenderTodoItem>();
const unresolvedTaskStatuses = new Map<
string,
MessageRenderTodoItem['status'] | 'deleted'
>();
let previousTaskTodos: MessageRenderTodoItem[] | null = null;
let sawTaskEvent = false;
let currentSessionBoundaryKnown = !hasEarlierMessages;
let lastUserBoundaryIndex = -1;
let currentSessionUserBoundaryIndex = -1;
for (let index = 0; index <= latestPlanIndex; index += 1) {
const message = messages[index];
if (isPlanUserBoundary(message)) {
lastUserBoundaryIndex = index;
continue;
}
if (agentPlanSource(toolNameOf(message)) !== 'task') continue;
const toolName = toolNameOf(message);
const resultText = resultByToolUseId.get(toolUseIdOf(message) ?? '');
const resultTasks = taskRecordsFromResult(resultText);
const input = readRecord(toolInputOf(message)) ?? {};
const targetTaskId = taskId(input) ?? taskId(resultTasks[0]);
const hasPreviousTaskContext =
previousTaskTodos !== null || unresolvedTaskStatuses.size > 0;
const previousAllDone =
hasPreviousTaskContext &&
(previousTaskTodos?.every((todo) => todo.status === 'completed') ?? true) &&
[...unresolvedTaskStatuses.values()].every(
(status) => status === 'completed' || status === 'deleted',
);
const targetsExistingTask = taskToolTargetsExistingTask(message, resultText, taskState);
const continuesCompletedTaskSession =
previousAllDone &&
(targetsExistingTask ||
Boolean(targetTaskId && unresolvedTaskStatuses.has(targetTaskId)));
// 与 findMessageTodoInsertions 保持同一条所有权边界:真实 user turn 后的
// 新 TaskCreate / 新清单不能继承前一轮的孤儿状态;显式更新当前已知 Task
// 仍允许跨 turn 续写,且不移动 session 的原始所有权锚点。
const crossesUserBoundary =
sawTaskEvent &&
lastUserBoundaryIndex > currentSessionUserBoundaryIndex &&
!targetsExistingTask;
const startsNewSession =
!sawTaskEvent ||
crossesUserBoundary ||
(previousAllDone && !continuesCompletedTaskSession);
if (startsNewSession) {
const startsAfterCompletedSession =
sawTaskEvent && previousAllDone && !continuesCompletedTaskSession;
const startsWithTaskCreateAfterVisibleUser =
toolName === 'TaskCreate' &&
lastUserBoundaryIndex >= 0 &&
(!sawTaskEvent || crossesUserBoundary);
taskState.clear();
unresolvedTaskStatuses.clear();
previousTaskTodos = null;
currentSessionBoundaryKnown =
!hasEarlierMessages ||
startsAfterCompletedSession ||
startsWithTaskCreateAfterVisibleUser;
currentSessionUserBoundaryIndex = lastUserBoundaryIndex;
}
sawTaskEvent = true;
if (toolName === 'TaskList') {
if (taskListResultIsAuthoritative(resultText)) {
currentSessionBoundaryKnown = true;
}
if (resultTasks.length > 0) {
const previousTaskState = new Map(taskState);
unresolvedTaskStatuses.clear();
for (const task of resultTasks) {
const id = taskId(task);
const status = normalizeTaskStatus(task.status) ?? 'pending';
if (!id || status === 'deleted') continue;
if (!taskContent(task) && !previousTaskState.has(id)) {
unresolvedTaskStatuses.set(id, status);
}
}
} else if (taskListResultClearsPlan(resultText)) {
unresolvedTaskStatuses.clear();
}
} else if (toolName !== 'TaskCreate') {
const resultTask = resultTasks[0];
const id = taskId(input) ?? taskId(resultTask);
if (id && !taskState.has(id)) {
unresolvedTaskStatuses.set(
id,
taskToolStatus(message, resultText) ?? 'pending',
);
}
}
const parsed = applyTaskPlanTool(taskState, message, resultText);
for (const id of taskState.keys()) unresolvedTaskStatuses.delete(id);
previousTaskTodos = parsed ?? currentTaskTodos(taskState);
if (
previousTaskTodos === null &&
unresolvedTaskStatuses.size === 0 &&
taskState.size === 0
) {
previousTaskTodos = [];
}
}
return currentSessionBoundaryKnown && unresolvedTaskStatuses.size === 0;
}
function buildToolResultLookup<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
): Map<string, string> {
const out = new Map<string, string>();
for (const message of messages) {
const toolUseId = toolUseIdOf(message);
if (!toolUseId || !isToolResultSource(message)) continue;
const result = toolResultTextOf(message);
if (result !== undefined) out.set(toolUseId, result);
}
return out;
}
function collectAgentPlanToolUseIds<TMessage extends MessageRenderSourceMessageLike>(
messages: readonly TMessage[],
): Set<string> {
const out = new Set<string>();
for (const message of messages) {
if (!isAgentPlanToolName(toolNameOf(message))) continue;
const toolUseId = toolUseIdOf(message);
if (toolUseId) out.add(toolUseId);
}
return out;
}
function isAgentPlanToolResult(
message: MessageRenderSourceMessageLike,
agentPlanToolUseIds: ReadonlySet<string>,
): boolean {
if (!isToolResultSource(message)) return false;
const toolUseId = toolUseIdOf(message);
return Boolean(toolUseId && agentPlanToolUseIds.has(toolUseId));
}
function agentPlanSource(toolName: string | undefined): MessageRenderTodoSource | null {
if (toolName === 'TodoWrite') return 'todo';
if (toolName === 'update_plan') return 'codex';
if (toolName && TASK_PLAN_TOOL_NAMES.has(toolName)) return 'task';
return null;
}
function normalizeTodoStatus(value: unknown): MessageRenderTodoItem['status'] | null {
if (value === 'pending' || value === 'completed') return value;
if (value === 'in_progress' || value === 'inProgress' || value === 'running') return 'in_progress';
return null;
}
function normalizeTaskStatus(status: unknown): MessageRenderTodoItem['status'] | 'deleted' | null {
if (status === 'pending' || status === 'in_progress' || status === 'completed') return status;
if (status === 'running' || status === 'inProgress') return 'in_progress';
if (status === 'deleted') return 'deleted';
return null;
}
function taskToolStatus(
message: MessageRenderSourceMessageLike,
resultText: string | undefined,
): MessageRenderTodoItem['status'] | 'deleted' | null {
const toolName = toolNameOf(message);
const input = readRecord(toolInputOf(message));
const resultTask = taskRecordsFromResult(resultText)[0];
if (toolName === 'TaskGet' && resultTask) return normalizeTaskStatus(resultTask.status);
return normalizeTaskStatus(input?.status ?? resultTask?.status);
}
function taskToolTargetsExistingTask(
message: MessageRenderSourceMessageLike,
resultText: string | undefined,
taskState: ReadonlyMap<string, MessageRenderTodoItem>,
): boolean {
const toolName = toolNameOf(message);
if (toolName === 'TaskList') {
return taskRecordsFromResult(resultText).some((task) => {
const id = taskId(task);
return Boolean(id && taskState.has(id));
});
}
if (toolName !== 'TaskUpdate' && toolName !== 'TaskGet') return false;
const input = readRecord(toolInputOf(message));
const resultTask = taskRecordsFromResult(resultText)[0];
const id = taskId(input ?? undefined) ?? taskId(resultTask);
return Boolean(id && taskState.has(id));
}
function extractStructuredPlanItems(items: unknown): MessageRenderTodoItem[] | null {
if (!Array.isArray(items) || items.length === 0) return null;
const todos = items
.map((item): MessageRenderTodoItem | null => {
const record = readRecord(item);
if (!record) return null;
const rawContent = record.content ?? record.text ?? record.step ?? record.title;
const content = typeof rawContent === 'string' ? rawContent.trim() : String(rawContent ?? '').trim();
if (!content) return null;
return {
content,
status: normalizeTodoStatus(record.status) ?? 'pending',
};
})
.filter((item): item is MessageRenderTodoItem => item !== null);
return todos.length > 0 ? todos : null;
}
function normalizePlanLine(line: string): string {
return line
.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '')
.replace(/^\s*\[[ xX-]\]\s+/, '')
.trim();
}
function applyTaskPlanTool(
taskState: Map<string, MessageRenderTodoItem>,
message: MessageRenderSourceMessageLike,
resultText: string | undefined,
): MessageRenderTodoItem[] | null {
const toolName = toolNameOf(message);
if (!TASK_PLAN_TOOL_NAMES.has(toolName)) return null;
const input = readRecord(toolInputOf(message)) ?? {};
const resultTasks = taskRecordsFromResult(resultText);
if (toolName === 'TaskList') {
if (resultTasks.length === 0) {
if (taskListResultClearsPlan(resultText)) {
taskState.clear();
return null;
}
return currentTaskTodos(taskState);
}
const previousTaskState = new Map(taskState);
taskState.clear();
for (const task of resultTasks) {
const id = taskId(task);
if (!id) continue;
const status = normalizeTaskStatus(task.status) ?? 'pending';
if (status === 'deleted') continue;
const content = taskContent(task) ?? previousTaskState.get(id)?.content;
if (!content) continue;
taskState.set(id, {
content,
status,
});
}
return currentTaskTodos(taskState);
}
const resultTask = resultTasks[0];
if (toolName === 'TaskCreate') {
const id = taskId(resultTask) ?? taskId(input) ?? `task-create:${toolUseIdOf(message) ?? sourceClientId(message)}`;
const status = normalizeTaskStatus(resultTask?.status);
const content = taskContent(input) ?? taskContent(resultTask);
if (!content) return currentTaskTodos(taskState);
taskState.set(id, {
content,
status: status && status !== 'deleted' ? status : 'pending',
});
return currentTaskTodos(taskState);
}
const id = taskId(input) ?? taskId(resultTask);
if (!id) return currentTaskTodos(taskState);
// A status-only TaskUpdate / TaskGet can only be applied after the target task
// has been reconstructed from an earlier TaskCreate or TaskList snapshot. In a
// paged history window, returning some other tasks here would make the latest
// event look resolved and stop backfill early, producing a partial plan such
// as "Step 1 / 1" for what was actually the fourth task.
const existing = taskState.get(id);
const suppliedContent = taskContent(input) ?? taskContent(resultTask);
if (!existing && !suppliedContent) return null;
if (toolName === 'TaskGet' && resultTask) {
const status = normalizeTaskStatus(resultTask.status) ?? taskState.get(id)?.status ?? 'pending';
if (status === 'deleted') {
taskState.delete(id);
} else {
const content = taskContent(resultTask) ?? existing?.content;
if (!content) return currentTaskTodos(taskState);
taskState.set(id, {
content,
status,
});
}
return currentTaskTodos(taskState);
}
const status = normalizeTaskStatus(input.status ?? resultTask?.status) ?? existing?.status ?? 'pending';
if (status === 'deleted') {
taskState.delete(id);
return currentTaskTodos(taskState);
}
const content = suppliedContent ?? existing?.content;
if (!content) return currentTaskTodos(taskState);
taskState.set(id, {
content,
status,
});
return currentTaskTodos(taskState);
}
function taskListResultClearsPlan(resultText: string | undefined): boolean {
const parsed = tryParseJsonRecord(resultText);
if (!parsed || !Array.isArray(parsed.tasks)) return false;
return parsed.tasks.every((task) => {
const record = readRecord(task);
return Boolean(record && normalizeTaskStatus(record.status) === 'deleted');
});
}
function taskListResultIsAuthoritative(resultText: string | undefined): boolean {
const parsed = tryParseJsonRecord(resultText);
return Boolean(parsed && Array.isArray(parsed.tasks));
}
function currentTaskTodos(taskState: Map<string, MessageRenderTodoItem>): MessageRenderTodoItem[] | null {
const todos = [...taskState.values()].filter((todo) => todo.content.trim().length > 0);
return todos.length > 0 ? todos : null;
}
function taskRecordsFromResult(resultText: string | undefined): Array<Record<string, unknown>> {
const parsed = tryParseJsonRecord(resultText);
if (!parsed) return taskRecordsFromPlainResult(resultText);
const rawTasks = parsed.tasks;
if (Array.isArray(rawTasks)) {
return rawTasks.filter((task): task is Record<string, unknown> =>
Boolean(task && typeof task === 'object' && !Array.isArray(task)),
);
}
const rawTask = parsed.task;
if (rawTask && typeof rawTask === 'object' && !Array.isArray(rawTask)) {
return [rawTask as Record<string, unknown>];
}
if (taskId(parsed) || taskContent(parsed)) return [parsed];
return taskRecordsFromPlainResult(resultText);
}
function taskRecordsFromPlainResult(resultText: string | undefined): Array<Record<string, unknown>> {
if (!resultText?.trim()) return [];
const tasks: Array<Record<string, unknown>> = [];
for (const rawLine of resultText.split(/\r?\n/)) {
const line = rawLine.trim();
if (!line) continue;
const created = parsePlainTaskCreatedLine(line);
if (created) {
tasks.push(created);
continue;
}
const snapshot = parsePlainTaskSnapshotLine(line);
if (snapshot) {
tasks.push(snapshot);
}
}
return tasks;
}
function parsePlainTaskCreatedLine(line: string): Record<string, unknown> | null {
if (!line.toLowerCase().startsWith('task')) return null;
if (!isWhitespaceCode(line.charCodeAt('task'.length))) return null;
const afterTask = line.slice('task'.length).trimStart();
if (!afterTask.startsWith('#')) return null;
const afterHash = afterTask.slice(1);
const idEnd = firstWhitespaceIndex(afterHash);
if (idEnd <= 0) return null;
const id = afterHash.slice(0, idEnd);
const rest = afterHash.slice(idEnd).trimStart();
const marker = 'created successfully:';
if (!rest.toLowerCase().startsWith(marker)) return null;
const subject = rest.slice(marker.length).trim();
return subject ? { id, status: 'pending', subject } : null;
}
function parsePlainTaskSnapshotLine(line: string): Record<string, unknown> | null {
if (!line.startsWith('#')) return null;
const afterHash = line.slice(1);
const idEnd = firstWhitespaceIndex(afterHash);
if (idEnd <= 0) return null;
const id = afterHash.slice(0, idEnd);
const rest = afterHash.slice(idEnd).trimStart();
if (!rest.startsWith('[')) return null;
const statusEnd = rest.indexOf(']');
if (statusEnd <= 1) return null;
const status = rest.slice(1, statusEnd).trim();
let subject = rest.slice(statusEnd + 1).trim();
const trailingMetaStart = subject.lastIndexOf(' [');
if (trailingMetaStart > 0 && subject.endsWith(']')) {
subject = subject.slice(0, trailingMetaStart).trim();
}
return subject ? { id, status, subject } : null;
}
function firstWhitespaceIndex(value: string): number {
for (let index = 0; index < value.length; index++) {
if (isWhitespaceCode(value.charCodeAt(index))) {
return index;
}
}
return -1;
}
function isWhitespaceCode(code: number): boolean {
return code === 9 || code === 10 || code === 11 || code === 12 || code === 13 || code === 32;
}
function firstString(record: Record<string, unknown> | undefined, keys: readonly string[]): string | undefined {
if (!record) return undefined;
for (const key of keys) {
const value = record[key];
if (typeof value === 'string' && value.trim()) return value.trim();
}
return undefined;
}
function taskContent(record: Record<string, unknown> | undefined): string | undefined {
return firstString(record, ['subject', 'content', 'description', 'activeForm', 'active_form', 'title', 'text']);
}
function taskId(record: Record<string, unknown> | undefined): string | undefined {
return firstString(record, ['taskId', 'task_id', 'id']);
}
function tryParseJsonRecord(text: string | undefined): Record<string, unknown> | null {
if (!text) return null;
try {
const parsed = JSON.parse(text) as unknown;
return readRecord(parsed);
} catch {
return null;
}
}
function groupMessageWorkRuns<TMessage extends MessageRenderNormalizedMessage>(
items: readonly MessageRenderItem<TMessage>[],
isSessionStreaming: boolean,
): MessageRenderItem<TMessage>[] {
return groupWorkRuns<MessageRenderItem<TMessage>, MessageRenderWorkChildItem<TMessage>>(
items, isSessionStreaming, {
isUserBoundary: (item) => item.type === 'message' && item.message.kind === 'user' && !isSteerUserRow(item.message.source),
isContinuationBoundary: (item) => item.type === 'message' && isContinuationMessage(item.message.source),
isAnswer: isAssistantAnswerCandidate,
canPrependToAnswer: (item) => item.type !== 'message' || item.message.source.agentMeta?.assistantPhase !== 'commentary',
isSealedAnswer: (item) => item.type === 'message' && isCompletedAssistantMessage(item.message),
isCompactBoundary: isCompactBoundaryItem,
isActivity: isWorkActivityItem,
isArchivable: (item): item is MessageRenderWorkChildItem<TMessage> =>
!isRunningAgentTaskItem(item) && !isDeliveryProseItem(item) && isWorkChild(item),
startTimestamp: itemTimestamp,
endTimestamp: itemEndTimestamp,
boundaryTimestamp,
userBoundaryEnd: (item, previousEnd) => maxTimestamp(previousEnd, itemEndTimestamp(item)),
createGroup: createWorkGroup,
createCompletedGroup: createCompletedWorkGroup,
activeStandalone: (item, isStreaming) => item.type === 'todo' ? { ...item, isStreaming } : item,
},
);
}
/**
* 运行中(未到终态)的子 Agent 卡是折叠时的"可见锚点",绝不折进「工作过程」组:
* 任务没完成就归档会谎报终态(典型:后台子 agent 仍在跑,父 turn 已产出最终正文)。
* status 派生口径与 buildAgentTaskCardModel / 桌面 MessageStream 的 isRunningAgentTask
* 完全一致:配对工具结果 secondaryBody 会把 stale running 收敛为 completed,
* 但不覆盖 failed/stopped 等明确终态,保证「卡片显示运行中」与「是否折叠」永远同步。
*/
function isRunningAgentTaskItem<
TMessage extends MessageRenderNormalizedMessage,
>(item: MessageRenderItem<TMessage>): boolean {
if (item.type !== 'agent_task') return false;
const status = deriveAgentTaskStatus(item.update?.status, item.toolCall?.secondaryBody, {
persistedStatus: item.toolCall?.agentTaskStatus,
resultIsLaunchReceipt:
item.toolCall !== undefined &&
(subagentSpawnReceiptName(
toolNameOf(item.toolCall.source),
toolInputOf(item.toolCall.source),
item.toolCall.secondaryBody,
) !== undefined
|| subagentSpawnResultIndicatesRunning(
toolNameOf(item.toolCall.source),
item.toolCall.secondaryBody,
)),
});
return status === 'running';
}
function isCompletedAssistantMessage(message: MessageRenderNormalizedMessage): boolean {
return !message.failedSamplingAttempt && message.turnCompleted === true;
}
function isAssistantAnswerCandidate<
TMessage extends MessageRenderNormalizedMessage,
>(item: MessageRenderItem<TMessage>): item is MessageRenderMessageItem<TMessage> {
return item.type === 'message'
&& item.message.kind === 'assistant'
&& !item.message.failedSamplingAttempt
&& item.message.body.trim().length > 0;
}
function isCompactBoundaryItem<TMessage extends MessageRenderNormalizedMessage>(
item: MessageRenderItem<TMessage>,
): item is MessageRenderMessageItem<TMessage> {
return item.type === 'message'
&& item.message.kind === 'system'
&& item.message.label === 'system:compact';
}
/**
* 「交付正文」长度阈值:超过它的 assistant 正文一律当本轮产出,不折进「工作过程」。
* 取 600 字符 —— 进度旁白(「先运行脚本」「继续读剩余 diff」)都在几十字量级,
* 而值得留在消息流里的简报、分析、总结普遍远超它。
*/
const DELIVERY_PROSE_MIN_LENGTH = 600;
/** 块级 markdown 标题:交付正文最强的结构信号,进度旁白不会给自己写标题。 */
const MARKDOWN_HEADING_RE = /^[ \t]{0,3}#{1,6}[ \t]+\S/m;
/**
* 表格分隔行(`| --- | :-: |`)。刻意要求同一行里既有 `-{3,}` 又有 `|`:
* 只有成型的表格会这样,单独的 `---` 水平线不算交付信号。
*/
const MARKDOWN_TABLE_DIVIDER_RE = /^[ \t]{0,3}\|?[ \t]*:?-{3,}:?[ \t]*\|[-:| \t]*$/m;
/** 块级列表项(无序 / 有序)。 */
const MARKDOWN_LIST_ITEM_RE = /^[ \t]{0,3}(?:[-*+][ \t]+|\d{1,3}[.)][ \t]+)\S/gm;
/** 列表要 ≥3 项才算交付结构:「我要做两件事」这类旁白也会顺手列两条。 */
const DELIVERY_PROSE_MIN_LIST_ITEMS = 3;
/**
* 正文里的图片:配一句短说明发出的图也是交付成果。两端渲染器都支持 `` 与
* 带 src 的单个 raw HTML `<img>`(桌面 remarkHtmlImages、手机 messageMarkdown)。
* 只决定是否折叠,偶尔多认(如代码块里的 <img>)只会多显示一条,方向安全。
*/
const MARKDOWN_IMAGE_RE = /!\[[^\]\n]*\]\([^)\s]+(?:\s[^)]*)?\)/;
const HTML_IMAGE_RE = /<img(?=[\s/>])[^<>]*\ssrc\s*=\s*["']?[^\s"'<>]+[^<>]*>/i;
/**
* 这段 assistant 正文是不是「交付内容」(而非进度旁白)。
*
* 判据刻意与位置无关:长度达阈值,或带块级 markdown 结构(标题 / 表格 /
* ≥3 项列表),或内嵌图片。两端共用这一份口径,不各自实现。
*/
export function isDeliveryProseText(text: string): boolean {
const trimmed = text.trim();
if (trimmed.length === 0) return false;
if (hasRichAnswer(trimmed)) return true;
if (trimmed.length >= DELIVERY_PROSE_MIN_LENGTH) return true;
if (MARKDOWN_HEADING_RE.test(trimmed)) return true;
if (MARKDOWN_TABLE_DIVIDER_RE.test(trimmed)) return true;
if (MARKDOWN_IMAGE_RE.test(trimmed) || HTML_IMAGE_RE.test(trimmed)) return true;
// /g 正则不用 test():lastIndex 会在调用之间残留。
const listItems = trimmed.match(MARKDOWN_LIST_ITEM_RE);
return (listItems?.length ?? 0) >= DELIVERY_PROSE_MIN_LIST_ITEMS;
}
/**
* 交付正文 item —— 无论落在 turn 的哪个位置都不折进「工作过程」。
*
* 为什么只靠 seal 位置不够:「最终答复」只认最后一次动作之后的正文,而 agent
* 常见「先输出正文 → 再执行一个收尾副作用(发通知 / 落库 / 提交) → 再说一句
* 已完成」。这时真正的交付内容排在收尾动作之前,会被整段折起来,只剩收尾那句
* 元数据留在消息流里(实例:2026-07-31 定时巡检的产品决策简报 3250 字被折,
* 外面只剩 110 字的「已触发通知」)。
*/
function isDeliveryProseItem<TMessage extends MessageRenderNormalizedMessage>(
item: MessageRenderItem<TMessage>,
): boolean {
return item.type === 'message'
&& item.message.kind === 'assistant'
&& !item.message.failedSamplingAttempt
&& isDeliveryProseText(item.message.body);
}
function isWorkChild<
TMessage extends MessageRenderNormalizedMessage,
>(item: MessageRenderItem<TMessage>): item is MessageRenderWorkChildItem<TMessage> {
return (
item.type === 'thinking'
|| item.type === 'tool_group'
|| item.type === 'agent_task'
|| (
item.type === 'message'
&& item.message.kind === 'assistant'
&& item.message.body.trim().length > 0
)
);
}
/** Normal progress stays visible; proven failed sampling output uses the existing fold. */
function isWorkActivityItem<TMessage extends MessageRenderNormalizedMessage>(
item: MessageRenderItem<TMessage>,
): item is Exclude<MessageRenderWorkChildItem<TMessage>, MessageRenderWorkGroupItem<TMessage>> {
return !isRunningAgentTaskItem(item)
&& (item.type === 'thinking' || item.type === 'tool_group' || item.type === 'agent_task' ||
(item.type === 'message' && item.message.kind === 'assistant' && item.message.failedSamplingAttempt === true));
}
/** 边界项(用户消息 / assistant 正文)的时间戳;非 message 卡片不作为时间边界。 */
function boundaryTimestamp<TMessage extends MessageRenderNormalizedMessage>(
item: MessageRenderItem<TMessage> | undefined,
): number | null {
return item?.type === 'message' ? itemTimestamp(item) : null;
}
function createWorkGroup<
TMessage extends MessageRenderNormalizedMessage,
>(
children: MessageRenderWorkChildItem<TMessage>[],
nextItem?: MessageRenderItem<TMessage>,
isStreaming = false,
previousBoundaryMs: number | null = null,
): MessageRenderWorkGroupItem<TMessage> {
const firstActivity = children.find((item) => item.type !== 'message' || item.message.kind === 'thinking');
const anchor = itemTimestamp(firstActivity ?? children[0]);
// 段起点优先锚上一个边界(用户消息 / 上一句正文),与桌面活表口径一致。
// 边界缺失(窗口截断)或时序异常时退回段内首个活动。
const start =
previousBoundaryMs !== null && (anchor === null || previousBoundaryMs <= anchor)
? previousBoundaryMs
: anchor;
const end =
nextItem?.type === 'message'
? itemTimestamp(nextItem)
: workRunFallbackEnd(children);
const durationMs = start !== null && end !== null && end >= start ? end - start : undefined;
return {
type: 'work_group',
key: `work-${workChildKey(firstActivity ?? children[0])}`,
children,
durationMs,
isStreaming,
...(start !== null ? { startedAtMs: start } : {}),
};
}
function createCompletedWorkGroup<TMessage extends MessageRenderNormalizedMessage>(
run: MessageRenderWorkChildItem<TMessage>[],
nextItem?: MessageRenderItem<TMessage>,
previousBoundaryMs: number | null = null,
): MessageRenderWorkGroupItem<TMessage> {
const hasAssistantText = run.some(
(item) => item.type === 'message' && item.message.kind === 'assistant' && !item.message.failedSamplingAttempt,
);
if (!hasAssistantText) return createWorkGroup(run, nextItem, false, previousBoundaryMs);
const children: MessageRenderWorkChildItem<TMessage>[] = [];
let activityRun: MessageRenderWorkChildItem<TMessage>[] = [];
let innerPreviousBoundaryMs = previousBoundaryMs;
const flushActivityRun = (activityNextItem?: MessageRenderItem<TMessage>) => {
if (activityRun.length === 0) return;
children.push(
createWorkGroup(activityRun, activityNextItem, false, innerPreviousBoundaryMs),
);
activityRun = [];
};
for (const item of run) {
if (item.type !== 'work_group' && isWorkActivityItem(item)) {
activityRun.push(item);
} else {
flushActivityRun(item);
children.push(item);
innerPreviousBoundaryMs = boundaryTimestamp(item);
}
}
flushActivityRun(nextItem);
const outer = createWorkGroup(run, nextItem, false, previousBoundaryMs);
const firstActivity = run.find((item) => item.type !== 'message' || item.message.kind === 'thinking');
return {
...outer,
key: `work-summary-${workChildKey(firstActivity ?? run[0])}`,
children,
isStreaming: false,
};
}
/**
* 没有下一项可作结算边界时(turn 尾部、或被空洞切开的那一段)的组结束时刻:取组内**全部**子项
* 结束时刻的最大值。
*
* 两处都不能省:
* - 必须用 itemEndTimestamp 而不是开始时刻 —— 一段只含工具活动、20 分钟后才回结果的组,拿
* 调用的开始时间当结束会把时长报成约 1 秒。空洞切分让这条回退路径变常见(空洞前那一段永远
* 没有 nextItem),低报会取代原来的超大时长成为新的谎报(#1210 review)。
* - 必须遍历全部子项取 max 而不是"取最后一个" —— 子项按**发起**时刻排序,并行的 Agent/Task
* 会乱序完成:A 先发起跑 40 分钟,B 后发起 2 分钟就结束,最后一个子项是 B,取它就把 A 的
* 40 分钟丢了。桌面 `workRunEndTs` 同款遍历取 max(#676 review codex P1),本文件
* `groupMessageWorkRuns` 的锚点也是同一口径。
*/
function workRunFallbackEnd<TMessage extends MessageRenderNormalizedMessage>(
run: readonly MessageRenderWorkChildItem<TMessage>[],
): number | null {
let latest: number | null = null;
for (const item of run) {
latest = maxTimestamp(latest, itemEndTimestamp(item));
}
return latest;
}
/** Promote long durations to hours/days, always retaining minutes (including zero). */
export function formatDuration(
ms: number,
{
minimumSeconds = 1,
alwaysShowRemainder = false,
padRemainder = false,
formatLongDuration,
}: {
minimumSeconds?: number;
alwaysShowRemainder?: boolean;
padRemainder?: boolean;
formatLongDuration?: (parts: { days: number; hours: string; minutes: string }) => string;
} = {},
): string {
const totalSec = Math.max(minimumSeconds, Math.round((Number.isFinite(ms) ? ms : 0) / 1000));
if (totalSec < 60) return `${totalSec}s`;
const formatRemainder = (value: number) => padRemainder ? String(value).padStart(2, '0') : String(value);
if (totalSec >= 3_600) {
const days = Math.floor(totalSec / 86_400);
const hours = Math.floor((totalSec % 86_400) / 3_600);
const minutes = Math.floor((totalSec % 3_600) / 60);
if (formatLongDuration) {
return formatLongDuration({
days,
hours: days > 0 ? formatRemainder(hours) : String(hours),
minutes: formatRemainder(minutes),
});
}
return days > 0
? `${days}d ${formatRemainder(hours)}h ${formatRemainder(minutes)}m`
: `${hours}h ${formatRemainder(minutes)}m`;
}
const minutes = Math.floor(totalSec / 60);
const seconds = totalSec % 60;
if (seconds === 0 && !alwaysShowRemainder) return `${minutes}m`;
return `${minutes}m ${formatRemainder(seconds)}s`;
}
function itemTimestamp<
TMessage extends MessageRenderNormalizedMessage,
>(item: MessageRenderItem<TMessage>): number | null {
const createdAt = itemCreatedAt(item);
const timestamp = new Date(createdAt).getTime();
return Number.isFinite(timestamp) ? timestamp : null;
}
function itemCreatedAt<
TMessage extends MessageRenderNormalizedMessage,
>(item: MessageRenderItem<TMessage>): string {
if (item.type === 'tool_group' || item.type === 'tool_media') return item.tools[0]?.createdAt ?? '';
if (item.type === 'todo') return item.createdAt;
if (item.type === 'agent_task') return item.createdAt;
if (item.type === 'work_group') return item.children[0] ? itemCreatedAt(item.children[0]) : '';
return item.message.createdAt;
}
/**
* item 的**结束**时刻,空洞判定的锚点(口径与桌面 `renderItemEndMs` 一致):
*
* - tool_group / tool_media:组内全部调用与结果时刻的最大值(结果时刻见 `settledAt`);
* - agent_task:live update 的 updatedAt → createdAt → 调用发起时刻,再与配对结果时刻取更晚
* (历史会话没有 live update,只有结果时刻才是这张卡真正的结束);
* - thinking:createdAt 是块**开始**的时刻,要加上时长 —— 一个想了半小时以上的 thinking 块
* 后面紧跟工具或正文时,只看 createdAt 会把它误判成空洞、切开一个本来连续的 turn;
* - 其余:退回开始时刻。
*/
function itemEndTimestamp<
TMessage extends MessageRenderNormalizedMessage,
>(item: MessageRenderItem<TMessage>): number | null {
if (item.type === 'tool_group' || item.type === 'tool_media') {
let end: number | null = null;
for (const tool of item.tools) {
end = maxTimestamp(end, parseTimestampMs(tool.createdAt));
end = maxTimestamp(end, parseTimestampMs(tool.settledAt));
}
return end ?? itemTimestamp(item);
}
if (item.type === 'agent_task') {
const liveEnd = parseTimestampMs(
item.update?.updatedAt ?? item.update?.createdAt ?? item.toolCall?.createdAt,
) ?? itemTimestamp(item);
return maxTimestamp(liveEnd, parseTimestampMs(item.toolCall?.settledAt));
}
if (item.type === 'work_group') {
// 全量取 max,不是"最后一个 child":children 按**发起**时刻排列,并行动作乱序完成时真正的
// 结束时刻可能落在更靠前的 child 上(先发起、更晚 settle)。取最后一个会低估组的结束时间,
// 于是空洞判定的锚点变小、把本来连续的 turn 误判成空洞切开(#1210 review)。与
// `workRunFallbackEnd` / `groupMessageWorkRuns` 的锚点同一口径。
let latest: number | null = null;
for (const child of item.children) {
latest = maxTimestamp(latest, itemEndTimestamp(child));
}
return latest;
}
const start = itemTimestamp(item);
if (item.type === 'thinking' && start !== null) {
// durationMs 可能是负数 / 非有限值(上游同样做了夹断防御)。不夹断会得出 end < start,
// 空洞判定与工作组时长都跟着错。
const durationMs = item.durationMs;
return start + (typeof durationMs === 'number' && Number.isFinite(durationMs)
? Math.max(0, durationMs)
: 0);
}
return start;
}
function maxTimestamp(a: number | null, b: number | null): number | null {
if (a === null) return b;
if (b === null) return a;
return Math.max(a, b);
}
function parseTimestampMs(createdAt: string | null | undefined): number | null {
if (!createdAt) return null;
const timestamp = Date.parse(createdAt);
return Number.isFinite(timestamp) ? timestamp : null;
}
function workChildKey<
TMessage extends MessageRenderNormalizedMessage,
>(item: MessageRenderWorkChildItem<TMessage>): string {
if (item.type === 'tool_group') return messageClientId(item.tools[0]);
if (item.type === 'todo') return item.key.startsWith('todo-') ? item.key.slice('todo-'.length) : item.key;
if (item.type === 'agent_task') return item.toolCall ? messageClientId(item.toolCall) : item.key;
if (item.type === 'work_group') return item.key;
return messageClientId(item.message);
}
function messageClientId(message: MessageRenderNormalizedMessage | undefined): string {
if (!message) return 'unknown';
return sourceClientId(message.source) || message.key;
}
function sourceClientId(message: MessageRenderSourceMessageLike | undefined): string {
if (!message) return 'unknown';
return message.clientId || message.id || 'unknown';
}
function toolNameOf(message: MessageRenderSourceMessageLike): string {
if (typeof message.toolName === 'string') return message.toolName;
const content = readRecord(message.content);
if (typeof content?.toolName === 'string') return content.toolName;
if (typeof content?.name === 'string') return content.name;
return '';
}
function toolInputOf(message: MessageRenderSourceMessageLike): unknown {
if (message.toolInput !== undefined) return message.toolInput;
const content = readRecord(message.content);
return content?.input;
}
/**
* host 的终态章可能在顶层字段(desktop live / hydrate 路径),也可能只在持久化
* content 里(mobile 直接渲染 main 广播的行,updateDbMessageContent 把章写进
* content)。session 边界与 insertion 的 sealed 判定都必须两处都认。
*/
function planRowSealOf(
message: MessageRenderSourceMessageLike | undefined,
): { sealed: boolean; sealedAtMs?: number } {
if (!message) return { sealed: false };
const content = readRecord(message.content);
const sealed =
message.terminalPlanSnapshot === true ||
(message.terminalPlanSnapshot === undefined && content?.terminalPlanSnapshot === true);
if (!sealed) return { sealed: false };
const sealedAtMs =
typeof message.terminalPlanAtMs === 'number'
? message.terminalPlanAtMs
: typeof content?.terminalPlanAtMs === 'number'
? content.terminalPlanAtMs
: undefined;
return { sealed: true, ...(sealedAtMs !== undefined ? { sealedAtMs } : {}) };
}
/** 同 planRowSealOf:失败印记(turnCompleted:false)也认 content 里的持久化位置。 */
function planRowTurnFailed(message: MessageRenderSourceMessageLike | undefined): boolean {
if (!message) return false;
if (message.turnCompleted === false) return true;
const content = readRecord(message.content);
return message.turnCompleted === undefined && content?.turnCompleted === false;
}
function toolUseIdOf(message: MessageRenderSourceMessageLike): string | undefined {
if (typeof message.toolUseId === 'string' && message.toolUseId.length > 0) return message.toolUseId;
const content = readRecord(message.content);
if (typeof content?.toolUseId === 'string' && content.toolUseId.length > 0) return content.toolUseId;
if (typeof content?.id === 'string' && content.id.length > 0) return content.id;
return undefined;
}
function isToolResultSource(message: MessageRenderSourceMessageLike): boolean {
if (message.role === 'tool_result') return true;
const content = readRecord(message.content);
return content?.role === 'tool_result' || content?.type === 'tool_result' || content?.kind === 'tool_result';
}
function toolResultTextOf(message: MessageRenderSourceMessageLike): string | undefined {
if (typeof message.content === 'string') return message.content;
const content = readRecord(message.content);
if (typeof content?.content === 'string') return content.content;
if (typeof content?.result === 'string') return content.result;
if (typeof content?.text === 'string') return content.text;
return undefined;
}
function parseThinking(message: MessageRenderSourceMessageLike): { durationMs?: number; redacted: boolean } {
const content = readRecord(message.content);
const durationMs = typeof content?.durationMs === 'number' && Number.isFinite(content.durationMs)
? content.durationMs
: undefined;
return {
durationMs,
redacted: content?.isRedacted === true,
};
}
function readRecord(value: unknown): Record<string, unknown> | null {
return value && typeof value === 'object' && !Array.isArray(value)
? value as Record<string, unknown>
: null;
}
/**
* 从单条 source message 直接抽取 todo 列表(用于移动端从 `sessions:patched` 等单消息回流即时
* 渲染 todo 卡,不经过 `buildMessageRenderItems` 的整段会话编排)。桌面侧走 `findMessageTodoInsertions`
* 的多消息归并路径,移动端这条是按单消息就地解析的轻量入口,二者共用同一 `MessageRenderTodoItem` 形状。
*/
export function extractTodosFromSourceMessage(message: MessageRenderSourceMessageLike): MessageRenderTodoItem[] | null {
const input = readRecord(readRecord(message.content)?.input);
const todos = input?.todos;
if (!Array.isArray(todos) || todos.length === 0) return null;
return todos.map((item) => {
const record = readRecord(item);
const rawStatus = typeof record?.status === 'string' ? record.status : '';
const status = rawStatus === 'completed' || rawStatus === 'in_progress' || rawStatus === 'pending'
? rawStatus
: 'pending';
const content = typeof record?.content === 'string'
? record.content
: String(record?.content ?? '');
const activeForm = typeof record?.activeForm === 'string' ? record.activeForm : undefined;
return { content, status, activeForm };
});
}