Provide official session export/inspect tooling for zstd-framed session logs

[ybkin1]

Summary

Session logs (<workspace>/<session-id>/session.jsonl.zstd) are a concatenation of zstd frames, so standard text tooling cannot read them: grep, tail, jq and friends all fail on the binary container. Any audit, debugging, or forensic pass over session history currently requires hand-rolling a frame-by-frame decompressor against a fast-moving rc-version internal package. We would love official CLI subcommands to list, inspect, and export sessions as plain JSONL. This would also make incident triage (for example, sessions damaged by a torn tail after a crash) dramatically easier.

Background & Evidence

• During a recent audit of session histories on our deployment (usage accounting and content review across multiple sessions), every single inspection required a custom script that walked the zstd frames (magic 28 b5 2f fd), decompressed each frame, and re-assembled the JSONL records. There is no supported way to do this today.
• The same friction shows up in incident triage: when a session fails to load due to tail damage, the only way to see which records survived is to decode the frames manually.
• Standard expectations for a local-first CLI tool include being able to answer "what is in this session file" without writing code; today that is not possible.

Failure Mode or Reproduction

• grep <needle> <workspace>/<session-id>/session.jsonl.zstd produces binary-match noise or nothing useful; the compressed container cannot be searched or diffed.
• Building tooling on the internal persistence package means chasing an rc-series API that changes between releases.

Proposed Fix

Add CLI subcommands, suggested shape:

• dsh session list — id, workspace, size, record count, mtime, health flag.
• dsh session inspect <session-id> — header/meta summary, frame count, integrity check (reports a torn tail if present), optionally per-frame offsets/sizes via --frames for forensics.
• dsh session export <session-id> --format jsonl [--out <file>] — streaming decompression to plain JSONL, pipe-friendly; optional --redact to strip message bodies and keep metadata only, for sharing sanitized samples in bug reports.

Implementation can live in the CLI layer over the existing persistence reader, so the on-disk format stays an internal detail while the export contract remains stable.

Additional Context

• dsh: @deepseek-ai/dsh 0.1.1-rc.2 (developer preview)
• OS: Windows 10 x64 (build 10.0.18363)
• Node.js: v22.23.2

[liyangbing]

这个需求和 SandBase Harness 的“可审计会话”边界比较接近，但实现层次不同：SandBase 不声称读取 DSH 的 zstd session 文件，也没有把它包装成 dsh session export；它提供稳定的 HTTP 资源接口，让客户端不必依赖内部压缩格式。

当前可用的路径是：

• GET /v1/sessions/:id：会话元数据、状态、Agent 版本、资源和 usage；
• GET /v1/sessions/:id/events：分页读取规范化事件；
• GET /v1/sessions/:id/events/stream：支持事件回放/断点续传；
• GET /v1/sessions/:id/artifacts 与 .../content：列出和下载会话产物。

参考：

• https://github.com/sandbaseai/sandbase-harness/blob/main/src/api/routes/sessions.ts
• https://github.com/sandbaseai/sandbase-harness/blob/main/src/api/routes/stream.ts
• https://github.com/sandbaseai/sandbase-harness/blob/main/README.md#L440-L470

如果 DSH 最终提供 CLI，我会建议把“文件格式解析”和“稳定导出契约”分开：先做完整 frame/尾部完整性检查，再输出版本化 JSONL；损坏尾部时保留可解码前缀并明确报告，而不是让整条 session 不可读。