@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/interactive/status/state-machine.ts

@@ -0,0 +1,530 @@
+import type { RunAbortSource } from "../../core/bus-events.js";
+import { ToolNames } from "../../core/tool-names.js";
+import type { ChatLoopEvent, RetryStatusPhase } from "../chat-loop.js";
+import { buildSummary, emptyRunTally, foldMessageIntoRunTally, summaryFromRunTally } from "./summary.js";
+import {
+	type AgentStatus,
+	INITIAL_STATUS,
+	type OverlayFrame,
+	type OverlayPhase,
+	type RetryOverlay,
+	type StatusPhase,
+	type ToolOverlay,
+	type TurnStopReason,
+} from "./types.js";
+import { computeWatchdogTier } from "./watchdog.js";
+
+export interface ReduceContext {
+	now: number;
+	localRuntime: boolean;
+	modelId?: string;
+	targetId?: string;
+	runId?: string | null;
+}
+
+export interface WatchdogTickEvent {
+	type: "watchdog_tick";
+}
+
+export interface OverlayPushEvent {
+	type: "overlay_push";
+	overlay: Exclude<OverlayPhase, "stuck" | "retrying">;
+	data?: unknown;
+}
+
+export interface OverlayPopEvent {
+	type: "overlay_pop";
+	overlay: Exclude<OverlayPhase, "stuck" | "retrying">;
+}
+
+export interface RunAbortedStatusEvent {
+	type: "run_aborted";
+	source?: RunAbortSource;
+	reason?: string;
+}
+
+export interface ForceCancelledStatusEvent {
+	type: "force_cancelled";
+	reason: string;
+}
+
+/** Worker stream evidence for a dispatch this turn is awaiting. */
+export interface DispatchProgressStatusEvent {
+	type: "dispatch_progress";
+}
+
+export type StatusInputEvent =
+	| ChatLoopEvent
+	| WatchdogTickEvent
+	| OverlayPushEvent
+	| OverlayPopEvent
+	| RunAbortedStatusEvent
+	| ForceCancelledStatusEvent
+	| DispatchProgressStatusEvent;
+
+const OVERLAY_PHASES = new Set<StatusPhase>(["tool_blocked", "retrying", "compacting", "dispatching", "stuck"]);
+const CORE_ACTIVE_PHASES = new Set<StatusPhase>(["preparing", "waiting_model", "thinking", "writing", "tool_running"]);
+const OVERLAY_PRECEDENCE: readonly OverlayPhase[] = ["stuck", "tool_blocked", "retrying", "compacting", "dispatching"];
+
+function isOverlayPhase(phase: StatusPhase): phase is OverlayPhase {
+	return OVERLAY_PHASES.has(phase);
+}
+
+function isActive(phase: StatusPhase): phase is Exclude<StatusPhase, "idle" | "ended"> {
+	return phase !== "idle" && phase !== "ended";
+}
+
+function targetModel(ctx: ReduceContext): { modelId: string; targetId: string } {
+	return { modelId: ctx.modelId ?? "", targetId: ctx.targetId ?? "" };
+}
+
+function peak(prev: AgentStatus, tier: AgentStatus["watchdogTier"]): AgentStatus["watchdogPeak"] {
+	return tier > prev.watchdogPeak ? tier : prev.watchdogPeak;
+}
+
+function refreshMeaningful(prev: AgentStatus, ctx: ReduceContext): AgentStatus {
+	return {
+		...prev,
+		lastMeaningfulAt: ctx.now,
+		watchdogTier: 0,
+		localRuntime: ctx.localRuntime,
+		...(ctx.runId !== undefined ? { runId: ctx.runId } : {}),
+	};
+}
+
+function compactPreview(value: unknown): string {
+	if (value === undefined) return "";
+	if (typeof value === "string") return value.slice(0, 60);
+	try {
+		return JSON.stringify(value).slice(0, 60);
+	} catch {
+		return String(value).slice(0, 60);
+	}
+}
+
+function overlayFrame(status: AgentStatus): OverlayFrame {
+	return {
+		phase: status.phase as OverlayPhase,
+		resumePhase: status.resumePhase ?? "preparing",
+		retry: status.retry,
+		tool: status.tool,
+		dispatch: status.dispatch,
+	};
+}
+
+function overlayFrames(prev: AgentStatus): Map<OverlayPhase, OverlayFrame> {
+	const frames = new Map<OverlayPhase, OverlayFrame>();
+	for (const frame of prev.overlayStack ?? []) frames.set(frame.phase, frame);
+	if (isOverlayPhase(prev.phase)) frames.set(prev.phase, overlayFrame(prev));
+	for (const phase of prev.activePhases ?? []) {
+		if (!frames.has(phase)) frames.set(phase, { phase, resumePhase: baseResumePhase(prev) });
+	}
+	return frames;
+}
+
+function baseResumePhase(prev: AgentStatus): StatusPhase {
+	if (isOverlayPhase(prev.phase)) return prev.resumePhase ?? "preparing";
+	return prev.phase;
+}
+
+function visibleOverlay(frames: ReadonlyMap<OverlayPhase, OverlayFrame>): OverlayFrame | undefined {
+	for (const phase of OVERLAY_PRECEDENCE) {
+		const frame = frames.get(phase);
+		if (frame) return frame;
+	}
+	return undefined;
+}
+
+function overlayStackWithoutVisible(
+	frames: ReadonlyMap<OverlayPhase, OverlayFrame>,
+	visible: OverlayFrame,
+): OverlayFrame[] {
+	return OVERLAY_PRECEDENCE.flatMap((phase) => {
+		if (phase === visible.phase) return [];
+		const frame = frames.get(phase);
+		return frame ? [frame] : [];
+	});
+}
+
+function statusForVisibleOverlay(
+	prev: AgentStatus,
+	visible: OverlayFrame,
+	frames: ReadonlyMap<OverlayPhase, OverlayFrame>,
+): AgentStatus {
+	const base = visible.resumePhase;
+	return {
+		...prev,
+		phase: visible.phase,
+		resumePhase: base,
+		retry: visible.retry,
+		tool: visible.tool,
+		dispatch: visible.dispatch,
+		activePhases: new Set(frames.keys()),
+		overlayStack: overlayStackWithoutVisible(frames, visible),
+	};
+}
+
+function pushOverlay(prev: AgentStatus, phase: OverlayPhase, ctx: ReduceContext, data?: unknown): AgentStatus {
+	if (!isActive(prev.phase)) return prev;
+	const frames = overlayFrames(prev);
+	const resumePhase = baseResumePhase(prev);
+	const nextFrame = overlayFrame(
+		overlayData(
+			{
+				...prev,
+				phase,
+				resumePhase,
+			},
+			phase,
+			data,
+		),
+	);
+	frames.set(phase, nextFrame);
+	const nextVisible = visibleOverlay(frames);
+	if (!nextVisible) return refreshMeaningful(prev, ctx);
+	return statusForVisibleOverlay(refreshMeaningful(prev, ctx), nextVisible, frames);
+}
+
+function overlayData(status: AgentStatus, phase: OverlayPhase, data?: unknown): AgentStatus {
+	if (phase === "retrying") {
+		const retry = data as RetryOverlay | undefined;
+		return { ...status, retry };
+	}
+	if (phase === "dispatching") {
+		const obj = data && typeof data === "object" ? (data as Record<string, unknown>) : {};
+		const agentName =
+			typeof obj.agentName === "string"
+				? obj.agentName
+				: typeof obj.agentId === "string"
+					? obj.agentId
+					: typeof obj.runId === "string"
+						? obj.runId
+						: "";
+		return { ...status, dispatch: { agentName } };
+	}
+	return status;
+}
+
+function popOverlay(prev: AgentStatus, overlay: OverlayPhase, ctx: ReduceContext): AgentStatus {
+	const frames = overlayFrames(prev);
+	const restore = baseResumePhase(prev);
+	frames.delete(overlay);
+	const nextVisible = visibleOverlay(frames);
+	if (nextVisible) return statusForVisibleOverlay(refreshMeaningful(prev, ctx), nextVisible, frames);
+	return {
+		...refreshMeaningful(prev, ctx),
+		phase: restore,
+		resumePhase: undefined,
+		activePhases: undefined,
+		overlayStack: [],
+		retry: undefined,
+		dispatch: undefined,
+	};
+}
+
+function activePhaseAfterStuck(prev: AgentStatus): StatusPhase {
+	if (prev.phase !== "stuck") return prev.phase;
+	return prev.resumePhase ?? "thinking";
+}
+
+function isAwaitingDispatch(prev: AgentStatus): boolean {
+	if (prev.phase === "dispatching") return true;
+	if (prev.activePhases?.has("dispatching")) return true;
+	return (prev.overlayStack ?? []).some((frame) => frame.phase === "dispatching");
+}
+
+function isWaitingForOperator(prev: AgentStatus): boolean {
+	return (
+		prev.tool?.toolName === ToolNames.AskUser &&
+		(prev.phase === "tool_running" || (prev.phase === "stuck" && prev.resumePhase === "tool_running"))
+	);
+}
+
+function cancelledSummary(
+	prev: AgentStatus,
+	ctx: ReduceContext,
+	stopReason: TurnStopReason,
+	truncated = false,
+	stopDetail?: string,
+) {
+	const start = prev.since > 0 ? prev.since : ctx.now;
+	const model = targetModel(ctx);
+	// The engine hands the cancel path a message window it has already replaced
+	// with one synthetic zero-usage failure message, so a summary rebuilt from
+	// it reports nothing. The live tally is what this run actually settled.
+	return summaryFromRunTally(prev.runTally ?? emptyRunTally(), {
+		startedAt: start,
+		endedAt: ctx.now,
+		modelId: model.modelId,
+		targetId: model.targetId,
+		watchdogPeak: prev.watchdogPeak,
+		stopReason,
+		truncated,
+		...(stopDetail !== undefined ? { stopDetail } : {}),
+	});
+}
+
+const ABORT_SOURCE_LABELS: Record<RunAbortSource, string> = {
+	dispatch_abort: "dispatch abort",
+	dispatch_drain: "dispatch drain",
+	stream_cancel: "stream cancel",
+	loop_guard: "loop guard",
+};
+
+function runAbortDetail(event: RunAbortedStatusEvent): string | undefined {
+	const label = event.source !== undefined ? ABORT_SOURCE_LABELS[event.source] : undefined;
+	if (label !== undefined && event.reason !== undefined) return `${label}: ${event.reason}`;
+	return event.reason ?? label;
+}
+
+function retryOverlay(status: {
+	phase: RetryStatusPhase;
+	attempt: number;
+	maxAttempts: number;
+	delayMs?: number;
+}): RetryOverlay {
+	return {
+		attempt: status.attempt,
+		maxAttempts: status.maxAttempts,
+		waitMs: status.delayMs ?? 0,
+	};
+}
+
+export function reduceStatus(prev: AgentStatus, event: StatusInputEvent, ctx: ReduceContext): AgentStatus {
+	switch (event.type) {
+		case "agent_start":
+			if (isActive(prev.phase)) return prev;
+			return {
+				...INITIAL_STATUS,
+				phase: "preparing",
+				since: ctx.now,
+				lastMeaningfulAt: ctx.now,
+				localRuntime: ctx.localRuntime,
+				...(ctx.runId !== undefined ? { runId: ctx.runId } : {}),
+			};
+		case "turn_start": {
+			const base = activePhaseAfterStuck(prev);
+			const next = refreshMeaningful({ ...prev, phase: base }, ctx);
+			if (base === "preparing") return { ...next, phase: "waiting_model", resumePhase: undefined };
+			return next;
+		}
+		case "message_start": {
+			const next = refreshMeaningful(prev, ctx);
+			const role = (event.message as { role?: unknown }).role;
+			if (role === "assistant" && prev.phase === "tool_running") return { ...next, phase: "writing" };
+			if (
+				role === "assistant" &&
+				(prev.phase === "preparing" || prev.phase === "waiting_model" || prev.phase === "thinking")
+			)
+				return { ...next, phase: "writing", resumePhase: undefined };
+			return next;
+		}
+		case "message_update": {
+			const base = activePhaseAfterStuck(prev);
+			const next = refreshMeaningful({ ...prev, phase: base }, ctx);
+			if (base === "preparing" || base === "waiting_model" || base === "thinking") {
+				return { ...next, phase: "writing", resumePhase: undefined };
+			}
+			if (CORE_ACTIVE_PHASES.has(base)) return { ...next, resumePhase: undefined };
+			return next;
+		}
+		case "tool_execution_update":
+			return refreshMeaningful(prev, ctx);
+		case "message_end":
+			// Fold every settled message as it lands. This is the only record of
+			// the run's usage that survives a cancel.
+			return {
+				...refreshMeaningful(prev, ctx),
+				runTally: foldMessageIntoRunTally(prev.runTally ?? emptyRunTally(), event.message),
+			};
+		case "tool_execution_end": {
+			const next = refreshMeaningful(prev, ctx);
+			if (prev.phase === "tool_running") return { ...next, phase: "preparing", tool: undefined, toolStartedAt: undefined };
+			if (prev.phase === "stuck" && prev.resumePhase === "tool_running") {
+				return { ...next, phase: "preparing", resumePhase: undefined, tool: undefined, toolStartedAt: undefined };
+			}
+			// A blocked call's end can land while an overlay is still visible
+			// (permission prompt not yet resolved, retry or dispatch in front).
+			// Without scrubbing the stashed frames, the eventual overlay pop
+			// restores phase tool_running with this already-finished call's
+			// overlay, leaving a perpetual "running tool" display.
+			if (isOverlayPhase(prev.phase)) {
+				return {
+					...next,
+					resumePhase: prev.resumePhase === "tool_running" ? "preparing" : prev.resumePhase,
+					tool: undefined,
+					toolStartedAt: undefined,
+					overlayStack: (prev.overlayStack ?? []).map((frame) => ({
+						...frame,
+						tool: undefined,
+						resumePhase: frame.resumePhase === "tool_running" ? "preparing" : frame.resumePhase,
+					})),
+				};
+			}
+			return next;
+		}
+		case "thinking_delta": {
+			const base = activePhaseAfterStuck(prev);
+			const next = refreshMeaningful({ ...prev, phase: base }, ctx);
+			// Model reasoning arriving while a tool still shows as running means the
+			// tool is done (its end never landed or was an admission block): the
+			// model is generating, nothing is executing, so drop the tool display.
+			if (base === "preparing" || base === "waiting_model" || base === "writing" || base === "tool_running") {
+				return { ...next, phase: "thinking", resumePhase: undefined, tool: undefined, toolStartedAt: undefined };
+			}
+			if (CORE_ACTIVE_PHASES.has(base)) return { ...next, resumePhase: undefined };
+			return next;
+		}
+		case "text_delta": {
+			const base = activePhaseAfterStuck(prev);
+			const next = refreshMeaningful({ ...prev, phase: base }, ctx);
+			// Streamed answer text while a tool still shows as running: same as
+			// above, the model is writing, so the running-tool spinner must clear.
+			if (base === "preparing" || base === "waiting_model" || base === "thinking" || base === "tool_running") {
+				return { ...next, phase: "writing", resumePhase: undefined, tool: undefined, toolStartedAt: undefined };
+			}
+			if (CORE_ACTIVE_PHASES.has(base)) return { ...next, resumePhase: undefined };
+			return next;
+		}
+		case "tool_execution_start": {
+			const tool: ToolOverlay = {
+				toolName: event.toolName,
+				toolPreview: compactPreview(event.args),
+			};
+			// Stamp this call's own start so the footer's running-tool timer counts
+			// from here, not from turn start.
+			return { ...refreshMeaningful(prev, ctx), phase: "tool_running", tool, toolStartedAt: ctx.now };
+		}
+		case "retry_status": {
+			const phase = event.status.phase;
+			if (phase === "scheduled" || phase === "waiting" || phase === "retrying") {
+				return pushOverlay(prev, "retrying", ctx, retryOverlay(event.status));
+			}
+			if (phase === "recovered") return popOverlay(prev, "retrying", ctx);
+			return {
+				...refreshMeaningful(prev, ctx),
+				phase: "ended",
+				summary: cancelledSummary(prev, ctx, phase === "cancelled" ? "cancelled" : "error"),
+				resumePhase: undefined,
+				activePhases: undefined,
+				overlayStack: [],
+			};
+		}
+		case "agent_end": {
+			const truncated = prev.phase === "idle";
+			const start = prev.since > 0 ? prev.since : ctx.now;
+			const model = targetModel(ctx);
+			const rebuilt = buildSummary({
+				startedAt: start,
+				endedAt: ctx.now,
+				modelId: model.modelId,
+				targetId: model.targetId,
+				messages: event.messages,
+				watchdogPeak: prev.watchdogPeak,
+				cancelled: false,
+				truncated,
+			});
+			// On the abort path the engine has already replaced the run's window
+			// with one synthetic zero-usage failure message, so this rebuild
+			// reports nothing and would undo the summary run_aborted just wrote
+			// from the live tally. Whichever record saw more tokens is the one
+			// that saw the run; on a normal turn the two agree exactly, because
+			// both fold the same messages through the same function.
+			const tally = prev.runTally;
+			const summary =
+				tally && tally.inputTokens + tally.outputTokens > rebuilt.inputTokens + rebuilt.outputTokens
+					? summaryFromRunTally(tally, {
+							startedAt: start,
+							endedAt: ctx.now,
+							modelId: model.modelId,
+							targetId: model.targetId,
+							watchdogPeak: prev.watchdogPeak,
+							stopReason: rebuilt.stopReason,
+							truncated,
+							...(rebuilt.stopDetail !== undefined ? { stopDetail: rebuilt.stopDetail } : {}),
+						})
+					: rebuilt;
+			// run_aborted may already have stamped this run's abort provenance
+			// (loop guard, dispatch drain, user cancel). The rebuild from the
+			// settled message window keeps that detail instead of dropping it.
+			if (prev.phase === "ended" && prev.summary?.stopDetail !== undefined && summary.stopDetail === undefined) {
+				summary.stopDetail = prev.summary.stopDetail;
+			}
+			return {
+				...refreshMeaningful(prev, ctx),
+				phase: "ended",
+				summary,
+				resumePhase: undefined,
+				activePhases: undefined,
+				overlayStack: [],
+			};
+		}
+		case "dispatch_progress":
+			// The orchestrator's own stream is silent for as long as a worker runs,
+			// so the await-watchdog measured its own silence and reported "no
+			// progress" about a worker that was streaming the whole time
+			// (issue #54). Worker output is this turn's progress.
+			if (!isActive(prev.phase) || !isAwaitingDispatch(prev)) return prev;
+			return refreshMeaningful(prev, ctx);
+		case "overlay_push":
+			return pushOverlay(prev, event.overlay, ctx, event.data);
+		case "overlay_pop":
+			return popOverlay(prev, event.overlay, ctx);
+		case "run_aborted":
+			if (!isActive(prev.phase)) return prev;
+			return {
+				...refreshMeaningful(prev, ctx),
+				phase: "ended",
+				summary: cancelledSummary(prev, ctx, "cancelled", false, runAbortDetail(event)),
+				resumePhase: undefined,
+				activePhases: undefined,
+				overlayStack: [],
+			};
+		case "force_cancelled":
+			return {
+				...refreshMeaningful(prev, ctx),
+				phase: "ended",
+				summary: cancelledSummary(prev, ctx, "cancelled", true, event.reason),
+				resumePhase: undefined,
+				activePhases: undefined,
+				overlayStack: [],
+			};
+		case "watchdog_tick": {
+			if (!isActive(prev.phase)) return prev;
+			if (isWaitingForOperator(prev)) {
+				return {
+					...prev,
+					phase: "tool_running",
+					resumePhase: undefined,
+					watchdogTier: 0,
+					localRuntime: ctx.localRuntime,
+				};
+			}
+			const elapsed = Math.max(0, ctx.now - prev.lastMeaningfulAt);
+			const tier = computeWatchdogTier(elapsed);
+			if (tier === 4 && prev.phase !== "stuck") {
+				return {
+					...prev,
+					phase: "stuck",
+					resumePhase: prev.phase,
+					watchdogTier: tier,
+					watchdogPeak: peak(prev, tier),
+					localRuntime: ctx.localRuntime,
+				};
+			}
+			if (prev.phase === "stuck" && tier < 4) {
+				return {
+					...prev,
+					phase: prev.resumePhase ?? "thinking",
+					resumePhase: undefined,
+					watchdogTier: tier,
+					watchdogPeak: peak(prev, tier),
+					localRuntime: ctx.localRuntime,
+				};
+			}
+			return { ...prev, watchdogTier: tier, watchdogPeak: peak(prev, tier), localRuntime: ctx.localRuntime };
+		}
+		default:
+			return prev;
+	}
+}

