dsh-task-progress

Live progress for long-running tasks in DeepSeek Harness. A script reports
structured progress to a file; the Web UI shows it in a floating overlay and a
right-sidebar tab — no polling the agent, no waiting for the command to finish.

Version 0.3.0 · MIT · 中文 · Changelog

A real session, not a mock-up: the floating panel with one task reporting.
Click it to expand, or open the Task progress tab in the right sidebar.

Why this exists

DSH's pwsh/bash tools are not streaming: a foreground command's output
appears only when it finishes, and a background job's output lives behind the
model's job_output cursor. The session-header job list shows status, but not a
single line of output. So a ten-minute build is a black box to the human watching
the GUI.

This plugin gives long tasks a second, purpose-built channel that is theirs to
write and the human's to read.

Install

# from npm — one command, which installs the plugin and registers it in the profile
dsh plugin --profile web add dsh-task-progress

# from git, if you would rather install the repository itself
dsh plugin --profile web add github:chen8923/dsh-task-progress

# from a local checkout of this repository (see Development)
./tools/rebuild.ps1 -Profile web -Checkout

DSH mounts a profile bundle at startup, so restart DSH afterwards. The plugin
requires the Web profile (webServer, connection, shellEnv, plus the browser
half's slots, locale and the right sidebar); in a composition without them it
stays unloaded and changes nothing.

The repository and the npm package share one name, so dsh plugin add dsh-task-progress cannot resolve to somebody else's package — there is no
discovery-name/install-name gap to get wrong here. The git install is also one
command with nothing to allow: the built plugin is committed, so there is no
build step for pnpm to gate.

What installing actually runs

Nothing. The package declares no install, postinstall or prepare
script (npm run build is a development command and prepublishOnly only
fires when a maintainer publishes), so installing it executes no code on your
machine. The only files that run afterwards are lib/index.js in the DSH Host
process and lib/client.js in the browser — both are in the package's files
allow-list, and nothing else from this repository is installed.

Checking the published bytes yourself

You do not have to take the tarball on trust, and you should not need to. The
built lib/ is committed, so the published bundle can be rebuilt and compared:

npm pack dsh-task-progress              # or: curl -sL  -o p.tgz
tar -xzf dsh-task-progress-*.tgz
git clone https://github.com/chen8923/dsh-task-progress
cd dsh-task-progress && npm ci && npm run build
diff -r ../package/lib lib              # empty output = published bytes are this source

npm view dsh-task-progress dist.integrity is the registry's own hash of that
tarball, so the three-way comparison — registry hash, tarball contents, and this
source tree rebuilt locally — can all be done without trusting the maintainer.

Compatibility

Access and footprint

Installing a DSH plugin is not a sandboxed act — the plugin runs in the DSH
process, with that process's privileges. So here is the entire footprint, before
you install rather than after. This is the same table SECURITY.md
commits to, and a mismatch between it and the code is itself a security report.

Report a vulnerability through private vulnerability reporting
rather than a public issue.

Use

Inside a DSH shell call the plugin hands the script its directory:

# PowerShell — one append per event
$line = '{"v":1,"task":"build","state":"running","pct":42,"msg":"linking"}'
[System.IO.File]::AppendAllText(
(Join-Path $env:DSH_PROGRESS_DIR 'build.jsonl'), $line + "`n",
[System.Text.UTF8Encoding]::new($false))

# bash
printf '{"v":1,"task":"build","pct":42,"msg":"linking"}\n' >> "$DSH_PROGRESS_DIR/build.jsonl"

# Python (any language works — it is just a file)
import json, os
path = os.path.join(os.environ["DSH_PROGRESS_DIR"], "build.jsonl")
with open(path, "a", encoding="utf-8") as handle:
handle.write(json.dumps({"v": 1, "task": "build", "pct": 42, "msg": "linking"}) + "\n")

Or let the bundled helper do the quoting:

node "$DSH_PROGRESS_CLI" emit --task build --pct 42 --msg "linking"
node "$DSH_PROGRESS_CLI" done --task build --msg "shipped"
node "$DSH_PROGRESS_CLI" list          # print what the directory currently says

Try it with no setup at all:

pwsh ./examples/simulate.ps1 -Task demo -Steps 30 -DelayMs 500

Then open the Task progress tab in the right sidebar (or click the floating
pill once it appears).

Out of the box

Installing the plugin is enough for the agent to know the convention: the host
half contributes a short section to the system prompt, right where the
background-jobs guidance already is, so the model arranges progress reporting for
long commands on its own. There is nothing to configure and no AGENTS.md edit —
a feature that only works after you edit your own instructions is not one you can
install.

If you want it stronger, or you run a composition without that prompt seam, the
same instruction can live in your workspace AGENTS.md:

## Long-running tasks
For any command expected to run longer than ~30s, wrap it:

node "$env:DSH_PROGRESS_CLI" run --task --

That announces the task, follows the output, reports a percentage when it can read
one, and writes the ending from the exit code — no script to write, no redirection
or encoding to get right, and the task id ends up in the command line, which is
what ties the row to the job. Anything it cannot express can still report by hand:
one JSON line per event to `$DSH_PROGRESS_DIR/.jsonl` (see the
dsh-task-progress protocol), or
`node "$env:DSH_PROGRESS_CLI" emit --task  --pct N --msg "..."`.
Never read the progress file back — it is for the human.

When nothing appears

The panel draws two kinds of row.

A task a script reported arrives with its percentage, its counters and its
messages. A background job nobody reported for still shows up: DSH already pushes
a per-session job mirror for its own job list, and that mirror carries the command
line, how long the job has run and how it ended — so the plugin draws those rows
instead of showing nothing. What it will not do is invent detail: with no script
reporting there is no percentage, and the group's own note says so rather than
implying a bar that does not exist.

A job in a session you are not looking at stays invisible, because every surface
here is scoped to the session in view.

When the script is killed

A task's ending is normally written by the script, which is a problem the moment
something kills the script: job_kill terminates the process tree, and on
Windows that is taskkill, which runs no user code at all. A finally block
does not run, no handler runs, and the terminal line is not late — it is never
coming. Measured, not assumed: a background pwsh job with a finally that
appends to a file, killed with job_kill, wrote nothing after the kill.

So the ending does not depend on the script getting there. The Host half asks
DSH's job registry, whose record outlives the process and says how it ended, and
a task still saying running whose writing job has ended is published as
ended: killed reads as cancelled, failed as failed, a clean exit as done. The
row says so underneath — process was killed without reporting an ending — so an
inference is never passed off as a report, and the file itself is left exactly as
the producer wrote it.

Three things make that inference land, and they are worth knowing when you write
the script:

• Name the task after something in the command line. The row is matched to
  the job by the same label heuristic the unreported-job rows use, so
  --task sync-catalog inside the command line is recognised and a task named
  job1 in a command that never says job1 is not. The match is a whole word,
  which is the safe direction: rebuild does not name a task called build, so a
  job like that keeps its row and still reminds the model, where a substring match
  would have quietly counted it as reported.
• One writer per task id, or one id per stage. Three jobs appending to one
  file is not a task with three writers; it is a task whose ending two of them
  cannot write.
• Write the ending anyway. try/finally still covers exceptions, Ctrl+C, and
  the ordinary path, and the ending carries the real outcome and message. It is
  the only thing that covers a machine that dies, so it is worth having — it is
  simply not the only thing that ends a row.

Settings

Its knobs are editable where every plugin's are: the Plugins page, whose card
for this plugin is titled Task progress settings (the title is the label this
plugin registers, not a runtime namespace).

Saving writes this entry's own config into the profile's cordis.patch.yml;
pressing Reset (or emptying a field) removes the override, so the value falls
back to the plugin row's config and then to the schema default. Changes apply
live: a new scan interval re-arms the Host loops on their next tick, and the state
document's pollMs follows the value the browser should use.

dirName is deliberately absent from the panel — it is part of every path
already written, so it stays a composition-level setting on the plugin row.

Design

Three layers, each independently replaceable — the point is that neither a
producer nor the UI knows about the other, and neither knows about DSH internals.

Why the plugin does not read job output. ctx.jobs.read() consumes a
single-consumer cursor that belongs to the model's job_output tool; a browser
path reading it would silently steal bytes the model can then never see (DSH
pins that as a tested invariant). Progress here is therefore something the
script chooses to report, which is what makes this plugin safe to install
alongside anything else.

Snapshots are not output. The same registry also offers list(), whose
snapshots carry lifecycle facts only — id, kind, the command label, timestamps,
and how the job ended. Observing those is a different act from consuming the
output cursor, and it is what lets this plugin do three things it otherwise could
not: draw a row for a job nobody reported for, tell the model once, at the step
where it can still act, that a long job is running unseen, and settle a task
whose writer was killed before it could report an ending. Two consumers of the
same cursor would be a bug; two observers of a snapshot are not.

The registry is read, never written to. A settled ending changes what the
Host half publishes for a task and nothing else: the progress file keeps the
producer's last words, so a script that resumes and appends running again
supersedes the inference by itself, and deleting the file still deletes the task.
That is the whole reason the fix belongs in the reading rather than in a
correction written back to the file — a reader that rewrites its input cannot be
reasoned about.

Why polling instead of push. The data is a couple of kilobytes of JSON on
localhost, and a poll loop is the one design that cannot desynchronize: every
reader sees the same last-wins document, a missed tick costs one interval, and
there is no reconnect logic to get wrong. The interval comes from the Host
half's configuration.

Zero dependencies. The host half imports Node built-ins only; the browser
half bundles everything it owns and treats react as a platform external. That
extends to the settings schema: ctx.settings.register takes a schemastery
schema, and this plugin supplies a minimal compatible node — callable for
resolution, toJSON() in schemastery's reference-graph form, and walkable by the
settings redactor — instead of depending on a package that a profile install
cannot resolve. Its own browser card passes a decoder so it never has to
rehydrate a schema envelope at all.

What it deliberately does not do

• No history. Progress is live state, not a log; finished tasks age out.
• No cancel button. Stopping a job is the model's job_kill (a human-initiated
  interrupt needs a delivery-semantics decision this plugin does not own).
