@adecore/agents-react 0.0.1 → 0.17.0-beta.1

package/src/chat/logic/fork.ts

@@ -0,0 +1,200 @@
+import i18next from 'i18next';
+import type { AgentKind, ChatForkPayload, ChatInfo, ChatItem, ChatTurnItem, ModelSelection } from '@adecore/agent-contracts';
+import type { TimelineRow } from './timeline';
+
+/* The providers whose chat a machine can fork, and go on with in a fork, are the ones with a conversation the CLI keeps. */
+export const FORKABLE_PROVIDERS: ReadonlySet<string> = new Set(['claude', 'codex']);
+
+/* Where a fork goes on after, as the dialog words it. */
+export interface ForkPoint {
+    turnId: string;
+    number: number;
+    total: number;
+    /* False while the client holds only the newest part of the thread, so `number` and `total` count from there. */
+    counted: boolean;
+    last: boolean;
+    /* The first line of what the person asked in that turn, or the label of a turn nobody typed. */
+    prompt: string | null;
+}
+
+function turnsOf(items: Record<string, ChatItem>, order: readonly string[]): ChatTurnItem[] {
+    return order.flatMap((id) => {
+        const item = items[id];
+        return item?.kind === 'turn' ? [item] : [];
+    });
+}
+
+/*
+ * Why a chat cannot be forked after this turn right now, or null when it can. A turn still running,
+ * or any turn in the chat, is a transcript that grows while it would be copied.
+ */
+export function forkRefusal(info: ChatInfo | null, turn: ChatItem | undefined): string | null {
+    if (info === null || turn?.kind !== 'turn') {
+        return i18next.t('agent-chat:fork.refusal.notInConversation');
+    }
+    if (!FORKABLE_PROVIDERS.has(info.provider)) {
+        return i18next.t('agent-chat:fork.refusal.cliCannotFork');
+    }
+    if (info.agentSessionId === null) {
+        return i18next.t('agent-chat:fork.refusal.noConversation');
+    }
+    if (turn.state === 'running' || info.activeTurnId !== null) {
+        return i18next.t('agent-chat:fork.refusal.turnRunning');
+    }
+    return null;
+}
+
+/* Why a fork cannot write a summary for its original right now, or null when it can. */
+export function summaryRefusal(state: { busy: boolean; originalPresent: boolean }): string | null {
+    if (!state.originalPresent) {
+        return i18next.t('agent-chat:fork.refusal.originalGone');
+    }
+    if (state.busy) {
+        return i18next.t('agent-chat:fork.refusal.turnRunning');
+    }
+    return null;
+}
+
+/* The forks this client knows of that went on after this turn of this chat, in the order it holds them. */
+export function forkIdsAfter(infos: Iterable<ChatInfo>, chatId: string, turnId: string): string[] {
+    const ids: string[] = [];
+    for (const info of infos) {
+        if (info.forkOf?.chatId === chatId && info.forkOf.turnId === turnId) {
+            ids.push(info.chatId);
+        }
+    }
+    return ids;
+}
+
+/* The turns of this chat that at least one fork this client knows of went on after. */
+export function forkedTurnIds(infos: Iterable<ChatInfo>, chatId: string): Set<string> {
+    const turns = new Set<string>();
+    for (const info of infos) {
+        if (info.forkOf?.chatId === chatId) {
+            turns.add(info.forkOf.turnId);
+        }
+    }
+    return turns;
+}
+
+/* The last turn that ended, which is where a fork from the node's menu goes on after. */
+export function lastSettledTurn(items: Record<string, ChatItem>, order: readonly string[]): string | null {
+    return turnsOf(items, order).findLast((turn) => turn.state !== 'running')?.id ?? null;
+}
+
+export function forkPointOf(items: Record<string, ChatItem>, order: readonly string[], turnId: string, whole: boolean): ForkPoint | null {
+    const turns = turnsOf(items, order);
+    const index = turns.findIndex((turn) => turn.id === turnId);
+    const turn = turns[index];
+    if (turn === undefined) {
+        return null;
+    }
+    const asked = order.map((id) => items[id]).find((item) => item?.kind === 'user' && item.turnId === turnId);
+    const text = asked?.kind === 'user' ? asked.text : (turn.label ?? '');
+    const prompt =
+        text
+            .split('\n')
+            .find((line) => line.trim() !== '')
+            ?.trim() ?? null;
+    return { turnId, number: index + 1, total: turns.length, counted: whole, last: index === turns.length - 1, prompt };
+}
+
+/* The line at the top of the dialog: which turn, and what it was about. */
+export function forkPointLabel(point: ForkPoint, maxPrompt = 60): string {
+    const where = point.last
+        ? i18next.t('agent-chat:fork.point.afterLast')
+        : point.counted
+          ? i18next.t('agent-chat:fork.point.afterTurn', { number: point.number, total: point.total })
+          : i18next.t('agent-chat:fork.point.afterThis');
+    if (point.prompt === null) {
+        return where;
+    }
+    const prompt = point.prompt.length > maxPrompt ? `${point.prompt.slice(0, maxPrompt - 1)}…` : point.prompt;
+    return i18next.t('agent-chat:fork.point.about', { where, prompt });
+}
+
+/* The turn a row of the thread belongs to, which is the turn "Fork from here" on that row goes on after. */
+export function turnIdOfRow(row: TimelineRow): string | null {
+    switch (row.kind) {
+        case 'turn-start':
+        case 'turn-fold':
+            return row.turn.id;
+        case 'changed-files':
+        case 'forks':
+            return row.turnId;
+        case 'work':
+        case 'work-live':
+        case 'workflow':
+            return row.tool.turnId;
+        case 'work-group':
+            return row.tools[0]?.turnId ?? null;
+        case 'user':
+        case 'assistant':
+        case 'thinking':
+        case 'subagent':
+        case 'approval':
+        case 'question':
+            return row.item.turnId;
+        default:
+            return null;
+    }
+}
+
+/* What a fork becomes: a chat node on a canvas, or a chat view of its own in the sidebar. */
+export type ForkShape = 'node' | 'view';
+
+/* What the dialog offers, first the default: a view forks into a view, and a node into a node or, when asked, a view. */
+export function forkShapes(origin: ForkShape): ForkShape[] {
+    return origin === 'view' ? ['view'] : ['node', 'view'];
+}
+
+/* A worktree the fork works in, on this branch, with or without the files as they were after the turn. */
+export interface ForkWorktreeChoice {
+    branch: string;
+    filesAfterTurn: boolean;
+}
+
+/* The CLI, model and account a fork goes on with; only what differs from the original is sent. */
+export interface ForkCliChoice {
+    provider: AgentKind;
+    selection: ModelSelection;
+    /* By id, the CLI's kind for its default account; absent leaves it to the machine. */
+    account?: string;
+}
+
+export function forkPayload(input: {
+    chatId: string;
+    turnId: string;
+    title: string;
+    shape: ForkShape;
+    worktree?: ForkWorktreeChoice | null;
+    cli?: { original: ForkCliChoice; chosen: ForkCliChoice };
+}): ChatForkPayload {
+    return {
+        chatId: input.chatId,
+        turnId: input.turnId,
+        title: input.title,
+        ...(input.shape === 'view' ? { asView: true } : {}),
+        ...(input.cli && input.cli.chosen.provider !== input.cli.original.provider ? { provider: input.cli.chosen.provider } : {}),
+        ...(input.cli && (input.cli.chosen.provider !== input.cli.original.provider || input.cli.chosen.selection.model !== input.cli.original.selection.model)
+            ? { selection: input.cli.chosen.selection }
+            : {}),
+        ...(input.cli?.chosen.account !== undefined &&
+        (input.cli.chosen.provider !== input.cli.original.provider || input.cli.chosen.account !== input.cli.original.account)
+            ? { account: input.cli.chosen.account }
+            : {}),
+        ...(input.worktree ? { worktree: { branch: input.worktree.branch }, ...(input.worktree.filesAfterTurn ? { filesAfterTurn: true } : {}) } : {})
+    };
+}
+
+/* Why a branch cannot be the fork's, or null when it can. */
+export function branchRefusal(branch: string, taken: readonly string[]): string | null {
+    const name = branch.trim();
+    if (name === '') {
+        return i18next.t('agent-chat:fork.branch.unnamed');
+    }
+    if (taken.includes(name)) {
+        return i18next.t('agent-chat:fork.branch.taken');
+    }
+    return null;
+}

