Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changes/unreleased/dsh-0.2.2-rc1-realignment.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
category: Changed
---

- The verified runtime baseline moved to `@deepseek-ai/[email protected]`, and both frozen contracts — the wire-parity surface and the launch contract — were re-baselined against it. The wire delta is additive: upstream now declares eight request methods while this crate still sends the same six, and `session/query`, `approval/request`, and `user-question/ask` stay deliberately unwrapped, so a leading `/` in run input is still sent to the model as prompt text rather than executed as a native command.
- Two documented facts were corrected, with no public-API change: upstream declares six server-to-client notifications while the crate still models four, `subagent.started` is emitted only for subagent-origin sessions (an ordinary fork therefore adds no tree edge), and a resumed session takes the initialized provider/model route instead of its stored selection, where a stored reasoning effort survives only when both match. The two added notification names reach the crate only through its unknown-method path.
- The runtime's install floor is documented as Node `>= 24.9.0`. The crate still installs, downloads, and versions nothing, so a caller below that bound sees the runtime's own engine failure rather than a crate error.
50 changes: 34 additions & 16 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -59,18 +59,19 @@ jobs:
# gate is a PM decision, not a workflow change).
#
# Pin rationale: the SDK launch/wire contract was re-verified at
# deepseek-harness `dsh-v0.2.1-rc.1` (`1600d8a1`, 2026-10-16) by re-running
# the `.mstar/specs/` §10 re-verification inventories (report + review:
# `.mstar/sdd/12-dsh-0.2.1-rc1-adaptation/task-1-report.md` and
# `task-1-review.md`). The wire core holds across the range: `initialize` /
# `session/prompt` / `shutdown` and all four notifications keep their
# shapes, and the request map grew only additively — the crate wraps just
# the three both reference SDKs expose (`session/resume`,
# `session/working-directory/get|set`). `session.event.event` stays an
# untyped `Value` (wire spec §3.2), so the crate imposes no parser on the
# upstream event vocabulary and an added event kind cannot break parsing.
# Exact pin, never a dist-tag: the handshake result is reproducible run
# to run.
# deepseek-harness `dsh-v0.2.2-rc.1` (`66491b05e3`, 2026-11-04) by re-running
# the `.mstar/specs/` re-verification inventories (report + review:
# `.mstar/sdd/13-dsh-0.2.2-rc1-adaptation/task-1-report.md` and
# `task-1-review.md`). The delta is additive only: upstream now declares
# eight request methods while this crate still sends six, and six
# server-to-client notifications while this crate still models four.
# `session/query`, `approval/request`, and `user-question/ask` stay
# deliberately unwrapped (wire spec §7.7, §8), so neither the sent method
# set nor the modelled notification set changes. `session.event.event` is
# still an untyped `Value` (wire spec §3.2), so the crate imposes no parser
# on the upstream event vocabulary and an added event kind cannot break
# parsing. Exact pin, never a dist-tag: the handshake result is reproducible
# run to run.
keyless-runtime-handshake:
name: keyless runtime handshake (pinned dsh)
runs-on: ubuntu-latest
Expand All @@ -83,6 +84,9 @@ jobs:
# actions/[email protected]
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
with:
# `24` resolves the newest v24.x release. The pinned runtime's
# apps/cli engines floor is `>=24.9.0`, which lives inside this same
# major, so the re-pin needed no Node major bump.
node-version: 24

- name: Cache npm
Expand All @@ -92,22 +96,36 @@ jobs:
path: ~/.npm
# keyed on the exact pin: the tarball for that version is immutable,
# so a hit is the full npm cache the pinned global install needs
key: ${{ runner.os }}-npm-dsh-cli-0.2.1-rc.1
key: ${{ runner.os }}-npm-dsh-cli-0.2.2-rc.1

- name: Install pinned dsh runtime
# exact pin (never a dist-tag); rationale in the job comment above
run: npm install -g @deepseek-ai/[email protected].1-rc.1
run: npm install -g @deepseek-ai/[email protected].2-rc.1

