@deepseek-ai/dsh-sdk-client 0.1.1-rc.2 → 0.1.2-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sdk/client/README.md
-README.md: b33457875f81d11d09bab2e5aa5ce730e233c78a
-README.zh.md: b89e56629fefe572394751bc1bee38aaba6f3300
+README.md: 176bddad402a21fd5cdc92aa0316a0716053dbfb
+README.zh.md: c650dd7fa9498c30c32bc66141ab023354dc70c7

package/README.md

@@ -1,49 +1,135 @@
+---
+description: "The TypeScript SDK client for callers that spawn a DeepSeek Harness runtime subprocess and drive agent turns over stdio JSON-RPC: the DeepSeekHarness run API and the lower-level HarnessClient."
+kind: "package-library"
+---
+
 # @deepseek-ai/dsh-sdk-client
 
 English | [中文](README.zh.md)
 
-The TypeScript client SDK for driving a DeepSeek Harness runtime as a subprocess over stdio JSON-RPC — the design twin of the [Python SDK](../../../python/README.md) (`deepseek-harness`), sharing the same runtime peer, protocol, and layering: `DeepSeekHarness` is the high-level owned-run API, `HarnessClient` the lower-level protocol client. The package root enumerates the consumer interface: the two client layers, caller-facing types, and `JsonRpcResponseError`; source modules, normalization helpers, and subscription-delivery machinery are not consumer imports. A pure library: it registers nothing on a Cordis context; the runtime process it spawns is a complete harness whose composition its own `cordis.yml` decides.
+## Summary
+
+`dsh-sdk-client` lets TypeScript programs drive a DeepSeek Harness runtime as a subprocess over stdio JSON-RPC. With `DeepSeekHarness` you can spawn the runtime, open sessions, send prompts, and collect the final response plus the event and notification streams; `HarnessClient` gives explicit control over the protocol layer. It is the design twin of the [Python SDK](../../../python/README.md), which shares the same runtime peer and protocol. The launch spec is explicit — callers may name the runtime executable via `dshBin`, omitted resolves the same-version `@deepseek-ai/dsh` package's bin, and the client constructs the arguments — so this client suits repository-adjacent TypeScript consumers such as the SDK subagent backend and automation that know which runtime they are launching. It is a pure library: it registers nothing on a Cordis context, and the runtime it spawns is a complete harness whose composition its own `cordis.yml` decides.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
 
-Unlike the Python SDK, the launch spec is fully explicit (`command`/`args`): this package is for repo-adjacent TypeScript consumers — including the [`dsh-subagent-dsh-sdk`](../../subagent/subagent-dsh-sdk/README.md) backend and automation — that know which runtime they are launching. Bundled-runtime resolution (finding a packaged executable) remains the Python distribution's concern.
+-----
 
-## DeepSeekHarness
+<a id="use-this-package"></a>
+## Use this package
+
+Use this client when TypeScript code must drive a complete Harness runtime from another process and you can name the runtime executable explicitly. The common path is minimal: construct a `DeepSeekHarness` with a launch spec, run prompts, and close it so the child process is always reaped.
+
+### Running agent turns with DeepSeekHarness
 
 ```ts
 import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 
 await using harness = new DeepSeekHarness({
-  launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
+  profile: 'sdk',
+  patches: ['./automation.cordis.yml'],
   provider: 'deepseek-official',
   model: 'deepseek-v4-flash',
+  reasoningEffort: ReasoningEffortId('max'),
   maxTokens: 49_152,
 })
 const result = await harness.run('say hi')
 console.log(result.finalResponse)
 ```
 
-The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; `close()` (or `await using`) is required so the child is always reaped. `start()` memoizes the `initialize` handshake (the workspace cwd — resolved absolute before it crosses the wire — plus the provider/model route and optional positive `maxTokens` output cap); a failed handshake reaps the runtime and swaps in a fresh client, so a later call retries with a new subprocess (until `close()`, which is terminal). The cap applies to each root-agent request and is inherited by in-process descendants; compaction plugins own their separate summary limits. `session(id?)` opens a named or fresh session handle.
+The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; call `close()` (or use `await using`) so the child is always reaped. `start()` memoizes the bounded `initialize` handshake, which carries the workspace cwd, provider/model route, optional adapter-owned `reasoningEffort`, and optional positive `maxTokens` output cap. The server validates that exact route before it accepts prompts; an omitted effort preserves the model's default. `initializeTimeoutMs` defaults to 10 seconds, and its diagnostic names the selected profile with the retained stderr tail. `run(input, { sessionId?, onNotification? })` accepts text or `SdkPromptContentBlock[]`; an inline raster block carries canonical base64 plus `mimeType` and becomes a durable attachment inside the runtime. The call owns one activity interval: it queues the prompt, waits until its message id appears in a durable inbox receipt, then collects through the next whole-agent `idle`. It returns `RunResult { sessionId, finalResponse, events, notifications }`, where `finalResponse` is the last committed root-session assistant text in that interval — not a response causally assigned to the prompt, because steering, injected context, and other queued work may contribute before idle. `session(id?)` opens a named or fresh session handle. When a failed handshake is cleaned up successfully, the instance installs a fresh client so a later call retries with a new process until terminal `close()`; if initialization and cleanup both fail, `start()` returns an ordered `AggregateError` and retains the failed client instead of spawning beside a process whose exit is unproved. `maxTokens` caps each root-agent request output and is inherited by in-process descendants; compaction plugins own their separate summary limits.
+
+### Lower-level control with HarnessClient
+
+`HarnessClient` is the protocol client under the run API: explicit `start()`, `initialize()`, `prompt()`, `request()`, and `close()`, plus notification subscriptions. `prompt()` returns the queued message id as soon as the runtime accepts it and never waits for agent activity. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK.
+
+The client exports typed errors for every failure mode: `JsonRpcResponseError` (a wire error response, code and data preserved), `RequestTimeoutError` (a configured bound elapsed), `SdkProtocolError` (a response outside the documented protocol), and `TransportClosedError` (the runtime is gone — the message carries the exit code and a bounded stderr tail). `close()` requests protocol `shutdown` (bounded by `shutdownTimeoutMs`, default 1000 ms), then walks a stdin-EOF → SIGTERM → SIGKILL ladder until the process has exited; it is idempotent, and a closed client refuses reuse. `HarnessClientOptions.env` replaces the child environment entirely when given (`undefined` inherits the parent's); callers own credential policy — `scrubbedParentEnv` from `dsh-subprocess` is the shared scrub base for isolation-minded launches.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design behind the client; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The client is two layers over one wire: `DeepSeekHarness` (owned runs) over `HarnessClient` (the protocol client), mirroring the Python SDK's layering. It runs outside any harness context, so it spawns the runtime directly rather than through the `dsh-subprocess` service — the seam's documented exception for SDK-managed transports — and its teardown ladder lives in this package. The runtime notifies for every session in its context; session-tree scoping is a client-side filter over `subagent.started` lineage edges.
 
-`run(input, { sessionId?, onNotification? })` owns one activity interval: it queues the prompt, waits until its `MessageId` appears in a durable `agent/inbox/spliced` receipt, then collects through the next whole-agent `idle`. It returns `RunResult { sessionId, finalResponse, events, notifications }`. `finalResponse` is the last committed root-session assistant text in that interval, not a response causally assigned to the prompt; steering, injected context, and other queued work may contribute before idle. `events` contains root-session events, while `notifications` also contains descendants discovered from `subagent.started`, all in wire order. The result carries no prompt-level status or turn reason. Transport loss, timeout, and protocol violations reject; model outcomes remain observable in the event stream without being attributed to one input.
+### Source map
 
-## HarnessClient
+| File | Role |
+|---|---|
+| [`src/api.ts`](src/api.ts) | `DeepSeekHarness` + `HarnessSession`: owned runs, receipt-to-idle collection, `finalResponse` |
+| [`src/client.ts`](src/client.ts) | `HarnessClient`: spawn, handshake, requests, subscription fan-out, typed errors |
+| [`src/dispose.ts`](src/dispose.ts) | Private teardown ladder: stdin EOF → SIGTERM → SIGKILL to actual exit |
+| [`src/types.ts`](src/types.ts) | Launch and timeout options, notification shapes, `RunResult` |
+| [`src/index.ts`](src/index.ts) | Consumer interface: the two client layers and caller-facing types |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant — the peer is a separate runtime process) |
 