package/src/chat/logic/handback.ts

@@ -0,0 +1,10 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+
+/* The report a `SubagentHandback` call carries in `input.message` (Claude Code 2.1.273), or null for any other item. */
+export function handbackReportOf(item: ChatItem): string | null {
+    if (item.kind !== 'tool' || item.name !== 'SubagentHandback' || typeof item.input !== 'object' || item.input === null) {
+        return null;
+    }
+    const message = (item.input as { message?: unknown }).message;
+    return typeof message === 'string' && message.trim() !== '' ? message : null;
+}

package/src/chat/logic/json.ts

@@ -0,0 +1,4 @@
+/* A plain object, which is what a tool's input and a stored record are and an array is not. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/chat/logic/limit.ts

@@ -0,0 +1,46 @@
+import i18next from 'i18next';
+import type { ChatInfo } from '@adecore/agent-contracts';
+import { formatMoment } from '@adecore/ui/format';
+
+export interface LimitView {
+    /* The state in a word or two with its time, for a pill in a header. */
+    pill: string;
+    title: string;
+    /* When it goes on, or what a person can do; null when the CLI named no time and nothing is owed. */
+    detail: string | null;
+}
+
+/*
+ * What a chat that stopped on a limit says about it, from its info alone, so a header that never holds
+ * the thread says the same as the chat. Null while the last turn stopped on nothing, or a turn runs.
+ */
+export function limitView(info: Pick<ChatInfo, 'limit' | 'resumeAt' | 'activeTurnId'>, now: number): LimitView | null {
+    const limit = info.limit;
+    if (limit === undefined || info.activeTurnId !== null) {
+        return null;
+    }
+    const resumes = info.resumeAt === undefined ? null : formatMoment(info.resumeAt, now);
+    if (limit.kind === 'overload') {
+        return {
+            pill: resumes === null ? i18next.t('agent-chat:limit.overload.pill') : i18next.t('agent-chat:limit.overload.pillRetry', { time: resumes }),
+            title: i18next.t('agent-chat:limit.overload.title'),
+            detail: resumes === null ? i18next.t('agent-chat:limit.overload.sendAgain') : i18next.t('agent-chat:limit.overload.retries', { time: resumes })
+        };
+    }
+    const resets = limit.resetsAt === undefined ? null : formatMoment(limit.resetsAt, now);
+    return {
+        pill:
+            resumes !== null
+                ? i18next.t('agent-chat:limit.usage.pillResumes', { time: resumes })
+                : resets !== null
+                  ? i18next.t('agent-chat:limit.usage.pillUntil', { time: resets })
+                  : i18next.t('agent-chat:limit.usage.pill'),
+        title: i18next.t('agent-chat:limit.usage.title'),
+        detail:
+            resumes !== null
+                ? i18next.t('agent-chat:limit.usage.resumes', { time: resumes })
+                : resets !== null
+                  ? i18next.t('agent-chat:limit.usage.resets', { time: resets })
+                  : null
+    };
+}

