Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

112 KB
Raw Blame
/**
 * OmniMessage stream → render view-model reducer. A
 * pure logic module, no React dependency: takes in an ordered sequence of
 * OmniMessage (history's complete messages + real-time partial/complete/
 * event), and produces a `ChatItem[]` view model (updated in place, with the caller triggering the re-render).
 *
 * Key points:
 *   - Fragment tracking: partial_text / partial_thinking are tracked by "the
 *     currently open fragment"; partial_tool_call / partial_tool_call_output
 *     are attributed to a tool card by tool_call_id. start opens it, delta
 *     accumulates, stop closes it; the subsequent complete message
 *     **replaces** the fragment's content (guaranteeing consistency;
 *     with no open fragment — mid-stream join — it's appended directly); an
 *     orphan delta (no start seen) is ignored, converging once the complete message arrives.
 *   - origin routing: messages carrying an origin go into a nested child
 *     model (surfaced in the UI as a subagent chip + the subagents panel);
 *     on a sub-session's first message it binds to "the most recent allowed
 *     (decision=allow) and not-yet-complete run_subagent tool card that
 *     hasn't been bound to an origin yet", falling back to a standalone
 *     SubagentItem if none is found; its opening prompt then moves it onto the
 *     card of the call that carried that prompt (see moveToSpawningCard).
 *     Inside the nested model, the same reducer recurses (with the first
 *     origin hop stripped). Sub-session token_usage counts toward this
 *     level's stats (same convention as the CLI).
 *   - Events: approval_decision annotates the corresponding tool card
 *     (labeled "manual" if clicked on this end, "automatic" otherwise);
 *     abort → an interruption marker item; request_end ending in any status
 *     the engine reconnects on (retryable) → a retry-hint item (the engine discards that
 *     attempt and resends the original input; the next request_begin marks the hint as resent, and an
 *     arriving abort marks it as retries exhausted); other request_begin/end
 *     events aren't rendered (Request duration is covered by Trace
 *     performance analysis); compaction_begin/end → a banner item;
 *     token_usage → fed into stats (task-stats.ts).
 *   - Compaction-internal messages: model_msg within a
 *     compaction_begin↔end range (the compaction prompt, thinking and summary output)
 *     are never rendered as transcript items and never counted toward Task
 *     segmentation; the request's thinking and the summary's own text (live
 *     partial_thinking / partial_text fragments, or the span's complete thinking
 *     and assistant text on rebuild) accumulate onto the running compaction
 *     banner instead (issue #290);
 *     user text prefixed with `[context_summary]` is a compaction-summary
 *     injection, treated as internal input (not rendered, doesn't start a new Task).
 *   - Task segmentation: a complete text/image/video message on the main
 *     session's user side starts a new Task; a Task ends when the live
 *     stream receives task_state:idle (notifyTaskIdle), or — during history
 *     rebuild — when the next Task starts / the stream ends
 *     (finalizeHistory). Either way the duration comes from Trace timestamps
 *     alone and never the local clock, so a round settles to the same figure
 *     watched live and replayed after a reload. A stats row is only added if token_usage occurred during the Task.
 *   - Overlap-dedup helpers: buildDedupIndex/isDuplicate
 *     judge duplicates by exact match of the envelope JSON; when a complete
 *     message hits the dedup check, discardFragmentFor also discards the corresponding in-flight fragment.
 * Docs: /docs/omni-message § "The streaming discipline".
 */
import {
  isEventMessage,
  isModelMessage,
  isPartialPayload,
  normalizeSessionSource,
  parseBackgroundTaskDoneMessage,
  parseUserSteeringText,
} from "@adelie/core/omnimessage";
import type {
  ApprovalDecision,
  CompactionMode,
  CompactionReason,
  CompleteModelPayload,
  EventPayload,
  OmniMessage,
  PartialModelPayload,
  SessionMetaPayload,
  SessionSource,
  StopReason,
  TokenUsagePayload,
} from "@adelie/core/omnimessage";
import type { TracePosition } from "@adelie/server/api";
import {
  addLlmDuration,
  addToolExecution,
  beginCompaction,
  commitPendingCompaction,
  createTaskStatsTracker,
  endCompaction,
  endTask,
  resetTaskCounters,
  trackMainUsage,
  trackSubagentUsage,
} from "./task-stats";
import type { TaskStats, TaskStatsTracker } from "./task-stats";
import { classifyMemoryPath, mergeMemoryChanges } from "./memory-changes";
import type { MemoryChangeEntry, MemoryChangeRow } from "./memory-changes";

// ---------------------------------------------------------------------------
// View model types
// ---------------------------------------------------------------------------

/** Source of an approval decision: clicked on this end (manual) / other (automatic judgment or submitted by another end). A policy veto needs no source — its decision value is "forbidden". */
export type DecisionSource = "manual" | "remote";

export interface UserTextItem {
  kind: "user_text";
  id: number;
  text: string;
  /** Set for a harness-injected input (a stop hook's continue, the goal plugin's round protocol): rendered with an origin caption, skipped by input history and the outline. */
  sender?: "harness";
  /** Message timestamp (milliseconds): shown on footer hover. History and real time share the same source — this message's own timestamp. */
  atMs?: number;
}

/**
 * Mid-run steering: a `[user_steering]`-wrapped user text delivered between turns
 * (see core `Session.steer`). Rendered as a compact user-styled chip **inside** the running
 * Task's flow — it never starts a new Task (`text` is the inner message, marker stripped).
 */
export interface UserSteeringItem {
  kind: "user_steering";
  id: number;
  text: string;
  /**
   * Images sent with this steering message: core delivers them as ordinary user image
   * messages right behind the text, and they are folded in here rather than rendered as
   * standalone bubbles — they are part of the same message and must not start a Task.
   * (Without vision the images arrive as `[attached image: …]` lines inside `text` instead,
   * which the chip restores at render time like any user message.)
   */
  images?: string[];
  /**
   * Videos sent with this steering message, delivered and folded in exactly like the images
   * above (a model that takes no video input gets the clip as an `[attached file: …]` line
   * inside `text` instead, so it needs no channel here).
   */
  videos?: string[];
  /** Message timestamp (milliseconds): shown on footer hover. */
  atMs?: number;
}

/**
 * A background completion notice steered into the running Task (`delivery: steering` on its
 * `[background_task_done]` block — see core's Session notice queue): rendered as the
 * completion banner **inside** the running Task's flow, like a steering chip it never starts
 * a new Task — so the turn's stats row still arrives exactly once, at task end. An unstamped
 * notice (an idle-launched notice task's own input) stays an ordinary `user_text` item and
 * keeps its independent turn. `text` is the raw message text (block included): the renderer
 * and the topology's terminal-state scan both re-parse it, exactly as they do for the
 * unstamped form.
 */
export interface BackgroundNoticeItem {
  kind: "background_notice";
  id: number;
  text: string;
  /** Message timestamp (milliseconds): shown on footer hover. */
  atMs?: number;
}

export interface UserImageItem {
  kind: "user_image";
  id: number;
  imageUrl: string;
  /** Message timestamp (milliseconds): shown on footer hover. */
  atMs?: number;
}

/**
 * A video the person sent (`video_url`), with the model that takes one: rendered as a bubble of
 * its own, exactly like `user_image` and for the same reason — it is part of the message, and a
 * message that is nothing but a clip still opens its own Task. `videoUrl` is inline bytes live, or
 * a windowed history page's reference to the same Trace record
 * (`/api/sessions/<id>/trace-video?…`), which the browser fetches from the Session's machine.
 */
export interface UserVideoItem {
  kind: "user_video";
  id: number;
  videoUrl: string;
  /** Message timestamp (milliseconds): shown on footer hover. */
  atMs?: number;
}

export interface AssistantTextItem {
  kind: "assistant_text";
  id: number;
  text: string;
  /** The streamed fragment is still accumulating. */
  streaming: boolean;
  stopReason?: StopReason;
  /**
   * Message timestamp (milliseconds): shown on footer hover. During
   * streaming it's a placeholder using the partial start's timestamp;
   * once the complete message arrives, it switches to that message's own
   * timestamp — the same convention as Trace (which records the **completion** time).
   */
  atMs?: number;
  /** Stable history coordinate, present after a history read (live replies resolve it on demand). */
  tracePosition?: TracePosition;
}

export interface ThinkingItem {
  kind: "thinking";
  id: number;
  thinking: string;
  streaming: boolean;
  stopReason?: StopReason;
  /** Start timestamp in milliseconds (the partial start's message time; approximated by the previous message's time when history has no fragments). */
  startedAtMs?: number;
  /** Thinking duration (settled when the complete message arrives: message time - start time). */
  durationMs?: number;
}

export interface ToolCallItem {
  kind: "tool_call";
  id: number;
  toolCallId: string;
  name: string;
  /** Tool argument JSON (accumulated via streamed deltas, replaced once the complete message arrives). */
  argumentsText: string;
  callStreaming: boolean;
  /** A complete tool_call message has been received (all streamed copies after this are ignored). */
  callComplete: boolean;
  callStopReason?: StopReason;
  /** Tool output (appended via streaming, replaced once the complete message arrives; truncation/timeout/interruption markers are already in the text). */
  output: string;
  /** Images carried by the tool output (an array of data URLs; a streamed delta carries the whole array at once, and the complete message converges it again). */
  images?: string[];
  outputStreaming: boolean;
  outputComplete: boolean;
  outputStopReason?: StopReason;
  /** Approval decision (annotated by the approval_decision event). */
  decision?: ApprovalDecision;
  decisionSource?: DecisionSource;
  /** run_subagent: the bound sub-session stream (nested model). */
  subagent?: StreamModel;
  subagentSessionId?: string;
  /** Tool execution start (the message time when the tool_call closed; same convention as Trace analysis). */
  callStartedAtMs?: number;
  /** Approval-granted moment (the approval_decision message time): execution timing starts from here, deducting the approval wait. */
  approvalAtMs?: number;
  /**
   * The moment THIS client answered the approval, read from the local clock as the decision is
   * submitted — the approval_decision event that carries approvalAtMs only arrives a broadcast
   * later. Kept apart from approvalAtMs because that one is a server message time that
   * noteApprovalWait subtracts callStartedAtMs (another server time) from: a local Date.now()
   * in there would put two clocks inside one stat, so a skewed client could corrupt
   * openApprovalWaitMs. Only the UI's elapsed-time gates read this, and they measure against
   * Date.now(), which is the clock it is already on.
   */
  localApprovalAtMs?: number;
  /** This card's approval wait has already been counted toward its owning Request (see noteApprovalWait): whichever of the two timestamps arrives later triggers it, guarding against double-counting. */
  approvalWaitCounted?: boolean;
  /**
   * Argument generation start (the partial_tool_call start's message time):
   * the rolling timing baseline during streamed argument generation.
   * Approximated by the previous message's time when history rebuild has no fragments (same convention as thinking).
   */
  argStartedAtMs?: number;
  /** Total tool duration (settled when the tool_call_output complete message arrives) = the argument-generation segment + the execution segment, excluding the approval wait (see settleToolDuration). */
  durationMs?: number;
}

/** A standalone sub-session card for when no run_subagent tool card can be bound. */
export interface SubagentItem {
  kind: "subagent";
  id: number;
  sessionId: string;
  model: StreamModel;
}

export interface AbortItem {
  kind: "abort";
  id: number;
  /** Machine-readable cause (the omnimessage ErrorCode vocabulary); the banner localizes from it. */
  errorCode?: string;
  /** Raw failure detail, shown verbatim (absent on live user interrupts). */
  errorMessage?: string;
  /** Legacy Traces only: the cause as English prose, rendered verbatim when no errorCode is present. */
  reason?: string;
}

/**
 * A run-ending LLM failure, from a `request_end` with status `fatal` (an LLM failure
 * produces no abort event — the request_end is its terminal record).
 */
export interface LlmErrorItem {
  kind: "llm_error";
  id: number;
  /** Machine-readable cause (request_end.error_code). */
  errorCode?: string;
  /** The provider's own error text (request_end.error_message), shown verbatim. */
  errorMessage?: string;
}

/** `retryable` is the live protocol; failed/timeout/malformed are legacy Trace spellings kept for replay. */
export type ReconnectStatus = "retryable" | "failed" | "timeout" | "malformed";

function isReconnectStatus(status: string | undefined): status is ReconnectStatus {
  return (
    status === "retryable" || status === "failed" || status === "timeout" || status === "malformed"
  );
}

