import type { ThreadStructure, ThreadStructureRuntime } from "@t3tools/client-runtime/state/shell";
import { resolveThreadWorkingStartedAt } from "@t3tools/client-runtime/state/models";
import {
type AssetResource,
type OrchestrationV2Checkpoint,
type OrchestrationV2ExecutionNode,
type OrchestrationV2PlanArtifact,
type OrchestrationV2ProjectedTurnItem,
type OrchestrationV2RunAttempt,
type OrchestrationV2TurnItem,
type PlanId,
type RunId,
type ToolActivitySurface,
type ToolActivityIcon,
type ToolActivitySource,
type ThreadId,
type TurnItemId,
} from "@t3tools/contracts";
import { extractToolActivityPresentation } from "@t3tools/client-runtime/work-log/tool-presentation";
import {
classifyToolActivity,
collectToolFilePaths,
formatReadToolLabel,
formatSearchToolLabel,
} from "@t3tools/shared/toolActivity";
import type { HtmlRenderReference } from "@t3tools/shared/htmlRender";
import { turnItemDetailRevision } from "@t3tools/client-runtime/work-log/item-detail";
import type { McpAppReference } from "@t3tools/shared/mcpApp";
import { htmlRenderFromToolItem, mcpAppFromToolItem } from "@t3tools/shared/toolOutput";
import {
contextCompactionLabel,
workEntryIndicatesToolFailure,
} from "@t3tools/client-runtime/work-log/presentation";
import type { ThreadCheckpointSummary } from "@t3tools/client-runtime/state/thread-checkpoints";
import type {
ThreadPendingApproval,
ThreadPendingUserInput,
} from "@t3tools/client-runtime/state/thread-requests";
import type { ThreadRunSummary, ThreadRuntimeSummary } from "@t3tools/client-runtime/state/shell";
import { threadRuntimeHasInterruptibleRun } from "@t3tools/client-runtime/state/thread-execution";
import { turnItemIsWorkspacePreparation } from "@t3tools/client-runtime/state/turn-item-presentation";
import {
isImageAttachment,
type ChatAttachment,
type ChatMessage,
type ProposedPlan,
type SessionPhase,
type TurnDiffSummary,
} from "./types";
import * as DateTime from "effect/DateTime";
import * as Equal from "effect/Equal";
import { shallow } from "zustand/vanilla/shallow";
export { formatDuration } from "@t3tools/shared/orchestrationTiming";
export {
workEntryDisplayIndicatesToolFailure,
workEntryIndicatesToolFailure,
} from "@t3tools/client-runtime/work-log/presentation";
export type WorkLogToolLifecycleStatus =
| "idle"
| "inProgress"
| "completed"
| "failed"
| "declined"
| "stopped";
export interface WorkLogEntry {
readonly questionAnswer?: import("@t3tools/contracts").UserInputAttachmentAnswerPayload;
readonly id: string;
readonly createdAt: string;
readonly runId?: RunId | null;
readonly label: string;
readonly detail?: string;
readonly command?: string;
readonly rawCommand?: string;
readonly changedFiles?: ReadonlyArray<string>;
readonly tone: "thinking" | "tool" | "info" | "error";
readonly toolTitle?: string;
readonly toolCallId?: string;
readonly viewedImagePath?: string;
readonly toolSurface?: ToolActivitySurface;
readonly toolIcon?: ToolActivityIcon;
readonly toolSource?: ToolActivitySource;
readonly sourceActivityKind?: string;
readonly taskId?: string;
readonly agentRole?: string;
readonly toolData?: unknown;
readonly requestKind?: string;
readonly itemType?: OrchestrationV2TurnItem["type"];
readonly toolLifecycleStatus?: WorkLogToolLifecycleStatus;
readonly structuredPayload?: OrchestrationV2TurnItem;
readonly sourceItemType?: OrchestrationV2TurnItem["type"];
readonly projectedItem?: OrchestrationV2ProjectedTurnItem;
}
export type PendingApproval = ThreadPendingApproval;
export type PendingUserInput = ThreadPendingUserInput;
export interface LatestProposedPlanState {
readonly id: PlanId;
readonly createdAt: string;
readonly updatedAt: string;
readonly runId: RunId | null;
readonly planMarkdown: string;
readonly status: OrchestrationV2PlanArtifact["status"];
}
export type TimelineAttempt = Pick<
OrchestrationV2RunAttempt,
"id" | "runId" | "attemptOrdinal" | "rootNodeId" | "status" | "completedAt"
>;
export type TimelineEntry = (
| {
readonly id: string;
readonly kind: "message";
readonly createdAt: string;
readonly message: ChatMessage;
readonly projectedItem?: OrchestrationV2ProjectedTurnItem;
}
| {
readonly id: string;
readonly kind: "proposed-plan";
readonly createdAt: string;
readonly proposedPlan: ProposedPlan;
}
| {
readonly id: string;
readonly kind: "html-render";
readonly createdAt: string;
readonly runId: RunId | null;
readonly htmlRender: HtmlRenderReference;
}
| {
readonly id: string;
readonly kind: "mcp-app";
readonly createdAt: string;
readonly runId: RunId | null;
readonly sourceThreadId: ThreadId;
readonly itemId: TurnItemId;
readonly revision: string;
readonly mcpApp: McpAppReference;
}
| {
readonly id: string;
readonly kind: "work";
readonly createdAt: string;
readonly entry: WorkLogEntry;
}
| {
readonly id: string;
readonly kind: "event";
readonly createdAt: string;
readonly projectedItem: OrchestrationV2ProjectedTurnItem;
}
) & {
readonly attempt?: TimelineAttempt;
};
export function workLogEntryIsToolLike(entry: WorkLogEntry): boolean {
return (
entry.tone === "tool" ||
entry.tone === "thinking" ||
entry.tone === "error" ||
entry.command !== undefined ||
entry.requestKind !== undefined
);
}
export function workEntrySignalsSevereFailure(entry: WorkLogEntry): boolean {
return entry.itemType === "error";
}
export function workEntryIndicatesToolSuccess(entry: WorkLogEntry): boolean {
if (
!workLogEntryIsToolLike(entry) ||
workEntryIndicatesToolFailure(entry) ||
(entry.tone === "thinking" && entry.itemType !== "reasoning")
) {
return false;
}
const status = entry.toolLifecycleStatus;
return (
status !== "failed" &&
status !== "declined" &&
status !== "inProgress" &&
status !== "stopped" &&
status !== "idle"
);
}
export function workEntryIndicatesToolNeutralStatus(entry: WorkLogEntry): boolean {
return (
workLogEntryIsToolLike(entry) &&
!workEntryIndicatesToolFailure(entry) &&
!workEntryIndicatesToolSuccess(entry)
);
}
export function isLatestRunSettled(
latestRun: Pick<ThreadRunSummary, "runId" | "startedAt" | "completedAt" | "status"> | null,
runtime: Pick<ThreadRuntimeSummary, "status" | "activeRunId"> | null,
): boolean {
if (latestRun === null) return false;
if (
latestRun.status === "preparing" ||
latestRun.status === "queued" ||
latestRun.status === "starting" ||
latestRun.status === "running" ||
latestRun.status === "waiting"
)
return false;
return runtime?.activeRunId !== latestRun.runId;
}
export function deriveActiveWorkStartedAt(
latestRun: Pick<
ThreadRunSummary,
"runId" | "startedAt" | "requestedAt" | "completedAt" | "status"
> | null,
runtime: Pick<ThreadRuntimeSummary, "status" | "activeRunId" | "activityStartedAt"> | null,
sendStartedAt: string | null,
): string | null {
const startedAt = resolveThreadWorkingStartedAt({ latestRun, runtime });
return startedAt ?? (runtime?.activeRunId == null ? sendStartedAt : null);
}
export function derivePendingApprovals(
approvals: ReadonlyArray<ThreadPendingApproval>,
): ThreadPendingApproval[] {
return [...approvals].toSorted((left, right) => left.createdAt.localeCompare(right.createdAt));
}
export function derivePendingUserInputs(
inputs: ReadonlyArray<ThreadPendingUserInput>,
): ThreadPendingUserInput[] {
return [...inputs].toSorted((left, right) => left.createdAt.localeCompare(right.createdAt));
}
function planItemTime(
projection: ThreadStructure,
plan: Pick<OrchestrationV2PlanArtifact, "id" | "runId">,
): string {
const item = projection.turnItems.findLast(
(candidate) =>
(candidate.type === "proposed_plan" || candidate.type === "todo_list") &&
candidate.planId === plan.id,
);
if (item?.type === "proposed_plan" || item?.type === "todo_list") {
return DateTime.formatIso(item.updatedAt);
}
// Without a plan item, the plan's run dates it; the thread's own timestamps move while a reply streams.
const run = projection.runs.find((candidate) => candidate.id === plan.runId);
return DateTime.formatIso(
run?.completedAt ?? run?.startedAt ?? run?.requestedAt ?? projection.thread.createdAt,
);
}
function toLatestProposedPlanState(
projection: ThreadStructure,
plan: Extract<OrchestrationV2PlanArtifact, { readonly kind: "proposed_plan" }>,
): LatestProposedPlanState {
const updatedAt = planItemTime(projection, plan);
return {
id: plan.id,
createdAt: updatedAt,
updatedAt,
runId: plan.runId,
planMarkdown: plan.markdown,
status: plan.status,
};
}
export function findLatestProposedPlan(
projection: ThreadStructure | null,
latestRunId: RunId | string | null | undefined,
): LatestProposedPlanState | null {
if (projection === null) return null;
const plans = projection.plans.filter((plan) => plan.kind === "proposed_plan");
const candidates = latestRunId ? plans.filter((plan) => plan.runId === latestRunId) : plans;
const plan = [...(candidates.length > 0 ? candidates : plans)]
.toSorted(
(left, right) =>
planItemTime(projection, left).localeCompare(planItemTime(projection, right)) ||
left.id.localeCompare(right.id),
)
.at(-1);
return plan === undefined ? null : toLatestProposedPlanState(projection, plan);
}
export function hasActionableProposedPlan(plan: LatestProposedPlanState | null): boolean {
return plan?.status === "active";
}
const STANDALONE_V2_ITEM_TYPES = new Set<OrchestrationV2ProjectedTurnItem["item"]["type"]>([
"fork",
"handoff",
"run_interrupt_request",
"run_interrupt_result",
"secret_request",
"link_request",
"subagent",
]);
const PERSISTENT_RESOURCE_V2_ITEM_TYPES = new Set<OrchestrationV2TurnItem["type"]>([
"fork",
"thread_created",
// Still answerable after a steer supersedes the attempt that asked.
"secret_request",
"link_request",
]);
export function timelineEntryIsPersistentResourceCard(entry: TimelineEntry): boolean {
return (
entry.kind === "event" && PERSISTENT_RESOURCE_V2_ITEM_TYPES.has(entry.projectedItem.item.type)
);
}
function projectedItemCreatedAt(row: OrchestrationV2ProjectedTurnItem): string {
return DateTime.formatIso(row.item.startedAt ?? row.item.updatedAt);
}
function projectedWorkEntryStatus(
item: OrchestrationV2TurnItem,
): NonNullable<WorkLogEntry["toolLifecycleStatus"]> {
switch (item.status) {
case "pending":
case "running":
case "waiting":
return "inProgress";
case "completed":
return "completed";
case "idle":
return "idle";
case "failed":
return "failed";
case "cancelled":
case "interrupted":
return "stopped";
}
}
function projectedWorkEntryTone(item: OrchestrationV2TurnItem): WorkLogEntry["tone"] {
if (item.type === "error") return "info";
if (item.type === "reasoning") return "thinking";
switch (item.type) {
case "command_execution":
case "file_change":
case "file_search":
case "web_search":
case "dynamic_tool":
case "subagent":
case "thread_created":
case "user_input_request":
case "approval_request":
return "tool";
default:
return "info";
}
}
export function providerErrorPresentation(
item: Extract<OrchestrationV2TurnItem, { readonly type: "error" }>,
): { readonly label: string; readonly detail: string } {
if (item.retry === undefined) {
return {
label:
item.failure.class === "usage_limit"
? "Usage limit reached"
: item.title?.trim() || "Provider error",
detail: item.failure.message,
};
}
const progress =
item.retry.maxAttempts === null
? `${item.retry.attempt}`
: `${item.retry.attempt}/${item.retry.maxAttempts}`;
const label =
item.status === "running"
? `Retrying provider (${progress})`
: item.status === "completed"
? `Provider recovered (${progress} retries)`
: item.status === "failed"
? `${item.failure.class === "usage_limit" ? "Usage limit reached" : "Provider error"} after ${progress} retries`
: `Provider retry stopped (${progress})`;
const retryDelay =
item.status === "running" && item.retry.retryDelayMs !== null && item.retry.retryDelayMs > 0
? item.retry.retryDelayMs < 1_000
? ` Retrying in ${item.retry.retryDelayMs}ms.`
: ` Retrying in ${(item.retry.retryDelayMs / 1_000).toFixed(1).replace(/\.0$/u, "")}s.`
: "";
return {
label,
detail: `${item.failure.message}${retryDelay}`,
};
}
function projectedWorkEntry(row: OrchestrationV2ProjectedTurnItem): WorkLogEntry {
const { item } = row;
const title = item.title?.trim() || null;
const common = {
id: item.id,
createdAt: projectedItemCreatedAt(row),
runId: item.runId,
tone: projectedWorkEntryTone(item),
itemType: item.type,
toolLifecycleStatus: projectedWorkEntryStatus(item),
structuredPayload: item,
projectedItem: row,
...extractToolActivityPresentation(item),
} as const;
switch (item.type) {
case "thread_created":
return {
...common,
label: "Created thread",
};
case "compaction":
return {
...common,
label: contextCompactionLabel(item),
sourceActivityKind: "context-compaction",
...(item.summary ? { detail: item.summary } : {}),
};
case "reasoning":
return {
...common,
label: title ?? "Thinking",
...(item.text ? { detail: item.text } : {}),
};
case "command_execution":
return {
...common,
label: title ?? "Ran command",
command: item.input,
rawCommand: item.input,
toolTitle: title ?? "Command",
toolData: item,
};
case "file_change": {
return {
...common,
label:
title ??
(item.changes !== undefined && item.changes.length > 1
? `Changed ${item.changes.length} files`
: `Changed ${item.fileName}`),
changedFiles: item.changes?.map((change) => change.path) ?? [item.fileName],
toolTitle: title ?? "File change",
toolData: item,
};
}
case "file_search":
return {
...common,
label: title ?? formatSearchToolLabel(item) ?? "Searched files",
...(item.pattern ? { detail: item.pattern } : {}),
toolTitle: title ?? "File search",
toolData: item,
};
case "web_search":
return {
...common,
label: title ?? "Searched the web",
...(item.patterns?.length ? { detail: item.patterns.join(", ") } : {}),
toolTitle: title ?? "Web search",
toolData: item,
};
case "checkpoint":
return {
...common,
label: title ?? "Checkpoint captured",
changedFiles: item.files.map((file) => file.path),
toolData: item,
};
case "system_notice":
return {
...common,
label: item.message,
sourceActivityKind: "runtime.warning",
};
case "error": {
const presentation = providerErrorPresentation(item);
return {
...common,
...presentation,
...(item.failure.class === "usage_limit" && item.status !== "completed"
? { sourceActivityKind: "runtime.warning" }
: item.retry === undefined
? { sourceActivityKind: "runtime.error" }
: {}),
toolData: item,
};
}
case "dynamic_tool": {
const classified = classifyToolActivity({
itemType: "dynamic_tool_call",
data: { toolName: item.toolName ?? undefined, input: item.input },
});
const [readPath] = collectToolFilePaths({ input: item.input });
return {
...common,
label:
title ??
(classified === "read"
? formatReadToolLabel(readPath ?? "")
: classified === "search"
? (formatSearchToolLabel({ input: item.input }) ?? item.toolName ?? "Tool call")
: (item.toolName ?? "Tool call")),
toolTitle: title ?? item.toolName ?? "Tool",
toolData: { input: item.input, output: item.output },
};
}
case "todo_list": {
// Each todo update is a quiet row where the agent wrote it; it opens to every step.
const done = item.steps.filter((step) => step.status === "completed").length;
const current =
item.steps.find((step) => step.status === "running") ??
item.steps.find((step) => step.status === "pending");
return {
...common,
label: `Tasks ${done}/${item.steps.length}${current ? ` · ${current.text}` : ""}`,
};
}
case "approval_request":
return {
...common,
label: title ?? "Approval requested",
detail: item.prompt ?? item.requestKind,
toolData: item,
};
case "user_input_request":
return {
...common,
label: title ?? (item.questionAnswer ? "Answered questions" : "Input requested"),
...(item.questionAnswer ? { questionAnswer: item.questionAnswer } : {}),
toolData: item,
};
default:
return {
...common,
label: title ?? item.type.replaceAll("_", " "),
toolData: item,
};
}
}
/** Preserve visibleTurnItems' committed order; interleave client messages by timestamp. */
export interface TimelineEntriesInput {
readonly visibleTurnItems: ReadonlyArray<OrchestrationV2ProjectedTurnItem>;
readonly optimisticMessages: ReadonlyArray<ChatMessage>;
readonly anchoredMessages?: ReadonlyArray<ChatMessage>;
readonly attachmentUrlById?: ReadonlyMap<string, string>;
readonly attempts?: ReadonlyArray<OrchestrationV2RunAttempt>;
readonly nodes?: ReadonlyArray<OrchestrationV2ExecutionNode>;
readonly plans?: ReadonlyArray<OrchestrationV2PlanArtifact>;
}
export interface TimelineEntriesProjection {
readonly input: TimelineEntriesInput;
readonly entries: TimelineEntry[];
}
export function deriveTimelineEntriesFromVisibleTurnItems(
input: TimelineEntriesInput,
): TimelineEntry[] {
const committedMessageIds = new Set<string>();
const entries: TimelineEntry[] = [];
const attemptByRootNodeId = new Map(
(input.attempts ?? []).map((attempt) => [attempt.rootNodeId, attempt] as const),
);
const nodeById = new Map((input.nodes ?? []).map((node) => [node.id, node] as const));
const planById = new Map((input.plans ?? []).map((plan) => [plan.id, plan] as const));
const resolveAttempt = (item: OrchestrationV2TurnItem): TimelineAttempt | undefined => {
if (item.nodeId === null || item.runId === null) return undefined;
let nodeId: OrchestrationV2ExecutionNode["id"] | null = item.nodeId;
const visited = new Set<OrchestrationV2ExecutionNode["id"]>();
while (nodeId !== null && !visited.has(nodeId)) {
visited.add(nodeId);
const directAttempt = attemptByRootNodeId.get(nodeId);
if (directAttempt?.runId === item.runId) return directAttempt;
const node = nodeById.get(nodeId);
if (node === undefined) return undefined;
const rootAttempt = attemptByRootNodeId.get(node.rootNodeId);
if (rootAttempt?.runId === item.runId) return rootAttempt;
nodeId = node.parentNodeId;
}
return undefined;
};
const foldedAnswerMessageIds = new Set(
input.visibleTurnItems.flatMap(({ item }) =>
item.type === "user_input_request" && item.questionAnswer
? [`async-answer:${item.questionAnswer.requestId}`]
: [],
),
);
for (const row of input.visibleTurnItems) {
const { item } = row;
if (turnItemIsWorkspacePreparation(item) && !item.deferredWork) continue;
if (item.type === "checkpoint") continue;
if (
item.type === "user_message" &&
item.inputIntent === "queued_turn" &&
item.status === "pending"
)
continue;
if (item.type === "user_message" && foldedAnswerMessageIds.has(item.messageId)) continue;
const createdAt = projectedItemCreatedAt(row);
const attempt = resolveAttempt(item);
const attemptMetadata = attempt === undefined ? {} : { attempt };
if (item.type === "notification") {
entries.push({
id: item.id,
kind: "work",
createdAt,
entry: {
id: item.id,
createdAt,
runId: item.runId,
label: item.summary,
tone: "info",
itemType: item.type,
structuredPayload: item,
projectedItem: row,
},
...attemptMetadata,
});
continue;
}
if (item.type === "user_message" || item.type === "assistant_message") {
const message: ChatMessage = {
id: item.messageId,
role: item.type === "user_message" ? "user" : "assistant",
text: item.text,
...(item.type === "user_message" && item.context ? { context: item.context } : {}),
...((item.attachments?.length ?? 0) > 0
? {
attachments: (item.attachments ?? []).map((attachment) => {
const previewUrl = input.attachmentUrlById?.get(attachment.id);
return previewUrl ? { ...attachment, previewUrl } : attachment;
}),
}
: {}),
runId: item.runId,
streaming: item.type === "assistant_message" && item.streaming,
...(item.type === "user_message"
? {
createdBy: item.createdBy,
creationSource: item.creationSource,
...(item.senderThreadId !== undefined ? { senderThreadId: item.senderThreadId } : {}),
...(item.idleCompaction !== undefined ? { idleCompaction: item.idleCompaction } : {}),
...(item.scheduledTaskId !== undefined
? { scheduledTaskId: item.scheduledTaskId }
: {}),
}
: {}),
createdAt,
updatedAt: DateTime.formatIso(item.updatedAt),
...(item.type === "user_message" ? { inputIntent: item.inputIntent } : {}),
};
committedMessageIds.add(message.id);
entries.push({
id: message.id,
kind: "message",
createdAt,
message,
projectedItem: row,
...attemptMetadata,
});
continue;
}
if (item.type === "proposed_plan") {
const plan = planById.get(item.planId);
const proposedPlan = {
id: item.planId,
runId: item.runId,
planMarkdown: item.markdown,
status: plan?.kind === "proposed_plan" ? plan.status : ("active" as const),
createdAt,
updatedAt: DateTime.formatIso(item.updatedAt),
};
entries.push({
id: item.id,
kind: "proposed-plan",
createdAt,
proposedPlan,
...attemptMetadata,
});
continue;
}
const htmlRender =
item.type === "dynamic_tool" && item.status === "completed"
? htmlRenderFromToolItem(item)
: undefined;
if (htmlRender !== undefined) {
entries.push({
id: item.id,
kind: "html-render",
createdAt,
runId: item.runId,
htmlRender,
...attemptMetadata,
});
continue;
}
const mcpApp = item.type === "dynamic_tool" ? mcpAppFromToolItem(item) : undefined;
if (mcpApp !== undefined) {
entries.push({
id: item.id,
kind: "mcp-app",
createdAt,
runId: item.runId,
sourceThreadId: row.sourceThreadId,
itemId: row.sourceItemId,
revision: turnItemDetailRevision(item),
mcpApp,
...attemptMetadata,
});
continue;
}
if (STANDALONE_V2_ITEM_TYPES.has(item.type)) {
entries.push({
id: item.id,
kind: "event",
createdAt,
projectedItem: row,
...attemptMetadata,
});
continue;
}
entries.push({
id: item.id,
kind: "work",
createdAt,
entry: projectedWorkEntry(row),
...attemptMetadata,
});
}
const retainedMessageIds = new Set([...committedMessageIds, ...foldedAnswerMessageIds]);
for (const message of input.anchoredMessages ?? []) {
if (retainedMessageIds.has(message.id)) continue;
retainedMessageIds.add(message.id);
const entry: TimelineEntry = {
id: message.id,
kind: "message",
createdAt: message.createdAt,
message,
};
const insertionIndex = entries.findIndex(
(candidate) => candidate.createdAt > message.createdAt,
);
if (insertionIndex === -1) {
entries.push(entry);
} else {
entries.splice(insertionIndex, 0, entry);
}
}
for (const message of input.optimisticMessages) {
if (message.inputIntent !== "queued_turn" && !retainedMessageIds.has(message.id)) {
retainedMessageIds.add(message.id);
entries.push({
id: message.id,
kind: "message",
createdAt: message.createdAt,
message,
});
}
}
return entries;
}
type AttachmentResource = Extract<AssetResource, { readonly _tag: "attachment" }>;
const EMPTY_IMAGE_RESOURCES = Object.freeze<ReadonlyArray<AttachmentResource>>([]);
export function selectMessageImageResources(
attachments: ChatMessage["attachments"],
): ReadonlyArray<AttachmentResource> {
const attachmentIds = new Set<string>();
for (const attachment of attachments ?? []) {
if (!isImageAttachment(attachment)) continue;
const previewUrl = attachment.previewUrl;
if (previewUrl?.startsWith("blob:") || previewUrl?.startsWith("data:")) continue;
attachmentIds.add(attachment.id);
}
return attachmentIds.size === 0
? EMPTY_IMAGE_RESOURCES
: Array.from(attachmentIds, (attachmentId) => ({ _tag: "attachment", attachmentId }));
}
export function selectHandoffImageResources(
messages: ReadonlyArray<Pick<ChatMessage, "id" | "role" | "attachments">> | undefined,
handoffs: Readonly<Record<string, ReadonlyArray<string>>>,
): ReadonlyArray<AttachmentResource> {
if (Object.keys(handoffs).length === 0) return EMPTY_IMAGE_RESOURCES;
const attachmentIds = new Set<string>();
for (const message of messages ?? []) {
if (message.role !== "user" || !handoffs[message.id]?.length) continue;
for (const attachment of message.attachments ?? []) {
if (isImageAttachment(attachment)) attachmentIds.add(attachment.id);
}
}
return attachmentIds.size === 0
? EMPTY_IMAGE_RESOURCES
: Array.from(attachmentIds, (attachmentId) => ({ _tag: "attachment", attachmentId }));
}
export function createMessageAttachmentPreviewProjector() {
const attachmentsBySource = new WeakMap<
ReadonlyArray<ChatAttachment>,
ReadonlyArray<ChatAttachment>
>();
const messagesBySource = new WeakMap<ChatMessage, ChatMessage>();
return (
message: ChatMessage,
previewUrlFor: (attachment: ChatAttachment) => string | undefined,
): ChatMessage => {
const source = message.attachments;
if (!source || source.length === 0) return message;
const previous = attachmentsBySource.get(source) ?? source;
let changed: ChatAttachment[] | undefined;
let hasOverrides = false;
for (const [index, attachment] of source.entries()) {
const previewUrl = previewUrlFor(attachment);
const sourceUrl = "previewUrl" in attachment ? attachment.previewUrl : undefined;
const previousAttachment = previous[index]!;
const previousUrl =
"previewUrl" in previousAttachment ? previousAttachment.previewUrl : undefined;
const next =
!previewUrl || previewUrl === sourceUrl
? attachment
: previewUrl === previousUrl
? previousAttachment
: { ...attachment, previewUrl };
hasOverrides ||= next !== attachment;
if (next !== previousAttachment) {
changed ??= previous.slice();
changed[index] = next;
}
}
const attachments = hasOverrides ? (changed ?? previous) : source;
attachmentsBySource.set(source, attachments);
if (attachments === source) {
messagesBySource.delete(message);
return message;
}
const previousMessage = messagesBySource.get(message);
if (previousMessage?.attachments === attachments) return previousMessage;
const result = { ...message, attachments };
messagesBySource.set(message, result);
return result;
};
}
export function isStreamingMessageTextUpdate(previous: ChatMessage, next: ChatMessage): boolean {
if (
previous.role !== "assistant" ||
next.role !== "assistant" ||
!previous.streaming ||
!next.streaming
) {
return false;
}
const { text: _previousText, updatedAt: _previousUpdatedAt, ...previousMetadata } = previous;
const { text: _nextText, updatedAt: _nextUpdatedAt, ...nextMetadata } = next;
return shallow(previousMetadata, nextMetadata);
}
export function isStreamingTurnItemTextUpdate(
previous: OrchestrationV2ProjectedTurnItem,
next: OrchestrationV2ProjectedTurnItem,
): boolean {
const { item: previousItem, ...previousSource } = previous;
const { item: nextItem, ...nextSource } = next;
if (
previousItem.type !== "assistant_message" ||
nextItem.type !== "assistant_message" ||
!previousItem.streaming ||
!nextItem.streaming ||
!shallow(previousSource, nextSource) ||
projectedItemCreatedAt(previous) !== projectedItemCreatedAt(next)
) {
return false;
}
const { text: _previousText, updatedAt: _previousUpdatedAt, ...previousMetadata } = previousItem;
const { text: _nextText, updatedAt: _nextUpdatedAt, ...nextMetadata } = nextItem;
// Wire decoding recreates timestamps and attachments; compare only the changed item's metadata.
return Equal.equals(previousMetadata, nextMetadata);
}
/**
* A changed tool or work item maps to exactly one entry with the item's id.
* Messages and question answers take part in cross-entry dedupe, and anchored
* messages are placed by createdAt, so those changes rebuild.
*/
function canRederiveInPlace(
input: TimelineEntriesInput,
previousItem: OrchestrationV2ProjectedTurnItem,
item: OrchestrationV2ProjectedTurnItem,
): boolean {
return (
item.item.id === previousItem.item.id &&
item.item.type === previousItem.item.type &&
item.item.type !== "user_message" &&
item.item.type !== "assistant_message" &&
item.item.type !== "user_input_request" &&
((input.anchoredMessages?.length ?? 0) === 0 ||
projectedItemCreatedAt(item) === projectedItemCreatedAt(previousItem))
);
}
function reuseTimelineEntries(
input: TimelineEntriesInput,
previous: TimelineEntriesProjection,
): TimelineEntry[] | null {
const before = previous.input;
if (
input.visibleTurnItems.length < before.visibleTurnItems.length ||
!shallow(input.optimisticMessages, before.optimisticMessages) ||
!shallow(input.anchoredMessages, before.anchoredMessages) ||
!shallow(input.attachmentUrlById, before.attachmentUrlById) ||
!shallow(input.attempts, before.attempts) ||
!shallow(input.nodes, before.nodes) ||
!shallow(input.plans, before.plans)
) {
return null;
}
const appended = input.visibleTurnItems.length > before.visibleTurnItems.length;
// Keep full projection until committed items interleave and deduplicate anchored/optimistic messages.
if (
appended &&
(input.optimisticMessages.length > 0 || (input.anchoredMessages?.length ?? 0) > 0)
) {
return null;
}
// Answer rows can replace a message already present in the retained prefix.
if (
appended &&
input.visibleTurnItems
.slice(before.visibleTurnItems.length)
.some(
({ item }) =>
(item.type === "user_input_request" && item.questionAnswer !== undefined) ||
(item.type === "user_message" && item.messageId.startsWith("async-answer:")),
)
)
return null;
const replacements = new Map<
OrchestrationV2ProjectedTurnItem,
OrchestrationV2ProjectedTurnItem
>();
const changedItems: OrchestrationV2ProjectedTurnItem[] = [];
for (let index = 0; index < before.visibleTurnItems.length; index += 1) {
const previousItem = before.visibleTurnItems[index]!;
const item = input.visibleTurnItems[index]!;
if (item === previousItem) continue;
if (isStreamingTurnItemTextUpdate(previousItem, item)) {
replacements.set(previousItem, item);
continue;
}
if (!canRederiveInPlace(input, previousItem, item)) return null;
changedItems.push(item);
}
// One batch keeps the attempt/node/plan lookups to a single build.
const rederived =
changedItems.length === 0
? []
: deriveTimelineEntriesFromVisibleTurnItems({
...input,
visibleTurnItems: changedItems,
optimisticMessages: [],
anchoredMessages: [],
});
if (
rederived.length !== changedItems.length ||
rederived.some((entry, index) => entry.id !== changedItems[index]!.item.id)
) {
return null;
}
const rederivedEntries = new Map(rederived.map((entry) => [entry.id, entry]));
if (replacements.size === 0 && rederivedEntries.size === 0 && !appended) {
return previous.entries;
}
let rederivedCount = 0;
const entries = previous.entries.map((entry): TimelineEntry => {
const rederivedEntry = rederivedEntries.get(entry.id);
if (rederivedEntry !== undefined) {
rederivedCount += 1;
return rederivedEntry;
}
const row =
entry.kind === "message" && entry.projectedItem !== undefined
? replacements.get(entry.projectedItem)
: undefined;
if (entry.kind !== "message" || row?.item.type !== "assistant_message") return entry;
return {
...entry,
projectedItem: row,
message: {
...entry.message,
text: row.item.text,
updatedAt: DateTime.formatIso(row.item.updatedAt),
},
};
});
if (rederivedCount !== rederivedEntries.size) return null;
if (appended) {
entries.push(
...deriveTimelineEntriesFromVisibleTurnItems({
...input,
visibleTurnItems: input.visibleTurnItems.slice(before.visibleTurnItems.length),
}),
);
}
return entries;
}
export function deriveTimelineEntriesFromVisibleTurnItemsWithState(
input: TimelineEntriesInput,
previous: TimelineEntriesProjection | null = null,
): TimelineEntriesProjection {
const reused = previous === null ? null : reuseTimelineEntries(input, previous);
if (reused !== null) return { input, entries: reused };
const entries = deriveTimelineEntriesFromVisibleTurnItems(input);
if (previous === null || !shallow(input.attachmentUrlById, previous.input.attachmentUrlById)) {
return { input, entries };
}
const previousMessages = new Map(
previous.entries.flatMap((entry) =>
entry.kind === "message" ? [[entry.id, entry] as const] : [],
),
);
return {
input,
entries: entries.map((entry) => {
if (entry.kind !== "message" || entry.projectedItem === undefined) return entry;
const before = previousMessages.get(entry.id);
if (before?.projectedItem !== entry.projectedItem) return entry;
return before.attempt === entry.attempt ? before : { ...entry, message: before.message };
}),
};
}
// Run ordinals keep increasing after a rewind; only visible local runs define predecessors.
export function deriveRevertTurnCountByUserMessageId(input: {
readonly timelineEntries: ReadonlyArray<TimelineEntry>;
readonly checkpoints: ReadonlyArray<ThreadCheckpointSummary>;
readonly threadStartCheckpointReady: boolean;
readonly availableRevertTurnCounts?: ReadonlySet<number> | undefined;
readonly unsettledRunId?: RunId | null;
}): Map<ChatMessage["id"], number> {
const readyTurnCountByRunId = new Map<RunId, number>();
for (const checkpoint of input.checkpoints) {
if (checkpoint.status === "ready") {
readyTurnCountByRunId.set(checkpoint.runId, checkpoint.checkpointTurnCount);
}
}
const targetByRunId = new Map<RunId, number | undefined>();
const byUserMessageId = new Map<ChatMessage["id"], number>();
let previousRunId: RunId | null = null;
for (const entry of input.timelineEntries) {
// Inherited history belongs to the source thread, not our checkpoint scope.
if (entry.kind !== "message" && entry.kind !== "work") continue;
const projectedItem =
entry.kind === "message" ? entry.projectedItem : entry.entry.projectedItem;
if (projectedItem?.visibility === "inherited") continue;
const runId =
entry.kind === "message"
? entry.message.runId
: entry.entry.itemType === "notification"
? entry.entry.runId
: null;
if (runId == null) continue;
if (!targetByRunId.has(runId)) {
targetByRunId.set(
runId,
previousRunId === null
? input.threadStartCheckpointReady
? 0
: undefined
: readyTurnCountByRunId.get(previousRunId),
);
previousRunId = runId;
}
if (entry.kind !== "message") continue;
const { message } = entry;
if (message.role !== "user" || message.runId === input.unsettledRunId) continue;
if (message.inputIntent !== "turn_start" && message.inputIntent !== "queued_turn") continue;
const target = targetByRunId.get(runId);
if (
target !== undefined &&
(input.availableRevertTurnCounts === undefined || input.availableRevertTurnCounts.has(target))
)
byUserMessageId.set(message.id, target);
}
return byUserMessageId;
}
export function findRevertCheckpoint(
checkpoints: ReadonlyArray<OrchestrationV2Checkpoint>,
turnCount: number,
): OrchestrationV2Checkpoint | undefined {
return checkpoints.findLast(
(checkpoint) =>
checkpoint.status === "ready" &&
(turnCount === 0
? checkpoint.ordinalWithinScope === 0 && checkpoint.appRunOrdinal === null
: checkpoint.appRunOrdinal === turnCount),
);
}
export function derivePhase(runtime: ThreadStructureRuntime | null): SessionPhase {
if (runtime === null) return "disconnected";
if (
runtime.status === "preparing" ||
runtime.status === "starting" ||
runtime.status === "queued"
)
return "connecting";
if (runtime.status === "running" || runtime.status === "waiting") return "running";
return "ready";
}
/** Preparing and starting runs can be interrupted; Stop need not wait for running. */
export function deriveCanInterruptRunningThread(
hasActiveThread: boolean,
runtime: ThreadStructureRuntime | null,
): boolean {
return (
hasActiveThread &&
(derivePhase(runtime) === "running" || threadRuntimeHasInterruptibleRun(runtime))
);
}
export type { TurnDiffSummary };