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 | 中文
The bar above the composer: empty while idle, deepening blue while running, solid deep blue at 100%
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)
dsh plugin --profile desktop add dsh-live-progress
Then restart DSH and refresh the page.
From a local checkout
dsh plugin --profile desktop add /path/to/dsh-live-progress
Manual (no CLI)
-
Copy this folder to <profile>/node_modules/dsh-live-progress.
-
Add to <profile>/package.json:
{
"dependencies": { "dsh-live-progress": "file:/path/to/dsh-live-progress" },
"dsh": { "profile": { "bundles": ["...", "dsh-live-progress"] } }
}
-
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):
curl -s ${DSH_WEB}/task-progress/health # subscriptions + active streams
curl -s "${DSH_WEB}/task-progress/state?session=<id>"
curl -sN "${DSH_WEB}/task-progress/stream?session=<id>" # 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:
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
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=<id> ─── JSON ───────────┤
GET /task-progress/stream?session=<id> ─── 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.
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 © 2026 chioplet
