npm - @deepseek-ai/dsh-subagent-dsh-sdk - Versions diffs - 0.1.1-rc.2 → 0.1.2-alpha.2 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.i18n.yaml CHANGED Viewed

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-dsh-sdk/README.md
-README.md: 8d20b44dacd773345986e2a2fc0e6aca9470bf2c
-README.zh.md: 3937724c28a693e3e74cca2e1c3f1ae61766a14e
+README.md: 59dc34f33a924c7cc67225a7337df2f8a3935f30
+README.zh.md: 31da5276333f5ea6a90bd283639ceb495345075e

package/README.md CHANGED Viewed

@@ -1,50 +1,68 @@
+---
+description: "The out-of-process SDK subagent backend for users and maintainers choosing a delegation provider, configuring a child Harness runtime command, or debugging remote child runs."
+kind: "package-reference"
+---
 # @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](../../sdk/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.
+## Summary
-## Start and ownership
+`dsh-subagent-dsh-sdk` runs each delegated child as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the TypeScript SDK client. It is the second out-of-process backend beside the ACP provider, differing in the wire and the child contract: the child is a full peer harness with its own `cordis.yml`-decided composition, session persistence, model route, and tools. Each run spawns the child runtime (the resolved `@deepseek-ai/dsh` CLI under Node, or the configured `dshBin`), completes an `initialize` handshake with the configured provider and model route, submits the task, and reads the answer from the child's session events. The parent receives only the child's final assistant text or a safe error — no intermediate messages or tool traffic crosses the boundary. Choose it when the child should be a genuine Harness runtime, fully isolated from the parent harness.
-`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.
+## Table of Contents
-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.
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
-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 non-empty `assistant/message` (an empty-content message that records usage is skipped), or the accumulated `text-delta` stream when no such message exists. Partial output remains available after cancellation or an error.
+-----
-`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.
+<a id="use-this-package"></a>
+## Use this package
-## Stop-reason mapping
+Mount this provider when a delegation should run as a complete Harness runtime in its own process. The common path is explicit: mount the seam, mount this provider, and give it a command that starts an SDK runtime with its own `cordis.yml`.
-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.
+### When to choose it
-## Capabilities and context
+Choose this backend when the child must be a full harness peer — its own composition, session persistence, model route, and tools — rather than an agent that shares the parent's process. Choose an in-process backend when the child must share the parent's composition or honor parent-enforced non-route capabilities: this provider accepts agent route options but rejects structured output, depth caps, tool filters, and personas rather than silently omitting them.
-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.
+The provider advertises `agentOptions: true`, with `outputSchema`/`depthLimit`/`toolFilter`/`persona` false, and `inheritsParentContext: false`. Its immutable `agentRouteDefaults` publish the configured provider/model baseline to `dsh-tool-subagent` before model overrides and exact-route preflight; `start()` independently applies the same configuration defaults for direct callers and `maxTokens`. Agent route values cross the SDK wire as an explicit whitelist; the child remains a fresh runtime in another process, and the only value derived from the parent agent itself is the workspace cwd. `dsh-tool-subagent` deployments over this provider set `maxDepth: 'provider-managed'` — the child harness owns its own recursion budget.
-## Configuration
+### Configuration
-| Key | Default | Meaning |
+| Field | 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. |
+| `providerName` | `dsh-sdk` | Registry name on `ctx.subagents` |
+| `dshBin` | SDK dependency | Explicit dsh CLI module, resolved and checked at plugin load; omission uses the SDK dependency |
+| `profile` | `sdk` | Named child profile |
+| `patches` | `[]` | Ordered per-launch profile patch files, resolved and checked at plugin load |
+| `dshHome` | required | Absolute isolated Harness home for every nested child process |
+| `cwd` | parent session cwd | Working-directory override for the child process and its SDK session |
+| `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` |
+| `env` | `{}` | Explicit child environment layered over the credential-scrubbed parent environment |
+| `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 |
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-subagent-dsh-sdk) is the exhaustive source for every accepted field and its JSDoc.
+Request `agentOptions` override `provider`, `model`, and `maxTokens` independently. `reasoningEffort` has no provider-instance default: an omitted request leaves it absent so the selected child model resolves its own default. The model-facing subagent tool can select provider/model/reasoning per call; `maxTokens` remains deployment-controlled through tool config or this provider's default.
 ```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']
+    profile: sdk
+    patches: ['./profiles/research-child.cordis.yml']
+    dshHome: !!js dshHomePath('children')
     maxTokens: 49152
     env:
       DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