/** An LLM Request ending retryable → the engine retries carrying the content already produced. */
export interface ReconnectItem {
  kind: "reconnect";
  id: number;
  /** Trigger status (legacy Traces carry the finer pre-convergence spellings). */
  status: ReconnectStatus;
  /** Which retry attempt this is — request_end.attempt, the core's authoritative 1-based ordinal (1 for Traces written before the field existed). */
  attempt: number;
  /** The retry request has been sent (set true by the next request_begin). */
  retrying: boolean;
  /** Retries exhausted: set at creation when the request_end announced no retry (`retryable` with no retry_in_ms — the run ends there), or by an abort event in legacy Traces. */
  gaveUp?: boolean;
  /** Machine-readable cause (request_end.error_code); the cause wording localizes from it. */
  errorCode?: string;
  /** The final failure's detail (request_end.error_message), rendered in the gave-up state. */
  errorMessage?: string;
  /**
   * The engine's planned wait before the next attempt (request_end.retry_in_ms; absent
   * when the event carried none — old Traces, or a final failure). Waits can reach the
   * 30s backoff ceiling, so the view renders a live countdown for the waiting state when
   * this is ≥2s (see ReconnectLine).
   */
  plannedDelayMs?: number;
  /**
   * CLIENT-clock arrival time of the request_end (the countdown anchor — client-local, so
   * server clock skew cannot bend the ticker). On history replay the following
   * request_begin/abort arrives immediately and flips retrying/gaveUp, so a replayed item
   * never stays in the waiting state to tick.
   */
  arrivedAtMs?: number;
}

export interface CompactionItem {
  kind: "compaction";
  id: number;
  reason: CompactionReason;
  mode: CompactionMode;
  /** True between begin and end (renders a "compaction in progress" banner). */
  running: boolean;
  status?: StopReason;
  /** Last failure detail from compaction_end.error_message (its share of the RetryDetail block; present on failed ends from new cores). */
  errorMessage?: string;
  /** The begin message's timestamp (ms); ticks the running row and anchors durationMs. */
  beginTsMs?: number;
  /** Wall time derived from the begin/end message timestamps (absent on a mid-stream join). */
  durationMs?: number;
  /**
   * Raw text of the summary the compaction request is generating (issue #290): accumulated
   * live from the span's own partial_text fragments, and rebuilt identically on history
   * replay from the span's complete assistant text — the banner shows the summary being
   * written and keeps it readable after a reload. Raw model output (summary tags included;
   * the banner strips them for display); absent when nothing streamed (e.g. discard mode).
   */
  summaryText?: string;
  /**
   * Raw text of the thinking the compaction request produced ahead of its summary:
   * accumulated live from the span's own partial_thinking fragments, and rebuilt identically
   * on history replay from the span's complete thinking messages — the banner shows it in a
   * collapsed section of its own. Absent when the request produced none (a model that does
   * not think, or discard mode).
   */
  thinkingText?: string;
  /** True while a thinking fragment of the compaction request is open (the section streams); settled by its stop, or by the end event. */
  thinkingStreaming?: boolean;
  /**
   * Start of the thinking section's wall time, and with it the rule both sections follow:
   * **a section is timed over exactly the window in which it shows itself running**, so the
   * number and the spinner beside it can never disagree.
   *
   * Thinking therefore starts at the first fragment that carried thinking and settles at that
   * fragment's stop — the moment the section stops spinning. The result section shows itself
   * running for the whole compaction (it has no fragment flag of its own), so it starts at the
   * first summary text and settles at `compaction_end`; its share of the header's begin-to-end
   * span is what the request spent writing plus the adoption behind it.
   *
   * History rebuild has no fragments: the previous message's time approximates each start and
   * the complete message's own time settles it — the ThinkingItem convention (see
   * `settleThinkingDuration`), so a reload lands within a message hop of the live numbers.
   *
   * A retried compaction concatenates every attempt into one draft (`thinkingText` and
   * `summaryText` both), so a start is recorded once and a later stop only extends the settled
   * value: the wall time covers the whole span that produced the prose on screen, the failed
   * attempts and the gaps between them included. Timing the last attempt alone would print a
   * short number against text it did not write.
   */
  thinkingStartedAtMs?: number;
  /** Settled thinking wall time (boundaries: see thinkingStartedAtMs). */
  thinkingDurationMs?: number;
  /** Start of the result section's wall time (boundaries: see thinkingStartedAtMs). */
  summaryStartedAtMs?: number;
  /** Settled result wall time (boundaries: see thinkingStartedAtMs). */
  summaryDurationMs?: number;
}

/**
 * The Session moved to another model between two contexts: derived from two consecutive
 * main-session `session_meta` records naming different (provider, model_id) pairs — an
 * in-session model switch opens its new context on the model the user picked, and nothing else
 * on the stream says so. Model ids rather than display names: the marker renders from the Trace
 * alone, and a model removed from the configuration since must still read.
 */
export interface ModelChangeItem {
  kind: "model_change";
  id: number;
  from: { provider: string; modelId: string };
  to: { provider: string; modelId: string };
  /** The timestamp of the `session_meta` that named the new model (ms). */
  tsMs?: number;
}

/** One MCP tool for the connect row's expandable list (from tool_list_ready, `mcp__` entries only). */
export interface McpToolSummary {
  name: string;
  description?: string;
}

/** One server's connect outcome (from the end payload), backing the row's per-server groups. */
export interface McpServerOutcome {
  server: string;
  /** `completed` / `fatal`; legacy Traces spell the failure `failed`. */
  status: StopReason;
  /** That server's own connect + discovery time (the payload's duration_ms). */
  durationMs: number;
  /** Discovered tool count (present on a completed connect). */
  tools?: number;
  /** Failure detail (present on a failed connect). */
  error?: string;
}

export interface McpConnectItem {
  kind: "mcp_connect";
  id: number;
  /** Servers being contacted (from mcp_connect_begin). */
  servers: string[];
  /** True between mcp_connect_begin and mcp_connect_end (renders a connecting banner). */
  running: boolean;
  /** The begin message's timestamp (ms); the end computes durationMs from it. */
  beginTsMs?: number;
  /** Total connect + discovery wall time, derived from the pair's message timestamps. */
  durationMs?: number;
  /** MCP tools discovered across connected servers (sum of the end results' counts). */
  toolCount?: number;
  /** Per-server outcomes (the end payload's results), one expandable group each. */
  results?: McpServerOutcome[];
  /** Discovered MCP tools (attached by the tool_list_ready that follows the end). */
  tools?: McpToolSummary[];
  /** Servers that failed to connect (empty list omitted); reasons live in `results`. */
  failed?: string[];
  /** The user aborted the run mid-connect (a fresh connect starts on the next send). */
  aborted?: boolean;
}

export interface TaskStatsItem {
  kind: "task_stats";
  id: number;
  /**
   * This Task's stats; `null` = no token_usage occurred this round (e.g. the
   * reply was interrupted mid-way), so there's nothing to show. This item
   * is still produced in that case — it also serves as that reply's
   * **footer** (timestamp + copy); not producing it would leave an interrupted reply without a timestamp or copy button.
   */
  stats: TaskStats | null;
  /** This Task's assistant text (the copy button's target); an empty string when there's no text. */
  assistantText: string;
  /**
   * Timestamp (milliseconds) of this Task's last assistant text. The stats
   * row sits right below the AI reply and itself doubles as that reply's
   * footer — the timestamp and copy both belong to it, and the assistant
   * message is never rendered with its own separate footer (otherwise two copy buttons would appear in the same spot).
   */
  atMs?: number;
  /** Final assistant record of this completed Task; used by Session fork. */
  forkPosition?: TracePosition;
  /** True only when the final assistant segment and its Request completed normally. */
  forkable?: boolean;
  /** Memory topic files this Task changed through the structured file tools (merged, one row per file); absent when there were none. */
  memoryChanges?: MemoryChangeRow[];
  /**
   * The model this Task ran on — the one its context's `session_meta` names (see
   * `StreamModel.contextModel`). Absent when nothing had said which by the time the Task
   * began — the history was read before the Session's Trace existed, and a first context's
   * meta is never streamed; the cost shown beside the row is then priced on the Session's
   * current model.
   */
  model?: { provider: string; modelId: string };
}

export type ChatItem =
  | UserTextItem
  | UserSteeringItem
  | BackgroundNoticeItem
  | UserImageItem
  | UserVideoItem
  | AssistantTextItem
  | ThinkingItem
  | ToolCallItem
  | SubagentItem
  | AbortItem
  | LlmErrorItem
  | ReconnectItem
  | CompactionItem
  | ModelChangeItem
  | McpConnectItem
  | TaskStatsItem;

// ---------------------------------------------------------------------------
// Model state
// ---------------------------------------------------------------------------

/**
 * Identity of a nested child session, captured from its own session_meta (a child session's
 * DTO isn't loaded by the chat page, so this is the panel's only live source for "which agent
 * runs this child"). Main-session models never fill it — their identity comes from the Session DTO.
 */
export interface NestedSessionMeta {
  /** Agent id parsed from the `agent_state` path (its parent directory name); null when unparseable. */
  agentId: string | null;
  provider: string;
  modelId: string;
  /** What kind of conversation the child is, as its meta records it (narrowed: an old Trace's missing source reads as `user`, `benchmark` as `cli`). */
  source: SessionSource;
}