-The protocol client under the owned-run API: explicit `start()`/`initialize()`/`prompt()`/`request()`/`close()`, plus notification subscriptions. `prompt()` returns the queued message id as soon as the runtime accepts it; it never waits for agent activity. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK. Error surfaces are typed and exported from this package: `JsonRpcResponseError` (wire error response, code/data preserved), `RequestTimeoutError` (a configured bound elapsed), `SdkProtocolError` (a response outside the documented protocol), `TransportClosedError` (the runtime is gone — message carries the exit code and a bounded stderr tail).
+### Owned activity flow
 
-`close()` requests protocol `shutdown` (bounded by `shutdownTimeoutMs`, default 1000 ms), then walks a stdin-EOF → SIGTERM → SIGKILL ladder (`disposeEofGraceMs` default 6000, `disposeGraceMs` default 3000) until the process has actually exited. The ladder is private to this client: it runs outside any harness context, so it cannot ride the [`dsh-subprocess`](../../subprocess/README.md) service — the seam's documented exception for SDK-managed transports. It is idempotent, and a closed client refuses reuse.
+A run subscribes to the session tree, queues the prompt, waits until the prompt's message id appears in a durable `agent/inbox/spliced` receipt, then collects notifications until the whole agent reports `idle`. `finalResponse` is derived from the last `assistant/message` in the collected events. Transport loss, timeout, and protocol violations reject the run; model outcomes remain observable in the event stream without being attributed to one input.
 
