dsh-context-lens
dsh-context-lens
Request Context Profiler for DeepSeek Harness — see what changed between model requests, and how cache reuse changed with it.
What it is
dsh-context-lens is a DeepSeek Harness plugin (server unit + client view) that answers one question continuously: "what did the harness send the model this time, and what changed since the last request?" It is a pure observer — it reads the session log, adds nothing to it, and never touches a model call.
dsh-context-lens dashboard
Quick start
dsh plugin --profile web add dsh-context-lens
Open any conversation, switch to the Request Context tab, and watch every
model request get one line: what changed vs the previous request, and how
cache reuse moved with it.
For every real LLM request it records one compact card:
- Request identity — turn:step, provider, model, context window, status (completed / failed / aborted).
- The committed request context — canonical fingerprints of the system prompt, the tool set (each tool's schema hash + estimated tokens), the request config, and the tool declaration order. Only state actually committed to a real model request is compared; the harness's mutable state is never observed.
- Cache reuse readout — computed strictly from the provider's disjoint usage buckets (uncached input + cache reads + cache writes = billed input). Missing fields stay absent (rendered
-), never zero.
- Diff vs the previous request — model, provider, config, system prompt, tool set (+added/−removed/~modified), tool order, estimated surface delta, and the cache-reuse boundary in percentage points.
- Drop alarm — when reuse dropped across the threshold, a ranked list of coincident changes (correlation, never causation) with an explicit disclaimer.
The view is change-first (a conversation.view slot, zh/en). Opening it answers "is anything wrong, and where?" in one glance:
- a session status strip — ✓ cache stable / ✓ structure stable / analyzed count, flipping to ⚠ alarm counts on anomalies;
- the recent-requests list, newest first (up to 100 retained), one line per request — a session-global ordinal, a change tag (Stable / Cache drop / Tools changed / System changed / +X tok), the cache readout, and a "hide unchanged requests" filter on by default;
- the inspector — cache reuse with its delta, new uncached input, estimated context surface, a line-by-line comparison vs the previous request (system / tools / tool order / config / model / provider), and a green conclusion when nothing is cache-impacting;
- raw usage buckets, header hashes, and the full tool list behind a "technical details" fold.
Accuracy boundaries
Everything on the left is genuinely observable; nothing on the right is ever claimed.
| Can determine | Cannot determine (and never claims) |
|---|
| System prompt, tool set, tool schemas, declaration order, request config — as committed to the request | The provider's internal cache key construction |
| Model and provider of each request | The exact token at which prefix reuse breaks (KV-causality) |
| Provider-reported usage buckets (uncached input / cache reads / cache writes / output / reasoning) | Which single change caused a drop — only correlation |
| Reuse ratio and its delta between consecutive requests | Cache state of sessions/requests that left the 100-entry window |
| A heuristic surface estimate (chars/4 + per-block + per-role overhead) | Anything about the harness's in-memory state |
Architecture
Server — one pure, replayable projection (contextLens) folds the session log: request/header events (epoch-logged, committed only on change) define the snapshot in force at each step/start; a header landing inside the step replaces it (that is the header the provider actually saw). step/end marks the span closed; finalization happens at turn/end for the last step, at the next step/start for intermediate steps, and crash-orphaned logs close as failed. Retries do not mint new records (mainline retries inside the same step; the fold also splits cleanly if a future mainline opens a fresh turn). Uninteresting events return the same state reference — the registry's zero-work Object.is gate.
Replay consistency is a tested invariant: folding the log incrementally (live) and folding the same log from init (replay) produce identical state and projection.
Client — registers the context-lens entry (order 30) in the conversation.view slot, reads the projection through the framework's useProjection('contextLens') seat, and ships its own zh/en locale namespace. Selection is component-local. No heavy UI dependencies; CSS Modules compiled with lightningcss and injected as one idempotent <style> tag.
Zero overhead — no new session events, no model tools, no prompt injection, no KV simulation. A no-op companion plugin (context-lens-invariant) exists solely to reserve the package name under the harness's invariants service.
Install & build
The plugin is an npm package with a single runtime dependency (zod); all @deepseek-ai/* references are type-only. Install it into a harness profile:
dsh plugin --profile web add dsh-context-lens
Developing from source: the harness packages install from the registry (since 0.1.5 the whole @deepseek-ai/* set is published, so the old vendor-stubs/ type-only snapshots are gone). autoInstallPeers is on and zod@^4 matches the framework contract. This plugin tracks the 0.1.5 harness contract: projection units declare stateSchema + wire, the system prompt is tracked from system/message history nodes, and CLIENT_EXTERNALS mirrors the shell's new PLATFORM_MODULES. See IMPLEMENTATION_NOTES.md → "0.1.5 harness contract".
pnpm install
pnpm typecheck # tsc --noEmit
pnpm test # vitest — 68 tests: fingerprint, cache math, diffing, projection lifecycle, step/end, replay consistency, formatting, determinism
pnpm build # tsc declarations → lib/types, tsdown → lib/index.js + lib/invariant.js + lib/client.js (browser, closure-factory ABI)
The browser bundle replicates the harness client-bundle ABI: window.__ModuleLoader__.load({ id: "dsh-context-lens", factory: (require) => … }), resolving react / react-dom / platform module-table entries through the loader-injected require and inlining everything else.
Real-runtime smoke scripts live in smoke/ (see smoke/README.md): a server-side smoke over the real harness packages, a client-loader ABI smoke, and a full GUI E2E against a second web instance with a mock LLM.
Layout
src/ server: types, fingerprint, cache, diff, projection, index; companion invariant
src/client/ the conversation view + locales + CSS Modules
tests/ vitest specs incl. the replay-consistency suite
smoke/ real-runtime smokes: server, client ABI, GUI E2E
cordis.patch.yml dsh bundle patch metadata
Roadmap
- Retained-window cursor to inspect older requests than 100.
- Correlation drill-down: group drops by (model, provider, tool-set hash) across the window.
- Distinguish session-level counters from the retained window in the status strip (a drop at #127 must not read as "recent 100 are clean").
License
MIT