• No remote producers. Everything is local files in the workspace the session
  already writes to.
• No session lookup. Directories are learned from the shell calls that were
  handed them, plus configured roots — so the plugin never revives a session or
  reads a path the browser suggested.
• No cross-session reads. The state endpoint answers for exactly one session
  per request and puts no filesystem path on the wire. DSH's web login fences the
  whole instance rather than a session, so an endpoint that answered with
  everything the process knows would hand any authenticated caller every other
  session's task names and messages.

Development

npm test          # the whole suite, one process (works in restricted sandboxes)
npm run test:runner   # the same suite through node --test
npm run build         # requires tsdown

Source layout:

src/protocol.ts        the shared contract (pure, bundled into both halves)
src/host/              settings schema, store, shell-environment contributor, HTTP route, prompt section, entry
src/client/            polling store, formatting, settings form, React components, slots, styles
bin/dsh-progress.mjs   the dependency-free producer CLI
docs/PROTOCOL.md       the file contract and every configuration key
test/                  eighteen suites: protocol, job reconciliation, store,
formatting, host wiring, settings, settings form, prompt
section, reminder, session hook, client contract, client
store, CLI, wrapper, bundle, settings chrome, privacy,
release
tools/                 test entry and the build/pack/install script

lib/ is committed, and that is load-bearing. A git-hosted package that has
to build needs pnpm's build-script allowlist, whose key contains the exact commit
— so the install would take two steps and the second one would change on every
push. Shipping the build makes it one command, at the cost of discipline: after
any source change, run npm run build and commit lib/ in the same commit.
test/bundle.test.ts fails if the build is missing, is not a loader bundle, or no
longer carries what the sources define, and CI rebuilds lib/ and fails if the
committed bytes are not what the sources produce — that second check is the one a
forgotten rebuild trips. prepublishOnly still builds for npm publish. The suites
run on Node 22.18+ (they execute the TypeScript sources directly through type
stripping), while the plugin itself runs on Node 20+.

