I read DSH's whole persistence layer to support it in my Agent Sessions open source app — looking for someone who runs DSH daily

[jazzyalex]

I maintain an open source (811 GitHub stars) Mac app that reads local session history off disk for 13 coding agents — Codex, Claude Code, OpenCode, Cursor, Copilot CLI, Pi, Kimi, Grok, Qwen and a few more, with Devin CLI and fx landing in the next release. Reading other people's transcript formats is basically the whole job, so I spent some time going through packages/session/session-persistence-jsonl and the architecture notes behind it. DSH would be the next one supported, and I'd like someone here to help me do it.

The ask

The app is Agent Sessions — MIT, macOS, local-only, one indie dev plus a few harness contributors. It browses and searches transcripts across those agents in one window, with resume where the CLI supports it.

I can write the DSH source myself, but it's better done by someone who actually runs DSH daily. Format work is only as good as the sessions you can test against, and I don't have a real corpus of DSH sessions.

Two sizes of help, and the small one is genuinely small:

• Add the source. 5.0 shipped a session-source registry: a new agent is a self-contained folder plus one line in the registry, and the whole obligation list is written down in docs/adding-a-session-source.md. It's a deliberately closed list — if the compiler surprises you with something not in that doc, that's a bug in the doc. Issue template: new agent source.
• Steward it. No code, no commit rights, no Xcode. You run one script against your own sessions two or three times a year and say whether the format moved. Ten minutes. It redacts before anything leaves your machine. Steward signup, details in STEWARDS.md.

Either way you get named credit, and DSH sessions stop being the ones nobody can search after the terminal scrolls away.

What DSH gets right, compared to the field

Worth saying, since I read the whole persistence layer and most harnesses don't come out of that reading well:

• The log is lossless, including assistant/chunk. The note in 2026-06-14-session-persistence.md explicitly turns down Codex's chunk-filtered rollout shape because seq = log.length and events[i].seq === i need a contiguous log. That's the correct call and it's rare. Several agents I read throw away the reasoning or the streaming deltas before they ever hit disk, and once that's gone no reader can bring it back.
• Metadata lives out of the log. The SessionHeader carries version, cwd, createdAt, parentSession, agentPreset. Because it's a dedicated first frame, listing a directory of huge sessions reads one frame per file. Most JSONL agents make you scan into the body — or the whole file — just to learn a session's cwd and title.
• A torn tail keeps the work. Repair truncates from the incomplete frame, keeps every complete decoded record, and appends synthetic tool/step/turn closers. The alternative most formats pick is "the last turn is garbage, drop it," which on a long autonomous run throws away real output.
• Two backends held to one contract. runPersistenceContract running over both the JSONL bytes and the SQLite rows is a nice trick — it means "which backend" never becomes "which semantics."

For context on the bar: I run a small benchmark (Session-Bench, 20 pass/fail gates on how well a harness preserves its own record) across these agents, and losslessness plus cheap listing is where most of them lose points. DSH isn't scored yet — I don't score anything off documentation, only off a real store on disk — but on paper it would be competitive at the top.

One practical note for anyone else writing a reader: compression defaults to 'zstd', so the artifact is session.jsonl.zstd and there's no grepping a session. Standard RFC 8878 frames, so it decodes fine, and packChunks rows unpack from the codec in dsh-session. Just budget for it.

[xiaoshenming]

如果你要在 Agent Sessions 里读 DSH 的 session.jsonl.zstd：格式是 header 单独一帧 + 后续 zstd 帧里的 JSONL（含 packed assistant/chunk 行）。官方 loader 对 committed seq 连续、以及 user/message / assistant/message / tool/result 的 message id / tool source 很严，坏文件会整份拒读。

dsh-session-surgeon 是离线扫描/修复这条格式的实现（decode + pack 往返、默认 dry-run）。可以当对照，不要直接当生产 decoder。真实语料请用户自己机器上跑 scan / inspect，不要收集别人的 ~/.dsh/sessions。

[jazzyalex]

谢谢你花时间写这段——你这份 docs/SESSION-FORMAT.md 比我手里的扎实。我是从 session-persistence-jsonl 和 architecture notes 读出来的，没有真实安装；你是对着官方实现、又在自己机器上验证过的。两边结论一致，这点我就放心了。

