The best way to control Claude Code, Codex and more from any computer or phone
perf(mobile): each environment sends about 85% less data at launch (#35072)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Theo Browne committed
Nov 12, 2026 at 02:52 UTC
8b2763f638241b1be5ddf334d4f3aac8de8114b3
17 files changed
+817
-85
apps/mobile/src/connection/runtime.ts
+2
@@ -40,6 +40,8 @@ const layerProvidedClientConnection = layerSnapshotLoader.pipe(
40
usageLimitSources: true,
41
usageLimitsCommand: true,
42
providerCatalogsOnDemand: true,
43
+ providerCatalogDigests: true,
44
+ providerStatusDeltas: true,
45
}),
46
),
47
Layer.provideMerge(
apps/mobile/src/state/server.ts
+3
@@ -14,6 +14,9 @@ export const serverEnvironment = createServerEnvironmentAtoms(connectionAtomRunt
14
usageLimitSources: true,
15
usageLimitsCommand: true,
16
providerCatalogsOnDemand: true,
17
+ providerCatalogDigests: true,
18
+ providerStatusDeltas: true,
19
+ omitRefreshedProviders: true,
20
});
21
export const describeOutdatedServer = createOutdatedServerDescriptionCommand(connectionAtomRuntime);
22
export const updateOutdatedServer = createOutdatedServerUpdateCommand(connectionAtomRuntime);
apps/mobile/src/widgets/useSubscriptionUsage.test.ts
+32
-1
@@ -1,4 +1,5 @@
1
import { EnvironmentId } from "@t3tools/contracts";
2
+import * as Option from "effect/Option";
3
import { Atom, AtomRegistry } from "effect/reactivity";
4
import { describe, expect, it, vi } from "vite-plus/test";
5
@@ -38,6 +39,18 @@ vi.mock("../state/presentation", async () => {
39
};
40
});
41
42
+vi.mock("../state/shell", async () => {
43
+ const { Atom } = await import("effect/reactivity");
44
+ const Option = await import("effect/Option");
45
+ return {
46
+ environmentShell: {
47
+ stateValueAtom: Atom.family((_id: string) =>
48
+ Atom.make({ status: "synchronizing", error: Option.none<string>() }),
49
+ ),
50
+ },
51
+ };
52
+});
53
+
54
vi.mock("../state/server", () => ({
55
serverEnvironment: { refreshProviders: { label: "Refresh providers" } },
56
}));
@@ -56,6 +69,7 @@ vi.mock("@t3tools/client-runtime/state/runtime", () => ({
69
import { environmentCatalog } from "../connection/catalog";
70
import { appAtomRegistry } from "../state/atom-registry";
71
import { environmentPresentations } from "../state/presentation";
72
+import { environmentShell } from "../state/shell";
73
import { installSubscriptionUsageRefresh } from "./useSubscriptionUsage";
74
75
const registry = appAtomRegistry as AtomRegistry.AtomRegistry;
@@ -66,8 +80,16 @@ const presentationsAtom = environmentPresentations.presentationsAtom as unknown
80
Map<string, { connection: { phase: string } }>
81
>;
82
83
+const shellAtom = (environmentId: EnvironmentId) =>
84
+ environmentShell.stateValueAtom(environmentId) as unknown as Atom.Writable<{
85
+ status: string;
86
+ error: Option.Option<string>;
87
+ }>;
88
+
89
const connected = EnvironmentId.make("env-connected");
90
const connecting = EnvironmentId.make("env-connecting");
91
+const syncing = EnvironmentId.make("env-syncing");
92
+const failed = EnvironmentId.make("env-failed");
93
94
describe("installSubscriptionUsageRefresh", () => {
95
it("refreshes connected environments once the catalog is ready and the app is active", () => {
@@ -79,8 +101,13 @@ describe("installSubscriptionUsageRefresh", () => {
101
new Map([
102
[connected, { connection: { phase: "connected" } }],
103
[connecting, { connection: { phase: "connecting" } }],
104
+ [syncing, { connection: { phase: "connected" } }],
105
+ [failed, { connection: { phase: "connected" } }],
106
]),
107
);
108
+ registry.set(shellAtom(connected), { status: "live", error: Option.none() });
109
+ // A shell that failed never goes live; its quotas still refresh.
110
+ registry.set(shellAtom(failed), { status: "cached", error: Option.some("Shell failed") });
111
112
const dispose = installSubscriptionUsageRefresh();
113
registry.set(catalogAtom, { isReady: true });
@@ -89,7 +116,11 @@ describe("installSubscriptionUsageRefresh", () => {
116
117
fixture.appState = "active";
118
for (const listener of fixture.appStateListeners) listener();
92
- expect(fixture.refreshed).toEqual([connected]);
119
+ expect(fixture.refreshed).toEqual([connected, failed]);
120
+
121
+ // The refresh waits for the thread list, so it never competes with it on a cold start.
122
+ registry.set(shellAtom(syncing), { status: "live", error: Option.none() });
123
+ expect(fixture.refreshed).toEqual([connected, failed, syncing]);
124
125
dispose();
126
expect(fixture.appStateListeners.size).toBe(0);
apps/mobile/src/widgets/useSubscriptionUsage.ts
+29
-10
@@ -1,13 +1,37 @@
1
import { runAtomCommand } from "@t3tools/client-runtime/state/runtime";
2
import type { EnvironmentId } from "@t3tools/contracts";
3
+import * as Option from "effect/Option";
4
+import { Atom } from "effect/reactivity";
5
6
import { environmentCatalog } from "../connection/catalog";
7
import { isAppActive, subscribeAppState } from "../lib/appState";
8
import { appAtomRegistry } from "../state/atom-registry";
9
import { environmentPresentations } from "../state/presentation";
10
import { serverEnvironment } from "../state/server";
11
+import { environmentShell } from "../state/shell";
12
import { createWidgetRefresher, WIDGET_REFRESH_INTERVAL } from "./subscriptionUsageSnapshot";
13
14
+// A shell that failed never goes live, and its environment still needs fresh quotas.
15
+const shellSettledAtom = Atom.family((environmentId: EnvironmentId) =>
16
+ Atom.make((get) => {
17
+ const shell = get(environmentShell.stateValueAtom(environmentId));
18
+ return shell.status === "live" || Option.isSome(shell.error);
19
+ }),
20
+);
21
+
22
+/**
23
+ * Connected environments whose thread list has loaded. A refresh re-probes every provider on
24
+ * the host, so on a cold start it waits until it cannot compete with the thread list.
25
+ */
26
+const refreshableEnvironmentsAtom = Atom.make((get) =>
27
+ [...get(environmentPresentations.presentationsAtom)]
28
+ .filter(
29
+ ([environmentId, presentation]) =>
30
+ presentation.connection.phase === "connected" && get(shellSettledAtom(environmentId)),
31
+ )
32
+ .map(([environmentId]) => environmentId),
33
+);
34
+
35
/**
36
* App-lifetime worker that keeps provider quotas fresh for the usage widget:
37
* on resume, on every connection change, and on a fixed interval while active.
@@ -24,23 +48,18 @@ export function installSubscriptionUsageRefresh(): () => void {
48
);
49
const update = () => {
50
if (!isAppActive() || !appAtomRegistry.get(environmentCatalog.catalogValueAtom).isReady) return;
27
- const connected = [...appAtomRegistry.get(environmentPresentations.presentationsAtom)]
28
- .filter(([, presentation]) => presentation.connection.phase === "connected")
29
- .map(([id]) => id);
30
- void refresh(connected, Date.now());
51
+ void refresh(appAtomRegistry.get(refreshableEnvironmentsAtom), Date.now());
52
};
53
54
const unsubscribeCatalog = appAtomRegistry.subscribe(environmentCatalog.catalogValueAtom, update);
34
- const unsubscribePresentations = appAtomRegistry.subscribe(
35
- environmentPresentations.presentationsAtom,
36
- update,
37
- { immediate: true },
38
- );
55
+ const unsubscribeEnvironments = appAtomRegistry.subscribe(refreshableEnvironmentsAtom, update, {
56
+ immediate: true,
57
+ });
58
const unsubscribeAppState = subscribeAppState(update);
59
const timer = setInterval(update, WIDGET_REFRESH_INTERVAL);
60
return () => {
61
unsubscribeCatalog();
43
- unsubscribePresentations();
62
+ unsubscribeEnvironments();
63
unsubscribeAppState();
64
clearInterval(timer);
65
};
apps/server/src/ws.test.ts
+120
-2
@@ -1168,6 +1168,7 @@ it.effect("on-demand clients get provider config without workspace snapshots", (
1168
],
1169
};
1170
let scansCwd = true;
1171
+ let registryProviders: ReadonlyArray<ServerProvider> = [provider];
1172
const providerChanges = yield* Queue.unbounded<ReadonlyArray<ServerProvider>>();
1173
const pulled = yield* Queue.unbounded<void>();
1174
const responses = yield* Queue.unbounded<unknown>();
@@ -1178,11 +1179,12 @@ it.effect("on-demand clients get provider config without workspace snapshots", (
1179
resolveFileManagerRevealKind: () => Effect.undefined,
1180
}),
1181
Layer.mock(ProviderRegistry.ProviderRegistry)({
1181
- getProviders: Effect.succeed([provider]),
1182
+ getProviders: Effect.sync(() => registryProviders),
1183
streamChanges: Stream.fromQueue(providerChanges).pipe(
1184
Stream.tap(() => Queue.offer(pulled, undefined)),
1185
),
1185
- refreshWorkspaceSnapshot: () => Effect.succeed([provider]),
1186
+ refresh: () => Effect.sync(() => registryProviders),
1187
+ refreshWorkspaceSnapshot: () => Effect.sync(() => registryProviders),
1188
}),
1189
Layer.mock(ProjectService.ProjectService)({
1190
workspaceScanDirectory: (cwd) => Effect.succeed(cwd),
@@ -1204,6 +1206,7 @@ it.effect("on-demand clients get provider config without workspace snapshots", (
1206
Layer.mock(UsageLimitSources.UsageLimitSources)({
1207
current: Effect.succeed([]),
1208
streamChanges: Stream.make([]),
1209
+ refresh: Effect.void,
1210
}),
1211
Layer.mock(RemoteOpenTargets.RemoteOpenTargets)({
1212
resolveTargets: () => Effect.succeed([]),
@@ -1359,6 +1362,121 @@ it.effect("on-demand clients get provider config without workspace snapshots", (
1362
},
1363
]);
1364
yield* server.write(0, { _tag: "Interrupt", requestId: configRequest, interruptors: [] });
1365
+
1366
+ // A client that takes digests and deltas, against a catalog of over 200 KB.
1367
+ const heavy: ServerProvider = {
1368
+ ...provider,
1369
+ slashCommands: Array.from({ length: 250 }, (_, index) => ({
1370
+ name: `command-${index}`,
1371
+ description: "d".repeat(400),
1372
+ })),
1373
+ skills: Array.from({ length: 200 }, (_, index) => ({
1374
+ name: `skill-${index}`,
1375
+ description: "d".repeat(500),
1376
+ path: `/home/user/.claude/skills/skill-${index}/SKILL.md`,
1377
+ enabled: true,
1378
+ })),
1379
+ };
1380
+ registryProviders = [heavy];
1381
+ const lightRequest = RpcMessage.RequestId("light-config");
1382
+ yield* server.write(0, {
1383
+ _tag: "Request",
1384
+ id: lightRequest,
1385
+ tag: WS_METHODS.subscribeServerConfig,
1386
+ payload: {
1387
+ workspaceSnapshotsOnDemand: true,
1388
+ providerCatalogsOnDemand: true,
1389
+ providerCatalogDigests: true,
1390
+ providerStatusDeltas: true,
1391
+ },
1392
+ headers: Headers.empty,
1393
+ });
1394
+ const light = (yield* Queue.take(responses)) as ServerConfigStreamEvent;
1395
+ if (light.type !== "snapshot") return yield* Effect.die("Missing light snapshot");
1396
+ const digest = light.config.providers[0]?.catalogDigest;
1397
+ assert.isString(digest);
1398
+ assert.deepEqual(
1399
+ [light.config.providers[0]?.slashCommands, light.config.providers[0]?.skills],
1400
+ [[], []],
1401
+ );
1402
+ // Budget for the first config a phone decodes: the catalog stays out of it.
1403
+ assert.isBelow(JSON.stringify(light.config.providers).length, 1024);
1404
+ yield* server.write(0, { _tag: "Ack", requestId: lightRequest });
1405
+
1406
+ // A health check sends the provider without the lists the client already holds.
1407
+ yield* Queue.offer(providerChanges, [{ ...heavy, checkedAt: "2026-10-25T00:10:00.000Z" }]);
1408
+ yield* Queue.take(pulled);
1409
+ yield* TestClock.adjust("1 second");
1410
+ const delta = (yield* Queue.take(responses)) as ServerConfigStreamEvent;
1411
+ if (delta.type !== "providerStatusDeltas") return yield* Effect.die("Expected provider deltas");
1412
+ assert.deepEqual(
1413
+ delta.payload.providers.map((entry) => [
1414
+ entry.checkedAt,
1415
+ entry.catalogDigest,
1416
+ entry.models,
1417
+ entry.slashCommands,
1418
+ entry.skills,
1419
+ ]),
1420
+ [["2026-10-25T00:10:00.000Z", digest, undefined, undefined, undefined]],
1421
+ );
1422
+ yield* server.write(0, { _tag: "Ack", requestId: lightRequest });
1423
+
1424
+ // A changed description changes the digest, so the client loads the lists again.
1425
+ yield* Queue.offer(providerChanges, [
1426
+ {
1427
+ ...heavy,
1428
+ checkedAt: "2026-10-25T00:20:00.000Z",
1429
+ skills: heavy.skills.map((skill, index) =>
1430
+ index === 0 ? { ...skill, description: "changed" } : skill,
1431
+ ),
1432
+ },
1433
+ ]);
1434
+ yield* Queue.take(pulled);
1435
+ yield* TestClock.adjust("1 second");
1436
+ const redescribed = (yield* Queue.take(responses)) as ServerConfigStreamEvent;
1437
+ if (redescribed.type !== "providerStatusDeltas") {
1438
+ return yield* Effect.die("Expected provider deltas");
1439
+ }
1440
+ assert.notEqual(redescribed.payload.providers[0]?.catalogDigest, digest);
1441
+ yield* server.write(0, { _tag: "Ack", requestId: lightRequest });
1442
+
1443
+ // A caller that only waits for a machine refresh gets no provider list back.
1444
+ yield* server.write(0, {
1445
+ _tag: "Request",
1446
+ id: RpcMessage.RequestId("refresh-omitted"),
1447
+ tag: WS_METHODS.serverRefreshProviders,
1448
+ payload: { workspaceSnapshotsOnDemand: true, omitProviders: true },
1449
+ headers: Headers.empty,
1450
+ });
1451
+ assert.deepEqual(yield* Queue.take(responses), { providers: [] });
1452
+
1453
+ // The cwd snapshot brings the lists the digest stands for, under the same digest.
1454
+ yield* server.write(0, {
1455
+ _tag: "Request",
1456
+ id: RpcMessage.RequestId("refresh-machine-catalog"),
1457
+ tag: WS_METHODS.serverRefreshProviders,
1458
+ payload: {
1459
+ instanceId,
1460
+ cwd: "/b",
1461
+ workspaceSnapshotsOnDemand: true,
1462
+ providerCatalogsOnDemand: true,
1463
+ omitProviders: true,
1464
+ machineCatalog: true,
1465
+ },
1466
+ headers: Headers.empty,
1467
+ });
1468
+ const loaded = (yield* Queue.take(responses)) as {
1469
+ readonly providers: ReadonlyArray<ServerProvider>;
1470
+ };
1471
+ assert.equal(loaded.providers[0]?.catalogDigest, digest);
1472
+ assert.deepEqual(loaded.providers[0]?.slashCommands[0], { name: "command-0" });
1473
+ assert.deepEqual(loaded.providers[0]?.skills[0], {
1474
+ name: "skill-0",
1475
+ path: "/home/user/.claude/skills/skill-0/SKILL.md",
1476
+ enabled: true,
1477
+ });
1478
+ assert.lengthOf(loaded.providers[0]?.workspaceSnapshots ?? [], 1);
1479
+ yield* server.write(0, { _tag: "Interrupt", requestId: lightRequest, interruptors: [] });
1480
}).pipe(
1481
Effect.provide(
1482
Layer.mergeAll(
apps/server/src/ws.ts
+101
-31
@@ -1,4 +1,6 @@
1
import { OrchestrationDispatchCommandError } from "@t3tools/contracts";
2
+// @effect-diagnostics-next-line nodeBuiltinImport:off -- A synchronous digest inside the pure provider mapping.
3
+import * as NodeCrypto from "node:crypto";
4
import * as Context from "effect/Context";
5
import * as SecureRandom from "effect/crypto/SecureRandom";
6
import * as Orchestrator from "./orchestration-v2/Orchestrator.ts";
@@ -83,6 +85,7 @@ import {
85
type ServerConfigStreamEvent,
86
type ServerLifecycleStreamEvent,
87
type ServerProvider,
88
+ serverProviderDeltas,
89
type FilesystemBrowseFailure,
90
FilesystemBrowseError,
91
AssetWorkspaceContextNotFoundError,
@@ -445,26 +448,67 @@ function workspaceSnapshotOrCatalog(
448
];
449
}
450
448
-// On-demand catalog clients read full entries from the cwd snapshot they fetch. Names still
449
-// change the config when the machine catalog does, so the client refetches, and skill names
450
-// and labels keep skill links working where no snapshot is fetched.
451
+// What an on-demand catalog client keeps of the machine catalog: full entries come from the
452
+// cwd snapshot it fetches, and skill names and labels keep skill links working without one.
453
+function machineCatalogNames(provider: Pick<ServerProvider, "slashCommands" | "skills">) {
454
+ return {
455
+ slashCommands: provider.slashCommands.map(({ name }) => ({ name })),
456
+ skills: provider.skills.map(({ description: _d, shortDescription: _s, ...skill }) => skill),
457
+ };
458
+}
459
+
460
+// Stable across restarts, so a client's cached lists stay current until the catalog changes.
461
+// It covers the full entries: a changed description or input hint must reach the client too.
462
+const machineCatalogDigest = (provider: Pick<ServerProvider, "slashCommands" | "skills">) =>
463
+ NodeCrypto.createHash("sha256")
464
+ .update(JSON.stringify([provider.slashCommands, provider.skills]))
465
+ .digest("hex")
466
+ .slice(0, 16);
467
+
468
+// Names, or the digest that stands for them, still change the config when the machine catalog
469
+// does, so the client refetches its cwd snapshot.
470
function withoutWorkspaceSnapshots(
471
providers: ReadonlyArray<ServerProvider>,
472
catalogsPerCwd: ReadonlySet<string> = new Set(),
473
+ catalogDigests = false,
474
): ServerProvider[] {
455
- return providers.map(({ workspaceSnapshots: _workspaceSnapshots, ...provider }) =>
456
- catalogsPerCwd.has(provider.instanceId)
475
+ return providers.map(({ workspaceSnapshots: _workspaceSnapshots, ...provider }) => {
476
+ if (!catalogsPerCwd.has(provider.instanceId)) return provider;
477
+ return catalogDigests
478
? {
479
...provider,
459
- slashCommands: provider.slashCommands.map(({ name }) => ({ name })),
460
- skills: provider.skills.map(
461
- ({ description: _d, shortDescription: _s, ...skill }) => skill,
462
- ),
480
+ slashCommands: [],
481
+ skills: [],
482
+ catalogDigest: machineCatalogDigest(provider),
483
}
464
- : provider,
465
- );
484
+ : { ...provider, ...machineCatalogNames(provider) };
485
+ });
486
}
487
488
+// Deltas are taken from the list this client last received, which a late snapshot replaces.
489
+const withProviderStatusDeltas = (sent: ReadonlyArray<ServerProvider>) =>
490
+ Stream.mapAccum(
491
+ () => sent,
492
+ (
493
+ previous,
494
+ event: ServerConfigStreamEvent,
495
+ ): readonly [ReadonlyArray<ServerProvider>, ReadonlyArray<ServerConfigStreamEvent>] => {
496
+ if (event.type === "snapshot") return [event.config.providers, [event]];
497
+ if (event.type !== "providerStatuses") return [previous, [event]];
498
+ const { providers } = event.payload;
499
+ return [
500
+ providers,
501
+ [
502
+ {
503
+ version: 1,
504
+ type: "providerStatusDeltas",
505
+ payload: { providers: serverProviderDeltas(previous, providers) },
506
+ },
507
+ ],
508
+ ];
509
+ },
510
+ );
511
+
512
function unexpectedCompatibilityError(error: never): never {
513
throw new Error(`Unhandled compatibility error: ${String(error)}`);
514
}
@@ -1767,6 +1811,7 @@ export const layerWsRpc = (
1811
readonly workspaceSnapshotsOnDemand: boolean;
1812
readonly deferNetworkDiscovery: boolean;
1813
readonly catalogsPerCwd?: ReadonlySet<string>;
1814
+ readonly catalogDigests?: boolean;
1815
}) {
1816
const keybindingsConfig = yield* keybindings.loadConfigState;
1817
const currentProviders = yield* providerRegistry.getProviders;
@@ -1774,7 +1819,11 @@ export const layerWsRpc = (
1819
? withUsageLimitsCommands(currentProviders, yield* usageLimitSources.current)
1820
: currentProviders;
1821
const providers = options.workspaceSnapshotsOnDemand
1777
- ? withoutWorkspaceSnapshots(commandProviders, options.catalogsPerCwd)
1822
+ ? withoutWorkspaceSnapshots(
1823
+ commandProviders,
1824
+ options.catalogsPerCwd,
1825
+ options.catalogDigests,
1826
+ )
1827
: commandProviders;
1828
const settings = ServerSettings.redactServerSettingsForClient(
1829
yield* serverSettings.getSettings,
@@ -2448,12 +2497,15 @@ export const layerWsRpc = (
2497
providers = yield* providerRegistry.refreshInstance(instance.instanceId);
2498
}
2499
}
2500
+ const { instanceId, cwd } = input;
2501
+ if (input.omitProviders === true && (instanceId === undefined || cwd === undefined)) {
2502
+ return { providers: [] };
2503
+ }
2504
if (input.workspaceSnapshotsOnDemand !== true) return { providers };
2505
const commandProviders =
2506
input.usageLimitsCommand === true
2507
? withUsageLimitsCommands(providers, yield* usageLimitSources.current)
2508
: providers;
2456
- const { instanceId, cwd } = input;
2509
if (instanceId === undefined || cwd === undefined) {
2510
return { providers: withoutWorkspaceSnapshots(commandProviders) };
2511
}
@@ -2463,14 +2515,23 @@ export const layerWsRpc = (
2515
return {
2516
providers: commandProviders
2517
.filter((provider) => provider.instanceId === instanceId)
2466
- .map((provider) => ({
2467
- ...provider,
2468
- // Callers read only the cwd snapshot; the config stream carries the rest.
2469
- models: [],
2470
- slashCommands: [],
2471
- skills: [],
2472
- workspaceSnapshots: workspaceSnapshotOrCatalog(provider, cwd, catalogOnDemand),
2473
- })),
2518
+ .map((provider) => {
2519
+ const catalog =
2520
+ catalogOnDemand && input.machineCatalog === true
2521
+ ? machineCatalogNames(provider)
2522
+ : undefined;
2523
+ return {
2524
+ ...provider,
2525
+ // Callers read only the cwd snapshot; the config stream carries the rest.
2526
+ models: [],
2527
+ slashCommands: catalog?.slashCommands ?? [],
2528
+ skills: catalog?.skills ?? [],
2529
+ ...(catalog === undefined
2530
+ ? {}
2531
+ : { catalogDigest: machineCatalogDigest(provider) }),
2532
+ workspaceSnapshots: workspaceSnapshotOrCatalog(provider, cwd, catalogOnDemand),
2533
+ };
2534
+ }),
2535
};
2536
}),
2537
[WS_METHODS.mcpAppsCallTool]: (input) => mcpAppRequests.callTool(input),
@@ -3222,6 +3283,7 @@ export const layerWsRpc = (
3283
),
3284
)
3285
: Effect.succeed(new Set<string>());
3286
+ const catalogDigests = input.providerCatalogDigests === true;
3287
// Buffer changes through discovery and the initial snapshot's send.
3288
const keybindingsChanges = yield* keybindings.subscribeChanges;
3289
const settingsChanges = yield* serverSettings.subscribeChanges;
@@ -3239,6 +3301,7 @@ export const layerWsRpc = (
3301
workspaceSnapshotsOnDemand,
3302
deferNetworkDiscovery: true,
3303
catalogsPerCwd: yield* currentCatalogsPerCwd,
3304
+ catalogDigests,
3305
});
3306
const keybindingsUpdates = keybindingsChanges.pipe(
3307
Stream.map((event) => ({
@@ -3269,7 +3332,11 @@ export const layerWsRpc = (
3332
workspaceSnapshotsOnDemand
3333
? currentCatalogsPerCwd.pipe(
3334
Effect.map((catalogsPerCwd) =>
3272
- withoutWorkspaceSnapshots(commandProviders, catalogsPerCwd),
3335
+ withoutWorkspaceSnapshots(
3336
+ commandProviders,
3337
+ catalogsPerCwd,
3338
+ catalogDigests,
3339
+ ),
3340
),
3341
)
3342
: Effect.succeed(commandProviders),
@@ -3335,19 +3402,22 @@ export const layerWsRpc = (
3402
remoteResult?._tag === "Success"
3403
? { ...config, remoteOpenTargets: remoteResult.value }
3404
: config;
3405
+ const updates = withLateConfigDiscovery(
3406
+ initialConfig,
3407
+ liveUpdates,
3408
+ externalLauncher,
3409
+ {
3410
+ resolveTargets: () => Fiber.join(remoteTargets),
3411
+ },
3412
+ { resolve: () => Fiber.join(directResult) },
3413
+ );
3414
return Stream.concat(
3415
rpcInitialItems([
3416
{ version: 1 as const, type: "snapshot" as const, config: initialConfig },
3417
]),
3342
- withLateConfigDiscovery(
3343
- initialConfig,
3344
- liveUpdates,
3345
- externalLauncher,
3346
- {
3347
- resolveTargets: () => Fiber.join(remoteTargets),
3348
- },
3349
- { resolve: () => Fiber.join(directResult) },
3350
- ),
3418
+ input.providerStatusDeltas === true
3419
+ ? updates.pipe(withProviderStatusDeltas(initialConfig.providers))
3420
+ : updates,
3421
);
3422
}),
3423
),
docs/internals/performance-regressions.md
+5
@@ -74,6 +74,11 @@ bounded snapshot for a thread of 40 finished runs behind one working run, so fin
74
ride along with a window. When clients gain an opt-in, add it to the test's client queries and give
75
a fixture the data it saves.
76
77
+The server config has its own budget in `apps/server/src/ws.test.ts`. A client that asks for
78
+catalog digests and status deltas gets the provider list of its first config in under 1 KiB, for a
79
+provider with 250 slash commands and 200 skills. The lists load with the first cwd snapshot, and a
80
+machine refresh sends back an empty provider list.
81
+
82
## Event store and startup
83
84
Sequence cursors must seek an index rather than scan retained history. The application sequence
packages/client-runtime/src/rpc/session.test.ts
+33
-5
@@ -5,6 +5,7 @@ import {
5
type ServerConfig as ServerConfigType,
6
ServerConfigStreamEvent,
7
type ServerConfigStreamEvent as ServerConfigStreamEventType,
8
+ ServerProvider,
9
WS_METHODS,
10
UsageLimitSourceId,
11
} from "@t3tools/contracts";
@@ -184,6 +185,18 @@ const SOURCE_SERVER_CONFIG: ServerConfigType = {
185
capabilities: { ...THEME_SERVER_CONFIG.environment.capabilities, usageLimitSources: true },
186
},
187
};
188
+const PROVIDER = Schema.decodeSync(ServerProvider)({
189
+ instanceId: "codex",
190
+ driver: "codex",
191
+ enabled: true,
192
+ installed: true,
193
+ version: "1.0.0",
194
+ status: "ready",
195
+ auth: { status: "authenticated" },
196
+ checkedAt: "2026-04-10T00:00:00.000Z",
197
+ models: [{ slug: "gpt", name: "GPT", isCustom: false, capabilities: null }],
198
+ slashCommands: [{ name: "compact" }],
199
+});
200
const SOURCE_EVENT: ServerConfigStreamEventType = {
201
version: 1,
202
type: "usageLimitSourcesUpdated",
@@ -673,10 +686,11 @@ describe("RpcSessionFactory", () => {
686
const readyFiber = yield* Effect.forkChild(session.ready);
687
const socket = yield* awaitSocket(sockets);
688
socket.open();
676
- yield* completeInitialConfig(socket, encodeServerConfig(SOURCE_SERVER_CONFIG), {
677
- environmentThemes: true,
678
- usageLimitSources: true,
679
- });
689
+ yield* completeInitialConfig(
690
+ socket,
691
+ encodeServerConfig({ ...SOURCE_SERVER_CONFIG, providers: [PROVIDER] }),
692
+ { environmentThemes: true, usageLimitSources: true },
693
+ );
694
yield* Fiber.join(readyFiber);
695
696
const slowSubscriberStarted = yield* Deferred.make<void>();
@@ -736,7 +750,16 @@ describe("RpcSessionFactory", () => {
750
SOURCE_EVENT,
751
{ version: 1, type: "usageLimitSourcesUpdated", payload: { sources: [] } },
752
];
739
- const allEvents = [...themeEvents, ...sourceEvents, ...settingsEvents];
753
+ // A delta carries no lists; a subscriber that misses it must still get its result.
754
+ const { models: _models, slashCommands: _commands, skills: _skills, ...status } = PROVIDER;
755
+ const providerEvent: ServerConfigStreamEventType = {
756
+ version: 1,
757
+ type: "providerStatusDeltas",
758
+ payload: {
759
+ providers: [{ ...status, checkedAt: "2026-04-10T00:05:00.000Z", message: "Checked" }],
760
+ },
761
+ };
762
+ const allEvents = [providerEvent, ...themeEvents, ...sourceEvents, ...settingsEvents];
763
const observedByFastSubscriber = yield* Queue.unbounded<ServerConfigStreamEventType>();
764
yield* session
765
.subscribeServerConfig({ environmentThemes: true, usageLimitSources: true })
@@ -758,6 +781,11 @@ describe("RpcSessionFactory", () => {
781
"environmentThemesUpdated",
782
"usageLimitSourcesUpdated",
783
]);
784
+ expect(recovered[1]).toMatchObject({
785
+ config: {
786
+ providers: [{ ...PROVIDER, checkedAt: "2026-04-10T00:05:00.000Z", message: "Checked" }],
787
+ },
788
+ });
789
expect(recovered[2]).toMatchObject({ payload: { themes: [] } });
790
expect(recovered[3]).toMatchObject({ payload: { sources: [] } });
791
packages/client-runtime/src/rpc/session.ts
+4
@@ -67,6 +67,8 @@ export interface RpcSessionOptions {
67
readonly usageLimitSources?: boolean;
68
readonly usageLimitsCommand?: boolean;
69
readonly providerCatalogsOnDemand?: boolean;
70
+ readonly providerCatalogDigests?: boolean;
71
+ readonly providerStatusDeltas?: boolean;
72
}
73
74
export class RpcSessionFactory extends Context.Service<
@@ -177,6 +179,8 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
179
...(options.usageLimitSources === true ? { usageLimitSources: true } : {}),
180
...(options.usageLimitsCommand === true ? { usageLimitsCommand: true } : {}),
181
...(options.providerCatalogsOnDemand === true ? { providerCatalogsOnDemand: true } : {}),
182
+ ...(options.providerCatalogDigests === true ? { providerCatalogDigests: true } : {}),
183
+ ...(options.providerStatusDeltas === true ? { providerStatusDeltas: true } : {}),
184
};
185
// Config state merges the snapshots it fetches back in, so no subscriber needs them broadcast.
186
const onDemandSnapshots = (input: ServerConfigSubscriptionInput) => ({
packages/client-runtime/src/state/runtime.ts
+5
-1
@@ -1024,6 +1024,8 @@ export function createEnvironmentRpcCommand<
1024
) => Started;
1025
readonly execute?: (
1026
input: Input,
1027
+ registry: AtomRegistry.AtomRegistry,
1028
+ environmentId: EnvironmentIdType,
1029
) => Effect.Effect<
1030
EnvironmentRpcSuccess<TTag>,
1031
EnvironmentRpcFailure<TTag> | EnvironmentRpcUnavailableError,
@@ -1068,7 +1070,9 @@ export function createEnvironmentRpcCommand<
1070
return permissions.authorize(registry, environmentId, input).pipe(
1071
Effect.andThen(() => {
1072
started = options.onStart?.(target, registry);
1071
- return options.execute?.(input) ?? requestGuarded(options.tag, input);
1073
+ return (
1074
+ options.execute?.(input, registry, environmentId) ?? requestGuarded(options.tag, input)
1075
+ );
1076
}),
1077
Effect.provideService(RpcPermissionGuard, {
1078
authorize: (id, method, payload) =>
packages/client-runtime/src/state/server.test.ts
+110
-5
@@ -52,6 +52,7 @@ import type { RpcSession } from "../rpc/session.ts";
52
import {
53
applyServerWelcomeEvent,
54
createServerEnvironmentAtoms,
55
+ type FetchedMachineCatalog,
56
makeEnvironmentServerWelcomeState,
57
makeEnvironmentServerConfigState,
58
isLegacyUpdateHandoffLoss,
@@ -398,6 +399,7 @@ describe("accepted server update recovery", () => {
399
400
const makeConfigPersistenceHarness = Effect.fn("test.makeConfigPersistenceHarness")(function* (
401
saveServerConfig: Persistence.EnvironmentCacheStore["Service"]["saveServerConfig"],
402
+ machineCatalogs?: Stream.Stream<ReadonlyArray<FetchedMachineCatalog>>,
403
) {
404
const events = yield* Queue.unbounded<ServerConfigStreamEvent>();
405
const client = {
@@ -426,10 +428,10 @@ const makeConfigPersistenceHarness = Effect.fn("test.makeConfigPersistenceHarnes
428
clearVcsRefs: () => Effect.void,
429
clear: () => Effect.void,
430
});
429
- const state = yield* makeEnvironmentServerConfigState({
430
- environmentThemes: true,
431
- usageLimitSources: true,
432
- }).pipe(
431
+ const state = yield* makeEnvironmentServerConfigState(
432
+ { environmentThemes: true, usageLimitSources: true },
433
+ machineCatalogs,
434
+ ).pipe(
435
Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
436
Effect.provideService(Persistence.EnvironmentCacheStore, cache),
437
);
@@ -443,7 +445,7 @@ const makeConfigPersistenceHarness = Effect.fn("test.makeConfigPersistenceHarnes
445
Effect.map(Option.getOrThrow),
446
);
447
});
446
- return { send };
448
+ return { send, state };
449
});
450
451
describe("server state projection", () => {
@@ -606,6 +608,92 @@ describe("server state projection", () => {
608
}),
609
);
610
611
+ it.effect("caches the lists a cwd snapshot loaded for a catalog digest", () =>
612
+ Effect.gen(function* () {
613
+ const saved = yield* Ref.make<ReadonlyArray<ServerConfig>>([]);
614
+ const catalogs = yield* Queue.unbounded<ReadonlyArray<FetchedMachineCatalog>>();
615
+ const instanceId = ProviderInstanceId.make("claudeAgent");
616
+ const otherInstanceId = ProviderInstanceId.make("codex");
617
+ const thirdInstanceId = ProviderInstanceId.make("cursor");
618
+ const slashCommands = [{ name: "compact" }];
619
+ // What the server sends: a digest in place of the two lists.
620
+ const snapshot = (catalogDigest = "d1") =>
621
+ snapshotEvent({
622
+ ...CONFIG,
623
+ providers: [
624
+ { instanceId, slashCommands: [], skills: [], catalogDigest },
625
+ { instanceId: otherInstanceId, slashCommands: [], skills: [], catalogDigest: "c1" },
626
+ { instanceId: thirdInstanceId, slashCommands: [], skills: [], catalogDigest: "t1" },
627
+ ],
628
+ } as unknown as ServerConfig);
629
+ yield* Effect.scoped(
630
+ Effect.gen(function* () {
631
+ const h = yield* makeConfigPersistenceHarness(
632
+ (_id, config) => Ref.update(saved, (values) => [...values, config]),
633
+ Stream.fromQueue(catalogs),
634
+ );
635
+ yield* h.send(snapshot());
636
+ yield* Queue.offer(catalogs, [{ instanceId, digest: "d1", slashCommands, skills: [] }]);
637
+ const loaded = yield* SubscriptionRef.changes(h.state).pipe(
638
+ Stream.map((value) => Option.getOrThrow(value).config.providers[0]),
639
+ Stream.filter((provider) => provider?.loadedCatalogDigest === "d1"),
640
+ Stream.runHead,
641
+ );
642
+ expect(Option.getOrThrow(loaded)?.slashCommands).toEqual(slashCommands);
643
+
644
+ yield* TestClock.adjust("10 seconds");
645
+ expect((yield* Ref.get(saved)).at(-1)?.providers[0]).toMatchObject({
646
+ slashCommands,
647
+ loadedCatalogDigest: "d1",
648
+ });
649
+
650
+ // A reconnect sends the digest again, and the loaded lists stay.
651
+ const reconnected = yield* h.send(snapshot());
652
+ expect(reconnected.config.providers[0]).toMatchObject({
653
+ slashCommands,
654
+ loadedCatalogDigest: "d1",
655
+ });
656
+
657
+ // A reply for an older catalog that lands late does not replace the current lists.
658
+ const late = { instanceId, digest: "d0", slashCommands: [{ name: "old" }], skills: [] };
659
+ yield* Queue.offer(catalogs, [late]);
660
+ yield* Queue.offer(catalogs, [
661
+ late,
662
+ { instanceId: otherInstanceId, digest: "c1", slashCommands: [], skills: [] },
663
+ ]);
664
+ const settled = yield* SubscriptionRef.changes(h.state).pipe(
665
+ Stream.map((value) => Option.getOrThrow(value).config.providers),
666
+ Stream.filter((providers) => providers[1]?.loadedCatalogDigest === "c1"),
667
+ Stream.runHead,
668
+ );
669
+ expect(Option.getOrThrow(settled)[0]).toMatchObject({
670
+ slashCommands,
671
+ loadedCatalogDigest: "d1",
672
+ });
673
+
674
+ // A reply for a newer catalog can land before the config names its digest. It is
675
+ // kept, and applies when the config does.
676
+ const newer = { instanceId, digest: "d2", slashCommands: [{ name: "new" }], skills: [] };
677
+ yield* Queue.offer(catalogs, [
678
+ newer,
679
+ { instanceId: thirdInstanceId, digest: "t1", slashCommands: [], skills: [] },
680
+ ]);
681
+ const kept = yield* SubscriptionRef.changes(h.state).pipe(
682
+ Stream.map((value) => Option.getOrThrow(value).config.providers),
683
+ Stream.filter((providers) => providers[2]?.loadedCatalogDigest === "t1"),
684
+ Stream.runHead,
685
+ );
686
+ expect(Option.getOrThrow(kept)[0]).toMatchObject({ loadedCatalogDigest: "d1" });
687
+ const advanced = yield* h.send(snapshot("d2"));
688
+ expect(advanced.config.providers[0]).toMatchObject({
689
+ slashCommands: newer.slashCommands,
690
+ loadedCatalogDigest: "d2",
691
+ });
692
+ }),
693
+ );
694
+ }),
695
+ );
696
+
697
it.effect("flushes pending durable changes after a transient event", () =>
698
Effect.gen(function* () {
699
const saved = yield* Ref.make<ReadonlyArray<ServerConfig>>([]);
@@ -1198,6 +1286,23 @@ describe("server state projection", () => {
1286
).providers[0]?.workspaceSnapshots,
1287
).toBeUndefined();
1288
1289
+ // A catalog digest stands for the lists: loading them keeps the snapshot, a new digest retires it.
1290
+ const digested = (catalogDigest: string, slashCommands: ReadonlyArray<{ name: string }> = []) =>
1291
+ ({ ...provider(claude, undefined, slashCommands), catalogDigest }) as ReturnType<
1292
+ typeof provider
1293
+ >;
1294
+ const fetchedByDigest = recordFetchedWorkspaceSnapshot(
1295
+ [],
1296
+ { instanceId: claude, cwd: "/a", fresh: false },
1297
+ [provider(claude, [claudeA])],
1298
+ digested("d1"),
1299
+ );
1300
+ const snapshotsFor = (current: ReturnType<typeof provider>) =>
1301
+ withFetchedWorkspaceSnapshots(configWith(true, [current]), fetchedByDigest).providers[0]
1302
+ ?.workspaceSnapshots;
1303
+ expect(snapshotsFor(digested("d1", [{ name: "loaded" }]))).toEqual([claudeA]);
1304
+ expect(snapshotsFor(digested("d2"))).toBeUndefined();
1305
+
1306
// Older servers send every snapshot and every drop; their config stands.
1307
const legacy = configWith(false, [provider(claude)]);
1308
expect(withFetchedWorkspaceSnapshots(legacy, fetched)).toBe(legacy);
packages/client-runtime/src/state/server.ts
+139
-21
@@ -25,7 +25,7 @@ import * as Result from "effect/Result";
25
import * as Schema from "effect/Schema";
26
import * as Stream from "effect/Stream";
27
import * as SubscriptionRef from "effect/SubscriptionRef";
28
-import { AsyncResult, Atom } from "effect/reactivity";
28
+import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
29
30
import {
31
createAtomCommandScheduler,
@@ -378,6 +378,45 @@ export interface ServerConfigSubscriptionOptions {
378
readonly usageLimitSources?: boolean;
379
readonly usageLimitsCommand?: boolean;
380
readonly providerCatalogsOnDemand?: boolean;
381
+ readonly providerCatalogDigests?: boolean;
382
+ readonly providerStatusDeltas?: boolean;
383
+}
384
+
385
+type ServerProviderEntry = ServerConfig["providers"][number];
386
+
387
+/** Machine slash commands and skills a cwd snapshot reply carried, with the digest they belong to. */
388
+export interface FetchedMachineCatalog {
389
+ readonly instanceId: ProviderInstanceId;
390
+ readonly digest: string;
391
+ readonly slashCommands: ServerProviderEntry["slashCommands"];
392
+ readonly skills: ServerProviderEntry["skills"];
393
+}
394
+
395
+function withFetchedMachineCatalogs(
396
+ projection: ServerConfigProjection,
397
+ catalogs: ReadonlyArray<FetchedMachineCatalog>,
398
+): ServerConfigProjection {
399
+ let changed = false;
400
+ const providers = projection.config.providers.map((provider) => {
401
+ const catalog = catalogs.find((entry) => entry.instanceId === provider.instanceId);
402
+ // Only the lists of the live catalog apply. A reply for an older one is dropped, and a
403
+ // reply that lands before the config names its digest applies when the config does.
404
+ if (
405
+ catalog === undefined ||
406
+ catalog.digest !== provider.catalogDigest ||
407
+ provider.loadedCatalogDigest === catalog.digest
408
+ ) {
409
+ return provider;
410
+ }
411
+ changed = true;
412
+ return {
413
+ ...provider,
414
+ slashCommands: catalog.slashCommands,
415
+ skills: catalog.skills,
416
+ loadedCatalogDigest: catalog.digest,
417
+ };
418
+ });
419
+ return changed ? { ...projection, config: { ...projection.config, providers } } : projection;
420
}
421
422
// Configs are JSON-shaped. Missing and undefined object fields persist identically.
@@ -416,7 +455,11 @@ function sameCacheValue(previous: unknown, next: unknown): boolean {
455
}
456
457
export const makeEnvironmentServerConfigState = Effect.fn("EnvironmentServerConfigState.make")(
419
- function* (subscription: ServerConfigSubscriptionOptions) {
458
+ function* (
459
+ subscription: ServerConfigSubscriptionOptions,
460
+ // Merged into the state, so the cache keeps the lists for the next launch and for offline.
461
+ machineCatalogs: Stream.Stream<ReadonlyArray<FetchedMachineCatalog>> = Stream.empty,
462
+ ) {
463
const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor;
464
const cache = yield* Persistence.EnvironmentCacheStore;
465
const environmentId = supervisor.target.environmentId;
@@ -495,16 +538,44 @@ export const makeEnvironmentServerConfigState = Effect.fn("EnvironmentServerConf
538
539
yield* runCachePersistence(persistence, persistPending).pipe(Effect.forkScoped);
540
498
- yield* subscribe(WS_METHODS.subscribeServerConfig, {
541
+ type Update = (
542
+ current: Option.Option<ServerConfigProjection>,
543
+ ) => Option.Option<ServerConfigProjection>;
544
+ // Written and read inside the one update loop below.
545
+ let fetchedCatalogs: ReadonlyArray<FetchedMachineCatalog> = [];
546
+ const configUpdates = subscribe(WS_METHODS.subscribeServerConfig, {
547
...(subscription.environmentThemes === true ? { environmentThemes: true } : {}),
548
...(subscription.usageLimitSources === true ? { usageLimitSources: true } : {}),
549
...(subscription.usageLimitsCommand === true ? { usageLimitsCommand: true } : {}),
550
...(subscription.providerCatalogsOnDemand === true ? { providerCatalogsOnDemand: true } : {}),
551
+ ...(subscription.providerCatalogDigests === true ? { providerCatalogDigests: true } : {}),
552
+ ...(subscription.providerStatusDeltas === true ? { providerStatusDeltas: true } : {}),
553
}).pipe(
504
- Stream.runForEach((event) =>
554
+ Stream.map((event): Update => (current) => {
555
+ const next = applyServerConfigProjection(current, event);
556
+ return fetchedCatalogs.length === 0
557
+ ? next
558
+ : Option.map(next, (projection) =>
559
+ withFetchedMachineCatalogs(projection, fetchedCatalogs),
560
+ );
561
+ }),
562
+ );
563
+ const catalogUpdates = machineCatalogs.pipe(
564
+ Stream.map((catalogs): Update => (current) => {
565
+ fetchedCatalogs = catalogs;
566
+ return Option.map(current, (projection) =>
567
+ withFetchedMachineCatalogs(projection, catalogs),
568
+ );
569
+ }),
570
+ );
571
+
572
+ // One loop for both sources, so a fetched catalog never overwrites a newer config event.
573
+ yield* Stream.merge(configUpdates, catalogUpdates).pipe(
574
+ Stream.runForEach((update) =>
575
Effect.gen(function* () {
506
- const next = applyServerConfigProjection(yield* SubscriptionRef.get(state), event);
507
- if (Option.isNone(next)) {
576
+ const current = yield* SubscriptionRef.get(state);
577
+ const next = update(current);
578
+ if (Option.isNone(next) || next.value === Option.getOrUndefined(current)) {
579
return;
580
}
581
yield* Ref.set(pendingPersistence, Option.some(next.value.config));
@@ -522,11 +593,12 @@ export const makeEnvironmentServerConfigState = Effect.fn("EnvironmentServerConf
593
function serverConfigStateChanges(
594
environmentId: EnvironmentId,
595
subscription: ServerConfigSubscriptionOptions,
596
+ machineCatalogs: Stream.Stream<ReadonlyArray<FetchedMachineCatalog>>,
597
) {
598
return followStreamInEnvironment(
599
environmentId,
600
Stream.unwrap(
529
- makeEnvironmentServerConfigState(subscription).pipe(
601
+ makeEnvironmentServerConfigState(subscription, machineCatalogs).pipe(
602
Effect.map((state) =>
603
SubscriptionRef.changes(state).pipe(
604
Stream.filterMap((projection) =>
@@ -671,8 +743,6 @@ export function resolveServerConfigValue(
743
return initialConfig ?? projection?.config ?? null;
744
}
745
674
-type ServerProviderEntry = ServerConfig["providers"][number];
675
-
746
/**
747
* The provider-wide fields a workspace snapshot builds on. A live session, a sign-out, or a
748
* /usage-limits change shows up here, so a snapshot fetched before it no longer applies.
@@ -681,8 +751,10 @@ const snapshotBasis = (provider: ServerProviderEntry | undefined) =>
751
provider && {
752
enabled: provider.enabled,
753
models: provider.models,
684
- slashCommands: provider.slashCommands,
685
- skills: provider.skills,
754
+ // The digest stands for the lists, which load with a snapshot and must not unseat it.
755
+ ...(provider.catalogDigest === undefined
756
+ ? { slashCommands: provider.slashCommands, skills: provider.skills }
757
+ : { catalogDigest: provider.catalogDigest }),
758
};
759
760
interface FetchedWorkspaceSnapshot {
@@ -771,6 +843,10 @@ export function createServerEnvironmentAtoms<R, E>(
843
readonly usageLimitSources?: boolean;
844
readonly usageLimitsCommand?: boolean;
845
readonly providerCatalogsOnDemand?: boolean;
846
+ readonly providerCatalogDigests?: boolean;
847
+ readonly providerStatusDeltas?: boolean;
848
+ /** Machine refresh replies carry no providers; the config stream already delivers them. */
849
+ readonly omitRefreshedProviders?: boolean;
850
},
851
) {
852
const configScheduler = createAtomCommandScheduler();
@@ -779,15 +855,30 @@ export function createServerEnvironmentAtoms<R, E>(
855
mode: "serial" as const,
856
key: ({ environmentId }: { readonly environmentId: string }) => environmentId,
857
};
858
+ const fetchedMachineCatalogsAtom = Atom.family((environmentId: EnvironmentId) =>
859
+ Atom.make<ReadonlyArray<FetchedMachineCatalog>>([]).pipe(
860
+ Atom.keepAlive,
861
+ Atom.withLabel(`environment-data:server:fetched-machine-catalogs:${environmentId}`),
862
+ ),
863
+ );
864
const configProjectionFamily = Atom.family((environmentId: EnvironmentId) =>
865
runtime
784
- .atom(
785
- serverConfigStateChanges(environmentId, {
786
- ...(options.environmentThemes === true ? { environmentThemes: true } : {}),
787
- ...(options.usageLimitSources === true ? { usageLimitSources: true } : {}),
788
- ...(options.usageLimitsCommand === true ? { usageLimitsCommand: true } : {}),
789
- ...(options.providerCatalogsOnDemand === true ? { providerCatalogsOnDemand: true } : {}),
790
- }),
866
+ .atom((get) =>
867
+ serverConfigStateChanges(
868
+ environmentId,
869
+ {
870
+ ...(options.environmentThemes === true ? { environmentThemes: true } : {}),
871
+ ...(options.usageLimitSources === true ? { usageLimitSources: true } : {}),
872
+ ...(options.usageLimitsCommand === true ? { usageLimitsCommand: true } : {}),
873
+ ...(options.providerCatalogsOnDemand === true
874
+ ? { providerCatalogsOnDemand: true }
875
+ : {}),
876
+ ...(options.providerCatalogDigests === true ? { providerCatalogDigests: true } : {}),
877
+ ...(options.providerStatusDeltas === true ? { providerStatusDeltas: true } : {}),
878
+ },
879
+ // Scoped to the stream, which restarts with every new session.
880
+ AtomRegistry.toStream(get.registry, fetchedMachineCatalogsAtom(environmentId)),
881
+ ),
882
)
883
.pipe(
884
Atom.setIdleTTL(5 * 60_000),
@@ -1476,17 +1567,44 @@ export function createServerEnvironmentAtoms<R, E>(
1567
refreshProviders: createEnvironmentRpcCommand(runtime, {
1568
label: "environment-data:server:refresh-providers",
1569
tag: WS_METHODS.serverRefreshProviders,
1479
- execute: (input) =>
1480
- requestGuarded(WS_METHODS.serverRefreshProviders, {
1570
+ execute: (input, registry, environmentId) => {
1571
+ const { instanceId, cwd } = input;
1572
+ const provider =
1573
+ instanceId === undefined || cwd === undefined
1574
+ ? undefined
1575
+ : registry
1576
+ .get(configValueAtom(environmentId))
1577
+ ?.providers.find((candidate) => candidate.instanceId === instanceId);
1578
+ return requestGuarded(WS_METHODS.serverRefreshProviders, {
1579
...input,
1580
workspaceSnapshotsOnDemand: true,
1581
...(options.usageLimitsCommand === true ? { usageLimitsCommand: true } : {}),
1582
...(options.providerCatalogsOnDemand === true ? { providerCatalogsOnDemand: true } : {}),
1485
- }),
1583
+ ...(options.omitRefreshedProviders === true ? { omitProviders: true } : {}),
1584
+ // The held lists are stale or missing, so the cwd snapshot brings the current ones.
1585
+ ...(provider?.catalogDigest !== undefined &&
1586
+ provider.loadedCatalogDigest !== provider.catalogDigest
1587
+ ? { machineCatalog: true }
1588
+ : {}),
1589
+ });
1590
+ },
1591
onSuccess: ({ environmentId, input }, registry, result) =>
1592
Effect.sync(() => {
1593
const { instanceId, cwd } = input;
1594
if (instanceId === undefined || cwd === undefined) return;
1595
+ const refreshed = result.providers.find((provider) => provider.instanceId === instanceId);
1596
+ if (refreshed?.catalogDigest !== undefined) {
1597
+ const catalog = {
1598
+ instanceId,
1599
+ digest: refreshed.catalogDigest,
1600
+ slashCommands: refreshed.slashCommands,
1601
+ skills: refreshed.skills,
1602
+ };
1603
+ registry.update(fetchedMachineCatalogsAtom(environmentId), (current) => [
1604
+ ...current.filter((entry) => entry.instanceId !== instanceId),
1605
+ catalog,
1606
+ ]);
1607
+ }
1608
registry.update(fetchedWorkspaceSnapshotsAtom(environmentId), (current) =>
1609
recordFetchedWorkspaceSnapshot(
1610
current,
packages/client-runtime/src/state/serverConfigProjection.test.ts
+57
@@ -79,3 +79,60 @@ describe("applyServerConfigProjection settingsUpdated", () => {
79
expect(Option.getOrThrow(next).config).toBe(Option.getOrThrow(current).config);
80
});
81
});
82
+
83
+describe("applyServerConfigProjection provider catalogs", () => {
84
+ const provider = (fields: Record<string, unknown>) =>
85
+ ({
86
+ instanceId: "claude",
87
+ checkedAt: "a",
88
+ models: [],
89
+ ...fields,
90
+ }) as unknown as ServerConfig["providers"][number];
91
+ const projection = (providers: ServerConfig["providers"]) =>
92
+ Option.some({
93
+ config: { providers } as unknown as ServerConfig,
94
+ latestEvent: {} as ServerConfigStreamEvent,
95
+ source: "cache" as const,
96
+ });
97
+ const apply = (current: ReturnType<typeof projection>, event: unknown) =>
98
+ Option.getOrThrow(applyServerConfigProjection(current, event as ServerConfigStreamEvent)).config
99
+ .providers[0]!;
100
+
101
+ it("keeps held slash commands and skills when the server sends a digest in their place", () => {
102
+ const slashCommands = [{ name: "compact" }];
103
+ const skills = [{ name: "review", path: "/skills/review", enabled: true }];
104
+ const held = provider({
105
+ slashCommands,
106
+ skills,
107
+ catalogDigest: "d1",
108
+ loadedCatalogDigest: "d1",
109
+ });
110
+ const sent = (fields: Record<string, unknown>) =>
111
+ provider({ slashCommands: [], skills: [], catalogDigest: "d1", ...fields });
112
+
113
+ const reconnected = apply(projection([held]), {
114
+ type: "snapshot",
115
+ config: { providers: [sent({ checkedAt: "b" })] },
116
+ });
117
+ expect(reconnected).toMatchObject({ checkedAt: "b", loadedCatalogDigest: "d1" });
118
+ expect(reconnected.slashCommands).toBe(slashCommands);
119
+ expect(reconnected.skills).toBe(skills);
120
+
121
+ // A changed catalog keeps the stale lists; the old marker says they need a reload.
122
+ const { slashCommands: _c, skills: _s, ...delta } = sent({ catalogDigest: "d2" });
123
+ const changed = apply(projection([held]), {
124
+ type: "providerStatusDeltas",
125
+ payload: { providers: [delta] },
126
+ });
127
+ expect(changed).toMatchObject({ catalogDigest: "d2", loadedCatalogDigest: "d1" });
128
+ expect(changed.skills).toBe(skills);
129
+
130
+ // Lists cached before digests existed carry over without a marker.
131
+ const legacy = apply(projection([provider({ slashCommands, skills })]), {
132
+ type: "providerStatuses",
133
+ payload: { providers: [sent({})] },
134
+ });
135
+ expect(legacy.slashCommands).toBe(slashCommands);
136
+ expect(legacy.loadedCatalogDigest).toBeUndefined();
137
+ });
138
+});
packages/client-runtime/src/state/serverConfigProjection.ts
+53
-9
@@ -1,4 +1,8 @@
1
-import type { ServerConfig, ServerConfigStreamEvent } from "@t3tools/contracts";
1
+import {
2
+ applyServerProviderDeltas,
3
+ type ServerConfig,
4
+ type ServerConfigStreamEvent,
5
+} from "@t3tools/contracts";
6
import * as Equal from "effect/Equal";
7
import * as Option from "effect/Option";
8
@@ -61,6 +65,34 @@ export function reuseUnchanged<T>(previous: unknown, next: T): T {
65
return (same ? previous : merged) as T;
66
}
67
68
+type ServerProviders = ServerConfig["providers"];
69
+
70
+/**
71
+ * A provider sent with a catalog digest comes without its slash commands and skills. Keep the
72
+ * lists this client holds, stale ones too, until it loads the lists the digest stands for.
73
+ */
74
+function withHeldProviderCatalogs(
75
+ previous: ServerProviders | undefined,
76
+ next: ServerProviders,
77
+): ServerProviders {
78
+ if (previous === undefined) return next;
79
+ return next.map((provider) => {
80
+ if (provider.catalogDigest === undefined || provider.loadedCatalogDigest !== undefined) {
81
+ return provider;
82
+ }
83
+ const held = previous.find((candidate) => candidate.instanceId === provider.instanceId);
84
+ if (held === undefined) return provider;
85
+ return {
86
+ ...provider,
87
+ slashCommands: held.slashCommands,
88
+ skills: held.skills,
89
+ ...(held.loadedCatalogDigest === undefined
90
+ ? {}
91
+ : { loadedCatalogDigest: held.loadedCatalogDigest }),
92
+ };
93
+ });
94
+}
95
+
96
export function applyServerConfigProjection(
97
current: Option.Option<ServerConfigProjection>,
98
event: ServerConfigStreamEvent,
@@ -77,6 +109,10 @@ export function applyServerConfigProjection(
109
: undefined;
110
const config: ServerConfig = {
111
...event.config,
112
+ providers: withHeldProviderCatalogs(
113
+ Option.getOrUndefined(current)?.config.providers,
114
+ event.config.providers,
115
+ ),
116
...(carriedThemes === undefined ? {} : { environmentThemes: carriedThemes }),
117
...(carriedSources === undefined ? {} : { usageLimitSources: carriedSources }),
118
};
@@ -98,14 +134,22 @@ export function applyServerConfigProjection(
134
source: "live",
135
}));
136
case "providerStatuses":
101
- return Option.map(current, (projection) => ({
102
- config: {
103
- ...projection.config,
104
- providers: reuseUnchanged(projection.config.providers, event.payload.providers),
105
- },
106
- latestEvent: event,
107
- source: "live",
108
- }));
137
+ case "providerStatusDeltas":
138
+ return Option.map(current, (projection) => {
139
+ const previous = projection.config.providers;
140
+ const providers =
141
+ event.type === "providerStatuses"
142
+ ? event.payload.providers
143
+ : applyServerProviderDeltas(previous, event.payload.providers);
144
+ return {
145
+ config: {
146
+ ...projection.config,
147
+ providers: reuseUnchanged(previous, withHeldProviderCatalogs(previous, providers)),
148
+ },
149
+ latestEvent: event,
150
+ source: "live",
151
+ };
152
+ });
153
case "settingsUpdated":
154
return Option.map(current, (projection) => {
155
const settings = reuseUnchanged(projection.config.settings, event.payload.settings);
packages/contracts/src/rpc.ts
+17
@@ -674,6 +674,16 @@ export const WsServerRefreshProvidersRpc = Rpc.make(WS_METHODS.serverRefreshProv
674
usageLimitsCommand: Schema.optional(Schema.Boolean),
675
/** As on `subscribeServerConfig`: a failed cwd scan replies with the machine catalog as a pending snapshot. */
676
providerCatalogsOnDemand: Schema.optional(Schema.Boolean),
677
+ /**
678
+ * Reply with no providers; the config stream carries the result. For callers that only wait
679
+ * for the refresh. Ignored with `instanceId` and `cwd`, whose reply is the snapshot.
680
+ */
681
+ omitProviders: Schema.optional(Schema.Boolean),
682
+ /**
683
+ * With `providerCatalogsOnDemand`, a cwd reply also carries the machine slash command names
684
+ * and skills with their `catalogDigest`. Sent by a client whose held lists are not current.
685
+ */
686
+ machineCatalog: Schema.optional(Schema.Boolean),
687
}),
688
success: ServerProviderUpdatedPayload,
689
error: Schema.Union([EnvironmentAuthorizationError, ProviderSetupError]),
@@ -1963,6 +1973,13 @@ export const WsSubscribeServerConfigRpc = Rpc.make(WS_METHODS.subscribeServerCon
1973
workspaceSnapshotsOnDemand: Schema.optional(Schema.Boolean),
1974
/** With on-demand snapshots, also omit machine slash commands and skills a cwd snapshot replaces. */
1975
providerCatalogsOnDemand: Schema.optional(Schema.Boolean),
1976
+ /**
1977
+ * With on-demand catalogs, send a `catalogDigest` in place of the machine slash command names
1978
+ * and skills. The client keeps the lists it holds and loads new ones with a cwd snapshot.
1979
+ */
1980
+ providerCatalogDigests: Schema.optional(Schema.Boolean),
1981
+ /** Send provider changes as `providerStatusDeltas`; older clients reject the event type. */
1982
+ providerStatusDeltas: Schema.optional(Schema.Boolean),
1983
}),
1984
success: ServerConfigStreamEvent,
1985
error: Schema.Union([KeybindingsConfigError, ServerSettingsError, EnvironmentAuthorizationError]),
packages/contracts/src/server.test.ts
+36
@@ -3,10 +3,13 @@ import { describe, expect, it } from "vite-plus/test";
3
4
import { ExecutionEnvironmentDescriptor } from "./environment.ts";
5
import {
6
+ applyServerProviderDeltas,
7
OtlpEndpointCheckInput,
8
resolveEnvironmentMachineKind,
9
+ ServerConfigProviderStatusDeltasPayload,
10
ServerObservability,
11
ServerProvider,
12
+ serverProviderDeltas,
13
ServerProviders,
14
} from "./server.ts";
15
import { ServerSettings } from "./settings.ts";
@@ -41,6 +44,39 @@ describe("ServerProvider", () => {
44
});
45
});
46
47
+describe("provider status deltas", () => {
48
+ it("send a provider's lists only when they change and rebuild the full list", () => {
49
+ const codex = decodeServerProvider({
50
+ ...baseProviderSnapshot,
51
+ models: [{ slug: "gpt", name: "GPT", isCustom: false, capabilities: null }],
52
+ slashCommands: [{ name: "compact" }],
53
+ skills: [{ name: "review", path: "/skills/review", enabled: true }],
54
+ });
55
+ const claude = decodeServerProvider({ ...baseProviderSnapshot, instanceId: "claudeAgent" });
56
+ const previous = [codex];
57
+ const next = [
58
+ claude,
59
+ { ...codex, checkedAt: "2026-04-10T00:05:00.000Z", skills: [], message: "Checked" },
60
+ ];
61
+
62
+ const deltas = serverProviderDeltas(previous, next);
63
+ // Unchanged lists stay home; a provider the reader never saw travels whole.
64
+ expect(deltas[0]).toEqual(claude);
65
+ expect(deltas[1]).not.toHaveProperty("models");
66
+ expect(deltas[1]).not.toHaveProperty("slashCommands");
67
+ expect(deltas[1]).toMatchObject({ skills: [], message: "Checked" });
68
+
69
+ const codec = Schema.toCodecJson(ServerConfigProviderStatusDeltasPayload);
70
+ const wire = JSON.parse(JSON.stringify(Schema.encodeSync(codec)({ providers: deltas })));
71
+ const received = Schema.decodeUnknownSync(codec)(wire).providers;
72
+ // A decoding default would turn the absent slash commands into an empty list.
73
+ expect(received[1]).not.toHaveProperty("slashCommands");
74
+ expect(applyServerProviderDeltas(previous, received)).toEqual(next);
75
+ // Without the provider the delta builds on, its lists are unknown.
76
+ expect(applyServerProviderDeltas([], received)).toEqual([claude]);
77
+ });
78
+});
79
+
80
describe("server config forward compatibility", () => {
81
it("drops providers this build cannot decode instead of failing the whole array", () => {
82
const decodedBase = decodeServerProvider(baseProviderSnapshot);
packages/contracts/src/server.ts
+71
@@ -275,9 +275,64 @@ export const ServerProvider = Schema.Struct({
275
versionAdvisory: Schema.optionalKey(ServerProviderVersionAdvisory),
276
compatibilityAdvisory: Schema.optionalKey(ServerProviderCompatibilityAdvisory),
277
updateState: Schema.optionalKey(ServerProviderUpdateState),
278
+ /**
279
+ * Stands for the machine slash commands and skills, which are then left out. Sent to clients
280
+ * that ask for catalog digests; they load both lists with their next cwd snapshot.
281
+ */
282
+ catalogDigest: Schema.optionalKey(TrimmedNonEmptyString),
283
+ /** Set by the client, never sent: the `catalogDigest` its slash commands and skills belong to. */
284
+ loadedCatalogDigest: Schema.optionalKey(TrimmedNonEmptyString),
285
});
286
export type ServerProvider = typeof ServerProvider.Type;
287
288
+/** A provider without the lists that equal the ones its reader already holds. */
289
+export const ServerProviderDelta = ServerProvider.mapFields((fields) => ({
290
+ ...fields,
291
+ models: Schema.optionalKey(fields.models),
292
+ // Declared again without the decoding default, which would read as a change to an empty list.
293
+ slashCommands: Schema.optionalKey(Schema.Array(ServerProviderSlashCommand)),
294
+ skills: Schema.optionalKey(Schema.Array(ServerProviderSkill)),
295
+}));
296
+export type ServerProviderDelta = typeof ServerProviderDelta.Type;
297
+
298
+const sameJson = (left: unknown, right: unknown) =>
299
+ left === right || JSON.stringify(left) === JSON.stringify(right);
300
+
301
+/** Leaves each provider's models, slash commands, and skills out when `previous` has the same. */
302
+export function serverProviderDeltas(
303
+ previous: ReadonlyArray<ServerProvider>,
304
+ next: ReadonlyArray<ServerProvider>,
305
+): ServerProviderDelta[] {
306
+ const held = new Map(previous.map((provider) => [provider.instanceId, provider]));
307
+ return next.map((provider) => {
308
+ const base = held.get(provider.instanceId);
309
+ if (base === undefined) return provider;
310
+ const { models, slashCommands, skills, ...rest } = provider;
311
+ return {
312
+ ...rest,
313
+ ...(sameJson(base.models, models) ? {} : { models }),
314
+ ...(sameJson(base.slashCommands, slashCommands) ? {} : { slashCommands }),
315
+ ...(sameJson(base.skills, skills) ? {} : { skills }),
316
+ };
317
+ });
318
+}
319
+
320
+/** Rebuilds the provider list `serverProviderDeltas` was made from. */
321
+export function applyServerProviderDeltas(
322
+ previous: ReadonlyArray<ServerProvider>,
323
+ deltas: ReadonlyArray<ServerProviderDelta>,
324
+): ServerProvider[] {
325
+ const held = new Map(previous.map((provider) => [provider.instanceId, provider]));
326
+ return deltas.flatMap((delta) => {
327
+ const base = held.get(delta.instanceId);
328
+ const models = delta.models ?? base?.models;
329
+ const slashCommands = delta.slashCommands ?? base?.slashCommands;
330
+ const skills = delta.skills ?? base?.skills;
331
+ // A list this reader never held cannot be rebuilt; drop the provider like an unreadable one.
332
+ return models && slashCommands && skills ? [{ ...delta, models, slashCommands, skills }] : [];
333
+ });
334
+}
335
+
336
export const ServerProviders = ForwardCompatibleArray(ServerProvider);
337
export type ServerProviders = typeof ServerProviders.Type;
338
@@ -731,6 +786,13 @@ export const ServerConfigProviderStatusesPayload = Schema.Struct({
786
});
787
export type ServerConfigProviderStatusesPayload = typeof ServerConfigProviderStatusesPayload.Type;
788
789
+export const ServerConfigProviderStatusDeltasPayload = Schema.Struct({
790
+ /** Every provider in order, as `serverProviderDeltas` from the list this client last received. */
791
+ providers: ForwardCompatibleArray(ServerProviderDelta),
792
+});
793
+export type ServerConfigProviderStatusDeltasPayload =
794
+ typeof ServerConfigProviderStatusDeltasPayload.Type;
795
+
796
export const ServerConfigSettingsUpdatedPayload = Schema.Struct({
797
settings: ServerSettings,
798
});
@@ -759,6 +821,14 @@ export const ServerConfigStreamProviderStatusesEvent = Schema.Struct({
821
export type ServerConfigStreamProviderStatusesEvent =
822
typeof ServerConfigStreamProviderStatusesEvent.Type;
823
824
+export const ServerConfigStreamProviderStatusDeltasEvent = Schema.Struct({
825
+ version: Schema.Literal(1),
826
+ type: Schema.Literal("providerStatusDeltas"),
827
+ payload: ServerConfigProviderStatusDeltasPayload,
828
+});
829
+export type ServerConfigStreamProviderStatusDeltasEvent =
830
+ typeof ServerConfigStreamProviderStatusDeltasEvent.Type;
831
+
832
export const ServerConfigStreamSettingsUpdatedEvent = Schema.Struct({
833
version: Schema.Literal(1),
834
type: Schema.Literal("settingsUpdated"),
@@ -799,6 +869,7 @@ export const ServerConfigStreamEvent = Schema.Union([
869
ServerConfigStreamSnapshotEvent,
870
ServerConfigStreamKeybindingsUpdatedEvent,
871
ServerConfigStreamProviderStatusesEvent,
872
+ ServerConfigStreamProviderStatusDeltasEvent,
873
ServerConfigStreamSettingsUpdatedEvent,
874
ServerConfigStreamEnvironmentThemesUpdatedEvent,
875
ServerConfigStreamUsageLimitSourcesUpdatedEvent,