package/src/chat/logic/resume-compaction.ts

@@ -0,0 +1,71 @@
+import type { ChatInfo, ChatItem, ProviderCapabilities } from '@adecore/agent-contracts';
+
+/*
+ * An absolute count, not a share of the window: reading a thread again costs per token, so 100k in a
+ * window of 1M is as expensive as 100k in a window of 200k.
+ */
+export const RESUME_COMPACTION_TOKENS = 100_000;
+
+/* The longest prompt cache Claude keeps is an hour, so past this the whole thread is read again anyway. */
+export const RESUME_COMPACTION_IDLE_MS = 70 * 60_000;
+
+export interface ResumeCompactionOffer {
+    /* The turn the offer is about, and the key "Keep full history" is remembered under. */
+    turnId: string;
+    tokens: number;
+}
+
+function lastTurn(items: readonly ChatItem[]): Extract<ChatItem, { kind: 'turn' }> | null {
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i]!;
+        if (item.kind === 'turn') {
+            return item;
+        }
+    }
+    return null;
+}
+
+/*
+ * Whether to offer compacting before the next message. The caller passes `now`, so this stays pure
+ * and the test needs no clock.
+ */
+export function resumeCompactionOffer({
+    info,
+    compaction,
+    items,
+    dismissedTurnId,
+    now
+}: {
+    info: ChatInfo;
+    /* Absent until the host answered `provider.list`. */
+    compaction: ProviderCapabilities['compaction'] | undefined;
+    items: readonly ChatItem[];
+    dismissedTurnId: string | null;
+    now: number;
+}): ResumeCompactionOffer | null {
+    if (compaction === undefined || compaction === 'none') {
+        return null;
+    }
+    if (info.activeTurnId !== null || (info.queue ?? []).length > 0) {
+        return null;
+    }
+    if (info.usage.contextTokens < RESUME_COMPACTION_TOKENS) {
+        return null;
+    }
+    const turn = lastTurn(items);
+    if (turn === null || turn.endedAt === null || turn.id === dismissedTurnId) {
+        return null;
+    }
+    if (now - turn.endedAt < RESUME_COMPACTION_IDLE_MS) {
+        return null;
+    }
+    /*
+     * `contextTokens` keeps the old number until the next request, so without this the offer would
+     * come straight back after a compaction. A native compaction is a turn without a message of the
+     * person, which is why this looks at the turn and not at the last thing that was said.
+     */
+    if (items.some((item) => item.kind === 'compaction' && item.turnId === turn.id)) {
+        return null;
+    }
+    return { turnId: turn.id, tokens: info.usage.contextTokens };
+}

