@deepseek-ai/dsh-sdk-client 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/scaffold/client/README.md
+README.md: b33457875f81d11d09bab2e5aa5ce730e233c78a
+README.zh.md: 271f07ffb0f97abe005971962beb517acfdc05a4

package/README.md

@@ -0,0 +1,49 @@
+# @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.
+
+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
+
+```ts
+import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client'
+
+await using harness = new DeepSeekHarness({
+  launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
+  provider: 'deepseek-official',
+  model: 'deepseek-v4-flash',
+  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.
+
+`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.
+
+## HarnessClient
+
+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).
+
+`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.
+
+`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.
+
+## 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.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## 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.
+- **Client→server notifications and server→client requests are unimplemented** on both wire ends; the transport carries them for future approval flows.

package/README.zh.md

@@ -0,0 +1,49 @@
+# @deepseek-ai/dsh-sdk-client
+
+[English](README.md) | 中文
+
+以子进程方式驱动 DeepSeek Harness 运行时、走 stdio JSON-RPC 的 TypeScript 客户端 SDK——[Python SDK](../../../python/README.md)（`deepseek-harness`）的设计孪生，共享同一个运行时对端、协议与分层：`DeepSeekHarness` 是高层自有运行 API，`HarnessClient` 是低层协议客户端。包（package）根枚举消费方接口：两层客户端、面向调用方的类型和 `JsonRpcResponseError`；源模块、规范化辅助函数与订阅投递机制不供消费方导入。纯库：不在任何 Cordis 上下文注册；它所 spawn 的运行时进程是一个完整 harness，其组成由自己的 `cordis.yml` 决定。
+
+与 Python SDK 不同，启动规格完全显式（`command`/`args`）：本包面向仓库近旁的 TypeScript 消费方，包括 [`dsh-subagent-dsh-sdk`](../../subagent/subagent-dsh-sdk/README.md) 后端和自动化；它们知道自己要启动哪个运行时。捆绑运行时解析（寻找打包可执行文件）仍归 Python 发行版负责。
+
+## DeepSeekHarness
+
+```ts
+import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client'
+
+await using harness = new DeepSeekHarness({
+  launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
+  provider: 'deepseek-official',
+  model: 'deepseek-v4-flash',
+  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(input, { sessionId?, onNotification? })` 拥有一个活动区间：它将提示词排入队列，等待其 `MessageId` 出现在持久的 `agent/inbox/spliced` 回执中，然后持续收集到整个 agent 下一次进入 `idle`。它返回 `RunResult { sessionId, finalResponse, events, notifications }`。`finalResponse` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的响应；steering（中途引导）、注入的上下文和其他排队工作都可能在 idle 前参与其中。`events` 包含根会话事件，`notifications` 还包含通过 `subagent.started` 发现的后代，均按协议传输顺序排列。结果不携带提示词级状态或轮次原因。传输丢失、超时和协议违例会导致 Promise 被拒绝；模型结果仍可在事件流中观察，但不会归属于某一输入。
+
+## 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 阶梯（`disposeEofGraceMs` 默认 6000，`disposeGraceMs` 默认 3000）直到进程真正退出。该阶梯为本客户端私有：它运行在任何 harness 上下文之外，无法搭乘 [`dsh-subprocess`](../../subprocess/README.md) 服务——即该 seam 所记录的 SDK 托管传输例外。幂等，已关闭的客户端拒绝复用。
+
+`HarnessClientOptions.env` 给定时整体替换子进程环境（`undefined` 原样继承父进程环境）；凭据策略归调用方——`dsh-subprocess` 的 `scrubbedParentEnv` 是面向隔离启动的共享擦除基底。
+
+## 模型体验
+
+无，因为这是一个客户端进程库；模型运行在 spawn 出的运行时中，其体验由该运行时的 `cordis.yml` 所组合的插件决定。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **无捆绑运行时解析**——调用方显式指定运行时可执行文件；打包可执行文件的发现留在 Python 侧，直到出现 TypeScript 发行版消费方。
+- **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见协议的 [已知限制](../protocol/README.md)）。
+- **没有逐提示词结果或取消**——低层 `prompt()` 只返回入队回执；高层 `run()` 负责从回执收集到 idle，放弃该过程意味着关闭运行时。
+- **客户端→服务端通知与服务端→客户端请求**在协议两端都未实现；传输层为未来审批流保留了承载能力。

package/lib/index.js

