From 447d0bdd41322d11d6c160359ebc6d99748eec87 Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 12:35:44 +0800 Subject: [PATCH 1/8] docs(specs): re-baseline the wire and launch contracts to dsh-v0.2.2-rc.1 Restate both frozen specs from the T1 re-verification at dsh-v0.2.2-rc.1 (66491b05e3), keeping every earlier table and dated amendment as history. Wire spec: eight upstream request methods and six notifications, with the crate still sending exactly six and a session/query row marked NOT sent; the two new notification names and the subagent.started origin narrowing; fact corrections for the seven turn/end kinds, Python run() -> session/query, TypeScript finishReason, and the additive optional config fields; new section 7.7 for the session/prompt divergence; decided non-goals for session/query, approval/request, and user-question/ask; new re-baseline table and re-verification anchor. Launch spec: re-anchor section 2.1 to the shipped-profile registry and the first-use self-init, re-anchor initialize.cwd consumption, record the Node >=24.9.0 install bound, and add the new re-baseline table and re-verification anchor. --- .mstar/specs/dsh-runtime-launch-contract.md | 55 +++++++--- .mstar/specs/dsh-sdk-wire-parity-surface.md | 108 ++++++++++++++------ 2 files changed, 120 insertions(+), 43 deletions(-) diff --git a/.mstar/specs/dsh-runtime-launch-contract.md b/.mstar/specs/dsh-runtime-launch-contract.md index beda6bc..71a2286 100644 --- a/.mstar/specs/dsh-runtime-launch-contract.md +++ b/.mstar/specs/dsh-runtime-launch-contract.md @@ -17,6 +17,8 @@ The crate MUST therefore compose a **launch** (program + ordered argv + child en The crate MUST NOT bundle, download, ship, or vend a runtime. Runtime acquisition stays bring-your-own (§8). +**Runtime install prerequisite (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`).** The `dsh` CLI declares Node **`>=24.9.0`** (`apps/cli/package.json:178-179`; the root manifest states the same bound). Bring-your-own therefore means an operator-installed runtime on a Node release at or above that bound; the crate installs, downloads, and versions nothing itself, and a caller below the bound gets the CLI's own engine failure rather than a crate error. + --- ## 2. Launch grammar @@ -27,15 +29,15 @@ The crate MUST NOT bundle, download, ship, or vend a runtime. Runtime acquisitio | Fact | Upstream evidence | |---|---| -| The launcher's own flags are six at `dsh-v0.2.1-rc.1` (amended 2026-10-17; the frozen basis recorded four at `apps/cli/src/args.ts:137-140`): `--profile ` (`:168`), `--from-default-profile ` (`:169`), `--patch ` (repeatable, `:170`), `--dump-config` (`:171`), `--dump-config-schema` (`:172`), `--dump-default-config` (`:173`) | `apps/cli/src/args.ts:168-173` at `dsh-v0.2.1-rc.1` | -| `--profile` is **mandatory**; a bare `dsh` prints `error: --profile is required` and does not boot | `apps/cli/src/args.ts:144-146` | -| An empty profile name is rejected (`error: --profile needs a name`) | `apps/cli/src/args.ts:148-149` | -| The profile names a directory under `$DSH_HOME/profiles` | `apps/cli/src/args.ts:137` | -| `--patch` is an ordered overlay applied **after** the profile layer, in argv order | `apps/cli/src/args.ts:138,24-25`; collector `:58-61`; empty patch path rejected `:91` | -| Arguments after the launcher's own flags belong to the booted app | `apps/cli/src/args.ts:129-136` | -| Shipped profile names include `sdk` and `sdk-minimal` | `packages/boot/app-boot/src/profile.ts:110-133` | +| The launcher's own flags are six at `dsh-v0.2.2-rc.1` (amended 2026-11-06; re-baselined 2026-10-17 from the frozen basis, which recorded four at `apps/cli/src/args.ts:137-140`): `--profile ` (`:168`), `--from-default-profile ` (`:169`), `--patch ` (repeatable, `:170`), `--dump-config` (`:171`), `--dump-config-schema` (`:172`), `--dump-default-config` (`:173`) | `apps/cli/src/args.ts:168-173` at `dsh-v0.2.2-rc.1` | +| `--profile` is **mandatory**; a bare `dsh` prints `error: --profile is required` and does not boot | `apps/cli/src/args.ts:177-179` | +| An empty profile name is rejected (`error: --profile needs a name`) | `apps/cli/src/args.ts:182` | +| The profile names a directory under `$DSH_HOME/profiles` | `apps/cli/src/args.ts:168` (help text) + `packages/boot/app-boot/src/profile.ts:39,390` | +| `--patch` is an ordered overlay applied **after** the profile layer, in argv order | `apps/cli/src/args.ts:26,170`; collector `:76`; empty patch path rejected `:113` | +| Arguments after the launcher's own flags belong to the booted app | `apps/cli/src/args.ts:167` | +| Shipped profile names include `sdk` and `sdk-minimal` | `packages/util/official-bundles/src/bundles.ts:9-26` (`sdk` `:20-22`, `sdk-minimal` `:23-25`) at `dsh-v0.2.2-rc.1`; the frozen `packages/boot/app-boot/src/profile.ts:110-133` citation stays as the `c389f96bf3` record | -The six-flag enumeration is a text refresh, not a contract change (Task 1 report L-1b/D-2): §2.2's crate obligations are unchanged and stay normative — the crate emits only `--profile`/`--patch`, and every §2.2 obligation re-verified PASS at the tag. +The six-flag enumeration is a text refresh, not a contract change (Task 1 report L-1b/D-2): §2.2's crate obligations are unchanged and stay normative — the crate emits only `--profile`/`--patch`, and every §2.2 obligation re-verified PASS at the tag. Re-anchored 2026-11-06 at `dsh-v0.2.2-rc.1`: the flag set is unchanged; the shipped-profile registry moved out of `profile.ts` into `packages/util/official-bundles/src/bundles.ts:9-26` (Task 1 report L-7/F-5), and every other row's lines moved only. Both reference clients compose exactly this argv: @@ -75,7 +77,7 @@ Evidence: `packages/util/home-paths/src/index.ts:87-91` (function body: `configu 2. Blank or whitespace-only `DSH_HOME` MUST be treated as unset, exactly as upstream does (`packages/util/home-paths/src/index.ts:88-89`). 3. The resolved home MUST be an absolute path with `~` expanded before it is written to the child environment. 4. The resolved home MUST be **observable by the caller** through public API. The crate MUST NOT resolve a home silently and write into it without the caller being able to read the value it selected. (This is the AC4 observability requirement; the product rationale is that `~/.dsh` is a real user directory, not a sandbox.) -5. The crate SHOULD create the resolved home directory when it does not exist, so a fresh home boots (`dsh` self-initializes `$DSH_HOME/profiles/` on first use — `packages/boot/app-boot/src/profile.ts:100,109-133,187`). +5. The crate SHOULD create the resolved home directory when it does not exist, so a fresh home boots (`dsh` self-initializes `$DSH_HOME/profiles/` on first use — `packages/boot/app-boot/src/profile.ts:202` at `dsh-v0.2.2-rc.1`, with the template it writes coming from `packages/util/official-bundles/src/bundles.ts:9-26`; the frozen `profile.ts:100,109-133,187` citation stays as the `c389f96bf3` record). ### 3.3 Deliberate divergence from the Python SDK @@ -119,7 +121,7 @@ Evidence that no reader exists upstream at `c389f96bf3`: - The bundled default `cordis.yml` that consumed `DSH_CORDIS_CONFIG` was deleted (`python/sdk-runtime/README.md:15`; `be7b064504` deleted the file), and `DSH_CORDIS_CONFIG` survives at HEAD only inside Python's own removal assertions (`python/sdk/tests/test_client.py:876`). - Sessions now live under `$DSH_HOME/sessions` (`packages/bundle/base/cordis.patch.yml:110-113` — `root: !!js dshHomePath('sessions')`), not under `DSH_SESSION_ROOT`. -- The workspace cwd reaches the runtime through `initialize.cwd` (`packages/sdk/protocol/src/types.ts:18` at `dsh-v0.2.1-rc.1`, consumed at `packages/sdk/server/src/server.ts:164,182-183`), not through `DSH_CWD`. Citation corrected 2026-10-17 (Task 1 report L-6b/D-3): the shipped `sdk-app` profile no longer declares a `{{cwd}}` persona — `packages/bundle/sdk-app/cordis.patch.yml:5-6` at the tag carries `{{model}}` only. The normative no-reader claim of this section is unaffected, and its grep re-ran green at the tag. +- The workspace cwd reaches the runtime through `initialize.cwd` (`packages/sdk/protocol/src/types.ts:18`, consumed at `packages/sdk/server/src/server.ts:235,253,590` at `dsh-v0.2.2-rc.1` — resolve, store, then record on each created session's `meta.cwd`), not through `DSH_CWD`. Citation corrected 2026-10-17 (Task 1 report L-6b/D-3) and re-anchored 2026-11-06 (Task 1 report L-16): the shipped `sdk-app` profile no longer declares a `{{cwd}}` persona — `packages/bundle/sdk-app/cordis.patch.yml:5-6` at the tag carries `{{model}}` only. The normative no-reader claim of this section is unaffected, and its grep re-ran green at the tag. - Python removed all three writes in `56e038b2e3`; `python/sdk/tests/test_client.py:116-118` pins their absence. Writing them is not merely useless — it is misleading: the old code made `Config::session_root` *appear* to control where sessions land while they in fact landed under `~/.dsh`. @@ -176,19 +178,21 @@ The crate MUST expose exactly these `Config` fields (Python-parity naming, `pyth Removed relative to v0.1: `session_root`, `cordis_config`, `launch_args_override`, `runtime_bin` (renamed). See §5. +**Additive upstream options (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`), not crate fields.** Python's config gained two optional fields — `on_user_question` (`python/sdk/src/deepseek_harness/api.py:40`) and `approval_requests` (`:41`) — and the TypeScript mirror gained `onUserQuestion?` plus `reasoningEffort?`/`maxTokens?`/`approvalRequests?` (`packages/sdk/client/src/types.ts:26,66,68,70`). They gate surfaces this crate deliberately does not wrap (`dsh-sdk-wire-parity-surface.md` §6.1/§8), so the field set above stays exact and no crate obligation changes. + ### 6.2 `RunResult` field set -`RunResult` MUST have exactly the five Python fields (`python/sdk/src/deepseek_harness/api.py:40-46`): +`RunResult` MUST have exactly the five Python fields (`python/sdk/src/deepseek_harness/api.py:44-53` at `dsh-v0.2.2-rc.1`): | Field | Type | Meaning | |---|---|---| | `session_id` | `String` | the SDK session the turn ran on | -| `final_response` | `String` | last root `assistant/message` text (Python algorithm, `python/sdk/src/deepseek_harness/api.py:211-228`) | -| `finish_reason` | `Option` | last root `turn/end` `data.reason.kind` (Python algorithm, `python/sdk/src/deepseek_harness/api.py:231-248`) | +| `final_response` | `String` | last root `assistant/message` text (Python algorithm, `python/sdk/src/deepseek_harness/api.py:298-315`) | +| `finish_reason` | `Option` | last root `turn/end` `data.reason.kind` (Python algorithm, `python/sdk/src/deepseek_harness/api.py:318-334`) | | `events` | `Vec` | root-session `session.event` payloads, transport order | | `notifications` | `Vec` | every tree notification, transport order | -`session_root` MUST NOT be present. `finish_reason` MUST be present: Python has it and TypeScript does not (`packages/sdk/client/src/types.ts:69-79`), and the crate's alignment baseline is Python (root `AGENTS.md`-level direction; roadmap § Direction). +`session_root` MUST NOT be present. `finish_reason` MUST be present, and the crate's alignment baseline is Python (root `AGENTS.md`-level direction; roadmap § Direction). **Amended 2026-11-06 (`dsh-v0.2.2-rc.1`):** TypeScript's `RunResult` now also carries `finishReason: string | null` (`packages/sdk/client/src/types.ts:74-85`, field `:80`), so `finish_reason` is no longer a crate-vs-TypeScript difference; the rule is unchanged and still follows Python (`dsh-sdk-wire-parity-surface.md` §6.2, F-3). --- @@ -266,3 +270,26 @@ Re-baseline citations (upstream @ `dsh-v0.2.1-rc.1` = `1600d8a1e140dcde43a1a0941 | `python/sdk/src/deepseek_harness/api.py` | 71-74 | Re-verification rule: if upstream advances past `dsh-v0.2.1-rc.1`, re-run the greps in §2.1, §3.1, and §4.2 against the new ref before restating any line here. A moved line number is not a contract change; a changed rule is. Re-baselined 2026-10-17 at `dsh-v0.2.1-rc.1` (`1600d8a1e1`): every §10 inventory row re-ran at the tag (Task 1 report §B, rows L-1a…L-14 — 14 PASS / 2 FAIL; both FAILs are the stale citations corrected above by the §2.1 and §4.2 amendments, not changed crate obligations). Re-verified rows at the tag: `apps/cli/src/args.ts` (flags `:168-173`; `--profile` mandatory `:177-179`; empty name rejected `:182`; ordered repeatable `--patch` `:170,26-27`; empty patch path rejected `:113`; app-args tail `:167`); `apps/cli/package.json:2,14-16`; `packages/util/home-paths/src/index.ts` (`:12`, `:18` exact; default `:71`; `~` expansion `:87-89`; resolution body `:108-109`; documented precedence `:127-131`); `packages/boot/app-boot/src/profile.ts` (`sdk` `:190`; `sdk-minimal` `:192-193`; first-use self-init `:266`); `packages/bundle/base/cordis.patch.yml:141`; `packages/bundle/sdk-app/cordis.patch.yml:17-18`; `packages/bundle/sdk-minimal/cordis.patch.yml:11-12`; `packages/sdk/protocol/src/types.ts:16-33`; `packages/sdk/client/src/launch.ts` (`:143`, `:148` exact; `sdk` default `:132`; patch resolution `:136-140`); `packages/sdk/client/src/types.ts:24-80`; `python/sdk/src/deepseek_harness/api.py` (`:14-37`; `RunResult` `:41-45`; key injection `:71-74`); `python/sdk/src/deepseek_harness/client.py` (`:60` exact; `env.update` `:77-78`; home refusals `:497-504`; argv `:506-512`); `python/sdk/tests/test_client.py:30-32,210-212,983`; `python/sdk-runtime/README.md:41`; and the §4.2 no-reader grep (`DSH_CORDIS_CONFIG` / `DSH_SESSION_ROOT` / `DSH_CWD` — every hit inside Python's own removal assertions). No row stays un-rerun at the older ref: all rows re-ran; body sections not amended above keep their frozen `c389f96bf3` citations, whose rules re-verified with moved line numbers only. + +Re-baseline citations (upstream @ `dsh-v0.2.2-rc.1` = `66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db`, 2026-11-04; recorded 2026-11-06 — the §1/§2.1/§3.2.5/§4.2/§6.1/§6.2 amendments above; the frozen and `dsh-v0.2.1-rc.1` tables stay as history): + +| Path | Lines used | +|---|---| +| `apps/cli/src/args.ts` | 24-27, 76, 113, 155-167, 168-173, 177-179, 182 | +| `apps/cli/package.json` | 2, 4, 14-16, 178-179 | +| `packages/util/official-bundles/src/bundles.ts` | 9-26 | +| `packages/boot/app-boot/src/profile.ts` | 39, 171, 202, 390 | +| `packages/util/home-paths/src/index.ts` | 12, 18, 70-71, 87, 108-109, 127-136 | +| `packages/credentials/credentials-local/src/index.ts` | 1-14 (header comment; §4.1's precedence fact stays report-derived, not verified) | +| `packages/bundle/base/cordis.patch.yml` | 138-141, 497-505 | +| `packages/bundle/sdk-app/cordis.patch.yml` | 5-6, 17-19 | +| `packages/bundle/sdk-minimal/cordis.patch.yml` | 11-12 | +| `packages/sdk/server/src/server.ts` | 235, 253, 590 | +| `packages/sdk/protocol/src/types.ts` | 18-33 | +| `packages/sdk/client/src/types.ts` | 24-55, 58-71, 74-85 | +| `packages/sdk/client/src/launch.ts` | 132, 136-140, 143, 148 | +| `python/sdk/src/deepseek_harness/api.py` | 14-41, 44-53, 125-127, 298-315, 318-334 | +| `python/sdk/src/deepseek_harness/client.py` | 87, 180-199, 601-616 | +| `python/sdk/tests/test_client.py` | 30-32, 211-213, 968, 990, 994 | + +Re-verification rule (re-anchored 2026-11-06): if upstream advances past `dsh-v0.2.2-rc.1`, re-run the greps in §2.1, §3.1, §4.1, §4.2, and §6 against the new ref before restating any line here. A moved line number is not a contract change; a changed rule is. Re-baselined 2026-11-06 at `dsh-v0.2.2-rc.1` (`66491b05e3`): **22 launch rows — 20 PASS / 2 FAIL (moved)** (Task 1 report §2), both failures being citation moves already corrected above — the shipped-profile registry (L-7/F-5) and the `initialize.cwd` consumption (L-16) — not changed crate obligations. Re-verified rows at the tag: `apps/cli/src/args.ts` (flags `:168-173`; `--profile` mandatory `:177-179`; empty name rejected `:182`; ordered repeatable `--patch` `:26,76,170`; empty patch path rejected `:113`; app-args tail `:167`); `apps/cli/package.json:2,4,14-16` with engines `>=24.9.0` at `:178-179`; `packages/util/official-bundles/src/bundles.ts:9-26`; `packages/boot/app-boot/src/profile.ts` (`PROFILES_DIR` `:39`, first-use self-init `:202`, `profilesDir` `:390`); `packages/util/home-paths/src/index.ts` (`:12` and `:18` exact; default `:70-71`; `~` expansion `:87`; resolution body `:108-109`; documented precedence `:127-136`); `packages/bundle/base/cordis.patch.yml` (`sessions` root `:138-141`; executor rows `:497-505`); `packages/bundle/sdk-app/cordis.patch.yml:5-6,17-19`; `packages/bundle/sdk-minimal/cordis.patch.yml:11-12`; `packages/sdk/server/src/server.ts:235,253,590`; `python/sdk/src/deepseek_harness/client.py:87,601-616`; `python/sdk/tests/test_client.py:30-32,211-213,968,990,994`; and the §4.2 no-reader grep (every hit inside Python's own removal assertions). Body sections not amended above keep their frozen `c389f96bf3` citations, whose rules re-verified with moved line numbers only. diff --git a/.mstar/specs/dsh-sdk-wire-parity-surface.md b/.mstar/specs/dsh-sdk-wire-parity-surface.md index 0df6db2..a9aaa95 100644 --- a/.mstar/specs/dsh-sdk-wire-parity-surface.md +++ b/.mstar/specs/dsh-sdk-wire-parity-surface.md @@ -14,6 +14,8 @@ This spec is cross-iteration authority. It states the target surface, not a stop **Amended 2026-10-17 (re-verified at `dsh-v0.2.1-rc.1`).** The SDK runtime speaks **newline-delimited JSON-RPC 2.0 over stdio** with **seven request methods** — `initialize`, `session/prompt`, `session/resume`, `session/wait`, `session/working-directory/get`, `session/working-directory/set`, `shutdown` (`packages/sdk/protocol/src/types.ts:145-153`) — and **four server-to-client notifications** (`:137-142`). The frozen basis (`c389f96bf3`) declared exactly three request methods (`packages/sdk/protocol/src/types.ts:106-119`); the four additions are recorded in §2 and §8. The crate sends exactly **six** — `initialize`, `session/prompt`, `session/resume`, `session/working-directory/get`, `session/working-directory/set`, `shutdown`. Upstream's `session/wait` is deliberately not wrapped, matching both reference SDKs, whose public surfaces expose only resume plus working-directory get/set (§8; Task 1 report D.1–D.3). The crate MUST mirror that set exactly: no additional method strings, no additional notification names, and no client-directed request handling exposed as public API. +**Amended 2026-11-06 (re-verified at `dsh-v0.2.2-rc.1` = `66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db`).** Upstream now declares **eight** request methods — the seven named above plus `session/query` (`packages/sdk/protocol/src/types.ts:210-219`; `session/query` at `:213`) — and **six** server-to-client notifications (`:193-207`). The crate still sends exactly the same **six** method strings and still models exactly four notification names: the additions are recorded in §2, §3 and §8, and none of them changes a crate obligation. `session/query` is declared upstream and is deliberately **not** sent by this crate (§7.7, §8). + The crate MUST keep unknown-tolerant parsing: an unrecognized content-block `type` (or a known tag with a malformed body) MUST fall through to `ContentBlock::Unknown(Value)` rather than fail the parse (`src/protocol.rs:63-73`; the reference clients are untyped here). --- @@ -22,21 +24,23 @@ The crate MUST keep unknown-tolerant parsing: an unrecognized content-block `typ | Method | Params | Result | Upstream evidence | |---|---|---|---| -| `initialize` | `{cwd, provider, model, reasoningEffort?, maxTokens?}` | `{serverInfo: {name, version}}` | `packages/sdk/protocol/src/types.ts:16-33,115`; dispatch `packages/sdk/server/src/server.ts:135,249` | -| `session/prompt` | `{sessionId, contentBlocks}` | `{messageId}` | `packages/sdk/protocol/src/types.ts:36-59,116`; dispatch `packages/sdk/server/src/server.ts:176,250` | -| `session/resume` | `{sessionId}` | `{}` — `Record`; never parsed | at `dsh-v0.2.1-rc.1`: `packages/sdk/protocol/src/types.ts:62-65,148`; dispatch `packages/sdk/server/src/server.ts:222-231,349-355`; wrappers — Python `resume_session` (`python/sdk/src/deepseek_harness/api.py:124-131`, `client.py:191-196`), TS `resumeSession` (`packages/sdk/client/src/api.ts:113`, `client.ts:305`) | -| `session/working-directory/get` | `{sessionId}` | `{cwd}` | at `dsh-v0.2.1-rc.1`: `packages/sdk/protocol/src/types.ts:74-77,150`; dispatch `packages/sdk/server/src/server.ts:270-273,361-367`; wrappers — Python `get_working_directory` (`python/sdk/src/deepseek_harness/api.py:148-151`, `client.py:199-205`), TS `getWorkingDirectory` (`packages/sdk/client/src/api.ts:185`, `client.ts:314`) | -| `session/working-directory/set` | `{sessionId, path}` | `{cwd}` | at `dsh-v0.2.1-rc.1`: `packages/sdk/protocol/src/types.ts:80-83,151`; dispatch `packages/sdk/server/src/server.ts:280-283,362-371`; wrappers — Python `set_working_directory` (`python/sdk/src/deepseek_harness/api.py:153-156`, `client.py:208-214`), TS `setWorkingDirectory` (`packages/sdk/client/src/api.ts:195`, `client.ts:324`) | -| `shutdown` | none (`params` omitted by both references) | `{}` | `packages/sdk/protocol/src/types.ts:118`; dispatch `packages/sdk/server/src/server.ts:206,252` | +| `initialize` | `{cwd, provider, model, approvalRequests?, reasoningEffort?, maxTokens?, capabilities?}` — only `cwd`, `provider`, `model` are required | `{serverInfo: {name, version}}` | at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:18-33,211`; dispatch/handler `packages/sdk/server/src/server.ts:223-263,500-501` | +| `session/prompt` | `{sessionId, contentBlocks}` | `{messageId}` | at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:71-96,212`; dispatch/handler `packages/sdk/server/src/server.ts:270-289,502-503` | +| `session/query` | `{sessionId, contentBlocks}` — the first text block may select a native `/` command | `{kind: "prompt", messageId}` or `{kind: "command", execution}` | **Declared upstream, NOT sent by this crate.** at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:99-113,213`; dispatch/handler `packages/sdk/server/src/server.ts:297-340,504-512`; divergences §7.7, non-goal §8 | +| `session/resume` | `{sessionId}` | `{}` — `Record`; never parsed | at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:119-122,214`; dispatch `packages/sdk/server/src/server.ts:513-519`; wrappers — Python `resume_session` (`python/sdk/src/deepseek_harness/api.py:179-186`, `client.py:220-226`), TS `resumeSession` (`packages/sdk/client/src/api.ts:115`, `client.ts:368-370`) | +| `session/working-directory/get` | `{sessionId}` | `{cwd}` | at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:131-134,216`; dispatch `packages/sdk/server/src/server.ts:525-532`; wrappers — Python `get_working_directory` (`python/sdk/src/deepseek_harness/api.py:204-207`, `client.py:243-250`), TS `getWorkingDirectory` (`packages/sdk/client/src/api.ts:236`, `client.ts:377-379`) | +| `session/working-directory/set` | `{sessionId, path}` | `{cwd}` | at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:137-146,217`; dispatch `packages/sdk/server/src/server.ts:525-534`; wrappers — Python `set_working_directory` (`python/sdk/src/deepseek_harness/api.py:209-212`, `client.py:252-259`), TS `setWorkingDirectory` (`packages/sdk/client/src/api.ts:246`, `client.ts:387-389`) | +| `shutdown` | none (`params` omitted by both references) | `{}` | at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:218`; dispatch/handler `packages/sdk/server/src/server.ts:446-449,536-537` | Normative rules: -1. The crate MUST send only these six method strings (amended 2026-10-17 at `dsh-v0.2.1-rc.1`; the frozen rule bound three). Upstream's seventh method, `session/wait`, MUST NOT be sent by this crate — it is deliberately unwrapped, matching both reference SDKs (§8). The method strings are wire constants, not an extension point. -2. `initialize` MUST be the first request on the transport, and `start()` MUST await its result before returning. `session/prompt` before a successful `initialize` is rejected by the runtime (`packages/sdk/server/src/server.ts:176-177` — `SDK server is not initialized`). -3. `session/prompt.contentBlocks` MUST be sent verbatim as the user message (`packages/sdk/protocol/src/types.ts:39-41`); the runtime does not re-normalize non-image blocks (`packages/sdk/server/src/server.ts:39-41`). -4. `shutdown` MUST be sent only by the close ladder. The runtime returns `{}` and the plugin then disposes the root and exits 0 (`packages/sdk/server/src/server.ts:206-237,252-253`). +1. The crate MUST send only these six method strings (amended 2026-10-17 at `dsh-v0.2.1-rc.1`; the frozen rule bound three). Upstream's `session/wait` MUST NOT be sent by this crate — it is deliberately unwrapped, matching both reference SDKs (§8). Amended 2026-11-06 at `dsh-v0.2.2-rc.1`: upstream now declares eight methods, the addition being `session/query`; it MUST NOT be sent by this crate either (§7.7, §8), so the sent set stays exactly these six. The method strings are wire constants, not an extension point. +2. `initialize` MUST be the first request on the transport, and `start()` MUST await its result before returning. `session/prompt` before a successful `initialize` is rejected by the runtime (`packages/sdk/server/src/server.ts:271` — `SDK server is not initialized`). +3. `session/prompt.contentBlocks` MUST be sent verbatim as the user message (`packages/sdk/protocol/src/types.ts:74-75`); the runtime does not re-normalize non-image blocks (`packages/sdk/server/src/server.ts:59-73`). +4. `shutdown` MUST be sent only by the close ladder. The runtime disposes server-owned agents and subscriptions to quiescence and returns `{}` (`packages/sdk/server/src/server.ts:440-449`); the plugin then exits 0. 5. Outgoing request ids SHOULD stay string UUIDs; incoming ids MUST accept both string and number, matching the reference transports. -6. `serverInfo.name` MUST equal `deepseek-harness-sdk-runtime` exactly; `serverInfo.version` is hard-coded `0.0.1` with **no version negotiation** (`packages/sdk/server/src/server.ts:168`). Strict name equality is a deliberate, documented divergence (§7.4). +6. `serverInfo.name` MUST equal `deepseek-harness-sdk-runtime` exactly; `serverInfo.version` is hard-coded `0.0.1` with **no version negotiation** (`packages/sdk/server/src/server.ts:262`). Strict name equality is a deliberate, documented divergence (§7.4). +7. **Documented runtime behavior — resumed-session model route (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`), not a crate obligation.** `session/resume` applies the initialized route to the restored session: the initialized `provider`/`model` replaces the restored session's stored model selection, and a stored `reasoningEffort` survives only when the previous provider and model both equal the initialized ones (`packages/sdk/server/src/server.ts:574-590`; replacement comment `:577`, effort fallback `:581-585`). The crate sends no model fields on resume, so nothing in its request changes; a consumer MUST NOT assume the stored route is kept. --- @@ -44,22 +48,28 @@ Normative rules: | Notification | Payload | Emission site | |---|---|---| -| `session.event` | `{sessionId, event}` — the full session-log event envelope | `packages/sdk/server/src/server.ts:95-98` | -| `session.status` | `{sessionId, status: "idle" \| "running"}` | `packages/sdk/server/src/server.ts:99-101` | -| `subagent.started` | `{parentSessionId, childSessionId}` | `packages/sdk/server/src/server.ts:102-110` | -| `subagent.finished` | `{provider, agentId, parentSessionId, childSessionId, status: "ok" \| "error", stopReason, lastAssistantMessage?}` | `packages/sdk/server/src/server.ts:111-127` | +| `session.event` | `{sessionId, event}` — the full session-log event envelope | `packages/sdk/server/src/server.ts:171-179` | +| `session.status` | `{sessionId, status: "idle" \| "running"}` | `packages/sdk/server/src/server.ts:185-187` | +| `subagent.started` | `{parentSessionId, childSessionId}` — emitted only when `session.header.origin === 'subagent'` and a parent exists | `packages/sdk/server/src/server.ts:188-196` | +| `subagent.finished` | `{provider, agentId, parentSessionId, childSessionId, status: "ok" \| "error", stopReason, lastAssistantMessage?}` | `packages/sdk/server/src/server.ts:197-215` | +| `user-question.cancelled` | `{requestId, sessionId}` — added upstream 2026-11-06; **not modelled by this crate** | `packages/sdk/server/src/user-questions.ts:41` | +| `session.query.completed` | `{sessionId, commandId, finalResponse, finishReason}` — added upstream 2026-11-06; **not consumed by this crate** (§7.7) | `packages/sdk/server/src/query-activity.ts:154` | + +The first four rows are the crate's whole model. The last two are upstream declarations recorded so the "must not invent others" rule reads as intentional; both reach the crate only as unknown notification methods on the opaque subscription path. -Type evidence: `packages/sdk/protocol/src/types.ts:64-104,106-112`; `session.status` vocabulary `packages/core/agent/src/runtime-types.ts:103-110`; `SubagentStopReason` five reasons `packages/subagent/subagent/src/types.ts:252-263`; `subagent.finished.status` is a deployment mapping, so `max-tokens` can map to `ok` (`packages/sdk/server/src/server.ts:65-68`). +Type evidence at `dsh-v0.2.2-rc.1`: `packages/sdk/protocol/src/types.ts:148-191` (the four payload interfaces), `:193-207` (the notification map, six members), `:52-57` (`SdkUserQuestionCancelled`); `session.status` vocabulary `packages/core/agent/src/runtime-types.ts:129-136`; `SubagentStopReason` five reasons `packages/subagent/subagent/src/types.ts:233-244`; `subagent.finished.status` is a deployment mapping (`packages/sdk/server/src/server.ts:86,208`), so `max-tokens` can map to `ok`. Normative rules: -1. The crate MUST model exactly these four names and MUST NOT invent others. +1. The crate MUST model exactly its four names (`session.event`, `session.status`, `subagent.started`, `subagent.finished`) and MUST NOT invent others. Amended 2026-11-06 at `dsh-v0.2.2-rc.1`: upstream declares **six** names, adding `user-question.cancelled` and `session.query.completed` (both recorded in the table above); the crate models neither, and both arrive only through its unknown-method path. 2. `session.event.event` MUST stay an untyped `Value` in the crate: the event vocabulary is merge-extensible, and session format v2 changed it (§5.2). Parsing it into a closed Rust enum would break on the next upstream addition. 3. `session.status` and `subagent.finished.status` / `stopReason` SHOULD stay strings rather than closed enums, matching both reference clients' unknown-value strategy. Their runtime vocabularies are documented here, not enforced at parse time. -4. `subagent.started` MUST be treated as the only source of client-side parent→child edges; the tree filter is derived from it (§4.3). +4. `subagent.started` MUST be treated as the only source of client-side parent→child edges; the tree filter is derived from it (§4.3). Amended 2026-11-06: the runtime emits it only for a session whose `session.header.origin === 'subagent'` with a known parent (`packages/sdk/server/src/server.ts:188-196` — the gate at `:190` precedes the notification at `:195`); an ordinary fork creates a child session but emits **no** edge, so the crate's tree is exactly what the runtime reports, never an inferred fork lineage. Re-verification record (2026-10-17): §3 was re-verified at `dsh-v0.2.1-rc.1` (Task 1 report W-3) — the four notifications, their payload shapes, and their emission sites hold with moved line numbers only (`packages/sdk/server/src/server.ts:103-147` at the tag). No §3 rule changed; nothing is restated here. +Re-verification record (2026-11-06, `dsh-v0.2.2-rc.1`): §3 re-ran green with two additions and one narrowing — the four pre-existing payloads are unchanged (`packages/sdk/protocol/src/types.ts:148-191`), the map grew to six names (`:193-207`), and `subagent.started` is now gated on the session origin (`packages/sdk/server/src/server.ts:188-196`). The crate's model and rules are unchanged; §4.4's tree filter is unaffected because the runtime's edge set only became more specific. + --- ## 4. Session-tree semantics @@ -146,38 +156,46 @@ Python `DeepSeekHarnessConfig` (`python/sdk/src/deepseek_harness/api.py:14-37`) Crate-only fields MUST NOT exist beyond `timeouts` (the close-ladder struct, a local composition of Python's single `shutdown_timeout_seconds`). Python-only fields MUST NOT be dropped silently: `next_request` / `respond` / `notify` are a **Python-only** low-level surface and stay a non-goal (the runtime sends no client-directed requests — §7.2). +**Additive upstream options (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`).** Python `DeepSeekHarnessConfig` gained `on_user_question: UserQuestionHandler | None = None` (`python/sdk/src/deepseek_harness/api.py:40`) and `approval_requests: bool = False` (`:41`); TypeScript's `HarnessClientOptions` mirror gained `onUserQuestion?` (`packages/sdk/client/src/types.ts:26`), and `DeepSeekHarnessOptions` gained `reasoningEffort?` / `maxTokens?` / `approvalRequests?` (`:66,68,70`). All are optional and additive, and each one gates a surface this crate deliberately does not wrap (§8). No crate obligation follows: the crate's `Config` field set stays exactly the list above, and the "no silent drop" rule still binds only the low-level Python-only methods. + ### 6.2 `RunResult` | Field | Python | TypeScript | Crate | |---|---|---|---| | `session_id` | yes | yes | yes | | `final_response` | yes | yes | yes | -| `finish_reason` | yes | **no** | yes — follows Python | +| `finish_reason` | yes | yes (`finishReason: string \| null`, added 2026-11-06) | yes — follows Python | | `events` | yes | yes | yes | | `notifications` | yes | yes | yes | | `session_root` | **no** (removed) | no | **MUST NOT** exist | -Evidence: `python/sdk/src/deepseek_harness/api.py:40-46`; `packages/sdk/client/src/types.ts:69-79`; upstream asserts the removal at `python/sdk/tests/test_client.py:880`. +Evidence at `dsh-v0.2.2-rc.1`: `python/sdk/src/deepseek_harness/api.py:44-53`; `packages/sdk/client/src/types.ts:74-85`; upstream asserts the removal at `python/sdk/tests/test_client.py:968,990,994`. Derivation algorithms MUST match Python exactly except where §7 records a divergence: -- `final_response` — reversed scan for the last root `assistant/message` whose `data` is an object and whose resolved `content` (`data.message.content` when `data.message` is an object, else `data.content`) is an array; a malformed last `assistant/message` (non-object `data` or non-array `content`) is skipped via `continue` and the scan falls back to the next earlier `assistant/message` (Python `continue` inside `reversed()`, `python/sdk/src/deepseek_harness/api.py:211-228`); a string `text` contributes its value while `null`, a missing `text`, or any other non-string `text` contributes `""` (Python coerces a *truthy* non-string `text` through `str()` instead — a recorded divergence, §7.6); `""` when no usable `assistant/message` exists. -- `finish_reason` — last root `turn/end`'s `data.reason.kind` inside the activity interval; no `turn/end` → `None`; a malformed last `turn/end` → protocol error with the exact message `turn/end event requires a string data.reason.kind`; malformedness is checked only on the last one (reversed scan) (`python/sdk/src/deepseek_harness/api.py:231-248`). -- The runtime's `turn/end` reason vocabulary is six kinds — `completed`, `aborted`, `blocked`, `error`, `max-tokens`, `interrupted` (`packages/core/session/src/types.ts:198-222`) — and MUST stay a string, not a closed enum. +- `final_response` — reversed scan for the last root `assistant/message` whose `data` is an object and whose resolved `content` (`data.message.content` when `data.message` is an object, else `data.content`) is an array; a malformed last `assistant/message` (non-object `data` or non-array `content`) is skipped via `continue` and the scan falls back to the next earlier `assistant/message` (Python `continue` inside `reversed()`, `python/sdk/src/deepseek_harness/api.py:298-315`); a string `text` contributes its value while `null`, a missing `text`, or any other non-string `text` contributes `""` (Python coerces a *truthy* non-string `text` through `str()` instead — a recorded divergence, §7.6); `""` when no usable `assistant/message` exists. +- `finish_reason` — last root `turn/end`'s `data.reason.kind` inside the activity interval; no `turn/end` → `None`; a malformed last `turn/end` → protocol error with the exact message `turn/end event requires a string data.reason.kind`; malformedness is checked only on the last one (reversed scan) (`python/sdk/src/deepseek_harness/api.py:318-334`). +- The runtime's `turn/end` reason vocabulary is **seven** kinds — `completed`, `aborted`, `blocked`, `error`, `max-tokens`, `interrupted`, `forked` (`packages/core/session/src/types.ts:206-235`, `forked` at `:234`; corrected 2026-11-06, F-1 below) — and MUST stay a string, not a closed enum. + +**Fact corrections (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`).** Three statements in this section were written from a smaller upstream surface. All three are corrections of documented facts, not of crate rules: + +- **F-1 — the `turn/end` vocabulary is seven kinds, not six.** `forked` (`packages/core/session/src/types.ts:234`) already existed at the `dsh-v0.2.1-rc.1` baseline (`types.ts:229` at that tag; introduced by `8696ec6cef`, 2026-09-17), so the 2026-10-17 re-verification missed it rather than upstream adding it in `dsh-v0.2.2-rc.1`. The crate's rule is exactly why the extra kind is harmless: `finish_reason` returns the raw string and never enumerates kinds. +- **F-2 — Python's `Session.run()` now routes through `session/query`.** `Session.run` calls the private `HarnessClient._query` (`python/sdk/src/deepseek_harness/api.py:237`), which posts `session/query` (`python/sdk/src/deepseek_harness/client.py:228-241`); `session_prompt` survives only as the low-level client method (`client.py:201-218`). `RunResult` itself is unchanged (five fields, `api.py:44-53`). This crate keeps `session/prompt` — a recorded divergence, §7.7. +- **F-3 — TypeScript's `RunResult` now carries `finishReason`.** `finishReason: string | null` (`packages/sdk/client/src/types.ts:74-85`, field at `:80`), with `finalResponse` documented as "final assistant text (empty when absent), native state-only result text, or a failure diagnostic" (`:77-78`). The crate keeps the five Python fields and still derives `finish_reason` itself because Python remains the alignment baseline (§6.2's crate column). ### 6.3 `reasoningEffort` — omit-when-unset (normative) 1. `Config::reasoning_effort: Option`; `InitializeParams.reasoning_effort: Option` serialized as the wire key `reasoningEffort`. 2. When unset (`None`) the key MUST be **omitted** from `params` entirely. When set, it MUST be sent as a non-empty string. -3. An empty or whitespace-only value MUST be treated as unset and dropped, never sent: the server rejects a non-string or empty `reasoningEffort` with `TypeError('initialize reasoningEffort must be a non-empty string')` (`packages/sdk/server/src/server.ts:136-138`). Python applies the same rule by only adding the key when the value is not `None` (`python/sdk/src/deepseek_harness/client.py:147-148`). -4. A set value is validated and applied by the server (`packages/sdk/server/src/server.ts:147-161`) and forwarded to every SDK-created agent (`packages/sdk/server/src/server.ts:285`). +3. An empty or whitespace-only value MUST be treated as unset and dropped, never sent: the server rejects a non-string or empty `reasoningEffort` with `TypeError('initialize reasoningEffort must be a non-empty string')` (`packages/sdk/server/src/server.ts:227-229` at `dsh-v0.2.2-rc.1`). Python applies the same rule by only adding the key when the value is not `None` (`python/sdk/src/deepseek_harness/client.py:174-175`). +4. A set value is validated and applied by the server (`packages/sdk/server/src/server.ts:238-252`) and forwarded to every SDK-created agent (`packages/sdk/server/src/server.ts:568-573`). ### 6.4 `initialize` bound (normative) -1. `Config::initialize_timeout` defaults to **30 s** (`python/sdk/src/deepseek_harness/api.py:33`). +1. `Config::initialize_timeout` defaults to **30 s** (`python/sdk/src/deepseek_harness/api.py:35` at `dsh-v0.2.2-rc.1`). 2. The bound MUST apply to the `initialize` handshake request only, not to the activity interval or to `session/prompt`. 3. `None` MUST mean **unbounded** and MUST remain expressible, so a caller can opt out deliberately. It is an explicit opt-out, not a legacy default and not a compatibility shim. -4. On expiry the crate MUST return its timeout error and MUST NOT leave the child running (`python/sdk/src/deepseek_harness/client.py:152-160` closes the client and appends the selected profile before raising). +4. On expiry the crate MUST return its timeout error and MUST NOT leave the child running (`python/sdk/src/deepseek_harness/client.py:180-199` at `dsh-v0.2.2-rc.1` closes the client and appends the selected profile before raising). TypeScript's default is 10 000 ms (`packages/sdk/client/src/launch.ts:12,151`; `packages/sdk/client/src/types.ts:44`). The crate follows **Python's 30 s**, consistent with the alignment baseline. @@ -207,6 +225,8 @@ Python's analogue is `on_notification: Callable[[Notification], None] | None` (` Re-verification record (2026-10-17): §6 was re-verified at `dsh-v0.2.1-rc.1` (Task 1 report W-5–W-8, W-18–W-19). Every parity verdict and derivation rule holds with moved line numbers only (Python `final_response` / `finish_reason` now at `python/sdk/src/deepseek_harness/api.py:230,250`). No §6 content is restated or changed. +Re-verification record (2026-11-06, `dsh-v0.2.2-rc.1`): §6 re-ran with four changed facts and no changed rule — F-1 (seven `turn/end` kinds), F-2 (Python `run()` → `session/query`), F-3 (TypeScript `finishReason`), and F-4 (additive optional config fields, §6.1). The derivation algorithms are unchanged at `python/sdk/src/deepseek_harness/api.py:298-315` (`final_response`) and `:318-334` (`finish_reason`), and the baseline `RunResult` still holds five fields at `:44-53`; the crate's field set and verdicts above are unchanged. + --- ## 7. Documented divergences @@ -243,18 +263,27 @@ Python appends `str(block.get("text") or "")` (`python/sdk/src/deepseek_harness/ Verdict: **keep the crate's rule**. Faithfully emulating `str()` for arbitrary JSON values would need a Python-`repr` formatter (bool → `True`, float `1.0` → `"1.0"`, dict → `{'a': 1}`, `inf`, …) to serve a path unreachable from a conformant runtime, which the crate's simplicity rules reject. The rustdoc on `RunResult::final_response` and `derive_final_response` states the real rule and points here; the `derive_final_response` unit table asserts both the shared-domain parity and these divergence rows. +### 7.7 `Session::run` stays on `session/prompt` + +`Session::run` MUST keep posting `session/prompt` (§2), so a leading `/` in run input is ordinary **prompt text**, never a native command. Both reference SDKs' *public* `run()` now route through the new `session/query` instead — Python calls the private `HarnessClient._query` (`python/sdk/src/deepseek_harness/api.py:215-237`, `client.py:228-241`), TypeScript reaches it through the internal `queryInput` helper (`packages/sdk/client/src/api.ts:260-265`, `client.ts:590-598`). The crate performs no command routing and does not need to: `prompt()` enqueues verbatim and contains no `/` branch (`packages/sdk/server/src/server.ts:270-289`); the branch exists only in `query()` (`:297-340`, at `:301`). + +The crate also MUST NOT consume `session.query.completed` (§3): it is an unknown notification name to this crate, delivered through the opaque subscription path, and run completion is still the root session's idle (§4.3). Consequence a consumer must know: on this crate `/plan`, `/review`, and any other native command are sent to the model as prompt text rather than executed by the runtime. Recorded 2026-11-06 at `dsh-v0.2.2-rc.1` from T1 facts F-2 and W-9 (Task 1 report §5, §6); the alternative is a new feature, not a parity fix, and is deferred in §8. + --- ## 8. Deferred and non-goal surface These are **out of scope** and MUST NOT be documented as delivered: -- Inline encoded-image prompt blocks (`SdkEncodedImageBlock`, `packages/sdk/protocol/src/types.ts:43-53`): needs a prompt-side type distinct from `ContentBlock::Image`; own plan. +- Inline encoded-image prompt blocks (`SdkEncodedImageBlock`, `packages/sdk/protocol/src/types.ts:78-90` at `dsh-v0.2.2-rc.1`): needs a prompt-side type distinct from `ContentBlock::Image`; own plan. - Python-only `next_request` / `respond` / `notify` (§7.2). - A Rust `expandAssistantStream` equivalent for v2 embedded streams (§5.3). - TypeScript-parity helpers (the crate has no TS parity contract). - Protocol version negotiation (`serverInfo.version` is hard-coded `0.0.1`). -- `session/wait` (recorded 2026-10-17 at `dsh-v0.2.1-rc.1`): upstream declares it (`packages/sdk/protocol/src/types.ts:68-71,149`; dispatch `packages/sdk/server/src/server.ts:240-257,356-360`), but **neither reference SDK's public surface wraps it** — Python and TypeScript each expose only resume plus working-directory get/set, with no wrapper anywhere in `python/sdk/src/deepseek_harness/**` or `packages/sdk/client/src/**` (Task 1 report D.1/D.2). Upstream's own `packages/subagent/subagent-dsh-sdk/src/run.ts:335` consumes the method internally through the raw `request()` escape hatch. Exposing it in this crate therefore takes a deliberate spec decision, never an accident. +- `session/wait` (recorded 2026-10-17 at `dsh-v0.2.1-rc.1`; re-anchored 2026-11-06 at `dsh-v0.2.2-rc.1`): upstream declares it (`packages/sdk/protocol/src/types.ts:125-128,215`; dispatch `packages/sdk/server/src/server.ts:520-524`), but **neither reference SDK's public surface wraps it** — Python and TypeScript each expose only resume plus working-directory get/set, with no wrapper anywhere in `python/sdk/src/deepseek_harness/**` or `packages/sdk/client/src/**` (Task 1 report D.1/D.2). Upstream's own `packages/subagent/subagent-dsh-sdk/src/run.ts:335` consumes the method internally through the raw `request()` escape hatch. Exposing it in this crate therefore takes a deliberate spec decision, never an accident. +- `session/query` (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`) — **decided non-goal, not a gap.** Upstream declares it (`packages/sdk/protocol/src/types.ts:99-113,213`; dispatch `packages/sdk/server/src/server.ts:504-512`), but no *public* reference surface exposes it: Python's only wrapper is the private `HarnessClient._query` (`python/sdk/src/deepseek_harness/client.py:228`), and TypeScript's `HarnessSession` offers only `getWorkingDirectory` / `setWorkingDirectory` / `run` (`packages/sdk/client/src/api.ts:236,246,260`), reaching `session/query` solely through the internal `queryInput` helper (`packages/sdk/client/src/client.ts:590-598`). No crate consumer has asked for slash-command routing, and `Session::run` deliberately keeps `session/prompt` (§7.7). Wrapping it would add a feature, not restore parity. +- `approval/request` (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`) — **decided non-goal, not a gap.** It is a server→client request the server only sends after the client opts in with `initialize.approvalRequests === true` (`packages/sdk/protocol/src/types.ts:239-242`, field `:22`; gate `packages/sdk/server/src/server.ts:130-144,258`). The crate never sends the field and auto-answers client-directed requests `-32601` (§7.2), so it cannot receive one; no public reference wrapper exists either. +- `user-question/ask` (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`) — **decided non-goal, not a gap.** Same opt-in shape: `initialize.capabilities.userQuestions === true` (`packages/sdk/protocol/src/types.ts:59-62`, field `:32`; gate `packages/sdk/server/src/server.ts:259`), with the paired cancellation notification at `packages/sdk/server/src/user-questions.ts:41`. No public reference wrapper, and no crate consumer for host-answered questions. --- @@ -316,3 +345,24 @@ Re-baseline citations (upstream @ `dsh-v0.2.1-rc.1` = `1600d8a1e140dcde43a1a0941 | `python/sdk/src/deepseek_harness/client.py` | 191-196, 199-205, 208-214 | Re-verification rule: if upstream advances past `dsh-v0.2.1-rc.1`, re-run the greps behind §2, §3, §5.1, §5.3, and §6.3 against the new ref before restating any line here. A moved line number is not a contract change; a changed rule is. Re-baselined 2026-10-17 at `dsh-v0.2.1-rc.1` (`1600d8a1e1`): all 25 wire §10 rows re-ran green (Task 1 report §A — moved line numbers only, no changed rule). Expected outputs at this ref: the request map at `packages/sdk/protocol/src/types.ts:145-153` with seven members, the four additions at `:148-151` (grep: `git grep -n "session/resume\|session/wait\|session/working-directory" dsh-v0.2.1-rc.1 -- packages/sdk/protocol/src/types.ts`); `serverInfo` still `{ name: 'deepseek-harness-sdk-runtime', version: '0.0.1' }` at `packages/sdk/server/src/server.ts:188`; `ContentBlockMap` at `packages/llm/llm/src/types.ts:137-144` with the seven members of §5.1.1 and `ImageBlock.offloaded?: true` at `:88`; no `tool-result` map member and no `ToolResultBlock` anywhere under `packages/llm`; tool results as message-level `role: 'tool'` at `packages/llm/llm/src/message.ts:299-305`; `SESSION_FORMAT_VERSION = 4` at `packages/core/session/src/types.ts:90`. The 2026-09-24 `dsh-v0.1.7-rc.1` expectations above remain history; the frozen `c389f96bf3` table remains the frozen-basis record. + +Re-baseline citations (upstream @ `dsh-v0.2.2-rc.1` = `66491b05e3f05ad35bcdd4f6cd7ed26041d9e3db`, 2026-11-04; recorded 2026-11-06 — the §1/§2/§3/§6/§7.7/§8 amendments above; every earlier table stays at its recorded ref, kept as history): + +| Path | Lines used | +|---|---| +| `packages/sdk/protocol/src/types.ts` | 18-33, 52-57, 59-62, 71-96, 78-90, 99-113, 119-122, 125-128, 131-146, 148-191, 193-207, 210-219, 239-242 | +| `packages/sdk/server/src/server.ts` | 59-73, 86, 130-144, 171-179, 185-187, 188-196, 197-215, 223-263, 270-289, 297-340, 440-449, 500-541, 568-590 | +| `packages/sdk/server/src/user-questions.ts` | 41 | +| `packages/sdk/server/src/query-activity.ts` | 154 | +| `packages/sdk/client/src/api.ts` | 115, 236, 246, 260-265 | +| `packages/sdk/client/src/client.ts` | 368-370, 377-379, 387-389, 590-598 | +| `packages/sdk/client/src/types.ts` | 24-55, 58-71, 74-85 | +| `packages/core/session/src/types.ts` | 90, 206-235 | +| `packages/core/agent/src/runtime-types.ts` | 129-136 | +| `packages/subagent/subagent/src/types.ts` | 233-244 | +| `packages/subagent/subagent-dsh-sdk/src/run.ts` | 335 | +| `python/sdk/src/deepseek_harness/api.py` | 14-41, 44-53, 179-186, 204-207, 209-212, 215-237, 298-315, 318-334 | +| `python/sdk/src/deepseek_harness/client.py` | 174-175, 180-199, 201-218, 220-226, 228-241, 243-250, 252-259 | +| `python/sdk/tests/test_client.py` | 968, 990, 994 | + +Re-verification rule (re-anchored 2026-11-06): if upstream advances past `dsh-v0.2.2-rc.1`, re-run the greps behind §2, §3, §5.1, §5.3, §6.1–§6.4, §7.7, and §8 against the new ref before restating any line here. A moved line number is not a contract change; a changed rule is. Re-baselined 2026-11-06 at `dsh-v0.2.2-rc.1` (`66491b05e3`): **29 wire rows — 27 PASS / 2 FAIL (fact)** (Task 1 report §1; Task 1 review confirms the counts), the two changed facts being the `turn/end` vocabulary and Python's `run()` routing, both restated above as F-1/F-2; the parallel launch inventory is **22 rows — 20 PASS / 2 FAIL (moved)**. One drift correction is recorded with them: `forked` was already present at the `dsh-v0.2.1-rc.1` baseline, so the 2026-10-17 re-verification missed a pre-existing kind rather than this tag adding one (F-1). Expected outputs at this ref: the request map at `packages/sdk/protocol/src/types.ts:210-219` with eight members and `session/query` at `:213`; the notification map at `:193-207` with six names; `serverInfo` still `{ name: 'deepseek-harness-sdk-runtime', version: '0.0.1' }` at `packages/sdk/server/src/server.ts:262`; `SESSION_FORMAT_VERSION = 4` at `packages/core/session/src/types.ts:90`; `ContentBlockMap` at `packages/llm/llm/src/types.ts:144-152` with the seven §5.1.1 members. From 0a17b164b5b7d43ba3f00e0ef7d8ce35b4c0d589 Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 12:42:41 +0800 Subject: [PATCH 2/8] docs: pin the keyless handshake to dsh 0.2.2-rc.1 and correct two wire facts CI: move the keyless-runtime-handshake pin to @deepseek-ai/dsh@0.2.2-rc.1 at all three textual sites (npm cache key, install command, fail-loud message) and rewrite the rationale for tag dsh-v0.2.2-rc.1 (66491b05e3, 2026-11-04): eight upstream request methods with the crate still sending six, six notifications with four modelled, session/query, approval/request, and user-question/ask deliberately unwrapped, and session.event.event still an untyped Value. The setup-node step notes the runtime's >=24.9.0 floor; no Node major bump was needed. Rustdoc: session/resume records that the initialized route replaces the restored session's stored model selection and that a stored reasoning effort survives only on a matching provider and model (server.ts:574-590 at the tag). The session-tree module and the subscription doc record that subagent.started is emitted only for subagent-origin sessions, so an ordinary fork adds no edge. README pair: replace the false "four server-to-client notifications" claim with the six-declared/four-modelled statement, name the two unmodelled notifications and the subagent-origin emission rule in both languages, and re-record both blob hashes in README.i18n.yaml. --- .github/workflows/ci.yml | 34 +++++++++++++++++++--------------- README.i18n.yaml | 4 ++-- README.md | 15 ++++++++++----- README.zh.md | 10 +++++++--- src/api.rs | 8 +++++++- src/client/core.rs | 6 +++++- src/client/session_tree.rs | 7 +++++++ 7 files changed, 57 insertions(+), 27 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 800bf82..1c750ad 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 @@ -83,6 +84,9 @@ jobs: # actions/setup-node@v7.0.0 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 @@ -92,11 +96,11 @@ 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/dsh@0.2.1-rc.1 + run: npm install -g @deepseek-ai/dsh@0.2.2-rc.1 - name: Resolve runtime binary # Fail loudly when the pinned runtime cannot be resolved: an empty @@ -105,7 +109,7 @@ jobs: run: | 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/dsh@0.2.1-rc.1" + echo "::error::dsh not found on PATH after npm install -g @deepseek-ai/dsh@0.2.2-rc.1" exit 1 fi echo "DSH_RUNTIME_BIN=$DSH_RUNTIME_BIN" >> "$GITHUB_ENV" diff --git a/README.i18n.yaml b/README.i18n.yaml index 377032d..cbe6fbf 100644 --- a/README.i18n.yaml +++ b/README.i18n.yaml @@ -3,5 +3,5 @@ # editing either side, bring the other along and re-record with: # git hash-object README.md # git hash-object README.zh.md -README.md: cc532f33d1caff65c752820118287907952a80d0 -README.zh.md: 9986e86080443cc592a704e05fb913ec39ad5088 +README.md: d623cfc2091ffc4f6fd16f5fbcb7942206691367 +README.zh.md: 03a4fe6a0c2942e446a7636201ab4ff04dc1cb61 diff --git a/README.md b/README.md index cc532f3..d623cfc 100644 --- a/README.md +++ b/README.md @@ -403,11 +403,16 @@ cannot strand the process), and resolves all pending requests with ### Notifications -The wire has four server-to-client notifications: `session.event`, -`session.status`, `subagent.started`, and `subagent.finished`. Tree -notifications travel a broadcast channel capped at 4096 with drop-oldest -semantics. If a high-volume tree floods more notifications than fit between -the SDK's reads, the dropped set can include the inbox receipt or the +Upstream declares six server-to-client notifications; this crate models four +of them: `session.event`, `session.status`, `subagent.started`, and +`subagent.finished`. The two it does not model — `user-question.cancelled` +and `session.query.completed` — reach it only as unknown method names on the +subscription path, forwarded as opaque payloads and never consumed. +`subagent.started` is emitted only for a session whose header `origin` is +`subagent`, so an ordinary fork adds no tree edge. Tree notifications travel +a broadcast channel capped at 4096 with drop-oldest semantics. If a +high-volume tree floods more notifications than fit between the SDK's reads, +the dropped set can include the inbox receipt or the root-idle notification a run depends on — rather than hang forever or return a silently truncated result, `Session::run` then **fails fast** with `Error::SdkProtocol`. A caller expecting very large bursts can bypass the cap diff --git a/README.zh.md b/README.zh.md index 9986e86..03a4fe6 100644 --- a/README.zh.md +++ b/README.zh.md @@ -357,9 +357,13 @@ SIGKILL → 等待。该阶梯幂等,是无条件清理(任何一层的失 ### 通知 -线上有四种服务器到客户端的通知:`session.event`、`session.status`、 -`subagent.started`、`subagent.finished`。树通知经由一条容量上限为 4096、 -drop-oldest 语义的广播通道。如果高流量会话树在 SDK 两次读取之间灌入超过 +线上有六种服务器到客户端的通知(上游声明);本 crate 建模其中四种: +`session.event`、`session.status`、`subagent.started`、`subagent.finished`。 +未建模的两种——`user-question.cancelled` 与 `session.query.completed`——只以 +未知方法名到达订阅路径,作为不透明载荷原样转发,本 crate 不消费。 +`subagent.started` 仅在会话头的 `origin` 为 `subagent` 时发出,因此普通 +fork 不会新增树边。树通知经由一条容量上限为 4096、drop-oldest 语义的广播 +通道。如果高流量会话树在 SDK 两次读取之间灌入超过 容量的通知,被丢弃集合可能包含某次 run 所依赖的收件回执或根 idle 通知——此时 `Session::run` 不会永远挂起或返回静默截断的结果,而是 **快速失败**,报 `Error::SdkProtocol`。预期超大突发量的调用方只能经由 diff --git a/src/api.rs b/src/api.rs index cb18a7c..2348141 100644 --- a/src/api.rs +++ b/src/api.rs @@ -169,11 +169,17 @@ impl DeepSeekHarness { /// Python `DeepSeekHarness.resume_session` parity. /// /// Upstream `session/resume` (`packages/sdk/server/src/server.ts` at - /// `dsh-v0.2.1-rc.1`) keeps the stored session identity and directory, + /// `dsh-v0.2.2-rc.1`) keeps the stored session identity and directory, /// repairs an interrupted final turn without sending input, and never /// creates a replacement; a missing, unreadable, or already-open/opening /// session is a JSON-RPC error (surfaced as [`Error::JsonRpc`]). /// + /// The initialized route then replaces the restored session's stored + /// model selection (`server.ts:574-590` at that tag): a stored reasoning + /// effort survives only when the previous provider and model both equal + /// the initialized ones, so a caller MUST NOT assume the stored route is + /// kept. + /// /// The runtime's empty ack carries nothing to parse, so a successful /// call yields a [`Session`] handle: no local id validation is applied /// (upstream rejects an empty id with a `TypeError`; this crate's diff --git a/src/client/core.rs b/src/client/core.rs index 7053b0c..81431cf 100644 --- a/src/client/core.rs +++ b/src/client/core.rs @@ -577,7 +577,11 @@ impl HarnessClient { /// (or their child session is the root), and session-scoped notifications /// pass when their `sessionId` is the root or a discovered descendant. /// The filter consults the live edge map, so a child started after the - /// subscription is matched from its first event onward. + /// subscription is matched from its first event onward. The runtime emits + /// `subagent.started` only for a session whose header `origin` is + /// `subagent` with a known parent + /// (`packages/sdk/server/src/server.ts:188-196` at `dsh-v0.2.2-rc.1`), so + /// an ordinary fork adds no edge and the tree never infers fork lineage. /// /// A subscription created after close/runtime death is born-failed: /// [`NotificationSubscription::recv`] rejects immediately with diff --git a/src/client/session_tree.rs b/src/client/session_tree.rs index 43856f2..0b8ddbd 100644 --- a/src/client/session_tree.rs +++ b/src/client/session_tree.rs @@ -1,5 +1,12 @@ //! The client-side session tree: the bounded `subagent.started` edge map and //! the tree-membership filter. +//! +//! `subagent.started` is the only source of parent→child edges, and the +//! runtime emits it only for a session whose header `origin` is `subagent` +//! with a known parent (`packages/sdk/server/src/server.ts:188-196` at +//! `dsh-v0.2.2-rc.1`). An ordinary fork creates a child session but emits no +//! edge, so this tree is exactly what the runtime reports, never an inferred +//! fork lineage. use std::collections::{HashMap, HashSet, VecDeque}; From d832ff9b01fe983fc0c89294ea291cde0054bb9b Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 12:46:31 +0800 Subject: [PATCH 3/8] docs(changes): record the 0.2.2-rc.1 realignment fragment --- .changes/unreleased/dsh-0.2.2-rc1-realignment.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .changes/unreleased/dsh-0.2.2-rc1-realignment.md diff --git a/.changes/unreleased/dsh-0.2.2-rc1-realignment.md b/.changes/unreleased/dsh-0.2.2-rc1-realignment.md new file mode 100644 index 0000000..d4c764a --- /dev/null +++ b/.changes/unreleased/dsh-0.2.2-rc1-realignment.md @@ -0,0 +1,7 @@ +--- +category: Changed +--- + +- The verified runtime baseline moved to `@deepseek-ai/dsh@0.2.2-rc.1`, 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. From 78a689f720935259c9da82ea274edb89799bf08a Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 12:57:56 +0800 Subject: [PATCH 4/8] docs: correct the finishReason fact and disclose the run routing divergence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix the six consolidated plan-QC findings on the docs surfaces only: - README pair: TypeScript's RunResult does carry the field, camelCase-named `finishReason: string | null`; the crate still follows Python's snake_case five-field set. - README pair + `Session::run` rustdoc: the run step sequence follows Python but the crate posts `session/prompt`, so a leading `/` is prompt text and `session.query.completed` is never consumed (wire spec §7.7). - README pair: bring-your-own runtime Node floor `>= 24.9.0` (npm CLI only; the wheel carries its own Node) with the upstream citation. - Wire §6.1/§7.2: the runtime emits client-directed requests only to a client that opts in at `initialize`; this crate never opts in and answers `-32601`. - Wire §6.1 and launch §6.1: split the additive-option paragraph so `reasoningEffort`/`maxTokens` are the already-supported `initialize` fields, and only the question/approval options gate the §8 non-goals. README.i18n.yaml re-recorded from `git hash-object README.md README.zh.md`. --- .mstar/specs/dsh-runtime-launch-contract.md | 2 +- .mstar/specs/dsh-sdk-wire-parity-surface.md | 6 ++--- README.i18n.yaml | 4 ++-- README.md | 25 ++++++++++++++++----- README.zh.md | 23 ++++++++++++++----- src/api.rs | 7 +++++- 6 files changed, 48 insertions(+), 19 deletions(-) diff --git a/.mstar/specs/dsh-runtime-launch-contract.md b/.mstar/specs/dsh-runtime-launch-contract.md index 71a2286..b0d750c 100644 --- a/.mstar/specs/dsh-runtime-launch-contract.md +++ b/.mstar/specs/dsh-runtime-launch-contract.md @@ -178,7 +178,7 @@ The crate MUST expose exactly these `Config` fields (Python-parity naming, `pyth Removed relative to v0.1: `session_root`, `cordis_config`, `launch_args_override`, `runtime_bin` (renamed). See §5. -**Additive upstream options (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`), not crate fields.** Python's config gained two optional fields — `on_user_question` (`python/sdk/src/deepseek_harness/api.py:40`) and `approval_requests` (`:41`) — and the TypeScript mirror gained `onUserQuestion?` plus `reasoningEffort?`/`maxTokens?`/`approvalRequests?` (`packages/sdk/client/src/types.ts:26,66,68,70`). They gate surfaces this crate deliberately does not wrap (`dsh-sdk-wire-parity-surface.md` §6.1/§8), so the field set above stays exact and no crate obligation changes. +**Additive upstream options (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`), not crate fields.** Python's config gained two optional fields — `on_user_question` (`python/sdk/src/deepseek_harness/api.py:40`) and `approval_requests` (`:41`) — and the TypeScript mirror gained `onUserQuestion?` plus `reasoningEffort?`/`maxTokens?`/`approvalRequests?` (`packages/sdk/client/src/types.ts:26,66,68,70`). `on_user_question`/`onUserQuestion` and `approval_requests`/`approvalRequests` gate surfaces this crate deliberately does not wrap (`dsh-sdk-wire-parity-surface.md` §6.1/§8); `reasoningEffort`/`maxTokens` are already supported through the crate's own `initialize` fields (§6.1 above). Either way the field set above stays exact and no crate obligation changes. ### 6.2 `RunResult` field set diff --git a/.mstar/specs/dsh-sdk-wire-parity-surface.md b/.mstar/specs/dsh-sdk-wire-parity-surface.md index a9aaa95..a0b50ac 100644 --- a/.mstar/specs/dsh-sdk-wire-parity-surface.md +++ b/.mstar/specs/dsh-sdk-wire-parity-surface.md @@ -154,9 +154,9 @@ Python `DeepSeekHarnessConfig` (`python/sdk/src/deepseek_harness/api.py:14-37`) | `shutdown_timeout_seconds` | `timeouts` (close-ladder struct) | parity in behaviour; Rust splits the ladder into typed tiers | | `base_url`, `api_key` | same names | parity (injected as `DEEPSEEK_BASE_URL` / `DEEPSEEK_API_KEY`) | -Crate-only fields MUST NOT exist beyond `timeouts` (the close-ladder struct, a local composition of Python's single `shutdown_timeout_seconds`). Python-only fields MUST NOT be dropped silently: `next_request` / `respond` / `notify` are a **Python-only** low-level surface and stay a non-goal (the runtime sends no client-directed requests — §7.2). +Crate-only fields MUST NOT exist beyond `timeouts` (the close-ladder struct, a local composition of Python's single `shutdown_timeout_seconds`). Python-only fields MUST NOT be dropped silently: `next_request` / `respond` / `notify` are a **Python-only** low-level surface and stay a non-goal (the runtime sends client-directed requests only to a client that opts in at `initialize` — §7.2, §8 — and this crate never opts in, auto-answering them `-32601`). -**Additive upstream options (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`).** Python `DeepSeekHarnessConfig` gained `on_user_question: UserQuestionHandler | None = None` (`python/sdk/src/deepseek_harness/api.py:40`) and `approval_requests: bool = False` (`:41`); TypeScript's `HarnessClientOptions` mirror gained `onUserQuestion?` (`packages/sdk/client/src/types.ts:26`), and `DeepSeekHarnessOptions` gained `reasoningEffort?` / `maxTokens?` / `approvalRequests?` (`:66,68,70`). All are optional and additive, and each one gates a surface this crate deliberately does not wrap (§8). No crate obligation follows: the crate's `Config` field set stays exactly the list above, and the "no silent drop" rule still binds only the low-level Python-only methods. +**Additive upstream options (recorded 2026-11-06 at `dsh-v0.2.2-rc.1`).** Python `DeepSeekHarnessConfig` gained `on_user_question: UserQuestionHandler | None = None` (`python/sdk/src/deepseek_harness/api.py:40`) and `approval_requests: bool = False` (`:41`); TypeScript's `HarnessClientOptions` mirror gained `onUserQuestion?` (`packages/sdk/client/src/types.ts:26`), and `DeepSeekHarnessOptions` gained `reasoningEffort?` / `maxTokens?` / `approvalRequests?` (`:66,68,70`). All are optional and additive, but they split two ways. `on_user_question` / `onUserQuestion` and `approval_requests` / `approvalRequests` gate the §8 opt-in surfaces this crate deliberately does not wrap. `reasoningEffort` and `maxTokens` are **already supported** through the crate's own `initialize` fields — `Config::reasoning_effort` (omit-when-unset, §6.3) and `Config::max_tokens` (the `max_tokens` parity row above). No crate obligation follows either way: the crate's `Config` field set stays exactly the list above, and the "no silent drop" rule still binds only the low-level Python-only methods. ### 6.2 `RunResult` @@ -239,7 +239,7 @@ The crate resolves `~/.dsh` when no home is configured, where Python raises `Val ### 7.2 No client-directed request API -Python exposes `next_request` / `respond` / `respond_error` / `notify` (`python/sdk/src/deepseek_harness/client.py:214-260`); TypeScript exposes none (`packages/sdk/client/src/client.ts:265-268`). The crate follows TypeScript: client-directed requests are auto-answered `-32601` and are not public API (`src/client/read_loop.rs:134-149`). The runtime emits no client-directed requests (`packages/sdk/server/src/server.ts:246-257`), so this costs nothing. Non-goal, not a gap. +Python exposes `next_request` / `respond` / `respond_error` / `notify` (`python/sdk/src/deepseek_harness/client.py:214-260`); TypeScript exposes none (`packages/sdk/client/src/client.ts:265-268`). The crate follows TypeScript: client-directed requests are auto-answered `-32601` and are not public API (`src/client/read_loop.rs:134-149`). The runtime emits client-directed requests only to a client that opts in at `initialize` — `approval/request` needs `approvalRequests: true` and `user-question/ask` needs `capabilities.userQuestions: true` (`packages/sdk/server/src/server.ts:130-144,246-259`; §8). This crate sends neither opt-in and auto-answers `-32601`, so this costs nothing. Non-goal, not a gap. ### 7.3 Malformed-notification policy is stricter than both references diff --git a/README.i18n.yaml b/README.i18n.yaml index cbe6fbf..e0c861f 100644 --- a/README.i18n.yaml +++ b/README.i18n.yaml @@ -3,5 +3,5 @@ # editing either side, bring the other along and re-record with: # git hash-object README.md # git hash-object README.zh.md -README.md: d623cfc2091ffc4f6fd16f5fbcb7942206691367 -README.zh.md: 03a4fe6a0c2942e446a7636201ab4ff04dc1cb61 +README.md: 8568b7eed859c81feb4a9ad98b359e7f824ea024 +README.zh.md: a31ee95239a5bb3a4d6849643e423ed7089a4871 diff --git a/README.md b/README.md index d623cfc..8568b7e 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,11 @@ Two prerequisites before the first run: a DSH runtime (see (`DEEPSEEK_API_KEY` in the environment, or `Config::api_key` / `Config::base_url`). +A bring-your-own runtime is operator-installed: the npm-published CLI requires +**Node.js `>= 24.9.0`** (its own declaration, `apps/cli/package.json`), while +the platform wheel carries its own Node. The crate installs nothing — below +the floor the CLI reports its own engine failure, not a crate error. + ## Quickstart ```rust @@ -249,7 +254,11 @@ the spawned child behind an async mutex, sessions interleave at the ### `Session::run` — one activity interval -`run` implements the Python `Session.run` algorithm: +`run` implements the Python `Session.run` step sequence, with one deliberate +routing divergence: this crate posts `session/prompt`, while both reference +SDKs' public `run()` now route through `session/query` — so a leading `/` in +the input is ordinary prompt text, never a native command such as `/plan` or +`/review`, and `session.query.completed` is never consumed (spec §7.7). 1. **Subscribe to the session tree before** writing the prompt, so no notification for this turn can be missed. @@ -354,14 +363,16 @@ object verbatim. ### `RunResult` `RunResult` follows the **Python** SDK field set — exactly five fields, no -`session_root` (upstream removed it and asserts its absence). The TypeScript -SDK's `RunResult` lacks `finish_reason`; Rust follows Python: +`session_root` (upstream removed it and asserts its absence). TypeScript's +`RunResult` carries the same fields under camelCase names, including +`finishReason: string | null`; Rust follows Python's snake_case five-field +set: | Field | Python | TypeScript | Rust (this crate) | |---|---|---|---| | `session_id` / `sessionId` | yes | yes | `session_id: String` | | `final_response` / `finalResponse` | yes | yes | `final_response: String` | -| `finish_reason` | yes | no | `finish_reason: Option` | +| `finish_reason` / `finishReason` | yes | yes | `finish_reason: Option` | | `events` | yes (root session only) | yes | `events: Vec` | | `notifications` | yes (root + descendants, transport order) | yes | `notifications: Vec` | | `session_root` | no (removed) | no | **does not exist** | @@ -454,8 +465,10 @@ Each divergence below is deliberate and documented; a contributor must not 1. **`DSH_HOME` fallback** — the crate resolves `~/.dsh` where Python raises `ValueError` ([`DSH_HOME` resolution](#dsh_home-resolution)). 2. **No client-directed request API** — Python exposes `next_request` / - `respond` / `notify`; the crate exposes none (the runtime emits no - client-directed requests; they are auto-answered `-32601`). Non-goal, not + `respond` / `notify`; the crate exposes none and auto-answers every + client-directed request `-32601`. The runtime only emits such requests to + a client that opts in at `initialize` (`approvalRequests` / + `capabilities.userQuestions`), which this crate never does. Non-goal, not a gap. 3. **Stricter malformed-notification policy** — a `session.event` / `session.status` whose payload fails its shape check fails the run with diff --git a/README.zh.md b/README.zh.md index 03a4fe6..a31ee95 100644 --- a/README.zh.md +++ b/README.zh.md @@ -49,6 +49,10 @@ crate 处于预发布线时,裸的 `cargo add deepseek-harness-sdk` 可能不 [运行时获取](#运行时获取))与模型凭据(环境变量 `DEEPSEEK_API_KEY`,或 `Config::api_key` / `Config::base_url`)。 +自带运行时由操作者自行安装:npm 发布的 CLI 要求 **Node.js `>= 24.9.0`** +(其自身声明,`apps/cli/package.json`),平台 wheel 则自带 Node。crate 本身 +不安装任何东西——低于该下界时由 CLI 报告它自己的引擎错误,而非 crate 错误。 + ## 快速开始 ```rust @@ -225,7 +229,11 @@ harness 主目录遵循**运行时自身的优先级**,从高到低: ### `Session::run` —— 一次活动区间 -`run` 实现 Python `Session.run` 算法: +`run` 实现 Python `Session.run` 的步骤序列,但有一处刻意的路由分歧:crate +发送 `session/prompt`,而两个参考 SDK 的公开 `run()` 现已改走 +`session/query`——因此输入开头的 `/` 是普通 prompt 文本,永远不会被当作 +`/plan`、`/review` 之类的原生命令执行,`session.query.completed` 也从不被 +消费(规格 §7.7)。 1. **在写入 prompt 之前**订阅会话树,保证本轮的每条通知都不会漏掉。 2. 发送 `session/prompt`(受 `Config::request_timeout` 约束)。 @@ -312,14 +320,15 @@ run-semantics 测试套件作为逐字透传锁定。 ### `RunResult` `RunResult` 遵循 **Python** SDK 的字段集——恰好五个字段,**没有** -`session_root`(上游已移除并断言其不存在)。TypeScript SDK 的 `RunResult` -缺少 `finish_reason`;Rust 跟随 Python: +`session_root`(上游已移除并断言其不存在)。TypeScript 的 `RunResult` 以 +camelCase 名称携带同样的字段,包括 `finishReason: string | null`;Rust 跟随 +Python 的 snake_case 五字段集合: | 字段 | Python | TypeScript | Rust(本 crate) | |---|---|---|---| | `session_id` / `sessionId` | yes | yes | `session_id: String` | | `final_response` / `finalResponse` | yes | yes | `final_response: String` | -| `finish_reason` | yes | no | `finish_reason: Option` | +| `finish_reason` / `finishReason` | yes | yes | `finish_reason: Option` | | `events` | yes(仅根会话) | yes | `events: Vec` | | `notifications` | yes(根 + 子代,传输顺序) | yes | `notifications: Vec` | | `session_root` | no(已移除) | no | **不存在** | @@ -400,8 +409,10 @@ fork 不会新增树边。树通知经由一条容量上限为 4096、drop-oldes 1. **`DSH_HOME` 回退** —— Python 抛 `ValueError` 时,crate 解析 `~/.dsh` (见 [`DSH_HOME` 解析](#dsh_home-解析))。 2. **无客户端定向请求 API** —— Python 暴露 `next_request` / `respond` / - `notify`;crate 一个都不暴露(运行时不会发出客户端定向请求;此类请求 - 一律自动应答 `-32601`)。非目标,不是缺口。 + `notify`;crate 一个都不暴露,并把每个客户端定向请求一律自动应答 + `-32601`。运行时只会向在 `initialize` 中选择加入的客户端发出此类请求 + (`approvalRequests` / `capabilities.userQuestions`),而本 crate 从不 + 选择加入。非目标,不是缺口。 3. **更严格的畸形通知策略** —— 载荷不符合形状检查的 `session.event` / `session.status` 会使本次 run 以 `Error::SdkProtocol` 失败。Python 会 静默跳过畸形 event/status,只在最后一条 `turn/end` 畸形时 raise; diff --git a/src/api.rs b/src/api.rs index 2348141..7abbe94 100644 --- a/src/api.rs +++ b/src/api.rs @@ -214,7 +214,12 @@ pub struct Session<'a> { impl Session<'_> { /// Run one user turn and wait for the agent to go idle. /// - /// Python `Session.run` verbatim: + /// Parity scope: the step sequence below follows the Python SDK's run + /// algorithm, but it is **not** verbatim parity. This crate posts + /// `session/prompt`, while both reference SDKs' public `run()` now route + /// through `session/query` (spec §7.7). A leading `/` in the input is + /// therefore ordinary prompt text, never a native command, and + /// `session.query.completed` is never consumed. /// /// 1. Subscribe to the session tree **before** writing the prompt, so no /// notification for this turn can be missed. From c2a00d65312904a4526d9c92f3d5ed13a3b63728 Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 13:03:09 +0800 Subject: [PATCH 5/8] ci: pin the resolved dsh to the npm global bin dir (qc3 F-04) --- .github/workflows/ci.yml | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1c750ad..55d780c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -105,13 +105,25 @@ jobs: - 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 proves the resolved dsh is the one this job's `npm install -g` + # just put in the npm global bin dir, not a preinstalled binary that + # happens to come first on PATH (qc3 F-04); it deliberately avoids + # parsing `dsh --version` output. run: | + 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/dsh@0.2.2-rc.1" exit 1 fi + case "$DSH_RUNTIME_BIN" in + "$NPM_GLOBAL_BIN"/*) ;; + *) + echo "::error::$DSH_RUNTIME_BIN is not the dsh npm install -g just provided; expected under $NPM_GLOBAL_BIN" + exit 1 + ;; + esac echo "DSH_RUNTIME_BIN=$DSH_RUNTIME_BIN" >> "$GITHUB_ENV" - name: Setup Rust toolchain From f90f197fdc9a5bd4304c0256aba056332a98ff31 Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 13:06:34 +0800 Subject: [PATCH 6/8] docs(knowledge): record additive-wire/behavioral-parity and pin-guard lessons --- .../best-practices/dsh-upstream-drift-realignment.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md b/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md index 1994836..7542af5 100644 --- a/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md +++ b/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md @@ -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 @@ -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 prove the pinned install, not merely the binary.** `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 just wrote. Deriving that directory (`npm prefix -g`) avoids a second copy of the version literal and avoids depending on `dsh --version` output format. + ## 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. @@ -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. From 7a5e18979def6561e37a58a8edb76de41e74d717 Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 13:23:53 +0800 Subject: [PATCH 7/8] docs: state the CI path guard as a location check, not a version proof --- .github/workflows/ci.yml | 12 +++++++----- .../best-practices/dsh-upstream-drift-realignment.md | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 55d780c..05b424d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -106,10 +106,12 @@ jobs: # 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). The second - # guard proves the resolved dsh is the one this job's `npm install -g` - # just put in the npm global bin dir, not a preinstalled binary that - # happens to come first on PATH (qc3 F-04); it deliberately avoids - # parsing `dsh --version` output. + # 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: | NPM_GLOBAL_BIN="$(npm prefix -g)/bin" DSH_RUNTIME_BIN="$(command -v dsh)" @@ -120,7 +122,7 @@ jobs: case "$DSH_RUNTIME_BIN" in "$NPM_GLOBAL_BIN"/*) ;; *) - echo "::error::$DSH_RUNTIME_BIN is not the dsh npm install -g just provided; expected under $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 diff --git a/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md b/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md index 7542af5..d99f31c 100644 --- a/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md +++ b/.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md @@ -55,7 +55,7 @@ This document captures the reusable discipline only; the specs own the facts. 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 prove the pinned install, not merely the binary.** `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 just wrote. Deriving that directory (`npm prefix -g`) avoids a second copy of the version literal and avoids depending on `dsh --version` output format. +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. ## Why This Matters From d2e0dc12c35dbbf9d6491dce476bc7a7ba086ce2 Mon Sep 17 00:00:00 2001 From: Tang Bohao Date: Fri, 6 Nov 2026 14:10:28 +0800 Subject: [PATCH 8/8] docs: state the verified runtime versions as a matrix The READMEs named no runtime version at all, leaving readers to guess which @deepseek-ai/dsh releases the crate was checked against. Add one section, right after the Node-floor prerequisites, listing 0.2.1-rc.1..rc.5 and 0.2.2-rc.1 with the check each one passed: keyless handshake (crate boots the runtime, initialize completes, close reaps the child) plus a reading of the upstream SDK-facing surface at the release tag. Each row is a fact with its method; the six-method, unknown-tolerant wire contract explains why additive upstream changes pass through, and versions outside the table are marked unverified. Re-record README.i18n.yaml with the new blob hashes. --- README.i18n.yaml | 4 ++-- README.md | 25 +++++++++++++++++++++++++ README.zh.md | 23 +++++++++++++++++++++++ 3 files changed, 50 insertions(+), 2 deletions(-) diff --git a/README.i18n.yaml b/README.i18n.yaml index e0c861f..82ee95f 100644 --- a/README.i18n.yaml +++ b/README.i18n.yaml @@ -3,5 +3,5 @@ # editing either side, bring the other along and re-record with: # git hash-object README.md # git hash-object README.zh.md -README.md: 8568b7eed859c81feb4a9ad98b359e7f824ea024 -README.zh.md: a31ee95239a5bb3a4d6849643e423ed7089a4871 +README.md: bf927d60ba34bb1ca51b81b968ee261f5bfe0988 +README.zh.md: 660d2c8ddabf4c3cd9fff58905d4c5b596cf5b00 diff --git a/README.md b/README.md index 8568b7e..bf927d6 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,31 @@ A bring-your-own runtime is operator-installed: the npm-published CLI requires the platform wheel carries its own Node. The crate installs nothing — below the floor the CLI reports its own engine failure, not a crate error. +### Verified runtime versions + +Each release below was checked two ways: a **keyless handshake** — the crate +spawns the runtime from that install, `DeepSeekHarness::start` completes +`initialize`, and `close` reaps the child, with no API key and no live turn — +and a reading of the **upstream SDK-facing surface** at the release tag. + +| Runtime (`@deepseek-ai/dsh`) | Status | Verified by | +|---|---|---| +| `0.2.2-rc.1` | verified | CI keyless handshake; wire and launch contract re-verified at `dsh-v0.2.2-rc.1` | +| `0.2.1-rc.5` | verified | keyless handshake; SDK-surface diff at `dsh-v0.2.1-rc.5` | +| `0.2.1-rc.4` | verified | keyless handshake; SDK-surface diff at `dsh-v0.2.1-rc.4` | +| `0.2.1-rc.3` | verified | keyless handshake; SDK-surface diff at `dsh-v0.2.1-rc.3` | +| `0.2.1-rc.2` | verified | keyless handshake; SDK-surface diff at `dsh-v0.2.1-rc.2` | +| `0.2.1-rc.1` | verified | keyless handshake; wire and launch contract re-verified at `dsh-v0.2.1-rc.1` | + +The crate sends only six methods — `initialize`, `session/prompt`, +`session/resume`, `session/working-directory/get`, +`session/working-directory/set`, and `shutdown` — and parses what comes back +tolerantly, so an unknown field never fails a response: additive upstream +changes between these releases are expected to pass through unchanged. + +Releases outside this table are **unverified**. The pin in +`.github/workflows/ci.yml` names the version the handshake job exercises. + ## Quickstart ```rust diff --git a/README.zh.md b/README.zh.md index a31ee95..660d2c8 100644 --- a/README.zh.md +++ b/README.zh.md @@ -53,6 +53,29 @@ crate 处于预发布线时,裸的 `cargo add deepseek-harness-sdk` 可能不 (其自身声明,`apps/cli/package.json`),平台 wheel 则自带 Node。crate 本身 不安装任何东西——低于该下界时由 CLI 报告它自己的引擎错误,而非 crate 错误。 +### 已验证的运行时版本 + +下表中的每个版本都经过两项检查:**无密钥握手**——crate 从该安装启动运行时, +`DeepSeekHarness::start` 完成 `initialize`,`close` 回收子进程,不需要 API key, +也不跑真实轮次;以及在对应发布 tag 上**阅读上游面向 SDK 的表面**。 + +| 运行时(`@deepseek-ai/dsh`) | 状态 | 验证方式 | +|---|---|---| +| `0.2.2-rc.1` | 已验证 | CI 无密钥握手;在 `dsh-v0.2.2-rc.1` 重新核对线上协议与启动契约 | +| `0.2.1-rc.5` | 已验证 | 无密钥握手;`dsh-v0.2.1-rc.5` 的 SDK 表面差异审计 | +| `0.2.1-rc.4` | 已验证 | 无密钥握手;`dsh-v0.2.1-rc.4` 的 SDK 表面差异审计 | +| `0.2.1-rc.3` | 已验证 | 无密钥握手;`dsh-v0.2.1-rc.3` 的 SDK 表面差异审计 | +| `0.2.1-rc.2` | 已验证 | 无密钥握手;`dsh-v0.2.1-rc.2` 的 SDK 表面差异审计 | +| `0.2.1-rc.1` | 已验证 | 无密钥握手;在 `dsh-v0.2.1-rc.1` 重新核对线上协议与启动契约 | + +crate 只发送六个方法——`initialize`、`session/prompt`、`session/resume`、 +`session/working-directory/get`、`session/working-directory/set` 与 +`shutdown`——并且对返回内容宽容解析:未知字段不会让响应解析失败。因此这些版本 +之间的上游增量变化预期可以原样透传。 + +表中之外的版本**未经验证**。握手任务实际运行的版本由 +`.github/workflows/ci.yml` 中的固定值指明。 + ## 快速开始 ```rust