@kortix/ui 0.14.3 → 0.14.5

package/dist/session/turn/plan-card.js

@@ -0,0 +1,316 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslations } from '../../i18n/index.js';
+/**
+ * The plan — its parts, and the chat's presentation of them.
+ *
+ * `session-chat.tsx` drops every plan-write part before segmentation, so
+ * session todos are drawn ONLY by the two surfaces built here and in
+ * `action-panel/easy/plan-card.tsx`. Exactly one of them is live at a time:
+ *
+ *  - **The Easy panel, on every desktop width.** The plan is session state,
+ *    not a turn artifact: one live singleton on one query key. The panel is
+ *    where the session's other live singletons already are (Outputs, Context,
+ *    Preview), and it does not scroll away mid-run. Collapsing the column or
+ *    covering it with a detail panel hides the plan rather than moving it —
+ *    deliberately, so it is never in two places across a session.
+ *  - **The chat, here, on mobile only.** Under 768px there is no panel COLUMN
+ *    at all — the cards are a drawer, shut by default — so the transcript is
+ *    the only surface always on screen. `usePlanInChat` (`plan-surface.ts`)
+ *    makes the call once; `session-chat.tsx` nulls the anchor on desktop, so
+ *    `ownsPlan` is false for every turn and this card never mounts there.
+ *
+ * The two never render together, and they share their ring (`PlanRing`) and
+ * their step list (`PlanSteps`) rather than reimplementing either — so the
+ * plan looks the same wherever it is drawn.
+ *
+ * Data is live — the `todo.updated` SSE event writes into the same query cache
+ * `useRuntimeSessionTodo` reads, so the card tracks the agent in real time.
+ */
+import { useRuntimeSessionTodo } from '@kortix/sdk/react';
+import { useId, useMemo, useState } from 'react';
+import { Disclosure, DisclosureContent, DisclosureTrigger } from '../../primitives/disclosure.js';
+import { STATUS_RING, STATUS_RING_PITCH } from '../../primitives/status-ring.js';
+import { parseTodos, TodoStatusIcon, } from '../tool/shared/todo-helpers.js';
+import { cn } from '../../lib/utils.js';
+// ============================================================================
+// Rail
+// ============================================================================
+/**
+ * One rail for every row in this card.
+ *
+ * `TodoStatusIcon` and `PlanRing` both take `RAIL_SLOT`, so 18px is the rail
+ * width and `gap-2.5` (10px) is its gutter — every text column in the card,
+ * trigger included, starts at the same 28px. `leading-[1.375rem]` gives each row
+ * an identical 22px line box, so the rows are parallel down the card, not merely
+ * aligned.
+ *
+ * The card was grown here from 12px/16px to 14px/18px. The ratio is deliberate:
+ * a 16px glyph beside 12px text is 1.33; 18px beside 14px is 1.29 — near enough
+ * that the rail keeps the same weight against the copy at the larger size. A
+ * `size-5` (20px) rail would have pushed it to 1.43 and made the glyphs shout.
+ */
+const RAIL_ROW = 'flex gap-2.5';
+/** Sizes the glyph itself — every status glyph is a bare `<svg>` with no
+ *  intrinsic dimensions, so this class IS its size. No wrapper box needed. */
+const RAIL_SLOT = 'size-4 shrink-0';
+const ROW_TEXT = 'text-sm leading-[1.375rem]';
+/** (22px line box − 18px glyph) / 2 — centres the glyph on the FIRST line of a
+ *  todo that wraps, which `items-start` alone cannot do. */
+const GLYPH_ON_FIRST_LINE = 'mt-0.5';
+/**
+ * The two trigger glyphs share one box and cross-fade between them.
+ *
+ * `scale 0.25 -> 1` with `blur 4px -> 0` is the house icon-swap curve: the blur
+ * is what bridges the two shapes so the eye reads a morph instead of a cut.
+ * Both layers are absolutely positioned in the same 18px square, so neither
+ * reflows the row as it changes.
+ *
+ * Named properties, never `transition-all` — `all` would sweep the ring's own
+ * `stroke-dashoffset` into this 300ms curve and fight the 500ms sweep.
+ */
+const GLYPH_LAYER = cn('absolute inset-0 size-full', 'transition-[opacity,scale,filter] duration-300 ease-[cubic-bezier(0.2,0,0,1)]', 'motion-reduce:transition-none');
+const GLYPH_SHOWN = 'scale-100 opacity-100 blur-none';
+const GLYPH_HIDDEN = 'pointer-events-none scale-[0.25] opacity-0 blur-[4px]';
+// ============================================================================
+// Ring geometry
+// ============================================================================
+/** SVG attributes are strings; unrounded float arithmetic writes its own noise
+ *  into them. Two decimals is finer than a single device pixel at this size. */
+function round(value) {
+    return Math.round(value * 100) / 100;
+}
+/**
+ * The dial is the `pending` todo glyph — same 16 viewBox, same r=6.3 centreline,
+ * same 1.5 stroke, same 3-on/3.4-off dash — turned into a progress indicator.
+ * That is the whole point: the summary ring at the top of the card and the
+ * pending dots in the list below are now one drawing at two jobs, so a plan that
+ * has not started looks exactly like the steps it has not started.
+ *
+ * It is reproduced as ONE circle plus a dash pattern rather than as literal
+ * arcs, because literal arcs cannot express a partial sweep and this card's
+ * whole job is to show one.
+ *
+ * `pathLength={RING_SEGMENTS}` re-scales the circle's own length to 6, so every
+ * dash number below is denominated in SEGMENTS instead of user units. A dash of
+ * `0.47` is "just under half a segment pitch" at any radius, which keeps the
+ * geometry readable and the arithmetic free of circumference constants.
+ */
+const RING_CENTER = STATUS_RING.CENTER;
+const RING_RADIUS = STATUS_RING.RADIUS;
+const RING_STROKE = STATUS_RING.STROKE;
+/**
+ * Six, because that is what the pending glyph draws. Its dash pattern is set in
+ * raw user units (3 on, 3.4 off) against a circumference of 2π·6.3 = 39.58,
+ * which is 6.19 pitches — so the real icon's last tick overlaps its first and
+ * the ring does not quite close. Rounding to 6 whole segments here widens each
+ * tick by 0.09 user units (3.09 vs 3.00 — under a tenth of a pixel at this size,
+ * invisible) and buys back a ring that closes exactly and divides cleanly for
+ * progress. Same texture, honest arithmetic.
+ */
+const RING_SEGMENTS = 6;
+/**
+ * Centreline dash, in segment units — the pending glyph's 3-in-6.4 ratio,
+ * re-expressed against a pitch of 1.
+ *
+ * The stencil is cut with BUTT caps, like the glyph it copies. Round caps here
+ * would extend every tick by half the stroke width at each end — 1.5 units on a
+ * 3-unit tick, so a 50% fatter tick against a 40% narrower gap. That is not a
+ * rounding difference, it is a different drawing: side by side the dial read
+ * chunky and the glyph read fine. Butt caps keep them the same object.
+ */
+const RING_DASH = round(STATUS_RING.DASH / STATUS_RING_PITCH);
+const RING_GAP = round(1 - RING_DASH);
+/** Half a dash. Shifts the pattern back so a segment is CENTRED on the path's
+ *  start rather than beginning there. Both the stencil and the sweep start at
+ *  12 o'clock, so this centres a tick on the top of the dial and leaves the
+ *  pattern symmetric about the vertical axis. */
+const RING_DASH_PHASE = RING_DASH / 2;
+/** SVG circles start at 3 o'clock. Progress reads from 12. */
+const RING_START_AT_TOP = `rotate(-90 ${RING_CENTER} ${RING_CENTER})`;
+/**
+ * The pie in the middle of the dial.
+ *
+ * The ring's ink stops at r=5.55 (centreline 6.3 minus half its 1.5 stroke), so
+ * the whole budget inside it is 11.1 units of diameter. The pie takes 7.2 of
+ * them and leaves 1.95 of clear air on each side — about 2.2px at the shipping
+ * 18px, which is where the tuning bottoms out. Rendered at r=3.9 the air falls
+ * to 1.65 (1.9px) and a wide slice visibly reaches for the ring.
+ *
+ * r=3.6 looked crowded on a first pass, but that was against a faint full-disc
+ * pie track that has since been removed — the track, not the radius, was what
+ * made the core read as a blob. Below r=3.3 the change stops being worth
+ * making: a 60° wedge is a few pixels of ink and stops reading as an angle.
+ *
+ * It replaced a travelling bead. On the old 2-unit ring a bead worked, but at
+ * 1.5 units of stroke it has to be ~2x the track's weight to register at all,
+ * and a dot that fat hangs off the arc head as a blob — worst when it lands on
+ * a tick, where it reads as a wart. A pie states the same fraction from the
+ * middle, where nothing else is competing for the pixels.
+ */
+const PIE_RADIUS = 3.6;
+/**
+ * How the slice is drawn: a circle at HALF the pie radius, stroked at the FULL
+ * pie radius. The stroke then extends PIE_RADIUS/2 inward and outward from that
+ * path, covering 0 → PIE_RADIUS — a solid disc, from one circle.
+ *
+ * The point of the detour is that it makes the slice animatable. A real sector
+ * is a `<path>` of arc commands, and `d` is not a CSS-transitionable property,
+ * so the pie would jump between renders. As a stroke it is carved by
+ * `stroke-dashoffset`, which transitions — on the same curve and duration as
+ * the ring, so the two move as one.
+ *
+ * Butt caps are what make it a pie rather than a blob: a butt cap on a circular
+ * stroke is perpendicular to the path, which at this radius is exactly radial.
+ * The slice's two straight edges are true radii.
+ */
+const PIE_PATH_RADIUS = round(PIE_RADIUS / 2);
+/**
+ * How far the ring has swept, and which state the plan is in. Pure, so the edge
+ * cases — an empty plan, nothing started, everything done — are unit-testable
+ * without a browser.
+ */
+export function planRingState(done, total, running) {
+    const sweep = total === 0 ? 0 : (done / total) * 360;
+    if (total > 0 && done === total)
+        return { sweep, state: 'complete' };
+    if (running)
+        return { sweep, state: 'running' };
+    return { sweep, state: 'idle' };
+}
+/** Amber while an item runs, green once the plan is done, neutral before it
+ *  starts. The same three tokens `TodoStatusIcon` uses in the list below, so the
+ *  summary and the list speak one language. */
+const RING_TONE = {
+    running: 'text-kortix-orange',
+    complete: 'text-kortix-green',
+    idle: 'text-muted-foreground',
+};
+/**
+ * Progress as a segmented dial with a pie at its heart.
+ *
+ * The ring is two layers, both cut to the same notch stencil by one `<mask>`,
+ * so the ticks line up exactly instead of being drawn twice and hoped over:
+ *
+ *  1. the full ring, muted — the track;
+ *  2. the swept arc, tinted — how far the plan has got.
+ *
+ * The pie sits inside it, outside the mask, and states the same fraction as an
+ * area instead of an angle. That redundancy is the design, not an oversight:
+ * ticks are precise but need counting, a pie is instant but coarse. Together
+ * the glyph answers "roughly how far?" at a glance and "exactly how far?" on a
+ * second look — at 18px, where a single encoding would have to pick one.
+ */
+export function PlanRing({ done, total, running, className, }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    const { state } = planRingState(done, total, running);
+    const fraction = total === 0 ? 0 : done / total;
+    // `useId` emits colons, which are legal in an HTML id but hostile inside a
+    // `url(#…)` reference — strip them rather than discover it in Safari.
+    const maskId = `plan-ring-${useId().replace(/:/g, '')}`;
+    return (_jsxs("svg", { viewBox: `0 0 ${STATUS_RING.BOX} ${STATUS_RING.BOX}`, fill: "none", role: "img", "aria-label": tI18nComplete('textd1a087aa7773', { value0: done, value1: total }), className: cn(RING_TONE[state], className), children: [_jsx("mask", { id: maskId, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: STATUS_RING.BOX, height: STATUS_RING.BOX, children: _jsx("circle", { cx: RING_CENTER, cy: RING_CENTER, r: RING_RADIUS, pathLength: RING_SEGMENTS, stroke: "#fff", strokeWidth: RING_STROKE, strokeLinecap: "butt", strokeDasharray: `${RING_DASH} ${RING_GAP}`, strokeDashoffset: RING_DASH_PHASE, transform: RING_START_AT_TOP }) }), _jsxs("g", { mask: `url(#${maskId})`, children: [_jsx("circle", { cx: RING_CENTER, cy: RING_CENTER, r: RING_RADIUS, pathLength: RING_SEGMENTS, stroke: "currentColor", strokeWidth: RING_STROKE, className: "text-muted-foreground" }), _jsx("circle", { cx: RING_CENTER, cy: RING_CENTER, r: RING_RADIUS, pathLength: RING_SEGMENTS, stroke: "currentColor", strokeWidth: RING_STROKE, strokeLinecap: "butt", strokeDasharray: RING_SEGMENTS, strokeDashoffset: round(RING_SEGMENTS * (1 - fraction)), transform: RING_START_AT_TOP, className: "transition-[stroke-dashoffset] duration-500 ease-[cubic-bezier(0.2,0,0,1)] motion-reduce:transition-none" })] }), _jsx("g", { children: fraction > 0 && (_jsx("circle", { cx: RING_CENTER, cy: RING_CENTER, r: PIE_PATH_RADIUS, pathLength: 1, fill: "none", stroke: "currentColor", strokeWidth: PIE_RADIUS, strokeLinecap: "butt", strokeDasharray: 1, strokeDashoffset: round(1 - fraction), transform: RING_START_AT_TOP, className: "transition-[stroke-dashoffset] duration-500 ease-[cubic-bezier(0.2,0,0,1)] motion-reduce:transition-none" })) })] }));
+}
+// ============================================================================
+// Card
+// ============================================================================
+/**
+ * Whether this session has a plan worth showing.
+ *
+ * `PlanCard` already returns null for an empty plan, but callers need the same
+ * answer BEFORE they lay out — the user message sizes its column differently
+ * when a plan sits under it, and `ownsPlan` alone is not that answer: the anchor
+ * falls back to the last turn when no turn ever wrote todos, so a session with
+ * zero todos still nominates an owner.
+ */
+export function useHasPlan(sessionId) {
+    const { data } = useRuntimeSessionTodo(sessionId);
+    return parseTodos(data).length > 0;
+}
+export function planSummary(todos) {
+    const total = todos.length;
+    const done = todos.filter((todo) => todo.status === 'completed').length;
+    const current = todos.find((todo) => todo.status === 'in_progress')?.content;
+    const complete = total > 0 && done === total;
+    return {
+        done,
+        total,
+        percent: total === 0 ? 0 : Math.round((done / total) * 100),
+        current,
+        /** Trigger title: the live step, or a calm complete label — never a shouty
+         *  "DONE", and never "complete" while steps remain. Undefined before the
+         *  plan starts is deliberate: the dial and the count already say "0 of 4",
+         *  and a filler title would add a word without adding information. */
+        label: current ?? (complete ? 'Plan complete' : undefined),
+        complete,
+    };
+}
+/**
+ * The list under the trigger, minus the row the trigger is already showing.
+ *
+ * The running step is the trigger's whole subject, so leaving it in the list
+ * printed it twice — the same sentence stacked on itself, once with a pending
+ * dot and once with a spinner. Completed and pending rows stay: they are the
+ * history and the road ahead, and the trigger says nothing about them.
+ *
+ * Filtering AFTER `keyTodos` is deliberate. Keying first means the surviving
+ * rows keep the keys they had while the running row was present, so React's
+ * state stays attached to a row as the agent advances past it.
+ */
+export function planListTodos(keyed) {
+    return keyed.filter(({ todo }) => todo.status !== 'in_progress');
+}
+/**
+ * Todos carry no id, so content is the only key available — and an agent
+ * repeats a line often enough ("Run the tests" twice) that keying on it alone
+ * collides. An occurrence counter disambiguates the repeat, which keeps React's
+ * state attached to the row rather than to its position.
+ */
+export function keyTodos(todos) {
+    const seen = new Map();
+    return todos.map((todo) => {
+        const n = seen.get(todo.content) ?? 0;
+        seen.set(todo.content, n + 1);
+        return { todo, key: n === 0 ? todo.content : `${todo.content}#${n}` };
+    });
+}
+export function PlanCard({ sessionId }) {
+    const tI18nComplete = useTranslations('hardcodedUi.i18nComplete');
+    const { data } = useRuntimeSessionTodo(sessionId);
+    const [open, setOpen] = useState(false);
+    const todos = useMemo(() => parseTodos(data), [data]);
+    const keyedTodos = useMemo(() => planListTodos(keyTodos(todos)), [todos]);
+    if (todos.length === 0)
+        return null;
+    const { done, total, current, label, complete } = planSummary(todos);
+    // Open + running is the only state where the trigger heads the running step.
+    const showSpinner = open && Boolean(current);
+    return (_jsxs(Disclosure, { open: open, onOpenChange: setOpen, className: "group/plan w-full select-none", variant: "outline", 
+        // bounce 0 — a plan opening is a disclosure, not a toy.
+        transition: { type: 'spring', duration: 0.3, bounce: 0 }, children: [_jsx(DisclosureTrigger, { children: _jsx("button", { type: "button", className: cn('w-full cursor-pointer rounded-md px-3 py-1.5 text-left', 'bg-transparent', 'hover:bg-primary/[0.04] transition-colors duration-150 select-none', 'focus-visible:ring-ring/50 focus-visible:ring-[3px] focus-visible:outline-none'), children: _jsxs("span", { className: cn(RAIL_ROW, 'w-full items-center'), children: [_jsxs("span", { className: cn('relative inline-flex', RAIL_SLOT), children: [_jsx(PlanRing, { done: done, total: total, running: Boolean(current), className: cn(GLYPH_LAYER, showSpinner ? GLYPH_HIDDEN : GLYPH_SHOWN) }), current ? (_jsx(TodoStatusIcon, { status: "in_progress", className: cn(GLYPH_LAYER, 
+                                        // IMPORTANT, and not decoration. `Loading` ships
+                                        // `in-[button.bg-transparent]:text-foreground` for spinners
+                                        // on transparent buttons — which this trigger is — and
+                                        // twMerge cannot collapse a prefixed utility against an
+                                        // unprefixed one, so both land and the prefixed rule would
+                                        // repaint the spinner in the body colour.
+                                        'text-kortix-orange!', showSpinner ? GLYPH_SHOWN : GLYPH_HIDDEN) })) : null] }), _jsxs("span", { className: cn('flex min-w-0 flex-1 items-baseline gap-2', ROW_TEXT), children: [_jsx("span", { className: cn('min-w-0 flex-1 truncate', complete && 'text-muted-foreground'), children: label }), _jsxs("span", { className: "text-muted-foreground shrink-0 text-xs tabular-nums", children: [done, " ", tI18nComplete.raw('text28391d3bc64e'), " ", total] })] })] }) }) }), _jsx(DisclosureContent, { children: _jsx(PlanSteps, { rows: keyedTodos, className: "px-3 py-2" }) })] }));
+}
+/**
+ * The steps themselves — the one list both surfaces draw.
+ *
+ * Extracted rather than copied into the panel card: the row rail (`RAIL_ROW`,
+ * `RAIL_SLOT`) and the four status treatments below are the plan's whole
+ * visual grammar, and two copies of it drift the moment either one is tuned.
+ * Callers own only the padding, because a disclosure body and a panel body sit
+ * in differently-inset containers.
+ *
+ * Takes rows already keyed and filtered (`planListTodos(keyTodos(todos))`) —
+ * the caller decides what the list is; this decides what it looks like.
+ */
+export function PlanSteps({ rows, className, }) {
+    return (
+    // No stepper rail. Each todo carries its own status glyph, so a connecting
+    // separator drew a second, weaker reading of the sequence the list already
+    // implies.
+    _jsx("ul", { className: cn('flex w-full flex-col gap-2', className), children: rows.map(({ todo, key }) => (_jsxs("li", { className: cn(RAIL_ROW, 'items-start'), children: [_jsx(TodoStatusIcon, { status: todo.status, className: cn(RAIL_SLOT, GLYPH_ON_FIRST_LINE) }), _jsx("p", { className: cn('min-w-0 flex-1 text-pretty', ROW_TEXT, todo.status === 'completed' && 'text-muted-foreground/60 line-through', todo.status === 'cancelled' && 'text-muted-foreground/40 line-through', todo.status === 'in_progress' && 'text-foreground font-medium', todo.status === 'pending' && 'text-foreground/85'), children: todo.content })] }, key))) }));
+}