package/src/chat/logic/scrubber.ts

@@ -0,0 +1,289 @@
+import type { ChatBookmark } from '@adecore/agent-contracts';
+import type { TimelineRow } from './timeline';
+
+/*
+ * The strip at the left edge of a chat view with a tick per message a person sent, as numbers: which
+ * rows get a tick, where the ticks go in the height the strip has, which messages are on screen, and
+ * which one a pointer means. The component only draws what comes out of here.
+ */
+
+/* A message the person sent, a turn the machine opened with the results of tasks, or any other message with a bookmark on it. */
+export type TickKind = 'person' | 'wake' | 'bookmark';
+
+export interface ScrubberTick {
+    id: string;
+    /* The row of the timeline the tick jumps to. */
+    rowIndex: number;
+    kind: TickKind;
+    text: string;
+    createdAt: number;
+    /* The turn the message opened, which is the turn a fork from the card goes on after. */
+    turnId: string | null;
+    bookmark: ChatBookmark | null;
+}
+
+/* With fewer messages than this the thread is short enough to scroll through, and the strip is noise. */
+export const SCRUBBER_MIN_TICKS = 3;
+
+export const TICK_HEIGHT_PX = 2;
+
+const PITCH_PX = 8;
+const MIN_PITCH_PX = 4;
+
+/* The thread's content column in a view of its own (`.chat-column-content`) and the scroller's padding around it (`px-4`). */
+const CONTENT_MAX_WIDTH_PX = 768;
+const THREAD_PADDING_PX = 16;
+export const STRIP_WIDTH_PX = 24;
+/* The strip's distance from the view's left edge, and the air it keeps between itself and the thread's text. */
+export const STRIP_INSET_PX = 8;
+const STRIP_CLEARANCE_PX = STRIP_INSET_PX + STRIP_WIDTH_PX + STRIP_INSET_PX;
+
+const WIDTH_HOVERED_PX = 16;
+const WIDTH_NEAR_PERSON_PX = 12;
+const WIDTH_NEAR_WAKE_PX = 8;
+const WIDTH_PERSON_PX = 8;
+const WIDTH_WAKE_PX = 5;
+
+/* `marks` is what `bookmarkRows` answers: the bookmark drawn at a row, by row id. */
+export function ticksOf(rows: readonly TimelineRow[], marks: ReadonlyMap<string, ChatBookmark> = new Map()): ScrubberTick[] {
+    return rows.flatMap((row, rowIndex): ScrubberTick[] => {
+        const bookmark = marks.get(row.id) ?? null;
+        if (row.kind === 'user') {
+            // A message of only attachments still has a place in the thread; its names stand in for the text.
+            const text = row.item.text !== '' ? row.item.text : (row.item.attachments ?? []).map((attachment) => attachment.name).join(', ');
+            return [{ id: row.id, rowIndex, kind: 'person', text, createdAt: row.item.createdAt, turnId: row.item.turnId, bookmark }];
+        }
+        // The other turns nobody asked for (a sub-agent that finished, the CLI going on) are no place to return to.
+        if (row.kind === 'turn-start' && ((row.turn.taskIds?.length ?? 0) > 0 || (row.turn.messageFrom?.length ?? 0) > 0)) {
+            return [{ id: row.id, rowIndex, kind: 'wake', text: row.label, createdAt: row.turn.createdAt, turnId: row.turn.id, bookmark: null }];
+        }
+        if (bookmark === null) {
+            return [];
+        }
+        if (row.kind === 'assistant') {
+            return [{ id: row.id, rowIndex, kind: 'bookmark', text: row.item.text, createdAt: row.item.createdAt, turnId: row.item.turnId, bookmark }];
+        }
+        // The fold of a turn a marked reply is hidden in; the card reads the start the bookmark kept.
+        const turnId = row.kind === 'turn-fold' ? row.turn.id : null;
+        return [{ id: row.id, rowIndex, kind: 'bookmark', text: bookmark.excerpt, createdAt: bookmark.createdAt, turnId, bookmark }];
+    });
+}
+
+/* One drawn tick: a message, or a run of messages merged once the height has fewer pixels than they need. */
+export interface TickSlot {
+    first: number;
+    last: number;
+    kind: TickKind;
+    /* Whether a message under it has a bookmark, which draws it in the accent. */
+    marked: boolean;
+    /* Whether a find hit falls under it, which puts a mark of the find's own color beside it. */
+    found: boolean;
+    /* The top of the tick inside the strip. */
+    y: number;
+}
+
+export interface ScrubberLayout {
+    top: number;
+    pitch: number;
+    count: number;
+    slots: TickSlot[];
+}
+
+/* `marked` and `found` say per message whether it has a bookmark and whether a find hit falls under it; absent, none has. */
+export function layoutTicks(kinds: readonly TickKind[], height: number, marked: readonly boolean[] = [], found: readonly boolean[] = []): ScrubberLayout {
+    const count = kinds.length;
+    const room = Math.max(0, Math.floor(height));
+    const slotCount = Math.min(count, Math.floor(room / MIN_PITCH_PX));
+    if (slotCount === 0) {
+        return { top: 0, pitch: MIN_PITCH_PX, count, slots: [] };
+    }
+    const pitch = Math.min(PITCH_PX, Math.floor(room / slotCount));
+    const top = Math.floor((room - slotCount * pitch) / 2);
+    const inset = Math.floor((pitch - TICK_HEIGHT_PX) / 2);
+    const slots: TickSlot[] = [];
+    for (let i = 0; i < slotCount; i++) {
+        const first = Math.floor((i * count) / slotCount);
+        const last = Math.floor(((i + 1) * count) / slotCount) - 1;
+        // A merged tick is the person's as soon as one message in it is, since those are what the strip is for.
+        const run = kinds.slice(first, last + 1);
+        const kind = run.includes('person') ? 'person' : run.includes('bookmark') ? 'bookmark' : 'wake';
+        slots.push({
+            first,
+            last,
+            kind,
+            marked: marked.slice(first, last + 1).includes(true),
+            found: found.slice(first, last + 1).includes(true),
+            y: top + i * pitch + inset
+        });
+    }
+    return { top, pitch, count, slots };
+}
+
+/*
+ * The tick whose stretch of the thread a row falls in: a tick stands for its row and every row up to
+ * the next tick's, and a row above the first tick counts under the first. Null without ticks.
+ */
+export function tickOfRow(ticks: readonly ScrubberTick[], rowIndex: number): number | null {
+    if (ticks.length === 0) {
+        return null;
+    }
+    let low = 0;
+    let high = ticks.length - 1;
+    let found = 0;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        if (ticks[middle]!.rowIndex <= rowIndex) {
+            found = middle;
+            low = middle + 1;
+        } else {
+            high = middle - 1;
+        }
+    }
+    return found;
+}
+
+/* Per tick, whether any of the rows has a find hit in its stretch. */
+export function ticksWithHits(ticks: readonly ScrubberTick[], hitRows: readonly number[]): boolean[] {
+    const found = ticks.map(() => false);
+    for (const row of hitRows) {
+        const tick = tickOfRow(ticks, row);
+        if (tick !== null) {
+            found[tick] = true;
+        }
+    }
+    return found;
+}
+
+/* The message under a height in the strip; inside a merged tick the height picks among its messages. */
+export function messageAt(layout: ScrubberLayout, y: number): number | null {
+    const { slots, top, pitch } = layout;
+    if (slots.length === 0) {
+        return null;
+    }
+    const offset = y - top;
+    const index = Math.min(slots.length - 1, Math.max(0, Math.floor(offset / pitch)));
+    const slot = slots[index]!;
+    const fraction = Math.min(1, Math.max(0, (offset - index * pitch) / pitch));
+    return slot.first + Math.min(slot.last - slot.first, Math.floor(fraction * (slot.last - slot.first + 1)));
+}
+
+export function slotOf(layout: ScrubberLayout, message: number): number | null {
+    const { slots } = layout;
+    let low = 0;
+    let high = slots.length - 1;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        const slot = slots[middle]!;
+        if (message < slot.first) {
+            high = middle - 1;
+        } else if (message > slot.last) {
+            low = middle + 1;
+        } else {
+            return middle;
+        }
+    }
+    return null;
+}
+
+/*
+ * At rest every tick of a kind is as long as the next, so length never competes with the brightness
+ * that says what is on screen. Only a pointer on the strip magnifies, the way a dock does, one step out.
+ */
+export function tickWidth(kind: TickKind, distanceFromPointer: number | null): number {
+    if (distanceFromPointer === 0) {
+        return WIDTH_HOVERED_PX;
+    }
+    if (distanceFromPointer === 1) {
+        return kind === 'wake' ? WIDTH_NEAR_WAKE_PX : WIDTH_NEAR_PERSON_PX;
+    }
+    return kind === 'wake' ? WIDTH_WAKE_PX : WIDTH_PERSON_PX;
+}
+
+/* The last index whose start lies at or above a line, or -1. The starts only grow. */
+function lastAtOrAbove(starts: readonly number[], line: number): number {
+    let low = 0;
+    let high = starts.length - 1;
+    let found = -1;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        if (starts[middle]! <= line) {
+            found = middle;
+            low = middle + 1;
+        } else {
+            high = middle - 1;
+        }
+    }
+    return found;
+}
+
+export interface ReadingPosition {
+    /* Where each message's row starts in the thread, in the virtualizer's measurements. */
+    starts: readonly number[];
+    scrollTop: number;
+    /* The height of the thread a person can read, without what the composer covers. */
+    visibleHeight: number;
+}
+
+export interface MessageRange {
+    first: number;
+    last: number;
+}
+
+/*
+ * The messages on screen. A message counts from its own start to the start of the next one, so the
+ * question whose answer fills the screen is in view even after it scrolled out at the top.
+ */
+export function messagesInView({ starts, scrollTop, visibleHeight }: ReadingPosition): MessageRange | null {
+    const bottom = scrollTop + visibleHeight;
+    if (starts.length === 0 || visibleHeight <= 0 || starts[0]! >= bottom) {
+        return null;
+    }
+    const first = Math.max(0, lastAtOrAbove(starts, scrollTop));
+    let last = lastAtOrAbove(starts, bottom);
+    // A row that starts on the very last line has not a pixel on screen yet.
+    if (starts[last]! >= bottom) {
+        last--;
+    }
+    return { first, last: Math.max(first, last) };
+}
+
+/* Whether a drawn tick covers any of the messages on screen. */
+export function slotInView(slot: TickSlot, range: MessageRange | null): boolean {
+    return range !== null && slot.last >= range.first && slot.first <= range.last;
+}
+
+/*
+ * The message a step back or forward lands on, among the ones `eligible` allows. A jump puts a
+ * message's start at the top, so back from there is the one before it, and back from the middle of
+ * a long answer is the question it belongs to. A pixel of slack absorbs rounding in the scroller.
+ */
+export function stepMessage(starts: readonly number[], eligible: (index: number) => boolean, scrollTop: number, direction: -1 | 1): number | null {
+    if (direction === -1) {
+        for (let i = lastAtOrAbove(starts, scrollTop - 1.5); i >= 0; i--) {
+            if (eligible(i)) {
+                return i;
+            }
+        }
+        return null;
+    }
+    for (let i = lastAtOrAbove(starts, scrollTop + 1) + 1; i < starts.length; i++) {
+        if (eligible(i)) {
+            return i;
+        }
+    }
+    return null;
+}
+
+/*
+ * The left padding of the thread in a view that draws the strip at its left edge. A wide view keeps
+ * the usual padding, since its centered column already clears the strip; a narrower one pads until
+ * the column's text starts clear of it, so nothing is ever drawn under the strip.
+ */
+export function threadPaddingLeft(width: number, strip: boolean): number {
+    if (!strip) {
+        return THREAD_PADDING_PX;
+    }
+    // The column's margin is half of what the padding leaves, so the padding counts the clearance twice.
+    const padding = 2 * STRIP_CLEARANCE_PX + CONTENT_MAX_WIDTH_PX + THREAD_PADDING_PX - Math.floor(width);
+    return Math.min(STRIP_CLEARANCE_PX, Math.max(THREAD_PADDING_PX, padding));
+}