export interface StreamModel {
  items: ChatItem[];
  /** A nested sub-session model (produces no stats row; its stats count toward the parent). */
  nested: boolean;
  /** Child-session identity from its session_meta (nested models only; null until it arrives). */
  meta: NestedSessionMeta | null;
  /** Absolute `agent_state` path from session_meta or the history page (null until known); the Memory root `<agent_state>/memory/` for the Task summary's memory-change rows. */
  agentState: string | null;
  /**
   * The model the running context was opened on, and the Session its `session_meta` names (null
   * until one arrives, or a history window says which model it starts on). A Session's model
   * can change between contexts — each context's meta records its own — so this follows
   * rotations, and a main-session meta naming another model than the one held pushes a
   * model-change marker. The chat page moves its Session row to this model when the two
   * disagree (see `sessionRowStale`).
   */
  contextModel: { sessionId: string; provider: string; modelId: string } | null;
  /** `contextModel` as the open Task began: a switch only happens between Tasks, so this is the model the whole Task runs on (see `TaskStatsItem.model`). */
  taskModel: { provider: string; modelId: string } | null;
  /**
   * Elapsed-time stamps for the subagents panel's topology nodes (nested models only — the main
   * session's timing is covered by task stats). Stamped in routeNested: the `firstSeen` pair when
   * the nested model is created, the `lastActivity` pair on every message routed into its subtree
   * (cheap assignments). Two clocks are kept because neither works alone:
   *   - Local wall clock (`firstSeenLocalMs` / `lastActivityLocalMs`): when this client saw the
   *     child appear / last act. Faithful only while watching live — a history replay sets all of
   *     them within one synchronous load, so every replayed span collapses to ~0 at load time.
   *   - Message timestamps (`firstTsMs` / `lastActivityTsMs`): the same two moments in SERVER
   *     time, recorded identically during live streaming and history replay — a reload reproduces
   *     the same span. May drift from the local clock (same caveat as LiveDuration's sinceMs).
   * Topology extraction therefore derives a done node's duration from the timestamp pair (correct
   * in both live and reloaded views) and ticks a running node from firstTsMs, falling back to the
   * local pair only when timestamps were unparseable (see agent-topology.ts).
   */
  firstSeenLocalMs?: number;
  lastActivityLocalMs?: number;
  firstTsMs?: number;
  lastActivityTsMs?: number;
  stats: TaskStatsTracker;
  /** The currently open text/thinking fragment (opened by start, closed by stop). */
  openText: AssistantTextItem | null;
  openThinking: ThinkingItem | null;
  /** A fragment that has stopped and is waiting to be replaced by the complete message. */
  pendingText: AssistantTextItem | null;
  pendingThinking: ThinkingItem | null;
  /**
   * The steering chip still collecting its media: core delivers a steering message's images (and
   * videos) as user media messages immediately behind its text, so one arriving while this is set
   * belongs to that chip. Any other message closes the window (see pushMessage) — an images-only
   * Prompt sent after a steering message is a genuine new Task.
   */
  openSteering: UserSteeringItem | null;
  /** tool_call_id → tool card (shared by both fragment attribution and complete-message replacement). */
  toolCards: Map<string, ToolCallItem>;
  /** Direct child Session id → nested model. */
  subagents: Map<string, StreamModel>;
  /**
   * Direct children bound before their opening prompt arrived, by position alone: the prompt
   * names the call that spawned them, and may still move them onto its card (see
   * moveToSpawningCard).
   */
  unconfirmedSubagents: Set<string>;
  /** toolCallIds whose approval was clicked on this end (shares the reference with nested models, labeled "manual"). */
  localDecisions: Set<string>;
  /** Approval decisions that arrived before their tool card (backfilled when the card is created). */
  pendingDecisions: Map<string, ApprovalDecision>;
  /** Approval timestamps that arrived before their tool card (backfilled into approvalAtMs when the card is created, used to deduct the approval duration). */
  pendingDecisionTs: Map<string, number>;
  /** Timestamp of the most recent message (used to approximate the start time when history's thinking has no fragments). */
  lastTsMs: number;
  /**
   * The millisecond time of the main session's currently unclosed Request's
   * request_begin (used for output TPS timing): when request_end arrives, it
   * pairs with this to compute the wall-clock duration added to this Task's
   * LLM time; compaction requests aren't timed; a later begin overrides an unclosed one.
   */
  openRequestBeginMs: number | null;
  /**
   * Total human approval wait time (milliseconds) within the currently
   * unclosed Request: deducted from the wall-clock duration at request_end,
   * so only the time the LLM is actually generating counts toward the
   * output TPS denominator. Core does `await approve(tc)` inside the
   * streaming loop — if approval doesn't return, the next chunk isn't
   * consumed and request_end isn't emitted either, so the whole human wait
   * sits sandwiched between request_begin and request_end; without
   * deducting it, "5s of generation + 55s of approval wait" would render
   * 100 tok/s as 8 tok/s. Tool **execution** isn't included here (core
   * dispatches it via `void executeOne`, which doesn't block the streaming loop — execution happens between two Requests).
   */
  openApprovalWaitMs: number;
  /** Task segmentation state. */
  taskOpen: boolean;
  /**
   * Local-clock instant the running Task's header elapsed ticks from — display
   * only; no settled duration is ever derived from it (see finalizeOpenTask,
   * which reads Trace timestamps alone). A live stream sets it to the real
   * start; a history rebuild would otherwise stamp the page-load instant and
   * restart the ticking value from zero on every reload, so pushMessages
   * back-dates it by the elapsed already behind the Task — measured entirely
   * in server time, so no client/server clock offset reaches it, and taken
   * from the server's own clock rather than the Trace's tail so that an event
   * still in flight is counted too.
   */
  taskStartLocalMs: number;
  /** The Task's first message timestamp, in SERVER time: both the settled duration and the back-dated live anchor measure from it. */
  taskFirstTsMs: number;
  /**
   * The latest timestamp seen among this round's messages. Two readers:
   *   - the **fallback for the round's end**, used only for a degenerate
   *     round that has no request_end at all (interrupted before its first
   *     Request even ran) — the normal round-end is taken from taskLastReqEndMs;
   *   - the floor under the anchor pushMessages back-dates taskStartLocalMs
   *     to, for a round still open when a history rebuild ends. That reader
   *     fires for every such round, degenerate or not, but only decides the
   *     anchor when the server's own clock did not come back with the
   *     response — it cannot see an event still in flight.
   */
  taskLastTsMs: number;
  /**
   * The timestamp of this round's last **non-compaction** request_end — this
   * is the true round end, and this round's duration = it − the first
   * message. A round's real work is done once its last Request finishes:
   *   - Automatic compaction **mid-round** (the engine keeps running with a
   *     carry-over after compacting, so a normal Request follows the
   *     compaction) sits **within** the span and is naturally counted into
   *     the round's duration — which is correct, since compaction did occupy this round's wall-clock time;
   *   - Compaction **after the round ends** (finalization's automatic
   *     compaction / manual /compact), the next round's injected
   *     `[context_summary]`, and the session_meta rewritten after a file
   *     rotation all come **after** it, and are naturally excluded from the round.
   * So no compaction wall-clock addition/subtraction is needed at all —
   * just take the span directly (history rebuild and live share the same
   * convention, consistent before and after a refresh).
   * null = this round has no request_end yet (a degenerate round, falls back to taskLastTsMs).
   */
  taskLastReqEndMs: number | null;
  /**
   * Whether the turn that ran most recently produced tool outputs — the same
   * question the engine asks to tell a mid-Task compaction from a wrap-up one
   * (`turn.toolOutputs.length > 0`). Set by a complete tool_call_output, cleared
   * when the next Request opens, and read at `compaction_begin` (see
   * `isWrapUpCompaction`).
   */
  turnToolOutputs: boolean;
  /**
   * A wrap-up compaction closed the round before its banner was created (see
   * `compaction_begin`), yet the Task can still continue: steering queued while
   * that compaction ran is delivered right after it and keeps the loop going.
   * The steering chip reopens a Task for that continuation, so its reply gets a
   * ledger of its own instead of no footer at all.
   */
  reopenTaskAtSteering: boolean;
  nextItemId: number;
}

function newModel(nested: boolean, localDecisions: Set<string>): StreamModel {
  return {
    items: [],
    nested,
    meta: null,
    agentState: null,
    contextModel: null,
    taskModel: null,
    stats: createTaskStatsTracker(),
    openText: null,
    openThinking: null,
    pendingText: null,
    pendingThinking: null,
    openSteering: null,
    toolCards: new Map(),
    subagents: new Map(),
    unconfirmedSubagents: new Set(),
    localDecisions,
    pendingDecisions: new Map(),
    pendingDecisionTs: new Map(),
    lastTsMs: 0,
    openRequestBeginMs: null,
    openApprovalWaitMs: 0,
    taskOpen: false,
    taskStartLocalMs: 0,
    taskFirstTsMs: 0,
    taskLastTsMs: 0,
    taskLastReqEndMs: null,
    turnToolOutputs: false,
    reopenTaskAtSteering: false,
    nextItemId: 1,
  };
}

/** Create the main-session model; localDecisions can inject a shared set (persisting across models when a resync rebuild swaps in a new one). */
export function createStreamModel(localDecisions: Set<string> = new Set()): StreamModel {
  return newModel(false, localDecisions);
}

function nextId(model: StreamModel): number {
  return model.nextItemId++;
}

// ---------------------------------------------------------------------------
// Main entry point
// ---------------------------------------------------------------------------

/** Feed in one OmniMessage in order (history or live); nowMs is used for the Task's live timing (injectable for tests). */
export function pushMessage(
  model: StreamModel,
  msg: OmniMessage,
  nowMs: number = Date.now(),
): void {
  if (msg.origin && msg.origin.length > 0) {
    routeNested(model, msg, nowMs);
    return;
  }
  // A steering message's images AND videos arrive as user media messages directly behind its text,
  // with nothing interleaved (core delivers the batch in one go) — so anything else on this
  // session closes the collection window opened by the chip (see openSteering). Subagent messages
  // returned above never reach here, so they leave the window alone.
  // The server answers the same "what is one Task" question over the Trace — see
  // `steeringImages` in server/src/services/trace-service.ts — and reaches the same answer for a
  // video by another route: a video is not one of that window's kinds, but it is not a turn starter
  // there either, so it lands in the steering message's own turn just the same. Folding it into the
  // chip keeps this side's grouping (and the clip's own rendering) identical to that.
  if (!isCompleteUserMedia(msg)) model.openSteering = null;
  if (msg.type === "model_msg") {
    // Internal messages within a compaction range (between begin and end)
    // (the compaction prompt, thinking, summary output): never rendered as transcript items,
    // never counted toward Task segmentation. The request's thinking and the summary being
    // written are the exception (issue #290): live they arrive as their own partial_thinking
    // / partial_text fragments (the engine forwards them between the paired events; the
    // complete messages stay off the stream once partials carried them), and history rebuild
    // reads the identical content back from the span's complete thinking and assistant text
    // — both accumulate onto the running banner, so a reload shows the same text the live
    // viewer watched being written.
    if (model.stats.compactionActive) {
      touchTask(model, msg.timestamp);
      const tsMs = tsOf(msg.timestamp);
      if (isPartialPayload(msg.payload)) {
        const p = msg.payload as {
          type?: string;
          event_type?: string;
          text?: string;
          thinking?: string;
        };
        // Live, a section is timed by its own fragment, so this one timestamp both starts it
        // (its first content) and, on the stop phase, settles it.
        if (p.type === "partial_text" && p.text) appendCompactionSummaryText(model, p.text, tsMs);
        else if (p.type === "partial_thinking") {
          appendCompactionThinking(model, p.thinking ?? "", p.event_type !== "stop", tsMs, tsMs);
        }
        // Partials never advance lastTs (same rule as the normal path below).
        return;
      }
      const p = msg.payload as { type?: string; role?: string; text?: string; thinking?: string };
      // History rebuild has no fragments: the previous message's time approximates the
      // section's start (the ThinkingItem convention), this message's own time settles it.
      // Read before advanceLastTs below, exactly as the ordinary complete path reads it.
      const startMs = model.lastTsMs > 0 ? model.lastTsMs : undefined;
      if (p.type === "text" && p.role === "assistant" && p.text) {
        appendCompactionSummaryText(model, p.text, startMs);
      } else if (p.type === "thinking" && p.thinking) {
        appendCompactionThinking(model, p.thinking, false, startMs, tsMs);
      }
      advanceLastTs(model, msg.timestamp);
      return;
    }
    if (isPartialPayload(msg.payload)) {
      touchTask(model, msg.timestamp);
      handlePartial(model, msg.payload, tsOf(msg.timestamp));
      // lastTsMs only advances from complete messages/events: an orphan
      // delta during a mid-stream join shouldn't push "the previous
      // message's time" up to just before a complete thinking message, or the approximated historical duration would collapse to ~0ms.
      return;
    }
    handleComplete(
      model,
      msg.payload as CompleteModelPayload,
      msg.timestamp,
      nowMs,
      (msg as OmniMessage & { tracePosition?: TracePosition }).tracePosition,
    );
    advanceLastTs(model, msg.timestamp);
    return;
  }
  if (isEventMessage(msg)) {
    touchTask(model, msg.timestamp);
    handleEvent(model, msg.payload as EventPayload, tsOf(msg.timestamp), nowMs);
    advanceLastTs(model, msg.timestamp);
    return;
  }
  // session_meta: never rendered as an item itself, but read at BOTH levels. Both keep the
  // agent_state path — the main session's Task summary classifies file-tool writes against
  // `<agent_state>/memory/` for its memory-change rows. History pages seed it when the meta
  // falls before their window. A NESTED child session additionally has no DTO
  // loaded here, so it captures the identity the subagents panel needs (which agent runs this
  // child, on which model); the main session takes the rest of its identity/config from the
  // Session DTO. A rewritten session_meta (file rotation) overwrites with the same values. On
  // the main session a meta naming another model than the one held means the Session switched
  // models: a marker says so — never for a same-model rewrite, a nested child's meta, or the
  // first meta of a model that was told nothing of the context it starts in.
  if (msg.type === "session_meta") {
    const p = msg.payload as SessionMetaPayload;
    model.agentState = p.agent_state;
    const next = { provider: p.provider, modelId: p.model_id };
    const held = model.contextModel;
    if (
      !model.nested &&
      held !== null &&
      (held.provider !== next.provider || held.modelId !== next.modelId)
    ) {
      const tsMs = tsOf(msg.timestamp);
      model.items.push({
        kind: "model_change",
        id: nextId(model),
        from: { provider: held.provider, modelId: held.modelId },
        to: next,
        ...(tsMs !== undefined ? { tsMs } : {}),
      });
    }
    model.contextModel = { sessionId: p.session_id, ...next };
  }
  if (msg.type === "session_meta" && model.nested) {
    const p = msg.payload as SessionMetaPayload;
    model.meta = {
      agentId: agentIdFromStatePath(p.agent_state),
      provider: p.provider,
      modelId: p.model_id,
      // Replayed from the child's own Trace, which may predate the required source.
      source: normalizeSessionSource(p.source),
    };
  }
}

/**
 * Whether the message is a complete user media (image or video) — the only kinds that can join an
 * open steering chip. A video joins it on the same terms as an image: both are delivered as user
 * media messages right behind the steering text, and both are part of that message rather than a
 * Task of their own.
 */
function isCompleteUserMedia(msg: OmniMessage): boolean {
  if (msg.type !== "model_msg") return false;
  const type = (msg.payload as { type?: string }).type;
  return type === "image_url" || type === "video_url";
}

/**
 * Agent id from a session_meta `agent_state` path: the path is
 * `<root>/<projectId>/agents/<agentId>/agent_state`, so the agent id is the parent directory
 * name. Returns null when the path has no parent segment (defensive — core always writes the full path).
 */
export function agentIdFromStatePath(agentStatePath: string): string | null {
  const segments = agentStatePath.split(/[\\/]/).filter((s) => s.length > 0);
  return segments.length >= 2 ? segments[segments.length - 2]! : null;
}

/**
 * Whether any pending approval sits at or below the given origin chain (prefix match on
 * approvalKey): `chain` is the ancestor chain ending with the subtree root's own session id.
 * Drives the subagent chip's amber dot and the toolbar badge — a nested approval must stay
 * discoverable even though the child conversation lives in the side panel.
 */