有一条是我漏掉的：loader 对 user/message / assistant/message / tool/result 的 message id 和 tool source 有多严，以及一条坏记录会让整份文件拒读。光读代码看不出这个的实际份量。

dsh-session-surgeon 里的合成 fixtures（healthy-packed、lone-surrogate、orphan-tmp，加上 build.mjs）正好解决了我在帖子里说的问题——我没有 DSH 语料可测。它们是合成的、MIT、不碰任何人的真实会话。请问我可以在 Agent Sessions 的解析器测试里用吗？会在 fixture 目录和发布说明里注明出处。

你那句"让用户在自己机器上跑 scan / inspect，不要去收集别人的 ~/.dsh/sessions"——我们的 steward 流程正是这样：脚本在本地跑，先脱敏，附什么由本人决定。

我直说我需要什么： 在动手之前，我需要一个说定了的 DSH steward，不是"有兴趣"。具体只有一件事：等我把 DSH source 写出来，你拿自己的真实会话在 Agent Sessions 里跑一遍，告诉我哪里读错、哪里根本没读出来。这一步我自己做不了——我没有 DSH 的真实会话。

为什么较真：已经有几个 source（Qwen、Devin、fx）是照着 CLI 的 help 和 reader 行为实现的，因为没人能用真实账号跑通，resume 至今没做过端到端验证。我不想 DSH 也落到那个状态。以 DSH 现在的体量，值得一次做对。

最理想的是你直接在我的 repo 提 PR。source 那一份我陪你走 docs/adding-a-session-source.md，review 我来。

• source 指南：https://github.com/jazzyalex/agent-sessions/blob/main/docs/adding-a-session-source.md
• steward 报名：https://github.com/jazzyalex/agent-sessions/issues/new?template=steward-signup.yml

---

Thank you for taking the time to write that. Your docs/SESSION-FORMAT.md is more solid than what I had — I read session-persistence-jsonl and the architecture notes without a real install, while you read the official implementation and checked it against your own machine. We landed in the same place, which is what I needed to know.

One thing I missed: how strict the loader is about message id and tool source on user/message / assistant/message / tool/result, and that one bad record rejects the whole file. Reading the code doesn't tell you how much that bites in practice.

The synthetic fixtures in dsh-session-surgeon — healthy-packed, lone-surrogate, orphan-tmp, plus build.mjs — solve exactly the problem I raised in the post: I have no DSH corpus to test against. They're synthetic, MIT, and touch nobody's real sessions. May I use them in Agent Sessions' parser tests? Attribution in the fixture directory and the release notes.

Your point about running scan / inspect on your own machine rather than collecting other people's ~/.dsh/sessions is how our steward process already works: the script runs locally, redacts first, and you decide what gets attached.

Here is what I actually need: before I start, a confirmed DSH steward — not "interested," settled. One concrete thing: once I write the DSH source, you run Agent Sessions against your own real sessions and tell me what it reads wrong and what it fails to read at all. I can't do that step myself, because I have no real DSH sessions.

Why I'm being firm about it: several sources (Qwen, Devin, fx) were implemented from the CLI's help output and reader behavior because nobody could authenticate a real account, and their resume paths have never been verified end to end. I don't want DSH to land in that state. At the size DSH is now, it's worth getting right the first time.

Best case, you open the PR in my repo directly. I'll walk you through docs/adding-a-session-source.md and do the review.

• Source guide: https://github.com/jazzyalex/agent-sessions/blob/main/docs/adding-a-session-source.md
• Steward signup: https://github.com/jazzyalex/agent-sessions/issues/new?template=steward-signup.yml

[liyangbing]

A useful implementation boundary for the proposed DSH source: treat the on-disk artifact as a storage format, not as one JSONL event per line.

For rc.8, the default path is concatenated checksummed Zstandard frames; the first logical record is a Session header, and streamed assistant deltas may be stored as text-chunks, reasoning-chunks, or tool-call-chunks rows. A reader should decode every frame, expand packed rows through the shipped @deepseek-ai/dsh-session codec, then validate contiguous logical seq values. A parser that only accepts row.seq or only known SessionEvent tags will silently lose output.