@@ -53,19 +71,74 @@ The provider advertises no start-time capabilities (`outputSchema`/`depthLimit`/
   config: { provider: dsh-sdk, toolName: subagent, maxDepth: 'provider-managed' }
 ```
-## Process boundary
+### What you get
+A successful run returns the child's final assistant text (or accumulated partial text after cancellation) as result output. The child's model route, tools, and session come from the child runtime itself — the parent supplies the task, working directory, and `initialize` route. The child's last durable `turn/end` maps into the seam vocabulary: `completed` and `max-tokens` pass through, `blocked` becomes `refusal`, and an unexpected or missing terminal becomes `error`. An `aborted` result stays aborted; only a child-side `disposed` cause adds a `child-disposed` diagnostic.
+### Failure and recovery
+An already-aborted request fails before path resolution or spawn. A route, spawn, handshake, or pre-publication cancellation failure ordinarily rejects only after the subprocess is reaped. If initialization and cleanup both fail, the ordered safe facts preserve both failures without claiming quiescence. A child runtime that fails after publication settles through the run rather than rejecting it; partial output stays separate from the safe diagnostic. Diagnostics expose only the provider plus `initialize`, `session-run`, or `shutdown` stage and a fixed category. They never copy SDK messages, stderr, paths, task content, environment values, credentials, or protocol payloads.
+-----
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+<details>
+<summary>Implementation internals — click to expand</summary>
+This section explains how the backend drives a child Harness runtime and where the observable behavior comes from; the full contract lives in [Use this package](#use-this-package).
+### Design concept
+- **Full harness peer.** Each child is a complete Harness runtime in its own process — own composition, session, model route, and tools; only the resolved working directory and the `initialize` route cross from the parent.
+- **One runtime per run.** Every run spawns a fresh runtime process; there is no pooling.
+- **The JSON-RPC wire is the serialization boundary.** Same-process subagent values are not defensively cloned; the protocol is where hostile input is validated.
+### Source map
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: config schema, provider registration |
+| [`src/run.ts`](src/run.ts) | The SDK run lifecycle, answer extraction, and stop-reason mapping |
+### Run flow
+A start resolves the child's working directory and one process-wide SDK route before spawning. Each declared `request.agentOptions` field (`provider`, `model`, `reasoningEffort`, or `maxTokens`) overrides the matching provider-instance default; omission preserves the configured provider/model and optional cap, while reasoning effort remains absent unless the request supplies it. The provider spawns the runtime through the SDK client and completes the `initialize` handshake, including exact-model and effort validation, before it fulfills. A route, spawn, handshake, or pre-publication cancellation failure rejects only after the subprocess is reaped; a working-directory resolution failure rejects before spawning. After publication the provider owns one SDK activity and reads the child's answer from its session events: the last complete non-empty `assistant/message` (an empty-content message that records usage is skipped), or the accumulated `text-delta` stream when no such message exists. Disposal is idempotent: it settles the result locally as `aborted`, sends a bounded protocol `shutdown` request, then escalates through stdin EOF → SIGTERM → SIGKILL to actual exit.
+### Stop-reason mapping
-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 child's last `turn/end` reason maps into the shared stop-reason vocabulary in [`src/run.ts`](src/run.ts).
-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).
+### Process boundary
+The child environment is the subprocess seam's credential-scrubbed parent environment with explicit `config.env` values merged after the scrub. The child is spawned by the SDK client rather than through `ctx.subprocess` — the documented exception for SDK-managed transports — which is why this backend applies the scrub itself.
+</details>
+-----
+<a id="further-exploration"></a>
+## Further Exploration
+Read these pages when the package-level contract is not enough. They move from this backend to the seam it plugs into and the SDK it drives.
+- [Subagent subsystem](../../../docs/subsystems/subagent.md) — the service contract, provider contract, and terminal result semantics.
+- [dsh-subagent seam](../subagent/README.md) — the registry and start API this provider registers on.
+- [ACP subagent backend](../subagent-acp/README.md) — the sibling out-of-process provider over the Agent Client Protocol.
+- [TypeScript SDK client](../../sdk/client/README.md) — the stdio JSON-RPC client this backend drives the child through.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-subagent-dsh-sdk) — every accepted config field and its source declaration.
+-----
+<a id="model-experience"></a>
 ## 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.
+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. A parent tool call may choose the child provider, model, and reasoning effort for this run; the selected route and any deployment-owned output cap are fixed for the new child process. Persona, tool filtering, depth enforcement, and structured output remain unsupported and are rejected instead of silently omitted.
 #### Token effect
@@ -79,7 +152,7 @@ Independent of the parent request cache. Each SDK child can reuse only prefixes
 #### 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.
+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. A diagnostic-bearing non-completed result presents the safe diagnostic before separately preserved partial assistant output; startup and shutdown errors expose the same fixed facts without raw SDK text.
 #### Token effect
@@ -91,7 +164,25 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
+<a id="known-limitations-and-deferred-work"></a>
+These limits define when this backend is a poor fit or needs special operational care. They are current package constraints, not a general SDK comparison or a task backlog.
 - **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.
+- **No non-route start-time capabilities** — the parent can select the child agent route but cannot enforce `outputSchema`, depth, tool filters, or persona inside the child process; configure the selected child profile and its ordered patches instead.
+- **The child's transcript stays in the child's own session root** — the parent log records only the delegation tool call and result; the streamed `session.event` channel is consumed for output extraction, not bridged into the parent log.
+- **Local child processes only** — the resolved working directory is a local path; a remote runtime would need its own backend.
+<a id="dev-note"></a>
+### Dev Note
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior and limits live in the sections above and in the package code.
+- **Spawn cost** — the full plugin tree per run is the price of full isolation; pooling would change that trade-off.
+- **Remote runtimes** — a remote runtime would need its own backend and workspace mapping.
+</details>

package/README.zh.md CHANGED Viewed

@@ -1,50 +1,68 @@
+---
+description: "面向用户与维护者的进程外 SDK subagent 后端，用于选择委派提供方、配置子 Harness 运行时命令或排查远程子 agent 运行问题。"
+kind: "package-reference"
+---
 # @deepseek-ai/dsh-subagent-dsh-sdk
 [English](README.md) | 中文
-SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../sdk/client/README.zh.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.zh.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程约定：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
+## 概述
-## 启动与所有权
+`dsh-subagent-dsh-sdk` 在全新的子进程中把每个被委派的子 agent（智能体）作为完整的 DeepSeek Harness 运行时运行，并经由 TypeScript SDK 客户端通过 stdio JSON-RPC 驱动。它是 ACP 提供方之外的第二个进程外后端，差异在协议格式（wire format）与子进程约定：子进程是完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由与工具。每次运行都会 spawn 子运行时（Node 下解析出的 `@deepseek-ai/dsh` CLI，或配置的 `dshBin`），以配置的提供方与模型路由完成 `initialize` 握手、提交任务，并从子进程的会话事件中读取答案。父级只收到子进程最终的 assistant 文本或安全错误——中间消息与工具流量不会跨越边界。当子进程应该是与父 harness 完全隔离的真实 Harness 运行时时，选择它。
-`start(request)` 先解析子进程工作目录，通过 `DeepSeekHarness` spawn 运行时，并在履行前完成 `initialize` 握手（携带配置的 `provider`/`model` 路由及可选的 `maxTokens` 输出上限）。因此，履行意味着子运行时已就绪、所有权已移交给调用方。spawn、握手或发布前取消失败时，只会在子进程被回收后拒绝；工作目录解析失败则会在尚未 spawn 任何内容时拒绝。
+## 目录
-工作目录的解析与 ACP 后端完全一致，并使用 seam 共享的进程外辅助工具（[`dsh-subagent`](../subagent/README.zh.md)）：设置了 `cwd` 覆盖值时使用该值（加载时校验一次），否则使用发起委派的父会话 cwd，绝不使用服务器进程自身的 cwd。解析出的路径同时成为子进程 cwd 和其 SDK 会话的工作区 cwd。
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
-返回的 run id 在父级命名空间中生成；子运行时的会话 id 只存在于子进程内部。发布后，提供方拥有一段 SDK 活动，并从子会话事件中读取答案：最后一条完整且非空的 `assistant/message`（记录 usage 的空内容消息会被跳过）；若没有这类消息，则取累积的 `text-delta` 流。取消或发生错误后，部分输出仍然可用。
+-----
-`dispose()`（资源释放）是幂等的：先在本地把结果确定为 `aborted`（协议层面没有提示词取消机制），再关闭运行时，即先发出一次有界的协议 `shutdown` 请求，随后通过共享的 stdin-EOF → SIGTERM → SIGKILL 阶梯使进程实际退出。
+<a id="use-this-package"></a>
+## 使用本包
-## 停止原因映射
+当委派应以完整 Harness 运行时在独立进程中运行时，挂载本提供方。常用路径是显式的：挂载 seam、挂载本提供方，并给出一个启动带有自身 `cordis.yml` 的 SDK 运行时的命令。
-SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个已持久化的 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 约定禁止 `result` 被拒绝。
+### 何时选择
-## 能力与上下文
+当子进程必须是完整的 harness 对等体——拥有自己的组合、会话持久化、模型路由与工具——而不是共享父进程的 agent 时，选择此后端。当子进程必须共享父级组合或遵守父级强制的非路由能力时，请选择进程内后端：本提供方接受 agent 路由选项，但会拒绝结构化输出、深度上限、工具过滤或 persona，而不是静默省略。
-Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilter`/`persona` 全为 false），且 `inheritsParentContext: false`：子进程是另一进程里的全新运行时，唯一来自父方的输入是工作区 cwd。基于本 provider 的 `dsh-tool-subagent` 部署应设置 `maxDepth: 'provider-managed'`——子 harness 拥有自己的递归预算。
+提供方声明 `agentOptions: true`，同时保持 `outputSchema`/`depthLimit`/`toolFilter`/`persona` 为 false，并且 `inheritsParentContext: false`。不可变的 `agentRouteDefaults` 会在模型覆盖与确切路由预检前，把配置的 provider／model 基线公开给 `dsh-tool-subagent`；`start()` 则为直接调用方与 `maxTokens` 独立应用同一份配置默认值。Agent 路由值通过显式白名单跨越 SDK 协议；子进程仍是另一进程里的全新运行时，唯一从父 agent 本身派生的值是工作区 cwd。基于本提供方的 `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.zh.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 之前也等待同样时长。 |
+| `providerName` | `dsh-sdk` | `ctx.subagents` 上的注册表名称 |
+| `dshBin` | SDK 依赖 | 显式 dsh CLI 模块，在插件加载时解析并校验；省略则使用 SDK 依赖 |
+| `profile` | `sdk` | 子进程命名的 profile |
+| `patches` | `[]` | 每次启动的有序 profile patch 文件，在插件加载时解析并校验 |
+| `dshHome` | 必填 | 每个嵌套子进程的绝对隔离 Harness home |
+| `cwd` | 父会话 cwd | 子进程及其 SDK 会话的工作目录覆盖值 |
+| `provider` | `deepseek-official` | 写入子进程 `initialize` 的提供方路由 |
+| `model` | `deepseek-v4-flash` | 写入子进程 `initialize` 的模型 |
+| `maxTokens` | 适配器／提供方路由默认值 | 写入子进程 `initialize` 的单次请求输出 token 上限 |
+| `env` | `{}` | 叠加在已清理凭据的父环境之上的显式子环境 |
+| `shutdownTimeoutMs` | `1000` | dispose 期间协议 `shutdown` 交换的时限 |
+| `disposeEofGraceMs` | `6000` | stdin EOF 之后、平台终止之前的宽限 |
+| `disposeGraceMs` | `3000` | 终止后的退出确认宽限 |
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-subagent-dsh-sdk)是每个受支持字段及其 JSDoc 的穷尽式真源。
+请求 `agentOptions` 会分别覆盖 `provider`、`model` 与 `maxTokens`。`reasoningEffort` 没有提供方实例默认值：请求省略时保持缺省，由所选子模型解析自身默认值。面向模型的 subagent 工具可在每次调用时选择提供方／模型／推理强度；`maxTokens` 仍由工具配置或本提供方默认值在部署侧控制。
 ```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']
+    profile: sdk
+    patches: ['./profiles/research-child.cordis.yml']
+    dshHome: !!js dshHomePath('children')
     maxTokens: 49152
     env:
       DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
@@ -53,19 +71,74 @@ Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilte
   config: { provider: dsh-sdk, toolName: subagent, maxDepth: 'provider-managed' }
 ```
-## 进程边界
+### 你会得到什么
+成功的运行会把子进程最终的 assistant 文本（或取消后累积的部分文本）作为结果输出返回。子进程的模型路由、工具与会话来自子运行时自身——父级提供任务、工作目录与 `initialize` 路由。子进程最后一个持久化 `turn/end` 会映射进 seam 词汇：`completed` 与 `max-tokens` 原样通过，`blocked` 变为 `refusal`，意外终态或缺少终态变为 `error`。`aborted` 结果保持中止；只有子进程侧 `disposed` 原因会附加 `child-disposed` 诊断。
+### 失败与恢复
+已取消的请求会在路径解析或 spawn 之前失败。路由、spawn、握手或发布前取消失败通常只在子进程被回收后拒绝；如果初始化与清理均失败，有序安全事实会保留两项失败，而不会宣称已完全停稳。子运行时在发布后失败时会通过运行本身结算，而不是拒绝；部分输出与安全诊断保持分离。诊断只公开提供方、`initialize`、`session-run` 或 `shutdown` 阶段，以及固定类别。SDK 消息、stderr、路径、任务内容、环境值、凭据和协议载荷绝不会复制到诊断中。
+-----
+<a id="understand-the-implementation"></a>
+## 理解实现
+<details>
+<summary>实现细节——点击展开</summary>
+本节解释后端如何驱动子 Harness 运行时，以及可观察行为从何而来；完整约定见[使用本包](#use-this-package)。
+### 设计理念
+- **完整 harness 对等体。** 每个子进程都是独立进程中的完整 Harness 运行时——拥有自己的组合、会话、模型路由与工具；只有解析后的工作目录与 `initialize` 路由从父级跨越。
+- **每次运行一个运行时。** 每次运行都 spawn 全新运行时进程；没有进程池。
+- **JSON-RPC 协议格式是序列化边界。** 同进程 subagent 值不会为防御目的克隆；协议才是校验不可信输入的地方。
+### 源码地图
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：config schema、提供方注册 |
+| [`src/run.ts`](src/run.ts) | SDK 运行生命周期、答案提取与停止原因映射 |
+### 运行流程
+一次启动会在 spawn 前解析子进程工作目录与一条进程级 SDK 路由。`request.agentOptions` 中每个已声明字段（`provider`、`model`、`reasoningEffort` 或 `maxTokens`）都会覆盖对应的提供方实例默认值；省略时保留已配置的提供方／模型与可选上限，而推理强度只有在请求提供时才会出现。随后，提供方通过 SDK 客户端 spawn 运行时，并在履行前完成 `initialize` 握手，其中包括确切模型与推理强度校验。路由、spawn、握手或发布前取消失败时，只会在子进程被回收后拒绝；工作目录解析失败则会在尚未 spawn 任何内容时拒绝。发布后，提供方拥有一段 SDK 活动，并从子会话事件中读取答案：最后一条完整且非空的 `assistant/message`（记录 usage 的空内容消息会被跳过）；若没有这类消息，则取累积的 `text-delta` 流。dispose（资源释放）是幂等的：先在本地把结果确定为 `aborted`，发出有界的协议 `shutdown` 请求，再经 stdin EOF → SIGTERM → SIGKILL 升级到实际退出。
+### 停止原因映射
-子进程环境以 [`dsh-subprocess`](../../subprocess/README.zh.md) seam 的 `scrubbedParentEnv()` 为基础，先移除疑似凭据和名称为 `DSH_*` 的环境变量，再合并显式 `config.env` 值。子进程由 SDK 客户端 spawn，而不是经由 `ctx.subprocess` spawn（这是 subprocess README 中记录的 SDK 托管传输例外），因此本后端会自行执行环境清理。JSON-RPC 协议格式才是真正的序列化边界。
+子进程最后一个 `turn/end` 的原因会映射进共享的停止原因词汇，实现见 [`src/run.ts`](src/run.ts)。
-本包没有默认导出。否则 Cordis loader 解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.zh.md)。
+### 进程边界
+子进程环境以子进程 seam 的已清理凭据父环境为基础，并在清除之后合并显式 `config.env` 值。子进程由 SDK 客户端 spawn，而不是经由 `ctx.subprocess`——这是 SDK 托管传输的文档化例外——因此本后端会自行执行环境清理。
+</details>
+-----
+<a id="further-exploration"></a>
+## 进一步探索
+当包级约定不够用时阅读以下页面。它们从本后端逐步进入它接入的 seam 与它驱动的 SDK。
+- [Subagent 子系统](../../../docs/subsystems/subagent.zh.md)——服务约定、提供方约定与终态结果语义。
+- [dsh-subagent seam](../subagent/README.zh.md)——本提供方注册于其上的注册表与启动 API。
+- [ACP subagent 后端](../subagent-acp/README.zh.md)——经 Agent Client Protocol 的兄弟进程外提供方。
+- [TypeScript SDK 客户端](../../sdk/client/README.zh.md)——本后端用以驱动子进程的 stdio JSON-RPC 客户端。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-subagent-dsh-sdk)——每个受支持配置字段及其源声明。
+-----
+<a id="model-experience"></a>
 ## 模型体验
 ### 子 agent 请求
-#### 模型看到的内容
+#### 模型看到什么
-子运行时的模型会收到作为用户消息的独立任务，以及该运行时自身配置的系统提示词、工具和全新会话。它不会收到父级对话。本提供方不声明可选的启动时能力，因此本地服务会拒绝要求 persona、工具过滤、深度强制或结构化输出的请求，而不是静默省略这些要求。
+子运行时的模型会收到作为用户消息的独立任务，以及该运行时自身配置的系统提示词、工具和全新会话。它不会收到父级对话。父级工具调用可以为本次运行选择子级提供方、模型与推理强度；所选路由和部署持有的可选输出上限会固定到这个新子进程。persona、工具过滤、深度强制与结构化输出仍不受支持，并会被拒绝而不是静默省略。
 #### Token 影响
@@ -77,9 +150,9 @@ Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilte
 ### 父级工具结果（间接）
-#### 模型看到的内容
+#### 模型看到什么
-经由 `dsh-tool-subagent`，父级只会收到子运行时最终的 assistant 文本（或累积的部分文本），或该消费方给出的精确停止原因错误；不会收到中间消息或工具流量。
+经由 `dsh-tool-subagent`，父级只会收到子运行时最终的 assistant 文本（或累积的部分文本），或该消费方给出的精确停止原因错误；不会收到中间消息或工具流量。带诊断的非完成结果会先呈现安全诊断，再单独呈现保留的部分 assistant 输出；启动与 shutdown 错误使用同一固定事实，不公开原始 SDK 文本。
 #### Token 影响
@@ -89,9 +162,27 @@ Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilte
 仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
-## 已知限制与暂缓事项
+## 已知限制与延期工作
+<a id="known-limitations-and-deferred-work"></a>
+这些限制说明本后端何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用 SDK 对比或任务积压。
+- **每次运行都使用全新的运行时进程**——不使用进程池；harness 运行时需要启动完整的插件树，因此每次运行的 spawn 成本高于 ACP 后端通常使用的子进程。
+- **不支持路由之外的启动时能力**——父级可以选择子 agent 路由，但无法在子进程内强制执行 `outputSchema`、深度限制、工具过滤或 persona；应改为配置所选子 profile 及其有序 patch。
+- **子进程的 transcript（文本记录）保留在其自身的会话根目录中**——父级日志只记录委派工具调用与结果；流式会话事件通道只用于提取输出，不会桥接到父级日志中。
+- **仅支持本地子进程**——解析出的工作目录是本地路径；远程运行时需要独立的后端。
+<a id="dev-note"></a>
+### 开发备注
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为与限制以上文和包代码为准。
+- **Spawn 成本**——每次运行加载完整插件树是彻底隔离的代价；池化会改变这一权衡。
+- **远程运行时**——远程运行时需要独立的后端与工作区映射。
-- **每次运行都使用全新的运行时进程**：不使用进程池；harness 运行时需要启动完整的插件树，因此每次运行的 spawn 成本高于 ACP 后端通常使用的子进程。
-- **不支持可选的启动时能力**：父级无法在子进程内强制执行 `outputSchema`、深度限制、工具过滤或 persona；应改为配置子进程自身的 `cordis.yml`。
-- **子进程的 transcript（文本记录）保留在其自身的会话根目录中**：父级日志只记录委派工具调用／结果（seam 的子级隔离规则）；流式 `session.event` 通道只用于提取输出，不会桥接到父级日志中。
-- **仅支持本地子进程**：解析出的 cwd 是本地路径；远程运行时需要独立的后端。
+</details>

package/lib/index.js CHANGED Viewed

@@ -1,19 +1,20 @@
+import { statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { AssistantOutputFold, 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 { brandString } from "@deepseek-ai/dsh-brand";
+import { DeepSeekHarness, JsonRpcResponseError, SdkProtocolError, TransportClosedError } from "@deepseek-ai/dsh-sdk-client";
 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.
+* cancellation and quiescent disposal. It publishes after the child
+* handshake, maps child failures to stop reasons, and tears down to
+* quiescence. The SDK client spawns the child rather than using
+* `ctx.subprocess` — the subprocess seam's documented exception for
+* SDK-managed transports — so this driver applies the seam's shared env scrub.
 *
 * @module @deepseek-ai/dsh-subagent-dsh-sdk/run
 */
@@ -23,19 +24,88 @@ const DEFAULT_DISPOSE_EOF_GRACE_MS = 6e3;
 const DEFAULT_DISPOSE_GRACE_MS = 3e3;
 /** Default bound on the protocol `shutdown` exchange during dispose. */
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e3;
+/** Fixed safe failure text derived only from provider-owned structured facts. */
+function failureDiagnostic(facts) {
+	return `Subagent failure (${[
+		"provider: DSH SDK",
+		`stage: ${facts.stage}`,
+		`category: ${facts.category}`
+	].join("; ")})`;
+}
+var SdkRunFailure = class extends Error {
+	facts;
+	constructor(facts, cause) {
+		super(`subagent-dsh-sdk: ${failureDiagnostic(facts)}`, { cause });
+		this.facts = facts;
+		this.name = "SdkRunFailure";
+	}
+};
+/** Runtime constructor seam replaced only by package-local fake-runtime tests. */
+const internals = { createHarness: (options) => new DeepSeekHarness(options) };
 /**
-* Map a child turn-end reason to a harness {@link SubagentStopReason}.
+* Hide a pre-spawn workspace/configuration failure behind fixed safe facts.
+* @param cause - original Host failure retained on the Error cause chain.
+* @returns an Error whose message contains only the fixed DSH SDK failure line.
+*/
+function sdkConfigurationFailure(cause) {
+	return new SdkRunFailure({
+		stage: "initialize",
+		category: "configuration"
+	}, cause);
+}
+/** Classify one SDK rejection without reading its message or stderr tail. */
+function sdkFailure(error, stage) {
+	return new SdkRunFailure(error instanceof TransportClosedError ? {
+		stage,
+		category: "transport"
+	} : error instanceof SdkProtocolError || error instanceof JsonRpcResponseError ? {
+		stage,
+		category: "protocol"
+	} : {
+		stage,
+		category: "unknown"
+	}, error);
+}
+/**
+* Map one child terminal reason to its complete shared result outcome.
 * @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`.
+* @returns the shared stop reason and any additional safe diagnostic.
 */
-function sdkStopReason(reason) {
+function sdkChildOutcome(reason) {
 	switch (reason?.kind) {
-		case "completed": return "completed";
-		case "max-tokens": return "max-tokens";
-		case "aborted": return "aborted";
-		default: return "error";
+		case "completed": return { stopReason: "completed" };
+		case "max-tokens": return { stopReason: "max-tokens" };
+		case "aborted": return reason.reason.kind === "disposed" ? {
+			stopReason: "aborted",
+			diagnostic: failureDiagnostic({
+				stage: "session-run",
+				category: "child-disposed"
+			})
+		} : { stopReason: "aborted" };
+		case "blocked": return { stopReason: "refusal" };
+		case "error": return {
+			stopReason: "error",
+			diagnostic: failureDiagnostic({
+				stage: "session-run",
+				category: "child-error"
+			})
+		};
+		case "interrupted": return { stopReason: "error" };
+		case void 0: return {
+			stopReason: "error",
+			diagnostic: failureDiagnostic({
+				stage: "session-run",
+				category: "missing-terminal"
+			})
+		};
+		default: return {
+			stopReason: "error",
+			diagnostic: failureDiagnostic({
+				stage: "session-run",
+				category: "child-unknown"
+			})
+		};
 	}
 }
 /** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
@@ -43,34 +113,62 @@ function toError(value) {
 	/* v8 ignore next */
 	return value instanceof Error ? value : new Error(String(value));
 }
+/** Report an original Host failure without letting the observation sink replace it. */
+function reportFailure(spec, error) {
+	try {
+		spec.onError?.(toError(error), "error");
+	} catch {}
+}
+/** Map an SDK-owned failed-start aggregate into safe initialize/shutdown lines. */
+function sdkStartupFailure(spec, error) {
+	if (!(error instanceof AggregateError) || error.errors.length < 2) {
+		reportFailure(spec, error);
+		return sdkFailure(error, "initialize");
+	}
+	const initializeError = error.errors[0];
+	const cleanupError = error.errors[1];
+	reportFailure(spec, initializeError);
+	reportFailure(spec, cleanupError);
+	const initializeFailure = sdkFailure(initializeError, "initialize");
+	const cleanupFailure = new SdkRunFailure({
+		stage: "shutdown",
+		category: "unknown"
+	}, cleanupError);
+	return new AggregateError([initializeFailure, cleanupFailure], `${initializeFailure.message}; ${cleanupFailure.message}`);
+}
 /**
 * 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.
+* Child failures resolve through the run result. Startup rejects with fixed
+* safe facts after SDK-owned cleanup; successful cleanup proves process reap.
+* Cleanup failure preserves initialize plus shutdown for an ordinary failure,
+* or shutdown alone after cancellation, without claiming quiescence. 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.
+* @param spec - the resolved spawn spec: profile/patches/home/cwd, the child's
+* provider/model/reasoning route, output cap, 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
+	const id = brandString(randomUUID());
+	const harness = internals.createHarness({
+		...spec.dshBin === void 0 ? {} : { dshBin: spec.dshBin },
+		profile: spec.profile,
+		patches: spec.patches,
+		dshHome: spec.dshHome,
+		processCwd: 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.reasoningEffort === void 0 ? {} : { reasoningEffort: spec.reasoningEffort },
 		...spec.maxTokens === void 0 ? {} : { maxTokens: spec.maxTokens }
 	});
 	const flags = { cancelled: false };
@@ -87,17 +185,27 @@ async function startSdkRun(request, spec) {
 		requestCancel();
 	};
 	request.signal.addEventListener("abort", onAbort, { once: true });
+	const cancelledStartup = /* @__PURE__ */ new Error("subagent cancelled before the SDK child initialized");
 	try {
 		await Promise.race([harness.start(), cancelSettled.then(() => {
-			throw new Error("subagent cancelled before the SDK child initialized");
+			throw cancelledStartup;
 		})]);
 		/* v8 ignore next */
-		if (flags.cancelled) throw new Error("subagent cancelled before the SDK child initialized");
+		if (flags.cancelled) throw cancelledStartup;
 	} 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);