export function hasPendingWithinOrigin(
  pendingKeys: Iterable<string>,
  chain: readonly string[],
): boolean {
  const prefix = chain.join("/");
  for (const key of pendingKeys) {
    // The approvalKey delimiters are load-bearing here: a key is `origin.join("/") + " " +
    // toolCallId`, so requiring the chain to be followed by a space (an approval on the subtree
    // root itself) or a slash (one strictly below it) is what keeps a sibling whose id merely
    // extends this chain ("c1" vs "c1x") from matching, and keeps a main-session key (leading
    // space) from matching any chain. Refactoring approvalKey to another separator would
    // silently break this predicate — change the two together.
    if (key.startsWith(`${prefix} `) || key.startsWith(`${prefix}/`)) return true;
  }
  return false;
}

/** ISO timestamp → milliseconds (returns undefined if invalid). */
function tsOf(timestamp: string): number | undefined {
  const ms = Date.parse(timestamp);
  return Number.isFinite(ms) ? ms : undefined;
}

function advanceLastTs(model: StreamModel, timestamp: string): void {
  const ms = Date.parse(timestamp);
  if (Number.isFinite(ms)) model.lastTsMs = ms;
}

/**
 * Replay a history rebuild. `serverNowMs` is the server's clock when it produced the
 * response (see StreamControllerDeps.loadMessages); null when unavailable.
 */
export function pushMessages(
  model: StreamModel,
  messages: OmniMessage[],
  nowMs: number = Date.now(),
  serverNowMs: number | null = null,
): void {
  for (const msg of messages) pushMessage(model, msg, nowMs);
  // Re-anchor a Task still open at the end of the replay. Every message in a
  // rebuild is fed the same `nowMs`, so startTask stamped taskStartLocalMs
  // with the instant the page loaded — and the header's live elapsed, which
  // ticks over `now − taskStartLocalMs`, would restart from zero on every
  // reload of a running Session. Back-date the anchor by the elapsed already
  // behind this Task, so the ticking value resumes where it left off:
  //
  //   now − anchor  ==  (now − loadInstant) + elapsedSoFar
  //
  // elapsedSoFar is measured in SERVER time and applied to the local clock, so
  // a client/server clock offset cancels out and never enters the result. Two
  // readings of it, the larger winning:
  //   - serverNowMs − taskFirstTsMs: the true elapsed, and the only one that
  //     covers an event still in flight — a tool executing, a Request
  //     streaming, a compaction running — where nothing has been appended to
  //     the Trace since it began. Whole-second precision (the `Date` header's
  //     format), which a chip ticking in whole seconds cannot show.
  //   - taskLastTsMs − taskFirstTsMs: the span the Trace itself proves. The
  //     fallback when no `Date` header came back, and a floor under a stale
  //     one: a cached or intermediary-rewritten reading can only be older
  //     than the true now, so it can under-report but never overshoot.
  // A live stream pushes one message at a time with the real current clock,
  // where both readings are still zero at startTask and this is a no-op.
  if (model.taskOpen) {
    const tracedSpan = model.taskLastTsMs - model.taskFirstTsMs;
    const serverSpan = serverNowMs === null ? 0 : serverNowMs - model.taskFirstTsMs;
    model.taskStartLocalMs = nowMs - Math.max(0, tracedSpan, serverSpan);
  }
}

/** The live stream received task_state:idle: finalize the current Task from its Trace timestamps. */
export function notifyTaskIdle(model: StreamModel): void {
  finalizeOpenTask(model);
}

/** History rebuild is complete (end of stream): finalize the last Task using message timestamps. */
export function finalizeHistory(model: StreamModel): void {
  finalizeOpenTask(model);
}

/** Register an approval clicked on this end (so the subsequent approval_decision event is labeled "manual"). */
export function registerLocalDecision(model: StreamModel, toolCallId: string): void {
  model.localDecisions.add(toolCallId);
}

/**
 * Pending-approvals table key: `origin.join("/") + " " + toolCallId` (empty
 * origin for the main session). A parent/child session's tool_call_id can
 * collide, so the origin chain must be included to distinguish them and
 * avoid lighting up the approval button on the wrong tool card.
 * The "/" and " " separators are relied on by hasPendingWithinOrigin's prefix
 * matching — keep the two in sync if this format ever changes.
 */
export function approvalKey(origin: readonly string[] | undefined, toolCallId: string): string {
  return `${origin?.join("/") ?? ""} ${toolCallId}`;
}

/** Locate a tool card in a nested model (at any depth) by its origin chain; returns null if there's no matching card. */
export function findToolCard(
  model: StreamModel,
  origin: readonly string[] | undefined,
  toolCallId: string,
): ToolCallItem | null {
  let cur: StreamModel | undefined = model;
  for (const hop of origin ?? []) {
    cur = cur.subagents.get(hop);
    if (!cur) return null;
  }
  return cur.toolCards.get(toolCallId) ?? null;
}

// ---------------------------------------------------------------------------
// Task segmentation
// ---------------------------------------------------------------------------

/**
 * Advance this round's "latest timestamp seen among its messages" — the
 * **fallback for the round's end** (see taskLastReqEndMs: the normal
 * round-end is set by request_end, and this only guarantees a usable
 * upper bound for a degenerate round with no request_end at all,
 * interrupted before its first Request even ran), and the floor under the
 * live anchor back-dated on a history rebuild when the server's own clock
 * did not come back with the response (see taskLastTsMs, pushMessages).
 * Compaction forms its own round, and messages within its range don't
 * belong to this round, so this isn't advanced for them.
 */
function touchTask(model: StreamModel, timestamp: string): void {
  if (!model.taskOpen) return;
  if (model.stats.compactionActive) return;
  const ts = Date.parse(timestamp);
  if (!Number.isFinite(ts) || ts <= model.taskLastTsMs) return;
  model.taskLastTsMs = ts;
}

function startTask(model: StreamModel, timestamp: string, nowMs: number): void {
  // The previous Task is finalized by "the next Task starting" (the history-rebuild convention).
  finalizeOpenTask(model);
  // Finalize any retry state left over from the previous Task: when the
  // server dies during a backoff window, the Trace's tail is
  // request_end(timeout) with no abort, and history rebuild would leave a
  // dangling "retrying…" — the new Task's first request_begin isn't its
  // retry, so mark it gaveUp.
  const waiting = findLastWaitingReconnect(model);
  if (waiting) waiting.gaveUp = true;
  // Any unclosed Request start / approval wait left over from the previous Task isn't carried into this Task's LLM timing.
  model.openRequestBeginMs = null;
  model.openApprovalWaitMs = 0;
  model.turnToolOutputs = false;
  model.reopenTaskAtSteering = false;
  model.taskOpen = true;
  model.taskModel = model.contextModel && {
    provider: model.contextModel.provider,
    modelId: model.contextModel.modelId,
  };
  model.taskStartLocalMs = nowMs;
  const ts = Date.parse(timestamp);
  model.taskFirstTsMs = Number.isFinite(ts) ? ts : nowMs;
  model.taskLastTsMs = model.taskFirstTsMs;
  model.taskLastReqEndMs = null;
  // Usage outside this Task's boundary (e.g. a manual compaction) shouldn't be mistakenly counted into this Task's delta.
  resetTaskCounters(model.stats);
}

function finalizeOpenTask(model: StreamModel): void {
  if (!model.taskOpen) return;
  model.taskOpen = false;
  // No more tool output will arrive once a Task is finalized: close cards still "executing" and stop their LiveDuration.
  closeExecutingToolCards(model);
  // This round's duration = this round's last non-compaction request_end −
  // the first message. The round's end is exactly the last Request's
  // finish: compaction **mid-round** sits within the span and is naturally
  // counted in (which is correct — it did occupy this round's wall-clock
  // time), while compaction **after the round ends** sits outside the span
  // and is naturally excluded — no compaction wall-clock addition/subtraction
  // is needed at all, and history rebuild and live share the same
  // convention, consistent before and after a refresh (see taskLastReqEndMs).
  //
  // Trace timestamps are the ONLY source here — the local clock is never
  // consulted, so a round settles to the same number whether it was watched
  // live or replayed from the Trace after a reload. A degenerate round (no
  // request_end at all, e.g. interrupted before its first Request even ran)
  // falls back to its message span, which the abort event's own timestamp
  // still bounds; that span is what a later reload would compute, so taking
  // the local clock instead — as this did before — only bought a number that
  // silently changed on refresh, along with idle-detection and mid-join
  // latency folded into it.
  const endMs = model.taskLastReqEndMs ?? model.taskLastTsMs;
  const elapsed = Math.max(0, endMs - model.taskFirstTsMs);
  const stats = endTask(model.stats, elapsed);
  if (model.nested) return;
  const reply = collectTaskAssistant(model);
  const memoryChanges = collectTaskMemoryChanges(model);
  // No token_usage (the reply was interrupted mid-way) → there are no stats
  // to show, but as long as this round produced any text, there still needs
  // to be a footer: the timestamp and copy are both rendered by the stats
  // row, so not producing it here would leave that reply with no footer at
  // all. Only skip when both are absent — then there's truly nothing to do.
  if (stats === null && reply.text === "") return;
  const statsItem: TaskStatsItem = {
    kind: "task_stats",
    id: nextId(model),
    stats,
    assistantText: reply.text,
    forkable: reply.completed,
    ...(reply.atMs !== undefined ? { atMs: reply.atMs } : {}),
    ...(reply.tracePosition !== undefined ? { forkPosition: reply.tracePosition } : {}),
    ...(memoryChanges.length > 0 ? { memoryChanges } : {}),
    ...(model.taskModel ? { model: model.taskModel } : {}),
  };
  // The stats row is inserted **before any trailing run of compaction banners** (and the
  // model-change markers a switch's compaction leaves behind them): compaction is its own
  // round, housekeeping outside this one, so it belongs after this round's ledger — a banner
  // sandwiched between the reply and the row (assistant_text → compaction → task_stats) reads
  // as if the row were the compaction's own stats.
  // A wrap-up compaction normally settles the round on arrival, before its banner exists
  // (see isWrapUpCompaction), so this loop is what still places the row correctly in the
  // cases that test declines to judge — a mid-stream join, or a round whose reply never
  // landed as an item.
  let at = model.items.length;
  while (at > 0 && ["compaction", "model_change"].includes(model.items[at - 1]!.kind)) at--;
  model.items.splice(at, 0, statsItem);
}

/**
 * Collect this Task's assistant text (walking backward from the end until
 * the previous task_stats, concatenating assistant_text), and give the
 * timestamp of the **last** assistant text item — the stats row is this
 * round's reply's footer, and this is the timestamp it shows.
 */
function collectTaskAssistant(model: StreamModel): {
  text: string;
  atMs?: number;
  tracePosition?: TracePosition;
  completed: boolean;
} {
  const parts: string[] = [];
  let atMs: number | undefined;
  let tracePosition: TracePosition | undefined;
  let completed = false;
  for (let i = model.items.length - 1; i >= 0; i--) {
    const it = model.items[i]!;
    if (it.kind === "task_stats") break;
    if (it.kind === "assistant_text" && it.text.trim()) {
      parts.push(it.text);
      if (atMs === undefined) {
        atMs = it.atMs; // walking backward: the first hit is the last one
        tracePosition = it.tracePosition;
        completed = it.stopReason === "completed";
      }
    }
  }
  return {
    text: parts.reverse().join("\n\n"),
    ...(atMs !== undefined ? { atMs } : {}),
    ...(tracePosition !== undefined ? { tracePosition } : {}),
    completed,
  };
}

/**
 * Collect this Task's memory changes (same walk as collectTaskAssistant: backward until the
 * previous task_stats): successfully completed `write_file` / `edit_file` calls whose path
 * falls under `<agent_state>/memory/`, merged to one row per file. Only this level's tool
 * cards are consulted — a subagent's memory writes belong to that child's own Agent and are
 * out of this Task summary's scope.
 */
function collectTaskMemoryChanges(model: StreamModel): MemoryChangeRow[] {
  if (model.agentState === null) return [];
  const entries: MemoryChangeEntry[] = [];
  for (let i = model.items.length - 1; i >= 0; i--) {
    const it = model.items[i]!;
    if (it.kind === "task_stats") break;
    if (it.kind !== "tool_call" || !it.outputComplete || it.outputStopReason !== "completed")
      continue;
    if (it.name !== "write_file" && it.name !== "edit_file") continue;
    let args: unknown;
    try {
      args = JSON.parse(it.argumentsText);
    } catch {
      continue; // a malformed argument record can't name a file
    }
    const filePath = (args as { file_path?: unknown }).file_path;
    if (typeof filePath !== "string") continue;
    const classed = classifyMemoryPath(filePath, model.agentState);
    if (classed === null) continue;
    const entry: MemoryChangeEntry = {
      ...classed,
      op: it.name === "write_file" ? "write" : "edit",
    };
    if (it.callStartedAtMs !== undefined) entry.atMs = it.callStartedAtMs;
    entries.push(entry);
  }
  return mergeMemoryChanges(entries.reverse()); // walked backward; merge in call order
}

// ---------------------------------------------------------------------------
// Streamed fragments
// ---------------------------------------------------------------------------

