dsh

Overview ¶

Package dsh implements an event-level adapter for DSH, the DeepSeek Harness.

SURFACE. DSH keeps one append-only session log per session at ${DSH_HOME:-~/.dsh}/sessions/<project-dir>/<session-dir>/session.jsonl.zstd. The default physical encoding is a concatenation of independent Zstandard frames — one checksummed frame for the header line, then one per durable append batch — so the file is JSONL only after decompression. A backend configured `compression: none` writes the same logical lines as plain session.jsonl instead, and discovery accepts both spellings. This is the second zstd surface in the harness matrix (codex is the other) and, unlike codex's, it is compressed BY DEFAULT: a reader without a zstd decoder sees nothing at all here rather than losing only cold sessions.

WHAT IS READ. Accounting and identity records, by name:

• `session` — the immutable header line: session id, cwd, agent preset.
• `assistant/message` — one completed model call: `data.usage` plus the provider/model that served it. This is the ONLY usage record.
• `tool/call` — one tool invocation the model requested, named and correlated to its step.
• `request/context` — provider/model fallback for a later completed call.
• `assistant/chunk` — usage-chunk sequence numbers only, to detect a completed message that lost its reported accounting.

Everything else — user prompts, tool results, packed chunk rows, request headers with their system prompt and tool schemas — is ignored by TYPE, so content never enters a decode in the first place.

SPLIT-IDENTITY TRAP (confirmed live). The same model call reports its usage TWICE: once as an `assistant/chunk` whose `chunk.type` is "usage", and once as the step's `assistant/message` `data.usage`. The numbers are identical — DSH's own token meter says so ("a final assistant-message usage for the same (turn, step) replaces that sample instead of double-counting it"). This adapter counts ONLY `assistant/message`. The message's `sourceEventSeqs` names every chunk seq it collapses, including that usage chunk, and is kept in the audit payload as the evidence that the collapse happened.

TOKEN ACCOUNTING. DSH's TokenUsage counts are DISJOINT: `inputTokens` is UNCACHED input, with cached input reported separately as `cacheReadTokens` and `cacheWriteTokens` (billed input is the sum of the three), and `reasoningTokens` is a subdivision of `outputTokens` that is never added again. So the components map straight onto the Anthropic-style ledger columns and the total is their sum; the source reports no total of its own.

FORK SEEDS. A forked session's log opens with its parent's leading events copied VERBATIM under a new session id, and `seedLength` counts them. Usage and activity keys are minted from the message identity, so those copies COLLAPSE onto the originals. Turn context cannot ride that: its value comes from the session HEADER, and the two headers can disagree about the very records they share, so the seeded prefix records no context here and leaves those turns to the log that owns them. See header.seeded.

COST ATTRIBUTION. A DSH step is, by the harness's own definition, "one model call plus the tool executions it requested", and every `tool/call` carries the (turn, step) it belongs to. So a call joins its usage row EXACTLY, with no timestamp guessing: the usage row is the `assistant/message` of the same (turn, step). When a step somehow carries no assistant message, or more than one, the calls are emitted UNATTRIBUTED rather than attached to a guess.

CRITICAL: strictly read-only. Files are opened O_RDONLY, never written, locked, rotated or repaired — DSH's own loader repairs a torn tail, and this adapter must never be the thing that does it.