package/src/interactive/status/summary.ts

@@ -0,0 +1,170 @@
+import { estimateReasoningTextTokens, extractReasoningTokens } from "../../domains/session/context-accounting.js";
+import type { AgentMessage } from "../../engine/types.js";
+import type { ReasoningTokenProvenance, RunTally, TurnStopReason, TurnSummary, WatchdogTier } from "./types.js";
+
+export interface BuildSummaryInput {
+	startedAt: number;
+	endedAt: number;
+	modelId: string;
+	targetId: string;
+	messages: ReadonlyArray<AgentMessage>;
+	watchdogPeak: WatchdogTier;
+	cancelled: boolean;
+	truncated?: boolean;
+}
+
+interface UsageLike {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+}
+
+function assistantThinkingText(message: AgentMessage): string {
+	const content = (message as { content?: unknown }).content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter(
+			(block): block is { type: "thinking"; thinking: string } =>
+				!!block &&
+				typeof block === "object" &&
+				(block as { type?: unknown }).type === "thinking" &&
+				typeof (block as { thinking?: unknown }).thinking === "string",
+		)
+		.map((block) => block.thinking)
+		.join("");
+}
+
+function finite(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+function assistantStopReason(value: unknown): TurnStopReason | null {
+	if (
+		value === "stop" ||
+		value === "length" ||
+		value === "toolUse" ||
+		value === "error" ||
+		value === "aborted" ||
+		value === "cancelled"
+	) {
+		return value;
+	}
+	return null;
+}
+
+export function emptyRunTally(): RunTally {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		reasoningTokens: 0,
+		hadProviderReasoning: false,
+		hadEstimatedReasoning: false,
+		toolCount: 0,
+		toolErrorCount: 0,
+	};
+}
+
+/**
+ * Fold one settled message into a run tally.
+ *
+ * `buildSummary` and the live accumulator that survives a cancel both go
+ * through here, so the two paths cannot drift into reporting a turn
+ * differently depending on how it ended.
+ */
+export function foldMessageIntoRunTally(tally: RunTally, message: AgentMessage): RunTally {
+	if (message.role === "toolResult") {
+		return {
+			...tally,
+			toolCount: tally.toolCount + 1,
+			toolErrorCount: tally.toolErrorCount + ((message as { isError?: boolean }).isError === true ? 1 : 0),
+		};
+	}
+	if (message.role !== "assistant") return tally;
+	const usage = (message as { usage?: UsageLike }).usage;
+	const next: RunTally = {
+		...tally,
+		inputTokens: tally.inputTokens + (usage ? finite(usage.input) : 0),
+		outputTokens: tally.outputTokens + (usage ? finite(usage.output) : 0),
+		cacheReadTokens: tally.cacheReadTokens + (usage ? finite(usage.cacheRead) : 0),
+		cacheWriteTokens: tally.cacheWriteTokens + (usage ? finite(usage.cacheWrite) : 0),
+	};
+	const reasoning = usage ? extractReasoningTokens(usage) : null;
+	if (reasoning !== null) {
+		next.reasoningTokens += reasoning;
+		next.hadProviderReasoning = true;
+		return next;
+	}
+	// Some providers emit thinking blocks without a usage object. Keep the
+	// fallback explicitly estimated so a run containing both shapes is
+	// reported as mixed rather than silently dropping the unreported block.
+	const estimated = estimateReasoningTextTokens(assistantThinkingText(message));
+	if (estimated !== null) {
+		next.reasoningTokens += estimated;
+		next.hadEstimatedReasoning = true;
+	}
+	return next;
+}
+
+export interface SummaryFromTallyInput {
+	startedAt: number;
+	endedAt: number;
+	modelId: string;
+	targetId: string;
+	watchdogPeak: WatchdogTier;
+	stopReason: TurnStopReason;
+	stopDetail?: string;
+	truncated?: boolean;
+}
+
+export function summaryFromRunTally(tally: RunTally, input: SummaryFromTallyInput): TurnSummary {
+	const summary: TurnSummary = {
+		elapsedMs: Math.max(0, input.endedAt - input.startedAt),
+		modelId: input.modelId,
+		targetId: input.targetId,
+		inputTokens: tally.inputTokens,
+		outputTokens: tally.outputTokens,
+		cacheReadTokens: tally.cacheReadTokens,
+		cacheWriteTokens: tally.cacheWriteTokens,
+		toolCount: tally.toolCount,
+		toolErrorCount: tally.toolErrorCount,
+		stopReason: input.stopReason,
+		...(input.stopDetail !== undefined ? { stopDetail: input.stopDetail } : {}),
+		watchdogPeak: input.watchdogPeak,
+		truncated: input.truncated === true,
+	};
+	if (tally.hadProviderReasoning || tally.hadEstimatedReasoning) {
+		summary.reasoningTokens = tally.reasoningTokens;
+		const provenance: ReasoningTokenProvenance =
+			tally.hadProviderReasoning && tally.hadEstimatedReasoning
+				? "mixed"
+				: tally.hadProviderReasoning
+					? "provider"
+					: "estimated";
+		summary.reasoningTokenProvenance = provenance;
+	}
+	return summary;
+}
+
+export function buildSummary(input: BuildSummaryInput): TurnSummary {
+	let stopReason: TurnStopReason = input.cancelled ? "cancelled" : "stop";
+	let tally = emptyRunTally();
+	for (const message of input.messages) {
+		tally = foldMessageIntoRunTally(tally, message);
+		if (message.role === "assistant") {
+			const reason = assistantStopReason((message as { stopReason?: unknown }).stopReason);
+			if (reason && reason !== "stop") stopReason = reason;
+		}
+	}
+	return summaryFromRunTally(tally, {
+		startedAt: input.startedAt,
+		endedAt: input.endedAt,
+		modelId: input.modelId,
+		targetId: input.targetId,
+		watchdogPeak: input.watchdogPeak,
+		stopReason,
+		...(input.truncated !== undefined ? { truncated: input.truncated } : {}),
+	});
+}