function handlePartial(model: StreamModel, p: PartialModelPayload, tsMs?: number): void {
  switch (p.type) {
    case "partial_text": {
      if (p.event_type === "start") {
        // start reopens the fragment; a stale pending that never got replaced keeps its streamed content and stops waiting to be replaced.
        model.pendingText = null;
        const item: AssistantTextItem = {
          kind: "assistant_text",
          id: nextId(model),
          text: p.text ?? "",
          streaming: true,
          ...(tsMs !== undefined ? { atMs: tsMs } : {}),
        };
        model.openText = item;
        model.items.push(item);
        return;
      }
      const open = model.openText;
      if (!open) return; // orphan delta/stop: ignored, converging once the complete message arrives
      if (p.text) open.text += p.text;
      if (p.event_type === "stop") {
        open.streaming = false;
        if (p.stop_reason !== undefined) open.stopReason = p.stop_reason;
        model.pendingText = open;
        model.openText = null;
      }
      return;
    }
    case "partial_thinking": {
      if (p.event_type === "start") {
        model.pendingThinking = null;
        const item: ThinkingItem = {
          kind: "thinking",
          id: nextId(model),
          thinking: p.thinking ?? "",
          streaming: true,
        };
        if (tsMs !== undefined) item.startedAtMs = tsMs;
        model.openThinking = item;
        model.items.push(item);
        return;
      }
      const open = model.openThinking;
      if (!open) return; // orphan, ignored
      if (p.thinking) open.thinking += p.thinking;
      if (p.event_type === "stop") {
        open.streaming = false;
        if (p.stop_reason !== undefined) open.stopReason = p.stop_reason;
        settleThinkingDuration(open, tsMs);
        model.pendingThinking = open;
        model.openThinking = null;
      }
      return;
    }
    case "partial_tool_call": {
      const card = model.toolCards.get(p.tool_call_id);
      // The complete message already arrived (history / dedup hit): the whole streamed copy is ignored.
      if (card?.callComplete) return;
      if (p.event_type === "start") {
        if (card) {
          // Duplicate start (out-of-order): reset the argument buffer.
          card.name = p.name || card.name;
          card.argumentsText = p.arguments ?? "";
          card.callStreaming = true;
          if (tsMs !== undefined && card.argStartedAtMs === undefined) card.argStartedAtMs = tsMs;
          return;
        }
        const created = createToolCard(model, {
          toolCallId: p.tool_call_id,
          name: p.name,
          argumentsText: p.arguments ?? "",
          callStreaming: true,
        });
        if (tsMs !== undefined) created.argStartedAtMs = tsMs;
        return;
      }
      if (!card) return; // orphan, ignored
      if (p.name && !card.name) card.name = p.name;
      if (p.arguments) card.argumentsText += p.arguments;
      if (p.event_type === "stop") {
        card.callStreaming = false;
        if (p.stop_reason !== undefined) card.callStopReason = p.stop_reason;
        // Execution start = the call's closing timestamp (same convention as Trace analysis: tool_call → tool_call_output).
        if (tsMs !== undefined) card.callStartedAtMs = tsMs;
      }
      return;
    }
    case "partial_tool_call_output": {
      const card = model.toolCards.get(p.tool_call_id);
      // No matching call card (orphan) or output already complete: ignored, converging once the complete message arrives.
      if (!card || card.outputComplete) return;
      if (p.event_type === "start") {
        card.outputStreaming = true;
        if (p.output) card.output += p.output;
        // A live-tail synthetic start (mid-stream join seed) may already carry the image
        // set; same whole-set semantics as the delta branch below.
        if (p.images && p.images.length > 0) card.images = p.images;
        return;
      }
      if (!card.outputStreaming) return; // orphan delta/stop
      if (p.output) card.output += p.output;
      // Image delta: a single delta carries the whole array at once (the complete message converges it again, overwriting with the same value).
      if (p.images && p.images.length > 0) card.images = p.images;
      if (p.event_type === "stop") {
        card.outputStreaming = false;
        if (p.stop_reason !== undefined) card.outputStopReason = p.stop_reason;
        settleToolDuration(card, tsMs, model.stats);
      }
      return;
    }
  }
}

// ---------------------------------------------------------------------------
// Complete messages
// ---------------------------------------------------------------------------

function handleComplete(
  model: StreamModel,
  p: CompleteModelPayload,
  timestamp: string,
  nowMs: number,
  tracePosition?: TracePosition,
): void {
  switch (p.type) {
    case "text": {
      if (p.role === "user") {
        // Compaction-summary injection (`[context_summary]` prefix, an
        // internal input in the new context file): not rendered as a user bubble, doesn't
        // start a new Task. The old `<context_summary>` prefix is still recognized — old
        // Traces containing it are re-rendered through this reducer.
        if (p.text.startsWith("[context_summary]") || p.text.startsWith("<context_summary>")) {
          touchTask(model, timestamp);
          return;
        }
        // Mid-run steering (`[user_steering]`-wrapped user text, delivered between turns):
        // stays inside the running Task — it must NOT start a new Task (same exclusion idea
        // as [context_summary]) — but unlike the summary it IS rendered, as a compact
        // user-styled steering chip in-flow.
        const steering = parseUserSteeringText(p.text);
        if (steering !== null) {
          // Unless a wrap-up compaction already settled the round it belongs to: this
          // steering is exactly why the Task went on past that compaction, so it opens the
          // continuation's own round rather than joining a closed one (see
          // reopenTaskAtSteering).
          if (model.reopenTaskAtSteering && !model.taskOpen) startTask(model, timestamp, nowMs);
          touchTask(model, timestamp);
          const steerMs = tsOf(timestamp);
          const item: UserSteeringItem = {
            kind: "user_steering",
            id: nextId(model),
            text: steering,
            ...(steerMs !== undefined ? { atMs: steerMs } : {}),
          };
          model.items.push(item);
          // Open the window for the images core delivers right behind this text.
          model.openSteering = item;
          return;
        }
        // A background completion notice ([background_task_done] block) injected into the
        // running Task: same exclusion as steering — rendered inside the Task as the
        // completion banner, never a Task starter, so no stats row is flushed at the
        // injection point. Two ways to recognize the injection:
        //   - the delivery stamp (`delivery: steering`), written by the engine's drain;
        //   - POSITION, for notices written by a pre-stamp core (0.2.4 traces): a Task can
        //     never end between a turn's paired tool outputs and the continuation request,
        //     so a notice arriving while this turn's tool outputs are still owed to the
        //     model (turnToolOutputs) is provably in-task even without the stamp. This is
        //     the same rule trace analysis has always applied (a tool-calling request
        //     forces a continuation), so the two pages agree on legacy data.
        // An unstamped notice after a NO-tool final turn still falls through to the
        // user_text branch below: there an idle-launched notice task is genuinely possible
        // and position cannot tell the two apart — only the stamp can, and new cores write
        // it.
        const notice = parseBackgroundTaskDoneMessage(p.text);
        if (notice !== null && (notice.done.delivery === "steering" || model.turnToolOutputs)) {
          // A wrap-up compaction may have settled the round early; an injected notice is
          // exactly what keeps the Task going past it, so it opens the continuation's own
          // round rather than joining a closed one (same rule as the steering chip above).
          if (model.reopenTaskAtSteering && !model.taskOpen) startTask(model, timestamp, nowMs);
          touchTask(model, timestamp);
          const noticeMs = tsOf(timestamp);
          model.items.push({
            kind: "background_notice",
            id: nextId(model),
            text: p.text,
            ...(noticeMs !== undefined ? { atMs: noticeMs } : {}),
          });
          return;
        }
        // A complete text message on the main session's user side: starts a new Task.
        startTask(model, timestamp, nowMs);
        const atMs = tsOf(timestamp);
        model.items.push({
          kind: "user_text",
          id: nextId(model),
          text: p.text,
          ...(p.sender === "harness" ? { sender: "harness" as const } : {}),
          ...(atMs !== undefined ? { atMs } : {}),
        });
        return;
      }
      touchTask(model, timestamp);
      // The complete message usually follows right after a fragment's stop: prefer replacing an already-closed pending fragment, then a still-open one.
      const target = model.pendingText ?? model.openText;
      if (target) {
        // A blank body discards the fragment instead of settling it (same fidelity-only case as
        // below — core starts a text segment on the first *truthy* delta, so a whitespace-only
        // segment does stream). Blanking it in place would leave the live view showing an empty
        // bubble that a reload then drops. Removing the item and clearing both slots is what
        // discardFragmentFor does for the dedup path, and it leaves no fragment stuck streaming.
        if (!p.text.trim()) {
          removeItem(model, target);
          if (target === model.openText) model.openText = null;
          model.pendingText = null;
          return;
        }
        // The complete message replaces the fragment's content (this guarantees consistency).
        target.text = p.text;
        target.streaming = false;
        const doneMs = tsOf(timestamp);
        if (doneMs !== undefined) target.atMs = doneMs; // the completion timestamp overrides the start placeholder
        if (tracePosition !== undefined) target.tracePosition = tracePosition;
        if (p.stop_reason !== undefined) target.stopReason = p.stop_reason;
        if (target === model.openText) model.openText = null;
        model.pendingText = null;
        return;
      }
      // Fidelity-only message: core emits a complete text/thinking message with an empty body
      // when the provider attached an opaque payload to an otherwise empty part — on this text
      // branch a Gemini thoughtSignature or a GPT-5 `fidelity.phase` segment marker (GPT-5's
      // encrypted reasoning rides the *thinking* branch instead) — which is why the blank bubble
      // showed up right after a thinking segment. The message has to exist so the fidelity
      // round-trips into history, but it has nothing to show, and usually no fragment was opened
      // for it either (core only starts a segment once a truthy delta arrives). Rendering it
      // produced a blank "assistant:" bubble; collectTaskAssistant already skipped these when
      // gathering the reply text, and with the blank-fragment discard above both the live and the
      // history path now agree with it.
      if (!p.text.trim()) return;
      // No open fragment (history / mid-stream join): append directly.
      const doneMs = tsOf(timestamp);
      const item: AssistantTextItem = {
        kind: "assistant_text",
        id: nextId(model),
        text: p.text,
        streaming: false,
        ...(doneMs !== undefined ? { atMs: doneMs } : {}),
        ...(tracePosition !== undefined ? { tracePosition } : {}),
      };
      if (p.stop_reason !== undefined) item.stopReason = p.stop_reason;
      model.items.push(item);
      return;
    }
    case "image_url": {
      // An image belonging to the steering message just rendered: it joins that chip and
      // leaves the running Task alone — unlike a Prompt's image, it starts nothing.
      if (model.openSteering) {
        touchTask(model, timestamp);
        model.openSteering.images = [...(model.openSteering.images ?? []), p.image_url];
        return;
      }
      startTask(model, timestamp, nowMs);
      const imgMs = tsOf(timestamp);
      model.items.push({
        kind: "user_image",
        id: nextId(model),
        imageUrl: p.image_url,
        ...(imgMs !== undefined ? { atMs: imgMs } : {}),
      });
      return;
    }
    case "video_url": {
      // A video, on a Session whose model takes one, is exactly the image case one line up: a clip
      // belonging to the steering message just rendered joins that chip, and a Prompt's clip starts
      // its Task and gets a bubble of its own.
      if (model.openSteering) {
        touchTask(model, timestamp);
        model.openSteering.videos = [...(model.openSteering.videos ?? []), p.video_url];
        return;
      }
      startTask(model, timestamp, nowMs);
      const videoMs = tsOf(timestamp);
      model.items.push({
        kind: "user_video",
        id: nextId(model),
        videoUrl: p.video_url,
        ...(videoMs !== undefined ? { atMs: videoMs } : {}),
      });
      return;
    }
    case "thinking": {
      touchTask(model, timestamp);
      const tsMs = tsOf(timestamp);
      const target = model.pendingThinking ?? model.openThinking;
      if (target) {
        // Blank body: discard the fragment rather than settle it (see the text branch).
        if (!p.thinking.trim()) {
          removeItem(model, target);
          if (target === model.openThinking) model.openThinking = null;
          model.pendingThinking = null;
          return;
        }
        target.thinking = p.thinking;
        target.streaming = false;
        if (p.stop_reason !== undefined) target.stopReason = p.stop_reason;
        settleThinkingDuration(target, tsMs);
        if (target === model.openThinking) model.openThinking = null;
        model.pendingThinking = null;
        return;
      }
      // Same fidelity-only case as the text branch above (GPT-5 encrypted reasoning): the
      // message carries the payload, not a thought to show.
      if (!p.thinking.trim()) return;
      const item: ThinkingItem = {
        kind: "thinking",
        id: nextId(model),
        thinking: p.thinking,
        streaming: false,
      };
      if (p.stop_reason !== undefined) item.stopReason = p.stop_reason;
      // History rebuild (no fragment): approximate the thinking start with the previous message's time.
      if (model.lastTsMs > 0) item.startedAtMs = model.lastTsMs;
      settleThinkingDuration(item, tsMs);
      model.items.push(item);
      return;
    }
    case "tool_call": {
      touchTask(model, timestamp);
      const tsMs = tsOf(timestamp);
      // A card that's already a complete call receives another complete tool_call with the same id:
      // not a duplicate delivery (duplicates were already caught by dedup) but **another** call reusing
      // the id — as seen in legacy Traces from a name-as-id provider (e.g. Gemini using the function
      // name as tool_call_id). Take the create branch and start a new card (createToolCard repoints the
      // Map to the newest card, so later output/approval attribute by id to the newest); never overwrite the old card.
      const existing = model.toolCards.get(p.tool_call_id);
      const card = existing?.callComplete ? undefined : existing;
      if (card) {
        card.name = p.name;
        card.argumentsText = p.arguments;
        card.callStreaming = false;
        card.callComplete = true;
        if (p.stop_reason !== undefined) card.callStopReason = p.stop_reason;
        if (tsMs !== undefined) card.callStartedAtMs = tsMs;
        noteApprovalWait(model, card); // Approval arrived first (mid-stream join): only here do both timestamps come together
        settleUndispatchedCall(card);
        return;
      }
      if (existing && !existing.outputComplete) {
        // If the replaced old card is still "executing" (output not closed): the Map is about to
        // repoint to the new card, so the old card will never get output — close it as aborted to stop
        // the running timer (same behavior as closeExecutingToolCards).
        existing.outputComplete = true;
        existing.outputStreaming = false;
        existing.outputStopReason ??= "aborted";
      }
      const created = createToolCard(model, {
        toolCallId: p.tool_call_id,
        name: p.name,
        argumentsText: p.arguments,
        callStreaming: false,
      });
      created.callComplete = true;
      if (p.stop_reason !== undefined) created.callStopReason = p.stop_reason;
      if (tsMs !== undefined) created.callStartedAtMs = tsMs;
      noteApprovalWait(model, created); // createToolCard may have already backfilled a pending approval timestamp
      // History rebuild (no partial_tool_call start): approximate "argument
      // generation started" with the previous message's time, same
      // convention as thinking. Otherwise the tool duration would lose its
      // argument-generation segment (often the bulk of it) after a refresh, for no reason.
      if (model.lastTsMs > 0) created.argStartedAtMs = model.lastTsMs;
      settleUndispatchedCall(created);
      return;
    }
    case "tool_call_output": {
      touchTask(model, timestamp);
      let card = model.toolCards.get(p.tool_call_id);
      if (!card) {
        // Mid-stream join: create a card if the call card is missing (name unknown, UI falls back to showing tool_call_id).
        card = createToolCard(model, {
          toolCallId: p.tool_call_id,
          name: "",
          argumentsText: "",
          callStreaming: false,
        });
      }
      card.output = p.output;
      // The complete message converges the images (the streamed delta already carried them once; overwrites with the same value; also serves as a fallback for a mid-stream join).
      if (p.images && p.images.length > 0) card.images = p.images;
      card.outputStreaming = false;
      card.outputComplete = true;
      if (p.stop_reason !== undefined) card.outputStopReason = p.stop_reason;
      settleToolDuration(card, tsOf(timestamp), model.stats);
      // This turn owes the model its results, so a compaction triggering now is mid-Task
      // and the round is not over (see turnToolOutputs).
      model.turnToolOutputs = true;
      return;
    }
    // inline_data / inline_thinking: same convention as the CLI's history rendering — not shown for now.
    case "inline_data":
    case "inline_thinking":
      touchTask(model, timestamp);
      return;
  }
}

