Blog · Tutorial

Trajectory tracing: the killer feature rivals hide

August 14, 2026 · dshbase

One feature of DeepSeek Harness keeps coming up as its biggest differentiator: every run is traceable. When an agent fails or loops, you can see the exact step it went wrong — information that OpenAI and Anthropic encrypt away from you. Here's what it is and, more importantly, how to actually use it. Everything below was produced while debugging on dsh 0.1.0-rc.6.

What trajectory tracing actually is

DSH stores sessions as an append-only event log. Every system prompt, user message, reasoning step, tool call and result, permission change, context injection, compression, and sub-agent schedule becomes an event. The model's next-turn history is re-derived from that log, not from a black box. The trajectory view lets you inspect each run by source — so you can see not just what happened, but which plugin or tool emitted each event. See what's in the log for the full breakdown.

Why this matters: rivals encrypt it away

US models (OpenAI, Anthropic) treat this as hidden internal state — you can't see the intermediate reasoning, tool calls, or where a task derailed. You get a final answer and, if it failed, a vague error. DSH gives you the whole trail. For debugging and research, that's a genuine advantage — and it's the difference between guessing at a failure and reading the exact event that caused it.

How to use it to debug

Find the derailment point — open the trajectory view and walk the events in order; the failure is almost always a specific tool call or permission decision, not the final line.
Check tool results — a wrong answer is often a tool returning bad data, not a model error. Trace the tool's output.
Review permission changes — if the agent did something unexpected, the permission events show when and why it was allowed.

The log also turns the most common plugin failures into a read-out instead of a mystery. Three we hit repeatedly, and their log signatures:

A plugin that never activates — the log shows the package added as a dependency but no load event. That's the signature of a missing dsh.bundle manifest.
ERR_REQUIRE_ESM — appears in the log as the exact load failure, meaning the plugin was compiled to CommonJS but depends on ESM-only packages.
cannot get property "systemPrompt" without inject — surfaces as an error event the moment plugin code reads ctx.systemPrompt without declaring inject: ["systemPrompt"].

Each has a one-line fix in the troubleshooting guide. The point here is that with the trajectory view you get the exact error string, which makes the fix a lookup instead of a guess.

A concrete run from our testing: a plugin installed via dsh plugin add github:owner/repo looked fine in the directory, but the agent never used it. Walking the trajectory in order, we saw a dependency-add event and then silence — no load event. That signature (a dependency with no load) is the missing-dsh.bundle tell. Reading it took thirty seconds and pointed straight at the fix; guessing would have burned ten minutes and produced a wrong conclusion.

How to use it to cut token waste

The trajectory log is also a cost profiler. Each event shows what went into context:

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

Combine this with a cache-friendly harness design (minimal tools, append-only sessions) and you get the 99.93% cache hit rate playbook. The connection is direct: an append-only log is also a stable request prefix, and a stable prefix is what keeps DeepSeek's automatic prefix cache hitting.

The takeaway

Trajectory tracing turns an opaque agent into an inspectable one. For anyone running agents seriously — debugging failures or optimizing cost — it's not a nice-to-have; it's the reason to pick a harness that doesn't hide its work. The rivals charge you for tokens and then encrypt the receipt. DSH hands you the receipt, line by line.

FAQ

Does trajectory tracing slow the agent down? No — sessions are already stored as event logs internally; the view is just reading that structure. You're inspecting the source of truth, not adding overhead.

Can I see the model's hidden reasoning? You see the reasoning steps the harness records as events (system prompt, tool calls, results), not the model's private internal chain-of-thought — which is the same boundary all providers keep.

How do I tell a missing dsh.bundle from a genuine crash? A missing manifest means the plugin is added as a dependency but emits no load event. A crash emits an error event with the exact message. The log distinguishes the two cleanly.

All articles →