Skip to content

Commit 61328be

Browse files
t3dotggclaude
andcommitted
perf(shell): new sessions resume the cached thread list instead of downloading it
Every new RPC session loaded the full HTTP shell snapshot (1.97 MB, 157 KB gzip on real data), even when the cache was seconds old. A shell now remembers its resume key (the server process key, the client build and the snapshot flags) and when its latest authoritative snapshot was applied. A new session resumes from the cursor when the key matches and that snapshot is under a day old. The server replays a gap without reading payloads: one grouped query finds each touched project and thread, and their current rows are sent once. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 8045537 commit 61328be

22 files changed

Lines changed: 935 additions & 224 deletions

File tree

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

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -204,11 +204,14 @@ describe("mobile SQLite environment cache store", () => {
204204
const store = yield* make().pipe(
205205
Effect.provideService(MobileDatabase.MobileDatabase, memory.database),
206206
);
207+
const resume = { key: "resume-key", syncedAt: 1_753_790_400_000 };
207208

208-
yield* store.saveShell(ENVIRONMENT_ID, SHELL_SNAPSHOT);
209+
yield* store.saveShell(ENVIRONMENT_ID, SHELL_SNAPSHOT, resume);
209210
yield* store.saveThread(ENVIRONMENT_ID, THREAD_SNAPSHOT);
210211

211-
const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID));
212+
const cached = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID));
213+
const shell = cached.snapshot;
214+
expect(cached.resume).toEqual(resume);
212215
const thread = Option.getOrThrow(yield* store.loadThread(ENVIRONMENT_ID, THREAD_ID));
213216

214217
expect(DateTime.formatIso(shell.threads[0]!.updatedAt)).toBe("2026-07-29T12:00:00.000Z");
@@ -257,7 +260,7 @@ describe("mobile SQLite environment cache store", () => {
257260
threads: [linked, unlinked],
258261
});
259262

