@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 182 lines 6.81 KB
Raw
1 import type { OrchestrationV2Run, OrchestrationV2RunStatus, RunId } from "@t3tools/contracts";
2 import { latestExecutedRun } from "@t3tools/shared/orchestrationV2ThreadError";
3 import { mFallback, msg } from "gt-i18n";
4 import type { MFunctionType } from "gt-i18n/types";
5
6 export type ThreadActivityStatus = "working" | "approval" | "input" | "idle";
7
8 /** Background threads say these too, so a status sounds the same wherever it's heard. */
9 export const THREAD_STATUS_TEXT = {
10 working: msg("Working"),
11 approval: msg("Needs approval"),
12 input: msg("Needs your input"),
13 done: msg("Done"),
14 failed: msg("Failed"),
15 stopped: msg("Stopped"),
16 } as const;
17
18 export interface ThreadActivitySnapshot {
19 readonly status: ThreadActivityStatus;
20 /** The pending approval or question, when there is one. */
21 readonly requestId: string | null;
22 readonly runId: RunId | null;
23 readonly runStatus: OrchestrationV2RunStatus | null;
24 }
25
26 export interface ThreadAnnouncementMemory {
27 readonly snapshot: ThreadActivitySnapshot;
28 /**
29 * The turn under way: the run it belongs to, "unknown" until that run shows
30 * up, or null between turns. Its ending is announced once, then it clears.
31 */
32 readonly turnRunId: RunId | "unknown" | null;
33 /** The run whose ending is already known, so a stale run is never announced as this turn's. */
34 readonly settledRunId: RunId | null;
35 /** The run shown while idle belongs to the last turn, even if it is still settling. */
36 readonly idleRunId: RunId | null;
37 }
38
39 const ACTIVE_RUN_STATUSES: ReadonlySet<OrchestrationV2RunStatus | null> = new Set([
40 "preparing",
41 "starting",
42 "running",
43 "waiting",
44 ]);
45
46 const STARTING_RUN_STATUSES: ReadonlySet<OrchestrationV2RunStatus | null> = new Set([
47 "queued",
48 "preparing",
49 "starting",
50 ]);
51
52 export function runOutcomeText(
53 status: OrchestrationV2RunStatus | null,
54 resolve: MFunctionType = mFallback,
55 ): string | null {
56 switch (status) {
57 case "completed":
58 return resolve(THREAD_STATUS_TEXT.done);
59 case "failed":
60 return resolve(THREAD_STATUS_TEXT.failed);
61 case "interrupted":
62 case "cancelled":
63 return resolve(THREAD_STATUS_TEXT.stopped);
64 default:
65 return null;
66 }
67 }
68
69 interface RunState {
70 readonly runId: RunId;
71 readonly status: OrchestrationV2RunStatus;
72 }
73
74 /**
75 * The thread's detail hasn't caught up with the live thread shell: it isn't
76 * loaded yet, or a cached copy still shows an older run or state. Reading such
77 * a frame as the baseline replays what already happened, so it's skipped.
78 */
79 export function isDetailBehindShell(detailRun: RunState | null, shellRun: RunState | null) {
80 return (
81 shellRun !== null &&
82 (detailRun?.runId !== shellRun.runId || detailRun.status !== shellRun.status)
83 );
84 }
85
86 /**
87 * A queued message cancelled before it started keeps its place in line, so it
88 * shows up as the thread's latest run. It never ran, so the turn ended however
89 * the last run that did ran.
90 */
91 export function announcedRun(
92 activityRun: (RunState & { readonly startedAt: string | null }) | null,
93 runs: ReadonlyArray<OrchestrationV2Run>,
94 ): RunState | null {
95 if (activityRun?.status !== "cancelled" || activityRun.startedAt !== null) return activityRun;
96 const run = latestExecutedRun(runs);
97 return run === null ? null : { runId: run.id, status: run.status };
98 }
99
100 /**
101 * Decides what a screen reader hears when the open thread's turn changes state.
102 * The first snapshot of a thread is a silent baseline, so opening or switching
103 * threads never replays what already happened.
104 */
105 export function nextThreadAnnouncement(
106 previous: ThreadAnnouncementMemory | null,
107 next: ThreadActivitySnapshot,
108 resolve: MFunctionType = mFallback,
109 ): { readonly memory: ThreadAnnouncementMemory; readonly announcement: string | null } {
110 const idle = next.status === "idle";
111 // A run still starting up while the thread looks idle (a queued message,
112 // a resume) is the next turn's, not a leftover from the last one.
113 const idleRunId =
114 idle && !STARTING_RUN_STATUSES.has(next.runStatus) ? next.runId : (previous?.idleRunId ?? null);
115 // A run doing new work; the run left over from the last turn doesn't count.
116 const newRunId =
117 !idle && ACTIVE_RUN_STATUSES.has(next.runStatus) && next.runId !== idleRunId
118 ? next.runId
119 : null;
120
121 if (previous === null) {
122 return {
123 memory: {
124 snapshot: next,
125 turnRunId: idle ? null : (newRunId ?? "unknown"),
126 settledRunId: runOutcomeText(next.runStatus) === null ? null : next.runId,
127 idleRunId,
128 },
129 announcement: null,
130 };
131 }
132 const memory = { ...previous, snapshot: next, idleRunId };
133 const { turnRunId } = previous;
134
135 if (!idle) {
136 // Sending can look idle for a moment before the server reports the run,
137 // so a turn is tied to its run as soon as one appears, and only another
138 // run taking over (a queued message starting) is a new turn.
139 const turnStarted =
140 turnRunId === null ||
141 (newRunId !== null && turnRunId !== "unknown" && newRunId !== turnRunId);
142 const nextTurnRunId =
143 turnStarted || turnRunId === "unknown" ? (newRunId ?? "unknown") : turnRunId;
144 const announcement =
145 next.status === "approval"
146 ? previous.snapshot.status === "approval" && previous.snapshot.requestId === next.requestId
147 ? null
148 : resolve(THREAD_STATUS_TEXT.approval)
149 : next.status === "input"
150 ? previous.snapshot.status === "input" && previous.snapshot.requestId === next.requestId
151 ? null
152 : resolve(THREAD_STATUS_TEXT.input)
153 : turnStarted
154 ? resolve(THREAD_STATUS_TEXT.working)
155 : null;
156 return { memory: { ...memory, turnRunId: nextTurnRunId }, announcement };
157 }
158
159 // Work can stop a moment before the run settles; the ending waits for the run.
160 const outcome = runOutcomeText(next.runStatus, resolve);
161 if (turnRunId === null) {
162 // A run that settled unseen is history too, or the next failed send would claim it.
163 const settledRunId = outcome === null ? previous.settledRunId : next.runId;
164 return { memory: { ...memory, settledRunId }, announcement: null };
165 }
166 if (next.runStatus === "rolled_back") {
167 return { memory: { ...memory, turnRunId: null, settledRunId: next.runId }, announcement: null };
168 }
169 if (outcome === null) return { memory, announcement: null };
170 // Work stopped without a new run, e.g. a send that failed; the retry is a new turn.
171 if (next.runId === previous.settledRunId) {
172 return { memory: { ...memory, turnRunId: null }, announcement: null };
173 }
174 // The last turn's run settling while this turn waits for its own run is not this turn's ending.
175 if (turnRunId === "unknown" && next.runId === previous.idleRunId) {
176 return { memory: { ...memory, settledRunId: next.runId }, announcement: null };
177 }
178 return {
179 memory: { ...memory, turnRunId: null, settledRunId: next.runId },
180 announcement: outcome,
181 };
182 }