/**
 * Close tool cards still "executing" (call complete, output not yet
 * arrived): after an interruption or Task finalization, these cards will
 * never get a tool_call_output, so mark output complete to stop the view
 * layer's rolling timer; the duration stays unset and isn't shown. The
 * stop reason is recorded as aborted — these tools **never produced a
 * result**, and leaving it unset would render as a "completed" checkmark,
 * visually indistinguishable from "executed successfully but with empty output".
 * A late-arriving complete tool_call_output (if any) still overrides unconditionally, unaffected by this.
 */
function closeExecutingToolCards(model: StreamModel): void {
  for (const card of model.toolCards.values()) {
    if (card.callComplete && !card.outputComplete) {
      card.outputComplete = true;
      card.outputStreaming = false;
      card.outputStopReason ??= "aborted";
    }
  }
}

/**
 * A tool_call that closed with a non-completed status (produced by an interrupt closure)
 * was never dispatched for execution and will never get a tool_call_output: settle the
 * card by its closing reason as soon as it arrives, so the execution timer doesn't keep
 * spinning forever.
 */
function settleUndispatchedCall(card: ToolCallItem): void {
  if (!card.callStopReason || card.callStopReason === "completed" || card.outputComplete) return;
  card.outputComplete = true;
  card.outputStreaming = false;
  card.outputStopReason ??= card.callStopReason;
}

/** Settle the thinking duration: end time - start time (skipped if either is missing; negative values clamp to 0). */
function settleThinkingDuration(item: ThinkingItem, endMs: number | undefined): void {
  if (endMs === undefined || item.startedAtMs === undefined) return;
  item.durationMs = Math.max(0, endMs - item.startedAtMs);
}

/**
 * Settle the tool duration = the argument-generation segment + the
 * execution segment (excluding the human approval wait).
 * - Argument-generation segment: callStartedAtMs − argStartedAtMs (tool_call
 *   from generation start to closing);
 * - Execution segment: endMs − the execution start point (preferring the
 *   approval-granted timestamp approvalAtMs, deducting the approval wait;
 *   falling back to the call's closing timestamp callStartedAtMs when there's no approval event).
 * Adding the two gives the tool call's total duration; a later-arriving
 * tool_call_output only fills in the execution segment, never overwriting
 * the already-settled generation segment.
 * Degrades to a pure execution segment when the start point is missing, still never negative.
 */
function settleToolDuration(
  card: ToolCallItem,
  endMs: number | undefined,
  stats?: TaskStatsTracker,
): void {
  if (endMs === undefined) return;
  const execStart = card.approvalAtMs ?? card.callStartedAtMs;
  if (execStart === undefined) return;
  const genMs =
    card.argStartedAtMs !== undefined && card.callStartedAtMs !== undefined
      ? Math.max(0, card.callStartedAtMs - card.argStartedAtMs)
      : 0;
  card.durationMs = genMs + Math.max(0, endMs - execStart);
  // The execution half alone feeds the session's tool wall time: the generation half above is
  // the model streaming arguments and is already inside taskLlmMs. Settling twice (a streamed
  // stop, then the complete message) is harmless — the intervals are unioned, not summed.
  if (stats) addToolExecution(stats, execStart, endMs);
}

/**
 * Add this card's human approval wait (approval_decision timestamp − the
 * tool_call's closing timestamp) into the currently unclosed Request, for
 * request_end to deduct from the wall-clock duration (see StreamModel.openApprovalWaitMs).
 *
 * The normal order is tool_call arriving first, approval_decision later;
 * joining the live stream mid-way can reverse this (the approval lands in
 * pendingDecisions first, backfilled when the card is created). So whichever
 * of the two timestamps arrives later triggers this, with
 * approvalWaitCounted guarding against double-counting. An auto-approved
 * interval is ≈0, so deducting it does no harm.
 */
function noteApprovalWait(model: StreamModel, card: ToolCallItem): void {
  if (card.approvalWaitCounted) return;
  const { callStartedAtMs: call, approvalAtMs: approval } = card;
  if (call === undefined || approval === undefined) return;
  card.approvalWaitCounted = true;
  const wait = approval - call;
  if (wait > 0) model.openApprovalWaitMs += wait;
}

function createToolCard(
  model: StreamModel,
  init: { toolCallId: string; name: string; argumentsText: string; callStreaming: boolean },
): ToolCallItem {
  const item: ToolCallItem = {
    kind: "tool_call",
    id: nextId(model),
    toolCallId: init.toolCallId,
    name: init.name,
    argumentsText: init.argumentsText,
    callStreaming: init.callStreaming,
    callComplete: false,
    output: "",
    outputStreaming: false,
    outputComplete: false,
  };
  // An approval decision that arrived before the card: backfilled at creation time.
  const pending = model.pendingDecisions.get(init.toolCallId);
  if (pending !== undefined) {
    item.decision = pending;
    item.decisionSource = model.localDecisions.has(init.toolCallId) ? "manual" : "remote";
    model.pendingDecisions.delete(init.toolCallId);
    const pendingTs = model.pendingDecisionTs.get(init.toolCallId);
    if (pendingTs !== undefined) {
      item.approvalAtMs = pendingTs;
      model.pendingDecisionTs.delete(init.toolCallId);
    }
  }
  model.toolCards.set(init.toolCallId, item);
  model.items.push(item);
  return item;
}

// ---------------------------------------------------------------------------
// Events
// ---------------------------------------------------------------------------

