The best way to control Claude Code, Codex and more from any computer or phone
fix(client): finishing a long background thread no longer freezes the app (#33503)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 9, 2026 at 11:26 UTC
077fd62222a94b2264ad4525aa4e25bdb29d5029
7 files changed
+461
-51
apps/mobile/src/connection/environment-cache-store.test.ts
+78
@@ -2,6 +2,7 @@ import {
2
ORCHESTRATION_CACHE_SCHEMA_VERSION,
3
ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
4
COMPACT_THREAD_CACHE_SCHEMA_VERSION,
5
+ type ConnectionPersistenceError,
6
StoredOrchestrationThreadSnapshot,
7
} from "@t3tools/client-runtime/platform";
8
import {
@@ -19,6 +20,7 @@ import {
20
import { describe, expect, it } from "@effect/vitest";
21
import * as DateTime from "effect/DateTime";
22
import * as Effect from "effect/Effect";
23
+import * as Fiber from "effect/Fiber";
24
import * as Logger from "effect/Logger";
25
import * as Option from "effect/Option";
26
import * as Schema from "effect/Schema";
@@ -213,6 +215,35 @@ function threadSnapshotWithItems(): OrchestrationV2ThreadDetailSnapshot {
215
};
216
}
217
218
+// More rows than one encoding chunk, so a cold save yields to the host mid-encode.
219
+function threadSnapshotWithManyItems(
220
+ snapshotSequence: number,
221
+ message = "A settled local notice.",
222
+): OrchestrationV2ThreadDetailSnapshot {
223
+ const base = threadSnapshotWithItems();
224
+ const turnItems = Array.from({ length: 40 }, (_, index) => ({
225
+ ...base.projection.turnItems[0]!,
226
+ id: TurnItemId.make(`notice-${snapshotSequence}-${index}`),
227
+ ordinal: index,
228
+ message,
229
+ }));
230
+ return {
231
+ ...THREAD_SNAPSHOT,
232
+ snapshotSequence,
233
+ projection: {
234
+ ...THREAD_SNAPSHOT.projection,
235
+ turnItems,
236
+ visibleTurnItems: turnItems.map((item, position) => ({
237
+ position,
238
+ visibility: "local" as const,
239
+ sourceThreadId: THREAD_ID,
240
+ sourceItemId: item.id,
241
+ item,
242
+ })),
243
+ },
244
+ };
245
+}
246
+
247
function makeDatabase() {
248
const values = new Map<string, string>();
249
const schemaVersions = new Map<string, number>();
@@ -608,6 +639,53 @@ describe("mobile SQLite environment cache store", () => {
639
}).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
640
});
641
642
+ it.effect("does not write a save that a removal, clear, or newer save overtook", () =>
643
+ Effect.gen(function* () {
644
+ const id = cacheId(ENVIRONMENT_ID, "thread", THREAD_ID);
645
+ const overtake = Effect.fn("overtake")(function* (
646
+ later: (
647
+ store: Effect.Success<ReturnType<typeof make>>,
648
+ ) => Effect.Effect<void, ConnectionPersistenceError>,
649
+ ) {
650
+ const memory = makeDatabase();
651
+ const store = yield* make().pipe(
652
+ Effect.provideService(MobileDatabase.MobileDatabase, memory.database),
653
+ );
654
+ const older = yield* store
655
+ .saveThread(ENVIRONMENT_ID, threadSnapshotWithManyItems(1))
656
+ .pipe(Effect.forkChild({ startImmediately: true }));
657
+ yield* later(store);
658
+ yield* Fiber.join(older);
659
+ return { memory, store };
660
+ });
661
+
662
+ const removed = yield* overtake((store) => store.removeThread(ENVIRONMENT_ID, THREAD_ID));
663
+ expect(removed.memory.values.has(id)).toBe(false);
664
+ const cleared = yield* overtake((store) => store.clear(ENVIRONMENT_ID));
665
+ expect(cleared.memory.values.has(id)).toBe(false);
666
+ const replaced = yield* overtake((store) =>
667
+ store.saveThread(ENVIRONMENT_ID, { ...THREAD_SNAPSHOT, snapshotSequence: 2 }),
668
+ );
669
+ const kept = yield* replaced.store.loadThread(ENVIRONMENT_ID, THREAD_ID);
670
+ expect(Option.getOrThrow(kept).snapshotSequence).toBe(2);
671
+ }),
672
+ );
673
+
674
+ it.effect("removes the older copy of a thread that grew past the cache limit", () =>
675
+ Effect.gen(function* () {
676
+ const memory = makeDatabase();
677
+ const store = yield* make().pipe(
678
+ Effect.provideService(MobileDatabase.MobileDatabase, memory.database),
679
+ );
680
+ const id = cacheId(ENVIRONMENT_ID, "thread", THREAD_ID);
681
+ yield* store.saveThread(ENVIRONMENT_ID, threadSnapshotWithItems());
682
+ expect(memory.values.has(id)).toBe(true);
683
+ yield* store.saveThread(ENVIRONMENT_ID, threadSnapshotWithManyItems(2, "x".repeat(200_000)));
684
+ expect(memory.values.has(id)).toBe(false);
685
+ expect(memory.removed).toEqual([id]);
686
+ }),
687
+ );
688
+
689
it.effect("deletes a corrupt cache record and treats it as a miss", () =>
690
Effect.gen(function* () {
691
const memory = makeDatabase();
apps/mobile/src/connection/environment-cache-store.ts
+28
-12
@@ -2,9 +2,10 @@ import {
2
ORCHESTRATION_CACHE_SCHEMA_VERSION,
3
COMPACT_THREAD_CACHE_SCHEMA_VERSION,
4
decodeStoredThreadSnapshot,
5
- encodeStoredThreadSnapshot,
5
Persistence,
6
makeStoredShellSnapshotEncoder,
7
+ makeStoredThreadSnapshotEncoder,
8
+ makeThreadCacheWriteOrder,
9
} from "@t3tools/client-runtime/platform";
10
import { type EnvironmentId, ServerConfig, VcsListRefsResult } from "@t3tools/contracts";
11
import * as Effect from "effect/Effect";
@@ -96,6 +97,8 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
97
const database = yield* MobileDatabase.MobileDatabase;
98
attachProjectFaviconDatabase(database);
99
const encodeStoredShellSnapshot = makeStoredShellSnapshotEncoder();
100
+ const encodeStoredThreadSnapshot = makeStoredThreadSnapshotEncoder({ format: "compact" });
101
+ const threadWriteOrder = makeThreadCacheWriteOrder();
102
return Persistence.EnvironmentCacheStore.of({
103
loadShell: Effect.fn("MobileEnvironmentCache.loadShell")((environmentId) =>
104
loadDecodedCache({
@@ -156,20 +159,32 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
159
),
160
saveThread: Effect.fn("MobileEnvironmentCache.saveThread")(function* (environmentId, snapshot) {
161
const threadId = snapshot.projection.thread.id;
162
+ const isLatest = threadWriteOrder.beginSave(environmentId, threadId);
163
const payload = yield* encodeStoredThreadSnapshot({
164
environmentId,
165
threadId,
166
snapshot,
167
}).pipe(Effect.mapError((cause) => persistenceError("save-thread", cause)));
164
- yield* database
165
- .saveCache(environmentId, "thread", threadId, COMPACT_THREAD_CACHE_SCHEMA_VERSION, payload)
166
- .pipe(Effect.mapError(mapDatabaseError("save-thread")));
168
+ if (!isLatest()) return;
169
+ // An older copy of a thread now too large to keep would paint stale on reopen.
170
+ yield* Option.match(payload, {
171
+ onNone: () => database.removeCache(environmentId, "thread", threadId),
172
+ onSome: (encoded) =>
173
+ database.saveCache(
174
+ environmentId,
175
+ "thread",
176
+ threadId,
177
+ COMPACT_THREAD_CACHE_SCHEMA_VERSION,
178
+ encoded,
179
+ ),
180
+ }).pipe(Effect.mapError(mapDatabaseError("save-thread")));
181
}),
168
- removeThread: Effect.fn("MobileEnvironmentCache.removeThread")((environmentId, threadId) =>
169
- database
182
+ removeThread: Effect.fn("MobileEnvironmentCache.removeThread")((environmentId, threadId) => {
183
+ threadWriteOrder.removeThread(environmentId, threadId);
184
+ return database
185
.removeCache(environmentId, "thread", threadId)
171
- .pipe(Effect.mapError(mapDatabaseError("remove-thread"))),
172
- ),
186
+ .pipe(Effect.mapError(mapDatabaseError("remove-thread")));
187
+ }),
188
loadServerConfig: Effect.fn("MobileEnvironmentCache.loadServerConfig")((environmentId) =>
189
loadDecodedCache({
190
database,
@@ -237,12 +252,13 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
252
.clearCacheKind(environmentId, "vcs-refs")
253
.pipe(Effect.mapError(mapDatabaseError("clear-vcs-refs"))),
254
),
240
- clear: Effect.fn("MobileEnvironmentCache.clear")((environmentId) =>
241
- Effect.promise(() => projectFaviconDatabaseCache.clearEnvironment(environmentId)).pipe(
255
+ clear: Effect.fn("MobileEnvironmentCache.clear")((environmentId) => {
256
+ threadWriteOrder.clearEnvironment(environmentId);
257
+ return Effect.promise(() => projectFaviconDatabaseCache.clearEnvironment(environmentId)).pipe(
258
Effect.andThen(database.clearEnvironmentCache(environmentId)),
259
Effect.mapError(mapDatabaseError("clear-environment")),
244
- ),
245
- ),
260
+ );
261
+ }),
262
});
263
});
264
apps/web/src/connection/storage.ts
+17
-9
@@ -3,7 +3,6 @@ import {
3
type ConnectionCatalogDocument as ConnectionCatalogDocumentType,
4
EMPTY_CONNECTION_CATALOG_DOCUMENT,
5
ORCHESTRATION_CACHE_SCHEMA_VERSION,
6
- ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
6
StoredOrchestrationShellSnapshot,
7
StoredOrchestrationThreadSnapshot,
8
decodeOrDiscardOrchestrationCache,
@@ -16,6 +15,8 @@ import {
15
replaceCatalogValue,
16
Persistence,
17
makeStoredShellSnapshotEncoder,
18
+ makeStoredThreadSnapshotEncoder,
19
+ makeThreadCacheWriteOrder,
20
} from "@t3tools/client-runtime/platform";
21
import { TokenStore } from "@t3tools/client-runtime/authorization";
22
import {
@@ -87,7 +88,6 @@ const decodeConnectionCatalogDocument = Schema.decodeUnknownEffect(ConnectionCat
88
const encodeConnectionCatalogDocument = Schema.encodeEffect(ConnectionCatalogDocumentJson);
89
const decodeStoredShellSnapshot = Schema.decodeUnknownEffect(StoredShellSnapshotJson);
90
const decodeStoredThreadSnapshot = Schema.decodeUnknownEffect(StoredThreadSnapshotJson);
90
-const encodeStoredThreadSnapshot = Schema.encodeEffect(StoredThreadSnapshotJson);
91
const decodeStoredServerConfig = Schema.decodeUnknownEffect(StoredServerConfigJson);
92
const encodeStoredServerConfig = Schema.encodeEffect(StoredServerConfigJson);
93
const decodeStoredVcsRefs = Schema.decodeUnknownEffect(StoredVcsRefsJson);
@@ -723,6 +723,11 @@ export const layer = Layer.effectContext(
723
const encodeStoredShellSnapshot = makeStoredShellSnapshotEncoder({
724
yieldToHost: yieldToBrowserTask,
725
});
726
+ const encodeStoredThreadSnapshot = makeStoredThreadSnapshotEncoder({
727
+ format: "full",
728
+ yieldToHost: yieldToBrowserTask,
729
+ });
730
+ const threadWriteOrder = makeThreadCacheWriteOrder();
731
732
const targetStore = Persistence.ConnectionTargetStore.of({
733
list: catalog.read.pipe(
@@ -948,18 +953,19 @@ export const layer = Layer.effectContext(
953
),
954
saveThread: Effect.fn("storage.saveThread")(
955
function* (environmentId, snapshot) {
956
+ const key = threadCacheKey(environmentId, snapshot.projection.thread.id);
957
+ const isLatest = threadWriteOrder.beginSave(environmentId, snapshot.projection.thread.id);
958
const encoded = yield* encodeStoredThreadSnapshot({
952
- schemaVersion: ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
959
environmentId,
960
threadId: snapshot.projection.thread.id,
961
snapshot,
962
}).pipe(Effect.mapError((cause) => persistenceError("save-thread", cause)));
957
- yield* writeDatabaseValue(
958
- database,
959
- THREAD_STORE_NAME,
960
- threadCacheKey(environmentId, snapshot.projection.thread.id),
961
- encoded,
962
- );
963
+ if (!isLatest()) return;
964
+ // An older copy of a thread now too large to keep would paint stale on reopen.
965
+ yield* Option.match(encoded, {
966
+ onNone: () => removeDatabaseValue(database, THREAD_STORE_NAME, key),
967
+ onSome: (payload) => writeDatabaseValue(database, THREAD_STORE_NAME, key, payload),
968
+ });
969
},
970
Effect.mapError((cause) =>
971
cause._tag === "ConnectionPersistenceError"
@@ -1036,6 +1042,7 @@ export const layer = Layer.effectContext(
1042
),
1043
removeThread: Effect.fn("Persistence.EnvironmentCacheStore.removeThread")(
1044
function (environmentId, threadId) {
1045
+ threadWriteOrder.removeThread(environmentId, threadId);
1046
return removeDatabaseValue(
1047
database,
1048
THREAD_STORE_NAME,
@@ -1044,6 +1051,7 @@ export const layer = Layer.effectContext(
1051
},
1052
),
1053
clear: Effect.fn("Persistence.EnvironmentCacheStore.clear")(function (environmentId) {
1054
+ threadWriteOrder.clearEnvironment(environmentId);
1055
return Effect.all(
1056
[
1057
Effect.promise(() => projectFaviconCache.clearEnvironment(environmentId)),
packages/client-runtime/src/platform/hostYield.ts
new
+11
@@ -0,0 +1,11 @@
1
+import * as Effect from "effect/Effect";
2
+
3
+// Effect's own yield resumes through `setImmediate` where the host defines it and a
4
+// zero-delay timer otherwise. React Native's `setImmediate` is a microtask shim, so
5
+// nothing from the host runs before the fiber resumes. A timer yields on every host;
6
+// a browser can pass a yield that its timer clamping and throttling do not slow.
7
+export const yieldToHostTimer = Effect.callback<void>((resume) => {
8
+ // @effect-diagnostics-next-line globalTimersInEffect:off - A host timer, not Effect.sleep, is the point.
9
+ const timer = setTimeout(() => resume(Effect.void), 0);
10
+ return Effect.sync(() => clearTimeout(timer));
11
+});
packages/client-runtime/src/platform/shellCacheEncoding.ts
+1
-10
@@ -2,20 +2,11 @@ import { OrchestrationV2ThreadShellJson } from "@t3tools/contracts";
2
import * as Effect from "effect/Effect";
3
import * as Schema from "effect/Schema";
4
5
+import { yieldToHostTimer } from "./hostYield.ts";
6
import { StoredOrchestrationShellSnapshot } from "./orchestrationCache.ts";
7
8
const ROWS_PER_CHUNK = 32;
9
9
-// Effect's own yield resumes through `setImmediate` where the host defines it and a
10
-// zero-delay timer otherwise. React Native's `setImmediate` is a microtask shim, so
11
-// nothing from the host runs before the fiber resumes. A timer yields on every host;
12
-// a browser can pass a yield that its timer clamping and throttling do not slow.
13
-const yieldToHostTimer = Effect.callback<void>((resume) => {
14
- // @effect-diagnostics-next-line globalTimersInEffect:off - A host timer, not Effect.sleep, is the point.
15
- const timer = setTimeout(() => resume(Effect.void), 0);
16
- return Effect.sync(() => clearTimeout(timer));
17
-});
18
-
10
const encodeThreadChunk = Schema.encodeEffect(Schema.Array(OrchestrationV2ThreadShellJson));
11
const EncodedRows = Schema.Array(Schema.Unknown);
12
const encodeEnvelope = Schema.encodeEffect(
packages/client-runtime/src/platform/threadCacheEncoding.test.ts
new
+141
@@ -0,0 +1,141 @@
1
+import { describe, expect, it } from "@effect/vitest";
2
+import {
3
+ EnvironmentId,
4
+ ThreadId,
5
+ TurnItemId,
6
+ type OrchestrationV2ThreadProjection,
7
+} from "@t3tools/contracts";
8
+import * as DateTime from "effect/DateTime";
9
+import * as Effect from "effect/Effect";
10
+import * as Option from "effect/Option";
11
+import * as Schema from "effect/Schema";
12
+
13
+import { v2Now, v2Projection, v2ThreadId } from "../state/orchestrationV2TestFixtures.ts";
14
+import {
15
+ ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
16
+ StoredOrchestrationThreadSnapshot,
17
+} from "./orchestrationCache.ts";
18
+import {
19
+ decodeStoredThreadSnapshot,
20
+ makeStoredThreadSnapshotEncoder,
21
+} from "./threadCacheEncoding.ts";
22
+
23
+const environmentId = EnvironmentId.make("environment-thread-cache");
24
+const otherThreadId = ThreadId.make("thread-parent");
25
+const encodeOriginal = Schema.encodeEffect(
26
+ Schema.fromJsonString(StoredOrchestrationThreadSnapshot),
27
+);
28
+
29
+const notice = (index: number, threadId = v2ThreadId) => ({
30
+ id: TurnItemId.make(`notice-${threadId}-${index}`),
31
+ threadId,
32
+ runId: null,
33
+ nodeId: null,
34
+ providerThreadId: null,
35
+ providerTurnId: null,
36
+ nativeItemRef: null,
37
+ parentItemId: null,
38
+ ordinal: index,
39
+ status: "completed" as const,
40
+ title: index % 2 === 0 ? null : ` Notice ${index} `,
41
+ startedAt: DateTime.add(v2Now, { seconds: index }),
42
+ completedAt: index % 3 === 0 ? null : v2Now,
43
+ updatedAt: v2Now,
44
+ type: "system_notice" as const,
45
+ message: `Notice ${index}`,
46
+});
47
+
48
+// Inherited rows come first, as in a fork, then local rows whose items alias turnItems.
49
+function projectionWith(count: number): OrchestrationV2ThreadProjection {
50
+ const inherited = Array.from({ length: 5 }, (_, index) => notice(index, otherThreadId));
51
+ const turnItems = Array.from({ length: count }, (_, index) => notice(index));
52
+ return {
53
+ ...v2Projection,
54
+ turnItems,
55
+ visibleTurnItems: [
56
+ ...inherited.map((item) => ({
57
+ position: 0,
58
+ visibility: "inherited" as const,
59
+ sourceThreadId: otherThreadId,
60
+ sourceItemId: item.id,
61
+ item,
62
+ })),
63
+ ...turnItems.map((item) => ({
64
+ position: 0,
65
+ visibility: "local" as const,
66
+ sourceThreadId: v2ThreadId,
67
+ sourceItemId: item.id,
68
+ item,
69
+ })),
70
+ ].map((row, position) => ({ ...row, position })),
71
+ };
72
+}
73
+
74
+const stored = (projection: OrchestrationV2ThreadProjection) => ({
75
+ environmentId,
76
+ threadId: v2ThreadId,
77
+ snapshot: { snapshotSequence: 7, projection, historyCursor: null, hasMoreHistory: false },
78
+});
79
+
80
+describe("cooperative thread cache encoding", () => {
81
+ it.effect("matches the plain encoding across chunks, cold and after rows change", () =>
82
+ Effect.gen(function* () {
83
+ const encode = makeStoredThreadSnapshotEncoder({ format: "full" });
84
+ const original = (projection: OrchestrationV2ThreadProjection) =>
85
+ encodeOriginal({
86
+ ...stored(projection),
87
+ schemaVersion: ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
88
+ });
89
+ const cold = projectionWith(70);
90
+ expect(yield* encode(stored(cold))).toEqual(Option.some(yield* original(cold)));
91
+
92
+ const [first, ...rest] = cold.turnItems;
93
+ const replaced = { ...first!, message: "Edited" };
94
+ const added = notice(70);
95
+ const warm: OrchestrationV2ThreadProjection = {
96
+ ...cold,
97
+ turnItems: [replaced, ...rest, added],
98
+ visibleTurnItems: [
99
+ ...cold.visibleTurnItems.map((row) =>
100
+ row.item === first ? { ...row, item: replaced } : row,
101
+ ),
102
+ {
103
+ position: cold.visibleTurnItems.length,
104
+ visibility: "local",
105
+ sourceThreadId: v2ThreadId,
106
+ sourceItemId: added.id,
107
+ item: added,
108
+ },
109
+ ],
110
+ };
111
+ expect(yield* encode(stored(warm))).toEqual(Option.some(yield* original(warm)));
112
+ }),
113
+ );
114
+
115
+ it.effect("round-trips the compact format", () =>
116
+ Effect.gen(function* () {
117
+ const projection = projectionWith(40);
118
+ const encoded = yield* makeStoredThreadSnapshotEncoder({ format: "compact" })(
119
+ stored(projection),
120
+ );
121
+ const decoded = yield* decodeStoredThreadSnapshot(Option.getOrThrow(encoded));
122
+ expect(decoded.snapshot.projection).toEqual(projection);
123
+ }),
124
+ );
125
+
126
+ it.effect("encodes nothing once the rows exceed the budget, warm or cold", () =>
127
+ Effect.gen(function* () {
128
+ const small = stored(projectionWith(4));
129
+ const large = stored(projectionWith(200));
130
+ const limit = Option.getOrThrow(
131
+ yield* makeStoredThreadSnapshotEncoder({ format: "full" })(small),
132
+ ).length;
133
+ for (const format of ["full", "compact"] as const) {
134
+ const encode = makeStoredThreadSnapshotEncoder({ format, maxJsonLength: limit });
135
+ expect(Option.isSome(yield* encode(small))).toBe(true);
136
+ expect(Option.isNone(yield* encode(large))).toBe(true);
137
+ expect(Option.isNone(yield* encode(large))).toBe(true);
138
+ }
139
+ }),
140
+ );
141
+});
packages/client-runtime/src/platform/threadCacheEncoding.ts
+185
-20
@@ -1,15 +1,29 @@
1
+import { OrchestrationV2ThreadProjectionJson } from "@t3tools/contracts";
2
import {
3
omitLocalVisibleTurnItems,
4
restoreLocalVisibleTurnItems,
5
} from "@t3tools/shared/orchestrationV2BoundedSnapshot";
6
import * as Effect from "effect/Effect";
7
+import * as Option from "effect/Option";
8
import * as Schema from "effect/Schema";
9
8
-import { StoredOrchestrationThreadSnapshot } from "./orchestrationCache.ts";
10
+import { yieldToHostTimer } from "./hostYield.ts";
11
+import {
12
+ ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
13
+ StoredOrchestrationThreadSnapshot,
14
+} from "./orchestrationCache.ts";
15
16
// Keep the full format for web/desktop; older clients discard compact records.
17
export const COMPACT_THREAD_CACHE_SCHEMA_VERSION = 6 as const;
18
19
+/**
20
+ * A thread followed live keeps every item it streams, so its projection can grow
21
+ * to hundreds of MB. Larger ones are not cached; reopening loads the bounded window.
22
+ */
23
+const THREAD_CACHE_MAX_JSON_LENGTH = 4 * 1024 * 1024;
24
+
25
+const ROWS_PER_CHUNK = 32;
26
+
27
const StoredCompactThreadSnapshot = StoredOrchestrationThreadSnapshot.mapFields((fields) => ({
28
...fields,
29
schemaVersion: Schema.Literal(COMPACT_THREAD_CACHE_SCHEMA_VERSION),
@@ -27,33 +41,184 @@ class InvalidThreadCache extends Schema.TaggedError<InvalidThreadCache>()(
41
{},
42
) {}
43
30
-const encodeCompact = Schema.encodeEffect(Schema.fromJsonString(StoredCompactThreadSnapshot));
44
const decodeCompatible = Schema.decodeUnknownEffect(
45
Schema.fromJsonString(
46
Schema.Union([StoredCompactThreadSnapshot, StoredOrchestrationThreadSnapshot]),
47
),
48
);
49
37
-export const encodeStoredThreadSnapshot = Effect.fn("ThreadCache.encode")(function* (
38
- stored: Pick<
39
- typeof StoredOrchestrationThreadSnapshot.Type,
40
- "environmentId" | "threadId" | "snapshot"
41
- >,
42
-) {
43
- const { snapshot } = stored;
44
- const compact = omitLocalVisibleTurnItems(snapshot.projection);
45
- return yield* encodeCompact({
46
- ...stored,
47
- schemaVersion: COMPACT_THREAD_CACHE_SCHEMA_VERSION,
48
- snapshot: {
49
- ...snapshot,
50
- projection: compact ?? snapshot.projection,
51
- turnItemsOmitLocalVisible: compact !== null,
52
- turnItemCount: snapshot.projection.turnItems.length,
53
- visibleTurnItemCount: snapshot.projection.visibleTurnItems.length,
50
+const EncodedRows = Schema.Array(Schema.Unknown);
51
+const ProjectionWithEncodedRows = OrchestrationV2ThreadProjectionJson.mapFields((fields) => ({
52
+ ...fields,
53
+ turnItems: EncodedRows,
54
+ visibleTurnItems: EncodedRows,
55
+}));
56
+const encodeFullEnvelope = Schema.encodeEffect(
57
+ Schema.fromJsonString(
58
+ StoredOrchestrationThreadSnapshot.mapFields((fields) => ({
59
+ ...fields,
60
+ snapshot: fields.snapshot.mapFields((snapshotFields) => ({
61
+ ...snapshotFields,
62
+ projection: ProjectionWithEncodedRows,
63
+ })),
64
+ })),
65
+ ),
66
+);
67
+const encodeCompactEnvelope = Schema.encodeEffect(
68
+ Schema.fromJsonString(
69
+ StoredCompactThreadSnapshot.mapFields((fields) => ({
70
+ ...fields,
71
+ snapshot: fields.snapshot.mapFields((snapshotFields) => ({
72
+ ...snapshotFields,
73
+ projection: ProjectionWithEncodedRows,
74
+ })),
75
+ })),
76
+ ),
77
+);
78
+const encodeTurnItemChunk = Schema.encodeEffect(
79
+ OrchestrationV2ThreadProjectionJson.fields.turnItems,
80
+);
81
+const encodeVisibleRowChunk = Schema.encodeEffect(
82
+ OrchestrationV2ThreadProjectionJson.fields.visibleTurnItems,
83
+);
84
+
85
+type StoredThread = Pick<
86
+ typeof StoredOrchestrationThreadSnapshot.Type,
87
+ "environmentId" | "threadId" | "snapshot"
88
+>;
89
+type Projection = StoredThread["snapshot"]["projection"];
90
+
91
+interface EncodedRow {
92
+ readonly encoded: unknown;
93
+ readonly length: number;
94
+}
95
+
96
+/**
97
+ * Thread saves yield while encoding, so they can finish after a later save, a
98
+ * removal, or an environment clear. Each takes a ticket when it starts; a save
99
+ * writes only while no newer ticket exists for its thread or environment.
100
+ */
101
+export function makeThreadCacheWriteOrder() {
102
+ let latest = 0;
103
+ const tickets = new Map<string, number>();
104
+ const threadKey = (environmentId: string, threadId: string) =>
105
+ `${environmentId}\u0000${threadId}`;
106
+ return {
107
+ beginSave: (environmentId: string, threadId: string) => {
108
+ const ticket = ++latest;
109
+ const key = threadKey(environmentId, threadId);
110
+ tickets.set(key, ticket);
111
+ return () => tickets.get(key) === ticket && (tickets.get(environmentId) ?? 0) < ticket;
112
+ },
113
+ removeThread: (environmentId: string, threadId: string) => {
114
+ tickets.set(threadKey(environmentId, threadId), ++latest);
115
},
116
+ clearEnvironment: (environmentId: string) => {
117
+ tickets.set(environmentId, ++latest);
118
+ },
119
+ };
120
+}
121
+
122
+/**
123
+ * Turn items are immutable and the projection reducer keeps unchanged ones by
124
+ * reference, so each encoder remembers the encoding of rows it has encoded and
125
+ * runs the row codec only for new ones, yielding to the host between chunks.
126
+ * Encodes to none once the rows exceed `maxJsonLength`, before the envelope.
127
+ */
128
+export function makeStoredThreadSnapshotEncoder(options: {
129
+ readonly format: "full" | "compact";
130
+ readonly yieldToHost?: Effect.Effect<void>;
131
+ readonly maxJsonLength?: number;
132
+}) {
133
+ const yieldToHost = options.yieldToHost ?? yieldToHostTimer;
134
+ const maxJsonLength = options.maxJsonLength ?? THREAD_CACHE_MAX_JSON_LENGTH;
135
+ const encodedTurnItems = new WeakMap<object, EncodedRow>();
136
+ const encodedVisibleRows = new WeakMap<object, EncodedRow>();
137
+
138
+ return Effect.fnUntraced(function* (stored: StoredThread) {
139
+ let hasWorked = false;
140
+ let length = 0;
141
+ const encodeRows =
142
+ /* Runs once per thread save inside the traced store call; avoid a span per row list. */
143
+ Effect.fnUntraced(function* <Row extends object>(
144
+ rows: ReadonlyArray<Row>,
145
+ cache: WeakMap<object, EncodedRow>,
146
+ encodeChunk: (
147
+ chunk: ReadonlyArray<Row>,
148
+ ) => Effect.Effect<ReadonlyArray<unknown>, Schema.SchemaError>,
149
+ ) {
150
+ let misses: Array<Row> = [];
151
+ const encodeMisses = Effect.gen(function* () {
152
+ if (hasWorked) yield* yieldToHost;
153
+ hasWorked = true;
154
+ const chunk = yield* encodeChunk(misses);
155
+ chunk.forEach((encoded, index) => {
156
+ const row = { encoded, length: JSON.stringify(encoded).length };
157
+ cache.set(misses[index]!, row);
158
+ length += row.length;
159
+ });
160
+ misses = [];
161
+ });
162
+ for (const row of rows) {
163
+ const cached = cache.get(row);
164
+ if (cached === undefined) misses.push(row);
165
+ else length += cached.length;
166
+ if (misses.length === ROWS_PER_CHUNK) yield* encodeMisses;
167
+ if (length > maxJsonLength) return undefined;
168
+ }
169
+ if (misses.length > 0) yield* encodeMisses;
170
+ if (length > maxJsonLength) return undefined;
171
+ return rows.map((row) => cache.get(row)!.encoded);
172
+ });
173
+ const encodeProjectionRows =
174
+ /* Runs once per thread save inside the traced store call. */
175
+ Effect.fnUntraced(function* (projection: Projection) {
176
+ const turnItems = yield* encodeRows(
177
+ projection.turnItems,
178
+ encodedTurnItems,
179
+ encodeTurnItemChunk,
180
+ );
181
+ if (turnItems === undefined) return undefined;
182
+ const visibleTurnItems = yield* encodeRows(
183
+ projection.visibleTurnItems,
184
+ encodedVisibleRows,
185
+ encodeVisibleRowChunk,
186
+ );
187
+ if (visibleTurnItems === undefined) return undefined;
188
+ if (hasWorked) yield* yieldToHost;
189
+ return { ...projection, turnItems, visibleTurnItems };
190
+ });
191
+
192
+ const { snapshot } = stored;
193
+ let payload: string;
194
+ if (options.format === "full") {
195
+ const projection = yield* encodeProjectionRows(snapshot.projection);
196
+ if (projection === undefined) return Option.none<string>();
197
+ payload = yield* encodeFullEnvelope({
198
+ ...stored,
199
+ schemaVersion: ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
200
+ snapshot: { ...snapshot, projection },
201
+ });
202
+ } else {
203
+ const compact = omitLocalVisibleTurnItems(snapshot.projection);
204
+ const projection = yield* encodeProjectionRows(compact ?? snapshot.projection);
205
+ if (projection === undefined) return Option.none<string>();
206
+ payload = yield* encodeCompactEnvelope({
207
+ ...stored,
208
+ schemaVersion: COMPACT_THREAD_CACHE_SCHEMA_VERSION,
209
+ snapshot: {
210
+ ...snapshot,
211
+ projection,
212
+ turnItemsOmitLocalVisible: compact !== null,
213
+ turnItemCount: snapshot.projection.turnItems.length,
214
+ visibleTurnItemCount: snapshot.projection.visibleTurnItems.length,
215
+ },
216
+ });
217
+ }
218
+ // The rest of the projection is not budgeted row by row; a huge one still stays out.
219
+ return payload.length > maxJsonLength ? Option.none<string>() : Option.some(payload);
220
});
56
-});
221
+}
222
223
export const decodeStoredThreadSnapshot = Effect.fn("ThreadCache.decode")(function* (raw: string) {
224
const stored = yield* decodeCompatible(raw);