Blog · Analysis

The hidden developer win: append-only session logs

August 14, 2026 · dshbase

One of the most developer-friendly — and most overlooked — features of DeepSeek Harness is how it stores sessions: as an append-only event log. Most agents give you a final answer or, on failure, a vague error. DSH gives you the whole trail — and after a week of debugging plugins against it, we can tell you exactly what that's worth.

What's in the log

Everything the model sees and does becomes an event:

System prompts and user messages
Reasoning content
Tool calls and their results
Permission changes
Context injections and compression
Sub-agent scheduling

Next turn history is re-derived

The model's history for the next turn is re-derived from this log — not from a black-box state. That design choice is what makes the whole thing inspectable: there's no hidden state the log can drift out of sync with, because the log is the source of truth. Every turn is a pure function of the events before it.

Why it matters: observability, auditing, reproducibility

When most agents fail, you only see "task failed" or an infinite loop — you can't tell where it went off the rails. DeepSeek Harness's trajectory view lets you inspect each run by source. For developers, that means:

Observable — see exactly which step derailed a task.
Auditable — trace every tool call and permission decision.
Reproducible — replay a run from its event log.

That's genuinely valuable for research and for debugging production agents. But the theory only matters if it pays off on real failures — and for us, it did.

What we actually debugged with it

While testing 101 community plugins on dsh 0.1.0-rc.6 for the plugin directory, the session log was the difference between "this plugin is broken" and "here's the exact line where it broke." Three recurring failures stood out because the log made them trivial to pin down:

ERR_REQUIRE_ESM — the log showed the plugin module failing to load because it was compiled to CommonJS but depended on an ESM-only package. The failing event pointed straight at the module, not at our setup.
cannot get property "systemPrompt" without inject — the log captured the plugin calling ctx.systemPrompt without declaring inject: ["systemPrompt"]. Without the event trail, this is a mysterious crash; with it, it's a one-line report to the plugin author.
Silently inert plugins — a package with no dsh.bundle manifest installs as a plain dependency and never loads. The log made the "never loaded" part visible: no plugin-init event, no error, just absence.

That last one is the subtle win. A black-box agent would have shown nothing at all — the plugin "just doesn't work." An event log shows you the absence of an event, which is itself diagnostic. The one-line fixes are all in our troubleshooting guide.

Observability is also a cost tool

The same log doubles as a cost profiler. Each event shows what went into context, so you can:

Spot re-sent context — the same large block appearing repeatedly is being re-injected (and re-billed).
Find unnecessary tool round-trips — long chains of read/search calls that could collapse into one (what PTC mode is for).
Check compression — see when context gets compressed and whether it's dropping useful history.

Combine an inspectable log with a cache-friendly request shape and you get the 99.93% cache hit rate playbook. Observability and cost are the same feature viewed from two sides.

Why "rebuildable" actually matters

The append-only design is also what makes the "rebuildable session" in our Codex comparison more than a talking point. Because the next turn's history is re-derived from events, a session can be resumed, replayed, or forked without losing the trail — a session log you can reconstruct from its events is a session you can trust as a debugging record, not just a transcript.

FAQ

Is the session log the same as a chat transcript?

No. A transcript is what the user sees. The event log includes everything the model sees internally — reasoning, tool results, permission changes, injections — and it's the source from which the next turn's history is re-derived.

Can I replay a session exactly?

Yes. Because the next turn is re-derived from the log, replaying a run from its events reproduces the same state — useful for reproducing bugs and for research.

Does this help if a plugin fails silently?

It's exactly where it helps most. A silent failure leaves no error, but the log shows the absence of the expected event — the plugin never initialized — which points you to the missing dsh.bundle manifest.

How does this compare to Claude Code or Codex?

Both keep their intermediate state hidden. DSH exposes the whole trail as first-class data, which is the single biggest observability difference between it and closed harnesses.

See the four modes guide — the Create mode and session logs together are what make DeepSeek Harness an agent framework rather than a finished product. For a deeper walkthrough of using the log to debug, see our trajectory tracing guide.

All articles →