package/dist/session/turn/queued-prompt-bubbles.d.ts

@@ -0,0 +1,23 @@
+/** Pending text stays legible while the active turn continues above it. */
+export declare const QUEUED_BUBBLE_OPACITY_CLASS = "[&_.text-foreground]:text-muted-foreground [&_p]:text-muted-foreground";
+/** `interrupted`: the runtime holds the message but a Stop ended the turn
+ *  before a step opened under it — it runs with the next send. */
+export type QueuedPromptState = 'queued' | 'interrupted';
+export type QueuedPromptStatusState = QueuedPromptState | 'failed' | 'sending' | 'held';
+/** Ring tone for a queued bubble. `pending` covers waiting and sending, so a
+ *  delivery retry that flips a row between them never changes the ring. */
+type QueuedBubbleTone = 'pending' | 'held' | 'failed';
+export declare function queuedBubbleTone(state: QueuedPromptStatusState | null | undefined): QueuedBubbleTone | undefined;
+/** Show delivery progress on the message itself, not only on the send button. */
+export declare function QueuedPromptProgress({ state }: {
+    state: 'queued' | 'sending' | 'interrupted';
+}): import("react").JSX.Element;
+/**
+ * A delivery failure retains its cause and recovery actions.
+ */
+export declare function QueuedPromptFailure({ lastError, onRetry, onRemove, }: {
+    lastError?: string | null;
+    onRetry?: () => void;
+    onRemove?: () => void;
+}): import("react").JSX.Element;
+export {};

