dsh-replay-theater — replay a session at its original token cadence (the dt[] array finally has a reader)

[ItBayMax]

Repo: https://github.com/ItBayMax/dsh-replay-theater · MIT · dsh plugin --profile web add dsh-replay-theater

The observation that started it

Packed chunk rows keep every token's real inter-arrival gap, and the source says why:

// packages/core/session/src/chunk-rows.ts:44
/** Epoch-ms gaps between consecutive members; length is one less than the member count. */
dt: number[]

"one entry per member, never joined — token boundaries are data" — chunk-rows.ts:48

Packed storage deliberately does not join a run's members into one string, so the original
cadence survives on disk. As far as I could tell, nothing in the harness read dt back.
This plugin is that reader: it turns the session log into a playable timeline.

What it does

A Theater tab appears beside Chat and Trajectory. The assistant's answer grows token by
token, spaced by the real millisecond gaps recorded when it was generated — play, pause,
single-step, scrub, 0.5×–8× speed.

Transport bar, plus scalar events (step/start, tool/result, …) on their own marker rail:

It also compares two runs side by side and reports where they stop matching — useful for
"why did the same prompt behave differently this time":

The replay core is framework-free and harness-free, so the same functions also work offline:

node scripts/replay-cli.mjs path/to/session.jsonl --frames 20
node scripts/replay-cli.mjs run-a.jsonl run-b.jsonl        # compare two runs

Two design notes that might interest others

Real cadence is unwatchable verbatim. On a real 5,776-event session (54,626 recorded gaps)
the median gap is 0 ms — provider chunks routinely land in the same millisecond, and the
log clock is millisecond-resolution. Replaying that literally makes whole paragraphs appear
instantly. So gaps are clamped on both ends: a minGapMs floor restores visible typing, a
maxGapMs ceiling keeps a 30-second think from stalling playback. Whenever silence is
compressed, the transport bar says by how much — playback alters the data's timing, so it
should admit it.

The two shapes of a chunk row are not the same. A JSONL storage line carries seq0/time0;
the client wire record carries seq/time. I read the wrong pair first, and only production
data exposed it — totals were roughly 2× too large and sequences collided. Worth a heads-up for
anyone else parsing session.jsonl directly. (decodeStorageRecord, chunk-rows.ts:363, is
the upstream decoder for the storage form.)

Compatibility

Developed and validated against 0.1.2-alpha.2. It reads only the public client surface —
session.eventSource and session.loadOlder() — deliberately, since 0.1.2 removed the whole
client/runtime package; depending on internals is not survivable.

@deepseek-ai/dsh-api-session-controller isn't on npm, so src/core/wire.ts carries structural
mirrors of the upstream shapes, each annotated with the file:line it was read from. They're
structurally compatible, so swapping them for real imports later needs no call-site changes.
If those types ever get published, I'd happily drop the mirrors.

148 tests; the replay core runs without a browser or a harness checkout.

---

中文

仓库：https://github.com/ItBayMax/dsh-replay-theater · MIT

打包存储刻意不合并 run 的成员，把每个 token 的真实到达间隔完整留在了 dt 数组里
（chunk-rows.ts:48：token 边界就是数据），但 harness 里似乎没有任何东西读回它。
这个插件就是那个使用者：在 Chat / Trajectory 旁边加一个剧场标签页，
按原始节奏逐 token 重演一次会话，支持播放/暂停/单步/拖拽/0.5×–8× 倍速，
还能把两次运行并排对比、报出首个分歧点。

两个可能对他人有用的发现：

1. 真实节奏直接回放是看不了的。一次真实会话（5,776 事件 / 54,626 个间隔）的间隔中位数是 0ms
   ——同一毫秒内到达的 chunk 很常见。所以两端都做了钳制，并且只要压缩了静默就在播放条上明示。
2. 存储形态与客户端线上形态不是一回事：JSONL 存储行是 seq0/time0，客户端记录是 seq/time。
   我一开始读错了，只有真实生产数据才暴露出来（总时长约 2 倍偏大、序号冲突）。
   直接解析 session.jsonl 的同学可以留意。

针对 0.1.2-alpha.2 开发并验证，只依赖公开客户端面（session.eventSource / session.loadOlder()）。

[ItBayMax]

Compatibility notice: this plugin does not work on 0.2.0 yet

Re-synced against 0.2.0-rc.2 (639ed015). Flagging this before anyone installs it and wonders why the tab is empty.

The premise still holds. The implementation is reading a shape that no longer exists.

What broke

The plugin consumes chunkrow/text-chunks, chunkrow/reasoning-chunks and chunkrow/tool-call-chunks. Those event types are gone — chunkrow has zero hits anywhere under packages/ on 0.2.0. packages/core/session/src/chunk-rows.ts, the file my type mirrors were annotated against, no longer exists either.

Two upstream changes did it, both deliberate:

1. The v1→v2 session-format edge folds the stream into the assistant event. Top-level assistant/chunk events were removed; an attempt now settles as one assistant/message (or assistant/attempt when it committed no surface message), with the timed stream embedded.
2. From format v2 on, each physical row holds exactly one event. The packed multi-member run is a v0/v1-era storage shape; seq0 now survives only inside the frozen v0 decoder.

So the offline session.jsonl path in this plugin only reads generation-0 logs, and the live path subscribes to events that are never emitted.

The good news: the cadence data was relocated, not removed