+		if (error !== cancelledStartup) throw sdkStartupFailure(spec, error);
+		try {
+			await harness.close();
+		} catch (cleanupError) {
+			reportFailure(spec, cleanupError);
+			const cleanupFailure = new SdkRunFailure({
+				stage: "shutdown",
+				category: "unknown"
+			}, cleanupError);
+			throw new AggregateError([cleanupFailure], cleanupFailure.message);
+		}
+		throw new Error("subagent request was aborted before the SDK child started");
 	}
 	const childSessionId = `session-${randomUUID().replaceAll("-", "")}`;
 	const fold = new AssistantOutputFold();
@@ -106,22 +214,41 @@ async function startSdkRun(request, spec) {
 		fold.push(notification.params.event);
 	};
 	const collectOutput = () => fold.collect() ?? [];
+	const teardown = async () => {
+		try {
+			await harness.close();
+		} catch (error) {
+			reportFailure(spec, error);
+			throw new SdkRunFailure({
+				stage: "shutdown",
+				category: "unknown"
+			}, error);
+		}
+	};
+	let diagnostic;
 	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)
-				};
+				try {
+					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 outcome = sdkChildOutcome(turn.events.findLast((event) => event.type === "turn/end")?.data.reason);
+					diagnostic = outcome.diagnostic;
+					return {
+						output: collectOutput(),
+						...outcome
+					};
+				} catch (error) {
+					diagnostic = failureDiagnostic(sdkFailure(error, "session-run").facts);
+					throw error;
+				}
 			},
 			collectOutput,
