The best way to control Claude Code, Codex and more from any computer or phone
refactor(server): provider registry owns explicit model cache invalidation (#19599)
Co-authored-by: maria-rcks <maria@kuuro.net>
Tristan Knight committed
Nov 3, 2026 at 01:33 UTC
948433da18a46791007585d02b8bd4efc6eaca17
5 files changed
+184
-29
apps/server/src/provider/ProviderRegistry.test.ts
+137
@@ -1478,6 +1478,143 @@ it.layer(
1478
);
1479
});
1480
1481
+ it.effect("invalidates model caches only for an explicit model refresh", () =>
1482
+ Effect.gen(function* () {
1483
+ const forceRefreshCalls = yield* Ref.make(0);
1484
+ const makeInstance = (name: string) =>
1485
+ Effect.gen(function* () {
1486
+ const driver = ProviderDriverKind.make("codex");
1487
+ const instanceId = ProviderInstanceId.make(name);
1488
+ const provider = {
1489
+ instanceId,
1490
+ driver,
1491
+ status: "ready",
1492
+ enabled: true,
1493
+ installed: true,
1494
+ auth: { status: "authenticated" },
1495
+ checkedAt: "2026-06-10T00:00:00.000Z",
1496
+ version: "1.0.0",
1497
+ models: [],
1498
+ slashCommands: [],
1499
+ skills: [],
1500
+ } as const satisfies ServerProvider;
1501
+ const invalidations = yield* Ref.make(0);
1502
+ const maintenanceReads = yield* Ref.make<ReadonlyArray<boolean>>([]);
1503
+ const instance = {
1504
+ instanceId,
1505
+ driverKind: driver,
1506
+ continuationIdentity: {
1507
+ driverKind: driver,
1508
+ continuationKey: `codex:instance:${name}`,
1509
+ },
1510
+ displayName: undefined,
1511
+ enabled: true,
1512
+ snapshot: {
1513
+ resolveMaintenance: (options) =>
1514
+ Ref.update(maintenanceReads, (reads) => [...reads, options?.fresh === true]).pipe(
1515
+ Effect.as(
1516
+ makeManualOnlyProviderMaintenanceCapabilities({
1517
+ provider: driver,
1518
+ packageName: `${name}-package`,
1519
+ }),
1520
+ ),
1521
+ ),
1522
+ getSnapshot: Effect.succeed(provider),
1523
+ refresh: Effect.succeed(provider),
1524
+ streamChanges: Stream.empty,
1525
+ applyUsageLimits: () => Effect.void,
1526
+ },
1527
+ invalidateCaches: Ref.update(invalidations, (count) => count + 1),
1528
+ orchestrationAdapter: {} as ProviderInstance["orchestrationAdapter"],
1529
+ textGeneration: {} as ProviderInstance["textGeneration"],
1530
+ } satisfies ProviderInstance;
1531
+ const takeMaintenanceReads = Ref.getAndSet(maintenanceReads, []);
1532
+ return { instance, invalidations, takeMaintenanceReads };
1533
+ });
1534
+ const first = yield* makeInstance("codex_first");
1535
+ const second = yield* makeInstance("codex_second");
1536
+ const instances = [first.instance, second.instance];
1537
+ const layerInstanceRegistry = Layer.succeed(
1538
+ ProviderInstanceRegistry.ProviderInstanceRegistry,
1539
+ {
1540
+ getInstance: (instanceId) =>
1541
+ Effect.succeed(instances.find((instance) => instance.instanceId === instanceId)),
1542
+ listInstances: Effect.succeed(instances),
1543
+ listUnavailable: Effect.succeed([]),
1544
+ streamChanges: Stream.empty,
1545
+ subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), PubSub.subscribe),
1546
+ },
1547
+ );
1548
+ const layerModelManifest = Layer.succeed(ModelManifest.ModelManifest, {
1549
+ current: Effect.succeed(ModelManifest.BUNDLED_MODEL_MANIFEST),
1550
+ refresh: Effect.succeed(ModelManifest.BUNDLED_MODEL_MANIFEST),
1551
+ forceRefresh: Ref.update(forceRefreshCalls, (count) => count + 1).pipe(
1552
+ Effect.as(ModelManifest.BUNDLED_MODEL_MANIFEST),
1553
+ ),
1554
+ refreshInBackground: Effect.void,
1555
+ });
1556
+ const layerLatestVersions = Layer.effect(
1557
+ ProviderLatestVersions.ProviderLatestVersions,
1558
+ ProviderLatestVersions.make([
1559
+ ["codex_first-package", "1.0.0"],
1560
+ ["codex_second-package", "1.0.0"],
1561
+ ]),
1562
+ );
1563
+ const readCachedVersion = (key: string) =>
1564
+ ProviderLatestVersions.ProviderLatestVersions.use((latestVersions) =>
1565
+ latestVersions.cached(key, Effect.succeed("2.0.0")),
1566
+ );
1567
+
1568
+ yield* Effect.gen(function* () {
1569
+ const registry = yield* ProviderRegistry.ProviderRegistry;
1570
+
1571
+ yield* registry.refreshInstance(first.instance.instanceId);
1572
+ yield* registry.refresh();
1573
+ assert.strictEqual(yield* Ref.get(forceRefreshCalls), 0);
1574
+ assert.strictEqual(yield* Ref.get(first.invalidations), 0);
1575
+ assert.strictEqual(yield* readCachedVersion("codex_first-package"), "1.0.0");
1576
+ yield* first.takeMaintenanceReads;
1577
+
1578
+ yield* registry.invalidateModelCaches({ instanceId: first.instance.instanceId });
1579
+ // The instance refresh that follows resolves installer metadata fresh itself.
1580
+ assert.deepStrictEqual(yield* first.takeMaintenanceReads, [false]);
1581
+ assert.strictEqual(yield* Ref.get(forceRefreshCalls), 1);
1582
+ assert.strictEqual(yield* Ref.get(first.invalidations), 1);
1583
+ assert.strictEqual(yield* Ref.get(second.invalidations), 0);
1584
+ assert.strictEqual(yield* readCachedVersion("codex_first-package"), "2.0.0");
1585
+ assert.strictEqual(yield* readCachedVersion("codex_second-package"), "1.0.0");
1586
+
1587
+ yield* registry.invalidateModelCaches({});
1588
+ assert.strictEqual(yield* Ref.get(first.invalidations), 2);
1589
+ assert.strictEqual(yield* Ref.get(second.invalidations), 1);
1590
+ assert.strictEqual(yield* readCachedVersion("codex_second-package"), "2.0.0");
1591
+ yield* first.takeMaintenanceReads;
1592
+
1593
+ // Only a cached workspace refresh leaves the fresh resolution to this call.
1594
+ const workspace = { instanceId: first.instance.instanceId, cwd: process.cwd() };
1595
+ yield* registry.invalidateModelCaches(workspace);
1596
+ assert.deepStrictEqual(yield* first.takeMaintenanceReads, [true]);
1597
+ yield* registry.invalidateModelCaches({ ...workspace, fresh: true });
1598
+ assert.deepStrictEqual(yield* first.takeMaintenanceReads, [false]);
1599
+ }).pipe(
1600
+ Effect.provide(
1601
+ ProviderRegistry.layer.pipe(
1602
+ Layer.provideMerge(layerInstanceRegistry),
1603
+ Layer.provideMerge(layerModelManifest),
1604
+ Layer.provideMerge(layerLatestVersions),
1605
+ Layer.provide(layerUnusedMutator),
1606
+ Layer.provideMerge(
1607
+ ServerConfig.layerTest(process.cwd(), {
1608
+ prefix: "t3-provider-registry-model-cache-",
1609
+ }),
1610
+ ),
1611
+ Layer.provideMerge(NodeServices.layer),
1612
+ ),
1613
+ ),
1614
+ );
1615
+ }),
1616
+ );
1617
+
1618
it.effect(
1619
"a second request for a cwd being scanned gets its result, even if the first leaves",
1620
() =>
apps/server/src/provider/ProviderRegistry.ts
+40
@@ -81,6 +81,17 @@ export class ProviderRegistry extends Context.Service<
81
readonly fresh?: boolean;
82
}) => Effect.Effect<ReadonlyArray<ServerProvider>>;
83
84
+ /**
85
+ * Drop T3-owned model caches before an explicit model refresh. Pass the
86
+ * target of the refresh that follows. Background and ordinary refreshes
87
+ * keep their cache timers and must not call this.
88
+ */
89
+ readonly invalidateModelCaches: (input: {
90
+ readonly instanceId?: ProviderInstanceId | undefined;
91
+ readonly cwd?: string | undefined;
92
+ readonly fresh?: boolean | undefined;
93
+ }) => Effect.Effect<void>;
94
+
95
readonly getProviderMaintenanceCapabilitiesForInstance: (
96
instanceId: ProviderInstanceId,
97
provider: ProviderDriverKind,
@@ -1026,6 +1037,34 @@ export const layer = Layer.effect(
1037
return yield* Fiber.join(claim.scan);
1038
});
1039
1040
+ const invalidateModelCaches = Effect.fn("ProviderRegistry.invalidateModelCaches")(function* (
1041
+ input: Parameters<ProviderRegistry["Service"]["invalidateModelCaches"]>[0],
1042
+ ) {
1043
+ yield* manifestService.forceRefresh;
1044
+ const instances = yield* instanceRegistry.listInstances;
1045
+ yield* Effect.forEach(
1046
+ instances.filter(
1047
+ (instance) => input.instanceId === undefined || input.instanceId === instance.instanceId,
1048
+ ),
1049
+ (instance) =>
1050
+ Effect.gen(function* () {
1051
+ yield* instance.invalidateCaches ?? Effect.void;
1052
+ // Instance and full refreshes resolve installer metadata fresh
1053
+ // themselves; a cached workspace refresh needs it resolved here.
1054
+ const maintenance = yield* instance.snapshot.resolveMaintenance({
1055
+ fresh:
1056
+ input.instanceId !== undefined && input.cwd !== undefined && input.fresh !== true,
1057
+ });
1058
+ yield* Effect.forEach(
1059
+ latestProviderVersionCacheKeys(maintenance),
1060
+ latestVersions.invalidate,
1061
+ { discard: true },
1062
+ );
1063
+ }),
1064
+ { concurrency: "unbounded", discard: true },
1065
+ );
1066
+ });
1067
+
1068
return {
1069
getProviders: Ref.get(providersRef),
1070
refresh: (provider?: ProviderDriverKind) =>
@@ -1037,6 +1076,7 @@ export const layer = Layer.effect(
1076
refreshWorkspaceSnapshot: (input) =>
1077
refreshWorkspaceSnapshot(input).pipe(Effect.catchCause(recoverRefreshFailure)),
1078
refreshAfterUpdate,
1079
+ invalidateModelCaches,
1080
getProviderMaintenanceCapabilitiesForInstance,
1081
setProviderMaintenanceActionState,
1082
get streamChanges() {
apps/server/src/provider/providerMaintenanceRunner.test.ts
+1
@@ -211,6 +211,7 @@ function makeRegistry(
211
);
212
},
213
refreshWorkspaceSnapshot: () => Ref.get(providersRef),
214
+ invalidateModelCaches: () => Effect.void,
215
getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
216
Effect.succeed(lifecycleFor(provider)),
217
setProviderMaintenanceActionState,
apps/server/src/provider/testUtils/providerRegistryMock.ts
+1
@@ -14,6 +14,7 @@ const makeProviderRegistryMock = (
14
reloadSecretsAndRefresh: () => Effect.succeed(providers),
15
refreshAfterUpdate: () => Effect.succeed(providers),
16
refreshWorkspaceSnapshot: () => Effect.succeed(providers),
17
+ invalidateModelCaches: () => Effect.void,
18
getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
19
Effect.succeed(makeManualOnlyProviderMaintenanceCapabilities({ provider, packageName: null })),
20
setProviderMaintenanceActionState: () => Effect.succeed(providers),
apps/server/src/ws.ts
+5
-29
@@ -173,9 +173,6 @@ import * as ProviderRegistry from "./provider/ProviderRegistry.ts";
173
import * as ProviderInstanceRegistry from "./provider/ProviderInstanceRegistry.ts";
174
import * as AcpRegistrySupport from "@t3tools/provider-acp-registry/server/AcpRegistrySupport";
175
import * as AcpRegistryRuntimeCoordinator from "@t3tools/provider-acp-registry/server/AcpRegistryRuntimeCoordinator";
176
-import * as ModelManifest from "./provider/ModelManifest.ts";
177
-import * as ProviderLatestVersions from "@t3tools/provider-core/server/ProviderLatestVersions";
178
-import { latestProviderVersionCacheKeys } from "@t3tools/provider-core/server/maintenanceResolver";
176
import * as ProviderMaintenanceRunner from "./provider/providerMaintenanceRunner.ts";
177
import * as ProviderAuthService from "./provider/ProviderAuthService.ts";
178
import { makeProviderInstallation } from "./provider/providerInstallation.ts";
@@ -1382,8 +1379,6 @@ export const layerWsRpc = (
1379
const previewManager = yield* PreviewManager.PreviewManager;
1380
const portDiscovery = yield* PortScanner.PortDiscovery;
1381
const providerRegistry = yield* ProviderRegistry.ProviderRegistry;
1385
- const modelManifest = yield* ModelManifest.ModelManifest;
1386
- const providerLatestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
1382
const providerInstances = yield* ProviderInstanceRegistry.ProviderInstanceRegistry;
1383
const acpRegistryCatalog = yield* AcpRegistrySupport.AcpRegistryCatalog;
1384
const acpRegistryRuntimeCoordinator =
@@ -2353,30 +2348,11 @@ export const layerWsRpc = (
2348
/* Request instrumentation already owns the span; keep this helper in that context. */
2349
Effect.fnUntraced(function* (input) {
2350
if (input.refreshModels) {
2356
- yield* modelManifest.forceRefresh;
2357
- const instances = yield* providerInstances.listInstances;
2358
- yield* Effect.forEach(
2359
- instances.filter(
2360
- (instance) =>
2361
- input.instanceId === undefined || input.instanceId === instance.instanceId,
2362
- ),
2363
- (instance) =>
2364
- Effect.gen(function* () {
2365
- yield* instance.invalidateCaches ?? Effect.void;
2366
- const maintenance = yield* instance.snapshot.resolveMaintenance({
2367
- fresh:
2368
- input.instanceId !== undefined &&
2369
- input.cwd !== undefined &&
2370
- input.fresh !== true,
2371
- });
2372
- yield* Effect.forEach(
2373
- latestProviderVersionCacheKeys(maintenance),
2374
- providerLatestVersions.invalidate,
2375
- { discard: true },
2376
- );
2377
- }),
2378
- { concurrency: "unbounded", discard: true },
2379
- );
2351
+ yield* providerRegistry.invalidateModelCaches({
2352
+ instanceId: input.instanceId,
2353
+ cwd: input.cwd,
2354
+ fresh: input.fresh,
2355
+ });
2356
}
2357
// Await refresh; RPC scope closure would interrupt a fork before the hub answered.
2358
if (input.instanceId === undefined) {