// packages/llm/llm/src/assistant-stream.ts:20-47
export type AssistantStreamRecord =
  | { readonly type: 'text-chunks'; readonly time0: number; readonly index: number
      readonly dt: readonly number[]; readonly texts: readonly string[] }
  | { readonly type: 'reasoning-chunks'; /* … */ }
  | { readonly type: 'tool-call-chunks'; /* … */ readonly id: ToolCallId; readonly args: readonly string[] }
  | { readonly type: 'chunk'; readonly time: number; readonly chunk: StreamChunk }

time0 / index / dt / texts / args kept their names. They moved from "top-level physical row plus a data sub-object" into assistant/message.data.stream[], described upstream as "Exact timed model stream, compacted without joining delta boundaries" (packages/core/session/src/types.ts:341-348). There is now also a fourth variant, a raw chunk carrying what the accumulator never packs.

So the observation this plugin was built on — that the per-token inter-arrival gaps are deliberately preserved rather than joined away — is still true on 0.2.0. What changed is where you read it.

What still works

conversation.view is unchanged (19 files reference it), and session.eventSource / loadOlder() are still the public client surface. The registration side needs no changes; only the wire reader does.

One behavior note for anyone screenshotting: the Trajectory tab is now hidden behind the Developer Tools toggle (packages/client/ui-conversation/src/client/apply.ts:185), so a session view shows fewer tabs by default than the screenshots in this post.

Fix shape, for anyone who wants to fork before I get to it

• Subscribe to assistant/message and assistant/attempt instead of chunkrow/*, and read data.stream[].
• Stop deriving per-frame sequence from seq0 + i. After the fold, a whole attempt occupies one seq; ordering within an attempt comes from the stream array plus time0 and dt.
• Handle the fourth { type: 'chunk', time, chunk } variant — it carries a single timestamp rather than a gap array.
• Offline files: expect session.vN.jsonl[.zstd]. A bare session.jsonl now specifically means generation 0.
• Also worth knowing if you parse logs directly: tool/code-dispatch* became tool/ptc-dispatch* in the v2→v3 edge, and v4 rejects the retired names.

I'd rather leave this notice up than let the README's install line mislead someone. Will update the repo and follow up here when the reader is ported.

---

Incidentally, this is a good advertisement for the structural-mirror approach the post describes: because the mirrored types carried file:line annotations pinned to a specific commit, finding out exactly what had moved took one pass over the diff rather than a debugging session.

[ItBayMax]

Ported. The reader now reads 0.2.0.

Following up on the compatibility notice above: the repo is updated and the install line is safe again.

First, a correction to my own notice. I wrote that chunkrow has "zero hits anywhere under packages/". That is wrong. It is zero hits in any .ts/.tsx — but there is one surviving mention, and it is in a file that matters more than source would: packages/client/AGENTS.md:104 still instructs implementers to handle chunkrow/* branches. That file is injected into agent context, so an agent following it today writes against a type the compiler no longer has. I have opened a separate report for it rather than bury it here: #8540.

What the port actually took

Three files, and the shape of the work was not "rename the event types":

• HistoryRecord became a two-variant union, {type:'event'} | {type:'transient'}. The transient entries are client-only provisional frames that upstream replaces atomically with the settled event. Rendering both plays every token twice. This one is easy to miss because the naive port — treat anything with an event field as durable — type-checks fine and looks right until you watch the output.
• recordLastSeq() collapsed to return record.event.seq. I kept the function anyway. The name carries the version-sensitive fact that a settled attempt is one sequence however many tokens it holds; a bare .event.seq at a call site carries nothing.
• The fourth stream variant is not an edge case. {type:'chunk', time, chunk} has no dt and no member sequence, so it cannot be expanded into frames — it has to land as a marker. In the snapshot I derived my fixture from, chunk is 12 of 16 stream members. Drop it and a large part of the timeline silently disappears.

A bug the port introduced, in case you hit the same one

My stage accumulator grouped blocks by (kind, block, turn, step, callId). On 0.2.0 a retried step settles as assistant/attempt (the abandoned one) and then assistant/message (the final one), and these frequently share the same turn/step/block. Result: the abandoned attempt's text and the final text concatenate into one visual block.

This cannot happen on 0.1.x — the old shape never put those two on comparable coordinates. It is specifically a hazard the fold introduces. Block identity now includes seq.

The snapshot corpus is far richer than I thought, and that matters for plugin authors

I had been asserting — in my README and in a fixture header — that the corpus cannot support stream tests, on the grounds that the longest same-block delta run in it is 2 members. I rescanned all of it on 639ed015:

	what I had been claiming	measured on 639ed015
session.v3.jsonl snapshots	118	173 (168 carry a stream)
packed runs	—	526
longest single run	2 members	2047 members (a tool-call run in web/present-svg)
time0 / dt inside runs	normalized away	present in all 526 (400 distinct time0 epoch-ms values)
row-level seq / time	normalized away	still normalized away (0 of 4343 rows)

So if you are writing anything that consumes AssistantStreamRecord, the snapshot corpus is a usable shape fixture — I was wrong to tell myself otherwise, and that wrong belief was doing real work: it was the reason I had never tested member accumulation above a handful of members. Added a 2047-member test; it passed, but it had never been exercised.

What the corpus still cannot give you is cadence: 373 of the 526 runs have an all-zero dt, and the largest gap anywhere in it is 156 ms. These were recorded against fast or stubbed models, so there is no "model pauses to think" silence to assert on. Timing tests still need hand-built fixtures.

Scope of verification, stated plainly

165 tests, clean typecheck, clean build. I have not run this against a live 0.2.0 instance. The porting evidence is upstream source plus the test suite, nothing more. If you install it on a real 0.2.0 and something is off, that is genuinely new information to me — please say so here.

Repo: https://github.com/ItBayMax/dsh-replay-theater (MIT)