dsh-live-progress
A real task progress bar above the DSH composer.
It shows what the host is actually doing — and refuses to invent the rest.
English | 中文
---
## What it does
A slim rounded bar sits full-width **above the message box**, in the same column as the
composer. It is there before a task starts (idle, empty, muted), it fills as the turn runs, and it
stays full and dark blue until the next task begins.
Under the bar there is one line of text: what is happening right now, which step it is, what has
already finished, and — when there is a real denominator — the percentage.
| State | What you see |
| --- | --- |
| Idle | Empty track + `待命中` / `Idle`, no percentage |
| Running, no real denominator | Honest indeterminate fill, `Step 3 · 2 actions done`, no fake `%` |
| Running, plan known | Fills step by step, real percentage (`40%`), darkest-so-far blue |
| Failed | `Task ended (with errors)`, failure count in the detail line |
| Done | 100%, solid deep blue, stays until the next task |
## Why the percentage is trustworthy
Most progress bars move because a timer moved them. This one only moves when the host says
something really happened:
- **Plan is the denominator.** When a task calls `todo_write`, the plan is the real step list, so
`2/5` becomes a real 40% instead of another estimate.
- **Workflow phases are a denominator too.** `workflow/phase` reports
`Phase 2/4` → 50%.
- **No denominator, no percentage.** Without a plan or a workflow, the bar runs an indeterminate
animation and the text reports real counters (steps, tool calls, responses). It never writes a
number it cannot defend.
- **It does not move while the model thinks.** No interpolation, no creep, no 99% stall.
- **100% means finished.** The bar only completes when `turn/end` or `agent/status idle` actually
arrives.
- **Estimates are labelled.** Once a session has completed the same kind of run twice, the host may
show a history-based estimate; it is rendered as `~42%` with `data-estimate="true"` and announced
as "about 42%".
## Features
- Full-width rounded bar docked in the official `conversation.input.dock` slot — no DOM
injection into anyone else's nodes.
- Real progress driven by host events (14 event names, per-session state, SSE push).
- Plan-aware: reads the session's real `todo_write` plan and follows its statuses.
- Blue only, deepening with progress: light blue at the start, deep blue at 100%.
- One accent colour at a time — no green/orange/red anywhere in the bar.
- Smooth `transform` animation, GPU-friendly, honours `prefers-reduced-motion`.
- Accessible: `role="progressbar"`, `aria-valuenow`, and an `aria-valuetext` that speaks the real
detail even in indeterminate state.
- Fail-quiet: if anything on the browser side throws, the widget degrades to a minimal read-only
row and reports the error back to the host (`/task-progress/client-report`) instead of breaking
the page.
- Zero build step: plain ESM on the host, a pre-built CommonJS bundle on the client.
- No runtime dependencies.
## Requirements
- DSH with the web conversation UI (`@deepseek-ai/dsh-client-ui-conversation`).
- A profile that can load a `dsh.bundle` patch (web or desktop profile).
## Install
### From npm (recommended)
```sh
dsh plugin --profile desktop add dsh-live-progress
```
Then restart DSH and refresh the page.
### From a local checkout
```sh
dsh plugin --profile desktop add /path/to/dsh-live-progress
```
### Manual (no CLI)
1. Copy this folder to `/node_modules/dsh-live-progress`.
2. Add to `/package.json`:
```json
{
"dependencies": { "dsh-live-progress": "file:/path/to/dsh-live-progress" },
"dsh": { "profile": { "bundles": ["...", "dsh-live-progress"] } }
}
```
3. Restart DSH, then refresh the page.
Uninstall: remove the dependency and the `dsh.profile.bundles` entry, restart DSH.
## Verify it is alive
The host half is plain HTTP/SSE (no `/api` auth fence, by design of `dsh-host-webserver`):
```sh
curl -s ${DSH_WEB}/task-progress/health # subscriptions + active streams
curl -s "${DSH_WEB}/task-progress/state?session="
curl -sN "${DSH_WEB}/task-progress/stream?session=" # SSE frames
curl -s ${DSH_WEB}/task-progress/debug # shapes + self-test + client diagnostics
```
## Offline verification
Four assertion suites run against the very same files the browser and the host load — no DSH
required:
```sh
node run-selftest.mjs # 25 assertions · host self-test + progress model
node run-real-shapes.mjs # 30 assertions · real session/event shapes
node run-client-test.mjs # 58 assertions · the browser bundle under a fake React
node run-host-routes.mjs # 75 assertions · HTTP routes, JSON contracts, SSE frames
```
All 188 assertions pass.
## How it works
```text
DSH host Browser
───────────────────────────────────────────── ───────────────────────────────
session/event · agent/status · tools/* conversation.input.dock slot
workflow/* · subagent/* · api-session/* │
│ │ fetch + EventSource
▼ │
lib/collector.js ── real events → one state per session │
│ │
GET /task-progress/state?session= ─── JSON ───────────┤
GET /task-progress/stream?session= ─── SSE ───────────┘
POST /task-progress/client-report ← browser diagnostics
```
- `index.js` — host half: subscribes to events, keeps the collector, serves the routes,
pushes SSE frames, runs the built-in self-test.
- `lib/collector.js` — the progress model: real counters, plan tracking, honesty rules,
per-session state, run history.
- `client.js` — browser half: registers the dock, reads the state over SSE, renders the bar,
smooths it, and degrades quietly on any error.
- `cordis.patch.yml` — the one-line bundle patch that puts the plugin into the profile's
loader tree.
More detail: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
## Compatibility
- Tested against DSH desktop profile on Windows, `dsh 0.2.0-rc.1`.
- The plugin declares `peerDependencies: { "@deepseek-ai/cordis": "^4.0.0" }`. The SDK it reads is
not bundled, so it follows the host it is installed into rather than pinning a copy.
## Design notes
- The fill is one accent hue, deepening from light blue to deep blue. No second colour is used to
signal anything; every other state (failed, idle) is expressed in text and fill behaviour.
- The row keeps the same height in every state, so the composer never jumps.
- In the finished state the bar stays at 100% until the next task starts — that is deliberate,
it is the receipt that the last task ended.
- The bar lives in a plugin-lifetime style tag (`data-plugin-css="dsh-live-progress:css"`); the
disposer removes it.
## Known limitations
- Percentages need a real denominator (a plan, or workflow phases). A plain tool-calling turn shows
counters, not a percentage. This is intentional.
- The browser half cannot see host events directly; it renders the host state that is pushed to it.
- A host-side code change needs a DSH restart (the loader caches host modules); a browser-side change
needs a page refresh.
## License
[MIT](LICENSE) © 2026 chioplet