-`HarnessClientOptions.env` replaces the child environment entirely when given (`undefined` inherits the parent's); callers own credential policy — `scrubbedParentEnv` from `dsh-subprocess` is the shared scrub base for isolation-minded launches.
+### Errors and teardown
 
+Every failure mode maps to one exported error class — a wire error response, an elapsed request bound, a response outside the documented protocol, or a dead runtime — so callers branch on failure type; the four classes are exported from [src/index.ts](src/index.ts). Teardown is a private, idempotent escalation (stdin EOF → SIGTERM → SIGKILL) in [src/dispose.ts](src/dispose.ts) that ends only at actual process exit.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the client contract is not enough. They move from the wire protocol to the serving plugin and the applications that use this client.
+
+- [SDK wire protocol](../protocol/README.md) — the JSON-RPC methods and payload shapes this client speaks.
+- [JSON-RPC serving plugin](../server/README.md) — the runtime plugin that serves this client.
+- [Python SDK](../../../python/README.md) — the design twin that shares the same runtime peer and protocol.
+- [SDK subagent backend](../../subagent/subagent-dsh-sdk/README.md) — a harness-internal consumer of this client.
+- [SDK application bundle](../../bundle/sdk-app/README.md) — the `dsh --profile sdk` runtime application this client launches.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-None, as this is a client-process library; the model runs in the spawned runtime, whose experience is owned by the plugins its `cordis.yml` composes.
+None, as this is a client-process library; model-facing behavior lives in the spawned runtime's composed plugins.
 
 #### KV Cache effect
 
-None; this package neither assembles nor sends a provider request.
+None in the client process. Profile, patch, provider, model, and history choices determine cache reuse in the child.
 
 ## Known Limitations and Deferred Work
 
-- **No bundled-runtime resolution** — callers name the runtime executable explicitly; packaged-executable discovery stays Python-side until a TypeScript distribution consumer exists.
-- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the protocol's [Known Limitations](../protocol/README.md)).
-- **No per-prompt result or cancel** — low-level `prompt()` returns only an enqueue receipt; high-level `run()` owns receipt-to-idle collection, and abandoning it means closing the runtime.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the client is a poor fit or needs special care. They are current package constraints, not a comparison with other SDK clients or a task backlog.
+
+- **No bundled-runtime resolution** — the client resolves the same-version `@deepseek-ai/dsh` package (or a caller-provided `dshBin`); packaged-executable discovery stays Python-side until a TypeScript distribution consumer exists.
+- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the [protocol limitations](../protocol/README.md#known-limitations-and-deferred-work)).
+- **No per-prompt result** — low-level `prompt()` returns only an enqueue receipt; high-level `run()` owns receipt-to-idle collection, and abandoning it means closing the runtime.
 - **Client→server notifications and server→client requests are unimplemented** on both wire ends; the transport carries them for future approval flows.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers and is explicitly non-authoritative — shipped behavior and limits live in the sections above and in the code. The launch spec is intentionally fully explicit: no bundled-runtime resolution is planned for TypeScript until a distribution consumer exists. Keep the dispose ladder and the error vocabulary in sync with the Python client, which drives the same runtime. No other unresolved design questions are recorded.
+
+</details>

package/README.zh.md

@@ -1,49 +1,135 @@
+---
+description: "面向以子进程方式启动 DeepSeek Harness 运行时、并通过 stdio JSON-RPC 驱动 agent 轮次的调用方的 TypeScript SDK 客户端：DeepSeekHarness 运行 API 与低层 HarnessClient。"
+kind: "package-library"
+---
+
 # @deepseek-ai/dsh-sdk-client
 
 [English](README.md) | 中文
 
-以子进程方式驱动 DeepSeek Harness 运行时、走 stdio JSON-RPC 的 TypeScript 客户端 SDK——[Python SDK](../../../python/README.zh.md)（`deepseek-harness`）的设计孪生，共享同一个运行时对端、协议与分层：`DeepSeekHarness` 是高层自有运行 API，`HarnessClient` 是低层协议客户端。包（package）根枚举消费方接口：两层客户端、面向调用方的类型和 `JsonRpcResponseError`；源模块、规范化辅助函数与订阅投递机制不供消费方导入。纯库：不在任何 Cordis 上下文注册；它所 spawn 的运行时进程是一个完整 harness，其组成由自己的 `cordis.yml` 决定。
+## 概述
+
+`dsh-sdk-client` 让 TypeScript 程序以子进程方式、通过 stdio JSON-RPC 驱动 DeepSeek Harness 运行时。使用 `DeepSeekHarness` 你可以启动运行时、打开会话、发送提示词，并收集最终响应以及事件与通知流；`HarnessClient` 提供对协议层的显式控制。它是 [Python SDK](../../../python/README.zh.md) 的设计孪生，共享同一个运行时对端与协议。启动说明是显式的——调用方可通过 `dshBin` 指定运行时可执行文件，省略时解析同版本 `@deepseek-ai/dsh` 包的 bin，参数由客户端构造——因此本客户端适合仓库近旁的 TypeScript 消费方，如 SDK subagent 后端和知道自己要启动哪个运行时的自动化。它是纯库：不在任何 Cordis 上下文注册，而且它启动的运行时是一个完整 harness，其组成由自己的 `cordis.yml` 决定。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
 
-与 Python SDK 不同，启动规格完全显式（`command`/`args`）：本包面向仓库近旁的 TypeScript 消费方，包括 [`dsh-subagent-dsh-sdk`](../../subagent/subagent-dsh-sdk/README.zh.md) 后端和自动化；它们知道自己要启动哪个运行时。捆绑运行时解析（寻找打包可执行文件）仍归 Python 发行版负责。
+-----
 
-## DeepSeekHarness
+<a id="use-this-package"></a>
+## 使用本包
+
+当 TypeScript 代码需要从另一进程驱动完整 Harness 运行时、且你能显式指名运行时可执行文件时，使用本客户端。常用路径极简：用启动规格构造 `DeepSeekHarness`，运行提示词，然后关闭它，使子进程总能被回收。
+
+### 用 DeepSeekHarness 运行 agent 轮次
 
 ```ts
 import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 
 await using harness = new DeepSeekHarness({
-  launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
+  profile: 'sdk',
+  patches: ['./automation.cordis.yml'],
   provider: 'deepseek-official',
   model: 'deepseek-v4-flash',
+  reasoningEffort: ReasoningEffortId('max'),
   maxTokens: 49_152,
 })
 const result = await harness.run('say hi')
 console.log(result.finalResponse)
 ```
 
-子进程在首次使用时惰性启动，并在多次 `run()` 之间持续归实例所有；必须 `close()`（或 `await using`），子进程才总能被回收。`start()` 记忆化 `initialize` 握手（工作区 cwd——在通过协议传输之前解析为绝对路径——加 provider/model 路由和可选的正整数 `maxTokens` 输出上限）；握手失败会回收运行时并换入全新客户端，后续调用用新子进程重试（直到终结性的 `close()`）。该上限作用于根 agent（智能体）的每次请求，并由进程内后代继承；压缩（compaction）插件单独持有摘要上限。`session(id?)` 打开具名或全新的会话句柄。
+子进程在首次使用时惰性启动，并在多次 `run()` 调用之间持续归实例所有；请调用 `close()`（或使用 `await using`），子进程才总能被回收。`start()` 会记忆化有界的 `initialize` 握手，其中包含工作区 cwd、提供方／模型路由、可选且由适配器持有的 `reasoningEffort`，以及可选的正整数 `maxTokens` 输出上限。服务器会在接受提示词前校验该确切路由；省略推理强度时保留模型自身的默认值。`initializeTimeoutMs` 默认 10 秒，诊断会写明所选 profile 并附带保留的 stderr 尾部。`run(input, { sessionId?, onNotification? })` 接受文本或 `SdkPromptContentBlock[]`；内联栅格图像块携带规范 base64 与 `mimeType`，并在运行时内变成持久附件。该调用拥有一个活动区间：它将提示词排入队列，等待其消息 id 出现在持久入队回执中，然后持续收集到整个 agent 下一次进入 `idle`。它返回 `RunResult { sessionId, finalResponse, events, notifications }`，其中 `finalResponse` 是该区间内根会话最后提交的助手文本——并非因果上归属于该提示词的响应，因为 steering（中途引导）、注入的上下文和其他排队工作都可能在 idle 前参与其中。`session(id?)` 打开具名或全新的会话句柄。握手失败且清理成功时，实例会换入全新客户端，使后续调用用新进程重试，直到终结性的 `close()`；如果初始化和清理均失败，`start()` 会返回保留两个原因的有序 `AggregateError`，并继续保留失败的客户端，避免在原进程退出尚未得到证明时启动另一个进程。`maxTokens` 限制每个根 agent 请求的输出量，并由进程内后代继承；压缩（compaction）插件单独持有摘要上限。
+
+### 用 HarnessClient 做低层控制
+
+`HarnessClient` 是运行 API 之下的协议客户端：显式 `start()`、`initialize()`、`prompt()`、`request()` 与 `close()`，外加通知订阅。`prompt()` 在运行时接受排队消息后立即返回该消息的 id，绝不等待 agent 活动。`subscribe(filter?)` 返回 `NotificationSubscription`（可等待的 `next()`、非阻塞 `tryNext()`、异步迭代）；`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知，范围限定在客户端完成，与 Python SDK 完全一致。
+
+本客户端为每种失败模式导出类型化错误：`JsonRpcResponseError`（协议错误响应，保留 code 与 data）、`RequestTimeoutError`（配置的时限已到）、`SdkProtocolError`（响应超出文档化协议）、`TransportClosedError`（运行时已消失——消息携带退出码与有界 stderr 尾部）。`close()` 先请求协议 `shutdown`（受 `shutdownTimeoutMs` 约束，默认 1000 毫秒），然后走 stdin-EOF → SIGTERM → SIGKILL 阶梯直到进程退出；幂等，已关闭的客户端拒绝复用。`HarnessClientOptions.env` 给定时整体替换子进程环境（`undefined` 原样继承父进程环境）；凭据策略归调用方——`dsh-subprocess` 的 `scrubbedParentEnv` 是面向隔离启动的共享擦除基底。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释客户端背后的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+客户端是同一协议上的两层：`DeepSeekHarness`（自有运行）叠加在 `HarnessClient`（协议客户端）之上，与 Python SDK 的分层一致。它运行在任何 harness 上下文之外，因此直接 spawn 运行时而非经由 `dsh-subprocess` 服务——即该 seam 记录的 SDK 托管传输例外——其关闭阶梯也位于本包。运行时对上下文内每个会话都发通知；会话树范围限定是客户端对 `subagent.started` 血缘边的过滤。
 
-`run(input, { sessionId?, onNotification? })` 拥有一个活动区间：它将提示词排入队列，等待其 `MessageId` 出现在持久的 `agent/inbox/spliced` 回执中，然后持续收集到整个 agent 下一次进入 `idle`。它返回 `RunResult { sessionId, finalResponse, events, notifications }`。`finalResponse` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的响应；steering（中途引导）、注入的上下文和其他排队工作都可能在 idle 前参与其中。`events` 包含根会话事件，`notifications` 还包含通过 `subagent.started` 发现的后代，均按协议传输顺序排列。结果不携带提示词级状态或轮次原因。传输丢失、超时和协议违例会导致 Promise 被拒绝；模型结果仍可在事件流中观察，但不会归属于某一输入。
+### 源码地图
 
-## HarnessClient
+| 文件 | 职责 |
+|---|---|
+| [`src/api.ts`](src/api.ts) | `DeepSeekHarness` + `HarnessSession`：自有运行、回收到 idle 的收集、`finalResponse` |
+| [`src/client.ts`](src/client.ts) | `HarnessClient`：spawn、握手、请求、订阅扇出、类型化错误 |
+| [`src/dispose.ts`](src/dispose.ts) | 私有关闭阶梯：stdin EOF → SIGTERM → SIGKILL 直到真正退出 |
+| [`src/types.ts`](src/types.ts) | 启动与超时选项、通知结构、`RunResult` |
+| [`src/index.ts`](src/index.ts) | 消费方接口：两层客户端与面向调用方的类型 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式配套插件（无运行时不变式——对端是独立运行时进程） |
 
-自有运行 API 之下的协议客户端：显式 `start()`/`initialize()`/`prompt()`/`request()`/`close()`，外加通知订阅。`prompt()` 在运行时接受排队消息后立即返回该消息的 ID，绝不等待 agent 活动。`subscribe(filter?)` 返回 `NotificationSubscription`（可等待的 `next()`、非阻塞 `tryNext()`、异步迭代）；`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知，范围限定在客户端完成，与 Python SDK 完全一致。本包导出有明确类型的错误：`JsonRpcResponseError`（协议错误响应，保留 code/data）、`RequestTimeoutError`（配置的时限已到）、`SdkProtocolError`（响应超出文档化协议）、`TransportClosedError`（运行时已消失——消息携带退出码与有界 stderr 尾部）。
+### 自有活动流程
 
-`close()` 先请求协议 `shutdown`（受 `shutdownTimeoutMs` 约束，默认 1000 毫秒），然后走 stdin-EOF → SIGTERM → SIGKILL 阶梯（`disposeEofGraceMs` 默认 6000，`disposeGraceMs` 默认 3000）直到进程真正退出。该阶梯为本客户端私有：它运行在任何 harness 上下文之外，无法搭乘 [`dsh-subprocess`](../../subprocess/README.zh.md) 服务——即该 seam 所记录的 SDK 托管传输例外。幂等，已关闭的客户端拒绝复用。
+一次运行会订阅会话树、把提示词排入队列，等待提示词的消息 id 出现在持久的 `agent/inbox/spliced` 回执中，然后持续收集通知，直到整个 agent 报告 `idle`。`finalResponse` 从收集到的事件中最后一条 `assistant/message` 派生。传输丢失、超时与协议违例会使本次运行被拒绝；模型结果仍可在事件流中观察，但不会归属于某一输入。
 
-`HarnessClientOptions.env` 给定时整体替换子进程环境（`undefined` 原样继承父进程环境）；凭据策略归调用方——`dsh-subprocess` 的 `scrubbedParentEnv` 是面向隔离启动的共享擦除基底。
+### 错误与关闭
 
+每种失败模式都映射到一个导出的错误类——协议错误响应、请求时限已到、响应超出文档化协议、运行时死亡——调用方可以按失败类型分支处理；这四个类从 [src/index.ts](src/index.ts) 导出。关闭采用私有的幂等阶梯（stdin EOF → SIGTERM → SIGKILL），位于 [src/dispose.ts](src/dispose.ts)，只在进程真正退出时结束。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当客户端约定不够用时阅读以下页面。它们从协议格式进入服务插件与使用本客户端的应用。
+
+- [SDK 协议格式](../protocol/README.zh.md) — 本客户端所说的 JSON-RPC 方法与载荷结构。
+- [JSON-RPC 服务插件](../server/README.zh.md) — 服务本客户端的运行时插件。
+- [Python SDK](../../../python/README.zh.md) — 共享同一运行时对端与协议的设计孪生。
+- [SDK subagent 后端](../../subagent/subagent-dsh-sdk/README.zh.md) — harness 内部消费本客户端的例子。
+- [SDK 应用组合包](../../bundle/sdk-app/README.zh.md) — 本客户端启动的 `dsh --profile sdk` 运行时应用。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-无，因为这是一个客户端进程库；模型运行在 spawn 出的运行时中，其体验由该运行时的 `cordis.yml` 所组合的插件决定。
+无，因为这是客户端进程库；模型可见行为存在于所 spawn 运行时组合的插件中。
 
 #### KV Cache 影响
 
-无；本包既不组装也不发送提供方请求。
+client 进程中无影响。子进程的 profile、patch、provider、model 与历史决定缓存复用。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本客户端何时不合适或需要特别注意。它们是当前包约束，不是与其他 SDK 客户端的对比或任务积压。
+
+- **无捆绑运行时解析**——客户端解析同版本 `@deepseek-ai/dsh` 包（或调用方提供的 `dshBin`）；打包可执行文件的发现留在 Python 侧，直到出现 TypeScript 发行版消费方。
+- **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见[协议限制](../protocol/README.zh.md#known-limitations-and-deferred-work)）。
+- **没有逐提示词结果**——低层 `prompt()` 只返回入队回执；高层 `run()` 负责从回收到 idle 的收集，放弃该过程意味着关闭运行时。
+- **客户端→服务端通知与服务端→客户端请求**在协议两端都未实现；传输层为未来审批流程保留了承载能力。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
 
-## 已知限制与暂缓事项
+本开发备注是维护者的工作上下文，明确不具权威性——已交付的行为与限制见上文各节与代码。启动规格有意保持完全显式：在出现 TypeScript 发行版消费方之前，不计划做捆绑运行时解析。请让关闭阶梯与错误词汇与驱动同一运行时的 Python 客户端保持同步。没有记录其他未解决的开放设计问题。
 
-- **无捆绑运行时解析**——调用方显式指定运行时可执行文件；打包可执行文件的发现留在 Python 侧，直到出现 TypeScript 发行版消费方。
-- **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见协议的 [已知限制](../protocol/README.zh.md)）。
-- **没有逐提示词结果或取消**——低层 `prompt()` 只返回入队回执；高层 `run()` 负责从回执收集到 idle，放弃该过程意味着关闭运行时。
-- **客户端→服务端通知与服务端→客户端请求**在协议两端都未实现；传输层为未来审批流保留了承载能力。
+</details>

package/lib/index.js

@@ -1,7 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { JsonRpcLineTransport, JsonRpcResponseError, JsonRpcResponseError as JsonRpcResponseError$1 } from "@deepseek-ai/dsh-sdk-protocol";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 //#region lib/types/dispose.js
 /**
 * Private teardown ladder for the runtime subprocess: stdin EOF (cooperative
@@ -96,6 +98,97 @@ async function disposeRuntimeProcess(child, graces, platform = process.platform)
 	}
 	await forceTerminateWithin(child, graces.disposeGraceMs);
 }
+/** Read a package manifest from one resolved package.json URL. */
+function manifest(url) {
+	return JSON.parse(readFileSync(fileURLToPath(url), "utf8"));
+}
+/**
+* Resolve and version-check a dsh executable from package manifests.
+* @param dshManifestUrl - resolved URL of the dsh package manifest.
+* @param clientManifestUrl - resolved URL of the SDK client manifest.
+* @returns the absolute dsh executable path.
+*/
+function resolveDshBinFromManifests(dshManifestUrl, clientManifestUrl) {
+	const dshManifest = manifest(dshManifestUrl);
+	const clientManifest = manifest(clientManifestUrl);
+	if (typeof dshManifest.version !== "string" || dshManifest.version !== clientManifest.version) throw new Error(`dsh SDK client ${String(clientManifest.version)} requires the same dsh version, got ${String(dshManifest.version)}`);
+	const bin = typeof dshManifest.bin === "object" && dshManifest.bin !== null ? dshManifest.bin.dsh : dshManifest.bin;
+	if (typeof bin !== "string" || bin === "") throw new Error("@deepseek-ai/dsh declares no dsh executable");
+	return resolve(dirname(fileURLToPath(dshManifestUrl)), bin);
+}
+/**
+* Resolve the Node launch for one same-version dsh package.
+* @param dshManifestUrl - resolved URL of the dsh package manifest.
+* @param clientManifestUrl - resolved URL of the SDK client manifest.
+* @param sourceLoaderUrl - optional absolute tsx loader URL for deterministic tests.
+* @returns built output, or the source entry plus its compatibility patch and tsx environment.
+*/
+function resolveDshNodeLaunchFromManifests(dshManifestUrl, clientManifestUrl, sourceLoaderUrl) {
+	const bin = resolveDshBinFromManifests(dshManifestUrl, clientManifestUrl);
+	if (existsSync(bin)) return {
+		nodeArgs: [bin],
+		patches: [],
+		environment: {}
+	};
+	const packageDir = dirname(fileURLToPath(dshManifestUrl));
+	const sourceBin = resolve(packageDir, "src/bin.ts");
+	const sourcePatch = resolve(packageDir, "src/sdk-source.cordis.patch.yml");
+	const sourceTsconfig = resolve(packageDir, "tsconfig.json");
+	if (!existsSync(sourceBin) || !existsSync(sourcePatch) || !existsSync(sourceTsconfig)) throw new Error(`@deepseek-ai/dsh is missing its built executable ${bin} and complete source launch files ${sourceBin}, ${sourcePatch}, ${sourceTsconfig}`);
+	return {
+		nodeArgs: [
+			"--import",
+			sourceLoaderUrl ?? import.meta.resolve("tsx/esm"),
+			sourceBin
+		],
+		patches: [sourcePatch],
+		environment: { TSX_TSCONFIG_PATH: sourceTsconfig }
+	};
+}
+/**
+* Resolve the installed dsh package to a built or source Node launch.
+* @returns the launch descriptor for the current checkout or installed package.
+*/
+function installedDshNodeLaunch() {
+	return resolveDshNodeLaunchFromManifests(import.meta.resolve("@deepseek-ai/dsh/package.json"), new URL("../package.json", import.meta.url).href);
+}
+/**
+* Resolve caller-relative filesystem inputs and construct canonical dsh argv.
+* @param options - public SDK launch options.
+* @param callerCwd - parent-process directory used for lexical resolution.
+* @returns one generic subprocess spec for the JSON-RPC transport.
+*/
+function resolveDshLaunch(options = {}, callerCwd = process.cwd()) {
+	const profile = options.profile ?? "sdk";
+	const dshLaunch = options.dshBin === void 0 ? installedDshNodeLaunch() : {
+		nodeArgs: [resolve(callerCwd, options.dshBin)],
+		patches: [],
+		environment: {}
+	};
+	const patches = [...dshLaunch.patches, ...(options.patches ?? []).map((path) => resolve(callerCwd, path))];
+	const dshHome = options.dshHome === void 0 ? void 0 : resolve(callerCwd, options.dshHome);
+	return {
+		command: process.execPath,
+		args: [
+			...dshLaunch.nodeArgs,
+			"--profile",
+			profile,
+			...patches.flatMap((path) => ["--patch", path])
+		],
+		...options.processCwd === void 0 ? {} : { cwd: resolve(callerCwd, options.processCwd) },
+		environment: () => ({
+			...options.env ?? process.env,
+			...dshLaunch.environment,
+			...dshHome === void 0 ? {} : { DSH_HOME: dshHome }
+		}),
+		description: `dsh profile ${JSON.stringify(profile)}`,
+		initializeTimeoutMs: options.initializeTimeoutMs ?? 1e4,
+		...options.requestTimeoutMs === void 0 ? {} : { requestTimeoutMs: options.requestTimeoutMs },
+		...options.shutdownTimeoutMs === void 0 ? {} : { shutdownTimeoutMs: options.shutdownTimeoutMs },
+		...options.disposeEofGraceMs === void 0 ? {} : { disposeEofGraceMs: options.disposeEofGraceMs },
+		...options.disposeGraceMs === void 0 ? {} : { disposeGraceMs: options.disposeGraceMs }
+	};
+}
 //#endregion
 //#region lib/types/client.js
 /**
@@ -197,7 +290,7 @@ var NotificationSubscriptionImpl = class {
 	* Deliver one notification to a waiter or the queue when the filter
 	* matches. A throwing filter fails only THIS subscription (detached, the
 	* throw becomes its terminal error) — it never disturbs sibling
-	* subscriptions or the transport's read loop, mirroring the Python client.
+	* subscriptions or the transport's read loop.
 	* @param notification - the wire notification to deliver.
 	*/
 	push(notification) {
@@ -233,7 +326,9 @@ var NotificationSubscriptionImpl = class {
 * runtime is closed.
 */
 var HarnessClient = class {
+	/** Original public dsh launch and timeout options for this client. */
 	options;
+	runtime;
 	child;
 	transport;
 	stderrTail = [];
@@ -244,9 +339,9 @@ var HarnessClient = class {
 	spawnError;
 	streamsSettled = Promise.resolve();
 	closeTask;
-	/** @param options - launch spec, complete child environment, and timeouts. */
-	constructor(options) {
+	constructor(options = {}, runtime) {
 		this.options = options;
+		this.runtime = runtime ?? resolveDshLaunch(options);
 	}
 	/**
 	* Spawn the runtime subprocess and start reading frames. Idempotent while
@@ -255,9 +350,9 @@ var HarnessClient = class {
 	start() {
 		if (this.closeTask !== void 0) throw new TransportClosedError("DeepSeek Harness runtime client is closed");
 		if (this.child !== void 0) return;
-		const child = spawn(this.options.command, this.options.args ?? [], {
-			cwd: this.options.cwd,
-			env: this.options.env ?? process.env,
+		const child = spawn(this.runtime.command, this.runtime.args, {
+			cwd: this.runtime.cwd,
+			env: this.runtime.environment(),
 			stdio: [
 				"pipe",
 				"pipe",
@@ -323,7 +418,7 @@ var HarnessClient = class {
 	* @returns the runtime's wire identity.
 	*/
 	async initialize(params) {
-		const result = await this.request("initialize", { ...params });
+		const result = await this.request("initialize", { ...params }, this.runtime.initializeTimeoutMs);
 		if (!isRecord(result) || !isRecord(result.serverInfo) || typeof result.serverInfo.name !== "string" || typeof result.serverInfo.version !== "string") throw new SdkProtocolError(`initialize returned no server identity: ${JSON.stringify(result)}`);
 		return { serverInfo: {
 			name: result.serverInfo.name,
@@ -363,12 +458,13 @@ var HarnessClient = class {
 		const transport = this.transport;
 		/* v8 ignore next -- start() either sets the transport or throws */
 		if (transport === void 0) throw new TransportClosedError("DeepSeek Harness runtime is not running");
-		const timeout = timeoutMs ?? this.options.requestTimeoutMs;
+		const timeout = timeoutMs ?? this.runtime.requestTimeoutMs;
 		try {
 			if (timeout === void 0) return await transport.request(method, params ?? {});
 			const abandon = new AbortController();
 			const timer = setTimeout(() => {
-				abandon.abort(new RequestTimeoutError(`${method} timed out after ${timeout}ms waiting for the DeepSeek Harness runtime`));
+				const stderr = this.stderrTail.length === 0 ? "" : `; stderr tail:\n${this.stderrTail.join("\n")}`;
+				abandon.abort(new RequestTimeoutError(`${method} timed out after ${timeout}ms waiting for ${this.runtime.description}${stderr}`));
 			}, timeout);
 			try {
 				return await transport.request(method, params ?? {}, abandon.signal);
@@ -407,8 +503,8 @@ var HarnessClient = class {
 	}
 	/**
 	* Subscribe to one session and the descendants discovered from
-	* `subagent.started` lineage edges (the runtime notifies for every session
-	* in its context; scoping is client-side, mirroring the Python SDK).
+	* `subagent.started` lineage edges. The runtime notifies for every session
+	* in its context, so this client applies the scope.
 	* @param sessionId - the root session id.
 	* @returns the filtered subscription handle.
 	*/
@@ -438,13 +534,13 @@ var HarnessClient = class {
 		const child = this.child;
 		if (child === void 0) return;
 		try {
-			await this.request("shutdown", void 0, this.options.shutdownTimeoutMs ?? 1e3);
+			await this.request("shutdown", void 0, this.runtime.shutdownTimeoutMs ?? 1e3);
 		} catch (error) {
 			this.appendStderr([`shutdown request failed: ${errorMessage(error)}`]);
 		}
 		await disposeRuntimeProcess(child, {
-			disposeEofGraceMs: this.options.disposeEofGraceMs ?? 6e3,
-			disposeGraceMs: this.options.disposeGraceMs ?? 3e3
+			disposeEofGraceMs: this.runtime.disposeEofGraceMs ?? 6e3,
+			disposeGraceMs: this.runtime.disposeGraceMs ?? 3e3
 		});
 		this.transport?.close();
 		this.failSubscriptions(this.closedError("DeepSeek Harness runtime closed"));
@@ -486,7 +582,7 @@ var HarnessClient = class {
 		})]);
 	}
 	closedError(reason) {
-		const parts = [reason];
+		const parts = [`${this.runtime.description}: ${reason}`];
 		if (this.spawnError !== void 0) parts.push(`spawn error: ${this.spawnError.message}`);
 		if (this.exitCode !== void 0) parts.push(`exit code: ${String(this.exitCode)}`);
 		if (this.stderrTail.length > 0) parts.push(`stderr tail:\n${this.stderrTail.join("\n")}`);
@@ -512,7 +608,6 @@ function errorMessage(error) {
 * High-level run API over {@link HarnessClient}: `DeepSeekHarness` owns one
 * runtime subprocess across many sessions; `HarnessSession.run` sends a
 * prompt and settles when the whole agent next becomes idle.
-* Mirrors the Python SDK's `DeepSeekHarness`/`Session` pair.
 *
 * @module @deepseek-ai/dsh-sdk-client/api
 */
@@ -524,26 +619,28 @@ function errorMessage(error) {
 */
 var DeepSeekHarness = class {
 	clientInstance;
-	launch;
+	createClient;
 	cwd;
 	provider;
 	model;
+	reasoningEffort;
 	maxTokens;
 	initialized;
 	closed = false;
-	/** @param options - runtime launch spec plus the session route (cwd/provider/model). */
-	constructor(options) {
-		this.launch = options.launch;
-		this.clientInstance = new HarnessClient(options.launch);
-		this.cwd = resolve(options.cwd ?? options.launch.cwd ?? process.cwd());
+	constructor(options = {}, clientFactory) {
+		this.createClient = clientFactory ?? (() => new HarnessClient(options));
+		this.clientInstance = this.createClient();
+		this.cwd = resolve(options.cwd ?? options.processCwd ?? process.cwd());
 		this.provider = options.provider ?? "deepseek-official";
 		this.model = options.model ?? "deepseek-v4-flash";
+		this.reasoningEffort = options.reasoningEffort;
 		this.maxTokens = options.maxTokens;
 	}
 	/**
 	* The underlying JSON-RPC client (exposed for low-level access). A failed
-	* handshake reaps its runtime and swaps in a fresh instance, so do not
-	* cache this across a failed {@link start}.
+	* handshake swaps in a fresh instance only after cleanup proves the runtime
+	* exited; cleanup failure retains this client, so do not cache it across a
+	* failed {@link start}.
 	* @returns the client currently owning the runtime subprocess.
 	*/
 	get client() {
@@ -551,9 +648,12 @@ var DeepSeekHarness = class {
 	}
 	/**
 	* Start the subprocess and perform the `initialize` handshake once. On
-	* failure the runtime is reaped and a fresh client replaces it
-	* (`HarnessClient.close` is permanent), so a later call retries with a new
-	* subprocess — unless {@link close} already ended this harness.
+	* failure, successful SDK-owned cleanup reaps the runtime and installs a
+	* fresh client (`HarnessClient.close` is permanent), so a later call retries
+	* with a new subprocess unless {@link close} already ended this harness. If
+	* cleanup also fails, rejects with an `AggregateError` whose ordered errors
+	* preserve both causes and retains the failed client rather than spawning
+	* alongside a process whose exit was not proved.
 	* @returns settlement of the (memoized) handshake.
 	*/
 	start() {
@@ -564,12 +664,17 @@ var DeepSeekHarness = class {
 					cwd: this.cwd,
 					provider: this.provider,
 					model: this.model,
+					...this.reasoningEffort === void 0 ? {} : { reasoningEffort: this.reasoningEffort },
 					...this.maxTokens === void 0 ? {} : { maxTokens: this.maxTokens }
 				});
 			} catch (error) {
 				this.initialized = void 0;
-				await this.clientInstance.close();
-				if (!this.closed) this.clientInstance = new HarnessClient(this.launch);
+				try {
+					await this.clientInstance.close();
+				} catch (cleanupError) {
+					throw new AggregateError([error, cleanupError], "DeepSeek Harness initialization and cleanup failed");
+				}
+				if (!this.closed) this.clientInstance = this.createClient();
 				throw error;
 			}
 		})();
@@ -683,6 +788,24 @@ function normalizeInput(input) {
 		text: input
 	}] : input;
 }
+/** Validate the provider-read fields of one wire turn-end reason. */
+function validatedTurnEndReason(value) {
+	if (!isRecord(value) || typeof value.kind !== "string") throw new SdkProtocolError(`turn/end carried no reason envelope: ${JSON.stringify(value)}`);
+	if (value.kind === "aborted") {
+		if (!isRecord(value.reason) || typeof value.reason.kind !== "string") throw new SdkProtocolError(`turn/end carried a malformed aborted reason: ${JSON.stringify(value)}`);
+		switch (value.reason.kind) {
+			case "user":
+			case "parent":
+			case "disposed":
+			case "legacy": break;
+			case "hook":
+				if (typeof value.reason.reason !== "string") throw new SdkProtocolError(`turn/end carried a malformed hook abort reason: ${JSON.stringify(value)}`);
+				break;
+			default: throw new SdkProtocolError(`turn/end carried an unknown abort reason: ${JSON.stringify(value)}`);
+		}
+	}
+	return value;
+}
 /** Validate the fields in a wire `session.event` envelope before returning the typed result. */
 function validatedSessionEvent(value) {
 	if (!isRecord(value) || typeof value.type !== "string") throw new SdkProtocolError(`session.event carried no event envelope: ${JSON.stringify(value)}`);
@@ -691,6 +814,11 @@ function validatedSessionEvent(value) {
 		const content = isRecord(message) ? message.content : void 0;
 		if (!Array.isArray(content) || !content.every((block) => isRecord(block) && typeof block.type === "string")) throw new SdkProtocolError(`assistant/message event carried malformed content: ${JSON.stringify(value)}`);
 	}
+	if (value.type === "turn/end") {
+		const data = isRecord(value.data) ? value.data : void 0;
+		if (data === void 0) throw new SdkProtocolError(`turn/end event carried malformed data: ${JSON.stringify(value)}`);
+		validatedTurnEndReason(data.reason);
+	}
 	return value;
 }
 /** Whether a raw session event is the durable enqueue receipt for `messageId`. */

package/lib/types/api.d.ts

@@ -2,13 +2,13 @@
  * High-level run API over {@link HarnessClient}: `DeepSeekHarness` owns one
  * runtime subprocess across many sessions; `HarnessSession.run` sends a
  * prompt and settles when the whole agent next becomes idle.
- * Mirrors the Python SDK's `DeepSeekHarness`/`Session` pair.
  *
  * @module @deepseek-ai/dsh-sdk-client/api
  */
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
 import { HarnessClient } from './client.ts';
-import type { ContentBlock, DeepSeekHarnessOptions, HarnessNotification, RunResult } from './types.ts';
+import type { RuntimeProcessOptions } from './launch.ts';
+import type { DeepSeekHarnessOptions, HarnessNotification, RunResult, SdkPromptContentBlock } from './types.ts';
 /**
  * Reusable SDK for running DeepSeek Harness agent turns in a runtime
  * subprocess. The subprocess starts lazily on first use and stays owned by
@@ -17,27 +17,32 @@ import type { ContentBlock, DeepSeekHarnessOptions, HarnessNotification, RunResu
  */
 export declare class DeepSeekHarness implements AsyncDisposable {
     private clientInstance;
-    private readonly launch;
+    private readonly createClient;
     private readonly cwd;
     private readonly provider;
     private readonly model;
+    private readonly reasoningEffort;
     private readonly maxTokens;
     private initialized;
     private closed;
-    /** @param options - runtime launch spec plus the session route (cwd/provider/model). */
-    constructor(options: DeepSeekHarnessOptions);
+    /** @param options - dsh launch configuration plus the session route, effort, and output cap. */
+    constructor(options?: DeepSeekHarnessOptions);
     /**
      * The underlying JSON-RPC client (exposed for low-level access). A failed
-     * handshake reaps its runtime and swaps in a fresh instance, so do not
-     * cache this across a failed {@link start}.
+     * handshake swaps in a fresh instance only after cleanup proves the runtime
+     * exited; cleanup failure retains this client, so do not cache it across a
+     * failed {@link start}.
      * @returns the client currently owning the runtime subprocess.
      */
     get client(): HarnessClient;
     /**
      * Start the subprocess and perform the `initialize` handshake once. On
-     * failure the runtime is reaped and a fresh client replaces it
-     * (`HarnessClient.close` is permanent), so a later call retries with a new
-     * subprocess — unless {@link close} already ended this harness.
+     * failure, successful SDK-owned cleanup reaps the runtime and installs a
+     * fresh client (`HarnessClient.close` is permanent), so a later call retries
+     * with a new subprocess unless {@link close} already ended this harness. If
+     * cleanup also fails, rejects with an `AggregateError` whose ordered errors
+     * preserve both causes and retains the failed client rather than spawning
+     * alongside a process whose exit was not proved.
      * @returns settlement of the (memoized) handshake.
      */
     start(): Promise<void>;
@@ -54,7 +59,7 @@ export declare class DeepSeekHarness implements AsyncDisposable {
      * @param options - optional session id and per-notification observer.
      * @returns the owned activity interval.
      */
-    run(input: string | ContentBlock[], options?: RunOptions): Promise<RunResult>;
+    run(input: string | SdkPromptContentBlock[], options?: RunOptions): Promise<RunResult>;
     /**
      * Shut down and reap the runtime subprocess. Idempotent and terminal —
      * a closed harness no longer retries a failed handshake.
@@ -67,6 +72,8 @@ export declare class DeepSeekHarness implements AsyncDisposable {
      */
     [Symbol.asyncDispose](): Promise<void>;
 }
+/** Construct the high-level API against a generic process for package-local fake-runtime tests. */
+export declare function createProcessDeepSeekHarness(runtime: RuntimeProcessOptions, options?: DeepSeekHarnessOptions): DeepSeekHarness;
 /** Per-run options: target session and streaming observer. */
 export interface RunOptions {
     /** Session id to run on; omitted mints a fresh session per call. */
@@ -92,14 +99,14 @@ export declare class HarnessSession {
      * @returns the owned activity interval; rejects on transport loss, timeout,
      * or a protocol error.
      */
-    run(input: string | ContentBlock[], options?: Pick<RunOptions, 'onNotification'>): Promise<RunResult>;
+    run(input: string | SdkPromptContentBlock[], options?: Pick<RunOptions, 'onNotification'>): Promise<RunResult>;
 }
 /**
  * Normalize run input: a string becomes one text block; blocks pass verbatim.
  * @param input - prompt text or content blocks.
  * @returns the content blocks to send.
  */
-export declare function normalizeInput(input: string | ContentBlock[]): ContentBlock[];
+export declare function normalizeInput(input: string | SdkPromptContentBlock[]): SdkPromptContentBlock[];
 /**
  * Extract the concatenated text of the last assistant message.
  * @param events - the activity interval's `session.event` payloads in wire order.

package/lib/types/client.d.ts

@@ -11,8 +11,8 @@
  *
  * @module @deepseek-ai/dsh-sdk-client/client
  */
-import { type InitializeParams, type InitializeResult } from '@deepseek-ai/dsh-sdk-protocol';
-import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import { type InitializeParams, type InitializeResult, type SdkPromptContentBlock } from '@deepseek-ai/dsh-sdk-protocol';
+import { type RuntimeProcessOptions } from './launch.ts';
 import type { HarnessClientOptions, HarnessNotification, NotificationFilter } from './types.ts';
 /**
  * The runtime subprocess is gone or unusable: it exited, its stdio closed, or
@@ -63,7 +63,9 @@ export interface NotificationSubscription extends AsyncIterable<HarnessNotificat
  * runtime is closed.
  */
 export declare class HarnessClient {
+    /** Original public dsh launch and timeout options for this client. */
     readonly options: HarnessClientOptions;
+    private readonly runtime;
     private child;
     private transport;
     private readonly stderrTail;
@@ -74,8 +76,8 @@ export declare class HarnessClient {
     private spawnError;
     private streamsSettled;
     private closeTask;
-    /** @param options - launch spec, complete child environment, and timeouts. */
-    constructor(options: HarnessClientOptions);
+    /** @param options - dsh profile, patch, home, process, environment, and timeout options. */
+    constructor(options?: HarnessClientOptions);
     /**
      * Spawn the runtime subprocess and start reading frames. Idempotent while
      * the process is live; rejects reuse after {@link close}.
@@ -93,7 +95,7 @@ export declare class HarnessClient {
      * @param contentBlocks - the user message, sent verbatim.
      * @returns the queued message id.
      */
-    prompt(sessionId: string, contentBlocks: ContentBlock[]): Promise<string>;
+    prompt(sessionId: string, contentBlocks: SdkPromptContentBlock[]): Promise<string>;
     /**
      * Send one JSON-RPC request and await its result.
      * @param method - the wire method name.
@@ -114,8 +116,8 @@ export declare class HarnessClient {
     subscribe(filter?: NotificationFilter): NotificationSubscription;
     /**
      * Subscribe to one session and the descendants discovered from
-     * `subagent.started` lineage edges (the runtime notifies for every session
-     * in its context; scoping is client-side, mirroring the Python SDK).
+     * `subagent.started` lineage edges. The runtime notifies for every session
+     * in its context, so this client applies the scope.
      * @param sessionId - the root session id.
      * @returns the filtered subscription handle.
      */
@@ -136,6 +138,8 @@ export declare class HarnessClient {
     private settleStreams;
     private closedError;
 }
+/** Construct the transport against a generic process for package-local fake-runtime tests. */
+export declare function createProcessHarnessClient(options: RuntimeProcessOptions): HarnessClient;
 /**
  * Whether `value` is a plain JSON object (the wire-boundary shape probe).
  * @param value - the wire value to probe.

package/lib/types/index.d.ts

@@ -1,10 +1,10 @@
 /**
  * TypeScript client SDK for the DeepSeek Harness runtime: spawn the
- * `dsh-jsonrpc-agent` runtime as a subprocess and drive agent turns over
- * stdio JSON-RPC. `DeepSeekHarness` is the high-level run API;
+ * same-version `dsh --profile sdk` runtime as a subprocess and drive agent
+ * turns over stdio JSON-RPC. `DeepSeekHarness` is the high-level run API;
  * `HarnessClient` is the lower-level protocol client. A pure library — it
- * registers nothing on a Cordis context; the runtime process it spawns is a
- * complete harness configured by its own `cordis.yml`.
+ * registers nothing on a Cordis context; named profiles and ordered patch
+ * files customize the runtime process it spawns.
  *
  * @module @deepseek-ai/dsh-sdk-client
  */
@@ -13,5 +13,5 @@ export type { RunOptions } from './api.ts';
 export { HarnessClient, RequestTimeoutError, SdkProtocolError, TransportClosedError, } from './client.ts';
 export type { NotificationSubscription } from './client.ts';
 export { JsonRpcResponseError } from '@deepseek-ai/dsh-sdk-protocol';
-export type { ContentBlock, DeepSeekHarnessOptions, HarnessClientOptions, HarnessNotification, NotificationFilter, RunResult, } from './types.ts';
+export type { ContentBlock, SdkPromptContentBlock, DeepSeekHarnessOptions, HarnessClientOptions, HarnessNotification, NotificationFilter, RunResult, } from './types.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/launch.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Resolve the public SDK launch configuration to one dsh subprocess.
+ * @module @deepseek-ai/dsh-sdk-client/launch
+ */
+import type { HarnessClientOptions } from './types.ts';
+/** Default bound for a profile to answer the SDK initialize handshake. */
+export declare const DEFAULT_INITIALIZE_TIMEOUT_MS = 10000;
+/** Internal generic process launch used by the transport and fake-runtime tests. */
+export interface RuntimeProcessOptions {
+    command: string;
+    args: string[];
+    cwd?: string;
+    /** Materialize the complete child environment when the client starts its subprocess. */
+    environment: () => NodeJS.ProcessEnv;
+    description: string;
+    initializeTimeoutMs: number;
+    requestTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    disposeEofGraceMs?: number;
+    disposeGraceMs?: number;
+}
+/** Node argv plus internal profile patches required by one resolved dsh entry. */
+export interface DshNodeLaunch {
+    /** Arguments before the profile selector. */
+    nodeArgs: string[];
+    /** Internal patches applied below caller-supplied patches. */
+    patches: string[];
+    /** Environment values required by the resolved entry mode. */
+    environment: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve and version-check a dsh executable from package manifests.
+ * @param dshManifestUrl - resolved URL of the dsh package manifest.
+ * @param clientManifestUrl - resolved URL of the SDK client manifest.
+ * @returns the absolute dsh executable path.
+ */
+export declare function resolveDshBinFromManifests(dshManifestUrl: string, clientManifestUrl: string): string;
+/**
+ * Resolve and version-check the built dsh executable installed with this SDK.
+ * @returns the absolute built executable path, whether or not it exists in a source checkout.
+ */
+export declare function installedDshBin(): string;
+/**
+ * Resolve the Node launch for one same-version dsh package.
+ * @param dshManifestUrl - resolved URL of the dsh package manifest.
+ * @param clientManifestUrl - resolved URL of the SDK client manifest.
+ * @param sourceLoaderUrl - optional absolute tsx loader URL for deterministic tests.
+ * @returns built output, or the source entry plus its compatibility patch and tsx environment.
+ */
+export declare function resolveDshNodeLaunchFromManifests(dshManifestUrl: string, clientManifestUrl: string, sourceLoaderUrl?: string): DshNodeLaunch;
+/**
+ * Resolve caller-relative filesystem inputs and construct canonical dsh argv.
+ * @param options - public SDK launch options.
+ * @param callerCwd - parent-process directory used for lexical resolution.
+ * @returns one generic subprocess spec for the JSON-RPC transport.
+ */
+export declare function resolveDshLaunch(options?: HarnessClientOptions, callerCwd?: string): RuntimeProcessOptions;
+//# sourceMappingURL=launch.d.ts.map

package/lib/types/types.d.ts

@@ -4,7 +4,8 @@
  *
  * @module @deepseek-ai/dsh-sdk-client/types
  */
-import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import type { SdkPromptContentBlock } from '@deepseek-ai/dsh-sdk-protocol';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
 /** One server-to-client notification as received off the wire. */
 export interface HarnessNotification {
@@ -17,19 +18,26 @@ export interface HarnessNotification {
 export type NotificationFilter = (notification: HarnessNotification) => boolean;
 /** Launch and timeout options for {@link HarnessClient}. */
 export interface HarnessClientOptions {
-    /** The runtime executable (the `dsh-jsonrpc-agent` bin, a packaged exe, or `node`). */
-    command: string;
-    /** Arguments passed to {@link command}. */
-    args?: string[];
-    /** Working directory for the runtime process itself. */
-    cwd?: string;
+    /** Absolute or caller-relative dsh CLI module; omitted resolves this package's same-version dependency. */
+    dshBin?: string;
+    /** Named profile serving the SDK protocol (default `sdk`). */
+    profile?: string;
+    /** Ordered per-launch profile patches; relative paths resolve before spawn. */
+    patches?: string[];
+    /** Explicit Harness home for this child; relative paths resolve before spawn. */
+    dshHome?: string;
+    /** Working directory for the dsh process itself. */
+    processCwd?: string;
     /**
-     * The complete child environment. `undefined` inherits the parent env
-     * verbatim; passing an object replaces it entirely, so callers own
+     * The complete child environment, read when {@link HarnessClient.start}
+     * spawns. `undefined` reads the parent env at that time; passing an object
+     * reads that object at spawn and replaces the parent environment entirely, so callers own
      * credential policy (see `scrubbedParentEnv` in `@deepseek-ai/dsh-subprocess`
      * for the shared scrub-then-merge base).
      */
     env?: NodeJS.ProcessEnv;
+    /** Bound (ms) on the initial profile handshake (default 10000). */
+    initializeTimeoutMs?: number;
     /** Per-request timeout (ms); `undefined` waits indefinitely (a turn can legitimately run long). */
     requestTimeoutMs?: number;
     /** Bound (ms) on the protocol `shutdown` exchange inside `close()` (default 1000). */
@@ -40,15 +48,15 @@ export interface HarnessClientOptions {
     disposeGraceMs?: number;
 }
 /** Options for the high-level {@link DeepSeekHarness} wrapper. */
-export interface DeepSeekHarnessOptions {
-    /** Launch spec for the runtime subprocess (command, args, cwd, env, timeouts). */
-    launch: HarnessClientOptions;
-    /** Workspace cwd recorded on every SDK-created session (default: the launch cwd, else `process.cwd()`). */
+export interface DeepSeekHarnessOptions extends HarnessClientOptions {
+    /** Workspace cwd recorded on every SDK-created session (default: the process cwd, else `process.cwd()`). */
     cwd?: string;
     /** Provider route for SDK-created agents (default `deepseek-official`). */
     provider?: string;
     /** Model for SDK-created agents (default `deepseek-v4-flash`). */
     model?: string;
+    /** Adapter-owned reasoning effort for the selected provider/model route. */
+    reasoningEffort?: ReasoningEffortId;
     /** Maximum output tokens for each conversation-model request. */
     maxTokens?: number;
 }
@@ -65,4 +73,5 @@ export interface RunResult {
 }
 /** Re-exported content-block alias so SDK callers need no extra import. */
 export type { ContentBlock };
+export type { SdkPromptContentBlock };
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sdk-client",
   "description": "TypeScript client SDK for driving a DeepSeek Harness runtime subprocess over stdio JSON-RPC: the DeepSeekHarness high-level turns API and the lower-level HarnessClient",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -30,18 +30,21 @@
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh": "0.1.2-alpha.2"
+  },
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-sdk-protocol": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-sdk-protocol": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2"
   }
 }