function handleEvent(model: StreamModel, p: EventPayload, tsMs?: number, nowMs?: number): void {
  switch (p.type) {
    case "approval_decision": {
      const card = model.toolCards.get(p.tool_call_id);
      if (card) {
        card.decision = p.decision;
        card.decisionSource = model.localDecisions.has(p.tool_call_id) ? "manual" : "remote";
        // Approval-granted timestamp: execution timing starts from here (deducting the approval wait).
        if (tsMs !== undefined && card.approvalAtMs === undefined) card.approvalAtMs = tsMs;
        noteApprovalWait(model, card); // Normal order: approval arrives later, both timestamps are already available here
      } else {
        model.pendingDecisions.set(p.tool_call_id, p.decision);
        if (tsMs !== undefined) model.pendingDecisionTs.set(p.tool_call_id, tsMs);
      }
      return;
    }
    case "abort": {
      // In-flight tools won't get any more output after an interruption (a
      // placeholder resend goes only to the model, never written to Trace): finalize the executing cards.
      closeExecutingToolCards(model);
      // A reconnect hint waiting to retry: an interruption means retries are
      // exhausted/abandoned, so mark it gaveUp (this interruption marker item gives the reason).
      const waiting = findLastWaitingReconnect(model);
      if (waiting) waiting.gaveUp = true;
      const item: AbortItem = { kind: "abort", id: nextId(model) };
      if (typeof p.error_code === "string") item.errorCode = p.error_code;
      if (typeof p.error_message === "string") item.errorMessage = p.error_message;
      if (p.reason != null) item.reason = p.reason;
      model.items.push(item);
      return;
    }
    case "token_usage":
      trackMainUsage(model.stats, p);
      return;
    case "mcp_connect_begin": {
      model.items.push({
        kind: "mcp_connect",
        id: nextId(model),
        servers: p.servers,
        running: true,
        ...(tsMs !== undefined ? { beginTsMs: tsMs } : {}),
      });
      return;
    }
    case "mcp_connect_end": {
      const item = findLastRunningMcpConnect(model);
      // Mid-stream join without the begin: the connect status is transient — nothing to show.
      if (!item) return;
      item.running = false;
      // Wall time comes from the pair's message timestamps (the payload carries no duplicate duration).
      if (tsMs !== undefined && item.beginTsMs !== undefined) {
        item.durationMs = Math.max(0, tsMs - item.beginTsMs);
      }
      if (p.status === "aborted") item.aborted = true;
      // Headline count for the connect row: MCP tools discovered across connected servers.
      item.toolCount = p.results.reduce((sum, r) => sum + (r.tools ?? 0), 0);
      // Per-server outcomes back the row's server groups (error details live there, not
      // on the header line).
      item.results = p.results.map((r) => {
        // Live results carry the unified pair; legacy Traces spell the detail `error`.
        const detail = r.error_message ?? (r as { error?: string }).error;
        return {
          server: r.server,
          status: r.status,
          durationMs: r.duration_ms,
          ...(r.tools !== undefined ? { tools: r.tools } : {}),
          ...(detail !== undefined ? { error: detail.slice(0, 500) } : {}),
        };
      });
      const failedResults = p.results.filter(
        (r) => r.status === "fatal" || (r.status as string) === "failed",
      );
      if (failedResults.length > 0) item.failed = failedResults.map((r) => r.server);
      return;
    }
    case "tool_list_ready": {
      // The Session's resolved toolset; the connect row keeps the MCP share as its
      // expandable tool list. Non-MCP entries (built-in tools) aren't news to the user.
      const item = findLastMcpConnect(model);
      if (!item) return;
      const mcpTools = p.tools.filter((t) => t.name.startsWith("mcp__"));
      if (mcpTools.length > 0) {
        item.tools = mcpTools.map((t) => ({
          name: t.name,
          ...(t.description !== undefined ? { description: t.description } : {}),
        }));
      }
      return;
    }
    case "compaction_begin": {
      // A wrap-up compaction is its own round, so the round it follows is over: settle that
      // round's ledger NOW, before the banner exists, and the banner is created underneath
      // it. Settling at task-idle instead would put the banner on screen first and slide the
      // stats row in above it once the compaction finished — a jump, since a compaction
      // request against the largest context of the session takes seconds.
      if (isWrapUpCompaction(model)) {
        finalizeOpenTask(model);
        model.reopenTaskAtSteering = true;
      }
      beginCompaction(model.stats);
      model.items.push({
        kind: "compaction",
        id: nextId(model),
        reason: p.reason,
        mode: p.mode,
        running: true,
        ...(tsMs !== undefined ? { beginTsMs: tsMs } : {}),
      });
      return;
    }
    case "compaction_end": {
      // status decides whether context usage is cleared: when not completed, the original context is kept (see endCompaction).
      endCompaction(model.stats, p.status);
      const item = findLastRunningCompaction(model);
      if (item) {
        item.running = false;
        item.status = p.status;
        if (p.error_message !== undefined) item.errorMessage = p.error_message;
        if (tsMs !== undefined && item.beginTsMs !== undefined) {
          item.durationMs = Math.max(0, tsMs - item.beginTsMs);
        }
        // The result section runs for as long as the row does, so its wall time ends here too.
        if (tsMs !== undefined && item.summaryStartedAtMs !== undefined) {
          item.summaryDurationMs = Math.max(0, tsMs - item.summaryStartedAtMs);
        }
        // A compaction that did not complete produced no summary — only a half-written
        // draft that was never adopted (a user quitting mid-compaction is the common case,
        // closed as `failed` when the session next loads). Discard it, and the thinking that
        // led to it, rather than leave a truncated summary on screen implying the context
        // was replaced by it.
        if (p.status !== "completed") {
          delete item.summaryText;
          delete item.thinkingText;
          delete item.thinkingStreaming;
          delete item.thinkingStartedAtMs;
          delete item.thinkingDurationMs;
          delete item.summaryStartedAtMs;
          delete item.summaryDurationMs;
        } else if (item.thinkingStreaming) {
          // Nothing streams past the end: a fragment whose stop never arrived settles here,
          // and its wall time settles with it rather than leaving the row without a number.
          item.thinkingStreaming = false;
          settleCompactionThinking(item, tsMs);
        }
      } else {
        // Mid-stream join (missed the begin): append a completed banner directly.
        const created: CompactionItem = {
          kind: "compaction",
          id: nextId(model),
          reason: p.reason,
          mode: p.mode,
          running: false,
          status: p.status,
          ...(p.error_message !== undefined ? { errorMessage: p.error_message } : {}),
        };
        model.items.push(created);
      }
      return;
    }
    case "request_begin": {
      // A retry request was sent: mark the waiting reconnect hint as resent (a no-op when there's no such item before a normal first request).
      const waiting = findLastWaitingReconnect(model);
      if (waiting) waiting.retrying = true;
      // Record this Request's start (for output TPS timing); compaction requests aren't timed.
      if (!model.stats.compactionActive) {
        model.openRequestBeginMs = tsMs ?? null;
        model.openApprovalWaitMs = 0;
        // A new turn: whatever the previous one owed the model has been sent with it.
        model.turnToolOutputs = false;
      }
      return;
    }
    case "request_end": {
      // A retryable end: the engine retries carrying the content already
      // produced, rendering a retry hint (with the attempt number); the terminal
      // statuses aren't rendered (Request duration is covered by Trace performance
      // analysis) and reset the consecutive-failure count. request events
      // within a compaction range (only visible during history rebuild)
      // are neither rendered nor counted — the compaction process only exposes the compaction event pair to the Human.
      if (model.stats.compactionActive) return;
      // Pairs with request_begin to compute this Request's wall-clock
      // duration, deducts the human approval wait, and adds the result to
      // this Task's LLM time (for output TPS) — this duration includes tool
      // argument generation but excludes tool execution (which happens
      // between two Requests) and excludes the human approval wait (see openApprovalWaitMs).
      if (model.openRequestBeginMs !== null && tsMs !== undefined) {
        addLlmDuration(model.stats, tsMs - model.openRequestBeginMs - model.openApprovalWaitMs);
      }
      model.openRequestBeginMs = null;
      model.openApprovalWaitMs = 0;
      // This is now the round's end (so far): update taskLastReqEndMs, with
      // the duration taken as "it − the first message". This also settles
      // compaction's Token attribution — reaching this point means a
      // pending compaction is followed by this round's normal Request (a
      // compaction triggered **mid-round**, which keeps running with a
      // carry-over after compacting), so its usage belongs to this round
      // and is settled into this round's cost. After a finalization
      // compaction / manual /compact, there's no more Request in this
      // round, so the pending compaction usage never reaches this step and is discarded at finalization (not counted into this round).
      if (tsMs !== undefined) model.taskLastReqEndMs = tsMs;
      commitPendingCompaction(model.stats);
      // A fatal end stops the run — no abort event follows; this request_end is the
      // terminal record, rendered as an error banner.
      if (p.status === "fatal") {
        const item: LlmErrorItem = { kind: "llm_error", id: nextId(model) };
        if (typeof p.error_code === "string") item.errorCode = p.error_code;
        if (typeof p.error_message === "string" && p.error_message) {
          item.errorMessage = p.error_message;
        }
        model.items.push(item);
        return;
      }
      // Every status the engine reconnects on gets an item — leaving one out would stall
      // the session for the whole ladder with nothing on screen and no give-up control.
      if (isReconnectStatus(p.status)) {
        const item: ReconnectItem = {
          kind: "reconnect",
          id: nextId(model),
          status: p.status,
          // The core stamps the authoritative ordinal on every retryable request_end; only
          // Traces written before the field existed lack it (rendered as attempt 1).
          attempt: p.attempt ?? 1,
          retrying: false,
        };
        if (typeof p.error_code === "string") item.errorCode = p.error_code;
        if (typeof p.error_message === "string" && p.error_message) {
          item.errorMessage = p.error_message;
        }
        // The engine announced its planned backoff: keep it with the CLIENT arrival time
        // as the countdown anchor (skew-free — see ReconnectItem.arrivedAtMs).
        if (typeof p.retry_in_ms === "number" && p.retry_in_ms > 0) {
          item.plannedDelayMs = p.retry_in_ms;
          item.arrivedAtMs = nowMs ?? Date.now();
        } else if (p.status === "retryable") {
          // A live-protocol retryable without a planned wait is the ladder giving up —
          // the run ends on it (an abort follows only in legacy Traces). The legacy
          // spellings never self-settle here: their era stamped no retry_in_ms mid-ladder,
          // and their exhaustion is marked by the abort event instead.
          item.gaveUp = true;
        }
        // One line per LADDER, not per attempt: a later attempt replaces the one before it, so
        // a request that retries four times reads 已发起第 4 次重试 / "retry #4 sent" on a single
        // line instead of stacking four. The count is already in the line, so nothing is lost
        // from the transcript — and the Trace is untouched, keeping every attempt as its own
        // event for the Trace panel, which builds from the raw events rather than from this model.
        const continues = continuedLadder(model, item);
        if (continues !== null) {
          // The previous item's id is kept so the rendered line UPDATES rather than being
          // replaced: a new key would remount the row and replay its entry animation, which
          // reads as a new failure rather than the same one progressing.
          model.items[model.items.length - 1] = { ...item, id: continues.id };
        } else {
          model.items.push(item);
        }
      }
      return;
    }
  }
}

function findLastRunningMcpConnect(model: StreamModel): McpConnectItem | null {
  for (let i = model.items.length - 1; i >= 0; i -= 1) {
    const item = model.items[i]!;
    if (item.kind === "mcp_connect" && item.running) return item;
  }
  return null;
}

/** Last connect row regardless of state: tool_list_ready lands right after its end. */
function findLastMcpConnect(model: StreamModel): McpConnectItem | null {
  for (let i = model.items.length - 1; i >= 0; i -= 1) {
    const item = model.items[i]!;
    if (item.kind === "mcp_connect") return item;
  }
  return null;
}

function findLastRunningCompaction(model: StreamModel): CompactionItem | null {
  for (let i = model.items.length - 1; i >= 0; i--) {
    const item = model.items[i]!;
    if (item.kind === "compaction" && item.running) return item;
  }
  return null;
}

/**
 * Appends streamed/replayed summary text onto the running compaction banner and starts the
 * result section's wall time on its first content (no-op without a running banner); the
 * section settles at compaction_end, where it stops showing itself as running.
 */
function appendCompactionSummaryText(
  model: StreamModel,
  text: string,
  startMs: number | undefined,
): void {
  if (!text) return;
  const item = findLastRunningCompaction(model);
  if (!item) return;
  item.summaryText = (item.summaryText ?? "") + text;
  if (startMs !== undefined && item.summaryStartedAtMs === undefined) {
    item.summaryStartedAtMs = startMs;
  }
}

/**
 * Appends streamed/replayed thinking onto the running compaction banner, records whether its
 * fragment is still open, and times the section from its first content to the stop that closes
 * it (no-op without a running banner). A content-free phase (the start, the stop) only moves
 * the streaming flag, so a request that never thought leaves no empty draft — and no stray
 * wall time — behind.
 */
function appendCompactionThinking(
  model: StreamModel,
  text: string,
  streaming: boolean,
  startMs: number | undefined,
  endMs: number | undefined,
): void {
  const item = findLastRunningCompaction(model);
  if (!item) return;
  if (text) {
    item.thinkingText = (item.thinkingText ?? "") + text;
    if (startMs !== undefined && item.thinkingStartedAtMs === undefined) {
      item.thinkingStartedAtMs = startMs;
    }
  }
  item.thinkingStreaming = streaming;
  if (!streaming) settleCompactionThinking(item, endMs);
}

/** Settle the thinking section: end time - its recorded start (a later attempt's stop extends the same span). */
function settleCompactionThinking(item: CompactionItem, endMs: number | undefined): void {
  if (endMs === undefined || item.thinkingStartedAtMs === undefined) return;
  item.thinkingDurationMs = Math.max(0, endMs - item.thinkingStartedAtMs);
}

/**
 * Whether a compaction starting right now wraps the round up rather than interrupting it
 * mid-Task — the test for settling the round's stats row ahead of the banner.
 *
 * Two signals must agree, and either one being unsure simply leaves the old behavior (the row
 * is placed above the trailing banners at finalization instead, see finalizeOpenTask):
 *   - the turn that just ran produced no tool outputs — the engine's own criterion for a
 *     mid-Task compaction (`turn.toolOutputs.length > 0`);
 *   - the round's last item is the model's reply, which is what "the conversation ended" looks
 *     like on screen. A client that joined mid-Task, or a history window paged in after this
 *     round's tool outputs, can satisfy the first signal without ever having seen them, while a
 *     tool card sitting at the end says the round is still working.
 * A manual `/compact` between Tasks needs neither: no Task is open, so there is nothing to
 * settle and the banner already lands after the previous round's row.
 */
function isWrapUpCompaction(model: StreamModel): boolean {
  if (!model.taskOpen || model.turnToolOutputs) return false;
  return model.items[model.items.length - 1]?.kind === "assistant_text";
}

/**
 * The reconnect item this one supersedes, or null when it opens a new line.
 *
 * A ladder's attempts climb (1, 2, 3, …), and they are adjacent WHEN THE FAILED ATTEMPTS
 * PRODUCED NOTHING — the `request_begin` that resends only marks the waiting item, so nothing
 * is pushed between two such rungs. An attempt cut off after it had already streamed thinking
 * or text pushes that content in between, and the ladder simply does not collapse: it renders
 * one line per attempt, exactly as it did before. That is the conservative direction, and the
 * reason this looks only at the tail rather than scanning back the way
 * {@link findLastWaitingReconnect} does — a scan would have to decide where the replacement
 * belongs among the content it skipped over.
 *
 * So the last item being a reconnect is necessary but NOT sufficient: a request that succeeded
 * pushes nothing, so the next failure's item is adjacent to the previous ladder's last one
 * while belonging to a different incident. That one restarts at attempt 1, which is what
 * separates the two cases.
 *
 * A ladder that gave up is closed and is never superseded: its line carries the final failure
 * and its detail, which is the one retry line worth keeping on screen.
 *
 * Traces written before the attempt ordinal existed read as attempt 1 throughout, so they never
 * collapse and render exactly as they always did — the safe direction for a record this cannot
 * re-derive.
 */
function continuedLadder(model: StreamModel, next: ReconnectItem): ReconnectItem | null {
  const last = model.items[model.items.length - 1];
  if (last === undefined || last.kind !== "reconnect") return null;
  if (last.gaveUp === true) return null;
  return next.attempt > last.attempt ? last : null;
}

function findLastWaitingReconnect(model: StreamModel): ReconnectItem | null {
  for (let i = model.items.length - 1; i >= 0; i--) {
    const item = model.items[i]!;
    if (item.kind === "reconnect") {
      return !item.retrying && !item.gaveUp ? item : null; // earlier items each already have a resolution, don't look further back
    }
  }
  return null;
}