@@ -0,0 +1,716 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { JsonRpcLineTransport, JsonRpcResponseError, JsonRpcResponseError as JsonRpcResponseError$1 } from "@deepseek-ai/dsh-sdk-protocol";
+//#region lib/types/dispose.js
+/**
+* Private teardown ladder for the runtime subprocess: stdin EOF (cooperative
+* quiesce), then SIGTERM, then SIGKILL, resolving only after the process has
+* actually exited. The SDK client runs OUTSIDE any harness context, so it
+* cannot ride the `dsh-subprocess` service — this module is the seam's
+* documented exception for SDK-managed transports.
+*
+* @module @deepseek-ai/dsh-sdk-client/dispose
+*/
+/**
+* Race the child's exit against a timer. Neither outcome leaves anything
+* behind on the child: the exit listener is removed on timeout and the timer
+* is cleared on exit, so the ladder's tiers never accumulate listeners.
+*/
+function exitsWithin(child, ms) {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
+	return new Promise((resolve) => {
+		const onExit = () => {
+			clearTimeout(timer);
+			resolve(true);
+		};
+		const timer = setTimeout(() => {
+			child.removeListener("exit", onExit);
+			resolve(false);
+		}, ms).unref();
+		child.once("exit", onExit);
+	});
+}
+/** Force-terminate the runtime and reject if no exit edge arrives within the grace. */
+function forceTerminateWithin(child, ms) {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		let accepted = false;
+		let settled = false;
+		const cleanup = () => {
+			clearTimeout(timer);
+			child.off("exit", onExit);
+			child.off("error", onError);
+		};
+		const settle = (complete) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			complete();
+		};
+		const onExit = () => {
+			settle(resolve);
+		};
+		const onError = (error) => {
+			settle(() => {
+				reject(error);
+			});
+		};
+		child.once("exit", onExit);
+		child.once("error", onError);
+		const timer = setTimeout(() => {
+			const disposition = accepted ? "accepted" : "refused";
+			settle(() => {
+				reject(/* @__PURE__ */ new Error(`runtime process did not exit within ${ms}ms after SIGKILL was ${disposition}`));
+			});
+		}, ms).unref();
+		try {
+			accepted = child.kill("SIGKILL");
+			if (child.exitCode !== null || child.signalCode !== null) settle(resolve);
+		} catch (error) {
+			settle(() => {
+				reject(new Error("SIGKILL failed", { cause: error }));
+			});
+		}
+	});
+}
+/**
+* Tear the runtime down to quiescence, resolving only after exit: close stdin
+* and allow cooperative flush, then use the host's graceful and forced
+* termination semantics. POSIX sends `SIGTERM` before `SIGKILL`; Windows
+* skips directly to forced termination because Node maps both signals to
+* `TerminateProcess`.
+* @param child - the runtime child process to tear down.
+* @param graces - the EOF and termination-confirmation windows (ms).
+* @param platform - the host platform, injectable for unit coverage.
+* @throws When forced termination errors or the child does not report exit
+* within `disposeGraceMs`.
+*/
+async function disposeRuntimeProcess(child, graces, platform = process.platform) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	child.stdin?.end();
+	if (await exitsWithin(child, graces.disposeEofGraceMs)) return;
+	if (platform !== "win32") {
+		child.kill("SIGTERM");
+		if (await exitsWithin(child, graces.disposeGraceMs)) return;
+	}
+	await forceTerminateWithin(child, graces.disposeGraceMs);
+}
+//#endregion
+//#region lib/types/client.js
+/**
+* Low-level JSON-RPC client for a DeepSeek Harness SDK runtime subprocess.
+* {@link HarnessClient} owns the child process: it spawns the runtime, speaks
+* the `@deepseek-ai/dsh-sdk-protocol` wire over the child's stdio, fans
+* server notifications out to subscriptions, and tears the child down to
+* quiescence through a private EOF → SIGTERM → SIGKILL ladder. The design
+* twin is the Python SDK's `HarnessClient` (`python/sdk`); both drive the
+* same runtime protocol. This client runs OUTSIDE any harness context, so it
+* spawns directly rather than through the `dsh-subprocess` service — the
+* seam's documented exception for SDK-managed transports.
+*
+* @module @deepseek-ai/dsh-sdk-client/client
+*/
+/** Retained stderr lines used to diagnose an unexpected runtime death. */
+const STDERR_TAIL_LIMIT = 400;
+/** Grace for the runtime's stdio streams to settle after its exit edge. */
+const STREAM_SETTLE_MS = 100;
+/**
+* The runtime subprocess is gone or unusable: it exited, its stdio closed, or
+* it was never launchable. The message carries the exit code and a stderr
+* tail when available.
+*/
+var TransportClosedError = class extends Error {
+	/** @param message - the failure description, including any stderr tail. */
+	constructor(message) {
+		super(message);
+		this.name = "TransportClosedError";
+	}
+};
+/** A request exceeded {@link HarnessClientOptions.requestTimeoutMs}. */
+var RequestTimeoutError = class extends Error {
+	/** @param message - which method timed out. */
+	constructor(message) {
+		super(message);
+		this.name = "RequestTimeoutError";
+	}
+};
+/**
+* The runtime answered outside its documented protocol (for example a
+* `session/prompt` response without `accepted: true`).
+*/
+var SdkProtocolError = class extends Error {
+	/** @param message - the protocol violation description. */
+	constructor(message) {
+		super(message);
+		this.name = "SdkProtocolError";
+	}
+};
+/** Internal producer side of a public notification subscription. */
+var NotificationSubscriptionImpl = class {
+	state;
+	unsubscribe;
+	constructor(state, unsubscribe) {
+		this.state = state;
+		this.unsubscribe = unsubscribe;
+	}
+	/**
+	* Await the next matching notification.
+	* @returns the notification; after the runtime died, drains what was
+	* already delivered and then rejects; after {@link close}, rejects
+	* immediately (the queue is dropped).
+	*/
+	next() {
+		const queued = this.state.queue.shift();
+		if (queued !== void 0) return Promise.resolve(queued);
+		if (this.state.failure !== void 0) return Promise.reject(this.state.failure);
+		return new Promise((resolve, reject) => {
+			this.state.waiters.push({
+				resolve,
+				reject
+			});
+		});
+	}
+	/**
+	* Drain one already-delivered notification without waiting.
+	* @returns the next queued notification, or `undefined` when none is queued.
+	*/
+	tryNext() {
+		return this.state.queue.shift();
+	}
+	/** Detach from the client; queued items drop and pending waiters reject. */
+	close() {
+		this.unsubscribe();
+		this.state.queue.length = 0;
+		this.fail(new TransportClosedError("notification subscription closed"));
+	}
+	/**
+	* Reject pending and future waits (delivery stops; the first failure wins).
+	* Already-queued notifications remain drainable via {@link next}/{@link tryNext}.
+	* @param error - the terminal failure delivered to waiters.
+	*/
+	fail(error) {
+		this.state.failure ??= error;
+		for (const waiter of this.state.waiters.splice(0)) waiter.reject(this.state.failure);
+	}
+	/**
+	* 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.
+	* @param notification - the wire notification to deliver.
+	*/
+	push(notification) {
+		let matches;
+		try {
+			matches = this.state.filter === void 0 || this.state.filter(notification);
+		} catch (error) {
+			this.unsubscribe();
+			this.fail(error instanceof Error ? error : new Error(String(error)));
+			return;
+		}
+		if (!matches) return;
+		const waiter = this.state.waiters.shift();
+		if (waiter !== void 0) waiter.resolve(notification);
+		else this.state.queue.push(notification);
+	}
+	/**
+	* Iterate notifications until the subscription or runtime closes (the
+	* terminating rejection propagates).
+	* @returns an async iterator over {@link next} results.
+	*/
+	async *[Symbol.asyncIterator]() {
+		for (;;) yield await this.next();
+	}
+};
+/**
+* JSON-RPC client for the DeepSeek Harness SDK runtime over subprocess stdio.
+*
+* The subprocess starts lazily on {@link start} and is owned by this instance
+* until {@link close}, which requests protocol `shutdown` and then walks the
+* shared EOF → SIGTERM → SIGKILL dispose ladder to quiescence. There is no
+* wire-level cancel: a timed-out request stays running server-side until the
+* runtime is closed.
+*/
+var HarnessClient = class {
+	options;
+	child;
+	transport;
+	stderrTail = [];
+	subscriptions = /* @__PURE__ */ new Map();
+	sessionParents = /* @__PURE__ */ new Map();
+	subscriptionSerial = 0;
+	exitCode;
+	spawnError;
+	streamsSettled = Promise.resolve();
+	closeTask;
+	/** @param options - launch spec, complete child environment, and timeouts. */
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* Spawn the runtime subprocess and start reading frames. Idempotent while
+	* the process is live; rejects reuse after {@link close}.
+	*/
+	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,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child = child;
+		child.once("error", (error) => {
+			this.spawnError = error;
+			this.transport?.close();
+			this.failSubscriptions(this.closedError("DeepSeek Harness runtime failed to start"));
+		});
+		/* v8 ignore next */
+		child.stdin.on("error", () => {});
+		let stderrBuffer = "";
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk) => {
+			stderrBuffer += chunk;
+			const newline = stderrBuffer.lastIndexOf("\n");
+			if (newline >= 0) {
+				this.appendStderr(stderrBuffer.slice(0, newline).split("\n"));
+				stderrBuffer = stderrBuffer.slice(newline + 1);
+			}
+		});
+		let signalStreamsSettled;
+		this.streamsSettled = new Promise((resolve) => {
+			signalStreamsSettled = resolve;
+		});
+		const settled = {
+			stderr: false,
+			exited: false
+		};
+		const maybeSettle = () => {
+			if (settled.stderr && settled.exited) signalStreamsSettled();
+		};
+		child.stderr.once("close", () => {
+			if (stderrBuffer.length > 0) this.appendStderr([stderrBuffer]);
+			settled.stderr = true;
+			maybeSettle();
+		});
+		child.once("exit", (code) => {
+			this.exitCode = code;
+			settled.exited = true;
+			maybeSettle();
+			this.failSubscriptions(this.closedError("DeepSeek Harness runtime exited"));
+		});
+		child.once("close", () => {
+			this.transport?.close();
+		});
+		const transport = new JsonRpcLineTransport(child.stdout, child.stdin);
+		transport.onNotification((method, params) => {
+			this.dispatchNotification({
+				method,
+				params
+			});
+		});
+		transport.start();
+		this.transport = transport;
+	}
+	/**
+	* Perform the process-wide handshake.
+	* @param params - workspace cwd plus the provider/model route.
+	* @returns the runtime's wire identity.
+	*/
+	async initialize(params) {
+		const result = await this.request("initialize", { ...params });
+		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,
+			version: result.serverInfo.version
+		} };
+	}
+	/**
+	* Queue one prompt and return its durable inbox identity.
+	* @param sessionId - target session; an unknown id creates it.
+	* @param contentBlocks - the user message, sent verbatim.
+	* @returns the queued message id.
+	*/
+	async prompt(sessionId, contentBlocks) {
+		const params = {
+			sessionId,
+			contentBlocks
+		};
+		const result = await this.request("session/prompt", { ...params });
+		if (!isRecord(result) || typeof result.messageId !== "string") throw new SdkProtocolError(`session/prompt returned no message id: ${JSON.stringify(result)}`);
+		return result.messageId;
+	}
+	/**
+	* Send one JSON-RPC request and await its result.
+	* @param method - the wire method name.
+	* @param params - the params object; omitted params send `{}`.
+	* @param timeoutMs - per-call override of {@link HarnessClientOptions.requestTimeoutMs}.
+	* @returns the raw result; rejects with {@link JsonRpcResponseError} on a
+	* protocol error response, {@link RequestTimeoutError} on timeout, and
+	* {@link TransportClosedError} when the runtime is gone.
+	*/
+	async request(method, params, timeoutMs) {
+		this.start();
+		if (this.exitCode !== void 0 || this.spawnError !== void 0) {
+			await this.settleStreams();
+			throw this.closedError("DeepSeek Harness runtime is not running");
+		}
+		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;
+		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`));
+			}, timeout);
+			try {
+				return await transport.request(method, params ?? {}, abandon.signal);
+			} finally {
+				clearTimeout(timer);
+			}
+		} catch (error) {
+			if (error instanceof JsonRpcResponseError$1 || error instanceof RequestTimeoutError) throw error;
+			await this.settleStreams();
+			throw this.closedError(errorMessage(error));
+		}
+	}
+	/**
+	* Subscribe to server notifications.
+	* @param filter - optional predicate; omitted means every notification.
+	* @returns the subscription handle; close it to stop delivery. After
+	* {@link close} or runtime death the handle is born failed — there is no
+	* producer left, so `next()` rejects instead of waiting forever.
+	*/
+	subscribe(filter) {
+		const id = String(this.subscriptionSerial++);
+		const subscription = new NotificationSubscriptionImpl({
+			queue: [],
+			waiters: [],
+			filter,
+			failure: void 0
+		}, () => {
+			this.subscriptions.delete(id);
+		});
+		if (this.closeTask !== void 0 || this.exitCode !== void 0 || this.spawnError !== void 0) {
+			subscription.fail(this.closedError("DeepSeek Harness runtime closed"));
+			return subscription;
+		}
+		this.subscriptions.set(id, subscription);
+		return subscription;
+	}
+	/**
+	* 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).
+	* @param sessionId - the root session id.
+	* @returns the filtered subscription handle.
+	*/
+	subscribeSessionTree(sessionId) {
+		return this.subscribe((notification) => {
+			const params = notification.params;
+			if (notification.method === "subagent.started" || notification.method === "subagent.finished") {
+				const parentId = params.parentSessionId;
+				if (typeof parentId === "string" && this.isDescendantOf(parentId, sessionId)) return true;
+				return params.childSessionId === sessionId;
+			}
+			const relatedId = params.sessionId;
+			return typeof relatedId === "string" && this.isDescendantOf(relatedId, sessionId);
+		});
+	}
+	/**
+	* Shut the runtime down and reap it: a best-effort protocol `shutdown`
+	* bounded by `shutdownTimeoutMs`, then the shared stdin-EOF → SIGTERM →
+	* SIGKILL ladder until the process actually exited. Idempotent.
+	* @returns settlement of the complete teardown.
+	*/
+	close() {
+		this.closeTask ??= this.performClose();
+		return this.closeTask;
+	}
+	async performClose() {
+		const child = this.child;
+		if (child === void 0) return;
+		try {
+			await this.request("shutdown", void 0, this.options.shutdownTimeoutMs ?? 1e3);
+		} catch (error) {
+			this.appendStderr([`shutdown request failed: ${errorMessage(error)}`]);
+		}
+		await disposeRuntimeProcess(child, {
+			disposeEofGraceMs: this.options.disposeEofGraceMs ?? 6e3,
+			disposeGraceMs: this.options.disposeGraceMs ?? 3e3
+		});
+		this.transport?.close();
+		this.failSubscriptions(this.closedError("DeepSeek Harness runtime closed"));
+	}
+	dispatchNotification(notification) {
+		this.recordSessionRelationship(notification);
+		for (const subscription of this.subscriptions.values()) subscription.push(notification);
+	}
+	recordSessionRelationship(notification) {
+		if (notification.method !== "subagent.started") return;
+		const parentId = notification.params.parentSessionId;
+		const childId = notification.params.childSessionId;
+		if (typeof parentId === "string" && parentId !== "" && typeof childId === "string" && childId !== "" && parentId !== childId) this.sessionParents.set(childId, parentId);
+	}
+	isDescendantOf(sessionId, rootSessionId) {
+		const visited = /* @__PURE__ */ new Set();
+		let current = sessionId;
+		while (!visited.has(current)) {
+			if (current === rootSessionId) return true;
+			visited.add(current);
+			const parent = this.sessionParents.get(current);
+			if (parent === void 0) return false;
+			current = parent;
+		}
+		/* v8 ignore next */
+		return false;
+	}
+	failSubscriptions(error) {
+		for (const subscription of this.subscriptions.values()) subscription.fail(error);
+	}
+	appendStderr(lines) {
+		const kept = lines.filter((line) => line.length > 0);
+		this.stderrTail.push(...kept);
+		if (this.stderrTail.length > STDERR_TAIL_LIMIT) this.stderrTail.splice(0, this.stderrTail.length - STDERR_TAIL_LIMIT);
+	}
+	settleStreams() {
+		return Promise.race([this.streamsSettled, new Promise((resolve) => {
+			setTimeout(resolve, STREAM_SETTLE_MS);
+		})]);
+	}
+	closedError(reason) {
+		const parts = [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")}`);
+		return new TransportClosedError(parts.join("\n"));
+	}
+};
+/**
+* Whether `value` is a plain JSON object (the wire-boundary shape probe).
+* @param value - the wire value to probe.
+* @returns `true` iff `value` is a non-null, non-array object.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The message of a thrown value (the transport only throws `Error`s; `String` covers the rest). */
+function errorMessage(error) {
+	/* v8 ignore next -- the transport and dispose ladder reject only with Errors */
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region lib/types/api.js
+/**
+* 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
+*/
+/**
+* Reusable SDK for running DeepSeek Harness agent turns in a runtime
+* subprocess. The subprocess starts lazily on first use and stays owned by
+* this instance until {@link close}; always close (or `await using`) so the
+* child is reaped.
+*/
+var DeepSeekHarness = class {
+	clientInstance;
+	launch;
+	cwd;
+	provider;
+	model;
+	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());
+		this.provider = options.provider ?? "deepseek-official";
+		this.model = options.model ?? "deepseek-v4-flash";
+		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}.
+	* @returns the client currently owning the runtime subprocess.
+	*/
+	get client() {
+		return this.clientInstance;
+	}
+	/**
+	* 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.
+	* @returns settlement of the (memoized) handshake.
+	*/
+	start() {
+		this.initialized ??= (async () => {
+			try {
+				this.clientInstance.start();
+				await this.clientInstance.initialize({
+					cwd: this.cwd,
+					provider: this.provider,
+					model: this.model,
+					...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);
+				throw error;
+			}
+		})();
+		return this.initialized;
+	}
+	/**
+	* Open a session handle (no wire traffic; the runtime creates the session
+	* on its first prompt).
+	* @param sessionId - explicit id to reuse; omitted mints a fresh one.
+	* @returns the session handle.
+	*/
+	session(sessionId) {
+		return new HarnessSession(this, sessionId ?? `session-${randomUUID().replaceAll("-", "")}`);
+	}
+	/**
+	* Run one prompt on a fresh (or named) session.
+	* @param input - prompt text, or content blocks sent verbatim.
+	* @param options - optional session id and per-notification observer.
+	* @returns the owned activity interval.
+	*/
+	run(input, options) {
+		return this.session(options?.sessionId).run(input, options);
+	}
+	/**
+	* Shut down and reap the runtime subprocess. Idempotent and terminal —
+	* a closed harness no longer retries a failed handshake.
+	* @returns settlement of the complete teardown.
+	*/
+	close() {
+		this.closed = true;
+		return this.clientInstance.close();
+	}
+	/**
+	* `await using` support: {@link close}.
+	* @returns settlement of the teardown.
+	*/
+	[Symbol.asyncDispose]() {
+		return this.close();
+	}
+};
+/**
+* One SDK session: a stable id plus owned activity intervals.
+*/
+var HarnessSession = class {
+	harness;
+	id;
+	/**
+	* @param harness - the owning harness (supplies the client and handshake).
+	* @param id - the wire session id this handle runs on.
+	*/
+	constructor(harness, id) {
+		this.harness = harness;
+		this.id = id;
+	}
+	/**
+	* Queue one prompt, then observe the whole session through its next idle.
+	* @param input - prompt text, or content blocks sent verbatim.
+	* @param options - optional per-notification observer.
+	* @returns the owned activity interval; rejects on transport loss, timeout,
+	* or a protocol error.
+	*/
+	async run(input, options) {
+		await this.harness.start();
+		const client = this.harness.client;
+		const contentBlocks = normalizeInput(input);
+		const events = [];
+		const notifications = [];
+		const subscription = client.subscribeSessionTree(this.id);
+		const collect = (notification) => {
+			if (notification.method === "session.event" && notification.params.sessionId === this.id) {
+				const event = validatedSessionEvent(notification.params.event);
+				notifications.push(notification);
+				options?.onNotification?.(notification);
+				events.push(event);
+				return;
+			}
+			notifications.push(notification);
+			options?.onNotification?.(notification);
+		};
+		try {
+			const messageId = await client.prompt(this.id, contentBlocks);
+			let received = false;
+			while (true) {
+				const notification = await subscription.next();
+				if (!received) {
+					if (notification.method !== "session.event" || notification.params.sessionId !== this.id || !isInboxReceipt(notification.params.event, messageId)) continue;
+					received = true;
+				}
+				collect(notification);
+				if (notification.method === "session.status" && notification.params.sessionId === this.id && notification.params.status === "idle") break;
+			}
+		} finally {
+			subscription.close();
+		}
+		return {
+			sessionId: this.id,
+			finalResponse: finalResponse(events),
+			events,
+			notifications
+		};
+	}
+};
+/**
+* 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.
+*/
+function normalizeInput(input) {
+	return typeof input === "string" ? [{
+		type: "text",
+		text: input
+	}] : input;
+}
+/** 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)}`);
+	if (value.type === "assistant/message") {
+		const message = isRecord(value.data) ? value.data.message : void 0;
+		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)}`);
+	}
+	return value;
+}
+/** Whether a raw session event is the durable enqueue receipt for `messageId`. */
+function isInboxReceipt(value, messageId) {
+	if (!isRecord(value) || value.type !== "agent/inbox/spliced" || !isRecord(value.data)) return false;
+	const inserted = value.data.inserted;
+	return Array.isArray(inserted) && inserted.some((message) => isRecord(message) && message.id === messageId);
+}
+/**
+* Extract the concatenated text of the last assistant message.
+* @param events - the activity interval's `session.event` payloads in wire order.
+* @returns the final response text, or `''` when no assistant message exists.
+*/
+function finalResponse(events) {
+	for (let index = events.length - 1; index >= 0; index--) {
+		const event = events[index];
+		if (event?.type !== "assistant/message") continue;
+		return event.data.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+	}
+	return "";
+}
+//#endregion
+export { DeepSeekHarness, HarnessClient, HarnessSession, JsonRpcResponseError, RequestTimeoutError, SdkProtocolError, TransportClosedError };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-sdk-client`.
+* @module @deepseek-ai/dsh-sdk-client/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-sdk-client";
+/** Cordis companion plugin name. */
+const name = "sdk-client-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this client library runs outside any harness context
+* (its peer is a separate runtime process); the runtime's own packages own
+* the event-stream relations.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/api.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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';
+/**
+ * Reusable SDK for running DeepSeek Harness agent turns in a runtime
+ * subprocess. The subprocess starts lazily on first use and stays owned by
+ * this instance until {@link close}; always close (or `await using`) so the
+ * child is reaped.
+ */
+export declare class DeepSeekHarness implements AsyncDisposable {
+    private clientInstance;
+    private readonly launch;
+    private readonly cwd;
+    private readonly provider;
+    private readonly model;
+    private readonly maxTokens;
+    private initialized;
+    private closed;
+    /** @param options - runtime launch spec plus the session route (cwd/provider/model). */
+    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}.
+     * @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.
+     * @returns settlement of the (memoized) handshake.
+     */
+    start(): Promise<void>;
+    /**
+     * Open a session handle (no wire traffic; the runtime creates the session
+     * on its first prompt).
+     * @param sessionId - explicit id to reuse; omitted mints a fresh one.
+     * @returns the session handle.
+     */
+    session(sessionId?: string): HarnessSession;
+    /**
+     * Run one prompt on a fresh (or named) session.
+     * @param input - prompt text, or content blocks sent verbatim.
+     * @param options - optional session id and per-notification observer.
+     * @returns the owned activity interval.
+     */
+    run(input: string | ContentBlock[], options?: RunOptions): Promise<RunResult>;
+    /**
+     * Shut down and reap the runtime subprocess. Idempotent and terminal —
+     * a closed harness no longer retries a failed handshake.
+     * @returns settlement of the complete teardown.
+     */
+    close(): Promise<void>;
+    /**
+     * `await using` support: {@link close}.
+     * @returns settlement of the teardown.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** Per-run options: target session and streaming observer. */
+export interface RunOptions {
+    /** Session id to run on; omitted mints a fresh session per call. */
+    sessionId?: string;
+    /** Observer invoked with every notification for this session tree, in wire order. */
+    onNotification?: (notification: HarnessNotification) => void;
+}
+/**
+ * One SDK session: a stable id plus owned activity intervals.
+ */
+export declare class HarnessSession {
+    readonly harness: DeepSeekHarness;
+    readonly id: string;
+    /**
+     * @param harness - the owning harness (supplies the client and handshake).
+     * @param id - the wire session id this handle runs on.
+     */
+    constructor(harness: DeepSeekHarness, id: string);
+    /**
+     * Queue one prompt, then observe the whole session through its next idle.
+     * @param input - prompt text, or content blocks sent verbatim.
+     * @param options - optional per-notification observer.
+     * @returns the owned activity interval; rejects on transport loss, timeout,
+     * or a protocol error.
+     */
+    run(input: string | ContentBlock[], 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[];
+/**
+ * Extract the concatenated text of the last assistant message.
+ * @param events - the activity interval's `session.event` payloads in wire order.
+ * @returns the final response text, or `''` when no assistant message exists.
+ */
+export declare function finalResponse(events: SessionEvent[]): string;
+//# sourceMappingURL=api.d.ts.map

package/lib/types/client.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Low-level JSON-RPC client for a DeepSeek Harness SDK runtime subprocess.
+ * {@link HarnessClient} owns the child process: it spawns the runtime, speaks
+ * the `@deepseek-ai/dsh-sdk-protocol` wire over the child's stdio, fans
+ * server notifications out to subscriptions, and tears the child down to
+ * quiescence through a private EOF → SIGTERM → SIGKILL ladder. The design
+ * twin is the Python SDK's `HarnessClient` (`python/sdk`); both drive the
+ * same runtime protocol. This client runs OUTSIDE any harness context, so it
+ * spawns directly rather than through the `dsh-subprocess` service — the
+ * seam's documented exception for SDK-managed transports.
+ *
+ * @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 { HarnessClientOptions, HarnessNotification, NotificationFilter } from './types.ts';
+/**
+ * The runtime subprocess is gone or unusable: it exited, its stdio closed, or
+ * it was never launchable. The message carries the exit code and a stderr
+ * tail when available.
+ */
+export declare class TransportClosedError extends Error {
+    /** @param message - the failure description, including any stderr tail. */
+    constructor(message: string);
+}
+/** A request exceeded {@link HarnessClientOptions.requestTimeoutMs}. */
+export declare class RequestTimeoutError extends Error {
+    /** @param message - which method timed out. */
+    constructor(message: string);
+}
+/**
+ * The runtime answered outside its documented protocol (for example a
+ * `session/prompt` response without `accepted: true`).
+ */
+export declare class SdkProtocolError extends Error {
+    /** @param message - the protocol violation description. */
+    constructor(message: string);
+}
+/** One client-side notification stream returned by {@link HarnessClient.subscribe}. */
+export interface NotificationSubscription extends AsyncIterable<HarnessNotification> {
+    /**
+     * Await the next matching notification.
+     * @returns the notification; after the runtime died, drains what was
+     * already delivered and then rejects; after {@link close}, rejects
+     * immediately (the queue is dropped).
+     */
+    next(): Promise<HarnessNotification>;
+    /**
+     * Drain one already-delivered notification without waiting.
+     * @returns the next queued notification, or `undefined` when none is queued.
+     */
+    tryNext(): HarnessNotification | undefined;
+    /** Detach from the client; queued items drop and pending waiters reject. */
+    close(): void;
+}
+/**
+ * JSON-RPC client for the DeepSeek Harness SDK runtime over subprocess stdio.
+ *
+ * The subprocess starts lazily on {@link start} and is owned by this instance
+ * until {@link close}, which requests protocol `shutdown` and then walks the
+ * shared EOF → SIGTERM → SIGKILL dispose ladder to quiescence. There is no
+ * wire-level cancel: a timed-out request stays running server-side until the
+ * runtime is closed.
+ */
+export declare class HarnessClient {
+    readonly options: HarnessClientOptions;
+    private child;
+    private transport;
+    private readonly stderrTail;
+    private readonly subscriptions;
+    private readonly sessionParents;
+    private subscriptionSerial;
+    private exitCode;
+    private spawnError;
+    private streamsSettled;
+    private closeTask;
+    /** @param options - launch spec, complete child environment, and timeouts. */
+    constructor(options: HarnessClientOptions);
+    /**
+     * Spawn the runtime subprocess and start reading frames. Idempotent while
+     * the process is live; rejects reuse after {@link close}.
+     */
+    start(): void;
+    /**
+     * Perform the process-wide handshake.
+     * @param params - workspace cwd plus the provider/model route.
+     * @returns the runtime's wire identity.
+     */
+    initialize(params: InitializeParams): Promise<InitializeResult>;
+    /**
+     * Queue one prompt and return its durable inbox identity.
+     * @param sessionId - target session; an unknown id creates it.
+     * @param contentBlocks - the user message, sent verbatim.
+     * @returns the queued message id.
+     */
+    prompt(sessionId: string, contentBlocks: ContentBlock[]): Promise<string>;
+    /**
+     * Send one JSON-RPC request and await its result.
+     * @param method - the wire method name.
+     * @param params - the params object; omitted params send `{}`.
+     * @param timeoutMs - per-call override of {@link HarnessClientOptions.requestTimeoutMs}.
+     * @returns the raw result; rejects with {@link JsonRpcResponseError} on a
+     * protocol error response, {@link RequestTimeoutError} on timeout, and
+     * {@link TransportClosedError} when the runtime is gone.
+     */
+    request(method: string, params?: object, timeoutMs?: number): Promise<unknown>;
+    /**
+     * Subscribe to server notifications.
+     * @param filter - optional predicate; omitted means every notification.
+     * @returns the subscription handle; close it to stop delivery. After
+     * {@link close} or runtime death the handle is born failed — there is no
+     * producer left, so `next()` rejects instead of waiting forever.
+     */
+    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).
+     * @param sessionId - the root session id.
+     * @returns the filtered subscription handle.
+     */
+    subscribeSessionTree(sessionId: string): NotificationSubscription;
+    /**
+     * Shut the runtime down and reap it: a best-effort protocol `shutdown`
+     * bounded by `shutdownTimeoutMs`, then the shared stdin-EOF → SIGTERM →
+     * SIGKILL ladder until the process actually exited. Idempotent.
+     * @returns settlement of the complete teardown.
+     */
+    close(): Promise<void>;
+    private performClose;
+    private dispatchNotification;
+    private recordSessionRelationship;
+    private isDescendantOf;
+    private failSubscriptions;
+    private appendStderr;
+    private settleStreams;
+    private closedError;
+}
+/**
+ * Whether `value` is a plain JSON object (the wire-boundary shape probe).
+ * @param value - the wire value to probe.
+ * @returns `true` iff `value` is a non-null, non-array object.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=client.d.ts.map

package/lib/types/dispose.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Private teardown ladder for the runtime subprocess: stdin EOF (cooperative
+ * quiesce), then SIGTERM, then SIGKILL, resolving only after the process has
+ * actually exited. The SDK client runs OUTSIDE any harness context, so it
+ * cannot ride the `dsh-subprocess` service — this module is the seam's
+ * documented exception for SDK-managed transports.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/dispose
+ */
+import type { ChildProcess } from 'node:child_process';
+/**
+ * Tear the runtime down to quiescence, resolving only after exit: close stdin
+ * and allow cooperative flush, then use the host's graceful and forced
+ * termination semantics. POSIX sends `SIGTERM` before `SIGKILL`; Windows
+ * skips directly to forced termination because Node maps both signals to
+ * `TerminateProcess`.
+ * @param child - the runtime child process to tear down.
+ * @param graces - the EOF and termination-confirmation windows (ms).
+ * @param platform - the host platform, injectable for unit coverage.
+ * @throws When forced termination errors or the child does not report exit
+ * within `disposeGraceMs`.
+ */
+export declare function disposeRuntimeProcess(child: ChildProcess, graces: {
+    disposeEofGraceMs: number;
+    disposeGraceMs: number;
+}, platform?: NodeJS.Platform): Promise<void>;
+//# sourceMappingURL=dispose.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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;
+ * `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`.
+ *
+ * @module @deepseek-ai/dsh-sdk-client
+ */
+export { DeepSeekHarness, HarnessSession } from './api.ts';
+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';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-sdk-client`.
+ * @module @deepseek-ai/dsh-sdk-client/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sdk-client-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Types for the TypeScript SDK client: launch options, notification shapes,
+ * and owned activity results.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/types
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** One server-to-client notification as received off the wire. */
+export interface HarnessNotification {
+    /** The JSON-RPC notification method name. */
+    method: string;
+    /** The raw params object; see `HarnessSdkNotificationMap` for the shapes per method. */
+    params: Record<string, unknown>;
+}
+/** Predicate deciding whether a subscription receives a notification. */
+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;
+    /**
+     * The complete child environment. `undefined` inherits the parent env
+     * verbatim; passing an object replaces it entirely, so callers own
+     * credential policy (see `scrubbedParentEnv` in `@deepseek-ai/dsh-subprocess`
+     * for the shared scrub-then-merge base).
+     */
+    env?: NodeJS.ProcessEnv;
+    /** 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). */
+    shutdownTimeoutMs?: number;
+    /** Grace (ms) for the runtime's stdin-EOF quiesce during `close()` (default 6000). */
+    disposeEofGraceMs?: number;
+    /** Termination confirmation window (ms) after SIGTERM/SIGKILL during `close()` (default 3000). */
+    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()`). */
+    cwd?: string;
+    /** Provider route for SDK-created agents (default `deepseek-official`). */
+    provider?: string;
+    /** Model for SDK-created agents (default `deepseek-v4-flash`). */
+    model?: string;
+    /** Maximum output tokens for each conversation-model request. */
+    maxTokens?: number;
+}
+/** One owned session activity interval, from enqueue receipt through idle. */
+export interface RunResult {
+    /** The session the activity ran on. */
+    sessionId: string;
+    /** Concatenated text of the interval's last assistant message (empty when none). */
+    finalResponse: string;
+    /** Every `session.event` payload for the root session, in wire order. */
+    events: SessionEvent[];
+    /** Every notification for the root session and discovered descendants, in wire order. */
+    notifications: HarnessNotification[];
+}
+/** Re-exported content-block alias so SDK callers need no extra import. */
+export type { ContentBlock };
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "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.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/scaffold/client"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}