@zvada/agent-server 0.2.1 → 0.3.0

package/src/protocol/reduce.ts

@@ -0,0 +1,749 @@
+import { z } from "zod";
+// The package ships raw .ts — keep imports exactly-used, or every consumer
+// compiling with noUnusedLocals inherits the noise as build errors.
+import { ErrorCategorySchema, ErrorInfoSchema } from "./errors.ts";
+import { isUnknownEvent } from "./guards.ts";
+import { AgentHarnessSchema } from "./harness.ts";
+import {
+	type CompactionStatus,
+	CompactionStatusSchema,
+	CompactionTriggerSchema,
+	type DecodedLifecycleEvent,
+	PermissionOptionSchema,
+	PermissionOutcomeSchema,
+	PermissionToolCallSchema,
+	SessionEndReasonSchema,
+	StopReasonSchema,
+	type UnknownEvent,
+} from "./lifecycle.ts";
+import { type Part, PartSchema, type UnknownPart } from "./parts.ts";
+import { EpochMsSchema } from "./time.ts";
+import { DEFAULT_TOKEN_USAGE, TokenUsageSchema, addTokenUsage } from "./tokens.ts";
+
+/**
+ * The canonical LifecycleEvent → conversation-state reducer.
+ *
+ * Every consumer of the stream ends up writing this fold (a UI store, a
+ * persistence shim, a CLI renderer — deus, agnt, and this repo's own CLI each
+ * had one). This is the reference implementation of the stream's consumption
+ * rules, so products inherit them instead of re-deriving them:
+ *
+ *  - `message.part` snapshots UPSERT by `part.id` — including a tool part
+ *    completing after its message (or turn) ended: the event's `messageId`
+ *    names the ORIGINAL message, and the upsert lands there.
+ *  - deltas are additive streaming aids; part snapshots are authoritative and
+ *    replace whatever the deltas built (field-ownership rule:
+ *    `delta("A"), delta("B"), snapshot{text:"C"}` folds to `"C"`).
+ *  - permission requests resolve exactly once (turn end / cancel resolves
+ *    stragglers as cancelled) — `pendingPermissions()` is what a UI renders.
+ *  - at `turn.ended{stopReason:"cancelled"}` every non-terminal tool part of
+ *    that turn transitions to `status:"cancelled"` (cancellation closure).
+ *  - `session.compaction` is an ID-addressed POSITIONAL entity: its first
+ *    event anchors it in the `timeline`; later upserts advance it in place.
+ *  - `turn.ended.tokens` is the turn's billing total (summed into `totals`);
+ *    `session.usage` is the live context gauge — different numbers, both kept.
+ *  - unknown event types are preserved in `unknownEvents` (Law 6), never
+ *    dropped.
+ *
+ * Pure and copy-on-write: `reduceConversation` never mutates its input; every
+ * changed slice (timeline entry, parts array, turn) is a fresh object, so the
+ * state is directly usable in identity-diffing UIs (React et al).
+ *
+ * Feed each event exactly once, in `seq` order — the wire client already
+ * dedupes and heals gaps; embedded consumers get ordered events from the sink.
+ * (`createSeqCursor()` is that discipline on its own, for consumers folding
+ * envelopes they received some other way.)
+ *
+ * Sinks that WRITE rather than render use `reduceConversationWithChanges`: the
+ * same fold, plus the list of what it touched (see `ConversationChange`).
+ */
+
+const UnknownPartSchema = z.looseObject({
+	type: z.string(),
+	id: z.string(),
+	sessionId: z.string(),
+	messageId: z.string(),
+	parentToolCallId: z.string().optional(),
+	raw: z.record(z.string(), z.unknown()),
+}) as unknown as z.ZodType<UnknownPart>;
+
+export const ConversationMessageSchema = z.object({
+	kind: z.literal("message"),
+	messageId: z.string(),
+	sessionId: z.string(),
+	turnId: z.string(),
+	outputIndex: z.number(),
+	role: z.enum(["user", "assistant"]),
+	/** Set when this is a sub-agent's output — nest it under that tool call. */
+	parentToolCallId: z.string().optional(),
+	model: z.string().optional(),
+	parts: z.array(z.union([PartSchema, UnknownPartSchema])),
+	startedAt: EpochMsSchema,
+	endedAt: EpochMsSchema.optional(),
+});
+export type ConversationMessage = z.infer<typeof ConversationMessageSchema>;
+
+/**
+ * The folded compaction entity. Upserts MERGE (a later event that omits
+ * `summary`/`preTokens` keeps the ones already known) — deliberately unlike
+ * `message.part`, whose snapshots fully REPLACE. A compaction's fields arrive
+ * from different harness events at different times ("started, 150k in" then
+ * "done, here's the summary"), so replace-semantics would make every producer
+ * restate everything or lose it. The cost is stated plainly: a producer cannot
+ * clear a compaction field once set.
+ */
+export const ConversationCompactionSchema = z.object({
+	kind: z.literal("compaction"),
+	compactionId: z.string(),
+	turnId: z.string(),
+	status: CompactionStatusSchema,
+	trigger: CompactionTriggerSchema.optional(),
+	preTokens: z.number().optional(),
+	postTokens: z.number().optional(),
+	summary: z.string().optional(),
+	abstractsIds: z.array(z.string()).optional(),
+	timestamp: EpochMsSchema,
+});
+export type ConversationCompaction = z.infer<typeof ConversationCompactionSchema>;
+
+/** The ordered render list: messages and compactions interleaved in stream order. */
+export const TimelineEntrySchema = z.discriminatedUnion("kind", [
+	ConversationMessageSchema,
+	ConversationCompactionSchema,
+]);
+export type TimelineEntry = z.infer<typeof TimelineEntrySchema>;
+
+export const ConversationTurnSchema = z.object({
+	turnId: z.string(),
+	/** Derived view state, not wire vocabulary. */
+	status: z.enum(["active", "ended"]),
+	stopReason: StopReasonSchema.optional(),
+	finishReason: z.string().optional(),
+	tokens: TokenUsageSchema.optional(),
+	cost: z.number().optional(),
+	/** Terminal error from `turn.ended`, when the turn failed. */
+	error: ErrorInfoSchema.optional(),
+	/** Non-terminal `error` events attributed to this turn. */
+	errors: z.array(
+		z.object({
+			category: ErrorCategorySchema,
+			message: z.string(),
+			recoverable: z.boolean(),
+			timestamp: EpochMsSchema,
+		}),
+	),
+	startedAt: EpochMsSchema,
+	endedAt: EpochMsSchema.optional(),
+});
+export type ConversationTurn = z.infer<typeof ConversationTurnSchema>;
+
+export const ConversationPermissionSchema = z.object({
+	requestId: z.string(),
+	turnId: z.string(),
+	title: z.string(),
+	toolCall: PermissionToolCallSchema.optional(),
+	options: z.array(PermissionOptionSchema),
+	requestedAt: EpochMsSchema,
+	/** Absent while the request is pending. */
+	outcome: PermissionOutcomeSchema.optional(),
+	resolvedAt: EpochMsSchema.optional(),
+});
+export type ConversationPermission = z.infer<typeof ConversationPermissionSchema>;
+
+const UnknownEventSchema = z.looseObject({
+	type: z.string(),
+	sessionId: z.string().optional(),
+	raw: z.record(z.string(), z.unknown()),
+}) as unknown as z.ZodType<UnknownEvent>;
+
+export const ConversationStateSchema = z.object({
+	sessionId: z.string().optional(),
+	/** Persist this and pass it back as `config.resumeSessionId` to resume. */
+	nativeSessionId: z.string().optional(),
+	harness: AgentHarnessSchema.optional(),
+	model: z.string().optional(),
+	/** From the last resume-requesting turn: false = fresh-session fallback. */
+	resumed: z.boolean().optional(),
+	timeline: z.array(TimelineEntrySchema),
+	turns: z.array(ConversationTurnSchema),
+	permissions: z.array(ConversationPermissionSchema),
+	/** Live context gauge (`session.usage`) — how full the window is NOW. */
+	usage: z
+		.object({
+			used: z.number(),
+			size: z.number().optional(),
+			cost: z.number().optional(),
+			updatedAt: EpochMsSchema,
+		})
+		.optional(),
+	/** Sum of every ended turn's billing tokens. */
+	totals: TokenUsageSchema,
+	totalCost: z.number().optional(),
+	/** `error` events that carried no turnId. */
+	errors: z.array(
+		z.object({
+			category: ErrorCategorySchema,
+			message: z.string(),
+			recoverable: z.boolean(),
+			timestamp: EpochMsSchema,
+		}),
+	),
+	/** The harness session is over (`session.ended`). */
+	ended: z.object({ reason: SessionEndReasonSchema, timestamp: EpochMsSchema }).optional(),
+	/** Unknown event types, preserved in arrival order (Law 6). */
+	unknownEvents: z.array(UnknownEventSchema),
+	/**
+	 * Raw JSON accumulated from `tool_input` deltas per part id, for UIs that
+	 * stream tool input as it is typed. Cleared when the part's snapshot
+	 * arrives with the parsed input (the authoritative form).
+	 */
+	toolInputJson: z.record(z.string(), z.string()),
+});
+export type ConversationState = z.infer<typeof ConversationStateSchema>;
+
+/** A fresh, empty conversation state. */
+export function emptyConversation(): ConversationState {
+	return {
+		timeline: [],
+		turns: [],
+		permissions: [],
+		// The same zero as `addTokenUsage` produces, so "nothing yet" and "summed
+		// nothing" are the same shape — a UI never has to handle two empties.
+		totals: { ...DEFAULT_TOKEN_USAGE },
+		errors: [],
+		unknownEvents: [],
+		toolInputJson: {},
+	};
+}
+
+/** The permission requests still awaiting an answer — render these. */
+export function pendingPermissions(state: ConversationState): ConversationPermission[] {
+	return state.permissions.filter((p) => p.outcome === undefined);
+}
+
+/** The message entries of the timeline, in order (convenience accessor). */
+export function conversationMessages(state: ConversationState): ConversationMessage[] {
+	return state.timeline.filter((e): e is ConversationMessage => e.kind === "message");
+}
+
+/**
+ * What one fold actually touched — the seam between "the stream says this" and
+ * "so write these rows / invalidate these queries".
+ *
+ * Emitted by `reduceConversationWithChanges`, which INSTRUMENTS the fold
+ * rather than diffing states: every mutation site reports itself, so a change
+ * list is exactly the set of writes the reducer performed, in the order it
+ * performed them. A no-op fold (a replayed duplicate) reports nothing.
+ *
+ * The addressing is the wire's: `messageId`/`partId`/`turnId`/`requestId` are
+ * the same ids the events carry, so a sink can upsert by them without holding
+ * a second index. `outputIndex`/`partIndex` are the event's positions when the
+ * change came from a `message.part`; for the parts the reducer closes itself
+ * (cancellation closure) they are the message's `outputIndex` and the part's
+ * position in that message — the same numbers for any stream that arrived in
+ * order.
+ */
+export const ConversationChangeSchema = z.discriminatedUnion("kind", [
+	/** A message was added to the timeline (started, or shelled in by a part). */
+	z.object({ kind: z.literal("message-upserted"), messageId: z.string(), turnId: z.string() }),
+	/** A part snapshot landed in its message (or a delta extended one in place). */
+	z.object({
+		kind: z.literal("part-upserted"),
+		messageId: z.string(),
+		partId: z.string(),
+		outputIndex: z.number(),
+		partIndex: z.number(),
+	}),
+	/** A message got its `endedAt` (once — a repeat is not a change). */
+	z.object({ kind: z.literal("message-ended"), messageId: z.string() }),
+	/** Streamed tool-input JSON was appended to `toolInputJson[partId]`. */
+	z.object({ kind: z.literal("delta-buffered"), partId: z.string() }),
+	/** A turn was opened, ended, or gained a non-terminal error. */
+	z.object({ kind: z.literal("turn-updated"), turnId: z.string() }),
+	z.object({ kind: z.literal("compaction-upserted"), compactionId: z.string() }),
+	/** A permission was requested, answered, or cancelled by its turn ending. */
+	z.object({ kind: z.literal("permission-updated"), requestId: z.string() }),
+	/** The context gauge (`session.usage`) or the billing totals moved. */
+	z.object({ kind: z.literal("usage-updated") }),
+	/**
+	 * Session-scoped facts changed: the `session.created` identity fields, or
+	 * an `error` event with no turn to attribute (it lands in `state.errors`).
+	 */
+	z.object({ kind: z.literal("session-meta-updated") }),
+	z.object({ kind: z.literal("session-ended") }),
+	z.object({ kind: z.literal("unknown-event-recorded") }),
+]);
+export type ConversationChange = z.infer<typeof ConversationChangeSchema>;
+
+/** Where a mutation site reports itself. */
+type ChangeRecorder = (change: ConversationChange) => void;
+
+/** The recorder the public `reduceConversation` passes — zero behavior change. */
+const IGNORE_CHANGES: ChangeRecorder = () => {};
+
+/** Replace the message with id `messageId` via `update`; no-op when absent. */
+function withMessage(
+	state: ConversationState,
+	messageId: string,
+	update: (message: ConversationMessage) => ConversationMessage,
+): ConversationState {
+	// Search from the end: the message being updated is almost always recent.
+	for (let i = state.timeline.length - 1; i >= 0; i--) {
+		const entry = state.timeline[i] as TimelineEntry;
+		if (entry.kind !== "message" || entry.messageId !== messageId) continue;
+		const updated = update(entry);
+		// Identity short-circuit: an update that declined (a repeated
+		// message.ended, a delta with no open snapshot) is a true no-op —
+		// returning the SAME state object makes "no changes recorded" and
+		// "state unchanged" the same fact, which sinks and tests rely on.
+		if (updated === entry) return state;
+		const timeline = state.timeline.slice();
+		timeline[i] = updated;
+		return { ...state, timeline };
+	}
+	return state;
+}
+
+/** Append a fresh message unless its id is already known (replay-safe). */
+function openMessage(
+	state: ConversationState,
+	init: {
+		messageId: string;
+		sessionId: string;
+		turnId: string;
+		outputIndex: number;
+		timestamp: number;
+		role: "user" | "assistant";
+		parentToolCallId?: string;
+		model?: string;
+	},
+	record: ChangeRecorder,
+): ConversationState {
+	if (state.timeline.some((e) => e.kind === "message" && e.messageId === init.messageId)) {
+		return state;
+	}
+	record({ kind: "message-upserted", messageId: init.messageId, turnId: init.turnId });
+	const message: ConversationMessage = {
+		kind: "message",
+		messageId: init.messageId,
+		sessionId: init.sessionId,
+		turnId: init.turnId,
+		outputIndex: init.outputIndex,
+		role: init.role,
+		...(init.parentToolCallId !== undefined && { parentToolCallId: init.parentToolCallId }),
+		...(init.model !== undefined && { model: init.model }),
+		parts: [],
+		startedAt: init.timestamp,
+	};
+	return { ...state, timeline: [...state.timeline, message] };
+}
+
+/** Resolve an ended turn's still-pending permissions as cancelled. */
+function cancelPendingForTurn(
+	permissions: ConversationPermission[],
+	turnId: string,
+	at: number,
+	record: ChangeRecorder,
+): ConversationPermission[] {
+	if (!permissions.some((p) => p.turnId === turnId && p.outcome === undefined)) {
+		return permissions;
+	}
+	return permissions.map((p) => {
+		if (p.turnId !== turnId || p.outcome !== undefined) return p;
+		record({ kind: "permission-updated", requestId: p.requestId });
+		return { ...p, outcome: { outcome: "cancelled" as const }, resolvedAt: at };
+	});
+}
+
+function upsertPart(
+	parts: Array<Part | UnknownPart>,
+	part: Part | UnknownPart,
+): Array<Part | UnknownPart> {
+	const index = parts.findIndex((p) => p.id === part.id);
+	if (index === -1) return [...parts, part];
+	const next = parts.slice();
+	next[index] = part;
+	return next;
+}
+
+/**
+ * `_meta` key holding the partial JSON a PENDING tool was still streaming when
+ * the turn was cancelled. The `cancelled` state carries a parsed `input`,
+ * which a pending call never had — without this the only record of what the
+ * call was about is dropped, and a cancel-heavy UI renders an empty tool card.
+ * Namespaced per Law 4: root names on canonical types stay reserved.
+ */
+export const PARTIAL_INPUT_META_KEY = "agent-server/partialInput";
+
+/**
+ * Cancellation closure: transition every non-terminal tool part of the turn's
+ * messages to `status:"cancelled"` — guarantees a consistent terminal state
+ * even when the harness died mid-tool and could emit nothing.
+ */
+function closeCancelledTools(
+	state: ConversationState,
+	turnId: string,
+	at: number,
+	record: ChangeRecorder,
+): ConversationState {
+	let changed = false;
+	const timeline = state.timeline.map((entry) => {
+		if (entry.kind !== "message" || entry.turnId !== turnId) return entry;
+		let messageChanged = false;
+		const parts = entry.parts.map((part, partIndex): Part | UnknownPart => {
+			if ("raw" in part || part.type !== "tool") return part;
+			const open = part.state;
+			if (open.status !== "pending" && open.status !== "in_progress") return part;
+			messageChanged = true;
+			record({
+				kind: "part-upserted",
+				messageId: entry.messageId,
+				partId: part.id,
+				outputIndex: entry.outputIndex,
+				partIndex,
+			});
+			// The half-streamed input survives the cancel. Its source is the
+			// SNAPSHOT's partialInput when the adapter re-stated one, else the
+			// fold's own delta accumulator — shipped adapters stream tool input
+			// as deltas without re-snapshotting the pending tool, so without the
+			// fallback the preservation never fires on a real cancel.
+			const streamed =
+				open.status === "pending" ? open.partialInput || state.toolInputJson[part.id] : undefined;
+			const meta = streamed ? { ...open._meta, [PARTIAL_INPUT_META_KEY]: streamed } : open._meta;
+			return {
+				...part,
+				state: {
+					status: "cancelled" as const,
+					input: open.status === "in_progress" ? open.input : {},
+					// A pending tool never started, so the cancel stamps both ends.
+					time: { start: open.status === "in_progress" ? open.time.start : at, end: at },
+					...(meta !== undefined && { _meta: meta }),
+				},
+			};
+		});
+		if (!messageChanged) return entry;
+		changed = true;
+		return { ...entry, parts };
+	});
+	return changed ? { ...state, timeline } : state;
+}
+
+/** Fold one lifecycle event into the conversation. Pure; returns a new state. */
+export function reduceConversation(
+	state: ConversationState,
+	event: DecodedLifecycleEvent | UnknownEvent,
+): ConversationState {
+	return reduceWith(state, event, IGNORE_CHANGES);
+}
+
+/**
+ * The same fold, plus the list of what it touched — for sinks that must WRITE
+ * rather than re-render: a persistence layer deciding which rows to upsert, a
+ * cache deciding which queries to invalidate, a projection keeping a second
+ * store in step.
+ *
+ * The changes are recorded BY the fold, not diffed from its output: there is
+ * exactly one implementation of the consumption rules, and `reduceConversation`
+ * is this function with the recorder thrown away. That is what makes the two
+ * impossible to drift apart — a new mutation site either reports itself or is
+ * invisible to every sink at once, which the tests pin.
+ *
+ * Ordering within one event is causal: the message shell before the part that
+ * forced it, the turn before the permissions its end cancelled. SQL semantics
+ * (ON CONFLICT vs REPLACE, COALESCE guards) stay yours — they are schema
+ * knowledge, not fold knowledge.
+ */
+export function reduceConversationWithChanges(
+	state: ConversationState,
+	event: DecodedLifecycleEvent | UnknownEvent,
+): { state: ConversationState; changes: ConversationChange[] } {
+	const changes: ConversationChange[] = [];
+	const next = reduceWith(state, event, (change) => changes.push(change));
+	return { state: next, changes };
+}
+
+function reduceWith(
+	state: ConversationState,
+	event: DecodedLifecycleEvent | UnknownEvent,
+	record: ChangeRecorder,
+): ConversationState {
+	if (isUnknownEvent(event)) {
+		record({ kind: "unknown-event-recorded" });
+		return { ...state, unknownEvents: [...state.unknownEvents, event] };
+	}
+	switch (event.type) {
+		case "session.created":
+			record({ kind: "session-meta-updated" });
+			return {
+				...state,
+				sessionId: event.sessionId,
+				nativeSessionId: event.nativeSessionId,
+				harness: event.harness,
+				...(event.model !== undefined && { model: event.model }),
+				...(event.resumed !== undefined && { resumed: event.resumed }),
+			};
+
+		case "session.ended":
+			record({ kind: "session-ended" });
+			return { ...state, ended: { reason: event.reason, timestamp: event.timestamp } };
+
+		case "turn.started": {
+			const existing = state.turns.findIndex((t) => t.turnId === event.turnId);
+			if (existing !== -1) return state; // replay overlap — the turn is known
+			const turn: ConversationTurn = {
+				turnId: event.turnId,
+				status: "active",
+				errors: [],
+				startedAt: event.timestamp,
+			};
+			record({ kind: "turn-updated", turnId: event.turnId });
+			return { ...state, turns: [...state.turns, turn] };
+		}
+
+		case "message.started":
+			return openMessage(state, { ...event, role: event.role }, record);
+
+		case "message.part": {
+			// Tolerance for the contract's stated exception: a part may arrive for
+			// a message whose start this consumer never saw — open a shell for it.
+			const ensured = openMessage(state, { ...event, role: "assistant" }, record);
+			let upserted = withMessage(ensured, event.messageId, (message) => ({
+				...message,
+				parts: upsertPart(message.parts, event.part),
+			}));
+			record({
+				kind: "part-upserted",
+				messageId: event.messageId,
+				partId: event.part.id,
+				outputIndex: event.outputIndex,
+				partIndex: event.partIndex,
+			});
+			// Redelivery convergence: a snapshot replayed AFTER its turn already
+			// ended cancelled would re-open the tool (the replayed turn.ended is a
+			// no-op, so the closure never re-runs) — re-apply the closure so a
+			// whole-turn redelivery folds to the same terminal state.
+			const owningTurn = upserted.turns.find((t) => t.turnId === event.turnId);
+			if (
+				owningTurn?.status === "ended" &&
+				!("raw" in event.part) &&
+				event.part.type === "tool" &&
+				(event.part.state.status === "pending" || event.part.state.status === "in_progress")
+			) {
+				upserted = closeCancelledTools(
+					upserted,
+					event.turnId,
+					owningTurn.endedAt ?? event.timestamp,
+					record,
+				);
+			}
+			// The snapshot's input is authoritative — drop the streamed JSON.
+			if (
+				!("raw" in event.part) &&
+				event.part.type === "tool" &&
+				upserted.toolInputJson[event.part.id] !== undefined
+			) {
+				const { [event.part.id]: _dropped, ...toolInputJson } = upserted.toolInputJson;
+				return { ...upserted, toolInputJson };
+			}
+			return upserted;
+		}
+
+		case "message.part.delta": {
+			const { delta } = event;
+			if (delta.type === "tool_input") {
+				record({ kind: "delta-buffered", partId: event.partId });
+				return {
+					...state,
+					toolInputJson: {
+						...state.toolInputJson,
+						[event.partId]: (state.toolInputJson[event.partId] ?? "") + delta.input,
+					},
+				};
+			}
+			return withMessage(state, event.messageId, (message) => {
+				const index = message.parts.findIndex((p) => p.id === event.partId);
+				if (index === -1) return message; // no open snapshot yet — the next snapshot carries the text
+				const part = message.parts[index] as Part | UnknownPart;
+				if ("raw" in part) return message;
+				if (part.type !== "text" && part.type !== "reasoning") return message;
+				const parts = message.parts.slice();
+				parts[index] = { ...part, text: part.text + delta.text };
+				record({
+					kind: "part-upserted",
+					messageId: event.messageId,
+					partId: event.partId,
+					outputIndex: event.outputIndex,
+					partIndex: event.partIndex,
+				});
+				return { ...message, parts };
+			});
+		}
+
+		case "message.ended":
+			return withMessage(state, event.messageId, (message) => {
+				if (message.endedAt !== undefined) return message;
+				record({ kind: "message-ended", messageId: event.messageId });
+				return { ...message, endedAt: event.timestamp };
+			});
+
+		case "turn.ended": {
+			const index = state.turns.findIndex((t) => t.turnId === event.turnId);
+			const base: ConversationTurn = (state.turns[index] as ConversationTurn | undefined) ?? {
+				turnId: event.turnId,
+				status: "active",
+				errors: [],
+				startedAt: event.timestamp,
+			};
+			if (base.status === "ended") return state; // replay overlap
+			const turn: ConversationTurn = {
+				...base,
+				status: "ended",
+				stopReason: event.stopReason,
+				...(event.finishReason !== undefined && { finishReason: event.finishReason }),
+				...(event.tokens !== undefined && { tokens: event.tokens }),
+				...(event.cost !== undefined && { cost: event.cost }),
+				...(event.error !== undefined && { error: event.error }),
+				endedAt: event.timestamp,
+			};
+			const turns = index === -1 ? [...state.turns, turn] : state.turns.slice();
+			if (index !== -1) turns[index] = turn;
+			record({ kind: "turn-updated", turnId: event.turnId });
+			// Terminal-permission invariant: normally a no-op (the engine emits
+			// permission.resolved first) — load-bearing on anomalous/partial
+			// streams so no prompt of an ended turn dangles as pending.
+			const permissions = cancelPendingForTurn(
+				state.permissions,
+				event.turnId,
+				event.timestamp,
+				record,
+			);
+			// The turn's billing rolls into the session aggregate.
+			if (event.tokens !== undefined || event.cost !== undefined) {
+				record({ kind: "usage-updated" });
+			}
+			let next: ConversationState = {
+				...state,
+				turns,
+				permissions,
+				...(event.tokens !== undefined && { totals: addTokenUsage(state.totals, event.tokens) }),
+				...(event.cost !== undefined && { totalCost: (state.totalCost ?? 0) + event.cost }),
+			};
+			// A turn's end closes whatever it left in flight — for EVERY terminal,
+			// not just user cancels. The contract already says so (§7's
+			// late-parts-are-terminal-tools rule: nothing non-terminal may follow
+			// turn.ended), and an error/max_tokens end that leaves a tool
+			// `in_progress` otherwise renders as a spinner that never stops in
+			// every consumer. `cancelled` is the truthful closed status: the tool
+			// did not fail — the turn died before it settled.
+			next = closeCancelledTools(next, event.turnId, event.timestamp, record);
+			return next;
+		}
+
+		case "session.usage":
+			// Sticky merge: harnesses report `size`/`cost` intermittently (Claude
+			// only on the final result) — a fresher `used` must not erase the last
+			// known window size or cumulative cost. Consumers inherit this instead
+			// of re-deriving it (deus carried a SQL COALESCE for exactly this).
+			record({ kind: "usage-updated" });
+			return {
+				...state,
+				usage: {
+					used: event.used,
+					...(event.size !== undefined
+						? { size: event.size }
+						: state.usage?.size !== undefined
+							? { size: state.usage.size }
+							: {}),
+					...(event.cost !== undefined
+						? { cost: event.cost }
+						: state.usage?.cost !== undefined
+							? { cost: state.usage.cost }
+							: {}),
+					updatedAt: event.timestamp,
+				},
+			};
+
+		case "session.compaction": {
+			const index = state.timeline.findIndex(
+				(e) => e.kind === "compaction" && e.compactionId === event.compactionId,
+			);
+			const entry: ConversationCompaction = {
+				kind: "compaction",
+				compactionId: event.compactionId,
+				turnId: event.turnId,
+				status: event.status as CompactionStatus,
+				...(event.trigger !== undefined && { trigger: event.trigger }),
+				...(event.preTokens !== undefined && { preTokens: event.preTokens }),
+				...(event.postTokens !== undefined && { postTokens: event.postTokens }),
+				...(event.summary !== undefined && { summary: event.summary }),
+				...(event.abstractsIds !== undefined && { abstractsIds: event.abstractsIds }),
+				timestamp: event.timestamp,
+			};
+			record({ kind: "compaction-upserted", compactionId: event.compactionId });
+			if (index === -1) {
+				// First appearance anchors the entity's position in the timeline.
+				return { ...state, timeline: [...state.timeline, entry] };
+			}
+			// Upsert in place — the entity never moves.
+			const existing = state.timeline[index] as ConversationCompaction;
+			const timeline = state.timeline.slice();
+			timeline[index] = {
+				...existing,
+				...entry,
+				// Preserve first-seen anchor semantics: keep the original timestamp.
+				timestamp: existing.timestamp,
+			};
+			return { ...state, timeline };
+		}
+
+		case "permission.requested": {
+			if (state.permissions.some((p) => p.requestId === event.requestId)) return state;
+			const permission: ConversationPermission = {
+				requestId: event.requestId,
+				turnId: event.turnId,
+				title: event.title,
+				...(event.toolCall !== undefined && { toolCall: event.toolCall }),
+				options: event.options,
+				requestedAt: event.timestamp,
+			};
+			record({ kind: "permission-updated", requestId: event.requestId });
+			return { ...state, permissions: [...state.permissions, permission] };
+		}
+
+		case "permission.resolved": {
+			const index = state.permissions.findIndex((p) => p.requestId === event.requestId);
+			if (index === -1) return state;
+			const existing = state.permissions[index] as ConversationPermission;
+			if (existing.outcome !== undefined) return state; // resolves exactly once
+			const permissions = state.permissions.slice();
+			permissions[index] = { ...existing, outcome: event.outcome, resolvedAt: event.timestamp };
+			record({ kind: "permission-updated", requestId: event.requestId });
+			return { ...state, permissions };
+		}
+
+		case "error": {
+			const entry = {
+				category: event.category,
+				message: event.message,
+				recoverable: event.recoverable,
+				timestamp: event.timestamp,
+			};
+			if (event.turnId !== undefined) {
+				const index = state.turns.findIndex((t) => t.turnId === event.turnId);
+				if (index !== -1) {
+					const turn = state.turns[index] as ConversationTurn;
+					const turns = state.turns.slice();
+					turns[index] = { ...turn, errors: [...turn.errors, entry] };
+					record({ kind: "turn-updated", turnId: event.turnId });
+					return { ...state, turns };
+				}
+			}
+			// No turn to attribute it to — a session-scoped fact.
+			record({ kind: "session-meta-updated" });
+			return { ...state, errors: [...state.errors, entry] };
+		}
+
+		case "raw":
+			return state;
+	}
+}