@deepseek-ai/dsh-subagent-dsh-sdk 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/subagent/subagent-dsh-sdk/README.md
+README.md: 0bbcfa105ecf024a2492d39d3bf8d28956110050
+README.zh.md: 8c8551f85951aa8475ab2ce95771e4d54e0ed89a

package/README.md

@@ -0,0 +1,97 @@
+# @deepseek-ai/dsh-subagent-dsh-sdk
+
+English | [中文](README.zh.md)
+
+The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the [TypeScript SDK client](../../scaffold/client/README.md). It is the second out-of-process backend beside [`subagent-acp`](../subagent-acp/README.md), differing in the wire and the child contract: the ACP backend drives any Agent Client Protocol agent; this backend drives specifically a harness SDK runtime (`dsh-jsonrpc-agent` bin or packaged executable), so the child is a full peer harness — own `cordis.yml`-decided composition, session persistence, model route, and tools.
+
+## Start and ownership
+
+`start(request)` resolves the child's working directory, spawns the runtime through `DeepSeekHarness`, and completes the `initialize` handshake (with the configured `provider`/`model` route and optional `maxTokens` output cap) before it fulfills. Fulfillment therefore means the child runtime is ready and ownership has transferred to the caller. A spawn, handshake, or pre-publication cancellation failure rejects only after the subprocess has been reaped; a working-directory resolution failure rejects before anything is spawned.
+
+The working directory resolves exactly like the ACP backend, through the seam's shared out-of-process helpers ([`dsh-subagent`](../subagent/README.md)): the configured `cwd` override when set (validated once at load), else the delegating parent session's cwd — never the server process's own cwd. The resolved path becomes the child process cwd and the workspace cwd of its SDK session.
+
+The returned run id is minted in the parent namespace; the child runtime's session id exists only inside the child process. After publication the provider owns one SDK activity and reads the child's answer from its session events: the last complete `assistant/message`, or the `text-delta` stream accumulated before the activity was cut short — a partial answer survives cancel and error paths.
+
+`dispose()` is idempotent: it settles the result locally as `aborted` (there is no wire-level prompt cancel), then closes the runtime — a bounded protocol `shutdown` request followed by the shared stdin-EOF → SIGTERM → SIGKILL ladder to actual exit.
+
+## Stop-reason mapping
+
+The SDK client returns an owned child activity rather than a prompt result. The provider reads the last durable `turn/end` inside that activity and maps it into the seam vocabulary: `completed` → `completed`, `max-tokens` → `max-tokens`, `aborted` → `aborted`; everything else — `error`, `interrupted`, `disposed`, a future variant, or an activity with no turn — maps to `error`, so an unclean stop is never reported as success. Transport-level failures after publication flatten to `stopReason: 'error'` through the `onError` diagnostic sink (wired to `ctx.logger.warn`); the seam contract forbids `result` rejecting.
+
+## Capabilities and context
+
+The provider advertises no start-time capabilities (`outputSchema`/`depthLimit`/`toolFilter`/`persona` all false) and `inheritsParentContext: false`: the child is a fresh runtime in another process, and the only parent-derived input is the workspace cwd. `dsh-tool-subagent` deployments over this provider set `maxDepth: 'provider-managed'` — the child harness owns its own recursion budget.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `providerName` | `dsh-sdk` | Registry name on `ctx.subagents`. |
+| `command` | required | Executable spawned per run (the child runtime bin or packaged exe). |
+| `args` | `[]` | Command arguments (typically the child's `cordis.yml` path). |
+| `cwd` | parent session cwd | Working-directory override; same validation as [`subagent-acp`](../subagent-acp/README.md). |
+| `provider` | `deepseek-official` | Provider route sent in the child's `initialize`. |
+| `model` | `deepseek-v4-flash` | Model sent in the child's `initialize`. |
+| `maxTokens` | adapter/provider route default | Per-request output-token cap sent in the child's `initialize`; it applies to the child root agent and its in-process descendants. |
+| `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment (e.g. the child's own `DEEPSEEK_API_KEY`, or `DSH_CORDIS_CONFIG`). |
+| `shutdownTimeoutMs` | `1000` | Bound on the protocol `shutdown` exchange during dispose. |
+| `disposeEofGraceMs` | `6000` | Grace after stdin EOF before platform termination. |
+| `disposeGraceMs` | `3000` | Exit-confirmation grace after termination; POSIX also waits this long after SIGTERM before SIGKILL. |
+
+```yaml
+- id: subagent-dsh-sdk
+  name: '@deepseek-ai/dsh-subagent-dsh-sdk'
+  config:
+    providerName: dsh-sdk
+    command: node
+    args: ['./packages/examples/jsonrpc-demo/lib/bin.js', './examples/jsonrpc-agent/cordis.yml']
+    maxTokens: 49152
+    env:
+      DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
+- id: tool-subagent
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config: { provider: dsh-sdk, toolName: subagent, maxDepth: 'provider-managed' }
+```
+
+## Process boundary
+
+The child environment is the [`dsh-subprocess`](../../subprocess/README.md) seam's `scrubbedParentEnv()` base — ambient credential-shaped and `DSH_*` names dropped — with explicit `config.env` values merged after the scrub. The child is spawned by the SDK client rather than through `ctx.subprocess` (the subprocess README's documented exception for SDK-managed transports), which is why this backend applies the scrub itself. The JSON-RPC wire is the real serialization boundary.
+
+The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
+
+## Model Experience
+
+### Child-agent request
+
+#### What the model sees
+
+The child runtime's model receives the standalone task as its user message plus that runtime's own configured system prompt, tools, and fresh session. It receives no parent conversation. This provider advertises no optional start-time capabilities, so the local service rejects requests for persona, tool filtering, depth enforcement, or structured output instead of silently omitting them.
+
+#### Token effect
+
+The child pays for an independent full context and its own multi-step history. These tokens never enter the parent's context.
+
+#### KV Cache effect
+
+Independent of the parent request cache. Each SDK child can reuse only prefixes identical under its own provider, model, composition, and history; child steps otherwise grow append-only.
+
+### Parent tool result, indirectly
+
+#### What the model sees
+
+Through `dsh-tool-subagent`, the parent receives only the child's final assistant text (or accumulated partial text) or that consumer's exact stop-reason error, not intermediate messages or tool traffic.
+
+#### Token effect
+
+Parent input grows only by the final result or error, which is data-dependent and retained until compaction. This provider adds no parent schema itself.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **A fresh runtime process per run** — no pooling; a harness runtime boots a full plugin tree, so per-run spawn cost is higher than the ACP backend's typical child.
+- **No optional start-time capabilities** — the parent cannot enforce `outputSchema`, depth, tool filters, or persona inside the child process; configure the child's own `cordis.yml` instead.
+- **The child's transcript stays in the child's own session root** — the parent log records only the delegation tool call/result (the seam's child-isolation rule); the streamed `session.event` channel is consumed for output extraction, not bridged into the parent log.
+- **Local child processes only** — the resolved cwd is a local path; a remote runtime would need its own backend.

package/README.zh.md

@@ -0,0 +1,97 @@
+# @deepseek-ai/dsh-subagent-dsh-sdk
+
+[English](README.md) | 中文
+
+SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程约定：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
+
+## 启动与所有权
+
+`start(request)` 先解析子进程工作目录，通过 `DeepSeekHarness` spawn 运行时，并在履行前完成 `initialize` 握手（携带配置的 `provider`/`model` 路由及可选的 `maxTokens` 输出上限）。因此，履行意味着子运行时已就绪、所有权已移交给调用方。spawn、握手或发布前取消失败时，只会在子进程被回收后拒绝；工作目录解析失败则会在尚未 spawn 任何内容时拒绝。
+
+工作目录的解析与 ACP 后端完全一致，并使用 seam 共享的进程外辅助工具（[`dsh-subagent`](../subagent/README.md)）：设置了 `cwd` 覆盖值时使用该值（加载时校验一次），否则使用发起委派的父会话 cwd，绝不使用服务器进程自身的 cwd。解析出的路径同时成为子进程 cwd 和其 SDK 会话的工作区 cwd。
+
+返回的 run id 在父级命名空间中生成；子运行时的会话 id 只存在于子进程内部。发布后，提供方拥有一段 SDK 活动，并从子会话事件中读取答案：最后一条完整的 `assistant/message`，或该活动中断前已经累积的 `text-delta` 流；部分答案在取消和错误路径上都得以保留。
+
+`dispose()`（资源释放）是幂等的：先在本地把结果确定为 `aborted`（协议层面没有提示词取消机制），再关闭运行时，即先发出一次有界的协议 `shutdown` 请求，随后通过共享的 stdin-EOF → SIGTERM → SIGKILL 阶梯使进程实际退出。
+
+## 停止原因映射
+
+SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个已持久化的 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 约定禁止 `result` 被拒绝。
+
+## 能力与上下文
+
+Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilter`/`persona` 全为 false），且 `inheritsParentContext: false`：子进程是另一进程里的全新运行时，唯一来自父方的输入是工作区 cwd。基于本 provider 的 `dsh-tool-subagent` 部署应设置 `maxDepth: 'provider-managed'`——子 harness 拥有自己的递归预算。
+
+## 配置
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `providerName` | `dsh-sdk` | `ctx.subagents` 上的注册名。 |
+| `command` | 必填 | 每次运行时 spawn 的可执行文件（子运行时 bin 或打包后的可执行文件）。 |
+| `args` | `[]` | 命令参数（通常是子进程的 `cordis.yml` 路径）。 |
+| `cwd` | 父会话 cwd | 工作目录覆盖；校验规则与 [`subagent-acp`](../subagent-acp/README.md) 相同。 |
+| `provider` | `deepseek-official` | 写入子进程 `initialize` 的提供方路由。 |
+| `model` | `deepseek-v4-flash` | 写入子进程 `initialize` 的模型。 |
+| `maxTokens` | 适配器／提供方路由默认值 | 写入子进程 `initialize` 的单次请求输出 token 上限；对子运行时的根 agent 及其进程内后代生效。 |
+| `env` | `{}` | 在凭据擦除后的父环境之上叠加的显式子环境（例如子进程自己的 `DEEPSEEK_API_KEY`，或 `DSH_CORDIS_CONFIG`）。 |
+| `shutdownTimeoutMs` | `1000` | dispose 期间协议 `shutdown` 交换的时限。 |
+| `disposeEofGraceMs` | `6000` | stdin EOF 之后、平台终止之前的宽限。 |
+| `disposeGraceMs` | `3000` | 终止后的退出确认窗口；POSIX 在 SIGTERM 之后、SIGKILL 之前也等待同样时长。 |
+
+```yaml
+- id: subagent-dsh-sdk
+  name: '@deepseek-ai/dsh-subagent-dsh-sdk'
+  config:
+    providerName: dsh-sdk
+    command: node
+    args: ['./packages/examples/jsonrpc-demo/lib/bin.js', './examples/jsonrpc-agent/cordis.yml']
+    maxTokens: 49152
+    env:
+      DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
+- id: tool-subagent
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config: { provider: dsh-sdk, toolName: subagent, maxDepth: 'provider-managed' }
+```
+
+## 进程边界
+
+子进程环境以 [`dsh-subprocess`](../../subprocess/README.md) seam 的 `scrubbedParentEnv()` 为基础，先移除疑似凭据和名称为 `DSH_*` 的环境变量，再合并显式 `config.env` 值。子进程由 SDK 客户端 spawn，而不是经由 `ctx.subprocess` spawn（这是 subprocess README 中记录的 SDK 托管传输例外），因此本后端会自行执行环境清理。JSON-RPC 协议格式才是真正的序列化边界。
+
+本包没有默认导出。否则 Cordis loader 解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
+
+## 模型体验
+
+### 子 agent 请求
+
+#### 模型看到的内容
+
+子运行时的模型会收到作为用户消息的独立任务，以及该运行时自身配置的系统提示词、工具和全新会话。它不会收到父级对话。本提供方不声明可选的启动时能力，因此本地服务会拒绝要求 persona、工具过滤、深度强制或结构化输出的请求，而不是静默省略这些要求。
+
+#### Token 影响
+
+子运行时会为独立的完整上下文及其多步骤历史消耗 token。这些 token 绝不会进入父级上下文。
+
+#### KV Cache 影响
+
+与父级请求缓存相互独立。每个 SDK 子进程只能复用其自身提供方、模型、组合和历史均相同时的前缀；除此之外，子 agent 的步骤仅追加增长。
+
+### 父级工具结果（间接）
+
+#### 模型看到的内容
+
+经由 `dsh-tool-subagent`，父级只会收到子运行时最终的 assistant 文本（或累积的部分文本），或该消费方给出的精确停止原因错误；不会收到中间消息或工具流量。
+
+#### Token 影响
+
+父级输入只增加最终结果或错误，其大小取决于数据，并保留到压缩（compaction）为止。本提供方自身不会向父级添加任何 schema。
+
+#### KV Cache 影响
+
+仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **每次运行都使用全新的运行时进程**：不使用进程池；harness 运行时需要启动完整的插件树，因此每次运行的 spawn 成本高于 ACP 后端通常使用的子进程。
+- **不支持可选的启动时能力**：父级无法在子进程内强制执行 `outputSchema`、深度限制、工具过滤或 persona；应改为配置子进程自身的 `cordis.yml`。
+- **子进程的 transcript（文本记录）保留在其自身的会话根目录中**：父级日志只记录委派工具调用／结果（seam 的子级隔离规则）；流式 `session.event` 通道只用于提取输出，不会桥接到父级日志中。
+- **仅支持本地子进程**：解析出的 cwd 是本地路径；远程运行时需要独立的后端。

package/lib/index.js

@@ -0,0 +1,222 @@
+import z from "@deepseek-ai/schemastery";
+import { NO_START_CAPABILITIES, assertPositiveFinite, resolveChildCwd, settleRunResult, subprocessRunHandle, validateConfiguredCwd } from "@deepseek-ai/dsh-subagent";
+import { randomUUID } from "node:crypto";
+import { DeepSeekHarness } from "@deepseek-ai/dsh-sdk-client";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
+//#region lib/types/run.js
+/**
+* Fresh-process SDK subagent client. Drives one child DeepSeek Harness
+* runtime over stdio JSON-RPC through `@deepseek-ai/dsh-sdk-client` and owns
+* cancellation and quiescent disposal. Structure mirrors the ACP backend
+* (`@deepseek-ai/dsh-subagent-acp`): publish after the child handshake,
+* flatten child failures into stop reasons, tear down to quiescence. The
+* child is spawned BY the SDK client rather than through `ctx.subprocess` —
+* the subprocess seam's documented exception for SDK-managed transports —
+* so this driver applies the seam's shared env scrub itself.
+*
+* @module @deepseek-ai/dsh-subagent-dsh-sdk/run
+*/
+/** EOF grace for child flush and nested-process teardown; wider than the signal grace below. */
+const DEFAULT_DISPOSE_EOF_GRACE_MS = 6e3;
+/** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
+const DEFAULT_DISPOSE_GRACE_MS = 3e3;
+/** Default bound on the protocol `shutdown` exchange during dispose. */
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e3;
+/**
+* Map a child turn-end reason to a harness {@link SubagentStopReason}.
+* @param reason - the owned child run's final durable turn reason, or
+* `undefined` when it settled without running a turn.
+* @returns the harness equivalent; an absent or unknown reason maps to
+* `error`, so an unclean stop is never reported as `completed`.
+*/
+function sdkStopReason(reason) {
+	switch (reason?.kind) {
+		case "completed": return "completed";
+		case "max-tokens": return "max-tokens";
+		case "aborted": return "aborted";
+		default: return "error";
+	}
+}
+/** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
+function toError(value) {
+	/* v8 ignore next */
+	return value instanceof Error ? value : new Error(String(value));
+}
+/**
+* Start and publish one SDK runtime child after its `initialize` handshake.
+* Child failures resolve through the run result; startup failures reject
+* after process reap. Disposal shuts the runtime down and reaps it.
+* @param request - the start request; its signal is the cancellation channel.
+* @param spec - the resolved spawn spec: command/args/cwd, the child's
+* provider/model route, env, timeouts, and the optional error sink.
+* @returns the ready run handle for the child subprocess.
+*/
+async function startSdkRun(request, spec) {
+	if (request.signal.aborted) throw new Error("subagent request was aborted before the SDK child started");
+	const id = SessionId(randomUUID());
+	const harness = new DeepSeekHarness({
+		launch: {
+			command: spec.command,
+			args: spec.args,
+			cwd: spec.cwd,
+			env: {
+				...scrubbedParentEnv(),
+				...spec.env
+			},
+			shutdownTimeoutMs: spec.shutdownTimeoutMs,
+			disposeEofGraceMs: spec.disposeEofGraceMs,
+			disposeGraceMs: spec.disposeGraceMs
+		},
+		cwd: spec.cwd,
+		provider: spec.provider,
+		model: spec.model,
+		...spec.maxTokens === void 0 ? {} : { maxTokens: spec.maxTokens }
+	});
+	const flags = { cancelled: false };
+	let signalCancelSettled;
+	const cancelSettled = new Promise((resolve) => {
+		signalCancelSettled = resolve;
+	});
+	const requestCancel = () => {
+		if (flags.cancelled) return;
+		flags.cancelled = true;
+		signalCancelSettled();
+	};
+	const onAbort = () => {
+		requestCancel();
+	};
+	request.signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		await Promise.race([harness.start(), cancelSettled.then(() => {
+			throw new Error("subagent cancelled before the SDK child initialized");
+		})]);
+		/* v8 ignore next */
+		if (flags.cancelled) throw new Error("subagent cancelled before the SDK child initialized");
+	} catch (error) {
+		request.signal.removeEventListener("abort", onAbort);
+		await harness.close();
+		if (flags.cancelled) throw new Error("subagent request was aborted before the SDK child started");
+		throw toError(error);
+	}
+	const childSessionId = `session-${randomUUID().replaceAll("-", "")}`;
+	let lastMessage;
+	const partial = [];
+	const observe = (notification) => {
+		if (notification.method !== "session.event" || notification.params.sessionId !== childSessionId) return;
+		const event = notification.params.event;
+		if (event.type === "assistant/chunk" && event.data.chunk.type === "text-delta") partial.push(event.data.chunk.text);
+		else if (event.type === "assistant/message") lastMessage = event.data.message.content;
+	};
+	const collectOutput = () => {
+		if (lastMessage !== void 0) return lastMessage;
+		const text = partial.join("");
+		return text.length > 0 ? [{
+			type: "text",
+			text
+		}] : [];
+	};
+	return subprocessRunHandle({
+		id,
+		result: settleRunResult({
+			attempt: async () => {
+				const turn = await Promise.race([harness.session(childSessionId).run(request.prompt, { onNotification: observe }), cancelSettled.then(() => "cancelled")]);
+				if (turn === "cancelled") return {
+					output: collectOutput(),
+					stopReason: "aborted"
+				};
+				const lastEnd = turn.events.findLast((event) => event.type === "turn/end");
+				return {
+					output: collectOutput(),
+					stopReason: sdkStopReason(lastEnd?.data.reason)
+				};
+			},
+			collectOutput,
+			cancelled: () => flags.cancelled,
+			onError: spec.onError,
+			signal: request.signal,
+			onAbort
+		}),
+		signal: request.signal,
+		onAbort,
+		requestCancel,
+		teardown: () => harness.close()
+	});
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Out-of-process SDK subagent backend. Each child is a complete DeepSeek
+* Harness runtime in its own process — own `cordis.yml`-decided composition,
+* session, model route, and tools — driven over stdio JSON-RPC through the
+* TypeScript SDK client, so it shares no Cordis context and advertises no
+* parent-enforced start capabilities; the ONE thing it reads off
+* `request.parent` is the session's workspace cwd. This plugin uses named
+* exports only; a default would hide its loader metadata (see
+* `docs/postmortem/0001-acp-default-export-drops-inject.md`).
+* @module @deepseek-ai/dsh-subagent-dsh-sdk
+*/
+const name = "subagent-dsh-sdk";
+const inject = ["subagents"];
+const Config = z.object({
+	providerName: z.string().default("dsh-sdk"),
+	command: z.string().required(),
+	args: z.array(z.string()).default([]),
+	cwd: z.string(),
+	provider: z.string().default("deepseek-official"),
+	model: z.string().default("deepseek-v4-flash"),
+	maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER),
+	env: z.dict(z.string()).default({}),
+	shutdownTimeoutMs: z.number().default(DEFAULT_SHUTDOWN_TIMEOUT_MS),
+	disposeEofGraceMs: z.number().default(DEFAULT_DISPOSE_EOF_GRACE_MS),
+	disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS)
+});
+/**
+* The SDK provider. Advertises NO start-time capabilities: an out-of-process
+* child cannot honor `outputSchema`/`maxDepth`/`toolFilter`/`persona` (the
+* service rejects a request needing any of them before `start` runs).
+*/
+var SdkProvider = class {
+	name;
+	ctx;
+	config;
+	capabilities = NO_START_CAPABILITIES;
+	inheritsParentContext = false;
+	constructor(name, ctx, config) {
+		this.name = name;
+		this.ctx = ctx;
+		this.config = config;
+	}
+	start(request) {
+		return startSdkRun(request, {
+			command: this.config.command,
+			args: this.config.args,
+			cwd: resolveChildCwd("subagent-dsh-sdk", this.config.cwd, request.parent.session.header.cwd),
+			provider: this.config.provider,
+			model: this.config.model,
+			...this.config.maxTokens === void 0 ? {} : { maxTokens: this.config.maxTokens },
+			env: this.config.env,
+			shutdownTimeoutMs: this.config.shutdownTimeoutMs,
+			disposeEofGraceMs: this.config.disposeEofGraceMs,
+			disposeGraceMs: this.config.disposeGraceMs,
+			onError: (error, stopReason) => {
+				this.ctx.logger.warn(`subagent-dsh-sdk "${this.name}": child run failed (${stopReason}): ${error.message}`);
+			}
+		});
+	}
+};
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveFinite("subagent-dsh-sdk", "shutdownTimeoutMs", resolved.shutdownTimeoutMs);
+	assertPositiveFinite("subagent-dsh-sdk", "disposeEofGraceMs", resolved.disposeEofGraceMs);
+	assertPositiveFinite("subagent-dsh-sdk", "disposeGraceMs", resolved.disposeGraceMs);
+	if (resolved.maxTokens !== void 0 && (!Number.isSafeInteger(resolved.maxTokens) || resolved.maxTokens <= 0)) throw new TypeError("subagent-dsh-sdk maxTokens must be a positive safe integer");
+	const configuredCwd = validateConfiguredCwd("subagent-dsh-sdk", resolved.cwd);
+	const validated = configuredCwd === void 0 ? resolved : {
+		...resolved,
+		cwd: configuredCwd
+	};
+	ctx.subagents.registerProvider(new SdkProvider(validated.providerName, ctx, validated));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-subagent-dsh-sdk`.
+* @module @deepseek-ai/dsh-subagent-dsh-sdk/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-subagent-dsh-sdk";
+/** Cordis companion plugin name. */
+const name = "subagent-dsh-sdk-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: run lifecycle pairing is owned and checked by the
+* subagent seam's invariant; this backend's own state lives in the child
+* process beyond this context's event streams.
+*/
+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/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Out-of-process SDK subagent backend. Each child is a complete DeepSeek
+ * Harness runtime in its own process — own `cordis.yml`-decided composition,
+ * session, model route, and tools — driven over stdio JSON-RPC through the
+ * TypeScript SDK client, so it shares no Cordis context and advertises no
+ * parent-enforced start capabilities; the ONE thing it reads off
+ * `request.parent` is the session's workspace cwd. This plugin uses named
+ * exports only; a default would hide its loader metadata (see
+ * `docs/postmortem/0001-acp-default-export-drops-inject.md`).
+ * @module @deepseek-ai/dsh-subagent-dsh-sdk
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "subagent-dsh-sdk";
+export declare const inject: string[];
+/** Config: how to spawn and drive the child SDK runtime process. */
+export interface Config {
+    /** Provider name on `ctx.subagents` (default `dsh-sdk`). */
+    providerName: string;
+    /** The executable to spawn for each run (the child runtime bin or packaged exe). */
+    command: string;
+    /** Arguments passed to {@link command} (typically the child's `cordis.yml` path). */
+    args: string[];
+    /**
+     * Working directory override for the child process and its SDK session
+     * workspace. Must be non-empty; a relative path resolves against the
+     * harness launch directory at load, and the result must be an existing
+     * directory. When omitted, each child inherits its delegating parent
+     * session's cwd — and starting one from a parent session that has no cwd
+     * fails.
+     */
+    cwd?: string;
+    /** Provider route the child runtime initializes with (default `deepseek-official`). */
+    provider: string;
+    /** Model the child runtime initializes with (default `deepseek-v4-flash`). */
+    model: string;
+    /** Optional per-request output-token cap for the child runtime. */
+    maxTokens?: number;
+    /**
+     * Extra environment variables for the child process — e.g. the child
+     * runtime's own `DEEPSEEK_API_KEY`, or `DSH_CORDIS_CONFIG` naming its
+     * config. Forwarded on top of a credential-scrubbed copy of the parent
+     * env, so an explicit key here reaches the child while ambient secrets do
+     * not leak implicitly.
+     */
+    env: Record<string, string>;
+    /** Bound (ms) on the protocol `shutdown` exchange during dispose. */
+    shutdownTimeoutMs?: number;
+    /**
+     * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
+     * window to flush persistence and tear down its own nested subprocesses
+     * before the parent escalates to a signal.
+     */
+    disposeEofGraceMs?: number;
+    /** Termination confirmation window (ms), including forced exit on every platform. */
+    disposeGraceMs?: number;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-dsh-sdk`.
+ * @module @deepseek-ai/dsh-subagent-dsh-sdk/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "subagent-dsh-sdk-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/run.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Fresh-process SDK subagent client. Drives one child DeepSeek Harness
+ * runtime over stdio JSON-RPC through `@deepseek-ai/dsh-sdk-client` and owns
+ * cancellation and quiescent disposal. Structure mirrors the ACP backend
+ * (`@deepseek-ai/dsh-subagent-acp`): publish after the child handshake,
+ * flatten child failures into stop reasons, tear down to quiescence. The
+ * child is spawned BY the SDK client rather than through `ctx.subprocess` —
+ * the subprocess seam's documented exception for SDK-managed transports —
+ * so this driver applies the seam's shared env scrub itself.
+ *
+ * @module @deepseek-ai/dsh-subagent-dsh-sdk/run
+ */
+import { type TurnEndReason } from '@deepseek-ai/dsh-session';
+import type { SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+/** Resolved spawn spec for an SDK runtime child process (no defaults — see Config). */
+export interface SdkRunSpec {
+    /** The executable to spawn (the child runtime — a `dsh-jsonrpc-agent` bin or packaged exe). */
+    command: string;
+    /** Arguments passed to {@link command} (typically the child's `cordis.yml` path). */
+    args: string[];
+    /**
+     * Absolute working directory for the child process AND the workspace cwd
+     * of its SDK session. The provider resolves it before this spec exists:
+     * config override, else the delegating parent session's workspace.
+     */
+    cwd: string;
+    /** Provider route the child runtime initializes with. */
+    provider: string;
+    /** Model the child runtime initializes with. */
+    model: string;
+    /** Optional per-request output-token cap sent in the child runtime's initialize handshake. */
+    maxTokens?: number;
+    /**
+     * Extra environment variables to ADD for the child (e.g. the child
+     * runtime's own `DEEPSEEK_API_KEY`, or `DSH_CORDIS_CONFIG`). Merged after
+     * the seam's `scrubbedParentEnv()` base, so an explicit credential or
+     * current `DSH_*` fact survives while ambient namesakes never leak.
+     */
+    env: Record<string, string>;
+    /** Bound (ms) on the protocol `shutdown` exchange during dispose. */
+    shutdownTimeoutMs: number;
+    /** Grace period (ms) for the child's EOF-driven quiesce on dispose. */
+    disposeEofGraceMs: number;
+    /** Termination confirmation window (ms), including forced exit on every platform. */
+    disposeGraceMs: number;
+    /**
+     * Sink for a child-level failure that the run flattened into a stop reason
+     * (the seam contract forbids `result` rejecting). A throw from the sink
+     * itself is contained. Optional — omitted in unit tests that assert the
+     * stop reason directly.
+     */
+    onError?: (error: Error, stopReason: SubagentStopReason) => void;
+}
+/** EOF grace for child flush and nested-process teardown; wider than the signal grace below. */
+export declare const DEFAULT_DISPOSE_EOF_GRACE_MS = 6000;
+/** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
+export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/** Default bound on the protocol `shutdown` exchange during dispose. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1000;
+/**
+ * Map a child turn-end reason to a harness {@link SubagentStopReason}.
+ * @param reason - the owned child run's final durable turn reason, or
+ * `undefined` when it settled without running a turn.
+ * @returns the harness equivalent; an absent or unknown reason maps to
+ * `error`, so an unclean stop is never reported as `completed`.
+ */
+export declare function sdkStopReason(reason: TurnEndReason | undefined): SubagentStopReason;
+/**
+ * Start and publish one SDK runtime child after its `initialize` handshake.
+ * Child failures resolve through the run result; startup failures reject
+ * after process reap. Disposal shuts the runtime down and reaps it.
+ * @param request - the start request; its signal is the cancellation channel.
+ * @param spec - the resolved spawn spec: command/args/cwd, the child's
+ * provider/model route, env, timeouts, and the optional error sink.
+ * @returns the ready run handle for the child subprocess.
+ */
+export declare function startSdkRun(request: SubagentStartRequest, spec: SdkRunSpec): Promise<SubagentRun>;
+//# sourceMappingURL=run.d.ts.map

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-dsh-sdk",
+  "description": "Out-of-process SDK subagent backend: drives a child DeepSeek Harness runtime subprocess over stdio JSON-RPC through the TypeScript SDK client",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/subagent/subagent-dsh-sdk"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sdk-client": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sdk-client": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1"
+  }
+}