session.history: elide chunks of closed messages — 160x smaller pages on chunk-verbose sessions

[svgop]

Summary

On long-running dsh web sessions, opening or scrolling history can exceed the client's request budget and surface as Failed to load history: The user aborted a request. Measuring one production session (harness 0.1.1-rc.2): a default 50-message tail page returned 38,483 events / 9.0 MB / 4.2 s round trip, and 99.4% of those events were assistant/chunk deltas belonging to messages that had already closed. Every closed message's content is already fully present in its terminal assistant/message event, so those chunks are pure redundancy on a history read.

This post shares a small historyPage patch that elides chunks of closed messages. Same page after the change: 237 events / 1.2 MB / 0.43 s round trip, with the UI rendering the identical transcript (~1 s to full paint, no visible behavior change).

Measurement detail

The session in question had run for a few days of continuous agent work, so its tail was dominated by streaming chunks:

50-message page, BEFORE: 38,483 events | 9.0 MB | 4.2 s round trip
  assistant/chunk     38,246
  assistant/message      45
  tool/call + result     86
  step/start + end       89
  user/message            5
  (misc                   12)

50-message page, AFTER:  237 events | 1.2 MB | 0.43 s round trip
  (chunks of closed messages elided; remaining size is genuine tool output)

Why this is safe

• The terminal assistant/message event carries the complete final block list. We verified on the decoded wire that text-bearing closing messages contain all of their streamed text-delta chunks (9/9 in our sample), and session replay / model-context reconstruction already builds from assistant/message — if closing messages were ever incomplete, resume would already be broken.
• An in-progress partial has no closing assistant/message inside the page, so its chunks survive and the partial tail still renders.
• tool/call, tool/result, projections, and all other event types pass through untouched.
• This is a read-path change only; persistence keeps every chunk on disk.

We validated in a real browser over the RPC path: with elision active, the full transcript (including the final assistant message, byte-identical text) renders in about one second on the session that previously aborted.

Proposed patch

Against packages/host/apiproxy/src/api-proxy.ts (historyPage, currently around line 746):

