CH 29 · Observability and Context Management

Word count~3,170 wordsTime~20 minPrereqCH 04, CH 16LevelConceptual focus

Chapter Goal

After the Agent is up and running, you'll eventually run into these questions: why did it just make that decision? How many tokens did this round cost? Long sessions get slower and more expensive, what to do?

dsh's approach is to lay out every step of the Agent for you — what it saw, what it thought, what it did, how much it cost, all traceable. CH 04 covered the basics of the Trajectory interface, CH 16 mentioned cache hit rate; this chapter makes observability and performance fully clear: how to read the Trajectory, where session logs are stored, how to read Token and cache metrics, how to manage context. Once you've mastered these, you can advance from "usable" to "use it efficiently and stably".

Trajectory: The Agent's Complete Running Account

What Is the Trajectory

Ordinary Agent tools show you the "chat history" — what you said, what it replied. But what happened in between? Which file did it read, what tool did it call, what did the tool return, why did it decide to call this tool and not that — these are invisible in the chat view.

The Trajectory solves this problem: it records the Agent's complete execution process in a timeline, it's "the model's view of the running account", not "the user's view of the chat history".

What's recorded:

Category	What it records
System prompt	The complete system prompt sent to the model on each request
User input	Your message, injected context
Model request	Complete content sent to the model, complete content returned by the model
Tool call	Which tool, what parameters, what the return result was
Subagent scheduling	How many subagents were started, what each did, how the results were aggregated
Approval interaction	Which operations requested approval, whether you allowed or denied

All of this is written into a single append-only session log — only added, never modified, guaranteeing record completeness and auditability.

Where to View the Trajectory

In the Web UI's session interface, there's a Trajectory tab at the top, click in.

The interface looks like the browser dev tools' network panel:

• Top timeline: drawn left to right by real start and end times, each round of requests takes a segment
• Left event list: one row per record, grouped by turn, each marked with type (LLM / TOOL / SUBAGENT / APPROVAL)
• Right detail panel: click a record to expand and see the complete content — tool call Schema / Payload / Result, the complete prompt and response of the model request

What Can the Trajectory Be Used For

1. Troubleshooting: Agent did something unexpected? Go back in the Trajectory and see what it received at the time, why it made that decision. 90% of "AI acting up" can be found in the Trajectory — usually it read a file you didn't notice, or the tool returned an abnormal value.
2. Review: the task went well or poorly, go back in the Trajectory and see which step was the key turning point, which step wasted tokens. Next time you can optimize the prompt or flow.
3. Reproduce experiments: when doing Agent research, the Trajectory is the complete experiment record — same input, same tool, same model version, can reproduce the same result.
4. Audit: when the team shares, the Trajectory can answer "when did it change this file, why" — more granular than git log, because it even records "why it changed".

Session Log: Where It Lives, How to Use It

Trajectory data ultimately lands in local files, not just in memory.

Storage Location

All sessions are stored in the ~/.dsh/sessions/ directory (on Windows: C:\Users\<your-username>\.dsh\sessions\), organized by workspace directory.

The workspace directory name is the escaped form of the path — wrapped with --, path separators replaced with -, special characters URL-encoded. For example, workspace E:\software-workspace\DeepSeek harness demo corresponds to directory name --E-software-workspace-DeepSeek~0020harness~0020demo--.

Each session is a subdirectory, named with the format session-<uuid> (created by Web UI) or pure <uuid> (run by headless), containing a session.jsonl.zstd file (zstd-compressed JSONL, one event per line).

~/.dsh/sessions/
├── --E-software-workspace-DeepSeek~0020harness~0020demo--/
│   ├── session-05da13b1-c7bf-4f42-843b-.../
│   │   └── session.jsonl.zstd
│   ├── session-06451c43-35fb-4338-bc87-.../
│   │   └── session.jsonl.zstd
│   └── 37e884fa-7c73-40fa-81fc-.../          ← session run by headless
│       └── session.jsonl.zstd
└── --E-software-workspace-doubaowork-DeepSeekHarnessGuide--/
    └── session-f417b4dd-3c8f-4098-85.../
        └── session.jsonl.zstd

Three Capabilities of a Session

Based on this log, dsh supports three operations:

1. Resume: close dsh and reopen it, the previous session is still there, you can continue chatting — because the log is persistent, not in-memory.
2. Fork: click the fork icon below a historical message, start a new path from that message, without touching the original session. For example, if the Agent went to step 5 and you think the direction is wrong, you can fork to step 4 and try a different prompt, the original session is preserved. The new session from the fork will have a (1), (2) suffix in its name, distinguishing it from the original.
3. Replay: replay a session's event stream, see each step's input and output. Suited for debugging plugins or reproducing issues.

Performance Metrics: Token, Cache, Context

dsh displays several key performance metrics in real time in the interface; learn to read these and you can control cost and speed.

Token Usage

After each round of requests, the bottom of the interface displays this round's Token statistics:

• Input Token: total tokens sent to the model (including system prompt, conversation history, tool results)
• Output Token: tokens generated by the model
• Cache hit Token: portion of input that hit DeepSeek's context cache

Cumulative usage is in the session stats — how many tokens the whole session used, how much money it cost.

Context Occupancy Rate

There's a ring on the right of the input box, showing the current context occupancy percentage. This is dsh's unique design — letting you see in real time "how much context space is left".

Context is finite (different model window sizes, generally 128K starting). When the occupancy approaches 100%, dsh auto-compresses the context — summarizing early history into a digest, replacing the original multi-turn conversation, ensuring the conversation can continue without erroring out due to exceeding the window.

Auto-compression is a fallback mechanism. So a more recommended approach is: at the right time, manually trigger compression yourself — type the /compact command in the input box, and dsh will immediately compress the current conversation into a summary, replacing the original multi-turn history. Compressing on your own rhythm, key information won't be lost.

When the occupancy is almost full, two choices: type /compact to manually compress, or just open a new session.

Context Management: How to Keep Long Sessions from Crashing

Agent sessions have a natural problem: the longer you chat, the more tokens you spend, and the model "remembers" less of the front. dsh gives several tools to manage this.

When to Open a New Session

Not all tasks should be done in one session. The following situations suggest opening a new session:

• Task type changed: just now was writing code, now need to make a PPT — open a new session, don't let the code context pollute the PPT task
• Workspace changed: switched project directory — open a new session, dsh's sessions are bound to the workspace
• Context occupancy over 70%: chatting further the model will drop early content, and reactions will slow down — sometimes you suddenly feel the model got dumber, that's why. Open a new session, or /compact first to compress

A Few Cost-Control Habits

1. Don't do everything in one session — split sessions by task, each session has short context, high cache hit rate, low cost
2. Don't repeatedly read large files — the Agent reading a 1000-line file costs tokens each time. After reading once, have it write the key information into a summary file, then just read the summary later
3. Use the right model — simple tasks with flash, complex reasoning with pro, visual tasks with vision — don't use the most expensive for everything
4. Check cumulative usage regularly — session stats show total tokens and estimated cost, don't wait until the end of the month to get a shock

What you learned in this chapter

You pass if you can complete the items below:

• [ ] Know what the Trajectory is, where to view it, what content is recorded in the Trajectory
• [ ] Know that session logs are stored in ~/.dsh/sessions/, supporting resume, fork, replay
• [ ] Can understand what input / output / cache hit in Token stats are
• [ ] Know where the context occupancy rate is shown, what to do when it's almost full
• [ ] Know how to use the /compact command, and when to manually compress
• [ ] Can state at least 3 cost control habits