dsh-live-progress

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.

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)

1. Copy this folder to <profile>/node_modules/dsh-live-progress.

2. Add to <profile>/package.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):

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