package/dist/session/turn/queued-prompt-bubbles.js

@@ -0,0 +1,27 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '../../primitives/button.js';
+import { InlineMeta } from '../../primitives/inline-meta.js';
+import { useTranslations } from '../../i18n/index.js';
+/** Pending text stays legible while the active turn continues above it. */
+export const QUEUED_BUBBLE_OPACITY_CLASS = '[&_.text-foreground]:text-muted-foreground [&_p]:text-muted-foreground';
+export function queuedBubbleTone(state) {
+    if (!state)
+        return undefined;
+    if (state === 'failed' || state === 'held')
+        return state;
+    return 'pending';
+}
+/** Show delivery progress on the message itself, not only on the send button. */
+export function QueuedPromptProgress({ state }) {
+    const t = useTranslations('threads');
+    return (_jsx(InlineMeta, { children: _jsx("span", { role: "status", "data-queued-status": state, className: "text-muted-foreground text-xs", children: state === 'sending' ? t('sending') : t('queued') }) }));
+}
+/**
+ * A delivery failure retains its cause and recovery actions.
+ */
+export function QueuedPromptFailure({ lastError, onRetry, onRemove, }) {
+    const copy = useTranslations('hardcodedUi.i18nComplete');
+    const common = useTranslations('common');
+    return (_jsx(InlineMeta, { children: _jsxs("span", { "data-queued-status": "failed", className: "flex items-center gap-1", children: [_jsxs("span", { className: "text-kortix-red", role: "status", title: lastError ?? undefined, children: [copy.raw('textcd5f943d5863'), lastError ? ` — ${lastError}` : ''] }), onRetry && (_jsx(Button, { type: "button", variant: "ghost", size: "xs", onClick: onRetry, children: copy.raw('text942087cc2d41') })), onRemove && (_jsx(Button, { type: "button", variant: "ghost", size: "xs", onClick: onRemove, children: common('remove') }))] }) }));
+}