The build toolchain is pinned, and Dependabot is told to leave it alone. tsdown
is held at an exact version, because a bundler release changes the bytes of the
committed lib/ — the build that ships to users and to git installs. typescript is
a range (^5.9.0), since it is the bundler that decides those bytes; a bump of
either, and its rebuild, belong in one commit, and a bot can only open the first half,
so .github/dependabot.yml ignores both. That includes their security pull
requests: the option is documented as changing how Dependabot creates security updates
too. What remains is the Dependabot alert on the Security tab, and that is the
signal to act — bump, npm run build, confirm test/bundle.test.ts still passes, and
commit lib/ in the same commit.
Everything else (the workflows' actions, the lockfile) still gets its automatic
pull requests, which is where automation belongs.

screenshots.json is marketplace metadata, not a build input. Plugin
directories and dsh-market show the UI capture it names on a plugin's detail
page, and the convention is that the repository declares it rather than the
list: 1–8 paths relative to this file, none leaving the plugin directory. It
changes nothing at runtime, and the image it names is the one docs/ already
ships.

Releasing

npm test                                  # the whole suite, one process
git push && git tag v0.3.0 && git push origin v0.3.0   # CI publishes it, with provenance
npm publish                               # manual fallback: builds first, then publishes

test/release.test.ts fails if the version in package.json is not also stated
in both READMEs, in the changelog and in the CLI's own --version string, if a
documented example is missing from files, or if the repository links disagree
with the install instructions — so the version cannot drift between those five.

Tagging publishes through .github/workflows/publish.yml, once the trusted
publisher is configured on npm (repository chen8923/dsh-task-progress, workflow
publish.yml). That path holds no token, and it attaches a signed provenance
attestation tying the tarball to the commit. A hand-run npm publish keeps
working for as long as npm lets a 2FA-bypassing token publish — it retires that
in January 2027 — but it can never carry provenance.

License

MIT