dsh-job-progress

dsh-job-progress

How far along is it? — a floating ball in the session that owns the job answers that.

A DeepSeek Harness plugin showing live progress for long-running background jobs: downloads, model conversions, renders, batch jobs — anything that runs in the background.

_{The ball floats over the conversation, badges the running count, and expands into the task panel.}

Features · Install · Quick start · Protocol · Verify · Troubleshooting · 中文

Features

Install

From a local folder (recommended)

git clone https://github.com/Rice00/dsh-job-progress.git
dsh plugin --profile <profile> add link:/abs/path/to/dsh-job-progress   # the checkout from above

The bundle patch inserts one row (job-progress) into the profile. Then restart that profile — host plugin modules are cached in-process, so a running harness will not pick the row up.

link: is a live link: edits to the source folder take effect immediately (after a restart for host code, after a refresh for UI code), but the folder must not be moved afterwards. To copy the files instead, use file:/abs/path/to/dsh-job-progress — then later edits need a re-install.

From GitHub or npm

dsh plugin --profile <profile> add github:Rice00/dsh-job-progress
dsh plugin --profile <profile> add dsh-job-progress        # once published to npm

For an AI assistant (copy-paste)

Please install the DSH plugin dsh-job-progress for me:

1) Install it into the web profile, from GitHub:
     dsh plugin --profile web add github:Rice00/dsh-job-progress
   or from a local checkout (absolute path of the folder):
     dsh plugin --profile web add link:<absolute-path>
2) Restart that profile — host plugin modules are cached in-process, so the new row is
   only picked up on boot. (UI-only changes just need a browser refresh.)
3) Verify:
     node <absolute-path>/test/preflight-client.mjs      → must print "ALL PASS (12)"
     the host log must contain:  job-progress: mounted, progress root …
   On Windows the host log is under %APPDATA%\DSH Desktop\logs\host\.
   If DSH starts normally and no new errors appear in the renderer console, you are done.

Quick start

Nothing to configure — run something in the background and the ball appears:

node download.mjs https://example.com/model.safetensors    # run_in_background

To get a progress bar, have the producer report numbers (one file, any language):

import { track } from 'dsh-job-progress/progress';

const t = track({ label: 'model.safetensors', total: 66000000 });
t.update(bytesSoFar);        // speed + ETA are measured for you
t.phase('verifying');
t.finish('done');            // or t.finish('failed', 'sha256 mismatch')

Or straight from a shell, no import needed:

node <plugin>/lib/dsh-progress.mjs set --label model.safetensors --done 12 --total 100
node <plugin>/lib/dsh-progress.mjs done --key model.safetensors

How it works

producer (your script)          host plugin                     client plugin (browser)
  track({ label, total })  ──▶  reads <DSH_HOME>/job-progress/  ──▶  polls jobProgress/snapshot
  writes <key>.json             <DSH_SESSION_ID>/*.json              every 2 s and renders the
                                + registry snapshots                 ball, badge and panel

The ball's position and the per-session "already cleared" list live in localStorage.

The progress protocol

A producer writes one JSON file per task into the session's progress directory:

<DSH_HOME>/job-progress/<DSH_SESSION_ID>/<key>.json

Both environment values already exist in every agent shell call, so a producer never has to be told a path.

{
  "label": "anima_preview_5B.safetensors",
  "done": 4187599360,
  "total": 9972879360,
  "unit": "bytes",
  "speed": 13107200,
  "eta": 440,
  "phase": "download",
  "status": "running",
  "note": "",
  "jobId": "bash-3",
  "updatedAt": 1758000000000
}

Heartbeat. While status is running, refresh updatedAt at least every ~15 s. A live entry that stops refreshing is treated as gone, because a producer that stopped writing is indistinguishable from one that crashed. done / failed entries stay visible for two minutes.

Atomic writes. Write <file>.tmp, then rename over the target; a reader must never observe a half-written record.

CLI reference

Clearing

Clear finished deletes every finished progress file of this session; running entries are never touched.

Registry jobs cannot be deleted — they are read-only projections — so terminal job rows are recorded in a per-session ignore list and stop appearing. That key includes the job's startedAt, because job ids are <kind>-N counted per process and a restart would otherwise let a stale ignore entry hide a brand-new job.

The host refuses a session id containing a path separator or .., and requires the session to actually exist: the id doubles as a directory name, so this is a path-traversal fence, not a formality. If the host does not answer, the UI reports the failure and changes nothing — it never claims a clear that did not happen.

Compatibility

Verify the install

# 1) the client plugin: module contract, slot registration, one render pass
node test/preflight-client.mjs            # → ALL PASS (12)

# 2) the host plugin mounted (Windows Desktop app)
Select-String -Path "$env:APPDATA\DSH Desktop\logs\host\dsh-*.log" -Pattern 'job-progress'
#    → dsh-job-progress: mounted, progress root …\.dsh\job-progress

# 3) the row is in the profile
dsh --profile <profile> --dump-config | Select-String 'job-progress'

Then start a background job in any session and hover the ball.

Troubleshooting

border-radius: 50%;
corner-shape: round;   /* omit it and you get a squircle — which may well be what you want */

node test/preflight-client.mjs     # no install, no browser needed

cordis.patch.yml            bundle patch: inserts the `job-progress` row
package.json                manifest: bundle patch + web client plugin
lib/client.js               client plugin: ball, drag, panel, clear
lib/index.js                host plugin: registry snapshots + progress dir + jobProgress/clear
lib/dsh-progress.mjs        producer side: protocol, helper, CLI
test/preflight-client.mjs   12 checks for the client plugin
assets/                     logo and screenshot used by this README

Uninstall

dsh plugin --profile <profile> remove dsh-job-progress

Progress files written by producers stay under <DSH_HOME>/job-progress/ — delete them yourself if you no longer need them. The plugin never deletes anything outside that directory.

Roadmap

• Jobs owned by subagents (today a session sees its own owner's jobs only)
• Move the icon and any large assets to a host route instead of an inlined data URI
• Richer phases, so a producer can announce arbitrary stages with labels
• More translations of this README

Contributing

Issues and pull requests are welcome. Before opening a PR:

node test/preflight-client.mjs     # must print ALL PASS

Keep the client plugin dependency-free (React only) and run the preflight after any edit — it exists because client-side mistakes are otherwise invisible.

License

MIT