package/dist/session/turn/same-parts.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Element-wise identity for a list of parts.
+ *
+ * The turn's segments are memoised (`session-chat.tsx`), so a burst's `parts`
+ * array keeps its identity until the turn's parts change. That is enough for
+ * every burst EXCEPT the one being streamed into — and while a turn streams,
+ * `allParts` changes on every frame, which hands every burst in that turn a
+ * fresh array even though only the last one grew.
+ *
+ * Comparing element by element is what saves the rest. A part object is
+ * replaced when it changes and kept when it does not, so an unchanged burst
+ * compares equal against its new array and its whole subtree is skipped.
+ *
+ * The loop is O(n) on a list that is almost always under ~20, against a subtree
+ * whose re-render runs `mergeBurstSteps`, `groupSteps`, `stepLabel` per part and
+ * — if anything below is open — shiki. The comparison is not close to the cost
+ * it avoids.
+ *
+ * No React import: this is a predicate, and it is unit-tested as one.
+ */
+export declare function samePartsList<T>(a: ReadonlyArray<T>, b: ReadonlyArray<T>): boolean;

package/dist/session/turn/same-parts.js

@@ -0,0 +1,31 @@
+/**
+ * Element-wise identity for a list of parts.
+ *
+ * The turn's segments are memoised (`session-chat.tsx`), so a burst's `parts`
+ * array keeps its identity until the turn's parts change. That is enough for
+ * every burst EXCEPT the one being streamed into — and while a turn streams,
+ * `allParts` changes on every frame, which hands every burst in that turn a
+ * fresh array even though only the last one grew.
+ *
+ * Comparing element by element is what saves the rest. A part object is
+ * replaced when it changes and kept when it does not, so an unchanged burst
+ * compares equal against its new array and its whole subtree is skipped.
+ *
+ * The loop is O(n) on a list that is almost always under ~20, against a subtree
+ * whose re-render runs `mergeBurstSteps`, `groupSteps`, `stepLabel` per part and
+ * — if anything below is open — shiki. The comparison is not close to the cost
+ * it avoids.
+ *
+ * No React import: this is a predicate, and it is unit-tested as one.
+ */
+export function samePartsList(a, b) {
+    if (a === b)
+        return true;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}