The handbook format map turns those boundaries into a read-only local validation checklist (copy/hash first, reject unsupported versions, preserve the only source, and test packed/unpacked/mixed layouts): https://sandbaseai.github.io/deepseek-harness-handbook/deepseek-harness-session-log-format.html

This is documentation-based guidance, not a claim that I have a real DSH corpus or have completed the Agent Sessions steward step. The official rc.8 sources and verification date are linked in the guide; synthetic fixtures and a volunteer own local corpus remain the right way to validate the integration.

[jazzyalex]

补充一条今天验证过的：格式已经动了，而且 version 字段不会告诉你。

版本线：0.1.0-rc.6 → rc.7 → rc.8 → 0.1.1-rc.1/rc.2 → 0.1.2-alpha.1 → 0.1.2-alpha.2（今天 13:52 UTC 发布）。

我 diff 了 rc.8 和 alpha.2 的 packages/session/session-persistence-jsonl/src/format.ts：storage record 多了一个 sourceEventSeqs，在存储边界做 range 编码——≥3 个连续 seq collapse 成 [start, end]，其余原样保留。读的一侧要用 @deepseek-ai/dsh-session 里的 decodeSeqRanges(record.sourceEventSeqs, record.seq) 展开回 number[]。

也就是说，外部 reader 现在需要两个 codec，不是一个：packed chunk rows，加上 seq-range provenance。

最关键的一点：SESSION_FORMAT_VERSION 在 rc.8 和 alpha.2 上都还是 0。record 的磁盘形状变了，header 里的 version 没变——所以 reader 没办法从 header 察觉这次变化，只会安静地读错。

@xiaoshenming 你那份 SESSION-FORMAT.md 是 rc.6，@liyangbing 你引的是 rc.8，现在线上是 alpha.2。三份对不上不是谁写错了，是这东西几天一版。

这恰好说明我要的为什么是 steward，而不是一次性实现：写一次、之后不再复查的 source 会静默腐烂，因为版本号不会提醒任何人。所以还是那两个问题：

• 有谁在日常用 DSH，愿意在我把 source 写完之后，拿自己的真实会话在 Agent Sessions 里跑一遍，告诉我哪里读错、哪里根本没读出来？
• 或者直接来提 PR，指南我陪着走，review 我来。

---

One thing I verified today, worth adding: the format has already moved, and the version field won't tell you.

The line runs 0.1.0-rc.6 → rc.7 → rc.8 → 0.1.1-rc.1/rc.2 → 0.1.2-alpha.1 → 0.1.2-alpha.2, published today at 13:52 UTC.

Diffing packages/session/session-persistence-jsonl/src/format.ts between rc.8 and alpha.2: storage records gained a sourceEventSeqs field, range-encoded at the storage boundary — runs of three or more consecutive seqs collapse to [start, end] pairs, anything else stays verbatim. A reader has to expand it back to number[] via decodeSeqRanges(record.sourceEventSeqs, record.seq) from @deepseek-ai/dsh-session.

So an external reader now needs two codecs rather than one: packed chunk rows, plus seq-range provenance.

The part that matters most: SESSION_FORMAT_VERSION is still 0 at both tags. The on-disk record shape changed while the header's version did not, so a reader cannot detect this from the header. It just quietly reads wrong.

@xiaoshenming your SESSION-FORMAT.md is rc.6, @liyangbing the guidance you linked is rc.8, and the current line is alpha.2. The three disagreeing isn't anyone getting it wrong — it's that this ships every few days.

Which is exactly why I'm asking for a steward rather than a one-off implementation: a source written once and never re-checked will rot silently, because the version number won't warn anybody. So, the same two questions:

• Is anyone here running DSH daily who'd be willing, once I've written the source, to run Agent Sessions against their own real sessions and tell me what it reads wrong and what it misses entirely?
• Or open the PR directly — I'll walk you through the guide and do the review.

Guide: https://github.com/jazzyalex/agent-sessions/blob/main/docs/adding-a-session-source.md
Steward signup: https://github.com/jazzyalex/agent-sessions/issues/new?template=steward-signup.yml