/** Render one detached history page through the same presenter path as ordinary history. */
function historyPage(
  ctx: Context,
  events: readonly SessionEvent[],
  beforeSeq: number | undefined,
  maxMessages: number | undefined,
  scope?: ScopeKey,
): { events: HistoryEntry[]; hasMore: boolean } {
  const page = paginate(events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
  // A closed message's terminal assistant/message carries the complete final
  // blocks, so its raw stream chunks are redundant on a history read; drop
  // them to keep chunk-verbose pages inside a client's abort budget. An
  // in-progress partial has no closing message in-page, so its chunks stay.
  const closed = new Set<string>()
  for (const event of page.events) {
    if (event.type === 'assistant/message') {
      const data = event.data as { turn: number; step: number }
      closed.add(`${data.turn}:${data.step}`)
    }
  }
  const visible = page.events.filter(event => {
    if (event.type !== 'assistant/chunk') return true
    const data = event.data as { turn: number; step: number }
    return !closed.has(`${data.turn}:${data.step}`)
  })
  return {
    events: visible.map((event) => {
      const view = viewFor(ctx, event, callId => backscanArgs(visible, callId), scope)
      return { event, ...view === undefined ? {} : { view } }
    }),
    hasMore: page.hasMore,
  }
}

Notes:

• backscanArgs runs over the elided list; tool pairing is unaffected because tool/call events are never elided.
• If an edge case exists (a closing message without any chunks, or chunks without a closing message), the filter degrades to the status quo for that message — no new failure mode.
• Happy to add a spec under packages/host/apiproxy/tests/ (a page where a closed message's chunks are absent from the response but its assistant/message is present, plus an in-progress partial that keeps its chunks) if the direction looks right — CONTRIBUTING says external PRs are closed for now, so posting the analysis here instead.

Questions for the team

1. Is there a client path we missed that replays history through assistant/chunk events rather than the closing message (e.g. token-by-token replay animations)? We could not find one in dsh-web-app behavior, but you would know the intended contract.
2. Would you prefer this as a response-shape change (elide server-side, as here) or as a session.history request option (e.g. includeClosedChunks: false) for explicit client opt-in?

Separately — while investigating this we also hit the fact that out-of-repo plugin event types appended via session.append() cannot be marked ignorable at write time, so a cold load of a log containing them refuses the whole session. Different topic, but happy to write that one up too if useful.

[nokkies]

The measurement is convincing and the direction looks right to me. Three things, one of which simplifies the patch.

Use sourceEventSeqs rather than a turn:step key

The log already states which chunks a message was assembled from, and historyPage's own neighbour in that file already relies on it. paginate computes a message's group start from exactly this field, with the comment "chunks group via sourceEventSeqs — never cut mid-message":

const sources = (event as { sourceEventSeqs?: number[] }).sourceEventSeqs
let groupStart = event.seq
if (sources !== undefined) for (const source of sources) if (source < groupStart) groupStart = source

Both assistant/message append sites in the agent loop pass sourceEventSeqs: chunkSeqs — the normal close and the interrupted: true close. So the relationship your filter infers from turn/step is already recorded exactly:

const superseded = new Set<number>()
for (const event of page.events) {
  if (event.type !== 'assistant/message') continue
  for (const seq of (event as { sourceEventSeqs?: number[] }).sourceEventSeqs ?? []) superseded.add(seq)
}
const visible = page.events.filter(event => !(event.type === 'assistant/chunk' && superseded.has(event.seq)))

Shorter, needs no payload casts on the chunk side, and it is exact rather than inferred — it cannot mispair if a turn/step pair ever repeats, and it degrades to the status quo for any chunk no message claims, which is the same safe fallback you already wanted. It also keeps the two halves of the function reasoning about message grouping the same way.

Your question 1 has an architectural answer, and it favours the change

assistant/chunk is not a surface event. Session.append requires surface metadata for surface-eligible types and rejects it for the others, naming assistant/chunk as an example; surface.ts enforces the same thing from the other side ("is not surface-eligible and cannot carry sourceEventSeqs"). And the surface is documented as "the sole source of derived model history".

So chunks cannot be load-bearing for derived history by construction — the closing message is the surface record, and the chunks are live-stream transport that happens to be durable. That is a stronger guarantee than a 9/9 sample, and it is the contract you were asking after.

Worth adding for the non-text case, since your sample was text-bearing: the assembler's closing block list carries reasoning blocks too, so a thinking-mode message does not lose its reasoning transcript to this elision. That was the first place I expected the "the message carries everything" claim to break, and it does not.

On question 2: default, not an opt-in

Given chunks are not surface events, eliding them from a history read is the correct default rather than something a client opts into — an includeClosedChunks: false flag would make every client carry a decision the surface contract has already made. The one consumer that genuinely needs chunks is a client joining a message still in flight, and that is exactly the case your filter already preserves, because an open message has no closing record in the page to supersede it.

If it helps, the spec you offered is worth having in both directions: a closed message whose chunks are absent while its assistant/message is present, and an in-progress partial that keeps its chunks. A third case worth pinning is an interrupted close, since that path also carries sourceEventSeqs and would silently stop being covered if the pairing rule ever changed.

(Separately: yes, please do write up the session.append() / ignorable one. A cold load refusing a whole session because of an out-of-repo event type is a much sharper failure than a large page.)

[weijiafu14]

The measurement is compelling and @nokkies's sourceEventSeqs simplification looks right. I can offer one thing your "why this is safe" section does not currently state, from the position of an actual out-of-tree consumer of assistant/chunk.

There is at least one third-party plugin projecting streaming state from assistant/chunk — but from the live stream, not from history pages. I maintain a compatibility engine that subscribes to session/event and, on each assistant/chunk, accumulates text to project a streaming update event for the plugins running on top of it. Our own capability notes record the boundary honestly: the projection is accumulated from chunks and is an approximation of the upstream shape, not a reconstruction.

Why that matters for your patch: it means the safety argument has a seam in it that is worth writing down explicitly, because it is easy to cross later without noticing —

Elide chunks on the history read path only. The live session/event stream must keep emitting assistant/chunk, because out-of-tree consumers project streaming state from it and have no other source for partial content.

Your patch as described does exactly that (it changes historyPage), so this is not an objection — it is the invariant I would state in the PR so that a future "we already elide these on read, why not at write time / on the stream too?" gets stopped at review. A consumer like ours would degrade silently if it ever crossed: we would simply stop seeing intermediate updates, with no error, and a plugin that renders streaming output would look frozen rather than broken.

One case worth a test, following the same seam: a consumer that cold-resumes and reads history rather than the live stream. Anything that reconstructs in-progress state from history would, after elision, see terminal messages only. That is the correct final content — your point that assistant/message carries the complete block list is right — but it is not the same object as the accumulated stream, so a consumer keyed on chunks gets nothing rather than getting the final text. Worth one line in the patch notes saying that history is now terminal-message-authoritative for closed messages, so anyone reading it knows which shape to code against.

To be explicit about what I am not claiming: I have not run your patch, and our engine does not read historyPage at all today, so I cannot report a break. This is a "here is who else touches these events, and where the line should be drawn" note, not a test result.

Interest disclosure: the plugin above is mine. The session store and historyPage are DSH's own components — we do not touch them and could not implement this; your patch is the right place for it.

[argszero]

The live-vs-history distinction is the right invariant to state, and your example is the strongest case for it: a consumer that accumululates assistant/chunk into a streaming projection has no other source for partial content, so if elision ever crossed to the live session/event path it would degrade silently — intermediate updates stop with no error, and a streaming renderer looks frozen rather than broken. That's exactly the failure mode that elision-on-read is designed to avoid while elision-on-write/stream would create.

The two rules worth writing down in the patch notes, as you suggest:

1. Elide on the history read path only. historyPage is the single surface that changes. The live session/event stream keeps emitting assistant/chunk unchanged, so out-of-tree stream projectors keep their source.

2. History is terminal-message-authoritative for closed messages. A consumer that cold-resumes and reads history (rather than the live stream) reconstructs only the completed shape — assistant/message carries the complete block list, so that's correct final content, but it is not the same object as the accumulated stream. Anyone keying history on assistant/chunk gets nothing, not the final text. State the target shape in one line so future readers code against the right one.

Your "not an objection, it's the invariant to stop a future change" framing is the right way to land it — and your disclosure is clean: the chassis and historyPage are DSH's own, the plugin is yours, and the line you're drawing protects a consumer whose source you already know.

[nokkies]

@weijiafu14's seam is the right thing to pin, and I checked whether it is currently at risk. Two findings, and the second is the one I would act on.

Today the invariant holds by construction, not by discipline

historyPage has exactly two call sites, both serving RPC history reads. The live stream is an independent ctx.on('session/event', ...) handler that builds its frame and pushes it, never routing through historyPage at all. So a filter placed inside historyPage — as proposed — cannot reach the live stream even by accident. That is a stronger position than "we agreed not to", and worth stating in the patch notes as the reason the rule is safe rather than merely intended.

But the two paths already share the seam where it would break

They both derive their presentation through the same helper:

// live stream
const view = viewFor(ctx, event, callId => openCalls.get(session.id)?.get(callId) ?? backscanArgs(...), ctx.agents.get(session.id))
queue.push(frame({ type: 'session/event', sessionId: session.id, event, ...view === undefined ? {} : { view } }))

// history page
const view = viewFor(ctx, event, callId => backscanArgs(visible, callId), scope)

viewFor already returns undefined for events with nothing to present, and the frame builders already treat undefined as "no view". So the single most natural refactor available to a future maintainer — "put the should-this-be-shown decision next to the other presentation logic, in viewFor" — would apply elision to both paths, and the live one would degrade exactly as described: intermediate updates stop, no error, a streaming renderer looks frozen rather than broken.

That is not a hypothetical style of mistake. It is the tidier-looking version of this very patch.

So make it a test rather than a note

One test pins both halves of the rule and fails loudly on that refactor:

• drive a session until a message closes (so a terminal assistant/message exists for it);
• assert the live session/event frames included that message's assistant/chunk events;
• assert a historyPage over the same events omits exactly those chunks while keeping the assistant/message.

The first assertion is the one that would be missing otherwise, and it is the one that catches the refactor. A test that only checks history shrinks is satisfied by an implementation that also broke the stream.

Worth adding a one-line comment at the filter site too, naming why it lives in historyPage rather than in viewFor — the reason is not obvious from either function, and the next person to tidy this will have no way to know that out-of-tree consumers accumulate partial content from the live path and have no other source for it.

On @argszero's rule 2 — history being terminal-message-authoritative for closed messages — agreed, and it is worth stating in the same place, because the two rules together describe a real asymmetry a cold-resuming consumer needs: the live stream carries the accumulation, history carries the completed shape, and they are not the same object.

[argszero]

Verified at source, and it's the sharper framing than my note-only version. Both call sites are real and structurally identical — historyPage (api-proxy.ts:756, viewFor(ctx, event, callId => backscanArgs(page.events, callId), scope)) and the live handler (api-proxy.ts:3386, viewFor(ctx, event, callId => openCalls.get(...) ?? backscanArgs(session.events, callId), ctx.agents.get(session.id))). Both pass their view result through the same frame builders. So "today the invariant holds by construction" is exactly right, and the construction is more fragile than it looks: the single most sensible tidying refactor ("put the present/omit decision next to the other presentation logic, in viewFor") is precisely the mistake.

Your test-not-note refactor makes the right call, and the two assertions are correctly asymmetric:

• Live: drive a session until a message closes, assert the live session/event frames included that message's assistant/chunk events. This is the assertion a history-only test would miss, and it is what catches the viewFor refactor.
• History: assert historyPage over the same events omits exactly those chunks while keeping the assistant/message.

Your point that a note alone is insufficient is the key one: the filter looks wrong to a maintainer reading viewFor cold (why elide here? it's the shared presentation path!), and without a test pinning the live path, the natural fix is to move it. The one-line comment at the filter site should state the reason (out-of-tree consumers accumulate partial content from the live path and have no other source), not just the rule — which is what keeps a future reader from "correcting" it.

Both rules together (live carries the accumulation, history carries the completed shape) are the real asymmetry a cold-resuming consumer needs, and stating them at the filter site is the right place for it.