@devries-cameron20 / t3code-1 / commits / 9557ab46c5
Fork 0

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

perf(mobile): thread list resumes from the saved cache, and large gaps reload over gzip HTTP (#32287)

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Julius Marminge committed Nov 8, 2026 at 16:04 UTC 9557ab46c5ebbc04d5307780b4397dfde952b196
11 files changed +442 -126
apps/mobile/src/connection/environment-cache-store.test.ts
+10 -1
@@ -498,12 +498,21 @@ describe("mobile SQLite environment cache store", () => {
498 Effect.provideService(MobileDatabase.MobileDatabase, memory.database),
499 );
500
501 - yield* store.saveShell(ENVIRONMENT_ID, SHELL_SNAPSHOT);
501 + const origin = {
502 + serverVersion: "1.0.0",
503 + databaseMigration: 70,
504 + omitIdleSubagents: true,
505 + omitOlderSettled: false,
506 + snapshotAt: 1_800_000_000_000,
507 + };
508 + yield* store.saveShell(ENVIRONMENT_ID, SHELL_SNAPSHOT, origin);
509 yield* store.saveThread(ENVIRONMENT_ID, THREAD_SNAPSHOT);
510
511 const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID));
512 const thread = Option.getOrThrow(yield* store.loadThread(ENVIRONMENT_ID, THREAD_ID));
513
514 + expect(shell.origin).toEqual(origin);
515 +
516 expect(DateTime.formatIso(shell.threads[0]!.updatedAt)).toBe("2026-07-29T12:00:00.000Z");
517 expect(DateTime.formatIso(shell.threads[0]!.latestUserMessageAt!)).toBe(
518 "2026-07-29T12:00:00.000Z",
apps/mobile/src/connection/environment-cache-store.ts
+26 -11
@@ -106,7 +106,13 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
106 operation: "load-shell",
107 decode: decodeStoredShellSnapshot,
108 select: (stored) =>
109 - stored.environmentId === environmentId ? Option.some(stored.snapshot) : Option.none(),
109 + stored.environmentId === environmentId
110 + ? Option.some(
111 + stored.origin === undefined
112 + ? stored.snapshot
113 + : { ...stored.snapshot, origin: stored.origin },
114 + )
115 + : Option.none(),
116 }).pipe(
117 Effect.zipWith(
118 Effect.promise(() => projectFaviconDatabaseCache.hydrate()),
@@ -115,16 +121,25 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
121 ),
122 ),
123 ),
118 - saveShell: Effect.fn("MobileEnvironmentCache.saveShell")(function* (environmentId, snapshot) {
119 - const payload = yield* encodeStoredShellSnapshot({
120 - schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
121 - environmentId,
122 - snapshot,
123 - }).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
124 - yield* database
125 - .saveCache(environmentId, "shell", "snapshot", ORCHESTRATION_CACHE_SCHEMA_VERSION, payload)
126 - .pipe(Effect.mapError(mapDatabaseError("save-shell")));
127 - }),
124 + saveShell: Effect.fn("MobileEnvironmentCache.saveShell")(
125 + function* (environmentId, snapshot, origin) {
126 + const payload = yield* encodeStoredShellSnapshot({
127 + schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
128 + environmentId,
129 + snapshot,
130 + ...(origin === undefined ? {} : { origin }),
131 + }).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
132 + yield* database
133 + .saveCache(
134 + environmentId,
135 + "shell",
136 + "snapshot",
137 + ORCHESTRATION_CACHE_SCHEMA_VERSION,
138 + payload,
139 + )
140 + .pipe(Effect.mapError(mapDatabaseError("save-shell")));
141 + },
142 + ),
143 loadThread: Effect.fn("MobileEnvironmentCache.loadThread")((environmentId, threadId) =>
144 loadDecodedCache({
145 database,
apps/server/src/ws.test.ts
+24 -9
@@ -1436,10 +1436,15 @@ it.effect("a publish whose push fails still refreshes the new remote", () =>
1436 ),
1437 );
1438
1439 -// Pruned history cannot be replayed: a cursor below the boundary must resync from a snapshot.
1440 -it.effect.each(["thread", "shell"] as const)(
1441 - "%s resume from a cursor below the pruned boundary loads a snapshot",
1442 - (scope) =>
1439 +// Pruned history cannot be replayed: a cursor below the boundary must resync from a snapshot,
1440 +// or, for a shell client that loads it over HTTP, be told to without the server building one.
1441 +it.effect.each([
1442 + { scope: "thread", httpSnapshotFallback: false },
1443 + { scope: "shell", httpSnapshotFallback: false },
1444 + { scope: "shell", httpSnapshotFallback: true },
1445 +] as const)(
1446 + "$scope resume from a cursor below the pruned boundary (HTTP fallback: $httpSnapshotFallback)",
1447 + ({ scope, httpSnapshotFallback }) =>
1448 Effect.gen(function* () {
1449 const sql = yield* SqlClient.SqlClient;
1450 const now = "2026-10-13T00:00:00.000Z";
@@ -1463,11 +1468,18 @@ it.effect.each(["thread", "shell"] as const)(
1468 ) VALUES (${OrchestrationEventStore.EVENT_LOG_PRUNED_THROUGH}, 2, ${second!.sequence}, ${now})
1469 `;
1470 const subscription = Effect.gen(function* () {
1466 - const stream =
1471 + const items: ReadonlyArray<unknown> =
1472 scope === "thread"
1468 - ? yield* subscribeOrchestrationV2Thread({ threadId, afterSequence: first!.sequence })
1469 - : yield* subscribeOrchestrationV2Shell({ afterSequence: first!.sequence });
1470 - return stream;
1473 + ? yield* Stream.runCollect(
1474 + yield* subscribeOrchestrationV2Thread({ threadId, afterSequence: first!.sequence }),
1475 + )
1476 + : yield* Stream.runCollect(
1477 + yield* subscribeOrchestrationV2Shell({
1478 + afterSequence: first!.sequence,
1479 + ...(httpSnapshotFallback ? { httpSnapshotFallback: true as const } : {}),
1480 + }),
1481 + );
1482 + return items;
1483 });
1484 const exit = yield* subscription.pipe(
1485 Effect.provideService(ThreadManagement.ThreadManagementService, {
@@ -1489,7 +1501,10 @@ it.effect.each(["thread", "shell"] as const)(
1501 } as ProjectEnrichment.ProjectEnrichmentService["Service"]),
1502 Effect.exit,
1503 );
1492 - assert.deepEqual(Exit.isFailure(exit) ? Cause.squash(exit.cause) : exit, "snapshot");
1504 + assert.deepEqual(
1505 + Exit.isFailure(exit) ? Cause.squash(exit.cause) : Array.from(exit.value),
1506 + httpSnapshotFallback ? [{ kind: "snapshot-required" }] : "snapshot",
1507 + );
1508 }).pipe(Effect.scoped, Effect.provide(ReplayTestLayer)),
1509 );
1510
apps/server/src/ws.ts
+15 -7
@@ -64,6 +64,7 @@ import {
64 OrchestrationV2ThreadLaunchError,
65 type OrchestrationProjectShell,
66 type OrchestrationV2ShellSnapshot,
67 + type OrchestrationV2ShellStreamItem,
68 type OrchestrationV2ThreadStreamItem,
69 type ApplicationStoredEvent,
70 type ProjectEntriesFailure,
@@ -1115,6 +1116,7 @@ export const subscribeOrchestrationV2Thread = Effect.fn("ws.orchestrationV2.subs
1116 export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subscribeShell")(
1117 function* (input: {
1118 readonly afterSequence?: number;
1119 + readonly httpSnapshotFallback?: true;
1120 readonly requestCompletionMarker?: boolean;
1121 readonly omitIdleSubagents?: boolean;
1122 readonly omitOlderSettled?: boolean;
@@ -1325,14 +1327,20 @@ export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subsc
1327 });
1328 }
1329
1328 - const fromSnapshot = Effect.gen(function* () {
1329 - const loaded = yield* loadSnapshot();
1330 - return composeShellStreamWithEnrichment({
1331 - initial: initialSnapshotItems(loaded),
1332 - tail: completionThenLive(loaded.snapshot.snapshotSequence),
1333 - enrichment: enrichmentRefreshes,
1334 - });
1330 + const snapshotRequired: Stream.Stream<OrchestrationV2ShellStreamItem> = Stream.make({
1331 + kind: "snapshot-required",
1332 });
1333 + const fromSnapshot =
1334 + input.httpSnapshotFallback === true
1335 + ? Effect.succeed(snapshotRequired)
1336 + : Effect.gen(function* () {
1337 + const loaded = yield* loadSnapshot();
1338 + return composeShellStreamWithEnrichment({
1339 + initial: initialSnapshotItems(loaded),
1340 + tail: completionThenLive(loaded.snapshot.snapshotSequence),
1341 + enrichment: enrichmentRefreshes,
1342 + });
1343 + });
1344 const highWater = yield* applicationEvents.latestApplicationSequence;
1345 if (!(yield* canReplayPersistedRange(input.afterSequence, highWater, SHELL_RESUME_MAX_GAP))) {
1346 return yield* fromSnapshot;
apps/web/src/connection/storage.ts
+7 -2
@@ -846,7 +846,11 @@ export const layer = Layer.effectContext(
846 Effect.mapError((cause) => persistenceError("load-shell", cause)),
847 Effect.map((stored) =>
848 stored.environmentId === environmentId
849 - ? Option.some(stored.snapshot)
849 + ? Option.some(
850 + stored.origin === undefined
851 + ? stored.snapshot
852 + : { ...stored.snapshot, origin: stored.origin },
853 + )
854 : Option.none(),
855 ),
856 ),
@@ -857,11 +861,12 @@ export const layer = Layer.effectContext(
861 );
862 }),
863 saveShell: Effect.fn("storage.saveShell")(
860 - function* (environmentId, snapshot) {
864 + function* (environmentId, snapshot, origin) {
865 const encoded = yield* encodeStoredShellSnapshot({
866 schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
867 environmentId,
868 snapshot,
869 + ...(origin === undefined ? {} : { origin }),
870 }).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
871 yield* writeDatabaseValue(database, SHELL_STORE_NAME, environmentId, encoded);
872 },
packages/client-runtime/src/platform/orchestrationCache.ts
+15
@@ -13,10 +13,25 @@ export const ORCHESTRATION_CACHE_SCHEMA_VERSION = 3 as const;
13 // Older caches may contain human turns that bypassed server history budgets.
14 export const ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION = 5 as const;
15
16 +/**
17 + * The server snapshot the cached rows descend from. Written only for rows that have one, so a
18 + * cache from before it existed decodes and never resumes.
19 + */
20 +export const ShellCacheOrigin = Schema.Struct({
21 + serverVersion: Schema.String,
22 + databaseMigration: Schema.NullOr(Schema.Int),
23 + omitIdleSubagents: Schema.Boolean,
24 + omitOlderSettled: Schema.Boolean,
25 + /** Epoch milliseconds of that snapshot; replay does not renew it. */
26 + snapshotAt: Schema.Number,
27 +});
28 +export type ShellCacheOrigin = typeof ShellCacheOrigin.Type;
29 +
30 export const StoredOrchestrationShellSnapshot = Schema.Struct({
31 schemaVersion: Schema.Literal(ORCHESTRATION_CACHE_SCHEMA_VERSION),
32 environmentId: EnvironmentId,
33 snapshot: OrchestrationV2ShellSnapshotJson,
34 + origin: Schema.optionalKey(ShellCacheOrigin),
35 });
36
37 export const StoredOrchestrationThreadSnapshot = Schema.Struct({
packages/client-runtime/src/platform/persistence.ts
+10 -1
@@ -14,6 +14,13 @@ import * as Schema from "effect/Schema";
14 import type { ConnectionRegistration } from "../connection/catalog.ts";
15 import type { DeferredShellSnapshot } from "../state/shellPullRequests.ts";
16 import type { ConnectionTarget, PersistedConnectionTarget } from "../connection/model.ts";
17 +import type { ShellCacheOrigin } from "./orchestrationCache.ts";
18 +
19 +export type { ShellCacheOrigin };
20 +
21 +export interface CachedShellSnapshot extends DeferredShellSnapshot {
22 + readonly origin?: ShellCacheOrigin;
23 +}
24
25 export class ConnectionPersistenceError extends Schema.TaggedError<ConnectionPersistenceError>()(
26 "ConnectionPersistenceError",
@@ -82,10 +89,12 @@ export class EnvironmentCacheStore extends Context.Service<
89 {
90 readonly loadShell: (
91 environmentId: EnvironmentId,
85 - ) => Effect.Effect<Option.Option<DeferredShellSnapshot>, ConnectionPersistenceError>;
92 + ) => Effect.Effect<Option.Option<CachedShellSnapshot>, ConnectionPersistenceError>;
93 + /** `origin` only when the rows descend from a server snapshot. */
94 readonly saveShell: (
95 environmentId: EnvironmentId,
96 snapshot: OrchestrationV2ShellSnapshot,
97 + origin?: ShellCacheOrigin,
98 ) => Effect.Effect<void, ConnectionPersistenceError>;
99 readonly loadThread: (
100 environmentId: EnvironmentId,
packages/client-runtime/src/state/shell-sync.test.ts
+179
@@ -1136,3 +1136,182 @@ describe("environment shell synchronization", () => {
1136 }),
1137 );
1138 });
1139 +
1140 +describe("environment shell cold start", () => {
1141 + const NOW = 1_800_000_000_000;
1142 + const HOUR = 60 * 60 * 1000;
1143 + const CACHED_SEQUENCE = 7;
1144 + const HTTP_SEQUENCE = 9;
1145 + // What `session()` advertises: server 1.0.0, no omissions, no migration.
1146 + const CURRENT_ORIGIN = {
1147 + serverVersion: "1.0.0",
1148 + databaseMigration: null,
1149 + omitIdleSubagents: false,
1150 + omitOlderSettled: false,
1151 + };
1152 + const RECENT_ORIGIN = { ...CURRENT_ORIGIN, snapshotAt: NOW - HOUR };
1153 +
1154 + const makeColdStart = Effect.fn("test.makeColdStartShell")(function* (
1155 + origin: Persistence.ShellCacheOrigin | undefined,
1156 + ) {
1157 + yield* TestClock.setTime(NOW);
1158 + const subscriptions = yield* Queue.unbounded<{
1159 + readonly input: unknown;
1160 + readonly events: Queue.Queue<OrchestrationV2ShellStreamItem>;
1161 + }>();
1162 + const saved = yield* Queue.unbounded<{
1163 + readonly snapshot: OrchestrationV2ShellSnapshot;
1164 + readonly origin: Persistence.ShellCacheOrigin | undefined;
1165 + }>();
1166 + const httpLoads = yield* Ref.make(0);
1167 + const client = {
1168 + [ORCHESTRATION_V2_WS_METHODS.subscribeShell]: (input: unknown) =>
1169 + Stream.unwrap(
1170 + Effect.gen(function* () {
1171 + const events = yield* Queue.unbounded<OrchestrationV2ShellStreamItem>();
1172 + yield* Queue.offer(subscriptions, { input, events });
1173 + return Stream.fromQueue(events);
1174 + }),
1175 + ),
1176 + } as unknown as WsRpcProtocolClient;
1177 + const activeSession = yield* SubscriptionRef.make(Option.some(session(client)));
1178 + const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
1179 + target: TARGET,
1180 + state: yield* SubscriptionRef.make(AVAILABLE_CONNECTION_STATE),
1181 + session: activeSession,
1182 + prepared: yield* SubscriptionRef.make(Option.some(PREPARED)),
1183 + connect: Effect.void,
1184 + disconnect: Effect.void,
1185 + retryNow: Effect.void,
1186 + } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
1187 + const cache = Persistence.EnvironmentCacheStore.of({
1188 + loadShell: () =>
1189 + Effect.succeedSome({
1190 + ...v2ShellSnapshot,
1191 + snapshotSequence: CACHED_SEQUENCE,
1192 + ...(origin === undefined ? {} : { origin }),
1193 + }),
1194 + saveShell: (_environmentId, snapshot, origin?: Persistence.ShellCacheOrigin) =>
1195 + Queue.offer(saved, { snapshot, origin }).pipe(Effect.asVoid),
1196 + loadThread: () => Effect.succeedNone,
1197 + saveThread: () => Effect.void,
1198 + removeThread: () => Effect.void,
1199 + loadServerConfig: () => Effect.succeedNone,
1200 + saveServerConfig: () => Effect.void,
1201 + loadVcsRefs: () => Effect.succeedNone,
1202 + saveVcsRefs: () => Effect.void,
1203 + removeVcsRefs: () => Effect.void,
1204 + clearVcsRefs: () => Effect.void,
1205 + clear: () => Effect.void,
1206 + });
1207 + const snapshotLoader = ShellSnapshotLoader.ShellSnapshotLoader.of({
1208 + load: () =>
1209 + Ref.updateAndGet(httpLoads, (count) => count + 1).pipe(
1210 + Effect.map((count) =>
1211 + Option.some({ ...v2ShellSnapshot, snapshotSequence: HTTP_SEQUENCE + count - 1 }),
1212 + ),
1213 + ),
1214 + });
1215 + const shellState = yield* makeEnvironmentShellState().pipe(
1216 + Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
1217 + Effect.provideService(Persistence.EnvironmentCacheStore, cache),
1218 + Effect.provideService(ShellSnapshotLoader.ShellSnapshotLoader, snapshotLoader),
1219 + );
1220 + return {
1221 + subscriptions,
1222 + saved,
1223 + httpLoads,
1224 + reconnect: SubscriptionRef.set(activeSession, Option.some(session(client))),
1225 + liveAt: (sequence: number) =>
1226 + SubscriptionRef.changes(shellState).pipe(
1227 + Stream.filter(
1228 + (state) =>
1229 + state.status === "live" &&
1230 + Option.exists(state.snapshot, (snapshot) => snapshot.snapshotSequence === sequence),
1231 + ),
1232 + Stream.runHead,
1233 + Effect.map(Option.getOrThrow),
1234 + ),
1235 + };
1236 + });
1237 +
1238 + it.effect.each([
1239 + { label: "a recent matching origin", origin: RECENT_ORIGIN, resumes: true },
1240 + { label: "no origin", origin: undefined, resumes: false },
1241 + {
1242 + label: "other omissions",
1243 + origin: { ...RECENT_ORIGIN, omitIdleSubagents: true },
1244 + resumes: false,
1245 + },
1246 + {
1247 + label: "another migration",
1248 + origin: { ...RECENT_ORIGIN, databaseMigration: 70 },
1249 + resumes: false,
1250 + },
1251 + {
1252 + label: "another server version",
1253 + origin: { ...RECENT_ORIGIN, serverVersion: "0.9.0" },
1254 + resumes: false,
1255 + },
1256 + {
1257 + label: "a 12 hour old origin",
1258 + origin: { ...RECENT_ORIGIN, snapshotAt: NOW - 12 * HOUR },
1259 + resumes: false,
1260 + },
1261 + ])("starts from a cache with $label (resumes: $resumes)", ({ origin, resumes }) =>
1262 + Effect.gen(function* () {
1263 + const h = yield* makeColdStart(origin);
1264 + const first = yield* Queue.take(h.subscriptions);
1265 + const sequence = resumes ? CACHED_SEQUENCE : HTTP_SEQUENCE;
1266 + expect(first.input).toMatchObject({ afterSequence: sequence });
1267 + // Only held rows may be refused; a fresh snapshot's cursor never loops back to HTTP.
1268 + if (resumes) expect(first.input).toMatchObject({ httpSnapshotFallback: true });
1269 + else expect(first.input).not.toHaveProperty("httpSnapshotFallback");
1270 + expect(yield* Ref.get(h.httpLoads)).toBe(resumes ? 0 : 1);
1271 +
1272 + // Thread families, older threads, and search wait for a nonzero generation.
1273 + yield* Queue.offer(first.events, { kind: "synchronized" });
1274 + expect((yield* h.liveAt(sequence)).generation).toBeGreaterThan(0);
1275 +
1276 + if (!resumes) {
1277 + // The next cold start may resume from this snapshot.
1278 + yield* TestClock.adjust("500 millis");
1279 + expect(yield* Queue.take(h.saved)).toMatchObject({
1280 + snapshot: { snapshotSequence: HTTP_SEQUENCE },
1281 + origin: { ...CURRENT_ORIGIN, snapshotAt: NOW },
1282 + });
1283 + }
1284 + }),
1285 + );
1286 +
1287 + it.effect("reloads over HTTP when the server answers a resume with snapshot-required", () =>
1288 + Effect.gen(function* () {
1289 + const h = yield* makeColdStart(RECENT_ORIGIN);
1290 +
1291 + const coldResume = yield* Queue.take(h.subscriptions);
1292 + expect(coldResume.input).toMatchObject({ afterSequence: CACHED_SEQUENCE });
1293 + yield* Queue.offer(coldResume.events, { kind: "snapshot-required" });
1294 + const coldReload = yield* Queue.take(h.subscriptions);
1295 + expect(coldReload.input).toMatchObject({ afterSequence: HTTP_SEQUENCE });
1296 + expect(coldReload.input).not.toHaveProperty("httpSnapshotFallback");
1297 + expect(yield* Ref.get(h.httpLoads)).toBe(1);
1298 + yield* Queue.offer(coldReload.events, { kind: "synchronized" });
1299 + expect((yield* h.liveAt(HTTP_SEQUENCE)).generation).toBeGreaterThan(0);
1300 +
1301 + // A warm reconnect resumes the in-memory shell and falls back the same way.
1302 + yield* h.reconnect;
1303 + const warmResume = yield* Queue.take(h.subscriptions);
1304 + expect(warmResume.input).toMatchObject({
1305 + afterSequence: HTTP_SEQUENCE,
1306 + httpSnapshotFallback: true,
1307 + });
1308 + expect(yield* Ref.get(h.httpLoads)).toBe(1);
1309 + yield* Queue.offer(warmResume.events, { kind: "snapshot-required" });
1310 + const warmReload = yield* Queue.take(h.subscriptions);
1311 + expect(warmReload.input).toMatchObject({ afterSequence: HTTP_SEQUENCE + 1 });
1312 + expect(yield* Ref.get(h.httpLoads)).toBe(2);
1313 + yield* Queue.offer(warmReload.events, { kind: "synchronized" });
1314 + yield* h.liveAt(HTTP_SEQUENCE + 1);
1315 + }),
1316 + );
1317 +});
packages/client-runtime/src/state/shell.ts
+141 -89
@@ -9,6 +9,7 @@ import {
9 type ThreadPullRequestLink,
10 } from "@t3tools/contracts";
11 import * as Cause from "effect/Cause";
12 +import * as Clock from "effect/Clock";
13 import * as Effect from "effect/Effect";
14 import * as Fiber from "effect/Fiber";
15 import * as Option from "effect/Option";
@@ -82,14 +83,41 @@ function withoutDeferredPullRequests(value: DeferredShellSnapshot): Orchestratio
83
84 const SHELL_SYNCHRONIZATION_ERROR_MESSAGE = "Could not synchronize environment data.";
85
85 -function groupBySession<A>(entries: ReadonlyArray<readonly [RpcSession, A]>) {
86 - const groups: Array<[RpcSession, Array<A>]> = [];
87 - for (const [session, value] of entries) {
88 - const last = groups.at(-1);
89 - if (last?.[0] === session) last[1].push(value);
90 - else groups.push([session, [value]]);
91 - }
92 - return groups;
86 +/**
87 + * Replay does not refresh the older-settled cut, rows that left the newest window, or
88 + * projections the server rebuilt, so drift grows with the age of the last server snapshot.
89 + */
90 +const CACHE_RESUME_MAX_AGE_MILLIS = 12 * 60 * 60 * 1000;
91 +
92 +type ShellOriginIdentity = Omit<Persistence.ShellCacheOrigin, "snapshotAt">;
93 +
94 +interface ShellSubscription {
95 + readonly session: RpcSession;
96 + /** What a snapshot from this subscription descends from; null when the server did not say. */
97 + readonly identity: ShellOriginIdentity | null;
98 +}
99 +
100 +function canResumeFrom(
101 + origin: Persistence.ShellCacheOrigin | undefined,
102 + identity: ShellOriginIdentity | null,
103 + now: number,
104 +): boolean {
105 + if (origin === undefined || identity === null) return false;
106 + const age = now - origin.snapshotAt;
107 + return (
108 + origin.serverVersion === identity.serverVersion &&
109 + origin.databaseMigration === identity.databaseMigration &&
110 + origin.omitIdleSubagents === identity.omitIdleSubagents &&
111 + origin.omitOlderSettled === identity.omitOlderSettled &&
112 + age >= 0 &&
113 + age < CACHE_RESUME_MAX_AGE_MILLIS
114 + );
115 +}
116 +
117 +interface LiveShell {
118 + readonly snapshot: OrchestrationV2ShellSnapshot;
119 + // Read together with the rows, so a save never pairs them with another snapshot's origin.
120 + readonly origin: Persistence.ShellCacheOrigin | undefined;
121 }
122
123 export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")(function* () {
@@ -105,29 +133,30 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
133 environmentId,
134 ...safeErrorLogAttributes(error),
135 }),
108 - Effect.as(Option.none<DeferredShellSnapshot>()),
136 + Effect.as(Option.none<Persistence.CachedShellSnapshot>()),
137 ),
138 ),
139 );
112 - const cachedSnapshot = Option.map(cached, withoutDeferredPullRequests);
140 + const cachedOrigin = Option.isSome(cached) ? cached.value.origin : undefined;
141 + const cachedSnapshot = Option.map(cached, ({ origin: _origin, ...rows }) =>
142 + withoutDeferredPullRequests(rows),
143 + );
144 const state = yield* SubscriptionRef.make<EnvironmentShellState>({
145 ...EMPTY_SHELL_STATE,
146 snapshot: cachedSnapshot,
147 status: shellStatusForSnapshot(cachedSnapshot),
148 });
149 const awaitingCompletion = yield* Ref.make(false);
119 - // The omissions and server build of the subscription whose snapshot the
120 - // in-memory shell last came from; null while it holds only cached data.
121 - const authoritativeOmission = yield* Ref.make<string | null>(null);
122 - // Items buffered from a previous session keep that session's key.
123 - const sessionOmissions = new WeakMap<RpcSession, string | null>();
124 - const latestLiveSnapshot = yield* Ref.make<Option.Option<OrchestrationV2ShellSnapshot>>(
125 - Option.none(),
126 - );
150 + const activeSubscription = yield* Ref.make<ShellSubscription | null>(null);
151 + // The server snapshot the in-memory rows descend from, directly or through the cache.
152 + // Only a server snapshot renews it; `snapshot-required` drops it.
153 + const origin = yield* Ref.make(cachedOrigin);
154 + const reloadRequests = yield* Queue.unbounded<void>();
155 + const latestLive = yield* Ref.make<Option.Option<LiveShell>>(Option.none());
156 const persistence = yield* Queue.sliding<OrchestrationV2ShellSnapshot>(1);
157
158 const persistenceLock = yield* Semaphore.make(1);
130 - let lastPersisted: OrchestrationV2ShellSnapshot | undefined;
159 + let lastPersisted: LiveShell | undefined;
160 // Rows still waiting for their deferred pull request links, which must not be saved:
161 // the cache would keep them without links until the next server refresh.
162 let pendingLinkRows: ReadonlySet<OrchestrationV2ThreadShell> = new Set();
@@ -135,24 +164,25 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
164 flush: boolean,
165 ) {
166 while (true) {
138 - const latest = yield* Ref.get(latestLiveSnapshot);
167 + const latest = yield* Ref.get(latestLive);
168 if (Option.isNone(latest) || latest.value === lastPersisted) return;
140 - if (latest.value.threads.some((thread) => pendingLinkRows.has(thread))) return;
141 - const snapshot = latest.value;
169 + const { snapshot, origin } = latest.value;
170 + if (snapshot.threads.some((thread) => pendingLinkRows.has(thread))) return;
171 if (
172 lastPersisted !== undefined &&
144 - snapshot.snapshotSequence >= lastPersisted.snapshotSequence &&
145 - snapshot.schemaVersion === lastPersisted.schemaVersion &&
146 - snapshot.projects === lastPersisted.projects &&
147 - snapshot.threads === lastPersisted.threads &&
148 - snapshot.archivedThreads === lastPersisted.archivedThreads
173 + origin === lastPersisted.origin &&
174 + snapshot.snapshotSequence >= lastPersisted.snapshot.snapshotSequence &&
175 + snapshot.schemaVersion === lastPersisted.snapshot.schemaVersion &&
176 + snapshot.projects === lastPersisted.snapshot.projects &&
177 + snapshot.threads === lastPersisted.snapshot.threads &&
178 + snapshot.archivedThreads === lastPersisted.snapshot.archivedThreads
179 ) {
180 // Keep the live cursor without rewriting the rows. Remember it here too so a
181 // later authoritative reset to a lower sequence still reaches the cache.
152 - lastPersisted = snapshot;
182 + lastPersisted = latest.value;
183 return;
184 }
155 - const saved = yield* cache.saveShell(environmentId, snapshot).pipe(
185 + const saved = yield* cache.saveShell(environmentId, snapshot, origin).pipe(
186 Effect.as(true),
187 Effect.catch((error) =>
188 Effect.logWarning("Could not persist environment shell cache.").pipe(
@@ -162,7 +192,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
192 ),
193 );
194 if (!saved) return;
165 - lastPersisted = snapshot;
195 + lastPersisted = latest.value;
196 if (!flush) return;
197 }
198 }, persistenceLock.withPermit);
@@ -220,14 +250,20 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
250 const snapshotWriteLock = yield* Semaphore.make(1);
251
252 const applyItems = Effect.fn("EnvironmentShellState.applyItems")(function* (
223 - items: ReadonlyArray<OrchestrationV2ShellStreamItem>,
224 - omission: string | null,
253 + entries: ReadonlyArray<readonly [RpcSession, OrchestrationV2ShellStreamItem]>,
254 pendingLinkIds?: ReadonlySet<ThreadId>,
255 ) {
256 + // Read under the lock: items buffered across a session change must not land on the
257 + // rows the next session loaded.
258 + const subscription = yield* Ref.get(activeSubscription);
259 + const items = entries.flatMap(([session, item]) =>
260 + session === subscription?.session ? [item] : [],
261 + );
262 const initial = yield* SubscriptionRef.get(state);
263 let waiting = yield* Ref.get(awaitingCompletion);
264 let next = initial;
265 let receivedAuthoritativeSnapshot = false;
266 + let snapshotRequired = false;
267 let deltas: Array<ShellStreamEvent> = [];
268 const flushDeltas = () => {
269 if (deltas.length > 0 && Option.isSome(next.snapshot)) {
@@ -260,6 +296,10 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
296 deltas = [];
297 };
298 for (const item of items) {
299 + if (item.kind === "snapshot-required") {
300 + snapshotRequired = true;
301 + continue;
302 + }
303 if (item.kind !== "snapshot" && item.kind !== "synchronized") {
304 deltas.push(item);
305 continue;
@@ -269,7 +309,13 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
309 if (item.kind === "synchronized") {
310 waiting = false;
311 if (Option.isSome(next.snapshot)) {
272 - next = { ...next, status: "live", error: Option.none() };
312 + next = {
313 + ...next,
314 + status: "live",
315 + error: Option.none(),
316 + // A cache resume that caught up is as current as a snapshot for generation readers.
317 + generation: next.generation === 0 ? ++lastShellGeneration : next.generation,
318 + };
319 }
320 continue;
321 }
@@ -292,6 +338,20 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
338 }
339 flushDeltas();
340 yield* Ref.set(awaitingCompletion, waiting);
341 + let nextOrigin = yield* Ref.get(origin);
342 + if (snapshotRequired) {
343 + // The rows stay on screen but reload before the next resume; the cache keeps the old
344 + // origin until that reload saves, which costs at most one more refusal.
345 + nextOrigin = undefined;
346 + yield* Ref.set(origin, nextOrigin);
347 + yield* Queue.offer(reloadRequests, undefined);
348 + } else if (receivedAuthoritativeSnapshot) {
349 + nextOrigin =
350 + subscription?.identity == null
351 + ? undefined
352 + : { ...subscription.identity, snapshotAt: yield* Clock.currentTimeMillis };
353 + yield* Ref.set(origin, nextOrigin);
354 + }
355 if (next === initial) return;
356 if (pendingLinkIds !== undefined && Option.isSome(next.snapshot)) {
357 pendingLinkRows = new Set(
@@ -299,12 +359,12 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
359 );
360 }
361 if (Option.isSome(next.snapshot)) {
302 - yield* Ref.set(latestLiveSnapshot, next.snapshot);
362 + yield* Ref.set(
363 + latestLive,
364 + Option.some({ snapshot: next.snapshot.value, origin: nextOrigin }),
365 + );
366 }
367 yield* SubscriptionRef.set(state, next);
305 - if (receivedAuthoritativeSnapshot && omission !== null) {
306 - yield* Ref.set(authoritativeOmission, omission);
307 - }
368 if (next.snapshot !== initial.snapshot && Option.isSome(next.snapshot)) {
369 yield* Queue.offer(persistence, next.snapshot.value);
370 }
@@ -365,11 +425,11 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
425 },
426 );
427 pendingLinkRows = new Set();
368 - const live = yield* Ref.get(latestLiveSnapshot);
428 + const live = yield* Ref.get(latestLive);
429 if (Option.isNone(live)) return;
370 - const latest = Option.isSome(filled) ? filled : live;
371 - yield* Ref.set(latestLiveSnapshot, latest);
372 - yield* Queue.offer(persistence, latest.value);
430 + const latest = Option.isSome(filled) ? filled.value : live.value.snapshot;
431 + yield* Ref.set(latestLive, Option.some({ snapshot: latest, origin: live.value.origin }));
432 + yield* Queue.offer(persistence, latest);
433 },
434 (effect) => snapshotWriteLock.withPermit(effect),
435 );
@@ -377,53 +437,52 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
437 yield* fillDeferredPullRequests(cached.value, cachedSnapshot.value);
438 }
439
380 - const foregroundResubscriptions = Option.match(wakeups, {
381 - onNone: () => Stream.never,
382 - onSome: (service) =>
383 - service.changes.pipe(Stream.filter(ConnectionWakeups.shouldResubscribeAfterWakeup)),
384 - });
440 + const resubscriptions = Stream.merge(
441 + Stream.fromQueue(reloadRequests),
442 + Option.match(wakeups, {
443 + onNone: () => Stream.never,
444 + onSome: (service) =>
445 + service.changes.pipe(Stream.filter(ConnectionWakeups.shouldResubscribeAfterWakeup)),
446 + }),
447 + );
448
449 yield* setSynchronizing;
450 yield* Effect.forkScoped(
451 subscribeDynamicWithSession(
452 ORCHESTRATION_V2_WS_METHODS.subscribeShell,
453 Effect.fn("EnvironmentShellState.makeSubscribeInput")(function* (session) {
391 - const { omitIdleSubagents, omitOlderSettled, omissionKey } =
392 - yield* session.initialConfig.pipe(
393 - Effect.map((config) => {
394 - const omitIdleSubagents = config.shellThreadFamilies === true;
395 - const omitOlderSettled = config.shellOlderSettled === true && omitIdleSubagents;
396 - // Migrations rewrite projections without events, so an upgraded server reloads.
397 - const { serverVersion, databaseMigration } = config.environment;
398 - return {
399 - omitIdleSubagents,
400 - omitOlderSettled,
401 - omissionKey: JSON.stringify([
402 - omitIdleSubagents,
403 - omitOlderSettled,
404 - serverVersion,
405 - databaseMigration ?? null,
406 - ]),
407 - };
408 - }),
409 - Effect.orElseSucceed(() => ({
410 - omitIdleSubagents: false,
411 - omitOlderSettled: false,
412 - omissionKey: null,
413 - })),
414 - );
415 - sessionOmissions.set(session, omissionKey);
454 + const identity = yield* session.initialConfig.pipe(
455 + Effect.map((config): ShellOriginIdentity => {
456 + const omitIdleSubagents = config.shellThreadFamilies === true;
457 + return {
458 + serverVersion: config.environment.serverVersion,
459 + // Migrations rewrite projections without events, so a migrated server reloads.
460 + databaseMigration: config.environment.databaseMigration ?? null,
461 + omitIdleSubagents,
462 + omitOlderSettled: config.shellOlderSettled === true && omitIdleSubagents,
463 + };
464 + }),
465 + Effect.orElseSucceed(() => null),
466 + );
467 + const { omitIdleSubagents, omitOlderSettled } = identity ?? {
468 + omitIdleSubagents: false,
469 + omitOlderSettled: false,
470 + };
471 + yield* Ref.set(activeSubscription, { session, identity });
472 yield* Ref.set(awaitingCompletion, true);
473 yield* setSynchronizing;
474
419 - // A shell from a server snapshot resumes from its cursor, on this session or a
420 - // new one. Cached data, other omissions, or another server build reload the
421 - // authoritative HTTP snapshot so a valid cursor cannot preserve stale data.
422 - const hasAuthoritativeSnapshot =
423 - omissionKey !== null && (yield* Ref.get(authoritativeOmission)) === omissionKey;
424 - let canResume = hasAuthoritativeSnapshot;
475 + // Rows from a recent server snapshot with the same omissions and server build resume
476 + // from their cursor, in memory or from the cache. Anything else reloads the HTTP
477 + // snapshot so a valid cursor cannot preserve stale or incomplete data.
478 let current = yield* SubscriptionRef.get(state);
426 - if (!hasAuthoritativeSnapshot || Option.isNone(current.snapshot)) {
479 + let canResume =
480 + Option.isSome(current.snapshot) &&
481 + canResumeFrom(yield* Ref.get(origin), identity, yield* Clock.currentTimeMillis);
482 + // Only rows the client already held may be refused; a cursor from the snapshot just
483 + // loaded falls back to the socket snapshot, so a refusal cannot loop.
484 + const resumingHeldRows = canResume;
485 + if (!canResume) {
486 const prepared = yield* SubscriptionRef.get(supervisor.prepared).pipe(
487 Effect.flatMap(
488 Option.match({
@@ -455,7 +514,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
514 ? []
515 : httpSnapshot.value.threads.map((thread) => thread.id),
516 );
458 - yield* applyItems([{ kind: "snapshot", snapshot }], omissionKey, pendingLinkIds);
517 + yield* applyItems([[session, { kind: "snapshot", snapshot }]], pendingLinkIds);
518 canResume = true;
519 current = yield* SubscriptionRef.get(state);
520 if (Option.isSome(current.snapshot)) {
@@ -473,6 +532,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
532 }
533 return {
534 afterSequence: current.snapshot.value.snapshotSequence,
535 + ...(resumingHeldRows ? { httpSnapshotFallback: true as const } : {}),
536 ...omission,
537 requestCompletionMarker: true as const,
538 };
@@ -480,17 +540,9 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
540 {
541 onExpectedFailure: (cause) => setStreamError(Cause.squash(cause)),
542 retryExpectedFailureAfter: "250 millis",
483 - resubscribe: foregroundResubscriptions,
543 + resubscribe: resubscriptions,
544 },
485 - ).pipe(
486 - Stream.runForEachArray((entries) =>
487 - Effect.forEach(
488 - groupBySession(entries),
489 - ([session, items]) => applyItems(items, sessionOmissions.get(session) ?? null),
490 - { discard: true },
491 - ),
492 - ),
493 - ),
545 + ).pipe(Stream.runForEachArray((entries) => applyItems(entries))),
546 );
547 yield* SubscriptionRef.changes(supervisor.state).pipe(
548 Stream.runForEach((connectionState) => {
packages/client-runtime/src/state/shellReducer.ts
+3 -6
@@ -131,10 +131,7 @@ export function mergeShellSnapshotProjects(
131
132 export function applyShellStreamEvent(
133 snapshot: OrchestrationV2ShellSnapshot,
134 - event: Exclude<
135 - OrchestrationV2ShellStreamItem,
136 - { readonly kind: "snapshot" } | { readonly kind: "synchronized" }
137 - >,
134 + event: ShellStreamEvent,
135 ): OrchestrationV2ShellSnapshot {
136 if (event.sequence <= snapshot.snapshotSequence) return snapshot;
137
@@ -217,9 +214,9 @@ function batchRows<T extends { readonly id: unknown }>(rows: ReadonlyArray<T>) {
214 };
215 }
216
220 -export type ShellStreamEvent = Exclude<
217 +export type ShellStreamEvent = Extract<
218 OrchestrationV2ShellStreamItem,
222 - { readonly kind: "snapshot" } | { readonly kind: "synchronized" }
219 + { readonly sequence: number }
220 >;
221
222 /** Apply ordered deltas with one index and at most one new array per collection. */
packages/contracts/src/orchestrationV2.ts
+12
@@ -2243,6 +2243,13 @@ export const OrchestrationV2ShellStreamItem = Schema.Union([
2243 Schema.Struct({
2244 kind: Schema.Literal("synchronized"),
2245 }),
2246 + /**
2247 + * The only item of a resume the server cannot replay when the client asked for
2248 + * `httpSnapshotFallback`: load the HTTP snapshot and subscribe again from its cursor.
2249 + */
2250 + Schema.Struct({
2251 + kind: Schema.Literal("snapshot-required"),
2252 + }),
2253 Schema.Struct({
2254 kind: Schema.Literal("snapshot"),
2255 snapshot: OrchestrationV2ShellSnapshot,
@@ -3692,6 +3699,11 @@ export type OrchestrationV2GetThreadProjectionInput =
3699
3700 export const OrchestrationV2SubscribeShellInput = Schema.Struct({
3701 afterSequence: Schema.optionalKey(NonNegativeInt),
3702 + /**
3703 + * With `afterSequence`, a gap the server cannot replay answers `snapshot-required` instead of
3704 + * a socket snapshot, which clients without transport compression download over gzip HTTP.
3705 + */
3706 + httpSnapshotFallback: Schema.optionalKey(Schema.Literal(true)),
3707 requestCompletionMarker: Schema.optionalKey(Schema.Boolean),
3708 /**
3709 * Snapshots leave out idle subagent children; read them with `getThreadFamily`. Send only to