Skip to content

Commit 9557ab4

Browse files
perf(mobile): thread list resumes from the saved cache, and large gaps reload over gzip HTTP (#32287)
Co-authored-by: Claude Fable 5.1 <[email protected]>
1 parent d456cd7 commit 9557ab4

11 files changed

Lines changed: 442 additions & 126 deletions

File tree

‎apps/mobile/src/connection/environment-cache-store.test.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -498,12 +498,21 @@ describe("mobile SQLite environment cache store", () => {
498498
Effect.provideService(MobileDatabase.MobileDatabase, memory.database),
499499
);
500500

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);
502509
yield* store.saveThread(ENVIRONMENT_ID, THREAD_SNAPSHOT);
503510

504511
const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID));
505512
const thread = Option.getOrThrow(yield* store.loadThread(ENVIRONMENT_ID, THREAD_ID));
506513

514+
expect(shell.origin).toEqual(origin);
515+
507516
expect(DateTime.formatIso(shell.threads[0]!.updatedAt)).toBe("2026-07-29T12:00:00.000Z");
508517
expect(DateTime.formatIso(shell.threads[0]!.latestUserMessageAt!)).toBe(
509518
"2026-07-29T12:00:00.000Z",

‎apps/mobile/src/connection/environment-cache-store.ts‎

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,13 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
106106
operation: "load-shell",
107107
decode: decodeStoredShellSnapshot,
108108
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(),
110116
}).pipe(
111117
Effect.zipWith(
112118
Effect.promise(() => projectFaviconDatabaseCache.hydrate()),
@@ -115,16 +121,25 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
115121
),
116122
),
117123
),
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+
),
128143
loadThread: Effect.fn("MobileEnvironmentCache.loadThread")((environmentId, threadId) =>
129144
loadDecodedCache({
130145
database,

‎apps/server/src/ws.test.ts‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1436,10 +1436,15 @@ it.effect("a publish whose push fails still refreshes the new remote", () =>
14361436
),
14371437
);
14381438

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 }) =>
14431448
Effect.gen(function* () {
14441449
const sql = yield* SqlClient.SqlClient;
14451450
const now = "2026-10-13T00:00:00.000Z";
@@ -1463,11 +1468,18 @@ it.effect.each(["thread", "shell"] as const)(
14631468
) VALUES (${OrchestrationEventStore.EVENT_LOG_PRUNED_THROUGH}, 2, ${second!.sequence}, ${now})
14641469
`;
14651470
const subscription = Effect.gen(function* () {
1466-
const stream =
1471+
const items: ReadonlyArray<unknown> =
14671472
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;
14711483
});
14721484
const exit = yield* subscription.pipe(
14731485
Effect.provideService(ThreadManagement.ThreadManagementService, {
@@ -1489,7 +1501,10 @@ it.effect.each(["thread", "shell"] as const)(
14891501
} as ProjectEnrichment.ProjectEnrichmentService["Service"]),
14901502
Effect.exit,
14911503
);
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+
);
14931508
}).pipe(Effect.scoped, Effect.provide(ReplayTestLayer)),
14941509
);
14951510

‎apps/server/src/ws.ts‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ import {
6464
OrchestrationV2ThreadLaunchError,
6565
type OrchestrationProjectShell,
6666
type OrchestrationV2ShellSnapshot,
67+
type OrchestrationV2ShellStreamItem,
6768
type OrchestrationV2ThreadStreamItem,
6869
type ApplicationStoredEvent,
6970
type ProjectEntriesFailure,
@@ -1115,6 +1116,7 @@ export const subscribeOrchestrationV2Thread = Effect.fn("ws.orchestrationV2.subs
11151116
export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subscribeShell")(
11161117
function* (input: {
11171118
readonly afterSequence?: number;
1119+
readonly httpSnapshotFallback?: true;
11181120
readonly requestCompletionMarker?: boolean;
11191121
readonly omitIdleSubagents?: boolean;
11201122
readonly omitOlderSettled?: boolean;
@@ -1325,14 +1327,20 @@ export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subsc
13251327
});
13261328
}
13271329

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",
13351332
});
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+
});
13361344
const highWater = yield* applicationEvents.latestApplicationSequence;
13371345
if (!(yield* canReplayPersistedRange(input.afterSequence, highWater, SHELL_RESUME_MAX_GAP))) {
13381346
return yield* fromSnapshot;

‎apps/web/src/connection/storage.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -846,7 +846,11 @@ export const layer = Layer.effectContext(
846846
Effect.mapError((cause) => persistenceError("load-shell", cause)),
847847
Effect.map((stored) =>
848848
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+
)
850854
: Option.none(),
851855
),
852856
),
@@ -857,11 +861,12 @@ export const layer = Layer.effectContext(
857861
);
858862
}),
859863
saveShell: Effect.fn("storage.saveShell")(
860-
function* (environmentId, snapshot) {
864+
function* (environmentId, snapshot, origin) {
861865
const encoded = yield* encodeStoredShellSnapshot({
862866
schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
863867
environmentId,
864868
snapshot,
869+
...(origin === undefined ? {} : { origin }),
865870
}).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
866871
yield* writeDatabaseValue(database, SHELL_STORE_NAME, environmentId, encoded);
867872
},

‎packages/client-runtime/src/platform/orchestrationCache.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,25 @@ export const ORCHESTRATION_CACHE_SCHEMA_VERSION = 3 as const;
1313
// Older caches may contain human turns that bypassed server history budgets.
1414
export const ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION = 5 as const;
1515

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+
1630
export const StoredOrchestrationShellSnapshot = Schema.Struct({
1731
schemaVersion: Schema.Literal(ORCHESTRATION_CACHE_SCHEMA_VERSION),
1832
environmentId: EnvironmentId,
1933
snapshot: OrchestrationV2ShellSnapshotJson,
34+
origin: Schema.optionalKey(ShellCacheOrigin),
2035
});
2136

2237
export const StoredOrchestrationThreadSnapshot = Schema.Struct({

‎packages/client-runtime/src/platform/persistence.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,13 @@ import * as Schema from "effect/Schema";
1414
import type { ConnectionRegistration } from "../connection/catalog.ts";
1515
import type { DeferredShellSnapshot } from "../state/shellPullRequests.ts";
1616
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+
}
1724

1825
export class ConnectionPersistenceError extends Schema.TaggedError<ConnectionPersistenceError>()(
1926
"ConnectionPersistenceError",
@@ -82,10 +89,12 @@ export class EnvironmentCacheStore extends Context.Service<
8289
{
8390
readonly loadShell: (
8491
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. */
8694
readonly saveShell: (
8795
environmentId: EnvironmentId,
8896
snapshot: OrchestrationV2ShellSnapshot,
97+
origin?: ShellCacheOrigin,
8998
) => Effect.Effect<void, ConnectionPersistenceError>;
9099
readonly loadThread: (
91100
environmentId: EnvironmentId,

0 commit comments

Comments
 (0)