fix(runtime-host): page oversized transcript Turns (#4433)

A Turn larger than the Host's own range limits made its Session unopenable. `readRangeEdges` trims a selection back to whole-Turn boundaries, and when the target Turn alone exceeded `SESSION_TRANSCRIPT_RANGE_MAX_MESSAGES` (256) or `SESSION_TRANSCRIPT_RANGE_MAX_BYTES` (16 MiB) it threw `RangeError`. `createSessionTranscriptBootstrap` maps anything that is not a `TranscriptOverlayCapacityError` to `persistence_failed`, so the reader saw "Session transcript is unavailable" and no amount of retrying helped. The limits are the Host's own, so nothing on the client side could avoid them, and a 257-message tool loop is an ordinary size. The throw was added in #4244 as the fallback for "not even one Turn fits".

Degrade instead of refusing: when a single Turn cannot be bracketed, return the selection unchanged with null range and protected-Turn boundaries. Nothing else moves. The page stays bounded because the bound never came from this function — bootstrap reads through `readDurablePage` with the range message limit and continuations through `continuationMessageLimit`, with `requirePageByteLimit` capping page bytes at 512 KB. Continuation still works because `pageFromSelection` signs its cursor from the reader's `selected.next`, and a null boundary is already a value both consumers handle: `session-subscription.ts` reads it as "boundary reached", and `desktop-transcript-replica.ts` was already written with `?? fallback` at all three sites. Ordinary Turns and partial-edge Turns take the same branches as before — the conditions are untouched.

An oversized Turn now pages: 286 messages arrive as 256 + 30, with no repeats and no gap.

One consequence worth recording: with a null protected-Turn boundary, Desktop groups the session under a single resident Turn key and cannot evict it, so its resident set is bounded by that Turn rather than by the Host's 256 / 16 MiB. That is a smaller problem than being unable to open the Session at all, and it belongs to the bounded-transcript work in #2913.

Fixes #4428

Generated-by: OpenAI Codex

Author: Sun-GLiang

packages/runtime-host/src/__tests__/session-transcript-pager.test.ts

@@ -360,32 +360,160 @@ test('opens the complete latest Turn when bootstrap starts inside its assistant'
   assert.equal(decoded.nextCursor, null);
 });
 