package/dist/session/turn/served-model.d.ts

@@ -0,0 +1,63 @@
+import type { SessionModelUsage } from '@kortix/sdk';
+import { type ModelKey } from '@kortix/sdk/react';
+/**
+ * What a session shows about the model that answered, from the gateway's
+ * request record (`useSessionModelUsage`). The runtime transcript and the
+ * composer name the model that was asked for. When the gateway answers from a
+ * fallback model, those two differ, and so does the cost.
+ */
+/** A request's row is written as the request ends: how long after a turn ends its last row can still be missing. */
+export declare const MODEL_USAGE_SETTLE_MS = 2500;
+interface NamedModel extends ModelKey {
+    modelName: string;
+}
+/** A gateway wire id as the model picker names it; the id when the picker does not list it. */
+export declare function modelNameOfWire(models: readonly NamedModel[] | undefined, wire: string): string;
+export interface ServedModelNotice {
+    /** Display name of the model that answered the newest request. */
+    served: string;
+    /** Display name of the model that did not answer. */
+    fallbackFrom: string;
+}
+/**
+ * The newest request was being served by a fallback model in place of the one
+ * the session asked for — what the session modal reports. Null before any
+ * answer, when the session's own model answered directly, or when the newest
+ * request ended without an answer: a cancel is not a fallback to report
+ * (KRTX-2572).
+ */
+export declare function servedModelNotice(usage: SessionModelUsage | undefined, models: readonly NamedModel[] | undefined): ServedModelNotice | null;
+export interface TurnServedModel {
+    /** Display names of the models that answered the turn, most requests first. */
+    models: string[];
+    /** Legacy aggregate metadata; never use this to infer individual request switches. */
+    fallbackFrom: string | null;
+    /** One switch per failed request, independent of the turn's aggregate model counts. */
+    fallbacks?: {
+        requested: string;
+        served: string;
+        reason: string;
+    }[];
+    /** What Kortix billed for the turn's model calls, in USD. */
+    billedCost: number;
+}
+/** The models that answered one turn, keyed by the id of the prompt that started it. */
+export declare function turnServedModel(usage: SessionModelUsage | undefined, messageId: string, models: readonly NamedModel[] | undefined): TurnServedModel | undefined;
+/**
+ * `turnServedModel` with one result per ledger entry. A refetch keeps the
+ * identity of each turn that did not change, and the memoized turn row needs
+ * the same from what it is given.
+ *
+ * A turn whose first switches repeat the previous turn's last switch drops
+ * them: the session is still on the same fallback, and a thread showed the
+ * same "failed — switched" row on every turn (2026-10-19).
+ */
+export declare function turnServedModelResolver(models: readonly NamedModel[] | undefined): (usage: SessionModelUsage | undefined, messageId: string, previousMessageId?: string) => TurnServedModel | undefined;
+/**
+ * What Kortix billed the session, when any of its requests was rerouted to a
+ * fallback model. The transcript's own estimate prices every turn at the model
+ * that was asked for, so it is wrong for exactly these sessions. Null keeps
+ * the estimate.
+ */
+export declare function sessionBilledCost(usage: SessionModelUsage | undefined): number | null;
+export {};