260-
const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID));
263+
const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID)).snapshot;
261264
expect(shell.threads.map((thread) => thread.pullRequests)).toEqual([undefined, undefined]);
262265
const links = yield* shell.loadPullRequests!;
263266
expect([...links]).toEqual([[THREAD_ID, [link]]]);
@@ -298,7 +301,7 @@ describe("mobile SQLite environment cache store", () => {
298301
payload.snapshot.threads[0].pullRequests = [{ number: -1 }];
299302
memory.values.set(id, JSON.stringify(payload));
300303

301-
const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID));
304+
const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID)).snapshot;
302305
expect(shell.threads.map((thread) => thread.id)).toEqual([THREAD_ID, readable.id]);
303306
expect([...(yield* shell.loadPullRequests!)]).toEqual([[readable.id, [link]]]);
304307
expect(messages).toHaveLength(1);

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

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,12 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
111111
operation: "load-shell",
112112
decode: decodeStoredShellSnapshot,
113113
select: (stored) =>
114-
stored.environmentId === environmentId ? Option.some(stored.snapshot) : Option.none(),
114+
stored.environmentId === environmentId
115+
? Option.some({
116+
snapshot: stored.snapshot,
117+
...(stored.resume === undefined ? {} : { resume: stored.resume }),
118+
})
119+
: Option.none(),
115120
}).pipe(
116121
Effect.zipWith(
117122
Effect.promise(() => projectFaviconDatabaseCache.hydrate()),
@@ -120,16 +125,25 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
120125
),
121126
),
122127
),
123-
saveShell: Effect.fn("MobileEnvironmentCache.saveShell")(function* (environmentId, snapshot) {
124-
const payload = yield* encodeStoredShellSnapshot({
125-
schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
126-
environmentId,
127-
snapshot,
128-
}).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
129-
yield* database
130-
.saveCache(environmentId, "shell", "snapshot", ORCHESTRATION_CACHE_SCHEMA_VERSION, payload)
131-
.pipe(Effect.mapError(mapDatabaseError("save-shell")));
132-
}),
128+
saveShell: Effect.fn("MobileEnvironmentCache.saveShell")(
129+
function* (environmentId, snapshot, resume) {
130+
const payload = yield* encodeStoredShellSnapshot({
131+
schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
132+
environmentId,
133+
snapshot,
134+
...(resume === undefined ? {} : { resume }),
135+
}).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
136+
yield* database
137+
.saveCache(
138+
environmentId,
139+
"shell",
140+
"snapshot",
141+
ORCHESTRATION_CACHE_SCHEMA_VERSION,
142+
payload,
143+
)
144+
.pipe(Effect.mapError(mapDatabaseError("save-shell")));
145+
},
146+
),
133147
loadThread: Effect.fn("MobileEnvironmentCache.loadThread")((environmentId, threadId) =>
134148
loadDecodedCache({
135149
database,

‎apps/mobile/src/connection/platform.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,10 @@ import * as Layer from "effect/Layer";
1616
import * as Option from "effect/Option";
1717
import * as Queue from "effect/Queue";
1818
import * as Stream from "effect/Stream";
19+
import * as Application from "expo-application";
1920
import Constants from "expo-constants";
2021
import * as Network from "expo-network";
22+
import * as Updates from "expo-updates";
2123
import { AppState } from "react-native";
2224

2325
import { authClientMetadata } from "../lib/authClientMetadata";
@@ -213,6 +215,12 @@ const layerCapabilities = Layer.effectContext(
213215
ClientCapabilities.ClientPresentation,
214216
ClientCapabilities.ClientPresentation.of({
215217
metadata: authClientMetadata(Constants.expoConfig?.version),
218+
// Store builds can share a version, and over-the-air updates keep the native build.
219+
build: [
220+
Constants.expoConfig?.version,
221+
Application.nativeBuildVersion,
222+
Updates.updateId ?? "embedded",
223+
].join(" "),
216224
}),
217225
),
218226
Context.add(

‎apps/server/src/orchestration-v2/ShellStream.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import {
2424
omitIdleSubagentShells,
2525
shellStreamItemFromEnrichmentRefresh,
2626
shellStreamItemsFromInitialSnapshot,
27+
ShellResumeKey,
2728
shouldPublishShellApplicationEvent,
2829
skipUnchangedThreadShells,
2930
} from "./ShellStream.ts";
@@ -574,3 +575,16 @@ describe("skipUnchangedThreadShells", () => {
574575
}),
575576
);
576577
});
578+
579+
describe("shell resume key", () => {
580+
it.effect("stays one value for the whole server process", () =>
581+
Effect.gen(function* () {
582+
// Each socket reads it on its own fiber, which falls back to the cached default.
583+
const read = Effect.gen(function* () {
584+
return yield* ShellResumeKey;
585+
});
586+
const [first, second] = yield* Effect.all([read, read], { concurrency: "unbounded" });
587+
expect(second).toBe(first);
588+
}),
589+
);
590+
});

‎apps/server/src/orchestration-v2/ShellStream.ts‎

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,14 @@ import {
1212
isLiveSubagentShell,
1313
OrchestrationProjectShell as ProjectShellSchema,
1414
OrchestrationV2ThreadShell as ThreadShellSchema,
15+
ProjectId,
16+
ThreadId,
1517
} from "@t3tools/contracts";
1618
import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
1719
import type * as Arr from "effect/Array";
1820
import type * as Cause from "effect/Cause";
1921
import * as Clock from "effect/Clock";
22+
import * as Context from "effect/Context";
2023
import * as Deferred from "effect/Deferred";
2124
import * as Effect from "effect/Effect";
2225
import * as Exit from "effect/Exit";
@@ -25,6 +28,7 @@ import * as Schema from "effect/Schema";
2528
import type * as SqlClient from "effect/sql/SqlClient";
2629
import * as Stream from "effect/Stream";
2730

31+
import type { ShellReplayHead } from "../persistence/OrchestrationEventStore.ts";
2832
import { bufferLatestLiveStream } from "./LiveStreamBudget.ts";
2933

3034
type ShellDelta = Extract<OrchestrationV2ShellStreamItem, { readonly sequence: number }>;
@@ -150,7 +154,14 @@ export type ShellApplicationEvent =
150154
readonly event: Pick<OrchestrationV2StoredEvent["event"], "threadId">;
151155
};
152156

