The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { RunId, ScreenReaderAnnouncements } from "@t3tools/contracts"; |
| 2 | import * as DateTime from "effect/DateTime"; |
| 3 | import { searchToolLabelParts } from "@t3tools/shared/toolActivity"; |
| 4 | import { msg } from "gt-react"; |
| 5 | |
| 6 | import { m } from "../../i18n/messages"; |
| 7 | import type { TimelineEntry, WorkLogEntry } from "../../session-logic"; |
| 8 | import { |
| 9 | liveWorkEntryLabel, |
| 10 | timelineEntryRunId, |
| 11 | timelineEntryStartsResponse, |
| 12 | } from "./MessagesTimeline.logic"; |
| 13 | import { markdownPlainText } from "./timelineMinimapItems"; |
| 14 | |
| 15 | export interface TurnMessage { |
| 16 | readonly id: string; |
| 17 | /** Markdown. */ |
| 18 | readonly text: string; |
| 19 | /** The agent stopped writing it and went on working. A turn's closing reply never is. */ |
| 20 | readonly finished: boolean; |
| 21 | /** It arrived after the entry the caller last saw, unlike history loaded above it. */ |
| 22 | readonly fresh: boolean; |
| 23 | } |
| 24 | |
| 25 | export interface TurnDetail { |
| 26 | /** The step the agent is on, or null when its newest output is not a step. */ |
| 27 | readonly activity: string | null; |
| 28 | /** The agent's messages in the latest turn, oldest first. */ |
| 29 | readonly messages: ReadonlyArray<TurnMessage>; |
| 30 | /** The thread's newest entry. */ |
| 31 | readonly tailId: string | null; |
| 32 | } |
| 33 | |
| 34 | export const NO_TURN_DETAIL: TurnDetail = { activity: null, messages: [], tailId: null }; |
| 35 | |
| 36 | const ACTIVITY_MAX_LENGTH = 120; |
| 37 | // Parsing is synchronous, and nobody listens to a longer message through a live region. |
| 38 | const MESSAGE_MAX_LENGTH = 2_000; |
| 39 | |
| 40 | /** The first `maxLength` code points of `text`, or null when it has no more than that. */ |
| 41 | function cutText(text: string, maxLength: number): string | null { |
| 42 | if (text.length <= maxLength) return null; |
| 43 | const characters = Array.from(text); |
| 44 | return characters.length > maxLength ? characters.slice(0, maxLength).join("") : null; |
| 45 | } |
| 46 | |
| 47 | // The app builds these labels as a whole "Searched ..." sentence: a web search from its search |
| 48 | // parts, a file search without a provider title from its parts or as "Searched files". |
| 49 | function appLabelledSearch(work: WorkLogEntry): boolean { |
| 50 | const data = work.toolData; |
| 51 | const record = |
| 52 | data !== null && typeof data === "object" && !Array.isArray(data) |
| 53 | ? (data as Record<string, unknown>) |
| 54 | : undefined; |
| 55 | if (work.itemType === "file_search") { |
| 56 | return typeof record?.title !== "string" || record.title.trim() === ""; |
| 57 | } |
| 58 | const { query, glob, target } = searchToolLabelParts(record); |
| 59 | return Boolean(query || glob || target); |
| 60 | } |
| 61 | |
| 62 | // On screen these labels are a path or a query beside an icon. |
| 63 | function withVerb(work: WorkLogEntry, label: string) { |
| 64 | if (work.itemType === "file_change") return m(msg("Editing {label}", { label })); |
| 65 | if (work.itemType !== "file_search" && work.itemType !== "web_search") return label; |
| 66 | if (appLabelledSearch(work)) return label; |
| 67 | // Labels that did not come from the search parts are provider text, which stays English. |
| 68 | if (/^search(?:ed|ing)?\s/i.test(label)) return label; |
| 69 | return work.itemType === "web_search" |
| 70 | ? m(msg("Searching the web for {label}", { label })) |
| 71 | : m(msg("Searching for {label}", { label })); |
| 72 | } |
| 73 | |
| 74 | type MessageEntry = Extract<TimelineEntry, { kind: "message" }>; |
| 75 | |
| 76 | // A steer starts a new attempt in the same run. The reply it cut off also stops streaming, |
| 77 | // so only one that completed before the steer finished; see completeSupersededReplyEntryIds. |
| 78 | function completedBeforeSuperseded(entry: MessageEntry) { |
| 79 | const item = entry.projectedItem?.item; |
| 80 | const supersededAt = entry.attempt?.completedAt ?? null; |
| 81 | return ( |
| 82 | item?.type === "assistant_message" && |
| 83 | item.status === "completed" && |
| 84 | item.completedAt !== null && |
| 85 | supersededAt !== null && |
| 86 | DateTime.isLessThan(item.completedAt, supersededAt) |
| 87 | ); |
| 88 | } |
| 89 | |
| 90 | function stepLabel(work: WorkLogEntry, workspaceRoot: string | undefined): string | null { |
| 91 | // Reasoning text is never read out. |
| 92 | if (work.itemType === "reasoning") return m(msg("Thinking")); |
| 93 | const status = work.toolLifecycleStatus; |
| 94 | if (status === "failed" || status === "declined" || status === "stopped") return null; |
| 95 | const label = liveWorkEntryLabel(work, workspaceRoot, true).replace(/\s+/g, " ").trim(); |
| 96 | if (label === "") return null; |
| 97 | const spoken = withVerb(work, label); |
| 98 | const cut = cutText(spoken, ACTIVITY_MAX_LENGTH); |
| 99 | return cut === null ? spoken : `${cut}…`; |
| 100 | } |
| 101 | |
| 102 | /** |
| 103 | * What a screen reader can be told about the latest turn beyond its status. |
| 104 | * It reads the thread's entries before "Tool calls in chat" hides any, so what |
| 105 | * is spoken follows the announcement setting alone. |
| 106 | */ |
| 107 | export function turnDetail( |
| 108 | entries: ReadonlyArray<TimelineEntry>, |
| 109 | workspaceRoot: string | undefined, |
| 110 | knownTailId: string | null, |
| 111 | ): TurnDetail { |
| 112 | const messages: TurnMessage[] = []; |
| 113 | // Runs and attempts the agent kept working in after the entry being looked at. |
| 114 | const continuedRunIds = new Set<RunId | null>(); |
| 115 | const continuedAttemptIds = new Set<string>(); |
| 116 | const markContinued = (entry: TimelineEntry, runId: RunId | null) => { |
| 117 | continuedRunIds.add(runId); |
| 118 | if (entry.attempt !== undefined) continuedAttemptIds.add(entry.attempt.id); |
| 119 | }; |
| 120 | let activity: string | null | undefined; |
| 121 | let fresh = true; |
| 122 | let index = entries.length - 1; |
| 123 | for (; index >= 0; index -= 1) { |
| 124 | const entry = entries[index]!; |
| 125 | if (timelineEntryStartsResponse(entry)) break; |
| 126 | if (entry.id === knownTailId) fresh = false; |
| 127 | if (entry.kind === "event") continue; |
| 128 | if (entry.kind === "work") { |
| 129 | const work = entry.entry; |
| 130 | if (work.sourceActivityKind === "context-compaction") { |
| 131 | activity ??= work.toolLifecycleStatus === "inProgress" ? work.label : null; |
| 132 | continue; |
| 133 | } |
| 134 | // Notices, todo lists and checkpoints sit beside the turn's steps without being one. |
| 135 | if (work.tone !== "tool" && work.itemType !== "reasoning") continue; |
| 136 | markContinued(entry, work.runId ?? null); |
| 137 | // A request is spoken as the thread's status; once answered, the step it was for goes on. |
| 138 | if (work.itemType === "approval_request" || work.itemType === "user_input_request") continue; |
| 139 | if (activity === undefined) activity = stepLabel(work, workspaceRoot); |
| 140 | continue; |
| 141 | } |
| 142 | if (entry.kind === "message" && entry.message.role !== "assistant") continue; |
| 143 | // A reply, plan or rendered page is newer than any step before it. |
| 144 | activity ??= null; |
| 145 | const runId = timelineEntryRunId(entry); |
| 146 | if (entry.kind === "message") { |
| 147 | messages.push({ |
| 148 | id: entry.message.id, |
| 149 | text: entry.message.text, |
| 150 | finished: |
| 151 | !entry.message.streaming && |
| 152 | continuedRunIds.has(runId) && |
| 153 | (entry.attempt?.status !== "superseded" || |
| 154 | continuedAttemptIds.has(entry.attempt.id) || |
| 155 | completedBeforeSuperseded(entry)), |
| 156 | fresh, |
| 157 | }); |
| 158 | } |
| 159 | markContinued(entry, runId); |
| 160 | } |
| 161 | // Nothing is known to be new when the entry last seen is gone, or there was none. |
| 162 | let tailKnown = !fresh; |
| 163 | if (knownTailId !== null) { |
| 164 | for (; !tailKnown && index >= 0; index -= 1) tailKnown = entries[index]!.id === knownTailId; |
| 165 | } |
| 166 | return { |
| 167 | activity: activity ?? null, |
| 168 | messages: (tailKnown |
| 169 | ? messages |
| 170 | : messages.map((message) => ({ ...message, fresh: false })) |
| 171 | ).reverse(), |
| 172 | tailId: entries.at(-1)?.id ?? null, |
| 173 | }; |
| 174 | } |
| 175 | |
| 176 | export interface TurnDetailSnapshot extends TurnDetail { |
| 177 | readonly level: ScreenReaderAnnouncements; |
| 178 | readonly status: "working" | "approval" | "input" | "idle"; |
| 179 | } |
| 180 | |
| 181 | export interface TurnDetailMemory { |
| 182 | readonly activity: string | null; |
| 183 | /** Each message seen in the turn, and whether it was already finished then. */ |
| 184 | readonly messages: ReadonlyMap<string, boolean>; |
| 185 | readonly tailId: string | null; |
| 186 | } |
| 187 | |
| 188 | /** The heading every agent message has in the timeline. */ |
| 189 | const MESSAGE_AUTHOR = "T3 Code"; |
| 190 | |
| 191 | /** |
| 192 | * Decides which of the turn's messages and steps a screen reader hears next. |
| 193 | * The first snapshot of a thread is a silent baseline, like its status. |
| 194 | */ |
| 195 | export function nextTurnDetailAnnouncement( |
| 196 | previous: TurnDetailMemory | null, |
| 197 | next: TurnDetailSnapshot, |
| 198 | ): { |
| 199 | readonly memory: TurnDetailMemory; |
| 200 | readonly messages: ReadonlyArray<string>; |
| 201 | readonly activity: string | null; |
| 202 | } { |
| 203 | const memory: TurnDetailMemory = { |
| 204 | // A step is spoken again after a pause for an approval or a question. |
| 205 | activity: next.status === "working" ? next.activity : null, |
| 206 | messages: new Map(next.messages.map((message) => [message.id, message.finished])), |
| 207 | tailId: next.tailId, |
| 208 | }; |
| 209 | // A turn that already ended is history, however late its entries arrive. |
| 210 | if (previous === null || next.level === "status" || next.status === "idle") { |
| 211 | return { memory, messages: [], activity: null }; |
| 212 | } |
| 213 | return { |
| 214 | memory, |
| 215 | messages: next.messages |
| 216 | .filter( |
| 217 | (message) => |
| 218 | message.finished && |
| 219 | previous.messages.get(message.id) !== true && |
| 220 | (message.fresh || previous.messages.has(message.id)), |
| 221 | ) |
| 222 | .map((message) => { |
| 223 | const cut = cutText(message.text, MESSAGE_MAX_LENGTH); |
| 224 | return cut === null |
| 225 | ? markdownPlainText(message.text) |
| 226 | : m(msg("{text} More in the thread.", { text: markdownPlainText(cut) })); |
| 227 | }) |
| 228 | .filter((text) => text !== "") |
| 229 | .map((text) => `${MESSAGE_AUTHOR}: ${text}`), |
| 230 | activity: |
| 231 | next.level === "everything" && memory.activity !== previous.activity ? memory.activity : null, |
| 232 | }; |
| 233 | } |