package/dist/session/turn/served-model.js

@@ -0,0 +1,92 @@
+import { modelKeyToWire } from '@kortix/sdk/react';
+/**
+ * What a session shows about the model that answered, from the gateway's
+ * request record (`useSessionModelUsage`). The runtime transcript and the
+ * composer name the model that was asked for. When the gateway answers from a
+ * fallback model, those two differ, and so does the cost.
+ */
+/** A request's row is written as the request ends: how long after a turn ends its last row can still be missing. */
+export const MODEL_USAGE_SETTLE_MS = 2_500;
+/** A gateway wire id as the model picker names it; the id when the picker does not list it. */
+export function modelNameOfWire(models, wire) {
+    return models?.find((model) => modelKeyToWire(model) === wire)?.modelName?.trim() || wire;
+}
+/**
+ * The newest request was being served by a fallback model in place of the one
+ * the session asked for — what the session modal reports. Null before any
+ * answer, when the session's own model answered directly, or when the newest
+ * request ended without an answer: a cancel is not a fallback to report
+ * (KRTX-2572).
+ */
+export function servedModelNotice(usage, models) {
+    const latest = usage?.latest;
+    // A request the user canceled did not fail: the selected model "not
+    // answering" is the cancel's effect, not a fallback to report (KRTX-2572).
+    // The notice returns with the next answered request, as before.
+    if (latest?.outcome === 'client_aborted' || latest?.outcome === 'error')
+        return null;
+    if (!latest?.fallback_from)
+        return null;
+    return {
+        served: modelNameOfWire(models, latest.served_model),
+        fallbackFrom: modelNameOfWire(models, latest.fallback_from),
+    };
+}
+/** The models that answered one turn, keyed by the id of the prompt that started it. */
+export function turnServedModel(usage, messageId, models) {
+    const turn = usage?.turns[messageId];
+    if (!turn)
+        return undefined;
+    return {
+        models: turn.served_models.map((wire) => modelNameOfWire(models, wire)),
+        fallbackFrom: turn.fallback_from ? modelNameOfWire(models, turn.fallback_from) : null,
+        fallbacks: (turn.fallbacks ?? []).map((event) => ({
+            requested: modelNameOfWire(models, event.requested_model),
+            served: modelNameOfWire(models, event.served_model),
+            reason: event.error_code,
+        })),
+        billedCost: turn.billed_cost,
+    };
+}
+/**
+ * `turnServedModel` with one result per ledger entry. A refetch keeps the
+ * identity of each turn that did not change, and the memoized turn row needs
+ * the same from what it is given.
+ *
+ * A turn whose first switches repeat the previous turn's last switch drops
+ * them: the session is still on the same fallback, and a thread showed the
+ * same "failed — switched" row on every turn (2026-10-19).
+ */
+export function turnServedModelResolver(models) {
+    const resolved = new WeakMap();
+    return (usage, messageId, previousMessageId) => {
+        const turn = usage?.turns[messageId];
+        if (!turn)
+            return undefined;
+        const previous = previousMessageId ? usage.turns[previousMessageId] : undefined;
+        const cached = resolved.get(turn);
+        if (cached && cached.previous === previous)
+            return cached.value;
+        const value = turnServedModel(usage, messageId, models);
+        const last = previous?.fallbacks?.at(-1);
+        // `value.fallbacks` maps the ledger's `turn.fallbacks` one to one.
+        const fresh = last ? (turn.fallbacks ?? []).findIndex((event) => event.requested_model !== last.requested_model ||
+            event.served_model !== last.served_model || event.error_code !== last.error_code) : 0;
+        if (fresh !== 0)
+            value.fallbacks = fresh < 0 ? [] : value.fallbacks?.slice(fresh);
+        resolved.set(turn, { previous, value });
+        return value;
+    };
+}
+/**
+ * What Kortix billed the session, when any of its requests was rerouted to a
+ * fallback model. The transcript's own estimate prices every turn at the model
+ * that was asked for, so it is wrong for exactly these sessions. Null keeps
+ * the estimate.
+ */
+export function sessionBilledCost(usage) {
+    if (!usage)
+        return null;
+    const fellBack = Object.values(usage.turns).some((turn) => turn.fallback_from) || !!usage.latest?.fallback_from;
+    return fellBack ? usage.billed_cost : null;
+}