153-
/** Focused subagents receive these updates through their thread subscription. */
157+
/** Subagent events the shell skips; focused subagents receive them through their thread subscription. */
158+
export const SUBAGENT_TRANSCRIPT_EVENT_TYPES: ReadonlySet<string> = new Set([
159+
"node.updated",
160+
"turn-item.updated",
161+
"provider-turn.updated",
162+
"message.updated",
163+
]);
164+
154165
export function shouldPublishShellApplicationEvent(
155166
stored: ApplicationStoredEvent,
156167
subagentThreadIds: Set<string>,
@@ -168,14 +179,22 @@ export function shouldPublishShellApplicationEvent(
168179
return true;
169180
}
170181
return !(
171-
subagentThreadIds.has(event.threadId) &&
172-
(event.type === "node.updated" ||
173-
event.type === "turn-item.updated" ||
174-
event.type === "provider-turn.updated" ||
175-
event.type === "message.updated")
182+
subagentThreadIds.has(event.threadId) && SUBAGENT_TRANSCRIPT_EVENT_TYPES.has(event.type)
176183
);
177184
}
178185

186+
/**
187+
* `ServerConfig.shellResumeKey`. The default is computed once and cached on the reference, so it
188+
* is one random value per server process; tests provide their own.
189+
*/
190+
export class ShellResumeKey extends Context.Reference<string>(
191+
"@t3tools/server/orchestration-v2/ShellStream/ShellResumeKey",
192+
{
193+
// @effect-diagnostics-next-line cryptoRandomUUID:off - A reference default runs outside Effect.
194+
defaultValue: () => crypto.randomUUID(),
195+
},
196+
) {}
197+
179198
/** Shell updates refetch an aggregate; drop transcript bodies before retaining an event. */
180199
export function toShellApplicationEvent(stored: ApplicationStoredEvent): ShellApplicationEvent {
181200
return "aggregateKind" in stored
@@ -188,6 +207,18 @@ export function toShellApplicationEvent(stored: ApplicationStoredEvent): ShellAp
188207
: { sequence: stored.sequence, event: { threadId: stored.event.threadId } };
189208
}
190209

210+
export function shellApplicationEventFromReplayHead(head: ShellReplayHead): ShellApplicationEvent {
211+
return head.aggregateKind === "project"
212+
? {
213+
aggregateKind: "project",
214+
aggregateId: ProjectId.make(head.aggregateId),
215+
// Only a deletion skips the row read; any other project event, even an unknown one, reads it.
216+
type: head.eventType === "project.deleted" ? "project.deleted" : "project.meta-updated",
217+
sequence: head.sequence,
218+
}
219+
: { sequence: head.sequence, event: { threadId: ThreadId.make(head.aggregateId) } };
220+
}
221+
191222
export function coalesceShellApplicationEvents<A extends ShellApplicationEvent>(
192223
events: ReadonlyArray<A>,
193224
): ReadonlyArray<A> {

‎apps/server/src/persistence/OrchestrationEventStore.test.ts‎

Lines changed: 68 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -209,11 +209,6 @@ layer("OrchestrationEventStore", (it) => {
209209
maxEvents: events.length,
210210
});
211211
assert.isAbove(stats.rawPayloadBytes, prompt.length * 6);
212-
const applicationStats = yield* store.getReplayStats({
213-
afterSequence,
214-
throughSequence: yield* store.latestApplicationSequence,
215-
});
216-
assert.isAbove(applicationStats.rawPayloadBytes, prompt.length * 6);
217212
}),
218213
);
219214

