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

main
ts 233 lines 9.13 KB
Raw
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 }