- name: Resolve runtime binary
# Fail loudly when the pinned runtime cannot be resolved: an empty
# DSH_RUNTIME_BIN would make test tiers skip and the job would go
# green without ever running the handshake (qc3 F-001).
# green without ever running the handshake (qc3 F-001). The second
# guard rejects a PATH-shadowed binary: the resolved path must lie in
# the npm global bin dir, so a preinstalled `dsh` earlier on PATH fails
# loudly instead of silently running the wrong runtime (qc3 F-04). It
# is a location check, not a version check — the exact-pin guarantee
# comes from the install step above on a clean runner; it deliberately
# avoids depending on `dsh --version` output format.
run: |
Comment thread
btspoony marked this conversation as resolved.
Resolved
NPM_GLOBAL_BIN="$(npm prefix -g)/bin"
DSH_RUNTIME_BIN="$(command -v dsh)"
if [ -z "$DSH_RUNTIME_BIN" ]; then
echo "::error::dsh not found on PATH after npm install -g @deepseek-ai/[email protected].1-rc.1"
echo "::error::dsh not found on PATH after npm install -g @deepseek-ai/[email protected].2-rc.1"
exit 1
fi
case "$DSH_RUNTIME_BIN" in
Comment thread
btspoony marked this conversation as resolved.
Resolved
"$NPM_GLOBAL_BIN"/*) ;;
*)
echo "::error::$DSH_RUNTIME_BIN is not under the npm global bin dir $NPM_GLOBAL_BIN; refusing a PATH-shadowed dsh"
exit 1
;;
esac
echo "DSH_RUNTIME_BIN=$DSH_RUNTIME_BIN" >> "$GITHUB_ENV"

- name: Setup Rust toolchain
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
module: deepseek-harness-sdk
date: 2026-09-08
last_updated: 2026-11-06
problem_type: best_practice
category: best-practices
severity: high
Expand Down Expand Up @@ -52,6 +53,10 @@ This document captures the reusable discipline only; the specs own the facts.

9. **Upstream drift is not only removal.** Re-alignment work has two shapes: a contract upstream replaced (the v0.1 launch break), where the crate must follow; and capability upstream added, where the crate must decide what to expose. The first is a migration, the second is a parity decision — and the second needs the reference-client comparison in guidance 7 before any surface is committed to.

10. **An additive wire map does not mean unchanged reference behavior.** A release can keep every existing method and parameter, add one new method, and still change what a reference SDK's public entry point does: `Session.run()` moving from `session/prompt` to a newly added `session/query` that also interprets a leading `/` as a native command. Compatibility review therefore has two separate questions — does the crate's sent surface still exist unchanged (wire), and does the crate's documented behavior still match the reference clients (parity). A crate that deliberately keeps the old method is wire-compatible and needs no code change, but the divergence belongs in the spec (§7 divergence plus §8 non-goal) and in its consumer docs; otherwise the pin can move while the documentation silently claims the old parity.

11. **A pinned handshake guard should reject a PATH-shadowed binary, and say so honestly.** `command -v dsh` can resolve a preinstalled runtime from an earlier plan run, so an exact-pin CI job also asserts the resolved path lives under the npm global bin directory that the install step writes. Deriving that directory (`npm prefix -g`) avoids a second copy of the version literal and avoids depending on `dsh --version` output format. That assertion proves **location**, not identity: another binary in the same directory would still satisfy it. The pinned-version guarantee comes from the exact-pin install step running on a clean runner; when stronger proof is needed, verify the installed package version explicitly (for example from the package manager's own listing) rather than inferring it from the path.
Comment thread
btspoony marked this conversation as resolved.
Resolved

## Why This Matters

The v0.1 break was silent: the crate compiled, unit tests passed, and only a real runtime failed to boot, because the launch contract had drifted and nothing verified it. Wrapper-derived facts can be wrapper choices, so the runtime source is the only authority. A keyless, pinned handshake in CI turns the next upstream drift into a loud failure at merge time instead of a customer-reported boot failure, and the frozen specs give any re-alignment plan a fixed target.
Expand All @@ -60,6 +65,7 @@ The v0.1 break was silent: the crate compiled, unit tests passed, and only a rea

- Verifying or extending any contract this crate holds with the deepseek-harness runtime, wire or launch.
- Upstream advances past the pinned ref: re-run the specs' re-verification greps before restating any contract line (launch spec §10, wire spec §10).
- Answering "is this upstream release compatible?" — split the question into wire-surface stability and reference-behavior parity before reading the supplied upgrade report as the whole answer.
- Removing or renaming an env knob, config field, or bundled asset: the removal must carry a named replacement and a deprecation note (AC5 pattern; launch spec §5).
- Building the deferred `runtime-bin-delivery` (schemes B/C): the launch grammar locked in the spec is the model both schemes must compose, and `DSH_RUNTIME_BIN` must keep working (launch spec §8).
- Adding a CI job that exercises a real runtime: pin an exact published version, cache npm, and fail loudly when the binary cannot be resolved.
Expand Down
Loading
Loading