[jazzyalex]

Closing the loop here: Agent Sessions 5.5 shipped local DeepSeek Harness history browsing and search for macOS, alongside 15 other supported coding-agent histories. Thanks to @xiaoshenming and @liyangbing for the format guidance. The current download is 5.5.1.

The integration is read-only and its test evidence is still limited: sanitized fixtures, a pinned event catalog, and a local UI smoke test, without broad real-world corpus coverage. If you run DSH on a Mac, I'd appreciate a report on sessions that are missing or misrendered; no private transcript needs to be shared.

I posted the full announcement and scope here: new bilingual announcement.

This is an independent third-party integration, not endorsed by DeepSeek.

补充一下：Agent Sessions 5.5 已支持在 Mac 本地浏览、搜索 DeepSeek Harness 历史记录，并可与另外 15 种编程 Agent 的会话一起检索。感谢 @xiaoshenming 和 @liyangbing 提供的格式信息。具体功能边界和下载链接见上面的新讨论；请不要公开私人会话内容。

[xiaoshenming]

Congrats on 5.5 — good to see DSH history land in Agent Sessions, and thanks for the citation. If your importer ever runs into a session that refuses to load (seq gap / torn frame / v0-migration refusals), the repair path plus the generation notes (v0 … v4, session.vN.jsonl.zstd) are in the repo — dry-run first, .bak.<utc> before any write. Happy to compare notes on the v3→v4 generation split if that helps your reader.

[jazzyalex]

Thanks for the repair path and generation notes — very helpful. I’d love to compare notes on the v3→v4 generation split. What are the key changes an importer should account for?

[xiaoshenming]

Happy to compare notes. Everything below is measured on @deepseek-ai/dsh@0.1.7-rc.1 and 0.1.7-rc.2 (identical on both).

Generations on disk. session.jsonl.zstd is v0; from 0.1.3 the file name carries the generation (session.vN.jsonl.zstd), and v4 is current. The first frame is header-only, later frames are event batches, and the logical sequence is contiguous across frames — seq is an address, not a counter, so a frame walker never has to trust a numbering.

The v3→v4 edge changes message sources, not the envelope. A v3 message could carry { "kind": "plugin", "plugin": "<pkg>" }. The stage lifts that to a producer-owned kind and drops plugin:

• "system-prompt" for @deepseek-ai/dsh-system-prompt in a system role;
• a renamed kind, for the packages in its rename table;
• the same string, for a fixed released set (user-approval, repeat-tool-reminder, tool-cordis, cordis-host-runner, tool-goal, tool-jobs, hooks-codex, hooks-claude-code, schedule, dsh-session-title-llm);
• plugin:<pkg> otherwise.

Native v4 admission then refuses any source whose kind is missing, empty, or the literal "plugin" (format v4 message requires a producer-owned source kind), while unknown non-plugin kinds pass through untouched. So an importer that renders the raw source member shows plugin for pre-v4 rows and producer kinds for v4 rows unless it applies the same mapping. Developer messages follow the same rule and additionally need id, role, content.

A v4 tool/result row carries toolCallId matching the tool source. We found that while synthesizing a fixture: a v4 row written with the older callId-style member is refused with format v4 tool/result at seq N requires toolCallId matching its tool source.

The current generation validates relationships while it is read, and the refusal is whole-file. SessionLogScanner.finish() calls assertReleasedV4Relationships, so a tool/call inside a closed step with no tool/result makes the log unreadable on the ordinary read path — not only at publish: stored log is corrupt: … step/end leaves unresolved tool call <id>. If Agent Sessions wants to show such a session anyway, it has to be deliberately more lenient than the official loader — worth saying out loud, because for a v4 file "it opens in your app" no longer implies "the harness can open it".

What we would test an importer against. Five entry points, one fixture: fixtures/probes/run.mjs (two migration stages accept, two restores refuse, a stored current-generation read refuses; it exits non-zero if any row drifts). It is the smallest thing we have that pins "acceptance" to a specific path instead of to a version number.

One caveat if you build before/after checks in your importer: the official restore.decodeRow() rewrites the row objects you hand it, in place — re-parse between passes, or the second verdict can come out silently wrong.