dsh-context 0.7.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +27 -88
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,119 +1,58 @@
1
+ ![Social preview](https://raw.githubusercontent.com/bowenliang123/dsh-context/main/docs/social-preview.png)
2
+
1
3
  # dsh-context
2
4
 
3
- A **Context insight panel** for [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) (dsh): a plugin that adds a **Context** tab to the web UI — right beside **Chat** and **Trajectory** — so you can see what the model's context window is actually made of, and how it evolves across the conversation.
5
+ [![npm version](https://img.shields.io/npm/v/dsh-context)](https://www.npmjs.com/package/dsh-context)
6
+ [![GitHub stars](https://img.shields.io/github/stars/bowenliang123/dsh-context?style=social)](https://github.com/bowenliang123/dsh-context)
4
7
 
5
- ![dsh-context screenshot](https://raw.githubusercontent.com/bowenliang123/dsh-context/main/docs/screenshot.png)
8
+ **See what your DeepSeek Harness agent's context window is actually made of and how it evolves.**
6
9
 
7
- ## Quick install
10
+ `dsh-context` is a [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) plugin that adds a **Context Insight** panel to the web UI: a live, visual answer to *"what is the model carrying right now, and how did it get there?"* — context composition, per-request history, compactions, and injections, all in one place.
8
11
 
9
- One command, from any [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) installation (the `web` profile is the one `dsh web` boots; it is created automatically on first use):
12
+ ![Context panel overview](https://raw.githubusercontent.com/bowenliang123/dsh-context/main/docs/context-overview.png)
10
13
 
11
- ```sh
12
- dsh plugin --profile web add dsh-context
13
- ```
14
+ ## Install
14
15
 
15
- then start the web UI and open any session — the **上下文 / Context** tab appears right beside **Chat** and **Trajectory**:
16
+ One command, from any DeepSeek Harness installation:
16
17
 
17
18
  ```sh
18
- dsh web
19
+ dsh plugin --profile web add dsh-context
19
20
  ```
20
21
 
21
- > Running dsh from a source checkout instead of the installed CLI? Prefix the commands with `pnpm` (`pnpm dsh plugin --profile web add dsh-context`).
22
-
23
- ## Why
24
-
25
- Every model request packs the same window from six sources: the system prompt, tool schemas, your messages, injected context (skills, AGENTS.md, runtime snapshots), assistant replies, and tool results. When a conversation degrades or gets compacted, *which part ate the budget* is usually invisible. dsh-context makes it observable:
26
-
27
- - **Current composition** — a stacked bar of the six categories, scaled against the model's context window (the gray track is your remaining headroom), plus the top-5 most expensive tool schemas.
28
- - **History** — one stacked bar per model request (finer than per-turn), with Y-axis ticks and gridlines. Click any bar for its full breakdown, including the **provider-reported** prompt/output tokens next to the estimate. ✂ marks where compaction/pruning happened — watch the bars drop.
29
- - **Context events** — compactions, tool-output prunes, skill injections (`Skill injected (code-review)`), plugin context injections, model switches — each with its token delta and timestamp.
30
- - **Messages** — the currently model-visible surface, message by message, with per-message token costs.
22
+ Then start the web UI with `dsh web`, open any session, and click the **上下文 / Context** tab. No build step, no restart.
31
23
 
32
- The UI is bilingual (中文/English) and follows the dsh locale automatically.
24
+ ## What you'll see
33
25
 
34
- ## Install
26
+ ### 📊 Context stats — the session at a glance
35
27
 
36
- dsh-context ships as a **dsh bundle**: an npm package with a `dsh.bundle` manifest (a `cordis.patch.yml` layer that inserts the plugin row) and a `dsh.client` manifest (the web UI half). No build step, no restart — the one-liner above installs it into the `web` profile (or any other profile you boot with `dsh --profile <name>`). The `dsh-context` loader row activates the host half, and the web app picks up the package's `./client` bundle and adds the **上下文 / Context** tab to every session view.
28
+ Turns, steps, how much context has been recycled by compactions and prunes, how many injections happened, model switches, and the estimated total tokens sent — next to the provider-reported actuals, so you can see how the estimate holds up.
37
29
 
38
- To install from this checkout instead (for development), from the repo root:
30
+ ### 🧱 Current composition — what's in the window right now
39
31
 
40
- ```sh
41
- dsh plugin --profile <name> add .
42
- ```
32
+ A six-color stacked bar scaled against the model's full context window (the gray track is your remaining headroom): system prompt, tool schemas, your messages, injected context, assistant replies, and tool results — plus the top-5 most expensive tool schemas. When a conversation starts degrading, this is where you find out *which part ate the budget*.
43
33
 
44
- If dsh is run from a source checkout, prefix the commands with `pnpm` (`pnpm dsh plugin ...`).
34
+ ### 📈 History — watch the window grow (and get compacted)
45
35
 
46
- ## Usage
36
+ One stacked bar per model request, finer than per-message. Toggle between **Turn** and **Step** granularity, scroll sideways through the session, hover any bar for a quick tooltip, and click to pin the full breakdown — including provider-reported actual prompt/output tokens next to the estimate. **✂ marks where compaction or pruning happened** — watch the bars drop:
47
37
 
48
- Open any session and click **上下文 / Context** (to the right of Chat and Trajectory). Data refreshes every 2 seconds while the tab is open; switching sessions switches the view to that session's log — including historical, persisted sessions.
38
+ ![History chart with a pinned request](https://raw.githubusercontent.com/bowenliang123/dsh-context/main/docs/history-detail.png)
49
39
 
50
- - **Hover** a history bar for a quick tooltip; **click** it to pin the breakdown below the chart.
51
- - The overview bar is scaled to the model's context window, so ~13% full means ~13% of the window is spoken for.
52
- - Numbers are estimates using the *same fixed-density heuristic as dsh's built-in tokenMeter* (~4 chars ≈ 1 token), so they match the harness's own stats. Wherever the provider reported real usage, it's shown alongside as "actual".
40
+ Above: a real session that grew to ~563k tokens across 48 turns, then compaction (✂) recycled −535.5k in one step, and the conversation continued from a fresh, small window.
53
41
 
54
- ## How it works
42
+ ### ⚡ Context events — when and why the window changed
55
43
 
56
- - **Data source**: the session's durable event log. Live sessions are folded straight from the in-memory log (`sessions.get(id).events` — no clone, no disk parse); persisted sessions fall back to `sessionQuery.readSession`.
57
- - **Transport**: host ↔ browser over a generic **Connection RPC channel** (`/dsh-context`, `ctx.connection.rpc` — the same channel mechanism the api gateway uses). The host half registers a `snapshot` endpoint; the client half calls it via `ctx.connection.rpc.call`.
58
- - **Incremental fold**: per-session fold state lives in the Host half, so each poll only processes newly appended events — reopening the tab is instant.
59
- - **Events decoded**: `request/header` (system prompt + tool schemas), surface events with `surfaceOp` (append/replace — compaction rewrites history in place), `compaction/summary|prune`, `assistant/message.usage` (real provider tokens), and message `source` metadata (`plugin` forms, `skill-invocation`) for injection events.
60
- - **Architecture**: `src/host/` is a plain ESM Cordis plugin (zero runtime dependencies) loaded by the `dsh-context` loader row; `src/client/` is the browser half, bundled at build time into the web boot's closure-factory bundle (`window.__ModuleLoader__.load`). The client renders with bare `React.createElement` — theme-native via dsh CSS variables, bilingual via the client `locale` service. Both halves are strict TypeScript with local (drift-free) service contracts, sharing the wire model in `src/shared/types.ts`.
44
+ Every compaction, tool-output prune, skill or plugin context injection, and model switch — each with its token delta, turn/step attribution, and timestamp:
61
45
 
62
- ## Development
46
+ ![Context events and messages](https://raw.githubusercontent.com/bowenliang123/dsh-context/main/docs/context-events.png)
63
47
 
64
- The project is a pnpm workspace root (`pnpm-workspace.yaml`), so `pnpm install` never walks up into a parent workspace.
48
+ ### 💬 Messages — the currently model-visible surface
65
49
 
66
- ```sh
67
- pnpm install # devDependencies only — the plugin itself stays dependency-free
68
- pnpm run typecheck # tsc --noEmit (strict)
69
- pnpm run build # esbuild: lib/index.js (host) + lib/client.js (client bundle)
70
- pnpm test # typecheck + functional tests for both halves
71
- pnpm run repro # real-React + jsdom render smoke (granularity-toggle regression)
72
- ```
50
+ The exact message list the model sees right now, newest first, with a per-message token cost.
73
51
 
74
- `build.mjs` also smoke-checks the outputs (both halves must parse; the host half must import with the `name`/`inject`/`apply` plugin shape).
75
52
 
76
- Commits are guarded by a [husky](https://typicode.github.io/husky/) pre-commit hook that runs `pnpm run typecheck` (`tsc --noEmit`, strict).
77
-
78
- ## Project structure
79
-
80
- ```
81
- src/
82
- shared/types.ts # Wire contract: Snapshot / RequestRecord / ContextEventRecord / SurfaceNode
83
- host/ # Host half — folds the session log into the snapshot
84
- index.ts # Plugin entry: name/inject/apply + /dsh-context RPC endpoint
85
- services.ts # Local service contracts (sessions/sessionQuery/connection)
86
- pricing.ts # dsh token-meter heuristic (estimateMessage/system/tools)
87
- fold.ts # Incremental per-session fold + whole-turn retention
88
- snapshot.ts # Snapshot building + event turn/step attribution + caching
89
- client/ # Client half — the Context tab UI
90
- index.ts # Plugin entry: dicts, styles, slot registration
91
- view.ts # Composition root: ViewKit + component wiring
92
- viewkit.ts # Shared component dependencies (t/tr/fmt/catLabel/event helpers)
93
- i18n.ts / styles.ts # Bilingual dictionaries / theme-native styles
94
- format.ts # Number (k/M) and time formatting
95
- categories.ts # Category colors + partsOf breakdown projection
96
- cache.ts # Per-session snapshot cache (stale-while-revalidate)
97
- components/ # One module per component (TrendChart, RequestDetail, …)
98
- scripts/ # build.mjs (esbuild) + publish.sh (npm release)
99
- tests/ # host.test.mjs, client.test.mjs, repro-real-react.mjs
100
- ```
53
+ ## Like it?
101
54
 
102
- First-screen notes: the tab seeds its initial render from the per-session snapshot cache (re-opening a session paints instantly, the poll refreshes behind it), pauses polling while the tab is hidden, and never blanks already-visible data on a transient fetch error. On the host, cold-session folding is a one-time ~10 ms pass over the durable log and is cached afterwards, so the `/dsh-context` poll stays cheap.
103
-
104
- ## Files
105
-
106
- | File | Role |
107
- | --- | --- |
108
- | `src/shared/types.ts` | Shared wire contract (type-only; both halves import it) |
109
- | `src/host/*.ts` | Host half: fold, pricing, snapshot, RPC entry |
110
- | `src/client/*.ts` | Client half: view composition, components, i18n, styles |
111
- | `tsconfig.json` | Strict typecheck config (noEmit; esbuild does the transpiling) |
112
- | `package.json` | `dsh.bundle` (patch layer) + `dsh.client` (web UI) manifests |
113
- | `cordis.patch.yml` | The bundle's patch layer: inserts the `dsh-context` row |
114
- | `scripts/build.mjs` | esbuild-based build of `lib/index.js` + `lib/client.js` |
115
- | `tests/*.mjs` | Functional tests for both halves + the real-React repro |
116
- | `docs/screenshot.png` | The UI in action |
55
+ If `dsh-context` helped you understand what your agent is carrying around, a ⭐ on [GitHub](https://github.com/bowenliang123/dsh-context) is much appreciated — and issues/PRs are welcome!
117
56
 
118
57
  ## License
119
58
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-context",
3
- "version": "0.7.0",
4
- "description": "Context insight panel for DeepSeek Harness: a Context tab (beside Chat/Trajectory) showing what the model's context window is made of and how it evolves — composition, per-request history, compactions, injections, and model switches.",
3
+ "version": "0.7.2",
4
+ "description": "Context insight panel for DeepSeek Harness: see what the model's context window is made of and how it evolves — composition, per-request history, compactions, injections, and model switches.",
5
5
  "author": "bowenliang123",
6
6
  "repository": {
7
7
  "type": "git",