package/dist/session/turn/source-pill.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Where a prompt came from, drawn above its bubble: mark · source · sender.
+ * One pill for every non-typed origin — a Slack / Teams / Telegram message
+ * (`ChannelMessage`) and a prompt another Kortix session sent
+ * (`MessageAuthorLabel`), a reminder fire and a trigger fire — so they never
+ * drift apart. Hovering or focusing it opens `card` with the origin's detail;
+ * `cardClassName` widens the card when a row holds a long value.
+ */
+export declare function SourcePill({ mark, source, sourceColor, sender, card, cardClassName, }: {
+    mark: React.ReactNode;
+    source: string;
+    sourceColor?: string;
+    sender: string;
+    card: React.ReactNode;
+    cardClassName?: string;
+}): import("react").JSX.Element;
+/** The hover card body: a titled header, label/value rows (empty rows drop) and an optional footer. */
+export declare function SourceCard({ mark, title, rows, footer, }: {
+    mark: React.ReactNode;
+    title: string;
+    rows?: Array<{
+        label: string;
+        value: React.ReactNode;
+    }>;
+    footer?: React.ReactNode;
+}): import("react").JSX.Element;

package/dist/session/turn/source-pill.js

@@ -0,0 +1,20 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HoverCard, HoverCardContent, HoverCardTrigger } from '../../primitives/hover-card.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Where a prompt came from, drawn above its bubble: mark · source · sender.
+ * One pill for every non-typed origin — a Slack / Teams / Telegram message
+ * (`ChannelMessage`) and a prompt another Kortix session sent
+ * (`MessageAuthorLabel`), a reminder fire and a trigger fire — so they never
+ * drift apart. Hovering or focusing it opens `card` with the origin's detail;
+ * `cardClassName` widens the card when a row holds a long value.
+ */
+export function SourcePill({ mark, source, sourceColor, sender, card, cardClassName, }) {
+    return (_jsxs(HoverCard, { openDelay: 300, closeDelay: 100, children: [_jsx(HoverCardTrigger, { asChild: true, children: _jsxs("button", { type: "button", "data-testid": "message-source", className: "bg-foreground/5 text-muted-foreground hover:bg-foreground/10 focus-visible:ring-ring inline-flex max-w-[80%] items-center gap-1.5 rounded-full py-0.5 pr-2.5 pl-2 text-xs transition-colors duration-(--duration-normal) focus-visible:ring-2 focus-visible:outline-none", children: [mark, _jsx("span", { style: sourceColor ? { color: sourceColor } : undefined, children: source }), _jsx("span", { "aria-hidden": "true", children: "\u00B7" }), _jsx("span", { className: "text-foreground truncate font-medium", children: sender })] }) }), _jsx(HoverCardContent, { align: "end", className: cn('w-60 p-0', cardClassName), children: card })] }));
+}
+/** The hover card body: a titled header, label/value rows (empty rows drop) and an optional footer. */
+export function SourceCard({ mark, title, rows = [], footer, }) {
+    const shown = rows.filter((row) => row.value);
+    return (_jsxs("div", { className: "flex flex-col gap-2 px-3.5 py-3 text-xs", children: [_jsxs("div", { className: "text-foreground flex items-center gap-1.5 font-medium", children: [mark, title] }), shown.length > 0 && (_jsx("dl", { className: "flex flex-col gap-1", children: shown.map((row) => (_jsxs("div", { className: "flex items-center gap-3", children: [_jsx("dt", { className: "text-muted-foreground w-18 shrink-0 whitespace-nowrap", children: row.label }), _jsx("dd", { className: "text-foreground min-w-0 truncate", children: row.value })] }, row.label))) })), footer] }));
+}

package/dist/session/turn/status-elapsed.d.ts

@@ -0,0 +1,12 @@
+export interface StatusElapsedState {
+    status: string;
+    working: boolean;
+    startedAtMs: number;
+    elapsedMs: number;
+}
+export interface StatusElapsedInput {
+    status: string;
+    working: boolean;
+    nowMs: number;
+}
+export declare function statusElapsedFrame(previous: StatusElapsedState | undefined, input: StatusElapsedInput): StatusElapsedState;