-test('rejects a latest Turn that exceeds the Host range message bound', async () => {
-  const durable = Array.from({ length: 257 }, (_, index) => ({
+test('pages through a terminal Turn that exceeds the Host range message bound', async () => {
+  const durable: StoredMessage[] = Array.from({ length: 286 }, (_, index) => ({
     ...assistantMessage(index),
     turnId: 'turn-1',
   }));
-
-  await assert.rejects(
-    createSessionTranscriptBootstrap({
-      reader: transcriptReader(durable),
+  const reader = transcriptReader(durable);
+  const { bootstrap, state } = await createSessionTranscriptBootstrap({
+    reader,
+    sessionId: 'session-1',
+    subscriptionId: 'subscription-1',
+    throughSequence: durable.length - 1,
+    rootTurn: {
       sessionId: 'session-1',
+      turnId: 'turn-1',
+      runId: 'run-1',
+      status: 'completed',
+      terminalEventId: 'terminal-1',
+    },
+    activeAssistantStreams: [],
+    maxBytes: 512 * 1024,
+    projection: 'owner',
+  });
+
+  assert.equal(bootstrap.durable.fragments.length, 256);
+  assert.equal(bootstrap.durable.rangeBoundarySequence, null);
+  assert.equal(bootstrap.durable.protectedTurnSequence, null);
+  assert.ok(bootstrap.durable.nextCursor);
+
+  const subscription = new ClientSessionSubscription(
+    {
+      hostEpoch: 'host-1',
       subscriptionId: 'subscription-1',
-      throughSequence: durable.length - 1,
-      rootTurn: {
-        sessionId: 'session-1',
-        turnId: 'turn-1',
-        runId: 'run-1',
-        status: 'running',
-      },
+      nextSequence: 1,
       activeAssistantStreams: [],
-      maxBytes: 16 * 1024,
-      projection: 'owner',
-    }),
-    /Turn range exceeds its capacity limit/,
+      transcript: bootstrap,
+      snapshot: {
+        schemaVersion: SESSION_CONTINUITY_SCHEMA_VERSION,
+        session: {
+          sessionId: 'session-1',
+          metadataRevision: 1,
+          status: 'active',
+          createdAt: 1,
+          isArchived: false,
+        },
+        projectionRevision: 1,
+        rootTurn: {
+          sessionId: 'session-1',
+          turnId: 'turn-1',
+          runId: 'run-1',
+          status: 'completed',
+          terminalEventId: 'terminal-1',
+        },
+        goal: null,
+        queue: { hostEpoch: 'host-1', queueRevision: 1, steering: [], followup: [] },
+        interactions: { pending: [] },
+      },
+    },
+    async () => undefined,
+    (request) => readSessionTranscriptPage({ reader, state, request }),
+  );
+  const decodeStoredMessage = (value: unknown): StoredMessage =>
+    decodePersistedStoredMessage(markPersisted<StoredMessage>(value));
+  const sequences: number[] = [];
+  let pageCount = 0;
+  let page = bootstrap.durable;
+
+  for (;;) {
+    pageCount += 1;
+    const decoded = await subscription.decodeTranscriptPage(page, decodeStoredMessage);
+    sequences.push(...decoded.messages.map(({ identity }) => identity));
+    if (decoded.nextCursor === null) {
+      assert.equal(page.nextCursor, null);
+      break;
+    }
+    page = await readSessionTranscriptPage({
+      reader,
+      state,
+      request: {
+        subscriptionId: 'subscription-1',
+        source: 'durable',
+        direction: 'older',
+        throughSequence: durable.length - 1,
+        cursor: decoded.nextCursor,
+        anchorSequence: null,
+        maxBytes: 512 * 1024,
+      },
+    });
+  }
+
+  assert.equal(pageCount, 2);
+  assert.equal(new Set(sequences).size, durable.length);
+  assert.deepEqual(
+    [...sequences].sort((left, right) => left - right),
+    Array.from({ length: durable.length }, (_, index) => index),
   );
 });
 
+test('degrades the range boundary for an oversized running Turn', async () => {
+  const durable: StoredMessage[] = Array.from({ length: 286 }, (_, index) => ({
+    ...assistantMessage(index),
+    turnId: 'turn-1',
+  }));
+  const { bootstrap } = await createSessionTranscriptBootstrap({
+    reader: transcriptReader(durable),
+    sessionId: 'session-1',
+    subscriptionId: 'subscription-1',
+    throughSequence: durable.length - 1,
+    rootTurn: {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      runId: 'run-1',
+      status: 'running',
+    },
+    activeAssistantStreams: [],
+    maxBytes: 512 * 1024,
+    projection: 'owner',
+  });
+
+  assert.equal(bootstrap.durable.fragments.length, 256);
+  assert.equal(bootstrap.durable.rangeBoundarySequence, null);
+  assert.equal(bootstrap.durable.protectedTurnSequence, null);
+  assert.ok(bootstrap.durable.nextCursor);
+});
+
+test('degrades the range boundary for a Turn that exceeds the byte bound', async () => {
+  const durable: StoredMessage[] = Array.from({ length: 32 }, (_, index) => ({
+    ...assistantMessage(index),
+    turnId: 'turn-1',
+    text: 'x'.repeat(600 * 1024),
+  }));
+  const { bootstrap } = await createSessionTranscriptBootstrap({
+    reader: transcriptReader(durable),
+    sessionId: 'session-1',
+    subscriptionId: 'subscription-1',
+    throughSequence: durable.length - 1,
+    rootTurn: {
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      runId: 'run-1',
+      status: 'completed',
+      terminalEventId: 'terminal-1',
+    },
+    activeAssistantStreams: [],
+    maxBytes: 512 * 1024,
+    projection: 'owner',
+  });
+
+  assert.ok(bootstrap.durable.fragments.length <= 256);
+  assert.ok(bootstrap.durable.rawBytes <= 512 * 1024);
+  assert.equal(bootstrap.durable.rangeBoundarySequence, null);
+  assert.equal(bootstrap.durable.protectedTurnSequence, null);
+  assert.ok(bootstrap.durable.nextCursor);
+});
+
 test('admits a latest Turn exactly at the Host range message bound', async () => {
   const durable: StoredMessage[] = [
     { ...assistantMessage(0), turnId: 'turn-before' },

packages/runtime-host/src/server/session-transcript-pager.ts

@@ -359,7 +359,11 @@ async function readRangeEdges(input: {
           targetBytes > SESSION_TRANSCRIPT_RANGE_MAX_BYTES
         ) {
           if (targetStart === 0) {
-            throw new RangeError('Session transcript Turn range exceeds its capacity limit');
+            return {
+              selected: input.selected,
+              rangeBoundarySequence: null,
+              protectedTurnSequence: null,
+            };
           }
           reachedFarEdge = true;
           break;
@@ -397,7 +401,11 @@ async function readRangeEdges(input: {
       groupBytes > SESSION_TRANSCRIPT_RANGE_MAX_BYTES
     ) {
       if (groupStart > 0) break;
-      throw new RangeError('Session transcript Turn range exceeds its capacity limit');
+      return {
+        selected: input.selected,
+        rangeBoundarySequence: null,
+        protectedTurnSequence: null,
+      };
     }
     if (
       retainedMessages + group.length > SESSION_TRANSCRIPT_RANGE_MAX_MESSAGES ||