+			collectDiagnostic: () => diagnostic,
 			cancelled: () => flags.cancelled,
 			onError: spec.onError,
 			signal: request.signal,
@@ -130,18 +257,19 @@ async function startSdkRun(request, spec) {
 		signal: request.signal,
 		onAbort,
 		requestCancel,
-		teardown: () => harness.close()
+		teardown
 	});
 }
 //#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,
+* Harness runtime in its own process — own named profile and patch 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
+* TypeScript SDK client, so it shares no Cordis context. It accepts the
+* provider/model/reasoning/maxTokens subset of `agentOptions`; other start
+* features remain unsupported. 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
@@ -150,8 +278,10 @@ 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([]),
+	dshBin: z.string(),
+	profile: z.string().default("sdk"),
+	patches: z.array(z.string()).default([]),
+	dshHome: z.string().required(),
 	cwd: z.string(),
 	provider: z.string().default("deepseek-official"),
 	model: z.string().default("deepseek-v4-flash"),
@@ -161,30 +291,68 @@ const Config = z.object({
 	disposeEofGraceMs: z.number().default(DEFAULT_DISPOSE_EOF_GRACE_MS),
 	disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS)
 });
+/** Resolve one configured runtime file against the harness launch directory and require a regular file. */
+function resolveConfiguredFile(field, value) {
+	const path = resolve(value);
+	try {
+		if (statSync(path).isFile()) return path;
+	} catch {}
+	throw new TypeError(`subagent-dsh-sdk ${field} must name an existing file: ${path}`);
+}
+/** DSH SDK can apply Agent route options while the other start features remain child-owned. */
+const SDK_START_CAPABILITIES = Object.freeze({
+	...NO_START_CAPABILITIES,
+	agentOptions: true
+});
+/** Merge the request's supported route fields over this provider instance's defaults. */
+function resolveSdkRoute(config, requested) {
+	const maxTokens = requested?.maxTokens ?? config.maxTokens;
+	return {
+		provider: requested?.provider ?? config.provider,
+		model: requested?.model ?? config.model,
+		...requested?.reasoningEffort === void 0 ? {} : { reasoningEffort: requested.reasoningEffort },
+		...maxTokens === void 0 ? {} : { maxTokens }
+	};
+}
 /**
-* 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).
+* The SDK provider. It resolves Agent route options into the child runtime's
+* process-wide handshake; output schema, depth, tool filter, and persona stay
+* unsupported because their ownership does not cross this process boundary.
 */
 var SdkSubagentProvider = class {
 	name;
 	ctx;
 	config;
-	capabilities = NO_START_CAPABILITIES;
+	capabilities = SDK_START_CAPABILITIES;
+	agentRouteDefaults;
 	inheritsParentContext = false;
 	constructor(name, ctx, config) {
 		this.name = name;
 		this.ctx = ctx;
 		this.config = config;
+		this.agentRouteDefaults = Object.freeze({
+			provider: config.provider,
+			model: config.model
+		});
 	}
 	start(request) {
+		if (request.signal.aborted) throw new Error("subagent request was aborted before the SDK child started");
+		let cwd;
+		try {
+			cwd = resolveChildCwd("subagent-dsh-sdk", this.config.cwd, request.parent.session.header.cwd);
+		} catch (error) {
+			const failure = sdkConfigurationFailure(error);
+			this.ctx.logger.warn(`subagent-dsh-sdk "${this.name}": child start failed: %o`, error);
+			throw failure;
+		}
+		const route = resolveSdkRoute(this.config, request.agentOptions);
 		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 },
+			...this.config.dshBin === void 0 ? {} : { dshBin: this.config.dshBin },
+			profile: this.config.profile,
+			patches: this.config.patches,
+			dshHome: this.config.dshHome,
+			cwd,
+			...route,
 			env: this.config.env,
 			shutdownTimeoutMs: this.config.shutdownTimeoutMs,
 			disposeEofGraceMs: this.config.disposeEofGraceMs,
@@ -201,9 +369,15 @@ function apply(ctx, config) {
 	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 : {
+	if (!isAbsolute(resolved.dshHome)) throw new TypeError("subagent-dsh-sdk dshHome must be an absolute path");
+	const launchPaths = {
 		...resolved,
+		patches: resolved.patches.map((path, index) => resolveConfiguredFile(`patches[${String(index)}]`, path)),
+		...resolved.dshBin === void 0 ? {} : { dshBin: resolveConfiguredFile("dshBin", resolved.dshBin) }
+	};
+	const configuredCwd = validateConfiguredCwd("subagent-dsh-sdk", resolved.cwd);
+	const validated = configuredCwd === void 0 ? launchPaths : {
+		...launchPaths,
 		cwd: configuredCwd
 	};
 	ctx.subagents.registerProvider(new SdkSubagentProvider(validated.providerName, ctx, validated));

package/lib/types/index.d.ts CHANGED Viewed

@@ -1,10 +1,11 @@
 /**
  * Out-of-process SDK subagent backend. Each child is a complete DeepSeek
- * Harness runtime in its own process — own `cordis.yml`-decided composition,
+ * Harness runtime in its own process — own named profile and patch 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
+ * TypeScript SDK client, so it shares no Cordis context. It accepts the
+ * provider/model/reasoning/maxTokens subset of `agentOptions`; other start
+ * features remain unsupported. 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
@@ -17,10 +18,14 @@ export declare const inject: string[];
 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[];
+    /** Explicit dsh CLI module, resolved and checked at plugin load; omission uses the SDK dependency. */
+    dshBin?: string;
+    /** Named child profile (default `sdk`). */
+    profile: string;
+    /** Ordered per-launch profile patch files, resolved and checked at plugin load. */
+    patches: string[];
+    /** Absolute isolated Harness home for every nested child process. */
+    dshHome: string;
     /**
      * Working directory override for the child process and its SDK session
      * workspace. Must be non-empty; a relative path resolves against the
@@ -38,8 +43,7 @@ export interface Config {
     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
+     * runtime's own `DEEPSEEK_API_KEY`. 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.
      */

package/lib/types/run.d.ts CHANGED Viewed

@@ -1,23 +1,28 @@
 /**
  * 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.
+ * cancellation and quiescent disposal. It publishes after the child
+ * handshake, maps child failures to stop reasons, and tears down to
+ * quiescence. The SDK client spawns the child rather than using
+ * `ctx.subprocess` — the subprocess seam's documented exception for
+ * SDK-managed transports — so this driver applies the seam's shared env scrub.
  *
  * @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';
+import { DeepSeekHarness, type DeepSeekHarnessOptions } from '@deepseek-ai/dsh-sdk-client';
+import type { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import type { TurnEndReason } from '@deepseek-ai/dsh-session';
+import type { SubagentResult, 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[];
+    /** Explicit dsh CLI module; omission resolves the SDK client's same-version dependency. */
+    dshBin?: string;
+    /** Named child profile. */
+    profile: string;
+    /** Ordered per-launch profile patch files. */
+    patches: string[];
+    /** Absolute isolated Harness home for the nested runtime. */
+    dshHome: string;
     /**
      * Absolute working directory for the child process AND the workspace cwd
      * of its SDK session. The provider resolves it before this spec exists:
@@ -28,11 +33,13 @@ export interface SdkRunSpec {
     provider: string;
     /** Model the child runtime initializes with. */
     model: string;
+    /** Optional adapter-owned reasoning effort sent in the child runtime's initialize handshake. */
+    reasoningEffort?: ReasoningEffortId;
     /** 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
+     * runtime's own `DEEPSEEK_API_KEY`). Merged after
      * the seam's `scrubbedParentEnv()` base, so an explicit credential or
      * current `DSH_*` fact survives while ambient namesakes never leak.
      */
@@ -44,10 +51,9 @@ export interface SdkRunSpec {
     /** 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.
+     * Host sink for startup, published-run, or shutdown failures. Model-visible
+     * text uses fixed safe facts, while this callback retains the original Error.
+     * A throw from the sink itself is contained.
      */
     onError?: (error: Error, stopReason: SubagentStopReason) => void;
 }
@@ -57,21 +63,34 @@ export declare const DEFAULT_DISPOSE_EOF_GRACE_MS = 6000;
 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;
+/** Runtime constructor seam replaced only by package-local fake-runtime tests. */
+export declare const internals: {
+    createHarness(options: DeepSeekHarnessOptions): DeepSeekHarness;
+};
 /**
- * Map a child turn-end reason to a harness {@link SubagentStopReason}.
+ * Hide a pre-spawn workspace/configuration failure behind fixed safe facts.
+ * @param cause - original Host failure retained on the Error cause chain.
+ * @returns an Error whose message contains only the fixed DSH SDK failure line.
+ */
+export declare function sdkConfigurationFailure(cause: unknown): Error;
+/**
+ * Map one child terminal reason to its complete shared result outcome.
  * @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`.
+ * @returns the shared stop reason and any additional safe diagnostic.
  */
-export declare function sdkStopReason(reason: TurnEndReason | undefined): SubagentStopReason;
+export declare function sdkChildOutcome(reason: TurnEndReason | undefined): Pick<SubagentResult, 'stopReason' | 'diagnostic'>;
 /**
  * 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.
+ * Child failures resolve through the run result. Startup rejects with fixed
+ * safe facts after SDK-owned cleanup; successful cleanup proves process reap.
+ * Cleanup failure preserves initialize plus shutdown for an ordinary failure,
+ * or shutdown alone after cancellation, without claiming quiescence. 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.
+ * @param spec - the resolved spawn spec: profile/patches/home/cwd, the child's
+ * provider/model/reasoning route, output cap, 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>;

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "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.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,29 +32,40 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-sdk-client": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-sdk-client": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-sdk-protocol": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-sdk-client": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent-instructions": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent-spine-demo": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-app-boot": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-sdk-client": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tool-subagent": "^0.1.2-alpha.2"
   }
 }