@@ -456,14 +451,77 @@ layer("OrchestrationEventStore", (it) => {
456451
rawPayloadBytes: 0,
457452
hasCreateEvent: false,
458453
});
459-
assert.deepEqual(
460-
yield* store.getReplayStats({ afterSequence: baseline, throughSequence: head }),
454+
}),
455+
);
456+
457+
it.effect("finds the newest shell event of each project and thread in a range", () =>
458+
Effect.gen(function* () {
459+
const store = yield* OrchestrationEventStore.OrchestrationEventStore;
460+
const sql = yield* SqlClient.SqlClient;
461+
const baseline = yield* store.latestApplicationSequence;
462+
const versions = new Map<string, number>();
463+
const insert = Effect.fn(function* (
464+
aggregateKind: "project" | "thread",
465+
streamId: string,
466+
eventType: string,
467+
applicationEventVersion = 2,
468+
) {
469+
const streamVersion = versions.get(streamId) ?? 0;
470+
versions.set(streamId, streamVersion + 1);
471+
const rows = yield* sql<{ readonly sequence: number }>`
472+
INSERT INTO orchestration_events (
473+
event_id, aggregate_kind, stream_id, stream_version, event_type,
474+
occurred_at, actor_kind, payload_json, metadata_json, application_event_version
475+
) VALUES (
476+
${`heads:${streamId}:${streamVersion}`}, ${aggregateKind}, ${streamId}, ${streamVersion},
477+
${eventType}, '2026-09-04T00:00:00.000Z', 'server', 'not JSON', '{}',
478+
${applicationEventVersion}
479+
) RETURNING sequence
480+
`;
481+
return rows[0]!.sequence;
482+
});
483+
yield* insert("thread", "heads:parent", "thread.created");
484+
const projectHead = yield* insert("project", "heads:project", "project.deleted");
485+
const childHead = yield* insert("thread", "heads:child", "thread.metadata-updated");
486+
yield* insert("thread", "heads:child", "turn-item.updated");
487+
// Legacy rows are not application events.
488+
yield* insert("thread", "heads:legacy", "thread.metadata-updated", 1);
489+
const parentHead = yield* insert("thread", "heads:parent", "future.event");
490+
const head = yield* store.latestApplicationSequence;
491+
const read = (input: { readonly afterSequence?: number; readonly limit?: number } = {}) =>
492+
store.readShellReplayHeads({
493+
afterSequence: input.afterSequence ?? baseline,
494+
throughSequence: head,
495+
transcriptEventTypes: ["turn-item.updated"],
496+
skipTranscriptOf: ["heads:child"],
497+
limit: input.limit ?? 10,
498+
});
499+
500+
assert.deepEqual(yield* read(), [
461501
{
462-
eventCount: 3,
463-
rawPayloadBytes:
464-
Buffer.byteLength(unicodePayload) + 2 * Buffer.byteLength(oversizedPayload),
502+
aggregateKind: "project",
503+
aggregateId: "heads:project",
504+
sequence: projectHead,
505+
eventType: "project.deleted",
506+
},
507+
{
508+
aggregateKind: "thread",
509+
aggregateId: "heads:child",
510+
sequence: childHead,
511+
eventType: "thread.metadata-updated",
465512
},
513+
{
514+
aggregateKind: "thread",
515+
aggregateId: "heads:parent",
516+
sequence: parentHead,
517+
eventType: "future.event",
518+
},
519+
]);
520+
assert.deepEqual(
521+
(yield* read({ limit: 2 })).map((row) => row.aggregateId),
522+
["heads:project", "heads:child"],
466523
);
524+
assert.deepEqual(yield* read({ afterSequence: parentHead }), []);
467525
}),
468526
);
469527

0 commit comments

Comments
 (0)