1
import { EnvironmentId, ProviderInstanceId, RunId, ThreadId } from "@t3tools/contracts";
2
-import { describe, expect, it } from "vite-plus/test";
2
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
3
4
-import { createInboxReturnTracker, sortWorkingThreadsBySend } from "./threadInbox.ts";
4
+import {
5
+ createInboxReturnTracker,
6
+ isThreadWorking,
7
+ sortInboxThreadsByReturn,
8
+ sortWorkingThreadsBySend,
9
+} from "./threadInbox.ts";
10
11
const environmentId = EnvironmentId.make("environment-1");
12
35
}
36
37
describe("createInboxReturnTracker", () => {
38
+ beforeEach(() => {
39
+ vi.useFakeTimers();
40
+ vi.setSystemTime(10_000);
41
+ });
42
+ afterEach(() => {
43
+ vi.clearAllTimers();
44
+ vi.useRealTimers();
45
+ });
46
it("stamps a thread when it stops working, but never on the first observation", () => {
47
const tracker = createInboxReturnTracker();
48
const first = tracker.observe([thread("a", true), thread("b", false)]);
36
- expect(first(thread("a", true))).toBeUndefined();
37
- expect(first(thread("b", false))).toBeUndefined();
49
+ expect(first.returnedAt(thread("a", true))).toBeUndefined();
50
+ expect(first.returnedAt(thread("b", false))).toBeUndefined();
51
52
+ const held = tracker.observe([thread("a", false), thread("b", false)]);
53
+ vi.advanceTimersByTime(2_000);
54
const second = tracker.observe([thread("a", false), thread("b", false)]);
40
- expect(second(thread("a", false))).toBeDefined();
41
- expect(second(thread("b", false))).toBeUndefined();
42
- expect(tracker.returnedAt(thread("a", false))).toBe(second(thread("a", false)));
55
+ expect(second.returnedAt(thread("a", false))).toBeDefined();
56
+ expect(second.returnedAt(thread("b", false))).toBeUndefined();
57
+ expect(tracker.returnedAt(thread("a", false))).toBe(second.returnedAt(thread("a", false)));
58
// An earlier observation keeps its answer, so lists built from it stay valid.
44
- expect(first(thread("a", false))).toBeUndefined();
59
+ expect(held.isWorking(thread("a", false))).toBe(true);
60
+ expect(held.returnedAt(thread("a", false))).toBeUndefined();
61
+ });
62
+
63
+ it("holds only placement, then expires and notifies without another shell event", () => {
64
+ const tracker = createInboxReturnTracker();
65
+ const notify = vi.fn();
66
+ const unsubscribe = tracker.subscribe(notify);
67
+ tracker.observe([thread("a", true)]);
68
+ tracker.observe([thread("a", false)]);
69
+ expect(isThreadWorking(thread("a", false))).toBe(false);
70
+ expect(tracker.isWorking(thread("a", false))).toBe(true);
71
+ vi.advanceTimersByTime(1_999);
72
+ tracker.observe([thread("a", false)]);
73
+ expect(tracker.isWorking(thread("a", false))).toBe(true);
74
+ expect(tracker.returnedAt(thread("a", false))).toBeUndefined();
75
+ vi.advanceTimersByTime(1);
76
+ expect(tracker.isWorking(thread("a", false))).toBe(false);
77
+ expect(tracker.returnedAt(thread("a", false))).toBe(12_000);
78
+ expect(notify).toHaveBeenCalledTimes(1);
79
+ unsubscribe();
80
+ });
81
+
82
+ it("cancels a transient return on resume and grants a fresh grace after the next finish", () => {
83
+ const tracker = createInboxReturnTracker();
84
+ tracker.observe([thread("a", false)]);
85
+ expect(tracker.isWorking(thread("a", false))).toBe(false);
86
+ tracker.observe([thread("a", true)]);
87
+ expect(tracker.isWorking(thread("a", true))).toBe(true);
88
+ tracker.observe([thread("a", false)]);
89
+ vi.advanceTimersByTime(1_500);
90
+ tracker.observe([thread("a", true)]);
91
+ vi.advanceTimersByTime(1_000);
92
+ expect(tracker.returnedAt(thread("a", true))).toBeUndefined();
93
+ tracker.observe([thread("a", false)]);
94
+ vi.advanceTimersByTime(1_999);
95
+ expect(tracker.isWorking(thread("a", false))).toBe(true);
96
+ vi.advanceTimersByTime(1);
97
+ expect(tracker.returnedAt(thread("a", false))).toBe(14_500);
98
+ });
99
+
100
+ it.each([
101
+ { hasPendingApprovals: true },
102
+ { hasPendingUserInput: true },
103
+ { pendingSubagentRequest: "approval" as const },
104
+ { pendingSubagentRequest: "user_input" as const },
105
+ { pendingGuestMessageCount: 1 },
106
+ { interactionMode: "plan" as const, hasActionableProposedPlan: true },
107
+ { runtime: { ...thread("a", true).runtime!, status: "failed" as const, lastError: "failed" } },
108
+ { pinnedAt: "2026-06-01T00:00:01Z" },
109
+ { settledOverride: "settled" as const },
110
+ { snoozedUntil: "2026-06-02T00:00:00Z" },
111
+ { activeOrderKey: "manual-order" },
112
+ ])("ends a grace immediately for attention or manual placement: %j", (change) => {
113
+ const tracker = createInboxReturnTracker();
114
+ tracker.observe([thread("a", true)]);
115
+ tracker.observe([thread("a", false)]);
116
+ tracker.observe([{ ...thread("a", false), ...change }]);
117
+ expect(tracker.isWorking(thread("a", false))).toBe(false);
118
+ expect(tracker.returnedAt(thread("a", false))).toBe(10_000);
119
+ expect(vi.getTimerCount()).toBe(0);
120
+ });
121
+
122
+ it.each(["interrupted", "cancelled", "rolled_back"] as const)(
123
+ "holds a %s run, because the server can still settle it",
124
+ (status) => {
125
+ const tracker = createInboxReturnTracker();
126
+ const stopped = {
127
+ ...thread("a", false),
128
+ latestRun: {
129
+ runId: RunId.make("stopped"),
130
+ status,
131
+ requestedAt: null,
132
+ startedAt: null,
133
+ completedAt: null,
134
+ assistantMessageId: null,
135
+ },
136
+ };
137
+ tracker.observe([thread("a", true)]);
138
+ tracker.observe([stopped]);
139
+ expect(tracker.isWorking(stopped)).toBe(true);
140
+ tracker.observe([{ ...stopped, settledOverride: "settled" as const }]);
141
+ expect(tracker.isWorking(stopped)).toBe(false);
142
+ },
143
+ );
144
+
145
+ it("grants grace after a retained expired snooze", () => {
146
+ const tracker = createInboxReturnTracker();
147
+ const retained = {
148
+ snoozedAt: "1970-01-01T00:00:01.000Z",
149
+ snoozedUntil: "1970-01-01T00:00:05.000Z",
150
+ latestRun: {
151
+ runId: RunId.make("completed-wake"),
152
+ status: "completed" as const,
153
+ requestedAt: "1970-01-01T00:00:02.000Z",
154
+ startedAt: "1970-01-01T00:00:02.000Z",
155
+ completedAt: "1970-01-01T00:00:09.000Z",
156
+ assistantMessageId: null,
157
+ },
158
+ };
159
+ const active = { ...thread("a", true), ...retained };
160
+ const finished = { ...thread("a", false), ...retained };
161
+ tracker.observe([active]);
162
+ tracker.observe([finished]);
163
+ expect(tracker.isWorking(finished)).toBe(true);
164
+ expect(tracker.returnedAt(finished)).toBeUndefined();
165
+ vi.advanceTimersByTime(1_999);
166
+ expect(tracker.isWorking(finished)).toBe(true);
167
+ vi.advanceTimersByTime(1);
168
+ expect(tracker.isWorking(finished)).toBe(false);
169
+ expect(tracker.returnedAt(finished)).toBe(12_000);
170
+ });
171
+
172
+ it("does not grant grace to a future snooze after background completion", () => {
173
+ const tracker = createInboxReturnTracker();
174
+ const retained = {
175
+ snoozedAt: "1970-01-01T00:00:01.000Z",
176
+ snoozedUntil: "1970-01-01T00:00:30.000Z",
177
+ };
178
+ tracker.observe([{ ...thread("a", true), ...retained }]);
179
+ const finished = { ...thread("a", false), ...retained };
180
+ tracker.observe([finished]);
181
+ expect(tracker.isWorking(finished)).toBe(false);
182
+ expect(vi.getTimerCount()).toBe(0);
183
+ });
184
+
185
+ it("stamps only stable returns and sorts them in their actual return order", () => {
186
+ const tracker = createInboxReturnTracker();
187
+ const a = { ...thread("a", false), createdAt: "1970-01-01T00:00:00Z" };
188
+ const b = { ...thread("b", false), createdAt: "1970-01-01T00:00:00Z" };
189
+ tracker.observe([thread("a", true), thread("b", true)]);
190
+ tracker.observe([a, thread("b", true)]);
191
+ vi.advanceTimersByTime(500);
192
+ tracker.observe([a, b]);
193
+ vi.advanceTimersByTime(1_500);
194
+ expect(tracker.returnedAt(a)).toBe(12_000);
195
+ expect(tracker.returnedAt(b)).toBeUndefined();
196
+ vi.advanceTimersByTime(500);
197
+ expect(sortInboxThreadsByReturn([a, b], tracker.returnedAt).map((entry) => entry.id)).toEqual([
198
+ "b",
199
+ "a",
200
+ ]);
201
+ });
202
+
203
+ it("cancels pending timers for removed threads and disabled shelves", () => {
204
+ const tracker = createInboxReturnTracker();
205
+ const notify = vi.fn();
206
+ tracker.subscribe(notify);
207
+ tracker.observe([thread("a", true)]);
208
+ tracker.observe([thread("a", false)]);
209
+ tracker.observe([]);
210
+ expect(vi.getTimerCount()).toBe(0);
211
+ tracker.observe([thread("a", true)]);
212
+ tracker.observe([thread("a", false)]);
213
+ tracker.observe(null);
214
+ vi.advanceTimersByTime(2_000);
215
+ expect(notify).not.toHaveBeenCalled();
216
+ expect(tracker.returnedAt(thread("a", false))).toBeUndefined();
217
});
218
});
219