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 22, 15:45 UTC
refactor(client): composers share one workspace snapshot refresh per provider and cwd (#25370)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Oct 26, 2026 at 02:51 UTC
6ea34149bb6ea7657f5905e34085c2bfee3f7f6d
6 files changed
+428
-256
apps/mobile/src/features/threads/use-composer-command-menu.test.ts
+4
-5
@@ -1,7 +1,6 @@
1
import { describe, expect, it, vi } from "vite-plus/test";
2
import { ProviderDriverKind } from "@t3tools/contracts";
3
4
-const refreshProviders = vi.hoisted(() => vi.fn());
4
vi.mock("react-native", () => ({ Alert: { alert: vi.fn() } }));
5
6
vi.mock("../../state/queries", () => ({
@@ -15,10 +14,10 @@ vi.mock("../../state/use-composer-drafts", () => ({
14
}));
15
vi.mock("../../lib/uuid", () => ({ uuidv4: () => "context-id" }));
16
vi.mock("../../state/server", () => ({
18
- serverEnvironment: { refreshProviders: Symbol("refreshProviders") },
19
-}));
20
-vi.mock("../../state/use-atom-command", () => ({
21
- useAtomCommand: () => refreshProviders,
17
+ serverEnvironment: {
18
+ providersValueAtom: vi.fn(),
19
+ refreshProviders: Symbol("refreshProviders"),
20
+ },
21
}));
22
23
import {
apps/mobile/src/features/threads/use-composer-command-menu.ts
+28
-110
@@ -11,10 +11,7 @@ import { matchComposerThreadItems } from "@t3tools/client-runtime/composerThread
11
import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/models";
12
13
const EMPTY_THREAD_SHELLS: ReadonlyArray<EnvironmentThreadShell> = [];
14
-import {
15
- COMPOSER_CONTEXT_MAX_RECORDS,
16
- PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS,
17
-} from "@t3tools/contracts";
14
+import { COMPOSER_CONTEXT_MAX_RECORDS } from "@t3tools/contracts";
15
import { formatComposerContextReference } from "@t3tools/shared/composerContextReferences";
16
import { pullRequestComposerContext, threadComposerContext } from "../../lib/composerContext";
17
import { uuidv4 } from "../../lib/uuid";
@@ -36,20 +33,20 @@ import {
33
scoreQueryMatch,
34
} from "@t3tools/shared/searchRanking";
35
import {
36
+ createProviderWorkspaceSnapshotRefreshAtomFamily,
37
dedupeProviderSkillsByName,
38
getProviderSkillsForSlashMenu,
39
getProviderSlashCommandsForSlashMenu,
40
isProviderSkillUserInvocable,
43
- hasCompleteProviderWorkspaceSnapshot,
44
- hasCurrentProviderWorkspaceSnapshot,
41
resolveProviderSkillsForCwd,
42
resolveProviderSlashCommandsForCwd,
43
} from "@t3tools/client-runtime/providerSkills";
44
+import { useAtomRefresh } from "@effect/atom-react";
45
+import { Atom } from "effect/reactivity";
46
import { useEffect, useRef, useState } from "react";
47
48
import type { ComposerEditorSelection } from "../../components/ComposerEditor";
49
import { serverEnvironment } from "../../state/server";
52
-import { useAtomCommand } from "../../state/use-atom-command";
50
import {
51
useComposerPathSearch,
52
useComposerPullRequestSearch,
@@ -58,9 +55,14 @@ import {
55
import type { ComposerCommandItem } from "./ComposerCommandPopover";
56
import { matchesSlashSkillQuery } from "./composerSlashSkillSearch";
57
61
-const WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS = 10_000;
62
-// A cwd that never scans, such as a deleted worktree, would otherwise retry forever.
63
-const WORKSPACE_SNAPSHOT_MAX_ATTEMPTS = 3;
58
+const providerWorkspaceSnapshotRefresh = createProviderWorkspaceSnapshotRefreshAtomFamily({
59
+ providers: serverEnvironment.providersValueAtom,
60
+ refreshProviders: serverEnvironment.refreshProviders,
61
+});
62
+
63
+const idleWorkspaceSnapshotRefreshAtom: Atom.Atom<unknown> = Atom.make<void>(undefined).pipe(
64
+ Atom.withLabel("mobile:provider-workspace-snapshot-refresh:idle"),
65
+);
66
67
function composerSelectionAtEnd(draftMessage: string): ComposerEditorSelection {
68
return { start: draftMessage.length, end: draftMessage.length };
@@ -214,9 +216,6 @@ export function useComposerCommandMenu({
216
// Thread mentions rank by recency as of when the composer mounted.
217
const [now] = useState(() => Date.now());
218
const previousOwnerKeyRef = useRef(ownerKey);
217
- const onSelectionChange = (nextSelection: ComposerEditorSelection) => {
218
- setSelection(nextSelection);
219
- };
219
useEffect(() => {
220
const inserted = ownerKey ? readComposerDraftSelection(ownerKey, draftMessage) : null;
221
if (inserted) {
@@ -245,109 +244,28 @@ export function useComposerCommandMenu({
244
const skills = selectedProviderStatus
245
? resolveProviderSkillsForCwd(selectedProviderStatus, projectCwd)
246
: [];
248
- const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
249
- reportFailure: false,
250
- });
247
const selectedProviderInstanceId = selectedProviderStatus?.instanceId;
252
- const hasWorkspaceSnapshot = hasCompleteProviderWorkspaceSnapshot(
253
- selectedProviderStatus,
254
- projectCwd,
255
- );
256
- // Record client request time to enforce TTL even when the client clock runs ahead of the server.
257
- const workspaceRefreshKeyRef = useRef<{ key: string; requestedAt: number } | null>(null);
258
- const failedRefreshesRef = useRef<{ key: string; count: number } | null>(null);
259
- const [workspaceRefreshRetry, setWorkspaceRefreshRetry] = useState<{
260
- key: string;
261
- notBefore: number;
262
- } | null>(null);
263
- const workspaceRefreshScopeKey =
248
+ const refreshWorkspaceSnapshot = useAtomRefresh(
249
environmentId && projectCwd && selectedProviderInstanceId
265
- ? `${environmentId}:${selectedProviderInstanceId}:${projectCwd}`
266
- : null;
267
- const workspaceSlashCommandsPending =
268
- selectedProviderStatus?.workspaceSnapshots?.some(
269
- (snapshot) => snapshot.cwd === projectCwd && snapshot.slashCommandsPending === true,
270
- ) ?? false;
271
- useEffect(() => {
272
- if (
273
- !workspaceSlashCommandsPending ||
274
- !workspaceRefreshRetry ||
275
- workspaceRefreshRetry.key !== workspaceRefreshScopeKey
276
- )
277
- return;
278
- const timeout = setTimeout(
279
- () => {
280
- setWorkspaceRefreshRetry((current) => (current === workspaceRefreshRetry ? null : current));
281
- },
282
- Math.max(0, workspaceRefreshRetry.notBefore - Date.now()),
283
- );
284
- return () => clearTimeout(timeout);
285
- }, [workspaceRefreshRetry, workspaceRefreshScopeKey, workspaceSlashCommandsPending]);
286
- const hadWorkspaceSnapshotRef = useRef(false);
287
- useEffect(() => {
288
- if (hadWorkspaceSnapshotRef.current && !hasWorkspaceSnapshot) {
289
- workspaceRefreshKeyRef.current = null;
290
- setWorkspaceRefreshRetry(null);
291
- }
292
- hadWorkspaceSnapshotRef.current = hasWorkspaceSnapshot;
293
- }, [hasWorkspaceSnapshot]);
250
+ ? providerWorkspaceSnapshotRefresh({
251
+ environmentId,
252
+ instanceId: selectedProviderInstanceId,
253
+ cwd: projectCwd,
254
+ })
255
+ : idleWorkspaceSnapshotRefreshAtom,
256
+ );
257
+ // Every draft change rechecks a stale snapshot, including drafts written by
258
+ // another surface (a prompt link) that never move the editor selection.
259
useEffect(() => {
295
- if (!environmentId || !projectCwd || !selectedProviderInstanceId) return;
296
- const key = `${environmentId}:${selectedProviderInstanceId}:${projectCwd}`;
297
- const now = Date.now();
298
- const lastRequest = workspaceRefreshKeyRef.current;
299
- if (
300
- lastRequest?.key === key &&
301
- now - lastRequest.requestedAt < PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS
302
- )
303
- return;
304
- if (hasCurrentProviderWorkspaceSnapshot(selectedProviderStatus, projectCwd, now)) {
305
- // oxlint-disable-next-line react/set-state-in-effect -- A current provider workspace snapshot clears the pending refresh retry.
306
- setWorkspaceRefreshRetry(null);
307
- return;
308
- }
309
- const retry = workspaceRefreshRetry;
310
- if (retry?.key === key && now < retry.notBefore) return;
311
- const request = { key, requestedAt: now };
312
- workspaceRefreshKeyRef.current = request;
313
- const retryLater = () => {
314
- if (workspaceRefreshKeyRef.current !== request) return;
315
- const failed = failedRefreshesRef.current;
316
- const count = failed?.key === key ? failed.count + 1 : 1;
317
- failedRefreshesRef.current = { key, count };
318
- // Keeping the request marker lets the TTL hold off the next scan.
319
- if (count >= WORKSPACE_SNAPSHOT_MAX_ATTEMPTS) return;
320
- workspaceRefreshKeyRef.current = null;
321
- setWorkspaceRefreshRetry({
322
- key,
323
- notBefore: Date.now() + WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS,
324
- });
325
- };
326
- void refreshProviders({
327
- environmentId,
328
- input: { instanceId: selectedProviderInstanceId, cwd: projectCwd },
329
- }).then((result) => {
330
- const refreshed =
331
- result._tag === "Success" &&
332
- hasCompleteProviderWorkspaceSnapshot(
333
- result.value.providers.find(
334
- (provider) => provider.instanceId === selectedProviderInstanceId,
335
- ),
336
- projectCwd,
337
- );
338
- if (!refreshed) retryLater();
339
- else failedRefreshesRef.current = null;
340
- }, retryLater);
260
+ refreshWorkspaceSnapshot();
261
}, [
342
- // oxlint-disable-next-line react/exhaustive-effect-dependencies -- Typing in the draft re-checks whether the provider workspace snapshot needs refreshing.
262
+ // oxlint-disable-next-line react/exhaustive-effect-dependencies -- Draft changes are the recheck signal.
263
draftMessage,
344
- environmentId,
345
- projectCwd,
346
- refreshProviders,
347
- selectedProviderInstanceId,
348
- selectedProviderStatus,
349
- workspaceRefreshRetry,
264
+ refreshWorkspaceSnapshot,
265
]);
266
+ const onSelectionChange = (nextSelection: ComposerEditorSelection) => {
267
+ setSelection(nextSelection);
268
+ };
269
270
const trigger = (() => {
271
if (!enabled || selection.start !== selection.end) {
apps/web/src/components/chat/ChatComposer.tsx
+1
-2
@@ -1006,8 +1006,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
1006
const refreshWorkspaceSnapshotOnTyping = useProviderWorkspaceSnapshotRefresh({
1007
environmentId,
1008
gitCwd,
1009
- selectedProviderEntry,
1010
- selectedProviderStatus: selectedProviderStatus,
1009
+ instanceId: selectedProviderEntry?.instanceId,
1010
});
1011
1012
const selectedPromptEffort = composerProviderState.promptEffort;
apps/web/src/components/chat/useProviderWorkspaceSnapshotRefresh.ts
+22
-136
@@ -1,146 +1,32 @@
1
-import {
2
- type EnvironmentId,
3
- PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS,
4
- type ServerProvider,
5
-} from "@t3tools/contracts";
6
-import { type ProviderInstanceEntry } from "../../providerInstances";
7
-import {
8
- hasCompleteProviderWorkspaceSnapshot,
9
- hasCurrentProviderWorkspaceSnapshot,
10
-} from "@t3tools/client-runtime/providerSkills";
1
+import { useAtomRefresh } from "@effect/atom-react";
2
+import { type EnvironmentId, type ProviderInstanceId } from "@t3tools/contracts";
3
+import { createProviderWorkspaceSnapshotRefreshAtomFamily } from "@t3tools/client-runtime/providerSkills";
4
+import { Atom } from "effect/reactivity";
5
+
6
import { serverEnvironment } from "../../state/server";
12
-import { useAtomCommand } from "../../state/use-atom-command";
13
-import { useEffect, useEffectEvent, useRef, useState } from "react";
14
-import { useStableCallback } from "../../hooks/useStableCallback";
7
16
-const WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS = 10_000;
17
-// A cwd that never scans, such as a deleted worktree, would otherwise retry forever.
18
-const WORKSPACE_SNAPSHOT_MAX_ATTEMPTS = 3;
8
+const providerWorkspaceSnapshotRefresh = createProviderWorkspaceSnapshotRefreshAtomFamily({
9
+ providers: serverEnvironment.providersValueAtom,
10
+ refreshProviders: serverEnvironment.refreshProviders,
11
+});
12
+
13
+const idleRefreshAtom: Atom.Atom<unknown> = Atom.make<void>(undefined).pipe(
14
+ Atom.withLabel("provider-workspace-snapshot-refresh:idle"),
15
+);
16
17
/**
18
* Keeps the selected provider's workspace snapshot fresh for the composer's
22
- * cwd. Returns a check to run when the user types.
19
+ * cwd while mounted. Returns a check to run when the user types.
20
*/
21
export function useProviderWorkspaceSnapshotRefresh(input: {
22
readonly environmentId: EnvironmentId;
23
readonly gitCwd: string | null;
27
- readonly selectedProviderEntry: ProviderInstanceEntry | undefined;
28
- readonly selectedProviderStatus: ServerProvider | null;
29
-}) {
30
- const { environmentId, gitCwd, selectedProviderEntry, selectedProviderStatus } = input;
31
- const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
32
- reportFailure: false,
33
- });
34
- // The last scan this composer asked for. A request inside the TTL is not
35
- // repeated, so a client clock ahead of the server's cannot loop rescans.
36
- const workspaceRefreshKeyRef = useRef<{ key: string; requestedAt: number } | null>(null);
37
- const failedRefreshesRef = useRef<{ key: string; count: number } | null>(null);
38
- const [workspaceRefreshRetry, setWorkspaceRefreshRetry] = useState<{
39
- key: string;
40
- notBefore: number;
41
- } | null>(null);
42
- const workspaceRefreshScopeKey =
43
- gitCwd && selectedProviderEntry
44
- ? `${environmentId}:${selectedProviderEntry.instanceId}:${gitCwd}`
45
- : null;
46
- const workspaceSlashCommandsPending =
47
- selectedProviderStatus?.workspaceSnapshots?.some(
48
- (snapshot) => snapshot.cwd === gitCwd && snapshot.slashCommandsPending === true,
49
- ) ?? false;
50
- useEffect(() => {
51
- if (
52
- !workspaceSlashCommandsPending ||
53
- !workspaceRefreshRetry ||
54
- workspaceRefreshRetry.key !== workspaceRefreshScopeKey
55
- )
56
- return;
57
- const timeout = setTimeout(
58
- () => {
59
- setWorkspaceRefreshRetry((current) => (current === workspaceRefreshRetry ? null : current));
60
- },
61
- Math.max(0, workspaceRefreshRetry.notBefore - Date.now()),
62
- );
63
- return () => clearTimeout(timeout);
64
- }, [workspaceRefreshRetry, workspaceRefreshScopeKey, workspaceSlashCommandsPending]);
65
- // Losing a snapshot (the server dropped it) lifts both the TTL and the retry
66
- // cooldown so the next check rescans at once.
67
- const hasWorkspaceSnapshot = hasCompleteProviderWorkspaceSnapshot(selectedProviderStatus, gitCwd);
68
- const [hadWorkspaceSnapshot, setHadWorkspaceSnapshot] = useState(hasWorkspaceSnapshot);
69
- const [workspaceSnapshotLossCount, setWorkspaceSnapshotLossCount] = useState(0);
70
- if (hadWorkspaceSnapshot !== hasWorkspaceSnapshot) {
71
- setHadWorkspaceSnapshot(hasWorkspaceSnapshot);
72
- if (!hasWorkspaceSnapshot) {
73
- setWorkspaceSnapshotLossCount((count) => count + 1);
74
- setWorkspaceRefreshRetry(null);
75
- }
76
- }
77
- const lastWorkspaceSnapshotLossRef = useRef(workspaceSnapshotLossCount);
78
- const refreshWorkspaceSnapshotIfStale = (
79
- now: number,
80
- key: string | null,
81
- retry: { key: string; notBefore: number } | null,
82
- snapshotLossCount: number,
83
- ) => {
84
- if (lastWorkspaceSnapshotLossRef.current !== snapshotLossCount) {
85
- lastWorkspaceSnapshotLossRef.current = snapshotLossCount;
86
- workspaceRefreshKeyRef.current = null;
87
- }
88
- if (key === null || !gitCwd || !selectedProviderEntry) return;
89
- const lastRequest = workspaceRefreshKeyRef.current;
90
- if (
91
- lastRequest?.key === key &&
92
- now - lastRequest.requestedAt < PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS
93
- )
94
- return;
95
- // A pending retry needs no clearing here: its cooldown lapses long before the TTL.
96
- if (hasCurrentProviderWorkspaceSnapshot(selectedProviderStatus, gitCwd, now)) return;
97
- if (retry?.key === key && now < retry.notBefore) return;
98
- const request = { key, requestedAt: now };
99
- workspaceRefreshKeyRef.current = request;
100
- const retryLater = () => {
101
- if (workspaceRefreshKeyRef.current !== request) return;
102
- const failed = failedRefreshesRef.current;
103
- const count = failed?.key === key ? failed.count + 1 : 1;
104
- failedRefreshesRef.current = { key, count };
105
- // Keeping the request marker lets the TTL hold off the next scan.
106
- if (count >= WORKSPACE_SNAPSHOT_MAX_ATTEMPTS) return;
107
- workspaceRefreshKeyRef.current = null;
108
- setWorkspaceRefreshRetry({
109
- key,
110
- notBefore: Date.now() + WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS,
111
- });
112
- };
113
- void refreshProviders({
114
- environmentId,
115
- input: { instanceId: selectedProviderEntry.instanceId, cwd: gitCwd },
116
- }).then((result) => {
117
- const refreshedSnapshot =
118
- result._tag === "Success" &&
119
- hasCompleteProviderWorkspaceSnapshot(
120
- result.value.providers.find(
121
- (provider) => provider.instanceId === selectedProviderEntry.instanceId,
122
- ),
123
- gitCwd,
124
- );
125
- if (!refreshedSnapshot) retryLater();
126
- else failedRefreshesRef.current = null;
127
- }, retryLater);
128
- };
129
- const refreshWorkspaceSnapshotOnChange = useEffectEvent(refreshWorkspaceSnapshotIfStale);
130
- useEffect(() => {
131
- refreshWorkspaceSnapshotOnChange(
132
- Date.now(),
133
- workspaceRefreshScopeKey,
134
- workspaceRefreshRetry,
135
- workspaceSnapshotLossCount,
136
- );
137
- }, [workspaceRefreshScopeKey, workspaceRefreshRetry, workspaceSnapshotLossCount]);
138
- return useStableCallback(() =>
139
- refreshWorkspaceSnapshotIfStale(
140
- Date.now(),
141
- workspaceRefreshScopeKey,
142
- workspaceRefreshRetry,
143
- workspaceSnapshotLossCount,
144
- ),
145
- );
24
+ readonly instanceId: ProviderInstanceId | undefined;
25
+}): () => void {
26
+ const { environmentId, gitCwd, instanceId } = input;
27
+ const atom =
28
+ gitCwd && instanceId
29
+ ? providerWorkspaceSnapshotRefresh({ environmentId, instanceId, cwd: gitCwd })
30
+ : idleRefreshAtom;
31
+ return useAtomRefresh(atom);
32
}
packages/client-runtime/src/providerSkills.test.ts
+174
-2
@@ -1,7 +1,15 @@
1
-import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
2
-import { describe, expect, it } from "vite-plus/test";
1
+import {
2
+ EnvironmentId,
3
+ ProviderDriverKind,
4
+ ProviderInstanceId,
5
+ type ServerProvider,
6
+} from "@t3tools/contracts";
7
+import * as Cause from "effect/Cause";
8
+import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
9
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
10
11
import {
12
+ createProviderWorkspaceSnapshotRefreshAtomFamily,
13
getProviderSkillsForSlashMenu,
14
hasCompleteProviderWorkspaceSnapshot,
15
resolveProviderSkillsForCwd,
@@ -123,3 +131,167 @@ describe("workspace provider snapshots", () => {
131
expect(hasCompleteProviderWorkspaceSnapshot(provider, null)).toBe(false);
132
});
133
});
134
+
135
+describe("provider workspace snapshot refresh atom", () => {
136
+ afterEach(() => {
137
+ vi.useRealTimers();
138
+ });
139
+
140
+ const cwd = "/workspace/project-a";
141
+ const environmentId = EnvironmentId.make("env");
142
+ const withSnapshot = (
143
+ checkedAt: string,
144
+ slashCommandsPending?: boolean,
145
+ ): ReadonlyArray<ServerProvider> => [
146
+ {
147
+ ...provider,
148
+ workspaceSnapshots: [
149
+ {
150
+ ...provider.workspaceSnapshots[0]!,
151
+ checkedAt,
152
+ ...(slashCommandsPending ? { slashCommandsPending } : {}),
153
+ },
154
+ ],
155
+ },
156
+ ];
157
+ const noSnapshot: ReadonlyArray<ServerProvider> = [{ ...provider, workspaceSnapshots: [] }];
158
+
159
+ type Response = () =>
160
+ | ReadonlyArray<ServerProvider>
161
+ | null
162
+ | Promise<ReadonlyArray<ServerProvider> | null>;
163
+
164
+ function setup(initialProviders: ReadonlyArray<ServerProvider>, initialResponses?: Response[]) {
165
+ const providersAtom = Atom.make<ReadonlyArray<ServerProvider> | null>(initialProviders);
166
+ const responses: Response[] = [...(initialResponses ?? [])];
167
+ const run = vi.fn(async () => {
168
+ const providers = await (responses.shift() ?? (() => null))();
169
+ return providers === null
170
+ ? AsyncResult.failure<{ providers: ReadonlyArray<ServerProvider> }, string>(
171
+ Cause.fail("offline"),
172
+ )
173
+ : AsyncResult.success({ providers });
174
+ });
175
+ const family = createProviderWorkspaceSnapshotRefreshAtomFamily({
176
+ providers: () => providersAtom,
177
+ refreshProviders: { label: "refresh", run },
178
+ });
179
+ const registry = AtomRegistry.make();
180
+ const atom = family({ environmentId, instanceId: provider.instanceId, cwd });
181
+ const unmount = registry.mount(atom);
182
+ return { registry, atom, family, providersAtom, responses, run, unmount };
183
+ }
184
+
185
+ it("scans a missing snapshot once and skips a repeat inside the TTL", async () => {
186
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:00:00.000Z") });
187
+ const { registry, atom, family, responses, run, unmount } = setup(noSnapshot);
188
+ // A second composer on the same target shares the scan.
189
+ registry.mount(family({ environmentId, instanceId: provider.instanceId, cwd }))();
190
+ expect(run).toHaveBeenCalledTimes(1);
191
+ expect(run).toHaveBeenCalledWith(expect.anything(), {
192
+ environmentId,
193
+ input: { instanceId: provider.instanceId, cwd },
194
+ });
195
+ responses.push(() => withSnapshot("2026-01-01T00:00:00.000Z"));
196
+ await vi.advanceTimersByTimeAsync(0);
197
+ registry.refresh(atom);
198
+ expect(run).toHaveBeenCalledTimes(1);
199
+ unmount();
200
+ });
201
+
202
+ it("does not rescan a current snapshot, and rescans once it ages past the TTL", () => {
203
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:01:00.000Z") });
204
+ const { registry, atom, run, unmount } = setup(withSnapshot("2026-01-01T00:00:00.000Z"));
205
+ expect(run).not.toHaveBeenCalled();
206
+ vi.setSystemTime(Date.parse("2026-01-01T00:05:00.000Z"));
207
+ registry.refresh(atom);
208
+ expect(run).toHaveBeenCalledTimes(1);
209
+ unmount();
210
+ });
211
+
212
+ it("cools down a failed scan, then retries on its own while the scan stays pending", async () => {
213
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:00:00.000Z") });
214
+ const { registry, atom, run, unmount } = setup(withSnapshot("2026-01-01T00:00:00.000Z", true));
215
+ expect(run).toHaveBeenCalledTimes(1);
216
+ await vi.advanceTimersByTimeAsync(0);
217
+ registry.refresh(atom);
218
+ expect(run).toHaveBeenCalledTimes(1);
219
+ await vi.advanceTimersByTimeAsync(9_999);
220
+ expect(run).toHaveBeenCalledTimes(1);
221
+ await vi.advanceTimersByTimeAsync(1);
222
+ expect(run).toHaveBeenCalledTimes(2);
223
+ unmount();
224
+ await vi.advanceTimersByTimeAsync(20_000);
225
+ expect(run).toHaveBeenCalledTimes(2);
226
+ expect(vi.getTimerCount()).toBe(0);
227
+ });
228
+
229
+ it("stops retrying after three failed scans until the TTL lapses", async () => {
230
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:00:00.000Z") });
231
+ const { registry, atom, run, unmount } = setup(withSnapshot("2026-01-01T00:00:00.000Z", true));
232
+ await vi.advanceTimersByTimeAsync(60_000);
233
+ expect(run).toHaveBeenCalledTimes(3);
234
+ registry.refresh(atom);
235
+ await vi.advanceTimersByTimeAsync(0);
236
+ expect(run).toHaveBeenCalledTimes(3);
237
+ expect(vi.getTimerCount()).toBe(0);
238
+ vi.setSystemTime(Date.parse("2026-01-01T00:10:00.000Z"));
239
+ registry.refresh(atom);
240
+ expect(run).toHaveBeenCalledTimes(4);
241
+ unmount();
242
+ });
243
+
244
+ it("does not retry on a timer when the failed scan left no pending snapshot", async () => {
245
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:00:00.000Z") });
246
+ const { registry, atom, run, unmount } = setup(noSnapshot);
247
+ await vi.advanceTimersByTimeAsync(10_000);
248
+ expect(run).toHaveBeenCalledTimes(1);
249
+ registry.refresh(atom);
250
+ expect(run).toHaveBeenCalledTimes(2);
251
+ unmount();
252
+ });
253
+
254
+ it("rescans at once when the server drops the snapshot, lifting TTL and cooldown", async () => {
255
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:00:00.000Z") });
256
+ const { registry, providersAtom, run, unmount } = setup(noSnapshot);
257
+ await vi.advanceTimersByTimeAsync(0);
258
+ expect(run).toHaveBeenCalledTimes(1);
259
+ registry.set(providersAtom, withSnapshot("2026-01-01T00:00:00.000Z"));
260
+ expect(run).toHaveBeenCalledTimes(1);
261
+ registry.set(providersAtom, noSnapshot);
262
+ expect(run).toHaveBeenCalledTimes(2);
263
+ unmount();
264
+ });
265
+
266
+ it("does not scan again when a scan fails after the last subscriber left", async () => {
267
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:00:00.000Z") });
268
+ let release = () => {};
269
+ const gate = new Promise<void>((resolve) => {
270
+ release = resolve;
271
+ });
272
+ const { run, unmount } = setup(withSnapshot("2026-01-01T00:00:00.000Z", true), [
273
+ async () => {
274
+ await gate;
275
+ return null;
276
+ },
277
+ ]);
278
+ expect(run).toHaveBeenCalledTimes(1);
279
+ unmount();
280
+ await vi.advanceTimersByTimeAsync(0);
281
+ release();
282
+ await vi.advanceTimersByTimeAsync(20_000);
283
+ expect(run).toHaveBeenCalledTimes(1);
284
+ expect(vi.getTimerCount()).toBe(0);
285
+ });
286
+
287
+ it("ignores provider updates that leave the snapshot status unchanged", () => {
288
+ vi.useFakeTimers({ now: Date.parse("2026-01-01T00:01:00.000Z") });
289
+ const { registry, providersAtom, run, unmount } = setup(
290
+ withSnapshot("2026-01-01T00:00:00.000Z"),
291
+ );
292
+ vi.setSystemTime(Date.parse("2026-01-01T00:06:00.000Z"));
293
+ registry.set(providersAtom, withSnapshot("2026-01-01T00:00:00.000Z"));
294
+ expect(run).not.toHaveBeenCalled();
295
+ unmount();
296
+ });
297
+});
packages/client-runtime/src/providerSkills.ts
+199
-1
@@ -1,9 +1,16 @@
1
import {
2
+ type EnvironmentId,
3
isProviderWorkspaceSnapshotCurrent,
4
+ PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS,
5
+ type ProviderInstanceId,
6
type ServerProvider,
7
type ServerProviderSkill,
8
type ServerProviderSlashCommand,
9
} from "@t3tools/contracts";
10
+import { Atom } from "effect/reactivity";
11
+
12
+import { deadlineStore } from "./clock.ts";
13
+import { type AtomCommand, runAtomCommand } from "./state/runtime.ts";
14
15
export type ProviderSkillSourceKind = "app" | "repo" | "project" | "personal" | "system" | "other";
16
@@ -98,7 +105,7 @@ export function hasCompleteProviderWorkspaceSnapshot(
105
return Boolean(snapshot && !snapshot.slashCommandsPending);
106
}
107
101
-export function hasCurrentProviderWorkspaceSnapshot(
108
+function hasCurrentProviderWorkspaceSnapshot(
109
provider: ServerProvider | null | undefined,
110
cwd: string | null | undefined,
111
nowMs: number,
@@ -124,3 +131,194 @@ export function resolveProviderSlashCommandsForCwd(
131
): ServerProvider["slashCommands"] {
132
return resolveProviderWorkspaceSnapshot(provider, cwd)?.slashCommands ?? provider.slashCommands;
133
}
134
+
135
+const WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS = 10_000;
136
+// A cwd that never scans, such as a deleted worktree, would otherwise retry forever.
137
+const WORKSPACE_SNAPSHOT_MAX_ATTEMPTS = 3;
138
+
139
+interface ProviderWorkspaceSnapshotRefreshState {
140
+ /**
141
+ * When the last scan was requested. A request inside the TTL is not
142
+ * repeated, so a client clock ahead of the server's cannot loop rescans.
143
+ */
144
+ readonly requestedAt: number | null;
145
+ /** A failed scan is not retried before this time. */
146
+ readonly retryNotBefore: number | null;
147
+ /** Scans in a row that ended without a complete snapshot. */
148
+ readonly failedAttempts: number;
149
+ readonly hadSnapshot: boolean;
150
+}
151
+
152
+const initialProviderWorkspaceSnapshotRefreshState: ProviderWorkspaceSnapshotRefreshState = {
153
+ requestedAt: null,
154
+ retryNotBefore: null,
155
+ failedAttempts: 0,
156
+ hadSnapshot: false,
157
+};
158
+
159
+/**
160
+ * Decides whether a composer looking at `cwd` should ask the server to rescan
161
+ * the provider's workspace, and when to look again if a retry is due while the
162
+ * server still reports the scan as pending.
163
+ */
164
+function planProviderWorkspaceSnapshotRefresh(
165
+ previous: ProviderWorkspaceSnapshotRefreshState,
166
+ provider: ServerProvider | null | undefined,
167
+ cwd: string,
168
+ now: number,
169
+): {
170
+ readonly state: ProviderWorkspaceSnapshotRefreshState;
171
+ readonly refresh: boolean;
172
+ readonly recheckAt: number | null;
173
+} {
174
+ const hasSnapshot = hasCompleteProviderWorkspaceSnapshot(provider, cwd);
175
+ // Losing a snapshot (the server dropped it) lifts both the TTL and the retry
176
+ // cooldown so the scan happens at once.
177
+ const lost = previous.hadSnapshot && !hasSnapshot;
178
+ const requestedAt = lost ? null : previous.requestedAt;
179
+ const retryNotBefore =
180
+ lost || (previous.retryNotBefore !== null && now >= previous.retryNotBefore)
181
+ ? null
182
+ : previous.retryNotBefore;
183
+ const state = {
184
+ requestedAt,
185
+ retryNotBefore,
186
+ // A complete snapshot ends the run of failures.
187
+ failedAttempts: hasSnapshot ? 0 : previous.failedAttempts,
188
+ hadSnapshot: hasSnapshot,
189
+ };
190
+ const refresh =
191
+ (requestedAt === null || now - requestedAt >= PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS) &&
192
+ !hasCurrentProviderWorkspaceSnapshot(provider, cwd, now) &&
193
+ retryNotBefore === null;
194
+ if (refresh) {
195
+ return { state: { ...state, requestedAt: now }, refresh: true, recheckAt: null };
196
+ }
197
+ const pending =
198
+ (provider && resolveProviderWorkspaceSnapshot(provider, cwd)?.slashCommandsPending) === true;
199
+ return { state, refresh: false, recheckAt: pending ? retryNotBefore : null };
200
+}
201
+
202
+/**
203
+ * A scan that failed, or finished without a complete snapshot, cools down
204
+ * before retrying. After the last attempt the request marker stays, so only
205
+ * the TTL (or a snapshot loss) lets the next scan through.
206
+ */
207
+function failProviderWorkspaceSnapshotRefresh(
208
+ state: ProviderWorkspaceSnapshotRefreshState,
209
+ requestedAt: number,
210
+ now: number,
211
+): ProviderWorkspaceSnapshotRefreshState {
212
+ // A newer request, or a snapshot loss, already superseded this one.
213
+ if (state.requestedAt !== requestedAt) return state;
214
+ const failedAttempts = state.failedAttempts + 1;
215
+ if (failedAttempts >= WORKSPACE_SNAPSHOT_MAX_ATTEMPTS) return { ...state, failedAttempts };
216
+ return {
217
+ ...state,
218
+ requestedAt: null,
219
+ retryNotBefore: now + WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS,
220
+ failedAttempts,
221
+ };
222
+}
223
+
224
+type WorkspaceSnapshotStatus = "absent" | "pending" | "complete";
225
+
226
+function resolveWorkspaceSnapshotStatus(
227
+ provider: ServerProvider | undefined,
228
+ cwd: string,
229
+): WorkspaceSnapshotStatus {
230
+ const snapshot = provider && resolveProviderWorkspaceSnapshot(provider, cwd);
231
+ if (!snapshot) return "absent";
232
+ return snapshot.slashCommandsPending ? "pending" : "complete";
233
+}
234
+
235
+interface ProviderWorkspaceSnapshotRefreshTarget {
236
+ readonly environmentId: EnvironmentId;
237
+ readonly instanceId: ProviderInstanceId;
238
+ readonly cwd: string;
239
+}
240
+
241
+/**
242
+ * Keeps one environment/provider/cwd workspace snapshot fresh while mounted:
243
+ * reading scans when it is missing or stale, and refreshing re-checks (the
244
+ * composer does as the user types). It owns the retry timer, so the timer dies
245
+ * with the last subscriber.
246
+ */
247
+export function createProviderWorkspaceSnapshotRefreshAtomFamily(input: {
248
+ readonly providers: (
249
+ environmentId: EnvironmentId,
250
+ ) => Atom.Atom<ReadonlyArray<ServerProvider> | null>;
251
+ readonly refreshProviders: AtomCommand<
252
+ {
253
+ readonly environmentId: EnvironmentId;
254
+ readonly input: { readonly instanceId: ProviderInstanceId; readonly cwd: string };
255
+ },
256
+ { readonly providers: ReadonlyArray<ServerProvider> },
257
+ unknown
258
+ >;
259
+}) {
260
+ // Plain-object keys compare structurally (Effect `Equal`/`Hash`).
261
+ const family = Atom.family((target: ProviderWorkspaceSnapshotRefreshTarget) => {
262
+ const { environmentId, instanceId, cwd } = target;
263
+ const key = `${environmentId}:${instanceId}:${cwd}`;
264
+ const findProvider = (providers: ReadonlyArray<ServerProvider> | null) =>
265
+ providers?.find((provider) => provider.instanceId === instanceId);
266
+ const statusAtom = Atom.make((get) =>
267
+ resolveWorkspaceSnapshotStatus(findProvider(get(input.providers(environmentId))), cwd),
268
+ ).pipe(Atom.withLabel(`provider-workspace-snapshot-status:${key}`));
269
+ type Update = (
270
+ state: ProviderWorkspaceSnapshotRefreshState,
271
+ ) => ProviderWorkspaceSnapshotRefreshState;
272
+ const refreshAtom: Atom.Writable<ProviderWorkspaceSnapshotRefreshState, Update> = Atom.writable(
273
+ (get): ProviderWorkspaceSnapshotRefreshState => {
274
+ get(statusAtom);
275
+ // `once`: unrelated provider updates must not trigger a check.
276
+ const provider = findProvider(get.once(input.providers(environmentId)));
277
+ // @effect-diagnostics-next-line globalDate:off
278
+ const now = Date.now();
279
+ const previous = get.self<ProviderWorkspaceSnapshotRefreshState>();
280
+ const plan = planProviderWorkspaceSnapshotRefresh(
281
+ previous._tag === "Some" ? previous.value : initialProviderWorkspaceSnapshotRefreshState,
282
+ provider,
283
+ cwd,
284
+ now,
285
+ );
286
+ if (plan.recheckAt !== null) {
287
+ get.addFinalizer(deadlineStore(plan.recheckAt).subscribe(() => get.refreshSelf()));
288
+ }
289
+ if (!plan.refresh) return plan.state;
290
+ const registry = get.registry;
291
+ // Outlives this build on purpose: a rebuild must not drop the retry.
292
+ // Once nothing subscribes, the retry state dies with the node; writing
293
+ // would recreate and rebuild it, which scans again with no subscriber.
294
+ const retryLater = () => {
295
+ const node = registry.getNodes().get(refreshAtom);
296
+ if (node === undefined || node.canBeRemoved) return;
297
+ registry.set(refreshAtom, (state) =>
298
+ // @effect-diagnostics-next-line globalDate:off
299
+ failProviderWorkspaceSnapshotRefresh(state, now, Date.now()),
300
+ );
301
+ };
302
+ void runAtomCommand(
303
+ registry,
304
+ input.refreshProviders,
305
+ { environmentId, input: { instanceId, cwd } },
306
+ { reportFailure: false },
307
+ ).then((result) => {
308
+ const refreshed =
309
+ result._tag === "Success" &&
310
+ hasCompleteProviderWorkspaceSnapshot(findProvider(result.value.providers), cwd);
311
+ if (!refreshed) retryLater();
312
+ }, retryLater);
313
+ return plan.state;
314
+ },
315
+ (ctx, update: Update) => {
316
+ ctx.setSelf(update(ctx.get(refreshAtom)));
317
+ ctx.refreshSelf();
318
+ },
319
+ ).pipe(Atom.withLabel(`provider-workspace-snapshot-refresh:${key}`));
320
+ return refreshAtom;
321
+ });
322
+ return (target: ProviderWorkspaceSnapshotRefreshTarget): Atom.Atom<unknown> =>
323
+ family({ environmentId: target.environmentId, instanceId: target.instanceId, cwd: target.cwd });
324
+}