// ---------------------------------------------------------------------------
// origin nested routing
// ---------------------------------------------------------------------------

function routeNested(model: StreamModel, msg: OmniMessage, nowMs: number): void {
  const head = msg.origin![0]!;
  // Sub-session token_usage: the request delta counts toward this level's stats (at any depth, same convention as the CLI).
  if (isEventMessage(msg) && msg.payload.type === "token_usage") {
    trackSubagentUsage(model.stats, msg.payload as TokenUsagePayload);
  }
  touchTask(model, msg.timestamp);

  let sub = model.subagents.get(head);
  if (!sub) {
    sub = newModel(true, model.localDecisions);
    sub.firstSeenLocalMs = nowMs;
    model.subagents.set(head, sub);
    bindSubagent(model, head, sub);
    model.unconfirmedSubagents.add(head);
  }
  // The child's first model message is the opening prompt its spawning call handed it — right
  // behind its session_meta, live and in its spliced Trace alike — and that prompt settles which
  // card it belongs on. A deeper descendant's message reaching it first means the prompt was
  // missed, and the binding by position stands.
  if (model.unconfirmedSubagents.has(head) && isModelMessage(msg)) {
    model.unconfirmedSubagents.delete(head);
    const prompt = msg.origin!.length === 1 ? openingPrompt(msg) : null;
    if (prompt !== null) moveToSpawningCard(model, head, sub, prompt);
  }
  // Elapsed-time stamps (see the StreamModel field docs): every message routed into this child's
  // subtree — its own or a deeper descendant's — counts as its activity; the recursive pushMessage
  // below stamps the deeper hops the same way.
  sub.lastActivityLocalMs = nowMs;
  const activityTs = tsOf(msg.timestamp);
  if (activityTs !== undefined) {
    if (sub.firstTsMs === undefined) sub.firstTsMs = activityTs;
    if (sub.lastActivityTsMs === undefined || activityTs > sub.lastActivityTsMs) {
      sub.lastActivityTsMs = activityTs;
    }
  }
  // Strip the first origin hop and recursively feed into the nested model.
  const rest = msg.origin!.slice(1);
  const forwarded: OmniMessage = { ...msg };
  if (rest.length > 0) forwarded.origin = rest;
  else delete forwarded.origin;
  pushMessage(sub, forwarded, nowMs);
}

/**
 * Binding rule: bind to the most recent allowed
 * (decision=allow) and not-yet-complete (output not yet complete)
 * run_subagent tool card that hasn't been bound to an origin yet; append a standalone SubagentItem if none is found.
 */
function bindSubagent(model: StreamModel, sessionId: string, sub: StreamModel): void {
  for (let i = model.items.length - 1; i >= 0; i--) {
    const item = model.items[i]!;
    if (
      item.kind === "tool_call" &&
      item.name === "run_subagent" &&
      !item.subagent &&
      !item.outputComplete &&
      item.decision === "allow"
    ) {
      item.subagent = sub;
      item.subagentSessionId = sessionId;
      return;
    }
  }
  model.items.push({ kind: "subagent", id: nextId(model), sessionId, model: sub });
}

/**
 * Moves a child onto the card of the run_subagent call that spawned it. Its first binding goes
 * by position, which picks the wrong card as soon as several calls run at once; the opening
 * prompt is exact, because core starts a child with the call's `prompt` argument verbatim as its
 * first user text. The spawning card is an allowed run_subagent card with that prompt, whose
 * `agent_id`, `model_id` and `provider` (including inherited parent values) are what the child's
 * session_meta records, and which holds no child yet or one still unconfirmed. When missing
 * metadata leaves different selectors ambiguous, its positional binding stands. Otherwise,
 * calls identical in all of that use the earliest one still running (calls start in
 * order), else the latest finished one (a background launch returns before its child's prompt
 * has streamed in). An unconfirmed child already on the spawning card trades places with this
 * one and moves again on its own prompt. A child bound standalone stays: no open card was left
 * for it, so its own was not open either.
 */
function moveToSpawningCard(
  model: StreamModel,
  sessionId: string,
  sub: StreamModel,
  prompt: string,
): void {
  const from = model.items.find(
    (item): item is ToolCallItem =>
      item.kind === "tool_call" && item.subagentSessionId === sessionId,
  );
  if (!from) return;
  const target = spawningCard(model, sessionId, prompt, sub.meta);
  if (target === null || target === from) return;
  const displacedId = target.subagentSessionId;
  const displaced = target.subagent;
  target.subagent = sub;
  target.subagentSessionId = sessionId;
  if (displaced !== undefined && displacedId !== undefined) {
    from.subagent = displaced;
    from.subagentSessionId = displacedId;
  } else {
    delete from.subagent;
    delete from.subagentSessionId;
  }
}

/** The opening prompt a child's first model message carries: a user text from its parent agent (or, in a Trace older than `sender`, from no one named). */
function openingPrompt(msg: OmniMessage): string | null {
  const p = msg.payload as { type?: string; role?: string; text?: unknown; sender?: string };
  if (p.type !== "text" || p.role !== "user" || typeof p.text !== "string") return null;
  return p.sender === undefined || p.sender === "parent_agent" ? p.text : null;
}

/** The card of the call that spawned `sessionId`, judged by its opening prompt (see moveToSpawningCard). */
function spawningCard(
  model: StreamModel,
  sessionId: string,
  prompt: string,
  meta: NestedSessionMeta | null,
): ToolCallItem | null {
  const inherited = [
    model.agentState === null ? null : agentIdFromStatePath(model.agentState),
    model.contextModel?.modelId ?? null,
    model.contextModel?.provider ?? null,
  ];
  const actual = meta === null ? null : [meta.agentId, meta.modelId, meta.provider];
  let matchedIdentity: (string | null)[] | null = null;
  let earliestRunning: ToolCallItem | null = null;
  let latestFinished: ToolCallItem | null = null;
  for (const item of model.items) {
    if (item.kind !== "tool_call" || item.name !== "run_subagent" || item.decision !== "allow") {
      continue;
    }
    const holder = item.subagentSessionId;
    if (holder !== undefined && holder !== sessionId && !model.unconfirmedSubagents.has(holder)) {
      continue;
    }
    const args = callArguments(item.argumentsText);
    if (args === null || args.prompt !== prompt) continue;
    const expected = ["agent_id", "model_id", "provider"].map((field, i) =>
      typeof args[field] === "string" ? args[field] : inherited[i]!,
    );
    if (
      actual !== null &&
      expected.some((value, i) => value !== null && actual[i] !== null && value !== actual[i])
    ) {
      continue;
    }
    // A window without parent metadata cannot distinguish inheritance from an override.
    // Preserve the existing binding instead of confirming an arbitrary same-prompt card.
    if (matchedIdentity !== null && expected.some((value, i) => value !== matchedIdentity![i])) {
      return null;
    }
    matchedIdentity = expected;
    if (!item.outputComplete) earliestRunning ??= item;
    else latestFinished = item;
  }
  return earliestRunning ?? latestFinished;
}

function callArguments(argumentsText: string): Record<string, unknown> | null {
  try {
    const args: unknown = JSON.parse(argumentsText);
    return typeof args === "object" && args !== null ? (args as Record<string, unknown>) : null;
  } catch {
    return null;
  }
}

// ---------------------------------------------------------------------------
// Overlap dedup (connect-first + dedup)
// ---------------------------------------------------------------------------

/** Stands in for an image's content inside a dedup key (see mediaInKey). */
const IMAGE_IN_KEY = "<image>";
/** The same for a video (see mediaInKey). */
const VIDEO_IN_KEY = "<video>";

/**
 * The Trace routes a windowed history page serves one record's bytes on, per media kind: the
 * record's image, or its video. A page names each of them by one of these instead of carrying the
 * bytes.
 */
const TRACE_MEDIA = {
  "trace-image": { route: /^\/api\/sessions\/[^/?#]+\/trace-image\?/, key: IMAGE_IN_KEY },
  "trace-video": { route: /^\/api\/sessions\/[^/?#]+\/trace-video\?/, key: VIDEO_IN_KEY },
} as const;

/**
 * A media slot's value as the dedup key sees it: inline bytes (`data:`) and a history page's
 * reference to the same Trace record (a `trace-image` / `trace-video` URL) are one picture or clip;
 * any other address (a web URL) is kept, since it is the same string in both copies anyway.
 */
function mediaInKey(value: unknown, kind: keyof typeof TRACE_MEDIA): unknown {
  if (typeof value !== "string") return value;
  const { route, key } = TRACE_MEDIA[kind];
  return value.startsWith("data:") || route.test(value) ? key : value;
}

/**
 * The envelope a history copy and its SSE copy share. Disk-only transport metadata
 * (`tracePosition`) must not make an otherwise identical SSE envelope look new, and neither may an
 * image's or a video's form: a windowed history page carries a user `image_url` / `video_url` and a
 * tool output's `images` by reference while the stream carries the bytes, and an SSE copy that
 * escaped the overlap dedup would draw the person's image — or download their clip a second time —
 * twice. Two media of one prompt may then share a key (same timestamp); that is harmless, since a
 * history read holds a prompt whole (the server appends held inputs the Trace lacks), so each
 * stream copy has its own history copy to match.
 */
function dedupKey(msg: OmniMessage): string {
  const { tracePosition: _tracePosition, ...envelope } = msg as OmniMessage & {
    tracePosition?: TracePosition;
  };
  if (msg.type === "model_msg") {
    const p = msg.payload as {
      type?: string;
      image_url?: unknown;
      video_url?: unknown;
      images?: unknown;
    };
    if (p.type === "image_url") {
      return JSON.stringify({
        ...envelope,
        payload: { ...p, image_url: mediaInKey(p.image_url, "trace-image") },
      });
    }
    if (p.type === "video_url") {
      return JSON.stringify({
        ...envelope,
        payload: { ...p, video_url: mediaInKey(p.video_url, "trace-video") },
      });
    }
    if (p.type === "tool_call_output" && Array.isArray(p.images)) {
      return JSON.stringify({
        ...envelope,
        payload: { ...p, images: p.images.map((image) => mediaInKey(image, "trace-image")) },
      });
    }
  }
  return JSON.stringify(envelope);
}

/** Build a dedup index from the envelope JSON of history's **last `limit` messages**. */
export function buildDedupIndex(messages: OmniMessage[], limit = 100): Set<string> {
  const index = new Set<string>();
  for (let i = Math.max(0, messages.length - limit); i < messages.length; i++) {
    index.add(dedupKey(messages[i]!));
  }
  return index;
}

/** Determine whether a complete message/event is exactly identical to history's envelope JSON (overlap dedup). */
export function isDuplicate(index: Set<string>, msg: OmniMessage): boolean {
  return index.has(dedupKey(msg));
}

/**
 * When a complete message hits the dedup check, discard the corresponding
 * in-flight streamed fragment: if a streamed copy was fed
 * into the reducer before this complete message, its content duplicates
 * history and must be entirely removed/cleared. Routed recursively to nested models by origin.
 */
export function discardFragmentFor(model: StreamModel, msg: OmniMessage): void {
  if (msg.origin && msg.origin.length > 0) {
    const sub = model.subagents.get(msg.origin[0]!);
    if (!sub) return;
    const rest = msg.origin.slice(1);
    const forwarded: OmniMessage = { ...msg };
    if (rest.length > 0) forwarded.origin = rest;
    else delete forwarded.origin;
    discardFragmentFor(sub, forwarded);
    return;
  }
  if (msg.type !== "model_msg" || isPartialPayload(msg.payload)) return;
  const p = msg.payload as CompleteModelPayload;
  switch (p.type) {
    case "text": {
      if (p.role !== "assistant") return;
      const target = model.pendingText ?? model.openText;
      if (target) {
        removeItem(model, target);
        if (target === model.openText) model.openText = null;
        model.pendingText = null;
      }
      return;
    }
    case "thinking": {
      const target = model.pendingThinking ?? model.openThinking;
      if (target) {
        removeItem(model, target);
        if (target === model.openThinking) model.openThinking = null;
        model.pendingThinking = null;
      }
      return;
    }
    case "tool_call": {
      const card = model.toolCards.get(p.tool_call_id);
      if (card && !card.callComplete) {
        removeItem(model, card);
        model.toolCards.delete(p.tool_call_id);
      }
      return;
    }
    case "tool_call_output": {
      const card = model.toolCards.get(p.tool_call_id);
      if (card && !card.outputComplete) {
        card.output = "";
        card.outputStreaming = false;
      }
      return;
    }
    default:
      return;
  }
}

function removeItem(model: StreamModel, item: ChatItem): void {
  const idx = model.items.indexOf(item);
  if (idx >= 0) model.items.splice(idx, 1);
}