@devries-cameron20 / t3code-1 / commits / eb1510d249
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(web): screen readers hear when the open thread starts, needs you or finishes (#23752)

Co-authored-by: PR Batch Tester <agent@local.test> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

shivam committed Oct 23, 2026 at 17:48 UTC eb1510d2493cbf28600432d5193cc22a1af8f3d8
6 files changed +603 -97
apps/web/src/components/ChatView.tsx
+27 -5
@@ -1,5 +1,6 @@
1 import { ScrollToEndButton, WorkspaceFileDropOverlay } from "./chat/TimelineOverlays";
2 import { usePasteToFocusComposer } from "./chat/usePasteToFocusComposer";
3 +import { announcedRun, isDetailBehindShell } from "./chat/threadActivityAnnouncement";
4 import {
5 deriveAvailableRevertTurnCounts,
6 deriveThreadPendingBackgroundTasks,
@@ -3275,11 +3276,22 @@ export default function ChatView(props: ChatViewProps) {
3276 }
3277 isCompacting={!paintOnlyDisplayedTimeline && isCompacting}
3278 awaitingUser={
3278 - !paintOnlyDisplayedTimeline &&
3279 - (activePendingApproval !== null ||
3280 - activePendingUserInput !== null ||
3281 - // A secret request has no runtime request; the shell carries it.
3282 - activeThreadShell?.hasPendingUserInput === true)
3279 + paintOnlyDisplayedTimeline
3280 + ? null
3281 + : activePendingApproval !== null
3282 + ? "approval"
3283 + : activePendingUserInput !== null ||
3284 + // A secret request has no runtime request; the shell carries it.
3285 + activeThreadShell?.hasPendingUserInput === true
3286 + ? "input"
3287 + : null
3288 + }
3289 + awaitingRequestId={
3290 + paintOnlyDisplayedTimeline
3291 + ? null
3292 + : (activePendingApproval?.requestId ??
3293 + activePendingUserInput?.requestId ??
3294 + null)
3295 }
3296 activeTurnStartedAt={paintOnlyDisplayedTimeline ? null : activeWorkStartedAt}
3297 worktreeSetup={paintOnlyDisplayedTimeline ? null : worktreeSetup}
@@ -3315,6 +3327,15 @@ export default function ChatView(props: ChatViewProps) {
3327 listRef={legendListRef}
3328 runs={paintOnlyDisplayedTimeline ? [] : (serverProjection?.runs ?? [])}
3329 latestRun={paintOnlyDisplayedTimeline ? null : activeActivityRun}
3330 + announcedRun={
3331 + paintOnlyDisplayedTimeline
3332 + ? null
3333 + : announcedRun(activeActivityRun, serverProjection?.runs ?? [])
3334 + }
3335 + detailBehindShell={
3336 + !paintOnlyDisplayedTimeline &&
3337 + isDetailBehindShell(activeLatestRun, activeThreadShell?.latestRun ?? null)
3338 + }
3339 runningRunId={paintOnlyDisplayedTimeline ? null : activeRunningTurnId}
3340 turnDiffSummaries={
3341 paintOnlyDisplayedTimeline ? EMPTY_HELD_TURN_DIFF_SUMMARIES : turnDiffSummaries
@@ -3325,6 +3346,7 @@ export default function ChatView(props: ChatViewProps) {
3346 routeThreadKey={displayedTimelineKey}
3347 displayThreadKey={displayedTimelineKey}
3348 paintOnly={paintOnlyDisplayedTimeline}
3349 + announceTurnStatus={!isProviderSubagent}
3350 onOpenTurnDiff={
3351 paintOnlyDisplayedTimeline ? noopHeldTurnDiff : onOpenTurnDiffStable
3352 }
apps/web/src/components/chat/MessagesTimeline.tsx
+126 -90
@@ -112,6 +112,7 @@ import {
112 import { V2EventTimelineRow } from "./TimelineV2EventRow";
113 import { useTimelinePositionRestore } from "./useTimelinePositionRestore";
114 import { useThreadFindPositionReader } from "./useThreadFindPositionReader";
115 +import { ThreadActivityAnnouncer } from "./ThreadActivityAnnouncer";
116 import { useStableHandoffRuns, useIncrementalTimelineRows, useStableRows } from "./useTimelineRows";
117
118 function timelineListStateFor(identity: string): {
@@ -192,17 +193,25 @@ interface MessagesTimelineProps {
193 onOpenWorktreeSetupTerminal?: (terminalId: string) => void;
194 isPreparingWorktree?: boolean;
195 isCompacting?: boolean;
195 - awaitingUser?: boolean;
196 + awaitingUser?: "approval" | "input" | null;
197 + /** Which request is waiting, so a second one of the same kind is announced too. */
198 + awaitingRequestId?: string | null;
199 footer?: ReactNode;
200
201 listRef: React.RefObject<LegendListRef | null>;
202 timelineEntries: ReadonlyArray<TimelineEntry>;
203 latestRun: TimelineLatestRun | null;
204 + /** The run the screen reader announcer follows; see announcedRun. */
205 + announcedRun?: { readonly runId: RunId; readonly status: TimelineLatestRun["status"] } | null;
206 + /** See isDetailBehindShell. */
207 + detailBehindShell?: boolean;
208 runningRunId?: RunId | null;
209 turnDiffSummaries: ReadonlyArray<TurnDiffSummary>;
210 routeThreadKey: string;
211 displayThreadKey?: string;
212 paintOnly?: boolean;
213 + /** Off where another region already speaks the thread's status, like a subagent's bar. */
214 + announceTurnStatus?: boolean;
215 onOpenTurnDiff: (runId: RunId, filePath?: string) => void;
216 onOpenThread: (threadId: OrchestrationV2TurnItem["threadId"]) => void;
217 parentThreadLink?: {
@@ -299,7 +308,8 @@ const ConversationTimeline = memo(function ConversationTimeline({
308 onOpenWorktreeSetupTerminal,
309 isPreparingWorktree = false,
310 isCompacting = false,
302 - awaitingUser = false,
311 + awaitingUser = null,
312 + awaitingRequestId = null,
313 listRef,
314 timelineEntries,
315 findExpanded = false,
@@ -308,11 +318,14 @@ const ConversationTimeline = memo(function ConversationTimeline({
318 findNavigationId = 0,
319 findPositionReaderRef,
320 latestRun,
321 + announcedRun = null,
322 + detailBehindShell = false,
323 runningRunId = null,
324 turnDiffSummaries,
325 routeThreadKey,
326 displayThreadKey,
327 paintOnly = false,
328 + announceTurnStatus = true,
329 onOpenTurnDiff,
330 onOpenThread,
331 parentThreadLink = null,
@@ -947,10 +960,22 @@ const ConversationTimeline = memo(function ConversationTimeline({
960 isRevertingCheckpoint,
961 backgroundWorktreeSetup,
962 activeTurnInProgress,
950 - awaitingUser,
963 + awaitingUser: awaitingUser !== null,
964 isPreparingWorktree,
965 latestRunId: latestRun?.runId ?? null,
966 };
967 + // Mounted in both the empty and filled timeline so a thread's first turn
968 + // starts from a baseline instead of a fresh, silent region.
969 + const activityAnnouncer = (
970 + <ThreadActivityAnnouncer
971 + threadKey={paintOnly || !announceTurnStatus ? null : listIdentityKey}
972 + status={awaitingUser ?? (isWorking ? "working" : "idle")}
973 + requestId={awaitingRequestId}
974 + runId={announcedRun?.runId ?? null}
975 + runStatus={announcedRun?.status ?? null}
976 + detailBehind={detailBehindShell}
977 + />
978 + );
979 const listHeaderLeadingContent =
980 parentThreadLink === null ? (
981 topFadeEnabled ? (
@@ -1044,100 +1069,111 @@ const ConversationTimeline = memo(function ConversationTimeline({
1069 footer === null
1070 ) {
1071 if (hideEmptyPlaceholder) {
1047 - return <div className="h-full min-h-0 bg-background" data-timeline-loading="true" />;
1072 + return (
1073 + <>
1074 + {activityAnnouncer}
1075 + <div className="h-full min-h-0 bg-background" data-timeline-loading="true" />
1076 + </>
1077 + );
1078 }
1079 return (
1050 - <div
1051 - className="flex h-full items-center justify-center ps-(--chat-lane-inset-start) pe-(--chat-lane-inset-end)"
1052 - style={{ paddingBottom: emptyPlaceholderInset }}
1053 - >
1054 - <p className="text-sm text-muted-foreground/30">
1055 - Send a message to start the conversation.
1056 - </p>
1057 - </div>
1080 + <>
1081 + {activityAnnouncer}
1082 + <div
1083 + className="flex h-full items-center justify-center ps-(--chat-lane-inset-start) pe-(--chat-lane-inset-end)"
1084 + style={{ paddingBottom: emptyPlaceholderInset }}
1085 + >
1086 + <p className="text-sm text-muted-foreground/30">
1087 + Send a message to start the conversation.
1088 + </p>
1089 + </div>
1090 + </>
1091 );
1092 }
1093
1094 return (
1062 - <MarkdownFindContext value={findActive}>
1063 - <TimelineRowActivityCtx value={activityState}>
1064 - <TooltipScrollDismissArea
1065 - ref={setTimelineViewportElement}
1066 - className="relative h-full min-h-0"
1067 - data-assistant-citation-viewport="true"
1068 - >
1069 - {onCiteAssistantText && citationThreadRef ? (
1070 - <AssistantSelectionToolbar
1071 - viewport={timelineViewportElement}
1072 - threadRef={citationThreadRef}
1073 - onCite={onCiteAssistantText}
1095 + <>
1096 + {activityAnnouncer}
1097 + <MarkdownFindContext value={findActive}>
1098 + <TimelineRowActivityCtx value={activityState}>
1099 + <TooltipScrollDismissArea
1100 + ref={setTimelineViewportElement}
1101 + className="relative h-full min-h-0"
1102 + data-assistant-citation-viewport="true"
1103 + >
1104 + {onCiteAssistantText && citationThreadRef ? (
1105 + <AssistantSelectionToolbar
1106 + viewport={timelineViewportElement}
1107 + threadRef={citationThreadRef}
1108 + onCite={onCiteAssistantText}
1109 + />
1110 + ) : null}
1111 + <LegendList<MessagesTimelineRow>
1112 + ref={setTimelineList}
1113 + data={rows}
1114 + extraData={listExtraData}
1115 + keyExtractor={keyExtractor}
1116 + getItemType={getItemType}
1117 + renderItem={renderItem}
1118 + estimatedItemSize={90}
1119 + initialScrollAtEnd={
1120 + !findActive && citationRequest === null && rememberedPosition?.atEnd !== false
1121 + }
1122 + // Legend needs a data refresh to mount new pins without a scroll event.
1123 + dataVersion={readyCitationRequest?.key ?? listIdentityKey}
1124 + {...(alwaysRender ? { alwaysRender } : {})}
1125 + onLoad={handleListLoad}
1126 + {...(anchoredEndSpace ? { anchoredEndSpace } : {})}
1127 + contentInsetEndAdjustment={anchoredEndSpace ? contentInsetEndAdjustment : 0}
1128 + maintainScrollAtEnd={
1129 + citationPositioning ||
1130 + (restoringThreadPosition && rememberedPosition?.atEnd === false) ||
1131 + anchoredEndSpace ||
1132 + !liveFollowEnabled ||
1133 + fullscreenAppRowId !== null ||
1134 + disclosureToggleSettling
1135 + ? false
1136 + : isWorking && !prefersReducedMotion && settlingListIdentity === null
1137 + ? TIMELINE_MAINTAIN_SCROLL_AT_END_SMOOTH
1138 + : TIMELINE_MAINTAIN_SCROLL_AT_END
1139 + }
1140 + maintainVisibleContentPosition={
1141 + findActive ||
1142 + citationPositioning ||
1143 + (restoringThreadPosition && rememberedPosition?.atEnd === false)
1144 + ? false
1145 + : maintainVisibleContentPosition
1146 + }
1147 + maintainScrollAtEndThreshold={1}
1148 + onScroll={handleScroll}
1149 + onItemSizeChanged={handleItemSizeChanged}
1150 + className={cn(
1151 + "messages-timeline-scroll scrollbar-gutter-both h-full min-h-0 overflow-x-hidden overscroll-y-contain [overflow-anchor:none]",
1152 + topFadeEnabled && "topbar-scroll-fade",
1153 + )}
1154 + ListHeaderComponent={listHeader}
1155 + ListFooterComponent={timelineListFooter}
1156 />
1075 - ) : null}
1076 - <LegendList<MessagesTimelineRow>
1077 - ref={setTimelineList}
1078 - data={rows}
1079 - extraData={listExtraData}
1080 - keyExtractor={keyExtractor}
1081 - getItemType={getItemType}
1082 - renderItem={renderItem}
1083 - estimatedItemSize={90}
1084 - initialScrollAtEnd={
1085 - !findActive && citationRequest === null && rememberedPosition?.atEnd !== false
1086 - }
1087 - // Legend needs a data refresh to mount new pins without a scroll event.
1088 - dataVersion={readyCitationRequest?.key ?? listIdentityKey}
1089 - {...(alwaysRender ? { alwaysRender } : {})}
1090 - onLoad={handleListLoad}
1091 - {...(anchoredEndSpace ? { anchoredEndSpace } : {})}
1092 - contentInsetEndAdjustment={anchoredEndSpace ? contentInsetEndAdjustment : 0}
1093 - maintainScrollAtEnd={
1094 - citationPositioning ||
1095 - (restoringThreadPosition && rememberedPosition?.atEnd === false) ||
1096 - anchoredEndSpace ||
1097 - !liveFollowEnabled ||
1098 - fullscreenAppRowId !== null ||
1099 - disclosureToggleSettling
1100 - ? false
1101 - : isWorking && !prefersReducedMotion && settlingListIdentity === null
1102 - ? TIMELINE_MAINTAIN_SCROLL_AT_END_SMOOTH
1103 - : TIMELINE_MAINTAIN_SCROLL_AT_END
1104 - }
1105 - maintainVisibleContentPosition={
1106 - findActive ||
1107 - citationPositioning ||
1108 - (restoringThreadPosition && rememberedPosition?.atEnd === false)
1109 - ? false
1110 - : maintainVisibleContentPosition
1111 - }
1112 - maintainScrollAtEndThreshold={1}
1113 - onScroll={handleScroll}
1114 - onItemSizeChanged={handleItemSizeChanged}
1115 - className={cn(
1116 - "messages-timeline-scroll scrollbar-gutter-both h-full min-h-0 overflow-x-hidden overscroll-y-contain [overflow-anchor:none]",
1117 - topFadeEnabled && "topbar-scroll-fade",
1118 - )}
1119 - ListHeaderComponent={listHeader}
1120 - ListFooterComponent={timelineListFooter}
1121 - />
1122 - <TimelineMinimap
1123 - items={minimapItems}
1124 - hasPersistentGutter={minimapHasPersistentGutter}
1125 - hitStripWidth={minimapHitStripWidth}
1126 - currentIndex={minimapCurrentIndex}
1127 - stripMap={minimapStripMap}
1128 - onWheel={forwardMinimapWheel}
1129 - onSelect={(item) => {
1130 - onManualNavigation();
1131 - void listRef.current?.scrollToIndex({
1132 - index: item.rowIndex,
1133 - animated: !window.matchMedia("(prefers-reduced-motion: reduce)").matches,
1134 - viewOffset: 24,
1135 - });
1136 - }}
1137 - />
1138 - </TooltipScrollDismissArea>
1139 - </TimelineRowActivityCtx>
1140 - </MarkdownFindContext>
1157 + <TimelineMinimap
1158 + items={minimapItems}
1159 + hasPersistentGutter={minimapHasPersistentGutter}
1160 + hitStripWidth={minimapHitStripWidth}
1161 + currentIndex={minimapCurrentIndex}
1162 + stripMap={minimapStripMap}
1163 + onWheel={forwardMinimapWheel}
1164 + onSelect={(item) => {
1165 + onManualNavigation();
1166 + void listRef.current?.scrollToIndex({
1167 + index: item.rowIndex,
1168 + animated: !window.matchMedia("(prefers-reduced-motion: reduce)").matches,
1169 + viewOffset: 24,
1170 + });
1171 + }}
1172 + />
1173 + </TooltipScrollDismissArea>
1174 + </TimelineRowActivityCtx>
1175 + </MarkdownFindContext>
1176 + </>
1177 );
1178 });
1179
apps/web/src/components/chat/ThreadActivityAnnouncer.tsx new
+57
@@ -0,0 +1,57 @@
1 +import { memo, useEffect, useRef } from "react";
2 +
3 +import {
4 + nextThreadAnnouncement,
5 + type ThreadActivitySnapshot,
6 + type ThreadAnnouncementMemory,
7 +} from "./threadActivityAnnouncement";
8 +
9 +/**
10 + * One polite live region for the open thread. Text is written straight to the
11 + * DOM so an announcement never re-renders the timeline.
12 + */
13 +export const ThreadActivityAnnouncer = memo(function ThreadActivityAnnouncer({
14 + threadKey,
15 + status,
16 + requestId,
17 + runId,
18 + runStatus,
19 + detailBehind,
20 +}: ThreadActivitySnapshot & {
21 + /** Null while the timeline shows another thread during a switch. */
22 + readonly threadKey: string | null;
23 + /** See isDetailBehindShell. */
24 + readonly detailBehind: boolean;
25 +}) {
26 + const regionRef = useRef<HTMLDivElement>(null);
27 + const memoryRef = useRef<{ threadKey: string; memory: ThreadAnnouncementMemory } | null>(null);
28 +
29 + useEffect(() => {
30 + const region = regionRef.current;
31 + if (threadKey === null) {
32 + memoryRef.current = null;
33 + if (region !== null) region.textContent = "";
34 + return;
35 + }
36 + if (detailBehind) return;
37 + const previous = memoryRef.current?.threadKey === threadKey ? memoryRef.current.memory : null;
38 + const { memory, announcement } = nextThreadAnnouncement(previous, {
39 + status,
40 + requestId,
41 + runId,
42 + runStatus,
43 + });
44 + memoryRef.current = { threadKey, memory };
45 + if (region === null) return;
46 + if (previous === null) {
47 + region.textContent = "";
48 + } else if (announcement !== null) {
49 + // Screen readers ignore a write that leaves the text unchanged, so a
50 + // repeated "Done" gets a trailing non-breaking space to count as new.
51 + region.textContent = region.textContent === announcement ? `${announcement} ` : announcement;
52 + }
53 + }, [threadKey, status, requestId, runId, runStatus, detailBehind]);
54 +
55 + // No role="status": Orca 50 maps it to a status bar in Chromium and drops its updates.
56 + return <div ref={regionRef} aria-live="polite" className="sr-only" />;
57 +});
apps/web/src/components/chat/threadActivityAnnouncement.test.ts new
+221
@@ -0,0 +1,221 @@
1 +import {
2 + MessageId,
3 + type OrchestrationV2Run,
4 + ProviderInstanceId,
5 + RunId,
6 + ThreadId,
7 +} from "@t3tools/contracts";
8 +import * as DateTime from "effect/DateTime";
9 +import { describe, expect, it } from "vite-plus/test";
10 +
11 +import {
12 + announcedRun,
13 + nextThreadAnnouncement,
14 + type ThreadActivitySnapshot,
15 + type ThreadAnnouncementMemory,
16 +} from "./threadActivityAnnouncement";
17 +
18 +const firstRun = RunId.make("run-1");
19 +const secondRun = RunId.make("run-2");
20 +
21 +const idle = (
22 + runId: RunId | null,
23 + runStatus: ThreadActivitySnapshot["runStatus"],
24 +): ThreadActivitySnapshot => ({ status: "idle", requestId: null, runId, runStatus });
25 +const busy = (
26 + status: Exclude<ThreadActivitySnapshot["status"], "idle"> = "working",
27 + runId: RunId | null = secondRun,
28 + runStatus: ThreadActivitySnapshot["runStatus"] = "running",
29 + requestId: string | null = status === "working" ? null : "request-1",
30 +): ThreadActivitySnapshot => ({ status, requestId, runId, runStatus });
31 +
32 +function speak(snapshots: ReadonlyArray<ThreadActivitySnapshot>) {
33 + let memory: ThreadAnnouncementMemory | null = null;
34 + const spoken: string[] = [];
35 + for (const snapshot of snapshots) {
36 + const result = nextThreadAnnouncement(memory, snapshot);
37 + memory = result.memory;
38 + if (result.announcement !== null) spoken.push(result.announcement);
39 + }
40 + return spoken;
41 +}
42 +
43 +describe("nextThreadAnnouncement", () => {
44 + it("follows a turn from start to finish", () => {
45 + expect(
46 + speak([idle(firstRun, "completed"), busy(), busy(), idle(secondRun, "completed")]),
47 + ).toEqual(["Working", "Done"]);
48 + });
49 +
50 + it("says Working once when a send looks idle before its run appears", () => {
51 + expect(
52 + speak([idle(null, null), busy(), idle(null, null), busy(), idle(secondRun, "completed")]),
53 + ).toEqual(["Working", "Done"]);
54 + });
55 +
56 + it("announces a queued message that starts as the last turn ends", () => {
57 + const thirdRun = RunId.make("run-3");
58 + expect(
59 + speak([
60 + idle(firstRun, "completed"),
61 + busy("working", firstRun, "completed"),
62 + busy(),
63 + busy("working", secondRun, "completed"),
64 + busy("working", thirdRun, "starting"),
65 + idle(thirdRun, "completed"),
66 + ]),
67 + ).toEqual(["Working", "Working", "Done"]);
68 + // The last turn's run is still settling when the follow-up is sent.
69 + expect(
70 + speak([
71 + idle(firstRun, "running"),
72 + busy("working", firstRun, "running"),
73 + busy("working", secondRun, "starting"),
74 + ]),
75 + ).toEqual(["Working"]);
76 + expect(
77 + speak([
78 + idle(firstRun, "running"),
79 + busy("working", firstRun, "running"),
80 + idle(firstRun, "completed"),
81 + busy("working", secondRun, "starting"),
82 + idle(secondRun, "completed"),
83 + ]),
84 + ).toEqual(["Working", "Done"]);
85 + expect(
86 + speak([
87 + busy("working", firstRun, "running"),
88 + idle(firstRun, "running"),
89 + busy("working", firstRun, "running"),
90 + busy("working", secondRun, "starting"),
91 + ]),
92 + ).toEqual(["Working"]);
93 + });
94 +
95 + it("treats a run that starts while the thread looks idle as the next turn", () => {
96 + const thirdRun = RunId.make("run-3");
97 + // A resume or a turn started from another device.
98 + expect(
99 + speak([
100 + idle(firstRun, "completed"),
101 + idle(secondRun, "starting"),
102 + busy("working", secondRun, "running"),
103 + idle(secondRun, "completed"),
104 + ]),
105 + ).toEqual(["Working", "Done"]);
106 + // A queued message waiting to start after the last turn.
107 + expect(
108 + speak([
109 + idle(firstRun, "completed"),
110 + busy(),
111 + idle(thirdRun, "queued"),
112 + idle(thirdRun, "starting"),
113 + busy("working", thirdRun, "running"),
114 + idle(thirdRun, "completed"),
115 + ]),
116 + ).toEqual(["Working", "Working", "Done"]);
117 + });
118 +
119 + it("stays silent when a thread opens mid-turn or after one", () => {
120 + expect(speak([idle(firstRun, "completed"), idle(firstRun, "completed")])).toEqual([]);
121 + expect(speak([busy(), busy()])).toEqual([]);
122 + });
123 +
124 + it("announces the end of a turn that was already running when the thread opened", () => {
125 + expect(speak([busy(), idle(secondRun, "failed")])).toEqual(["Failed"]);
126 + });
127 +
128 + it("says how the turn ended when a queued message was cancelled before it started", () => {
129 + const now = DateTime.makeUnsafe("2026-06-20T00:00:00.000Z");
130 + const run = (id: RunId, ordinal: number, status: OrchestrationV2Run["status"]) =>
131 + ({
132 + id,
133 + threadId: ThreadId.make("thread-1"),
134 + ordinal,
135 + providerInstanceId: ProviderInstanceId.make("codex"),
136 + modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
137 + providerThreadId: null,
138 + userMessageId: MessageId.make(`message-${ordinal}`),
139 + rootNodeId: null,
140 + activeAttemptId: null,
141 + status,
142 + requestedAt: now,
143 + startedAt: status === "cancelled" ? null : now,
144 + completedAt: now,
145 + checkpointId: null,
146 + contextHandoffId: null,
147 + }) satisfies OrchestrationV2Run;
148 + const cancelledRun = RunId.make("run-3");
149 + const ended = announcedRun({ runId: cancelledRun, status: "cancelled", startedAt: null }, [
150 + run(secondRun, 1, "completed"),
151 + run(cancelledRun, 2, "cancelled"),
152 + ]);
153 + expect(speak([busy(), idle(ended?.runId ?? null, ended?.status ?? null)])).toEqual(["Done"]);
154 + });
155 +
156 + it("waits for the run to settle before announcing how the turn ended", () => {
157 + expect(
158 + speak([
159 + idle(firstRun, "completed"),
160 + busy(),
161 + idle(secondRun, "running"),
162 + idle(secondRun, "interrupted"),
163 + ]),
164 + ).toEqual(["Working", "Stopped"]);
165 + });
166 +
167 + it("does not report the previous turn's ending when work stops before a new run exists", () => {
168 + expect(
169 + speak([
170 + idle(firstRun, "completed"),
171 + busy("working", firstRun, "completed"),
172 + idle(firstRun, "completed"),
173 + busy(),
174 + idle(secondRun, "completed"),
175 + ]),
176 + ).toEqual(["Working", "Working", "Done"]);
177 + // The previous run finished while this client looked idle.
178 + expect(
179 + speak([
180 + idle(firstRun, "completed"),
181 + idle(secondRun, "completed"),
182 + busy("working", secondRun, "completed"),
183 + idle(secondRun, "completed"),
184 + ]),
185 + ).toEqual(["Working"]);
186 + });
187 +
188 + it("lets the next turn start after one is rolled back", () => {
189 + expect(
190 + speak([
191 + idle(firstRun, "completed"),
192 + busy(),
193 + idle(secondRun, "rolled_back"),
194 + busy("working", RunId.make("run-3")),
195 + ]),
196 + ).toEqual(["Working", "Working"]);
197 + });
198 +
199 + it("announces each request once without repeating that work resumed", () => {
200 + expect(
201 + speak([
202 + busy(),
203 + busy("approval"),
204 + busy("approval"),
205 + busy(),
206 + busy("input"),
207 + idle(secondRun, "completed"),
208 + ]),
209 + ).toEqual(["Needs approval", "Needs your input", "Done"]);
210 + });
211 +
212 + it("announces a second request of the same kind once the first is answered", () => {
213 + expect(
214 + speak([
215 + busy(),
216 + busy("approval", secondRun, "running", "request-1"),
217 + busy("approval", secondRun, "running", "request-2"),
218 + ]),
219 + ).toEqual(["Needs approval", "Needs approval"]);
220 + });
221 +});
apps/web/src/components/chat/threadActivityAnnouncement.ts new
+166
@@ -0,0 +1,166 @@
1 +import type { OrchestrationV2Run, OrchestrationV2RunStatus, RunId } from "@t3tools/contracts";
2 +import { latestExecutedRun } from "@t3tools/shared/orchestrationV2ThreadError";
3 +
4 +export type ThreadActivityStatus = "working" | "approval" | "input" | "idle";
5 +
6 +export interface ThreadActivitySnapshot {
7 + readonly status: ThreadActivityStatus;
8 + /** The pending approval or question, when there is one. */
9 + readonly requestId: string | null;
10 + readonly runId: RunId | null;
11 + readonly runStatus: OrchestrationV2RunStatus | null;
12 +}
13 +
14 +export interface ThreadAnnouncementMemory {
15 + readonly snapshot: ThreadActivitySnapshot;
16 + /**
17 + * The turn under way: the run it belongs to, "unknown" until that run shows
18 + * up, or null between turns. Its ending is announced once, then it clears.
19 + */
20 + readonly turnRunId: RunId | "unknown" | null;
21 + /** The run whose ending is already known, so a stale run is never announced as this turn's. */
22 + readonly settledRunId: RunId | null;
23 + /** The run shown while idle belongs to the last turn, even if it is still settling. */
24 + readonly idleRunId: RunId | null;
25 +}
26 +
27 +const ACTIVE_RUN_STATUSES: ReadonlySet<OrchestrationV2RunStatus | null> = new Set([
28 + "preparing",
29 + "starting",
30 + "running",
31 + "waiting",
32 +]);
33 +
34 +const STARTING_RUN_STATUSES: ReadonlySet<OrchestrationV2RunStatus | null> = new Set([
35 + "queued",
36 + "preparing",
37 + "starting",
38 +]);
39 +
40 +function runOutcomeText(status: OrchestrationV2RunStatus | null): string | null {
41 + switch (status) {
42 + case "completed":
43 + return "Done";
44 + case "failed":
45 + return "Failed";
46 + case "interrupted":
47 + case "cancelled":
48 + return "Stopped";
49 + default:
50 + return null;
51 + }
52 +}
53 +
54 +interface RunState {
55 + readonly runId: RunId;
56 + readonly status: OrchestrationV2RunStatus;
57 +}
58 +
59 +/**
60 + * The thread's detail hasn't caught up with the live thread shell: it isn't
61 + * loaded yet, or a cached copy still shows an older run or state. Reading such
62 + * a frame as the baseline replays what already happened, so it's skipped.
63 + */
64 +export function isDetailBehindShell(detailRun: RunState | null, shellRun: RunState | null) {
65 + return (
66 + shellRun !== null &&
67 + (detailRun?.runId !== shellRun.runId || detailRun.status !== shellRun.status)
68 + );
69 +}
70 +
71 +/**
72 + * A queued message cancelled before it started keeps its place in line, so it
73 + * shows up as the thread's latest run. It never ran, so the turn ended however
74 + * the last run that did ran.
75 + */
76 +export function announcedRun(
77 + activityRun: (RunState & { readonly startedAt: string | null }) | null,
78 + runs: ReadonlyArray<OrchestrationV2Run>,
79 +): RunState | null {
80 + if (activityRun?.status !== "cancelled" || activityRun.startedAt !== null) return activityRun;
81 + const run = latestExecutedRun(runs);
82 + return run === null ? null : { runId: run.id, status: run.status };
83 +}
84 +
85 +/**
86 + * Decides what a screen reader hears when the open thread's turn changes state.
87 + * The first snapshot of a thread is a silent baseline, so opening or switching
88 + * threads never replays what already happened.
89 + */
90 +export function nextThreadAnnouncement(
91 + previous: ThreadAnnouncementMemory | null,
92 + next: ThreadActivitySnapshot,
93 +): { readonly memory: ThreadAnnouncementMemory; readonly announcement: string | null } {
94 + const idle = next.status === "idle";
95 + // A run still starting up while the thread looks idle (a queued message,
96 + // a resume) is the next turn's, not a leftover from the last one.
97 + const idleRunId =
98 + idle && !STARTING_RUN_STATUSES.has(next.runStatus) ? next.runId : (previous?.idleRunId ?? null);
99 + // A run doing new work; the run left over from the last turn doesn't count.
100 + const newRunId =
101 + !idle && ACTIVE_RUN_STATUSES.has(next.runStatus) && next.runId !== idleRunId
102 + ? next.runId
103 + : null;
104 +
105 + if (previous === null) {
106 + return {
107 + memory: {
108 + snapshot: next,
109 + turnRunId: idle ? null : (newRunId ?? "unknown"),
110 + settledRunId: runOutcomeText(next.runStatus) === null ? null : next.runId,
111 + idleRunId,
112 + },
113 + announcement: null,
114 + };
115 + }
116 + const memory = { ...previous, snapshot: next, idleRunId };
117 + const { turnRunId } = previous;
118 +
119 + if (!idle) {
120 + // Sending can look idle for a moment before the server reports the run,
121 + // so a turn is tied to its run as soon as one appears, and only another
122 + // run taking over (a queued message starting) is a new turn.
123 + const turnStarted =
124 + turnRunId === null ||
125 + (newRunId !== null && turnRunId !== "unknown" && newRunId !== turnRunId);
126 + const nextTurnRunId =
127 + turnStarted || turnRunId === "unknown" ? (newRunId ?? "unknown") : turnRunId;
128 + const announcement =
129 + next.status === "approval"
130 + ? previous.snapshot.status === "approval" && previous.snapshot.requestId === next.requestId
131 + ? null
132 + : "Needs approval"
133 + : next.status === "input"
134 + ? previous.snapshot.status === "input" && previous.snapshot.requestId === next.requestId
135 + ? null
136 + : "Needs your input"
137 + : turnStarted
138 + ? "Working"
139 + : null;
140 + return { memory: { ...memory, turnRunId: nextTurnRunId }, announcement };
141 + }
142 +
143 + // Work can stop a moment before the run settles; the ending waits for the run.
144 + const outcome = runOutcomeText(next.runStatus);
145 + if (turnRunId === null) {
146 + // A run that settled unseen is history too, or the next failed send would claim it.
147 + const settledRunId = outcome === null ? previous.settledRunId : next.runId;
148 + return { memory: { ...memory, settledRunId }, announcement: null };
149 + }
150 + if (next.runStatus === "rolled_back") {
151 + return { memory: { ...memory, turnRunId: null, settledRunId: next.runId }, announcement: null };
152 + }
153 + if (outcome === null) return { memory, announcement: null };
154 + // Work stopped without a new run, e.g. a send that failed; the retry is a new turn.
155 + if (next.runId === previous.settledRunId) {
156 + return { memory: { ...memory, turnRunId: null }, announcement: null };
157 + }
158 + // The last turn's run settling while this turn waits for its own run is not this turn's ending.
159 + if (turnRunId === "unknown" && next.runId === previous.idleRunId) {
160 + return { memory: { ...memory, settledRunId: next.runId }, announcement: null };
161 + }
162 + return {
163 + memory: { ...memory, turnRunId: null, settledRunId: next.runId },
164 + announcement: outcome,
165 + };
166 +}
apps/web/src/components/sidebar/SidebarThreadRow.tsx
+6 -2
@@ -1344,8 +1344,12 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
1344 ) : null}
1345 {/* The label alone is the live region: a role="status"
1346 wrapper around the ticking duration would make
1347 - screen readers announce every second. */}
1348 - <span role="status">{topStatus.label}</span>
1347 + screen readers announce every second. The open
1348 + thread announces its own status, so its row stays
1349 + quiet instead of saying everything twice. */}
1350 + <span role={props.isRouteThread ? undefined : "status"}>
1351 + {topStatus.label}
1352 + </span>
1353 {status === "working" ? (
1354 <span aria-hidden>
1355 <WorkingDuration startedAt={resolveWorkingStartedAt(thread)} />