@devries-cameron20 / t3code Mirror · read-only / commits / 6ea34149bb
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 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 +}