@devries-cameron20 / t3code Mirror · read-only / commits / 8b2763f638
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 19:45 UTC

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,