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

main
ts 478 lines 18.9 KB
Raw
1 import {
2 DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL,
3 type ServerProvider,
4 ServerSettingsError,
5 } from "@t3tools/contracts";
6 import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings";
7 import * as Context from "effect/Context";
8 import * as Duration from "effect/Duration";
9 import * as Effect from "effect/Effect";
10 import * as Equal from "effect/Equal";
11 import * as Fiber from "effect/Fiber";
12 import * as PubSub from "effect/PubSub";
13 import * as Queue from "effect/Queue";
14 import * as Ref from "effect/Ref";
15 import * as Scope from "effect/Scope";
16 import * as Stream from "effect/Stream";
17 import * as Semaphore from "effect/Semaphore";
18
19 import * as ProviderHost from "./ProviderHost.ts";
20 import {
21 applyUsageLimitsUpdate,
22 makeUsageLimits,
23 resolveUsageLimitsAfterProbe,
24 } from "./usageLimits.ts";
25 import type { ManagedServerProvider } from "./snapshot.ts";
26
27 interface ProviderSnapshotState {
28 readonly snapshot: ServerProvider;
29 readonly enrichmentGeneration: number;
30 // null preserves an explicitly cleared plan across probes and enrichment.
31 readonly usageAuthLabel: string | null | undefined;
32 readonly checked: boolean;
33 }
34
35 function withUsageLimits(
36 snapshot: ServerProvider,
37 usageLimits: ServerProvider["usageLimits"],
38 ): ServerProvider {
39 if (snapshot.usageLimits === usageLimits) {
40 return snapshot;
41 }
42 const { usageLimits: _previous, ...rest } = snapshot;
43 return usageLimits ? { ...rest, usageLimits } : rest;
44 }
45
46 const FAILED_CHECK_RECHECK_DELAY = "30 seconds";
47
48 /**
49 * True inside a `checkProvider` whose failure over a ready provider is discarded for a recheck.
50 * A provider that also records check results in its own state must leave that failure out of it.
51 */
52 export const DeferringFailedCheck = Context.Reference<boolean>("t3/provider/DeferringFailedCheck", {
53 defaultValue: () => false,
54 });
55
56 export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(function* <
57 Settings,
58 >(input: {
59 readonly resolveMaintenance: ManagedServerProvider["resolveMaintenance"];
60 readonly getSettings: Effect.Effect<Settings, ServerSettingsError>;
61 readonly streamSettings: Stream.Stream<Settings>;
62 readonly haveSettingsChanged: (previous: Settings, next: Settings) => boolean;
63 readonly initialSnapshot: (settings: Settings) => Effect.Effect<ServerProvider>;
64 readonly checkProvider: Effect.Effect<ServerProvider, ServerSettingsError>;
65 readonly checkUsageLimits?: Effect.Effect<ServerProvider["usageLimits"]>;
66 readonly invalidateUsageCache?: Effect.Effect<void>;
67 readonly enrichSnapshot?: (input: {
68 readonly settings: Settings;
69 readonly snapshot: ServerProvider;
70 readonly getSnapshot: Effect.Effect<ServerProvider>;
71 readonly publishSnapshot: (snapshot: ServerProvider) => Effect.Effect<void>;
72 }) => Effect.Effect<void>;
73 readonly refreshInterval?: Duration.Input;
74 readonly refreshOnInterval?: boolean | ((snapshot: ServerProvider) => boolean);
75 readonly checkProviderOnSettingsChange?: (previous: Settings, next: Settings) => boolean;
76 }): Effect.fn.Return<
77 ManagedServerProvider,
78 ServerSettingsError,
79 Scope.Scope | ProviderHost.ProviderHost
80 > {
81 const host = yield* ProviderHost.ProviderHost;
82 const refreshSemaphore = yield* Semaphore.make(1);
83 const usageRefreshQueued = yield* Ref.make<symbol | null>(null);
84 const changesPubSub = yield* Effect.acquireRelease(
85 PubSub.unbounded<ServerProvider>(),
86 PubSub.shutdown,
87 );
88 const initialSettings = yield* input.getSettings;
89 const initialSnapshot = yield* input.initialSnapshot(initialSettings);
90 const snapshotStateRef = yield* Ref.make<ProviderSnapshotState>({
91 snapshot: initialSnapshot,
92 enrichmentGeneration: 0,
93 usageAuthLabel: undefined,
94 checked: false,
95 });
96 const settingsRef = yield* Ref.make(initialSettings);
97 const recheckPendingRef = yield* Ref.make(false);
98 const enrichmentFiberRef = yield* Ref.make<Fiber.Fiber<void, unknown> | null>(null);
99 const scope = yield* Effect.scope;
100
101 const publishEnrichedSnapshot = Effect.fn("publishEnrichedSnapshot")(function* (
102 generation: number,
103 nextSnapshot: ServerProvider,
104 ) {
105 const snapshotToPublish = yield* Ref.modify(snapshotStateRef, (state) => {
106 if (state.enrichmentGeneration !== generation) {
107 return [null, state] as const;
108 }
109 // Enrichment must not revert usage updates newer than its input snapshot.
110 const merged = withUsageLimits(
111 state.usageAuthLabel === undefined
112 ? nextSnapshot
113 : {
114 ...nextSnapshot,
115 auth: { ...nextSnapshot.auth, label: state.usageAuthLabel ?? undefined },
116 },
117 state.snapshot.usageLimits,
118 );
119 if (Equal.equals(state.snapshot, merged)) {
120 return [null, state] as const;
121 }
122 return [merged, { ...state, snapshot: merged }] as const;
123 });
124 if (snapshotToPublish === null) {
125 return;
126 }
127 yield* PubSub.publish(changesPubSub, snapshotToPublish);
128 });
129
130 const restartSnapshotEnrichment = Effect.fn("restartSnapshotEnrichment")(function* (
131 settings: Settings,
132 snapshot: ServerProvider,
133 generation: number,
134 ) {
135 const previousFiber = yield* Ref.getAndSet(enrichmentFiberRef, null);
136 if (previousFiber) {
137 yield* Fiber.interrupt(previousFiber).pipe(Effect.ignore);
138 }
139
140 if (!input.enrichSnapshot || !snapshot.enabled) {
141 return;
142 }
143
144 const fiber = yield* input
145 .enrichSnapshot({
146 settings,
147 snapshot,
148 getSnapshot: Ref.get(snapshotStateRef).pipe(Effect.map((state) => state.snapshot)),
149 publishSnapshot: (nextSnapshot) => publishEnrichedSnapshot(generation, nextSnapshot),
150 })
151 .pipe(Effect.ignoreCause({ log: true }), Effect.forkIn(scope));
152
153 yield* Ref.set(enrichmentFiberRef, fiber);
154 });
155
156 const applySnapshotBase = Effect.fn("applySnapshot")(function* (
157 nextSettings: Settings,
158 options?: { readonly forceRefresh?: boolean; readonly deferFailure?: boolean },
159 ) {
160 const previousSettings = yield* Ref.get(settingsRef);
161 const settingsChanged =
162 options?.forceRefresh === true || input.haveSettingsChanged(previousSettings, nextSettings);
163 // Nothing watches credential files, so any settings apply rechecks a failed sign-in.
164 const { snapshot: currentSnapshot } = yield* Ref.get(snapshotStateRef);
165 const forceRefresh =
166 options?.forceRefresh === true ||
167 (currentSnapshot.enabled && currentSnapshot.auth.status === "unauthenticated");
168 if (!forceRefresh && !settingsChanged) {
169 yield* Ref.set(settingsRef, nextSettings);
170 return yield* Ref.get(snapshotStateRef).pipe(Effect.map((state) => state.snapshot));
171 }
172
173 if (
174 !forceRefresh &&
175 input.checkProviderOnSettingsChange?.(previousSettings, nextSettings) === false
176 ) {
177 const state = yield* Ref.get(snapshotStateRef);
178 const nextGeneration = state.enrichmentGeneration + 1;
179 yield* Ref.set(snapshotStateRef, {
180 ...state,
181 enrichmentGeneration: nextGeneration,
182 });
183 yield* Ref.set(settingsRef, nextSettings);
184 yield* restartSnapshotEnrichment(nextSettings, state.snapshot, nextGeneration);
185 return state.snapshot;
186 }
187
188 // A probe without usage must not erase a report published while its I/O was in flight.
189 const usageBeforeProbe = (yield* Ref.get(snapshotStateRef)).snapshot.usageLimits;
190 const probedSnapshot = yield* input.checkProvider.pipe(
191 Effect.provideService(DeferringFailedCheck, options?.deferFailure === true),
192 );
193 // One failed periodic check over a ready provider is often transient; recheck before showing it.
194 if (
195 options?.deferFailure === true &&
196 probedSnapshot.status === "error" &&
197 probedSnapshot.auth.status !== "unauthenticated"
198 ) {
199 const { snapshot } = yield* Ref.get(snapshotStateRef);
200 if (snapshot.enabled && snapshot.status === "ready") {
201 yield* Ref.set(recheckPendingRef, true);
202 return snapshot;
203 }
204 }
205 const { snapshot: nextSnapshot, generation: nextGeneration } = yield* Ref.modify(
206 snapshotStateRef,
207 (state) => {
208 const generation = input.enrichSnapshot
209 ? state.enrichmentGeneration + 1
210 : state.enrichmentGeneration;
211 // Failed reads retain limits only for the same account and original workspace.
212 const previous = state.snapshot.auth;
213 const differs = (a: string | undefined, b: string | undefined) =>
214 a !== undefined && b !== undefined && a !== b;
215 const switchedAccount =
216 differs(probedSnapshot.auth.email?.toLowerCase(), previous.email?.toLowerCase()) ||
217 (probedSnapshot.auth.workspaceId !== undefined &&
218 probedSnapshot.auth.workspaceId !== previous.workspaceId);
219 const usageLimits = switchedAccount
220 ? probedSnapshot.usageLimits
221 : probedSnapshot.usageLimits === undefined &&
222 state.snapshot.usageLimits !== usageBeforeProbe
223 ? state.snapshot.usageLimits
224 : resolveUsageLimitsAfterProbe({
225 published: state.snapshot.usageLimits,
226 probed: probedSnapshot.usageLimits,
227 });
228 const workspaceId =
229 usageLimits === probedSnapshot.usageLimits ? undefined : state.snapshot.auth.workspaceId;
230 const usageAuthLabel =
231 !switchedAccount && usageLimits?.checkedAt === state.snapshot.usageLimits?.checkedAt
232 ? state.usageAuthLabel
233 : undefined;
234 const labeledProbe =
235 usageAuthLabel === undefined
236 ? probedSnapshot
237 : {
238 ...probedSnapshot,
239 auth: { ...probedSnapshot.auth, label: usageAuthLabel ?? undefined },
240 };
241 const snapshot = withUsageLimits(
242 workspaceId && !probedSnapshot.auth.workspaceId
243 ? { ...labeledProbe, auth: { ...labeledProbe.auth, workspaceId } }
244 : labeledProbe,
245 usageLimits,
246 );
247 return [
248 { snapshot, generation },
249 { snapshot, enrichmentGeneration: generation, usageAuthLabel, checked: true },
250 ] as const;
251 },
252 );
253 yield* Ref.set(settingsRef, nextSettings);
254 yield* PubSub.publish(changesPubSub, nextSnapshot);
255 yield* restartSnapshotEnrichment(nextSettings, nextSnapshot, nextGeneration);
256 return nextSnapshot;
257 });
258 const applySnapshot = (nextSettings: Settings, options?: { readonly forceRefresh?: boolean }) =>
259 refreshSemaphore.withPermits(1)(applySnapshotBase(nextSettings, options));
260
261 // Providers call this on every token-usage tick, usually without changing the snapshot.
262 const applyUsageLimits: ManagedServerProvider["applyUsageLimits"] = Effect.fnUntraced(
263 function* (update) {
264 const snapshotToPublish = yield* Ref.modify(snapshotStateRef, (state) => {
265 const complete = update.complete && update.windows.length > 0;
266 const usageLimits = complete
267 ? makeUsageLimits(update)
268 : applyUsageLimitsUpdate({
269 previous: state.snapshot.usageLimits,
270 update,
271 checkedAt: update.checkedAt,
272 });
273 const { auth } = state.snapshot;
274 const label = update.windows.length > 0 ? update.authLabel : undefined;
275 const relabel =
276 (label !== undefined || (complete && state.usageAuthLabel !== undefined)) &&
277 label !== auth.label;
278 if (usageLimits === state.snapshot.usageLimits && !relabel) {
279 return [null, state] as const;
280 }
281 const snapshot = withUsageLimits(
282 relabel ? { ...state.snapshot, auth: { ...auth, label } } : state.snapshot,
283 usageLimits,
284 );
285 return [
286 snapshot,
287 {
288 ...state,
289 snapshot,
290 usageAuthLabel: label ?? (complete ? null : state.usageAuthLabel),
291 },
292 ] as const;
293 });
294 if (snapshotToPublish !== null) {
295 yield* PubSub.publish(changesPubSub, snapshotToPublish);
296 }
297 },
298 );
299
300 const refreshSnapshot = Effect.fn("refreshSnapshot")(function* () {
301 const nextSettings = yield* input.getSettings;
302 return yield* applySnapshot(nextSettings, { forceRefresh: true });
303 });
304
305 const refreshUsage = Effect.fn("ManagedServerProvider.refreshUsage")(function* () {
306 const { snapshot } = yield* Ref.get(snapshotStateRef);
307 if (
308 !snapshot.enabled ||
309 !snapshot.usageLimits ||
310 snapshot.usageLimits.unavailable?.reason === "unsupported"
311 )
312 return;
313 // An in-flight refresh may have read cached usage, so one refresh waits behind it.
314 const claim = Symbol();
315 const release = Ref.update(usageRefreshQueued, (queued) => (queued === claim ? null : queued));
316 yield* Effect.uninterruptibleMask((restore) =>
317 Ref.modify(usageRefreshQueued, (queued) => [queued !== null, queued ?? claim]).pipe(
318 Effect.flatMap((held) =>
319 held
320 ? Effect.void
321 : restore(
322 refreshSemaphore.withPermits(1)(
323 release.pipe(
324 Effect.andThen(input.invalidateUsageCache ?? Effect.void),
325 Effect.andThen(input.getSettings),
326 Effect.flatMap((settings) =>
327 applySnapshotBase(settings, { forceRefresh: true }),
328 ),
329 ),
330 ),
331 ).pipe(Effect.onInterrupt(() => release)),
332 ),
333 ),
334 );
335 });
336
337 const needsUsageRecovery = (snapshot: ServerProvider) =>
338 input.checkUsageLimits !== undefined &&
339 snapshot.installed &&
340 snapshot.status === "ready" &&
341 snapshot.auth.status === "authenticated" &&
342 snapshot.usageLimits?.unavailable?.reason === "probeFailed";
343
344 const needsProviderRefresh = (snapshot: ServerProvider) =>
345 input.refreshOnInterval !== false &&
346 (typeof input.refreshOnInterval !== "function" || input.refreshOnInterval(snapshot));
347
348 const refreshOnInterval = Effect.fn("ManagedServerProvider.refreshOnInterval")(function* (
349 deferFailure: boolean,
350 ) {
351 const { snapshot } = yield* Ref.get(snapshotStateRef);
352 if (!snapshot.enabled) return;
353 if (!needsUsageRecovery(snapshot) || !input.checkUsageLimits) {
354 if (needsProviderRefresh(snapshot)) {
355 yield* applySnapshotBase(yield* input.getSettings, { forceRefresh: true, deferFailure });
356 }
357 return;
358 }
359 const probed = yield* input.checkUsageLimits;
360 const next = yield* Ref.modify(snapshotStateRef, (state) => {
361 const usageLimits = resolveUsageLimitsAfterProbe({
362 published: state.snapshot.usageLimits,
363 probed,
364 });
365 const snapshot = withUsageLimits(state.snapshot, usageLimits);
366 return [snapshot, { ...state, snapshot }] as const;
367 });
368 yield* PubSub.publish(changesPubSub, next);
369 });
370
371 const shouldRefreshOnInterval = Effect.gen(function* () {
372 const state = yield* Ref.get(snapshotStateRef);
373 // A disabled instance has nothing to probe; a periodic check would only
374 // republish a snapshot that differs in checkedAt.
375 if (
376 !state.snapshot.enabled ||
377 (!needsUsageRecovery(state.snapshot) && !needsProviderRefresh(state.snapshot))
378 ) {
379 return false;
380 }
381 const instanceId = state.snapshot.instanceId;
382 const [genericDemand, instanceDemand] = yield* Effect.all([
383 host.shouldRunBackgroundWork({ type: "provider-status" }),
384 host.shouldRunBackgroundWork({ type: "provider-status", instanceId }),
385 ]);
386 return genericDemand || instanceDemand;
387 });
388
389 const getRefreshInterval =
390 input.refreshInterval !== undefined
391 ? Effect.succeed(input.refreshInterval)
392 : host.settings.get.pipe(
393 Effect.map(
394 (settings) =>
395 resolveServerBackgroundActivitySettings(settings).providerHealthRefreshInterval,
396 ),
397 Effect.orElseSucceed(() => DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL),
398 );
399
400 const refreshIntervalChanges = yield* Queue.sliding<void>(1);
401 if (input.refreshInterval === undefined) {
402 const serverSettingsChanges = yield* host.settings.subscribe;
403 yield* serverSettingsChanges.pipe(
404 Stream.map((settings) =>
405 Duration.toMillis(
406 resolveServerBackgroundActivitySettings(settings).providerHealthRefreshInterval,
407 ),
408 ),
409 Stream.changes,
410 Stream.runForEach(() => Queue.offer(refreshIntervalChanges, undefined).pipe(Effect.asVoid)),
411 Effect.forkScoped,
412 );
413 }
414
415 // A failed check must not end this subscription: the next settings change
416 // retries, like the periodic and initial checks below.
417 yield* Stream.runForEach(input.streamSettings, (nextSettings) =>
418 Effect.asVoid(applySnapshot(nextSettings)).pipe(Effect.ignoreCause({ log: true })),
419 ).pipe(Effect.forkScoped);
420
421 yield* Effect.forever(
422 Effect.all([getRefreshInterval, Ref.getAndSet(recheckPendingRef, false)]).pipe(
423 Effect.flatMap(([configuredInterval, recheckPending]) => {
424 const refreshInterval = recheckPending ? FAILED_CHECK_RECHECK_DELAY : configuredInterval;
425 // @effect-diagnostics-next-line raceFirstWithSleepToTimeout:off - races the interval against a settings-change signal, not a timeout
426 return Effect.raceFirst(
427 Effect.sleep(
428 Duration.toMillis(Duration.fromInputUnsafe(refreshInterval)) <= 0
429 ? "60 seconds"
430 : refreshInterval,
431 ).pipe(Effect.as(true)),
432 Queue.take(refreshIntervalChanges).pipe(Effect.as(false)),
433 ).pipe(
434 Effect.flatMap((intervalElapsed) =>
435 intervalElapsed && Duration.toMillis(Duration.fromInputUnsafe(refreshInterval)) > 0
436 ? shouldRefreshOnInterval.pipe(
437 Effect.flatMap((shouldRefresh) =>
438 shouldRefresh
439 ? refreshSemaphore.withPermits(1)(refreshOnInterval(!recheckPending))
440 : Effect.void,
441 ),
442 )
443 : Effect.void,
444 ),
445 );
446 }),
447 Effect.ignoreCause({ log: true }),
448 ),
449 ).pipe(Effect.forkScoped);
450
451 // Probes spawn provider CLIs; starting them during server startup slows the first client load.
452 yield* (host.awaitServerReady ?? Effect.void).pipe(
453 Effect.andThen(
454 // Read under the lock, so a settings check in flight cannot be overwritten with older settings.
455 refreshSemaphore.withPermits(1)(
456 Ref.get(settingsRef).pipe(
457 Effect.flatMap((settings) => applySnapshotBase(settings, { forceRefresh: true })),
458 ),
459 ),
460 ),
461 Effect.ignoreCause({ log: true }),
462 Effect.forkScoped,
463 );
464
465 return {
466 resolveMaintenance: input.resolveMaintenance,
467 getSnapshot: Ref.get(snapshotStateRef).pipe(Effect.map((state) => state.snapshot)),
468 isAwaitingFirstCheck: Ref.get(snapshotStateRef).pipe(Effect.map((state) => !state.checked)),
469 refresh: input
470 .resolveMaintenance({ fresh: true })
471 .pipe(Effect.andThen(refreshSnapshot), Effect.tapError(Effect.logError), Effect.orDie),
472 applyUsageLimits,
473 refreshUsage: refreshUsage(),
474 get streamChanges() {
475 return Stream.fromPubSub(changesPubSub);
476 },
477 } satisfies ManagedServerProvider;
478 });