package/src/chat/logic/thread-cards.ts

@@ -0,0 +1,64 @@
+import type { ThreadCard } from '../../host';
+import type { TimelineRow } from './timeline';
+
+/*
+ * When what a row shows began, or null for a row that only follows the one before it: a turn's
+ * changed files and forks, a note, a report. The working row closes the thread, so every card goes
+ * above it.
+ */
+function rowTime(row: TimelineRow): number | null {
+    switch (row.kind) {
+        case 'user':
+        case 'assistant':
+        case 'thinking':
+        case 'approval':
+        case 'question':
+        case 'subagent':
+            return row.item.createdAt;
+        case 'turn-start':
+        case 'turn-fold':
+            return row.turn.createdAt;
+        case 'work':
+        case 'work-live':
+        case 'workflow':
+            return row.tool.createdAt;
+        case 'work-group':
+            return row.tools[0]?.createdAt ?? null;
+        case 'working':
+            return Number.POSITIVE_INFINITY;
+        default:
+            return null;
+    }
+}
+
+/* Prefixed, so a card never shares a key with a row of the chat's own. */
+function cardRow(card: ThreadCard): TimelineRow {
+    return { kind: 'app-card', id: `app-card-${card.id}`, card };
+}
+
+/*
+ * The thread's rows with an app's cards among them: a card goes right before the first row that
+ * began after it, so in a folded turn it lands under the fold, and in an open one between its calls.
+ * Without cards the rows come back as they are, the same array.
+ */
+export function withThreadCards(rows: TimelineRow[], cards: readonly ThreadCard[]): TimelineRow[] {
+    if (cards.length === 0) {
+        return rows;
+    }
+    // Sorting is stable, so cards of the same moment keep the order the app gave them.
+    const pending = [...cards].sort((first, second) => first.at - second.at);
+    const merged: TimelineRow[] = [];
+    let next = 0;
+    for (const row of rows) {
+        const time = rowTime(row);
+        while (time !== null && next < pending.length && pending[next]!.at < time) {
+            merged.push(cardRow(pending[next]!));
+            next += 1;
+        }
+        merged.push(row);
+    }
+    for (; next < pending.length; next++) {
+        merged.push(cardRow(pending[next]!));
+    }
+    return merged;
+}