Upgrade DSH Python SDK: wheel and bundled dsh runtime

Upgrading the DeepSeek Harness Python SDK is not just swapping a Python dependency: the wheel also contains a matched native runtime and the dsh command. The SDK lazily starts a dsh --profile sdk-minimal process and reuses it until the context exits. So the upgrade sequence is install the target wheel, restart the host process, and verify the profile—not just step one.

DeepSeek Harness: Three things move together

One wheel upgrade changes the Python API, the bundled dsh runtime, and the bundled profile templates. What each affects:(source)

The official docs note that sdk-minimal does not contain dsh-base; it inserts a complete tree on an empty root. Tools added to the base profile later do not appear implicitly. If a tool disappears after an upgrade, check this boundary before assuming the install failed.

The wheel also packages the full web profile and frontend assets, but dsh web is a separate CLI app and cannot serve a Python SDK client. Keep “SDK bundled runtime” and “separately installed dsh” distinct.

DeepSeek Harness: What to record first

Record versions and a configuration baseline before upgrading, or you will have nothing to compare against. Three items:(source)

1. Python package version — python -m pip show deepseek-harness-sdk. Expected: note the exact version.
2. Bundled dsh version — dsh -V inside the same venv. Expected: confirm it comes from this venv, not another global install.
3. sdk-minimal config — dsh --profile sdk-minimal --dump-config if the profile exists. Expected: save the effective tree for a later diff.

If the profile is not initialized yet, run dsh --profile sdk-minimal --dump-default-config >/dev/null first so the profile files exist.

DeepSeek Harness: Upgrade steps

Install the target version in the same venv, restart the Python host, then verify with a minimal task. Steps:(source)

# 1. Activate the SDK virtualenv
. .venv/bin/activate

# 2. Install a pinned target version
python -m pip install --upgrade "deepseek-harness-sdk==<target>"

# 3. Check the bundled runtime
dsh -V

1. Pin the version — production should not float to “latest” during a routine upgrade. Expected: pip show reports the target version.
2. Restart the host process — close every process using DeepSeekHarness, then start again. Expected: the new runtime loads at startup.
3. Run a minimal task — use minimal.py or a read-only task. Expected: final_response returns normally.
4. Compare the profile — dump the effective tree and diff against the baseline. Expected: no field was silently removed or rewritten.

Step 2 is the most commonly skipped: a running process keeps the dsh process it started until the context exits, even after the wheel on disk changes.

DeepSeek Harness: Three upgrade strategies

In-place, side-by-side, and version pinning suit different risk levels. Compare:(source)

1. In-place venv — install the new version into the existing venv. Expected: least disk, but rollback means reinstalling the old version.
2. Side-by-side venv — create .venv-next, validate, then switch. Expected: rollback is a symlink or shell switch.
3. Pinned version + mirror — pin the SDK in requirements and install from an internal mirror. Expected: consistent across machines, insulated from upstream releases.

In every strategy, do not delete DSH_HOME; profiles, plugins, and sessions live there.

DeepSeek Harness: Rollback and verification commands

Write down the old version before upgrading so rollback is not a guess. A practical set:(source)

python -m pip show deepseek-harness-sdk | grep ^Version
dsh -V
# Roll back to the recorded version
python -m pip install "deepseek-harness-sdk==<old>"
dsh --profile sdk-minimal --dump-config > /tmp/sdk-config-after.yml

1. Record the old version — one line from pip show, one from dsh -V. Expected: a clear rollback target.
2. Reinstall the old version — pin it in the same venv. Expected: no fallback to another profile.
3. Restart and verify — rerun the minimal task and check final_response. Expected: the Python package and runtime match.
4. Compare config — dump the profile before and after. Expected: no field silently disappears.

Rollback only swaps the wheel; DSH_HOME stays. Sessions and plugins remain, but an older version may not understand a newer format, so follow the startup prompt if migration is required.

DeepSeek Harness: Common incompatibilities

Most post-upgrade failures are old patches no longer matching the new tree, not a broken install. Four cases:(source)

1. Patch points at a removed plugin — startup reports an unresolved package. Expected: delete the corresponding insert from cordis.patch.yml.
2. str_replace_editor patch stops working — the package name or mount method changed. Expected: regenerate editor.patch.yml for the new version.
3. sdk-minimal loses a tool — it does not contain dsh-base and does not inherit new base tools. Expected: add the tool with a patch if needed.
4. Session format migration prompt — the new version wants to migrate old JSONL. Expected: follow the prompt instead of deleting logs.

If startup fails outright, read whether the error is “missing server entry”, “unresolved plugin”, or “invalid patch”; none of them fall back to another combination.

DeepSeek Harness FAQ

Do I need to reinstall plugins after upgrading? Not necessarily. Plugins live in DSH_HOME and survive the wheel upgrade. If a plugin is incompatible with the new runtime, update or reinstall it according to its documentation.

Can a global dsh upgrade the SDK runtime? No. The SDK uses the runtime in its own wheel; a global dsh is another installation. The versions can differ, so record both to avoid checking the wrong one.

How do I roll back a failed upgrade? A side-by-side venv switches back directly; an in-place upgrade reinstalls the old wheel and restarts. DSH_HOME stays untouched.

The short version: treat an SDK upgrade as three things—wheel, runtime, profile—and restart the process; skipping the restart means you did not upgrade.