Fix DSH Python SDK startup: profile, plugin and patch

DeepSeek Harness Python SDK startup is fail-fast: a profile without a JSON-RPC server entry, an unresolved plugin, or an invalid patch stops startup, and none of them fall back to another combination. This is different from a model request that can retry. Configuration-layer failures must be fixed before the SDK can start.

DeepSeek Harness: Three failure classes

The same “SDK will not start” can point at three different layers. Compare:(source)

Read whether the error names the profile, a package, or a patch file before changing anything. Reinstalling the SDK is rarely the first correct move.

DeepSeek Harness: Fix a missing server entry

The SDK does not run on an arbitrary profile; it needs a JSON-RPC server entry. Fix it:(source)

1. Use a shipped profile — try profile="sdk-minimal" or profile="sdk" to prove the SDK itself works. Expected: a minimal task returns.
2. Inspect the custom profile — open $DSH_HOME/profiles/<name>/package.json and confirm the bundle list includes SDK-related bundles. Expected: it is not a copy of the web profile.
3. Add the server entry — insert @deepseek-ai/dsh-sdk-app or an equivalent JSON-RPC server entry. Expected: startup no longer reports a missing server.

If you only need isolation, create the profile with --from-default-profile from sdk-minimal instead of hand-writing an empty directory.

DeepSeek Harness: Fix an unresolved plugin

Resolution failure usually means “this profile does not have the package”, not “the package is broken”. Check:(source)

1. Confirm the profile — the SDK’s profile argument selects the directory. Expected: you are not looking in the web profile for a sdk-minimal plugin.
2. Check dependencies — dsh plugin --profile <name> list or inspect pnpm state. Expected: the package name matches the patch.
3. Check the patch reference — is the name an absolute path or a complete package name? Expected: no relative path points at the wrong directory.
4. Install the missing package — dsh plugin --profile <name> add <package>. Expected: resolution succeeds.

A package in another home does not come along when you copy a patch. Either install it in the new home or migrate the patch and its dependencies together.

DeepSeek Harness: Fix an invalid patch

DeepSeek Harness patches replace the target row’s entire config, not deep-merge it; that is the most common source of “invalid”. Check:(source)

1. Back up the patch — copy cordis.patch.yml and any file passed through patches. Expected: you can restore it.
2. Keep one patch — temporarily remove the constructor patches tuple and keep only the profile patch. Expected: rule out conflicts between files.
3. Restore in pieces — add back one insert or one config block at a time. Expected: identify the failing section.
4. Validate with dump — dsh --profile <name> --dump-config. Expected: dump succeeds before starting the SDK.

Common errors: inconsistent indentation, an insert target that does not exist, half a config object, or an array written as an object. A patch must satisfy the target schema, not just be short.

DeepSeek Harness: Use dump for binary search

Dump is the cheapest pre-start check: it composes configuration and resolves patches and plugins without starting the app. Three uses:(source)

1. Dump defaults — --dump-default-config. Expected: the template itself is valid.
2. Dump effective config — --dump-config with the same --patch. Expected: reproduce the failure in the configuration layer.
3. Dump schema — --dump-config-schema. Expected: confirm field names and types.

If dump succeeds but the SDK fails, return to the profile server entry. If dump fails, fix the file and target named on stderr.

DeepSeek Harness: Minimal profile structure

Confirm the profile is not just an empty directory. A startable SDK profile needs:(source)

• package.json — a dsh.profile manifest with a bundle list that references SDK bundles.
• cordis.patch.yml — may be empty, but must parse as YAML.
• Resolvable dependencies — every bundle package exists in the profile’s node_modules or the built-in install.

Check with:

dsh --profile sdk-minimal --dump-config >/tmp/sdk.yml

A successful dump means the configuration composes. If it fails, fix the patch or dependency before touching Python code.

Minimal reproduction experiments

Change one variable at a time instead of editing three layers at once. Three experiments:

1. Profile only — run the same Python code with sdk-minimal. Expected: success means the SDK and environment are fine; the custom profile is the problem.
2. Remove patches — keep the profile, drop the constructor patches tuple. Expected: startup means the per-run patch is invalid.
3. One plugin at a time — comment out all but one insert in the profile patch. Expected: narrow to the failing package or row.

Back up cordis.patch.yml and package.json before each experiment. Three runs usually identify the layer.

After fixing, check four things: the same profile starts three times, a minimal task returns text, dump provenance matches expectations, and session logs still go to the original home.

DeepSeek Harness FAQ

Can the SDK automatically fall back to sdk-minimal on startup failure? No. The official behavior is to fail on a missing server entry, an unresolved plugin, or an invalid patch. If you need a fallback, catch the exception in your application and switch profiles explicitly.

Is deleting the whole home the fastest recovery? It recovers, but loses sessions, plugins, and configuration. Back up first, rebuild only the profile, or validate the SDK in a new home.

The patch is correct, but another machine fails to start—why? Dependencies do not travel with a patch. Install the packages in the target profile on that machine.

The short version: SDK startup failures are profile, plugin, or patch—none self-heal. Use dump to find the layer, then fix that layer only.